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

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

@@ -51,8 +51,16 @@ const selectTheme = {
     helperTextStates: formsBaseTheme.helperTextStates,
     // Left icon style - inherited from common form theme
     iconStartStyle: formsBaseTheme.iconStyles.left,
-    // Right icon style - inherited from common form theme
+    iconStartStyles: formsBaseTheme.iconStyles.leftSizes,
+    iconStartPaddings: formsBaseTheme.iconStyles.paddingLeftSizes,
+    // Right icon (the chevron) — size-aware: the slot insets from the control's
+    // own --form-px-*, the glyph ramps 12/14/16, and the text runway is reserved
+    // to match. Flat `pr-3` + `size-4` at every size left the sm chevron both
+    // oversized against 14px text and further from the edge than it looked.
     iconEndStyle: formsBaseTheme.iconStyles.right,
+    iconEndStyles: formsBaseTheme.iconStyles.rightSizes,
+    iconEndSizes: formsBaseTheme.iconStyles.sizes,
+    iconEndPaddings: formsBaseTheme.iconStyles.paddingRightSizes,
     // Check icon style for selected options
     checkIconStyle: "absolute inset-y-0 right-0 flex items-center pr-3 text-[var(--color-primary)] " +
         "dark:text-[var(--color-primary-400)]",

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

@@ -26,7 +26,7 @@ export interface SelectBaseProps {
  * Select component props
  * @template T The type of the select value
  */
-export interface SelectProps<T = unknown> extends SelectBaseProps {
+export interface SelectCommonProps<T = unknown> extends SelectBaseProps {
     /** ID for the select component */
     id?: string;
     /** Name for the select component */
@@ -35,8 +35,6 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     size?: SelectSize;
     /** Current state of the select component */
     state?: SelectState;
-    /** Currently selected option */
-    value?: T;
     /** Custom display value to show in trigger (overrides selected option label) */
     displayValue?: React.ReactNode;
     /** Placeholder text when no option is selected */
@@ -51,12 +49,8 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     label?: React.ReactNode;
     /** Helper text below the select — pass a string for default styling, or a ReactNode for full control */
     helperText?: React.ReactNode;
-    /** Enable multi-select mode — value becomes T[] and chips are rendered in trigger */
-    multiple?: boolean;
     /** Maximum number of chips to display before showing "+N more" (default: 3) */
     maxDisplayedChips?: number;
-    /** Called when the selection changes */
-    onChange?: (value: T) => void;
     /** Called when the select receives focus */
     onFocus?: (event: React.FocusEvent<HTMLButtonElement>) => void;
     /** Called when the select loses focus */
@@ -113,7 +107,74 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     elevation?: SurfaceElevation;
     /** `false` opts out of the relative lift — paints at the listbox's base rung. */
     lift?: boolean;
+    /**
+     * Accessible name for a Select with no visible `label` — e.g. a control sitting
+     * in a toolbar. `aria-labelledby` wins over this when both are present.
+     *
+     * 🔴 Declared explicitly because TypeScript does NOT check hyphenated JSX
+     * attributes against a component's props type: before this existed,
+     * `<Select aria-label="…" />` typechecked cleanly and was then dropped at
+     * runtime, leaving the trigger with no accessible name at all.
+     */
+    "aria-label"?: string;
+}
+/**
+ * Single-select props — the default mode.
+ * `value` is one `T` and `onChange` receives one `T`.
+ */
+export interface SelectSingleProps<T = unknown> extends SelectCommonProps<T> {
+    /** Enable multi-select mode. Omit or pass `false` for single-select. */
+    multiple?: false;
+    /**
+     * Currently selected option.
+     * 🔴 `NoInfer` matters: without it TS treats this as an inference site for `T`,
+     * so `<Select multiple value={["a"]} />` infers `T = string[]` from THIS branch
+     * and then demands `SelectOption<string[]>[]` for `options`. Inference must come
+     * from `options` alone; the value/onChange shapes follow from it.
+     */
+    value?: NoInfer<T>;
+    /** Called when the selection changes */
+    onChange?: (value: NoInfer<T>) => void;
 }
+/**
+ * Multi-select props — `multiple` is `true`, so `value` is an ARRAY and
+ * `onChange` receives the full next array (not the toggled item).
+ */
+export interface SelectMultipleProps<T = unknown> extends SelectCommonProps<T> {
+    /** Enable multi-select mode — chips are rendered in the trigger. */
+    multiple: true;
+    /** Currently selected options. `NoInfer` for the reason given on the single variant. */
+    value?: NoInfer<T>[];
+    /** Called with the complete next selection whenever it changes */
+    onChange?: (value: NoInfer<T>[]) => void;
+}
+/**
+ * Select component props — a discriminated union on `multiple`.
+ *
+ * 🔴 `value`/`onChange` change shape with the mode, which a single
+ * `value?: T` could not express: multi-select genuinely hands back a `T[]`.
+ * The implementation always did this and lied about it with
+ * `onChange?.(updated as unknown as T)`, so `<Select multiple value={["a"]} />`
+ * — correct usage, and what the JSDoc documented — failed to type-check while
+ * `onChange` handlers were silently typed as the element type instead of the
+ * array. Narrow with `multiple` to get the right shape on both.
+ *
+ * @template T The type of an individual option value (NOT the array)
+ */
+export type SelectProps<T = unknown> = SelectSingleProps<T> | SelectMultipleProps<T>;
+/**
+ * @internal Widened shape the implementation destructures. A union cannot be
+ * destructured and then called (`onChange` would be a union of incompatible
+ * signatures), so the mode-dependent members are widened exactly once, here,
+ * and the public `Select` export casts back to the precise union. This is the
+ * single sanctioned cast — it replaces three `as unknown as T` casts that
+ * previously misreported the runtime contract to consumers.
+ */
+export type SelectInternalProps<T = unknown> = SelectCommonProps<T> & {
+    multiple?: boolean;
+    value?: T | T[];
+    onChange?: (value: T | T[]) => void;
+};
 /**
  * Select button props
  */
@@ -148,6 +209,8 @@ export interface SelectButtonProps extends SelectBaseProps {
     "aria-describedby"?: string;
     /** ID of the element that labels this button (e.g. form label) */
     "aria-labelledby"?: string;
+    /** Accessible name for a Select with no visible `label` (e.g. a toolbar control) */
+    "aria-label"?: string;
     /** Structural content rendered before iconStart */
     contentStart?: React.ReactNode;
     /** Structural content rendered after iconEnd */
@@ -240,8 +303,23 @@ export interface SelectThemeOverrides {
     helperTextStates?: Partial<Record<SelectState, string>>;
     /** Left icon style */
     iconStartStyle?: string;
-    /** Right icon style */
+    /** Per-size left icon slot style (position + inset) */
+    iconStartStyles?: Partial<Record<SelectSize, string>>;
+    /** Per-size text runway reserved for the left icon */
+    iconStartPaddings?: Partial<Record<SelectSize, string>>;
+    /**
+     * Right icon slot style.
+     * @deprecated superseded by `iconEndStyles`, which insets the slot from the
+     * control's own `--form-px-*` instead of a flat `pr-3` at every size. Still
+     * honoured as a fallback when `iconEndStyles` has no entry for the size.
+     */
     iconEndStyle?: string;
+    /** Per-size right icon slot style (position + inset) */
+    iconEndStyles?: Partial<Record<SelectSize, string>>;
+    /** Per-size sizing for the built-in chevron */
+    iconEndSizes?: Partial<Record<SelectSize, string>>;
+    /** Per-size text runway reserved for the right icon */
+    iconEndPaddings?: Partial<Record<SelectSize, string>>;
     /** Style for the check icon in selected options */
     checkIconStyle?: string;
     /** Icon padding styles */

package/dist/components/forms/Select/useSelectState.d.ts

@@ -5,10 +5,16 @@ import type { SelectOption } from "./Select.types";
 export interface UseSelectStateProps<T = any> {
     /** Array of available options */
     options: SelectOption<T>[];
-    /** Currently selected value (controlled) */
-    value?: T;
+    /** Currently selected value (controlled). `T[]` when `multiple` is set. */
+    value?: T | T[];
     /** Callback when selection changes */
-    onChange?: (value: T) => void;
+    /**
+     * Called when the selection changes. In `multiple` mode the payload is the
+     * complete next `T[]`, not the toggled item — which is why this is widened
+     * rather than `(value: T) => void`. The public `SelectProps` union narrows it
+     * back to the exact shape per mode.
+     */
+    onChange?: (value: T | T[]) => void;
     /** Whether filtering/search is enabled */
     searchable?: boolean;
     /** Whether new options can be created */

package/dist/components/forms/Select/useSelectState.js

@@ -23,7 +23,10 @@ import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 function useSelectState({ options = [], value, onChange, searchable = false, creatable = false, onCreateOption, createLabel, enableTypeahead = true, multiple = false, }) {
     // Core state
     const [isOpen, setIsOpen] = useState(false);
-    const [selectedValue, setSelectedValue] = useState(value);
+    // `value` is widened to `T | T[]` because multi-select hands back an array;
+    // this single-value slot only ever holds the non-array branch (the array lives
+    // in `selectedValues` below), matching the Array.isArray idiom used throughout.
+    const [selectedValue, setSelectedValue] = useState(Array.isArray(value) ? undefined : value);
     const [highlightedIndex, setHighlightedIndex] = useState(-1);
     const [searchValue, setSearchValue] = useState("");
     // Multi-select state

package/dist/components/forms/SelectableCard/SelectableCard.js

@@ -5,6 +5,7 @@ import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { Radio } from '../Radio/Radio.js';
 import { Checkbox } from '../Checkbox/Checkbox.js';
+import { Ripple } from '../../core/shared/Ripple.js';
 import { useOptionalSelectableCardContext } from './SelectableCardContext.js';
 import { selectableCardTheme } from './SelectableCard.theme.js';
 import { SelectableCardGroup } from './SelectableCardGroup.js';
@@ -63,7 +64,7 @@ const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDis
         ? { variants: cardVariants, animate: "rest", whileTap: "press" }
         : {};
     const indicatorNode = resolvedIndicator !== "none" && (jsx("div", { className: cn(theme.indicator, "pointer-events-none"), "aria-hidden": "true", children: resolvedIndicator === "radio" ? (jsx(Radio, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) : (jsx(Checkbox, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) }));
-    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode] }));
+    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode, jsx(Ripple, { disabled: isDisabled })] }));
 });
 SelectableCardRoot.displayName = "SelectableCard";
 // ─── Compound Export ─────────────────────────────────────────────────────────

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

