@unofficialbox/box-open-elements 0.21.0 → 0.23.0

package/dist/patterns/flow-builder/flow-builder.d.ts

@@ -1,16 +1,30 @@
 import { BaseElement } from "../../core/index.js";
-import { type FlowKind, type FlowNode, type NodePath } from "./model.js";
-export type InspectorRenderer = (node: FlowNode, container: HTMLElement) => void | (() => void);
-/** Host-owned document editing with accessible navigation and responsive inspection. */
-export declare class FlowBuilder extends BaseElement {
+import { type FlowKind, type FlowModel, type FlowNode, type FlowNodeBase, type NodePath } from "./model.js";
+export type InspectorRenderer<N extends FlowNodeBase = FlowNode> = (node: N, container: HTMLElement) => void | (() => void);
+export interface ValidationOptions {
+    /**
+     * Show the message in the builder's own error line (default `true`). Pass
+     * `false` when the host already shows the error persistently, so the
+     * message isn't on screen twice; the step is still marked and announced.
+     */
+    showMessage?: boolean;
+}
+/**
+ * Host-owned document editing with accessible navigation and responsive inspection.
+ * `N` is the host's node type; it defaults to {@link FlowNode}, which the default
+ * model reads. Hosts with their own document shape set {@link model}.
+ */
+export declare class FlowBuilder<N extends FlowNodeBase = FlowNode> extends BaseElement {
     static readonly tagName = "box-flow-builder";
     private nodesValue;
+    private modelValue;
     private catalogValue;
     private selectedValue;
     private invalidValue;
     private renderer?;
     private cleanupInspector?;
     private inspected;
+    private headingEl?;
     private renderedRenderer?;
     private observer?;
     private narrow;
@@ -24,14 +38,25 @@ export declare class FlowBuilder extends BaseElement {
     private inspector;
     private drawer;
     private error;
-    get nodes(): FlowNode[];
-    set nodes(value: FlowNode[]);
-    get catalog(): readonly FlowKind[];
-    set catalog(value: readonly FlowKind[]);
-    get selected(): FlowNode | null;
-    set selected(node: FlowNode | null);
-    get renderInspector(): InspectorRenderer | undefined;
-    set renderInspector(renderer: InspectorRenderer | undefined);
+    static get observedAttributes(): string[];
+    get nodes(): N[];
+    set nodes(value: N[]);
+    /** How to read the host document; defaults to `body` / `branches` ({@link FlowNode}). */
+    get model(): FlowModel<N>;
+    set model(value: FlowModel<N>);
+    /** Text above the first step (`start-label`). */
+    get startLabel(): string;
+    set startLabel(value: string);
+    /** Text below the last step (`end-label`). */
+    get endLabel(): string;
+    set endLabel(value: string);
+    get catalog(): readonly FlowKind<N>[];
+    set catalog(value: readonly FlowKind<N>[]);
+    get selected(): N | null;
+    set selected(node: N | null);
+    get renderInspector(): InspectorRenderer<N> | undefined;
+    set renderInspector(renderer: InspectorRenderer<N> | undefined);
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private setNarrow;
@@ -39,10 +64,16 @@ export declare class FlowBuilder extends BaseElement {
     protected setupListeners(): void;
     private closePicker;
     private insert;
-    select(node: FlowNode | null): void;
+    select(node: N | null): void;
     /** Mark validation without opening a sheet over the error on a narrow screen. */
-    setValidation(message: string, path?: NodePath, document?: unknown): void;
+    setValidation(message: string, path?: NodePath, document?: unknown, options?: ValidationOptions): void;
     refresh(): void;
+    /**
+     * Re-render one step's card and the inspector heading after the host edits
+     * its fields. Structural edits (adding, removing, moving steps) need
+     * {@link refresh}.
+     */
+    refreshNode(node: N): void;
     protected update(): void;
     private updateInspector;
 }

package/dist/patterns/flow-builder/flow-builder.js

@@ -1,17 +1,23 @@
 import { BaseElement } from "../../core/index.js";
 import { announce } from "../../foundations/a11y/index.js";
-import { nodeAtPath, nodeTitle } from "./model.js";
-import { InsertPoint } from "./primitives.js";
-/** Host-owned document editing with accessible navigation and responsive inspection. */
+import { defaultFlowModel, nodeAtPath, nodeDescription, nodeTitle } from "./model.js";
+import { FLOW_SPINE_PARTS, InsertPoint, KIND_PICKER_PARTS } from "./primitives.js";
+/**
+ * Host-owned document editing with accessible navigation and responsive inspection.
+ * `N` is the host's node type; it defaults to {@link FlowNode}, which the default
+ * model reads. Hosts with their own document shape set {@link model}.
+ */
 export class FlowBuilder extends BaseElement {
     static tagName = "box-flow-builder";
     nodesValue = [];
+    modelValue = defaultFlowModel;
     catalogValue = [];
     selectedValue = null;
     invalidValue = null;
     renderer;
     cleanupInspector;
     inspected;
+    headingEl;
     renderedRenderer;
     observer;
     narrow = false;
@@ -25,8 +31,18 @@ export class FlowBuilder extends BaseElement {
     inspector;
     drawer;
     error;
+    static get observedAttributes() { return ["start-label", "end-label"]; }
     get nodes() { return this.nodesValue; }
     set nodes(value) { this.nodesValue = value; this.refresh(); }
+    /** How to read the host document; defaults to `body` / `branches` ({@link FlowNode}). */
+    get model() { return this.modelValue; }
+    set model(value) { this.modelValue = value; this.refresh(); }
+    /** Text above the first step (`start-label`). */
+    get startLabel() { return this.getAttribute("start-label") ?? "Flow starts"; }
+    set startLabel(value) { this.setAttribute("start-label", value); }
+    /** Text below the last step (`end-label`). */
+    get endLabel() { return this.getAttribute("end-label") ?? "Flow ends"; }
+    set endLabel(value) { this.setAttribute("end-label", value); }
     get catalog() { return this.catalogValue; }
     set catalog(value) { this.catalogValue = value; this.refresh(); }
     get selected() { return this.selectedValue; }
@@ -34,6 +50,11 @@ export class FlowBuilder extends BaseElement {
     get renderInspector() { return this.renderer; }
     set renderInspector(renderer) { this.renderer = renderer; if (this.isRendered)
         this.updateInspector(); }
+    attributeChangedCallback(name, oldValue, newValue) {
+        super.attributeChangedCallback(name, oldValue, newValue);
+        if (oldValue !== newValue)
+            this.refresh();
+    }
     connectedCallback() {
         super.connectedCallback();
         if (typeof ResizeObserver !== "undefined") {
@@ -68,7 +89,7 @@ export class FlowBuilder extends BaseElement {
       [part=picker-popup]{position:fixed;z-index:1000;max-width:min(360px,calc(100vw - 24px));max-height:65vh;overflow:auto;padding:16px;background:var(--boe-token-surface-surface,#fff);border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:12px;box-shadow:0 8px 32px #0003}
       [part=error]{color:var(--boe-token-text-status-text-error,#b92340);margin-bottom:16px;overflow-wrap:anywhere}
       [hidden]{display:none!important} h2{font:inherit;font-weight:650;margin:0 0 12px}
-      </style><div part="error" hidden></div><div part="layout"><box-flow-spine></box-flow-spine><aside part="inspector"><box-kind-picker></box-kind-picker><div part="editor"></div></aside></div><div part="picker-popup" hidden><box-kind-picker></box-kind-picker></div><box-drawer position="bottom" size="large"></box-drawer>`;
+      </style><div part="error" hidden></div><div part="layout"><box-flow-spine exportparts="${FLOW_SPINE_PARTS.join(", ")}"></box-flow-spine><aside part="inspector"><box-kind-picker exportparts="${KIND_PICKER_PARTS.join(", ")}"></box-kind-picker><div part="editor"></div></aside></div><div part="picker-popup" hidden><box-kind-picker exportparts="${KIND_PICKER_PARTS.join(", ")}"></box-kind-picker></div><box-drawer position="bottom" size="large"></box-drawer>`;
         this.spine = this.shadowRoot.querySelector("box-flow-spine");
         this.aside = this.shadowRoot.querySelector("aside");
         this.palette = this.aside.querySelector("box-kind-picker");
@@ -129,7 +150,7 @@ export class FlowBuilder extends BaseElement {
         this.refresh();
         // Keep the newly inserted card visible on small screens; explicit selection opens editing.
         this.spine.focusNode(node);
-        announce(`Added ${nodeTitle(node, this.catalog)}`, "polite", this.ownerDocument);
+        announce(`Added ${nodeTitle(node, this.catalog, this.model)}`, "polite", this.ownerDocument);
         this.dispatchEvent(new CustomEvent("flow-changed", { detail: { nodes: this.nodes, node, reason: "insert" }, bubbles: true, composed: true }));
     }
     select(node) {
@@ -141,10 +162,11 @@ export class FlowBuilder extends BaseElement {
         this.dispatchEvent(new CustomEvent("selection-changed", { detail: { node }, bubbles: true, composed: true }));
     }
     /** Mark validation without opening a sheet over the error on a narrow screen. */
-    setValidation(message, path = [], document = { body: this.nodes }) {
+    setValidation(message, path = [], document = { body: this.nodes }, options = {}) {
         this.invalidValue = message ? nodeAtPath(document, path) : null;
-        this.error.textContent = message;
-        this.error.hidden = !message;
+        const show = options.showMessage ?? true;
+        this.error.textContent = show ? message : "";
+        this.error.hidden = !message || !show;
         this.spine.select(this.selected, this.invalidValue);
         if (message) {
             if (!this.narrow && this.invalidValue)
@@ -156,9 +178,28 @@ export class FlowBuilder extends BaseElement {
     }
     refresh() { if (this.isRendered)
         this.update(); }
+    /**
+     * Re-render one step's card and the inspector heading after the host edits
+     * its fields. Structural edits (adding, removing, moving steps) need
+     * {@link refresh}.
+     */
+    refreshNode(node) {
+        if (!this.isRendered)
+            return;
+        this.spine.refreshNode(node);
+        if (node === this.selected) {
+            const title = nodeTitle(node, this.catalog, this.model);
+            if (this.headingEl)
+                this.headingEl.textContent = title;
+            this.drawer.heading = title;
+        }
+    }
     update() {
         this.spine.nodes = this.nodes;
         this.spine.catalog = this.catalog;
+        this.spine.model = this.model;
+        this.spine.startLabel = this.startLabel;
+        this.spine.endLabel = this.endLabel;
         this.spine.selected = this.selected;
         this.spine.invalid = this.invalidValue;
         this.spine.refresh();
@@ -183,16 +224,18 @@ export class FlowBuilder extends BaseElement {
         this.renderedRenderer = this.renderer;
         if (this.selected) {
             const heading = document.createElement("h2");
-            heading.textContent = nodeTitle(this.selected, this.catalog);
+            heading.setAttribute("part", "inspector-heading");
+            heading.textContent = nodeTitle(this.selected, this.catalog, this.model);
             this.inspector.append(heading);
+            this.headingEl = heading;
             if (this.renderer)
                 this.cleanupInspector = this.renderer(this.selected, this.inspector) || undefined;
             else {
                 const description = document.createElement("p");
-                description.textContent = this.selected.description || this.catalog.find(kind => kind.kind === this.selected.kind)?.description || "Select a step to inspect its configuration.";
+                description.textContent = nodeDescription(this.selected, this.catalog, this.model) || "Select a step to inspect its configuration.";
                 this.inspector.append(description);
             }
-            this.drawer.heading = nodeTitle(this.selected, this.catalog);
+            this.drawer.heading = nodeTitle(this.selected, this.catalog, this.model);
         }
         this.drawer.open = this.narrow && Boolean(this.selected);
     }

package/dist/patterns/flow-builder/model.d.ts

@@ -1,6 +1,13 @@
-export interface FlowNode {
-    id?: string;
+/**
+ * The least the flow builder needs from a node. Hosts keep their own
+ * document shape; a {@link FlowModel} tells the builder how to read it.
+ */
+export interface FlowNodeBase {
     kind: string;
+}
+/** The document shape the default model reads. */
+export interface FlowNode extends FlowNodeBase {
+    id?: string;
     title?: string;
     description?: string;
     status?: string;
@@ -11,23 +18,64 @@ export interface FlowBranch {
     label: string;
     body: FlowNode[];
 }
-export interface FlowKind {
+/** One list of steps nested under a node. */
+export interface FlowChildList {
+    /** A branch label. Unlabeled lists render as the node's inline body; labeled lists render as branch columns. */
+    label?: string;
+    /** The host's own array. The builder splices new steps into it. */
+    list: FlowNodeBase[];
+    /** Show a remove control on this branch; the builder emits `branch-remove-request`. */
+    removable?: boolean;
+}
+/**
+ * How the builder reads a host document. Every traversal, title and insert
+ * label goes through the model, so hosts pass their own nodes — identity
+ * (selection, undo, validation paths) is preserved.
+ */
+export interface FlowModel<N extends FlowNodeBase = FlowNodeBase> {
+    /** Nested lists under `node`, in display order. */
+    children(node: N): FlowChildList[];
+    /** A distinct name for the node; falls back to its kind's label. */
+    title?(node: N): string | undefined;
+    /** One sentence about what the node does at run time; falls back to its kind's description. */
+    description?(node: N): string | undefined;
+    /** A short status line shown on the card. */
+    status?(node: N): string | undefined;
+    /** When it returns a label, the node's branches get an add control; the builder emits `branch-add-request`. */
+    addBranchLabel?(node: N): string | undefined;
+}
+/** Reads {@link FlowNode}: `body` renders inline and `branches` render as labeled columns. */
+export declare const defaultFlowModel: FlowModel<FlowNode>;
+export interface FlowKind<N extends FlowNodeBase = FlowNodeBase> {
     kind: string;
     label: string;
     description: string;
     group?: string;
     /** Supply an authored SVG node (for example from a named glyph import). */
     icon?: () => Node;
-    create(): FlowNode;
+    /**
+     * Icon color. `accent` (the default) uses the brand color; `neutral` uses
+     * secondary text, so a host can reserve the accent for its primary object.
+     */
+    tone?: "accent" | "neutral";
+    create(): N;
 }
 export interface FlowInsertDetail {
-    list: FlowNode[];
+    list: FlowNodeBase[];
     index: number;
     label: string;
 }
+export interface FlowBranchRequestDetail {
+    node: FlowNodeBase;
+    /** The branch's position among the node's labeled lists (remove requests only). */
+    index?: number;
+    /** The branch's own list (remove requests only). */
+    list?: FlowNodeBase[];
+}
 export type NodePath = readonly (string | number)[];
-export declare const nodeTitle: (node: FlowNode, catalog?: readonly FlowKind[]) => string;
-export declare function cardLabel(node: FlowNode, catalog?: readonly FlowKind[], invalid?: boolean): string;
-export declare function insertLabel(list: readonly FlowNode[], index: number, where?: string, catalog?: readonly FlowKind[]): string;
+export declare const nodeTitle: (node: FlowNodeBase, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>) => string;
+export declare const nodeDescription: (node: FlowNodeBase, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>) => string;
+export declare function cardLabel(node: FlowNodeBase, catalog?: readonly FlowKind[], invalid?: boolean, model?: FlowModel<FlowNodeBase>): string;
+export declare function insertLabel(list: readonly FlowNodeBase[], index: number, where?: string, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>): string;
 /** Return the deepest node on a validation path, including paths ending in a field. */
-export declare function nodeAtPath(document: unknown, path: NodePath): FlowNode | null;
+export declare function nodeAtPath(document: unknown, path: NodePath): FlowNodeBase | null;

package/dist/patterns/flow-builder/model.js

@@ -1,17 +1,29 @@
-export const nodeTitle = (node, catalog = []) => node.title || catalog.find(kind => kind.kind === node.kind)?.label || "Step";
-export function cardLabel(node, catalog = [], invalid = false) {
+/** Reads {@link FlowNode}: `body` renders inline and `branches` render as labeled columns. */
+export const defaultFlowModel = {
+    children: node => [
+        ...(node.body ? [{ list: node.body }] : []),
+        ...(node.branches ?? []).map(branch => ({ label: branch.label, list: branch.body })),
+    ],
+    title: node => node.title,
+    description: node => node.description,
+    status: node => node.status,
+};
+export const nodeTitle = (node, catalog = [], model = defaultFlowModel) => model.title?.(node) || catalog.find(kind => kind.kind === node.kind)?.label || "Step";
+export const nodeDescription = (node, catalog = [], model = defaultFlowModel) => model.description?.(node) || catalog.find(kind => kind.kind === node.kind)?.description || "";
+export function cardLabel(node, catalog = [], invalid = false, model = defaultFlowModel) {
     const kind = catalog.find(entry => entry.kind === node.kind);
-    const title = nodeTitle(node, catalog);
-    return [title, kind?.label !== title ? kind?.label : "", node.description || kind?.description, node.status, invalid ? "Needs attention" : ""].filter(Boolean).join(". ");
+    const title = nodeTitle(node, catalog, model);
+    return [title, kind?.label !== title ? kind?.label : "", nodeDescription(node, catalog, model), model.status?.(node), invalid ? "Needs attention" : ""].filter(Boolean).join(". ");
 }
-export function insertLabel(list, index, where = "in the flow", catalog = []) {
+export function insertLabel(list, index, where = "in the flow", catalog = [], model = defaultFlowModel) {
+    const title = (node) => nodeTitle(node, catalog, model);
     if (!list.length)
         return `Add the first step ${where}`;
     if (index === 0)
-        return `Insert before ${nodeTitle(list[0], catalog)} ${where}`;
+        return `Insert before ${title(list[0])} ${where}`;
     if (index >= list.length)
-        return `Insert after ${nodeTitle(list[list.length - 1], catalog)} ${where}`;
-    return `Insert between ${nodeTitle(list[index - 1], catalog)} and ${nodeTitle(list[index], catalog)} ${where}`;
+        return `Insert after ${title(list[list.length - 1])} ${where}`;
+    return `Insert between ${title(list[index - 1])} and ${title(list[index])} ${where}`;
 }
 /** Return the deepest node on a validation path, including paths ending in a field. */
 export function nodeAtPath(document, path) {

package/dist/patterns/flow-builder/primitives.d.ts

@@ -1,9 +1,16 @@
 import { BaseElement } from "../../core/index.js";
-import { type FlowInsertDetail, type FlowKind, type FlowNode } from "./model.js";
+import { type FlowInsertDetail, type FlowKind, type FlowModel, type FlowNodeBase } from "./model.js";
+/** Parts a card exposes; the spine and builder forward them unchanged. */
+export declare const FLOW_CARD_PARTS: readonly ["card", "icon", "title", "kind", "description", "status", "error"];
+/** Parts the spine exposes (its own plus forwarded card and insert-point parts). */
+export declare const FLOW_SPINE_PARTS: readonly ["spine", "endpoint", "body", "branches", "branch", "branch-header", "branch-label", "branch-remove", "branch-add", "insert", "card", "icon", "title", "kind", "description", "status", "error"];
+/** Parts a kind picker exposes. */
+export declare const KIND_PICKER_PARTS: readonly ["choices", "group-heading", "choice", "choice-icon", "choice-label", "choice-description"];
 export declare class FlowCard extends BaseElement {
     static readonly tagName = "box-flow-card";
-    node: FlowNode;
+    node: FlowNodeBase;
     catalog: readonly FlowKind[];
+    model: FlowModel<FlowNodeBase>;
     selected: boolean;
     invalid: boolean;
     protected renderTemplate(): void;
@@ -32,16 +39,19 @@ export declare class KindPicker extends BaseElement {
 }
 export declare class FlowSpine extends BaseElement {
     static readonly tagName = "box-flow-spine";
-    nodes: FlowNode[];
+    nodes: FlowNodeBase[];
     catalog: readonly FlowKind[];
-    selected: FlowNode | null;
-    invalid: FlowNode | null;
+    model: FlowModel<FlowNodeBase>;
+    selected: FlowNodeBase | null;
+    invalid: FlowNodeBase | null;
     startLabel: string;
     endLabel: string;
     private cards;
     protected renderTemplate(): void;
     refresh(): void;
-    focusNode(node: FlowNode): void;
-    select(node: FlowNode | null, invalid?: FlowNode | null): void;
+    /** Re-render one card after its fields change, without rebuilding the spine. */
+    refreshNode(node: FlowNodeBase): void;
+    focusNode(node: FlowNodeBase): void;
+    select(node: FlowNodeBase | null, invalid?: FlowNodeBase | null): void;
     protected update(): void;
 }

package/dist/patterns/flow-builder/primitives.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-import { boeFocusVisibleStyles } from "../../foundations/tokens/index.js";
-import { cardLabel, insertLabel, nodeTitle } from "./model.js";
+import { boeFocusVisibleStyles } from "../../foundations/tokens/interaction.js";
+import { cardLabel, defaultFlowModel, insertLabel, nodeDescription, nodeTitle } from "./model.js";
 const styles = `
   :host { display:block; min-width:0; color:var(--boe-token-text-text,#222); font:inherit; }
   :host([hidden]) { display:none!important; }
@@ -8,10 +8,17 @@ const styles = `
   ${boeFocusVisibleStyles("button")}
 `;
 function emit(host, name, detail) { host.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true })); }
+/** Parts a card exposes; the spine and builder forward them unchanged. */
+export const FLOW_CARD_PARTS = ["card", "icon", "title", "kind", "description", "status", "error"];
+/** Parts the spine exposes (its own plus forwarded card and insert-point parts). */
+export const FLOW_SPINE_PARTS = ["spine", "endpoint", "body", "branches", "branch", "branch-header", "branch-label", "branch-remove", "branch-add", "insert", ...FLOW_CARD_PARTS];
+/** Parts a kind picker exposes. */
+export const KIND_PICKER_PARTS = ["choices", "group-heading", "choice", "choice-icon", "choice-label", "choice-description"];
 export class FlowCard extends BaseElement {
     static tagName = "box-flow-card";
-    node = { id: "", kind: "" };
+    node = { kind: "" };
     catalog = [];
+    model = defaultFlowModel;
     selected = false;
     invalid = false;
     renderTemplate() {
@@ -20,7 +27,7 @@ export class FlowCard extends BaseElement {
       button[aria-pressed=true] { border-color:var(--boe-token-surface-surface-brand,#0061d5); background:color-mix(in srgb,var(--boe-token-surface-surface-brand,#0061d5) 8%,var(--boe-token-surface-surface,#fff)); }
       button[data-invalid=true] { border-color:var(--boe-token-text-status-text-error,#b92340); }
       button.has-icon{grid-template-columns:20px minmax(0,1fr);column-gap:12px} button.has-icon [part=icon]{grid-column:1;grid-row:1/span 4} button.has-icon [part=title],button.has-icon [part=kind],button.has-icon [part=description],button.has-icon [part=status],button.has-icon [part=error]{grid-column:2}
-      [part=icon]{color:var(--boe-token-surface-surface-brand,#0061d5);width:20px;height:20px} [part=icon] svg{display:block;width:20px;height:20px} [part=title] { font-weight:650; } [part=kind],[part=description] { color:var(--boe-token-text-text-secondary,#666); } [part=error] { color:var(--boe-token-text-status-text-error,#b92340); }
+      [part=icon]{color:var(--boe-token-surface-surface-brand,#0061d5);width:20px;height:20px} [part=icon][data-tone=neutral]{color:var(--boe-token-text-text-secondary,#666)} [part=icon] svg{display:block;width:20px;height:20px} [part=title] { font-weight:650; } [part=kind],[part=description] { color:var(--boe-token-text-text-secondary,#666); } [part=error] { color:var(--boe-token-text-status-text-error,#b92340); }
       [hidden] { display:none!important; }
       </style><button type="button" part="card"><span part="icon" aria-hidden="true"></span><span part="title"></span><span part="kind"></span><span part="description"></span><span part="status"></span><span part="error">Needs attention</span></button>`;
     }
@@ -30,16 +37,17 @@ export class FlowCard extends BaseElement {
     focus(options) { this.shadowRoot?.querySelector("button")?.focus(options); }
     update() {
         const kind = this.catalog.find(kind => kind.kind === this.node.kind);
-        const title = nodeTitle(this.node, this.catalog);
+        const title = nodeTitle(this.node, this.catalog, this.model);
         const button = this.shadowRoot.querySelector("button");
         button.setAttribute("aria-pressed", String(this.selected));
         button.classList.toggle("has-icon", Boolean(kind?.icon));
-        button.setAttribute("aria-label", cardLabel(this.node, this.catalog, this.invalid));
+        button.setAttribute("aria-label", cardLabel(this.node, this.catalog, this.invalid, this.model));
         button.dataset.invalid = String(this.invalid);
         const iconEl = this.shadowRoot.querySelector("[part=icon]");
         iconEl.replaceChildren(kind?.icon?.() ?? "");
         iconEl.hidden = !kind?.icon;
-        for (const [part, text] of Object.entries({ title, kind: kind?.label !== title ? kind?.label ?? "" : "", description: this.node.description || kind?.description || "", status: this.node.status || "" })) {
+        iconEl.dataset.tone = kind?.tone ?? "accent";
+        for (const [part, text] of Object.entries({ title, kind: kind?.label !== title ? kind?.label ?? "" : "", description: nodeDescription(this.node, this.catalog, this.model), status: this.model.status?.(this.node) || "" })) {
             const element = this.shadowRoot.querySelector(`[part=${part}]`);
             element.textContent = text;
             element.hidden = !text;
@@ -59,7 +67,7 @@ export class KindPicker extends BaseElement {
     static tagName = "box-kind-picker";
     catalog = [];
     variant = "inline";
-    renderTemplate() { this.shadowRoot.innerHTML = `<style>${styles} [part=choices]{display:grid;gap:8px} button{text-align:start;padding:10px;border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:8px;background:var(--boe-token-surface-surface,#fff)} small{display:block;color:var(--boe-token-text-text-secondary,#666)} h3{font:inherit;font-weight:650;margin:12px 0 4px}</style><div part="choices"></div>`; }
+    renderTemplate() { this.shadowRoot.innerHTML = `<style>${styles} [part=choices]{display:grid;gap:8px} button{text-align:start;padding:10px;border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:8px;background:var(--boe-token-surface-surface,#fff)} button.has-icon{display:grid;grid-template-columns:20px minmax(0,1fr);column-gap:10px;align-items:start} [part=choice-icon]{grid-row:1/span 2;width:20px;height:20px;color:var(--boe-token-surface-surface-brand,#0061d5)} [part=choice-icon][data-tone=neutral]{color:var(--boe-token-text-text-secondary,#666)} [part=choice-icon] svg{display:block;width:20px;height:20px} [part=choice-label]{display:block} small{display:block;color:var(--boe-token-text-text-secondary,#666)} h3{font:inherit;font-weight:650;margin:12px 0 4px}</style><div part="choices"></div>`; }
     setupListeners() {
         this.shadowRoot.addEventListener("keydown", event => {
             const e = event;
@@ -96,17 +104,32 @@ export class KindPicker extends BaseElement {
                 const heading = document.createElement("h3");
                 heading.textContent = kind.group;
                 heading.setAttribute("role", "presentation");
+                heading.setAttribute("part", "group-heading");
                 choices.append(heading);
                 group = kind.group;
             }
             const button = document.createElement("button");
             button.type = "button";
-            button.textContent = kind.label;
+            button.setAttribute("part", "choice");
+            if (kind.icon) {
+                const icon = document.createElement("span");
+                icon.setAttribute("part", "choice-icon");
+                icon.setAttribute("aria-hidden", "true");
+                icon.dataset.tone = kind.tone ?? "accent";
+                icon.append(kind.icon());
+                button.classList.add("has-icon");
+                button.append(icon);
+            }
+            const label = document.createElement("span");
+            label.setAttribute("part", "choice-label");
+            label.textContent = kind.label;
+            button.append(label);
             if (this.variant === "menu") {
                 button.setAttribute("role", "menuitem");
                 button.tabIndex = index === 0 ? 0 : -1;
             }
             const description = document.createElement("small");
+            description.setAttribute("part", "choice-description");
             description.textContent = kind.description;
             button.append(description);
             button.addEventListener("click", () => emit(this, "kind-pick", { kind }));
@@ -120,14 +143,17 @@ export class FlowSpine extends BaseElement {
     static tagName = "box-flow-spine";
     nodes = [];
     catalog = [];
+    model = defaultFlowModel;
     selected = null;
     invalid = null;
     startLabel = "Flow starts";
     endLabel = "Flow ends";
     cards = new Map();
-    renderTemplate() { this.shadowRoot.innerHTML = `<style>${styles} [part=spine]{display:grid;gap:0;min-width:0} [part=branches]{display:flex;gap:16px;overflow-x:auto;max-width:100%;padding:8px} [part=branch]{flex:1 0 240px;min-width:0} [part=body]{margin:0 0 0 16px;border-inline-start:2px solid var(--boe-token-stroke-stroke,#ddd);padding:8px 12px} [part=endpoint]{text-align:center;font-weight:600;padding:12px} h3{font:inherit;font-weight:600}</style><div part="spine"></div>`; }
+    renderTemplate() { this.shadowRoot.innerHTML = `<style>${styles} [part=spine]{display:grid;gap:0;min-width:0} [part=branches]{display:flex;gap:16px;overflow-x:auto;max-width:100%;padding:8px} [part=branch]{flex:1 0 240px;min-width:0} [part=body]{margin:0 0 0 16px;border-inline-start:2px solid var(--boe-token-stroke-stroke,#ddd);padding:8px 12px} [part=endpoint]{text-align:center;font-weight:600;padding:12px} [part=branch-header]{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:1em 0} h3{font:inherit;font-weight:600;margin:0} [part=branch-remove],[part=branch-add]{border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:16px;background:var(--boe-token-surface-surface,#fff);padding:4px 10px} [part=branch-add]{justify-self:center;margin:4px 0}</style><div part="spine"></div>`; }
     refresh() { if (this.isRendered)
         this.update(); }
+    /** Re-render one card after its fields change, without rebuilding the spine. */
+    refreshNode(node) { this.cards.get(node)?.refresh(); }
     focusNode(node) { this.cards.get(node)?.focus(); }
     select(node, invalid = this.invalid) { this.selected = node; this.invalid = invalid; for (const [item, card] of this.cards) {
         card.selected = item === node;
@@ -137,11 +163,13 @@ export class FlowSpine extends BaseElement {
     update() {
         const root = this.shadowRoot.querySelector("[part=spine]");
         const seen = new Set();
+        const title = (node) => nodeTitle(node, this.catalog, this.model);
         const listView = (list, where, ancestors) => {
             const fragment = document.createDocumentFragment();
             for (let index = 0; index <= list.length; index++) {
                 const point = document.createElement(InsertPoint.tagName);
-                point.detail = { list, index, label: insertLabel(list, index, where, this.catalog) };
+                point.setAttribute("exportparts", "button: insert");
+                point.detail = { list, index, label: insertLabel(list, index, where, this.catalog, this.model) };
                 fragment.append(point);
                 if (index === list.length)
                     break;
@@ -150,26 +178,62 @@ export class FlowSpine extends BaseElement {
                     continue;
                 seen.add(node);
                 const card = this.cards.get(node) ?? document.createElement(FlowCard.tagName);
+                card.setAttribute("exportparts", FLOW_CARD_PARTS.join(", "));
                 this.cards.set(node, card);
                 card.node = node;
                 card.catalog = this.catalog;
+                card.model = this.model;
                 card.selected = node === this.selected;
                 card.invalid = node === this.invalid;
                 card.refresh();
                 fragment.append(card);
                 const nextAncestors = new Set([...ancestors, node]);
-                if (node.body) {
+                const children = this.model.children(node);
+                for (const child of children.filter(child => child.label === undefined)) {
                     const body = document.createElement("section");
                     body.setAttribute("part", "body");
-                    body.setAttribute("aria-label", `${nodeTitle(node, this.catalog)} steps`);
-                    body.append(listView(node.body, `inside ${nodeTitle(node, this.catalog)}`, nextAncestors));
+                    body.setAttribute("aria-label", `${title(node)} steps`);
+                    body.append(listView(child.list, `inside ${title(node)}`, nextAncestors));
                     fragment.append(body);
                 }
-                if (node.branches) {
+                const branchLists = children.filter(child => child.label !== undefined);
+                const addLabel = this.model.addBranchLabel?.(node);
+                if (branchLists.length || addLabel) {
                     const branches = document.createElement("div");
                     branches.setAttribute("part", "branches");
-                    node.branches.forEach(branch => { const column = document.createElement("section"); column.setAttribute("part", "branch"); column.setAttribute("aria-label", branch.label); const heading = document.createElement("h3"); heading.textContent = branch.label; column.append(heading, listView(branch.body, `in ${branch.label}`, nextAncestors)); branches.append(column); });
+                    branchLists.forEach((branch, branchIndex) => {
+                        const label = branch.label;
+                        const column = document.createElement("section");
+                        column.setAttribute("part", "branch");
+                        column.setAttribute("aria-label", label);
+                        const header = document.createElement("div");
+                        header.setAttribute("part", "branch-header");
+                        const heading = document.createElement("h3");
+                        heading.setAttribute("part", "branch-label");
+                        heading.textContent = label;
+                        header.append(heading);
+                        if (branch.removable) {
+                            const remove = document.createElement("button");
+                            remove.type = "button";
+                            remove.setAttribute("part", "branch-remove");
+                            remove.textContent = "Remove";
+                            remove.setAttribute("aria-label", `Remove ${label} from ${title(node)}`);
+                            remove.addEventListener("click", () => emit(this, "branch-remove-request", { node, index: branchIndex, list: branch.list }));
+                            header.append(remove);
+                        }
+                        column.append(header, listView(branch.list, `in ${label}`, nextAncestors));
+                        branches.append(column);
+                    });
                     fragment.append(branches);
+                    if (addLabel) {
+                        const add = document.createElement("button");
+                        add.type = "button";
+                        add.setAttribute("part", "branch-add");
+                        add.textContent = addLabel;
+                        add.setAttribute("aria-label", `${addLabel} to ${title(node)}`);
+                        add.addEventListener("click", () => emit(this, "branch-add-request", { node }));
+                        fragment.append(add);
+                    }
                 }
             }
             return fragment;

package/dist/patterns/governance/governance-panel.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-governance-panel";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/insights/chart-panel.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-chart-panel";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/insights/metric-card.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-metric-card";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")