@candor-ui/react 1.0.1 → 1.3.0

package/LICENSE

@@ -20,5 +20,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-This licence covers only the free-tier items listed in scripts/tiers.json. See
-LICENSE.md.
+This licence covers only Candor UI's free-tier items, the ones published at
+https://github.com/MethodicDev/candor. Paid items are under the Candor UI
+Commercial Licence (https://candor.themethodic.com/licence).

package/dist/blocks/copy-field.d.ts

@@ -1,3 +1,9 @@
+/** CopyField's fixed words; override them under `copyField` in LocaleProvider's `strings`. */
+export declare const copyFieldStrings: {
+    copy: string;
+    copied: string;
+    failed: string;
+};
 /**
  * A value a person copies somewhere else (a callback URL, a scope list). The
  * whole field is the copy target; it says "Copied" only once the clipboard

package/dist/blocks/copy-field.js

@@ -3,6 +3,13 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Check, Copy, X } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { useCopy } from "../lib/use-copy.js";
+import { useStrings } from "./locale.js";
+/** CopyField's fixed words; override them under `copyField` in LocaleProvider's `strings`. */
+export const copyFieldStrings = {
+    copy: "Copy",
+    copied: "Copied",
+    failed: "Couldn’t copy",
+};
 /**
  * A value a person copies somewhere else (a callback URL, a scope list). The
  * whole field is the copy target; it says "Copied" only once the clipboard
@@ -10,6 +17,7 @@ import { useCopy } from "../lib/use-copy.js";
  */
 function CopyField({ label, value, className, }) {
     const { state, copy } = useCopy();
-    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-left outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/40", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text" }), " Copied"] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " Couldn\u2019t copy"] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " Copy"] })) })] })] }));
+    const t = useStrings("copyField", copyFieldStrings);
+    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-start outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/40", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
 }
 export { CopyField };

package/dist/blocks/degraded-panel.d.ts

@@ -1,3 +1,9 @@
+/** DegradedPanel's fixed words; override them under `degradedPanel` in LocaleProvider's `strings`. */
+export declare const degradedPanelStrings: {
+    missing: string;
+    retry: string;
+    retrying: string;
+};
 /**
  * Something couldn't be done. Says what went wrong, what is missing because of
  * it, and offers a retry only when the caller can actually retry (Candor's

package/dist/blocks/degraded-panel.js

@@ -3,12 +3,20 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CircleAlert, RotateCw } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { Button } from "../ui/button.js";
+import { useStrings } from "./locale.js";
+/** DegradedPanel's fixed words; override them under `degradedPanel` in LocaleProvider's `strings`. */
+export const degradedPanelStrings = {
+    missing: "Missing:",
+    retry: "Retry",
+    retrying: "Retrying",
+};
 /**
  * Something couldn't be done. Says what went wrong, what is missing because of
  * it, and offers a retry only when the caller can actually retry (Candor's
  * DegradedPanel: a degraded state names what's missing, never just looks sad).
  */
 function DegradedPanel({ reason, missing, onRetry, retrying = false, variant = "block", className, }) {
-    return (_jsxs("div", { "data-slot": "degraded-panel", role: "status", className: cn("flex gap-2.5 text-sm", variant === "block" ? "items-start rounded-lg border border-warning/40 bg-warning-weak/60 p-3" : "items-center", className), children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-0.5 size-4 shrink-0 text-warning-text" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-foreground", children: reason }), missing && _jsxs("p", { className: "mt-0.5 text-xs text-muted-foreground", children: ["Missing: ", missing] })] }), onRetry && (_jsxs(Button, { size: "xs", variant: "outline", onClick: onRetry, disabled: retrying, "aria-busy": retrying, className: "shrink-0", children: [_jsx(RotateCw, { className: cn(retrying && "animate-spin") }), " ", retrying ? "Retrying" : "Retry"] }))] }));
+    const t = useStrings("degradedPanel", degradedPanelStrings);
+    return (_jsxs("div", { "data-slot": "degraded-panel", role: "status", className: cn("flex gap-2.5 text-sm", variant === "block" ? "items-start rounded-lg border border-warning/40 bg-warning-weak/60 p-3" : "items-center", className), children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-0.5 size-4 shrink-0 text-warning-text" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-foreground", children: reason }), missing && _jsxs("p", { className: "mt-0.5 text-xs text-muted-foreground", children: [t("missing"), " ", missing] })] }), onRetry && (_jsxs(Button, { size: "xs", variant: "outline", onClick: onRetry, disabled: retrying, "aria-busy": retrying, className: "shrink-0", children: [_jsx(RotateCw, { className: cn(retrying && "animate-spin") }), " ", retrying ? t("retrying") : t("retry")] }))] }));
 }
 export { DegradedPanel };

