@flikk/ui 1.0.0-beta.32 → 1.0.0-beta.33

package/CHANGELOG.md

@@ -1,5 +1,207 @@
 # Changelog
 
+## [1.0.0-beta.33] - 2026-08-20
+
+### Breaking Changes
+
+- 07713f5: **Fixed `ColorPicker` emitting `onChange` on mount, and echoing values the parent pushed in.**
+
+  `prevOutputRef` started as `undefined`, so the very first pass of the notify effect always "differed" and fired `onChange` — before any interaction. Worse, ColorPicker re-derives its output through hex → HSL (integer rounding) → hex, so the emitted string often isn't the one that was passed in (`#3B82F6` round-trips to `#3C83F6`, casing normalizes). A consumer cannot tell that apart from a real user edit:
+
+  - Any app tracking "has the user modified this?" recorded a **phantom override** — merely rendering the picker (e.g. selecting a layer in an inspector) wrote a colour identical to the one already in force.
+  - A parent that stores what it receives and feeds it back could ping-pong into `Maximum update depth exceeded`, since each render handed back a value that re-entered as a new `value` prop.
+
+  Two changes:
+
+  1. **The first effect pass seeds the baseline and emits nothing.** Mounting is not a user edit.
+  2. **A value arriving via the controlled `value` prop is recorded as already in force**, using a new pure `formatColorAs(color, format)` that mirrors the display pipeline. The parent's own value is therefore never echoed back.
+
+  Real user changes (preset click, hex entry, slider drag, format switch) emit exactly as before — now exactly once.
+
+  `InputCounter` was audited as the only other component emitting from an effect. Its emission is deliberate and stays: it fires only when the incoming `value` is outside `min`/`max`, which is a genuine correction the parent must know about — suppressing it would leave the parent disagreeing with what's displayed.
+
+  CLAUDE.md §9 now states the rule: a controlled component never emits a change for a value the user didn't produce.
+
+- 07713f5: **Fixed `ColorPicker` panel overflowing the viewport instead of clamping to it.**
+
+  `ColorPicker.Body` positions through `useSelectPortal`, which measures the panel via the `contentRef` it **returns** and shifts the panel left when its right edge would cross the viewport edge. Body declared its _own_ `contentRef` for click-outside and attached that one to the panel, so the hook's ref stayed `null` for the panel's whole lifetime.
+
+  With nothing to measure, `measureDropdownWidth` fell through to its last-resort fallback — the **trigger's** width. Collision detection then fitted a ~32px box, concluded there was plenty of room, and left the ~320px panel anchored at `bottom-start` running off the right edge. The same null ref also disabled the vertical clamp and left the panel's `ResizeObserver` observing nothing.
+
+  Body now takes `contentRef` from the hook and attaches it to the panel, which is what every other `useSelectPortal` consumer already does. Click-outside uses the same ref — one element, one ref, no merging needed.
+
+  Audited the other nine consumers (Select, Combobox, Dropdown, Tooltip, Popover, TimePicker, InputTag, DatePicker, DateRangePicker): all wire the hook's ref correctly. ColorPicker was the only one.
+
+- 07713f5: **Fixed a family of components that looked controlled but weren't.** Two distinct root causes, both of which made a component silently disagree with the props it was given.
+
+  ### Controlled props are now authoritative (`Pill`, `DatePicker`)
+
+  Both mirrored their controlled prop into `useState` and re-synced from a `useEffect` keyed on that prop — the pattern §9 forbids ("derive per render, never store in state"). The effect only fires when the prop _changes_, so a parent that **rejects or normalizes** a change left the component holding a value the parent never accepted:
+
+  - **`Pill`** — in a single-choice group, re-clicking the option already in force calls `onSelect(false)`, the parent keeps `selected={true}`, the prop is unchanged, the effect never runs, and the chip reports `aria-pressed="false"` while still being the selected option. A control lying about the state it controls. Consumers were working around this by remounting the pill with a `key` to force the truth back — that hack can now be deleted.
+  - **`DatePicker`** — same desync, plus its sync effect was unconditional, so on mount it ran with `value === undefined` and wiped the `useState(value || defaultValue)` seed. **`defaultValue` — a documented public prop — never survived the first paint.** It works now.
+
+  Both components now derive `isControlled` per render and write internal state only when uncontrolled.
+
+  **`Pill` gains `defaultSelected`** to complete the conventional pair, so an uncontrolled row of filter chips can start with some applied. Passing both `selected` and `defaultSelected` dev-warns; `selected` wins.
+
+  ⚠️ **Behavior change:** `<Pill selected={true}>` passed once as a _one-time initial value_ no longer toggles — that now means "controlled, permanently selected", which is what the prop always claimed. Use `defaultSelected` for the initial-value case.
+
+  `DatePicker`'s internal context no longer exposes `setSelectedValue` (it was unused and could not be made controlled-safe), and its single-mode dedupe now compares dates **by time rather than identity** — every calendar click builds a new `Date`, so the old `newDate !== selectedValue` guard was always true and never fired.
+
+  ### Handlers are composed, not clobbered (`RichTextEditor`, `Mention`)
+
+  `{...rest}` spread before an element's own attributes means every later attribute silently wins. The prop stays in the public type, so TypeScript accepts it and it does nothing at runtime — invisible on both sides. `RichTextEditor` dropped `onInput`, `onPaste`, `onDrop`, `onKeyUp`, `onMouseUp` and `onBlur`; `Mention` dropped seven of its nine.
+
+  Spreading last isn't the fix either: a consumer's `onKeyUp` would then _replace_ `RichTextEditor`'s selection tracking and silently disable the toolbar's active state. Internal handlers are load-bearing machinery, not defaults. Both components now compose via a new internal `composeEventHandlers(ours, theirs)`:
+
+  - **Ours runs first**, so consumer code observes settled internal state.
+  - **Both always run.** A `preventDefault()` in either does not skip the other — a consumer that cares reads `event.defaultPrevented`. Conditionally dropping the second handler would reintroduce the same invisible-drop bug in a new costume.
+
+  `Pill`'s `onKeyDown` had the _mirrored_ version of this bug — `{...restProps}` spreads last there, so a consumer's handler replaced Pill's own and silently killed Enter/Space selection. Now composed.
+
+  `ScrollArea` and `Signature` were audited and are correct as-is (ScrollArea already calls through to `props.onWheel`; Signature's spread targets the wrapper while the drawing handlers sit on the canvas, so consumer handlers still fire via bubbling). Both gained tests pinning that contract.
+
+  CLAUDE.md §9 documents the merge rules for `className`, `style`, `id` and handlers.
+
+- f4ac111: **Icons inside form controls are now themeable and size-aware — `--form-icon-size-sm/md/lg`.**
+
+  A field had its box tokenised (`--form-min-h-*`, `--form-px/py-*`, `--form-radius`) and its type tokenised (`--form-text-size-*`), but every icon inside it was a hardcoded `size-4` / `size-5` / `h-4 w-4` at the call site. Icon size was the one axis of a control's geometry a theme could not reach: scale a preset up and the chevron, clock and search glyph stayed exactly where they were.
+
+  `--form-icon-size-sm/md/lg` (12 / 14 / 16px) closes that, consumed as `size-[var(--form-icon-size-…)]` through `formsBaseTheme.iconStyles.sizes`. The ramp is 12/14/16, matching the control type ramp. (It shipped as the gentler of the two, against a type ramp of 14/14/16, on the argument that an icon carries more optical mass per px than a text glyph; the `sm` type rung dropped to 12px in the same release and the two converged.)
+
+  **Slot geometry ramps with it**, derived from the control's own padding rather than flat literals:
+
+  |             | leading slot                     | trailing slot                 |
+  | ----------- | -------------------------------- | ----------------------------- |
+  | inset       | `--form-px-*` exactly (12/14/16) | `--form-px-* − 4px` (8/10/12) |
+  | text runway | `+ 20/22/24` (32/36/40)          | `+ 16/18/20` (28/32/36)       |
+
+  The two differ on purpose: a leading icon stands where the text would have started, so matching `--form-px-*` keeps a field's left edge constant with or without one, while a trailing affordance is chrome — a chevron is mostly whitespace and reads further from the edge than a glyph at the same metric distance. New keys on `formsBaseTheme.iconStyles`: `leftSizes`, `rightSizes`, `paddingLeftSizes`, `paddingRightSizes`, `sizes`. The size-blind `left` / `right` / `padding` remain as the fallback.
+
+  **Adopted by** `Input` (built-in type glyphs, number-stepper glyphs, both slots), `Select`, `Combobox`, `DatePicker`, `DateRangePicker`, `TimePicker`. Each component's theme gained optional per-size keys (`iconStartStyles`, `iconEndStyles`, `iconSizes`, `iconPaddings` / `iconEndPaddings`) and falls back to its flat keys, so an existing theme override keeps applying.
+
+  ⚠️ **Visible change.** `Input`'s built-in lock and search glyphs were `size-5` (20px) at every size and are now 14px at `md`; the picker/clock/calendar carets were `h-4 w-4` and now ramp. **Consumer-supplied slot icons are untouched** — passing `className` on a slot icon replaces the auto size (§7), so only our own built-ins moved.
+
+  **Not adopted by** listbox check marks or panel chrome (ColorPicker internals, FileUpload dropzone): a dropdown row's type doesn't track its trigger's size, so its icons shouldn't either.
+
+  ### Breaking: `--button-icon-size-*` → `--button-icon-square-*`
+
+  The icon-only Button's **box** (aliased to `--form-min-h-*`) was called `--button-icon-size-*`. Shipping a glyph token called `--form-icon-size-*` alongside it would have put two tokens named "icon size" meaning different things into the system, so the box token was renamed to say what it is. Update any theme overriding it.
+
+  The Figma exporter's variable NAME is deliberately unchanged (`size/button/icon-size-*`): it matches existing kit variables by name, so emitting a new name would create a second variable and strand every component bound to the first. Renaming it in the kit is a deliberate pass, not a side effect. `--form-icon-size-*` exports as `size/form/icon-*`.
+
+- 967f18b: **`InputCounter` gains `size` and manual entry; `InputAddress` and `InputCreditCard` gain `size`.**
+
+  ### `size` — the counter can finally line up with the fields around it
+
+  `InputCounter` was the only stepper-style control with no `size` prop, and its geometry was hardcoded three ways: an implicit height from `p-1`, `<Button size="sm">` on both steppers, and a `text-sm` number. Nothing about it responded to a size, so a counter sitting under a `Select` in an inspector column was visibly taller and chunkier than the fields above it, with no way to fix it from the outside.
+
+  It now takes `size?: 'sm' | 'md' | 'lg'` (default `'md'`), drawn from the shared `formsBaseTheme.sizes` scale — the same `--form-min-h-*` / `--form-text-size-*` tokens `Input`, `Select` and `Combobox` use, which is what keeps a row of fields on one baseline. A `buttonSizes` map in the theme picks the stepper Button size per counter size, so it is tunable in one place.
+
+  ⚠️ **Visual change at the default.** Today's hardcoded look is roughly `md` height with `sm` steppers and `sm` text; at `size="md"` the number and steppers now grow to match a real `md` field. That is the point of the change, but existing counters will render slightly larger.
+
+  `InputAddress` and `InputCreditCard` take the same `size`, forwarded to every field they render (a per-field `*InputProps.size` still wins). `InputDate` already inherited and forwarded it via `InputProps`.
+
+  ### The steppers are now derived from the counter, and the edge is the shared one
+
+  Two geometry bugs fell out of the size work, both visible at `sm`:
+
+  - **The steppers were mapped onto `Button`'s own size scale**, which has only three rungs — so `sm` and `md` both got the same 32px square, and at `sm` that square was **taller than the counter's content box**: the ghost hover fill punched straight through the rounded border, and its 6px radius didn't match the container's 8px. They are now squares derived from the counter's own height (`--form-min-h-*` minus the container's 4px inset → 24 / 28 / 32) with a concentric radius (`--form-radius` − 4px), so they scale with the control instead of landing on whichever `Button` size is closest. Stepper icons track the type ramp too (16 / 16 / 20px). A `buttonProps.className` still wins.
+  - **The container drew a real `border`.** That is a §9 violation on its own — the edge of every form control is the shared inset `box-shadow` — but it was also doing structural damage: a real border consumes 2px of the fixed `--form-min-h-*` height, which is what left the `sm` steppers with only 30px to fit into. It now composes `formsBaseTheme.inputGroupBorderStyle`, so the counter reads identically to the `Select` beside it, picks up the hover edge, gains a **focus ring it never had** (it was the only tabbable form control without one), and takes the shared `states.invalid` instead of a bespoke `ring-1`.
+
+  `formsBaseTheme` gains `inputGroupBorderStyle` — the field edge alone, without `inputGroupBaseStyle`'s `flex`, fill and `transition-all`. The counter's root is a motion element carrying `layout`, and `transition-all` there covers `transform`, re-interpolating motion's per-frame writes every frame (§12); it lists `transition-[box-shadow,background-color]` instead. `inputGroupBaseStyle` is now literally that constant plus the three extras, so there is still exactly one definition of the edge.
+
+  The number also drops to normal weight, matching the text in the fields it sits beside, and disabled counters now take the shared `states.disabled` treatment instead of looking identical to an enabled one.
+
+  **The odometer no longer rolls for values that never travelled.** The sliding animation is feedback for _stepping_ — it shows the value moving by a step. A typed value didn't move through the digits in between, so rolling `4 → 9` past 5, 6, 7 and 8 read as the control second-guessing the entry. Manual entry now lands in place, and so does any return from an edit session: the display is mounted fresh when the field unmounts, and a motion element without `initial` animates on mount, so even **Escape** used to roll the untouched number up from zero. Stepping still animates.
+
+  ### Manual entry
+
+  Clicking the number — or pressing Enter while the counter has focus, so it is reachable without a mouse — swaps `SlidingNumber` for a real text field, focused with its contents selected. Typing is free-form: no clamping and no `onChange` while the user is mid-edit, so typing `5` on the way to `50` under `min={10}` is no longer eaten. The value is parsed, rounded to the counter's decimal places, clamped to `min`/`max` and emitted on **Enter or blur**; **Escape** reverts and returns focus to the counter. Empty or unparseable input reverts. Per §9, a typed value equal to the current one emits nothing.
+
+  **Clicking the number does not resize the control.** The field used to size itself with the `size` attribute — the browser's average character width — which never matched `SlidingNumber`'s fixed per-character em box, so the counter grew 1–3px on every click, animated into a visible wobble by the root's `layout`. Both states now lay into one slot whose width is reserved from the character count in the same `em` metric `SlidingNumber` uses (exported as `SLIDING_NUMBER_CHAR_WIDTH_EM`, internal). A bounded counter reserves room for its widest legal value up front, so stepping 9 → 10 doesn't resize it either.
+
+  **An out-of-range draft is flagged while you type.** Typing stays free-form and clamping still happens on commit — clamping mid-edit would eat the `5` on the way to `50` under `min={10}` — but a draft that parses outside `min`/`max` now paints the shared invalid edge and sets `aria-invalid` on the field, so `34` under `max={10}` reads as rejected _before_ you blur rather than silently becoming `10`. Unparseable input isn't flagged; it simply reverts.
+
+  The field is mounted only while editing, so there is exactly one tab stop at any moment and no `tabIndex` juggling. The root keeps `role="spinbutton"` — a spinbutton containing a textbox is the canonical composite pattern — and its arrow/PageUp/PageDown handling is suppressed while editing so those keys move the caret instead of stepping the value.
+
+  Opt out with `editable={false}`.
+
+  The field is a bare transparent `<input>` inside the counter's existing surface rather than a nested `<Input>`, which would have meant suppressing that component's border, background, height and padding. CLAUDE.md §2 records this as the one sanctioned exception to the reuse rule, with the test for when it applies.
+
+  ### Removed: `InputCounter`'s `formatNumber`
+
+  **Breaking.** The prop was destructured and never used — it never reached the rendered `SlidingNumber`, so passing it did nothing. It has been removed rather than wired up, because its documented default (`(n) => n.toString()`) would render `1` where the display shows `1.00`, making "fixing" it a behavior change rather than a fix.
+
+  The counter displays a number; render units (`%`, `px`, `$`) as adjacent text, and use `decimalPlaces` (auto-detected from `step`) for precision. It was already excluded from the generative schema, so the curated surface is unchanged.
+
+- 07713f5: **Fixed `RichTextEditor` silently discarding a consumer's `style` prop, and `RichTextEditor`/`Mention` discarding a consumer's `id`.**
+
+  Both components spread `{...rest}` onto their contentEditable surface _before_ setting their own attributes on the same element, so any prop the component also sets was overwritten by the later JSX attribute. `style` and `id` are both part of the public typed surface — the props extend `React.HTMLAttributes<HTMLDivElement>` — so TypeScript accepted them and they silently did nothing. The reported symptom was a consumer routing typography overrides through the forwarded ref because `style` never landed.
+
+  `style` was the outlier: `Mention` already destructured and merged it (`{ minHeight, ...styleProp }`), and every other component in the library that sets `style` alongside a spread merges the incoming value (Skeleton, AspectRatio, Masonry, AppShell's sidebars, the effects family). `RichTextEditor` is now consistent with them:
+
+  ```tsx
+  style={{ minHeight, maxHeight, ...styleProp }}
+  ```
+
+  A passed `style` therefore wins over the `minHeight`/`maxHeight` props for the keys it sets, and leaves the rest in place.
+
+  `id` was missing from both. Every other form control resolves `id || generatedId` (Input, Textarea, Select, Switch, Slider, DatePicker, …); these two ignored the prop and kept their `useId()` value, which also left `FormLabel`'s `htmlFor` pointing at an id the consumer could not predict. Both now resolve `idProp ?? autoId`, and every derived id (`-description`, `-listbox`) hangs off the resolved value, so a consumer-supplied id makes the whole ARIA wiring addressable.
+
+  `className` was already merged correctly on both components and is unchanged.
+
+- f4ac111: **`Select`'s chevron scales with the control.**
+
+  The trailing chevron was hardcoded three ways at every size — a `size-4` glyph, a `pr-3` slot, and a `pr-10` text runway — while the field's own horizontal padding ramps 12 / 14 / 16 (`--form-px-*`). At `sm` that left a 16px icon out-weighing the 14px text beside it, and at every size the icon's distance from the edge was unrelated to the control it sat in.
+
+  All three now derive from the size:
+
+  |                       | sm                         | md                        | lg                        |
+  | --------------------- | -------------------------- | ------------------------- | ------------------------- |
+  | glyph                 | 12px                       | 14px                      | 16px                      |
+  | inset from right edge | `--form-px-sm − 4px` (8)   | `--form-px-md − 4px` (10) | `--form-px-lg − 4px` (12) |
+  | text runway           | `--form-px-sm + 16px` (28) | `+ 18px` (32)             | `+ 20px` (36)             |
+
+  The slot insets one step tighter than the text on purpose: a chevron is mostly whitespace, so at the same metric distance it reads as further from the edge than a glyph does. Both are expressed against `--form-px-*` rather than literals, so retuning a theme's control padding moves the icon with it.
+
+  The values live in `formsBaseTheme.iconStyles` as `rightSizes` / `paddingRightSizes` / `sizes`, alongside the size-blind `right` / `padding` they replace. **`Select` is the only adopter so far** — `Input`, `Combobox`, `DatePicker`, `DateRangePicker` and `TimePicker` still render trailing icons through the flat keys and are unchanged.
+
+  `SelectThemeOverrides` gains `iconEndStyles`, `iconEndSizes` and `iconEndPaddings` (all `Partial<Record<SelectSize, string>>`). `iconEndStyle` and `iconPadding.right` still work and are used as the fallback when a size has no entry, so an existing theme override keeps applying.
+
+- 8819689: **The `sm` control rung is now a 28px box with 12px type.**
+
+  `--form-text-size-sm` moves from `--text-sm` (14px) to `--text-xs` (12px) with its line-height partner, and `--form-min-h-sm` from 32px to 28px. Everything that aliases them follows: `--button-text-size-sm`, `--segmented-text-size-sm`, `--button-min-h-sm`, `--segmented-min-h-sm`, `--otp-slot-size-sm`, `--button-icon-square-sm`. So `sm` finally reads as a genuinely denser rung rather than an `md` in a slightly shorter box.
+
+  `--form-py-sm` drops to 6px alongside. A 28px box around a 12px/16px line has exactly 12px of padding to spend; at 8px the padding claimed 16px of a 12px content box — invisible wherever a fixed `h-*` wins, but wrong for anything sized by padding.
+
+  This retires the "deliberately two rungs across three sizes" note in `docs/THEMING.md`, which argued that 12px on a 32px-tall action was a legibility liability and that the repeat shouldn't be "fixed" into 12/14/16 without a design pass. That pass is this change: shadcn ships `text-xs` on its `sm` button at `h-8`, and the objection was really about 12px in a control too tall for it — so the box came down to 28px in the same move. The type ramp is now 12/14/16 and matches the control icon ramp exactly.
+
+  ### `InputCounter` at `sm` and WCAG 2.2 target size
+
+  A 28px box cannot hold a 24px stepper at any sensible inset, so the `sm` steppers (20×20) are undersized for **SC 2.5.8 Target Size (Minimum), Level AA** and clear it through the spacing exception instead: a 24px circle centred on each target must not intersect the next one's. The neighbouring target is the click-to-edit value, so `sm` widens its gap to 8px, putting those centres **25.2px** apart. `md` (26px) and `lg` (30px) pass on size outright.
+
+  Two details are load-bearing there, both commented in the source:
+
+  - The value slot now reserves a **two-character minimum**. A single-character slot pulls the centres back to 21.6px and fails.
+  - `sm` uses a 4px inset (20×20 square) where `md`/`lg` use 5px. The uniform 5px inset it briefly had produced a 22×22 square at 32px whose centres sat 22.2px apart — which also failed, on the previous box height.
+
+### Fixed
+
+- 91f4939: **Fix: `Textarea` with `unstyled` silently ignored `onValueChange`, making a controlled textarea read-only.**
+
+  The `unstyled` early return destructured `onValueChange` out of props and then never wired it — only the styled path below it did. So `value` + `onValueChange` + `unstyled` rendered a textarea React considered controlled with no `onChange`: it logged the controlled-without-onChange warning and then discarded every keystroke. Nothing threw, and the field simply refused to accept input. `onChange` worked on both paths, which is why `PromptInput` (the only in-library consumer of `unstyled`) never hit it.
+
+  Both paths now share one `handleChange`, wired above the branch so a future path cannot drop it again.
+
+  Two related defects in the same branch, found while fixing it:
+
+  - **`{...props}` was spread AFTER the internal `onFocus`/`onBlur`**, so a consumer's handlers silently replaced the component's own — §9's clobber rule, in the one place it still applied.
+  - **Those internal handlers only fed an `isFocused` state that nothing read.** Rather than compose dead code, the state and both wrappers are removed; consumer `onFocus`/`onBlur` now pass straight through. No visual behaviour changes — the focus ring is CSS `focus-within`, never that state.
+
+  Regression tests cover all three, and were confirmed to fail against the pre-fix component.
+
 ## [1.0.0-beta.32] - 2026-08-14
 
 ### Breaking Changes

package/dist/components/ai/AgentRequest/AgentRequest.theme.js

@@ -22,7 +22,7 @@ const agentRequestTheme = {
     // `bottom-5` centres the 24px nav against the 32px `size="sm"` button sitting
     // on the panel's 16px bottom inset.
     navStyle: "absolute bottom-5 left-3 z-[2] flex shrink-0 items-center gap-0.5",
-    // Overrides Button's `iconOnly` sizing (--button-icon-size-sm is the FORM
+    // Overrides Button's `iconOnly` sizing (--button-icon-square-sm is the FORM
     // control height — too heavy for a quiet header affordance). Plain utilities,
     // not `!important`: Button puts `className` last in its own `cn(...)`, so
     // twMerge already resolves these against the size/padding it set.

package/dist/components/core/Button/Button.theme.js

@@ -87,15 +87,15 @@ const buttonTheme = {
             // Tighten the corner radius at sm so a short button doesn't read as a pill
             // (overrides baseStyle's rounded-[var(--button-radius)] via twMerge).
             default: "font-medium min-h-[var(--button-min-h-sm)] px-[var(--button-px-sm)] py-[var(--button-py-sm)] text-[length:var(--button-text-size-sm)]/[var(--button-line-height-sm)] rounded-[calc(var(--button-radius)*0.75)]",
-            iconOnly: "size-[var(--button-icon-size-sm)] p-[var(--button-icon-p-sm)] rounded-[calc(var(--button-radius)*0.75)]",
+            iconOnly: "size-[var(--button-icon-square-sm)] p-[var(--button-icon-p-sm)] rounded-[calc(var(--button-radius)*0.75)]",
         },
         md: {
             default: "font-medium min-h-[var(--button-min-h-md)] px-[var(--button-px-md)] py-[var(--button-py-md)] text-[length:var(--button-text-size-md)]/[var(--button-line-height-md)]",
-            iconOnly: "size-[var(--button-icon-size-md)] p-[var(--button-icon-p-md)]",
+            iconOnly: "size-[var(--button-icon-square-md)] p-[var(--button-icon-p-md)]",
         },
         lg: {
             default: "font-medium min-h-[var(--button-min-h-lg)] px-[var(--button-px-lg)] py-[var(--button-py-lg)] text-[length:var(--button-text-size-lg)]/[var(--button-line-height-lg)]",
-            iconOnly: "size-[var(--button-icon-size-lg)] p-[var(--button-icon-p-lg)]",
+            iconOnly: "size-[var(--button-icon-square-lg)] p-[var(--button-icon-p-lg)]",
         },
     },
     // Icon slot sizing. `[&>svg]:size-*` sizes the icon itself, so a caller passing a bare

package/dist/components/core/Pill/Pill.js

@@ -6,6 +6,7 @@ import { pillTheme } from './Pill.theme.js';
 import { createPressVariants } from '../shared/interaction.animations.js';
 import { Ripple } from '../shared/Ripple.js';
 import { cn } from '../../../utils/cn.js';
+import { composeEventHandlers } from '../../../utils/composeEventHandlers.js';
 
 // Shared press physics + subtle hover lift (module-level constant)
 const PILL_PRESS_VARIANTS = createPressVariants(0.97, 1.02);
@@ -46,19 +47,21 @@ const PILL_PRESS_VARIANTS = createPressVariants(0.97, 1.02);
  */
 const Pill = React__default.forwardRef((props, ref) => {
     var _a, _b;
-    const { children, size = "md", iconStart, selected = false, onSelect, readOnly = false, className, theme = {}, onClick, ...restProps } = props;
+    const { children, size = "md", iconStart, selected, defaultSelected = false, onSelect, readOnly = false, className, theme = {}, onClick, onKeyDown, ...restProps } = props;
     // Detect whether the consumer *explicitly* passed `selected` (even
-    // `selected={undefined}` counts as not-passed) — checking the raw props
-    // object, BEFORE the `selected = false` default above is applied, so a
-    // plain `<Pill>` with no `selected` prop at all never trips the
-    // dev-warning below just because the destructured default made it look
-    // "set".
-    const hasExplicitSelected = "selected" in props && props.selected !== undefined;
+    // `selected={undefined}` counts as not-passed), so a plain `<Pill>` with no
+    // `selected` prop never trips the dev-warning below.
+    const hasExplicitSelected = selected !== undefined;
+    const hasExplicitDefaultSelected = "defaultSelected" in props && props.defaultSelected !== undefined;
     // ========== State Management ==========
-    const [isSelected, setIsSelected] = useState(selected);
-    useEffect(() => {
-        setIsSelected(selected);
-    }, [selected]);
+    // 🔴 §9: mode is DERIVED per render, never stored. `selected` used to be
+    // mirrored into state and re-synced from a `useEffect(…, [selected])`. A
+    // single-choice group that rejects a deselect leaves the prop identical, so
+    // the effect never fired and the chip reported `aria-pressed="false"` while
+    // still being the option in force — the control lying about its own state.
+    const isControlled = hasExplicitSelected;
+    const [uncontrolledSelected, setUncontrolledSelected] = useState(defaultSelected);
+    const isSelected = isControlled ? selected : uncontrolledSelected;
     const shouldReduceMotion = useReducedMotion();
     // ========== Derived State ==========
     const isSelectable = Boolean(onSelect);
@@ -71,8 +74,12 @@ const Pill = React__default.forwardRef((props, ref) => {
                 // eslint-disable-next-line no-console
                 console.warn('[Pill] Component has "selected" prop but missing "onSelect" handler. The pill will not be interactive.');
             }
+            if (hasExplicitSelected && hasExplicitDefaultSelected) {
+                // eslint-disable-next-line no-console
+                console.warn("[Pill] Received both `selected` and `defaultSelected`. `selected` wins and the pill is controlled; drop `defaultSelected`.");
+            }
         }
-    }, [hasExplicitSelected, onSelect]);
+    }, [hasExplicitSelected, hasExplicitDefaultSelected, onSelect]);
     // ========== Event Handlers ==========
     const handleClick = useCallback((e) => {
         if (readOnly) {
@@ -81,21 +88,29 @@ const Pill = React__default.forwardRef((props, ref) => {
         }
         if (onSelect) {
             const newSelected = !isSelected;
-            setIsSelected(newSelected);
+            // Controlled: the parent owns the value — it may accept, reject or
+            // normalize this. Writing a local copy is what desynced the chip.
+            if (!isControlled)
+                setUncontrolledSelected(newSelected);
             onSelect(newSelected);
         }
         onClick === null || onClick === void 0 ? void 0 : onClick(e);
-    }, [readOnly, onSelect, isSelected, onClick]);
+    }, [readOnly, onSelect, isSelected, isControlled, onClick]);
     const handleKeyDown = useCallback((e) => {
         if (readOnly || !isSelectable)
             return;
         if (e.key === "Enter" || e.key === " ") {
             e.preventDefault();
             const newSelected = !isSelected;
-            setIsSelected(newSelected);
+            if (!isControlled)
+                setUncontrolledSelected(newSelected);
             onSelect === null || onSelect === void 0 ? void 0 : onSelect(newSelected);
         }
-    }, [readOnly, isSelectable, isSelected, onSelect]);
+    }, [readOnly, isSelectable, isSelected, isControlled, onSelect]);
+    // 🔴 §9: `{...restProps}` spreads AFTER this element's own attributes, so a
+    // consumer's onKeyDown used to REPLACE ours and silently kill Enter/Space
+    // selection. Compose instead — ours first, then theirs.
+    const composedKeyDown = composeEventHandlers(handleKeyDown, onKeyDown);
     // ========== Theme Merging ==========
     const mergedTheme = {
         baseStyle: theme.baseStyle || pillTheme.baseStyle,
@@ -119,7 +134,7 @@ const Pill = React__default.forwardRef((props, ref) => {
         isSelected && mergedTheme.selectedStyle, 
         // Cursor styling
         isInteractive ? "cursor-pointer" : "cursor-default", className // User overrides (highest priority)
-        ), onClick: handleClick, onKeyDown: handleKeyDown, "data-size": size, "data-selected": isSelected ? "true" : "false", "data-readonly": !isInteractive ? "true" : "false", "data-selectable": isSelectable ? "true" : "false", 
+        ), onClick: handleClick, onKeyDown: composedKeyDown, "data-size": size, "data-selected": isSelected ? "true" : "false", "data-readonly": !isInteractive ? "true" : "false", "data-selectable": isSelectable ? "true" : "false", 
         // Accessibility
         role: isSelectable && !readOnly ? "button" : undefined, tabIndex: isInteractive ? 0 : undefined, "aria-pressed": isSelectable && !readOnly ? isSelected : undefined, "aria-readonly": readOnly || undefined, 
         // Animation

package/dist/components/core/Pill/Pill.types.d.ts

@@ -30,8 +30,21 @@ export interface PillProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "
      * Note: Replaced by CheckIcon when pill is selected
      */
     iconStart?: React.ReactNode;
-    /** Whether the pill is selected (controlled state) */
+    /**
+     * Whether the pill is selected — CONTROLLED. Passing it makes the prop
+     * authoritative: the pill renders from it on every render and keeps no copy,
+     * so a parent that rejects or normalizes a change (a single-choice group
+     * refusing to deselect the active option) stays truthfully reflected.
+     *
+     * Mutually exclusive with `defaultSelected` (dev-warns if both are passed).
+     */
     selected?: boolean;
+    /**
+     * Initial selection for an UNCONTROLLED pill, which then owns its own state.
+     * Ignored when `selected` is provided.
+     * @default false
+     */
+    defaultSelected?: boolean;
     /**
      * Callback when selection state changes
      * @param selected - The new selected state

package/dist/components/core/SlidingNumber/SlidingNumber.d.ts

@@ -1,5 +1,13 @@
 import React from "react";
 import { SlidingNumberProps } from "./SlidingNumber.types";
+/**
+ * Every rendered character — an animated digit or a static one (`-`, `.`, `,`) —
+ * occupies exactly this many `em`s. Exported so a host can reserve an exact width
+ * for a given character count WITHOUT measuring the DOM: `InputCounter` sizes its
+ * value slot from it, which is what keeps the box identical whether the animated
+ * number or the click-to-edit field is mounted. Changing it changes that geometry.
+ */
+export declare const SLIDING_NUMBER_CHAR_WIDTH_EM = 0.6;
 /**
  * SlidingNumber component with odometer-style digit animation
  *

package/dist/components/core/SlidingNumber/SlidingNumber.js

@@ -4,11 +4,20 @@ import React__default, { useMemo } from 'react';
 import { motion, useReducedMotion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 
-const DIGIT_CONTAINER_STYLE = { height: "1em", width: "0.6em", lineHeight: "1em" };
+/**
+ * Every rendered character — an animated digit or a static one (`-`, `.`, `,`) —
+ * occupies exactly this many `em`s. Exported so a host can reserve an exact width
+ * for a given character count WITHOUT measuring the DOM: `InputCounter` sizes its
+ * value slot from it, which is what keeps the box identical whether the animated
+ * number or the click-to-edit field is mounted. Changing it changes that geometry.
+ */
+const SLIDING_NUMBER_CHAR_WIDTH_EM = 0.6;
+const CHAR_WIDTH = `${SLIDING_NUMBER_CHAR_WIDTH_EM}em`;
+const DIGIT_CONTAINER_STYLE = { height: "1em", width: CHAR_WIDTH, lineHeight: "1em" };
 const DIGIT_ITEM_STYLE = { height: "1em", lineHeight: "1em" };
 const DIGITS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 const DEFAULT_TRANSITION = { type: "spring", stiffness: 300, damping: 30, bounce: 0 };
-const STATIC_CHAR_STYLE = { width: "0.6em" };
+const STATIC_CHAR_STYLE = { width: CHAR_WIDTH };
 const ROOT_STYLE = { lineHeight: "1" };
 /**
  * Individual digit component that handles the sliding animation
@@ -72,4 +81,4 @@ const SlidingNumber = React__default.forwardRef(({ value, decimalPlaces = 0, pad
 });
 SlidingNumber.displayName = "SlidingNumber";
 
-export { SlidingNumber };
+export { SLIDING_NUMBER_CHAR_WIDTH_EM, SlidingNumber };

package/dist/components/forms/ColorPicker/ColorPicker.js

@@ -34,6 +34,24 @@ const DEFAULT_GRADIENT = {
  * and return null). Skip parsing for gradient values.
  */
 const isGradientString = (v) => /^(?:repeating-)?(?:linear|radial|conic)-gradient\(/.test(v.trim());
+/**
+ * The solid-color output pipeline, as a pure function.
+ *
+ * Mirrors `getFormattedValue` below, but callable from an effect that needs to
+ * know what a color WILL serialize to before that color reaches state — used to
+ * mark a parent-supplied value as already in force so it is never echoed back
+ * through `onChange`.
+ */
+const formatColorAs = (c, fmt) => {
+    switch (fmt) {
+        case 'rgb':
+            return formatRgb(c.h, c.s, c.l, c.a);
+        case 'hsl':
+            return formatHsl(c.h, c.s, c.l, c.a);
+        default:
+            return formatHex(c.h, c.s, c.l);
+    }
+};
 /**
  * ColorPicker Root Component
  * Follows Flikkui compound component pattern (similar to Accordion, Tabs, Popover)
@@ -55,6 +73,11 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
     const [color, setColor] = useState(initialColor);
     const [format, setFormat] = useState(initialFormat);
     const [isOpen, setIsOpen] = useState(false);
+    // Last value handed to `onChange` (or accepted from the parent). Declared
+    // here because BOTH the controlled-value sync and the emit effect below
+    // write it — see the emit effect for the full rationale.
+    const prevOutputRef = useRef(undefined);
+    const hasSeededOutputRef = useRef(false);
     // Mode state (controlled/uncontrolled)
     const [internalMode, setInternalMode] = useState(defaultMode);
     const mode = modeProp !== null && modeProp !== void 0 ? modeProp : internalMode;
@@ -130,9 +153,14 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
             const parsed = parseColor(value);
             if (parsed) {
                 setColor(parsed);
+                // 🔴 Record what this externally-supplied value normalizes to, so the
+                // emit effect below treats the resulting render as "already in force"
+                // and does not echo the parent's own value back as an onChange. Without
+                // this, a parent that writes what it receives ping-pongs forever.
+                prevOutputRef.current = formatColorAs(parsed, format);
             }
         }
-    }, [value]);
+    }, [value, format]);
     // Individual channel setters
     const setHue = useCallback((h) => {
         setColor((prev) => ({ ...prev, h }));
@@ -147,6 +175,7 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
         setColor((prev) => ({ ...prev, a }));
     }, []);
     // Utility functions to get color in different formats
+    // (module-level `formatColorAs` is the same pipeline, callable outside render)
     const getHexValue = useCallback(() => {
         return formatHex(color.h, color.s, color.l);
     }, [color]);
@@ -180,10 +209,23 @@ const ColorPickerRoot = React__default.forwardRef(({ value, defaultValue = '#000
         }
         return getFormattedValue();
     }, [mode, gradient, getFormattedValue]);
-    // Notify parent of color changes
-    const prevOutputRef = useRef(undefined);
+    // Notify parent of color changes.
+    //
+    // 🔴 A controlled component NEVER emits for a value it wasn't given by the
+    // user. This used to fire on mount — `prevOutputRef` started `undefined`, so
+    // the first pass always "differed" — handing the consumer a value nobody
+    // chose. Because the output is re-derived through hex -> HSL (integer
+    // rounding) -> hex, that value often wasn't even the one passed in, so a
+    // parent storing what it receives recorded a phantom user edit, and a parent
+    // that fed it back re-rendered into an infinite emit loop.
     useEffect(() => {
         const output = getOutputValue();
+        // First pass: seed the baseline, emit nothing. Mounting is not a user edit.
+        if (!hasSeededOutputRef.current) {
+            hasSeededOutputRef.current = true;
+            prevOutputRef.current = output;
+            return;
+        }
         if (onChange && !disabled && output !== prevOutputRef.current) {
             prevOutputRef.current = output;
             onChange(output);

package/dist/components/forms/ColorPicker/ColorPickerBody.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx } from 'react/jsx-runtime';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
-import { useContext, useRef, useEffect } from 'react';
+import { useContext, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { cn } from '../../../utils/cn.js';
@@ -16,15 +16,19 @@ import { useIsClient } from '../../../hooks/useIsClient.js';
  */
 const ColorPickerBody = ({ children, className, portal = true, animation = true, ...rest }) => {
     const context = useContext(ColorPickerContext);
-    const contentRef = useRef(null);
     const shouldReduceMotion = useReducedMotion();
     const isClient = useIsClient();
     if (!context) {
         throw new Error('ColorPicker.Body must be used within a ColorPicker');
     }
     const { isOpen, setIsOpen, theme, triggerRef, placement, offset, dialogId } = context;
-    // Use positioning hook (same as Dropdown/Select)
-    const { position, cssVariables } = useSelectPortal({
+    // Use positioning hook (same as Dropdown/Select).
+    // 🔴 `contentRef` MUST come from the hook and be attached to the panel below:
+    // the hook measures the panel through it to clamp against the viewport. Body
+    // used to declare its own ref, leaving the hook's forever null — so
+    // `measureDropdownWidth` fell through to the TRIGGER's width, clamping fitted
+    // a ~32px box, and the ~320px panel ran straight off the right edge.
+    const { position, cssVariables, contentRef } = useSelectPortal({
         triggerRef,
         isOpen: isOpen || false,
         placement,

package/dist/components/forms/Combobox/Combobox.js

@@ -134,7 +134,7 @@ const ComboboxOptions = ({ isOpen, onClose, triggerRef, portal, placement, offse
  * ```
  */
 const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", label, helperText, size = "md", state = "default", clearable = true, iconStart, iconEnd, openOnFocus = true, filterFn = defaultFilterFn, emptyMessage = "No results found", creatable = false, onCreateOption, createLabel, required = false, name, className, wrapperClassName, inputClassName, dropdownClassName, theme: themeOverrides, portal = true, placement = "bottom-start", offset = 8, elevation, lift, id, ...props }, ref) => {
-    var _a;
+    var _a, _b, _c, _d, _e, _f, _g;
     // Merge theme
     const theme = React__default.useMemo(() => ({ ...comboboxTheme, ...(themeOverrides || {}) }), [themeOverrides]);
     // Generate unique ID
@@ -405,8 +405,12 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     // Icon padding
     const hasLeftIcon = Boolean(iconStart);
     const hasRightIcon = Boolean(iconEnd);
-    const iconStartPadding = hasLeftIcon ? theme.iconPadding.left : "";
-    const iconEndPadding = hasRightIcon ? theme.iconPadding.right : "";
+    const iconStartPadding = hasLeftIcon
+        ? ((_c = (_b = theme.iconPaddings) === null || _b === void 0 ? void 0 : _b.left) === null || _c === void 0 ? void 0 : _c[size]) || theme.iconPadding.left
+        : "";
+    const iconEndPadding = hasRightIcon
+        ? ((_e = (_d = theme.iconPaddings) === null || _d === void 0 ? void 0 : _d.right) === null || _e === void 0 ? void 0 : _e[size]) || theme.iconPadding.right
+        : "";
     // Create a modified selectState for the provider with our custom filtered options
     const modifiedSelectState = React__default.useMemo(() => ({
         ...selectState,
@@ -416,7 +420,7 @@ const ComboboxInner = ({ options, value, onChange, placeholder = "Search...", la
     return (jsx(SelectProvider, { selectState: modifiedSelectState, size: size, componentState: state, theme: theme, searchable: true, enableTypeahead: false, children: jsxs("div", { ref: ref, className: cn("relative", containerClasses, stateClass, wrapperClassName), ...props, children: [label && (typeof label === 'string' ? (jsx(FormLabel, { htmlFor: comboboxId, state: state, required: required, children: label })) : (label)), jsxs("div", { ref: wrapperRef, className: theme.wrapperStyle, children: [jsx("div", { className: cn(inputGroupClasses, stateClasses, className), children: jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: comboboxId, type: "text", role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": listboxId, "aria-activedescendant": highlightedIndex >= 0 &&
                                             customFilteredOptions[highlightedIndex]
                                             ? `${comboboxId}-option-${customFilteredOptions[highlightedIndex].id}`
-                                            : undefined, "aria-autocomplete": "list", "aria-invalid": isInvalid, "aria-describedby": helperText ? `${comboboxId}-helper` : undefined, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, (hasRightIcon || showClearButton) && iconEndPadding, showClearButton && "pr-8", inputClassName), value: searchValue, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, required: required }), hasLeftIcon && (jsx("div", { className: theme.iconStartStyle, children: iconStart })), showClearButton && (jsx("button", { type: "button", className: theme.clearButtonStyle, onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: jsx(X, { className: theme.clearIconStyle }) })), hasRightIcon && !showClearButton && (jsx("div", { className: theme.iconEndStyle, children: iconEnd }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, listboxId: listboxId, comboboxId: comboboxId, elevation: elevation, lift: lift })] }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${comboboxId}-helper`, className: cn(helperTextClasses, helperTextStateClasses), children: helperText })) : (helperText)), name && (jsx("input", { type: "hidden", name: name, value: value !== undefined ? String(value) : "" }))] }) }));
+                                            : undefined, "aria-autocomplete": "list", "aria-invalid": isInvalid, "aria-describedby": helperText ? `${comboboxId}-helper` : undefined, autoComplete: "off", className: cn(inputClasses, sizeClasses, iconStartPadding, (hasRightIcon || showClearButton) && iconEndPadding, showClearButton && "pr-8", inputClassName), value: searchValue, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, required: required }), hasLeftIcon && (jsx("div", { className: ((_f = theme.iconStartStyles) === null || _f === void 0 ? void 0 : _f[size]) || theme.iconStartStyle, children: iconStart })), showClearButton && (jsx("button", { type: "button", className: theme.clearButtonStyle, onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: jsx(X, { className: theme.clearIconStyle }) })), hasRightIcon && !showClearButton && (jsx("div", { className: ((_g = theme.iconEndStyles) === null || _g === void 0 ? void 0 : _g[size]) || theme.iconEndStyle, children: iconEnd }))] }) }), jsx(ComboboxOptions, { isOpen: isOpen, onClose: () => setIsOpen(false), triggerRef: wrapperRef, portal: portal, placement: placement, offset: offset, emptyMessage: emptyMessage, className: dropdownClassName, listboxId: listboxId, comboboxId: comboboxId, elevation: elevation, lift: lift })] }), helperText && (typeof helperText === 'string' ? (jsx("p", { id: `${comboboxId}-helper`, className: cn(helperTextClasses, helperTextStateClasses), children: helperText })) : (helperText)), name && (jsx("input", { type: "hidden", name: name, value: value !== undefined ? String(value) : "" }))] }) }));
 };
 const ComboboxForwarded = React__default.forwardRef(ComboboxInner);
 ComboboxForwarded.displayName = "Combobox";

