@unofficialbox/box-open-elements 0.10.0 → 0.12.0

package/dist/components/feedback/skeleton.d.ts

@@ -1,14 +1,84 @@
 import { BaseElement } from "../../core/index.js";
+import type { BoeGridPlacement, ResolvedBoeGridPlacement } from "../../foundations/layout/index.js";
+/**
+ * Shape of the placeholder.
+ *
+ * `box` is a single rectangle sized by `width`/`height` — the original
+ * behaviour, and still the default. `line` is a stack of text lines. `grid` is
+ * a column layout whose regions stand in for cards, tiles or panels.
+ */
+export type SkeletonVariant = "box" | "line" | "grid";
+/**
+ * Narrow an author-supplied variant, falling back to `box`.
+ *
+ * A typo should render the original single rectangle rather than an empty
+ * element: every multi-part branch is scoped to a known value.
+ */
+export declare const resolveSkeletonVariant: (value: string | null | undefined) => SkeletonVariant;
+/**
+ * The columns in Adobe Spectrum's responsive grid.
+ *
+ * Delegated to the layout foundation that `box-grid` also builds on: a
+ * skeleton stands in for a real layout, so if the two disagreed about what a
+ * column is worth the placeholder would stop matching what replaces it.
+ */
+export declare const SKELETON_DEFAULT_COLUMNS = 12;
+/** One region of the grid, in Spectrum's terms. */
+export type SkeletonGridItem = BoeGridPlacement;
+/** A resolved region: every field present, every value in range. */
+export type ResolvedSkeletonGridItem = ResolvedBoeGridPlacement;
+/** Attribute payloads are author input — validate every record. */
+export declare const isSkeletonGridItemRecord: (value: unknown) => value is BoeGridPlacement;
+/**
+ * Fit a region to the grid, clamping every value to the declared totals.
+ *
+ * Still exported here because it is part of this component's published
+ * surface; the behaviour now lives in the foundation.
+ */
+export declare const resolveSkeletonGridItem: (item: BoeGridPlacement, columns: number, rows: number) => ResolvedBoeGridPlacement;
 export declare class Skeleton extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
     private skeletonEl;
+    private rootEl;
     private appliedWidth;
     private appliedHeight;
+    private renderedVariant;
+    private itemsRaw;
+    private itemsCache;
     get width(): string;
     set width(value: string);
     get height(): string;
     set height(value: string);
+    /** Shape of the placeholder. An unknown value falls back to `box`. */
+    get variant(): SkeletonVariant;
+    set variant(value: SkeletonVariant);
+    /** Lines drawn by the `line` variant. Values below 1 render a single line. */
+    get lines(): number;
+    set lines(value: number);
+    /** Columns in the `grid` variant. Defaults to Spectrum's twelve. */
+    get columns(): number;
+    set columns(value: number);
+    /** Rows in the `grid` variant. Also the ceiling for any region's `rowSpan`. */
+    get rows(): number;
+    set rows(value: number);
+    /** Height of one grid row; a region spanning two is twice this plus a gutter. */
+    get rowHeight(): string;
+    set rowHeight(value: string);
+    /**
+     * Regions of the `grid` variant, in order.
+     *
+     * With none given the grid is filled with single-column regions — `rows` ×
+     * `columns` of them — so `rows` and `columns` alone describe a uniform grid.
+     */
+    get items(): SkeletonGridItem[];
+    set items(value: SkeletonGridItem[]);
+    /** The grid's regions as rendered: clamped to `columns` and `rows`. */
+    get resolvedItems(): ResolvedSkeletonGridItem[];
     protected renderTemplate(): void;
     protected update(): void;
+    /** Render the `line` or `grid` variant, which draw many bars rather than one. */
+    private updateGroup;
+    private renderLines;
+    private renderGrid;
 }

package/dist/components/feedback/skeleton.js

@@ -1,12 +1,48 @@
 import { BaseElement } from "../../core/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
