@kitn.ai/ui 0.28.0 → 0.29.0

package/src/elements/tooltip.tsx

@@ -1,85 +0,0 @@
-import { type Placement } from '@floating-ui/dom';
-import { Tooltip, type TooltipController } from '../ui/tooltip';
-import { defineWebComponent } from './define';
-import { wireDisclosure } from './disclosure';
-
-interface Props extends Record<string, unknown> {
-  /** The hint text shown on hover/focus of the slotted trigger. */
-  content?: string;
-  /** Delay (ms) before the tooltip appears on hover. Defaults to 600. Focus
-   *  shows it immediately regardless. */
-  openDelay?: number;
-  /** Delay (ms) before it hides after the pointer leaves. Defaults to 0 (hides
-   *  immediately). */
-  closeDelay?: number;
-  /** Preferred placement: `'top' | 'bottom' | 'left' | 'right'` (+ optional
-   *  `-start`/`-end`). Defaults to `'top'`; flips to stay in view. */
-  placement?: string;
-  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
-   *  attribute, the element still self-manages on hover/focus). Set `el.open = true`,
-   *  or `<kai-tooltip open>`; listen for `kai-open-change`. */
-  open?: boolean;
-  /** Initial open state on mount (uncontrolled seed). */
-  defaultOpen?: boolean;
-  /** Turn the tooltip off while keeping the trigger mounted (hover/focus and
-   *  `show()` no longer open it). */
-  disabled?: boolean;
-}
-
-/** Events fired by `<kai-tooltip>`. */
-interface Events {
-  /** The tooltip opened or closed (by hover/focus, outside-click, or a method). */
-  'kai-open-change': { open: boolean };
-}
-
-/**
- * `<kai-tooltip>` — wraps a trigger and shows a hint on hover/focus. Put the
- * trigger as light-DOM content; set the text via `content`. Positions itself and
- * dismisses on Escape/outside-click; the content is portaled inside the shadow
- * root so it isn't clipped.
- *
- * ```html
- * <kai-tooltip content="Voice input">
- *   <kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
- * </kai-tooltip>
- * ```
- */
-defineWebComponent<Props, Events>('kai-tooltip', {
-  content: '',
-  openDelay: undefined,
-  closeDelay: undefined,
-  placement: undefined,
-  open: undefined,
-  defaultOpen: undefined,
-  disabled: undefined,
-}, (props, ctx) => {
-  const { flag } = ctx;
-  let api: TooltipController | undefined;
-
-  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
-  // show/hide/toggle, disabled-gating. See ./disclosure.
-  wireDisclosure(ctx, () => api, () => props.open);
-
-  return (
-    <>
-      {/* The shared element base sets `:host{display:block}` (styles.css). A block
-          host wraps the inline-flex trigger in a line box, so the font-descender
-          strut makes the host taller than the control and pins the control to the
-          top, so it reads off-center beside non-tooltipped siblings in a
-          flex-items-center row. inline-flex (like kai-button) drops the line box so
-          the host hugs the trigger and their centers line up. */}
-      <style>{':host{display:inline-flex}'}</style>
-      <Tooltip
-        content={props.content ?? ''}
-        openDelay={props.openDelay != null ? Number(props.openDelay) : undefined}
-        closeDelay={props.closeDelay != null ? Number(props.closeDelay) : undefined}
-        placement={(props.placement as Placement | undefined) ?? undefined}
-        defaultOpen={flag('defaultOpen')}
-        disabled={flag('disabled')}
-        controllerRef={(a) => (api = a)}
-      >
-        <slot />
-      </Tooltip>
-    </>
-  );
-});

package/src/elements/validate-messages.ts