@@ -2,7 +2,7 @@ const selectableCardTheme = {
     group: "flex flex-col gap-3",
     card: 
     // Base layout — no justify-between; indicator position handled by render order
-    "relative flex items-start gap-3 rounded-[var(--radius-base)] cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-200 " +
+    "relative flex items-start gap-3 rounded-[var(--radius-base)] cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-[var(--motion-duration-base)] " +
         // Default state
         "border border-[var(--color-border)] bg-[var(--color-surface)] " +
         "dark:bg-[var(--color-background)] " +

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

@@ -12,7 +12,7 @@
 const switchTheme = {
     container: "flex w-full justify-between items-center gap-4",
     // Structural base only — no state colors (those live in `trackStates`)
-    track: "group rounded-full cursor-pointer shadow-inner-real-sm transition-colors duration-500 motion-reduce:transition-none outline-1 outline-[var(--color-border)] peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--color-primary-600)]",
+    track: "group rounded-full cursor-pointer shadow-inner-real-sm transition-colors duration-[var(--motion-duration-slowest)] motion-reduce:transition-none outline-1 outline-[var(--color-border)] peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--color-primary-600)]",
     // Resolved in JS and layered via cn() so later keys win (tailwind-merge dedupes bg-*).
     // No `invalid` key: a switch is binary — on and off are both valid values, so there is
     // nothing to validate. (See §9 carve-out: invalid only applies to controls with a value.)
@@ -25,7 +25,7 @@ const switchTheme = {
     // off-track, which is never white). ON state: Switch.tsx swaps the fill to
     // --color-primary-contrast so the knob stays visible on any primary track — white
     // on a dark primary, dark on a light primary (the near-white-primary case).
-    thumb: "rounded-full bg-gradient-to-b from-neutral-200 via-neutral-50 to-white shadow-real-lg border-t border-white/80 dark:border-white/20 transition-shadow duration-300 motion-reduce:transition-none",
+    thumb: "rounded-full bg-gradient-to-b from-neutral-200 via-neutral-50 to-white shadow-real-lg border-t border-white/80 dark:border-white/20 transition-shadow duration-[var(--motion-duration-slow)] motion-reduce:transition-none",
     description: "text-sm text-[var(--color-text-muted)] -mt-1.5",
     trackSizes: {
         sm: "w-9 h-5",

package/dist/components/forms/Textarea/Textarea.js

@@ -1,13 +1,12 @@
 "use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useState } from 'react';
+import React__default from 'react';
 import { FormLabel } from '../FormLabel/FormLabel.js';
 import { textareaTheme } from './Textarea.theme.js';
 import { cn } from '../../../utils/cn.js';
 
 const Textarea = React__default.forwardRef(({ size = "md", state = "default", className = "", label, labelClassName = "", helperText, errorMessage, helperTextClassName = "", wrapperClassName = "", inputGroupClassName = "", id, theme = {}, required, rows = 3, cols, unstyled = false, onValueChange, ...props }, ref) => {
     var _a, _b, _c, _d;
-    const [isFocused, setIsFocused] = useState(false);
     const generatedId = React__default.useId();
     const inputId = id || generatedId;
     // Derived state flags for internal use
@@ -16,17 +15,20 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
     // errorMessage takes precedence over helperText while invalid; helperText
     // behavior is unchanged otherwise.
     const displayedMessage = isInvalid && errorMessage ? errorMessage : helperText;
+    // Pull onChange out of props so the explicit handler below isn't overwritten
+    // by the spread, and wire it ONCE — 🔴 both render paths must use it. The
+    // `unstyled` early return below used to drop `onValueChange` entirely, so
+    // `value` + `onValueChange` + `unstyled` produced a permanently read-only
+    // textarea: React saw a controlled value with no onChange, warned, and
+    // nothing the user typed ever reached the consumer.
+    const { onChange: propsOnChange, ...restProps } = props;
+    const handleChange = (event) => {
+        propsOnChange === null || propsOnChange === void 0 ? void 0 : propsOnChange(event);
+        onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(event.target.value);
+    };
     // If unstyled, render only the textarea element
     if (unstyled) {
-        return (jsx("textarea", { ref: ref, id: inputId, className: className, disabled: isDisabled, "aria-invalid": isInvalid, required: required, rows: rows, cols: cols, onFocus: (e) => {
-                var _a;
-                setIsFocused(true);
-                (_a = props.onFocus) === null || _a === void 0 ? void 0 : _a.call(props, e);
-            }, onBlur: (e) => {
-                var _a;
-                setIsFocused(false);
-                (_a = props.onBlur) === null || _a === void 0 ? void 0 : _a.call(props, e);
-            }, ...props }));
+        return (jsx("textarea", { ref: ref, id: inputId, className: className, disabled: isDisabled, "aria-invalid": isInvalid, required: required, rows: rows, cols: cols, onChange: handleChange, ...restProps }));
     }
     // State class for CSS selectors
     const stateClass = isInvalid
@@ -34,8 +36,6 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
         : isDisabled
             ? "state-disabled"
             : "state-default";
-    // Pull onChange out of props so the explicit handler below isn't overwritten by the spread
-    const { onChange: propsOnChange, ...restProps } = props;
     // Get theme classes
     const wrapperClasses = theme.wrapperStyle || textareaTheme.wrapperStyle || "";
     const inputGroupClasses = theme.inputGroupStyle || textareaTheme.inputGroupStyle || "";
@@ -43,18 +43,7 @@ const Textarea = React__default.forwardRef(({ size = "md", state = "default", cl
     const sizeClasses = ((_a = theme.sizes) === null || _a === void 0 ? void 0 : _a[size]) || ((_b = textareaTheme.sizes) === null || _b === void 0 ? void 0 : _b[size]) || "";
     const stateClasses = ((_c = theme.states) === null || _c === void 0 ? void 0 : _c[state]) || ((_d = textareaTheme.states) === null || _d === void 0 ? void 0 : _d[state]) || "";
     const helperTextClasses = theme.helperText || textareaTheme.helperText || "";
-    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }) })) : (label)), jsx("div", { children: jsx("div", { className: cn(inputGroupClasses, stateClasses, inputGroupClassName), children: jsx("div", { className: "relative flex-1", children: jsx("textarea", { ref: ref, id: inputId, className: cn(baseClasses, sizeClasses, className), disabled: isDisabled, "aria-invalid": isInvalid, "aria-describedby": displayedMessage ? `${inputId}-helper` : undefined, required: required, rows: rows, cols: cols, onFocus: (e) => {
-                                var _a;
-                                setIsFocused(true);
-                                (_a = props.onFocus) === null || _a === void 0 ? void 0 : _a.call(props, e);
-                            }, onBlur: (e) => {
-                                var _a;
-                                setIsFocused(false);
-                                (_a = props.onBlur) === null || _a === void 0 ? void 0 : _a.call(props, e);
-                            }, onChange: (e) => {
-                                propsOnChange === null || propsOnChange === void 0 ? void 0 : propsOnChange(e);
-                                onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(e.target.value);
-                            }, ...restProps }) }) }) }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: `${inputId}-helper`, role: isInvalid ? "alert" : undefined, className: cn(helperTextClasses, helperTextClassName), children: displayedMessage })) : (displayedMessage))] }));
+    return (jsxs("div", { className: cn(wrapperClasses, stateClass, wrapperClassName), children: [label && (typeof label === 'string' ? (jsx("div", { className: "mb-1", children: jsx(FormLabel, { htmlFor: inputId, className: labelClassName, state: state, required: required, children: label }) })) : (label)), jsx("div", { children: jsx("div", { className: cn(inputGroupClasses, stateClasses, inputGroupClassName), children: jsx("div", { className: "relative flex-1", children: jsx("textarea", { ref: ref, id: inputId, className: cn(baseClasses, sizeClasses, className), disabled: isDisabled, "aria-invalid": isInvalid, "aria-describedby": displayedMessage ? `${inputId}-helper` : undefined, required: required, rows: rows, cols: cols, onChange: handleChange, ...restProps }) }) }) }), displayedMessage && (typeof displayedMessage === 'string' ? (jsx("div", { id: `${inputId}-helper`, role: isInvalid ? "alert" : undefined, className: cn(helperTextClasses, helperTextClassName), children: displayedMessage })) : (displayedMessage))] }));
 });
 Textarea.displayName = "Textarea";
 

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