+import { BOE_GRID_COLUMNS, BOE_GRID_GUTTER_PROPERTY, boeGridGutterStyles, isBoeGridPlacementRecord, resolveBoeGridPlacement, resolveGridCount, } from "../../foundations/layout/index.js";
 import { boeMotionDuration, boeMotionEasing, boeReducedMotionStyles, } from "../../foundations/motion/index.js";
 const DEFAULT_TAG_NAME = "box-skeleton";
+const SKELETON_VARIANTS = new Set(["box", "line", "grid"]);
+/**
+ * Narrow an author-supplied variant, falling back to `box`.
+ *
+ * A typo should render the original single rectangle rather than an empty
+ * element: every multi-part branch is scoped to a known value.
+ */
+export const resolveSkeletonVariant = (value) => SKELETON_VARIANTS.has(value) ? value : "box";
+/**
+ * The columns in Adobe Spectrum's responsive grid.
+ *
+ * Delegated to the layout foundation that `box-grid` also builds on: a
+ * skeleton stands in for a real layout, so if the two disagreed about what a
+ * column is worth the placeholder would stop matching what replaces it.
+ */
+export const SKELETON_DEFAULT_COLUMNS = BOE_GRID_COLUMNS;
+/** Attribute payloads are author input — validate every record. */
+export const isSkeletonGridItemRecord = isBoeGridPlacementRecord;
+/**
+ * Fit a region to the grid, clamping every value to the declared totals.
+ *
+ * Still exported here because it is part of this component's published
+ * surface; the behaviour now lives in the foundation.
+ */
+export const resolveSkeletonGridItem = resolveBoeGridPlacement;
 const skeletonStyles = `
   :host {
     display: inline-block;
     color: inherit;
     font: inherit;
+
+  }
+
+${boeGridGutterStyles(":host")}
+
+  /* The multi-part variants are layout, so they take the full width they are
+     given rather than shrink-wrapping like the single box. */
+  :host([variant="line"]),
+  :host([variant="grid"]) {
+    display: block;
   }
 
   [part="skeleton"] {
@@ -22,6 +58,38 @@ const skeletonStyles = `
     animation: boe-skeleton-shimmer ${boeMotionDuration.shimmer} ${boeMotionEasing.standard} infinite;
   }
 