package/dist/blocks/locale.d.ts

@@ -0,0 +1,86 @@
+import * as React from "react";
+/**
+ * The interface's words, language and direction. Every fixed string in Candor (labels, buttons, screen-reader text,
+ * "just now") reads from here, with English as the default, and dates and numbers follow the locale. Terms stays for
+ * the app's own nouns ("environment", "account").
+ *
+ * Each component keeps its English defaults in an exported table named after it (`threadStrings`, `composerStrings`),
+ * and you override any of them under the component's registry name in camelCase (`thread`, `relativeTime`,
+ * `commandPalette`):
+ *
+ *   <LocaleProvider locale="fr" strings={{ thread: { jumpToLatest: "Aller au plus récent" } }}>
+ *
+ * A string can hold `{name}` placeholders, and a count can choose between plural forms
+ * (`{ one: "{count} file", other: "{count} files" }`), so every override stays plain, serialisable data that a
+ * server component can pass.
+ */
+/** One string, or its plural forms chosen by `count`; `{name}` placeholders are filled in. */
+export type Phrase = string | ({
+    other: string;
+} & Partial<Record<Intl.LDMLPluralRule, string>>);
+/** A component's strings: its English defaults, or your overrides. */
+export type StringTable = Record<string, Phrase>;
+/** Overrides by component name, e.g. `{ thread: { jumpToLatest: "…" }, composer: { send: "…" } }`. */
+export type StringOverrides = Record<string, Partial<StringTable> | undefined>;
+export type TextDirection = "ltr" | "rtl";
+/** "rtl" for Arabic, Hebrew, Persian, Urdu and the like; "ltr" otherwise. */
+export declare function directionOf(locale: string | undefined): TextDirection;
+declare function LocaleProvider({ locale, dir, timeZone, strings, children, }: {
+    /** A BCP 47 tag such as "en-GB", "fr" or "ar-EG", for dates, numbers and plural forms. Left out, the browser's own is used once the page has hydrated. */
+    locale?: string;
+    /** Text direction. Left out, it follows the locale: "rtl" for Arabic, Hebrew, Persian, Urdu and the like. Set `dir` on `<html>` too, so the page's own layout flips with Candor's. */
+    dir?: TextDirection;
+    /** An IANA time zone such as "Europe/Paris". With `locale`, server and browser format dates the same way, so absolute times render on the server too. */
+    timeZone?: string;
+    /** Overrides by component name, e.g. `{ thread: { jumpToLatest: "…" } }`; any left out stay English. Nested providers merge. */
+    strings?: StringOverrides;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The locale, time zone and text direction in effect. */
+declare function useLocale(): {
+    locale?: string;
+    timeZone?: string;
+    dir: TextDirection;
+};
+/**
+ * False while rendering on the server and during React's hydration pass, true after. Anything that depends on the
+ * browser (its locale, its time zone) waits for true, so server and browser render the same markup.
+ */
+declare function useHydrated(): boolean;
+/** How an absolute time reads: "5 Nov 2026", "5 Nov 2026, 14:03" or "14:03". */
+export type DateStyle = "date" | "datetime" | "time";
+export type Formatter = {
+    /** The locale actually used right now; "en-US" before hydration when no locale is set. */
+    tag: string | undefined;
+    /** A number in the locale: "1,234.5", "1 234,5". */
+    number: (n: number, options?: Intl.NumberFormatOptions) => string;
+    /** An absolute time. Until the page hydrates it reads as an ISO date in UTC, unless both `locale` and `timeZone` are set. */
+    date: (date: Date | string | number, style?: DateStyle) => string;
+    /** Items joined as the locale does: "A, B and C". */
+    list: (items: string[], type?: "conjunction" | "disjunction") => string;
+};
+/**
+ * Locale-aware formatting that's safe to render on the server. With no `locale` set, numbers use "en-US" until the
+ * page hydrates and then the browser's locale; dates show their ISO form until then. Set `locale` (and `timeZone`
+ * for dates) on the provider to render the final text on the server.
+ */
+declare function useFormat(): Formatter;
+/** Fill `{name}` placeholders. Numbers go through the locale's number format. */
+export declare function fill(template: string, vars: Record<string, string | number> | undefined, number?: (n: number) => string): string;
+/** The plural form for `count`, falling back to `other`. */
+export declare function pick(message: Phrase, count: number | undefined, rules: Intl.PluralRules): string;
+/**
+ * A translated sentence with elements in it: `place(t("signedInAs"), { email: <strong>{email}</strong> })`. Each
+ * `{name}` becomes that node, so translators can move it within the sentence and it keeps its styling.
+ */
+export declare function place(text: string, nodes: Record<string, React.ReactNode>): React.ReactNode[];
+/** Looks up one string by key and fills its placeholders; `count` also picks the plural form. */
+export type Translate<T extends StringTable> = (key: keyof T & string, vars?: Record<string, string | number>) => string;
+/**
+ * A component's strings: `t("jumpToLatest")`, `t("remove", { name })`, `t("files", { count: 3 })`. `name` is the
+ * component's registry name in camelCase, the key apps override it under; `defaults` is its English table.
+ */
+declare function useStrings<T extends StringTable>(name: string, defaults: T): Translate<T>;
+/** Physical side for the reading direction: "left" in LTR, "right" in RTL. For the few places CSS can't say start. */
+declare function useStartSide(): "left" | "right";
+export { LocaleProvider, useLocale, useFormat, useHydrated, useStrings, useStartSide };

package/dist/blocks/locale.js

@@ -0,0 +1,146 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Direction } from "radix-ui";
+const LocaleContext = React.createContext({ dir: "ltr", strings: {} });
+// Scripts written right to left, by language subtag. Intl.Locale's text info isn't in every browser yet.
+const rtlLanguages = new Set(["ar", "arc", "ckb", "dv", "fa", "he", "iw", "ks", "ku", "ps", "sd", "syr", "ug", "ur", "yi"]);
+/** "rtl" for Arabic, Hebrew, Persian, Urdu and the like; "ltr" otherwise. */
+export function directionOf(locale) {
+    if (!locale)
+        return "ltr";
+    try {
+        const l = new Intl.Locale(locale);
+        if (l.script)
+            return ["Arab", "Hebr", "Thaa", "Syrc", "Nkoo", "Adlm", "Rohg"].includes(l.script) ? "rtl" : "ltr";
+        return rtlLanguages.has(l.language) ? "rtl" : "ltr";
+    }
+    catch {
+        return "ltr";
+    }
+}
+function LocaleProvider({ locale, dir, timeZone, strings, children, }) {
+    const parent = React.useContext(LocaleContext);
+    const nextLocale = locale ?? parent.locale;
+    // `strings` is usually an inline object; keyed by its content so consumers don't re-render on every render here.
+    const stringsKey = JSON.stringify(strings ?? {});
+    const value = React.useMemo(() => {
+        const merged = { ...parent.strings };
+        for (const [name, table] of Object.entries(strings ?? {}))
+            merged[name] = { ...parent.strings[name], ...table };
+        return {
+            locale: nextLocale,
+            timeZone: timeZone ?? parent.timeZone,
+            dir: dir ?? (locale ? directionOf(locale) : parent.dir),
+            strings: merged,
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `strings` is tracked by its content (stringsKey)
+    }, [parent, nextLocale, locale, timeZone, dir, stringsKey]);
+    return (_jsx(LocaleContext.Provider, { value: value, children: _jsx(Direction.Provider, { dir: value.dir, children: children }) }));
+}
+/** The locale, time zone and text direction in effect. */
+function useLocale() {
+    const { locale, timeZone, dir } = React.useContext(LocaleContext);
+    return { locale, timeZone, dir };
+}
+const noop = () => () => { };
+/**
+ * False while rendering on the server and during React's hydration pass, true after. Anything that depends on the
+ * browser (its locale, its time zone) waits for true, so server and browser render the same markup.
+ */
+function useHydrated() {
+    return React.useSyncExternalStore(noop, () => true, () => false);
+}
+const dateOptions = {
+    date: { dateStyle: "medium" },
+    datetime: { dateStyle: "medium", timeStyle: "short" },
+    time: { timeStyle: "short" },
+};
+/** The ISO form shown before hydration: the same on server and browser, in UTC, and says so. */
+function isoText(d, style) {
+    const iso = d.toISOString();
+    if (style === "date")
+        return iso.slice(0, 10);
+    if (style === "time")
+        return `${iso.slice(11, 16)} UTC`;
+    return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+/**
+ * Locale-aware formatting that's safe to render on the server. With no `locale` set, numbers use "en-US" until the
+ * page hydrates and then the browser's locale; dates show their ISO form until then. Set `locale` (and `timeZone`
+ * for dates) on the provider to render the final text on the server.
+ */
+function useFormat() {
+    const { locale, timeZone } = React.useContext(LocaleContext);
+    const hydrated = useHydrated();
+    return React.useMemo(() => {
+        const tag = locale ?? (hydrated ? undefined : "en-US");
+        const fixedDates = hydrated || Boolean(locale && timeZone);
+        return {
+            tag,
+            number: (n, options) => new Intl.NumberFormat(tag, options).format(n),
+            date: (value, style = "datetime") => {
+                const d = value instanceof Date ? value : new Date(value);
+                if (Number.isNaN(d.getTime()))
+                    return String(value);
+                if (!fixedDates)
+                    return isoText(d, style);
+                return new Intl.DateTimeFormat(tag, { ...dateOptions[style], ...(timeZone && { timeZone }) }).format(d);
+            },
+            list: (items, type = "conjunction") => new Intl.ListFormat(tag, { style: "long", type }).format(items),
+        };
+    }, [locale, timeZone, hydrated]);
+}
+/** Fill `{name}` placeholders. Numbers go through the locale's number format. */
+export function fill(template, vars, number = String) {
+    if (!vars)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (whole, key) => {
+        const v = vars[key];
+        return v === undefined ? whole : typeof v === "number" ? number(v) : v;
+    });
+}
+/** The plural form for `count`, falling back to `other`. */
+export function pick(message, count, rules) {
+    if (typeof message === "string")
+        return message;
+    if (count === undefined)
+        return message.other;
+    if (count === 0 && message.zero !== undefined)
+        return message.zero;
+    return message[rules.select(count)] ?? message.other;
+}
+/**
+ * A translated sentence with elements in it: `place(t("signedInAs"), { email: <strong>{email}</strong> })`. Each
+ * `{name}` becomes that node, so translators can move it within the sentence and it keeps its styling.
+ */
+export function place(text, nodes) {
+    return text.split(/\{(\w+)\}/).map((part, i) => (i % 2 ? _jsx(React.Fragment, { children: part in nodes ? nodes[part] : `{${part}}` }, i) : part));
+}
+/**
+ * A component's strings: `t("jumpToLatest")`, `t("remove", { name })`, `t("files", { count: 3 })`. `name` is the
+ * component's registry name in camelCase, the key apps override it under; `defaults` is its English table.
+ */
+function useStrings(name, defaults) {
+    const { strings, locale } = React.useContext(LocaleContext);
+    const format = useFormat();
+    const overrides = strings[name];
+    return React.useMemo(() => {
+        // Plural forms follow the language of the strings: the provider's locale, else English (the defaults). Never the
+        // browser's, which would pick Japanese "other" for English "{count} file".
+        const rules = new Intl.PluralRules(locale ?? "en-US");
+        const number = (n) => format.number(n);
+        return (key, vars) => {
+            const message = overrides?.[key] ?? defaults[key];
+            if (message === undefined)
+                return key;
+            const count = typeof vars?.count === "number" ? vars.count : undefined;
+            return fill(pick(message, count, rules), vars, number);
+        };
+    }, [overrides, defaults, format, locale]);
+}
+/** Physical side for the reading direction: "left" in LTR, "right" in RTL. For the few places CSS can't say start. */
+function useStartSide() {
+    return useLocale().dir === "rtl" ? "right" : "left";
+}
+export { LocaleProvider, useLocale, useFormat, useHydrated, useStrings, useStartSide };

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

@@ -1,13 +1,31 @@
 import * as React from "react";
-export declare function formatRelative(date: Date, now?: Date): string;
+import { type DateStyle } from "./locale.js";
+/** RelativeTime's fixed words; override them under `relativeTime` in LocaleProvider's `strings`. */
+export declare const relativeTimeStrings: {
+    justNow: string;
+};
+/**
+ * "5 minutes ago", "in 6 days", in the locale (the runtime's own when left out). `bare` drops the direction for tight
+ * spaces: "5 minutes".
+ */
+export declare function formatRelative(date: Date, now?: Date, { locale, justNow, bare }?: {
+    locale?: string;
+    justNow?: string;
+    bare?: boolean;
+}): string;
 /** The current time in milliseconds, updated every 30 seconds; null while rendering on the server. */
 export declare function useNow(): number | null;
-/** "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. */
-declare function RelativeTime({ date, bare, className, }: {
+/**
+ * "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known.
+ * `format` shows an absolute time instead ("5 Nov 2026, 14:03"), in the locale, with the same server-safe gate.
+ */
+declare function RelativeTime({ date, bare, format, className, }: {
     /** When it happened. Shown as "5 minutes ago", with the exact time on hover. */
     date: Date | string;
     /** Drop "ago" and "in", for tight spaces: "5 minutes". */
     bare?: boolean;
+    /** "relative" (the default), or an absolute "date", "datetime" or "time" in the locale. */
+    format?: "relative" | DateStyle;
     className?: string;
 }): React.JSX.Element;
 export { RelativeTime };

package/dist/blocks/relative-time.js

@@ -1,6 +1,11 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
+import { useFormat, useStrings } from "./locale.js";
+/** RelativeTime's fixed words; override them under `relativeTime` in LocaleProvider's `strings`. */
+export const relativeTimeStrings = {
+    justNow: "just now",
+};
 const units = [
     ["year", 31_536_000],
     ["month", 2_592_000],
@@ -10,14 +15,21 @@ const units = [
     ["minute", 60],
     ["second", 1],
 ];
-const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
-export function formatRelative(date, now = new Date()) {
+/**
+ * "5 minutes ago", "in 6 days", in the locale (the runtime's own when left out). `bare` drops the direction for tight
+ * spaces: "5 minutes".
+ */
+export function formatRelative(date, now = new Date(), { locale, justNow = relativeTimeStrings.justNow, bare = false } = {}) {
     const seconds = Math.round((date.getTime() - now.getTime()) / 1000);
     if (Math.abs(seconds) < 10)
-        return "just now";
+        return justNow;
     for (const [unit, size] of units) {
-        if (Math.abs(seconds) >= size || unit === "second")
-            return rtf.format(Math.round(seconds / size), unit);
+        if (Math.abs(seconds) >= size || unit === "second") {
+            const n = Math.round(seconds / size);
+            return bare
+                ? new Intl.NumberFormat(locale, { style: "unit", unit, unitDisplay: "long" }).format(Math.abs(n))
+                : new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(n, unit);
+        }
     }
     return "";
 }
@@ -50,13 +62,20 @@ function subscribe(onChange) {
 export function useNow() {
     return React.useSyncExternalStore(subscribe, () => now || (now = Date.now()), () => null);
 }
-/** "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. */
-function RelativeTime({ date, bare = false, className, }) {
+/**
+ * "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known.
+ * `format` shows an absolute time instead ("5 Nov 2026, 14:03"), in the locale, with the same server-safe gate.
+ */
+function RelativeTime({ date, bare = false, format = "relative", className, }) {
     const d = typeof date === "string" ? new Date(date) : date;
     const current = useNow();
-    let text = current === null ? d.toISOString().slice(0, 10) : formatRelative(d, new Date(current));
-    if (bare)
-        text = text.replace(/ ago$/, "").replace(/^in /, "");
-    return (_jsx("time", { dateTime: d.toISOString(), title: current === null ? undefined : d.toLocaleString(), className: className, children: text }));
+    const fmt = useFormat();
+    const t = useStrings("relativeTime", relativeTimeStrings);
+    const text = format !== "relative"
+        ? fmt.date(d, format)
+        : current === null
+            ? d.toISOString().slice(0, 10)
+            : formatRelative(d, new Date(current), { locale: fmt.tag, justNow: t("justNow"), bare });
+    return (_jsx("time", { dateTime: d.toISOString(), title: current === null ? undefined : fmt.date(d, "datetime"), className: className, children: text }));
 }
 export { RelativeTime };

package/dist/blocks/status-dot.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
-import { statusLabel } from "../lib/status.js";
+import { useStatusLabel } from "../lib/status.js";
 const dotColor = {
     idle: "bg-faint-foreground/60",
     queued: "bg-faint-foreground",
@@ -18,7 +19,8 @@ const dotColor = {
  * to assistive tech; pass `showLabel` to print it too.
  */
 function StatusDot({ status, showLabel = false, label, className, }) {
-    const text = label ?? statusLabel[status];
+    const statusLabel = useStatusLabel();
+    const text = label ?? statusLabel(status);
     const live = status === "running" || status === "waiting";
     return (_jsxs("span", { "data-slot": "status-dot", "data-status": status, className: cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className), children: [_jsx("span", { "aria-hidden": true, className: cn("size-2 shrink-0 rounded-full", dotColor[status], live && "animate-pulse-dot") }), showLabel ? _jsx("span", { children: text }) : _jsx("span", { className: "sr-only", children: text })] }));
 }

package/dist/blocks/step-list.js

@@ -1,8 +1,9 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Check, CircleSlash, Hand, LoaderCircle, X } from "lucide-react";
 import { cn } from "../lib/utils.js";
-import { statusLabel } from "../lib/status.js";
+import { useStatusLabel } from "../lib/status.js";
 function StepMark({ status, }) {
     const base = "relative z-10 flex size-5 shrink-0 items-center justify-center rounded-full";
     switch (status) {
@@ -28,10 +29,11 @@ function StepMark({ status, }) {
  * a run's stages. The rail fills as steps finish.
  */
 function StepList({ steps, className, }) {
+    const statusLabel = useStatusLabel();
     return (_jsx("ol", { "data-slot": "step-list", className: cn("flex flex-col", className), children: steps.map((step, i) => {
             const last = i === steps.length - 1;
             const done = step.status === "succeeded";
-            return (_jsxs("li", { className: "relative flex gap-3 pb-4 last:pb-0 animate-rise-in", style: { animationDelay: `${i * 40}ms` }, children: [!last && (_jsx("span", { "aria-hidden": true, className: cn("absolute top-5 bottom-0 left-[9.5px] w-px transition-colors duration-500", done ? "bg-success/50" : "bg-input") })), _jsx(StepMark, { status: step.status }), _jsxs("div", { className: "min-w-0 flex-1 pt-px", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("p", { className: cn("text-sm font-medium", step.status === "idle" && "text-muted-foreground", (step.status === "skipped" || step.status === "cancelled") && "text-faint-foreground line-through"), children: [step.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel[step.status]] })] }), step.meta && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: step.meta })] }), step.detail && _jsx("div", { className: "mt-1 text-[0.8125rem] text-muted-foreground", children: step.detail })] })] }, step.id));
+            return (_jsxs("li", { className: "relative flex gap-3 pb-4 last:pb-0 animate-rise-in", style: { animationDelay: `${i * 40}ms` }, children: [!last && (_jsx("span", { "aria-hidden": true, className: cn("absolute top-5 bottom-0 start-[9.5px] w-px transition-colors duration-500", done ? "bg-success/50" : "bg-input") })), _jsx(StepMark, { status: step.status }), _jsxs("div", { className: "min-w-0 flex-1 pt-px", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("p", { className: cn("text-sm font-medium", step.status === "idle" && "text-muted-foreground", (step.status === "skipped" || step.status === "cancelled") && "text-faint-foreground line-through"), children: [step.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel(step.status)] })] }), step.meta && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: step.meta })] }), step.detail && _jsx("div", { className: "mt-1 text-[0.8125rem] text-muted-foreground", children: step.detail })] })] }, step.id));
         }) }));
 }
 export { StepList, StepMark };

