@godxjp/ui 19.0.0 → 19.2.0

package/dist/props/components/charts.prop.d.ts

@@ -72,9 +72,8 @@ export type CompactBarTrendProp = {
     /** Plot-height tier — `xs|sm|md|lg`. Defaults to `xs` (dashboard summary-card density). */
     size?: SizeProp;
     /**
-     * Index of the emphasized ("current") bar. Negative counts from the end
-     * (`-1` = the latest datum); out of range = no emphasis. Never colour-only —
-     * the emphasized row is annotated in the screen-reader text alternative.
+     * Index of the emphasized ("current") bar. Negative counts from the end (`-1` = the latest
+     * datum); out of range = no emphasis.
      */
     emphasizedIndex?: number;
     /** Render the category tick labels under the plot. */

package/dist/props/components/data-display.prop.d.ts

@@ -1,5 +1,31 @@
 /** Data Display component prop types — @see docs/COMPONENTS.md#data-display */
 import type * as React from "react";
+/** @see CodeBlock — a block of preformatted text (request bodies, logs, snippets). */
+export type CodeBlockProp = {
+    /** The text. Pass a string; a highlighter's spans also work. */
+    children?: ChildrenProp;
+    /** Soft-wrap long lines (default true). `false` scrolls horizontally instead. */
+    wrap?: boolean;
+    /** Scroll inside the block past this height. Default `none` (grows with the content). */
+    maxHeight?: "sm" | "md" | "lg" | "none";
+    /** Type size. Default `sm`. */
+    size?: Extract<SizeProp, "xs" | "sm">;
+    /** Cosmetic: lands on `data-language`; no highlighter is bundled. */
+    language?: string;
+    className?: ClassNameProp;
+};
+/**
+ * @see Prose — typography for rendered content (Markdown, CMS bodies). Styles descendant semantic
+ * HTML from the tokens; it has no opinion about where the HTML comes from.
+ */
+export type ProseProp = {
+    /** Body size. `md` is the page body size; `sm` is the compact step. Default `md`. */
+    size?: Extract<SizeProp, "sm" | "md">;
+    /** `fit` scales images to the column (default); `original` shows them at their authored size. */
+    imageSize?: "fit" | "original";
+    className?: ClassNameProp;
+    children?: ChildrenProp;
+};
 import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp } from "../vocabulary/index.js";
 /** @see EmptyState */
 /**
@@ -15,26 +41,14 @@ export type EmptyStateProp = {
     action?: ActionProp;
     /** Visual weight appropriate to the empty condition. Default `page`. */
     variant?: "page" | "section" | "compact";
-    /**
-     * Medallion colour intent. Default `muted` (the neutral placeholder look). Set `success` for a
-     * confirmation zero-state (e.g. device approved), or `warning`/`destructive`/`info` to match the
-     * condition — tints the icon foreground + medallion fill from the matching role token, so a
-     * consumer never hand-rolls a `.ui-success-state` class to recolour it.
-     */
+    /** Medallion colour intent. Default `muted` (the neutral placeholder look). */
     tone?: EmptyStateToneProp;
-    /**
-     * Semantic heading level (`h1`–`h4`) for the title. Default `3`. Choose it to
-     * keep the page outline valid (`h1 → h2 → h3`, no skipped levels), NOT for
-     * visual size — the title size is fixed by `--empty-state` styles regardless
-     * of level. A page/onboarding empty state directly under a page `h1` uses
-     * `titleLevel={2}`; an empty state nested in an already-`h2` section uses `3`.
-     */
+    /** Semantic heading level (`h1`–`h4`) for the title. Default `3`. */
     titleLevel?: HeadingLevelProp;
     /**
-     * Render the title as a non-heading element (`p` / `div`) instead of a
-     * heading. Use for a `compact`/`section` empty state placed inside a section
-     * that already owns its heading, so the zero-state message is not announced as
-     * a heading and cannot skip an outline level. Overrides `titleLevel`.
+     * Render the title as a non-heading element (`p` / `div`) instead of a heading. Use for a
+     * `compact`/`section` empty state placed inside a section that already owns its heading, so the
+     * zero-state message is not announced as a heading and cannot skip an outline level.
      */
     titleAs?: "h1" | "h2" | "h3" | "h4" | "p" | "div";
     className?: ClassNameProp;
