sh3-core 0.13.1 → 0.13.2

package/dist/primitives/Button.svelte

@@ -6,6 +6,9 @@
    * `icon` accepts either a sprite symbol id ("save") or a direct URL
    * ending in .svg / containing a slash ("./foo.svg"); the URL form
    * bypasses the active sprite entirely.
+   *
+   * `loading` flips the button into a pending state: spinner takes the
+   * icon slot, label stays put, button is disabled, aria-busy is set.
    */
 
   import type { Snippet } from 'svelte';
@@ -17,6 +20,7 @@
     icon,
     sprite,
     disabled = false,
+    loading,
     type = 'button',
     title,
     ariaLabel,
@@ -29,10 +33,12 @@
     /** Override the sprite sheet URL for this button only. */
     sprite?: string;
     disabled?: boolean;
+    /** Controlled pending state. When true, spinner + disabled + aria-busy. */
+    loading?: boolean;
     type?: 'button' | 'submit' | 'reset';
     title?: string;
     ariaLabel?: string;
-    onclick?: (event: MouseEvent) => void;
+    onclick?: (event: MouseEvent) => void | Promise<unknown>;
     children?: Snippet;
   } = $props();
 
@@ -49,19 +55,48 @@
     return `${base}#${icon}`;
   });
 
+  let autoPending = $state(false);
+  const pending = $derived(loading ?? autoPending);
   const iconOnly = $derived(variant === 'icon' || (!!icon && !children));
+
+  async function handleClick(event: MouseEvent) {
+    if (!onclick) return;
+    const result = onclick(event);
+    if (result && typeof (result as PromiseLike<unknown>).then === 'function') {
+      autoPending = true;
+      try {
+        await result;
+      } finally {
+        autoPending = false;
+      }
+    }
+  }
 </script>
 
 <button
   {type}
   class="sh3-btn sh3-btn--{variant}"
   class:sh3-btn--icon-only={iconOnly}
-  {disabled}
+  disabled={disabled || pending}
+  aria-busy={pending || undefined}
   {title}
   aria-label={ariaLabel ?? (iconOnly ? title : undefined)}
-  {onclick}
+  onclick={handleClick}
 >