package/dist/components/forms/Combobox/Combobox.theme.js

@@ -31,6 +31,15 @@ const comboboxTheme = {
     iconEndStyle: "absolute inset-y-0 right-0 flex items-center pr-2 pointer-events-none text-[var(--color-text-muted)]",
     // Icon padding configuration
     iconPadding: formsBaseTheme.iconStyles.padding,
+    // Size-aware icon geometry: slot inset from --form-px-*, glyph from
+    // --form-icon-size-*. Flat keys above stay as the fallback.
+    iconStartStyles: formsBaseTheme.iconStyles.leftSizes,
+    iconEndStyles: formsBaseTheme.iconStyles.rightSizes,
+    iconSizes: formsBaseTheme.iconStyles.sizes,
+    iconPaddings: {
+        left: formsBaseTheme.iconStyles.paddingLeftSizes,
+        right: formsBaseTheme.iconStyles.paddingRightSizes,
+    },
     // Clear button styles
     clearButtonStyle: "absolute inset-y-0 right-0 flex items-center pr-2 cursor-pointer " +
         "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors z-10",

package/dist/components/forms/Combobox/Combobox.types.d.ts

@@ -97,8 +97,21 @@ export interface ComboboxTheme {
     sizes: Record<ComboboxSize, string>;
     states: Record<ComboboxState, string>;
     focusStates: Record<ComboboxState, string>;
+    /** @deprecated size-blind; superseded by `iconStartStyles` */
     iconStartStyle: string;
+    /** @deprecated size-blind; superseded by `iconEndStyles` */
     iconEndStyle: string;
+    /** Per-size leading icon slot (position + inset) */
+    iconStartStyles?: Partial<Record<ComboboxSize, string>>;
+    /** Per-size trailing icon slot (position + inset) */
+    iconEndStyles?: Partial<Record<ComboboxSize, string>>;
+    /** Per-size sizing for built-in icons */
+    iconSizes?: Record<ComboboxSize, string>;
+    /** Per-size text runway reserved for each icon slot */
+    iconPaddings?: {
+        left?: Partial<Record<ComboboxSize, string>>;
+        right?: Partial<Record<ComboboxSize, string>>;
+    };
     iconPadding: {
         left: string;
         right: string;