@sincpro/web-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SINCPRO S.R.L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# @sincpro/web-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A design system for enterprise web software** — ERPs, back offices, management tools: the
+screens where people spend eight hours a day reading records, filtering lists and filling
+forms. React + Tailwind v4, open source, by [Sincpro](https://github.com/Sincpro-SRL).
+
+Most design systems are built for marketing sites and consumer apps, then stretched over
+business software. This one starts from the other end: dense data, long sessions, keyboard
+users, numbers that must be legible, and screens that are always about _records_.
+
+## The idea
+
+**Every management screen is one of two things: one record, or N records.** That is the
+whole product surface, and the system is organised around it in four levels — each one
+defined by what it _knows_, and each one importing only from the levels below:
+
+| Level           | What it knows                           | Examples                                                |
+| --------------- | --------------------------------------- | ------------------------------------------------------- |
+| **Foundations** | The decisions. No components.           | color, typography, scales, motion, surfaces             |
+| **Primitives**  | Nothing about the screen it is on.      | `Button`, `Field`, `Menu`, `Tag`, `Table`, `Dialog`     |
+| **Components**  | One question of the product, by family. | data tables, search and criteria, record parts, chatter |
+| **Views**       | The two macros, and nothing else.       | `Record` (one) · `List` (N)                             |
+
+If something does not fit one of the two views, it is not a view — it is a component in
+disguise. And if something needs to know what an invoice, a dataset or a customer _is_, it
+does not belong here: that is domain, and it lives in the application.
+
+### Principles
+
+- **Tokens or nothing.** Every color, size and radius comes from `src/tokens.css`. No
+  arbitrary Tailwind values, no hand-written hex, no raw `px`, no raw Tailwind palette — a
+  test enforces it, and every exception is written down with its reason.
+- **Contrast is measured, not guessed.** Each color token carries its WCAG ratio next to it,
+  and a test recomputes it: a number that drifted from its color fails the build.
+- **Two surfaces.** The work happens on a warm light _canvas_; navigation lives on a dark
+  _chrome_. A piece is judged on the surface it will actually live on.
+- **Density is a setting, not a fork.** The same components serve a dense ERP grid and a
+  roomy form (`DensityProvider`).
+- **Language is data.** Interface copy is English by default and replaced as a whole table
+  (`installCopy(SPANISH_COPY)`, `UiCopyProvider`) — never hard-coded in a component.
+- **Accessible by default.** Storybook runs the a11y checks as errors, not warnings.
+
+## Using it
+
+```bash
+yarn add @sincpro/web-ui react react-dom tailwindcss @tanstack/react-table @tanstack/react-virtual
+```
+
+Your bundler must run Tailwind v4 (`@tailwindcss/vite` or `@tailwindcss/postcss`). Then import
+the tokens once — fonts, theme and Tailwind come with it:
+
+```css
+@import "@sincpro/web-ui/tokens.css";
+```
+
+```tsx
+import { Field, installCopy, SPANISH_COPY, TextInput } from "@sincpro/web-ui";
+
+installCopy(SPANISH_COPY); // optional: the interface in Spanish
+
+export function CompanyName({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+}) {
+  return (
+    <Field label="Company name" required>
+      <TextInput value={value} onChange={onChange} />
+    </Field>
+  );
+}
+```
+
+Each level is also its own entry — `@sincpro/web-ui/foundations`, `/primitives`,
+`/components`, `/views` — so what a level offers is one import away.
+
+**React Server Components.** Every module that needs the browser (hooks, context, events)
+starts with `"use client"`, and a test keeps it that way; pure logic (calendar, pivot,
+criteria) stays callable from the server. The views are client components: compose
+`Record` inside a client component of your own.
+
+### Theming (light / dark)
+
+The palettes live in `tokens.css`: the same `--color-*` names, redefined for dark. Components
+never read the theme — they use `bg-surface` / `text-ink` and the cascade resolves them — so
+a screen needs no change to work in both.
+
+- With nothing configured the stylesheet follows `prefers-color-scheme`.
+- `data-theme="dark"` / `"light"` on **any** element forces that palette for everything under it
+  (a light invoice preview inside a dark app works). Portals live under `<html>`, so an app
+  switch writes it there.
+- `ThemeProvider` + `useTheme()` do that write (`"system" | "light" | "dark"`; `"system"`
+  removes the attribute) and `ThemeSwitcher` is the tiny control. Remembering the choice is
+  the app's job (`onChange`).
+
+```tsx
+<ThemeProvider
+  defaultValue="system"
+  onChange={(theme) => localStorage.setItem("theme", theme)}
+>
+  <App /> {/* somewhere: <ThemeSwitcher /> */}
+</ThemeProvider>
+```
+
+Rules a new token must follow: define it in **both** palettes with its contrast on the same line
+(`tests/tokens.test.ts` measures each theme against its own ground, surface and chrome, and fails
+if a light token has no dark twin or the two dark copies drift); the gold stays the primary
+action in both (`on-accent` keeps the text on it dark); never write a colour outside
+`tokens.css`; use `bg-scrim` — not `bg-ink/30` — for a veil. In Storybook the toolbar has a
+theme switch, or open a story with `&globals=theme:dark`.
+
+## Developing it
+
+```bash
+make init        # pre-commit + yarn install
+make dev         # Storybook on :6006 — the living documentation
+make test        # node --test: behaviour, tokens, contrast, client boundaries
+make smoke       # every story opened in headless Chrome: no console errors, no blanks
+make build       # dist/ (JS + .d.ts + tokens.css)
+```
+
+Node 26 (the active LTS) or newer — `nvm use` reads `.nvmrc`. Every operation — local or CI —
+goes through the `Makefile`; run `make` to list the targets.
+
+```text
+src/
+├── tokens.css     the source of every value: color, type, spacing, radii, motion
+├── index.ts       the public surface: the four levels below
+├── foundations/   density, surface, copy, slots, calendar, pivot, xlsx
+├── primitives/    one folder per family: button, field, menu, table, tabs, …
+├── components/    one folder per family: listing, record, search, form, chatter, frame, shell
+└── views/         list (N records) · record (one record)
+stories/           Storybook, by level — and templates/: whole pages built from the public API
+tests/             node --test over the TypeScript sources
+```
+
+`make doctor` rejects an import that climbs a level (a primitive importing a component, a
+component importing a view), so the layering holds without anyone remembering it.
+
+### Iterating with AI
+
+This system is developed together with AI agents, and it is set up for it: the rules an
+agent must follow live in [`AGENTS.md`](./AGENTS.md), the guards that catch what an agent
+gets wrong (tokens, contrast, import direction, client boundaries, stories that blow up)
+run in `make test`, `make doctor` and `make smoke`, and
+while `make dev` runs, Storybook serves an MCP endpoint at `/mcp` so an agent reads the
+stories that already exist instead of guessing them.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and pull requests are welcome — especially
+from people who build business software for a living.
+
+## License
+
+[MIT](./LICENSE) © SINCPRO S.R.L.

package/dist/components/assist/AssistMark.d.ts

@@ -0,0 +1,64 @@
+import { type AssistOrigin, type AssistSource } from "./assist.js";
+import type { ChatterEvent } from "../chatter/Chatter.js";
+import type { ReactNode } from "react";
+/** The robot and the assistant's name: the header of a suggestion, a review, a pending
+ *  state. `children` replaces the name — «Asistente sugiere». */
+export declare function AssistLabel({ children, id }: {
+    children?: ReactNode;
+    id?: string;
+}): import("react").JSX.Element;
+/**
+ * Where the assistant got it: «Fuente: orden de compra PO/2026/0042».
+ *
+ * Context: a value without its source is a value nobody can check, and an unchecked value
+ * from a machine is the one people stop trusting after the first mistake. The source is a
+ * LINK to the record it was read from — with `href` a real `<a>` (middle-click, copy), with
+ * `onOpen` a link the screen answers — so checking it is one press, not a search.
+ */
+export declare function AssistSourceLink({ source }: {
+    source: AssistSource;
+}): import("react").JSX.Element;
+export type AssistMarkProps = {
+    /** When, from what, and who accepted it. Each one that is present is said in the card. */
+    origin?: AssistOrigin;
+};
+/**
+ * The small robot next to a value the assistant set — provenance, after the fact.
+ *
+ * Context: once a suggestion is accepted the value looks like any other, and a week later
+ * nobody remembers whether «30 días» was typed or proposed. The mark keeps that answer next
+ * to the value: its tooltip says «Lo completó el asistente», and pressing it opens WHO
+ * (the assistant, and the person who accepted), WHEN and FROM WHAT — with the source as a
+ * link. It is a popover and not a tooltip because the source is a link, and a tooltip can
+ * never be entered with the keyboard.
+ *
+ * Next to a field, write it in the field's `action`; next to a read value, use
+ * `AssistedValue`.
+ */
+export declare function AssistMark({ origin }: AssistMarkProps): import("react").JSX.Element;
+/** A read value with the assistant's mark after it: a `Record.Facts` value, a table cell. */
+export declare function AssistedValue({ children, origin, }: {
+    /** The value, drawn the way it would be without the mark. */
+    children: ReactNode;
+    origin?: AssistOrigin;
+}): import("react").JSX.Element;
+/**
+ * The assistant's entry in a record's history: the chatter's event, with the robot as its
+ * node, the assistant (and who accepted) as its author, and the source as its detail.
+ *
+ * Context: provenance has two places. The mark answers «where did THIS value come from»
+ * while looking at it; the history answers «what has the assistant done on this record»,
+ * in the order it happened, next to what people did. Same mark in both, so the eye learns
+ * it once.
+ *
+ * Call it when the change happens (in the handler), not at module load: it reads the
+ * installed copy, like the formatters do.
+ */
+export declare function assistEvent({ id, label, at, source, acceptedBy, }: {
+    id: string;
+    /** What happened, in the past: «completó 5 líneas desde la orden de compra». */
+    label: ReactNode;
+    at: Date | string | number;
+    source?: AssistSource;
+    acceptedBy?: string;
+}): ChatterEvent;

package/dist/components/assist/AssistMark.js

@@ -0,0 +1,108 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ASSIST_ICON, } from "./assist.js";
+import { currentCopy, fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { cn, focusRing } from "../../foundations/variants.js";
+import { PopoverTrigger } from "../../primitives/overlay/PopoverTrigger.js";
+import { Tooltip, TooltipTrigger } from "../../primitives/overlay/Tooltip.js";
+import { DateValue } from "../../primitives/value/Fecha.js";
+import { Link } from "react-aria-components";
+/* ==================================================================== *
+ *  THE ASSISTANT'S MARK — how a screen says «this came from the assistant».
+ *
+ *  Three pieces, one look:
+ *
+ *      AssistLabel       the robot and the word «Asistente», in the info tone:
+ *                        the header of anything the assistant proposes
+ *      AssistSourceLink  «Fuente: orden de compra PO/2026/0042», a real link
+ *      AssistMark        the small robot next to a value it SET, which opens
+ *                        who, when and from what
+ *
+ *  ── Why the info tone, and never the gold ───────────────────────────
+ *
+ *  The gold is the ONE main action of a screen (PRINCIPLES §2–3). The assistant
+ *  is not an action, it is a source of information — and `info` already means
+ *  «a fact that changes how you read what is below». It is also never the color
+ *  alone: the robot and the word are always there, so a person who does not tell
+ *  teal from navy still reads «Asistente».
+ *
+ *  ── Why a robot and not sparkles ────────────────────────────────────
+ *
+ *  Sparkles celebrate; a business screen states. «An automated assistant did
+ *  this» is the fact a person needs to weigh a value, and the robot says exactly
+ *  that. The icon lives in `ASSIST_ICON`, so changing it is one line.
+ * ==================================================================== */
+/** The robot and the assistant's name: the header of a suggestion, a review, a pending
+ *  state. `children` replaces the name — «Asistente sugiere». */
+export function AssistLabel({ children, id }) {
+    const copy = useUiCopy();
+    const Icon = ASSIST_ICON;
+    return (_jsxs("span", { id: id, "data-assist": "label", className: "inline-flex shrink-0 items-center gap-1 text-micro font-medium text-info", children: [_jsx(Icon, { className: "size-(--size-icon-sm) shrink-0", strokeWidth: 2, "aria-hidden": true }), children ?? copy.assist.assistant] }));
+}
+/**
+ * Where the assistant got it: «Fuente: orden de compra PO/2026/0042».
+ *
+ * Context: a value without its source is a value nobody can check, and an unchecked value
+ * from a machine is the one people stop trusting after the first mistake. The source is a
+ * LINK to the record it was read from — with `href` a real `<a>` (middle-click, copy), with
+ * `onOpen` a link the screen answers — so checking it is one press, not a search.
+ */
+export function AssistSourceLink({ source }) {
+    const copy = useUiCopy();
+    const goes = source.href !== undefined || source.onOpen !== undefined;
+    return (_jsxs("span", { className: "inline-flex max-w-full min-w-0 items-baseline gap-1 text-micro text-muted", children: [_jsxs("span", { className: "shrink-0", children: [copy.assist.source, ":"] }), goes ? (_jsx(Link, { ...(source.href === undefined ? {} : { href: source.href }), ...(source.onOpen === undefined ? {} : { onPress: source.onOpen }), className: ({ isFocusVisible }) => cn("min-w-0 cursor-pointer truncate rounded-mark text-primary underline-offset-2 hover:underline", focusRing({ isFocusVisible })), children: source.label })) : (_jsx("span", { className: "min-w-0 truncate text-ink", children: source.label }))] }));
+}
+/** The mark's own button. It forwards `ref` and spreads native props, so `PopoverTrigger`
+ *  anchors to it and `TooltipTrigger` names it — the same contract as `IconButton`, in the
+ *  assistant's tone instead of the three an icon button has. */
+function MarkButton({ label, expanded, haspopup, ref, ...native }) {
+    const Icon = ASSIST_ICON;
+    return (_jsxs(TooltipTrigger, { children: [_jsx("button", { ...native, ref: ref, type: "button", "aria-label": label, ...(haspopup === undefined ? {} : { "aria-haspopup": haspopup }), ...(expanded === undefined ? {} : { "aria-expanded": expanded }), "data-assist": "mark", className: "inline-flex size-(--size-control-sm) shrink-0 items-center justify-center rounded-pill text-info transition-colors duration-(--duration-instant) hover:bg-info/10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary", children: _jsx(Icon, { className: "size-(--size-icon-sm)", strokeWidth: 2, "aria-hidden": true }) }), _jsx(Tooltip, { children: label })] }));
+}
+/**
+ * The small robot next to a value the assistant set — provenance, after the fact.
+ *
+ * Context: once a suggestion is accepted the value looks like any other, and a week later
+ * nobody remembers whether «30 días» was typed or proposed. The mark keeps that answer next
+ * to the value: its tooltip says «Lo completó el asistente», and pressing it opens WHO
+ * (the assistant, and the person who accepted), WHEN and FROM WHAT — with the source as a
+ * link. It is a popover and not a tooltip because the source is a link, and a tooltip can
+ * never be entered with the keyboard.
+ *
+ * Next to a field, write it in the field's `action`; next to a read value, use
+ * `AssistedValue`.
+ */
+export function AssistMark({ origin = {} }) {
+    const copy = useUiCopy();
+    return (_jsx(PopoverTrigger, { title: copy.assist.madeBy, placement: "bottom end", trigger: _jsx(MarkButton, { label: copy.assist.madeBy }), children: _jsxs("div", { className: "flex max-w-72 min-w-0 flex-col gap-1.5 text-micro text-muted", children: [origin.source === undefined ? null : _jsx(AssistSourceLink, { source: origin.source }), origin.at === undefined ? null : _jsx(DateValue, { when: origin.at, format: "exact" }), origin.acceptedBy === undefined ? null : (_jsx("span", { children: fillCopy(copy.assist.acceptedBy, { name: origin.acceptedBy }) }))] }) }));
+}
+/** A read value with the assistant's mark after it: a `Record.Facts` value, a table cell. */
+export function AssistedValue({ children, origin, }) {
+    return (_jsxs("span", { className: "inline-flex max-w-full min-w-0 items-center gap-0.5", children: [_jsx("span", { className: "min-w-0 truncate", children: children }), _jsx(AssistMark, { ...(origin === undefined ? {} : { origin }) })] }));
+}
+/**
+ * The assistant's entry in a record's history: the chatter's event, with the robot as its
+ * node, the assistant (and who accepted) as its author, and the source as its detail.
+ *
+ * Context: provenance has two places. The mark answers «where did THIS value come from»
+ * while looking at it; the history answers «what has the assistant done on this record»,
+ * in the order it happened, next to what people did. Same mark in both, so the eye learns
+ * it once.
+ *
+ * Call it when the change happens (in the handler), not at module load: it reads the
+ * installed copy, like the formatters do.
+ */
+export function assistEvent({ id, label, at, source, acceptedBy, }) {
+    const copy = currentCopy();
+    const by = acceptedBy === undefined
+        ? copy.assist.assistant
+        : `${copy.assist.assistant} · ${fillCopy(copy.assist.acceptedBy, { name: acceptedBy })}`;
+    return {
+        id,
+        label,
+        at,
+        by,
+        icon: ASSIST_ICON,
+        ...(source === undefined ? {} : { detail: _jsx(AssistSourceLink, { source: source }) }),
+    };
+}

package/dist/components/assist/AssistPending.d.ts

@@ -0,0 +1,24 @@
+export type AssistPendingProps = {
+    /** What the assistant is doing, in the screen's words: «Leyendo la orden de compra
+     *  PO/2026/0042…». The copy's «El asistente está trabajando…» when absent. */
+    label?: string;
+    /** Stops it. Present = a «Cancelar» next to the sentence. */
+    onCancel?: () => void;
+    /** Skeleton bars under the sentence, standing in for the proposal that is coming —
+     *  `0` (the default) is the one-line form, for under a field. */
+    rows?: number;
+};
+/**
+ * The assistant is working on a suggestion, and the screen goes on.
+ *
+ * Context: the assistant is slower than a form, and a screen that locks while it thinks
+ * teaches people to wait for it — or to close it. So this BLOCKS NOTHING: it is a line in
+ * the place where the suggestion will appear (under a field, above the lines), the fields
+ * stay editable, and «Cancelar» stops it. What the person types in the meantime wins; the
+ * screen decides whether a suggestion that arrives late still makes sense.
+ *
+ * The sentence is a polite live region (`role="status"`), so a screen reader hears that
+ * the assistant started without being interrupted; the bars are silent. The spinner and
+ * the bars' pulse stop under reduced motion, by the global rule in `tokens.css`.
+ */
+export declare function AssistPending({ label, onCancel, rows }: AssistPendingProps): import("react").JSX.Element;

package/dist/components/assist/AssistPending.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AssistLabel } from "./AssistMark.js";
+import { useUiCopy } from "../../foundations/copy.js";
+import { Button } from "../../primitives/button/Button.js";
+import { LoaderCircle } from "lucide-react";
+/** The widths of the skeleton's bars: uneven, so it reads as lines of content and not as
+ *  a striped box. */
+const BAR = ["w-2/3", "w-1/2", "w-3/4", "w-2/5"];
+/**
+ * The assistant is working on a suggestion, and the screen goes on.
+ *
+ * Context: the assistant is slower than a form, and a screen that locks while it thinks
+ * teaches people to wait for it — or to close it. So this BLOCKS NOTHING: it is a line in
+ * the place where the suggestion will appear (under a field, above the lines), the fields
+ * stay editable, and «Cancelar» stops it. What the person types in the meantime wins; the
+ * screen decides whether a suggestion that arrives late still makes sense.
+ *
+ * The sentence is a polite live region (`role="status"`), so a screen reader hears that
+ * the assistant started without being interrupted; the bars are silent. The spinner and
+ * the bars' pulse stop under reduced motion, by the global rule in `tokens.css`.
+ */
+export function AssistPending({ label, onCancel, rows = 0 }) {
+    const copy = useUiCopy();
+    return (_jsxs("div", { "data-assist": "pending", "aria-busy": "true", className: "flex min-w-0 flex-col gap-2", children: [_jsxs("span", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx(LoaderCircle, { className: "size-(--size-icon-sm) shrink-0 animate-spin text-info", strokeWidth: 2, "aria-hidden": true }), _jsx(AssistLabel, {}), _jsx("span", { role: "status", className: "min-w-0 text-micro text-muted", children: label ?? copy.assist.working }), onCancel === undefined ? null : (_jsx(Button, { role: "ghost", size: "sm", onClick: onCancel, children: copy.assist.cancel }))] }), rows <= 0 ? null : (_jsx("span", { "aria-hidden": true, className: "flex flex-col gap-2 pl-5", children: Array.from({ length: rows }, (_, i) => (_jsx("span", { className: `h-3 rounded-control bg-ink/8 motion-safe:animate-pulse ${BAR[i % BAR.length]}` }, i))) }))] }));
+}

