twico-ui 1.45.0 → 1.46.0

package/dist/index.d.cts

@@ -591,7 +591,17 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   children?: React.ReactNode;
 }
 
-declare function Button(props: ButtonProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the `<button>` (or the `<a>` when `as="a"` — `ButtonProps` already commits to
+ * `ButtonHTMLAttributes<HTMLButtonElement>`, so the declared element type follows it).
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Button: React.ForwardRefExoticComponent<
+  ButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 /**
  * Surface container for grouped content. Supports header (title/subtitle),
@@ -1604,7 +1614,16 @@ interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   tone?: Tone;
 }
 
-declare function Checkbox(props: CheckboxProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input type="checkbox">`, merged with the internal ref that drives `indeterminate`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Checkbox: React.ForwardRefExoticComponent<
+  CheckboxProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /**
  * Color picker with a saturation/value square, hue slider, hex input, and
@@ -1745,7 +1764,16 @@ type ComboboxOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type ComboboxGroup = OptionGroup;
 
-declare function Combobox(props: ComboboxProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the text `<input>`, merged with the internal ref used for focus and caret handling.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Combobox: React.ForwardRefExoticComponent<
+  ComboboxProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface Command {
   /** Stable id. */
@@ -2059,6 +2087,26 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    * full row objects server-side rather than relying on `selectedRows`.
    */
   batchActions?: DatatableBatchAction<T>[];
+  /**
+   * #492: extra node in the **selection** toolbar, rendered beside the "N selected" count and before
+   * the batch actions — for the number the count does not carry.
+   *
+   * The count is not always what decides anything. A batch capped by total **size** refuses on
+   * gigabytes, not on items: "12 selected" is not the number the user needs, "12 selected · 2.4 GB"
+   * is. Before this there was nowhere to put it, so hosts lifted it into the main toolbar behind
+   * their own `selected.length > 0` guard — putting it in a different row from the count it
+   * qualifies, and re-deriving a selection this component already tracks.
+   *
+   * Prefer the **function form**: it receives the same `(keys, rows)` the batch actions get, so the
+   * host supplies one pure function and keeps no selection state of its own. (With `retainSelectedRows`
+   * the off-page rows resolve too; without it only the rows currently rendered do.) Pass a plain
+   * node when the summary does not depend on the selection.
+   *
+   * Complements `disabledReason` (#479), which explains the refusal once a cap is exceeded: this is
+   * the running total *before* that point, which is what lets someone stop at the right number
+   * instead of discovering the cap by hitting it.
+   */
+  selectionSummary?: React.ReactNode | ((keys: Array<string | number>, rows: T[]) => React.ReactNode);
   /** #322: fired when the checkbox row selection changes — `(keys, rows)`. The row-mode analogue of
    *  `onCellSelectionChange`, so a consumer can track the selection and drive a batch action's own
    *  `disabled`/`hidden` (which also accept predicates). */
@@ -2851,6 +2899,26 @@ interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElem
    * `ctx.anchorEl` so an action can anchor a popover to its own button.
    */
   batchActions?: CardGridBatchAction<Row>[];
+  /**
+   * #492: extra node in the **selection** toolbar, rendered beside the "N selected" count and before
+   * the batch actions — for the number the count does not carry.
+   *
+   * The count is not always what decides anything. A batch capped by total **size** refuses on
+   * gigabytes, not on items: "12 selected" is not the number the user needs, "12 selected · 2.4 GB"
+   * is. Before this there was nowhere to put it, so hosts lifted it into the main toolbar behind
+   * their own `selected.length > 0` guard — putting it in a different row from the count it
+   * qualifies, and re-deriving a selection this component already tracks.
+   *
+   * Prefer the **function form**: it receives the same `(keys, rows)` the batch actions get, so the
+   * host supplies one pure function and keeps no selection state of its own. (With `retainSelectedRows`
+   * the off-page rows resolve too; without it only the rows currently rendered do.) Pass a plain
+   * node when the summary does not depend on the selection.
+   *
+   * Complements `disabledReason` (#479), which explains the refusal once a cap is exceeded: this is
+   * the running total *before* that point, which is what lets someone stop at the right number
+   * instead of discovering the cap by hitting it.
+   */
+  selectionSummary?: React.ReactNode | ((keys: Array<string | number>, rows: Row[]) => React.ReactNode);
   /** Fired when the selection changes — `(keys, rows)`, matching `Datatable.onRowSelectionChange`. */
   onRowSelectionChange?: (keys: Array<string | number>, rows: Row[]) => void;
   /**
@@ -3269,7 +3337,16 @@ type MultiSelectOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type MultiSelectGroup = OptionGroup;
 
-declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the text `<input>`, merged with the internal ref used for focus and the token-removal keys.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const MultiSelect: React.ForwardRefExoticComponent<
+  MultiSelectProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /** The kinds of filter control a field can render. */
 type FilterFieldType = "multiselect" | "daterange" | "search" | "text" | "number" | "boolean" | "select";
@@ -3573,7 +3650,16 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
   "aria-label": string;
 }
 
