@spectral_labs/ui 1.5.3 → 1.6.0

package/dist/components/__tests__/overlay-scrim-source.test.js

@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+/**
+ * spectral-ui#206 — the six covering surfaces paint the OPAQUE scrim token and
+ * own the veil's alpha through `opacity` (0.32, via the component's
+ * `--sp-comp-*-overlay-opacity` token where one exists). Exactly one owner:
+ * the colour is never translucent, the opacity is never missing or wrong.
+ *
+ * The two values are matched against an ALLOW-LIST, not a deny-list: any other
+ * spelling fails, so `#0000004d`, `oklch(0 0 0 / .3)`, `rgb(0 0 0 / 30%)` or a
+ * `color-mix()` cannot slip through a list of forbidden prefixes. Declarations
+ * are parsed (property, value) instead of substring-matched, because
+ * `--sp-comp-dialog-overlay-opacity: 0.32;` literally ends with
+ * `opacity: 0.32;` and would otherwise satisfy a naive regex while the real
+ * `opacity` declaration says something else.
+ *
+ * EVERY rule in the file that targets the class is inspected, not just the
+ * first one: in a Svelte component a later rule (a duplicate, a `@media`
+ * block) lives in the same scoped `<style>` and wins the cascade.
+ *
+ * Three of these surfaces (SideSheet, NavDrawer, BottomSheet) have no cell in
+ * `tests/e2e/scrim-alpha.spec.ts`, so this file is their only control — it has
+ * to be exact. The list is literal on purpose: a seventh surface that forgets
+ * the idiom has to be added here.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const SURFACES = [
+    { file: 'dialog/components/dialog-overlay.svelte', selector: '.sp-dialog-overlay' },
+    {
+        file: 'alert-dialog/components/alert-dialog-overlay.svelte',
+        selector: '.sp-alert-dialog-overlay',
+    },
+    { file: 'sheet/components/sheet-overlay.svelte', selector: '.sp-sheet-overlay' },
+    { file: 'side-sheet/side-sheet.svelte', selector: '.sp-side-sheet-overlay' },
+    { file: 'nav-drawer/components/nav-drawer-root.svelte', selector: '.sp-nav-drawer-overlay' },
+    {
+        file: 'bottom-sheet/components/bottom-sheet-root.svelte',
+        selector: '.sp-bottom-sheet-overlay',
+    },
+];
+/** `background-color` values that keep the colour opaque and token-driven. */
+const ALLOWED_BACKGROUND = [
+    /^var\(--sp-sys-color-scrim\)$/,
+    /^var\(--sp-comp-[a-z-]+-overlay-color,\s*var\(--sp-sys-color-scrim\)\)$/,
+];
+/** `opacity` values that make the component the single owner of the alpha. */
+const ALLOWED_OPACITY = [/^0\.32$/, /^var\(--sp-comp-[a-z-]+-overlay-opacity,\s*0\.32\)$/];
+/** The component's scoped stylesheet, so template braces are never parsed. */
+function styleBlock(componentSource, file) {
+    const match = componentSource.match(/<style>(.*)<\/style>/s);
+    if (!match)
+        throw new Error(`${file}: no <style> block`);
+    return match[1];
+}
+/** Every rule in `source` whose selector list mentions `selector`, in order. */
+function rulesTargeting(source, selector) {
+    const rules = [];
+    for (let open = 0; open < source.length; open++) {
+        if (source[open] !== '{')
+            continue;
+        let start = open - 1;
+        while (start >= 0 && !'{};'.includes(source[start]))
+            start--;
+        const selectorList = source.slice(start + 1, open).trim();
+        if (!selectorList.includes(selector))
+            continue;
+        let depth = 1;
+        let close = open + 1;
+        for (; close < source.length && depth > 0; close++) {
+            if (source[close] === '{')
+                depth++;
+            else if (source[close] === '}')
+                depth--;
+        }
+        const declarations = source
+            .slice(open + 1, close - 1)
+            .split(';')
+            .map((chunk) => chunk.trim())
+            .filter((chunk) => chunk.includes(':') && !chunk.includes('{'))
+            .map((chunk) => ({
+            property: chunk.slice(0, chunk.indexOf(':')).trim(),
+            value: chunk.slice(chunk.indexOf(':') + 1).trim(),
+        }));
+        rules.push({ selectorList, declarations });
+    }
+    return rules;
+}
+const valueOf = (rule, property) => rule.declarations.findLast((d) => d.property === property)?.value;
+describe('overlay surfaces own the scrim alpha through opacity (#206)', () => {
+    for (const { file, selector } of SURFACES) {
+        const source = readFileSync(resolve(here, '..', file), 'utf8');
+        const rules = rulesTargeting(styleBlock(source, file), selector);
+        // The veil rule is the one whose selector is the bare class; anything else
+        // (`[data-state='closed']`, a media-query variant) is a variant rule.
+        const veilRules = rules.filter((r) => r.selectorList === selector);
+        const variantRules = rules.filter((r) => r.selectorList !== selector);
+        it(`${selector} is painted by exactly one veil rule`, () => {
+            expect(veilRules).toHaveLength(1);
+        });
+        it(`${selector} paints the opaque scrim token`, () => {
+            const background = valueOf(veilRules[0], 'background-color');
+            expect(background, `${file}: background-color`).toBeDefined();
+            expect(ALLOWED_BACKGROUND.some((allowed) => allowed.test(background)), `${file}: background-color "${background}" is not an opaque token reference`).toBe(true);
+        });
+        it(`${selector} carries the veil's alpha as opacity 0.32`, () => {
+            const opacity = valueOf(veilRules[0], 'opacity');
+            expect(opacity, `${file}: opacity`).toBeDefined();
+            expect(ALLOWED_OPACITY.some((allowed) => allowed.test(opacity)), `${file}: opacity "${opacity}" is not the 0.32 the component owns`).toBe(true);
+        });
+        it(`${selector} declares no local overlay token that would change the veil`, () => {
+            for (const rule of rules) {
+                for (const { property, value } of rule.declarations) {
+                    if (/^--sp-comp-[a-z-]+-overlay-opacity$/.test(property)) {
+                        expect(value, `${file}: ${property}`).toBe('0.32');
+                    }
+                    if (/^--sp-comp-[a-z-]+-overlay-color$/.test(property)) {
+                        expect(value, `${file}: ${property}`).toBe('var(--sp-sys-color-scrim)');
+                    }
+                }
+            }
+        });
+        it(`${selector} variants only fade the veil out, never repaint it`, () => {
+            for (const rule of variantRules) {
+                expect(valueOf(rule, 'background-color'), `${file}: "${rule.selectorList}" repaints the veil`).toBeUndefined();
+                const opacity = valueOf(rule, 'opacity');
+                if (opacity !== undefined) {
+                    expect(opacity, `${file}: "${rule.selectorList}" opacity`).toBe('0');
+                }
+            }
+        });
+    }
+});