package/dist/blocks/streaming-text.js

@@ -5,7 +5,7 @@ import { cn } from "../lib/utils.js";
  * politely so screen readers hear the finished text rather than every token.
  */
 function StreamingText({ text, streaming = false, className, }) {
-    return (_jsxs("div", { "data-slot": "streaming-text", "aria-live": "polite", "aria-busy": streaming, className: cn("whitespace-pre-wrap text-[0.9375rem] leading-relaxed text-foreground", className), children: [text, streaming && (_jsx("span", { "aria-hidden": true, className: "ml-0.5 inline-block h-[1.05em] w-[2px] translate-y-[0.18em] rounded-full bg-primary animate-caret" }))] }));
+    return (_jsxs("div", { "data-slot": "streaming-text", "aria-live": "polite", "aria-busy": streaming, className: cn("whitespace-pre-wrap text-[0.9375rem] leading-relaxed text-foreground", className), children: [text, streaming && (_jsx("span", { "aria-hidden": true, className: "ms-0.5 inline-block h-[1.05em] w-[2px] translate-y-[0.18em] rounded-full bg-primary animate-caret" }))] }));
 }
 /** A label that shimmers while an agent is working ("Thinking", "Reading the docs"). */
 function ShimmerLabel({ children, className, }) {

package/dist/blocks/surface.d.ts

@@ -2,8 +2,8 @@ import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const surfaceVariants: (props?: ({
     tone?: "plain" | "muted" | "subtle" | "raised" | "floating" | "accent" | null | undefined;
-    radius?: "lg" | "md" | "xl" | null | undefined;
-    pad?: "none" | "sm" | "lg" | "md" | null | undefined;
+    radius?: "md" | "lg" | "xl" | null | undefined;
+    pad?: "none" | "md" | "sm" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Surface({ className, tone, radius, pad, ...props }: React.ComponentProps<"div"> & VariantProps<typeof surfaceVariants>): React.JSX.Element;
 export { Surface, surfaceVariants };

package/dist/chat/agent-avatar.d.ts

@@ -1,6 +1,20 @@
 import * as React from "react";
 import { type LucideIcon } from "lucide-react";
 import type { AgentIdentity } from "../lib/chat.js";
+/** AgentAvatar's fixed words; override them under `agentAvatar` in LocaleProvider's `strings`. */
+export declare const agentAvatarStrings: {
+    assistant: string;
+    orchestrator: string;
+    planner: string;
+    researcher: string;
+    analyst: string;
+    designer: string;
+    coder: string;
+    reviewer: string;
+    tester: string;
+    /** Screen-reader text after the agent's name. */
+    roleAgent: string;
+};
 export type AgentRoleInfo = {
     Icon: LucideIcon;
     noun: string;

package/dist/chat/agent-avatar.js

@@ -3,6 +3,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Bot, ClipboardList, CodeXml, Compass, FlaskConical, PenTool, ScanSearch, SearchCheck, Workflow } from "lucide-react";
 import { cn } from "../lib/utils.js";
+import { useStrings } from "../blocks/locale.js";
+/** AgentAvatar's fixed words; override them under `agentAvatar` in LocaleProvider's `strings`. */
+export const agentAvatarStrings = {
+    assistant: "Assistant",
+    orchestrator: "Orchestrator",
+    planner: "Planner",
+    researcher: "Researcher",
+    analyst: "Analyst",
+    designer: "Designer",
+    coder: "Coder",
+    reviewer: "Reviewer",
+    tester: "Tester",
+    /** Screen-reader text after the agent's name. */
+    roleAgent: ", {noun} agent",
+};
+const isBaseRole = (role) => role !== "roleAgent" && Object.hasOwn(agentAvatarStrings, role);
 // Each role keeps one glyph and one chart hue everywhere it appears, so a
 // person learns "the green flask is the tester" once.
 export const baseAgentRoles = {
@@ -27,7 +43,14 @@ function AgentRolesProvider({ roles, children, }) {
 /** Look up a role's glyph, noun and hue; unknown roles read as "Assistant". */
 function useAgentRoles() {
     const roles = React.useContext(RolesContext);
-    return React.useCallback((role) => roles[role] ?? unknownRole, [roles]);
+    const t = useStrings("agentAvatar", agentAvatarStrings);
+    return React.useCallback((role) => {
+        const info = roles[role];
+        if (!info)
+            return { ...unknownRole, noun: t("assistant") };
+        // Built-in roles take their noun from the strings table; an app's own roles keep theirs.
+        return isBaseRole(role) && info === baseAgentRoles[role] ? { ...info, noun: t(role) } : info;
+    }, [roles, t]);
 }
 /** An agent's mark: its role glyph on a tile tinted with the role's hue. */
 function AgentAvatar({ agent, size = "md", className, }) {
@@ -37,6 +60,7 @@ function AgentAvatar({ agent, size = "md", className, }) {
 /** Avatar plus name, with the role spelled out for screen readers. */
 function AgentBadge({ agent, size = "md", className, }) {
     const { noun } = useAgentRoles()(agent.role);
-    return (_jsxs("span", { "data-slot": "agent-badge", className: cn("inline-flex min-w-0 items-center gap-2", className), children: [_jsx(AgentAvatar, { agent: agent, size: size }), _jsx("span", { className: cn("truncate font-medium", size === "sm" ? "text-xs" : "text-sm"), children: agent.name }), _jsxs("span", { className: "sr-only", children: [", ", noun, " agent"] })] }));
+    const t = useStrings("agentAvatar", agentAvatarStrings);
+    return (_jsxs("span", { "data-slot": "agent-badge", className: cn("inline-flex min-w-0 items-center gap-2", className), children: [_jsx(AgentAvatar, { agent: agent, size: size }), _jsx("span", { className: cn("truncate font-medium", size === "sm" ? "text-xs" : "text-sm"), children: agent.name }), _jsx("span", { className: "sr-only", children: t("roleAgent", { noun }) })] }));
 }
 export { AgentAvatar, AgentBadge, AgentRolesProvider, useAgentRoles };

package/dist/chat/attachment-preview.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+import { type Formatter, type Translate } from "../blocks/locale.js";
+import type { Attachment } from "../lib/chat.js";
+/** AttachmentPreview's fixed words; override them under `attachmentPreview` in LocaleProvider's `strings`. */
+export declare const attachmentPreviewStrings: {
+    remove: string;
+    open: string;
+    attachments: {
+        one: string;
+        other: string;
+    };
+    /** File sizes; `{size}` is already formatted. */
+    bytes: string;
+    kilobytes: string;
+    megabytes: string;
+};
+/** "820 B", "14 KB", "2.4 MB", in the locale. */
+export declare function formatFileSize(bytes: number | undefined, number: Formatter["number"], t: Translate<typeof attachmentPreviewStrings>): string | null;
+/** An icon for a file, from its media type or, failing that, its extension. */
+export declare function fileIcon(a: Pick<Attachment, "name" | "mediaType">): LucideIcon;
+/**
+ * A file waiting to be sent, as a chip in the composer: its name, then upload progress, an error, or its size, and a
+ * remove button. Images show their preview when the app gives one.
+ */
+declare function AttachmentChip({ attachment: a, onRemove, className, }: {
+    /** The file, with progress (0–1) while uploading or an error if it failed. */
+    attachment: Attachment;
+    /** Shows a remove button. */
+    onRemove?: (id: string) => void;
+    className?: string;
+}): React.JSX.Element;
+/**
+ * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with
+ * its name and size. The name is never a link: with `onOpen` the tile is a button and your app decides what opening
+ * means (a viewer, a signed download).
+ */
+declare function AttachmentPreview({ attachment: a, onOpen, className, }: {
+    /** The file. `previewUrl` must be one your app serves (a thumbnail, a blob: URL); it's shown only for images. */
+    attachment: Attachment;
+    /** Makes the tile a button that opens the file. */
+    onOpen?: (attachment: Attachment) => void;
+    className?: string;
+}): React.JSX.Element;
+/** Several sent files, as a wrapping row of tiles, announced as a list. */
+declare function AttachmentList({ attachments, onOpen, className, }: {
+    /** The files. */
+    attachments: Attachment[];
+    /** Makes each tile a button that opens its file. */
+    onOpen?: (attachment: Attachment) => void;
+    className?: string;
+}): React.JSX.Element;
+export { AttachmentChip, AttachmentPreview, AttachmentList };