@@ -1,76 +0,0 @@
-import type { ChatMessage } from './chat-types';
-
-/**
- * Boundary validation for the untyped `message` / `messages` properties.
- *
- * A web component's properties are an untyped boundary: nothing stops a consumer
- * from assigning the pre-0.20.0 `{ id, role, content }` shape, and TypeScript is
- * not there at runtime to catch it. `parts` is REQUIRED internally, so a message
- * without one throws inside a Solid render pass (`groupMessageParts` iterating
- * `undefined`), and an uncaught exception there blanks the WHOLE element, not
- * just the offending message. Validating here turns that into a skipped message
- * plus one clear console error naming the element and the expected shape.
- */
-
-/** True when `m` carries the required `parts` array. */
-export function hasParts(m: unknown): m is ChatMessage {
-  return !!m && typeof m === 'object' && Array.isArray((m as { parts?: unknown }).parts);
-}
-
-/** Shared tail of every diagnostic, so all facades say the same thing. */
-const EXPECTED =
-  "each entry needs a 'parts' array (e.g. parts: [{ type: 'text', text: 'Hi' }]). " +
-  "The 'content' string field was removed in 0.20.0.";
-
-const EMPTY: ChatMessage[] = [];
-
-/**
- * Creates a per-element-instance validator for a `messages` array. Returns the
- * INPUT array unchanged when every entry is valid (no allocation, so streaming
- * identity checks upstream still hold), a filtered copy when some are not, and
- * `[]` when the property itself is not an array.
- *
- * Logs at most one `console.error` per validation pass, and never re-logs for a
- * message object it has already reported, so an unrelated re-render during
- * streaming does not spam the console.
- */
-export function createMessagesGuard(tag: string): (messages: unknown) => ChatMessage[] {
-  const warned = new WeakSet<object>();
-  // WeakSet only holds objects, so primitive entries (a stray string/null in the
-  // array) get one shared latch instead.
-  let warnedPrimitive = false;
-  let warnedNonArray = false;
-
-  return (messages: unknown): ChatMessage[] => {
-    if (!Array.isArray(messages)) {
-      if (messages != null && !warnedNonArray) {
-        warnedNonArray = true;
-        console.error(`<${tag}>: 'messages' must be an array. Ignoring it.`);
-      }
-      return EMPTY;
-    }
-    // Fast path: nothing to report, hand back the same reference.
-    if (messages.every(hasParts)) return messages as ChatMessage[];
-
-    let invalid = 0;
-    let unreported = 0;
-    for (const m of messages) {
-      if (hasParts(m)) continue;
-      invalid++;
-      if (m !== null && typeof m === 'object') {
-        if (warned.has(m as object)) continue;
-        warned.add(m as object);
-      } else {
-        if (warnedPrimitive) continue;
-        warnedPrimitive = true;
-      }
-      unreported++;
-    }
-    if (unreported > 0) {
-      console.error(
-        `<${tag}>: skipped ${invalid} of ${messages.length} messages: ${EXPECTED}`,
-      );
-    }
-    return messages.filter(hasParts);
-  };
-}

package/src/elements/voice-input.tsx