-declare function IconButton(props: IconButtonProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the `<button>` (or the `<a>` when `as="a"`, as with `Button`).
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const IconButton: React.ForwardRefExoticComponent<
+  IconButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 /** One toggle button in a {@link ToggleGroup}. */
 interface ToggleGroupItem {
@@ -3668,7 +3754,10 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   clearable?: boolean;
 }
 
-declare function Input(props: InputProps): React.JSX.Element;
+/** Forwards `ref` to the inner `<input>` (merged with the internal one `clearable` uses). */
+declare const Input: React.ForwardRefExoticComponent<
+  InputProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface KanbanColumn {
   /** Unique column id (matches a card's `column`). */
@@ -3900,7 +3989,16 @@ interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   tone?: Tone;
 }
 
-declare function Radio(props: RadioProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input type="radio">`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Radio: React.ForwardRefExoticComponent<
+  RadioProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface RadioGroupOption {
   /** Submitted value for this choice. */
@@ -4057,7 +4155,16 @@ type SelectOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type SelectGroup = OptionGroup;
 
-declare function Select(props: SelectProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the trigger `<button>`, merged with the internal ref used for focus return.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Select: React.ForwardRefExoticComponent<
+  SelectProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 interface SidebarItem {
   /** Item label. */
@@ -4280,7 +4387,16 @@ interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>,
   tone?: Tone;
 }
 
-declare function Switch(props: SwitchProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input role="switch">`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Switch: React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /** Sort state: the sorted column field (null = unsorted) and direction. */
 interface TableSort {
@@ -4830,7 +4946,17 @@ interface CodeProps extends React.HTMLAttributes<HTMLElement> {
   rel?: string;
 }
 
-declare function Code(props: CodeProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the rendered root (`<code>`, or `<pre>` when `block`, or whatever `as` names), merged with the
+ * internal ref used to read the text for the copy button.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Code: React.ForwardRefExoticComponent<
+  CodeProps & React.RefAttributes<HTMLElement>
+>;
 
 /** Font-size token suffixes available to `Heading` (see tokens/typography.css). */
 type HeadingSize =

package/dist/index.d.ts

@@ -591,7 +591,17 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   children?: React.ReactNode;
 }
 
-declare function Button(props: ButtonProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the `<button>` (or the `<a>` when `as="a"` — `ButtonProps` already commits to
+ * `ButtonHTMLAttributes<HTMLButtonElement>`, so the declared element type follows it).
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Button: React.ForwardRefExoticComponent<
+  ButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 /**
  * Surface container for grouped content. Supports header (title/subtitle),
@@ -1604,7 +1614,16 @@ interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   tone?: Tone;
 }
 
-declare function Checkbox(props: CheckboxProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input type="checkbox">`, merged with the internal ref that drives `indeterminate`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Checkbox: React.ForwardRefExoticComponent<
+  CheckboxProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /**
  * Color picker with a saturation/value square, hue slider, hex input, and
@@ -1745,7 +1764,16 @@ type ComboboxOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type ComboboxGroup = OptionGroup;
 
-declare function Combobox(props: ComboboxProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the text `<input>`, merged with the internal ref used for focus and caret handling.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Combobox: React.ForwardRefExoticComponent<
+  ComboboxProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface Command {
   /** Stable id. */
@@ -2059,6 +2087,26 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    * full row objects server-side rather than relying on `selectedRows`.
    */
   batchActions?: DatatableBatchAction<T>[];
+  /**
+   * #492: extra node in the **selection** toolbar, rendered beside the "N selected" count and before
+   * the batch actions — for the number the count does not carry.
+   *
+   * The count is not always what decides anything. A batch capped by total **size** refuses on
+   * gigabytes, not on items: "12 selected" is not the number the user needs, "12 selected · 2.4 GB"
+   * is. Before this there was nowhere to put it, so hosts lifted it into the main toolbar behind
+   * their own `selected.length > 0` guard — putting it in a different row from the count it
+   * qualifies, and re-deriving a selection this component already tracks.
+   *
+   * Prefer the **function form**: it receives the same `(keys, rows)` the batch actions get, so the
+   * host supplies one pure function and keeps no selection state of its own. (With `retainSelectedRows`
+   * the off-page rows resolve too; without it only the rows currently rendered do.) Pass a plain
+   * node when the summary does not depend on the selection.
+   *
+   * Complements `disabledReason` (#479), which explains the refusal once a cap is exceeded: this is
+   * the running total *before* that point, which is what lets someone stop at the right number
+   * instead of discovering the cap by hitting it.
+   */
+  selectionSummary?: React.ReactNode | ((keys: Array<string | number>, rows: T[]) => React.ReactNode);
   /** #322: fired when the checkbox row selection changes — `(keys, rows)`. The row-mode analogue of
    *  `onCellSelectionChange`, so a consumer can track the selection and drive a batch action's own
    *  `disabled`/`hidden` (which also accept predicates). */
@@ -2851,6 +2899,26 @@ interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElem
    * `ctx.anchorEl` so an action can anchor a popover to its own button.
    */
   batchActions?: CardGridBatchAction<Row>[];
+  /**
+   * #492: extra node in the **selection** toolbar, rendered beside the "N selected" count and before
+   * the batch actions — for the number the count does not carry.
+   *
+   * The count is not always what decides anything. A batch capped by total **size** refuses on
+   * gigabytes, not on items: "12 selected" is not the number the user needs, "12 selected · 2.4 GB"
+   * is. Before this there was nowhere to put it, so hosts lifted it into the main toolbar behind
+   * their own `selected.length > 0` guard — putting it in a different row from the count it
+   * qualifies, and re-deriving a selection this component already tracks.
+   *
+   * Prefer the **function form**: it receives the same `(keys, rows)` the batch actions get, so the
+   * host supplies one pure function and keeps no selection state of its own. (With `retainSelectedRows`
+   * the off-page rows resolve too; without it only the rows currently rendered do.) Pass a plain
+   * node when the summary does not depend on the selection.
+   *
+   * Complements `disabledReason` (#479), which explains the refusal once a cap is exceeded: this is
+   * the running total *before* that point, which is what lets someone stop at the right number
+   * instead of discovering the cap by hitting it.
+   */
+  selectionSummary?: React.ReactNode | ((keys: Array<string | number>, rows: Row[]) => React.ReactNode);
   /** Fired when the selection changes — `(keys, rows)`, matching `Datatable.onRowSelectionChange`. */
   onRowSelectionChange?: (keys: Array<string | number>, rows: Row[]) => void;
   /**
@@ -3269,7 +3337,16 @@ type MultiSelectOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type MultiSelectGroup = OptionGroup;
 
-declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the text `<input>`, merged with the internal ref used for focus and the token-removal keys.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const MultiSelect: React.ForwardRefExoticComponent<
+  MultiSelectProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /** The kinds of filter control a field can render. */
 type FilterFieldType = "multiselect" | "daterange" | "search" | "text" | "number" | "boolean" | "select";
@@ -3573,7 +3650,16 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
   "aria-label": string;
 }
 
-declare function IconButton(props: IconButtonProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the `<button>` (or the `<a>` when `as="a"`, as with `Button`).
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const IconButton: React.ForwardRefExoticComponent<
+  IconButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 /** One toggle button in a {@link ToggleGroup}. */
 interface ToggleGroupItem {
@@ -3668,7 +3754,10 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   clearable?: boolean;
 }
 
-declare function Input(props: InputProps): React.JSX.Element;
+/** Forwards `ref` to the inner `<input>` (merged with the internal one `clearable` uses). */
+declare const Input: React.ForwardRefExoticComponent<
+  InputProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface KanbanColumn {
   /** Unique column id (matches a card's `column`). */
@@ -3900,7 +3989,16 @@ interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   tone?: Tone;
 }
 
-declare function Radio(props: RadioProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input type="radio">`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Radio: React.ForwardRefExoticComponent<
+  RadioProps & React.RefAttributes<HTMLInputElement>
+>;
 
 interface RadioGroupOption {
   /** Submitted value for this choice. */
@@ -4057,7 +4155,16 @@ type SelectOption = Option;
 /** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
 type SelectGroup = OptionGroup;
 
-declare function Select(props: SelectProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the trigger `<button>`, merged with the internal ref used for focus return.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Select: React.ForwardRefExoticComponent<
+  SelectProps & React.RefAttributes<HTMLButtonElement>
+>;
 
 interface SidebarItem {
   /** Item label. */
@@ -4280,7 +4387,16 @@ interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>,
   tone?: Tone;
 }
 
-declare function Switch(props: SwitchProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the native `<input role="switch">`.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Switch: React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+>;
 
 /** Sort state: the sorted column field (null = unsorted) and direction. */
 interface TableSort {
@@ -4830,7 +4946,17 @@ interface CodeProps extends React.HTMLAttributes<HTMLElement> {
   rel?: string;
 }
 
-declare function Code(props: CodeProps): React.JSX.Element;
+/**
+ * #490: forwards `ref` to the rendered root (`<code>`, or `<pre>` when `block`, or whatever `as` names), merged with the
+ * internal ref used to read the text for the copy button.
+ *
+ * Declared rather than left to React 19's implicit pass-through: on React 19 `ref` is an ordinary
+ * prop, so `{...rest}` would land one on the element anyway, but React 18 strips it and the type
+ * denied it on both. `forwardRef` works on both majors — see #488.
+ */
+declare const Code: React.ForwardRefExoticComponent<
+  CodeProps & React.RefAttributes<HTMLElement>
+>;
 
 /** Font-size token suffixes available to `Heading` (see tokens/typography.css). */
 type HeadingSize =