@@ -30,12 +30,21 @@ const timePickerTheme = {
     // Icon padding styles - inherited from common form theme
     iconStartPadding: formsBaseTheme.iconStyles.padding.left,
     iconEndPadding: formsBaseTheme.iconStyles.padding.right,
+    // 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,
+    },
     // Placeholder text style - matches Select/Combobox placeholder styling
     placeholderTextStyle: formsBaseTheme.placeholderStyle,
     // Selected value text style
     valueTextStyle: "text-[var(--color-text-primary)]",
     // Clear button styles (positioned between left content and right icon)
-    clearButtonStyle: "absolute right-8 top-1/2 -translate-y-1/2 p-1 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors z-10",
+    clearButtonStyle: "absolute right-8 top-1/2 -translate-y-1/2 p-1 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface)] transition-colors z-10",
     // Dropdown container styles (TimePicker-specific)
     // Width is controlled by trigger size via estimatedWidth parameter
     dropdownStyle: "fixed z-[1000] backdrop-blur-md border border-[var(--color-border)] rounded-[var(--form-radius)] shadow-lg overflow-hidden",

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

@@ -141,6 +141,17 @@ export interface TimePickerThemeOverrides {
     iconStartPadding?: string;
     /** End icon padding */
     iconEndPadding?: string;
+    /** Per-size leading icon slot (position + inset) */
+    iconStartStyles?: Partial<Record<TimePickerSize, string>>;
+    /** Per-size trailing icon slot (position + inset) */
+    iconEndStyles?: Partial<Record<TimePickerSize, string>>;
+    /** Per-size sizing for the built-in clock/caret/clear icons */
+    iconSizes?: Record<TimePickerSize, string>;
+    /** Per-size text runway reserved for each icon slot */
+    iconPaddings?: {
+        left?: Partial<Record<TimePickerSize, string>>;
+        right?: Partial<Record<TimePickerSize, string>>;
+    };
     /** Placeholder text style */
     placeholderTextStyle?: string;
     /** Selected value text style */

package/dist/components/forms/TimePicker/TimePickerTrigger.js

@@ -11,7 +11,7 @@ import { TimePickerContext } from './TimePickerContext.js';
  * Follows the same visual pattern as DatePickerTrigger and SelectButton
  */
 const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md', clearable, onClear, iconStart, iconEnd, className, inputValue, onInputChange, onInputFocus, onInputKeyDown, format, period, onPeriodToggle, placeholder, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedby, }) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     const context = useContext(TimePickerContext);
     if (!context) {
         throw new Error('TimePickerTrigger must be used within a TimePicker');
@@ -21,12 +21,14 @@ const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md
     const sizeStyle = ((_a = theme.triggerSizes) === null || _a === void 0 ? void 0 : _a[size]) || "";
     const stateStyle = ((_b = theme.triggerStates) === null || _b === void 0 ? void 0 : _b[state]) || "";
     const hoverStateStyle = ((_c = theme.triggerHoverStates) === null || _c === void 0 ? void 0 : _c[state]) || "";
-    const iconStartStyle = theme.iconStartStyle || "";
+    const iconStartStyle = ((_d = theme.iconStartStyles) === null || _d === void 0 ? void 0 : _d[size]) || theme.iconStartStyle || "";
+    // Glyph ramps with the control (--form-icon-size-*), not a flat h-4 w-4.
+    const iconSizeStyle = ((_e = theme.iconSizes) === null || _e === void 0 ? void 0 : _e[size]) || "size-4";
     const inputStyle = theme.inputStyle || "";
     const periodToggleStyle = theme.periodToggleStyle || "";
     // Apply focused styles when open — same pattern as SelectButton and DatePickerTrigger
     const activeFocusState = isOpen
-        ? ((_d = theme.triggerFocusStates) === null || _d === void 0 ? void 0 : _d[state]) || "shadow-[inset_0_0_0_1px_var(--color-primary-600)] ring-4 ring-[var(--color-primary)]/10 dark:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20"
+        ? ((_f = theme.triggerFocusStates) === null || _f === void 0 ? void 0 : _f[state]) || "shadow-[inset_0_0_0_1px_var(--color-primary-600)] ring-4 ring-[var(--color-primary)]/10 dark:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20"
         : "";
     // Determine whether start icon is present (for input padding)
     const hasStartIcon = iconStart !== undefined ? Boolean(iconStart) : true;
@@ -45,10 +47,10 @@ const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md
                 (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.focus();
                 setIsOpen(true);
             }, className: cn(baseStyle, stateStyle, hoverStateStyle, activeFocusState, 'w-full items-center', className // User overrides take highest precedence
-            ), children: [jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: id, type: "text", inputMode: "numeric", value: inputValue, onChange: (e) => onInputChange(e.target.value), onFocus: onInputFocus, onKeyDown: onInputKeyDown, placeholder: placeholder, maxLength: 5, disabled: disabled, className: cn(inputStyle, sizeStyle, hasStartIcon && iconStartPadding), role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-controls": dialogId, "aria-label": "Enter time", "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, autoComplete: "off" }), iconStart !== undefined ? (iconStart && jsx("div", { className: iconStartStyle, children: iconStart })) : (jsx("div", { className: iconStartStyle, children: jsx(Clock, { className: "h-4 w-4" }) }))] }), format === '12h' && (jsx("button", { type: "button", onClick: onPeriodToggle, disabled: disabled, className: cn(periodToggleStyle, "shrink-0"), "aria-label": `Toggle AM/PM, current: ${period}`, tabIndex: -1, children: period || 'AM' })), clearable && hasValue && !disabled && (jsx("button", { type: "button", onClick: (e) => {
+            ), children: [jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: id, type: "text", inputMode: "numeric", value: inputValue, onChange: (e) => onInputChange(e.target.value), onFocus: onInputFocus, onKeyDown: onInputKeyDown, placeholder: placeholder, maxLength: 5, disabled: disabled, className: cn(inputStyle, sizeStyle, hasStartIcon && iconStartPadding), role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-controls": dialogId, "aria-label": "Enter time", "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, autoComplete: "off" }), iconStart !== undefined ? (iconStart && jsx("div", { className: iconStartStyle, children: iconStart })) : (jsx("div", { className: iconStartStyle, children: jsx(Clock, { className: iconSizeStyle }) }))] }), format === '12h' && (jsx("button", { type: "button", onClick: onPeriodToggle, disabled: disabled, className: cn(periodToggleStyle, "shrink-0"), "aria-label": `Toggle AM/PM, current: ${period}`, tabIndex: -1, children: period || 'AM' })), clearable && hasValue && !disabled && (jsx("button", { type: "button", onClick: (e) => {
                         e.stopPropagation();
                         onClear === null || onClear === void 0 ? void 0 : onClear();
-                    }, className: "shrink-0 p-0.5 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors", "aria-label": "Clear time", tabIndex: -1, children: jsx(X, { className: "w-4 h-4" }) })), iconEnd !== undefined ? (iconEnd && (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: iconEnd }))) : (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: jsx(CaretUpDown, { className: "h-4 w-4" }) }))] }) }));
+                    }, className: "shrink-0 p-0.5 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface)] transition-colors", "aria-label": "Clear time", tabIndex: -1, children: jsx(X, { className: iconSizeStyle }) })), iconEnd !== undefined ? (iconEnd && (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: iconEnd }))) : (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: jsx(CaretUpDown, { className: iconSizeStyle }) }))] }) }));
 };
 
 export { TimePickerTrigger };

