@unofficialbox/box-open-elements 0.11.0 → 0.13.0

package/dist/components/output/formatted-value.js

@@ -0,0 +1,100 @@
+import { BaseElement } from "../../core/index.js";
+import { resolveLocale } from "../../foundations/format/index.js";
+const valueStyles = `
+  :host {
+    display: inline;
+    color: inherit;
+    font: inherit;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  /* Numbers and dates are scanned in columns far more often than they are read
+     in prose — a modified date beside a file name, a size in a table. Tabular
+     figures keep those columns aligned without the host having to ask. */
+  :host([tabular]) [part="value"] {
+    font-variant-numeric: tabular-nums;
+  }
+
+  [part="value"] {
+    white-space: nowrap;
+  }
+`;
+/**
+ * Shared behaviour for the read-only `box-formatted-*` renderers.
+ *
+ * These components render a typed value and nothing else: no interaction, no
+ * state, no events. What they do share is the awkward part — resolving a
+ * locale, deciding what a broken value looks like, and keeping a
+ * machine-readable form beside the human one.
+ *
+ * **A value that cannot be formatted hides the element.** Not `Invalid Date`,
+ * not `NaN`, not the raw string echoed back. A malformed value is a host bug,
+ * and rendering its wreckage puts the bug in front of a reader who can do
+ * nothing about it. The host is left with an empty inline box, which is what a
+ * missing value should look like anyway.
+ */
+export class FormattedValue extends BaseElement {
+    valueEl;
+    /**
+     * Whether to render into `<time>` rather than `<span>`.
+     *
+     * Only the instant-valued renderers should; `<time>` on a file size would be
+     * a lie to anything reading the document semantically.
+     */
+    usesTimeElement() {
+        return false;
+    }
+    /** Extra styles a subclass wants appended. */
+    valueStyles() {
+        return valueStyles;
+    }
+    /**
+     * The locale to format in. Absent means the host's own — deliberately
+     * `undefined` rather than a hardcoded tag.
+     */
+    get locale() {
+        return resolveLocale(this.getAttribute("locale"));
+    }
+    set locale(value) {
+        if (!value) {
+            this.removeAttribute("locale");
+            return;
+        }
+        this.setAttribute("locale", value);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const tag = this.usesTimeElement() ? "time" : "span";
+        this.shadowRoot.innerHTML = `<style>${this.valueStyles()}</style><${tag} part="value"></${tag}>`;
+        this.valueEl = this.shadowRoot.querySelector('[part="value"]');
+    }
+    setupListeners() {
+        // Output only: nothing to listen to.
+    }
+    update() {
+        if (!this.valueEl) {
+            return;
+        }
+        const result = this.formatted();
+        // toggleAttribute rather than `.hidden = `, so a host that set `hidden`
+        // itself is not fought with on every update.
+        this.toggleAttribute("hidden", result === null);
+        if (!result) {
+            this.valueEl.textContent = "";
+            this.valueEl.removeAttribute("datetime");
+            return;
+        }
+        this.valueEl.textContent = result.text;
+        if (result.machine) {
+            this.valueEl.setAttribute("datetime", result.machine);
+        }
+        else {
+            this.valueEl.removeAttribute("datetime");
+        }
+    }
+}

package/dist/components/output/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./formatted-value.js";
+export * from "./code-block.js";
+export * from "./formatted-date.js";
+export * from "./relative-time.js";
+export * from "./formatted-number.js";
+export * from "./formatted-file-size.js";

package/dist/components/output/index.js

@@ -0,0 +1,9 @@
+// Read-only renderers for typed values: dates, relative durations, numbers and
+// file sizes, all locale-aware and all hiding themselves when handed something
+// they cannot format.
+export * from "./formatted-value.js";
+export * from "./code-block.js";
+export * from "./formatted-date.js";
+export * from "./relative-time.js";
+export * from "./formatted-number.js";
+export * from "./formatted-file-size.js";

package/dist/components/output/relative-time.d.ts

