twico-ui 1.44.0 → 1.45.1

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. */
@@ -1951,6 +1979,65 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
    *  **Columns** panel ("Row number"). @default false */
   rowNumbers?: boolean;
+  /**
+   * #481: style a whole row from its own state — the row-level counterpart to a column's `cellStyle`.
+   * Without it, marking a row meant assigning `cellStyle` to **every** column: O(columns) for a
+   * row-level fact, hand-composed against whatever else already used `cellStyle`, and with no fixed
+   * column list to decorate at all when the columns come from a schema.
+   *
+   * Called `(row, index)`, the same shape as `rowKey`. **`index` is the row's 0-based position among
+   * the rows currently rendered** — after sorting and filtering, and **within the current page**. It is
+   * therefore *not* the number the `rowNumbers` column shows, which continues across pages; if you need
+   * an absolute position, read it off `row` rather than from this argument.
+   *
+   * A `background` (or `backgroundColor`) is forwarded to the row's CELLS through the `--twc-dt-row-bg`
+   * custom property, because `.twc-dt__td` paints an opaque surface of its own — without that it would
+   * be invisible — and is **removed** from what reaches the `<tr>`, since a row box paints below its
+   * cells and a leftover copy there would composite with the tint rather than hide behind it. Every
+   * other declaration lands on the `<tr>`, except `border` (ignored on row boxes under
+   * `border-collapse: separate`) and `backgroundImage` (painted under the cells' opaque surface) — both
+   * need {@link getRowClassName} and a `… .twc-dt__td` rule. Sticky positioning and measured row height
+   * are applied after yours, so a hook cannot break row pinning or row resizing.
+   *
+   * **Layering — one rule, not a bespoke order:** the row tint is the **bottom** layer above the
+   * cell's plain surface, and **every** built-in state background covers it. The base `.twc-dt__td`
+   * rule is the lowest-specificity background in the component, so hover, row selection,
+   * `activeRowId`, a pinned row, a grabbed row, the diff add/remove/modify washes, cell
+   * selection/active and inline editing all outrank it — and an inline per-cell `cellStyle` outranks
+   * those. A row tint is a *data-derived* wash; nothing data-derived should be able to hide an
+   * interaction state. So selection still reads on a tinted row, hover feedback is never lost, and a
+   * per-cell state wins with nothing to compose on your side.
+   *
+   * Need a tint that survives hover? Use {@link getRowClassName} with a rule outranking `(0,3,0)` —
+   * note `.twc-dt__row.my-row .twc-dt__td` is itself `(0,3,0)`, a tie decided by source order, so add
+   * an element: `tr.twc-dt__row.my-row .twc-dt__td` is `(0,3,1)`, and `… .twc-dt__td[data-pin]` is
+   * `(0,4,1)` for the pinned-column twins. You are then choosing to cover the hover cue on those rows.
+   *
+   * **Stripes:** there are none to layer against. Datatable does not zebra-stripe its data rows —
+   * the only `data-zebra` rules in the component style the PIVOT grid's cells, and the hook does not
+   * apply to pivot rows. So a row tint never has to compete with a stripe.
+   *
+   * **Which rows:** every data row. That includes rows pinned with the row ⋮ menu (the hook runs and
+   * the class/non-background declarations apply, though the pinned-row highlight covers a background
+   * tint for as long as the row is pinned, exactly like selection), and cells in a pinned COLUMN pick
+   * the tint up, so a tinted row shows no hole where a frozen column scrolls over it. NOT group-header
+   * rows or the pivot grid's aggregate rows: those have no `row` object to pass. Skeleton rows shown
+   * while `loading` are untouched.
+   */
+  getRowStyle?: (row: T, index: number) => React.CSSProperties | undefined;
+  /**
+   * #481: a class on the row's `<tr>`, appended to `twc-dt__row` (never replacing it). Same
+   * `(row, index)` signature as {@link getRowStyle}.
+   *
+   * **Which to reach for.** `getRowStyle` is the default: its *background* does not land inline on the
+   * cells — it is routed through `--twc-dt-row-bg` and read by the `(0,1,0)` base rule, so it is the
+   * **lowest** layer and every built-in state covers it, which is almost always what a row tint should
+   * do. (Its *non-background* declarations — opacity, font-weight, text-decoration — are ordinary
+   * inline styles on the `<tr>` and do win.) Reach for `getRowClassName` when you deliberately want the
+   * tint to **outrank** those cues, since your own rule picks its specificity: beat `(0,3,0)`, e.g.
+   * `tr.twc-dt__row.my-row .twc-dt__td`. You are then choosing to cover the hover cue on those rows.
+   */
+  getRowClassName?: (row: T, index: number) => string | undefined;
   /** Restrict the toolbar quick-search to these column `field`s (client mode); defaults to every
    *  visible column. Mirrors `runDatatableQuery`'s `options.searchFields`. */
   searchFields?: string[];
