@lerianstudio/sindarian-ui 1.2.0-beta.13 → 1.2.0-beta.14

package/dist/esm/domain/money-math.js

@@ -0,0 +1,98 @@
+/**
+ * money-math — exact integer-minor-unit arithmetic for the double-entry third rail.
+ *
+ * INTERNAL to the domain layer: nothing here is re-exported from
+ * `src/domain/index.ts`, so `toMinor`/`Amount`/`sumMinor` are NOT part of
+ * `@lerianstudio/sindarian-ui`'s public API. The consumers that need exact money
+ * arithmetic reach it through the components that own it (`moneyDiff`,
+ * `MoneyText`, `DelinquencyAging`).
+ *
+ * Amounts parse to integer minor units (BigInt) at a fixed scale; sums never
+ * round-trip through IEEE-754. Pass amounts as canonical decimal STRINGS for
+ * lossless math — numbers are converted via toFixed, which is float-bounded
+ * (fine for display-scale magnitudes, exact for strings).
+ */
+import { isValidDigitCount } from './format.js';
+// Round half-away-from-zero on the first dropped fraction digit.
+function roundsUp(fraction, scale) {
+    return fraction.length > scale && fraction.charCodeAt(scale) - 48 >= 5;
+}
+/** Normalize to a canonical signed decimal: trim, unicode-minus, accounting parens. */
+function canonical(raw) {
+    let s = raw.trim().replace(/−/g, '-');
+    if (/^\(.*\)$/.test(s))
+        s = '-' + s.slice(1, -1).trim(); // (1.23) -> -1.23
+    return s;
+}
+/**
+ * Amount -> integer minor units at `scale`, or null if unparseable.
+ *
+ * `scale` is validated before it reaches `toFixed`/`repeat`: an out-of-range
+ * scale (a caller passing `minorDigits: -1`) would throw a RangeError mid-render
+ * rather than degrade. It is the single choke point every money path in this
+ * layer routes through (`sumMinor`, `moneyDiff`, `delinquencyRate`,
+ * `sumBucketTotals`), so guarding it here guards all of them.
+ */
+export function toMinor(value, scale) {
+    if (!isValidDigitCount(scale))
+        return null;
+    if (value === null || value === undefined || value === '')
+        return null;
+    let s = typeof value === 'number'
+        ? Number.isFinite(value)
+            ? value.toFixed(scale)
+            : ''
+        : canonical(value);
+    if (s === '' || s === '-' || s === '.' || !/^-?\d*(\.\d*)?$/.test(s))
+        return null;
+    const neg = s.startsWith('-');
+    if (neg)
+        s = s.slice(1);
+    const [intPart = '', fracPart = ''] = s.split('.');
+    // DELIBERATE DIVERGENCE from sindarian-x@0.15.0: the legacy regex admits a
+    // digitless token ('-.', and '.' once the sign is stripped) and coerced it to
+    // an exact 0n. A fabricated exact zero is the worst possible answer in
+    // reconciliation — it reads as a perfect tie and hides the bad input — so a
+    // digitless amount is now indeterminate (null), like every other garbage
+    // token. This mirrors the guard the legacy `rateFraction` already had.
+    if (intPart === '' && fracPart === '')
+        return null;
+    const frac = (fracPart + '0'.repeat(scale)).slice(0, scale);
+    let minor = BigInt((intPart || '0') + frac);
+    if (roundsUp(fracPart, scale))
+        minor += 1n;
+    return neg ? -minor : minor;
+}
+/** Sum amounts to minor units; null if ANY operand is unparseable (indeterminate). */
+export function sumMinor(values, scale) {
+    let total = 0n;
+    for (const v of values) {
+        const m = toMinor(v, scale);
+        if (m === null)
+            return null;
+        total += m;
+    }
+    return total;
+}
+/** Currency's minor-unit digit count via CLDR (BRL/USD->2, JPY->0, BHD->3), or fallback. */
+export function minorDigitsOf(currency, fallback = 2) {
+    try {
+        const opts = new Intl.NumberFormat('en', {
+            style: 'currency',
+            currency,
+            currencyDisplay: 'code'
+        }).resolvedOptions();
+        return opts.maximumFractionDigits ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Minor units -> canonical decimal string (lossless), for handing to MoneyText. */
+export function minorToDecimal(minor, scale) {
+    const neg = minor < 0n;
+    const abs = (neg ? -minor : minor).toString().padStart(scale + 1, '0');
+    const intPart = abs.slice(0, abs.length - scale) || '0';
+    const fracPart = scale > 0 ? '.' + abs.slice(abs.length - scale) : '';
+    return (neg ? '-' : '') + intPart + fracPart;
+}

package/dist/esm/domain/money-text/index.d.ts

@@ -0,0 +1,37 @@
+export type MoneyTextProps = {
+    amount: string | number | null | undefined;
+    /** ISO 4217 currency code, e.g. "BRL", "USD". */
+    currency?: string | null;
+    /** Number of fraction digits. Defaults to 2. */
+    fractionDigits?: number;
+    /** Hide the trailing currency code. */
+    hideCurrency?: boolean;
+    /** Color negative values red. Defaults to true. */
+    signColor?: boolean;
+    /** BCP 47 locale for grouping/decimal marks. Defaults to the runtime locale. */
+    locale?: string;
+    className?: string;
+};
+/**
+ * Normalize a raw amount into a string the Intl formatter accepts while
+ * preserving precision: trim, convert the unicode minus U+2212 to ASCII '-',
+ * and rewrite accounting parens `(123.45)` → `-123.45`. Returns null when the
+ * input is empty after trimming (→ NO_VALUE upstream).
+ *
+ * Internal: exported for its unit tests, never from `src/domain/index.ts`.
+ */
+export declare function normalizeAmount(amount: string | number): string | null;
+/**
+ * Pure money formatting: normalize the amount, format it via Intl (preserving
+ * precision through the ES2020 string overload), and derive sign + finiteness
+ * from the formatted parts — so color and glyph can never disagree. Returns
+ * null for empty, non-finite, or unparseable input (→ NO_VALUE upstream).
+ *
+ * Internal: exported for its unit tests, never from `src/domain/index.ts`.
+ */
+export declare function formatMoneyParts(amount: string | number, fractionDigits: number, locale?: string): {
+    formatted: string;
+    negative: boolean;
+} | null;
+export declare function MoneyText({ amount, currency, fractionDigits, hideCurrency, signColor, locale, className }: MoneyTextProps): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/domain/money-text/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/domain/money-text/index.tsx"],"names":[],"mappings":"AAwBA,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAOtE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA+CjD;AAED,wBAAgB,SAAS,CAAC,EACxB,MAAM,EACN,QAAQ,EACR,cAAkB,EAClB,YAAoB,EACpB,SAAgB,EAChB,MAAM,EACN,SAAS,EACV,EAAE,cAAc,+BA8BhB"}

package/dist/esm/domain/money-text/index.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * MoneyText renders a monetary amount with optional ISO currency code,
+ * tabular figures so columns line up. The amount is formatted losslessly: when
+ * passed as a string, `Intl.NumberFormat.format()` (ES2020+) parses it as an
+ * arbitrary-precision value and rounds to `fractionDigits` without ever
+ * round-tripping through an IEEE-754 double — so 16+ significant-digit tokens
+ * keep every digit. Pass the raw decimal string (not a pre-coerced Number) to
+ * preserve that guarantee.
+ *
+ * The currency code is shown as a suffix rather than a symbol so mixed-currency
+ * ledgers stay unambiguous. Negative amounts get the destructive color;
+ * null/undefined/empty render the muted no-value placeholder.
+ *
+ * SIGN COLOR IS NOT THE CREDIT ROLE. `--destructive` marks a negative/alarm
+ * amount; `--credit` is the accounting reading of a credit amount. They are two
+ * roles, and a consumer layers the credit role on top (matcher's fork passes
+ * `signColor={false}` with `tone="credit"` precisely so the two never fight).
+ * Collapsing the sign color into `text-credit` would erase that distinction —
+ * this class stays `text-destructive`, as in sindarian-x@0.15.0.
+ */
+import { cn } from '../../lib/utils.js';
+import { NO_VALUE, isValidDigitCount } from '../format.js';
+/**
+ * Normalize a raw amount into a string the Intl formatter accepts while
+ * preserving precision: trim, convert the unicode minus U+2212 to ASCII '-',
+ * and rewrite accounting parens `(123.45)` → `-123.45`. Returns null when the
+ * input is empty after trimming (→ NO_VALUE upstream).
+ *
+ * Internal: exported for its unit tests, never from `src/domain/index.ts`.
+ */
+export function normalizeAmount(amount) {
+    let s = String(amount).trim();
+    if (s === '')
+        return null;
+    s = s.replace(/−/g, '-');
+    const parens = s.match(/^\((.*)\)$/);
+    if (parens)
+        s = `-${parens[1].trim()}`;
+    return s;
+}
+/**
+ * Pure money formatting: normalize the amount, format it via Intl (preserving
+ * precision through the ES2020 string overload), and derive sign + finiteness
+ * from the formatted parts — so color and glyph can never disagree. Returns
+ * null for empty, non-finite, or unparseable input (→ NO_VALUE upstream).
+ *
+ * Internal: exported for its unit tests, never from `src/domain/index.ts`.
+ */
+export function formatMoneyParts(amount, fractionDigits, locale) {
+    // Reject non-finite numeric inputs (NaN / ±Infinity) before they reach Intl,
+    // which would otherwise render literal "NaN" / "∞".
+    if (typeof amount === 'number' && !Number.isFinite(amount))
+        return null;
+    // A caller-supplied digit count reaches Intl directly; an out-of-range one
+    // would throw a RangeError and blank the amount instead of degrading to
+    // NO_VALUE.
+    if (!isValidDigitCount(fractionDigits))
+        return null;
+    const normalized = normalizeAmount(amount);
+    if (normalized === null)
+        return null;
+    // DELIBERATE DIVERGENCE from sindarian-x@0.15.0: an exact zero written with a
+    // sign ('-0', '-0.00', '(0)') formatted as "-0.00" and reported negative:true,
+    // which painted a zero balance in the destructive sign color. Zero is neither
+    // positive nor negative — a signed-zero ledger cell is a rendering artifact of
+    // the input notation, never a fact about the money. The sign is dropped for an
+    // EXACT zero only; '-0.004' still rounds to "-0.00" and stays negative,
+    // because that one really is below zero.
+    const exactZero = /\d/.test(normalized) && /^-?0*(\.0*)?$/.test(normalized);
+    const forFormat = exactZero ? normalized.replace(/^-/, '') : normalized;
+    const formatter = new Intl.NumberFormat(locale, {
+        minimumFractionDigits: fractionDigits,
+        maximumFractionDigits: fractionDigits,
+        signDisplay: 'auto'
+    });
+    // The bundled lib types only model a `number | bigint` overload; the ES2020
+    // string overload (which preserves precision) is unmodelled, so the
+    // normalized amount is cast at the boundary.
+    //
+    // RUNTIME FLOOR: this relies on a V8 with exact decimal-STRING Intl support
+    // (Node >= 20, evergreen browsers) — the whole point is that a 20-digit amount
+    // never round-trips through an IEEE-754 double. There is deliberately NO
+    // Number-coercion fallback for older runtimes: that fallback would silently
+    // reintroduce the precision loss this function exists to prevent.
+    const parts = formatter.formatToParts(forFormat);
+    // Intl emits a literal "nan"/"∞" part for non-finite values; treat those as
+    // no-value rather than rendering them.
+    if (parts.some((p) => p.type === 'nan' || p.type === 'infinity'))
+        return null;
+    return {
+        formatted: parts.map((p) => p.value).join(''),
+        negative: parts.some((p) => p.type === 'minusSign')
+    };
+}
+export function MoneyText({ amount, currency, fractionDigits = 2, hideCurrency = false, signColor = true, locale, className }) {
+    const noValue = (_jsx("span", { className: cn('text-muted-foreground tabular-nums', className), children: NO_VALUE }));
+    if (amount === null || amount === undefined || amount === '')
+        return noValue;
+    // Sign and finiteness are derived from the formatted parts, not a raw string
+    // prefix — so color and glyph can never disagree, and "-0" / "(0)" are
+    // treated as the non-negative zero Intl renders.
+    const result = formatMoneyParts(amount, fractionDigits, locale);
+    if (result === null)
+        return noValue;
+    const { formatted, negative } = result;
+    return (_jsxs("span", { className: cn('tabular-nums', signColor && negative && 'text-destructive', className), children: [formatted, !hideCurrency && currency ? (_jsx("span", { className: "text-muted-foreground ml-1 text-xs", children: currency })) : null] }));
+}

package/dist/esm/domain/section-label/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SectionLabel — THE canonical uppercase tracked sans label of the console.
+ *
+ * Every panel heading, section title, and caption is uppercase, tracked
+ * (0.08em) muted-foreground — the recessive foil that lets the mono figures be
+ * loud. The class itself lives in `@/lib/typography` (`SECTION_LABEL_CLASS`,
+ * an alias of `LABEL_VOICE_CLASS`) and is NEVER re-stated here, so the voice
+ * cannot drift between this component and the `ui/` layer that shares it.
+ *
+ * Renders an `<h2>` by default (the ledger-sheet cell heading), but `as` lets
+ * it become a `<p>`/`<span>`/`<dt>` for captions and inline labels.
+ */
+import type { ElementType, ReactNode } from 'react';
+export type SectionLabelProps = {
+    children: ReactNode;
+    className?: string;
+    /** Render element. Defaults to `h2` (the ledger-sheet cell heading). */
+    as?: ElementType;
+};
+export declare function SectionLabel({ children, className, as: Tag }: SectionLabelProps): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/domain/section-label/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/domain/section-label/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,EAAE,CAAC,EAAE,WAAW,CAAA;CACjB,CAAA;AAED,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,SAAS,EACT,EAAE,EAAE,GAAU,EACf,EAAE,iBAAiB,+BAEnB"}

package/dist/esm/domain/section-label/index.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SECTION_LABEL_CLASS } from '../../lib/typography.js';
+import { cn } from '../../lib/utils.js';
+export function SectionLabel({ children, className, as: Tag = 'h2' }) {
+    return _jsx(Tag, { className: cn(SECTION_LABEL_CLASS, className), children: children });
+}

package/dist/esm/domain/status-rail/index.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+export type StatusRailItem = {
+    /** Optional stable key for dynamic (reordered/filtered) rails; falls back to index. */
+    id?: string;
+    /** Optional uppercase label rendered inline before the value. */
+    label?: ReactNode;
+    value: ReactNode;
+};
+export type StatusRailChip = {
+    /** Optional stable key for dynamic (reordered/filtered) rails; falls back to index. */
+    id?: string;
+    label: ReactNode;
+    value: ReactNode;
+    /** Escalate the chip to destructive styling when a count is in alarm. */
+    alarm?: boolean;
+};
+export type StatusRailProps = {
+    /** Foreground identity token, rendered first (e.g. context name). */
+    lead?: ReactNode;
+    /** Dot-separated mono tape items. */
+    items?: StatusRailItem[];
+    /** Right-pinned count chips. */
+    chips?: StatusRailChip[];
+    className?: string;
+};
+export declare function StatusRail({ lead, items, chips, className }: StatusRailProps): import("react").JSX.Element;
+/** Decorative dot separator — muted, so the tape reads as punctuated, not broken. */
+export declare function Dot(): import("react").JSX.Element;
+/**
+ * The live auto-refresh pulse: a success dot with a reduced-motion-gated ping
+ * ring. Place it inside a tape item value, e.g. `<><LivePulse /> Live</>`.
+ *
+ * The ring rides Tailwind's built-in `ping` keyframe under the `motion-safe:`
+ * variant (`@media (prefers-reduced-motion: no-preference)`), so a
+ * reduced-motion reader sees only the static dot — same gating as the
+ * hand-rolled `status-rail-pulse` keyframe it replaces, with no stylesheet of
+ * its own.
+ */
+export declare function LivePulse(): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/domain/status-rail/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/domain/status-rail/index.tsx"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,MAAM,cAAc,GAAG;IAC3B,uFAAuF;IACvF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,uFAAuF;IACvF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,SAAS,CAAA;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,qCAAqC;IACrC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,gCAAgC;IAChC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAU,EACV,KAAU,EACV,SAAS,EACV,EAAE,eAAe,+BA+DjB;AAkBD,qFAAqF;AACrF,wBAAgB,GAAG,gCAMlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,gCAOxB"}