package/dist/components/assist/AssistSuggestion.d.ts

@@ -0,0 +1,42 @@
+import { type AssistApply, type AssistSource } from "./assist.js";
+import { type ReactNode } from "react";
+export type AssistSuggestionProps = {
+    /** The proposed value, drawn as it will read once applied: «30 días», «15/11/2026», a
+     *  product with its code. */
+    value: ReactNode;
+    /** Where the assistant got it — a link to the record it read. */
+    source?: AssistSource;
+    /** Applies the value. Return the function that reverts it and the screen gets a
+     *  «Deshacer» notice; the suggestion itself is the screen's to remove. */
+    onAccept: AssistApply;
+    /** «No, gracias»: the screen forgets the suggestion. */
+    onDismiss: () => void;
+    /** The field's name, for the notice after accepting. Inside a `Field` the accessible
+     *  name already takes the field's label; the notice is read elsewhere, so it needs it. */
+    field?: string;
+};
+/**
+ * The assistant proposes a value for ONE field: the customer's payment term, the product of
+ * a scanned line, the due date. It goes right under the control it would change.
+ *
+ * Context: a suggestion has to be noticed and must not be mistaken for the value. So it is
+ * NOT written into the control — a pre-filled field reads as «someone already decided» and
+ * gets saved without a look. It sits under the control, in a dashed box (dashed: proposed,
+ * not yet real), with the robot and «Asistente sugiere», the value, and its source as a
+ * link. «Aceptar» applies it at once, and the notice carries «Deshacer» — undo over
+ * confirm, the system's rule. The × forgets it.
+ *
+ * Written inside a `Field`, after the control:
+ *
+ *     <Field label="Plazo de pago">
+ *       <NumberInput … />
+ *       <AssistSuggestion value="30 días" source={…} onAccept={…} onDismiss={…} />
+ *     </Field>
+ *
+ * It is a group named «Sugerencia del asistente» + the field's label, so a screen reader
+ * hears which field it is about before the value. Both buttons are plain buttons: Tab
+ * reaches them, Enter and Space press them. After pressing either, the focus goes back to
+ * the field's control — the suggestion that held it is gone, and the control is what the
+ * person was working on.
+ */
+export declare function AssistSuggestion({ value, source, onAccept, onDismiss, field, }: AssistSuggestionProps): import("react").JSX.Element;