@@ -0,0 +1,41 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * How long ago something happened, in the reader's locale.
+ *
+ * ```html
+ * <box-relative-time value="2026-08-24T09:00:00Z"></box-relative-time>
+ * ```
+ *
+ * Renders into `<time datetime="…">` carrying the exact instant, because
+ * "4 days ago" is an approximation and the precise value is what a reader
+ * reaches for when the approximation is not enough. `box-due-badge` makes the
+ * same trade for the same reason.
+ *
+ * `reference-time` pins what "now" means. It exists for the same reason
+ * `box-due-badge` has one: a component whose output depends on the wall clock
+ * cannot be tested or screenshotted deterministically, and a host rendering a
+ * list wants every row measured against one instant rather than each against
+ * the moment it happened to render.
+ */
+export declare class RelativeTime extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    protected usesTimeElement(): boolean;
+    /** The instant being described, as ISO 8601 or epoch milliseconds. */
+    get value(): string;
+    set value(next: string);
+    /** What "now" means. Absent uses the current time. */
+    get referenceTime(): string;
+    set referenceTime(next: string);
+    /**
+     * `auto` lets Intl say "yesterday" where the language has a word for it;
+     * `always` forces "1 day ago". Defaults to `auto`, because the idiomatic
+     * form is what a reader expects.
+     */
+    get numeric(): string;
+    set numeric(next: string);
+    protected formatted(): {
+        machine: string;
+        text: string;
+    } | null;
+}

package/dist/components/output/relative-time.js

@@ -0,0 +1,82 @@
+import { FormattedValue } from "./formatted-value.js";
+import { parseInstant, resolveRelativeParts } from "../../foundations/format/index.js";
+const DEFAULT_TAG_NAME = "box-relative-time";
+const NUMERIC_MODES = new Set(["always", "auto"]);
+/**
+ * How long ago something happened, in the reader's locale.
+ *
+ * ```html
+ * <box-relative-time value="2026-08-24T09:00:00Z"></box-relative-time>
+ * ```
+ *
+ * Renders into `<time datetime="…">` carrying the exact instant, because
+ * "4 days ago" is an approximation and the precise value is what a reader
+ * reaches for when the approximation is not enough. `box-due-badge` makes the
+ * same trade for the same reason.
+ *
+ * `reference-time` pins what "now" means. It exists for the same reason
+ * `box-due-badge` has one: a component whose output depends on the wall clock
+ * cannot be tested or screenshotted deterministically, and a host rendering a
+ * list wants every row measured against one instant rather than each against
+ * the moment it happened to render.
+ */
+export class RelativeTime extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["locale", "numeric", "reference-time", "value"];
+    }
+    usesTimeElement() {
+        return true;
+    }
+    /** The instant being described, as ISO 8601 or epoch milliseconds. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /** What "now" means. Absent uses the current time. */
+    get referenceTime() {
+        return this.getAttribute("reference-time") ?? "";
+    }
+    set referenceTime(next) {
+        if (!next) {
+            this.removeAttribute("reference-time");
+            return;
+        }
+        this.setAttribute("reference-time", next);
+    }
+    /**
+     * `auto` lets Intl say "yesterday" where the language has a word for it;
+     * `always` forces "1 day ago". Defaults to `auto`, because the idiomatic
+     * form is what a reader expects.
+     */
+    get numeric() {
+        const raw = this.getAttribute("numeric");
+        return raw && NUMERIC_MODES.has(raw) ? raw : "auto";
+    }
+    set numeric(next) {
+        this.setAttribute("numeric", next);
+    }
+    formatted() {
+        const instant = parseInstant(this.value);
+        if (!instant) {
+            return null;
+        }
+        // An unparseable reference falls back to now rather than hiding the
+        // element: the instant being described is still valid, and a broken
+        // reference should not erase it.
+        const reference = parseInstant(this.referenceTime) ?? new Date();
+        const { unit, value } = resolveRelativeParts(instant, reference);
+        try {
+            const formatter = new Intl.RelativeTimeFormat(this.locale, {
+                numeric: this.numeric,
+            });
+            return { machine: instant.toISOString(), text: formatter.format(value, unit) };
+        }
+        catch {
+            return { machine: instant.toISOString(), text: instant.toISOString() };
+        }
+    }
+}
+RelativeTime.register();