package/dist/esm/domain/status-rail/index.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * StatusRail — Row 0 of every console screen. A thin, full-width recessed strip
+ * that reads "the terminal is live": a dot-separated mono tape on the recessed
+ * page surface (`bg-body-surface`), with optional right-pinned count chips.
+ *
+ *   <StatusRail
+ *     lead={contextName}
+ *     items={[
+ *       { value: '90d' },
+ *       { label: 'Updated', value: '12:04 UTC' },
+ *       { value: <><LivePulse /> Live</> }
+ *     ]}
+ *     chips={[
+ *       { label: 'Open', value: '12' },
+ *       { label: 'Pending overdue', value: '3', alarm: true }
+ *     ]}
+ *   />
+ *
+ * The first token (`lead`) is `text-foreground font-medium`. Tape items are
+ * dot-separated; an item with a `label` renders the uppercase label inline
+ * before its value. Chips pin right via `ml-auto`; `alarm` escalates a chip to
+ * destructive.
+ */
+import { TriangleAlert } from 'lucide-react';
+import { cn } from '../../lib/utils.js';
+export function StatusRail({ lead, items = [], chips = [], className }) {
+    return (_jsxs("div", { className: cn(
+        // Recessed instrument strip: the page surface inside a hairline border
+        // whose top edge runs one step darker — light-from-above recession
+        // without any inner shadow.
+        'border-border border-t-foreground/10 bg-body-surface text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-1.5 rounded-lg border px-4 py-2 font-mono text-xs tabular-nums', className), children: [lead !== undefined && lead !== null ? (_jsx("span", { className: "text-foreground font-medium", children: lead })) : null, items.map((item, i) => (_jsx(RailFragment, { hasLead: lead != null || i > 0, children: item.label != null ? (_jsxs("span", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "tracking-[0.08em] uppercase", children: item.label }), item.value] })) : (_jsx("span", { className: "flex items-center gap-1.5", children: item.value })) }, item.id ?? i))), chips.length ? (_jsx("span", { className: "ml-auto flex flex-wrap items-center gap-x-3 gap-y-1.5", children: chips.map((chip, i) => (_jsxs("span", { className: "inline-flex items-center gap-1.5", children: [_jsx("span", { className: "tracking-[0.08em] uppercase", children: chip.label }), _jsxs("span", { className: cn(
+                            // Tiny mono token: raised a hair off the sunken tape by the
+                            // card surface + whisper shadow.
+                            'inline-flex items-center gap-1 rounded-sm border px-1.5 py-0.5 shadow-sm', chip.alarm
+                                ? 'border-destructive/40 bg-destructive/10 text-destructive'
+                                : 'border-border bg-card text-foreground'), children: [chip.alarm ? (_jsxs(_Fragment, { children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3" }), _jsx("span", { className: "sr-only", children: "(alarme)" })] })) : null, chip.value] })] }, chip.id ?? i))) })) : null] }));
+}
+/** A tape item preceded by a separator dot when it is not the first token. */
+function RailFragment({ children, hasLead }) {
+    return (_jsxs(_Fragment, { children: [hasLead ? _jsx(Dot, {}) : null, children] }));
+}
+/** Decorative dot separator — muted, so the tape reads as punctuated, not broken. */
+export function Dot() {
+    return (_jsx("span", { "aria-hidden": true, className: "text-muted-foreground/50", children: "\u00B7" }));
+}
+/**
+ * The live auto-refresh pulse: a success dot with a reduced-motion-gated ping
+ * ring. Place it inside a tape item value, e.g. `<><LivePulse /> Live</>`.
+ *
+ * The ring rides Tailwind's built-in `ping` keyframe under the `motion-safe:`
+ * variant (`@media (prefers-reduced-motion: no-preference)`), so a
+ * reduced-motion reader sees only the static dot — same gating as the
+ * hand-rolled `status-rail-pulse` keyframe it replaces, with no stylesheet of
+ * its own.
+ */
+export function LivePulse() {
+    return (_jsxs("span", { className: "relative flex size-2", "aria-hidden": true, children: [_jsx("span", { className: "bg-system-success/60 absolute inline-flex size-2 rounded-full motion-safe:animate-ping" }), _jsx("span", { className: "bg-system-success relative inline-flex size-2 rounded-full" })] }));
+}

package/dist/esm/domain/threshold-gauge/index.d.ts

@@ -0,0 +1,84 @@
+export type GaugeBand = 'low' | 'warn' | 'breach';
+/** higher-is-worse: value climbs into danger (warn < breach) — utilization.
+ *  lower-is-worse: value falls into danger (breach < warn) — coverage ratio. */
+export type GaugeDirection = 'higher-is-worse' | 'lower-is-worse';
+/** How the numeric readout is formatted. 'ratio' is a 0..1 share shown as a
+ *  percent; 'percent' is an already-scaled 0..100; 'count' a plain integer;
+ *  'money' an ISO-4217 amount via MoneyText. */
+export type GaugeFormat = 'percent' | 'ratio' | 'count' | 'money';
+/** Whether a value sitting exactly ON a threshold escalates.
+ *  'strict' (default) — it stays in the calmer band; escalation needs the value
+ *  strictly past the edge. 'inclusive' — being ON the edge already escalates,
+ *  for consumers whose enforcement is inclusive (a quota that blocks at
+ *  `used >= limit`: a tenant exactly at the cap is already blocked). */
+export type GaugeEdges = 'strict' | 'inclusive';
+export interface GaugeThresholds {
+    /** The warn edge — crossing it escalates low → warn. */
+    warn: number;
+    /** The breach edge — crossing it escalates to breach. */
+    breach: number;
+    /** Whether a value exactly ON a threshold escalates. Defaults to 'strict'. */
+    edges?: GaugeEdges;
+}
+export interface ThresholdGaugeProps {
+    /** The observed value, in the same unit as `min`/`max`/`warn`/`breach`. It
+     *  drives the band, the track fill and every ARIA attribute. */
+    value: number;
+    /** The figure to PRINT, when it differs from `value`. A consumer that must
+     *  keep `aria-valuenow` inside [min, max] has to clamp `value` — pass the true
+     *  (unclamped) figure here so the readout does not contradict the number the
+     *  consumer renders beside the gauge. Band and ARIA still follow `value`.
+     *  Omitted → the readout formats `value`. */
+    displayValue?: number;
+    /** Bottom of the track. Defaults to 0. */
+    min?: number;
+    /** Top of the track. */
+    max: number;
+    /** Warn edge (see `GaugeThresholds`). */
+    warn: number;
+    /** Breach edge (see `GaugeThresholds`). */
+    breach: number;
+    /** On-edge behaviour (see `GaugeEdges`). Defaults to 'strict'. */
+    edges?: GaugeEdges;
+    /** Which way is danger — mandatory, the numbers alone do not say. */
+    direction: GaugeDirection;
+    /** Numeric readout format. Defaults to 'percent'. */
+    format?: GaugeFormat;
+    /** ISO 4217 code for `format='money'`, e.g. "BRL". */
+    currency?: string;
+    /** BCP 47 locale for figure grouping/decimal marks. */
+    locale?: string;
+    /** Quiet caption above the gauge (e.g. "Utilização do limite"). */
+    label?: string;
+    /** Accessible name for the meter when no visible `label` is rendered, or when
+     *  the meter needs a fuller name than the caption. A meter with no name is
+     *  announced as a bare number, so this resolves `ariaLabel ?? label ?? the
+     *  band word`, which is never empty. Additive — existing call sites that pass
+     *  only `label` are unaffected. */
+    ariaLabel?: string;
+    /** Override the accessible band word, per band, in the consumer's own locale.
+     *  Shallow-merged over the pt-BR defaults, so `{ breach: 'Limit exceeded' }`
+     *  leaves low/warn untouched. The band word is the ONLY non-chromatic carrier
+     *  of the band (the glyph and the tint are decorative), so a consumer serving
+     *  en/es MUST be able to translate it — see WCAG 1.4.1 note above. */
+    bandLabels?: Partial<Record<GaugeBand, string>>;
+    className?: string;
+}
+/**
+ * Resolve which band a value occupies. Pure — the testable heart of the atom.
+ *
+ * STRICT edges by default: a value exactly ON a threshold stays in the CALMER
+ * band; escalation needs the value strictly past.
+ *
+ *  - higher-is-worse: `value > breach` → breach; `value > warn` → warn; else low.
+ *  - lower-is-worse:  `value < breach` → breach; `value < warn` → warn; else low.
+ *
+ * `thresholds.edges = 'inclusive'` opts into `>=` / `<=` instead, for a consumer
+ * whose enforcement is inclusive. Omitted or 'strict' → the behaviour above.
+ *
+ * Non-finite input degrades to 'low' rather than throwing — a missing reading is
+ * not, by itself, an alarm.
+ */
+export declare function gaugeBand(value: number, thresholds: GaugeThresholds, direction: GaugeDirection): GaugeBand;
+export declare function ThresholdGauge({ value, displayValue, min, max, warn, breach, edges, direction, format, currency, locale, label, ariaLabel, bandLabels, className }: ThresholdGaugeProps): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/domain/threshold-gauge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/domain/threshold-gauge/index.tsx"],"names":[],"mappings":"AAiDA,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEjD;gFACgF;AAChF,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;AAEjE;;gDAEgD;AAChD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;AAEjE;;;;wEAIwE;AACxE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/C,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC;oEACgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb;;;;iDAI6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,qEAAqE;IACrE,SAAS,EAAE,cAAc,CAAA;IACzB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;uCAImC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;0EAIsE;IACtE,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,eAAe,EAC3B,SAAS,EAAE,cAAc,GACxB,SAAS,CAUX;AA+CD,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,YAAY,EACZ,GAAO,EACP,GAAG,EACH,IAAI,EACJ,MAAM,EACN,KAAK,EACL,SAAS,EACT,MAAkB,EAClB,QAAQ,EACR,MAAM,EACN,KAAK,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACV,EAAE,mBAAmB,+BAyErB"}

package/dist/esm/domain/threshold-gauge/index.js

@@ -0,0 +1,153 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ThresholdGauge — where a value sits across ordered, NAMED bands.
+ *
+ * A metric is rarely interesting in isolation; what matters is which band it has
+ * crossed. A credit utilization of 95% is a breach; a liquidity coverage ratio
+ * of 95% may be perfectly calm. So a gauge that paints a smooth red→green
+ * gradient is lying by implication — it suggests a continuum where the business
+ * has hard thresholds. This atom STATES the thresholds: it resolves the current
+ * band (low / warn / breach), names it with a glyph + an sr-only word + a tint,
+ * and marks the band edges on the bar so the reader sees the line the value
+ * crossed, not a vibe.
+ *
+ *   <ThresholdGauge value={0.92} max={1} warn={0.8} breach={0.9} format="percent"
+ *     direction="higher-is-worse" label="Utilização do limite" />   // breach
+ *   <ThresholdGauge value={1.18} max={2} warn={1} breach={0.9} format="ratio"
+ *     direction="lower-is-worse" label="Índice de cobertura" />      // low (calm)
+ *
+ * DIRECTION is mandatory because the same numbers mean opposite things:
+ *  - higher-is-worse: the value climbs INTO danger (warn < breach). Utilization,
+ *    concentration, error rate.
+ *  - lower-is-worse: the value FALLS into danger (breach < warn). Coverage,
+ *    liquidity, capital adequacy.
+ *
+ * INVARIANT (strict edges by DEFAULT): a band escalation requires the value to
+ * be STRICTLY beyond the edge. A value sitting exactly ON a threshold belongs to
+ * the calmer band, not the louder one — `gaugeBand` encodes this so an on-edge
+ * utilization of exactly the breach line still reads as warn, never a surprise
+ * breach. A consumer whose own enforcement is INCLUSIVE (a quota blocking at
+ * `used >= limit`) opts out with `edges="inclusive"`, which escalates ON the
+ * edge in both directions.
+ *
+ * The current band is the load-bearing signal and it never rides on color alone
+ * (WCAG 1.4.1): a glyph leads, an sr-only word names it, the tint only
+ * reinforces. The numeric position reads via a mono `Figure`, never inferred
+ * from the bar geometry — and a consumer forced to clamp `value` to keep
+ * `aria-valuenow` in range can still print the true figure via `displayValue`.
+ *
+ * Pure display: server-safe, no directive.
+ */
+import { OctagonX, ShieldCheck, TriangleAlert } from 'lucide-react';
+import { LABEL_VOICE_CLASS } from '../../lib/typography.js';
+import { cn } from '../../lib/utils.js';
+import { Figure } from '../figure/index.js';
+import { formatCount, formatPercent, NO_VALUE } from '../format.js';
+import { MoneyText } from '../money-text/index.js';
+/** Band → glyph + tint + accessible word. The glyph and sr-only word are the
+ *  load-bearing cue; the tint only reinforces, so the band survives grayscale
+ *  and color-vision deficiency. The words are pt-BR defaults — a consumer in
+ *  another locale overrides them via the `bandLabels` prop. */
+const BAND = {
+    low: {
+        Icon: ShieldCheck,
+        tint: 'text-system-success',
+        word: 'Dentro do limite'
+    },
+    warn: {
+        Icon: TriangleAlert,
+        tint: 'text-system-alert',
+        word: 'Próximo do limite'
+    },
+    breach: {
+        Icon: OctagonX,
+        tint: 'text-destructive',
+        word: 'Limite ultrapassado'
+    }
+};
+/** Track fill tint per band — kept distinct from the glyph tint so the bar can
+ *  use the softer wash while the glyph carries the full tint. */
+const BAND_FILL = {
+    low: 'bg-system-success',
+    warn: 'bg-system-alert',
+    breach: 'bg-destructive'
+};
+/**
+ * Resolve which band a value occupies. Pure — the testable heart of the atom.
+ *
+ * STRICT edges by default: a value exactly ON a threshold stays in the CALMER
+ * band; escalation needs the value strictly past.
+ *
+ *  - higher-is-worse: `value > breach` → breach; `value > warn` → warn; else low.
+ *  - lower-is-worse:  `value < breach` → breach; `value < warn` → warn; else low.
+ *
+ * `thresholds.edges = 'inclusive'` opts into `>=` / `<=` instead, for a consumer
+ * whose enforcement is inclusive. Omitted or 'strict' → the behaviour above.
+ *
+ * Non-finite input degrades to 'low' rather than throwing — a missing reading is
+ * not, by itself, an alarm.
+ */
+export function gaugeBand(value, thresholds, direction) {
+    if (!Number.isFinite(value))
+        return 'low';
+    const { warn, breach, edges = 'strict' } = thresholds;
+    const beyond = direction === 'higher-is-worse'
+        ? (edge) => (edges === 'inclusive' ? value >= edge : value > edge)
+        : (edge) => (edges === 'inclusive' ? value <= edge : value < edge);
+    if (beyond(breach))
+        return 'breach';
+    if (beyond(warn))
+        return 'warn';
+    return 'low';
+}
+/**
+ * An empty or whitespace-only string is not a name. `??` only skips null and
+ * undefined, so `ariaLabel=""` or `bandLabels={{ breach: '' }}` won the fallback
+ * chain and produced an EMPTY accessible name — worse than the missing one it
+ * was meant to fix, because `aria-label=""` also suppresses the element's other
+ * naming routes. Normalizing to undefined lets the chain fall through properly.
+ */
+function nonEmpty(value) {
+    return value != null && value.trim() !== '' ? value : undefined;
+}
+/** Clamp a value into [min, max] then normalize to a 0..1 fraction of the
+ *  track. A zero-width track (max <= min) collapses to 0 rather than dividing by
+ *  zero. */
+function trackFraction(value, min, max) {
+    if (!Number.isFinite(value) || max <= min)
+        return 0;
+    const clamped = Math.max(min, Math.min(max, value));
+    return (clamped - min) / (max - min);
+}
+/** Format the value for the mono readout per `format`. Money routes through
+ *  MoneyText (never a hand-rolled string); the rest through the format helpers. */
+function readout(value, format, currency, locale) {
+    if (!Number.isFinite(value))
+        return NO_VALUE;
+    if (format === 'money') {
+        return (_jsx(MoneyText, { amount: value, currency: currency, signColor: false, locale: locale }));
+    }
+    if (format === 'percent')
+        return formatPercent(value, { unit: 'percent', locale });
+    if (format === 'ratio')
+        return formatPercent(value, { unit: 'ratio', locale });
+    return formatCount(value, locale);
+}
+export function ThresholdGauge({ value, displayValue, min = 0, max, warn, breach, edges, direction, format = 'percent', currency, locale, label, ariaLabel, bandLabels, className }) {
+    const band = gaugeBand(value, { warn, breach, edges }, direction);
+    const { Icon, tint } = BAND[band];
+    // The sr-only word is the band's only non-chromatic cue, so it is also the
+    // string a trilingual consumer has to translate. pt-BR default, override wins.
+    // Every rung of the naming chain is normalized: an empty override must fall
+    // through to the next source rather than win with a blank string.
+    const word = nonEmpty(bandLabels?.[band]) ?? BAND[band].word;
+    const caption = nonEmpty(label);
+    // A `role="meter"` with no accessible name is announced as a naked number.
+    // The band word is always present and always meaningful, so the meter is named
+    // even when a consumer renders the gauge without a visible caption.
+    const meterName = nonEmpty(ariaLabel) ?? caption ?? word;
+    const valuePct = trackFraction(value, min, max) * 100;
+    const warnPct = trackFraction(warn, min, max) * 100;
+    const breachPct = trackFraction(breach, min, max) * 100;
+    return (_jsxs("div", { className: cn('flex flex-col gap-2', className), children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [caption != null ? (_jsx("span", { className: LABEL_VOICE_CLASS, children: caption })) : (_jsx("span", {})), _jsxs("span", { className: cn('inline-flex items-center gap-1.5', tint), children: [_jsx(Icon, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsxs("span", { className: "sr-only", children: [word, ": "] }), _jsx(Figure, { size: "row", className: tint, children: readout(displayValue ?? value, format, currency, locale) })] })] }), _jsxs("div", { role: "meter", "aria-valuenow": value, "aria-valuemin": min, "aria-valuemax": max, "aria-label": meterName, className: "border-border bg-muted relative h-2 w-full overflow-hidden rounded-full border", children: [_jsx("div", { "aria-hidden": true, className: cn('absolute inset-y-0 left-0 rounded-full', BAND_FILL[band]), style: { width: `${valuePct}%` } }), _jsx("span", { "aria-hidden": true, className: "bg-system-alert absolute inset-y-0 w-px", style: { left: `${warnPct}%` } }), _jsx("span", { "aria-hidden": true, className: "bg-destructive absolute inset-y-0 w-px", style: { left: `${breachPct}%` } })] })] }));
+}