@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/components/shell/AppFrame.js

@@ -0,0 +1,80 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HeaderSlotContext } from "./headerSlot.js";
+import { stickyTop, useStickyLayer } from "../../foundations/sticky.js";
+import { useState } from "react";
+/* ==================================================================== *
+ *  THE APPLICATION FRAME — the three bands, and nothing between them.
+ *
+ *      ┌───────────────────────────────────────────────────────┐
+ *      │ menu                                                  │  ← sticky
+ *      ├───────────────────────────────────────────────────────┤  ← no seam
+ *      │ view                                                  │
+ *      ├───────────────────────────────────────────────────────┤  ← no seam
+ *      │ status                                                │
+ *      └───────────────────────────────────────────────────────┘
+ *
+ *  It exists because the frame was handwritten in the application, with a
+ *  `px-3 py-2.5` here and a `bg-surface` there, and every hole fix opened
+ *  another one in another view. The decisions below are taken ONCE and hold
+ *  for every view — list, record, form — which is what makes them look alike
+ *  without anybody remembering to copy them.
+ *
+ *  ── What this frame decides, and why ────────────────────────────────
+ *
+ *  **The three bands touch.** No padding, no margin, no `gap` between the
+ *  menu, the view and the status. Any gap here reads as a white border around
+ *  the content: the dark band of a list stops reading as the continuation of
+ *  the menu and starts looking like a loose card.
+ *
+ *  **The view does not get padding from the frame.** Inner air is put by the
+ *  view, which is the only one that knows whether it is drawing a table to
+ *  both edges or a narrow form. A padding here would impose it on both.
+ *
+ *  **Nothing forces the window height.** A short view ends where its content
+ *  ends: without cascading `h-full` there is no leftover white under the
+ *  status, and the page scrolls as a whole like any page.
+ *
+ *  ── The sidebar ─────────────────────────────────────────────────────
+ *
+ *      ┌───────────────────────────────────────────────────────┐
+ *      │ menu                                                  │  ← sticky
+ *      ├──────────┬────────────────────────────────────────────┤
+ *      │ sidebar  │ view                                       │
+ *      │ (sticky) │   …scrolls with the page…                  │
+ *      ├──────────┴────────────────────────────────────────────┤
+ *      │ status                                                │
+ *      └───────────────────────────────────────────────────────┘
+ *
+ *  It sticks UNDER the menu, not at the top of the window: it reads the same
+ *  measured `--sticky-top` the view's own sticky bands read, so a menu that
+ *  wraps to two lines pushes the sidebar down with it. It is as tall as what
+ *  is left of the window and scrolls on its own, so a long module never takes
+ *  the page with it. The page still scrolls as a whole — only the view moves.
+ *  Without a `sidebar` the frame is exactly what it was.
+ * ==================================================================== */
+export function AppFrame({ 
+/** The bar at the top. It stays in view while scrolling. */
+menu, 
+/** The band at the bottom. It goes AFTER the content, not pinned to the
+ *  floor of the window — pinning left a hole between it and a short view. */
+status, 
+/** The module's navigation, on the left of the view: a `NavigationTree`. */
+sidebar, children, }) {
+    /* La barra de arriba MIDE lo que ocupa y se lo pasa a lo de abajo: la barra
+       de una lista se pega debajo de ella, y el encabezado de una tabla debajo de
+       las dos. Ninguna de las tres tiene alto fijo — ver `system/sticky.tsx`. */
+    const bar = useStickyLayer();
+    /* The slot for a view's header (see `headerSlot.ts`): full width, stuck under the
+       application bar, and it pushes the stack down for the sidebar and the table header. */
+    const [slot, setSlot] = useState(null);
+    const head = useStickyLayer();
+    return (
+    /* The frame owns the page: its background and its full height. A screen built inside
+       it is only composition — before, every page had to wrap itself in a `div` with the
+       ground color and `min-h-dvh`, and the one that forgot ended where its content did. */
+    _jsxs("div", { className: "relative flex min-h-dvh min-w-0 flex-col bg-ground", children: [menu === undefined ? null : (_jsx("div", { ref: bar.ref, className: "sticky top-0 z-40", children: menu })), sidebar === undefined ? (_jsx("main", { className: "flex min-w-0 flex-1 flex-col", style: bar.below, children: children })) : (_jsx(HeaderSlotContext, { value: slot, children: _jsxs("div", { className: "flex min-w-0 flex-1 flex-col", style: bar.below, children: [_jsx("div", { ref: (node) => {
+                                head.ref.current = node;
+                                setSlot(node);
+                            }, className: "sticky z-30 min-w-0", style: head.self }), _jsxs("div", { className: "flex min-w-0 flex-1 items-start", style: head.below, children: [_jsx("aside", { className: "sticky w-(--container-sidebar) shrink-0 self-start overflow-y-auto overscroll-contain border-r border-line bg-ground", style: { ...stickyTop, height: "calc(100dvh - var(--sticky-top, 0px))" }, children: sidebar }), _jsx("main", { className: "flex min-w-0 flex-1 flex-col self-stretch", children: children })] })] }) })), status] }));
+}