package/dist/element-maps.d.ts

@@ -36,6 +36,14 @@ import type { CollaboratorAvatars } from "./patterns/share/collaborator-avatars.
 import type { ColorPicker } from "./components/forms/color-picker.js";
 import type { Combobox } from "./components/forms/combobox.js";
 import type { CommandPalette } from "./components/overlays/command-palette.js";
+import type { CommentThread } from "./patterns/comments/comment-thread.js";
+import type { CodeBlock } from "./components/output/code-block.js";
+import type { FormattedDate } from "./components/output/formatted-date.js";
+import type { Indicator } from "./components/feedback/indicator.js";
+import type { TileGroup } from "./components/forms/tile-group.js";
+import type { FormattedFileSize } from "./components/output/formatted-file-size.js";
+import type { FormattedNumber } from "./components/output/formatted-number.js";
+import type { RelativeTime } from "./components/output/relative-time.js";
 import type { CompareView } from "./patterns/diff/compare-view.js";
 import type { ContactDatalistItem } from "./components/identity/contact-datalist-item.js";
 import type { ContentExplorer } from "./patterns/content-explorer/content-explorer.js";
@@ -178,6 +186,14 @@ declare global {
         "box-color-picker": ColorPicker;
         "box-combobox": Combobox;
         "box-command-palette": CommandPalette;
+        "box-comment-thread": CommentThread;
+        "box-code-block": CodeBlock;
+        "box-formatted-date": FormattedDate;
+        "box-indicator": Indicator;
+        "box-tile-group": TileGroup;
+        "box-formatted-file-size": FormattedFileSize;
+        "box-formatted-number": FormattedNumber;
+        "box-relative-time": RelativeTime;
         "box-compare-view": CompareView;
         "box-contact-datalist-item": ContactDatalistItem;
         "box-content-explorer": ContentExplorer;
@@ -291,4 +307,4 @@ declare global {
     }
 }
 /** Every element tag the library registers, for host-side narrowing. */