package/dist/components/assist/AssistSuggestion.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { acceptedMessage, applyWithUndo, } from "./assist.js";
+import { AssistLabel, AssistSourceLink } from "./AssistMark.js";
+import { useUiCopy } from "../../foundations/copy.js";
+import { Button, IconButton } from "../../primitives/button/Button.js";
+import { FieldIdsContext } from "../../primitives/field/context.js";
+import { useToastIfAny } from "../../primitives/notice/Toast.js";
+import { Check, X } from "lucide-react";
+import { useContext, useId } from "react";
+/**
+ * The assistant proposes a value for ONE field: the customer's payment term, the product of
+ * a scanned line, the due date. It goes right under the control it would change.
+ *
+ * Context: a suggestion has to be noticed and must not be mistaken for the value. So it is
+ * NOT written into the control — a pre-filled field reads as «someone already decided» and
+ * gets saved without a look. It sits under the control, in a dashed box (dashed: proposed,
+ * not yet real), with the robot and «Asistente sugiere», the value, and its source as a
+ * link. «Aceptar» applies it at once, and the notice carries «Deshacer» — undo over
+ * confirm, the system's rule. The × forgets it.
+ *
+ * Written inside a `Field`, after the control:
+ *
+ *     <Field label="Plazo de pago">
+ *       <NumberInput … />
+ *       <AssistSuggestion value="30 días" source={…} onAccept={…} onDismiss={…} />
+ *     </Field>
+ *
+ * It is a group named «Sugerencia del asistente» + the field's label, so a screen reader
+ * hears which field it is about before the value. Both buttons are plain buttons: Tab
+ * reaches them, Enter and Space press them. After pressing either, the focus goes back to
+ * the field's control — the suggestion that held it is gone, and the control is what the
+ * person was working on.
+ */
+export function AssistSuggestion({ value, source, onAccept, onDismiss, field, }) {
+    const copy = useUiCopy();
+    const toasts = useToastIfAny();
+    const ids = useContext(FieldIdsContext);
+    const nameId = useId();
+    /* Back to the control once this box is gone. A frame later: the screen removes the
+       suggestion in the same update, and the control is only focusable after it. */
+    const refocus = () => {
+        const target = ids?.id;
+        if (target === undefined || typeof document === "undefined")
+            return;
+        requestAnimationFrame(() => document.getElementById(target)?.focus());
+    };
+    return (_jsxs("div", { role: "group", "aria-labelledby": ids === null ? nameId : `${nameId} ${ids.labelId}`, "data-assist": "suggestion", className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1.5 rounded-control border border-dashed border-info/40 bg-info/5 py-1 pr-1 pl-2.5", children: [_jsx("span", { id: nameId, hidden: true, children: copy.assist.suggestion }), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5 py-0.5", children: [_jsxs("span", { className: "flex min-w-0 flex-wrap items-baseline gap-x-1.5", children: [_jsxs(AssistLabel, { children: [copy.assist.assistant, " ", copy.assist.suggests] }), _jsx("span", { className: "min-w-0 text-meta font-semibold text-ink tabular-nums", children: value })] }), source === undefined ? null : _jsx(AssistSourceLink, { source: source })] }), _jsxs("span", { className: "flex shrink-0 items-center gap-0.5", children: [_jsx(Button, { role: "secondary", size: "sm", icon: Check, onClick: () => {
+                            applyWithUndo(onAccept, toasts, acceptedMessage(copy, field), copy.assist.undo);
+                            refocus();
+                        }, children: copy.assist.accept }), _jsx(IconButton, { icon: X, label: copy.assist.dismiss, onClick: () => {
+                            onDismiss();
+                            refocus();
+                        } })] })] }));
+}

