FluxFlow.Components.Designer 6.0.0-rc.1

FluxFlow.Components.Designer

Reusable component presentation metadata and canonical application-editing contracts for FluxFlow. The package depends on FluxFlow.Composition, but not on FluxFlow.Engine or a rendering framework.

Registration

Use AddFluxFlowComponents() when a tool needs component catalogs without hosting an application. Family extensions target the returned FluxFlowRegistrationBuilder:

var services = new ServiceCollection();

services
    .AddFluxFlowComponents()
    .AddSources()
    .AddMapping()
    .AddTimers();

using var provider = services.BuildServiceProvider();
var runtimeCatalog = provider.GetRequiredService<ComponentCatalog>();
var designCatalog = provider.GetRequiredService<ComponentDesignMetadataCatalog>();

ComponentCatalog remains owned by Composition. Every designed registration automatically contributes to the immutable ComponentDesignMetadataCatalog; there is no terminal catalog-registration call and no second component registry. A chain containing only Advanced.AddDynamicComponent(...) registers only the runtime catalog.

Complete Designed Contracts

Official packages create complete ComponentContract values through DesignedComponentContract.Create(...). One flat declaration produces the exact runtime descriptor, typed authoring handle, and presentation metadata. Family registration passes that same contract to AddDesignedComponent(...); metadata inspection never activates the node factory.

public static ComponentContract<TransformHandle> Transform { get; } =
    DesignedComponentContract.Create(
        "sample.transform",
        ConfigureTransform,
        static component => new TransformHandle(component));

services.AddFluxFlowComponents()
    .AddDesignedComponent(Transform);

Code-first application builders carry the contract's runtime descriptor in the built definition. JSON hosts use the family extension or the explicit designed registration above because JSON contains no executable descriptor.

Low-Level Designed Components

The retained low-level AddComponent(type, callback) path creates the runtime descriptor and presentation metadata from one authoritative, flat callback. The type appears once, the callback runs immediately, and no Build, Commit, nested builder, reflection, or scanning is involved.

There is no parallel metadata builder or option/resource metadata factory. Registration authors use this callback; standalone tooling constructs the immutable metadata records directly and passes them to ComponentDesignMetadataCatalog.

builder.AddComponent("sample.transform", component =>
{
    component.UseProcessing(CompositionProcessingCapabilities.Sequential);

    component.WithDisplay(
        displayName: "Sample Transform",
        category: "Samples",
        summary: "Transforms a sample value.",
        iconKey: "transform",
        preferredNodeName: "transform",
        suggestedEditorWidth: 420);

    component
        .UseFactory(CreateTransform)
        .HasInput(
            "Input",
            static node => node.Input,
            displayName: "Input",
            group: "Values",
            order: 0,
            summary: "Value to transform.",
            isPrimary: true)
        .HasOutput(
            "Output",
            static node => node.Output,
            displayName: "Output",
            group: "Results",
            order: 0,
            summary: "Transformed value.",
            isPrimary: true)
        .HasEvents(
            "Diagnostics",
            static node => node.Events,
            displayName: "Diagnostics",
            group: "Diagnostics",
            order: 1);

    component.AddOption<string>(
        "expression",
        kind: OptionValueKind.Expression,
        displayName: "Expression",
        helperText: "Expression evaluated for each input.",
        isRequired: true,
        section: "Mapping",
        editor: OptionDesignMetadataAttributeValues.Expression);

    component.AddOption<string>(
        "mode",
        kind: OptionValueKind.Enum,
        displayName: "Mode",
        defaultValue: "strict");
    component.AddOptionChoice("mode", "strict", displayName: "Strict");
    component.AddOptionChoice("mode", "relaxed", displayName: "Relaxed");

    component.AddResource<IExpressionEngine>(
        "engine",
        displayName: "Engine",
        order: 0,
        summary: "Host-owned expression engine.",
        isRequired: true,
        ownership: ResourceDesignMetadataAttributeValues.HostOwned,
        pickerKind: ResourceDesignMetadataAttributeValues.ExpressionEngine);

    component.SetOptionAttribute("expression", "relatedResource", "engine");
    component.SetPortAttribute("Input", PortDirection.Input, "accepts", "json");
    component.AddAttribute("shape", "transform");
});

