@markii/stdlib 0.11.0 → 0.12.0

package/dist/contracts.js

@@ -15,6 +15,7 @@
  */
 import { LAYOUT_ATTRIBUTES, layoutWrapperAxis, otherLayoutAxis, } from './layout.js';
 import { TEXT_ALIGN_ATTRIBUTE } from './text-align.js';
+import { DECIMALS_ATTRIBUTE, FORMAT_ATTRIBUTE } from './value-format.js';
 /**
  * Builds one of docs/format.md's layout-wrapper container contracts,
  * `center`/`left`/`right`/`wide`/`narrow`/`full`/`fit`, which are otherwise
@@ -239,8 +240,10 @@ export const STANDARD_COMPONENTS = {
                 enum: ['up', 'down', 'flat'],
                 description: "Colors/annotates `delta` as an increase, decrease, or no change. Overridden by a bound `data=` object's `trend` field when both are present; absent/invalid means no trend styling.",
             },
+            format: FORMAT_ATTRIBUTE,
+            decimals: DECIMALS_ATTRIBUTE,
         },
-        description: 'A leaf directive rendering a big value plus label, e.g. `::stat{value=42 label="stars" trend=up}`. Data binding (§8): `data=name` resolves against the value store — a number/string value supplies `value` directly; an object may supply `value`/`label`/`delta`/`trend` fields (explicit attributes on the directive always take precedence over the bound object\'s fields). Degrades to `—` when both the attribute and the bound value are absent — never throws.',
+        description: 'A leaf directive rendering a big value plus label, e.g. `::stat{value=42 label="stars" trend=up}`. Data binding (§8): `data=name` resolves against the value store — a number/string value supplies `value` directly; an object may supply `value`/`label`/`delta`/`trend` fields (explicit attributes on the directive always take precedence over the bound object\'s fields). Degrades to `—` when both the attribute and the bound value are absent — never throws. `format`/`decimals` (docs/format.md) format the headline value before display.',
     },
     progress: {
         name: 'progress',
@@ -261,8 +264,10 @@ export const STANDARD_COMPONENTS = {
                 required: false,
                 description: 'Optional caption shown above/alongside the bar. Absent means no caption line is rendered.',
             },
+            format: FORMAT_ATTRIBUTE,
+            decimals: DECIMALS_ATTRIBUTE,
         },
-        description: 'A leaf directive rendering a meter bar, e.g. `::progress{value=3 max=5 label="tasks"}`. Data binding (§8): `data=name` resolves against the value store — a bare number supplies `value` directly; an object may supply `value`/`max` fields (explicit attributes take precedence). Parses defensively and clamps rather than throwing; missing/invalid input renders an empty (0%) bar.',
+        description: 'A leaf directive rendering a meter bar, e.g. `::progress{value=3 max=5 label="tasks"}`. Data binding (§8): `data=name` resolves against the value store — a bare number supplies `value` directly; an object may supply `value`/`max` fields (explicit attributes take precedence). Parses defensively and clamps rather than throwing; missing/invalid input renders an empty (0%) bar. `format`/`decimals` (docs/format.md), when present, format the fraction `value/max` for the percent readout in place of the default rounded integer percent; absent means the unchanged default (`42%`).',
     },
     chart: {
         name: 'chart',
@@ -282,6 +287,31 @@ export const STANDARD_COMPONENTS = {
         },
         description: 'A leaf directive rendering a minimal hand-rolled inline SVG chart, e.g. `::chart{kind=line values="1,3,2,5"}`. Sizes to its container — use docs/format.md\'s `width`/`align` layout presets to control its footprint, not a pixel attribute. Data binding (§8): `data=name` resolves against the value store — expects an array of numbers (typically a Lua script returning a table), or an array of `{value}` objects. Non-finite/non-numeric entries are filtered out and the point count is capped; an empty or all-invalid series renders a small neutral empty state rather than a broken chart. Never throws, and never places unescaped text into the emitted SVG markup.',
     },
+    table: {
+        name: 'table',
+        kind: 'leaf',
+        attributes: {
+            columns: {
+                type: 'string',
+                required: false,
+                description: "Comma-separated key list, shown in that order instead of the bound data's own key order. A key no row has renders an empty cell for that column. Only meaningful for an array-of-objects or single-object binding.",
+            },
+            caption: {
+                type: 'string',
+                required: false,
+                description: 'Optional caption text shown with the table. Absent means no caption.',
+            },
+            limit: {
+                type: 'string',
+                required: false,
+                description: 'Maximum number of rows shown, as a positive integer. An absent, non-integer, or non-positive value is ignored and every row is shown.',
+            },
+            text: TEXT_ALIGN_ATTRIBUTE,
+            format: FORMAT_ATTRIBUTE,
+            decimals: DECIMALS_ATTRIBUTE,
+        },
+        description: 'A leaf directive rendering a data-bound table, e.g. `::table{data=users columns="name,role" limit=10}`. Data binding (§8): `data=name` resolves against the value store — an array of objects becomes columns from the union of keys in first-seen order (or `columns=`, when given); an array of arrays becomes rows as given; an array of primitives becomes a single column; a single object becomes key/value rows. `format`/`decimals` (docs/format.md) apply to numeric cells only; non-numeric cells render as plain text regardless. Degrades to the same quiet empty/stale/failure presentation as `stat` for a missing, stale, or failed binding — never throws.',
+    },
     row: {
         name: 'row',
         kind: 'container',

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { getContract, STANDARD_COMPONENTS, type AttributeSchema, type ComponentContract, type ComponentKind, } from './contracts.js';
 export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS, layoutWrapperAxis, otherLayoutAxis, type LayoutAxis, } from './layout.js';
 export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, type TextAlignPreset, } from './text-align.js';
+export { formatValue, isNumericLike, FORMAT_ATTRIBUTE, DECIMALS_ATTRIBUTE, type ValueFormat, } from './value-format.js';
+export { deriveTableShape, type TableShape } from './table-shape.js';

package/dist/index.js

@@ -1,3 +1,5 @@
 export { getContract, STANDARD_COMPONENTS, } from './contracts.js';
 export { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, LAYOUT_ATTRIBUTES, WIDTH_PRESETS, layoutWrapperAxis, otherLayoutAxis, } from './layout.js';
 export { TEXT_ALIGN_ATTRIBUTE, TEXT_ALIGN_COMPONENTS, TEXT_ALIGN_PRESETS, } from './text-align.js';
+export { formatValue, isNumericLike, FORMAT_ATTRIBUTE, DECIMALS_ATTRIBUTE, } from './value-format.js';
+export { deriveTableShape } from './table-shape.js';

package/dist/table-shape.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The pure "what does a bound value look like as a table" logic behind
+ * `::table` (docs/format.md), shared by `@markii/react` and `@markii/html`
+ * so the same bound value produces the same rows/columns in both engines —
+ * exactly the reasoning `@markii/stdlib`'s `layout.ts` gives for keeping the
+ * width/align preset vocabulary in one neutral place instead of two
+ * hand-copied renderer implementations.
+ *
+ * Zero dependency, no rendering concerns: this module only classifies a
+ * JS value into rows and (when there are any) column headers. Formatting a
+ * cell's value to display text is `formatValue`'s job (`./value-format.ts`);
+ * building markup is each renderer's own.
+ */
+/** A bound array of plain objects: columns = the union of keys in first-seen order (or `columns=`, when given), each row's cells aligned to them. */
+export interface ObjectRowsTableShape {
+    kind: 'objects';
+    columns: string[];
+    rows: unknown[][];
+}
+/** A bound array of arrays: rows exactly as given, no column headers. */
+export interface ArrayRowsTableShape {
+    kind: 'arrays';
+    rows: unknown[][];
+}
+/** A bound array of primitives (numbers, strings, booleans, `null`): one column, one cell per row. */
+export interface PrimitiveRowsTableShape {
+    kind: 'primitives';
+    rows: unknown[][];
+}
+/** A bound single plain object: one row per key, in `columns=` order when given, otherwise the object's own key order. */
+export interface KeyValueTableShape {
+    kind: 'keyvalue';
+    rows: Array<[key: string, value: unknown]>;
+}
+/** An empty array, or a bound value that is neither an array nor a plain object (a bare number/string, `null`, `undefined`): nothing to show as a table. */
+export interface EmptyTableShape {
+    kind: 'empty';
+}
+export type TableShape = ObjectRowsTableShape | ArrayRowsTableShape | PrimitiveRowsTableShape | KeyValueTableShape | EmptyTableShape;
+/**
+ * Classifies a bound `data` value into a `TableShape`, per docs/format.md's
+ * four bindable shapes. `columnsOverride` is `::table`'s `columns=`
+ * attribute (already split on commas and trimmed by the caller); it
+ * reorders/restricts the columns of an `objects`/`keyvalue` shape and is
+ * ignored for `arrays`/`primitives`, which have no keys to select from.
+ *
+ * MAY THROW for a hostile bound value: `Array.isArray`, `Object.keys`, and
+ * every property read below go through whatever traps a host put on the
+ * object. The guard is at the call site (each renderer's own `safeRead`
+ * equivalent), which wraps the whole extraction rather than each read —
+ * matching `stat`/`progress`/`chart`'s existing `readStatFields`/
+ * `readProgressFields`/`resolvePoints` functions in both engines. Only
+ * plain data (strings, the union-of-keys array, cell values already read
+ * off the bound object) ever leaves here, so nothing hostile escapes the
+ * guard.
+ */
+export declare function deriveTableShape(data: unknown, columnsOverride?: readonly string[]): TableShape;