@@ -75,13 +89,8 @@ export type AvatarProp = React.ComponentPropsWithoutRef<"span"> & {
     /**
      * Presence — WHO is reachable right now, drawn as an indicator at the block-end/inline-end
      * corner of the mark with a localized `sr-only` label folded into the avatar's accessible text.
-     * Never colour alone (WCAG 1.4.1): each value also has its own silhouette (filled · half-filled ·
-     * barred · hollow).
-     *
-     * OMIT the prop entirely for an entity that has no presence concept (an organization mark, a
-     * capability medallion) — an absent prop emits no node and no attribute, so the DOM stays
-     * byte-identical to today's. Pass `"offline"` for a person KNOWN to be unreachable; that is a
-     * different statement, exactly as `ListRow`'s omitted vs `false` `unread` is.
+     * Never colour alone (WCAG 1.4.1): each value also has its own silhouette (filled · half-filled
+     * · barred · hollow).
      */
     presence?: AvatarPresenceProp;
     /**
@@ -149,15 +158,9 @@ export type CredentialRevealTone = Extract<ToneProp, "warning" | "destructive" |
 export type CredentialRevealProp = {
     /** The one-time secret value shown masked by default and copied verbatim. */
     secret: string;
-    /**
-     * Accessible name / caption for the secret (e.g. "API key", "デバイス資格情報"). When set it labels
-     * the secret region; when omitted a generic localized label is used.
-     */
+    /** Accessible name / caption for the secret (e.g. "API key", "デバイス資格情報"). */
     label?: LabelProp;
-    /**
-     * Caution banner copy. Defaults to the localized "shown only once" warning. Pass `null` to
-     * suppress the banner entirely (e.g. when the surrounding Dialog already carries the caution).
-     */
+    /** Caution banner copy. Defaults to the localized "shown only once" warning. */
     warning?: React.ReactNode | null;
     /** Controlled reveal state (masked ↔ shown). */
     revealed?: boolean;
@@ -213,43 +216,31 @@ export type DataTableProp<T> = {
     loading?: boolean;
     empty?: React.ReactNode;
     /**
-     * Failure state (#216). `true` = built-in localized message (with a retry when `onRetry` is
-     * given); any other node replaces it. `false`/`undefined` = the read succeeded.
+     * `true` = built-in localized message (with a retry when `onRetry` is given); any other node
+     * replaces it. `false`/`undefined` = the read succeeded.
      */
     error?: React.ReactNode;
-    /**
-     * Permission-denied state (#216) — refused, not failed. `true` = built-in localized message
-     * with NO retry. Takes precedence over `error`.
-     */
+    /** `true` = built-in localized message with NO retry. Takes precedence over `error`. */
     denied?: React.ReactNode;
     /** Retry handler surfaced by the built-in `error` state. */
     onRetry?: HandlerProp;
     /**
-     * Named collection contract (gh#253) — the SAME preset the `Table` primitive owns, forwarded to
-     * the table DataTable renders. `"default"` (the default) emits no attribute and matches no
-     * selector. `"action-collection"` is the canonical dense approval / action queue: below
-     * `collapseBelow` the desktop intrinsic column widths give way to the token-owned column-PRIORITY
-     * measures (`--table-action-collection-*`) under `table-layout: fixed`, cells wrap, and the
-     * surface drops its `--table-surface-min-inline-size` floor — so every column, row actions
-     * included, stays inside a 390px frame with no horizontal scroll. Mark each column with
+     * `"default"` (the default) emits no attribute and matches no selector. Mark each column with
      * `priority` on its `ColumnDef`.
      */
     preset?: TablePresetProp;
     /**
-     * Container step at which `preset="action-collection"` switches to the compact priority measures.
-     * Measured against the TABLE's own container (a container query), not the viewport, so a table in
-     * a master rail collapses before the page does. Default `"sm"`. Ignored while `preset` is
-     * `"default"`.
+     * Container step at which `preset="action-collection"` switches to the compact priority
+     * measures. Default `"sm"`.
      */
     collapseBelow?: BreakpointProp;
     className?: ClassNameProp;
     children?: ChildrenProp;
 };
 /**
- * ListRow geometry — `default` (the roomy entity row) or `compact` (#246: the inline-actions row —
- * Avatar + title/description + one or two small trailing Buttons on ONE line inside a narrow card).
- * A ListRow-LOCAL subset of the shared density vocabulary: the row has no `comfortable` step, so it
- * is deliberately narrower than `DensityProp` (and unrelated to `PageDensityProp`/`TableDensityProp`).
+ * A ListRow-LOCAL subset of the shared density vocabulary: the row has no `comfortable` step, so
+ * it is deliberately narrower than `DensityProp` (and unrelated to
+ * `PageDensityProp`/`TableDensityProp`).
  */
 export type ListRowDensityProp = Exclude<DensityProp, "comfortable">;
 /** @see ListRow */
@@ -266,11 +257,8 @@ export type ListRowProp = {
     trailing?: React.ReactNode;
     /** Cross-axis alignment of the columns — `center` (default) or `start` for multi-line content. */
     align?: "center" | "start";
-    /** How over-long title/description resolve — `truncate` (default) or `wrap` (#224). */
     overflow?: "truncate" | "wrap";
-    /** Row geometry — `default` or the compact inline-actions preset (#246). */
     density?: ListRowDensityProp;
-    /** Read/unread state — indicator dot + localized `sr-only` text, never colour alone (#225). */
     unread?: boolean;
     className?: ClassNameProp;
 };
@@ -315,8 +303,7 @@ export type PermissionMatrixProp = {
     grants: PermissionMatrixGrantsProp;
     /**
      * Grant toggle handler. Its PRESENCE makes the matrix editable (checkbox cells); omitted, the
-     * matrix is the canonical read-only ✓/— grid. Locked roles and `readOnly` stay read-only
-     * regardless.
+     * matrix is the canonical read-only ✓/— grid.
      */
     onGrantChange?: (roleId: string, permissionId: string, granted: boolean) => void;
     /** Force the read-only grid even when `onGrantChange` is present (e.g. viewer permission). */
@@ -331,7 +318,6 @@ export type PermissionMatrixProp = {
     loading?: boolean;
     /** Custom empty content when `permissions` is empty; defaults to a localized EmptyState. */
     empty?: React.ReactNode;
-    /** Failure state (mirrors DataTable #216): `true` = built-in localized message, node = replace. */
     error?: React.ReactNode;
     /** Permission-denied state — refused, not failed. Takes precedence over `error`. */
     denied?: React.ReactNode;
@@ -341,25 +327,15 @@ export type PermissionMatrixProp = {
     id?: IdProp;
 };
 /**
- * Edge the ScrollArea viewport sticks to as its content grows (gh#311).
- *
- * - `none` — the scroll offset is left entirely alone. This is the default and is exactly the
- *   behaviour a ScrollArea has always had.
- * - `bottom` — a live stream (chat, log tail, streaming response, activity feed). While the reader
- *   is within `anchorOffset` of the bottom, arriving content keeps the newest item in view; once
- *   they scroll away to read history, growth NEVER moves them, and content inserted ABOVE the
- *   read position is compensated so the item under their eyes stays put.
+ * This is the default and is exactly the behaviour a ScrollArea has always had. - `bottom` — a
+ * live stream (chat, log tail, streaming response, activity feed).
  */
 export type ScrollAreaAnchorProp = "none" | "bottom";
 /** @see ScrollArea */
 export type ScrollAreaProp = {
     /**
      * Ref to the element that actually SCROLLS — the Radix viewport — not the root. The root is
-     * `overflow: hidden` and never scrolls, so the component's own `ref` cannot serve. Use this to
-     * read `scrollTop`/`scrollHeight`, call `scrollTo()`, restore a saved position, or drive a
-     * "jump to newest" button. It is the typed, supported alternative to querying the Radix-internal
-     * `[data-radix-scroll-area-viewport]` attribute, which is not a public contract and is ambiguous
-     * the moment two ScrollAreas nest.
+     * `overflow: hidden` and never scrolls, so the component's own `ref` cannot serve.
      */
     viewportRef?: React.Ref<HTMLDivElement>;
     /** Edge the viewport sticks to as content grows. Default `none` (inert). */

package/dist/props/components/data-entry.prop.d.ts

@@ -42,7 +42,6 @@ export type TextareaProp = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
     onClear?: () => void;
     /** `ghost` drops the field's own border/background/ring for a textarea inside a surface that already draws the box. */
     variant?: "default" | "ghost";
-    /** Grow the box with its content between `minRows` and `maxRows` instead of a fixed `rows` height (default false). */
     autoGrow?: boolean;
     /** Floor in text rows while `autoGrow`; never undercuts the `--control-height` tier. */
     minRows?: number;
@@ -72,9 +71,9 @@ export type NumberInputProp = FieldA11yProps & {
     readOnly?: boolean;
     size?: SizeProp;
     placeholder?: PlaceholderProp;
-    /** Leading affix inside the field (e.g. `¥`). Decorative — `aria-hidden`. */
+    /** Leading affix inside the field (e.g. `¥`). */
     prefix?: React.ReactNode;
-    /** Trailing affix inside the field (e.g. `%`). Decorative — `aria-hidden`. */
+    /** Trailing affix inside the field (e.g. `%`). */
     suffix?: React.ReactNode;
     /** Form field name — the visible input submits its value natively. */
     name?: NameProp;
@@ -96,19 +95,12 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
     collapseBelow?: BreakpointProp | false;
     columns?: ResponsiveGridColumnsProp;
     density?: DensityProp;
-    /**
-     * Server validation error bag (e.g. Inertia's `form.errors`). Each `FormField name="…"` inside
-     * resolves its own message from the bag automatically and CLAIMS its key; `<FormErrors />`
-     * renders the remaining, unclaimed entries — errors attached to hidden/derived fields that no
-     * visible field displays. Works in both the `<form>` and `asChild` modes. A Form WITHOUT this
-     * prop joins a surrounding `FormErrorsProvider` instead (sibling Card+Form sections sharing one
-     * bag); a Form WITH it starts its own (shadowing) registry.
-     */
+    /** Server validation error bag (e.g. Inertia's `form.errors`). */
     errors?: ErrorBagProp;
     /**
-     * Render the caller's own element instead of a `<form>`, keeping only the layout context.
-     * For routing libraries that own the form element (Inertia, TanStack Form) — two `<form>`
-     * elements cannot nest. `columns` does not apply in this mode; wrap fields in ResponsiveGrid.
+     * Render the caller's own element instead of a `<form>`, keeping only the layout context. For
+     * routing libraries that own the form element (Inertia, TanStack Form) — two `<form>` elements
+     * cannot nest.
      */
     asChild?: boolean;
     className?: ClassNameProp;
@@ -129,11 +121,17 @@ export type FormFieldProp = {
     id?: IdProp;
     /**
      * Error-bag key of this field. When the surrounding `Form` carries `errors`, the field
-     * resolves its message from `errors[name]` automatically (an explicit `error` prop wins)
-     * and CLAIMS the key so `<FormErrors />` does not repeat it. Not injected into the child —
-     * pass `name` on the control itself for native form submission.
+     * resolves its message from `errors[name]` automatically (an explicit `error` prop wins) and
+     * CLAIMS the key so `<FormErrors />` does not repeat it.
      */
     name?: NameProp;
+    /**
+     * Rendered on the control as `data-field`, and as a native `name` when the app opted in via
+     * `<AppProvider emitFieldNames>`. Defaults to `name`, then `id` — which is why an app whose
+     * fields already carry a column-named `id` gets the attribute on every control without
+     * editing a single screen.
+     */
+    field?: NameProp;
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
@@ -160,6 +158,8 @@ export type FormFieldProp = {
      * and CLAIMS the key so `<FormErrors />` does not repeat it.
      */
     name?: NameProp;
+    /** Stable machine key — see the `children` variant above. Unused on a read-only row. */
+    field?: NameProp;
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
@@ -274,8 +274,23 @@ export type FieldProp = {
 };
 /** @see Slider — numeric range (Radix Slider). */
 export type SliderProp = React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>;
-/** @see Calendar — react-day-picker DayPicker. */
-export type CalendarProp = DayPickerProps;
+/** @see Calendar — react-day-picker DayPicker plus an opt-in footer. */
+export type CalendarProp = DayPickerProps & CalendarFooterProp & {
+    /** Replaces the built-in footer actions. */
+    footer?: React.ReactNode;
+};
+/** Footer actions shared by Calendar and the pickers that embed it. Both default to off. */
+export type CalendarFooterProp = {
+    /**
+     * Show a Today action: jumps to the current month and selects today (single), fills the open
+     * end of the range (range) or adds today (multiple). Disabled when today is outside
+     * `startMonth` / `endMonth` or matches `disabled`.
+     */
+    showToday?: boolean;
+    /** Show a Close action that calls `onClose`. */
+    showClose?: boolean;
+    onClose?: () => void;
+};
 /** @see DatePicker */
 export type DatePickerProp = FieldA11yProps & {
     value?: ValueProp<Date>;
@@ -292,7 +307,7 @@ export type DatePickerProp = FieldA11yProps & {
     toDate?: Date;
     /** Show an inline ✕ to clear the value when one is set (default true). */
     allowClear?: boolean;
-};
+} & Pick<CalendarFooterProp, "showToday" | "showClose">;
 /** @see MonthPicker */
 export type MonthPickerProp = FieldA11yProps & {
     value?: ValueProp<Date>;
@@ -346,7 +361,7 @@ export type DateRangePickerProp = FieldA11yProps & {
     toDate?: Date;
     /** Show an inline ✕ to clear the range when one is set (default true). */
     allowClear?: boolean;
-};
+} & Pick<CalendarFooterProp, "showToday" | "showClose">;
 /** @see TimePicker — popover HH:mm picker (canonical 24h storage). */
 export type TimePickerProp = FieldA11yProps & {
     value?: ValueProp;
@@ -415,8 +430,7 @@ export type SearchSelectProp = {
     /**
      * Custom renderer for the SELECTED value shown on the trigger (Ant Design `labelRender`).
      * Receives the value, the resolved label, and the full option when it is loaded (undefined for
-     * an async preset whose page hasn't arrived). Only used while a value is selected; the
-     * placeholder still shows when empty. Overrides the default icon + label trigger content.
+     * an async preset whose page hasn't arrived).
      */
     labelRender?: (selected: {
         value: string;
@@ -444,7 +458,7 @@ export type SearchSelectProp = {
     /**
      * Read-only: the current value is shown (and the clear affordance hidden) but the popover cannot
      * be opened — no new pick, no search. Mirrors the Input/NumberInput readOnly contract (stays
-     * focusable + submits its value, unlike `disabled`). Default false.
+     * focusable + submits its value, unlike `disabled`).
      */
     readOnly?: boolean;
     /** Trigger height tier — forwarded to the underlying Button. Default matches Button's own default. */
@@ -458,7 +472,7 @@ export type SearchSelectProp = {
     /**
      * Override the default client-side filter (`options` mode only — ignored with `loadOptions`,
      * which is responsible for its own server-side filtering). Receives the option and the trimmed
-     * query; return true to keep the row. Only consulted while the query is non-empty.
+     * query; return true to keep the row.
      */
     filterOption?: (option: SearchSelectOptionProp, query: string) => boolean;
     /**
@@ -490,16 +504,13 @@ export type SearchSelectProp = {
     "aria-invalid"?: boolean | "true" | "false";
     "aria-required"?: boolean | "true" | "false";
     "data-testid"?: string;
+    /** Normally injected by `FormField`. */
+    "data-field"?: string;
 };
 /**
  * Data-driven (Ant-style) form of {@link Select} — one component covering static `options` or
  * async `loadOptions`, with `showSearch` toggling the searchable combobox vs a plain listbox.
  * Passing `options`/`loadOptions` to `<Select>` switches it from the compound API to this one.
- *
- * `readOnly`/`size`/`open`/`onOpenChange`/`search`/`onSearchChange`/`filterOption`/`renderError`/
- * `renderLoadMore` (inherited from {@link SearchSelectProp}) take effect ONLY in searchable mode
- * (`showSearch` or `loadOptions`) — they configure the `SearchSelect` engine that mode delegates
- * to. The plain listbox (no search) is a native Radix listbox and ignores them.
  */
 export type SelectDataProp = SearchSelectProp & {
     /** Show the search box (combobox). Defaults to true when `loadOptions` is set, otherwise false. */

package/dist/props/components/form.prop.d.ts

@@ -13,8 +13,7 @@ export type UseZodFormReturnProp<TFieldValues extends FieldValues> = UseFormRetu
  * Framework-agnostic form-state adapter — decouples `FormRoot`/`FormFieldControl` from any single
  * form library. The DS ships the built-in react-hook-form path (`form`), and an adapter lets a
  * SERVER-driven form library plug into the same auto-binding: Inertia's `useForm`
- * (`@godxjp/ui/inertia`), formik, or TanStack Form. The core has ZERO dependency on any of them —
- * a consumer wraps its own form object in an adapter and passes it to `FormRoot`.
+ * (`@godxjp/ui/inertia`), formik, or TanStack Form.
  */
 export interface FormStateAdapter {
     /** Current value of the field `name` (dotted paths allowed if the underlying store supports them). */
@@ -27,7 +26,6 @@ export interface FormStateAdapter {
     isSubmitting: boolean;
     /** Optional blur handler (e.g. touch-tracking); called with the field name. */
     onBlur?(name: string): void;
-    /** Optional snapshot of all values, passed to `onSubmit`; defaults to `{}` when absent. */
     getValues?(): unknown;
 }
 /** @see FormRoot */
@@ -39,11 +37,9 @@ export type FormRootProp<TFieldValues extends FieldValues> = {
     form?: UseZodFormReturnProp<TFieldValues>;
     /**
      * Framework-agnostic form-state adapter (e.g. `inertiaAdapter(form)` from `@godxjp/ui/inertia`).
-     * Provide EITHER `form` OR `adapter`. With an adapter, `FormFieldControl` auto-binds each field by
-     * `name` (value/onChange/error/aria) and `useFormSubmitting()` reads `isSubmitting`.
      */
     adapter?: FormStateAdapter;
-    /** Submit handler. RHF path receives validated `values`; the adapter path calls it with a snapshot (`getValues()`), typically ignored in favour of the form library's own submit (`form.post(url)`). */
+    /** Submit handler. */
     onSubmit: (values: TFieldValues) => void | Promise<void>;
     children: React.ReactNode;
     className?: string;

package/dist/props/components/general.prop.d.ts

@@ -3,7 +3,7 @@ import type * as React from "react";
 import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DisabledProp, FontWeightProp, HeadingLevelProp, LabelProp, OnClickProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp } from "../vocabulary/index.js";
 /** @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`. */
 export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
-    /** Render element. Default `span`. Covers inline/block text + description-list + code/caption. */
+    /** Render element. Default `span`. */
     as?: "span" | "p" | "div" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr";
     /** Size from the type scale — never an arbitrary px. Default `sm` (base). */
     size?: TextSizeProp;
@@ -15,10 +15,8 @@ export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
     /** Single-line ellipsis. Mutually exclusive with `clamp` — when both are set, `clamp` wins. */
     truncate?: boolean;
     /**
-     * Multi-line clamp — max rendered lines (integer ≥ 1); overflow ends in an ellipsis.
-     * Token-owned line-clamp styling (never write the `line-clamp-N` utility page-side).
-     * Visual-only: the full text stays in the DOM / accessible name. Mutually exclusive with
-     * `truncate` — when both are set, `clamp` wins (dev builds warn).
+     * Multi-line clamp — max rendered lines (integer ≥ 1); overflow ends in an ellipsis. Token-owned
+     * line-clamp styling (never write the `line-clamp-N` utility page-side).
      */
     clamp?: number;
     /** Tabular figures for aligned numbers. */
@@ -44,10 +42,6 @@ export type ButtonProp = React.ButtonHTMLAttributes<HTMLButtonElement> & {
     size?: ButtonSizeProp;
     /** Corner shape — `default` (control radius) · `pill` (fully rounded) · `sharp` (square). */
     shape?: ShapeProp;
-    /**
-     * Span the full width of the container (`width:100%`) instead of sizing to content —
-     * the prop form of `className="w-full"` for stacked/auth/dialog-footer actions (rule #42).
-     */
     fullWidth?: boolean;
     asChild?: AsChildProp;
     onClick?: OnClickProp;
@@ -60,16 +54,13 @@ export type ButtonProp = React.ButtonHTMLAttributes<HTMLButtonElement> & {
     /** Optional label to swap in while `loading` (pass the `t()`-translated string). */
     loadingText?: string;
     /**
-     * Optional numeric count rendered as a borderless counter pill after the label
-     * (filter tabs / segmented toggles, e.g. "Chờ bay 18"). Formatted with
-     * `Intl.NumberFormat` in the active locale and styled to read on the button's
-     * own variant — never nest a `Badge` inside a Button for this.
-     * Ignored when `asChild` (Radix Slot requires a single child).
+     * Optional numeric count rendered as a borderless counter pill after the label (filter tabs /
+     * segmented toggles, e.g. "Chờ bay 18").
      */
     count?: number;
     /**
-     * Cap for `count` (Ant Badge parity). When `count` exceeds it the pill shows
-     * `{overflowCount}+` (e.g. `99+`). Defaults to 99.
+     * Cap for `count` (Ant Badge parity). When `count` exceeds it the pill shows `{overflowCount}+`
+     * (e.g.
      */
     overflowCount?: number;
     /**
@@ -90,7 +81,7 @@ export type RevealProp = React.HTMLAttributes<HTMLDivElement> & {
     children?: ChildrenProp;
     /**
      * Stagger ordinal — an INDEX into the motion ladder (`0..6`), never a raw ms. Each step adds one
-     * `--reveal-stagger-step` of delay so sibling reveals cascade. Default `0` (enter immediately).
+     * `--reveal-stagger-step` of delay so sibling reveals cascade.
      */
     delay?: RevealDelayProp;
     /**
@@ -117,14 +108,11 @@ export type RevealProp = React.HTMLAttributes<HTMLDivElement> & {
  * own mark structure, so there is no single child to merge onto.
  */
 export type ActivityProp = Omit<React.HTMLAttributes<HTMLSpanElement>, "color"> & {
-    /**
-     * The mark. Default `dots` — three dots rising in sequence, the ellipsis convention.
-     * `pulse` is a single breathing mark (live / recording); `bar` an indeterminate sweep (syncing).
-     */
+    /** The mark. Default `dots` — three dots rising in sequence, the ellipsis convention. */
     variant?: ActivityVariantProp;
     /**
      * Size step, the standard ladder. Default `sm` — an ambient mark is never the loudest thing on
-     * screen. Scales the mark AND the label together (the mark is `em`-based).
+     * screen.
      */
     size?: SizeProp;
     /** Semantic colour intent. Default `muted` — ambient, not an alert. */
@@ -132,9 +120,7 @@ export type ActivityProp = Omit<React.HTMLAttributes<HTMLSpanElement>, "color">
     /**
      * Localized description of WHAT is happening ("Hưng đang nhập…", "同期中…"). Rendered as visible
      * `Text` beside the mark when `children` are absent; when `children` ARE present it becomes an
-     * `sr-only` description instead, so the indicator is never animation-only. Consumer-owned copy —
-     * the library never invents it, and the plural form of "N people are typing" must come from the
-     * consumer's `Intl.PluralRules`.
+     * `sr-only` description instead, so the indicator is never animation-only.
      */
     label?: LabelProp;
     /**
@@ -145,8 +131,6 @@ export type ActivityProp = Omit<React.HTMLAttributes<HTMLSpanElement>, "color">
     /**
      * Announce the label to assistive technology. Default `false` — the DELIBERATE default, because
      * an ambient indicator that fires a live region on every socket event is a screen-reader flood.
-     * With `false` NO live region is emitted at all. `"polite"` wraps ONLY the label in a single
-     * `aria-live="polite" aria-atomic="true"` region; the mark stays outside it and `aria-hidden`.
      */
     announce?: ActivityAnnounceProp;
     className?: ClassNameProp;