@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/components/feedback/due-badge.js

@@ -0,0 +1,168 @@
+import { DUE_BUCKET_LABELS, formatDueLabel, resolveDueBucket } from "./due-types.js";
+import { BaseElement } from "../../core/index.js";
+const DEFAULT_TAG_NAME = "box-due-badge";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const elementStyles = `
+        :host {
+          display: inline-block;
+        }
+
+        [part="badge"] {
+          display: inline-flex;
+          align-items: center;
+          gap: 0.28rem;
+          padding: 0.14rem 0.45rem;
+          border-radius: 999px;
+          border: 1px solid transparent;
+          font-size: 0.74rem;
+          font-weight: 600;
+          white-space: nowrap;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          background: color-mix(in srgb, var(--boe-token-surface-surface-hover, #f4f4f4) 80%, transparent);
+        }
+
+        [part="badge"][data-bucket="overdue"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 14%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+          border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 32%, transparent);
+        }
+
+        [part="badge"][data-bucket="today"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 18%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 46%, black 54%);
+          border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 38%, transparent);
+        }
+
+        [part="badge"][data-bucket="this-week"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 10%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 78%, black 22%);
+          border-color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 26%, transparent);
+        }
+
+        [part="marker"] {
+          inline-size: 0.42rem;
+          block-size: 0.42rem;
+          border-radius: 999px;
+          background: currentColor;
+        }
+
+        /* Tone is never the only signal: the label always states the urgency
+           in words, so the dot is decoration and stays out of the a11y tree. */
+        [part="badge"][data-bucket="later"] [part="marker"],
+        [part="badge"][data-bucket="none"] [part="marker"] {
+          background: color-mix(in srgb, currentColor 45%, transparent);
+        }
+
+        [part="badge"][data-compact="true"] {
+          padding: 0.1rem 0.35rem;
+          font-size: 0.7rem;
+        }
+      `;
+/**
+ * SLA / aging urgency for a due date — the badge the work-queue rows and
+ * record headers were specified to share.
+ *
+ * The label states the urgency in words ("Overdue by 3 days"), so colour is
+ * never the only signal, and the day count answers the question a due badge
+ * exists for: *how late is this?* A bare date makes the reader do that
+ * arithmetic themselves.
+ *
+ * `reference-time` pins "now" so rendering is deterministic — the same
+ * inputs always produce the same badge, in tests and in screenshots.
+ */
+export class DueBadge extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["compact", "due-at", "label", "reference-time"];
+    }
+    badgeEl;
+    textEl;
+    /** ISO timestamp the badge describes. Absent renders the no-due-date state. */
+    get dueAt() {
+        return this.getAttribute("due-at") ?? "";
+    }
+    set dueAt(value) {
+        this.setAttribute("due-at", value);
+    }
+    /** Overrides the derived wording; the bucket still drives the tone. */
+    get label() {
+        return this.getAttribute("label") ?? "";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    get compact() {
+        return this.hasAttribute("compact");
+    }
+    set compact(value) {
+        this.toggleAttribute("compact", value);
+    }
+    get referenceTime() {
+        return this.getAttribute("reference-time") ?? "";
+    }
+    set referenceTime(value) {
+        this.setAttribute("reference-time", value);
+    }
+    now() {
+        const raw = this.referenceTime;
+        if (raw) {
+            const parsed = new Date(raw);
+            if (!Number.isNaN(parsed.getTime())) {
+                return parsed;
+            }
+        }
+        return new Date();
+    }
+    /** The urgency bucket currently rendered. */
+    get bucket() {
+        return resolveDueBucket(this.dueAt || undefined, this.now());
+    }
+    /** The rendered wording, derived unless `label` overrides it. */
+    get resolvedLabel() {
+        return this.label || formatDueLabel(this.dueAt || undefined, this.now());
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <span part="badge">
+        <span part="marker" aria-hidden="true"></span>
+        <span part="text"></span>
+      </span>
+    `;
+        this.badgeEl = this.shadowRoot.querySelector('[part="badge"]');
+        this.textEl = this.shadowRoot.querySelector('[part="text"]');
+    }
+    setupListeners() {
+        // Presentational: no interaction to wire.
+    }
+    update() {
+        if (!this.badgeEl) {
+            return;
+        }
+        const bucket = this.bucket;
+        const label = this.resolvedLabel;
+        this.badgeEl.setAttribute("data-bucket", bucket);
+        this.badgeEl.setAttribute("data-compact", String(this.compact));
+        this.textEl.textContent = label;
+        // A machine-readable date for anything consuming the DOM, and a title so
+        // the exact timestamp stays reachable when the label is relative.
+        if (this.dueAt && bucket !== "none") {
+            this.badgeEl.setAttribute("title", this.dueAt);
+            this.setAttribute("datetime", this.dueAt);
+        }
+        else {
+            this.badgeEl.removeAttribute("title");
+            this.removeAttribute("datetime");
+        }
+        this.badgeEl.setAttribute("aria-label", bucket === "none" ? escapeHtml(DUE_BUCKET_LABELS.none) : escapeHtml(label));
+    }
+}
+DueBadge.register();

package/dist/components/feedback/due-types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SLA / aging urgency model, shared by `box-due-badge` and the work-queue
+ * pattern. Pure and timezone-independent.
+ *
+ * This lives with the component rather than the pattern because patterns
+ * compose components, not the other way round. `patterns/work-queue/types`
+ * re-exports it, so its public import path is unchanged.
+ */
+/** Urgency buckets, most urgent first. */
+export type DueBucket = "overdue" | "today" | "this-week" | "later" | "none";
+export declare const DUE_BUCKET_ORDER: readonly DueBucket[];
+export declare const DUE_BUCKET_LABELS: Record<DueBucket, string>;
+/**
+ * Bucket a due timestamp relative to `now`. Pure and timezone-independent:
+ * callers supply the reference time and day boundaries resolve against the
+ * reference time's UTC day, so the same inputs bucket identically on every
+ * host. A host that wants local-day semantics offsets the reference time it
+ * passes.
+ */
+export declare const resolveDueBucket: (dueAt: string | undefined, now: Date) => DueBucket;
+/**
+ * Whole days between `dueAt` and `now`, negative when overdue. Measured
+ * between UTC day boundaries rather than by elapsed milliseconds, so
+ * "tomorrow" is 1 whether it is 23 hours away or 25.
+ */
+export declare const daysUntilDue: (dueAt: string | undefined, now: Date) => number | null;
+/**
+ * Human phrasing for a due date: "Overdue by 3 days", "Due today",
+ * "Due tomorrow", "Due in 5 days". Aging is stated in days rather than as a
+ * bare date because an SLA badge exists to answer "how late is this?".
+ */
+export declare const formatDueLabel: (dueAt: string | undefined, now: Date) => string;

package/dist/components/feedback/due-types.js

@@ -0,0 +1,91 @@
+/**
+ * SLA / aging urgency model, shared by `box-due-badge` and the work-queue
+ * pattern. Pure and timezone-independent.
+ *
+ * This lives with the component rather than the pattern because patterns
+ * compose components, not the other way round. `patterns/work-queue/types`
+ * re-exports it, so its public import path is unchanged.
+ */
+export const DUE_BUCKET_ORDER = [
+    "overdue",
+    "today",
+    "this-week",
+    "later",
+    "none",
+];
+export const DUE_BUCKET_LABELS = {
+    overdue: "Overdue",
+    today: "Due today",
+    "this-week": "Due this week",
+    later: "Later",
+    none: "No due date",
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Bucket a due timestamp relative to `now`. Pure and timezone-independent:
+ * callers supply the reference time and day boundaries resolve against the
+ * reference time's UTC day, so the same inputs bucket identically on every
+ * host. A host that wants local-day semantics offsets the reference time it
+ * passes.
+ */
+export const resolveDueBucket = (dueAt, now) => {
+    if (!dueAt) {
+        return "none";
+    }
+    const due = new Date(dueAt);
+    if (Number.isNaN(due.getTime())) {
+        return "none";
+    }
+    if (due.getTime() < now.getTime()) {
+        return "overdue";
+    }
+    const endOfToday = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1) - 1;
+    if (due.getTime() <= endOfToday) {
+        return "today";
+    }
+    if (due.getTime() <= endOfToday + 6 * DAY_MS) {
+        return "this-week";
+    }
+    return "later";
+};
+/**
+ * Whole days between `dueAt` and `now`, negative when overdue. Measured
+ * between UTC day boundaries rather than by elapsed milliseconds, so
+ * "tomorrow" is 1 whether it is 23 hours away or 25.
+ */
+export const daysUntilDue = (dueAt, now) => {
+    if (!dueAt) {
+        return null;
+    }
+    const due = new Date(dueAt);
+    if (Number.isNaN(due.getTime())) {
+        return null;
+    }
+    const dueDay = Date.UTC(due.getUTCFullYear(), due.getUTCMonth(), due.getUTCDate());
+    const nowDay = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    return Math.round((dueDay - nowDay) / DAY_MS);
+};
+/**
+ * Human phrasing for a due date: "Overdue by 3 days", "Due today",
+ * "Due tomorrow", "Due in 5 days". Aging is stated in days rather than as a
+ * bare date because an SLA badge exists to answer "how late is this?".
+ */
+export const formatDueLabel = (dueAt, now) => {
+    const days = daysUntilDue(dueAt, now);
+    if (days === null) {
+        return DUE_BUCKET_LABELS.none;
+    }
+    if (days < 0) {
+        const overdue = Math.abs(days);
+        return `Overdue by ${String(overdue)} ${overdue === 1 ? "day" : "days"}`;
+    }
+    if (days === 0) {
+        // A same-day deadline that has already passed is overdue by hours, not
+        // days — the bucket knows, the day count does not.
+        return resolveDueBucket(dueAt, now) === "overdue" ? "Overdue" : "Due today";
+    }
+    if (days === 1) {
+        return "Due tomorrow";
+    }
+    return `Due in ${String(days)} days`;
+};

package/dist/components/feedback/progress-steps.d.ts

@@ -1,25 +1,71 @@
 import { BaseElement } from "../../core/index.js";
-type BoxProgressStep = {
+/**
+ * Explicit per-step status. Absent means the step derives complete / current /
+ * upcoming from its position relative to `value` — the behaviour existing
+ * hosts rely on. An explicit status wins over the positional derivation:
+ * `complete` marks out-of-order completion, `blocked` and `disabled` make the
+ * step non-interactive, `failed` stays interactive because a failed step is
+ * usually exactly where the user needs to go.
+ */
+export type ProgressStepStatus = "complete" | "blocked" | "failed" | "disabled";
+export interface ProgressStepItem {
     description?: string;
     label: string;
     value: string;
-};
+    status?: ProgressStepStatus;
+    /** Short visible note under the label explaining the status ("Waiting on legal review"). */
+    statusNote?: string;
+}
+export type ProgressStepState = "current" | "upcoming" | ProgressStepStatus;
+export interface ResolvedProgressStep {
+    item: ProgressStepItem;
+    state: ProgressStepState;
+    /**
+     * True on the step `value` points at, whatever its status — currency is
+     * position, status is condition, and the two are stated separately so a
+     * failed step can still be the one the user is on.
+     */
+    isCurrent: boolean;
+    /** Blocked and disabled steps take no clicks and no focus. */
+    interactive: boolean;
+}
+/** Attribute payloads are author input — validate every record. */
+export declare const isProgressStepRecord: (value: unknown) => value is ProgressStepItem;
+/**
+ * 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 declare const resolveStepStates: (items: readonly ProgressStepItem[], value: string) => ResolvedProgressStep[];
+/** Every state in words — colour never carries the meaning alone. */
+export declare const STEP_STATE_LABEL: Record<ProgressStepState, string>;
 export declare class ProgressSteps extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private stepsEl;
+    private liveEl;
     private itemsSignature;
     get label(): string;
     set label(value: string);
-    get items(): BoxProgressStep[];
-    set items(value: BoxProgressStep[]);
+    get items(): ProgressStepItem[];
+    set items(value: ProgressStepItem[]);
+    /** The resolved states — same objects the render uses. */
+    get resolvedSteps(): ResolvedProgressStep[];
     get value(): string;
     set value(nextValue: string);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected renderTemplate(): void;
     protected setupListeners(): void;
     private selectValue;
+    /** A polite announcement on user-driven step changes, never on render. */
+    private announceStep;
+    /**
+     * 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.
+     */
+    private tabbableIndex;
     protected update(): void;
 }
-export {};