package/dist/table-shape.js

@@ -0,0 +1,98 @@
+/**
+ * The pure "what does a bound value look like as a table" logic behind
+ * `::table` (docs/format.md), shared by `@markii/react` and `@markii/html`
+ * so the same bound value produces the same rows/columns in both engines —
+ * exactly the reasoning `@markii/stdlib`'s `layout.ts` gives for keeping the
+ * width/align preset vocabulary in one neutral place instead of two
+ * hand-copied renderer implementations.
+ *
+ * Zero dependency, no rendering concerns: this module only classifies a
+ * JS value into rows and (when there are any) column headers. Formatting a
+ * cell's value to display text is `formatValue`'s job (`./value-format.ts`);
+ * building markup is each renderer's own.
+ */
+/** A plain (non-array, non-`null`) object — the shape test every branch below needs. */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Reads `key` off `object` without `in`/bracket access resolving a hostile
+ * key (`'__proto__'`, `'constructor'`, `'toString'`) through the prototype
+ * chain to an inherited `Object.prototype` member instead of correctly
+ * reporting "this row has no such key" — the same defensive pattern
+ * `./contracts.ts`'s `getContract` and every renderer's registry lookup use.
+ */
+function readOwn(object, key) {
+    return Object.hasOwn(object, key) ? object[key] : undefined;
+}
+/**
+ * The union of every plain-object row's own keys, in first-seen order
+ * across the whole array — not just the first row's keys — so a row later
+ * in the array that carries an extra field still gets its own column
+ * rather than being silently dropped. A non-object entry mixed into an
+ * otherwise-object array (defensive: the format never asks authors to mix
+ * shapes) contributes no keys of its own.
+ */
+function unionKeysInFirstSeenOrder(rows) {
+    const seen = new Set();
+    const columns = [];
+    for (const row of rows) {
+        if (!isPlainObject(row))
+            continue;
+        for (const key of Object.keys(row)) {
+            if (!seen.has(key)) {
+                seen.add(key);
+                columns.push(key);
+            }
+        }
+    }
+    return columns;
+}
+/**
+ * Classifies a bound `data` value into a `TableShape`, per docs/format.md's
+ * four bindable shapes. `columnsOverride` is `::table`'s `columns=`
+ * attribute (already split on commas and trimmed by the caller); it
+ * reorders/restricts the columns of an `objects`/`keyvalue` shape and is
+ * ignored for `arrays`/`primitives`, which have no keys to select from.
+ *
+ * MAY THROW for a hostile bound value: `Array.isArray`, `Object.keys`, and
+ * every property read below go through whatever traps a host put on the
+ * object. The guard is at the call site (each renderer's own `safeRead`
+ * equivalent), which wraps the whole extraction rather than each read —
+ * matching `stat`/`progress`/`chart`'s existing `readStatFields`/
+ * `readProgressFields`/`resolvePoints` functions in both engines. Only
+ * plain data (strings, the union-of-keys array, cell values already read
+ * off the bound object) ever leaves here, so nothing hostile escapes the
+ * guard.
+ */
+export function deriveTableShape(data, columnsOverride) {
+    const hasOverride = columnsOverride !== undefined && columnsOverride.length > 0;
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return { kind: 'empty' };
+        const first = data[0];
+        if (isPlainObject(first)) {
+            const columns = hasOverride
+                ? [...columnsOverride]
+                : unionKeysInFirstSeenOrder(data);
+            const rows = data.map((row) => isPlainObject(row)
+                ? columns.map((column) => readOwn(row, column))
+                : columns.map(() => undefined));
+            return { kind: 'objects', columns, rows };
+        }
+        if (Array.isArray(first)) {
+            const rows = data.map((row) => (Array.isArray(row) ? row : [row]));
+            return { kind: 'arrays', rows };
+        }
+        return { kind: 'primitives', rows: data.map((value) => [value]) };
+    }
+    if (isPlainObject(data)) {
+        const keys = hasOverride ? [...columnsOverride] : Object.keys(data);
+        const rows = keys.map((key) => [
+            key,
+            readOwn(data, key),
+        ]);
+        return { kind: 'keyvalue', rows };
+    }
+    return { kind: 'empty' };
+}