-export type BoxElementTagName = "box-access-stats" | "box-accordion" | "box-activity-density" | "box-agent-chat" | "box-alert" | "box-annotation-inspector" | "box-annotation-thread" | "box-annotation-toolbar" | "box-app-shell" | "box-audit-log" | "box-avatar" | "box-badge" | "box-badgeable" | "box-bar-chart" | "box-breadcrumb" | "box-bulk-action-bar" | "box-button" | "box-button-group" | "box-calendar" | "box-card" | "box-carousel" | "box-category-selector" | "box-chart-panel" | "box-checkbox" | "box-checkbox-group" | "box-chip" | "box-collaborator-avatars" | "box-color-picker" | "box-combobox" | "box-command-palette" | "box-compare-view" | "box-contact-datalist-item" | "box-content-explorer" | "box-content-picker" | "box-content-sidebar" | "box-content-uploader" | "box-context-menu" | "box-datalist-item" | "box-date-field" | "box-dialog" | "box-diff-viewer" | "box-divider" | "box-grid" | "box-donut-chart" | "box-draggable-list" | "box-drawer" | "box-drop-zone" | "box-dropdown" | "box-dual-listbox" | "box-due-badge" | "box-empty-state" | "box-error-mask" | "box-explorer-action-menu" | "box-explorer-breadcrumbs" | "box-explorer-items" | "box-explorer-list" | "box-explorer-table" | "box-explorer-toolbar" | "box-fieldset" | "box-file-request-builder" | "box-filter-bar" | "box-form-wizard" | "box-governance-panel" | "box-grid-view" | "box-guide-tooltip" | "box-help-text" | "box-icon-button" | "box-illustration" | "box-invite-collaborators-modal" | "box-item-details-panel" | "box-item-form" | "box-line-chart" | "box-lineage-graph" | "box-link-button" | "box-menu" | "box-menu-item" | "box-metadata-filter-builder" | "box-metadata-inspector" | "box-metric-card" | "box-multi-select" | "box-nav-sidebar" | "box-notification-bell" | "box-notification-inbox" | "box-nudge" | "box-number-input" | "box-pagination" | "box-permission-matrix" | "box-persona" | "box-pill-cloud" | "box-pill-selector-dropdown" | "box-popover" | "box-presence" | "box-preview-element" | "box-preview-header" | "box-progress-bar" | "box-progress-ring" | "box-progress-steps" | "box-provenance-strip" | "box-radio-group" | "box-range-slider" | "box-rating" | "box-review-queue-item" | "box-rich-text-input" | "box-run-trace" | "box-saved-view-picker" | "box-search-field" | "box-search-results-header" | "box-section" | "box-segmented-control" | "box-select" | "box-share-panel" | "box-shortcuts-overlay" | "box-sidebar-toggle-button" | "box-signature-ceremony" | "box-skeleton" | "box-slider" | "box-spin-button" | "box-spinner" | "box-split-view" | "box-path" | "box-switch" | "box-table" | "box-tabs" | "box-tag-input" | "box-task-assignment-panel" | "box-text-area" | "box-text-field" | "box-thumbnail-card" | "box-time-field" | "box-timeline" | "box-toast" | "box-tooltip" | "box-tree" | "box-tree-grid" | "box-unified-share-modal" | "box-version-graph" | "box-version-list" | "box-wizard-summary" | "box-work-queue" | "box-workload-board";
+export type BoxElementTagName = "box-access-stats" | "box-accordion" | "box-activity-density" | "box-agent-chat" | "box-alert" | "box-annotation-inspector" | "box-annotation-thread" | "box-annotation-toolbar" | "box-app-shell" | "box-audit-log" | "box-avatar" | "box-badge" | "box-badgeable" | "box-bar-chart" | "box-breadcrumb" | "box-bulk-action-bar" | "box-button" | "box-button-group" | "box-calendar" | "box-card" | "box-carousel" | "box-category-selector" | "box-chart-panel" | "box-checkbox" | "box-checkbox-group" | "box-chip" | "box-collaborator-avatars" | "box-color-picker" | "box-combobox" | "box-command-palette" | "box-comment-thread" | "box-code-block" | "box-formatted-date" | "box-indicator" | "box-tile-group" | "box-formatted-file-size" | "box-formatted-number" | "box-relative-time" | "box-compare-view" | "box-contact-datalist-item" | "box-content-explorer" | "box-content-picker" | "box-content-sidebar" | "box-content-uploader" | "box-context-menu" | "box-datalist-item" | "box-date-field" | "box-dialog" | "box-diff-viewer" | "box-divider" | "box-grid" | "box-donut-chart" | "box-draggable-list" | "box-drawer" | "box-drop-zone" | "box-dropdown" | "box-dual-listbox" | "box-due-badge" | "box-empty-state" | "box-error-mask" | "box-explorer-action-menu" | "box-explorer-breadcrumbs" | "box-explorer-items" | "box-explorer-list" | "box-explorer-table" | "box-explorer-toolbar" | "box-fieldset" | "box-file-request-builder" | "box-filter-bar" | "box-form-wizard" | "box-governance-panel" | "box-grid-view" | "box-guide-tooltip" | "box-help-text" | "box-icon-button" | "box-illustration" | "box-invite-collaborators-modal" | "box-item-details-panel" | "box-item-form" | "box-line-chart" | "box-lineage-graph" | "box-link-button" | "box-menu" | "box-menu-item" | "box-metadata-filter-builder" | "box-metadata-inspector" | "box-metric-card" | "box-multi-select" | "box-nav-sidebar" | "box-notification-bell" | "box-notification-inbox" | "box-nudge" | "box-number-input" | "box-pagination" | "box-permission-matrix" | "box-persona" | "box-pill-cloud" | "box-pill-selector-dropdown" | "box-popover" | "box-presence" | "box-preview-element" | "box-preview-header" | "box-progress-bar" | "box-progress-ring" | "box-progress-steps" | "box-provenance-strip" | "box-radio-group" | "box-range-slider" | "box-rating" | "box-review-queue-item" | "box-rich-text-input" | "box-run-trace" | "box-saved-view-picker" | "box-search-field" | "box-search-results-header" | "box-section" | "box-segmented-control" | "box-select" | "box-share-panel" | "box-shortcuts-overlay" | "box-sidebar-toggle-button" | "box-signature-ceremony" | "box-skeleton" | "box-slider" | "box-spin-button" | "box-spinner" | "box-split-view" | "box-path" | "box-switch" | "box-table" | "box-tabs" | "box-tag-input" | "box-task-assignment-panel" | "box-text-area" | "box-text-field" | "box-thumbnail-card" | "box-time-field" | "box-timeline" | "box-toast" | "box-tooltip" | "box-tree" | "box-tree-grid" | "box-unified-share-modal" | "box-version-graph" | "box-version-list" | "box-wizard-summary" | "box-work-queue" | "box-workload-board";

