@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/patterns/diff/engine.js

@@ -0,0 +1,276 @@
+/**
+ * LCS matching cap. Above this many DP cells the middle of the comparison is
+ * treated as a whole replacement instead — O(n·m) memory on arbitrary input
+ * is not acceptable for an element attribute, and a clause-sized document
+ * never gets near the cap.
+ */
+const MAX_LCS_CELLS = 400_000;
+/** Generic LCS-based edit script over two arrays. */
+const editScript = (a, b) => {
+    // Trim the common prefix/suffix first — it keeps the DP small for the
+    // typical "one clause edited in a long document" case.
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start]) {
+        start += 1;
+    }
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+    }
+    const middleA = a.slice(start, endA);
+    const middleB = b.slice(start, endB);
+    const ops = [];
+    if (start > 0) {
+        ops.push({ kind: "equal", items: a.slice(0, start) });
+    }
+    if (middleA.length === 0 && middleB.length === 0) {
+        // Nothing between prefix and suffix.
+    }
+    else if (middleA.length === 0) {
+        ops.push({ kind: "added", items: middleB });
+    }
+    else if (middleB.length === 0) {
+        ops.push({ kind: "removed", items: middleA });
+    }
+    else if (middleA.length * middleB.length > MAX_LCS_CELLS) {
+        ops.push({ kind: "removed", items: middleA });
+        ops.push({ kind: "added", items: middleB });
+    }
+    else {
+        const m = middleA.length;
+        const n = middleB.length;
+        const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+        for (let i = m - 1; i >= 0; i -= 1) {
+            for (let j = n - 1; j >= 0; j -= 1) {
+                dp[i][j] =
+                    middleA[i] === middleB[j]
+                        ? dp[i + 1][j + 1] + 1
+                        : Math.max(dp[i + 1][j], dp[i][j + 1]);
+            }
+        }
+        let i = 0;
+        let j = 0;
+        const push = (kind, item) => {
+            const last = ops[ops.length - 1];
+            if (last && last.kind === kind) {
+                last.items.push(item);
+            }
+            else {
+                ops.push({ kind, items: [item] });
+            }
+        };
+        while (i < m && j < n) {
+            if (middleA[i] === middleB[j]) {
+                push("equal", middleA[i]);
+                i += 1;
+                j += 1;
+            }
+            else if (dp[i + 1][j] >= dp[i][j + 1]) {
+                push("removed", middleA[i]);
+                i += 1;
+            }
+            else {
+                push("added", middleB[j]);
+                j += 1;
+            }
+        }
+        while (i < m) {
+            push("removed", middleA[i]);
+            i += 1;
+        }
+        while (j < n) {
+            push("added", middleB[j]);
+            j += 1;
+        }
+    }
+    if (endA < a.length) {
+        ops.push({ kind: "equal", items: a.slice(endA) });
+    }
+    return ops;
+};
+/** Split into word/whitespace tokens so joins reproduce the exact line. */
+const tokenize = (line) => line.split(/(\s+)/).filter(token => token.length > 0);
+const mergeSegments = (segments) => {
+    // Whitespace-only equal runs between two same-kind change runs read as
+    // noise ("a b c" → three separate marks); absorb them into the change.
+    const absorbed = [];
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const previous = segments[index - 1];
+        const next = segments[index + 1];
+        if (segment.kind === "equal" &&
+            segment.text.trim() === "" &&
+            previous &&
+            next &&
+            previous.kind !== "equal" &&
+            previous.kind === next.kind) {
+            absorbed.push({ kind: previous.kind, text: segment.text });
+        }
+        else {
+            absorbed.push(segment);
+        }
+    }
+    const merged = [];
+    for (const segment of absorbed) {
+        const last = merged[merged.length - 1];
+        if (last && last.kind === segment.kind) {
+            last.text += segment.text;
+        }
+        else {
+            merged.push({ ...segment });
+        }
+    }
+    return merged;
+};
+/**
+ * Word-level runs for one changed line pair: the before side carries
+ * equal/removed segments, the after side equal/added.
+ */
+export const computeInlineSegments = (before, after) => {
+    const ops = editScript(tokenize(before), tokenize(after));
+    const beforeSegments = [];
+    const afterSegments = [];
+    for (const op of ops) {
+        const text = op.items.join("");
+        if (op.kind === "equal") {
+            beforeSegments.push({ kind: "equal", text });
+            afterSegments.push({ kind: "equal", text });
+        }
+        else if (op.kind === "removed") {
+            beforeSegments.push({ kind: "removed", text });
+        }
+        else {
+            afterSegments.push({ kind: "added", text });
+        }
+    }
+    return { before: mergeSegments(beforeSegments), after: mergeSegments(afterSegments) };
+};
+/** True when a removed/added line pair is similar enough to render as one changed row. */
+const isChangedPair = (before, after) => {
+    if (before === after) {
+        return true;
+    }
+    const segments = computeInlineSegments(before, after);
+    const equalLength = segments.after
+        .filter(segment => segment.kind === "equal")
+        .reduce((total, segment) => total + segment.text.length, 0);
+    const maxLength = Math.max(before.length, after.length);
+    return maxLength > 0 && equalLength / maxLength >= 0.3;
+};
+/**
+ * Line-level diff of two documents. Adjacent removed/added runs are paired
+ * into `changed` rows (with word-level segments) when the lines are similar
+ * enough; otherwise they stay as distinct removals and additions.
+ */
+export const computeTextDiff = (before, after) => {
+    // Normalize EOL styles first — two documents differing only in CRLF vs LF
+    // must not read as a full-document replacement.
+    const toLines = (text) => text.length ? text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n") : [];
+    const beforeLines = toLines(before);
+    const afterLines = toLines(after);
+    const ops = editScript(beforeLines, afterLines);
+    const rows = [];
+    const stats = { added: 0, removed: 0, changed: 0 };
+    let beforeNumber = 1;
+    let afterNumber = 1;
+    let index = 0;
+    while (index < ops.length) {
+        const op = ops[index];
+        if (op.kind === "equal") {
+            for (const text of op.items) {
+                rows.push({
+                    kind: "equal",
+                    before: { number: beforeNumber, text },
+                    after: { number: afterNumber, text },
+                });
+                beforeNumber += 1;
+                afterNumber += 1;
+            }
+            index += 1;
+            continue;
+        }
+        // A removed run directly followed by an added run pairs line-by-line.
+        const next = ops[index + 1];
+        if (op.kind === "removed" && next?.kind === "added") {
+            const removed = op.items;
+            const added = next.items;
+            const paired = Math.min(removed.length, added.length);
+            for (let pair = 0; pair < paired; pair += 1) {
+                const beforeText = removed[pair];
+                const afterText = added[pair];
+                if (isChangedPair(beforeText, afterText)) {
+                    const segments = computeInlineSegments(beforeText, afterText);
+                    rows.push({
+                        kind: "changed",
+                        before: { number: beforeNumber, text: beforeText, segments: segments.before },
+                        after: { number: afterNumber, text: afterText, segments: segments.after },
+                    });
+                    stats.changed += 1;
+                }
+                else {
+                    rows.push({ kind: "removed", before: { number: beforeNumber, text: beforeText } });
+                    rows.push({ kind: "added", after: { number: afterNumber, text: afterText } });
+                    stats.removed += 1;
+                    stats.added += 1;
+                }
+                beforeNumber += 1;
+                afterNumber += 1;
+            }
+            for (let rest = paired; rest < removed.length; rest += 1) {
+                rows.push({ kind: "removed", before: { number: beforeNumber, text: removed[rest] } });
+                stats.removed += 1;
+                beforeNumber += 1;
+            }
+            for (let rest = paired; rest < added.length; rest += 1) {
+                rows.push({ kind: "added", after: { number: afterNumber, text: added[rest] } });
+                stats.added += 1;
+                afterNumber += 1;
+            }
+            index += 2;
+            continue;
+        }
+        if (op.kind === "removed") {
+            for (const text of op.items) {
+                rows.push({ kind: "removed", before: { number: beforeNumber, text } });
+                stats.removed += 1;
+                beforeNumber += 1;
+            }
+        }
+        else {
+            for (const text of op.items) {
+                rows.push({ kind: "added", after: { number: afterNumber, text } });
+                stats.added += 1;
+                afterNumber += 1;
+            }
+        }
+        index += 1;
+    }
+    const changeRanges = [];
+    for (let row = 0; row < rows.length; row += 1) {
+        if (rows[row].kind === "equal") {
+            continue;
+        }
+        const start = row;
+        while (row + 1 < rows.length && rows[row + 1].kind !== "equal") {
+            row += 1;
+        }
+        changeRanges.push({ start, end: row });
+    }
+    return { rows, stats, changeRanges };
+};
+/** Compact "+A −R ~C" summary for headers and chips. */
+export const formatDiffStats = (stats) => {
+    const parts = [];
+    if (stats.added) {
+        parts.push(`+${String(stats.added)}`);
+    }
+    if (stats.removed) {
+        parts.push(`−${String(stats.removed)}`);
+    }
+    if (stats.changed) {
+        parts.push(`~${String(stats.changed)}`);
+    }
+    return parts.length ? parts.join(" ") : "No changes";
+};

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

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./engine.js";
+export * from "./diff-viewer.js";
+export * from "./compare-view.js";