-  {#if iconHref}
+  {#if pending}
+    <svg class="sh3-btn__spinner" aria-hidden="true" viewBox="0 0 16 16">
+      <circle
+        cx="8"
+        cy="8"
+        r="6"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-dasharray="30 10"
+      />
+    </svg>
+  {:else if iconHref}
     <svg class="sh3-btn__icon" aria-hidden="true">
       <use href={iconHref} />
     </svg>
@@ -141,4 +176,15 @@
     display: inline-flex;
     white-space: nowrap;
   }
+
+  .sh3-btn__spinner {
+    width: 16px;
+    height: 16px;
+    flex-shrink: 0;
+    animation: sh3-btn-spin 0.8s linear infinite;
+  }
+
+  @keyframes sh3-btn-spin {
+    to { transform: rotate(360deg); }
+  }
 </style>

package/dist/primitives/Button.svelte.d.ts

@@ -7,10 +7,12 @@ type $$ComponentProps = {
     /** Override the sprite sheet URL for this button only. */
     sprite?: string;
     disabled?: boolean;
+    /** Controlled pending state. When true, spinner + disabled + aria-busy. */
+    loading?: boolean;
     type?: 'button' | 'submit' | 'reset';
     title?: string;
     ariaLabel?: string;
-    onclick?: (event: MouseEvent) => void;
+    onclick?: (event: MouseEvent) => void | Promise<unknown>;
     children?: Snippet;
 };
 declare const Button: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/primitives/Collapsible.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+  /*
+   * Collapsible — structural primitive for show/hide sections.
+   *
+   * Body is conditionally rendered (not just hidden) so heavy children
+   * don't stay live when collapsed. Defaults to closed. No collapse/expand
+   * animation in v1 — caret rotates 90° via CSS, but no transitions
+   * (waiting on the motion RFC).
+   *
+   * `header` snippet, when provided, replaces the `title` string.
+   */
+
+  import type { Snippet } from 'svelte';
+
+  let {
+    open = $bindable(false),
+    title,
+    header,
+    children,
+    onopenchange,
+  }: {
+    /** Bindable; defaults to false. */
+    open?: boolean;
+    /** Plain text header. Ignored if `header` snippet is provided. */
+    title?: string;
+    /** Snippet alternative to `title` for richer headers. */
+    header?: Snippet;
+    children: Snippet;
+    onopenchange?: (open: boolean) => void;
+  } = $props();
+
+  function toggle() {
+    open = !open;
+    onopenchange?.(open);
+  }
+</script>
+
+<div class="sh3-collapsible" class:sh3-collapsible--open={open}>
+  <button
+    class="sh3-collapsible__head"
+    type="button"
+    aria-expanded={open}
+    onclick={toggle}
+  >
+    <svg class="sh3-collapsible__caret" aria-hidden="true" viewBox="0 0 16 16">
+      <path
+        d="M5 3l6 5-6 5"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
+    {#if header}
+      {@render header()}
+    {:else if title}
+      <span class="sh3-collapsible__title">{title}</span>
+    {/if}
+  </button>
+  {#if open}
+    <div class="sh3-collapsible__body">{@render children()}</div>
+  {/if}
+</div>
+
+<style>
+  .sh3-collapsible {
+    border: 1px solid var(--shell-border);
+    border-radius: var(--shell-radius);
+    background: transparent;
+  }
+  .sh3-collapsible__head {
+    appearance: none;
+    width: 100%;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--shell-pad-sm);
+    padding: var(--shell-pad-sm) 12px;
+    background: transparent;
+    color: var(--shell-fg);
+    border: none;
+    border-radius: inherit;
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.875rem;
+    line-height: var(--shell-line);
+    text-align: left;
+  }
+  .sh3-collapsible__head:hover { background: var(--shell-bg-elevated); }
+  .sh3-collapsible__head:focus-visible {
+    box-shadow: var(--shell-focus-ring);
+    outline: none;
+  }
+  .sh3-collapsible__caret {
+    width: 12px;
+    height: 12px;
+    flex-shrink: 0;
+    color: var(--shell-fg-muted);
+  }
+  .sh3-collapsible--open .sh3-collapsible__caret {
+    transform: rotate(90deg);
+  }
+  .sh3-collapsible__title {
+    flex: 1;
+  }
+  .sh3-collapsible__body {
+    padding: var(--shell-pad-sm) 12px;
+    border-top: 1px solid var(--shell-border);
+  }
+</style>

package/dist/primitives/Collapsible.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Bindable; defaults to false. */
+    open?: boolean;
+    /** Plain text header. Ignored if `header` snippet is provided. */
+    title?: string;
+    /** Snippet alternative to `title` for richer headers. */
+    header?: Snippet;
+    children: Snippet;
+    onopenchange?: (open: boolean) => void;
+};
+declare const Collapsible: import("svelte").Component<$$ComponentProps, {}, "open">;
+type Collapsible = ReturnType<typeof Collapsible>;
+export default Collapsible;

package/dist/primitives/widgets/AppPicker.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
+  import PickerList from './PickerList.svelte';
+  import type { PickerItem } from './PickerList';
+  import { listRegisteredApps } from '../../apps/registry.svelte';
+
+  /** Apps the framework ships and that bypass the project allowlist server-side. */
+  const FRAMEWORK_APP_IDS = new Set(['sh3-admin-app', 'sh3-store-app']);
+
+  let {
+    value = $bindable<string[]>([]),
+    onchange,
+    disabled = false,
+    size = 'md',
+  }: {
+    value?: string[];
+    disabled?: boolean;
+    size?: 'sm' | 'md';
+  } & CommitOnlyEvents<string[]> = $props();
+
+  const items = $derived<PickerItem[]>(
+    listRegisteredApps()
+      .filter((m) => !FRAMEWORK_APP_IDS.has(m.id) && !m.admin)
+      .map((m) => ({ id: m.id, label: m.label, sublabel: m.id }))
+      .sort((a, b) => a.label.localeCompare(b.label)),
+  );
+
+  function handleChange(next: string[]) {
+    value = next;
+    onchange?.(next);
+  }
+</script>
+
+<PickerList
+  {items}
+  {value}
+  onchange={handleChange}
+  {disabled}
+  {size}
+  emptyText="No apps installed."
+/>

package/dist/primitives/widgets/AppPicker.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { CommitOnlyEvents } from './_contract';
+type $$ComponentProps = {
+    value?: string[];
+    disabled?: boolean;
+    size?: 'sm' | 'md';
+} & CommitOnlyEvents<string[]>;
+declare const AppPicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type AppPicker = ReturnType<typeof AppPicker>;
+export default AppPicker;

package/dist/primitives/widgets/AppPicker.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/AppPicker.svelte.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import AppPicker from './AppPicker.svelte';
+vi.mock('../../apps/registry.svelte', () => ({
+    listRegisteredApps: () => [
+        { id: 'sh3-store-app', label: 'Store' },
+        { id: 'app.alpha', label: 'Alpha' },
+        { id: 'app.bravo', label: 'Bravo', admin: true },
+        { id: 'app.charlie', label: 'Charlie' },
+    ],
+}));
+describe('AppPicker event contract', () => {
+    it('renders only non-framework, non-admin apps', () => {
+        const { container } = render(AppPicker, { props: { value: [] } });
+        const labels = Array.from(container.querySelectorAll('.sh3-picker__row-label')).map((el) => el.textContent);
+        expect(labels).toEqual(['Alpha', 'Charlie']);
+    });
+    it('fires onchange when an app row is toggled', async () => {
+        const onchange = vi.fn();
+        const { container } = render(AppPicker, { props: { value: [], onchange } });
+        const checkboxes = container.querySelectorAll('input[type=checkbox]');
+        await fireEvent.click(checkboxes[0]);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith(['app.alpha']);
+    });
+});

package/dist/primitives/widgets/AppPicker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/AppPicker.test.js

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mount, unmount, tick } from 'svelte';
+import AppPicker from './AppPicker.svelte';
+import { registerApp, __resetAppRegistryForTest } from '../../apps/registry.svelte';
+let host;
+let cmp = null;
+function makeApp(id, label, opts = {}) {
+    return {
+        manifest: Object.assign({ id, label, version: '0.0.0', requiredShards: [], layoutVersion: 1 }, (opts.admin ? { admin: true } : {})),
+        initialLayout: { type: 'leaf', viewId: 'x:v' },
+    };
+}
+beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    __resetAppRegistryForTest();
+});
+afterEach(() => {
+    if (cmp) {
+        unmount(cmp);
+        cmp = null;
+    }
+    host.remove();
+    __resetAppRegistryForTest();
+});
+describe('AppPicker', () => {
+    it('renders one row per non-framework, non-admin app', async () => {
+        registerApp(makeApp('notes', 'Notes'));
+        registerApp(makeApp('files', 'Files'));
+        registerApp(makeApp('sh3-admin-app', 'Admin')); // framework — excluded
+        registerApp(makeApp('sh3-store-app', 'Store')); // framework — excluded
+        registerApp(makeApp('shadow', 'Shadow', { admin: true })); // admin flag — excluded
+        cmp = mount(AppPicker, { target: host, props: { value: [] } });
+        await tick();
+        const rows = host.querySelectorAll('.sh3-picker__row');
+        expect(rows.length).toBe(2);
+        const labels = Array.from(rows).map((r) => { var _a; return (_a = r.querySelector('.sh3-picker__row-label')) === null || _a === void 0 ? void 0 : _a.textContent; }).sort();
+        expect(labels).toEqual(['Files', 'Notes']);
+    });
+    it('passes selected ids through as checked rows', async () => {
+        registerApp(makeApp('notes', 'Notes'));
+        registerApp(makeApp('files', 'Files'));
+        cmp = mount(AppPicker, { target: host, props: { value: ['files'] } });
+        await tick();
+        const checks = host.querySelectorAll('input[type="checkbox"]');
+        const byLabel = (text) => Array.from(checks).find((c) => { var _a, _b; return (_b = (_a = c.closest('.sh3-picker__row')) === null || _a === void 0 ? void 0 : _a.textContent) === null || _b === void 0 ? void 0 : _b.includes(text); });
+        expect(byLabel('Files').checked).toBe(true);
+        expect(byLabel('Notes').checked).toBe(false);
+    });
+    it('fires onchange with the new array on row click', async () => {
+        registerApp(makeApp('notes', 'Notes'));
+        registerApp(makeApp('files', 'Files'));
+        let received = null;
+        cmp = mount(AppPicker, {
+            target: host,
+            props: {
+                value: [],
+                onchange: (next) => { received = next; },
+            },
+        });
+        await tick();
+        const filesRow = Array.from(host.querySelectorAll('.sh3-picker__row'))
+            .find((r) => { var _a; return (_a = r.textContent) === null || _a === void 0 ? void 0 : _a.includes('Files'); });
+        filesRow.querySelector('input[type="checkbox"]').click();
+        await tick();
+        expect(received).toEqual(['files']);
+    });
+    it('shows emptyText when there are no installable apps', async () => {
+        registerApp(makeApp('sh3-admin-app', 'Admin')); // framework — excluded
+        cmp = mount(AppPicker, { target: host, props: { value: [] } });
+        await tick();
+        expect(host.textContent).toMatch(/No apps installed\./);
+    });
+});