package/dist/entries/code-block.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/code-block.js";

package/dist/entries/code-block.js

@@ -0,0 +1 @@
+export * from "../components/output/code-block.js";

package/dist/entries/comment-thread.d.ts

@@ -0,0 +1 @@
+export * from "../patterns/comments/index.js";

package/dist/entries/comment-thread.js

@@ -0,0 +1 @@
+export * from "../patterns/comments/index.js";

package/dist/entries/formatted-date.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/formatted-date.js";

package/dist/entries/formatted-date.js

@@ -0,0 +1 @@
+export * from "../components/output/formatted-date.js";

package/dist/entries/formatted-file-size.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/formatted-file-size.js";

package/dist/entries/formatted-file-size.js

@@ -0,0 +1 @@
+export * from "../components/output/formatted-file-size.js";

package/dist/entries/formatted-number.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/formatted-number.js";

package/dist/entries/formatted-number.js

@@ -0,0 +1 @@
+export * from "../components/output/formatted-number.js";

package/dist/entries/indicator.d.ts

@@ -0,0 +1 @@
+export * from "../components/feedback/indicator.js";

package/dist/entries/indicator.js

@@ -0,0 +1 @@
+export * from "../components/feedback/indicator.js";

package/dist/entries/relative-time.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/relative-time.js";

package/dist/entries/relative-time.js

@@ -0,0 +1 @@
+export * from "../components/output/relative-time.js";

package/dist/entries/tile-group.d.ts

@@ -0,0 +1 @@
+export * from "../components/forms/tile-group.js";

package/dist/entries/tile-group.js

@@ -0,0 +1 @@
+export * from "../components/forms/tile-group.js";