@@ -1,100 +0,0 @@
-import { defineWebComponent } from './define';
-import { VoiceInput, type VoiceInputController } from '../components/voice-input';
-
-interface Props extends Record<string, unknown> {
-  /**
-   * Transcriber the host supplies: records audio, returns the text. This is a
-   * **function-valued property** (`el.transcribe = async blob => '...'`) because
-   * a value-returning callback can't be modelled as a fire-and-forget event.
-   */
-  transcribe?: (audio: Blob) => Promise<string>;
-  /** Disable the mic button (non-interactive). */
-  disabled?: boolean;
-  /**
-   * BCP-47 language tag for the native `SpeechRecognition` path (e.g. `en-US`).
-   * Attribute: `recognition-lang` (the plain `lang` attribute is reserved by
-   * `HTMLElement` and can't be a custom-element property). No effect when
-   * `transcribe` is set or the browser lacks SpeechRecognition.
-   */
-  recognitionLang?: string;
-  /** Emit live partial transcripts (`kai-transcript-interim`) during native
-   *  recognition. Attribute: `interim`. No-op on the transcribe/fallback paths. */
-  interim?: boolean;
-}
-
-/** Events fired by `<kai-voice-input>`. */
-interface Events {
-  /** Raw audio captured (before transcription), for hosts that prefer to handle
-   *  transcription themselves instead of via the `transcribe` property. Also the
-   *  unsupported-fallback signal: no `transcribe`, no SpeechRecognition, so only
-   *  the blob is produced (no text). */
-  'kai-audio-captured': { blob: Blob };
-  /** Final transcript: the `transcribe` property resolved, OR native
-   *  `SpeechRecognition` produced final text (no `transcribe` set). */
-  'kai-transcription': { text: string };
-  /** Live partial transcript during native recognition (only when `interim` is
-   *  set). Fires repeatedly before the final `kai-transcription`. */
-  'kai-transcript-interim': { text: string };
-  /** Recording started or stopped. Lets the host drive its own UI (waveform,
-   *  push-to-talk indicator) in sync with the mic. Fires on real transitions
-   *  only (manual click and programmatic start()/stop()), never on mount. */
-  'kai-recording-change': { recording: boolean };
-  /** A voice session failed, so no failure is ever silent. `detail.source` names
-   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
-   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
-   *  thrown exception's name, or `no-result` when recognition ended with no error
-   *  and no text (the user said nothing), and `detail.message` is human-readable.
-   *  Deliberate cancellation does not fire. */
-  'kai-voice-error': { source: 'recognition'; error: string; message: string };
-}
-
-/**
- * `<kai-voice-input>` — a mic button that records and transcribes. Works
- * natively by default: with no `transcribe` callback it uses the browser's
- * `SpeechRecognition` (Chrome/Safari; no Firefox — and cloud-based in Chrome).
- * Set `el.transcribe` to route audio through your own async transcriber instead.
- * Where neither is available it records the blob and emits `kai-audio-captured`
- * with no text. Also emits `kai-transcription` (final text), `kai-voice-error`
- * (a failed or empty session) and, with `interim`, `kai-transcript-interim`
- * (live partials).
- */
-defineWebComponent<Props, Events>('kai-voice-input', {
-  transcribe: undefined,
-  disabled: false,
-  recognitionLang: undefined,
-  interim: false,
-}, (props, { dispatch, flag, expose }) => {
-  // Pattern C: the VoiceInput component owns useVoiceRecorder; it hands up a
-  // start/stop controller and an onRecordingChange callback. The facade captures
-  // the controller and exposes delegating methods (start/stop both run the same
-  // record→transcribe path as the mic click, so manual + programmatic emit the
-  // same kai-audio-captured/kai-transcription/kai-recording-change events).
-  let controller: VoiceInputController | undefined;
-  expose({
-    /** Begin recording programmatically (e.g. push-to-talk bound to a global
-     *  key). Runs the same getUserMedia path as clicking the mic; no-ops if
-     *  already recording. */
-    start: () => controller?.start(),
-    /** Stop the in-progress recording, producing the blob (→ kai-audio-captured)
-     *  and running transcription. Pairs with start() for push-to-talk. */
-    stop: () => controller?.stop(),
-  });
-
-  return (
-    <VoiceInput
-      disabled={flag('disabled')}
-      hasTranscribe={typeof props.transcribe === 'function'}
-      lang={props.recognitionLang}
-      interim={flag('interim')}
-      onTranscribe={async (blob) => {
-        dispatch('kai-audio-captured', { blob });
-        return props.transcribe ? props.transcribe(blob) : '';
-      }}
-      onTranscription={(text) => dispatch('kai-transcription', { text })}
-      onInterim={(text) => dispatch('kai-transcript-interim', { text })}
-      onRecordingChange={(recording) => dispatch('kai-recording-change', { recording })}
-      onError={(detail) => dispatch('kai-voice-error', detail)}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-});

package/src/elements/voice-output.tsx

@@ -1,82 +0,0 @@
-import { defineWebComponent } from './define';
-import { VoiceOutput, type VoiceOutputController } from '../components/voice-output';
-
-interface Props extends Record<string, unknown> {
-  /** The utterance to read aloud. */
-  text?: string;
-  /** Speak automatically when `text` is set/changed. */
-  autoplay?: boolean;
-  /**
-   * TTS model seam the host supplies: given text, returns an audio `Blob` to
-   * play. This is a **function-valued property** (`el.synthesize = async text =>
-   * blob`); when set, the native `speechSynthesis` path is bypassed. Mirrors
-   * `<kai-voice-input>`'s `transcribe`. A value-returning callback can't be
-   * modelled as a fire-and-forget event, hence a property.
-   */
-  synthesize?: (text: string) => Promise<Blob>;
-  /** Disable the button (non-interactive). */
-  disabled?: boolean;
-}
-
-/** Events fired by `<kai-voice-output>`. */
-interface Events {
-  /** Playback started or stopped. Drive your own UI in sync. `speaking: true`
-   *  fires when audio actually starts (utterance.onstart natively; audio playback
-   *  beginning on the `synthesize` path), not when speak() is called; earlier
-   *  releases fired it optimistically inside speak() itself. Fires on real
-   *  transitions only (manual click and programmatic speak()/stop()), never on
-   *  mount. */
-  'kai-speaking-change': { speaking: boolean };
-  /** The model path (`synthesize`) resolved audio: the raw `Blob` before playback. */
-  'kai-synthesized': { blob: Blob };
-  /** A voice session failed, so no failure is ever silent. `detail.source` names
-   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
-   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
-   *  thrown exception's name, or `no-result` when recognition ended with no error
-   *  and no text (the user said nothing), and `detail.message` is human-readable.
-   *  Deliberate cancellation does not fire. */
-  'kai-voice-error': { source: 'synthesis'; error: string; message: string };
-}
-
-/**
- * `<kai-voice-output>` — a speaker button that reads `text` aloud. Native by
- * default (`speechSynthesis`); set `el.synthesize` to route through your TTS
- * model instead. The output sibling of `<kai-voice-input>`. Emits
- * `kai-speaking-change`, `kai-voice-error` (a failed synthesis) and (model
- * path) `kai-synthesized`.
- */
-defineWebComponent<Props, Events>('kai-voice-output', {
-  text: '',
-  autoplay: false,
-  synthesize: undefined,
-  disabled: false,
-}, (props, { dispatch, flag, expose }) => {
-  // Pattern C: the VoiceOutput component owns playback; it hands up a
-  // speak/pause/resume/stop controller. The facade captures it and exposes
-  // delegating methods (manual + programmatic run the same path, so both emit
-  // the same kai-speaking-change / kai-synthesized events).
-  let controller: VoiceOutputController | undefined;
-  expose({
-    /** Speak the current `text` (native, or via `synthesize` if set). */
-    speak: () => controller?.speak(),
-    /** Pause playback (resumable). */
-    pause: () => controller?.pause(),
-    /** Resume paused playback. */
-    resume: () => controller?.resume(),
-    /** Stop playback and reset. */
-    stop: () => controller?.stop(),
-  });
-
-  return (
-    <VoiceOutput
-      text={(props.text as string | undefined) ?? ''}
-      autoplay={flag('autoplay')}
-      disabled={flag('disabled')}
-      onSynthesize={props.synthesize ? (text) => props.synthesize!(text) : undefined}
-      onSpeakingChange={(speaking) => dispatch('kai-speaking-change', { speaking })}
-      onSynthesized={(blob) => dispatch('kai-synthesized', { blob })}
-      onError={(detail) => dispatch('kai-voice-error', detail)}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-});