@urbicon-ui/blocks 6.21.1 → 6.21.3

package/dist/primitives/Combobox/combobox.variants.d.ts

@@ -2,14 +2,14 @@ import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const comboboxVariants: ((props?: {
     tier?: "commit" | "modify" | undefined;
     variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-    size?: "sm" | "md" | "lg" | undefined;
+    size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
     open?: boolean | undefined;
     disabled?: boolean | undefined;
 } | undefined) => {
     base: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -18,7 +18,7 @@ export declare const comboboxVariants: ((props?: {
     label: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -27,7 +27,7 @@ export declare const comboboxVariants: ((props?: {
     requiredMark: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -36,7 +36,7 @@ export declare const comboboxVariants: ((props?: {
     inputWrapper: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -45,7 +45,7 @@ export declare const comboboxVariants: ((props?: {
     input: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -54,16 +54,16 @@ export declare const comboboxVariants: ((props?: {
     message: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
-    hint: (props?: ({
+    helper: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -72,7 +72,7 @@ export declare const comboboxVariants: ((props?: {
     listbox: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -81,7 +81,7 @@ export declare const comboboxVariants: ((props?: {
     option: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -90,7 +90,7 @@ export declare const comboboxVariants: ((props?: {
     optionActive: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -99,7 +99,25 @@ export declare const comboboxVariants: ((props?: {
     optionSelected: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    group: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    groupLabel: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -108,7 +126,16 @@ export declare const comboboxVariants: ((props?: {
     noResults: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    loading: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -117,7 +144,7 @@ export declare const comboboxVariants: ((props?: {
     clear: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -126,7 +153,7 @@ export declare const comboboxVariants: ((props?: {
     chevronButton: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {
@@ -135,7 +162,52 @@ export declare const comboboxVariants: ((props?: {
     chevron: (props?: ({
         tier?: "commit" | "modify" | undefined;
         variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
-        size?: "sm" | "md" | "lg" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    control: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    search: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    tag: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    tagLabel: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
+        open?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    tagRemove: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | "underline" | undefined;
+        size?: "sm" | "md" | "lg" | "xs" | "xl" | undefined;
         open?: boolean | undefined;
         disabled?: boolean | undefined;
     } & {

package/dist/primitives/Combobox/combobox.variants.js

@@ -15,7 +15,7 @@ export const comboboxVariants = tv({
             'disabled:opacity-50 disabled:cursor-not-allowed'
         ],
         message: 'text-xs text-danger',
-        hint: 'text-xs text-text-tertiary',
+        helper: 'text-xs text-text-tertiary',
         // `position`, `width`, `overflow-y` are set inline in Combobox.svelte
         // so the native `popover="manual"` top-layer rendering works
         // correctly and the UA's `overflow: auto` doesn't render a duplicate
@@ -38,7 +38,14 @@ export const comboboxVariants = tv({
         ],
         optionActive: 'bg-surface-hover',
         optionSelected: 'bg-surface-selected font-medium',
+        // Grouped options (parity with Select). `group` is a bare container; the
+        // label is a quiet, uppercase section header.
+        group: '',
+        groupLabel: 'px-3 py-1.5 text-xs font-medium text-text-tertiary uppercase tracking-wider',
         noResults: 'px-3 py-4 text-center text-sm text-text-tertiary',
+        // Async-search in-flight message (queryFn). Mirrors noResults so both listbox
+        // status rows read alike; separate slot so consumers can style them apart.
+        loading: 'px-3 py-4 text-center text-sm text-text-tertiary',
         clear: [
             'absolute right-2 top-1/2 -translate-y-1/2 rounded-modify p-1.5',
             'text-text-tertiary hover:text-text-primary',
@@ -58,46 +65,120 @@ export const comboboxVariants = tv({
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
             'disabled:cursor-not-allowed disabled:hover:text-text-tertiary'
         ],
-        chevron: ['w-4 h-4', 'transition-transform duration-[var(--blocks-duration-fast)]']
+        chevron: ['w-4 h-4', 'transition-transform duration-[var(--blocks-duration-fast)]'],
+        // ── Multi-select tokenizer (only rendered when `multiple`) ──────────────
+        // In multi mode the visible frame moves from the `input` onto `control`: a
+        // flex-wrap box that holds the selected tags and a borderless search input.
+        // The `input` slot (and its full tier/variant/size styling) stays the frame
+        // for single mode — untouched — so the two modes never fight over the same
+        // classes. Frame colour/radius/size come from the axes below, mirroring how
+        // `input` is styled for single mode.
+        control: [
+            'flex w-full flex-wrap items-center border bg-surface-base cursor-text',
+            'transition-colors duration-[var(--blocks-duration-fast)]',
+            'focus-within:outline-none focus-within:ring-2 focus-within:ring-primary/50 focus-within:border-primary'
+        ],
+        // Borderless search input inside `control`; the frame owns the border/ring.
+        search: [
+            'flex-1 min-w-[6rem] border-0 bg-transparent p-0 text-text-primary placeholder:text-text-tertiary',
+            'focus-visible:outline-none focus-visible:ring-0',
+            'disabled:cursor-not-allowed'
+        ],
+        // Removable selection chip. `customTag` replaces this entirely.
+        tag: [
+            'inline-flex max-w-full items-center gap-1 rounded-modify bg-surface-interactive text-text-primary font-medium'
+        ],
+        tagLabel: 'truncate',
+        tagRemove: [
+            'inline-flex shrink-0 items-center justify-center rounded-full',
+            'text-text-tertiary hover:text-text-primary',
+            'transition-colors duration-[var(--blocks-duration-fast)]',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+            'disabled:cursor-not-allowed'
+        ]
     },
     variants: {
         // 3-tier semantic radius for the Combobox input. Default `modify`.
-        // Options keep their own r-interactive; only the input rounding flips.
+        // Options keep their own r-interactive; only the input (and, in multi mode,
+        // the tokenizer `control`) rounding flips.
         tier: {
-            modify: { input: 'rounded-modify' },
-            commit: { input: 'rounded-commit' }
+            modify: { input: 'rounded-modify', control: 'rounded-modify' },
+            commit: { input: 'rounded-commit', control: 'rounded-commit' }
         },
         // Visual style, at parity with Input / Textarea / Select. Default
         // `outlined` reproduces the historical Combobox frame exactly.
+        // Each variant styles both the single-mode `input` frame and the multi-mode
+        // `control` frame identically; `control` drops the per-tag `hover:` shifts
+        // that would misfire when hovering a chip inside the box.
         variant: {
             // Surface-family border: form-control frames stay quiet (`border-subtle`);
             // the `border-neutral` intent token is reserved for Action surfaces
             // (Outline-Button, Menu) where the border must read as clickable.
-            outlined: { input: 'border-border-subtle hover:border-border-default' },
+            outlined: {
+                input: 'border-border-subtle hover:border-border-default',
+                control: 'border-border-subtle hover:border-border-default'
+            },
             filled: {
-                input: 'bg-surface-interactive border-transparent hover:bg-surface-hover focus-visible:bg-surface-base'
+                input: 'bg-surface-interactive border-transparent hover:bg-surface-hover focus-visible:bg-surface-base',
+                control: 'bg-surface-interactive border-transparent focus-within:bg-surface-base'
             },
             ghost: {
-                input: 'bg-transparent border-transparent hover:bg-surface-subtle focus-visible:bg-surface-base focus-visible:border-border-subtle'
+                input: 'bg-transparent border-transparent hover:bg-surface-subtle focus-visible:bg-surface-base focus-visible:border-border-subtle',
+                control: 'bg-transparent border-transparent focus-within:bg-surface-base focus-within:border-border-subtle'
             },
             underline: {
-                input: 'bg-transparent border-0 border-b-2 border-border-subtle rounded-none focus-visible:ring-0'
+                input: 'bg-transparent border-0 border-b-2 border-border-subtle rounded-none focus-visible:ring-0',
+                control: 'bg-transparent border-0 border-b-2 border-border-subtle rounded-none focus-within:ring-0'
             }
         },
         size: {
-            sm: {
+            // Full xs–xl scale, mirroring Input's h-7…h-14 ladder (form-family
+            // symmetry: a dense form should not pair an xs Input with an sm Combobox).
+            // The multi-mode tokenizer (`control`/`search`/`tag`) tracks the same
+            // ladder: `control` uses `min-h-*` (not `h-*`) so it grows as tags wrap,
+            // and reserves right padding (`pr-*`) for the absolute chevron/clear.
+            xs: {
                 // `pointer-coarse:text-base` floors the input to 16px on touch-primary
                 // devices so iOS Safari doesn't auto-zoom (and never un-zoom) on focus.
+                input: 'h-7 px-2 pr-7 text-xs pointer-coarse:text-base',
+                option: 'px-2 py-1 text-xs min-h-[1.75rem]',
+                control: 'min-h-7 gap-1 px-1.5 py-1 pr-7',
+                search: 'text-xs pointer-coarse:text-base',
+                tag: 'text-xs px-1.5 py-0.5',
+                tagRemove: '[&_svg]:h-2.5 [&_svg]:w-2.5'
+            },
+            sm: {
+                // See `xs` — floor to 16px on touch to avoid iOS Safari focus-zoom.
                 input: 'h-8 px-3 pr-8 text-sm pointer-coarse:text-base',
-                option: 'px-2 py-1.5 text-sm min-h-[2rem]'
+                option: 'px-2 py-1.5 text-sm min-h-[2rem]',
+                control: 'min-h-8 gap-1 px-2 py-1 pr-8',
+                search: 'text-sm pointer-coarse:text-base',
+                tag: 'text-xs px-2 py-0.5',
+                tagRemove: '[&_svg]:h-3 [&_svg]:w-3'
             },
             md: {
                 input: 'h-10 px-3 pr-8 text-base',
-                option: 'px-3 py-2 text-sm min-h-[2.5rem]'
+                option: 'px-3 py-2 text-sm min-h-[2.5rem]',
+                control: 'min-h-10 gap-1.5 px-2 py-1.5 pr-8',
+                search: 'text-base',
+                tag: 'text-sm px-2 py-0.5',
+                tagRemove: '[&_svg]:h-3 [&_svg]:w-3'
             },
             lg: {
                 input: 'h-12 px-4 pr-10 text-lg',
-                option: 'px-3 py-2.5 text-base min-h-[3rem]'
+                option: 'px-3 py-2.5 text-base min-h-[3rem]',
+                control: 'min-h-12 gap-2 px-3 py-2 pr-10',
+                search: 'text-lg',
+                tag: 'text-base px-2.5 py-1',
+                tagRemove: '[&_svg]:h-3.5 [&_svg]:w-3.5'
+            },
+            xl: {
+                input: 'h-14 px-6 pr-12 text-xl',
+                option: 'px-4 py-3 text-lg min-h-[3.5rem]',
+                control: 'min-h-14 gap-2 px-4 py-2.5 pr-12',
+                search: 'text-xl',
+                tag: 'text-lg px-3 py-1',
+                tagRemove: '[&_svg]:h-4 [&_svg]:w-4'
             }
         },
         open: {

package/dist/primitives/Combobox/index.d.ts

@@ -9,53 +9,27 @@ export interface ComboboxOption<T extends SelectValue = string> {
     value: T;
     disabled?: boolean;
 }
+/** A labelled group of combobox options (parity with Select's `groups`). */
+export interface ComboboxGroup<T extends SelectValue = string> {
+    label: string;
+    options: ComboboxOption<T>[];
+}
 /**
- * @description Searchable menu (autocomplete) combining a text input with a
- * filterable option list. Implements the ARIA combobox pattern with
- * keyboard navigation, custom filtering, and two-way bindable state.
- *
- * @tag form
- * @related Select
- * @related Input
- * @related Menu
- *
- * @example
- * ```svelte
- * <Combobox
- *   options={[
- *     { label: 'Apple', value: 'apple' },
- *     { label: 'Banana', value: 'banana' },
- *     { label: 'Cherry', value: 'cherry' }
- *   ]}
- *   bind:value={selected}
- *   placeholder="Search fruit…"
- * />
- * ```
- *
- * @example Numeric IDs — the generic value type keeps `value` typed as `number`
- * ```svelte
- * <Combobox
- *   options={tenants.map((t) => ({ label: t.name, value: t.id }))}
- *   bind:value={tenantId}
- * />
- * ```
- *
- * @example
- * ```svelte
- * <Combobox
- *   options={countries}
- *   bind:value={country}
- *   filter={(option, query) => option.label.toLowerCase().startsWith(query.toLowerCase())}
- *   clearable
- *   size="lg"
- * />
- * ```
+ * Shared props for both single- and multi-select Combobox modes. The
+ * mode-specific shapes (`value`, `onValueChange`, and the multi-only tag props)
+ * live on {@link ComboboxSingleProps} / {@link ComboboxMultipleProps} and narrow
+ * against `multiple`.
  */
-export interface ComboboxProps<T extends SelectValue = string> extends ComboboxVariants, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+interface ComboboxBaseProps<T extends SelectValue = string> extends ComboboxVariants, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Array of selectable options. Each needs a unique `value`. */
-    options: ComboboxOption<T>[];
-    /** Currently selected value. Supports `bind:value` for two-way binding. */
-    value?: T | null;
+    options?: ComboboxOption<T>[];
+    /**
+     * Grouped options with section labels, at parity with Select. Takes precedence
+     * over `options` when set. Filtering runs per group; groups whose options all
+     * filter out are hidden, and keyboard navigation flows across the flattened,
+     * still-visible options exactly as it does for a flat list.
+     */
+    groups?: ComboboxGroup<T>[];
     /** Current search query text. Supports `bind:query` for external control (e.g. server-side filtering). */
     query?: string;
     /** Placeholder shown when the input is empty. @default 'Search…' */
@@ -66,22 +40,49 @@ export interface ComboboxProps<T extends SelectValue = string> extends ComboboxV
     helper?: string;
     /** Error message — replaces helper text and flags the field as invalid. */
     error?: string;
-    /** Marks the field as required. Adds the asterisk on the label. @default false */
+    /**
+     * Marks the field as required. Adds the asterisk on the label. @default false
+     *
+     * In multi-select mode this is visual only — the transient search input
+     * carries no native `required` (it is cleared after each pick), so enforce a
+     * minimum selection in your submit handler.
+     */
     required?: boolean;
-    /** Custom filter replacing the built-in case-insensitive label match. Return `true` to include an option. */
+    /** Custom filter replacing the built-in case-insensitive label match. Return `true` to include an option. Ignored when `queryFn` is set (the server filters). */
     filter?: (option: ComboboxOption<T>, query: string) => boolean;
+    /**
+     * Server-side search (analogous to the Table remote-mode API). When set, the
+     * Combobox stops filtering client-side and instead calls `queryFn` — debounced
+     * by {@link debounceMs} — on each query change, replacing the option list with
+     * the resolved result. The `AbortSignal` is aborted when a newer query
+     * supersedes an in-flight request, so a slow stale response never clobbers a
+     * fresh one. Aborted rejections are swallowed; other rejections leave the
+     * previous options in place (and warn in dev). `options`/`groups` are ignored
+     * in this mode. The selected option's label is cached so it survives result
+     * sets that no longer contain it.
+     */
+    queryFn?: (query: string, signal: AbortSignal) => Promise<ComboboxOption<T>[]>;
+    /** Debounce applied to `queryFn` in milliseconds. @default 250 */
+    debounceMs?: number;
+    /** Text shown in the listbox while an async `queryFn` request is in flight. @default 'Loading…' */
+    loadingText?: string;
     /** Show a clear button when a value is selected. Click or press Escape to reset. @default false */
     clearable?: boolean;
     /** Disable the entire combobox. @default false */
     disabled?: boolean;
-    /** Shared `name` for a hidden input for native form submission. */
+    /** Shared `name` for a hidden input for native form submission. In multi-select mode one hidden input is emitted per selected value. */
     name?: string;
     /** Text displayed when the filter produces no matches. @default 'No results found' */
     noResultsText?: string;
-    /** Fires after the selected value changes. Receives the new value or `null` on clear. */
-    onValueChange?: (value: T | null) => void;
     /** Controls the open state of the listbox. Supports `bind:open`. @default false */
     open?: boolean;
+    /**
+     * Fires when the listbox opens or closes from user interaction (focus,
+     * typing, chevron toggle, selection, Escape, outside click). Receives the
+     * new open state — use it e.g. to lazy-load options on first open. Not
+     * called when the consumer writes `bind:open` directly.
+     */
+    onOpenChange?: (open: boolean) => void;
     /** Custom option renderer. Receives the option and whether it is selected. */
     customOption?: Snippet<[ComboboxOption<T>, boolean]>;
     /**
@@ -115,8 +116,9 @@ export interface ComboboxProps<T extends SelectValue = string> extends ComboboxV
     /** Remove all default tv() classes — only user-provided classes apply. @default false */
     unstyled?: boolean;
     /** Per-slot class overrides merged with tv() styles. Slots: base | label | requiredMark |
-     *  inputWrapper | input | message | hint | listbox | option | optionActive | optionSelected |
-     *  noResults | clear | chevron */
+     *  inputWrapper | input | message | helper | listbox | option | optionActive | optionSelected |
+     *  group | groupLabel | loading | noResults | clear | chevron | control | search | tag |
+     *  tagLabel | tagRemove */
     slotClasses?: Partial<Record<ComboboxSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Combobox: {...} }}>`.
@@ -128,6 +130,119 @@ export interface ComboboxProps<T extends SelectValue = string> extends ComboboxV
     /** Deterministic HTML `id` for the component. Auto-generated when omitted. */
     id?: string;
 }
+/**
+ * Single-select arm (the default). `value` is `T | null`, and `onValueChange`
+ * receives the new value or `null` on clear. Selecting an option closes the
+ * listbox and mirrors the picked label back into the input.
+ */
+export interface ComboboxSingleProps<T extends SelectValue = string> extends ComboboxBaseProps<T> {
+    /** Single-select mode (the default). Omit or set to `false` explicitly. */
+    multiple?: false;
+    /** Currently selected value. Supports `bind:value` for two-way binding. */
+    value?: T | null;
+    /** Fires after the selected value changes. Receives the new value or `null` on clear. */
+    onValueChange?: (value: T | null) => void;
+    /** Disallowed in single mode — only relevant for multi-select. */
+    maxItems?: never;
+    /** Disallowed in single mode — only relevant for multi-select. */
+    onRemoveTag?: never;
+    /** Disallowed in single mode — only relevant for multi-select. */
+    customTag?: never;
+}
+/**
+ * Multi-select arm. `value` is an array of the selected values, rendered as
+ * removable tag chips below the search input. Selecting an option adds a tag and
+ * keeps the listbox open so several picks flow without re-opening; the search
+ * query is cleared after each pick. Backspace on an empty query removes the last
+ * tag.
+ */
+export interface ComboboxMultipleProps<T extends SelectValue = string> extends ComboboxBaseProps<T> {
+    /** Enable multi-select mode. */
+    multiple: true;
+    /** Currently selected values. Supports `bind:value`. @default [] */
+    value?: T[];
+    /** Fires after the selection changes. Receives the new array. */
+    onValueChange?: (value: T[]) => void;
+    /**
+     * Cap the number of selected values. Once reached, options that aren't already
+     * selected become non-selectable (and are skipped by keyboard navigation) until
+     * a tag is removed; already-selected options can still be toggled off.
+     */
+    maxItems?: number;
+    /**
+     * Fires when a single value is removed from the selection — via the tag's
+     * remove button, Backspace on an empty query, or toggling a selected option
+     * off. Receives the removed value. `onValueChange` fires alongside it with the
+     * resulting array; use `onRemoveTag` for per-tag side effects (analytics, exit
+     * animations). Note: the bulk clear button does NOT fire this per tag — it
+     * signals through `onValueChange([])` only.
+     */
+    onRemoveTag?: (value: T) => void;
+    /**
+     * Custom tag renderer replacing the default chip. Receives the selected option
+     * and a `remove` callback — call it to drop the tag (fires `onRemoveTag` +
+     * `onValueChange`). Use it to render a `<Badge>` or any bespoke chip.
+     *
+     * Positional args: `(option, remove)`.
+     */
+    customTag?: Snippet<[ComboboxOption<T>, () => void]>;
+}
+/**
+ * @description Searchable menu (autocomplete) combining a text input with a
+ * filterable option list. Implements the ARIA combobox pattern with keyboard
+ * navigation, custom filtering, and two-way bindable state. Single-select by
+ * default; pass `multiple` for an array-bound multi-select that renders picks as
+ * removable tag chips.
+ *
+ * @tag form
+ * @related Select
+ * @related Input
+ * @related Menu
+ *
+ * @example
+ * ```svelte
+ * <Combobox
+ *   options={[
+ *     { label: 'Apple', value: 'apple' },
+ *     { label: 'Banana', value: 'banana' },
+ *     { label: 'Cherry', value: 'cherry' }
+ *   ]}
+ *   bind:value={selected}
+ *   placeholder="Search fruit…"
+ * />
+ * ```
+ *
+ * @example Numeric IDs — the generic value type keeps `value` typed as `number`
+ * ```svelte
+ * <Combobox
+ *   options={tenants.map((t) => ({ label: t.name, value: t.id }))}
+ *   bind:value={tenantId}
+ * />
+ * ```
+ *
+ * @example Multi-select with removable tags
+ * ```svelte
+ * <Combobox
+ *   options={skills}
+ *   multiple
+ *   bind:value={selectedSkills}
+ *   maxItems={5}
+ *   placeholder="Add skills…"
+ * />
+ * ```
+ *
+ * @example Grouped options — filtering hides empty groups automatically
+ * ```svelte
+ * <Combobox
+ *   groups={[
+ *     { label: 'Fruit', options: [{ label: 'Apple', value: 'apple' }] },
+ *     { label: 'Veg', options: [{ label: 'Carrot', value: 'carrot' }] }
+ *   ]}
+ *   bind:value={food}
+ * />
+ * ```
+ */
+export type ComboboxProps<T extends SelectValue = string> = ComboboxSingleProps<T> | ComboboxMultipleProps<T>;
 /** Backwards-compatible alias for {@link ComboboxOption} (legacy name). */
 export type ComboboxOptionType<T extends SelectValue = string> = ComboboxOption<T>;
 export { default as Combobox } from './Combobox.svelte';