package/dist/components/command/__tests__/CommandTest.svelte

@@ -16,6 +16,10 @@
     closeOnOutsideClick = true,
     onOpenChange = undefined,
     onClose = undefined,
+    itemAttrs = undefined,
+    disabledItemAttrs = undefined,
+    onItemSelect = undefined,
+    onDisabledItemSelect = undefined,
   }: {
     value?: string
     shouldFilter?: boolean
@@ -25,6 +29,14 @@
     closeOnOutsideClick?: boolean
     onOpenChange?: (open: boolean) => void
     onClose?: () => void
+    /** Arbitrary HTML attributes / native handlers spread onto the `copy` item. */
+    itemAttrs?: Record<string, unknown>
+    /** Same, spread onto the `settings` item (the disabled one). */
+    disabledItemAttrs?: Record<string, unknown>
+    /** Spectral `onSelect` of the `copy` item. */
+    onItemSelect?: (value: string) => void
+    /** Spectral `onSelect` of the `settings` item. */
+    onDisabledItemSelect?: (value: string) => void
   } = $props()
 </script>
 
@@ -42,14 +54,24 @@
   <CommandList>
     <CommandEmpty>No results found.</CommandEmpty>
     <CommandGroup heading="Actions">
-      <CommandItem value="copy" keywords={['duplicate']}>Copy</CommandItem>
+      <CommandItem
+        value="copy"
+        keywords={['duplicate']}
+        onSelect={onItemSelect}
+        {...itemAttrs ?? {}}>Copy</CommandItem
+      >
       <CommandItem value="paste">Paste</CommandItem>
       <CommandItem value="cut">Cut</CommandItem>
     </CommandGroup>
     <CommandSeparator />
     <CommandGroup heading="Navigation">
       <CommandItem value="home">Home</CommandItem>
-      <CommandItem value="settings" disabled>Settings</CommandItem>
+      <CommandItem
+        value="settings"
+        disabled
+        onSelect={onDisabledItemSelect}
+        {...disabledItemAttrs ?? {}}>Settings</CommandItem
+      >
     </CommandGroup>
   </CommandList>
 </CommandRoot>