package/dist/foundations/format/format.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed-value formatting, as a foundation.
+ *
+ * Every read surface in a content platform renders the same handful of value
+ * types — a modified date, a file size, a count, a duration since something
+ * happened. Before this module each consumer reinvented that, which meant
+ * locale handling, `<time datetime>` semantics and invalid-input behaviour were
+ * reinvented with it, differently each time.
+ *
+ * The rules here are deliberately shared rather than per-component:
+ *
+ * - **A locale is never guessed.** An absent `locale` means "use the host's",
+ *   which is `undefined` to `Intl` — not a hardcoded `en-US`. Substituting one
+ *   would silently render American dates to a German reader.
+ * - **Invalid input renders nothing.** Not `Invalid Date`, not `NaN`, not the
+ *   raw string. A malformed value is a host bug, and showing its wreckage to a
+ *   reader helps nobody; the element collapses and the host sees an empty slot.
+ */
+/**
+ * The locale to format in.
+ *
+ * `undefined` is meaningful: it tells `Intl` to use the runtime's own locale.
+ * An empty or absent attribute must therefore become `undefined` rather than
+ * any particular language tag.
+ */
+export declare const resolveLocale: (value: string | null | undefined) => string | undefined;
+/**
+ * Parse an instant from author input.
+ *
+ * Accepts an ISO 8601 string or epoch milliseconds, because hosts have both:
+ * a JSON API hands over strings, a `Date.now()` arithmetic result hands over
+ * numbers. Anything unparseable is `null` rather than an Invalid Date, so
+ * callers test one thing instead of remembering `Number.isNaN(d.getTime())`.
+ */
+export declare const parseInstant: (value: string | number | null | undefined) => Date | null;
+/** Parse a finite number from author input, or `null`. */
+export declare const parseNumber: (value: string | number | null | undefined) => number | null;
+/** Date and time presets, mirroring `Intl.DateTimeFormat`'s own vocabulary. */
+export type BoeDateStyle = "full" | "long" | "medium" | "short";
+/** Narrow an author-supplied style, or `undefined` to omit it entirely. */
+export declare const resolveDateStyle: (value: string | null | undefined) => BoeDateStyle | undefined;
+/** A relative duration, in the largest unit that yields a whole number ≥ 1. */
+export interface BoeRelativeParts {
+    unit: Intl.RelativeTimeFormatUnit;
+    value: number;
+}
+/**
+ * Express the distance from `reference` to `instant` in one unit.
+ *
+ * The sign follows `Intl.RelativeTimeFormat`: negative is the past. The largest
+ * unit that yields a magnitude of at least one is chosen, so a four-day-old
+ * file reads "4 days ago" rather than "96 hours ago"; months and years are the
+ * usual approximations, which is what a reader wants from a relative label and
+ * why an exact timestamp stays available alongside it.
+ */
+export declare const resolveRelativeParts: (instant: Date, reference: Date) => BoeRelativeParts;
+/**
+ * Byte units.
+ *
+ * `binary` is powers of 1024 with IEC names (KiB, MiB); `decimal` is powers of
+ * 1000 with SI names (kB, MB). Box's own UI reports decimal, which is why it is
+ * the default — a file the product calls 1.2 MB should not become 1.1 MiB here.
+ */
+export type BoeByteUnits = "decimal" | "binary";
+/** Narrow author-supplied byte units, falling back to `decimal`. */
+export declare const resolveByteUnits: (value: string | null | undefined) => BoeByteUnits;
+/** A file size split into the number to format and the unit to append. */
+export interface BoeFileSizeParts {
+    suffix: string;
+    value: number;
+}
+/**
+ * Reduce a byte count to a readable magnitude and its unit.
+ *
+ * The number is returned unformatted so the caller can run it through
+ * `Intl.NumberFormat` in the reader's locale — a size rendered as "1,5 MB" for
+ * a German reader is the whole point of not doing this with `toFixed`.
+ *
+ * Bytes themselves are never fractional: "1.5 B" is nonsense, so the base unit
+ * is reported whole.
+ */
+export declare const resolveFileSizeParts: (bytes: number, units?: BoeByteUnits) => BoeFileSizeParts;

package/dist/foundations/format/format.js