+  [part="lines"] {
+    display: flex;
+    flex-direction: column;
+    gap: 0.55rem;
+  }
+
+  [part="lines"] [part="skeleton"] {
+    display: block;
+    inline-size: 100%;
+  }
+
+  /* The last line stops short, the way a paragraph's does. Without it a stack
+     of equal bars reads as a table rather than as text. */
+  [part="lines"] [part="skeleton"]:last-child:not(:only-child) {
+    inline-size: 62%;
+  }
+
+  [part="grid"] {
+    display: grid;
+    grid-template-columns: repeat(var(--boe-skeleton-columns, ${BOE_GRID_COLUMNS}), minmax(0, 1fr));
+    grid-auto-rows: var(--boe-skeleton-row-height, 48px);
+    gap: var(${BOE_GRID_GUTTER_PROPERTY});
+  }
+
+  /* Offsets are spacers rather than an explicit grid-column-start, so they
+     compose with auto-placement instead of fighting it: an explicit start makes
+     the item hunt for a row where that exact column is free, which reorders the
+     regions the author listed. */
+  [part="grid-offset"] {
+    visibility: hidden;
+  }
+
   @keyframes boe-skeleton-shimmer {
     0% {
       background-position: 100% 0;
@@ -37,11 +105,15 @@ const skeletonStyles = `
 export class Skeleton extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["height", "width"];
+        return ["columns", "height", "items", "lines", "row-height", "rows", "variant", "width"];
     }
     skeletonEl;
+    rootEl;
     appliedWidth = "";
     appliedHeight = "";
+    renderedVariant = null;
+    itemsRaw = null;
+    itemsCache = [];
     get width() {
         return this.getAttribute("width") ?? "100%";
     }
@@ -54,6 +126,85 @@ export class Skeleton extends BaseElement {
     set height(value) {
         this.setAttribute("height", value);
     }
+    /** Shape of the placeholder. An unknown value falls back to `box`. */
+    get variant() {
+        return resolveSkeletonVariant(this.getAttribute("variant"));
+    }
+    set variant(value) {
+        this.setAttribute("variant", value);
+    }
+    /** Lines drawn by the `line` variant. Values below 1 render a single line. */
+    get lines() {
+        const parsed = Number.parseInt(this.getAttribute("lines") ?? "", 10);
+        return Number.isFinite(parsed) ? Math.max(parsed, 1) : 3;
+    }
+    set lines(value) {
+        this.setAttribute("lines", String(value));
+    }
+    /** Columns in the `grid` variant. Defaults to Spectrum's twelve. */
+    get columns() {
+        return resolveGridCount(this.getAttribute("columns"), BOE_GRID_COLUMNS);
+    }
+    set columns(value) {
+        this.setAttribute("columns", String(value));
+    }
+    /** Rows in the `grid` variant. Also the ceiling for any region's `rowSpan`. */
+    get rows() {
+        return resolveGridCount(this.getAttribute("rows"), 1);
+    }
+    set rows(value) {
+        this.setAttribute("rows", String(value));
+    }
+    /** Height of one grid row; a region spanning two is twice this plus a gutter. */
+    get rowHeight() {
+        return this.getAttribute("row-height") ?? "48px";
+    }
+    set rowHeight(value) {
+        this.setAttribute("row-height", value);
+    }
+    /**
+     * Regions of the `grid` variant, in order.
+     *
+     * With none given the grid is filled with single-column regions — `rows` ×
+     * `columns` of them — so `rows` and `columns` alone describe a uniform grid.
+     */
+    get items() {
+        const raw = this.getAttribute("items");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.itemsRaw) {
+            this.itemsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.itemsCache =
+                    Array.isArray(parsed) && parsed.every(isSkeletonGridItemRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.itemsCache = [];
+            }
+        }
+        return [...this.itemsCache];
+    }
+    set items(value) {
+        if (value.length) {
+            this.setAttribute("items", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("items");
+    }
+    /** The grid's regions as rendered: clamped to `columns` and `rows`. */
+    get resolvedItems() {
+        const columns = this.columns;
+        const rows = this.rows;
+        const declared = this.items;
+        const source = declared.length
+            ? declared
+            : Array.from({ length: rows * columns }, () => ({}));
+        return source.map(item => resolveSkeletonGridItem(item, columns, rows));
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
@@ -65,8 +216,29 @@ export class Skeleton extends BaseElement {
         this.skeletonEl = this.shadowRoot.querySelector('[part="skeleton"]');
         this.appliedWidth = "";
         this.appliedHeight = "";
+        this.renderedVariant = "box";
     }
     update() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const variant = this.variant;
+        if (variant !== "box") {
+            this.updateGroup(variant);
+            return;
+        }
+        if (this.renderedVariant !== "box") {
+            // Coming back from a multi-part variant: restore the single box that the
+            // width/height path writes into.
+            this.shadowRoot.innerHTML = `
+        <style>${skeletonStyles}</style>
+        <span part="skeleton" style="display:inline-block;" aria-hidden="true"></span>
+      `;
+            this.skeletonEl = this.shadowRoot.querySelector('[part="skeleton"]');
+            this.appliedWidth = "";
+            this.appliedHeight = "";
+            this.renderedVariant = "box";
+        }
         if (!this.skeletonEl) {
             return;
         }
@@ -85,5 +257,63 @@ export class Skeleton extends BaseElement {
             this.appliedHeight = nextHeight;
         }
     }
+    /** Render the `line` or `grid` variant, which draw many bars rather than one. */
+    updateGroup(variant) {
+        const shadowRoot = this.shadowRoot;
+        if (this.renderedVariant !== variant) {
+            shadowRoot.innerHTML = `
+        <style>${skeletonStyles}</style>
+        <div part="${variant === "line" ? "lines" : "grid"}" aria-hidden="true"></div>
+      `;
+            this.rootEl = shadowRoot.querySelector(`[part="${variant === "line" ? "lines" : "grid"}"]`);
+            this.renderedVariant = variant;
+            this.appliedWidth = "";
+            this.appliedHeight = "";
+        }
+        if (variant === "line") {
+            this.renderLines();
+            return;
+        }
+        this.renderGrid();
+    }
+    renderLines() {
+        const count = this.lines;
+        const height = this.height;
+        // Reuse the bars already there: only the count changes between renders, and
+        // replacing every node would restart the shimmer on each update.
+        while (this.rootEl.childElementCount > count) {
+            this.rootEl.lastElementChild.remove();
+        }
+        while (this.rootEl.childElementCount < count) {
+            const line = document.createElement("span");
+            line.setAttribute("part", "skeleton");
+            this.rootEl.append(line);
+        }
+        for (const child of Array.from(this.rootEl.children)) {
+            // Via the CSSOM, for the same reason the box variant does: the value is
+            // author input and setProperty drops anything that is not a length.
+            child.style.setProperty("height", height);
+        }
+    }
+    renderGrid() {
+        this.rootEl.style.setProperty("--boe-skeleton-columns", String(this.columns));
+        this.rootEl.style.setProperty("--boe-skeleton-row-height", this.rowHeight);
+        // Rebuilt rather than patched: a change to items can alter every region's
+        // span and offset, so there is no stable identity to reuse.
+        this.rootEl.replaceChildren();
+        for (const item of this.resolvedItems) {
+            if (item.offset > 0) {
+                const spacer = document.createElement("span");
+                spacer.setAttribute("part", "grid-offset");
+                spacer.style.setProperty("grid-column", `span ${item.offset}`);
+                this.rootEl.append(spacer);
+            }
+            const region = document.createElement("span");
+            region.setAttribute("part", "skeleton");
+            region.style.setProperty("grid-column", `span ${item.span}`);
+            region.style.setProperty("grid-row", `span ${item.rowSpan}`);
+            this.rootEl.append(region);
+        }
+    }
 }
 Skeleton.register();

package/dist/components/feedback/toast.d.ts

@@ -1,11 +1,25 @@
 import { BaseElement } from "../../core/index.js";
+/**
+ * Whether the toast clears itself.
+ *
+ * `dismissible` auto-dismisses after `duration` and can also be closed by hand;
+ * `sticky` stays until the reader closes it, whatever `duration` says. Both
+ * carry the close control — a toast the reader cannot get rid of is a trap.
+ */
+export type ToastMode = "dismissible" | "sticky";
+/** Narrow an author-supplied mode, falling back to `dismissible`. */
+export declare const resolveToastMode: (value: string | null | undefined) => ToastMode;
 export declare class Toast extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
     private openValue;
     private timeoutId;
     private toastEl;
+    private iconEl;
+    private headingEl;
+    private toneLabelEl;
     private messageEl;
+    private renderedTone;
     private actionSlot;
     private dismissEl;
     /** Auto-dismiss delay in ms for the declarative `open` path. 0 = sticky. */
@@ -16,6 +30,29 @@ export declare class Toast extends BaseElement {
     private scheduleAutoDismiss;
     get message(): string;
     set message(value: string);
+    /**
+     * Optional bold line above the message — "Upload failed" over "3 of 12 files
+     * could not be read". Named to match `box-alert`, which established the
+     * heading-plus-message shape in this family. Salesforce calls it `label`.
+     */
+    get heading(): string;
+    set heading(value: string);
+    /**
+     * @deprecated Every toast is borderless now, so this does nothing.
+     *
+     * Kept because it shipped in 0.11.0 and removing it would break hosts that
+     * set it for no benefit — what they asked for is what they already get. The
+     * attribute is still reflected so those hosts read back what they wrote.
+     */
+    get borderless(): boolean;
+    set borderless(value: boolean);
+    /**
+     * Whether the toast clears itself. `sticky` overrides any `duration`: a
+     * caller that has said "this one stays" should not have it taken away by a
+     * duration set elsewhere.
+     */
+    get mode(): ToastMode;
+    set mode(value: ToastMode);
     get tone(): string;
     set tone(value: string);
     disconnectedCallback(): void;