@classic-homes/theme-svelte 1.27.1 → 1.29.0

package/dist/lib/components/Combobox.svelte

@@ -1,6 +1,8 @@
 <script lang="ts">
   import { Combobox as ComboboxPrimitive } from 'bits-ui';
+  import { DEV } from 'esm-env';
   import { cn } from '../utils.js';
+  import type { SelectGroup } from '../types/components.js';
   import { computeDescribedBy } from '../utils/form.js';
   import Spinner from './Spinner.svelte';
   import Label from './Label.svelte';
@@ -17,8 +19,8 @@
     value?: string;
     /** Callback when value changes */
     onValueChange?: (value: string) => void;
-    /** Array of selectable options */
-    options: ComboboxOption[];
+    /** Array of options or grouped options */
+    options: (ComboboxOption | SelectGroup)[];
     /** Placeholder text for the input */
     placeholder?: string;
     /** Message to display when no results found */
@@ -45,6 +47,10 @@
     debounceMs?: number;
     /** Additional class for the trigger */
     class?: string;
+    /** Accessible name for the input, when there is no visible label */
+    'aria-label'?: string;
+    /** ID of an element that labels the input */
+    'aria-labelledby'?: string;
   }
 
   let {
@@ -64,6 +70,8 @@
     onSearch,
     debounceMs = 300,
     class: className,
+    'aria-label': ariaLabelProp,
+    'aria-labelledby': ariaLabelledby,
   }: Props = $props();
 
   // Generate unique IDs for accessibility ($props.id() is SSR-stable)
@@ -79,16 +87,53 @@
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let open = $state(false);
 
-  // Find selected option label
-  const selectedLabel = $derived(options.find((opt) => opt.value === value)?.label);
+  // The placeholder is only a last-resort name: an aria-label would override
+  // an external <label for={id}> or aria-labelledby.
+  const fallbackAriaLabel = $derived(
+    ariaLabelProp ?? (!label && !id && !ariaLabelledby ? placeholder : undefined)
+  );
 