package/dist/components/assist/ChangeReview.d.ts

@@ -0,0 +1,56 @@
+import { type AssistApply, type AssistSource, type ProposedChange } from "./assist.js";
+import { type DialogContext } from "../../primitives/dialog/Dialog.js";
+import { type ReactNode } from "react";
+type GroupProps = {
+    /** «Campos», «Líneas». Without it the changes are listed without a heading. */
+    title?: string;
+    children?: ReactNode;
+};
+type ReviewProps = {
+    /** What the proposal is, as a heading. The copy's «Cambios propuestos» when absent. */
+    title?: string;
+    /** One sentence under the title: what the assistant read and what it would do. */
+    summary?: string;
+    /** Where the whole proposal comes from. A change may carry its own. */
+    source?: AssistSource;
+    /** Applies the chosen changes — their ids, in the listed order. Return the function that
+     *  reverts them, and the screen gets «Deshacer». */
+    onApply: AssistApply<[ids: string[]]>;
+    /** Rejects the proposal. */
+    onDiscard: () => void;
+    /** The chosen ids, controlled. Uncontrolled from «all but the `unchosen` ones». */
+    chosen?: readonly string[];
+    onChosenChange?: (ids: string[]) => void;
+    /** `ChangeReview.Group` and `ChangeReview.Change`. */
+    children?: ReactNode;
+};
+export type ChangeReviewProps = ReviewProps & {
+    /** The role of «Aplicar». `primary` by default; `secondary` inside a record whose rail
+     *  already shows the screen's one primary. */
+    emphasis?: "primary" | "secondary";
+};
+/** The review inside the page: a dashed card in the record it would change. */
+export declare function ChangeReview(props: ChangeReviewProps): import("react").JSX.Element;
+export declare namespace ChangeReview {
+    var Group: ((props: GroupProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"group">;
+    var Change: ((props: ProposedChange) => ReactNode) & import("../../foundations/slots.js").Slotted<"change">;
+}
+export type ChangeReviewDialogProps = ReviewProps & {
+    open: boolean;
+    /** Every way out ends here: ×, Escape, the scrim — «later», the proposal stays — and
+     *  also after «Aplicar» and «Descartar». */
+    onClose: () => void;
+    /** What the dialog is about, in its header: «factura · FAC/2026/0120». */
+    context?: DialogContext;
+};
+/**
+ * The same review, in a `Dialog`: opened on demand — from a notice that says «el asistente
+ * encontró la orden de compra» — and a bottom sheet on a phone. «Aplicar» is the dialog's
+ * primary; closing without choosing keeps the proposal for later.
+ */
+export declare function ChangeReviewDialog(props: ChangeReviewDialogProps): import("react").JSX.Element;
+export declare namespace ChangeReviewDialog {
+    var Group: ((props: GroupProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"group">;
+    var Change: ((props: ProposedChange) => ReactNode) & import("../../foundations/slots.js").Slotted<"change">;
+}
+export {};