@kitn.ai/ui 0.17.0 → 0.18.0

package/src/components/voice-output.tsx

@@ -0,0 +1,202 @@
+import { splitProps, Show, createSignal, createEffect, on, onCleanup } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { Tooltip } from '../ui/tooltip';
+
+/** Imperative handle exposed via `controllerRef` — surfaces the playback controls
+ *  so the `<kai-voice-output>` facade can forward them as instance methods. Both
+ *  the native (speechSynthesis) and model (synthesize → Audio) paths run through
+ *  these, so manual clicks and programmatic calls behave identically. */
+export interface VoiceOutputController {
+  /** Speak the current `text` (native by default, model if `synthesize` is set). */
+  speak(): void;
+  /** Pause playback (resumable). */
+  pause(): void;
+  /** Resume paused playback. */
+  resume(): void;
+  /** Stop playback and reset. */
+  stop(): void;
+}
+
+export interface VoiceOutputProps {
+  /** The utterance to read aloud. */
+  text: string;
+  /** Speak automatically when `text` is set/changed. */
+  autoplay?: boolean;
+  /** TTS model seam: given text, return an audio Blob to play. When set, the
+   *  native speechSynthesis path is bypassed. Mirrors VoiceInput's `onTranscribe`. */
+  onSynthesize?: (text: string) => Promise<Blob>;
+  /** Fires whenever playback starts or stops. */
+  onSpeakingChange?: (speaking: boolean) => void;
+  /** Fires once the model path resolves audio (model path only). */
+  onSynthesized?: (blob: Blob) => void;
+  disabled?: boolean;
+  class?: string;
+  /** Receive the imperative controller once mounted. The `<kai-voice-output>`
+   *  facade forwards these as element methods (speak/pause/resume/stop). */
+  controllerRef?: (controller: VoiceOutputController) => void;
+}
+
+/** True when the browser exposes the Web Speech synthesis API. */
+function hasSpeechSynthesis(): boolean {
+  return typeof window !== 'undefined' && 'speechSynthesis' in window;
+}
+
+export function VoiceOutput(props: VoiceOutputProps) {
+  const [local] = splitProps(props, ['text', 'disabled', 'class']);
+  const [isSpeaking, setIsSpeaking] = createSignal(false);
+  const [isLoading, setIsLoading] = createSignal(false);
+
+  // The model path plays through one reused <Audio>; the native path drives
+  // speechSynthesis. Only one is live at a time (branch on onSynthesize).
+  let audio: HTMLAudioElement | undefined;
+  let objectUrl: string | undefined;
+  let utterance: SpeechSynthesisUtterance | undefined;
+
+  // No way to speak at all → render disabled. A model seam OR native synthesis
+  // is enough; absent both, the control is inert (see the facade/spec).
+  const capable = () => !!props.onSynthesize || hasSpeechSynthesis();
+
+  const label = () =>
+    isLoading() ? 'Synthesizing...' : isSpeaking() ? 'Stop' : 'Read aloud';
+
+  function revokeUrl() {
+    if (objectUrl) {
+      URL.revokeObjectURL(objectUrl);
+      objectUrl = undefined;
+    }
+  }
+
+  // Native path: speechSynthesis.speak(new SpeechSynthesisUtterance(text)).
+  function speakNative() {
+    if (!hasSpeechSynthesis() || !local.text) return;
+    window.speechSynthesis.cancel();
+    utterance = new SpeechSynthesisUtterance(local.text);
+    utterance.onend = () => setIsSpeaking(false);
+    utterance.onerror = () => setIsSpeaking(false);
+    setIsSpeaking(true);
+    window.speechSynthesis.speak(utterance);
+  }
+
+  // Model path: await onSynthesize(text) → play the Blob via an <Audio>.
+  async function speakModel() {
+    if (!props.onSynthesize || !local.text) return;
+    setIsLoading(true);
+    try {
+      const blob = await props.onSynthesize(local.text);
+      props.onSynthesized?.(blob);
+      revokeUrl();
+      objectUrl = URL.createObjectURL(blob);
+      audio ??= new Audio();
+      audio.src = objectUrl;
+      audio.onended = () => setIsSpeaking(false);
+      audio.onerror = () => setIsSpeaking(false);
+      setIsSpeaking(true);
+      await audio.play();
+    } catch {
+      setIsSpeaking(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  function speak() {
+    if (props.onSynthesize) void speakModel();
+    else speakNative();
+  }
+
+  function stop() {
+    if (props.onSynthesize) {
+      if (audio) {
+        audio.pause();
+        audio.currentTime = 0;
+      }
+    } else if (hasSpeechSynthesis()) {
+      window.speechSynthesis.cancel();
+    }
+    setIsSpeaking(false);
+  }
+
+  function pause() {
+    if (props.onSynthesize) audio?.pause();
+    else if (hasSpeechSynthesis()) window.speechSynthesis.pause();
+  }
+
+  function resume() {
+    if (props.onSynthesize) void audio?.play();
+    else if (hasSpeechSynthesis()) window.speechSynthesis.resume();
+  }
+
+  function handleClick() {
+    if (isSpeaking()) stop();
+    else speak();
+  }
+
+  // Emit speaking transitions to the host. `defer: true` skips the spurious
+  // initial `false` — only real start/stop transitions fire.
+  createEffect(on(isSpeaking, (speaking) => {
+    props.onSpeakingChange?.(speaking);
+  }, { defer: true }));
+
+  // Autoplay: speak when text first arrives / changes (defer skips the mount
+  // value so an empty seed doesn't speak).
+  createEffect(on(() => local.text, (text) => {
+    if (props.autoplay && text) speak();
+  }, { defer: true }));
+
+  props.controllerRef?.({ speak, pause, resume, stop });
+
+  onCleanup(() => {
+    stop();
+    revokeUrl();
+  });
+
+  // Speaker icon (idle)
+  const SpeakerIcon = () => (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5" />
+      <path d="M19.07 4.93a10 10 0 010 14.14M15.54 8.46a5 5 0 010 7.07" />
+    </svg>
+  );
+
+  // Square stop icon (speaking)
+  const StopIcon = () => (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">
+      <rect x="4" y="4" width="16" height="16" rx="2" />
+    </svg>
+  );
+
+  // Spinner (model synthesis in flight)
+  const Spinner = () => (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="animate-spin">
+      <path d="M21 12a9 9 0 11-6.219-8.56" />
+    </svg>
+  );
+
+  return (
+    <div class={cn('relative inline-flex items-center justify-center', local.class)}>
+      <Tooltip content={label()}>
+        <Button
+          part="button"
+          variant="ghost"
+          size="icon-sm"
+          aria-label={label()}
+          aria-pressed={isSpeaking()}
+          onClick={handleClick}
+          disabled={local.disabled || !capable() || isLoading()}
+          class={cn('relative z-10 rounded-full transition-all duration-300')}
+        >
+          <Show when={isLoading()}>
+            <Spinner />
+          </Show>
+          <Show when={!isLoading() && isSpeaking()}>
+            <StopIcon />
+          </Show>
+          <Show when={!isLoading() && !isSpeaking()}>
+            <SpeakerIcon />
+          </Show>
+        </Button>
+      </Tooltip>
+    </div>
+  );
+}

package/src/elements/agent-card.tsx

@@ -0,0 +1,67 @@
+import { defineWebComponent } from './define';
+import { AgentCard, type AgentStatus } from '../ui/agent-card';
+
+interface Props extends Record<string, unknown> {
+  /** The agent's name — the primary label. Attribute: `name`. */
+  name?: string;
+  /** Selected / focused state: highlighted border + surface. Attribute: `active`. */
+  active?: boolean;
+  /** Raise a prominent "Needs you" pill plus a glowing amber edge — the
+   *  attention-routing signal that pulls focus to this agent. Attribute:
+   *  `needs-attention`. */
+  needsAttention?: boolean;
+  /** Run status — a JS PROPERTY (object), not an attribute. Shape:
+   *  `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` |
+   *  `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an
+   *  optional short string beside the dot, and `pulse` animates the dot. Set it
+   *  with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
+  status?: AgentStatus;
+}
+
+/** Events fired by `<kai-agent-card>`. */
+interface Events {
+  /** The card was activated — clicked, or Enter / Space while focused. Promote
+   *  this agent back to focus. */
+  'kai-activate': void;
+  /** The trailing "..." kebab was clicked. The consumer opens its own menu; the
+   *  card only surfaces the affordance (the click does not also activate the card). */
+  'kai-menu': void;
+}
+
+/**
+ * `<kai-agent-card>` — the compact glanceable card for one agent in a multi-agent
+ * workspace. The agent name with a leading tone-colored status dot, an optional
+ * "Needs you" attention treatment, an `active` (selected) state, and a trailing
+ * "..." overflow button.
+ *
+ * Set `status` as a JS property (it's an object); `name` is a string attribute and
+ * `active` / `needs-attention` are boolean attributes. Listen for `kai-activate`
+ * (promote to focus) and `kai-menu` (open your own per-agent menu).
+ *
+ * ```html
+ * <kai-agent-card name="Refactor bot" active></kai-agent-card>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const card = document.querySelector('kai-agent-card');
+ *   card.status = { tone: 'working', label: 'Working', pulse: true };
+ *   card.addEventListener('kai-activate', () => focusAgent());
+ *   card.addEventListener('kai-menu', () => openMenu());
+ * </script>
+ * ```
+ * Recolor the status dot via `::part(status)` and the kebab via `::part(menu)`.
+ */
+defineWebComponent<Props, Events>('kai-agent-card', {
+  name: undefined,
+  active: undefined,
+  needsAttention: undefined,
+  status: undefined,
+}, (props, { dispatch, flag }) => (
+  <AgentCard
+    name={(props.name as string) ?? ''}
+    active={flag('active')}
+    needsAttention={flag('needsAttention')}
+    status={(props.status as AgentStatus) ?? { tone: 'idle' }}
+    onActivate={() => dispatch('kai-activate')}
+    onMenu={() => dispatch('kai-menu')}
+  />
+));

package/src/elements/artifact.tsx

@@ -1,14 +1,19 @@
 import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
-import { Artifact, type ArtifactFile, type ArtifactTab } from '../components/artifact';
+import { Artifact, type ArtifactController, type ArtifactFile, type ArtifactTab } from '../components/artifact';
 
 interface Props extends Record<string, unknown> {
   /** URL the preview iframe frames. Consumer-controlled. */
   src?: string;
   /** Files for the Code tab tree + each file's preview `url`. Set as a JS property (array). */
   files: ArtifactFile[];
-  /** Active tab: `preview` (default) or `code`. */
+  /** Controlled active tab: `preview` or `code`. When set, the artifact follows it
+   *  (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). */
   tab?: ArtifactTab;
+  /** Uncontrolled INITIAL tab (used only when `tab` is unset). Default `preview`.
+   *  Seeds the starting tab; the user can then switch freely without the consumer
+   *  re-asserting a controlled `tab`. */
+  defaultTab?: ArtifactTab;
   /** Selected file path — syncs the tree highlight, Code source, and preview. */
   activeFile?: string;
   /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
@@ -35,6 +40,11 @@ interface Props extends Record<string, unknown> {
   standalone?: boolean;
   /** Show the address but make it read-only (visible, nav-tracking, non-editable). */
   readonlyPath?: boolean;
+  /** Friendly address shown in the path field instead of the real current url
+   *  (read-only, non-navigable). Use when the framed url is not consumer-facing
+   *  (e.g. a `data:` blob) so a clean address shows instead of leaking it. Scalar
+   *  string: set as the `display-url` attribute or the `displayUrl` property. */
+  displayUrl?: string;
 }
 
 interface Events extends Record<string, unknown> {
@@ -59,7 +69,8 @@ interface Events extends Record<string, unknown> {
 defineWebComponent<Props, Events>('kai-artifact', {
   src: undefined,
   files: [],
-  tab: 'preview',
+  tab: undefined,
+  defaultTab: undefined,
   activeFile: undefined,
   sandbox: 'allow-scripts allow-forms',
   iframeTitle: undefined,
@@ -73,9 +84,44 @@ defineWebComponent<Props, Events>('kai-artifact', {
   noTabs: false,
   standalone: false,
   readonlyPath: false,
-}, (props, { element, dispatch, flag }) => {
+  displayUrl: undefined,
+}, (props, { element, dispatch, flag, expose }) => {
   const [maximized, setMaximized] = createSignal(flag('maximized'));
 
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Pattern C: the Artifact component owns the history stack + tab/file/maximize
+  // state and hands up a controller; the facade captures it and exposes delegating
+  // methods. Every internal handler still fires its event (navigate → kai-navigate;
+  // selectFile → kai-file-select; maximize/restore → kai-maximize-change). Names are
+  // collision-checked against the props: openExternal (not openInTab — a prop),
+  // maximize/restore (not maximized — a prop), navigate/selectFile (not src/activeFile
+  // — props); NO tab-switching method (tab is a prop → switch via `el.tab`).
+  let controller: ArtifactController | undefined;
+  expose({
+    /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+    back: () => controller?.back(),
+    /** Go forward in the history stack (no-op when there's no forward entry). */
+    forward: () => controller?.forward(),
+    /** Force-reload the current preview url (also re-renders an inline PDF). */
+    reload: () => controller?.reload(),
+    /** Navigate to the `src` home url (no-op when there's no `src`). */
+    home: () => controller?.home(),
+    /** Push + load a url in the preview — the path-field submit path (fires kai-navigate). */
+    navigate: (url: string) => controller?.navigate(url),
+    /** Select a file by path: highlights the tree, shows its source, navigates the
+     *  preview (fires kai-file-select + kai-navigate). Named selectFile to avoid the
+     *  `activeFile` prop. */
+    selectFile: (path: string) => controller?.selectFile(path),
+    /** Open the current url in a new browser tab (no-op when there's no concrete url).
+     *  Named openExternal, NOT openInTab — that's a prop (toolbar button visibility). */
+    openExternal: () => controller?.openExternal(),
+    /** Enter the maximized view-state (fires kai-maximize-change{maximized:true}).
+     *  Named maximize, NOT maximized — that's a prop. */
+    maximize: () => controller?.maximize(),
+    /** Exit the maximized view-state (fires kai-maximize-change{maximized:false}). */
+    restore: () => controller?.restore(),
+  });
+
   const onMaximizeChange = (next: boolean) => {
     setMaximized(next);
     // 1) The PROTOCOL intent — raw, bubbling + composed (NOT via dispatch()).
@@ -113,6 +159,7 @@ defineWebComponent<Props, Events>('kai-artifact', {
           src={props.src}
           files={props.files}
           tab={props.tab}
+          defaultTab={props.defaultTab}
           activeFile={props.activeFile}
           sandbox={props.sandbox}
           iframeTitle={props.iframeTitle}
@@ -126,10 +173,12 @@ defineWebComponent<Props, Events>('kai-artifact', {
           showTabs={!flag('noTabs')}
           standalone={flag('standalone')}
           readonlyPath={flag('readonlyPath')}
+          displayUrl={props.displayUrl}
           onMaximizeChange={onMaximizeChange}
           onNavigate={(url) => dispatch('kai-navigate', { url })}
           onTabChange={(tab) => dispatch('kai-tab-change', { tab })}
           onFileSelect={(path) => dispatch('kai-file-select', { path })}
+          controllerRef={(c) => (controller = c)}
         />
       </div>
     </>

package/src/elements/attachments.tsx

@@ -118,6 +118,7 @@ defineWebComponent<Props, Events>('kai-attachments', {
                       }
                     >
                       <img
+                        part="preview"
                         src={item.url}
                         alt={getAttachmentLabel(item)}
                         class="block max-h-64 max-w-xs rounded object-contain"

package/src/elements/avatar.tsx

@@ -0,0 +1,33 @@
+import { Avatar } from '../ui/avatar';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Image URL/data-URI. When absent, the `fallback` initials show instead. */
+  src?: string;
+  /** Alt text for the image. Defaults to `fallback`. */
+  alt?: string;
+  /** Short text shown when there's no image — usually initials (e.g. "JD", "AI"). */
+  fallback?: string;
+  /** Size token: `sm` | `md` (default) | `lg`. */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * `<kai-avatar>` — a person/entity avatar: a rounded image that falls back to
+ * initials when there's no `src`. This is an *identity* badge (the thing next to
+ * a message or in a conversation list), not a generic icon — for a glyph, use an
+ * `icon` prop on another element.
+ *
+ * ```html
+ * <kai-avatar src="/me.jpg" fallback="JD"></kai-avatar>
+ * <kai-avatar fallback="AI" size="sm"></kai-avatar>
+ * ```
+ */
+defineWebComponent<Props>('kai-avatar', {
+  src: undefined,
+  alt: undefined,
+  fallback: '',
+  size: 'md',
+}, (props) => (
+  <Avatar src={props.src} alt={props.alt} fallback={props.fallback ?? ''} size={props.size ?? 'md'} />
+));

package/src/elements/badge.tsx

@@ -0,0 +1,32 @@
+import { Badge } from '../ui/badge';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** `default` (muted pill) · `count` (compact number badge) · `citation`
+   *  (filled primary, for inline citation markers). Defaults to `default`. */
+  variant?: 'default' | 'count' | 'citation';
+}
+
+/**
+ * `<kai-badge>` — a small pill for labels, status, counts, or citation markers.
+ * Put the content as light-DOM text.
+ *
+ * ```html
+ * <kai-badge>Beta</kai-badge>
+ * <kai-badge variant="count">3</kai-badge>
+ * <kai-badge variant="citation">1</kai-badge>
+ * ```
+ * Restyle via `::part(badge)`.
+ */
+defineWebComponent<Props>('kai-badge', {
+  variant: 'default',
+}, (props) => (
+  <>
+    {/* Base sets `:host{display:block}`; a badge/pill flows inline with text and
+        beside sibling badges, so inline-flex like kai-button. */}
+    <style>{':host{display:inline-flex}'}</style>
+    <Badge variant={props.variant ?? 'default'} part="badge">
+      <slot />
+    </Badge>
+  </>
+));

package/src/elements/button.tsx

@@ -0,0 +1,126 @@
+import { Show } from 'solid-js';
+import { Button } from '../ui/button';
+import { renderIcon } from '../ui/icon';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Visual style. `default` (filled), `subtle` (muted text, hover tint — the
+   *  toolbar icon look), `ghost` (transparent, hover fill), `outline`, or
+   *  `destructive`. Defaults to `default`. */
+  variant?: 'default' | 'subtle' | 'ghost' | 'outline' | 'destructive';
+  /** Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` /
+   *  `md` / `lg` size text buttons. Defaults to `md`. */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI,
+   *  or plain text. Renders before any slotted label. */
+  icon?: string;
+  /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
+  iconTrailing?: string;
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored
+   *  when you slot visible text, which already names the button. */
+  label?: string;
+  /** Disable the button (non-interactive, dimmed). */
+  disabled?: boolean;
+  /** Stretch the button to the full width of its container (a block button) —
+   *  e.g. a card CTA or a stacked action. Attribute: `full`. */
+  full?: boolean;
+  /** Justify the button's content: `start`, `center` (default), or `end`.
+   *  Combine with `full` for a full-width, left-aligned button. */
+  align?: 'start' | 'center' | 'end';
+  /** Native button `type`. Defaults to `button` (so it never submits a form). */
+  type?: 'button' | 'submit' | 'reset';
+}
+
+/** Events fired by `<kai-button>`. */
+interface Events {
+  /** The button was activated (pointer or keyboard). Carries no detail. The
+   *  native `click` also bubbles (composed) for consumers who prefer it. */
+  'kai-click': void;
+}
+
+/**
+ * `<kai-button>` — the kit's button as a drop-in element, so consumers compose
+ * polished, theme-aware controls instead of hand-rolling `<button>` + inline
+ * hover styles. Put the label as light-DOM text; use `icon` for a leading glyph
+ * and `label` to name an icon-only button.
+ *
+ * ```html
+ * <kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
+ * <kai-button variant="ghost" icon-trailing="chevron-down">High</kai-button>
+ * <kai-button>Send</kai-button>
+ * <kai-button label="Ship"><svg slot="icon" viewBox="0 0 24 24">…</svg></kai-button>
+ * ```
+ *
+ * The `icon` prop renders a curated/URL icon; for anything else, slot your own
+ * inline SVG via `slot="icon"` (it wins over `icon`). Restyle via `::part(button)`.
+ * Emits `kai-click`.
+ */
+defineWebComponent<Props, Events>('kai-button', {
+  variant: 'default',
+  size: 'md',
+  icon: undefined,
+  iconTrailing: undefined,
+  label: undefined,
+  disabled: false,
+  full: false,
+  align: 'center',
+  type: 'button',
+}, (props, { dispatch, flag, element, expose }) => {
+  // `icon` / `icon-sm` are square, icon-ONLY sizes: suppress the text label and
+  // trailing icon so a stray label doesn't get cramped into the square (the
+  // `label` prop still names it for assistive tech).
+  const iconOnly = () => props.size === 'icon' || props.size === 'icon-sm';
+
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // The real <button> lives in the shadow root, so native focus()/blur()/click()
+  // on the host hit the wrapper, not the control. Forward to the inner button.
+  // These shadow the inherited HTMLElement methods — intended; expose() uses
+  // defineProperty so the override sticks. No collision with the props above.
+  expose({
+    /** Focus the inner `<button>` (host.focus() would focus the wrapper). */
+    focus: (options?: FocusOptions) =>
+      element.shadowRoot?.querySelector('button')?.focus(options),
+    /** Blur the inner `<button>`. */
+    blur: () => element.shadowRoot?.querySelector('button')?.blur(),
+    /** Programmatically activate the button — runs the same path as a user
+     *  click and fires kai-click. Forwarding to the inner button means
+     *  `disabled` is respected automatically. */
+    click: () => element.shadowRoot?.querySelector('button')?.click(),
+  });
+  return (
+    <>
+      {/* The host shrinks to the label by default (inline-flex), so a text button
+          is only as wide as its content — until a parent stretches it. A text
+          button's inner control is w-full, so when the host IS stretched (a flex
+          column with items-stretch, e.g. a card's collapsed footer, or an explicit
+          `full`) the button fills it. `full` forces that standalone (a block CTA).
+          Icon buttons stay square (no w-full). */}
+      <style>{':host{display:inline-flex}:host([full]){display:block}'}</style>
+    <Button
+      part="button"
+      variant={props.variant ?? 'default'}
+      size={props.size ?? 'md'}
+      align={props.align ?? 'center'}
+      full={flag('full') || !iconOnly()}
+      type={props.type ?? 'button'}
+      disabled={flag('disabled')}
+      aria-label={props.label}
+      onClick={() => dispatch('kai-click')}
+    >
+      {/* Leading icon: a slotted SVG (slot="icon") wins — drop in any icon
+          library or your own; otherwise the `icon` prop renders a curated/URL one. */}
+      <slot name="icon">
+        <Show when={props.icon}>
+          {renderIcon(props.icon, { class: 'size-4 shrink-0', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
+        </Show>
+      </slot>
+      <Show when={!iconOnly()}>
+        <slot />
+      </Show>
+      <Show when={props.iconTrailing && !iconOnly()}>
+        {renderIcon(props.iconTrailing, { class: 'size-4 shrink-0 opacity-60', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
+      </Show>
+    </Button>
+    </>
+  );
+});