@kitn.ai/ui 0.17.0 → 0.18.1

package/src/components/confirm-card.tsx

@@ -7,6 +7,7 @@ import {
   createMemo,
   createEffect,
   on,
+  onMount,
   ErrorBoundary,
 } from 'solid-js';
 import { cn } from '../utils/cn';
@@ -121,6 +122,21 @@ export function defaultActionId(actions: ConfirmAction[]): string | undefined {
 // The <ConfirmCard> component.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Imperative handle exposed via `controllerRef` — surfaces the confirm card's
+ *  latent action/dismiss capabilities so the `<kai-confirm>` facade can forward
+ *  them as instance methods (focus/confirm/dismiss/reopen). */
+export interface ConfirmController {
+  /** Focus the default action button (or the first action if none default). */
+  focus(options?: FocusOptions): void;
+  /** Activate an action by id (or the default action when omitted) — emits the
+   *  `action` verb + resolves single-shot. */
+  confirm(actionId?: string): 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 ConfirmCardProps {
   /** The confirm definition (CardEnvelope.data). */
   data?: ConfirmCardData;
@@ -138,6 +154,9 @@ export interface ConfirmCardProps {
   class?: string;
   /** When set, render the chromed read-only view instead of the buttons. */
   resolution?: CardResolution;
+  /** Receive the imperative controller once mounted. The `<kai-confirm>` facade
+   *  forwards these as element methods (focus/confirm/dismiss/reopen). */
+  controllerRef?: (controller: ConfirmController) => void;
 }
 
 /**
@@ -159,6 +178,7 @@ export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
     'autofocus',
     'class',
     'resolution',
+    'controllerRef',
   ]);
 
   const ctxHost = useCardHost();
@@ -220,6 +240,39 @@ export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
   const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
 
   let bodyRef: HTMLDivElement | undefined;
+  let actionsRef: HTMLDivElement | undefined;
+
+  // The default action button (or the first action button if none is marked
+  // default) — the same target the `autofocus` prop focuses on mount.
+  const focusTarget = (): HTMLButtonElement | null => {
+    if (!actionsRef) return null;
+    return (
+      actionsRef.querySelector<HTMLButtonElement>('button[data-kai-default="true"]') ??
+      actionsRef.querySelector<HTMLButtonElement>('button[data-action-id]')
+    );
+  };
+
+  // ── Imperative controller (Pattern C): hand the facade a handle over the
+  //    card's latent action/dismiss capabilities. Every method drives the SAME
+  //    internal path the buttons drive, so the same kai-card events fire. ──────────
+  onMount(() => {
+    local.controllerRef?.({
+      // Focus the default (or first) action button on demand.
+      focus: (options) => focusTarget()?.focus(options),
+      // Activate an action by id (or the default action with no id) — the button path.
+      confirm: (actionId) => {
+        const list = actions();
+        const id = actionId ?? defaultId();
+        if (id === undefined) return;
+        const action = list.find((a) => a.id === id);
+        if (action) onAction(action);
+      },
+      // Trigger the dismiss path (the X-button path).
+      dismiss: () => onDismiss(),
+      // Re-open a dismissed card (the stub's affordance path).
+      reopen: () => onReopen(),
+    });
+  });
 
   // Surface the resolved action id for host styling.
   createEffect(() => {
@@ -269,7 +322,7 @@ export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
                     <X size={16} aria-hidden="true" />
                   </Button>
                 </Show>
-                <div class="ml-auto flex flex-wrap items-center gap-2">
+                <div ref={actionsRef} class="ml-auto flex flex-wrap items-center gap-2">
                   <For each={actions()}>
                     {(action) => (
                       <Button

package/src/components/conversation-item.tsx

@@ -1,16 +1,78 @@
-import { splitProps } from 'solid-js';
+import { Show, splitProps, createMemo } from 'solid-js';
+import { MessageSquare } from 'lucide-solid';
 import { cn } from '../utils/cn';
 import type { ConversationSummary } from '../types';
 
-export interface ConversationItemProps { conversation: ConversationSummary; isActive: boolean; onSelect: (id: string) => void; class?: string; }
+export interface ConversationItemProps {
+  conversation: ConversationSummary;
+  isActive: boolean;
+  onSelect: (id: string) => void;
+  /** Dense single-line row: a leading dot + title, no message count. */
+  compact?: boolean;
+  class?: string;
+}
+
+/**
+ * Short relative time from an ISO date string: "just now", "5m ago", "3h ago",
+ * "2d ago", "24d ago". Pure — it snapshots `now` (defaults to `Date.now()`) at
+ * call time, so it re-derives whenever the list re-renders; there is no internal
+ * ticking clock. Returns '' for a missing or unparseable date.
+ */
+export function relativeTimeShort(iso?: string, now: number = Date.now()): string {
+  if (!iso) return '';
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return '';
+  const secs = Math.max(0, Math.round((now - then) / 1000));
+  if (secs < 60) return 'just now';
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
 
 export function ConversationItem(props: ConversationItemProps) {
-  const [local] = splitProps(props, ['conversation', 'isActive', 'onSelect', 'class']);
+  const [local] = splitProps(props, ['conversation', 'isActive', 'onSelect', 'compact', 'class']);
+  // The trailing text: the consumer's own `trailing` field, else an auto relative
+  // time from updatedAt (fallback lastMessageAt). REACTIVITY: this (and the auto
+  // time) update when the consumer re-assigns the `conversations` array with a new
+  // reference — the kit's standard reactivity model — not via an internal clock.
+  const trailing = createMemo(
+    () => local.conversation.trailing ?? relativeTimeShort(local.conversation.updatedAt ?? local.conversation.lastMessageAt),
+  );
   return (
-    <button data-conversation-id={local.conversation.id} onClick={() => local.onSelect(local.conversation.id)}
-      class={cn('w-full text-left rounded-lg px-2.5 py-2 transition-colors', local.isActive ? 'bg-muted' : 'hover:bg-muted/50', local.class)}>
-      <div class={cn('truncate text-sm', local.isActive ? 'text-foreground font-medium' : 'text-foreground/80')}>{local.conversation.title}</div>
-      <div class={cn('truncate mt-0.5 text-xs', local.isActive ? 'text-foreground/70' : 'text-muted-foreground')}>{local.conversation.messageCount} messages</div>
+    <button
+      data-conversation-id={local.conversation.id}
+      onClick={() => local.onSelect(local.conversation.id)}
+      class={cn(
+        'w-full rounded-lg text-left transition-colors',
+        local.compact ? 'px-2.5 py-1.5' : 'px-2.5 py-2',
+        local.isActive ? 'bg-muted' : 'hover:bg-muted/50',
+        local.class,
+      )}
+    >
+      <Show
+        when={local.compact}
+        fallback={
+          <>
+            <div class="flex items-center gap-2">
+              <div class={cn('min-w-0 flex-1 truncate text-sm', local.isActive ? 'font-medium text-foreground' : 'text-foreground/80')}>{local.conversation.title}</div>
+              <Show when={trailing()}>
+                <span part="trailing" class="ml-auto shrink-0 text-xs text-muted-foreground">{trailing()}</span>
+              </Show>
+            </div>
+            <div class={cn('mt-0.5 truncate text-xs', local.isActive ? 'text-foreground/70' : 'text-muted-foreground')}>{local.conversation.messageCount} messages</div>
+          </>
+        }
+      >
+        <div class="flex items-center gap-2.5">
+          <MessageSquare class={cn('size-3.5 shrink-0', local.isActive ? 'text-foreground' : 'text-muted-foreground')} />
+          <span class={cn('min-w-0 flex-1 truncate text-sm', local.isActive ? 'font-medium text-foreground' : 'text-foreground/80')}>{local.conversation.title}</span>
+          <Show when={trailing()}>
+            <span part="trailing" class="ml-auto shrink-0 text-xs text-muted-foreground">{trailing()}</span>
+          </Show>
+        </div>
+      </Show>
     </button>
   );
 }

package/src/components/conversation-list.tsx

@@ -1,4 +1,5 @@
-import { splitProps, For, Show, createSignal, createMemo } from 'solid-js';
+import { splitProps, For, Show, createSignal, createMemo, onMount, type JSX } from 'solid-js';
+import { PanelLeftOpen } from 'lucide-solid';
 import { cn } from '../utils/cn';
 import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '../ui/collapsible';
 import { Button } from '../ui/button';
@@ -7,6 +8,26 @@ import { ScrollArea } from '../ui/scroll-area';
 import { ConversationItem } from './conversation-item';
 import type { ConversationSummary, ConversationGroup } from '../types';
 
+/**
+ * The collapsed-rail fallback: a floating reopen button shown when the
+ * conversation sidebar is collapsed. Shared by `kai-workspace` (its collapsed
+ * branch) and the standalone `kai-conversations` (collapsed mode), so the rail
+ * collapses identically in both. Renders only the button; the host owns the
+ * surrounding region (the workspace puts the thread beside it, the standalone
+ * element stands alone). `onExpand` reopens the rail.
+ */
+export function CollapsedRail(props: { onExpand: () => void; class?: string }) {
+  return (
+    <Button
+      variant="ghost" size="icon-sm" aria-label="Open sidebar"
+      class={cn('rounded-full bg-card/80 shadow-sm backdrop-blur', props.class)}
+      onClick={props.onExpand}
+    >
+      <PanelLeftOpen class="size-4" />
+    </Button>
+  );
+}
+
 export interface ConversationListProps {
   groups: ConversationGroup[];
   conversations: ConversationSummary[];
@@ -14,12 +35,48 @@ export interface ConversationListProps {
   onSelect: (id: string) => void;
   onNewChat: () => void;
   onToggleSidebar?: () => void;
+  /** Replaces the built-in title bar (toggle / "Chats" / New chat). */
+  header?: JSX.Element;
+  /** A row below the list (e.g. account / settings / usage). */
+  footer?: JSX.Element;
+  /** Replaces the built-in "no conversations yet" state. */
+  empty?: JSX.Element;
+  /** Dense single-line rows (a leading dot + title, no message count). */
+  compact?: boolean;
+  /** Fired whenever the built-in search box query changes (typing or a
+   *  programmatic `clear()`). Lets the facade surface a `kai-search` event. */
+  onSearchChange?: (query: string) => void;
+  /** Receive the imperative controller once mounted. The `kai-conversations`
+   *  facade uses it to focus / clear the internal search input. */
+  controllerRef?: (controller: ConversationListController) => void;
   class?: string;
 }
 
+/** Imperative handle exposed via `controllerRef` — surfaces the internal search
+ *  box to the `kai-conversations` facade (the searchQuery signal lives here). */
+export interface ConversationListController {
+  /** Focus the built-in search `<input>`. */
+  focus(options?: FocusOptions): void;
+  /** Clear the internal search query (resets the list filter). */
+  clearSearch(): void;
+}
+
 export function ConversationList(props: ConversationListProps) {
-  const [local] = splitProps(props, ['groups', 'conversations', 'activeId', 'onSelect', 'onNewChat', 'onToggleSidebar', 'class']);
+  const [local] = splitProps(props, ['groups', 'conversations', 'activeId', 'onSelect', 'onNewChat', 'onToggleSidebar', 'header', 'footer', 'empty', 'compact', 'onSearchChange', 'controllerRef', 'class']);
   const [searchQuery, setSearchQuery] = createSignal('');
+  const isEmpty = createMemo(() => local.conversations.length === 0);
+  // The search query is owned here; setQuery is the single mutation point so both
+  // typing and the imperative clearSearch() notify the facade (→ kai-search).
+  let searchInput: HTMLInputElement | undefined;
+  const setQuery = (q: string) => { setSearchQuery(q); local.onSearchChange?.(q); };
+
+  // Hand the imperative controller (focus / clear the search box) to the facade.
+  onMount(() => {
+    local.controllerRef?.({
+      focus: (options) => searchInput?.focus(options),
+      clearSearch: () => setQuery(''),
+    });
+  });
 
   const filteredConversations = createMemo(() => {
     const q = searchQuery().toLowerCase();
@@ -41,45 +98,85 @@ export function ConversationList(props: ConversationListProps) {
 
   return (
     <div class={cn('flex flex-col h-full bg-sidebar', local.class)}>
-      <div class="flex items-center justify-between p-3 pb-2">
-        <div class="flex items-center gap-2">
-          <Button variant="ghost" size="icon-sm" aria-label="Toggle sidebar" onClick={local.onToggleSidebar}>
-            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
-          </Button>
-          <span class="text-sm font-semibold text-foreground">Chats</span>
+      {/* header (replace): the consumer's own title bar, else the built-in one. */}
+      <Show
+        when={local.header}
+        fallback={
+          <div class="flex items-center justify-between p-3 pb-2">
+            <div class="flex items-center gap-2">
+              <Button variant="ghost" size="icon-sm" aria-label="Toggle sidebar" onClick={local.onToggleSidebar}>
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
+              </Button>
+              <span class="text-sm font-semibold text-foreground">Chats</span>
+            </div>
+            <Button variant="ghost" size="icon-sm" aria-label="New chat" onClick={local.onNewChat}>
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
+            </Button>
+          </div>
+        }
+      >
+        {local.header}
+      </Show>
+      <Show when={!isEmpty()}>
+        <div class="px-3 pb-2">
+          <div class="flex items-center gap-2 rounded-md bg-surface-strong px-2.5 py-1.5">
+            <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="text-muted-foreground"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
+            <input ref={searchInput} type="text" value={searchQuery()} onInput={(e) => setQuery(e.currentTarget.value)} placeholder="Search chats..."
+              aria-label="Search chats"
+              class="bg-transparent text-[13px] text-foreground placeholder:text-muted-foreground rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring w-full" />
+          </div>
         </div>
-        <Button variant="ghost" size="icon-sm" aria-label="New chat" onClick={local.onNewChat}>
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
-        </Button>
-      </div>
-      <div class="px-3 pb-2">
-        <div class="flex items-center gap-2 rounded-md bg-muted/40 px-2.5 py-1.5">
-          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="text-muted-foreground"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
-          <input type="text" value={searchQuery()} onInput={(e) => setSearchQuery(e.currentTarget.value)} placeholder="Search chats..."
-            aria-label="Search chats"
-            class="bg-transparent text-[13px] text-foreground placeholder:text-muted-foreground rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring w-full" />
-        </div>
-      </div>
-      <ScrollArea class="flex-1 px-2">
-        <For each={local.groups}>
-          {(group) => {
-            const convs = createMemo(() => groupedConversations().get(group.id) ?? []);
-            return (
-              <Show when={convs().length > 0}>
-                <GroupSection name={group.name} count={convs().length} conversations={convs()} activeId={local.activeId} onSelect={local.onSelect} />
-              </Show>
-            );
-          }}
-        </For>
-        <Show when={ungrouped().length > 0}>
-          <GroupSection name="Ungrouped" count={ungrouped().length} conversations={ungrouped()} activeId={local.activeId} onSelect={local.onSelect} />
-        </Show>
-      </ScrollArea>
+      </Show>
+      {/* list, or the empty state (replace) when there are no conversations. */}
+      <Show
+        when={!isEmpty()}
+        fallback={
+          <Show
+            when={local.empty}
+            fallback={
+              <div class="flex flex-1 flex-col items-center justify-center gap-1 p-6 text-center text-sm text-muted-foreground">
+                No conversations yet
+              </div>
+            }
+          >
+            {local.empty}
+          </Show>
+        }
+      >
+        <ScrollArea class="flex-1 px-2">
+          <For each={local.groups}>
+            {(group) => {
+              const convs = createMemo(() => groupedConversations().get(group.id) ?? []);
+              return (
+                <Show when={convs().length > 0}>
+                  <GroupSection name={group.name} count={convs().length} conversations={convs()} activeId={local.activeId} onSelect={local.onSelect} compact={local.compact} />
+                </Show>
+              );
+            }}
+          </For>
+          <Show when={ungrouped().length > 0}>
+            <Show
+              when={local.compact}
+              fallback={<GroupSection name="Ungrouped" count={ungrouped().length} conversations={ungrouped()} activeId={local.activeId} onSelect={local.onSelect} />}
+            >
+              <div class="space-y-0.5 py-1">
+                <For each={ungrouped()}>
+                  {(conv) => <ConversationItem conversation={conv} isActive={conv.id === local.activeId} onSelect={local.onSelect} compact />}
+                </For>
+              </div>
+            </Show>
+          </Show>
+        </ScrollArea>
+      </Show>
+      {/* footer (inject): a row below the list (account / settings / …). */}
+      <Show when={local.footer}>
+        <div class="shrink-0 border-t border-border">{local.footer}</div>
+      </Show>
     </div>
   );
 }
 
-function GroupSection(props: { name: string; count: number; conversations: ConversationSummary[]; activeId?: string; onSelect: (id: string) => void }) {
+function GroupSection(props: { name: string; count: number; conversations: ConversationSummary[]; activeId?: string; onSelect: (id: string) => void; compact?: boolean }) {
   const [open, setOpen] = createSignal(true);
   return (
     <Collapsible open={open()} onOpenChange={setOpen}>
@@ -92,7 +189,7 @@ function GroupSection(props: { name: string; count: number; conversations: Conve
       <CollapsibleContent>
         <div class="pl-2 mt-0.5 space-y-0.5">
           <For each={props.conversations}>
-            {(conv) => <ConversationItem conversation={conv} isActive={conv.id === props.activeId} onSelect={props.onSelect} />}
+            {(conv) => <ConversationItem conversation={conv} isActive={conv.id === props.activeId} onSelect={props.onSelect} compact={props.compact} />}
           </For>
         </div>
       </CollapsibleContent>