@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/form-wizard/wizard-summary.d.ts

@@ -0,0 +1,62 @@
+import { summarizeWizardValues } from "./types.js";
+import type { WizardStepConfig, WizardSummaryField } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The review step of a `box-form-wizard`: everything collected so far, grouped
+ * by the step that collected it, with an Edit link per group.
+ *
+ * The card is read-only and emits `edit-requested` rather than navigating
+ * itself, so the host stays in charge of the wizard — the same intent contract
+ * the rest of the patterns use.
+ *
+ * Two details carry the weight:
+ *
+ * - Sections follow **step order**, so the summary reads back in the sequence
+ *   the user filled it in rather than in whatever order the fields were
+ *   declared.
+ * - A field naming a step that does not exist lands in a trailing section
+ *   instead of vanishing. A review card exists so someone can confirm what
+ *   they are submitting; silently dropping a row would let them confirm a
+ *   value they were never shown.
+ */
+export declare class WizardSummary extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private hostEl;
+    private fieldsRaw;
+    private fieldsCache;
+    private stepsRaw;
+    private stepsCache;
+    private valuesRaw;
+    private valuesCache;
+    get heading(): string;
+    set heading(value: string);
+    /** Verb on the per-section control. The step label is appended for its accessible name. */
+    get editLabel(): string;
+    set editLabel(value: string);
+    /** Placeholder for a field with nothing collected. */
+    get emptyText(): string;
+    set emptyText(value: string);
+    /**
+     * Fields to summarise. Note that `format` cannot survive the attribute
+     * round-trip — set the property directly when a field needs one.
+     */
+    get fields(): WizardSummaryField[];
+    /**
+     * Setting any of `fields`, `steps`, or `values` as a **property** stores the
+     * value as-is and re-renders. It is not mirrored to the attribute, because
+     * these carry things a JSON round-trip destroys — a field's `format`
+     * function, a `Date` in the collected values. The attributes remain the
+     * declarative path for plain records; whichever is set last wins.
+     */
+    set fields(value: WizardSummaryField[]);
+    get steps(): WizardStepConfig[];
+    set steps(value: WizardStepConfig[]);
+    get values(): Record<string, unknown>;
+    set values(value: Record<string, unknown>);
+    /** The sections as rendered — same order, so a host can mirror the card. */
+    get sections(): ReturnType<typeof summarizeWizardValues>;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/patterns/form-wizard/wizard-summary.js

