@unofficialbox/box-open-elements 0.12.0 → 0.14.0

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";

package/dist/index.js

@@ -7,6 +7,8 @@ export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_P
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
 // Foundations: Adobe Spectrum's responsive grid (shared by box-grid and box-skeleton)
 export * from "./foundations/layout/index.js";
+// Foundations: locale-aware typed-value formatting (shared by box-formatted-*)
+export * from "./foundations/format/index.js";
 // Foundations: viewport-aware overlay positioning (for building custom overlays)
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 // Components: actions
@@ -38,6 +40,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";
@@ -72,6 +75,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";
@@ -86,6 +90,13 @@ 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";
+// Components: output (read-only typed-value renderers)
+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";
 // Components: layout
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",