@kitn.ai/ui 0.20.1 → 0.21.0

package/src/elements/validate-messages.ts

@@ -0,0 +1,76 @@
+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

@@ -3,7 +3,7 @@ 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
+   * 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.
    */
@@ -24,18 +24,18 @@ interface Props extends Record<string, unknown> {
 
 /** 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). */
+  /** 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
+  /** 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,
+  /** 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 };

package/src/elements/voice-output.tsx

@@ -7,7 +7,7 @@ interface Props extends Record<string, unknown> {
   /** Speak automatically when `text` is set/changed. */
   autoplay?: boolean;
   /**
-   * TTS model seam the host supplies — given text, returns an audio `Blob` to
+   * 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
@@ -20,10 +20,10 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-voice-output>`. */
 interface Events {
-  /** Playback started or stopped — drive your own UI in sync. Fires on real
-   *  transitions only (manual click and programmatic speak()/stop()), never on mount. */
+  /** Playback started or stopped. Drive your own UI in sync. 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. */
+  /** The model path (`synthesize`) resolved audio: the raw `Blob` before playback. */
   'kai-synthesized': { blob: Blob };
 }
 

package/src/index.ts

@@ -1,3 +1,22 @@
+// The package root entry (".").
+//
+// SCOPE — read before adding an export here.
+// -----------------------------------------
+// Every consumer of `@kitn.ai/ui` pays for this barrel, INCLUDING React/Vue/
+// Svelte consumers who never render a Solid component. It is therefore frozen at
+// the surface that shipped: adding a Solid component here taxes four frameworks
+// to serve one. Closing the 79/79 element coverage gaps on this file grew it
+// 591,359 -> 705,031 bytes (+19.2%), which is what motivated the split.
+//
+// The COMPLETE SolidJS surface — all 79 elements' components plus a `<Name>Props`
+// type for every public component — lives on `@kitn.ai/ui/solid` (src/solid.ts),
+// which is its own build target so only Solid consumers pay for it. `./solid`
+// re-exports this file, so it is a strict superset: anything here is reachable
+// there too, and a Solid consumer only ever needs the one import.
+//
+// Rule of thumb: a NEW Solid component export belongs in src/solid.ts.
+// Type-only exports are free (fully erased by the build) and may live in either.
+
 // Shared types (folded in from @tab-zen/shared)
 export type { ModelOption, SearchFilters, ConversationScope, ConversationSummary, ConversationGroup } from './types';
 
@@ -27,7 +46,7 @@ export type {
 } from './primitives/toast-store';
 export { Toast, ToastRegion } from './components/toast';
 export type {
-  ToastRegionProps, ToastDismissReason, ToastPosition,
+  ToastProps, ToastRegionProps, ToastDismissReason, ToastPosition,
 } from './components/toast';
 
 // Card Contract (generative-UI foundation)
@@ -160,32 +179,64 @@ export type { ButtonProps } from './ui/button';
 export { Avatar } from './ui/avatar';
 export type { AvatarProps } from './ui/avatar';
 export { Tooltip } from './ui/tooltip';
+export type { TooltipProps, TooltipController } from './ui/tooltip';
 export { HoverCard } from './ui/hover-card';
+export type { HoverCardProps, HoverCardController } from './ui/hover-card';
 export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './ui/collapsible';
+export type {
+  CollapsibleProps, CollapsibleTriggerProps, CollapsibleContentProps, CollapsibleController,
+} from './ui/collapsible';
 export { ScrollArea } from './ui/scroll-area';
+export type { ScrollAreaProps, ScrollOrientation } from './ui/scroll-area';
 export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from './ui/dropdown';
+export type {
+  DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, DropdownController,
+} from './ui/dropdown';
 export { Textarea } from './ui/textarea';
 export type { TextareaProps } from './ui/textarea';
 export { Badge } from './ui/badge';
 export type { BadgeProps } from './ui/badge';
 export { Separator } from './ui/separator';
+export type { SeparatorProps } from './ui/separator';
 export { ResizablePanelGroup, ResizablePanel, ResizableHandle, Resizable, normalizeSize, resolveToPx } from './ui/resizable';
 export type { ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps, ResizableProps, SizeValue } from './ui/resizable';
 export { Skeleton } from './ui/skeleton';
+export type { SkeletonProps, SkeletonVariant } from './ui/skeleton';
 export { FileTree, buildFileTree } from './components/file-tree';
 export type {
   FileTreeProps, FileTreeFile, FileTreeNode, FileTreeFolderNode, FileTreeFileNode,
 } from './components/file-tree';
 export { Artifact } from './components/artifact';
 export type { ArtifactProps, ArtifactFile, ArtifactTab } from './components/artifact';
+export { ArtifactCard, DEFAULT_ARTIFACT_CARD_HEIGHT } from './components/artifact-card';
+// `ArtifactCardFile` is the SAME declaration `FileTreeFile` and `ArtifactFile`
+// alias, authored in primitives/card-data-types.ts because `ArtifactCardData.files`
+// reaches it and that module has to stay resolvable from a Node/no-DOM project.
+// It is exported here under its authored name because that is the name the
+// generated element metadata records for `kai-artifact.files` / `kai-file-tree.files`,
+// and tests/elements/prop-types-exported.ts requires every named prop type to be
+// importable from this entry. The two aliases stay exported above, unchanged.
+export type {
+  ArtifactCardProps,
+  ArtifactCardData,
+  ArtifactCardEnvelope,
+  ArtifactCardFile,
+  ArtifactCardTab,
+} from './components/artifact-card';
 
 // Layer 3: AI/Feature Components
 export {
   ChatContainer, ChatContainerRoot, ChatContainerContent, ChatContainerScrollAnchor,
   useChatContainer,
 } from './components/chat-container';
-export { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyButton } from './components/message';
-export type { MessageCopyButtonProps } from './components/message';
+export type {
+  ChatContainerProps, ChatContainerRootProps, ChatContainerContentProps, ChatContainerScrollAnchorProps,
+} from './components/chat-container';
+export { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyButton, MessageBody } from './components/message';
+export type {
+  MessageProps, MessageAvatarProps, MessageContentProps, MessageActionsProps,
+  MessageActionProps, MessageCopyButtonProps, MessageBodyProps,
+} from './components/message';
 export { ResponseCompare, useResolved } from './components/response-compare';
 export type { ResponseCompareProps, CompareLayout, ResolvedController } from './components/response-compare';
 export {
@@ -201,14 +252,20 @@ export type {
   CompareSelection,
 } from './components/response-compare';
 export { MessageSkills } from './components/message-skills';
-export type { Skill as MessageSkill } from './components/message-skills';
+export type { MessageSkillsProps, Skill as MessageSkill } from './components/message-skills';
 export {
   PromptInput, PromptInputTextarea, PromptInputActions, PromptInputAction,
   usePromptInput,
 } from './components/prompt-input';
+export type {
+  PromptInputProps, PromptInputTextareaProps, PromptInputActionsProps, PromptInputActionProps,
+} from './components/prompt-input';
 export { ResponseStream } from './components/response-stream';
+export type { ResponseStreamProps } from './components/response-stream';
 export { Markdown } from './components/markdown';
+export type { MarkdownProps } from './components/markdown';
 export { CodeBlock, CodeBlockCode, CodeBlockGroup } from './components/code-block';
+export type { CodeBlockProps, CodeBlockCodeProps, CodeBlockGroupProps } from './components/code-block';
 export { Loader } from './components/loader';
 export type { LoaderVariant, LoaderSize, LoaderProps } from './components/loader';
 export {
@@ -216,13 +273,26 @@ export {
   DotsLoader, TypingLoader, WaveLoader, BarsLoader,
   TerminalLoader, TextBlinkLoader, TextShimmerLoader, TextDotsLoader,
 } from './components/loader';
-export { FeedbackBar, type FeedbackValue, type FeedbackDetail } from './components/feedback-bar';
+export type {
+  LoaderShapeProps, LoaderTextProps,
+  CircularLoaderProps, ClassicLoaderProps, PulseLoaderProps, PulseDotLoaderProps,
+  DotsLoaderProps, TypingLoaderProps, WaveLoaderProps, BarsLoaderProps,
+  TerminalLoaderProps, TextBlinkLoaderProps, TextShimmerLoaderProps, TextDotsLoaderProps,
+} from './components/loader';
+export { FeedbackBar, type FeedbackValue, type FeedbackDetail, type FeedbackBarProps } from './components/feedback-bar';
 export {
   ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger,
   ChainOfThoughtContent, ChainOfThoughtItem,
 } from './components/chain-of-thought';
+export type {
+  ChainOfThoughtProps, ChainOfThoughtStepProps, ChainOfThoughtTriggerProps,
+  ChainOfThoughtContentProps, ChainOfThoughtItemProps,
+  ChainOfThoughtType, ChainOfThoughtStepData, ChainOfThoughtController,
+} from './components/chain-of-thought';
 export { Source, SourceTrigger, SourceContent, SourceList } from './components/source';
+export type { SourceProps, SourceTriggerProps, SourceContentProps, SourceListProps } from './components/source';
 export { PromptSuggestion } from './components/prompt-suggestion';
+export type { PromptSuggestionProps } from './components/prompt-suggestion';
 export {
   Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent, emptyMediaVariants,
 } from './components/empty';
@@ -230,7 +300,9 @@ export type {
   EmptyProps, EmptyHeaderProps, EmptyMediaProps, EmptyTitleProps, EmptyDescriptionProps, EmptyContentProps,
 } from './components/empty';
 export { ScrollButton } from './components/scroll-button';
+export type { ScrollButtonProps } from './components/scroll-button';
 export { TextShimmer } from './components/text-shimmer';
+export type { TextShimmerProps } from './components/text-shimmer';
 export { Checkpoint, CheckpointIcon, CheckpointTrigger } from './components/checkpoint';
 export type { CheckpointProps, CheckpointIconProps, CheckpointTriggerProps } from './components/checkpoint';
 export {
@@ -253,14 +325,29 @@ export type {
   ContextContentBodyProps,
   ContextContentFooterProps,
   ContextUsageRowProps,
+  ContextInputUsageProps,
+  ContextOutputUsageProps,
+  ContextReasoningUsageProps,
+  ContextCacheUsageProps,
 } from './components/context';
 export { VoiceInput } from './components/voice-input';
+export type { VoiceInputProps, VoiceInputController } from './components/voice-input';
 export { ConversationList } from './components/conversation-list';
+export type { ConversationListProps, ConversationListController } from './components/conversation-list';
 export { ConversationItem } from './components/conversation-item';
+export type { ConversationItemProps } from './components/conversation-item';
 export { ModelSwitcher } from './components/model-switcher';
+export type { ModelSwitcherProps } from './components/model-switcher';
 export { ChatScopePicker } from './components/chat-scope-picker';
+export type { ChatScopePickerProps } from './components/chat-scope-picker';
 export { Tool } from './components/tool';
 export type { ToolPart, ToolProps } from './components/tool';
+// ToolPart.kind's doc comment says "Derive with `classifyTool(type)`", so the
+// function has to be reachable from every entry that surfaces ToolPart. It is
+// total, deterministic and terminates in 'generic', so it is safe public API and
+// genuinely useful to anyone rendering tool calls themselves.
+export { classifyTool } from './components/tool-classify';
+export type { ToolKind } from './components/tool-classify';
 export { ThinkingBar } from './components/thinking-bar';
 export type { ThinkingBarProps } from './components/thinking-bar';
 export { Reasoning, ReasoningTrigger, ReasoningContent } from './components/reasoning';
@@ -283,4 +370,52 @@ export type {
 } from './components/attachments';
 
 // Chat message types — public API for consumers who need to type their own message arrays.
-export type { ChatMessage, ChatMessageAction, CustomAction, AvatarData, FeedbackVote } from './elements/chat-types';
+// NOTE: chat-types.ts also exports an unrelated `Source` interface (a citation), and
+// `Source` is already a public component export (./components/source, a citation
+// chip/trigger), so re-exporting both under that name is a duplicate-identifier error.
+// The citation type therefore ships under its alias `MessageSource`, which is also the
+// argument type of the public `AssistantStream.addSource(source)`.
+export type {
+  ChatMessage, ChatMessageAction, CustomAction, AvatarData, FeedbackVote, MessagePart,
+  MessageSource, RawOrigin,
+} from './elements/chat-types';
+
+// Composer document model. This belongs on "." rather than "./solid" because it
+// is part of the ELEMENT contract, not the Solid-only surface: `ComposerDoc` is
+// the non-string half of `kai-prompt-input` / `kai-composer` / `kai-default-input`'s
+// `value` property, and `doc` + `entities` on their `kai-submit` /
+// `kai-value-change` details. The shipped prop docs name `ComposerDoc` by name,
+// so a React or Vue consumer reading them has to be able to import it. Type-only,
+// so it is erased by the build and costs the root barrel nothing.
+export type { ComposerDoc, Segment, EntityRef } from './primitives/composer-model';
+
+// ---------------------------------------------------------------------------
+// Named types for the remaining kai-* array/object PROPERTIES.
+//
+// Same rationale as `ComposerDoc` above, applied to the whole class instead of
+// one instance: the generated `./elements` declarations and React wrappers expand
+// every prop type structurally (deliberately — see the `IMPORTS = {}` note in
+// scripts/gen-element-api.mjs), so a consumer who wants to NAME the shape had to
+// write `NonNullable<KaiPromptInputElementProps['triggers']>`. Every element-prop
+// type that has a name in source is now reachable from "." — the entry a React /
+// Vue / Svelte / vanilla consumer imports — not only from "./solid".
+//
+// Type-only, so the root barrel pays nothing at runtime.
+// Guarded by tests/elements/prop-types-exported.test.ts, which re-derives the
+// list from the facades with the TS checker and fails on a new unexported one.
+// ---------------------------------------------------------------------------
+export type { TriggerDef, TriggerItem } from './components/composer';
+export type { ChatThreadContextUsage } from './components/chat-thread';
+export type { Skill } from './components/message-skills';
+export type { AgentStatus } from './ui/agent-card';
+export type { KaiNavItem } from './ui/nav';
+export type { KaiTabItem } from './ui/tabs';
+export type { PaneStatus } from './ui/pane';
+export type { PaneTab } from './ui/pane-group';
+export type {
+  KaiCommandItem, KaiContextUsage, KaiMenuItem, KaiSegmentedOption, KaiSourceItem,
+} from './elements/element-data-types';
+// `kai-audio-visualizer.shader` takes a ShaderSpec. The element arrived from main
+// after this block was written, and prop-types-exported.test.ts caught it, which
+// is the point of deriving that list from the facades rather than maintaining it.
+export type { ShaderSpec } from './components/audio-visualizer';

package/src/primitives/card-component-types.ts

@@ -0,0 +1,63 @@
+// src/primitives/card-component-types.ts
+// `CardEnvelope.type` -> the Solid component that renders it, as a TYPE.
+//
+// TYPES ONLY, AND THAT IS THE WHOLE FILE. `BUILTIN_CARD_COMPONENTS` and
+// `mergeCardComponents` stay in card-registry.tsx and cannot follow them here: they
+// ARE JSX. So this is not the same split card-tags.ts made — that one moved data and
+// its type; this one moves only the type, because the value half has nowhere else to
+// go. Do not try to "finish" the symmetry by dragging the component map over.
+//
+// WHY THE TYPES ARE ALONE IN A `.ts`
+// ----------------------------------
+// The same reason, one layer along, that card-tags.ts exists — read that file's header
+// first; this is the second instance of its problem, not a new one.
+//
+// `@kitn.ai/ui/schemas` is the server-safe entry, and src/schemas/registry.ts declares
+// `CustomCardSpec.component` and `CardRegistry.components` in terms of
+// `CardComponentMap`. That is a TYPE import and erases at runtime, but a type import
+// still has to RESOLVE, and while these two types lived in card-registry.tsx it
+// resolved to a `.tsx`. tsconfig.mcp.json has no `jsx` on purpose, so the `kai` MCP's
+// typecheck pass reported, on any tree that had not been built:
+//
+//   src/schemas/registry.ts(61,51): error TS6142: Module '../primitives/card-registry'
+//   was resolved to '.../card-registry.tsx', but '--jsx' is not set.
+//
+// Exactly one error, and the last one standing on an unbuilt tree. Moving the two type
+// aliases into this file takes that pass to 0. Measured on this tree, both directions.
+//
+// Relaxing tsconfig.mcp.json instead is not an option, and that is measured too, not
+// recalled: giving that project `jsx: "preserve"` + `jsxImportSource: "solid-js"` —
+// the settings the main tsconfig.json actually uses — takes it from 1 error to 130,
+// almost all `TS2304: Cannot find name 'HTMLDivElement' / 'window'`, because a `jsx`
+// setting drags the whole Solid component tree into a Node-only, `lib: ["ESNext"]`
+// pass. (`jsx: "preserve"` with no import source is worse still: 838.) card-tags.ts
+// records 1364 for the broader case. The figures differ because the reachable set
+// differs; the conclusion does not. The Node/no-DOM boundary is load-bearing.
+//
+// `import type { Component } from 'solid-js'` below does NOT reintroduce the problem
+// it just solved. Type-importing from solid-js resolves to a `.d.ts`, and a
+// declaration file needs no `jsx` to be read; `skipLibCheck` covers what is inside it.
+// It is resolving a `.tsx` SOURCE file that TS6142 objects to, and this file resolves
+// none.
+//
+// WHAT THIS SPLIT DOES NOT DO
+// ---------------------------
+// It changes nothing at runtime, and must not be sold as if it did. This module is
+// types only, so it compiles to nothing and there is no emitted module to compare:
+// `verify:ssr` and `verify:schemas` read the BUILT entry and cannot tell the two
+// arrangements apart even in principle. card-tags.ts records the same finding for its
+// own case from the harder direction, where there WAS a bundle to diff and it came out
+// byte-identical. The boundary this file defends is a compile-time one. The
+// discriminating check is `tsc --noEmit -p tsconfig.mcp.json` on an UNBUILT tree, and
+// nothing else is evidence for it.
+
+import type { Component } from 'solid-js';
+import type { CardEnvelope, CardHost } from './card-contract';
+
+/** Solid renderer for one envelope. `host` is the resolved CardHost so each wrapper
+ *  can bridge its card's emit convention (form/confirm/tasks take `host`;
+ *  link/embed take `onEmit`). */
+export type CardComponent = Component<{ envelope: CardEnvelope; host?: CardHost }>;
+
+/** Solid layer: envelope type → the component that draws it. */
+export type CardComponentMap = Record<string, CardComponent>;