package/dist/patterns/diff/index.js

@@ -0,0 +1,8 @@
+// Diff model types
+export * from "./types.js";
+// Pure diff engine
+export * from "./engine.js";
+// Composed comparison surface
+export * from "./diff-viewer.js";
+// Scroll-locked side-by-side shell for doc-vs-doc review
+export * from "./compare-view.js";

package/dist/patterns/diff/types.d.ts

@@ -0,0 +1,69 @@
+/** A run of text inside one line: unchanged, or part of the delta. */
+export type DiffSegmentKind = "equal" | "added" | "removed";
+export interface DiffSegment {
+    kind: DiffSegmentKind;
+    text: string;
+}
+/** How an aligned row of the comparison classifies. */
+export type DiffRowKind = "equal" | "added" | "removed" | "changed";
+export interface DiffLine {
+    /** 1-based line number in its own document. */
+    number: number;
+    text: string;
+    /** Word-level runs; present on the paired lines of a `changed` row. */
+    segments?: DiffSegment[];
+}
+/**
+ * One aligned row: `equal` and `changed` rows carry both sides, `removed`
+ * only the before side, `added` only the after side. Side-by-side renders
+ * the two sides in one grid row; inline mode renders removed then added.
+ */
+export interface DiffRow {
+    kind: DiffRowKind;
+    before?: DiffLine;
+    after?: DiffLine;
+}
+export interface DiffStats {
+    added: number;
+    removed: number;
+    changed: number;
+}
+export interface DiffResult {
+    rows: DiffRow[];
+    stats: DiffStats;
+    /**
+     * Row-index ranges of consecutive non-equal rows — the navigable "changes"
+     * (hunks) the viewer steps through.
+     */
+    changeRanges: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * How a comparison shell maps one pane's scroll position onto the other.
+ *
+ * `proportional` matches by fraction of the scrollable range — the only sane
+ * default when the two documents are different lengths, since the shorter one
+ * would otherwise run out long before the longer one finished.
+ * `absolute` keeps the same pixel offset, which is what you want for two
+ * renderings of the *same* document, where line N sits at the same height in
+ * both and proportional mapping would slowly drift them apart.
+ */
+export type CompareSyncMode = "proportional" | "absolute";
+/** The three numbers a scroll calculation needs, so the maths stays DOM-free. */
+export interface ScrollMetrics {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/** How far a pane can actually scroll. Zero when the content fits. */
+export declare const scrollableRange: (metrics: ScrollMetrics) => number;
+/**
+ * Where `target` should scroll to so it matches `source`.
+ *
+ * Both degenerate cases return 0 rather than `NaN`: a target that cannot
+ * scroll has nowhere to go, and a source that cannot scroll carries no
+ * position to map (its fraction would be 0/0).
+ */
+export declare const mapScrollPosition: (source: ScrollMetrics, target: ScrollMetrics, mode?: CompareSyncMode) => number;

package/dist/patterns/diff/types.js

@@ -0,0 +1,24 @@
+/** How far a pane can actually scroll. Zero when the content fits. */
+export const scrollableRange = (metrics) => Math.max(0, metrics.scrollHeight - metrics.clientHeight);
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * Where `target` should scroll to so it matches `source`.
+ *
+ * Both degenerate cases return 0 rather than `NaN`: a target that cannot
+ * scroll has nowhere to go, and a source that cannot scroll carries no
+ * position to map (its fraction would be 0/0).
+ */
+export const mapScrollPosition = (source, target, mode = "proportional") => {
+    const targetRange = scrollableRange(target);
+    if (targetRange === 0) {
+        return 0;
+    }
+    if (mode === "absolute") {
+        return clamp(source.scrollTop, 0, targetRange);
+    }
+    const sourceRange = scrollableRange(source);
+    if (sourceRange === 0) {
+        return 0;
+    }
+    return clamp((source.scrollTop / sourceRange) * targetRange, 0, targetRange);
+};

package/dist/patterns/file-request/file-request-builder.d.ts

@@ -11,7 +11,8 @@ type FileRequestBuilderSetting = {
     description?: string;
 };
 type FileRequestBuilderValues = Record<string, boolean | string>;
-export declare class BoxFileRequestBuilderElement extends BaseElement {
+export declare class FileRequestBuilder extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     get fields(): FileRequestBuilderField[];
@@ -32,5 +33,4 @@ export declare class BoxFileRequestBuilderElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxFileRequestBuilderElement: (tagName?: string) => typeof BoxFileRequestBuilderElement;
 export {};

package/dist/patterns/file-request/file-request-builder.js

@@ -145,7 +145,8 @@ const elementStyles = `
           color: var(--boe-token-text-text-on-brand, #ffffff);
         }
       `;
-export class BoxFileRequestBuilderElement extends BaseElement {
+export class FileRequestBuilder extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["fields", "heading", "message", "settings", "value"];
     }
@@ -334,11 +335,4 @@ export class BoxFileRequestBuilderElement extends BaseElement {
         });
     }
 }
-export const defineBoxFileRequestBuilderElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxFileRequestBuilderElement);
-    return BoxFileRequestBuilderElement;
-};
+FileRequestBuilder.register();

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

@@ -0,0 +1,39 @@
+import { Controller } from "../../core/controller.js";
+import type { WizardEvents, WizardSessionConfig, WizardState, WizardStepValidation } from "./types.js";
+/**
+ * Headless multi-step form session: owns the step sequence, a value store,
+ * and per-step validation gating. Forward navigation and submission run the
+ * step's validator; backward navigation and jumps to already-visited steps
+ * never re-validate — a reviewer can always go back. The host owns the
+ * fields and persistence; the controller owns the choreography.
+ */
+export declare class FormWizardController extends Controller<WizardState, WizardEvents> {
+    readonly config: WizardSessionConfig;
+    constructor(config: WizardSessionConfig);
+    get isFirstStep(): boolean;
+    get isLastStep(): boolean;
+    setValue(field: string, value: unknown): void;
+    setValues(patch: Record<string, unknown>): void;
+    /** Validate a step (default: the current one) without navigating. */
+    validateStep(stepId?: string): WizardStepValidation;
+    /** Advance if the current step passes (or is optional and untouched by a validator). */
+    next(): boolean;
+    /** Backward navigation never validates. */
+    previous(): boolean;
+    /**
+     * Jump to a step. Earlier and already-visited steps are always reachable;
+     * jumping forward gates every intermediate step in order, stopping (and
+     * reporting) on the first failure.
+     */
+    goTo(stepId: string): boolean;
+    /** Emit the values for the host to persist. Never validates — drafts may be incomplete. */
+    saveDraft(): void;
+    /**
+     * Validate every non-optional step (in order); emit `submitted` when all
+     * pass, otherwise navigate to the first failing step and report it.
+     */
+    submit(): boolean;
+    reset(): void;
+    private gateCurrentStep;
+    private moveTo;
+}

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