-  // Always filter options locally based on search query
-  const filteredOptions = $derived.by(() => {
+  if (DEV) {
+    $effect(() => {
+      if (!label && !id && !ariaLabelProp && !ariaLabelledby) {
+        console.warn(
+          '[Combobox] Missing accessible label. Provide a label prop or an id with a matching <label for="...">.'
+        );
+      }
+    });
+  }
+
+  function isGroup(item: ComboboxOption | SelectGroup): item is SelectGroup {
+    return 'options' in item;
+  }
+
+  // Flat list for the label lookup and for bits-ui's items
+  const flatItems = $derived(options.flatMap((item) => (isGroup(item) ? item.options : [item])));
+
+  const selectedLabel = $derived(flatItems.find((opt) => opt.value === value)?.label);
+
+  // Always filter options locally based on search query; groups keep only
+  // their matching options and drop out when none match.
+  const filteredOptions = $derived.by((): (ComboboxOption | SelectGroup)[] => {
     if (!searchQuery) return options;
     const query = searchQuery.toLowerCase();
-    return options.filter((opt) => opt.label.toLowerCase().includes(query));
+    const matches = (opt: ComboboxOption) => opt.label.toLowerCase().includes(query);
+    return options.flatMap((item): (ComboboxOption | SelectGroup)[] => {
+      if (!isGroup(item)) return matches(item) ? [item] : [];
+      const groupOptions = item.options.filter(matches);
+      return groupOptions.length > 0 ? [{ ...item, options: groupOptions }] : [];
+    });
   });
 
+  const filteredCount = $derived(
+    filteredOptions.reduce((n: number, item) => n + (isGroup(item) ? item.options.length : 1), 0)
+  );
+
+  // Closed, the input shows the selected label; open, it holds what the user
+  // types, with the selected label as the placeholder so the full list shows.
+  const inputValue = $derived(open ? searchQuery : (selectedLabel ?? ''));
+  const inputPlaceholder = $derived(open ? selectedLabel || placeholder : placeholder);
+
   function handleSearchInput(e: Event) {
     const target = e.target as HTMLInputElement;
     searchQuery = target.value;
@@ -127,12 +172,41 @@
   const resultsAnnouncement = $derived.by(() => {
     if (loading) return 'Loading options...';
     if (!open) return '';
-    if (filteredOptions.length === 0) return emptyMessage;
-    const count = filteredOptions.length;
+    if (filteredCount === 0) return emptyMessage;
+    const count = filteredCount;
     return `${count} ${count === 1 ? 'option' : 'options'} available`;
   });
 </script>
 
+{#snippet comboboxItem(option: ComboboxOption)}
+  <ComboboxPrimitive.Item
+    value={option.value}
+    label={option.label}
+    disabled={option.disabled}
+    class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
+  >
+    {#if option.value === value}
+      <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="h-4 w-4"
+        >
+          <polyline points="20 6 9 17 4 12" />
+        </svg>
+      </span>
+    {/if}
+    {option.label}
+  </ComboboxPrimitive.Item>
+{/snippet}
+
 <!-- One structure whether or not there is a label, hint or error, so the
      focused control is never remounted when an error appears. -->
 <div class="space-y-2">
@@ -155,11 +229,12 @@
     onOpenChange={handleOpenChange}
     onValueChange={handleValueChange}
     {value}
+    items={flatItems}
   >
     <div class="relative">
       <ComboboxPrimitive.Input
         id={componentId}
-        placeholder={selectedLabel || placeholder}
+        placeholder={inputPlaceholder}
         oninput={handleSearchInput}
         onfocus={() => (open = true)}
         onclick={() => (open = true)}
@@ -170,9 +245,15 @@
         )}
         role="combobox"
         aria-expanded={open}
+        aria-label={fallbackAriaLabel}
+        aria-labelledby={ariaLabelledby}
         aria-invalid={error ? 'true' : undefined}
         aria-describedby={describedBy}
-      />
+      >
+        {#snippet child({ props })}
+          <input {...props} value={inputValue} />
+        {/snippet}
+      </ComboboxPrimitive.Input>
     </div>
 
     <!-- Portal to <body>: escapes transformed/overflow-hidden ancestors
@@ -190,38 +271,24 @@
               <Spinner size="sm" />
               <span class="ml-2 text-sm text-muted-foreground">Loading...</span>
             </div>
-          {:else if filteredOptions.length === 0}
+          {:else if filteredCount === 0}
             <div class="py-6 text-center text-sm text-muted-foreground">
               {emptyMessage}
             </div>
           {:else}
-            {#each filteredOptions as option}
-              <ComboboxPrimitive.Item
-                value={option.value}
-                label={option.label}
-                disabled={option.disabled}
-                class="relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[disabled]:cursor-default"
-              >
-                {#if option.value === value}
-                  <span class="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
-                    <svg
-                      xmlns="http://www.w3.org/2000/svg"
-                      width="16"
-                      height="16"
-                      viewBox="0 0 24 24"
-                      fill="none"
-                      stroke="currentColor"
-                      stroke-width="2"
-                      stroke-linecap="round"
-                      stroke-linejoin="round"
-                      class="h-4 w-4"
-                    >
-                      <polyline points="20 6 9 17 4 12" />
-                    </svg>
-                  </span>
-                {/if}
-                {option.label}
-              </ComboboxPrimitive.Item>
+            {#each filteredOptions as item}
+              {#if isGroup(item)}
+                <ComboboxPrimitive.Group>
+                  <ComboboxPrimitive.GroupHeading class="py-1.5 pl-8 pr-2 text-sm font-semibold">
+                    {item.label}
+                  </ComboboxPrimitive.GroupHeading>
+                  {#each item.options as option}
+                    {@render comboboxItem(option)}
+                  {/each}
+                </ComboboxPrimitive.Group>
+              {:else}
+                {@render comboboxItem(item)}
+              {/if}
             {/each}
           {/if}
         </div>

package/dist/lib/components/Combobox.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { SelectGroup } from '../types/components.js';
 export interface ComboboxOption {
     value: string;
     label: string;
@@ -8,8 +9,8 @@ interface Props {
     value?: string;
     /** Callback when value changes */
     onValueChange?: (value: string) => void;
-    /** Array of selectable options */
-    options: ComboboxOption[];
+    /** Array of options or grouped options */
+    options: (ComboboxOption | SelectGroup)[];
     /** Placeholder text for the input */
     placeholder?: string;
     /** Message to display when no results found */
@@ -36,6 +37,10 @@ interface Props {
     debounceMs?: number;
     /** Additional class for the trigger */
     class?: string;
+    /** Accessible name for the input, when there is no visible label */
+    'aria-label'?: string;
+    /** ID of an element that labels the input */
+    'aria-labelledby'?: string;
 }
 declare const Combobox: import("svelte").Component<Props, {}, "value">;
 type Combobox = ReturnType<typeof Combobox>;

package/dist/lib/components/DropdownMenu.svelte

@@ -2,6 +2,7 @@
   import { DropdownMenu as DropdownMenuPrimitive } from 'bits-ui';
   import { cn } from '../utils.js';
   import type { Snippet } from 'svelte';
+  import type { Attachment } from 'svelte/attachments';
   import Icon, { type IconName } from './Icon.svelte';
   import { buttonVariants, type ButtonVariants } from './button-variants.js';
 
@@ -60,6 +61,19 @@
      * so a text trigger (e.g. header navigation) reads as a menu rather than a link.
      */
     showChevron?: boolean;
+    /**
+     * Disable the trigger `<button>`: sets native `disabled` and stops the menu from opening
+     * (pointer and keyboard). Use this instead of nesting a disabled `<Button>` in `trigger`.
+     */
+    triggerDisabled?: boolean;
+    /**
+     * Keep the trigger's pointer, mouse, click and opening-key (Enter, Space, ArrowDown)
+     * events from bubbling past the trigger, so a menu inside a clickable row or card
+     * opens without also activating the row. The menu still opens as usual.
+     */
+    triggerStopPropagation?: boolean;
+    /** Called on a click of the trigger, before the event bubbles to its ancestors */
+    onTriggerClick?: (event: MouseEvent) => void;
   }
 
   let {
@@ -75,8 +89,56 @@
     triggerSize = 'sm',
     triggerLabel,
     showChevron = false,
+    triggerDisabled = false,
+    triggerStopPropagation = false,
+    onTriggerClick,
   }: Props = $props();
 
+  type TriggerHandler = ((event: Event) => void) | undefined;
+
+  /** Keys the bits-ui trigger acts on (toggle/open), so they are the row-activating ones too. */
+  const OPENING_KEYS = new Set(['Enter', ' ', 'ArrowDown']);
+
+  /** Events that would reach a clickable ancestor (row click, row link, row keyboard activate). */
+  const ISOLATED_EVENTS = [
+    'pointerdown',
+    'pointerup',
+    'mousedown',
+    'mouseup',
+    'click',
+    'auxclick',
+    'keydown',
+  ] as const;
+
+  /**
+   * With `triggerStopPropagation`, listen natively on the trigger itself: run the bits-ui
+   * handler (and `onTriggerClick`) at the target, then stop the event there. Svelte's
+   * delegated handlers run at the root, so a stop inside one would also keep bits-ui's own
+   * (delegated) handlers from running and could not stop native listeners on ancestors.
+   */
+  function isolateTrigger(props: Record<string, unknown>): Attachment<HTMLButtonElement> {
+    return (node) => {
+      const listeners = ISOLATED_EVENTS.map((type) => {
+        const listener = (event: Event) => {
+          (props[`on${type}`] as TriggerHandler)?.(event);
+          if (type === 'click') onTriggerClick?.(event as MouseEvent);
+          if (type === 'keydown' && !OPENING_KEYS.has((event as KeyboardEvent).key)) return;
+          event.stopPropagation();
+        };
+        node.addEventListener(type, listener);
+        return () => node.removeEventListener(type, listener);
+      });
+      return () => listeners.forEach((remove) => remove());
+    };
+  }
+
+  /** Trigger props without the event handlers that `isolateTrigger` calls itself. */
+  function withoutHandlers(props: Record<string, unknown>): Record<string, unknown> {
+    const rest = { ...props };
+    for (const type of ISOLATED_EVENTS) delete rest[`on${type}`];
+    return rest;
+  }
+
   function handleOpenChange(newOpen: boolean) {
     open = newOpen;
     onOpenChange?.(newOpen);
@@ -87,6 +149,21 @@
   }
 </script>
 
+{#snippet triggerContent()}
+  {@render trigger()}
+  {#if showChevron}
+    <Icon
+      name="chevron-down"
+      size={16}
+      class={cn(
+        'ml-1 shrink-0 opacity-60 transition-transform duration-200 motion-reduce:transition-none',
+        open && 'rotate-180'
+      )}
+      aria-hidden="true"
+    />
+  {/if}
+{/snippet}
+
 {#snippet itemContent(item: DropdownMenuItem)}
   {#if item.icon}
     <Icon name={item.icon} size={16} class="mr-2 shrink-0" aria-hidden="true" />
@@ -143,29 +220,32 @@
 {/snippet}
 
 <DropdownMenuPrimitive.Root bind:open onOpenChange={handleOpenChange}>
-  <DropdownMenuPrimitive.Trigger>
+  <DropdownMenuPrimitive.Trigger disabled={triggerDisabled}>
     {#snippet child({ props })}
-      <button
-        type="button"
-        {...props}
-        class={triggerVariant
-          ? cn(buttonVariants({ variant: triggerVariant, size: triggerSize }), triggerClass)
-          : triggerClass}
-        aria-label={triggerLabel}
-      >
-        {@render trigger()}
-        {#if showChevron}
-          <Icon
-            name="chevron-down"
-            size={16}
-            class={cn(
-              'ml-1 shrink-0 opacity-60 transition-transform duration-200 motion-reduce:transition-none',
-              open && 'rotate-180'
-            )}
-            aria-hidden="true"
-          />
-        {/if}
-      </button>
+      {@const buttonClass = triggerVariant
+        ? cn(buttonVariants({ variant: triggerVariant, size: triggerSize }), triggerClass)
+        : triggerClass}
+      {#if triggerStopPropagation}
+        <button
+          type="button"
+          {...withoutHandlers(props)}
+          class={buttonClass}
+          aria-label={triggerLabel}
+          {@attach isolateTrigger(props)}
+        >
+          {@render triggerContent()}
+        </button>
+      {:else}
+        <button
+          type="button"
+          {...props}
+          class={buttonClass}
+          aria-label={triggerLabel}
+          onclick={onTriggerClick}
+        >
+          {@render triggerContent()}
+        </button>
+      {/if}
     {/snippet}
   </DropdownMenuPrimitive.Trigger>
 

package/dist/lib/components/DropdownMenu.svelte.d.ts

@@ -54,6 +54,19 @@ interface Props {
      * so a text trigger (e.g. header navigation) reads as a menu rather than a link.
      */
     showChevron?: boolean;
+    /**
+     * Disable the trigger `<button>`: sets native `disabled` and stops the menu from opening
+     * (pointer and keyboard). Use this instead of nesting a disabled `<Button>` in `trigger`.
+     */
+    triggerDisabled?: boolean;
+    /**
+     * Keep the trigger's pointer, mouse, click and opening-key (Enter, Space, ArrowDown)
+     * events from bubbling past the trigger, so a menu inside a clickable row or card
+     * opens without also activating the row. The menu still opens as usual.
+     */
+    triggerStopPropagation?: boolean;
+    /** Called on a click of the trigger, before the event bubbles to its ancestors */
+    onTriggerClick?: (event: MouseEvent) => void;
 }
 declare const DropdownMenu: import("svelte").Component<Props, {}, "open">;
 type DropdownMenu = ReturnType<typeof DropdownMenu>;

package/dist/lib/components/Select.svelte

@@ -4,6 +4,7 @@
   import { validateNonEmptyArray } from '../validation.js';
   import { DEV } from 'esm-env';
   import Label from './Label.svelte';
+  import Combobox from './Combobox.svelte';
 
   export interface SelectOption {
     value: string;
@@ -45,6 +46,11 @@
     'aria-label'?: string;
     /** ID of an element that labels the trigger */
     'aria-labelledby'?: string;
+    /**
+     * Type to narrow the options: `true` always renders a Combobox; a number
+     * renders one once there are at least that many options.
+     */
+    searchable?: boolean | number;
   }
 
   let {
@@ -62,6 +68,7 @@
     hint,
     'aria-label': ariaLabelProp,
     'aria-labelledby': ariaLabelledby,
+    searchable = false,
   }: Props = $props();
 
   // Generate unique IDs for accessibility using sequential counter
@@ -132,6 +139,10 @@
     return items;
   });
 
+  const useCombobox = $derived(
+    typeof searchable === 'number' ? flatItems.length >= searchable : searchable
+  );
+
   function handleValueChange(newValue: string) {
     value = newValue;
     onValueChange?.(newValue);
@@ -267,30 +278,49 @@
   </SelectPrimitive.Root>
 {/snippet}
 
-<!-- One structure whether or not there is a label, hint or error, so the
+{#if useCombobox}
+  <Combobox
+    bind:value
+    {onValueChange}
+    {options}
+    {placeholder}
+    {disabled}
+    {name}
+    {required}
+    {label}
+    {id}
+    {error}
+    {hint}
+    aria-label={ariaLabelProp}
+    aria-labelledby={ariaLabelledby}
+    class={className}
+  />
+{:else}
+  <!-- One structure whether or not there is a label, hint or error, so the
      focused control is never remounted when an error appears. -->
-<div class="space-y-2">
-  {#if label}
-    <Label for={componentId} {disabled}>
-      {label}
-      {#if required}
-        <span class="text-destructive ml-0.5" aria-hidden="true">*</span>
-        <span class="sr-only">(required)</span>
-      {/if}
-    </Label>
-  {/if}
+  <div class="space-y-2">
+    {#if label}
+      <Label for={componentId} {disabled}>
+        {label}
+        {#if required}
+          <span class="text-destructive ml-0.5" aria-hidden="true">*</span>
+          <span class="sr-only">(required)</span>
+        {/if}
+      </Label>
+    {/if}
 
-  {@render selectRoot(fallbackAriaLabel)}
+    {@render selectRoot(fallbackAriaLabel)}
 
-  {#if hint && !error}
-    <p id={hintId} class="text-sm text-muted-foreground">
-      {hint}
-    </p>
-  {/if}
+    {#if hint && !error}
+      <p id={hintId} class="text-sm text-muted-foreground">
+        {hint}
+      </p>
+    {/if}
 
-  {#if error}
-    <p id={errorId} class="text-sm text-destructive" role="alert" aria-live="polite">
-      {error}
-    </p>
-  {/if}
-</div>
+    {#if error}
+      <p id={errorId} class="text-sm text-destructive" role="alert" aria-live="polite">
+        {error}
+      </p>
+    {/if}
+  </div>
+{/if}

package/dist/lib/components/Select.svelte.d.ts

@@ -36,6 +36,11 @@ interface Props {
     'aria-label'?: string;
     /** ID of an element that labels the trigger */
     'aria-labelledby'?: string;
+    /**
+     * Type to narrow the options: `true` always renders a Combobox; a number
+     * renders one once there are at least that many options.
+     */
+    searchable?: boolean | number;
 }
 declare const Select: import("svelte").Component<Props, {}, "value">;
 type Select = ReturnType<typeof Select>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/theme-svelte",
-  "version": "1.27.1",
+  "version": "1.29.0",
   "description": "Svelte components for the Classic theme system",
   "type": "module",
   "svelte": "./dist/lib/index.js",