package/dist/primitives/widgets/ColorSwatch.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
   import { shell } from '../../shellRuntime.svelte';
 
   let {
@@ -6,19 +7,23 @@
     label,
     disabled = false,
     size = 'md',
+    onchange,
   }: {
     value?: string;
     label?: string;
     disabled?: boolean;
     size?: 'sm' | 'md';
-  } = $props();
+  } & CommitOnlyEvents<string> = $props();
 
   let trigger: HTMLButtonElement | undefined;
 
   async function open() {
     if (disabled) return;
     const result = await shell.color.pick({ initial: value, anchor: trigger });
-    if (result !== null && result !== undefined) value = result;
+    if (result !== null && result !== undefined) {
+      value = result;
+      onchange?.(result);
+    }
   }
 </script>
 

package/dist/primitives/widgets/ColorSwatch.svelte.d.ts

@@ -1,9 +1,10 @@
+import type { CommitOnlyEvents } from './_contract';
 type $$ComponentProps = {
     value?: string;
     label?: string;
     disabled?: boolean;
     size?: 'sm' | 'md';
-};
+} & CommitOnlyEvents<string>;
 declare const ColorSwatch: import("svelte").Component<$$ComponentProps, {}, "value">;
 type ColorSwatch = ReturnType<typeof ColorSwatch>;
 export default ColorSwatch;

