@unofficialbox/box-open-elements 0.5.0 → 0.7.0

package/dist/components/feedback/progress-steps.js

@@ -8,6 +8,50 @@ const escapeHtml = (value) => value
     .replaceAll(">", ">")
     .replaceAll('"', """)
     .replaceAll("'", "'");
+const STEP_STATUSES = new Set(["complete", "blocked", "failed", "disabled"]);
+/** Attribute payloads are author input — validate every record. */
+export const isProgressStepRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const step = value;
+    return (typeof step.value === "string" &&
+        step.value.length > 0 &&
+        typeof step.label === "string" &&
+        step.label.length > 0 &&
+        (step.status === undefined || STEP_STATUSES.has(step.status)) &&
+        // Non-string text fields would reach escapeHtml and throw mid-render.
+        (step.description === undefined || typeof step.description === "string") &&
+        (step.statusNote === undefined || typeof step.statusNote === "string"));
+};
+/**
+ * The state rules, pure and DOM-free, so a host can drive its own surface
+ * (or decide whether "Continue" is enabled) from the same function the
+ * component renders from. An unknown `value` falls back to the first step,
+ * matching the component's long-standing behaviour.
+ */
+export const resolveStepStates = (items, value) => {
+    const currentIndex = Math.max(0, items.findIndex(item => item.value === value));
+    return items.map((item, index) => {
+        const positional = index < currentIndex ? "complete" : index === currentIndex ? "current" : "upcoming";
+        const state = item.status ?? positional;
+        return {
+            item,
+            state,
+            isCurrent: index === currentIndex,
+            interactive: state !== "blocked" && state !== "disabled",
+        };
+    });
+};
+/** Every state in words — colour never carries the meaning alone. */
+export const STEP_STATE_LABEL = {
+    complete: "Complete",
+    current: "Current step",
+    upcoming: "Not started",
+    blocked: "Blocked",
+    failed: "Failed",
+    disabled: "Unavailable",
+};
 const progressStepsStyles = `
   :host {
     display: block;
@@ -100,6 +144,66 @@ const progressStepsStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
     line-height: 1.45;
   }
+
+  [part="step"]:disabled {
+    cursor: not-allowed;
+    background: var(--boe-token-surface-surface, #ffffff);
+  }
+
+  [part="step"][data-state="blocked"] [part="step-label"],
+  [part="step"][data-state="disabled"] [part="step-label"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="step"][data-state="blocked"] [part="marker"] {
+    background: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 18%, var(--boe-token-surface-surface, #ffffff) 82%);
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 52%, var(--boe-token-text-text, #222222));
+  }
+
+  [part="step"][data-state="failed"] {
+    border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 34%, transparent);
+  }
+
+  [part="step"][data-state="failed"] [part="marker"] {
+    border-color: transparent;
+    background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 16%, var(--boe-token-surface-surface, #ffffff) 84%);
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 72%, black 28%);
+  }
+
+  [part="step"][data-state="disabled"] {
+    opacity: 0.62;
+  }
+
+  /* The status, in words: visible for the conditions a user must not miss. */
+  [part="step-status"] {
+    font-size: 0.8rem;
+    font-weight: 700;
+  }
+
+  [part="step"][data-state="blocked"] [part="step-status"] {
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 48%, var(--boe-token-text-text, #222222));
+  }
+
+  [part="step"][data-state="failed"] [part="step-status"] {
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+  }
+
+  [part="step-status-note"] {
+    font-size: 0.82rem;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  .boe-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    clip: rect(0, 0, 0, 0);
+    overflow: hidden;
+    white-space: nowrap;
+  }
 `;
 export class ProgressSteps extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
@@ -108,6 +212,7 @@ export class ProgressSteps extends BaseElement {
     }
     valueInternal = "";
     stepsEl;
+    liveEl;
     itemsSignature = "";
     get label() {
         return this.getAttribute("label") ?? "Progress Steps";
@@ -122,7 +227,9 @@ export class ProgressSteps extends BaseElement {
         }
         try {
             const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
+            return Array.isArray(parsed) && parsed.every(isProgressStepRecord)
+                ? parsed
+                : [];
         }
         catch {
             return [];
@@ -131,6 +238,10 @@ export class ProgressSteps extends BaseElement {
     set items(value) {
         this.setAttribute("items", JSON.stringify(value));
     }
+    /** The resolved states — same objects the render uses. */
+    get resolvedSteps() {
+        return resolveStepStates(this.items, this.valueInternal);
+    }
     get value() {
         return this.valueInternal;
     }
@@ -154,8 +265,10 @@ export class ProgressSteps extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${progressStepsStyles}</style>
       <div part="steps" role="group"></div>
+      <div part="live" class="boe-sr-only" aria-live="polite"></div>
     `;
         this.stepsEl = this.shadowRoot.querySelector('[part="steps"]');
+        this.liveEl = this.shadowRoot.querySelector('[part="live"]');
     }
     setupListeners() {
         this.stepsEl.addEventListener("click", event => {
@@ -175,34 +288,51 @@ export class ProgressSteps extends BaseElement {
             if (!step || !this.stepsEl.contains(step)) {
                 return;
             }
-            const items = this.items;
+            const resolved = this.resolvedSteps;
             const index = Array.from(this.stepsEl.querySelectorAll('[part="step"]')).indexOf(step);
-            if (index < 0) {
+            if (index < 0 || resolved.length === 0) {
                 return;
             }
-            const lastIndex = items.length - 1;
-            let nextIndex = index;
+            // Arrows walk to the next *interactive* step — blocked and disabled
+            // steps are skipped, not landed on and bounced off.
+            const isInteractive = (candidate) => resolved[candidate]?.interactive ?? false;
+            const walk = (direction) => {
+                for (let offset = 1; offset <= resolved.length; offset += 1) {
+                    const candidate = (((index + direction * offset) % resolved.length) + resolved.length) % resolved.length;
+                    if (isInteractive(candidate)) {
+                        return candidate;
+                    }
+                }
+                return -1;
+            };
+            let nextIndex;
             if (keyboardEvent.key === "ArrowRight" || keyboardEvent.key === "ArrowDown") {
-                nextIndex = index >= lastIndex ? 0 : index + 1;
+                nextIndex = walk(1);
             }
             else if (keyboardEvent.key === "ArrowLeft" || keyboardEvent.key === "ArrowUp") {
-                nextIndex = index <= 0 ? lastIndex : index - 1;
+                nextIndex = walk(-1);
             }
             else if (keyboardEvent.key === "Home") {
-                nextIndex = 0;
+                nextIndex = resolved.findIndex(entry => entry.interactive);
             }
             else if (keyboardEvent.key === "End") {
-                nextIndex = lastIndex;
+                nextIndex = -1;
+                for (let candidate = resolved.length - 1; candidate >= 0; candidate -= 1) {
+                    if (isInteractive(candidate)) {
+                        nextIndex = candidate;
+                        break;
+                    }
+                }
             }
             else {
                 return;
             }
             keyboardEvent.preventDefault();
-            const nextStep = items[nextIndex];
-            if (!nextStep) {
+            const nextStep = resolved[nextIndex];
+            if (nextIndex < 0 || !nextStep) {
                 return;
             }
-            this.selectValue(nextStep.value);
+            this.selectValue(nextStep.item.value);
             queueMicrotask(() => {
                 const nextButton = this.stepsEl.querySelectorAll('[part="step"]')[nextIndex];
                 nextButton?.focus();
@@ -210,6 +340,13 @@ export class ProgressSteps extends BaseElement {
         });
     }
     selectValue(nextValue) {
+        // Disabled buttons never emit clicks and the keyboard path skips them,
+        // but the invariant should not depend on every caller knowing that.
+        const resolved = resolveStepStates(this.items, this.valueInternal);
+        const target = resolved.find(entry => entry.item.value === nextValue);
+        if (!target || !target.interactive) {
+            return;
+        }
         this.valueInternal = nextValue;
         this.setAttribute("value", nextValue);
         this.dispatchEvent(new CustomEvent("value-changed", {
@@ -218,6 +355,28 @@ export class ProgressSteps extends BaseElement {
             detail: { value: nextValue },
         }));
         this.update();
+        this.announceStep(target);
+    }
+    /** A polite announcement on user-driven step changes, never on render. */
+    announceStep(target) {
+        if (!this.liveEl) {
+            return;
+        }
+        const items = this.items;
+        const position = items.findIndex(item => item.value === target.item.value) + 1;
+        this.liveEl.textContent = `${target.item.label}, step ${String(position)} of ${String(items.length)}`;
+    }
+    /**
+     * The tab stop lives on the current step — unless that step is blocked or
+     * disabled (a host can point `value` anywhere), in which case the first
+     * interactive step takes it so the group stays reachable.
+     */
+    tabbableIndex(resolved) {
+        const currentIndex = resolved.findIndex(entry => entry.isCurrent);
+        if (resolved[currentIndex]?.interactive) {
+            return currentIndex;
+        }
+        return resolved.findIndex(entry => entry.interactive);
     }
     update() {
         if (!this.stepsEl) {
@@ -231,24 +390,35 @@ export class ProgressSteps extends BaseElement {
             this.setAttribute("value", selectedValue);
         }
         this.stepsEl.setAttribute("aria-label", this.label);
+        const resolved = resolveStepStates(items, this.valueInternal);
+        const tabbable = this.tabbableIndex(resolved);
         const signature = JSON.stringify(items);
         if (signature !== this.itemsSignature) {
             this.itemsSignature = signature;
-            this.stepsEl.innerHTML = items
-                .map((item, index) => {
-                const state = index < activeIndex ? "complete" : index === activeIndex ? "current" : "upcoming";
+            this.stepsEl.innerHTML = resolved
+                .map((entry, index) => {
+                const { item, state, isCurrent, interactive } = entry;
+                // Blocked / failed / disabled are said out loud on the surface; the
+                // positional states get a screen-reader word so colour and a number
+                // are never the only carriers of the state.
+                const explicitStatus = item.status
+                    ? `<span part="step-status">${STEP_STATE_LABEL[state]}</span>
+               ${item.statusNote ? `<span part="step-status-note">${escapeHtml(item.statusNote)}</span>` : ""}`
+                    : `<span part="step-state" class="boe-sr-only">${STEP_STATE_LABEL[state]}</span>`;
                 return `
             <button
               type="button"
               part="step"
               data-state="${state}"
               data-value="${escapeHtml(item.value)}"
-              aria-current="${state === "current" ? "step" : "false"}"
-              tabindex="${index === activeIndex ? "0" : "-1"}"
+              aria-current="${isCurrent ? "step" : "false"}"
+              tabindex="${index === tabbable ? "0" : "-1"}"
+              ${interactive ? "" : "disabled"}
             >
               <span part="marker">${index + 1}</span>
               <span part="content">
                 <strong part="step-label">${escapeHtml(item.label)}</strong>
+                ${explicitStatus}
                 ${item.description ? `<span part="step-description">${escapeHtml(item.description)}</span>` : ""}
               </span>
             </button>
@@ -258,12 +428,20 @@ export class ProgressSteps extends BaseElement {
             return;
         }
         this.stepsEl.querySelectorAll('[part="step"]').forEach((step, index) => {
-            const state = index < activeIndex ? "complete" : index === activeIndex ? "current" : "upcoming";
+            const entry = resolved[index];
+            if (!entry) {
+                return;
+            }
             const button = step;
-            button.dataset.state = state;
-            button.setAttribute("aria-current", state === "current" ? "step" : "false");
-            button.setAttribute("aria-selected", String(index === activeIndex));
-            button.tabIndex = index === activeIndex ? 0 : -1;
+            button.dataset.state = entry.state;
+            button.setAttribute("aria-current", entry.isCurrent ? "step" : "false");
+            button.tabIndex = index === tabbable ? 0 : -1;
+            button.disabled = !entry.interactive;
+            // Positional states move with `value`; keep the spoken word in step.
+            const stateWord = button.querySelector('[part="step-state"]');
+            if (stateWord) {
+                stateWord.textContent = STEP_STATE_LABEL[entry.state];
+            }
         });
     }
 }

package/dist/components/feedback/stage-path.d.ts

@@ -0,0 +1,44 @@
+import { BaseElement } from "../../core/index.js";
+/** One point in a record's lifecycle. */
+export interface StagePathStage {
+    id: string;
+    label: string;
+    /** Optional detail shown under the label on the current stage. */
+    description?: string;
+}
+export type StageState = "complete" | "current" | "upcoming";
+/** Attribute payloads are author input — validate every record. */
+export declare const isStagePathStageRecord: (value: unknown) => value is StagePathStage;
+/** State of each stage relative to the current one. */
+export declare const resolveStageStates: (stages: readonly StagePathStage[], currentId: string) => StageState[];
+/**
+ * Horizontal chevron lifecycle tracker for record headers — Draft → In
+ * Review → Approved → Executed.
+ *
+ * Distinct from `box-progress-steps`, which is a vertical setup rail for a
+ * task the reader is working through: this states where a *record* sits in
+ * its lifecycle, is read-only, and belongs in a header rather than a form.
+ *
+ * Rendered as an ordered list with the current stage marked `aria-current`,
+ * so the sequence and the position are both available without relying on the
+ * chevron geometry — which is decoration, and collapses on narrow viewports.
+ */
+export declare class StagePath extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private pathEl;
+    private stagesRaw;
+    private stagesCache;
+    get label(): string;
+    set label(value: string);
+    /** Id of the stage the record is at. An unknown id leaves every stage upcoming. */
+    get current(): string;
+    set current(value: string);
+    get stages(): StagePathStage[];
+    set stages(value: StagePathStage[]);
+    /** State of each stage, in order. */
+    get states(): StageState[];
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/components/feedback/stage-path.js

@@ -0,0 +1,235 @@
+import { BaseElement } from "../../core/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+const DEFAULT_TAG_NAME = "box-stage-path";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** Attribute payloads are author input — validate every record. */
+export const isStagePathStageRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const stage = value;
+    return (typeof stage.id === "string" &&
+        stage.id.length > 0 &&
+        typeof stage.label === "string" &&
+        stage.label.length > 0);
+};
+/** State of each stage relative to the current one. */
+export const resolveStageStates = (stages, currentId) => {
+    const index = stages.findIndex(stage => stage.id === currentId);
+    // An unknown current id means nothing is complete — better than silently
+    // marking the whole path done because the host sent a stale value.
+    return stages.map((_, position) => index === -1
+        ? "upcoming"
+        : position < index
+            ? "complete"
+            : position === index
+                ? "current"
+                : "upcoming");
+};
+const elementStyles = `
+        :host {
+          display: block;
+        }
+
+        [part="path"] {
+          display: flex;
+          flex-wrap: wrap;
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+
+        [part="stage"] {
+          position: relative;
+          flex: 1 1 0;
+          min-inline-size: 6rem;
+          padding: 0.45rem 0.7rem 0.45rem 1.35rem;
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.82rem;
+          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        [part="stage"]:first-child {
+          padding-inline-start: 0.8rem;
+          border-start-start-radius: 999px;
+          border-end-start-radius: 999px;
+        }
+
+        [part="stage"]:last-child {
+          border-start-end-radius: 999px;
+          border-end-end-radius: 999px;
+        }
+
+        /* The chevron: a notch cut from the following stage plus an arrow on
+           this one, so the path reads as a directed sequence rather than a row
+           of pills. Drawn with clip-path so no extra elements are needed. */
+        [part="stage"]:not(:last-child) {
+          clip-path: polygon(0 0, calc(100% - 0.7rem) 0, 100% 50%, calc(100% - 0.7rem) 100%, 0 100%, 0.7rem 50%);
+          margin-inline-end: -0.55rem;
+        }
+
+        [part="stage"]:first-child:not(:last-child) {
+          clip-path: polygon(0 0, calc(100% - 0.7rem) 0, 100% 50%, calc(100% - 0.7rem) 100%, 0 100%);
+        }
+
+        [part="stage"]:last-child:not(:first-child) {
+          clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%, 0.7rem 50%);
+        }
+
+        [part="stage"][data-state="complete"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 18%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 72%, black 28%);
+        }
+
+        [part="stage"][data-state="current"] {
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+          color: var(--boe-token-text-text-on-brand, #ffffff);
+          font-weight: 700;
+        }
+
+        [part="stage-label"] {
+          display: block;
+        }
+
+        [part="stage-description"] {
+          display: block;
+          margin-block-start: 0.1rem;
+          font-size: 0.72rem;
+          font-weight: 400;
+          opacity: 0.85;
+        }
+
+        [part="stage-marker"] {
+          margin-inline-end: 0.3rem;
+          font-weight: 700;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+          [part="stage"] {
+            transition: none;
+          }
+        }
+
+        @media (max-width: 34rem) {
+          /* Chevrons collapse below the width where they stop being legible;
+             the states still read from tone and the completed marker. */
+          [part="stage"],
+          [part="stage"]:first-child:not(:last-child),
+          [part="stage"]:last-child:not(:first-child) {
+            clip-path: none;
+            margin-inline-end: 0;
+            padding-inline-start: 0.8rem;
+            border-radius: 0;
+          }
+        }
+      `;
+/**
+ * Horizontal chevron lifecycle tracker for record headers — Draft → In
+ * Review → Approved → Executed.
+ *
+ * Distinct from `box-progress-steps`, which is a vertical setup rail for a
+ * task the reader is working through: this states where a *record* sits in
+ * its lifecycle, is read-only, and belongs in a header rather than a form.
+ *
+ * Rendered as an ordered list with the current stage marked `aria-current`,
+ * so the sequence and the position are both available without relying on the
+ * chevron geometry — which is decoration, and collapses on narrow viewports.
+ */
+export class StagePath extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["current", "label", "stages"];
+    }
+    pathEl;
+    stagesRaw = null;
+    stagesCache = [];
+    get label() {
+        return this.getAttribute("label") ?? "Lifecycle";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    /** Id of the stage the record is at. An unknown id leaves every stage upcoming. */
+    get current() {
+        return this.getAttribute("current") ?? "";
+    }
+    set current(value) {
+        this.setAttribute("current", value);
+    }
+    get stages() {
+        const raw = this.getAttribute("stages");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.stagesRaw) {
+            this.stagesRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.stagesCache =
+                    Array.isArray(parsed) && parsed.every(isStagePathStageRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.stagesCache = [];
+            }
+        }
+        return [...this.stagesCache];
+    }
+    set stages(value) {
+        if (value.length) {
+            this.setAttribute("stages", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("stages");
+    }
+    /** State of each stage, in order. */
+    get states() {
+        return resolveStageStates(this.stages, this.current);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><ol part="path"></ol>`;
+        this.pathEl = this.shadowRoot.querySelector('[part="path"]');
+    }
+    setupListeners() {
+        // Read-only: a record's lifecycle position is not something a header edits.
+    }
+    update() {
+        if (!this.pathEl) {
+            return;
+        }
+        const stages = this.stages;
+        const states = resolveStageStates(stages, this.current);
+        this.pathEl.setAttribute("aria-label", this.label);
+        this.pathEl.innerHTML = stages
+            .map((stage, index) => {
+            const state = states[index];
+            // The completed marker is a second, non-colour signal for "done".
+            const marker = state === "complete" ? `<span part="stage-marker" aria-hidden="true">✓</span>` : "";
+            return `
+          <li
+            part="stage"
+            data-stage-id="${escapeHtml(stage.id)}"
+            data-state="${state}"
+            ${state === "current" ? 'aria-current="step"' : ""}
+          >
+            <span part="stage-label">${marker}${escapeHtml(stage.label)}</span>
+            ${state === "current" && stage.description
+                ? `<span part="stage-description">${escapeHtml(stage.description)}</span>`
+                : ""}
+          </li>
+        `;
+        })
+            .join("");
+    }
+}
+StagePath.register();

package/dist/components/forms/select.d.ts

@@ -6,6 +6,11 @@ type SelectOption = {
     disabled?: boolean;
     group?: string;
 };
+/** Detail of this element's `value-changed` event; `values` only when `multiple`. */
+export interface SelectValueChangedDetail {
+    value: string;
+    values?: string[];
+}
 export declare class Select extends FormAssociatedElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
@@ -15,6 +20,8 @@ export declare class Select extends FormAssociatedElement {
     private labelEl;
     private descriptionEl;
     private errorEl;
+    private controlEl;
+    private statusEl;
     /** Allow selecting several options (native multi-select list box). */
     get multiple(): boolean;
     set multiple(value: boolean);
@@ -27,6 +34,20 @@ export declare class Select extends FormAssociatedElement {
     set disabled(value: boolean);
     get label(): string;
     set label(value: string);
+    /**
+     * True while options are being fetched: shows a trailing spinner (matching
+     * `box-text-field`'s status vocabulary) and states "Loading options…" in
+     * the control instead of leaving it blank.
+     */
+    get loading(): boolean;
+    set loading(value: boolean);
+    /**
+     * What the control says when it has no options and is not loading. An
+     * async-loaded select with an empty result must say so — a silently blank
+     * control reads as broken.
+     */
+    get emptyText(): string;
+    set emptyText(value: string);
     get options(): SelectOption[];
     set options(value: SelectOption[]);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;