@@ -0,0 +1,157 @@
+import { Controller } from "../../core/controller.js";
+const createInitialState = (config) => ({
+    steps: config.steps,
+    currentStepId: config.steps[0]?.id ?? "",
+    currentStepIndex: 0,
+    values: { ...(config.initialValues ?? {}) },
+    visitedStepIds: config.steps[0] ? [config.steps[0].id] : [],
+    stepError: null,
+    submitted: false,
+});
+/**
+ * Headless multi-step form session: owns the step sequence, a value store,
+ * and per-step validation gating. Forward navigation and submission run the
+ * step's validator; backward navigation and jumps to already-visited steps
+ * never re-validate — a reviewer can always go back. The host owns the
+ * fields and persistence; the controller owns the choreography.
+ */
+export class FormWizardController extends Controller {
+    config;
+    constructor(config) {
+        if (!config.steps.length) {
+            throw new Error("FormWizardController requires at least one step");
+        }
+        super(createInitialState(config));
+        this.config = config;
+    }
+    get isFirstStep() {
+        return this.state.currentStepIndex === 0;
+    }
+    get isLastStep() {
+        return this.state.currentStepIndex === this.state.steps.length - 1;
+    }
+    setValue(field, value) {
+        this.setValues({ [field]: value });
+    }
+    setValues(patch) {
+        const values = { ...this.state.values, ...patch };
+        this.setState({
+            ...this.state,
+            values,
+            // Editing clears the stale failure — it re-runs on the next gate.
+            stepError: null,
+        });
+        this.emit("valuesChanged", { values });
+    }
+    /** Validate a step (default: the current one) without navigating. */
+    validateStep(stepId = this.state.currentStepId) {
+        const validator = this.config.validators?.[stepId];
+        return validator ? validator(this.state.values) : { valid: true };
+    }
+    /** Advance if the current step passes (or is optional and untouched by a validator). */
+    next() {
+        if (this.isLastStep) {
+            return false;
+        }
+        if (!this.gateCurrentStep()) {
+            return false;
+        }
+        this.moveTo(this.state.currentStepIndex + 1);
+        return true;
+    }
+    /** Backward navigation never validates. */
+    previous() {
+        if (this.isFirstStep) {
+            return false;
+        }
+        this.moveTo(this.state.currentStepIndex - 1);
+        return true;
+    }
+    /**
+     * Jump to a step. Earlier and already-visited steps are always reachable;
+     * jumping forward gates every intermediate step in order, stopping (and
+     * reporting) on the first failure.
+     */
+    goTo(stepId) {
+        const targetIndex = this.state.steps.findIndex(step => step.id === stepId);
+        if (targetIndex < 0 || targetIndex === this.state.currentStepIndex) {
+            return false;
+        }
+        if (targetIndex < this.state.currentStepIndex || this.state.visitedStepIds.includes(stepId)) {
+            this.moveTo(targetIndex);
+            return true;
+        }
+        for (let index = this.state.currentStepIndex; index < targetIndex; index += 1) {
+            if (!this.gateCurrentStep()) {
+                return false;
+            }
+            this.moveTo(index + 1);
+        }
+        return true;
+    }
+    /** Emit the values for the host to persist. Never validates — drafts may be incomplete. */
+    saveDraft() {
+        this.emit("draftSaved", { values: this.state.values });
+    }
+    /**
+     * Validate every non-optional step (in order); emit `submitted` when all
+     * pass, otherwise navigate to the first failing step and report it.
+     */
+    submit() {
+        for (const [index, step] of this.state.steps.entries()) {
+            if (step.optional) {
+                continue;
+            }
+            const validation = this.validateStep(step.id);
+            if (!validation.valid) {
+                this.moveTo(index);
+                this.setState({ ...this.state, stepError: validation });
+                this.emit("stepInvalid", { stepId: step.id, validation });
+                return false;
+            }
+        }
+        this.setState({ ...this.state, stepError: null, submitted: true });
+        this.emit("submitted", { values: this.state.values });
+        return true;
+    }
+    reset() {
+        this.setState(createInitialState(this.config));
+        this.emit("stepChanged", {
+            stepId: this.state.currentStepId,
+            stepIndex: this.state.currentStepIndex,
+        });
+        this.emit("valuesChanged", { values: this.state.values });
+    }
+    gateCurrentStep() {
+        const step = this.state.steps[this.state.currentStepIndex];
+        if (!step || step.optional) {
+            return true;
+        }
+        const validation = this.validateStep(step.id);
+        if (validation.valid) {
+            if (this.state.stepError) {
+                this.setState({ ...this.state, stepError: null });
+            }
+            return true;
+        }
+        this.setState({ ...this.state, stepError: validation });
+        this.emit("stepInvalid", { stepId: step.id, validation });
+        return false;
+    }
+    moveTo(index) {
+        const step = this.state.steps[index];
+        if (!step) {
+            return;
+        }
+        this.setState({
+            ...this.state,
+            currentStepId: step.id,
+            currentStepIndex: index,
+            stepError: null,
+            visitedStepIds: this.state.visitedStepIds.includes(step.id)
+                ? this.state.visitedStepIds
+                : [...this.state.visitedStepIds, step.id],
+        });
+        this.emit("stepChanged", { stepId: step.id, stepIndex: index });
+    }
+}

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