@@ -0,0 +1,122 @@
+/**
+ * Typed-value formatting, as a foundation.
+ *
+ * Every read surface in a content platform renders the same handful of value
+ * types — a modified date, a file size, a count, a duration since something
+ * happened. Before this module each consumer reinvented that, which meant
+ * locale handling, `<time datetime>` semantics and invalid-input behaviour were
+ * reinvented with it, differently each time.
+ *
+ * The rules here are deliberately shared rather than per-component:
+ *
+ * - **A locale is never guessed.** An absent `locale` means "use the host's",
+ *   which is `undefined` to `Intl` — not a hardcoded `en-US`. Substituting one
+ *   would silently render American dates to a German reader.
+ * - **Invalid input renders nothing.** Not `Invalid Date`, not `NaN`, not the
+ *   raw string. A malformed value is a host bug, and showing its wreckage to a
+ *   reader helps nobody; the element collapses and the host sees an empty slot.
+ */
+/**
+ * The locale to format in.
+ *
+ * `undefined` is meaningful: it tells `Intl` to use the runtime's own locale.
+ * An empty or absent attribute must therefore become `undefined` rather than
+ * any particular language tag.
+ */
+export const resolveLocale = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+};
+/**
+ * Parse an instant from author input.
+ *
+ * Accepts an ISO 8601 string or epoch milliseconds, because hosts have both:
+ * a JSON API hands over strings, a `Date.now()` arithmetic result hands over
+ * numbers. Anything unparseable is `null` rather than an Invalid Date, so
+ * callers test one thing instead of remembering `Number.isNaN(d.getTime())`.
+ */
+export const parseInstant = (value) => {
+    if (value === null || value === undefined || value === "") {
+        return null;
+    }
+    // A bare number, or a numeric string, is epoch milliseconds. Checking the
+    // string form first matters: `new Date("1700000000000")` is not the same
+    // instant as `new Date(1700000000000)`.
+    const numeric = typeof value === "number" ? value : Number(value);
+    const date = Number.isFinite(numeric) ? new Date(numeric) : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date;
+};
+/** Parse a finite number from author input, or `null`. */
+export const parseNumber = (value) => {
+    if (value === null || value === undefined || value === "") {
+        return null;
+    }
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const DATE_STYLES = new Set(["full", "long", "medium", "short"]);
+/** Narrow an author-supplied style, or `undefined` to omit it entirely. */
+export const resolveDateStyle = (value) => DATE_STYLES.has(value) ? value : undefined;
+/**
+ * The units a relative time can be expressed in, largest first.
+ *
+ * Seconds are the floor: "0 minutes ago" reads as broken, and a surface that
+ * needs sub-second precision is not one a human is reading.
+ */
+const RELATIVE_UNITS = [
+    { unit: "year", ms: 365 * 24 * 60 * 60 * 1000 },
+    { unit: "month", ms: 30 * 24 * 60 * 60 * 1000 },
+    { unit: "week", ms: 7 * 24 * 60 * 60 * 1000 },
+    { unit: "day", ms: 24 * 60 * 60 * 1000 },
+    { unit: "hour", ms: 60 * 60 * 1000 },
+    { unit: "minute", ms: 60 * 1000 },
+    { unit: "second", ms: 1000 },
+];
+/**
+ * Express the distance from `reference` to `instant` in one unit.
+ *
+ * The sign follows `Intl.RelativeTimeFormat`: negative is the past. The largest
+ * unit that yields a magnitude of at least one is chosen, so a four-day-old
+ * file reads "4 days ago" rather than "96 hours ago"; months and years are the
+ * usual approximations, which is what a reader wants from a relative label and
+ * why an exact timestamp stays available alongside it.
+ */
+export const resolveRelativeParts = (instant, reference) => {
+    const delta = instant.getTime() - reference.getTime();
+    const magnitude = Math.abs(delta);
+    for (const { unit, ms } of RELATIVE_UNITS) {
+        if (magnitude >= ms) {
+            // Truncate rather than round: 47 hours is "1 day ago", not "2 days ago".
+            // Rounding would let a label claim a boundary the instant has not crossed.
+            return { unit, value: Math.trunc(delta / ms) };
+        }
+    }
+    return { unit: "second", value: 0 };
+};
+const BYTE_UNITS = new Set(["decimal", "binary"]);
+/** Narrow author-supplied byte units, falling back to `decimal`. */
+export const resolveByteUnits = (value) => BYTE_UNITS.has(value) ? value : "decimal";
+const DECIMAL_SUFFIXES = ["B", "kB", "MB", "GB", "TB", "PB"];
+const BINARY_SUFFIXES = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+/**
+ * Reduce a byte count to a readable magnitude and its unit.
+ *
+ * The number is returned unformatted so the caller can run it through
+ * `Intl.NumberFormat` in the reader's locale — a size rendered as "1,5 MB" for
+ * a German reader is the whole point of not doing this with `toFixed`.
+ *
+ * Bytes themselves are never fractional: "1.5 B" is nonsense, so the base unit
+ * is reported whole.
+ */
+export const resolveFileSizeParts = (bytes, units = "decimal") => {
+    const base = units === "binary" ? 1024 : 1000;
+    const suffixes = units === "binary" ? BINARY_SUFFIXES : DECIMAL_SUFFIXES;
+    const magnitude = Math.abs(bytes);
+    if (magnitude < base) {
+        return { suffix: suffixes[0], value: Math.trunc(bytes) };
+    }
+    // Clamped so a petabyte-plus value keeps the largest name we have rather than
+    // running off the end of the table.
+    const exponent = Math.min(Math.floor(Math.log(magnitude) / Math.log(base)), suffixes.length - 1);
+    return { suffix: suffixes[exponent], value: bytes / base ** exponent };
+};

package/dist/foundations/format/index.d.ts

@@ -0,0 +1 @@
+export * from "./format.js";

package/dist/foundations/format/index.js

@@ -0,0 +1,3 @@
+// Typed-value formatting: locale resolution, instant parsing, relative
+// durations and byte magnitudes, shared by the box-formatted-* renderers.
+export * from "./format.js";

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_P
 export type { ApplyDesignProfileOptions, DesignProfileChangeDetail, DesignProfileController, DesignProfileControllerOptions, DesignProfileDefinition, DesignProfileDensity, DesignProfileElevation, DesignProfileMotion, DesignProfileRadius, DesignProfileSpacing, DesignProfileTypography, } from "./foundations/profiles/index.js";
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
 export * from "./foundations/layout/index.js";
+export * from "./foundations/format/index.js";
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, } from "./foundations/overlay/index.js";
 export * from "./components/actions/button.js";
