@kitn.ai/ui 0.16.0 → 0.18.0

package/src/components/choice-card.tsx

@@ -8,6 +8,7 @@ import {
   createMemo,
   createEffect,
   on,
+  onMount,
   ErrorBoundary,
   createUniqueId,
 } from 'solid-js';
@@ -15,11 +16,12 @@ import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { HoverCard } from '../ui/hover-card';
 import { Card } from './card';
+import { DismissedStub } from './dismissed-stub';
 import type { CardEnvelope, CardEvent, CardHost, CardResolution } from '../primitives/card-contract';
 import { useCardResolution } from './use-card-resolution';
 import { emitCardEvent } from '../primitives/card-routing';
 import { useCardHost } from '../primitives/card-host';
-import { Check } from 'lucide-solid';
+import { Check, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (choice.schema.json) — see src/primitives/card-schemas/choice.schema.json
@@ -49,6 +51,7 @@ export interface ChoiceCardData {
   options: ChoiceOption[]; // 1..N
   allowOther?: ChoiceAllowOther; // free-text escape
   submitLabel?: string; // label for the Submit button (default 'Submit')
+  dismissible?: boolean; // show a close affordance that emits `dismiss`
 }
 
 export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
@@ -149,6 +152,22 @@ export function firstEnabledIndex(options: ChoiceOption[]): number {
 // The <ChoiceCard> component.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Imperative handle exposed via `controllerRef` — surfaces the choice card's
+ *  latent selection/submit/dismiss capabilities so the `<kai-choice>` facade can
+ *  forward them as instance methods (focus/select/send/dismiss/reopen). */
+export interface ChoiceController {
+  /** Focus the radiogroup roving tab stop (or the Other input when selected). */
+  focus(options?: FocusOptions): void;
+  /** Select an option by id locally (no emit) — same as a row click. */
+  select(optionId: string): void;
+  /** Submit the current selection — emits the `action` verb + resolves single-shot. */
+  send(): void;
+  /** Dismiss the card — emits `dismiss` + optimistically collapses to the stub. */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub — emits `reopen`. */
+  reopen(): void;
+}
+
 export interface ChoiceCardProps {
   /** The choice definition (CardEnvelope.data). */
   data?: ChoiceCardData;
@@ -164,6 +183,17 @@ export interface ChoiceCardProps {
   class?: string;
   /** When set, render the chromed read-only view instead of the interactive radiogroup. */
   resolution?: CardResolution;
+  /** Controlled selection (option id). When set, the consumer owns the current pick. */
+  value?: string;
+  /** Option id to pre-select on mount (uncontrolled seed). */
+  defaultValue?: string;
+  /** Disable the whole radiogroup + Submit (e.g. while the agent is busy). */
+  disabled?: boolean;
+  /** Fires when the selection changes BEFORE submit (row click or select()). */
+  onValueChange?: (value: string) => void;
+  /** Receive the imperative controller once mounted. The `<kai-choice>` facade
+   *  forwards these as element methods (focus/select/send/dismiss/reopen). */
+  controllerRef?: (controller: ChoiceController) => void;
 }
 
 /**
@@ -180,7 +210,20 @@ export interface ChoiceCardProps {
  */
 export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   const merged = mergeProps({ cardId: 'kai-choice' }, props);
-  const [local] = splitProps(merged, ['data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution']);
+  const [local] = splitProps(merged, [
+    'data',
+    'cardId',
+    'heading',
+    'host',
+    'hostElement',
+    'class',
+    'resolution',
+    'value',
+    'defaultValue',
+    'disabled',
+    'onValueChange',
+    'controllerRef',
+  ]);
 
   const ctxHost = useCardHost();
   const uid = createUniqueId();
@@ -212,20 +255,33 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   });
 
   const [focusIndex, setFocusIndex] = createSignal(0);
-  const [selectedId, setSelectedId] = createSignal<string | undefined>(undefined);
+  // Uncontrolled selection store, seeded from `defaultValue`. When the consumer
+  // sets the `value` prop the controlled path wins (same pattern as the composer):
+  // `selectedId()` reads value ?? internal, and `setSelection()` writes the
+  // internal store + fires onValueChange so a controlled host can mirror it.
+  const [internalId, setInternalId] = createSignal<string | undefined>(props.defaultValue);
+  const selectedId = createMemo<string | undefined>(() => local.value ?? internalId());
+  const setSelection = (id: string): void => {
+    if (selectedId() === id) return;
+    setInternalId(id);
+    local.onValueChange?.(id);
+  };
   const [otherText, setOtherText] = createSignal('');
 
+  const isDisabled = (): boolean => local.disabled === true;
+
   let groupRef: HTMLDivElement | undefined;
   let otherInputRef: HTMLInputElement | undefined;
 
   const otherSelected = createMemo(() => selectedId() === OTHER_ACTION);
 
-  // Reset all transient state whenever a NEW definition arrives.
+  // Reset all transient state whenever a NEW definition arrives (re-seed the
+  // uncontrolled selection from `defaultValue`).
   createEffect(
     on(
       () => local.data,
       () => {
-        setSelectedId(undefined);
+        setInternalId(local.defaultValue);
         setOtherText('');
         setFocusIndex(Math.max(0, firstEnabledIndex(options())));
       },
@@ -262,11 +318,12 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
 
   const isOther = (opt: ChoiceOption): boolean => opt.id === OTHER_ACTION;
 
-  // Select (do NOT emit) the given option locally.
+  // Select (do NOT emit) the given option locally; fires onValueChange.
   const select = (opt: ChoiceOption): void => {
     if (res.isResolved()) return; // single-shot
+    if (isDisabled()) return; // group-level freeze
     if (opt.disabled) return;
-    setSelectedId(opt.id);
+    setSelection(opt.id);
     if (isOther(opt)) {
       queueMicrotask(() => otherInputRef?.focus());
     }
@@ -275,6 +332,7 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   // Whether the current selection is submittable.
   const canSubmit = createMemo(() => {
     if (res.isResolved()) return false;
+    if (isDisabled()) return false; // group-level freeze
     const id = selectedId();
     if (id === undefined) return false;
     if (id === OTHER_ACTION) return otherText().trim().length > 0;
@@ -286,6 +344,7 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   // Submit the current selection: emit `action` then resolve (single-shot).
   const submit = (): void => {
     if (res.isResolved()) return;
+    if (isDisabled()) return; // group-level freeze
     const id = selectedId();
     if (id === undefined) return;
     if (id === OTHER_ACTION) {
@@ -310,13 +369,52 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
     });
   };
 
-  const focusRadio = (index: number): void => {
+  // Dismiss: emit `dismiss` AND optimistically flip to a `dismissed` resolution so
+  // the card collapses to its re-openable stub immediately.
+  const onDismiss = (): void => {
+    if (res.isResolved()) return;
+    emit({ kind: 'dismiss', cardId: local.cardId });
+    res.setLocal({ kind: 'dismissed' });
+  };
+  const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
+
+  const focusRadio = (index: number, options?: FocusOptions): void => {
     const radios = groupRef?.querySelectorAll<HTMLElement>('[role="radio"]');
-    radios?.[index]?.focus();
+    radios?.[index]?.focus(options);
   };
 
+  // ── Imperative controller (Pattern C): hand the facade a handle over the
+  //    card's latent selection/submit/dismiss capabilities. Every method drives
+  //    the SAME internal path the buttons/keyboard drive, so the same kai-card
+  //    events fire (and onValueChange for select()). ─────────────────────────────
+  onMount(() => {
+    local.controllerRef?.({
+      // Focus the roving radiogroup tab stop, or the Other input when it's selected.
+      focus: (options) => {
+        if (otherSelected() && otherInputRef) otherInputRef.focus(options);
+        else focusRadio(focusIndex(), options);
+      },
+      // Select an option by id locally (no emit) — same as a row click; respects
+      // disabled/resolved gating and moves the roving focus to the picked row.
+      select: (optionId) => {
+        const opts = options();
+        const idx = opts.findIndex((o) => o.id === optionId);
+        if (idx === -1) return;
+        setFocusIndex(idx);
+        select(opts[idx]);
+      },
+      // Submit the current selection (the Submit-button path).
+      send: () => submit(),
+      // Trigger the dismiss path (the X-button path).
+      dismiss: () => onDismiss(),
+      // Re-open a dismissed card (the stub's affordance path).
+      reopen: () => onReopen(),
+    });
+  });
+
   const onGroupKeyDown = (e: KeyboardEvent): void => {
     if (res.isResolved()) return;
+    if (isDisabled()) return; // group-level freeze
     const opts = options();
     const i = focusIndex();
     if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
@@ -353,6 +451,10 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
           return <Card heading={local.heading} errorMessage="The card failed to render." />;
         }}
       >
+        <Show
+          when={!res.isDeferred()}
+          fallback={<DismissedStub type={CHOICE_CARD_TYPE} title={local.heading} onReopen={onReopen} />}
+        >
         <Card heading={local.heading}>
           <div class={cn('flex flex-col gap-3', local.class)}>
             <Show when={local.data?.prompt}>
@@ -370,14 +472,18 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                 role="radiogroup"
                 aria-label={groupLabel()}
                 aria-describedby={local.data?.prompt ? promptId : undefined}
-                class="divide-y divide-border overflow-hidden rounded-lg border border-input"
+                aria-disabled={isDisabled() ? 'true' : undefined}
+                class={cn(
+                  'divide-y divide-border overflow-hidden rounded-lg border border-input',
+                  isDisabled() && 'cursor-not-allowed opacity-60',
+                )}
                 onKeyDown={onGroupKeyDown}
               >
                 <For each={options()}>
                   {(opt, index) => {
                     const checked = () => selectedId() === opt.id;
                     const tabStop = () =>
-                      !opt.disabled && index() === focusIndex() && !res.isResolved();
+                      !opt.disabled && !isDisabled() && index() === focusIndex() && !res.isResolved();
                     const descId = `kai-choice-desc-${uid}-${opt.id}`;
                     const hasDesc = () => Boolean(opt.description);
                     return (
@@ -407,7 +513,8 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                     id={otherInputId}
                     ref={otherInputRef}
                     type="text"
-                    class="w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    disabled={isDisabled()}
+                    class="w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-60"
                     placeholder={otherCfg()?.placeholder}
                     value={otherText()}
                     onInput={(e) => setOtherText(e.currentTarget.value)}
@@ -421,12 +528,26 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                 </div>
               </Show>
 
-              <Button type="button" class="self-end" disabled={!canSubmit()} onClick={submit}>
-                {submitLabel()}
-              </Button>
+              <div class="flex w-full flex-wrap items-center justify-between gap-2">
+                <Show when={local.data?.dismissible === true}>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label="Dismiss"
+                    onClick={onDismiss}
+                  >
+                    <X size={16} aria-hidden="true" />
+                  </Button>
+                </Show>
+                <Button type="button" class="ml-auto" disabled={!canSubmit()} onClick={submit}>
+                  {submitLabel()}
+                </Button>
+              </div>
             </Show>
           </div>
         </Card>
+        </Show>
       </ErrorBoundary>
     </Show>
   );

package/src/components/coachmark.tsx

@@ -0,0 +1,245 @@
+import { createSignal, createUniqueId, createEffect, onCleanup, Show, type Accessor, type JSX } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { X } from 'lucide-solid';
+import type { Placement } from '@floating-ui/dom';
+import { cn } from '../utils/cn';
+import { useChatConfig } from '../primitives/chat-config';
+import { createPresence, usePosition } from '../ui/overlay';
+
+/** Imperative open controller, handed to the kai-coachmark facade via
+ *  `controllerRef` so it can drive/observe open state with `wireDisclosure`. */
+export interface CoachmarkController {
+  open: Accessor<boolean>;
+  setOpen: (v: boolean) => void;
+}
+
+export interface CoachmarkProps {
+  /** The anchor/trigger (the default slot). The bubble is positioned against it. */
+  children?: JSX.Element;
+  /** The bubble body text (the `content` slot). */
+  content?: JSX.Element;
+  /** The bold title. NOT `title` — that is a reserved IDL attr (see define.tsx). */
+  headline?: JSX.Element;
+  /** A small badge pill (e.g. "New"). */
+  badge?: JSX.Element;
+  /** Floating placement relative to the anchor. Defaults to `'bottom'`. */
+  placement?: Placement;
+  /** Color tone: `primary` (default, theme accent), `info` (blue), `success`
+   *  (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
+  tone?: 'primary' | 'info' | 'success' | 'warning' | 'error';
+  /** Controlled open state. When set, the component never changes it itself;
+   *  drive it from `onOpenChange`. Omit for uncontrolled (internal) state. */
+  open?: boolean;
+  /** Initial open state when uncontrolled. */
+  defaultOpen?: boolean;
+  /** Fires whenever open wants to change (the × button / a method). */
+  onOpenChange?: (open: boolean) => void;
+  /** Dismiss intent: the × button. */
+  onDismiss?: () => void;
+  /** Render the arrow that points at the anchor. Defaults to `true`; set `false`
+   *  for a plain bubble with no pointer. */
+  arrow?: boolean;
+  /** Receive the open controller once mounted. */
+  controllerRef?: (api: CoachmarkController) => void;
+}
+
+/** Map a (post flip/shift) placement side to the bubble edge the arrow sits on. */
+const STATIC_SIDE: Record<string, 'top' | 'bottom' | 'left' | 'right'> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+};
+
+/** DEFAULT bubble colors per `tone`. `info` is the blue onboarding look (white
+ *  text). These seed the `--kai-coachmark-bg` / `--kai-coachmark-fg` custom
+ *  properties. A consumer can override those in CSS (e.g. `kai-coachmark {
+ *  --kai-coachmark-bg: var(--color-tool-blue) }`) to recolor the bubble, arrow,
+ *  and text in one place, persistently, without touching `tone`. */
+const TONE_DEFAULTS = {
+  primary: { bg: 'var(--color-primary)', fg: 'var(--color-primary-foreground)' },
+  info: { bg: 'var(--color-tool-blue)', fg: '#fff' },
+  success: { bg: 'var(--color-tool-green)', fg: '#fff' },
+  // Amber is light, so it carries a fixed dark foreground for contrast (a theme
+  // var would flip to white in dark mode and fail against the amber).
+  warning: { bg: 'var(--color-tool-amber)', fg: '#1a1a1a' },
+  error: { bg: 'var(--color-tool-red)', fg: '#fff' },
+} as const;
+
+// The dismiss/badge/content sub-elements derive from the bubble's foreground via
+// `currentColor` (which inherits the resolved `--kai-coachmark-fg`), so they
+// follow the tone default OR any CSS override automatically (no per-tone class).
+const DISMISS_CLS = 'text-current/70 hover:bg-current/15 hover:text-current';
+const BADGE_CLS = 'bg-current/20';
+const CONTENT_CLS = 'text-current/85';
+
+/**
+ * Coachmark is the presentational onboarding hint: a tinted bubble with an arrow,
+ * anchored to a trigger. It wraps the anchor (the default slot) and positions the
+ * bubble against it with `usePosition` (the shared Floating UI primitive) so the
+ * arrow tracks the anchor on scroll/resize AND when a sibling reflows it,
+ * flipping/shifting to stay on screen. The developer owns when it shows
+ * (`open`/`default-open`); the ×, Escape, OR clicking the trigger fires
+ * `onDismiss`. Color comes from `--kai-coachmark-bg` / `--kai-coachmark-fg` (each
+ * defaulting to the `tone` palette), so a consumer can recolor purely in CSS; the
+ * arrow reads the same bg var so it always continues the bubble.
+ */
+export function Coachmark(props: CoachmarkProps) {
+  const config = useChatConfig();
+  const tone = () => TONE_DEFAULTS[props.tone ?? 'primary'];
+  const titleId = createUniqueId();
+  const [internalOpen, setInternalOpen] = createSignal(props.defaultOpen ?? false);
+  const [anchor, setAnchor] = createSignal<HTMLElement>();
+  const [bubble, setBubble] = createSignal<HTMLElement>();
+  const [arrowEl, setArrowEl] = createSignal<HTMLElement>();
+
+  const isControlled = () => props.open !== undefined;
+  const isOpen = () => (isControlled() ? !!props.open : internalOpen());
+  const setOpen = (v: boolean) => {
+    if (!isControlled()) setInternalOpen(v);
+    props.onOpenChange?.(v);
+  };
+
+  props.controllerRef?.({ open: isOpen, setOpen });
+
+  const presence = createPresence(isOpen);
+  const position = usePosition(anchor, bubble, {
+    placement: props.placement ?? 'bottom',
+    gutter: 10,
+    arrowEl,
+    // Anchor removed from the DOM -> close so the bubble portal doesn't orphan.
+    onDisconnect: () => setOpen(false),
+  });
+
+  // The bubble edge the arrow sits on, derived from the resolved (post flip/shift)
+  // placement.
+  const arrowSide = () => STATIC_SIDE[position.pos().placement.split('-')[0]] ?? 'top';
+
+  const dismiss = () => {
+    setOpen(false);
+    props.onDismiss?.();
+  };
+
+  // Clicking the trigger dismisses the hint (alongside the × and Escape): the
+  // consumer engaged with what the hint points at, so it has done its job. A
+  // native listener (not preventing default or stopping propagation) so the
+  // trigger's own click still fires, and so it works for a slotted trigger in the
+  // web component. Only acts while open so it never re-fires onDismiss when shut.
+  createEffect(() => {
+    const el = anchor();
+    if (!el) return;
+    const onClick = () => { if (isOpen()) dismiss(); };
+    el.addEventListener('click', onClick);
+    onCleanup(() => el.removeEventListener('click', onClick));
+  });
+
+  return (
+    <>
+      {/* The anchor wrapper. inline-FLEX (not inline-block) so it hugs the trigger
+          it positions against WITHOUT the baseline strut: an inline-block sits on
+          the host line box's baseline, which reserves descender space below it
+          (line-height 24px), making the host ~6px taller than the trigger and
+          anchoring the trigger to the top, so in a flex toolbar (items-center) the
+          trigger renders a few px above the other controls. inline-flex +
+          vertical-align:middle decouples from that baseline so the wrapper hugs the
+          trigger's true height and stays centered. The trigger-click dismissal is
+          wired as a NATIVE listener on this element (see the effect below) rather
+          than a Solid-delegated onClick, so it also fires for a trigger projected
+          through the <slot/> in the web component (Solid's delegation walks
+          parentNode, which for slotted content stays in the light DOM and never
+          reaches this shadow ancestor). */}
+      <span ref={setAnchor} style={{ display: 'inline-flex', 'vertical-align': 'middle' }}>
+        {props.children}
+      </span>
+      <Show when={presence.present()}>
+        <Portal mount={config.portalMount()}>
+          <div
+            ref={(el) => { setBubble(el); presence.setRef(el); }}
+            part="bubble"
+            role="dialog"
+            aria-labelledby={titleId}
+            data-expanded={presence.state() === 'open' ? '' : undefined}
+            data-closed={presence.state() === 'closed' ? '' : undefined}
+            style={{
+              position: 'fixed',
+              left: `${position.pos().x}px`,
+              top: `${position.pos().y}px`,
+              visibility: position.hidden() ? 'hidden' : 'visible',
+              // Color via CSS vars: defaults to the `tone` palette, overridable in
+              // CSS. The text color is inherited by every child (dismiss/badge/
+              // content read it through currentColor).
+              background: `var(--kai-coachmark-bg, ${tone().bg})`,
+              color: `var(--kai-coachmark-fg, ${tone().fg})`,
+            }}
+            class={cn(
+              'z-50 w-64 rounded-lg p-3 pr-8 text-sm kai-elevation',
+              'animate-in fade-in-0 zoom-in-95 data-[closed]:animate-out data-[closed]:fade-out-0 data-[closed]:zoom-out-95',
+            )}
+          >
+            {/* The arrow: a rotated square inheriting the bubble bg. usePosition
+                writes its offset-axis position (x for top/bottom placements, y for
+                left/right); the static side (`-4px`) pins it to the bubble edge
+                facing the anchor so it pokes out as a pointer.
+
+                Each side is an EXPLICIT, static key. Do NOT collapse this to a
+                computed `[arrowSide()]: '-4px'` key: Solid compiles `style={{…}}`
+                object literals to per-property setStyleProperty calls at build time
+                and silently DROPS dynamic/computed keys, so the offset never
+                reaches the DOM and the arrow sinks into the bubble's padding box
+                (invisible against the matching background). */}
+            <Show when={props.arrow !== false}>
+              <div
+                ref={setArrowEl}
+                part="arrow"
+                aria-hidden="true"
+                class="absolute size-2 rotate-45"
+                style={{
+                  left: arrowSide() === 'left' ? '-4px'
+                    : position.arrowPos().x != null ? `${position.arrowPos().x}px` : '',
+                  top: arrowSide() === 'top' ? '-4px'
+                    : position.arrowPos().y != null ? `${position.arrowPos().y}px` : '',
+                  right: arrowSide() === 'right' ? '-4px' : '',
+                  bottom: arrowSide() === 'bottom' ? '-4px' : '',
+                  // Same bg var as the bubble so the arrow always reads as part of it.
+                  background: `var(--kai-coachmark-bg, ${tone().bg})`,
+                }}
+              />
+            </Show>
+
+            <button
+              type="button"
+              part="dismiss"
+              aria-label="Dismiss"
+              onClick={dismiss}
+              class={cn('absolute right-2 top-2 inline-flex size-5 items-center justify-center rounded transition-colors', DISMISS_CLS)}
+            >
+              <X class="size-3.5" aria-hidden="true" />
+            </button>
+
+            <Show when={props.headline}>
+              <div class="flex items-center gap-2">
+                <span id={titleId} part="title" class="font-semibold leading-tight">
+                  {props.headline}
+                </span>
+                <Show when={props.badge}>
+                  <span
+                    part="badge"
+                    class={cn('inline-flex items-center rounded-full px-1.5 py-0.5 text-[0.625rem] font-medium uppercase leading-none tracking-wide', BADGE_CLS)}
+                  >
+                    {props.badge}
+                  </span>
+                </Show>
+              </div>
+            </Show>
+
+            <Show when={props.content}>
+              <div class={cn(CONTENT_CLS, props.headline ? 'mt-1.5' : '')}>
+                {props.content}
+              </div>
+            </Show>
+          </div>
+        </Portal>
+      </Show>
+    </>
+  );
+}