package/dist/components/shell/TopBar.d.ts

@@ -0,0 +1,73 @@
+import { type MenuGroup } from "../../primitives/menu/Menu.js";
+import { type LucideIcon } from "lucide-react";
+import { type ReactNode } from "react";
+export interface AppEntry {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+    /** One line: what this app is for. It shows in the switcher. */
+    hint?: string;
+}
+export interface TopMenu {
+    id: string;
+    label: string;
+    groups: readonly MenuGroup[];
+}
+export declare function TopBar({ app, apps, currentApp, onAppSelect, menus, onMenuSelect, systray, user, onUserSelect, userGroups, }: {
+    /** The product's name, when there is ONE product. It is drawn like the
+     *  current app of the switcher —same icon, same weight— but without the
+     *  switcher: nothing to switch to. */
+    app?: {
+        label: string;
+        icon?: LucideIcon;
+    };
+    /** Everything that exists. Without this there is no switcher — a product with
+     *  a single app does not need one, and drawing it empty promises something
+     *  that is not there. */
+    apps?: readonly AppEntry[];
+    currentApp?: string;
+    onAppSelect?: (id: string) => void;
+    /** The menus OF the current app. */
+    menus?: readonly TopMenu[];
+    onMenuSelect?: (menuId: string, optionId: string) => void;
+    /** What happened while I was not looking: activity, alerts. Icons with a count. */
+    systray?: ReactNode;
+    user?: {
+        name: string;
+        detail?: string;
+    };
+    userGroups?: readonly MenuGroup[];
+    onUserSelect?: (id: string) => void;
+}): import("react").JSX.Element;
+/** The app switcher: a grid, not a list.
+ *
+ *  Context: there are six or eight, each with an icon, and they are picked by
+ *  recognition rather than by reading. A vertical list forces you to read all
+ *  six to find the one you already know; the grid shows them at once and the
+ *  position gets learned. */
+export declare function AppSwitcher({ apps, current, onSelect, }: {
+    apps: readonly AppEntry[];
+    current?: string;
+    onSelect?: (id: string) => void;
+}): import("react").JSX.Element;
+/** A systray icon with its count.
+ *
+ *  Zero is NOT drawn: a bell with a «0» next to it forces you to read a number
+ *  to discover there is nothing. With no count you can already see there is
+ *  nothing. */
+export declare function SystrayButton({ icon: Icon, label, count, tone, onClick, active, }: {
+    icon: LucideIcon;
+    label: string;
+    count?: number;
+    tone?: "info" | "warn" | "bad";
+    onClick?: () => void;
+    active?: boolean;
+}): import("react").JSX.Element;
+/** Who I am and how I leave. The name is drawn when there is width; when narrow
+ *  only the avatar stays, which is what gets recognised without reading. */
+export declare function UserMenu({ name, detail, groups, onSelect, }: {
+    name: string;
+    detail?: string;
+    groups: readonly MenuGroup[];
+    onSelect?: (id: string) => void;
+}): import("react").JSX.Element;