@@ -37,6 +38,7 @@ export * from "./components/feedback/due-types.js";
 export * from "./components/feedback/empty-state.js";
 export * from "./components/feedback/error-mask.js";
 export * from "./components/feedback/help-text.js";
+export * from "./components/feedback/indicator.js";
 export * from "./components/feedback/nudge.js";
 export * from "./components/feedback/progress-bar.js";
 export * from "./components/feedback/progress-ring.js";
@@ -66,6 +68,7 @@ export * from "./components/forms/slider.js";
 export * from "./components/forms/spin-button.js";
 export * from "./components/forms/switch.js";
 export * from "./components/forms/tag-input.js";
+export * from "./components/forms/tile-group.js";
 export * from "./components/forms/time-field.js";
 export * from "./components/forms/category-selector.js";
 export * from "./components/forms/checkbox-group.js";
@@ -80,6 +83,12 @@ export * from "./components/forms/search-field.js";
 export * from "./components/forms/select.js";
 export * from "./components/forms/text-area.js";
 export * from "./components/forms/text-field.js";
+export * from "./components/output/formatted-value.js";
+export * from "./components/output/code-block.js";
+export * from "./components/output/formatted-date.js";
+export * from "./components/output/relative-time.js";
+export * from "./components/output/formatted-number.js";
+export * from "./components/output/formatted-file-size.js";
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";
 export * from "./components/layout/grid.js";
@@ -110,6 +119,7 @@ export * from "./patterns/versions/index.js";
 export * from "./patterns/lineage/index.js";
 export * from "./patterns/agent-chat/index.js";
 export * from "./patterns/audit/index.js";
+export * from "./patterns/comments/index.js";
 export * from "./patterns/notifications/index.js";
 export * from "./patterns/search/index.js";
 export * from "./patterns/item/index.js";