twico-ui 1.45.1 → 1.47.0

package/dist/index.d.cts

@@ -1636,6 +1636,34 @@ interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "o
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk to the label). @default false */
@@ -1696,6 +1724,34 @@ interface OptionGroup {
 interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
   label?: React.ReactNode;
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   error?: React.ReactNode;
   required?: boolean;
   size?: "sm" | "md" | "lg";
@@ -1825,6 +1881,34 @@ interface CurrencyProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   label?: React.ReactNode;
   /** Helper text below the field; linked to the input via aria-describedby. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error text below the field; sets aria-invalid and is linked via aria-describedby (takes precedence over hint). */
   error?: React.ReactNode;
   /** Intercepted to render the label asterisk, and forwarded to the native input as `required`. @default false */
@@ -1865,6 +1949,34 @@ interface CurrencyFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
   label?: React.ReactNode;
   /** Helper text below the field; linked to the input via aria-describedby. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error text below the field; sets aria-invalid and is linked via aria-describedby (takes precedence over hint). */
   error?: React.ReactNode;
   /** Intercepted to render the label asterisk, and forwarded to the native input as `required`. @default false */
@@ -2087,6 +2199,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). */
@@ -2879,6 +3011,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;
   /**
@@ -3013,6 +3165,34 @@ interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk to the label). @default false */
@@ -3066,6 +3246,34 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk to the label). @default false */
@@ -3123,6 +3331,34 @@ interface TimePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk to the label). @default false */
@@ -3178,6 +3414,34 @@ interface DateTimePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — recolors both controls and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk to the label). @default false */
@@ -3235,6 +3499,34 @@ declare function DateTimePicker(props: DateTimePickerProps): React.JSX.Element;
 interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
   label?: React.ReactNode;
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   error?: React.ReactNode;
   required?: boolean;
   /** Control height preset, matching Select/Combobox. @default "md" */
@@ -3500,6 +3792,34 @@ interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — replaces the hint and renders in the danger color. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk after the label). @default false */
@@ -3688,6 +4008,34 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk and forwards to the native input). */
@@ -3996,6 +4344,34 @@ interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   label?: React.ReactNode;
   /** Helper text below the group. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error text below the group; sets `aria-invalid` and is announced once for the whole group. */
   error?: React.ReactNode;
   /** Lay the radios in a column or a wrapping row. @default "vertical" */
@@ -4058,6 +4434,34 @@ declare function Rating(props: RatingProps): React.JSX.Element;
 interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onChange" | "defaultValue"> {
   label?: React.ReactNode;
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   error?: React.ReactNode;
   required?: boolean;
   size?: "sm" | "md" | "lg";
@@ -4495,6 +4899,34 @@ interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement
   label?: React.ReactNode;
   /** Helper text shown below when there is no error. */
   hint?: React.ReactNode;
+  /**
+   * #494: always render the footer lane, empty when there is nothing to say, so this field is the
+   * same height as one that has a `hint`, an `error` or a counter.
+   *
+   * A row of fields aligned with `align="flex-end"` splits onto two lines the moment ONE of them
+   * has a hint: that field grows a footer, the others do not, and the caption ends up moving a
+   * *different* control. `align` cannot fix it - `flex-start` lines up the labels instead, so the
+   * controls part company as soon as one label wraps at a narrow width.
+   *
+   * Set it per field, or once on any ancestor for everything inside, which is the safer habit in a
+   * row - with a per-field prop alone, adding a field later and forgetting it brings the
+   * misalignment straight back:
+   *
+   * ```jsx
+   * <Stack direction="row" align="flex-end" data-reserve-footer>
+   *   <Select label="Filter" … />
+   *   <Select label="Comparison" hint="Matches the whole value." … />
+   *   <Input  label="Value" … />
+   * </Stack>
+   * ```
+   *
+   * The lane is held open by generated content, so it matches the real footer by construction -
+   * same font metrics, same flex gap - rather than by a height that drifts when a token changes.
+   * It adds no text to the accessibility tree.
+   *
+   * @default false
+   */
+  reserveFooter?: boolean;
   /** Error message — turns the field red and replaces the hint. */
   error?: React.ReactNode;
   /** Marks the field required (adds an asterisk and forwards to the native textarea). */