@@ -0,0 +1,324 @@
+import { isWizardSummaryFieldRecord, summarizeWizardValues, } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-wizard-summary";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const elementStyles = `
+        :host {
+          display: block;
+        }
+
+        [part="card"] {
+          border: ${boePanel.border};
+          border-radius: ${boePanel.radius};
+          background: ${boePanel.background};
+          overflow: hidden;
+        }
+
+        [part="heading"] {
+          margin: 0;
+          padding: 0.85rem 1rem;
+          font: inherit;
+          font-size: 0.95rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+          border-block-end: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+        }
+
+        [part="sections"] {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+
+        [part="section"] + [part="section"] {
+          border-block-start: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 55%, transparent);
+        }
+
+        [part="section-header"] {
+          display: flex;
+          align-items: baseline;
+          gap: 0.75rem;
+          padding: 0.7rem 1rem 0.3rem;
+        }
+
+        [part="section-label"] {
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="edit"] {
+          margin-inline-start: auto;
+          appearance: none;
+          font: inherit;
+          font-size: 0.78rem;
+          padding: 0.15rem 0.5rem;
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          border-radius: ${boeRadius.control};
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: var(--boe-token-surface-surface-brand, #0061d5);
+          cursor: pointer;
+        }
+
+        [part="edit"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="edit"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+
+        [part="rows"] {
+          margin: 0;
+          padding: 0 1rem 0.8rem;
+          display: grid;
+          grid-template-columns: minmax(8rem, 14rem) 1fr;
+          gap: 0.3rem 1rem;
+        }
+
+        [part="row-label"] {
+          margin: 0;
+          font-size: 0.85rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="row-value"] {
+          margin: 0;
+          font-size: 0.85rem;
+          color: var(--boe-token-text-text, #1f1e1b);
+          overflow-wrap: anywhere;
+        }
+
+        [part="row-value"][data-empty="true"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-style: italic;
+        }
+
+        [part="empty"] {
+          padding: 1.2rem 1rem;
+          text-align: center;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+      `;
+/**
+ * The review step of a `box-form-wizard`: everything collected so far, grouped
+ * by the step that collected it, with an Edit link per group.
+ *
+ * The card is read-only and emits `edit-requested` rather than navigating
+ * itself, so the host stays in charge of the wizard — the same intent contract
+ * the rest of the patterns use.
+ *
+ * Two details carry the weight:
+ *
+ * - Sections follow **step order**, so the summary reads back in the sequence
+ *   the user filled it in rather than in whatever order the fields were
+ *   declared.
+ * - A field naming a step that does not exist lands in a trailing section
+ *   instead of vanishing. A review card exists so someone can confirm what
+ *   they are submitting; silently dropping a row would let them confirm a
+ *   value they were never shown.
+ */
+export class WizardSummary extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["edit-label", "empty-text", "fields", "heading", "steps", "values"];
+    }
+    hostEl;
+    fieldsRaw = null;
+    fieldsCache = [];
+    stepsRaw = null;
+    stepsCache = [];
+    valuesRaw = null;
+    valuesCache = {};
+    get heading() {
+        return this.getAttribute("heading") ?? "Review your answers";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /** Verb on the per-section control. The step label is appended for its accessible name. */
+    get editLabel() {
+        return this.getAttribute("edit-label") ?? "Edit";
+    }
+    set editLabel(value) {
+        this.setAttribute("edit-label", value);
+    }
+    /** Placeholder for a field with nothing collected. */
+    get emptyText() {
+        return this.getAttribute("empty-text") ?? "Not provided";
+    }
+    set emptyText(value) {
+        this.setAttribute("empty-text", value);
+    }
+    /**
+     * Fields to summarise. Note that `format` cannot survive the attribute
+     * round-trip — set the property directly when a field needs one.
+     */
+    get fields() {
+        const raw = this.getAttribute("fields");
+        if (!raw) {
+            return [...this.fieldsCache];
+        }
+        if (raw !== this.fieldsRaw) {
+            this.fieldsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.fieldsCache =
+                    Array.isArray(parsed) && parsed.every(isWizardSummaryFieldRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.fieldsCache = [];
+            }
+        }
+        return [...this.fieldsCache];
+    }
+    /**
+     * Setting any of `fields`, `steps`, or `values` as a **property** stores the
+     * value as-is and re-renders. It is not mirrored to the attribute, because
+     * these carry things a JSON round-trip destroys — a field's `format`
+     * function, a `Date` in the collected values. The attributes remain the
+     * declarative path for plain records; whichever is set last wins.
+     */
+    set fields(value) {
+        this.fieldsCache = [...value];
+        this.fieldsRaw = null;
+        this.removeAttribute("fields");
+        this.update();
+    }
+    get steps() {
+        const raw = this.getAttribute("steps");
+        if (!raw) {
+            return [...this.stepsCache];
+        }
+        if (raw !== this.stepsRaw) {
+            this.stepsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.stepsCache = Array.isArray(parsed)
+                    ? parsed.filter(step => typeof step === "object" &&
+                        step !== null &&
+                        typeof step.id === "string" &&
+                        typeof step.label === "string")
+                    : [];
+            }
+            catch {
+                this.stepsCache = [];
+            }
+        }
+        return [...this.stepsCache];
+    }
+    set steps(value) {
+        this.stepsCache = [...value];
+        this.stepsRaw = null;
+        this.removeAttribute("steps");
+        this.update();
+    }
+    get values() {
+        const raw = this.getAttribute("values");
+        if (!raw) {
+            return { ...this.valuesCache };
+        }
+        if (raw !== this.valuesRaw) {
+            this.valuesRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.valuesCache =
+                    typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+                        ? parsed
+                        : {};
+            }
+            catch {
+                this.valuesCache = {};
+            }
+        }
+        return { ...this.valuesCache };
+    }
+    set values(value) {
+        this.valuesCache = { ...value };
+        this.valuesRaw = null;
+        this.removeAttribute("values");
+        this.update();
+    }
+    /** The sections as rendered — same order, so a host can mirror the card. */
+    get sections() {
+        return summarizeWizardValues(this.fields, this.values, this.steps);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><div part="host"></div>`;
+        this.hostEl = this.shadowRoot.querySelector('[part="host"]');
+    }
+    setupListeners() {
+        this.hostEl.addEventListener("click", event => {
+            const trigger = event.target.closest('[part="edit"]');
+            if (!trigger) {
+                return;
+            }
+            const stepId = trigger.getAttribute("data-step-id");
+            if (stepId === null) {
+                return;
+            }
+            this.dispatchEvent(new CustomEvent("edit-requested", {
+                detail: { stepId },
+                bubbles: true,
+                composed: true,
+            }));
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        const sections = this.sections;
+        const body = sections.length
+            ? `<ul part="sections" role="list">${sections
+                .map(section => {
+                const rows = section.rows
+                    .map(row => {
+                    const shown = row.empty ? this.emptyText : row.value;
+                    return `
+                  <dt part="row-label">${escapeHtml(row.label)}</dt>
+                  <dd part="row-value" data-empty="${String(row.empty)}" data-key="${escapeHtml(row.key)}">${escapeHtml(shown)}</dd>
+                `;
+                })
+                    .join("");
+                // The accessible name carries the step, because a screen-reader
+                // user hearing five buttons all called "Edit" learns nothing about
+                // which one goes where.
+                const edit = section.unknownStep
+                    ? ""
+                    : `<button type="button" part="edit" data-step-id="${escapeHtml(section.stepId)}" aria-label="${escapeHtml(`${this.editLabel} ${section.label}`)}">${escapeHtml(this.editLabel)}</button>`;
+                return `
+              <li part="section" data-step-id="${escapeHtml(section.stepId)}" data-unknown-step="${String(section.unknownStep)}">
+                <div part="section-header">
+                  <span part="section-label">${escapeHtml(section.label)}</span>
+                  ${edit}
+                </div>
+                <dl part="rows">${rows}</dl>
+              </li>
+            `;
+            })
+                .join("")}</ul>`
+            : `<div part="empty">Nothing to review yet.</div>`;
+        this.hostEl.innerHTML = `
+      <section part="card" aria-label="${escapeHtml(this.heading)}">
+        <h3 part="heading">${escapeHtml(this.heading)}</h3>
+        ${body}
+      </section>
+    `;
+    }
+}
+WizardSummary.register();

package/dist/patterns/internal/safe-href.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One definition of "may this author-supplied href become a real link?",
+ * shared by every surface that renders evidence or citation chips
+ * (`box-timeline`, `box-agent-chat`, `box-audit-log`). Internal: it is not
+ * re-exported from any pattern barrel.
+ *
+ * Three copies of this check previously drifted apart, which is exactly how
+ * the protocol-relative hole below survived in all of them.
+ *
+ * Allowed: absolute `http(s)`, a same-document fragment, and a rooted path.
+ * The path branch requires a *single* leading slash — `//evil.example/x` is
+ * protocol-relative and a browser resolves it to an external origin, and
+ * `/\evil.example` is normalized to that same form by some parsers. Anything
+ * else (including `javascript:`, `data:`, and leading-whitespace tricks)
+ * fails the test, and the caller renders a button instead of an anchor.
+ */
+export declare const isSafeHref: (value: string) => boolean;

package/dist/patterns/internal/safe-href.js

@@ -0,0 +1,17 @@
+/**
+ * One definition of "may this author-supplied href become a real link?",
+ * shared by every surface that renders evidence or citation chips
+ * (`box-timeline`, `box-agent-chat`, `box-audit-log`). Internal: it is not
+ * re-exported from any pattern barrel.
+ *
+ * Three copies of this check previously drifted apart, which is exactly how
+ * the protocol-relative hole below survived in all of them.
+ *
+ * Allowed: absolute `http(s)`, a same-document fragment, and a rooted path.
+ * The path branch requires a *single* leading slash — `//evil.example/x` is
+ * protocol-relative and a browser resolves it to an external origin, and
+ * `/\evil.example` is normalized to that same form by some parsers. Anything
+ * else (including `javascript:`, `data:`, and leading-whitespace tricks)
+ * fails the test, and the caller renders a button instead of an anchor.
+ */
+export const isSafeHref = (value) => /^https?:\/\//i.test(value) || /^\/(?![/\\])/.test(value) || value.startsWith("#");

package/dist/patterns/lineage/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./lineage-graph.js";
+export * from "./provenance-strip.js";

package/dist/patterns/lineage/index.js

@@ -0,0 +1,6 @@
+// Lineage model + validation
+export * from "./types.js";
+// Provenance DAG with deviation-toned edges
+export * from "./lineage-graph.js";
+// Linear ancestry strip for record headers
+export * from "./provenance-strip.js";

package/dist/patterns/lineage/lineage-graph.d.ts

@@ -0,0 +1,30 @@
+import type { LineageNode } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * Provenance DAG for clause lineage (opportunity 2): source clause →
+ * template versions → executed contracts, laid out by the versions
+ * pattern's `computeVersionGraphLayout` and rendered with tone-coloured
+ * deviation edges. Every node is an HTML button (`node-selected`), and every
+ * derivation edge is ALSO a per-row chip button (`edge-selected` with the
+ * parent/child pair — the diff viewer's input), so edge activation is
+ * keyboard-accessible without SVG hit targets: the row rail is the
+ * accessible contract, the SVG is presentation.
+ */
+export declare class LineageGraph extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private nodesValue;
+    private rovingId;
+    private hostEl;
+    get heading(): string;
+    set heading(value: string);
+    get nodes(): LineageNode[];
+    set nodes(value: LineageNode[]);
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private parseNodesAttribute;
+    private getNode;
+    private nodeButtons;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}