@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/primitives/block/Steps.d.ts

@@ -0,0 +1,76 @@
+import type { BlockStatus } from "./Block.js";
+import { type LucideIcon } from "lucide-react";
+import { type ReactNode } from "react";
+/**
+ * Context: a procedure laid flat — every stage of one piece of work on a single
+ * page, each collapsed to its title until you need it.
+ *
+ * ── Why not a `Wizard` ──────────────────────────────────────────────
+ *
+ * A wizard shows one step and hides the rest, which is right when the steps are
+ * a single sitting and wrong when they are the work itself. This is for work
+ * that spans days: you come back to a half-done piece and the first thing you
+ * need is **where it stands** — which stages are settled, which are waiting on
+ * you, which cannot start yet — and a wizard answers that with one screen and a
+ * «back» button.
+ *
+ * ── Why collapsed and not a `Block` per stage ───────────────────────
+ *
+ * `Block` already carries the half of this that matters — a header that says
+ * «Required» or «(Incomplete)» so you can see what is missing WITHOUT opening
+ * anything. What it cannot do is *close*. Seven open blocks is a page nobody
+ * scrolls; seven closed ones with their state on the line is an index of the
+ * work, and that index IS the view.
+ *
+ * ── Locked is a sentence, never a disabled box ──────────────────────
+ *
+ * A stage that cannot start yet says **what would unlock it**, because «you
+ * cannot do this» without «do that first» is the failure mode that makes people
+ * click every section looking for the one that works.
+ */
+export type StepProps = {
+    title: string;
+    /** The stage's own mark, to the left of the title — what the eye finds when
+     *  scanning a closed stack. */
+    icon?: LucideIcon;
+    /** «Required», «(Incomplete)», «(Complete)» — whatever this stage's state is
+     *  called by whoever composes; the kit does not know what complete means. */
+    status?: BlockStatus;
+    /** Present when the stage cannot be opened yet. The sentence says what would
+     *  unlock it, and it is shown in place of the contents. */
+    locked?: string;
+    /** What can be done with this stage, on its header line. Hidden while closed:
+     *  an action you cannot see the context of is an action you press by mistake. */
+    actions?: ReactNode;
+    open: boolean;
+    onToggle: () => void;
+    children: ReactNode;
+};
+/**
+ * One stage. Controlled on purpose: which stage is open is a fact about where
+ * the work stands, so the page owns it — completing one can open the next, and
+ * arriving at a half-done piece can open the one that is waiting.
+ */
+export declare function Step({ title, icon: Icon, status, locked, actions, open, onToggle, children, }: StepProps): import("react").JSX.Element;
+export type StepsProps = {
+    children: ReactNode;
+};
+/** The stack. One frame: the outer corners are the only rounded ones, and the
+ *  stages share a hairline. A box around a box would be two frames arguing. */
+export declare function Steps({ children }: StepsProps): import("react").JSX.Element;
+/**
+ * Which stage is open, when the page has no better answer than «one at a time».
+ *
+ * Returns the current id and a toggle: pressing the open one closes it, so a
+ * fully collapsed stack —the index of the work— is always one click away.
+ *
+ * `openStep` exists for the rail: the button that says what to do next lives up
+ * there with the other actions, and pressing it has to open the stage down here
+ * that does it.
+ */
+export declare function useSteps(initial?: string): {
+    open: string | undefined;
+    isOpen: (id: string) => boolean;
+    toggle: (id: string) => void;
+    openStep: (id: string) => void;
+};