package/dist/components/command/__tests__/command-item-passthrough.test.svelte.js

@@ -0,0 +1,284 @@
+import { flushSync, mount, unmount } from 'svelte';
+import { afterEach, describe, expect, it } from 'vitest';
+import CommandTest from './CommandTest.svelte';
+// jsdom does not define PointerEvent — polyfill it for tests
+if (typeof globalThis.PointerEvent === 'undefined') {
+    // @ts-expect-error — minimal polyfill for testing
+    globalThis.PointerEvent = class PointerEvent extends MouseEvent {
+        constructor(type, init) {
+            super(type, init);
+        }
+    };
+}
+/**
+ * spectral-ui#205 — `Command.Item` forwards native HTML attributes and handlers
+ * to its real `role="option"` node.
+ *
+ * Contract pinned here:
+ *  - consumer attributes (`title`, `aria-*`, `data-testid`, `style`, …) reach
+ *    the option, and a value reassigned by the parent AFTER mount is reflected;
+ *  - the option's IDENTITY stays under the component's control: `role`, `id`,
+ *    `tabindex`, `aria-selected`, `aria-disabled` and the internal `data-*`
+ *    (`data-command-item`, `data-value`, `data-selected`, `data-disabled`)
+ *    cannot be overridden — the spread comes FIRST, the identity comes after;
+ *  - native handlers COMPOSE with the built-in behaviour: the consumer's runs
+ *    first, `preventDefault()` cancels the Spectral selection, `onSelect` only
+ *    fires after a real selection;
+ *  - activation of a disabled row is inert: consumer `onclick` / `onkeydown` do
+ *    not run either, while `onpointermove` stays observable (a dimmed row can
+ *    still be hovered) without ever selecting the row.
+ *
+ * Tests titled `guard —` were already green on the pre-#205 tree (nothing was
+ * forwarded, so nothing could be overridden, leaked or mis-composed); their
+ * discriminating power comes from the mutant campaign below, each mutant
+ * applied alone on the final tree and killed by the named test(s):
+ *  - spread placed LAST → identity guard, Enter-from-input guard
+ *  - rest not spread → forwarding, post-mount reactivity, identity
+ *  - `keywords` left in rest → no-leak guard
+ *  - consumer handler run BEFORE the disabled guard → disabled-inert guard
+ *  - onclick / onkeydown / onpointermove ignore `defaultPrevented` → cancel pins
+ *  - onkeydown not composed → onkeydown compose + cancel
+ *  - rest captured statically at init → post-mount reactivity
+ *  - `data-command-item` rendered boolean → identity
+ *  - onpointermove guarded on disabled → disabled-observable pin
+ *  - hover routed through `select()` → hover-does-not-fire-onSelect guard
+ *  - Space branch dropped → Space activation guard
+ *  - disabled keydown returns before `preventDefault()` → disabled-Space pin
+ *  - `'id'` dropped from the type's `Omit` → `src/__typecheck__` pin
+ *
+ * Keyboard note: Enter pressed in the INPUT activates the selected option
+ * through a synthetic `click()` (command-input.svelte), so a consumer observes
+ * that path through `onclick`, not `onkeydown`.
+ */
+describe('command item — native attribute passthrough (#205)', () => {
+    let target;
+    let instance;
+    function setup(props = {}) {
+        target = document.createElement('div');
+        document.body.appendChild(target);
+        instance = mount(CommandTest, { target, props: { portalTo: target, ...props } });
+        flushSync();
+        flushSync(); // $effect item registration
+        return target;
+    }
+    const option = (value) => target.querySelector(`[role="option"][data-value="${value}"]`);
+    const input = () => target.querySelector('input[role="combobox"]');
+    afterEach(() => {
+        if (instance)
+            unmount(instance);
+        target?.remove();
+    });
+    // ── Forwarding ────────────────────────────────────────────────────────
+    it('forwards consumer HTML attributes to the option element', () => {
+        setup({
+            itemAttrs: {
+                title: 'Copy the selection',
+                'aria-label': 'Copy',
+                'aria-describedby': 'copy-hint',
+                'data-testid': 'opt-copy',
+                style: 'color: red',
+            },
+        });
+        const el = option('copy');
+        expect(el.getAttribute('title')).toBe('Copy the selection');
+        expect(el.getAttribute('aria-label')).toBe('Copy');
+        expect(el.getAttribute('aria-describedby')).toBe('copy-hint');
+        expect(el.getAttribute('data-testid')).toBe('opt-copy');
+        expect(el.style.color).toBe('red');
+    });
+    it('reflects a consumer attribute reassigned by the parent after mount', () => {
+        target = document.createElement('div');
+        document.body.appendChild(target);
+        const props = $state({
+            portalTo: target,
+            itemAttrs: { title: 'Before', 'aria-describedby': 'hint-before' },
+        });
+        instance = mount(CommandTest, { target, props });
+        flushSync();
+        expect(option('copy').getAttribute('title')).toBe('Before');
+        props.itemAttrs = { title: 'After', 'aria-describedby': 'hint-after' };
+        flushSync();
+        expect(option('copy').getAttribute('title')).toBe('After');
+        expect(option('copy').getAttribute('aria-describedby')).toBe('hint-after');
+    });
+    it('guard — keeps the DS class alongside a consumer class', () => {
+        setup({ itemAttrs: { class: 'mine' } });
+        const el = option('copy');
+        expect(el.classList.contains('sp-command-item')).toBe(true);
+        expect(el.classList.contains('mine')).toBe(true);
+    });
+    // ── Identity stays ours ───────────────────────────────────────────────
+    it('keeps its identity attributes when a consumer tries to override them', () => {
+        setup({
+            itemAttrs: {
+                role: 'menuitem',
+                id: 'consumer-id',
+                tabindex: 0,
+                'aria-selected': 'false',
+                'aria-disabled': 'true',
+                'data-selected': 'false',
+                'data-value': 'leak',
+                'data-disabled': '',
+                'data-command-item': 'nope',
+                'data-testid': 'still-forwarded',
+            },
+        });
+        // `copy` is the first enabled item → auto-selected.
+        const el = target.querySelector('[data-testid="still-forwarded"]');
+        expect(el).toBeTruthy();
+        expect(el.getAttribute('role')).toBe('option');
+        expect(el.id).toMatch(/^sp-command-item-\d+$/);
+        expect(el.getAttribute('tabindex')).toBe('-1');
+        expect(el.getAttribute('aria-selected')).toBe('true');
+        expect(el.hasAttribute('aria-disabled')).toBe(false);
+        expect(el.getAttribute('data-selected')).toBe('true');
+        expect(el.getAttribute('data-value')).toBe('copy');
+        expect(el.hasAttribute('data-disabled')).toBe(false);
+        // `data-command-item` keeps its shipped form: present, empty-valued.
+        expect(el.hasAttribute('data-command-item')).toBe(true);
+        expect(el.getAttribute('data-command-item')).toBe('');
+    });
+    it('guard — Enter in the input activates the item Spectral selected, whatever the consumer claims', () => {
+        const selected = [];
+        setup({
+            itemAttrs: { 'data-selected': 'false' },
+            onItemSelect: (v) => selected.push(v),
+        });
+        input().dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+        flushSync();
+        expect(selected).toEqual(['copy']);
+    });
+    it('guard — does not leak component props to the DOM', () => {
+        setup({ onItemSelect: () => { } });
+        const copy = option('copy');
+        // (`on*` keys never surface as attributes in Svelte, so only these can fail.)
+        for (const attr of ['value', 'keywords']) {
+            expect(copy.hasAttribute(attr)).toBe(false);
+        }
+        expect(option('settings').hasAttribute('disabled')).toBe(false);
+    });
+    // ── Handler composition ───────────────────────────────────────────────
+    it('composes a consumer onclick with the built-in selection (consumer first)', () => {
+        const seen = [];
+        setup({
+            itemAttrs: { onclick: () => seen.push('consumer') },
+            onItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        option('copy').click();
+        flushSync();
+        expect(seen).toEqual(['consumer', 'selected:copy']);
+    });
+    it('lets a consumer onclick cancel the selection with preventDefault', () => {
+        const selected = [];
+        setup({
+            itemAttrs: { onclick: (e) => e.preventDefault() },
+            onItemSelect: (v) => selected.push(v),
+        });
+        // Move the selection away first, so a (wrongly) successful click is visible.
+        input().dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+        flushSync();
+        expect(option('paste').getAttribute('data-selected')).toBe('true');
+        option('copy').click();
+        flushSync();
+        expect(selected).toEqual([]);
+        expect(option('copy').getAttribute('data-selected')).toBe('false');
+        expect(option('paste').getAttribute('data-selected')).toBe('true');
+    });
+    it('composes a consumer onkeydown with Enter on the option (consumer first)', () => {
+        const seen = [];
+        setup({
+            itemAttrs: { onkeydown: () => seen.push('consumer') },
+            onItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        option('copy').dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+        flushSync();
+        expect(seen).toEqual(['consumer', 'selected:copy']);
+    });
+    it('guard — composes a consumer onkeydown with Space on the option (consumer first)', () => {
+        const seen = [];
+        setup({
+            itemAttrs: { onkeydown: () => seen.push('consumer') },
+            onItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        option('copy').dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true }));
+        flushSync();
+        expect(seen).toEqual(['consumer', 'selected:copy']);
+    });
+    it('lets a consumer onkeydown cancel the Enter/Space activation with preventDefault', () => {
+        const selected = [];
+        setup({
+            itemAttrs: { onkeydown: (e) => e.preventDefault() },
+            onItemSelect: (v) => selected.push(v),
+        });
+        option('copy').dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true }));
+        flushSync();
+        expect(selected).toEqual([]);
+    });
+    it('composes a consumer onpointermove with the hover-selection — which never fires onSelect', () => {
+        const seen = [];
+        setup({
+            itemAttrs: { onpointermove: () => seen.push('consumer') },
+            onItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        // Start from a different selection so the hover-select is observable.
+        input().dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+        flushSync();
+        expect(option('paste').getAttribute('data-selected')).toBe('true');
+        option('copy').dispatchEvent(new PointerEvent('pointermove', { bubbles: true, cancelable: true }));
+        flushSync();
+        expect(seen).toEqual(['consumer']);
+        expect(option('copy').getAttribute('data-selected')).toBe('true');
+    });
+    it('lets a consumer onpointermove cancel the hover-selection with preventDefault', () => {
+        setup({ itemAttrs: { onpointermove: (e) => e.preventDefault() } });
+        input().dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+        flushSync();
+        option('copy').dispatchEvent(new PointerEvent('pointermove', { bubbles: true, cancelable: true }));
+        flushSync();
+        expect(option('copy').getAttribute('data-selected')).toBe('false');
+        expect(option('paste').getAttribute('data-selected')).toBe('true');
+    });
+    // ── Disabled: activation inert, hover observable ──────────────────────
+    it('guard — activation of a disabled item is inert: consumer onclick/onkeydown do not run', () => {
+        const seen = [];
+        setup({
+            disabledItemAttrs: {
+                onclick: () => seen.push('click'),
+                onkeydown: () => seen.push('keydown'),
+            },
+            onDisabledItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        const settings = option('settings');
+        settings.click();
+        settings.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+        flushSync();
+        expect(seen).toEqual([]);
+        expect(option('copy').getAttribute('data-selected')).toBe('true');
+        expect(settings.getAttribute('data-selected')).toBe('false');
+    });
+    it('still prevents the Space default on a focused disabled item, without running the consumer onkeydown', () => {
+        const seen = [];
+        setup({ disabledItemAttrs: { onkeydown: () => seen.push('keydown') } });
+        const event = new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true });
+        option('settings').dispatchEvent(event);
+        flushSync();
+        // Pre-#205 the item prevented Enter/Space before bailing on `disabled`,
+        // so Space on a dimmed, focused row never scrolled the list.
+        expect(event.defaultPrevented).toBe(true);
+        expect(seen).toEqual([]);
+        expect(option('copy').getAttribute('data-selected')).toBe('true');
+    });
+    it('keeps a consumer onpointermove observable on a disabled item without selecting it', () => {
+        const seen = [];
+        setup({
+            disabledItemAttrs: { onpointermove: () => seen.push('move') },
+            onDisabledItemSelect: (v) => seen.push(`selected:${v}`),
+        });
+        const settings = option('settings');
+        settings.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, cancelable: true }));
+        flushSync();
+        expect(seen).toEqual(['move']);
+        expect(settings.getAttribute('data-selected')).toBe('false');
+        expect(option('copy').getAttribute('data-selected')).toBe('true');
+    });
+});