package/dist/components/shell/TopBar.js

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { SurfaceProvider } from "../../foundations/surface.js";
+import { Menu } from "../../primitives/menu/Menu.js";
+import { Avatar } from "../../primitives/value/Person.js";
+import { Grid3x3 } from "lucide-react";
+import { useState } from "react";
+export function TopBar({ app, apps, currentApp, onAppSelect, menus, onMenuSelect, systray, user, onUserSelect, userGroups, }) {
+    const copy = useUiCopy();
+    const actual = apps?.find((a) => a.id === currentApp);
+    const brand = app ?? actual;
+    return (_jsx(SurfaceProvider, { value: "chrome", children: _jsxs("header", { className: "flex h-(--size-appbar) min-w-0 items-center gap-1 border-b border-chrome-edge bg-chrome px-2", children: [apps === undefined || apps.length === 0 ? null : (_jsx(AppSwitcher, { apps: apps, current: currentApp, ...(onAppSelect === undefined ? {} : { onSelect: onAppSelect }) })), brand === undefined ? null : (_jsxs("span", { className: "flex shrink-0 items-center gap-2 pr-2 pl-1", children: [brand.icon === undefined ? null : (_jsx(brand.icon, { className: "size-(--size-icon-md) text-chrome-link", strokeWidth: 2, "aria-hidden": true })), _jsx("span", { className: "text-lead font-medium text-chrome-ink", children: brand.label })] })), menus === undefined ? null : (_jsx("nav", { className: "flex min-w-0 items-center gap-0.5 overflow-hidden", "aria-label": copy.shell.menus, children: menus.map((m) => (_jsx(Menu, { label: m.label, groups: m.groups, surface: "chrome", variant: "text", chevron: false, onSelect: (id) => onMenuSelect?.(m.id, id) }, m.id))) })), _jsxs("div", { className: "ml-auto flex shrink-0 items-center gap-1 pl-2", children: [systray, user === undefined ? null : (_jsx(UserMenu, { name: user.name, ...(user.detail === undefined ? {} : { detail: user.detail }), groups: userGroups ?? [], ...(onUserSelect === undefined ? {} : { onSelect: onUserSelect }) }))] })] }) }));
+}
+/** The app switcher: a grid, not a list.
+ *
+ *  Context: there are six or eight, each with an icon, and they are picked by
+ *  recognition rather than by reading. A vertical list forces you to read all
+ *  six to find the one you already know; the grid shows them at once and the
+ *  position gets learned. */
+export function AppSwitcher({ apps, current, onSelect, }) {
+    const [open, setOpen] = useState(false);
+    const copy = useUiCopy();
+    return (_jsxs("div", { className: "relative shrink-0", children: [_jsx("button", { type: "button", onClick: () => setOpen((v) => !v), "aria-expanded": open, "aria-haspopup": "menu", "aria-label": copy.shell.modules, title: copy.shell.modules, className: `inline-flex size-(--size-control-md) items-center justify-center rounded-pill transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-chrome-link ${open
+                    ? "bg-chrome-ink/12 text-chrome-ink"
+                    : "text-chrome-muted hover:bg-chrome-ink/10 hover:text-chrome-ink"}`, children: _jsx(Grid3x3, { className: "size-(--size-icon-md)", strokeWidth: 2 }) }), !open ? null : (_jsxs(_Fragment, { children: [_jsx("div", { className: "fixed inset-0 z-40", onClick: () => setOpen(false), role: "presentation" }), _jsx("div", { role: "menu", className: "absolute top-full left-0 z-50 mt-1 grid w-(--container-apps) grid-cols-3 gap-1 rounded-panel border border-line bg-surface p-2 shadow-float", children: apps.map((a) => {
+                            const here = a.id === current;
+                            return (_jsxs("button", { type: "button", role: "menuitem", title: a.hint, onClick: () => {
+                                    onSelect?.(a.id);
+                                    setOpen(false);
+                                }, className: `flex flex-col items-center gap-1.5 rounded-box px-2 py-3 text-center transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${here ? "bg-primary/8 text-primary" : "text-ink hover:bg-ink/5"}`, children: [_jsx(a.icon, { className: "size-(--size-icon-lg)", strokeWidth: 1.75, "aria-hidden": true }), _jsx("span", { className: "text-micro leading-tight", children: a.label })] }, a.id));
+                        }) })] }))] }));
+}
+/** A systray icon with its count.
+ *
+ *  Zero is NOT drawn: a bell with a «0» next to it forces you to read a number
+ *  to discover there is nothing. With no count you can already see there is
+ *  nothing. */
+export function SystrayButton({ icon: Icon, label, count = 0, tone = "info", onClick, active = false, }) {
+    const PUNTO = {
+        info: "bg-chrome-link text-chrome",
+        warn: "bg-chrome-warn text-chrome",
+        bad: "bg-chrome-bad text-chrome",
+    };
+    return (_jsxs("button", { type: "button", onClick: onClick, title: count > 0 ? `${label} (${count})` : label, "aria-label": count > 0 ? `${label}: ${count}` : label, className: `relative inline-flex size-(--size-control-md) items-center justify-center rounded-pill transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-chrome-link ${active
+            ? "bg-chrome-ink/12 text-chrome-ink"
+            : "text-chrome-muted hover:bg-chrome-ink/10 hover:text-chrome-ink"}`, children: [_jsx(Icon, { className: "size-(--size-icon-md)", strokeWidth: 2, "aria-hidden": true }), count <= 0 ? null : (_jsx("span", { "aria-hidden": true, className: `absolute -top-0.5 -right-0.5 inline-flex min-w-4 items-center justify-center rounded-pill px-1 text-micro leading-none font-semibold tabular-nums ${PUNTO[tone]}`, children: count > 99 ? "99+" : count }))] }));
+}
+/** Who I am and how I leave. The name is drawn when there is width; when narrow
+ *  only the avatar stays, which is what gets recognised without reading. */
+export function UserMenu({ name, detail, groups, onSelect, }) {
+    const copy = useUiCopy();
+    return (_jsxs("span", { className: "flex shrink-0 items-center gap-2 pl-1", children: [_jsx(Avatar, { name: name, size: "md" }), _jsxs("span", { className: "hidden min-w-0 flex-col leading-tight sm:flex", children: [_jsx("span", { className: "truncate text-meta text-chrome-ink", children: name }), detail === undefined ? null : (_jsx("span", { className: "truncate text-micro text-chrome-muted", children: detail }))] }), _jsx(Menu, { label: copy.shell.account, groups: groups, surface: "chrome", variant: "text", align: "end", iconOnly: true, ...(onSelect === undefined ? {} : { onSelect }) })] }));
+}