package/dist/primitives/block/Steps.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Tag } from "../tag/Tag.js";
+import { ChevronDown, Lock } from "lucide-react";
+import { useState } from "react";
+/**
+ * One stage. Controlled on purpose: which stage is open is a fact about where
+ * the work stands, so the page owns it — completing one can open the next, and
+ * arriving at a half-done piece can open the one that is waiting.
+ */
+export function Step({ title, icon: Icon, status, locked, actions, open, onToggle, children, }) {
+    const isLocked = locked !== undefined;
+    const expanded = open && !isLocked;
+    return (_jsxs("section", { className: "min-w-0 border-t border-line bg-surface first:border-t-0", children: [_jsx("h3", { className: "min-w-0", children: _jsxs("button", { type: "button", onClick: onToggle, "aria-expanded": expanded, 
+                    /* Open is a ground bar: the stage you are in is the only row with a
+                       fill. Closed rows stay on the paper, so the stack still reads as
+                       an index. */
+                    className: `group/step relative flex w-full min-w-0 items-center px-3 py-2.5 text-left ${expanded ? "border-b border-line bg-ground" : ""} ${isLocked ? "cursor-default" : "cursor-pointer"}`, children: [isLocked ? null : (_jsx("span", { "aria-hidden": true, className: "pointer-events-none absolute inset-x-1 inset-y-0.5 rounded-control group-hover/step:bg-ground" })), _jsxs("span", { className: "relative z-10 flex min-w-0 flex-1 items-center gap-3", children: [Icon === undefined ? null : (_jsx(Icon, { className: `size-(--size-icon-md) shrink-0 ${isLocked ? "text-muted/60" : "text-muted"}`, "aria-hidden": true })), _jsx("span", { className: `min-w-0 truncate text-meta font-medium ${isLocked ? "text-muted" : "text-ink"}`, children: title }), isLocked ? (_jsx(Lock, { className: "size-(--size-icon-sm) shrink-0 text-muted/60", "aria-hidden": true })) : status === undefined ? null : (_jsx(Tag, { tone: status.tone ?? "neutral", children: status.label })), _jsx(ChevronDown, { className: `ml-auto size-(--size-icon-md) shrink-0 text-muted transition-transform ${expanded ? "rotate-180" : ""}`, "aria-hidden": true })] })] }) }), !expanded ? null : (_jsxs("div", { className: "px-3 py-3", children: [actions === undefined ? null : (_jsx("div", { className: "mb-3 flex flex-wrap items-center gap-1", children: actions })), children] })), !isLocked ? null : (_jsx("p", { className: "border-t border-line px-3 py-2 text-micro text-muted", children: locked }))] }));
+}
+/** The stack. One frame: the outer corners are the only rounded ones, and the
+ *  stages share a hairline. A box around a box would be two frames arguing. */
+export function Steps({ children }) {
+    return (_jsx("div", { className: "flex min-w-0 flex-col overflow-hidden rounded-box border border-line bg-surface", children: children }));
+}
+/**
+ * Which stage is open, when the page has no better answer than «one at a time».
+ *
+ * Returns the current id and a toggle: pressing the open one closes it, so a
+ * fully collapsed stack —the index of the work— is always one click away.
+ *
+ * `openStep` exists for the rail: the button that says what to do next lives up
+ * there with the other actions, and pressing it has to open the stage down here
+ * that does it.
+ */
+export function useSteps(initial) {
+    const [open, setOpen] = useState(initial);
+    return {
+        open,
+        isOpen: (id) => open === id,
+        toggle: (id) => setOpen((current) => (current === id ? undefined : id)),
+        openStep: (id) => setOpen(id),
+    };
+}

package/dist/primitives/block/index.d.ts

@@ -0,0 +1,4 @@
+export { Block, type BlockProps, type BlockStatus, Rule, SectionHeader, } from "./Block.js";
+export { FullWidth, SectionGrid } from "./SectionGrid.js";
+export { Line } from "./Line.js";
+export { Step, type StepProps, Steps, type StepsProps, useSteps, } from "./Steps.js";

package/dist/primitives/block/index.js

@@ -0,0 +1,7 @@
+/* The structure of a view: where each section starts and ends. */
+export { Block, Rule, SectionHeader, } from "./Block.js";
+export { FullWidth, SectionGrid } from "./SectionGrid.js";
+/* La línea de tres zonas: lo que centra el centro contra la LÍNEA y no contra
+   lo que sobra. La usan las dos bandas — la del registro y la de la lista. */
+export { Line } from "./Line.js";
+export { Step, Steps, useSteps, } from "./Steps.js";

package/dist/primitives/button/Button.d.ts