package/dist/primitives/widgets/ColorSwatch.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/ColorSwatch.svelte.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import ColorSwatch from './ColorSwatch.svelte';
+vi.mock('../../shellRuntime.svelte', () => ({
+    shell: {
+        color: {
+            pick: vi.fn(async () => '#abcdef'),
+        },
+    },
+}));
+describe('ColorSwatch event contract', () => {
+    it('fires onchange with new hex when picker resolves', async () => {
+        const onchange = vi.fn();
+        const { container } = render(ColorSwatch, { props: { value: '#000000', onchange } });
+        const trigger = container.querySelector('.sh3-swatch__btn');
+        await fireEvent.click(trigger);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith('#abcdef');
+    });
+    it('does not fire onchange when picker is cancelled (returns null)', async () => {
+        const { shell } = await import('../../shellRuntime.svelte');
+        shell.color.pick.mockResolvedValueOnce(null);
+        const onchange = vi.fn();
+        const { container } = render(ColorSwatch, { props: { value: '#000000', onchange } });
+        const trigger = container.querySelector('.sh3-swatch__btn');
+        await fireEvent.click(trigger);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(onchange).not.toHaveBeenCalled();
+    });
+});

package/dist/primitives/widgets/Field.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import type { LiveInputEvents } from './_contract';
 
   let {
     value = $bindable(''),
@@ -15,6 +16,7 @@
     size = 'md',
     required = false,
     autocomplete,
+    oninput,
     onchange,
   }: {
     value?: string;
@@ -30,8 +32,7 @@
     size?: 'sm' | 'md';
     required?: boolean;
     autocomplete?: AutoFill;
-    onchange?: (next: string) => void;
-  } = $props();
+  } & LiveInputEvents<string> = $props();
 
   const showError = $derived(invalid && !!error);
   const helperText = $derived(showError ? error : helper);
@@ -50,6 +51,7 @@
       {autocomplete}
       aria-invalid={invalid || undefined}
       bind:value