package/dist/text-align.d.ts

@@ -11,7 +11,7 @@
  * those components' contracts.
  *
  * This module carries values only: the closed value list and the schema
- * four contracts share. It says nothing about markup or classes; each
+ * five contracts share. It says nothing about markup or classes; each
  * renderer's own `layout.ts` maps a value to a class.
  */
 import type { AttributeSchema } from './contracts.js';
@@ -21,12 +21,12 @@ export declare const TEXT_ALIGN_PRESETS: readonly ["left", "center", "right"];
 export type TextAlignPreset = (typeof TEXT_ALIGN_PRESETS)[number];
 /**
  * The standard components that accept `text` (docs/spec.md §3). Listed here
- * so `./contracts.ts` builds all four from one source, and so a test can
+ * so `./contracts.ts` builds all five from one source, and so a test can
  * assert the set both renderers honor is exactly this one.
  */
-export declare const TEXT_ALIGN_COMPONENTS: readonly ["row", "cell", "card", "callout"];
+export declare const TEXT_ALIGN_COMPONENTS: readonly ["row", "cell", "card", "callout", "table"];
 /**
- * The shared `text` schema. Identical wording on all four components on
+ * The shared `text` schema. Identical wording on all five components on
  * purpose: the attribute means the same thing everywhere, and a reader who
  * learned it on `callout` should not have to re-read it on `card`. The
  * row-specific cascade is spelled out because it is the one place `text`

package/dist/text-align.js

@@ -2,7 +2,7 @@
 export const TEXT_ALIGN_PRESETS = ['left', 'center', 'right'];
 /**
  * The standard components that accept `text` (docs/spec.md §3). Listed here
- * so `./contracts.ts` builds all four from one source, and so a test can
+ * so `./contracts.ts` builds all five from one source, and so a test can
  * assert the set both renderers honor is exactly this one.
  */
 export const TEXT_ALIGN_COMPONENTS = [
@@ -10,9 +10,10 @@ export const TEXT_ALIGN_COMPONENTS = [
     'cell',
     'card',
     'callout',
+    'table',
 ];
 /**
- * The shared `text` schema. Identical wording on all four components on
+ * The shared `text` schema. Identical wording on all five components on
  * purpose: the attribute means the same thing everywhere, and a reader who
  * learned it on `callout` should not have to re-read it on `card`. The
  * row-specific cascade is spelled out because it is the one place `text`

package/dist/value-format.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The ONE shared value-formatting primitive for the `format`/`decimals`
+ * attributes (docs/format.md, docs/scripting.md's "Where values go"):
+ * `:value[...]`, `::stat`, `::progress`, and `::table` all display a stored
+ * or attribute value through `formatValue`, so a number, date, or
+ * percentage reads identically no matter which component or which engine
+ * (`@markii/react`, `@markii/html`) rendered it.
+ *
+ * Zero dependency beyond the platform's own `Intl` — no third-party
+ * date/number library, matching this package's neutral, framework-free
+ * posture. Every branch is defensive: a hostile bound value (a throwing
+ * getter, a revoked `Proxy`, a `Symbol`, `NaN`, `±Infinity`, a huge number,
+ * negative zero) degrades to the plain stringified value rather than
+ * throwing, and an unrecognized `format` name behaves exactly like `plain`.
+ *
+ * Locale is pinned to `'en-US'` rather than left to the host environment:
+ * grouping separators, date wording, and the "3 hours ago" phrasing must
+ * read the same in a Node test runner, a browser preview, and a
+ * statically-exported HTML file, and an unpinned locale would make
+ * `@markii/html`'s conformance fixtures depend on the machine running them.
+ */
+import type { AttributeSchema } from './contracts.js';
+/** The closed `format=` vocabulary. Any other string (including a typo or an author's guess) behaves as `'plain'`. */
+export type ValueFormat = 'plain' | 'number' | 'compact' | 'percent' | 'date' | 'relative';
+/**
+ * Whether `value` is something a numeric `format` would actually format —
+ * a `number` (any value, including `NaN`/`±Infinity`) or a numeric string.
+ * `::table`'s "`format`/`decimals` apply to numeric cells only" (docs/
+ * format.md) uses this to decide, per cell, whether to route through
+ * `formatValue` with the requested format or fall back to plain text.
+ */
+export declare function isNumericLike(value: unknown): boolean;
+/**
+ * Formats `value` for display, per the closed `format=` vocabulary
+ * (docs/format.md): `plain` (default, and the fallback for an unrecognized
+ * name) reproduces exactly what `:value[...]` has always rendered;
+ * `number`/`compact`/`percent` render a coerced numeric value (falling back
+ * to `plain` for non-numeric input) and accept `decimals` (an integer
+ * `0`-`6`, otherwise ignored in favor of the format's own default);
+ * `date`/`relative` parse an ISO 8601 string or epoch-millisecond input
+ * (number or numeric string) into a local date, `relative` phrasing it
+ * against `now` (defaulting to render time, `Date.now()`) rather than
+ * carrying a clock read into the render itself — a caller in a script
+ * context can pass a fixed `now` to keep a render pure.
+ *
+ * Never throws, for any `value` (including a hostile object, a throwing
+ * getter, a `Symbol`, `NaN`, `±Infinity`, a huge number, or negative zero)
+ * and any `format`/`decimals` string.
+ */
+export declare function formatValue(value: unknown, format?: string, decimals?: string, now?: number): string;
+/**
+ * The shared `format` schema, reused by every contract that renders a
+ * value through `formatValue` (`::stat`, `::progress`, `::table`). Wording
+ * is identical everywhere on purpose: an author who learned `format` on
+ * `stat` should not have to re-read it on `table`.
+ */
+export declare const FORMAT_ATTRIBUTE: AttributeSchema;
+/** The shared `decimals` schema, reused alongside `FORMAT_ATTRIBUTE`. */
+export declare const DECIMALS_ATTRIBUTE: AttributeSchema;

package/dist/value-format.js

@@ -0,0 +1,301 @@
+const VALUE_FORMATS = [
+    'plain',
+    'number',
+    'compact',
+    'percent',
+    'date',
+    'relative',
+];
+/** The one locale every `Intl` call in this module uses, so formatted output is identical across machines and CI runners. */
+const LOCALE = 'en-US';
+/** `decimals=` is accepted for these three formats only; `date`/`relative`/`plain` ignore it. */
+const DECIMAL_AWARE_FORMATS = new Set([
+    'number',
+    'compact',
+    'percent',
+]);
+/** The default `maximumFractionDigits` per decimal-aware format when `decimals=` is absent or invalid. */
+const DEFAULT_MAX_FRACTION_DIGITS = {
+    number: 3, // Intl.NumberFormat's own default for a plain decimal
+    compact: 1, // "2.3M" / "12.4k"
+    percent: 1, // "12.3%"
+};
+/** `decimals=` is clamped to this closed range; anything else is ignored (falls back to the format's own default). */
+const MIN_DECIMALS = 0;
+const MAX_DECIMALS = 6;
+function normalizeFormat(format) {
+    if (format === undefined)
+        return 'plain';
+    return VALUE_FORMATS.includes(format)
+        ? format
+        : 'plain';
+}
+/**
+ * Parses `decimals=` to an integer in `[0, 6]`, or `undefined` for anything
+ * else: absent, empty, negative, above 6, non-integer (`2.5`), or
+ * non-numeric text. An out-of-range or malformed value is ignored rather
+ * than clamped or rejected — the format's own default decides instead.
+ */
+function parseDecimals(decimals) {
+    if (decimals === undefined)
+        return undefined;
+    const trimmed = decimals.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed))
+        return undefined;
+    if (parsed < MIN_DECIMALS || parsed > MAX_DECIMALS)
+        return undefined;
+    return parsed;
+}
+/**
+ * `String(value)` for a value that may be actively hostile — a revoked
+ * `Proxy`, an object with a throwing `toString`/`Symbol.toPrimitive`, an
+ * `Object.create(null)` with no `toString` at all. Degrades to the empty
+ * string rather than throwing.
+ */
+function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The `format: 'plain'` behavior, and the fallback every other format uses
+ * for input it cannot make sense of (docs/format.md: "non-numeric input
+ * under a numeric format renders the plain stringified value, never an
+ * error"). Objects/arrays render as JSON; `null`/`undefined` render as the
+ * empty string. Never throws for any value.
+ */
+function plainStringify(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    try {
+        const json = JSON.stringify(value);
+        return json ?? '';
+    }
+    catch {
+        return safeString(value);
+    }
+}
+/**
+ * Coerces `value` to a number for a numeric format (`number`/`compact`/
+ * `percent`), or `undefined` when it isn't one — a boolean, `null`,
+ * `undefined`, an object/array, a `Symbol`, or a non-numeric string all
+ * return `undefined` here rather than a guessed number. A `number` typed
+ * value (including `NaN`/`±Infinity`) is returned as-is: `Intl.NumberFormat`
+ * renders those without throwing (`"NaN"`, `"∞"`), so there is nothing to
+ * guard against by rejecting them. Negative zero is normalized to `0`
+ * before it ever reaches `Intl`, since a stray `-0` in the middle of a
+ * document reads as a bug, not a value worth preserving.
+ */
+function coerceNumericInput(value) {
+    if (typeof value === 'number')
+        return Object.is(value, -0) ? 0 : value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return undefined;
+        const parsed = Number(trimmed);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+/**
+ * Whether `value` is something a numeric `format` would actually format —
+ * a `number` (any value, including `NaN`/`±Infinity`) or a numeric string.
+ * `::table`'s "`format`/`decimals` apply to numeric cells only" (docs/
+ * format.md) uses this to decide, per cell, whether to route through
+ * `formatValue` with the requested format or fall back to plain text.
+ */
+export function isNumericLike(value) {
+    return coerceNumericInput(value) !== undefined;
+}
+/**
+ * Parses `value` into a `Date` for `date`/`relative`, accepting an ISO 8601
+ * string, a numeric string of epoch milliseconds, or a `number` of epoch
+ * milliseconds — exactly the two input shapes docs/format.md promises.
+ * Returns `undefined` for anything else, or for text/numbers that parse to
+ * an invalid date (`NaN`, `±Infinity`, out-of-range milliseconds, garbage
+ * text): the `Date` constructor never throws for these, it just produces an
+ * "Invalid Date", so the `isNaN` check is what turns that into "not a date"
+ * for this module's purposes.
+ */
+function parseDateInput(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return undefined;
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return undefined;
+        const asEpoch = /^-?\d+$/.test(trimmed) ? Number(trimmed) : undefined;
+        const date = new Date(asEpoch ?? trimmed);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    return undefined;
+}
+/**
+ * `Intl.NumberFormat`'s compact notation renders the thousands magnitude as
+ * `"12K"` (uppercase); docs/format.md's example is lowercase (`"12.4k"`),
+ * following the common "k for thousand, M/B/T for the rest" convention. The
+ * uppercase `K` is the only magnitude suffix `Intl` renders that way for
+ * `en-US` (millions/billions/trillions are already `M`/`B`/`T`), so a single
+ * trailing-letter replacement is enough — never a broader case-fold, which
+ * would also mangle a negative sign or digits.
+ */
+function lowercaseThousandsSuffix(formatted) {
+    return formatted.endsWith('K') ? `${formatted.slice(0, -1)}k` : formatted;
+}
+/** Buckets a millisecond duration into the coarsest unit `Intl.RelativeTimeFormat` should phrase it in, rounding to the nearest whole unit. */
+function relativeParts(diffMs) {
+    const seconds = diffMs / 1000;
+    if (Math.abs(seconds) < 60)
+        return { value: Math.round(seconds), unit: 'second' };
+    const minutes = seconds / 60;
+    if (Math.abs(minutes) < 60)
+        return { value: Math.round(minutes), unit: 'minute' };
+    const hours = minutes / 60;
+    if (Math.abs(hours) < 24)
+        return { value: Math.round(hours), unit: 'hour' };
+    const days = hours / 24;
+    if (Math.abs(days) < 30)
+        return { value: Math.round(days), unit: 'day' };
+    const months = days / 30;
+    if (Math.abs(months) < 12)
+        return { value: Math.round(months), unit: 'month' };
+    const years = days / 365;
+    return { value: Math.round(years), unit: 'year' };
+}
+function formatNumeric(format, value, decimals) {
+    const num = coerceNumericInput(value);
+    if (num === undefined)
+        return plainStringify(value);
+    const maxFractionDigits = decimals ?? DEFAULT_MAX_FRACTION_DIGITS[format];
+    try {
+        if (format === 'number') {
+            return new Intl.NumberFormat(LOCALE, {
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: maxFractionDigits,
+            }).format(num);
+        }
+        if (format === 'compact') {
+            const formatted = new Intl.NumberFormat(LOCALE, {
+                notation: 'compact',
+                minimumFractionDigits: decimals,
+                maximumFractionDigits: maxFractionDigits,
+            }).format(num);
+            return lowercaseThousandsSuffix(formatted);
+        }
+        return new Intl.NumberFormat(LOCALE, {
+            style: 'percent',
+            minimumFractionDigits: decimals,
+            maximumFractionDigits: maxFractionDigits,
+        }).format(num);
+    }
+    catch {
+        // `Intl.NumberFormat` does not throw for any finite/NaN/Infinity number
+        // with these options, but this is not the place to bet a "never
+        // throws" contract on that: any failure here still degrades cleanly.
+        return plainStringify(value);
+    }
+}
+function formatDate(value) {
+    const date = parseDateInput(value);
+    if (!date)
+        return plainStringify(value);
+    try {
+        return new Intl.DateTimeFormat(LOCALE, { dateStyle: 'medium' }).format(date);
+    }
+    catch {
+        return plainStringify(value);
+    }
+}
+function formatRelative(value, now) {
+    const date = parseDateInput(value);
+    if (!date)
+        return plainStringify(value);
+    try {
+        const { value: amount, unit } = relativeParts(date.getTime() - now);
+        return new Intl.RelativeTimeFormat(LOCALE, { numeric: 'auto' }).format(amount, unit);
+    }
+    catch {
+        return plainStringify(value);
+    }
+}
+/**
+ * Formats `value` for display, per the closed `format=` vocabulary
+ * (docs/format.md): `plain` (default, and the fallback for an unrecognized
+ * name) reproduces exactly what `:value[...]` has always rendered;
+ * `number`/`compact`/`percent` render a coerced numeric value (falling back
+ * to `plain` for non-numeric input) and accept `decimals` (an integer
+ * `0`-`6`, otherwise ignored in favor of the format's own default);
+ * `date`/`relative` parse an ISO 8601 string or epoch-millisecond input
+ * (number or numeric string) into a local date, `relative` phrasing it
+ * against `now` (defaulting to render time, `Date.now()`) rather than
+ * carrying a clock read into the render itself — a caller in a script
+ * context can pass a fixed `now` to keep a render pure.
+ *
+ * Never throws, for any `value` (including a hostile object, a throwing
+ * getter, a `Symbol`, `NaN`, `±Infinity`, a huge number, or negative zero)
+ * and any `format`/`decimals` string.
+ */
+export function formatValue(value, format, decimals, now = Date.now()) {
+    const effectiveFormat = normalizeFormat(format);
+    if (effectiveFormat === 'plain')
+        return plainStringify(value);
+    const parsedDecimals = DECIMAL_AWARE_FORMATS.has(effectiveFormat)
+        ? parseDecimals(decimals)
+        : undefined;
+    switch (effectiveFormat) {
+        case 'number':
+        case 'compact':
+        case 'percent':
+            return formatNumeric(effectiveFormat, value, parsedDecimals);
+        case 'date':
+            return formatDate(value);
+        case 'relative':
+            return formatRelative(value, now);
+        /* istanbul ignore next -- exhaustiveness guard; normalizeFormat never returns anything else here */
+        default:
+            return plainStringify(value);
+    }
+}
+/**
+ * The shared `format` schema, reused by every contract that renders a
+ * value through `formatValue` (`::stat`, `::progress`, `::table`). Wording
+ * is identical everywhere on purpose: an author who learned `format` on
+ * `stat` should not have to re-read it on `table`.
+ */
+export const FORMAT_ATTRIBUTE = {
+    type: 'string',
+    required: false,
+    enum: VALUE_FORMATS,
+    description: 'Formats the displayed value: `plain` (default), `number` (grouped ' +
+        'thousands), `compact` (`2.3M`, `12.4k`), `percent` (`0.123` -> ' +
+        '`12.3%`), `date` (an ISO 8601 string or epoch milliseconds -> a local ' +
+        'date), or `relative` (`3 hours ago`, computed against render time). ' +
+        'Non-numeric input under a numeric format, or non-date input under ' +
+        '`date`/`relative`, renders the plain value instead of an error; an ' +
+        'unrecognized name behaves as `plain`.',
+};
+/** The shared `decimals` schema, reused alongside `FORMAT_ATTRIBUTE`. */
+export const DECIMALS_ATTRIBUTE = {
+    type: 'string',
+    required: false,
+    description: 'Number of decimal places for the `number`, `compact`, and `percent` ' +
+        'formats, as an integer `0`-`6`. Ignored for `date`/`relative`/`plain`. ' +
+        "An out-of-range or non-integer value is ignored, and the format's own " +
+        'default decimal count is used instead.',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/stdlib",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Neutral, framework-agnostic standard component contracts for Mark (.mk.md) — the kind/attribute-schema seam every renderer (e.g. @markii/react) implements against. No React, zero dependencies.",
   "keywords": [
     "markdown",