WidgetStudio.Contracts 0.2.0

WidgetStudio.Contracts

C# contracts for the widget JSON rendered by the @lieselthuriot/widget-renderer Angular package. Build widgets in a .NET API, serialize them with the included source-generated context, and render them in the browser.

• Live editor: widget-studio.liesel.dev. Design a widget visually and copy the generated C# code.
• Source and issues: github.com/LieselThuriot/widget-studio

The package targets netstandard2.0.

Installation

dotnet add package WidgetStudio.Contracts

Usage

using System.Text.Json;
using WidgetStudio.Contracts;
using WidgetStudio.Contracts.Elements;
using WidgetStudio.Contracts.Enums;
using WidgetStudio.Contracts.Styles;

var widget = new WidgetContract
{
    Id = "hello-widget",
    Size = WidgetSize.Square,
    Rows = [GridTrack.Auto],
    Columns = [GridTrack.Star()],
    Background = new BackgroundConfig
    {
        Color = WidgetColor.Rgb(23, 32, 51),
        Sensitive = false,
        Repeat = false,
        Size = BackgroundSize.Cover,
        Anchor = ElementAnchor.Center,
    },
    Refresh = new RefreshConfig { Enabled = true, Label = "Refresh widget" },
    Elements =
    [
        new TextElement
        {
            Grid = new ElementGrid { Row = 0, Column = 0, RowSpan = 1, ColumnSpan = 1, Anchor = ElementAnchor.Center },
            Sensitive = false,
            Text = "Hello from .NET",
            Style = new TextStyle
            {
                Color = WidgetColor.White,
                Font = new TextFontStyle { Size = 16, Bold = true },
                Align = TextAlign.Center,
                Wrap = true,
            },
        },
    ],
};

var json = JsonSerializer.Serialize(widget, WidgetJsonContext.Default.WidgetContract);

Always serialize with WidgetJsonContext. It emits camel-case property names, lowercase enum values, space-separated anchor values such as "top left", and the type discriminator required by the renderer's polymorphic element model. It also omits null properties. The default JsonSerializerOptions do not produce the renderer wire format.

This package is primarily a serialization layer. When deserializing external JSON with WidgetJsonContext, put each polymorphic discriminator before the object's other properties: type first for widget elements and kind first for progress items. JSON produced by WidgetJsonContext already has this order.

Layout fingerprints

WidgetFingerprint.Compute returns a stable ID of a widget's look, such as wfp:1:3f9c…, and matches computeWidgetFingerprint from @lieselthuriot/widget-renderer. Use it to gate user-built widgets behind an approval step:

var fingerprint = widget.ComputeFingerprint(); // or WidgetFingerprint.Compute(json)
var approved = fingerprint is not null && approvedLayouts.Contains(fingerprint);

Content that can differ per visitor is ignored: the widget Id, text, button labels, image alt text, chart titles, chart and progress data, button URLs and bodies, and the refresh label. Only whether text, labels, alt text, and titles are empty is included. Styles, positions, element order, image sources, and the background are included. Compute returns null when the JSON cannot be deserialized or the widget has no rows or columns; validate payloads with the renderer for the full rule set.

Colors

Use WidgetColor to create renderer-compatible hexadecimal colors without formatting channel values by hand:

using WidgetStudio.Contracts;

var background = WidgetColor.Rgb(16, 24, 39);       // #101827
var overlay = WidgetColor.Rgba(16, 24, 39, 184);    // #101827b8
var softBlue = WidgetColor.Pastel(WidgetColor.Blue); // #8080ff
var transparent = WidgetColor.Transparent;           // #00000000

Pastel accepts #RGB, #RRGGBB, and #RRGGBBAA values, blends the color toward white, and preserves an input alpha channel. Its default blend amount is 50%; pass a value from 0 to 1 as the second argument to control the blend.

Compatibility

The package and the npm renderer share the same JSON wire format, and the repository tests serialized contracts against the built renderer. Use matching versions of WidgetStudio.Contracts and @lieselthuriot/widget-renderer.

License

MIT