@@ -0,0 +1,137 @@
+import type { Surface } from "../../foundations/types.js";
+import type { LucideIcon } from "lucide-react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+export type ButtonRole = "primary" | "secondary" | "ghost" | "danger";
+export type ButtonSize = "sm" | "md" | "lg";
+export type { Surface };
+/** The icon accompanies the label and never replaces it.
+ *
+ *  Size `sm` (12px) on the small button and `md` (16px) on the medium one, with
+ *  the stroke that belongs to each — see the iconography scale: what stays
+ *  constant is the optical weight, not the number. */
+/** The look of a button, without the button.
+ *
+ *  Context: it exists because there are things that LOOK like a button and are
+ *  not — a menu trigger is the case. Without this, each one copies the classes
+ *  and by the third copy they no longer match: that is exactly what happened
+ *  with «＋ Crear», which was the only primary button in the product with a
+ *  different height. */
+export declare function buttonClasses(role?: ButtonRole, size?: ButtonSize, surface?: Surface): string;
+/** What kind of thing a trigger opens. `menu` is the default because it is what the
+ *  `expanded` prop always announced; a `PopoverTrigger` opens a `dialog`, a picker a
+ *  `listbox`. */
+export type ButtonPopup = "menu" | "dialog" | "listbox";
+/** The native attributes a system button lets through.
+ *
+ *  Context: React Aria's triggers (`TooltipTrigger`, `DialogTrigger`, a `Toolbar`) talk to
+ *  the control by handing it a `ref` and DOM props — pointer and focus handlers,
+ *  `aria-describedby`, `aria-expanded`. A button that drops them is a button the tooltip
+ *  never learns was hovered. So everything native goes through, and `ref` is a plain prop
+ *  (React 19).
+ *
+ *  What stays out on purpose: `className` and `style` — the look is the role, the size and
+ *  the surface, and a primitive that takes classes from outside stops being the one place
+ *  where a button is decided; `role`, because here it is the button's ROLE in the hierarchy
+ *  (`primary`…), not an ARIA role; and the attributes the props below already own. */
+type NativeProps<E extends "button" | "a", Own extends string> = Omit<ComponentPropsWithRef<E>, "children" | "className" | "style" | "role" | Own>;
+export type ButtonProps = NativeProps<"button", "type" | "disabled" | "title" | "aria-haspopup" | "aria-expanded"> & {
+    children: ReactNode;
+    role?: ButtonRole;
+    size?: ButtonSize;
+    surface?: Surface;
+    /** To the left of the label. Never alone: a button with only an icon is an
+     *  `IconButton` and has its own piece, with its mandatory `aria-label`. */
+    icon?: LucideIcon;
+    disabled?: boolean;
+    title?: string;
+    /** `submit` for the button that sends the form it is in. `button` by default, so a
+     *  button dropped inside a `<form>` never submits it by accident. */
+    type?: "button" | "submit";
+    /** Context: the button that opens a dropdown has to say so. Without
+     *  `aria-expanded`, a screen reader announces it as an ordinary button and
+     *  whoever uses it does not know there is something open underneath. */
+    expanded?: boolean;
+    /** What it opens, written to `aria-haspopup`. `menu` when absent. */
+    haspopup?: ButtonPopup;
+};
+export declare function Button({ children, role, size, surface: surfaceProp, icon: Icon, disabled, title, type, expanded, haspopup, ref, ...native }: ButtonProps): import("react").JSX.Element;
+export type ButtonLinkProps = NativeProps<"a", "href" | "download" | "title"> & {
+    children: ReactNode;
+    href: string;
+    role?: ButtonRole;
+    size?: ButtonSize;
+    surface?: Surface;
+    icon?: LucideIcon;
+    /** The name it is saved with. `true` lets the server decide it. */
+    download?: string | boolean;
+    title?: string;
+};
+/**
+ * The same button, but it is a real link.
+ *
+ * Context: it exists because a `<button>` that navigates breaks middle-click,
+ * «open in a new tab» and «save as» — and downloading a file is exactly that.
+ * The look is shared entirely with `Button`: two different silhouettes for
+ * «download» and «synthesize» in the same bar is the problem this file exists
+ * in order not to have.
+ *
+ * It does not carry `inline-block`: a flex item gets blockified anyway, and with
+ * that class the `<a>`'s box measured its padding with zero content and the text
+ * was painted on top of its neighbor.
+ */
+export declare function ButtonLink({ children, href, role, size, surface: surfaceProp, icon: Icon, download, title, ref, ...native }: ButtonLinkProps): import("react").JSX.Element;
+/** The `IconButton` is SQUARE: its side is the height of its step. An icon
+ *  button narrower than it is tall has less area than it appears to, and misses
+ *  when you aim right at the edges. */
+export type IconTone = "normal" | "action" | "danger";
+export type IconButtonProps = NativeProps<"button", "type" | "disabled" | "title" | "aria-label" | "aria-haspopup" | "aria-expanded"> & {
+    icon: LucideIcon;
+    /** What is read aloud and shown in the tooltip. It is not optional: an icon
+     *  alone does not say what it does, and whoever knows already knew what to
+     *  press. */
+    label: string;
+    size?: ButtonSize;
+    surface?: Surface;
+    tone?: IconTone;
+    disabled?: boolean;
+    type?: "button" | "submit";
+    /** Opens a menu and says whether it is open. Without this, a screen reader
+     *  announces «button» where there is a dropdown. */
+    expanded?: boolean;
+    /** What it opens, written to `aria-haspopup`. `menu` when absent. */
+    haspopup?: ButtonPopup;
+    /** The system's `Tooltip` with the `label`, on hover and focus. On by default; `false`
+     *  falls back to the native `title`. */
+    tooltip?: boolean;
+};
+/** Only an icon, and that is why the label is mandatory even though it is not
+ *  drawn.
+ *
+ *  It exists because «download» was a grey 11 px `↓` character with no box: the
+ *  most frequent action of a row was the hardest one to hit. Here it has its
+ *  full control height and a background on hover — the target is the same as
+ *  that of a button with text, only without the text. */
+export declare function IconButton({ icon: Icon, label, size, surface: surfaceProp, tone, disabled, type, expanded, haspopup, tooltip, ref, ...native }: IconButtonProps): import("react").JSX.Element;
+export type IconLinkProps = NativeProps<"a", "href" | "download" | "title" | "aria-label"> & {
+    icon: LucideIcon;
+    label: string;
+    href: string;
+    /** The name it is saved with. Present = the browser downloads the file
+     *  instead of navigating. */
+    download?: string;
+    size?: ButtonSize;
+    surface?: Surface;
+    tone?: IconTone;
+    /** As in `IconButton`: the system's `Tooltip` by default, the native `title` with
+     *  `false`. */
+    tooltip?: boolean;
+};
+/**
+ * The same icon, but it is a real link.
+ *
+ * Context: it exists for the same reason as `ButtonLink` — downloading a file or
+ * going to a view is NOT pressing a button. With a `<button>` you lose
+ * middle-click, «copy the address» and the browser's `download`, which is the
+ * only thing that keeps a 150 MB CSV from going through the tab's memory.
+ */
+export declare function IconLink({ icon: Icon, label, href, download, size, surface: surfaceProp, tone, tooltip, ref, ...native }: IconLinkProps): import("react").JSX.Element;

