@classic-homes/theme-svelte 1.9.1 → 1.10.0

package/dist/__tests__/header-search.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor, within } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'vitest-axe';
+import HeaderSearch from '../lib/components/HeaderSearch.svelte';
+const groups = [
+    {
+        title: 'Pages',
+        items: [
+            { id: 'p1', title: 'Dashboard', href: '/dashboard', icon: 'home' },
+            { id: 'p2', title: 'Documents', href: '/documents' },
+        ],
+    },
+    {
+        title: 'Selections',
+        items: [
+            { id: 's1', title: 'Quartz countertop', description: 'Kitchen', category: 'Selection' },
+        ],
+    },
+];
+async function openSearch(props = {}) {
+    // A dialog left open by the previous test can leave pointer-events: none on body.
+    const user = userEvent.setup({ pointerEventsCheck: 0 });
+    const result = render(HeaderSearch, { props: { results: groups, ...props } });
+    await user.click(screen.getByRole('button', { name: 'Search' }));
+    const input = await screen.findByRole('combobox');
+    return { user, input, ...result };
+}
+describe('HeaderSearch', () => {
+    it('renders a heading for each result group', async () => {
+        await openSearch();
+        const pages = screen.getByRole('group', { name: 'Pages' });
+        expect(within(pages).getAllByRole('option')).toHaveLength(2);
+        const selections = screen.getByRole('group', { name: 'Selections' });
+        expect(within(selections).getByRole('option', { name: /Quartz countertop/ })).toBeInTheDocument();
+    });
+    it('renders flat results without headings', async () => {
+        const flat = [{ id: 'a', title: 'Alpha' }];
+        await openSearch({ results: flat });
+        expect(screen.getByRole('option', { name: /Alpha/ })).toBeInTheDocument();
+        expect(screen.queryByText('Pages')).not.toBeInTheDocument();
+    });
+    it('moves the active result across groups and points the input at it', async () => {
+        const { user, input } = await openSearch();
+        const options = screen.getAllByRole('option');
+        expect(input).toHaveAttribute('aria-activedescendant', options[0].id);
+        await user.keyboard('{ArrowDown}{ArrowDown}');
+        expect(input).toHaveAttribute('aria-activedescendant', options[2].id);
+        expect(options[2]).toHaveAttribute('aria-selected', 'true');
+        expect(options[0]).toHaveAttribute('aria-selected', 'false');
+    });
+    it('selects the active result on Enter and closes', async () => {
+        const onSelect = vi.fn();
+        const { user } = await openSearch({ onSelect });
+        await user.keyboard('{ArrowDown}{ArrowDown}{Enter}');
+        expect(onSelect).toHaveBeenCalledWith(groups[1].items[0]);
+        await waitFor(() => expect(screen.queryByRole('combobox')).not.toBeInTheDocument());
+    });
+    it('shows result icons only when asked', async () => {
+        const { unmount } = await openSearch();
+        expect(screen.getByRole('option', { name: /Dashboard/ }).querySelector('svg')).toBeNull();
+        unmount();
+        await openSearch({ showIcons: true });
+        expect(screen.getByRole('option', { name: /Dashboard/ }).querySelector('svg')).not.toBeNull();
+    });
+    it('caps the results list at the given height', async () => {
+        await openSearch({ resultsMaxHeight: '60vh' });
+        const listbox = screen.getByRole('listbox');
+        expect(listbox.parentElement).toHaveStyle({ maxHeight: '60vh' });
+    });
+    it('has no axe violations with grouped results open', async () => {
+        await openSearch();
+        const dialog = screen.getByRole('dialog');
+        expect(await axe(dialog)).toHaveNoViolations();
+    });
+});

package/dist/lib/components/HeaderSearch.svelte

@@ -10,6 +10,8 @@
    * - Keyboard shortcut support (Cmd/Ctrl+K)
    * - Full keyboard navigation in results
    * - Custom result rendering via snippets
+   * - Grouped results with headings (pass `SearchResultGroup[]`)
+   * - Combobox semantics: the active result is announced as you arrow through
    * - Loading and empty states
    *
    * @example Basic usage:
@@ -30,6 +32,7 @@
   import type { Snippet } from 'svelte';
   import type { SearchResultItem, SearchResultGroup } from '../types/layout.js';
   import Spinner from './Spinner.svelte';