+      oninput={() => oninput?.(value)}
       onblur={() => onchange?.(value)}
     />
     {#if suffix}<span class="sh3-field__affix">{@render suffix()}</span>{/if}

package/dist/primitives/widgets/Field.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { LiveInputEvents } from './_contract';
 type $$ComponentProps = {
     value?: string;
     type?: 'text' | 'email' | 'password' | 'search' | 'url' | 'tel';
@@ -13,8 +14,7 @@ type $$ComponentProps = {
     size?: 'sm' | 'md';
     required?: boolean;
     autocomplete?: AutoFill;
-    onchange?: (next: string) => void;
-};
+} & LiveInputEvents<string>;
 declare const Field: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Field = ReturnType<typeof Field>;
 export default Field;

package/dist/primitives/widgets/Field.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/Field.svelte.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import Field from './Field.svelte';
+describe('Field event contract', () => {
+    it('fires oninput on every keystroke with current value', async () => {
+        const oninput = vi.fn();
+        const { container } = render(Field, { props: { value: '', oninput } });
+        const input = container.querySelector('input');
+        await fireEvent.input(input, { target: { value: 'h' } });
+        await fireEvent.input(input, { target: { value: 'he' } });
+        await fireEvent.input(input, { target: { value: 'hel' } });
+        expect(oninput).toHaveBeenCalledTimes(3);
+        expect(oninput).toHaveBeenNthCalledWith(1, 'h');
+        expect(oninput).toHaveBeenNthCalledWith(2, 'he');
+        expect(oninput).toHaveBeenNthCalledWith(3, 'hel');
+    });
+    it('fires onchange exactly once on blur with final value', async () => {
+        const onchange = vi.fn();
+        const { container } = render(Field, { props: { value: '', onchange } });
+        const input = container.querySelector('input');
+        await fireEvent.input(input, { target: { value: 'hello' } });
+        await fireEvent.blur(input);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith('hello');
+    });
+    it('renders error text and aria-invalid when invalid', () => {
+        const { container, getByText } = render(Field, {
+            props: { value: '', invalid: true, error: 'Required' },
+        });
+        expect(container.querySelector('input').getAttribute('aria-invalid')).toBe('true');
+        expect(getByText('Required')).toBeInTheDocument();
+    });
+});

package/dist/primitives/widgets/FilePicker.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
   import { extractValue, displayName, type FilePickerValue } from './FilePicker';
 
   let {
@@ -18,8 +19,7 @@
     invalid?: boolean;
     size?: 'sm' | 'md';
     buttonLabel?: string;
-    onchange?: (next: FilePickerValue) => void;
-  } = $props();
+  } & CommitOnlyEvents<FilePickerValue> = $props();
 
   function onPick(e: Event) {
     const target = e.currentTarget as HTMLInputElement;

package/dist/primitives/widgets/FilePicker.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { CommitOnlyEvents } from './_contract';
 import { type FilePickerValue } from './FilePicker';
 type $$ComponentProps = {
     value?: FilePickerValue;
@@ -7,8 +8,7 @@ type $$ComponentProps = {
     invalid?: boolean;
     size?: 'sm' | 'md';
     buttonLabel?: string;
-    onchange?: (next: FilePickerValue) => void;
-};
+} & CommitOnlyEvents<FilePickerValue>;
 declare const FilePicker: import("svelte").Component<$$ComponentProps, {}, "value">;
 type FilePicker = ReturnType<typeof FilePicker>;
 export default FilePicker;

package/dist/primitives/widgets/FilePicker.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/FilePicker.svelte.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import FilePicker from './FilePicker.svelte';
+function makeFile(name) {
+    return new File(['x'], name, { type: 'text/plain' });
+}
+describe('FilePicker event contract', () => {
+    it('fires onchange with single File when picked', async () => {
+        const onchange = vi.fn();
+        const { container } = render(FilePicker, { props: { onchange } });
+        const native = container.querySelector('input[type=file]');
+        const file = makeFile('hello.txt');
+        Object.defineProperty(native, 'files', { value: [file] });
+        await fireEvent.change(native);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange.mock.calls[0][0]).toBeInstanceOf(File);
+        expect(onchange.mock.calls[0][0].name).toBe('hello.txt');
+    });
+    it('fires onchange with File[] when multiple', async () => {
+        const onchange = vi.fn();
+        const { container } = render(FilePicker, { props: { multiple: true, onchange } });
+        const native = container.querySelector('input[type=file]');
+        const files = [makeFile('a.txt'), makeFile('b.txt')];
+        Object.defineProperty(native, 'files', { value: files });
+        await fireEvent.change(native);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        const next = onchange.mock.calls[0][0];
+        expect(Array.isArray(next)).toBe(true);
+        expect(next.map((f) => f.name)).toEqual(['a.txt', 'b.txt']);
+    });
+});

package/dist/primitives/widgets/IconToggleGroup.svelte

@@ -1,24 +1,24 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import type { CommitOnlyEvents } from './_contract';
   import { toggleSingle, toggleMultiple } from './IconToggleGroup';
 
   type Option = { value: string; icon: Snippet; tooltip?: string };
 
   let {
     options,
-    value = $bindable(),
     multiple = false,
+    value = $bindable<string | string[]>(multiple ? [] : (options[0]?.value ?? '')),
     disabled = false,
     size = 'md',
     onchange,
   }: {
     options: Option[];
-    value: string | string[];
     multiple?: boolean;
+    value?: string | string[];
     disabled?: boolean;
     size?: 'sm' | 'md';
-    onchange?: (next: string | string[]) => void;
-  } = $props();
+  } & CommitOnlyEvents<string | string[]> = $props();
 
   function isActive(v: string): boolean {
     if (multiple && Array.isArray(value)) return value.includes(v);