@@ -3210,7 +3297,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";
@@ -3514,7 +3610,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 {
@@ -3609,7 +3714,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`). */
@@ -3841,7 +3949,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. */
@@ -3998,7 +4115,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. */
@@ -4221,7 +4347,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 {
@@ -4771,7 +4906,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. */
@@ -1951,6 +1979,65 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
    *  **Columns** panel ("Row number"). @default false */
   rowNumbers?: boolean;
+  /**
+   * #481: style a whole row from its own state — the row-level counterpart to a column's `cellStyle`.
+   * Without it, marking a row meant assigning `cellStyle` to **every** column: O(columns) for a
+   * row-level fact, hand-composed against whatever else already used `cellStyle`, and with no fixed
+   * column list to decorate at all when the columns come from a schema.
+   *
+   * Called `(row, index)`, the same shape as `rowKey`. **`index` is the row's 0-based position among
+   * the rows currently rendered** — after sorting and filtering, and **within the current page**. It is
+   * therefore *not* the number the `rowNumbers` column shows, which continues across pages; if you need
+   * an absolute position, read it off `row` rather than from this argument.
+   *
+   * A `background` (or `backgroundColor`) is forwarded to the row's CELLS through the `--twc-dt-row-bg`
+   * custom property, because `.twc-dt__td` paints an opaque surface of its own — without that it would
+   * be invisible — and is **removed** from what reaches the `<tr>`, since a row box paints below its
+   * cells and a leftover copy there would composite with the tint rather than hide behind it. Every
+   * other declaration lands on the `<tr>`, except `border` (ignored on row boxes under
+   * `border-collapse: separate`) and `backgroundImage` (painted under the cells' opaque surface) — both
+   * need {@link getRowClassName} and a `… .twc-dt__td` rule. Sticky positioning and measured row height
+   * are applied after yours, so a hook cannot break row pinning or row resizing.
+   *
+   * **Layering — one rule, not a bespoke order:** the row tint is the **bottom** layer above the
+   * cell's plain surface, and **every** built-in state background covers it. The base `.twc-dt__td`
+   * rule is the lowest-specificity background in the component, so hover, row selection,
+   * `activeRowId`, a pinned row, a grabbed row, the diff add/remove/modify washes, cell
+   * selection/active and inline editing all outrank it — and an inline per-cell `cellStyle` outranks
+   * those. A row tint is a *data-derived* wash; nothing data-derived should be able to hide an
+   * interaction state. So selection still reads on a tinted row, hover feedback is never lost, and a
+   * per-cell state wins with nothing to compose on your side.
+   *
+   * Need a tint that survives hover? Use {@link getRowClassName} with a rule outranking `(0,3,0)` —
+   * note `.twc-dt__row.my-row .twc-dt__td` is itself `(0,3,0)`, a tie decided by source order, so add
+   * an element: `tr.twc-dt__row.my-row .twc-dt__td` is `(0,3,1)`, and `… .twc-dt__td[data-pin]` is
+   * `(0,4,1)` for the pinned-column twins. You are then choosing to cover the hover cue on those rows.
+   *
+   * **Stripes:** there are none to layer against. Datatable does not zebra-stripe its data rows —
+   * the only `data-zebra` rules in the component style the PIVOT grid's cells, and the hook does not
+   * apply to pivot rows. So a row tint never has to compete with a stripe.
+   *
+   * **Which rows:** every data row. That includes rows pinned with the row ⋮ menu (the hook runs and
+   * the class/non-background declarations apply, though the pinned-row highlight covers a background
+   * tint for as long as the row is pinned, exactly like selection), and cells in a pinned COLUMN pick
+   * the tint up, so a tinted row shows no hole where a frozen column scrolls over it. NOT group-header
+   * rows or the pivot grid's aggregate rows: those have no `row` object to pass. Skeleton rows shown
+   * while `loading` are untouched.
+   */
+  getRowStyle?: (row: T, index: number) => React.CSSProperties | undefined;
+  /**
+   * #481: a class on the row's `<tr>`, appended to `twc-dt__row` (never replacing it). Same
+   * `(row, index)` signature as {@link getRowStyle}.
+   *
+   * **Which to reach for.** `getRowStyle` is the default: its *background* does not land inline on the
+   * cells — it is routed through `--twc-dt-row-bg` and read by the `(0,1,0)` base rule, so it is the
+   * **lowest** layer and every built-in state covers it, which is almost always what a row tint should
+   * do. (Its *non-background* declarations — opacity, font-weight, text-decoration — are ordinary
+   * inline styles on the `<tr>` and do win.) Reach for `getRowClassName` when you deliberately want the
+   * tint to **outrank** those cues, since your own rule picks its specificity: beat `(0,3,0)`, e.g.
+   * `tr.twc-dt__row.my-row .twc-dt__td`. You are then choosing to cover the hover cue on those rows.
+   */
+  getRowClassName?: (row: T, index: number) => string | undefined;
   /** Restrict the toolbar quick-search to these column `field`s (client mode); defaults to every
    *  visible column. Mirrors `runDatatableQuery`'s `options.searchFields`. */
   searchFields?: string[];
@@ -3210,7 +3297,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";
@@ -3514,7 +3610,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 {
@@ -3609,7 +3714,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`). */
@@ -3841,7 +3949,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. */
@@ -3998,7 +4115,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. */
@@ -4221,7 +4347,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 {
@@ -4771,7 +4906,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 =