+  import Icon, { type IconName } from './Icon.svelte';
 
   interface Props<T = SearchResultItem> {
     /** Whether search is enabled/visible */
@@ -60,6 +63,10 @@
     renderResult?: Snippet<[T, boolean]>;
     /** Custom empty state renderer */
     renderEmpty?: Snippet;
+    /** Show each result's `icon` (an Icon name) beside it (default: false) */
+    showIcons?: boolean;
+    /** Max height of the results list, any CSS length (default: '300px') */
+    resultsMaxHeight?: string;
     /** Additional classes for trigger button */
     class?: string;
   }
@@ -79,9 +86,15 @@
     size = 'md',
     renderResult,
     renderEmpty,
+    showIcons = false,
+    resultsMaxHeight = '300px',
     class: className,
   }: Props = $props();
 
+  const uid = $props.id();
+  const listboxId = `${uid}-results`;
+  const optionId = (index: number) => `${uid}-option-${index}`;
+
   // State
   let open = $state(false);
   let query = $state('');
@@ -89,14 +102,36 @@
   let inputRef: HTMLInputElement | undefined = $state();
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
-  // Flatten results for keyboard navigation
-  const flatResults = $derived.by(() => {
+  function isGrouped(
+    value: SearchResultItem[] | SearchResultGroup[]
+  ): value is SearchResultGroup[] {
+    return value.length > 0 && 'items' in value[0];
+  }
+
+  // Sections to render; ungrouped results are one untitled section. `offset`
+  // is each section's first index in the flat keyboard order.
+  const sections = $derived.by(() => {
     if (!results || results.length === 0) return [];
-    // Check if grouped results
-    if (results.length > 0 && 'items' in results[0]) {
-      return (results as SearchResultGroup[]).flatMap((g) => g.items);
-    }
-    return results as SearchResultItem[];
+    const groups: { title?: string; items: SearchResultItem[] }[] = isGrouped(results)
+      ? results
+      : [{ items: results as SearchResultItem[] }];
+    let offset = 0;
+    return groups
+      .filter((group) => group.items.length > 0)
+      .map((group) => {
+        const section = { title: group.title, items: group.items, offset };
+        offset += group.items.length;
+        return section;
+      });
+  });
+
+  // Flatten results for keyboard navigation
+  const flatResults = $derived(sections.flatMap((section) => section.items));
+
+  // Keep the active result in view while arrowing through a long list.
+  $effect(() => {
+    if (!open || flatResults.length === 0) return;
+    document.getElementById(optionId(selectedIndex))?.scrollIntoView?.({ block: 'nearest' });
   });
 
   // Keyboard shortcut handler
@@ -237,6 +272,7 @@
         class="fixed left-[50%] top-[20%] z-50 w-full max-w-lg translate-x-[-50%] overflow-hidden rounded-lg border border-black bg-background shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:top-[15%]"
         aria-describedby={undefined}
       >
+        <DialogPrimitive.Title class="sr-only">Search</DialogPrimitive.Title>
         <!-- Search Input -->
         <div class="flex items-center border-b border-black bg-muted/30 px-3">
           <svg
@@ -255,6 +291,12 @@
           <input
             bind:this={inputRef}
             type="search"
+            role="combobox"
+            aria-label={placeholder}
+            aria-expanded={flatResults.length > 0}
+            aria-controls={listboxId}
+            aria-autocomplete="list"
+            aria-activedescendant={flatResults.length > 0 ? optionId(selectedIndex) : undefined}
             {placeholder}
             value={query}
             oninput={(e) => handleInput(e.currentTarget.value)}
@@ -270,7 +312,7 @@
         </div>
 
         <!-- Results Area -->
-        <div class="max-h-[300px] overflow-y-auto p-2" role="listbox">
+        <div class="overflow-y-auto p-2" style:max-height={resultsMaxHeight}>
           {#if loading && flatResults.length === 0}
             <div class="flex items-center justify-center py-6">
               <Spinner size="sm" />
@@ -286,40 +328,70 @@
             {/if}
           {:else if flatResults.length === 0}
             <div class="py-6 text-center text-sm text-muted-foreground">Type to search...</div>
-          {:else}
-            {#each flatResults as item, index (item.id)}
-              <button
-                type="button"
-                onclick={() => handleSelect(item)}
-                class={cn(
-                  'flex w-full cursor-pointer items-start gap-3 rounded-md px-3 py-2 text-left text-sm',
-                  index === selectedIndex
-                    ? 'bg-accent text-accent-foreground'
-                    : 'hover:bg-accent-hover'
-                )}
-                role="option"
-                aria-selected={index === selectedIndex}
+          {/if}
+
+          <div id={listboxId} role="listbox" aria-label="Search results">
+            {#each sections as section, sectionIndex (section.offset)}
+              <div
+                role="group"
+                aria-labelledby={section.title ? `${uid}-group-${sectionIndex}` : undefined}
+                class={cn(sectionIndex > 0 && section.title && 'mt-2')}
               >
-                {#if renderResult}
-                  {@render renderResult(item, index === selectedIndex)}
-                {:else}
-                  <div class="min-w-0 flex-1">
-                    <div class="truncate font-medium">{item.title}</div>
-                    {#if item.description}
-                      <div class="truncate text-xs text-muted-foreground">
-                        {item.description}
-                      </div>
-                    {/if}
+                {#if section.title}
+                  <div
+                    id="{uid}-group-{sectionIndex}"
+                    role="presentation"
+                    class="px-3 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground"
+                  >
+                    {section.title}
                   </div>
-                  {#if item.category}
-                    <span class="shrink-0 text-xs text-muted-foreground">
-                      {item.category}
-                    </span>
-                  {/if}
                 {/if}
-              </button>
+                {#each section.items as item, itemIndex (item.id)}
+                  {@const index = section.offset + itemIndex}
+                  <button
+                    type="button"
+                    id={optionId(index)}
+                    tabindex="-1"
+                    onclick={() => handleSelect(item)}
+                    onmousemove={() => (selectedIndex = index)}
+                    class={cn(
+                      'flex w-full cursor-pointer items-start gap-3 rounded-md px-3 py-2 text-left text-sm',
+                      index === selectedIndex
+                        ? 'bg-accent text-accent-foreground'
+                        : 'hover:bg-accent-hover'
+                    )}
+                    role="option"
+                    aria-selected={index === selectedIndex}
+                  >
+                    {#if renderResult}
+                      {@render renderResult(item, index === selectedIndex)}
+                    {:else}
+                      {#if showIcons && item.icon}
+                        <Icon
+                          name={item.icon as IconName}
+                          size={16}
+                          class="mt-0.5 shrink-0 text-muted-foreground"
+                        />
+                      {/if}
+                      <div class="min-w-0 flex-1">
+                        <div class="truncate font-medium">{item.title}</div>
+                        {#if item.description}
+                          <div class="truncate text-xs text-muted-foreground">
+                            {item.description}
+                          </div>
+                        {/if}
+                      </div>
+                      {#if item.category}
+                        <span class="shrink-0 text-xs text-muted-foreground">
+                          {item.category}
+                        </span>
+                      {/if}
+                    {/if}
+                  </button>
+                {/each}
+              </div>
             {/each}
-          {/if}
+          </div>
         </div>
 
         <!-- Footer with keyboard hints -->

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

@@ -29,6 +29,10 @@ interface Props<T = SearchResultItem> {
     renderResult?: Snippet<[T, boolean]>;
     /** Custom empty state renderer */
     renderEmpty?: Snippet;
+    /** Show each result's `icon` (an Icon name) beside it (default: false) */
+    showIcons?: boolean;
+    /** Max height of the results list, any CSS length (default: '300px') */
+    resultsMaxHeight?: string;
     /** Additional classes for trigger button */
     class?: string;
 }

package/dist/lib/types/layout.d.ts

@@ -63,6 +63,10 @@ export interface HeaderSearchConfig<T = SearchResultItem> {
     renderResult?: Snippet<[T, boolean]>;
     /** Custom empty state renderer */
     renderEmpty?: Snippet;
+    /** Show each result's `icon` (an Icon name) beside it (default: false) */
+    showIcons?: boolean;
+    /** Max height of the results list, any CSS length (default: '300px') */
+    resultsMaxHeight?: string;
 }
 /**
  * Navigation item for sidebar and header navigation

package/package.json

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