@keboola/design 15.0.0 → 16.0.0

package/AGENTS.md

@@ -10,9 +10,10 @@ Working **on** the package (commands, layer boundary, token surface, the FA→Lu
 
 - **ESM only.** The package ships no CommonJS build — no `*.cjs` and no `require` condition in the `exports` map. Consume it from an ESM-capable bundler (Vite, webpack, Rollup, esbuild) or `import` it from Node. A `require()` resolves to the ESM entry, so it works only where the runtime can require ESM (Node ≥ 22.12) and throws `ERR_REQUIRE_ESM` on older ones.
 - **Always** import from the package root: `import { Button } from '@keboola/design'`.
-- App entry points **must** import styles. Two paths, pick by build setup:
-  - `import '@keboola/design/styles'` — Tailwind-extending consumers. Your PostCSS+Tailwind processes `@tailwind` directives plus design's `dist/` in your content scan. Avoids duplicate preflights/utilities. **Default for any Keboola app.**
-  - `import '@keboola/design/styles/compiled'` — drop-in pre-compiled CSS (~176 KB minified). No Tailwind setup required. Use only when you genuinely cannot run Tailwind.
+- App entry points **must** import styles:
+  - `@import '@keboola/design/styles/compiled'` — design's pre-compiled CSS: component chrome, runtime `--*` tokens, scoped preflight. **Every Keboola app uses this**, after `@keboola/design/theme` and before its own `tailwindcss/utilities.css`, so app utilities win same-specificity ties — copy the entry from `apps/boilerplate/src/index.css`.
+  - `@import '@keboola/design/theme'` — the portable `@theme` tokens, custom utilities and variants, so an app's own Tailwind build can generate `tw:bg-primary`, `tw:scroll-fade-y`, … A token an app authors belongs here, not in design's `styles.css`.
+  - `@keboola/design/styles` — design's Tailwind source entry; no app in this repo imports it.
 - Icons: `import { ChevronDown } from '@keboola/design/icons'`.
 - Code editors: `import { CodeEditor, SqlEditor, MergeEditor } from '@keboola/design/editors'`. These pull the full CodeMirror bundle (~1.3 MB), so they ship from a dedicated subpath — keeping the root barrel CodeMirror-free for apps that don't edit code.
 
@@ -32,8 +33,8 @@ The root barrel (`@keboola/design`) is **not** the whole package. These live onl
 | `@keboola/design/markdown-editor` | `MarkdownEditor`                                                   | Markdown editing — **not** in the root barrel                             |
 | `@keboola/design/rjsf`            | `RjsfSchemaEditor`, `useRootFormData`                              | JSON-Schema-driven config forms (RJSF) — pulls `@rjsf/*` + ajv            |
 | `@keboola/design/testing`         | `renderWithTheme`                                                  | Unit tests that need a component wrapped in `ThemeProvider`               |
-| `@keboola/design/styles`          | Tailwind-extending stylesheet                                      | App entry, Tailwind consumers (**default**)                               |
-| `@keboola/design/styles/compiled` | Pre-compiled CSS (~176 KB)                                         | App entry, when you cannot run Tailwind                                   |
+| `@keboola/design/styles/compiled` | Pre-compiled CSS                                                   | App entry (**default**)                                                   |
+| `@keboola/design/theme`           | Portable `@theme` tokens, utilities, variants                      | App entry, before `styles/compiled`                                       |
 
 ### design ≠ shadcn — API deltas
 

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @keboola/design
 
+## 16.0.0
+
+### Major Changes
+
+- Drops exports no consumer imports.
+  - `@keboola/design`: `UsageStatsRing` and `DIAGRAM_LANGUAGES` are internal; `UsageStats` still renders the ring.
+  - `@keboola/agent-vocabulary`: no `MermaidDiagramIconName` type; `MERMAID_DIAGRAM_ICON_NAMES` stays.
+
+### Minor Changes
+
+- `Badge`'s default `gray` now clears WCAG-AA (6.73:1), so every badge and `Combobox`/`MultiCombobox` chip without an explicit `color` is legible.
+  - **Visible change:** `gray` fills `neutral-500` instead of `neutral-400`, a darker grey in every app.
+  - `gray-darker` fills `neutral-600` (9.02:1) so it stays a step darker than `gray`.
+  - The solid contrast stories assert `gray`, `gray-darker` and the default `Badge`, in both schemes.
+
+- `Button` takes `disabledReason`: it disables the button and shows the reason in a tooltip on hover and focus.
+  - The button stays focusable (`aria-disabled`, not `disabled`), so a keyboard user reaches the reason too.
+  - Clicks and form submits are blocked.
+  - The `not-disabled` variant also skips `aria-disabled="true"`, so a focusable unavailable control no longer lights up on hover.
+  - The `disabled-button-tooltip` recipe is replaced by this prop.
+
+- `FieldItem`, `FieldItemProps` and `useFieldContext` are exported, so an app can write a form connector for a control the package does not ship
+  - Wrap the control in `FieldItem` and bind it with `useFieldContext`, inside `form.AppField`.
+  - For a control that is not a labelable element (`div[role]`, CodeMirror), pass `labelling="aria-labelledby"`.
+
+- Popconfirm splits its footer evenly between Cancel and Confirm, sets its body text at 14/20, is at least 288 px wide, wraps its text at 384 px and widens past that only to fit its buttons, and adds `Popconfirm.Title`, `Popconfirm.Description` and `layout="centered"` on `Popconfirm.Content`
+
+- `TextInput` and `field.TextField` accept `type="url"`
+  - The input renders as `<input type="url">`: URL keyboard on mobile, native URL check on submit.
+
+- `Markdown` and `Markdown.Root` take `headingScale="compact"`: answer-sized headings. The default scale is unchanged.
+
+- `PromptInput` and `PromptInputSubmit` take `sendIcon="arrow-up"` for an upward-arrow send button; the paper plane stays the default.
+
+- `AnswerActions` takes `groupDivider` (a rule between Copy and the votes and the trailing controls) and `timestamp` (the time as a clock's tooltip, not inline). Both are off by default.
+
+- `ChatNotice` takes `bordered={false}` for a notice on a tinted surface; the border stays by default.
+
+- `Markdown` and `Markdown.Block` take `renderCitation`: a `[n]` in running text is drawn as whatever it returns for `n`. Code and links are skipped; without it `[n]` stays text.
+
+### Patch Changes
+
+- `@keboola/design/theme` gives an app's own Tailwind build every custom utility it authors.
+  - `tw:animate-fade`, `tw:scroll-fade`, `tw:scroll-fade-x`, `tw:scroll-fade-y` and `tw:stroke-/fill-aigradient-600/700` generate from the theme.
+  - `tw:duration-brand` sets `--tw-duration`, so it holds alongside `tw:transition`.
+  - `tw:font-display` falls back through the full sans stack.
+  - The compiled stylesheet is otherwise unchanged; design's token scales live in CSS, and its Tailwind config carries prose typography only.
+
+- `RjsfSchemaEditor` propagates a field reverted to the value the form opened with.
+  - The form-data-after-defaults baseline is ignored only until the first value reaches `onChange`.
+  - After that, any edit that differs from `value` reaches `onChange`, including a return to the opened state.
+
+- `Select` can hold an item whose value is `''`, such as an "All" filter option
+  - Selected, that item shows its label in the trigger instead of the placeholder.
+  - Picking it calls `onValueChange('')`.
+  - With no such item, `''` still shows the placeholder.
+  - Not for a natively submitted `<form>` with `name`: the hidden `<select>` sends an internal value for that item, and `required` passes.
+
+- Runtime dependencies require their latest patch and minor releases.
+  - `@keboola/design`: `@rjsf/*` 6.11, `pele` 1.10, `react-resizable-panels` 4.15, `tailwind-merge` 3.7, `vega-lite` 6.5, `@tanstack/react-virtual` 3.14.22, plus patch releases of `dompurify`, `sonner`, `react-day-picker`, `node-diff3` and `@lezer/highlight`.
+  - `@keboola/api-client`: `qs` 6.16.1.
+  - `@keboola/codemirror-lang-sql`: `@lezer/highlight` 1.2.5.
+
+- `SearchInput` and `Search` call the latest handler when a debounced change fires. `Search` now debounces like `SearchInput`: clearing or unmounting drops a pending change, and a controlled `value` no longer overwrites text typed while a change is pending.
+
+- Updated dependencies:
+  - @keboola/brand-registry@3.1.0
+  - @keboola/codemirror-lang-sql@0.7.4
+
+## 15.1.0
+
+### Minor Changes
+
+- `Badge` `color` gains status values — `success`, `warning`, `info`, `destructive`, `neutral`, each with a pastel `-subtle` twin — read from the brand's status tokens, so a status badge re-skins with the brand and follows dark mode. Keep the hue colours for categorical labels. New pastel tokens `bg-<status>-subtle` / `text-<status>-subtle-foreground` back the `-subtle` values; set `--<status>-subtle` / `--<status>-subtle-foreground` to override them. `color="red-inverse"` adds the missing pastel error hue, with a dark-mode pair.
+
+- `useTimeout(callback, delayMs)` runs a callback once after a delay and clears the timer on unmount; a new callback identity does not restart it (UT-5890)
+
+- AIKit: `AttachmentChip` takes `lead` and `label`, `ContextChip` takes `number` and an optional `excerpt` and `onRemove`, `JumpToLatest` takes `tooltip`.
+
+- `PromptInput` takes `shellClassName` for the element around its frame and `onFocusChange`; that element carries `data-focused` while focus is inside.
+
+- `AnswerActions` takes `extraActions` (`{ id, label, icon, onSelect, disabled? }[]`), drawn in the style of copy and thumbs; `actions` stays for a raw node.
+
+- `PromptInput` takes `mentionInsert`: the text a picked `@` mention leaves at the caret, in the same update that removes the token.
+
+### Patch Changes
+
+- Dark mode sits quieter: solid `Badge` colours drop to a deeper rung and `Modal` gets a hairline edge.
+  - `Badge` `green`, `green-darker`, `blue`, `red`, `orange`, `amber`, `teal`, `purple` and `cyan` keep their light fill and take a deeper fill in dark (`green-darker` one rung deeper than `green`), white text where it clears 4.5:1.
+  - `Modal.Content` draws a hairline ring in dark, so its edge no longer depends on the scrim.
+  - `InlineStepLabel` meta text reads `muted-foreground` at full strength, which clears 4.5:1 in dark and reads clearer in light.
+
+- `Modal`, `AlertModal`, `Sheet`, `HoverCard` and the `ZoomableSvg` fullscreen overlay share one layer with `DropdownMenu`, `Popover`, `Select` and `Combobox`: the `z-overlay` utility, backed by the `--z-index-overlay` theme token (`1055`). The one opened last paints on top, so a modal opened from a menu item covers that menu, and anything opened inside a modal sits above it. `Tooltip` (`z-[1060]`) stays above the layer.
+
 ## 15.0.0
 
 ### Major Changes

package/COMPONENT-API.md

@@ -14,13 +14,14 @@ Source: `src/components/Button/Button.tsx`
 
 > Icons are composed as children, not an `icon` prop. Plus all native `<button>` attributes.
 
-| Prop        | Type                                                                                                                  | Required | Default   | Description                                                                                                                 |
-| ----------- | --------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `asChild`   | `boolean`                                                                                                             | no       | `false`   | Render as a Radix `Slot` so the parent JSX (e.g. a `react-router` `<Link>`) becomes the button element.                     |
-| `block`     | `boolean \| null`                                                                                                     | no       | `false`   |                                                                                                                             |
-| `isLoading` | `boolean`                                                                                                             | no       | `false`   | Shows a spinner in place of the leading icon, or before the label when there is none. The caller still controls `disabled`. |
-| `size`      | `"small" \| "medium" \| "large" \| "icon-lg" \| "icon" \| "icon-sm" \| "icon-xs" \| "icon-2xs" \| "icon-3xs" \| null` | no       | `medium`  |                                                                                                                             |
-| `variant`   | `"primary" \| "secondary" \| "kai" \| "danger" \| "outline" \| "invisible" \| "inline" \| null`                       | no       | `primary` |                                                                                                                             |
+| Prop             | Type                                                                                                                  | Required | Default   | Description                                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `asChild`        | `boolean`                                                                                                             | no       | `false`   | Render as a Radix `Slot` so the parent JSX (e.g. a `react-router` `<Link>`) becomes the button element.                     |
+| `block`          | `boolean \| null`                                                                                                     | no       | `false`   |                                                                                                                             |
+| `disabledReason` | `ReactNode`                                                                                                           | no       | —         | Disables the button and shows this on hover and focus; the button stays focusable.                                          |
+| `isLoading`      | `boolean`                                                                                                             | no       | `false`   | Shows a spinner in place of the leading icon, or before the label when there is none. The caller still controls `disabled`. |
+| `size`           | `"small" \| "medium" \| "large" \| "icon-lg" \| "icon" \| "icon-sm" \| "icon-xs" \| "icon-2xs" \| "icon-3xs" \| null` | no       | `medium`  |                                                                                                                             |
+| `variant`        | `"primary" \| "secondary" \| "kai" \| "danger" \| "outline" \| "invisible" \| "inline" \| null`                       | no       | `primary` |                                                                                                                             |
 
 ### `ButtonInline`
 
@@ -89,22 +90,22 @@ Source: `src/blocks/TextInput/TextInput.tsx`
 
 > Bare input. Plus all native `<input>` attributes.
 
-| Prop                 | Type                                                            | Required | Default   | Description                                                                                      |
-| -------------------- | --------------------------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------ |
-| `allowClear`         | `boolean`                                                       | no       | `false`   |                                                                                                  |
-| `defaultValue`       | `string \| null`                                                | no       | —         |                                                                                                  |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | `default` |                                                                                                  |
-| `leftSuffix`         | `ReactNode`                                                     | no       | `null`    |                                                                                                  |
-| `onClear`            | `(() => void)`                                                  | no       | —         |                                                                                                  |
-| `onValueBlur`        | `((value: string) => void)`                                     | no       | —         | Receives the string value; `onBlur` gets the raw event.                                          |
-| `onValueChange`      | `((value: string) => void)`                                     | no       | —         | Receives the string value; `onChange` gets the raw event.                                        |
-| `prefix`             | `ReactNode`                                                     | no       | `null`    |                                                                                                  |
-| `rightSuffix`        | `ReactNode`                                                     | no       | `null`    | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`). |
-| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | `default` |                                                                                                  |
-| `state`              | `"warning" \| "error" \| "default" \| null`                     | no       | `default` |                                                                                                  |
-| `testId`             | `string`                                                        | no       | —         |                                                                                                  |
-| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | `text`    |                                                                                                  |
-| `value`              | `string \| null`                                                | no       | —         |                                                                                                  |
+| Prop                 | Type                                                                     | Required | Default   | Description                                                                                      |
+| -------------------- | ------------------------------------------------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `allowClear`         | `boolean`                                                                | no       | `false`   |                                                                                                  |
+| `defaultValue`       | `string \| null`                                                         | no       | —         |                                                                                                  |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                                     | no       | `default` |                                                                                                  |
+| `leftSuffix`         | `ReactNode`                                                              | no       | `null`    |                                                                                                  |
+| `onClear`            | `(() => void)`                                                           | no       | —         |                                                                                                  |
+| `onValueBlur`        | `((value: string) => void)`                                              | no       | —         | Receives the string value; `onBlur` gets the raw event.                                          |
+| `onValueChange`      | `((value: string) => void)`                                              | no       | —         | Receives the string value; `onChange` gets the raw event.                                        |
+| `prefix`             | `ReactNode`                                                              | no       | `null`    |                                                                                                  |
+| `rightSuffix`        | `ReactNode`                                                              | no       | `null`    | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`). |
+| `rightSuffixVariant` | `"default" \| "addon"`                                                   | no       | `default` |                                                                                                  |
+| `state`              | `"warning" \| "error" \| "default" \| null`                              | no       | `default` |                                                                                                  |
+| `testId`             | `string`                                                                 | no       | —         |                                                                                                  |
+| `type`               | `"text" \| "url" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | `text`    |                                                                                                  |
+| `value`              | `string \| null`                                                         | no       | —         |                                                                                                  |
 
 ### `PasswordInput`
 
@@ -158,21 +159,21 @@ Source: `src/blocks/FormGroup/FormGroupTextInput.tsx`
 
 > NO `error` prop — error styling comes from the parent `FormGroup state="error"` via context. `state` is omitted from the surface for the same reason. Plus native `<input>` attributes.
 
-| Prop                 | Type                                                            | Required | Default | Description                                                                                      |
-| -------------------- | --------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
-| `allowClear`         | `boolean`                                                       | no       | —       |                                                                                                  |
-| `defaultValue`       | `string \| null`                                                | no       | —       |                                                                                                  |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | —       |                                                                                                  |
-| `leftSuffix`         | `ReactNode`                                                     | no       | —       |                                                                                                  |
-| `onClear`            | `(() => void)`                                                  | no       | —       |                                                                                                  |
-| `onValueBlur`        | `((value: string) => void)`                                     | no       | —       | Receives the string value; `onBlur` gets the raw event.                                          |
-| `onValueChange`      | `((value: string) => void)`                                     | no       | —       | Receives the string value; `onChange` gets the raw event.                                        |
-| `prefix`             | `ReactNode`                                                     | no       | —       |                                                                                                  |
-| `rightSuffix`        | `ReactNode`                                                     | no       | —       | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`). |
-| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | —       |                                                                                                  |
-| `testId`             | `string`                                                        | no       | —       |                                                                                                  |
-| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                                  |
-| `value`              | `string \| null`                                                | no       | —       |                                                                                                  |
+| Prop                 | Type                                                                     | Required | Default | Description                                                                                      |
+| -------------------- | ------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `allowClear`         | `boolean`                                                                | no       | —       |                                                                                                  |
+| `defaultValue`       | `string \| null`                                                         | no       | —       |                                                                                                  |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                                     | no       | —       |                                                                                                  |
+| `leftSuffix`         | `ReactNode`                                                              | no       | —       |                                                                                                  |
+| `onClear`            | `(() => void)`                                                           | no       | —       |                                                                                                  |
+| `onValueBlur`        | `((value: string) => void)`                                              | no       | —       | Receives the string value; `onBlur` gets the raw event.                                          |
+| `onValueChange`      | `((value: string) => void)`                                              | no       | —       | Receives the string value; `onChange` gets the raw event.                                        |
+| `prefix`             | `ReactNode`                                                              | no       | —       |                                                                                                  |
+| `rightSuffix`        | `ReactNode`                                                              | no       | —       | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`). |
+| `rightSuffixVariant` | `"default" \| "addon"`                                                   | no       | —       |                                                                                                  |
+| `testId`             | `string`                                                                 | no       | —       |                                                                                                  |
+| `type`               | `"text" \| "url" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                                  |
+| `value`              | `string \| null`                                                         | no       | —       |                                                                                                  |
 
 ### `FormGroup.Help`
 