package/dist/components/forms/forms.theme.d.ts

@@ -5,6 +5,8 @@
  */
 export declare const formsBaseTheme: {
     wrapperStyle: string;
+    /** The field edge alone — for controls that must supply their own transition/fill. */
+    inputGroupBorderStyle: string;
     inputGroupBaseStyle: string;
     controlBaseStyle: string;
     sizes: {
@@ -51,6 +53,61 @@ export declare const formsBaseTheme: {
             left: string;
             right: string;
         };
+        /**
+         * The leading-icon slot, inset by the control's own horizontal padding —
+         * EXACTLY, not the trailing slot's `− 4px`. A leading icon stands where the
+         * text would have started, so matching `--form-px-*` keeps one constant left
+         * edge for a field's contents whether or not it has an icon. The trailing
+         * slot is chrome rather than content, which is why it insets tighter.
+         */
+        leftSizes: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        /** Text runway for the leading slot: inset + icon + an 8px gap (32/36/40). */
+        paddingLeftSizes: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        /**
+         * The trailing-icon slot, inset from the right edge by the control's own
+         * horizontal padding MINUS 4px (8 / 10 / 12 at the default theme). Tighter
+         * than the text inset on purpose: a chevron is mostly whitespace, so at the
+         * same metric distance it reads as further from the edge than a glyph does.
+         * Derived from `--form-px-*` rather than a literal, so retuning a theme's
+         * control padding moves the icon with it.
+         */
+        rightSizes: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        /**
+         * Text runway reserved for that slot: inset + icon + an 8px gap, i.e.
+         * `--form-px-*` + 16/18/20 (28 / 32 / 36). It replaces a flat `pr-10` that
+         * over-reserved at every size.
+         */
+        paddingRightSizes: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        /**
+         * The glyph itself, ramping with the control (12 / 14 / 16px) instead of a
+         * flat 16 — at `sm` a 16px icon out-weighed the 14px text beside it.
+         *
+         * 🔴 Reads --form-icon-size-*, not a Tailwind literal: icon size was the one
+         * axis of a field's geometry a theme could not retune, so a preset that
+         * scaled height/padding/type left every decorator at its hardcoded size.
+         * Not to be confused with --button-icon-square-*, which is a BUTTON's box.
+         */
+        sizes: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
     };
     dropdownStyles: {
         container: string;