package/dist/components/shell/headerSlot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Context: **where a view's header goes when the frame has a sidebar.**
+ *
+ * With a sidebar the screen is a grid: the application bar on top, the sidebar on the
+ * left, the view on the right. A list's bar (crumbs, search, pagination, actions, sort,
+ * presentation switcher) is the header of the SCREEN, not of the column to the right of
+ * the sidebar — drawn inside that column it started at the sidebar's edge and the
+ * sidebar, taller and darker, won the top-left of the page. The frame offers a full-width
+ * slot between the application bar and the sidebar row; a view that has a header renders
+ * it into the slot (a portal, so its context — density, surface, copy — comes along).
+ *
+ * `null` = there is no slot (no sidebar, or the slot has not mounted yet): the view draws
+ * its header where it always did. Not exported from the package: it is the contract
+ * between `AppFrame` and the views, not something an app writes.
+ */
+export declare const HeaderSlotContext: import("react").Context<HTMLElement | null>;
+export declare function useHeaderSlot(): HTMLElement | null;

package/dist/components/shell/headerSlot.js

@@ -0,0 +1,21 @@
+"use client";
+import { createContext, useContext } from "react";
+/**
+ * Context: **where a view's header goes when the frame has a sidebar.**
+ *
+ * With a sidebar the screen is a grid: the application bar on top, the sidebar on the
+ * left, the view on the right. A list's bar (crumbs, search, pagination, actions, sort,
+ * presentation switcher) is the header of the SCREEN, not of the column to the right of
+ * the sidebar — drawn inside that column it started at the sidebar's edge and the
+ * sidebar, taller and darker, won the top-left of the page. The frame offers a full-width
+ * slot between the application bar and the sidebar row; a view that has a header renders
+ * it into the slot (a portal, so its context — density, surface, copy — comes along).
+ *
+ * `null` = there is no slot (no sidebar, or the slot has not mounted yet): the view draws
+ * its header where it always did. Not exported from the package: it is the contract
+ * between `AppFrame` and the views, not something an app writes.
+ */
+export const HeaderSlotContext = createContext(null);
+export function useHeaderSlot() {
+    return useContext(HeaderSlotContext);
+}

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