@@ -198,28 +199,28 @@ Source: `src/blocks/Form/connectors/TextField.tsx`
 
 > Value/onChange/onBlur/id/name are wired from the field — do not pass them. Forwards remaining `FormGroup.TextInput` props.
 
-| Prop                 | Type                                                            | Required | Default | Description                                                                                                                                              |
-| -------------------- | --------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`             | `ReactNode`                                                     | no       | —       | Trailing node on the label row (e.g. a `Link`); not part of the accessible name.                                                                         |
-| `allowClear`         | `boolean`                                                       | no       | —       |                                                                                                                                                          |
-| `aria-describedby`   | `string`                                                        | no       | —       | Identifies the element (or elements) that describes the object. @see aria-labelledby                                                                     |
-| `className`          | `string`                                                        | no       | —       |                                                                                                                                                          |
-| `defaultValue`       | `string \| null`                                                | no       | —       |                                                                                                                                                          |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | —       |                                                                                                                                                          |
-| `help`               | `ReactNode`                                                     | no       | —       |                                                                                                                                                          |
-| `label`              | `ReactNode`                                                     | no       | —       |                                                                                                                                                          |
-| `leftSuffix`         | `ReactNode`                                                     | no       | —       |                                                                                                                                                          |
-| `onClear`            | `(() => void)`                                                  | no       | —       |                                                                                                                                                          |
-| `onValueBlur`        | `((value: string) => void)`                                     | no       | —       | Receives the string value; `onBlur` gets the raw event.                                                                                                  |
-| `onValueChange`      | `((value: string) => void)`                                     | no       | —       | Receives the string value; `onChange` gets the raw event.                                                                                                |
-| `prefix`             | `ReactNode`                                                     | no       | —       |                                                                                                                                                          |
-| `required`           | `boolean`                                                       | no       | —       |                                                                                                                                                          |
-| `requiredMark`       | `RequiredMark`                                                  | no       | —       | Gated by `required`: `'required'` shows `*` only if required, `'optional'` shows `(optional)` only if not, `'hidden'` neither. Defaults to `'required'`. |
-| `rightSuffix`        | `ReactNode`                                                     | no       | —       | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`).                                                         |
-| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | —       |                                                                                                                                                          |
-| `testId`             | `string`                                                        | no       | —       |                                                                                                                                                          |
-| `tooltip`            | `ReactNode`                                                     | no       | —       |                                                                                                                                                          |
-| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                                                                                          |
+| Prop                 | Type                                                                     | Required | Default | Description                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`             | `ReactNode`                                                              | no       | —       | Trailing node on the label row (e.g. a `Link`); not part of the accessible name.                                                                         |
+| `allowClear`         | `boolean`                                                                | no       | —       |                                                                                                                                                          |
+| `aria-describedby`   | `string`                                                                 | no       | —       | Identifies the element (or elements) that describes the object. @see aria-labelledby                                                                     |
+| `className`          | `string`                                                                 | no       | —       |                                                                                                                                                          |
+| `defaultValue`       | `string \| null`                                                         | no       | —       |                                                                                                                                                          |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                                     | no       | —       |                                                                                                                                                          |
+| `help`               | `ReactNode`                                                              | no       | —       |                                                                                                                                                          |
+| `label`              | `ReactNode`                                                              | no       | —       |                                                                                                                                                          |
+| `leftSuffix`         | `ReactNode`                                                              | no       | —       |                                                                                                                                                          |
+| `onClear`            | `(() => void)`                                                           | no       | —       |                                                                                                                                                          |
+| `onValueBlur`        | `((value: string) => void)`                                              | no       | —       | Receives the string value; `onBlur` gets the raw event.                                                                                                  |
+| `onValueChange`      | `((value: string) => void)`                                              | no       | —       | Receives the string value; `onChange` gets the raw event.                                                                                                |
+| `prefix`             | `ReactNode`                                                              | no       | —       |                                                                                                                                                          |
+| `required`           | `boolean`                                                                | no       | —       |                                                                                                                                                          |
+| `requiredMark`       | `RequiredMark`                                                           | no       | —       | Gated by `required`: `'required'` shows `*` only if required, `'optional'` shows `(optional)` only if not, `'hidden'` neither. Defaults to `'required'`. |
+| `rightSuffix`        | `ReactNode`                                                              | no       | —       | `rightSuffixVariant="addon"` truncates it; the ellipsis needs inline content (text or `<span>`).                                                         |
+| `rightSuffixVariant` | `"default" \| "addon"`                                                   | no       | —       |                                                                                                                                                          |
+| `testId`             | `string`                                                                 | no       | —       |                                                                                                                                                          |
+| `tooltip`            | `ReactNode`                                                              | no       | —       |                                                                                                                                                          |
+| `type`               | `"text" \| "url" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                                                                                          |
 
 ### `field.PasswordField`
 
@@ -748,7 +749,7 @@ Source: `src/blocks/EmptyState/EmptyState.tsx`
 
 Source: `src/components/Popconfirm/Popconfirm.tsx`
 
-> Lightweight inline confirmation anchored to its trigger. Compound: `Popconfirm.Trigger`, `Popconfirm.Content`, `Popconfirm.Body`, `Popconfirm.Footer`, `Popconfirm.Confirm`, `Popconfirm.Cancel`.
+> Lightweight inline confirmation anchored to its trigger. Compound: `Popconfirm.Trigger`, `Popconfirm.Content` (`layout="centered"` centres the body), `Popconfirm.Body`, `Popconfirm.Title`, `Popconfirm.Description`, `Popconfirm.Footer`, `Popconfirm.Confirm`, `Popconfirm.Cancel`.
 
 | Prop            | Type                                                                            | Required | Default        | Description |
 | --------------- | ------------------------------------------------------------------------------- | -------- | -------------- | ----------- |