Root-level methods cover display information, ports, options, resources, choices, and attributes. References to unknown options, ports, or resources fail during registration. Duplicate names, invalid ranges, missing factories, duplicate output/event names, and invalid metadata also fail immediately. Event ports are explicit and may use any valid output name. They select a FlowEvent source and publish ComponentEvent values; no event metadata is injected implicitly and Events is not reserved.

Equivalent repeated built-in family registration is idempotent. A semantically different runtime descriptor or design registration for an existing type throws a clear conflict exception; registration never uses last-write-wins behavior.

Runtime-only dynamic components belong to FluxFlow.Composition and use the distinct Advanced.AddDynamicComponent(...) API, so Composition-only consumers do not need this package.

Metadata Contracts

• ComponentDesignMetadata describes display name, category, summary, icon, preferred node name, suggested width, processing capabilities, options, resources, ports, and attributes.
• OptionDesignMetadata describes value kind, default, requiredness, helper text, numeric/duration range, choices, and editor attributes.
• ResourceDesignMetadata describes a host-owned resource slot, order, value type hint, requiredness, summary, and picker attributes.
• PortDesignMetadata describes direction, display name, grouping, order, message/value types, cardinality, primary status, and attributes.
• ComponentDesignMetadataCatalog is a read-only, ordered snapshot. Its public constructor accepts metadata directly for standalone tooling; normal DI registration builds it automatically from designed components.

ComponentDesignMetadataValidator validates identifiers, null collections, duplicates, option kinds/defaults/ranges/choices, port directions and primary ports, resource/port ordering, and attributes. Designed registration adds the canonical processing hints and traced Events output, validates the complete metadata, and snapshots nested collections before changing DI. Direct catalog construction applies the same finalization, so later source mutations cannot change the catalog.

Option And Resource Hints

Option kinds are text, number, boolean, enum, multiline text, JSON, expression, duration, and secret. Enum options require choices. Min and Max apply to number and duration options.

Option attributes describe sections, importance, editor kind, syntax, and related resources. Resource attributes describe ownership, picker kind, key patterns, related options, and conditional requiredness. These are neutral host hints: the host still chooses controls, supplies keyed resources, owns secrets, and controls service lifetimes.

ComponentResourcePickerHints.Create(...) returns an ordered neutral view of host-owned picker hints. It does not enumerate, resolve, create, validate, or dispose host resources.

Canonical Application Persistence

DesignerApplicationPersistence loads and saves the same flat ApplicationDefinition used by Composition. It delegates JSON shape, address resolution, and link grammar to Composition rather than maintaining a second schema or parser.

var persistence = new DesignerApplicationPersistence(componentCatalog, metadataCatalog);
var loaded = persistence.Load(json);

var link = DesignerApplicationLink.Create(
    ApplicationAddress.WorkflowPort("Orders", "Read", "Output"),
    ApplicationAddress.WorkflowPort("Orders", "Validate", "Input"));

var edited = loaded.Document with
{
    Links = [.. loaded.Document.Links, link]
};

var savedJson = persistence.Serialize(edited, writeIndented: true);

Loads require exact canonical component and resource identities and return structured diagnostics for unknown values. Malformed component properties stay raw and round-trip unchanged. Conditional link validation can use an explicitly configured ApplicationLinkCompiler; there is no service discovery fallback.

Package Extensions

Component packages expose one normal extension over FluxFlowRegistrationBuilder and register every designed component with AddComponent(...):

public static FluxFlowRegistrationBuilder AddSampleTransforms(
    this FluxFlowRegistrationBuilder builder)
    => builder.AddComponent("sample.transform", component =>
    {
        component.WithDisplay(displayName: "Sample Transform", category: "Samples");
        component
            .UseFactory(CreateTransform)
            .HasInput("Input", static node => node.Input, displayName: "Input")
            .HasOutput("Output", static node => node.Output, displayName: "Output")
            .HasEvents("Events", static node => node.Events, displayName: "Events");
    });

Packages remain explicit and Engine-independent. The Designer package does not execute workflows, own resources, render UI, scan assemblies, or provide global registries.