@@ -0,0 +1,2 @@
+export { AppFrame } from "./AppFrame.js";
+export { type AppEntry, SystrayButton, TopBar, type TopMenu, } from "./TopBar.js";

package/dist/components/shell/index.js

@@ -0,0 +1,3 @@
+/* EL MARCO DE LA APLICACIÓN — lo que está arriba de toda vista. */
+export { AppFrame } from "./AppFrame.js";
+export { SystrayButton, TopBar, } from "./TopBar.js";

package/dist/foundations/aria.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+/**
+ * The locale React Aria formats with — month names, the order of day/month/year in a date
+ * field, the first day of the week — taken from the copy table, the one locale the whole
+ * system speaks.
+ *
+ * Context: React Aria reads the browser's language when nobody tells it. An app installed
+ * in Spanish on a browser in English would show a Spanish form with a date field in
+ * month/day/year — the one place in the screen that reads in another language, and the
+ * one where a wrong order changes the data.
+ */
+export declare function AriaLocale({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/foundations/aria.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "./copy.js";
+import { I18nProvider } from "react-aria-components";
+/**
+ * The locale React Aria formats with — month names, the order of day/month/year in a date
+ * field, the first day of the week — taken from the copy table, the one locale the whole
+ * system speaks.
+ *
+ * Context: React Aria reads the browser's language when nobody tells it. An app installed
+ * in Spanish on a browser in English would show a Spanish form with a date field in
+ * month/day/year — the one place in the screen that reads in another language, and the
+ * one where a wrong order changes the data.
+ */
+export function AriaLocale({ children }) {
+    const copy = useUiCopy();
+    return _jsx(I18nProvider, { locale: copy.locale, children: children });
+}

package/dist/foundations/calendar.d.ts

@@ -0,0 +1,28 @@
+import type { GroupGrain } from "./grouping.js";
+/**
+ * Una fecha recortada a la CLAVE de su grano.
+ *
+ * El texto es el que produce el motor —«2026», «2026-Q3», «2026-09», «2026-W38»,
+ * «2026-09-15»—, y que los dos lados lo escriban igual es lo que deja comparar
+ * un agrupado hecho en el navegador con uno contado a mil kilómetros. Sin fecha
+ * la clave es vacía: un montón que existe —el de los que no tienen— y que se
+ * dibuja con las palabras de la copia.
+ */
+export declare function dateKey(when: Date | string | number | null | undefined, grain: GroupGrain): string;
+/**
+ * El RÓTULO de una clave de fecha, en el idioma activo.
+ *
+ * `within` son los granos que los montones de arriba ya dijeron: con el año
+ * arriba, un mes es «Septiembre» y no «Septiembre de 2026». Una clave que no
+ * tiene la forma de su grano se dibuja TAL CUAL —es lo que hace que un montón
+ * contado afuera, con una clave que esta capa no escribió, siga siendo legible
+ * en vez de desaparecer detrás de una fecha inventada.
+ */
+export declare function dateLabel(key: string, grain: GroupGrain, within?: readonly GroupGrain[]): string;
+/** El nombre de un mes —1 a 12— en el idioma activo. Lo usa el que ofrece meses
+ *  sin tener ninguna fecha en la mano, como el recorte por período. */
+export declare function monthName(month: number): string;
+/** Cómo se llama un GRANO —«día», «semana»—, que es distinto de cómo se llama un
+ *  montón suyo: el grano nombra el corte y el rótulo nombra lo cortado. Sale de
+ *  la copia, que es donde ya viven las unidades de tiempo en singular. */
+export declare function grainName(grain: GroupGrain): string;

package/dist/foundations/calendar.js

@@ -0,0 +1,183 @@
+import { currentCopy, currentCopyLocale, fillCopy } from "./copy.js";
+/**
+ * EL CALENDARIO: de una fecha a una CLAVE, y de una clave a un RÓTULO.
+ *
+ * Context: un montón de fecha tiene dos textos y no son el mismo. «2026-09» es
+ * lo que el motor escribe —lo que identifica al montón, lo que se compara con lo
+ * que contó el servidor, lo que se guarda plegado— y «Septiembre» es lo que se
+ * lee. Escribir uno solo obliga a elegir cuál se pierde: con la clave a la vista
+ * la interfaz habla en máquina, y con el rótulo por identidad dos septiembres de
+ * años distintos se funden en un montón que no existe.
+ *
+ * Por eso son dos funciones y no una:
+ *
+ *     dateKey(when, "month")      → «2026-09»     la identidad, en un solo idioma
+ *     dateLabel("2026-09", …)     → «Septiembre»  el rótulo, en el idioma activo
+ *
+ * ── El idioma no se traduce: se PIDE ────────────────────────────────
+ *
+ * Los meses y los días de la semana los dice `Intl` con el `locale` que la copia
+ * tiene puesto, así que no hay acá ninguna tabla de doce meses en español ni en
+ * inglés — ni la habría que escribir para un tercer idioma. Lo único que sí es
+ * copia son la semana y el trimestre, porque ningún calendario los nombra: «W38»
+ * no es una palabra y `Intl` no la tiene.
+ *
+ * ── Un rótulo dice lo que el de arriba NO dijo ──────────────────────
+ *
+ * Un árbol de fechas se lee de arriba hacia abajo, y repetir el año en cada mes
+ * y el mes en cada día llena la sangría de texto que ya está dos renglones más
+ * arriba:
+ *
+ *     2026                        ← el año lo dice una vez
+ *       Septiembre                ← no «Septiembre de 2026»
+ *         Semana 38               ← no «Semana 38 de 2026»
+ *           Martes                ← no «martes, 15 sept 2026»
+ *
+ * De eso se ocupa `within`: los granos que los montones de arriba —del mismo
+ * campo— ya dijeron. Sin nadie arriba, el rótulo se planta solo y dice la fecha
+ * entera, porque un «Martes» suelto no es ningún día.
+ */
+/**
+ * La forma de la clave de cada grano. Es `GroupGrain` entero: un grano que el
+ * calendario no supiera cortar sería un nivel que no parte nada.
+ *
+ * Los rangos van en la expresión y no en un `if` porque `new Date(2026, 12, 1)`
+ * no falla: se corre a enero de 2027. Una clave «2026-13» dibujada como «Enero»
+ * es un mes que nadie contó, y eso es peor que un rótulo ilegible.
+ */
+const KEY_SHAPES = {
+    year: /^(\d{4})$/,
+    quarter: /^(\d{4})-Q([1-4])$/,
+    month: /^(\d{4})-(0[1-9]|1[0-2])$/,
+    week: /^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$/,
+    day: /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/,
+};
+/**
+ * Una fecha recortada a la CLAVE de su grano.
+ *
+ * El texto es el que produce el motor —«2026», «2026-Q3», «2026-09», «2026-W38»,
+ * «2026-09-15»—, y que los dos lados lo escriban igual es lo que deja comparar
+ * un agrupado hecho en el navegador con uno contado a mil kilómetros. Sin fecha
+ * la clave es vacía: un montón que existe —el de los que no tienen— y que se
+ * dibuja con las palabras de la copia.
+ */
+export function dateKey(when, grain) {
+    if (when === null || when === undefined || when === "")
+        return "";
+    const date = when instanceof Date ? when : new Date(when);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    const year = date.getFullYear();
+    const month = date.getMonth() + 1;
+    if (grain === "year")
+        return String(year);
+    if (grain === "quarter")
+        return `${year}-Q${Math.floor(date.getMonth() / 3) + 1}`;
+    if (grain === "month")
+        return `${year}-${pad(month)}`;
+    if (grain === "week") {
+        const [weekYear, week] = isoWeek(date);
+        return `${weekYear}-W${pad(week)}`;
+    }
+    return `${year}-${pad(month)}-${pad(date.getDate())}`;
+}
+/**
+ * El RÓTULO de una clave de fecha, en el idioma activo.
+ *
+ * `within` son los granos que los montones de arriba ya dijeron: con el año
+ * arriba, un mes es «Septiembre» y no «Septiembre de 2026». Una clave que no
+ * tiene la forma de su grano se dibuja TAL CUAL —es lo que hace que un montón
+ * contado afuera, con una clave que esta capa no escribió, siga siendo legible
+ * en vez de desaparecer detrás de una fecha inventada.
+ */
+export function dateLabel(key, grain, within = []) {
+    const copy = currentCopy();
+    if (key === "")
+        return copy.time.noDate;
+    const parts = KEY_SHAPES[grain].exec(key);
+    if (parts === null)
+        return key;
+    const locale = currentCopyLocale();
+    const year = Number(parts[1]);
+    const said = (one) => within.includes(one);
+    if (grain === "year")
+        return String(year);
+    if (grain === "quarter") {
+        const quarter = Number(parts[2]);
+        return said("year")
+            ? fillCopy(copy.calendar.quarter, { n: quarter })
+            : fillCopy(copy.calendar.quarterOfYear, { n: quarter, year });
+    }
+    if (grain === "week") {
+        const week = Number(parts[2]);
+        /* El mes también alcanza: una semana adentro de septiembre ya sabe de qué
+           año es, porque el mes lo dijo. */
+        return said("year") || said("quarter") || said("month")
+            ? fillCopy(copy.calendar.week, { n: week })
+            : fillCopy(copy.calendar.weekOfYear, { n: week, year });
+    }
+    if (grain === "month") {
+        const when = new Date(year, Number(parts[2]) - 1, 1);
+        return capitalized(said("year")
+            ? format(locale, { month: "long" }).format(when)
+            : format(locale, { month: "long", year: "numeric" }).format(when));
+    }
+    const day = Number(parts[3]);
+    const when = new Date(year, Number(parts[2]) - 1, day);
+    /* El 31 de febrero tiene la forma de un día y no es ninguno: `Date` lo corre
+       al 3 de marzo en vez de quejarse, así que se pregunta si volvió el mismo. */
+    if (when.getDate() !== day)
+        return key;
+    /* Adentro de una semana, el día es su NOMBRE: son siete y ninguno se repite,
+       así que «Martes» alcanza y el número de día sería ruido. Afuera no: un
+       «Martes» suelto no dice cuál de los cincuenta y dos. */
+    if (said("week"))
+        return capitalized(format(locale, { weekday: "long" }).format(when));
+    return capitalized(format(locale, {
+        weekday: "long",
+        day: "numeric",
+        month: "short",
+        ...(said("year") ? {} : { year: "numeric" }),
+    }).format(when));
+}
+/** El nombre de un mes —1 a 12— en el idioma activo. Lo usa el que ofrece meses
+ *  sin tener ninguna fecha en la mano, como el recorte por período. */
+export function monthName(month) {
+    return capitalized(format(currentCopyLocale(), { month: "long" }).format(new Date(2000, month - 1, 1)));
+}
+/** Cómo se llama un GRANO —«día», «semana»—, que es distinto de cómo se llama un
+ *  montón suyo: el grano nombra el corte y el rótulo nombra lo cortado. Sale de
+ *  la copia, que es donde ya viven las unidades de tiempo en singular. */
+export function grainName(grain) {
+    return capitalized(currentCopy().dates[grain]);
+}
+/**
+ * El año y la semana ISO de una fecha.
+ *
+ * La semana 1 es la que tiene el primer jueves del año, así que se calcula con
+ * el jueves de la semana del dato: es él quien decide a qué año pertenece, y por
+ * eso una semana de fin de diciembre puede ser la 1 del año siguiente. El año
+ * que sale de acá es el de ESA semana y no el de la fecha.
+ */
+function isoWeek(date) {
+    const thursday = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    thursday.setDate(thursday.getDate() + 3 - ((thursday.getDay() + 6) % 7));
+    const first = new Date(thursday.getFullYear(), 0, 4);
+    const week = 1 +
+        Math.round(((thursday.getTime() - first.getTime()) / 86_400_000 - 3 + ((first.getDay() + 6) % 7)) /
+            7);
+    return [thursday.getFullYear(), week];
+}
+function format(locale, options) {
+    return new Intl.DateTimeFormat(locale, options);
+}
+/** Un rótulo encabeza un montón, y en español `Intl` devuelve «septiembre» con
+ *  minúscula. Se sube la primera letra con el idioma activo, que es el que sabe
+ *  cuál es la mayúscula de esa letra. */
+function capitalized(text) {
+    const first = text.charAt(0);
+    return first === "" ? text : first.toLocaleUpperCase(currentCopyLocale()) + text.slice(1);
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}