@@ -0,0 +1,63 @@
+import { FormWizardController } from "./controller.js";
+import type { WizardStepConfig, WizardStepValidator } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+export declare class FormWizard extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private controller;
+    private pendingStart;
+    private unsubscribeFns;
+    private validatorsValue;
+    private initialValuesValue;
+    private titleEl;
+    private railEl;
+    private panelsEl;
+    private errorEl;
+    private backEl;
+    private draftEl;
+    private nextEl;
+    private submitEl;
+    private panelsSignature;
+    private suppressRailEvent;
+    get heading(): string;
+    set heading(value: string);
+    /**
+     * Step configuration; JSON `[{"id","label","description?","optional?"}]`.
+     * A step's id doubles as the slot name feeding its panel.
+     */
+    get steps(): WizardStepConfig[];
+    set steps(value: WizardStepConfig[]);
+    get submitLabel(): string;
+    set submitLabel(value: string);
+    /** When set, a Save draft button renders and emits `draft-saved`. */
+    get draftLabel(): string | null;
+    set draftLabel(value: string | null);
+    get validators(): Record<string, WizardStepValidator>;
+    set validators(value: Record<string, WizardStepValidator>);
+    get initialValues(): Record<string, unknown>;
+    set initialValues(value: Record<string, unknown>);
+    get values(): Record<string, unknown>;
+    get activeStep(): string;
+    /** The live session controller. Null until steps are configured. */
+    get wizardController(): FormWizardController | null;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    setValue(field: string, value: unknown): void;
+    setValues(patch: Record<string, unknown>): void;
+    next(): boolean;
+    previous(): boolean;
+    goTo(stepId: string): boolean;
+    saveDraft(): void;
+    submit(): boolean;
+    reset(): void;
+    private scheduleStart;
+    private startController;
+    private subscribeToController;
+    private teardownController;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    /** One panel per step, fed by a slot named after the step id. */
+    private rebuildPanels;
+    protected update(): void;
+}