@kitn.ai/ui 0.27.0 → 0.28.0

package/src/components/conversation-item.tsx

@@ -31,6 +31,29 @@ export function relativeTimeShort(iso?: string, now: number = Date.now()): strin
   return `${Math.floor(hours / 24)}d ago`;
 }
 
+/**
+ * Whether a conversation should show an unread indicator (owner round,
+ * 2026-08-26). `lastReadAt`'s own doc (`types.ts`) has the full contract;
+ * this is the one place that reads it, so both list surfaces (this file's
+ * `ConversationItem` and the widget-box `ConversationPanel`) derive it
+ * identically rather than each restating the comparison.
+ *
+ * Absent `lastReadAt` reads as NOT unread — the decide-loudly default for a
+ * store that never implements `ConversationStore.markRead` at all (every
+ * summary it returns leaves the field undefined forever, so this always
+ * returns `false` for it) rather than guessing "probably unread" from a
+ * signal the store never actually provided. Defensive `Date.parse`, same
+ * pattern as `relativeTimeShort` above: an unparsable date reads as not
+ * unread rather than throwing.
+ */
+export function isConversationUnread(conv: Pick<ConversationSummary, 'updatedAt' | 'lastReadAt'>): boolean {
+  if (!conv.lastReadAt) return false;
+  const updated = Date.parse(conv.updatedAt);
+  const read = Date.parse(conv.lastReadAt);
+  if (Number.isNaN(updated) || Number.isNaN(read)) return false;
+  return updated > read;
+}
+
 /**
  * The slotted-item shape rendered by `<kai-conversation-item>` — the composed
  * row of the consumer-owned loop. Distinct from the

package/src/components/conversation-panel.tsx

@@ -0,0 +1,118 @@
+import { For, Show, createMemo } from 'solid-js';
+import { cn } from '../utils/cn';
+import { ScrollArea } from '../ui/scroll-area';
+import { relativeTimeShort, isConversationUnread } from './conversation-item';
+import { byRecency } from '../primitives/conversation-store';
+import type { ConversationSummary } from '../types';
+
+export interface ConversationPanelProps {
+  conversations: ConversationSummary[];
+  activeId?: string;
+  onSelect: (id: string) => void;
+  onNewChat: () => void;
+  /** Wording for the floating new-conversation pill. Defaults to "New conversation". */
+  newChatLabel?: string;
+  class?: string;
+}
+
+/**
+ * The widget-box list view (owner rework, 2026-08-26 — the earlier retrofit
+ * of the desktop `ConversationList` into this box was rejected at the live
+ * demo). NOT `ConversationList`, which stays the desktop-sidebar surface
+ * unchanged: no search box, no group headers, no per-row menu, no full-width
+ * footer bar, no second "+" beside the header toggle. A row is a
+ * conversation, full stop — bold title, right-aligned relative time, one
+ * truncated line of the last message. The ONE way to start a new
+ * conversation is the floating pill near the bottom.
+ *
+ * Modeled directly on Intercom's Messenger "Messages" tab (first-hand
+ * research: `.superpowers/sdd/2026-08-26-conversations/
+ * research-intercom-messages-view.md`) — a box this size gets one job at a
+ * time: browsing conversations OR having one, never both, and the list
+ * replaces the ENTIRE content area (`ChatThread` hides the thread,
+ * suggestions and composer while this renders — see its `view() === 'list'`
+ * branch).
+ */
+export function ConversationPanel(props: ConversationPanelProps) {
+  // Most-recently-updated first — the same defensive sort ChatThread's own
+  // auto-restore uses (an unparsable/missing date sorts last, never throws).
+  const ordered = createMemo(() =>
+    [...props.conversations].sort(byRecency),
+  );
+
+  return (
+    <div class={cn('relative flex h-full flex-col', props.class)}>
+      <Show
+        when={props.conversations.length > 0}
+        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>
+        }
+      >
+        <ScrollArea class="flex-1 px-2 pt-2">
+          {/* Bottom padding clears the floating pill so the last row is never
+              hidden behind it. */}
+          <div role="list" aria-label="Conversations" class="space-y-0.5 pb-16">
+            <For each={ordered()}>
+              {(conv) => {
+                const isActive = () => conv.id === props.activeId;
+                const time = () => relativeTimeShort(conv.updatedAt ?? conv.lastMessageAt);
+                const unread = () => isConversationUnread(conv);
+                return (
+                  <button
+                    type="button"
+                    role="listitem"
+                    data-conversation-id={conv.id}
+                    data-active={isActive() ? '' : undefined}
+                    data-unread={unread() ? '' : undefined}
+                    aria-current={isActive() ? 'true' : undefined}
+                    onClick={() => props.onSelect(conv.id)}
+                    class={cn(
+                      'block w-full rounded-lg px-3 py-2.5 text-left transition-colors',
+                      isActive() ? 'bg-muted' : 'hover:bg-muted/50',
+                    )}
+                  >
+                    <div class="flex items-baseline gap-2">
+                      <span class={cn('min-w-0 flex-1 truncate text-sm font-semibold', isActive() ? 'text-foreground' : 'text-foreground/90')}>
+                        {conv.title}
+                      </span>
+                      <Show when={time()}>
+                        <span class="shrink-0 text-xs text-muted-foreground">{time()}</span>
+                      </Show>
+                    </div>
+                    {/* Trailing line: the last-message preview, plus — Intercom's own
+                        placement (research doc §2) — a small unread dot at its end. No
+                        preview text and no unread still renders nothing, same as before. */}
+                    <Show when={conv.trailing || unread()}>
+                      <div class="mt-0.5 flex items-center gap-1.5">
+                        <span class="min-w-0 flex-1 truncate text-xs text-muted-foreground">{conv.trailing}</span>
+                        <Show when={unread()}>
+                          <span aria-hidden="true" class="size-1.5 shrink-0 rounded-full bg-unread" />
+                          <span class="sr-only">Unread</span>
+                        </Show>
+                      </div>
+                    </Show>
+                  </button>
+                );
+              }}
+            </For>
+          </div>
+        </ScrollArea>
+      </Show>
+      {/* The ONE new-conversation control: a compact centered floating pill,
+          never a header "+" AND a footer bar at once (the retrofit's
+          rejected shape). */}
+      <div class="pointer-events-none absolute inset-x-0 bottom-3 flex justify-center">
+        <button
+          type="button"
+          data-kai-new-conversation
+          onClick={props.onNewChat}
+          class="pointer-events-auto rounded-full border border-border bg-background px-4 py-2 text-sm font-medium text-foreground shadow-md transition-colors hover:bg-muted/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          {props.newChatLabel ?? 'New conversation'}
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/home-panel.tsx

@@ -0,0 +1,159 @@
+import { For, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { renderIcon } from '../ui/icon';
+import { isSafeUrl } from '../primitives/url-scheme-policy';
+import { relativeTimeShort, isConversationUnread } from './conversation-item';
+import type { ConversationSummary, HomeLinkEntry } from '../types';
+
+export interface HomePanelProps {
+  greeting?: { title?: string; subtitle?: string };
+  /** The most-recent conversation, host-derived. `undefined` hides the card
+   *  entirely — this component never fetches or picks one itself. */
+  recent?: ConversationSummary;
+  /** Defaults to `true`. */
+  showNewConversation?: boolean;
+  /** Defaults to `'Send us a message'`. */
+  newChatLabel?: string;
+  links?: HomeLinkEntry[];
+  onSelectRecent?: (id: string) => void;
+  onNewChat: () => void;
+  /** Fired only for href-less link entries — an entry with a safe `href`
+   *  navigates as a real anchor instead. */
+  onLink?: (entry: HomeLinkEntry) => void;
+  class?: string;
+}
+
+/**
+ * The widget home screen (Intercom-pattern, H-1): greeting, the most-recent
+ * conversation, a "start a new conversation" CTA, and a list of host-defined
+ * links. Pure props in, events out — no fetching, no routing; a later task
+ * wires this behind `ChatThread`'s Home/Messages tab bar.
+ *
+ * Unsafe-href rule: a `links` entry with an `href` that fails `isSafeUrl`
+ * (e.g. `javascript:`) is NOT silently promoted into a button/event-emitter —
+ * that would let a host-authored-but-attacker-influenced config still fire a
+ * handler off a scheme SAFE_SCHEMES rejects. It renders as a plain,
+ * non-interactive row: label visible, no anchor, no button, no click handler.
+ */
+export function HomePanel(props: HomePanelProps) {
+  const title = () => props.greeting?.title ?? 'Hi there 👋';
+
+  return (
+    <div
+      data-kai-home-panel
+      class={cn('flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-5', props.class)}
+    >
+      <div class="flex flex-col gap-1">
+        <h2 class="text-xl font-semibold text-foreground">{title()}</h2>
+        <Show when={props.greeting?.subtitle}>
+          <p class="text-sm text-muted-foreground">{props.greeting!.subtitle}</p>
+        </Show>
+      </div>
+
+      <Show when={props.recent}>
+        {(recent) => {
+          const time = () => relativeTimeShort(recent().updatedAt ?? recent().lastMessageAt);
+          const unread = () => isConversationUnread(recent());
+          return (
+            <button
+              type="button"
+              data-kai-home-recent
+              onClick={() => props.onSelectRecent?.(recent().id)}
+              class="flex flex-col gap-1 rounded-xl border border-border p-4 text-left transition-colors hover:bg-accent"
+            >
+              <span class="flex items-center gap-2 text-sm font-semibold text-foreground">
+                <span class="min-w-0 flex-1 truncate">{recent().title}</span>
+                <Show when={unread()}>
+                  <span aria-hidden="true" class="size-1.5 shrink-0 rounded-full bg-unread" />
+                </Show>
+                <Show when={time()}>
+                  <span class="shrink-0 text-xs font-normal text-muted-foreground">{time()}</span>
+                </Show>
+              </span>
+              <Show when={recent().trailing}>
+                <span class="line-clamp-1 text-sm text-muted-foreground">{recent().trailing}</span>
+              </Show>
+            </button>
+          );
+        }}
+      </Show>
+
+      <Show when={props.showNewConversation !== false}>
+        <Button
+          type="button"
+          data-kai-home-new
+          full
+          align="start"
+          onClick={() => props.onNewChat()}
+          class="justify-between"
+        >
+          <span>{props.newChatLabel ?? 'Send us a message'}</span>
+          {renderIcon('arrow-right', { class: 'size-4 shrink-0' })}
+        </Button>
+      </Show>
+
+      <Show when={props.links && props.links.length > 0}>
+        <div class="flex flex-col overflow-hidden rounded-xl border border-border">
+          <For each={props.links}>
+            {(entry) => {
+              const safeHref = () => (entry.href && isSafeUrl(entry.href) ? entry.href : undefined);
+              const inner = (
+                <>
+                  <span class="flex min-w-0 items-center gap-2">
+                    <Show when={entry.icon}>{renderIcon(entry.icon, { class: 'size-4 shrink-0 text-muted-foreground' })}</Show>
+                    <span class="flex min-w-0 flex-col text-left">
+                      <span class="truncate text-sm font-medium text-foreground">{entry.label}</span>
+                      <Show when={entry.description}>
+                        <span class="truncate text-xs text-muted-foreground">{entry.description}</span>
+                      </Show>
+                    </span>
+                  </span>
+                  {renderIcon('chevron-right', { class: 'size-4 shrink-0 text-muted-foreground' })}
+                </>
+              );
+              const rowClass = 'flex items-center justify-between gap-2 border-b border-border p-3 last:border-b-0';
+              return (
+                <Show
+                  when={!entry.href}
+                  fallback={
+                    <Show
+                      when={safeHref()}
+                      fallback={
+                        // Unsafe href: a non-interactive row. No anchor, no
+                        // button, no handler — the label stays visible, it
+                        // just never becomes clickable.
+                        <div data-kai-home-link class={rowClass}>
+                          {inner}
+                        </div>
+                      }
+                    >
+                      <a
+                        data-kai-home-link
+                        href={safeHref()}
+                        target="_blank"
+                        rel="noreferrer noopener"
+                        class={cn(rowClass, 'transition-colors hover:bg-accent')}
+                      >
+                        {inner}
+                      </a>
+                    </Show>
+                  }
+                >
+                  <button
+                    type="button"
+                    data-kai-home-link
+                    onClick={() => props.onLink?.(entry)}
+                    class={cn(rowClass, 'w-full text-left transition-colors hover:bg-accent')}
+                  >
+                    {inner}
+                  </button>
+                </Show>
+              );
+            }}
+          </For>
+        </div>
+      </Show>
+    </div>
+  );
+}

package/src/components/widget-tab-bar.tsx

@@ -0,0 +1,73 @@
+import { Show } from 'solid-js';
+import { cn } from '../utils/cn';
+import { renderIcon } from '../ui/icon';
+
+export interface WidgetTabBarProps {
+  active: 'home' | 'messages';
+  onChange: (tab: 'home' | 'messages') => void;
+  /** Whether the Messages tab has unread activity. Reaches BOTH the visible
+   *  dot and the tab's accessible name (`aria-label`) — a dot alone is
+   *  invisible to assistive tech, the #336 lesson this test pins. */
+  unread?: boolean;
+  homeLabel?: string;
+  messagesLabel?: string;
+}
+
+/**
+ * The widget's Home/Messages tab bar (Intercom-pattern chrome, H-2/H-6). Real
+ * `tablist`/`tab` semantics — this is a persistent view switch within the
+ * widget, not page navigation, so it is not `<Nav>`'s `role="page"` dialect.
+ */
+export function WidgetTabBar(props: WidgetTabBarProps) {
+  const home = () => props.homeLabel ?? 'Home';
+  const messages = () => props.messagesLabel ?? 'Messages';
+  const messagesLabel = () => (props.unread ? `${messages()} (unread)` : messages());
+
+  return (
+    <nav
+      role="tablist"
+      aria-label="Widget navigation"
+      class="flex h-14 shrink-0 items-stretch border-t border-border bg-background"
+    >
+      <button
+        type="button"
+        role="tab"
+        data-kai-tab-home
+        aria-selected={props.active === 'home'}
+        aria-label={home()}
+        onClick={() => props.onChange('home')}
+        class={cn(
+          'flex flex-1 flex-col items-center justify-center gap-0.5 text-xs transition-colors',
+          props.active === 'home' ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+        )}
+      >
+        {renderIcon('home', { class: 'size-5' })}
+        <span>{home()}</span>
+      </button>
+      <button
+        type="button"
+        role="tab"
+        data-kai-tab-messages
+        aria-selected={props.active === 'messages'}
+        aria-label={messagesLabel()}
+        onClick={() => props.onChange('messages')}
+        class={cn(
+          'flex flex-1 flex-col items-center justify-center gap-0.5 text-xs transition-colors',
+          props.active === 'messages' ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+        )}
+      >
+        <span class="relative">
+          {renderIcon('message-square', { class: 'size-5' })}
+          <Show when={props.unread}>
+            <span
+              data-kai-tab-unread
+              aria-hidden="true"
+              class="absolute -right-0.5 -top-0.5 size-1.5 rounded-full bg-unread"
+            />
+          </Show>
+        </span>
+        <span>{messages()}</span>
+      </button>
+    </nav>
+  );
+}

package/src/elements/chat.tsx

@@ -10,12 +10,51 @@ import type { ChatMessage } from './chat-types';
 import type { TriggerDef } from '../components/composer';
 import type { ComposerDoc } from '../primitives/composer-model';
 import type { ProseSize } from '../primitives/chat-config';
-import type { ModelOption } from '../types';
+import type { ModelOption, HomeConfig, HomeLinkEntry } from '../types';
+import type { ConversationStore } from '../primitives/conversation-store';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
   | 'onMessageAction' | 'onWebSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'cardHostElement' | 'messages'
   | 'accept' | 'onAttachmentsRejected'
+  // `conversations`/`store` are re-declared below (own doc comments, matching
+  // this element's own attribute/property conventions) rather than left to
+  // flow through `Omit`'s pass-through — same reason `messages` is excluded
+  // above. Left unexcluded, the intersection carries TWO declarations of the
+  // same property (the inherited `ChatThreadProps` one plus the re-declared
+  // one below) and `gen-element-api.mjs` concatenates both JSDoc comments into
+  // one duplicated, em-dash-laden description.
+  | 'conversations' | 'store'
+  // `home` is re-declared below for the same reason as `conversations`/`store`
+  // above (own element-facing doc comment rather than the ChatThread-level one
+  // flowing through `Omit`'s pass-through). `onHomeLink` is wired internally
+  // (JSX prop on `<ChatThread>` below) as a dispatched `kai-home-link` event,
+  // matching every other ChatThread callback on this element — same reasoning
+  // as `onConversationLoad` just below.
+  | 'home' | 'onHomeLink'
+  // `onConversationLoad` is wired internally (below, JSX prop on
+  // `<ChatThread>`) as a dispatched `kai-conversation-load` event — matching
+  // every other ChatThread callback on this element — rather than left as a
+  // settable JS property: a `JSX.Element`-shaped callback prop has no HTML-
+  // consumer analogue the way `store`/`messages` do, and the kai- contract's
+  // idiom for "this thread wants to tell you something" is already an event.
+  // Excluded from `Props` for the same reason `onValueChange`/`onSubmit`/etc
+  // are excluded above: it is not a property a consumer of `<kai-chat>` sets.
+  | 'onConversationLoad'
+  // `hostOpen`/`onUnreadChange` (unread indicators, 2026-08-26) are the SAME
+  // "types without forwarding" trap as `onConversationLoad` above, for the
+  // same reason: this facade does not read either off the host element and
+  // forward it onto `<ChatThread>` below. Both exist for a caller composing
+  // `ChatThread` directly as a Solid component with its OWN show/hide chrome
+  // to report through `hostOpen` and its own sibling control (a `Dock`'s
+  // `unread` badge) to mirror `onUnreadChange` onto — the construct engine's
+  // emitted App is the motivating case (codegen.ts's `emitChatThreadUnreadProps`),
+  // exactly like `headerEndContent`/`emptyContent` below. `<kai-chat>` has no
+  // such sibling chrome of its own to report to or read from, so there is
+  // nothing here for either prop to DO — left unexcluded, `gen-element-api.mjs`
+  // would still type them into the public API and docs as settable properties
+  // that silently do nothing when set.
+  | 'hostOpen' | 'onUnreadChange'
   // `headerEndContent`/`emptyContent` are JSX.Element escape hatches for a caller
   // composing `ChatThread` directly as a Solid component (see their doc comments in
   // chat-thread.tsx — the construct-engine's emitted App is the motivating case).
@@ -75,6 +114,40 @@ type Props = Omit<ChatThreadProps,
      *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
      *  so the tighter type would reject both of the normal ways to supply one. */
     cardSchemas?: Record<string, object>;
+    /** Turns on the prior-conversations list (a list-toggle button in the
+     *  header, plus a second list view sharing the panel, C-1). Attribute-
+     *  settable like every other boolean flag on this element:
+     *  `<kai-chat conversations>`. Requires `store`. A row select, "new
+     *  conversation," or the visitor's mount-time auto-restore all deliver
+     *  their messages the same way: listen for `kai-conversation-load` and
+     *  set `el.messages` from `event.detail.messages` (a fresh array): this
+     *  element does not update `messages` for you. Set with no `store`, the
+     *  underlying `ChatThread` decides loudly (one console.error) and stays
+     *  visually off; this facade always supplies its own internal load
+     *  handler (the `kai-conversation-load` dispatch below), so the second
+     *  ChatThread guard, missing `onConversationLoad`, never trips here,
+     *  even for a consumer who never listens for the event. Default false. */
+    conversations?: boolean;
+    /** The adapter this thread persists conversations through: an object of
+     *  three functions (`list`/`load`/`save`; `ConversationStore`, exported
+     *  from `@kitn.ai/ui`'s `primitives/conversation-store`). A JS PROPERTY
+     *  ONLY: `el.store = myAdapter`. It can never be an attribute, since a
+     *  function-bearing object has no HTML string form, the same reasoning
+     *  that keeps `messages`/`cardSchemas` property-only (the kai- contract:
+     *  array/object props are JS properties, never attributes). Two built-ins
+     *  ship: `localStorageStore(name, userId?)` and `fetchStore(url, userId?)`. */
+    store?: ConversationStore;
+    /** Turns on the widget home screen (Intercom-pattern): the panel boots into
+     *  a `home` view, with a greeting, most-recent-conversation card, a "new
+     *  conversation" CTA, and host-defined links, plus a Home/Messages tab bar
+     *  for switching back to the thread. An OBJECT, so it is a JS property only:
+     *  `el.home = { greeting: { title: 'Hey' }, links: [...] }`, never an
+     *  attribute (the kai- contract: array/object props are JS properties).
+     *  A `links` entry with no `href` fires `kai-home-link` with that entry when
+     *  tapped, rather than navigating; one WITH `href` opens it directly
+     *  (only when the URL passes the kit's own scheme allowlist). Omit for the
+     *  no-home widget (chat view only, unchanged). */
+    home?: HomeConfig;
   };
 
 interface Events {
@@ -102,6 +175,19 @@ interface Events {
   'kai-web-search': Record<string, never>;
   /** The Mic / voice button was clicked. */
   'kai-voice': Record<string, never>;
+  /** A conversation's history loaded: a row tap in the list, "new
+   *  conversation," or the visitor's own mount-time auto-restore of their
+   *  most recent thread (only fires when `conversations` is on and a `store`
+   *  is set). `detail.id` is that conversation's id, `undefined` for the
+   *  "new conversation" case (no id exists until the first message mints
+   *  one, C-6). Set `el.messages = event.detail.messages` (already a fresh
+   *  array) to actually render it, since this element does not do that for
+   *  you; `messages` stays your own state like everywhere else on this
+   *  element. */
+  'kai-conversation-load': { id: string | undefined; messages: ChatMessage[] };
+  /** A `home.links` entry with no `href` was activated (tapped/clicked/Enter).
+   *  Meaningful only when `home` is set. */
+  'kai-home-link': { entry: HomeLinkEntry };
 }
 
 defineWebComponent<Props, Events>('kai-chat', {
@@ -111,7 +197,8 @@ defineWebComponent<Props, Events>('kai-chat', {
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
   attach: true, webSearch: false, voice: false, triggers: undefined, kindIcons: undefined,
   actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined, accept: undefined,
-  reasoning: undefined, reasoningOpen: undefined,
+  reasoning: undefined, reasoningOpen: undefined, conversations: false, store: undefined,
+  home: undefined,
 }, (props, { dispatch, flag, reflectFlag, element, expose }) => {
   // `messages` is an untyped boundary: a consumer can hand it anything at
   // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
@@ -185,6 +272,11 @@ defineWebComponent<Props, Events>('kai-chat', {
     actionsReveal={props.actionsReveal as 'always' | 'hover'}
     cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
     cardSchemas={props.cardSchemas as Record<string, object> | undefined}
+    conversations={flag('conversations')}
+    store={props.store as ConversationStore | undefined}
+    onConversationLoad={(messages, id) => dispatch('kai-conversation-load', { id, messages })}
+    home={props.home as HomeConfig | undefined}
+    onHomeLink={(entry) => dispatch('kai-home-link', { entry })}
     /* F-26: card parts emit off THIS element as the bubbling `kai-card` event,
        so `listenForCardEvents(el)` / addEventListener('kai-card') work. */
     cardHostElement={element}