package/dist/primitives/button/Button.js

@@ -0,0 +1,234 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* ==================================================================== *
+ *  BUTTON — DO.
+ *
+ *  The product had THREE contradictory primaries at the same time: a blue
+ *  `+ Crear`, a golden `Registrar pago` and a blue `+ Importar facturas`. Three equal
+ *  weights saying three different things, and therefore no hierarchy at all.
+ *
+ *  The rule that fixes it is four roles and not one more:
+ *
+ *      primary     DO         — solid gold, `ink` on top (6.98:1)
+ *      secondary   do without urgency — a box with an edge
+ *      ghost       goes along — no weight, only the color of «go»
+ *      danger      DESTROY    — and it cannot be undone
+ *
+ *  **Only one solid gold per surface.** `+ Crear` is the chrome's CTA,
+ *  `Registrar pago` the panel's: they do not compete because they do not share a
+ *  surface.
+ *
+ *  ── Why a labeled button is a box, and an icon target is a circle ──
+ *
+ *  `pill` is «what is a capsule and not a box» — a tag, a chip, a counter.
+ *  A labeled button is the opposite: a box that gets pressed. A row of actions
+ *  in capsules reads as a row of tags, and then what has to be pressed and
+ *  what merely informs have the same silhouette. `radius/control` is the step
+ *  for «what is touched and measures one line of text».
+ *
+ *  An icon-only target has no line of text. It is a square hit area, and a
+ *  square with an 8px corner still reads as a leftover box. The circle is the
+ *  silhouette of that target (the same call Spectrum makes for icon-only
+ *  buttons). It does not meet the tag: the tag has text, the circle does not.
+ *
+ *  ── The weight of the type is hierarchy too ─────────────────────────
+ *
+ *  The four roles do NOT carry the same weight, and that is deliberate. The
+ *  primary goes in `semibold` because it is the only thing on the screen that
+ *  has to be seen from far away; the rest in `medium`. Putting all four at the
+ *  same weight forces color to do the whole job of hierarchy by itself — and
+ *  then someone glancing at the screen out of the corner of their eye, or who
+ *  cannot tell the gold from the red apart, sees four identical buttons.
+ *
+ *  ── `surface`: the prop wins, the context is the default ────────────
+ *
+ *  The same piece lives on both surfaces and does NOT behave the same: on the
+ *  canvas, «ghost» is painted with the navigation blue (7.48:1); on the chrome
+ *  that blue gives 1.4:1 and the lightened one has to be used. The band that is
+ *  dark (`AppFrame`'s bar, a `Record.Rail surface="chrome"`) provides its surface
+ *  through `SurfaceProvider`, so a button written inside it takes the right
+ *  palette without remembering to say so — which is how a navy band ends up with
+ *  canvas-colored buttons. The explicit prop still wins, so a one-off decision
+ *  stays auditable by reading the JSX.
+ *
+ *  ── What this file does NOT do ──────────────────────────────────────
+ *
+ *  It does not know what an invoice is, it does not call anything, it has no
+ *  state and it does not write a single value by hand: every height, every
+ *  radius and every color comes from a token. If it needed any of those things,
+ *  it would not be a primitive.
+ * ==================================================================== */
+import { useSurface } from "../../foundations/surface.js";
+import { Tooltip, TooltipTrigger, useInTooltipTrigger, } from "../overlay/Tooltip.js";
+/** The height comes from `--size-control-*`; the padding and the type follow.
+ *
+ *      sm  a row, the header of a block
+ *      md  the working size — the action bar of a record
+ *      lg  a SINGLE, prominent action: a dialog's CTA, an empty state
+ *
+ *  **Every button in the same row measures the same.** `lg` is not «the
+ *  primary»: it is for when the button is alone. Mixing heights in a bar looks
+ *  like an alignment mistake, not like hierarchy — and hierarchy is already
+ *  done by the color and the weight, which work without changing the size of
+ *  anything.
+ *
+ *  The padding grows FASTER than the height (3 → 4 → 6). A tall, narrow button
+ *  reads as a stretched icon; what gives it presence is the air on the sides of
+ *  the label, not the height alone. */
+const SIZE = {
+    sm: "h-(--size-control-sm) px-3 gap-1.5 text-meta",
+    md: "h-(--size-control-md) px-4 gap-2 text-body",
+    lg: "h-(--size-control-lg) px-6 gap-2 text-lead",
+};
+/** The weight per role. See the header note: it is not aesthetics, it is half
+ *  of the hierarchy — the half that keeps working out of the corner of your
+ *  eye. */
+const WEIGHT = {
+    primary: "font-semibold",
+    secondary: "font-medium",
+    ghost: "font-medium",
+    danger: "font-semibold",
+};
+/** Each role on its two surfaces. The table exists so that adding a third
+ *  surface is one column here and not an `if` scattered across the tree — and
+ *  so that the day a combination is missing, the compiler says so. */
+const ROLE = {
+    primary: {
+        // `btn-accent` is the brand gradient, use 3 of 4. Barely a glint of metal:
+        // a strong gradient turns a tool into a landing page.
+        canvas: "btn-accent border border-transparent hover:brightness-[1.04] active:brightness-95",
+        chrome: "btn-accent border border-transparent hover:brightness-[1.04] active:brightness-95",
+    },
+    secondary: {
+        // Quiet on purpose. The blue belongs to `ghost` (go) and the gold to
+        // `primary` (do). A secondary painted in the action color is a second
+        // primary, which is the defect this file exists to stop.
+        canvas: "border border-line-strong bg-ink/6 text-ink hover:bg-ink/10",
+        chrome: "border border-chrome-muted/30 bg-chrome-raised text-chrome-ink hover:bg-chrome-ink/10",
+    },
+    ghost: {
+        canvas: "border border-transparent text-primary hover:bg-primary/8",
+        chrome: "border border-transparent text-chrome-link hover:bg-chrome-ink/8",
+    },
+    danger: {
+        canvas: "border border-transparent bg-danger text-surface hover:bg-danger-hover",
+        chrome: "border border-transparent bg-danger text-surface hover:bg-danger-hover",
+    },
+};
+/** The icon accompanies the label and never replaces it.
+ *
+ *  Size `sm` (12px) on the small button and `md` (16px) on the medium one, with
+ *  the stroke that belongs to each — see the iconography scale: what stays
+ *  constant is the optical weight, not the number. */
+/** The look of a button, without the button.
+ *
+ *  Context: it exists because there are things that LOOK like a button and are
+ *  not — a menu trigger is the case. Without this, each one copies the classes
+ *  and by the third copy they no longer match: that is exactly what happened
+ *  with «＋ Crear», which was the only primary button in the product with a
+ *  different height. */
+export function buttonClasses(role = "secondary", size = "md", surface = "canvas") {
+    return `inline-flex shrink-0 items-center justify-center rounded-control whitespace-nowrap transition-[background-color,border-color,filter,color] duration-(--duration-instant) ease-(--ease-out) disabled:pointer-events-none disabled:opacity-45 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary ${SIZE[size]} ${WEIGHT[role]} ${ROLE[role][surface]}`;
+}
+const ICON = {
+    sm: { size: "size-(--size-icon-sm)", stroke: 2 },
+    md: { size: "size-(--size-icon-md)", stroke: 1.75 },
+    lg: { size: "size-(--size-icon-lg)", stroke: 1.5 },
+};
+/** `aria-haspopup` + `aria-expanded`, only when the button opens something. Spread AFTER the
+ *  native props, and only when it applies, so it never erases what a React Aria trigger
+ *  already wrote. */
+function popupAttrs(expanded, haspopup) {
+    if (expanded === undefined && haspopup === undefined)
+        return {};
+    return {
+        "aria-haspopup": haspopup ?? "menu",
+        ...(expanded === undefined ? {} : { "aria-expanded": expanded }),
+    };
+}
+export function Button({ children, role = "secondary", size = "md", surface: surfaceProp, icon: Icon, disabled = false, title, type = "button", expanded, haspopup, ref, ...native }) {
+    const surface = useSurface(surfaceProp);
+    const ic = ICON[size];
+    return (_jsxs("button", { ...native, ref: ref, type: type, title: title, disabled: disabled, ...popupAttrs(expanded, haspopup), "data-emphasis": role, className: buttonClasses(role, size, surface), children: [Icon === undefined ? null : (_jsx(Icon, { className: `${ic.size} shrink-0`, strokeWidth: ic.stroke, "aria-hidden": true })), children] }));
+}
+/**
+ * The same button, but it is a real link.
+ *
+ * Context: it exists because a `<button>` that navigates breaks middle-click,
+ * «open in a new tab» and «save as» — and downloading a file is exactly that.
+ * The look is shared entirely with `Button`: two different silhouettes for
+ * «download» and «synthesize» in the same bar is the problem this file exists
+ * in order not to have.
+ *
+ * It does not carry `inline-block`: a flex item gets blockified anyway, and with
+ * that class the `<a>`'s box measured its padding with zero content and the text
+ * was painted on top of its neighbor.
+ */
+export function ButtonLink({ children, href, role = "secondary", size = "md", surface: surfaceProp, icon: Icon, download, title, ref, ...native }) {
+    const surface = useSurface(surfaceProp);
+    const ic = ICON[size];
+    return (_jsxs("a", { ...native, ref: ref, "data-emphasis": role, href: href, title: title, ...(download === undefined ? {} : { download }), className: `${buttonClasses(role, size, surface)} no-underline`, children: [Icon === undefined ? null : (_jsx(Icon, { className: `${ic.size} shrink-0`, strokeWidth: ic.stroke, "aria-hidden": true })), children] }));
+}
+/** Outside the component because the button and the link share it: the same
+ *  icon has to look the same whether it leads to an action or to a file. */
+const TONE = {
+    normal: {
+        canvas: "text-muted hover:bg-ink/6 hover:text-ink",
+        chrome: "text-chrome-muted hover:bg-chrome-ink/10 hover:text-chrome-ink",
+    },
+    action: {
+        canvas: "text-primary hover:bg-primary/8",
+        chrome: "text-chrome-link hover:bg-chrome-link/12",
+    },
+    danger: {
+        canvas: "text-danger hover:bg-danger/8",
+        chrome: "text-chrome-bad hover:bg-chrome-bad/12",
+    },
+};
+const BOX = "inline-flex shrink-0 items-center justify-center rounded-pill transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary";
+const SQUARE = {
+    sm: "size-(--size-control-sm)",
+    md: "size-(--size-control-md)",
+    lg: "size-(--size-control-lg)",
+};
+/** The label of an icon, shown.
+ *
+ *  Context: the native `title` was the only way to learn what an icon does, and it is the
+ *  browser's tooltip — late, unstyled, never on keyboard focus. So an icon target draws the
+ *  system's `Tooltip` with its `label` instead, on hover AND on focus, and drops the `title`
+ *  so two tooltips never show at once. `false` brings the `title` back, for the rare icon
+ *  whose name is already written next to it. Inside a `TooltipTrigger` the consumer's
+ *  tooltip wins and this one steps aside. */
+function Labelled({ label, tooltip, children, }) {
+    const wrapped = useInTooltipTrigger();
+    if (wrapped)
+        return children(undefined);
+    if (!tooltip)
+        return children(label);
+    return (_jsxs(TooltipTrigger, { children: [children(undefined), _jsx(Tooltip, { children: label })] }));
+}
+/** Only an icon, and that is why the label is mandatory even though it is not
+ *  drawn.
+ *
+ *  It exists because «download» was a grey 11 px `↓` character with no box: the
+ *  most frequent action of a row was the hardest one to hit. Here it has its
+ *  full control height and a background on hover — the target is the same as
+ *  that of a button with text, only without the text. */
+export function IconButton({ icon: Icon, label, size = "sm", surface: surfaceProp, tone = "normal", disabled = false, type = "button", expanded, haspopup, tooltip = true, ref, ...native }) {
+    const surface = useSurface(surfaceProp);
+    const ic = ICON[size];
+    return (_jsx(Labelled, { label: label, tooltip: tooltip, children: (title) => (_jsx("button", { ...native, ref: ref, type: type, title: title, "aria-label": label, disabled: disabled, ...popupAttrs(expanded, haspopup), className: `${BOX} disabled:pointer-events-none disabled:opacity-45 ${SQUARE[size]} ${TONE[tone][surface]}`, children: _jsx(Icon, { className: ic.size, strokeWidth: ic.stroke, "aria-hidden": true }) })) }));
+}
+/**
+ * The same icon, but it is a real link.
+ *
+ * Context: it exists for the same reason as `ButtonLink` — downloading a file or
+ * going to a view is NOT pressing a button. With a `<button>` you lose
+ * middle-click, «copy the address» and the browser's `download`, which is the
+ * only thing that keeps a 150 MB CSV from going through the tab's memory.
+ */
+export function IconLink({ icon: Icon, label, href, download, size = "sm", surface: surfaceProp, tone = "action", tooltip = true, ref, ...native }) {
+    const surface = useSurface(surfaceProp);
+    const ic = ICON[size];
+    return (_jsx(Labelled, { label: label, tooltip: tooltip, children: (title) => (_jsx("a", { ...native, ref: ref, href: href, ...(download === undefined ? {} : { download }), title: title, "aria-label": label, className: `${BOX} ${SQUARE[size]} ${TONE[tone][surface]}`, children: _jsx(Icon, { className: ic.size, strokeWidth: ic.stroke, "aria-hidden": true }) })) }));
+}

package/dist/primitives/button/index.d.ts

@@ -0,0 +1 @@
+export { Button, buttonClasses, ButtonLink, type ButtonLinkProps, type ButtonPopup, type ButtonProps, type ButtonRole, type ButtonSize, IconButton, type IconButtonProps, IconLink, type IconLinkProps, type IconTone, } from "./Button.js";

package/dist/primitives/button/index.js

@@ -0,0 +1,2 @@
+/* DO. Four roles, three sizes, two surfaces. */
+export { Button, buttonClasses, ButtonLink, IconButton, IconLink, } from "./Button.js";

package/dist/primitives/cell/CellStack.d.ts

@@ -0,0 +1,47 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+/**
+ * A thumbnail — the photo of a product, the logo of a customer — or, when there is none, its
+ * icon on a quiet tile. One size per context so a column of them lines up.
+ *
+ * Context: a list of forty products where only the name tells them apart makes people read
+ * every row; the picture is recognised without reading. The tile without a photo keeps the
+ * same size and place, so the rows that have one and the rows that do not still align.
+ */
+export declare function Thumb({ src, alt, icon: Icon, size, }: {
+    /** The image. Without it, `icon` on a tile; without both, an empty tile. */
+    src?: string;
+    /** What the image shows, for whoever cannot see it. Required with `src`. */
+    alt?: string;
+    icon?: LucideIcon;
+    /** `sm` for a dense row (24 px), `md` for a table (32 px), `lg` for a card (48 px). */
+    size?: "sm" | "md" | "lg";
+}): import("react").JSX.Element;
+/**
+ * A cell with hierarchy: what the row IS on top, what tells it apart below — a product and its
+ * description, a customer and its NIT, an account and its code — with an optional picture.
+ *
+ * Context: a table cell used to hold one string. An ERP row is rarely one thing: a product line
+ * is «Soporte mensual» AND «plan estándar · SKU SOP-01», and putting them in two columns spends
+ * width on a column nobody sorts by, while squeezing them into one string loses the hierarchy.
+ * Two lines, the first in ink and the second small and quiet, read as one thing with a detail —
+ * the way the eye already reads a line of an invoice.
+ *
+ * It works in any cell: `DataTable` (a column's `cell`), `Table`/`Td`, the rows of a list, a
+ * card. The second line wraps or truncates (`wrap`); the first always truncates, with the full
+ * text on hover.
+ */
+export declare function CellStack({ primary, secondary, media, wrap, }: {
+    /** What the row is — the name. In ink, one line. */
+    primary: ReactNode;
+    /** What tells it apart — a description, a code, a reference. Small and quiet. */
+    secondary?: ReactNode;
+    /** A picture or icon on the left: `{ src, alt }` or `{ icon }`. */
+    media?: {
+        src?: string;
+        alt?: string;
+        icon?: LucideIcon;
+    };
+    /** Let the second line wrap (a description) instead of truncating (a code). */
+    wrap?: boolean;
+}): import("react").JSX.Element;

package/dist/primitives/cell/CellStack.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A thumbnail — the photo of a product, the logo of a customer — or, when there is none, its
+ * icon on a quiet tile. One size per context so a column of them lines up.
+ *
+ * Context: a list of forty products where only the name tells them apart makes people read
+ * every row; the picture is recognised without reading. The tile without a photo keeps the
+ * same size and place, so the rows that have one and the rows that do not still align.
+ */
+export function Thumb({ src, alt, icon: Icon, size = "md", }) {
+    const box = { sm: "size-6", md: "size-8", lg: "size-12" }[size];
+    if (src !== undefined) {
+        return (_jsx("img", { src: src, alt: alt ?? "", loading: "lazy", className: `${box} shrink-0 rounded-control bg-ink/5 object-cover` }));
+    }
+    return (_jsx("span", { "aria-hidden": true, className: `${box} flex shrink-0 items-center justify-center rounded-control bg-ink/5 text-muted`, children: Icon === undefined ? null : (_jsx(Icon, { className: size === "lg" ? "size-(--size-icon-lg)" : "size-(--size-icon-sm)", strokeWidth: 1.75 })) }));
+}
+/**
+ * A cell with hierarchy: what the row IS on top, what tells it apart below — a product and its
+ * description, a customer and its NIT, an account and its code — with an optional picture.
+ *
+ * Context: a table cell used to hold one string. An ERP row is rarely one thing: a product line
+ * is «Soporte mensual» AND «plan estándar · SKU SOP-01», and putting them in two columns spends
+ * width on a column nobody sorts by, while squeezing them into one string loses the hierarchy.
+ * Two lines, the first in ink and the second small and quiet, read as one thing with a detail —
+ * the way the eye already reads a line of an invoice.
+ *
+ * It works in any cell: `DataTable` (a column's `cell`), `Table`/`Td`, the rows of a list, a
+ * card. The second line wraps or truncates (`wrap`); the first always truncates, with the full
+ * text on hover.
+ */
+export function CellStack({ primary, secondary, media, wrap = false, }) {
+    return (_jsxs("span", { className: "flex min-w-0 items-center gap-2.5", children: [media === undefined ? null : (_jsx(Thumb, { size: "md", ...(media.src === undefined ? {} : { src: media.src }), ...(media.alt === undefined ? {} : { alt: media.alt }), ...(media.icon === undefined ? {} : { icon: media.icon }) })), _jsxs("span", { className: "flex min-w-0 flex-col", children: [_jsx("span", { className: "truncate text-meta font-medium text-ink", ...(typeof primary === "string" ? { title: primary } : {}), children: primary }), secondary === undefined ? null : (_jsx("span", { className: `text-micro text-muted ${wrap ? "line-clamp-2" : "truncate"}`, ...(typeof secondary === "string" ? { title: secondary } : {}), children: secondary }))] })] }));
+}

package/dist/primitives/cell/index.d.ts

@@ -0,0 +1 @@
+export { CellStack, Thumb } from "./CellStack.js";

package/dist/primitives/cell/index.js

@@ -0,0 +1,3 @@
+/* LOS WIDGETS DE CELDA — lo que va adentro de una celda, una fila o una tarjeta con jerarquía:
+   lo principal en tinta, lo que lo distingue chico y callado, y la foto si la hay. */
+export { CellStack, Thumb } from "./CellStack.js";

package/dist/primitives/choice/ComboBox.d.ts

@@ -0,0 +1,19 @@
+import { type ChoiceOption } from "./options.js";
+import { type FormMode } from "../field/mode.js";
+export type ComboBoxProps = {
+    /** The chosen option's `value`, or `null` when nothing is chosen. */
+    value: string | null;
+    onChange?: (next: string | null) => void;
+    options: readonly ChoiceOption[];
+    placeholder?: string;
+    disabled?: boolean;
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    /** The name of the control when it is NOT inside a `Field` — a cell of an editable table.
+     *  Inside a field, the field's label names it. */
+    "aria-label"?: string;
+    /** Forces the mode. By default it inherits the form's: in read mode it draws the label. */
+    mode?: FormMode;
+};
+export declare function ComboBox({ mode, ...props }: ComboBoxProps): import("react").JSX.Element;