package/dist/components/command/components/command-item.svelte

@@ -10,6 +10,12 @@
     onSelect,
     class: className,
     children,
+    // Pulled out of `rest` so the built-in behaviour can COMPOSE with them
+    // instead of being clobbered by the spread.
+    onclick,
+    onkeydown,
+    onpointermove,
+    ...rest
   }: CommandItemProps = $props()
   const ctx = getCommandContext()
   const id = useId('sp-command-item')
@@ -23,37 +29,68 @@
     return () => ctx.unregisterItem(id)
   })
 
-  function onclick() {
-    if (disabled) return
+  /** Svelte's DOM attribute handlers narrow `currentTarget` to the host
+   *  element; a bare `MouseEvent` is not assignable to that. */
+  type RowEvent<E extends Event> = E & { currentTarget: EventTarget & HTMLDivElement }
+
+  // `onSelect` only fires after a real Spectral selection.
+  function select() {
     ctx.select(value)
     onSelect?.(value)
   }
 
-  function onpointermove() {
+  // Activation of a disabled item is INERT, which includes the consumer's
+  // handler: a dimmed, unselectable row must not fire an application effect.
+  function handleClick(event: RowEvent<MouseEvent>) {
+    if (disabled) return
+    onclick?.(event)
+    if (event.defaultPrevented) return
+    select()
+  }
+
+  function handleKeydown(event: RowEvent<KeyboardEvent>) {
+    if (disabled) {
+      // Activation stays inert, but Enter/Space keep their default prevented so
+      // a focused, dimmed row never scrolls the list.
+      if (event.key === 'Enter' || event.key === ' ') event.preventDefault()
+      return
+    }
+    onkeydown?.(event)
+    if (event.defaultPrevented) return
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      select()
+    }
+  }
+
+  // Deliberately NOT guarded on `disabled`: a consumer may observe the pointer
+  // over a dimmed row; only the internal hover-selection is forbidden.
+  function handlePointerMove(event: RowEvent<PointerEvent>) {
+    onpointermove?.(event)
+    if (event.defaultPrevented) return
     if (!disabled && ctx.selectedValue !== value) ctx.select(value)
   }
 </script>
 
 {#if isVisible}
+  <!-- `{...rest}` FIRST: a consumer may add attributes, never override the
+       option's identity (role, id, selection state, internal data-*) — those
+       come after and win. `data-command-item=""` keeps its shipped form. -->
   <div
+    {...rest}
     class="sp-command-item {className ?? ''}"
     {id}
     role="option"
     aria-selected={isSelected}
     aria-disabled={disabled || undefined}
-    data-command-item
+    data-command-item=""
     data-value={value}
     data-selected={isSelected}
     data-disabled={disabled || undefined}
     tabindex={-1}
-    {onclick}
-    onkeydown={(e) => {
-      if (e.key === 'Enter' || e.key === ' ') {
-        e.preventDefault()
-        onclick()
-      }
-    }}
-    {onpointermove}
+    onclick={handleClick}
+    onkeydown={handleKeydown}
+    onpointermove={handlePointerMove}
   >
     {#if children}{@render children()}{/if}
   </div>

package/dist/components/command/components/command-item.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-item.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-item.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAuDnD,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"command-item.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-item.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAyFnD,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/components/command/types.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
 export interface CommandProps {
     /** Current search query (bindable). */
     value?: string;
@@ -53,14 +54,38 @@ export interface CommandGroupProps {
     class?: string;
     children?: Snippet;
 }
-export interface CommandItemProps {
+/**
+ * Extends the native `div` attributes (spectral-ui#205): a consumer's `title`,
+ * `aria-*` (including `aria-label`, which replaces the name derived from the
+ * content — standard ARIA precedence; `value`/`keywords` stay the filter's
+ * authority), `data-testid`, `style` and native event handlers reach the real
+ * `role="option"` node.
+ *
+ * The option's identity stays with the component: `role`, `id`, `tabindex`,
+ * `aria-selected` and `aria-disabled` are rejected by the type, and the
+ * internal `data-*` (`data-command-item`, `data-value`, `data-selected`,
+ * `data-disabled`) cannot be overridden — the type cannot exclude `data-*`
+ * keys, the markup order does.
+ *
+ * Consumer handlers COMPOSE with the built-in ones: yours runs first, and
+ * calling `preventDefault()` cancels the Spectral selection. Activation of a
+ * disabled item is inert (`onclick` / `onkeydown` do not run); `onpointermove`
+ * stays observable on a disabled item, which is never selected.
+ */
+export interface CommandItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children' | 'role' | 'id' | 'tabindex' | 'aria-selected' | 'aria-disabled'> {
     /** Unique value for this item. */
     value: string;
     /** Extra keywords used for search matching (not displayed). */
     keywords?: string[];
     /** Whether the item is disabled. */
     disabled?: boolean;
-    /** Called when the item is selected (Enter or click). */
+    /**
+     * Called after a real Spectral selection (click, Enter/Space on the option,
+     * or Enter in the input — which reaches the option as a synthetic `click`).
+     * Hover-selection never fires it. `onSelect` is the Spectral callback; the
+     * native lowercase `onselect` DOM handler, if provided, stays an ordinary DOM
+     * event — Command's selection mechanisms never invoke it.
+     */
     onSelect?: (value: string) => void;
     class?: string;
     children?: Snippet;

package/dist/components/command/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACvE,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,mDAAmD;IACnD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAChD,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACjD,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACvE,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,mDAAmD;IACnD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAChD,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACjD,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAC5C,cAAc,CAAC,cAAc,CAAC,EAC9B,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,CACtF;IACC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spectral_labs/ui",
   "type": "module",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/src/themes/__tests__/generated-css-drift.test.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { generateThemeCSS, generateTokensCSS, themes } from '../../../../../scripts/generate-themes'
+
+/**
+ * Durable control between `scripts/generate-themes.ts` and the six committed
+ * theme files (+ `tokens.css`): the committed file must be exactly what the
+ * generator emits once formatted by the repo's Prettier config. A hand edit
+ * of a generated file, or a generator change without regeneration, turns this
+ * RED — the two can no longer drift apart silently (spectral-ui#206).
+ *
+ * Importing the generator must not write anything: `main()` only runs when
+ * the script is executed directly.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const themesDir = resolve(here, '..')
+
+// Vitest resolves `prettier` with the `browser` condition (standalone build,
+// no `resolveConfig`); the Node build is what the repo's `prettier --write`
+// runs, so load exactly that one.
+const require = createRequire(import.meta.url)
+const prettier = require('prettier') as typeof import('prettier')
+
+async function formatted(css: string, filepath: string): Promise<string> {
+  const config = (await prettier.resolveConfig(filepath)) ?? {}
+  return prettier.format(css, { ...config, filepath })
+}
+
+describe('generated theme CSS matches the generator (#206)', () => {
+  it('exposes the six themes', () => {
+    expect(themes.map((t) => t.name).sort()).toEqual(
+      ['carbon', 'day', 'docs', 'iris-ocr', 'midnight', 'spectral'].sort(),
+    )
+  })
+
+  for (const theme of themes) {
+    it(`${theme.name}.css is prettier(generateThemeCSS)`, async () => {
+      const filepath = resolve(themesDir, `${theme.name}.css`)
+      const committed = readFileSync(filepath, 'utf8')
+      expect(committed).toBe(await formatted(generateThemeCSS(theme), filepath))
+    })
+  }
+
+  it('tokens.css is prettier(generateTokensCSS)', async () => {
+    const filepath = resolve(themesDir, '..', 'tokens.css')
+    const committed = readFileSync(filepath, 'utf8')
+    expect(committed).toBe(await formatted(generateTokensCSS(), filepath))
+  })
+})

package/src/themes/__tests__/scrim-opaque.test.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * spectral-ui#206 — `--sp-sys-color-scrim` is an OPAQUE colour in every theme
+ * and every mode. The veil's intensity belongs to the component's opacity
+ * token (`--sp-comp-*-overlay-opacity`, default 0.32) — never to the token,
+ * and never to both at once.
+ *
+ * This is a SOURCE pin: every `--sp-sys-color-scrim` declaration in the six
+ * generated theme files must be the opaque reference tone, and the generator
+ * must carry no hand-tuned scrim override that could re-introduce an alpha.
+ * The cascade itself (which declaration wins in `.dark`) is proven in a real
+ * Chromium by `tests/e2e/scrim-alpha.spec.ts`; jsdom cannot be that oracle.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const THEMES = ['spectral', 'day', 'midnight', 'carbon', 'iris-ocr', 'docs'] as const
+const OPAQUE = 'var(--sp-ref-palette-neutral-0)'
+
+describe('--sp-sys-color-scrim is opaque in every theme and mode (#206)', () => {
+  for (const theme of THEMES) {
+    it(`${theme}.css declares the scrim as the opaque reference tone only`, () => {
+      const css = readFileSync(resolve(here, `../${theme}.css`), 'utf8')
+      const declarations = [...css.matchAll(/--sp-sys-color-scrim:([^;]+);/g)].map((m) =>
+        m[1].trim(),
+      )
+      // One in the generated light block, one in the generated dark block —
+      // nothing else, so no hand-tuned block can shadow them with an alpha.
+      // This single equality subsumes "never translucent": ANY other value, in
+      // any spelling (`rgba()`, `color-mix()`, `#RRGGBBAA`, `oklch(… / a)`),
+      // and any extra or missing declaration, fails here.
+      expect(declarations).toEqual([OPAQUE, OPAQUE])
+    })
+  }
+
+  it('the generator carries no hand-tuned color-scrim override', () => {
+    const generator = readFileSync(
+      resolve(here, '../../../../../scripts/generate-themes.ts'),
+      'utf8',
+    )
+    // A hand-tuned override is a `'color-scrim': '<value>'` entry (the
+    // `SystemColorTokens` interface field `'color-scrim': string` is not one).
+    const overrides = generator.match(/['"]color-scrim['"]\s*:\s*['"]/g) ?? []
+    expect(overrides).toEqual([])
+    // The two generated declarations (light + dark) still exist and are opaque.
+    const emitted = [...generator.matchAll(/--sp-sys-color-scrim:\s*\$\{ref\('neutral', 0\)\};/g)]
+    expect(emitted).toHaveLength(2)
+  })
+})

package/src/themes/carbon.css

@@ -3,7 +3,7 @@
  * Grey charcoal theme (#5c7cfa) for Refero/AutomaticBook.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */
@@ -265,7 +265,6 @@
   --sp-sys-color-success: #34c759;
   --sp-sys-color-warning: #ff9f0a;
   --sp-sys-color-error: #ff3b30;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.3);
   --sp-sys-color-inverse-surface: #2c2c2e;
   --sp-sys-color-inverse-on-surface: #f5f5f7;
 }

package/src/themes/day.css

@@ -3,7 +3,7 @@
  * Light macOS-like theme (#f5f5f7), transversal for all apps.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */
@@ -265,7 +265,6 @@
   --sp-sys-color-success: #34c759;
   --sp-sys-color-warning: #ff9f0a;
   --sp-sys-color-error: #ff3b30;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.3);
   --sp-sys-color-inverse-surface: #2c2c2e;
   --sp-sys-color-inverse-on-surface: #f5f5f7;
 }

package/src/themes/docs.css

@@ -3,7 +3,7 @@
  * Grey + warm orange theme (#ce9178) for SpectralDocs/Status.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */

package/src/themes/iris-ocr.css

@@ -3,7 +3,7 @@
  * Hybrid theme for Iris-OCR: day light mode + neon dark mode.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */
@@ -265,7 +265,6 @@
   --sp-sys-color-success: #34c759;
   --sp-sys-color-warning: #ff9f0a;
   --sp-sys-color-error: #ff3b30;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.3);
   --sp-sys-color-inverse-surface: #2c2c2e;
   --sp-sys-color-inverse-on-surface: #f5f5f7;
 

package/src/themes/midnight.css

@@ -3,7 +3,7 @@
  * Blue-black Catppuccin-inspired theme (#89b4fa) for Translator/Preparo.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */
@@ -265,7 +265,6 @@
   --sp-sys-color-success: #34c759;
   --sp-sys-color-warning: #ff9f0a;
   --sp-sys-color-error: #ff3b30;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.3);
   --sp-sys-color-inverse-surface: #2c2c2e;
   --sp-sys-color-inverse-on-surface: #f5f5f7;
 }

package/src/themes/spectral.css

@@ -3,7 +3,7 @@
  * Spectral hybrid theme: day light mode + iris-ocr dark mode.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 /* ═══ REFERENCE TOKENS ═══ */
@@ -265,7 +265,6 @@
   --sp-sys-color-success: #34c759;
   --sp-sys-color-warning: #ff9f0a;
   --sp-sys-color-error: #ff3b30;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.3);
   --sp-sys-color-inverse-surface: #2c2c2e;
   --sp-sys-color-inverse-on-surface: #f5f5f7;
 
@@ -307,7 +306,6 @@
   --sp-sys-color-success: #69f0ae;
   --sp-sys-color-warning: #ffab40;
   --sp-sys-color-error: #ff5252;
-  --sp-sys-color-scrim: rgba(0, 0, 0, 0.6);
 
   /* ═══ EXTENSION TOKENS (--sp-ext-*) — Internal, theme-specific ═══ */
   --sp-ext-glow-color: #00ffe0;

package/src/tokens.css

@@ -4,7 +4,7 @@
  * Shared across all themes — included in base.css.
  *
  * Generated by scripts/generate-themes.ts
- * Do not edit manually — regenerate with: npx tsx scripts/generate-themes.ts
+ * Do not edit manually — regenerate with: pnpm generate:themes
  */
 
 :root {