@kitnai/chat 0.7.0 → 0.8.0

package/src/elements/styles.css

@@ -10,9 +10,17 @@
   :host { display: block; }
   * { border-color: var(--color-border); }
 
+  /* Native controls (date/time pickers, <select>, number spinners, the
+     checkbox/radio fallbacks, scrollbars) must follow the kit's light/dark
+     mode — NOT the OS — so e.g. the native calendar icon never renders black
+     on a dark surface. `color-scheme` drives that native rendering; we set it
+     from the resolved mode (the `.dark` scope the element factory toggles). */
+  :host { color-scheme: light; }
+  .dark { color-scheme: dark; }
+
   /* One token-driven focus ring for EVERY focusable element in the shadow root.
      Blue by default (via --color-ring), consistent in light + dark, and
-     overridable through --kitn-color-ring. Uses `outline` (not a box-shadow
+     overridable through --kc-color-ring. Uses `outline` (not a box-shadow
      ring) so it never clips on overflow and follows the element's radius;
      `:focus-visible` so it only appears for keyboard navigation, never on a
      mouse click. Components that render their own ring set
@@ -45,3 +53,134 @@
   *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
   *::-webkit-scrollbar-corner { background: transparent; }
 }
+
+@layer components {
+  /* Designed radio + checkbox (appearance-none) so the form controls read as
+     intentional, theme correctly in light/dark, and have comfortable targets —
+     replacing the weak native defaults. Used via `.kc-radio` / `.kc-checkbox`. */
+  .kc-radio,
+  .kc-checkbox {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    margin: 0;
+    flex-shrink: 0;
+    cursor: pointer;
+    border: 1.5px solid var(--color-input);
+    background-color: var(--color-background);
+    display: inline-grid;
+    place-content: center;
+    box-shadow: 0 1px 2px rgb(0 0 0 / 0.04);
+    transition: border-color 0.18s ease, background-color 0.18s ease, box-shadow 0.18s ease,
+      transform 0.1s ease;
+  }
+  .kc-radio { border-radius: 9999px; }
+  .kc-checkbox { border-radius: 0.3rem; }
+  .kc-radio::after {
+    content: "";
+    inline-size: 0.5rem;
+    block-size: 0.5rem;
+    border-radius: 9999px;
+    background-color: var(--color-primary);
+    transform: scale(0);
+    transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+  .kc-radio:checked { border-color: var(--color-primary); }
+  .kc-radio:checked::after { transform: scale(1); }
+  .kc-checkbox:checked {
+    background-color: var(--color-primary);
+    border-color: var(--color-primary);
+  }
+  .kc-checkbox::after {
+    content: "";
+    inline-size: 0.8rem;
+    block-size: 0.8rem;
+    background-color: var(--color-primary-foreground);
+    transform: scale(0);
+    transition: transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+    -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E") center / contain no-repeat;
+    mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E") center / contain no-repeat;
+  }
+  .kc-checkbox:checked::after { transform: scale(1); }
+  .kc-radio:hover:not(:disabled),
+  .kc-checkbox:hover:not(:disabled) {
+    border-color: var(--color-primary);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--color-primary) 9%, transparent);
+  }
+  .kc-radio:active:not(:disabled),
+  .kc-checkbox:active:not(:disabled) { transform: scale(0.92); }
+  .kc-checkbox:checked {
+    box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
+  }
+  .kc-radio:disabled,
+  .kc-checkbox:disabled { opacity: 0.5; cursor: not-allowed; }
+
+  /* Custom range slider: a filled track (--kc-range-fill set by the widget) and a
+     refined thumb that scales on hover/press with a focus halo — no native chrome. */
+  .kc-range {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 100%;
+    block-size: 1.25rem;
+    background: transparent;
+    cursor: pointer;
+    margin: 0;
+  }
+  .kc-range::-webkit-slider-runnable-track {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    border: none;
+    box-shadow: none;
+    background: linear-gradient(
+      to right,
+      var(--color-primary) var(--kc-range-fill, 0%),
+      var(--color-muted) var(--kc-range-fill, 0%)
+    );
+  }
+  .kc-range::-moz-range-track {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    border: none;
+    box-shadow: none;
+    background: var(--color-muted);
+  }
+  .kc-range::-moz-range-progress {
+    block-size: 0.375rem;
+    border-radius: 9999px;
+    background: var(--color-primary);
+  }
+  .kc-range::-webkit-slider-thumb {
+    appearance: none;
+    -webkit-appearance: none;
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    border-radius: 9999px;
+    background: var(--color-background);
+    border: 2px solid var(--color-primary);
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.18);
+    margin-block-start: -0.375rem;
+    transition: transform 0.12s ease, box-shadow 0.12s ease;
+  }
+  .kc-range::-moz-range-thumb {
+    inline-size: 1.125rem;
+    block-size: 1.125rem;
+    border-radius: 9999px;
+    background: var(--color-background);
+    border: 2px solid var(--color-primary);
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.18);
+    transition: transform 0.12s ease, box-shadow 0.12s ease;
+  }
+  .kc-range:hover::-webkit-slider-thumb { transform: scale(1.12); }
+  .kc-range:hover::-moz-range-thumb { transform: scale(1.12); }
+  .kc-range:focus-visible { outline: none; }
+  .kc-range:focus-visible::-webkit-slider-thumb,
+  .kc-range:active::-webkit-slider-thumb {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-primary) 14%, transparent);
+  }
+  .kc-range:focus-visible::-moz-range-thumb,
+  .kc-range:active::-moz-range-thumb {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-primary) 14%, transparent);
+  }
+  .kc-range:disabled { opacity: 0.5; cursor: not-allowed; }
+}

package/src/elements/task-list-card.stories.tsx

@@ -0,0 +1,194 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './task-list-card';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { TaskListCardData } from '../components/task-list-card';
+import type { CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-task-list': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type TaskListEl = HTMLElement & { data?: TaskListCardData };
+
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '460px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kc-task-list>, sets `.data`, logs the emitted CardEvent under the render. */
+function TaskListDemo(props: { def: TaskListCardData; cardId: string; heading?: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: TaskListEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.data = props.def;
+    el.addEventListener('kc-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kc-task-list ref={(e) => (el = e as TaskListEl)} card-id={props.cardId} heading={props.heading} />
+        <pre
+          style={{
+            margin: 0,
+            'max-height': '180px',
+            overflow: 'auto',
+            background: 'var(--color-muted, #f4f4f5)',
+            'border-radius': '8px',
+            padding: '8px',
+            'font-size': '12px',
+          }}
+        >
+          {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+        </pre>
+      </div>
+    </Frame>
+  );
+}
+
+const PLAN: TaskListCardData = {
+  mode: 'select',
+  selectAll: true,
+  confirmLabel: 'Run selected',
+  tasks: [
+    { id: 'lint', label: 'Run linter', checked: true },
+    { id: 'test', label: 'Run unit tests', checked: true },
+    { id: 'build', label: 'Build production bundle' },
+    { id: 'deploy', label: 'Deploy to staging', description: 'Reversible; staging only' },
+  ],
+};
+
+const REQUIRE_ONE: TaskListCardData = {
+  confirmLabel: 'Apply',
+  allowEmpty: false,
+  tasks: [
+    { id: 'cache', label: 'Clear the CDN cache' },
+    { id: 'reindex', label: 'Rebuild the search index' },
+    { id: 'restart', label: 'Restart the workers' },
+  ],
+};
+
+const BOUNDED: TaskListCardData = {
+  heading: 'Pick up to 2 reviewers',
+  confirmLabel: 'Request review',
+  min: 1,
+  max: 2,
+  tasks: [
+    { id: 'ana', label: 'Ana' },
+    { id: 'ben', label: 'Ben' },
+    { id: 'cat', label: 'Cat' },
+    { id: 'dan', label: 'Dan' },
+  ],
+};
+
+const WITH_DESCRIPTIONS: TaskListCardData = {
+  selectAll: true,
+  confirmLabel: 'Run cleanup',
+  tasks: [
+    { id: 'tmp', label: 'Delete temp files', description: 'Frees ~2.1 GB; safe to remove' },
+    { id: 'logs', label: 'Rotate logs', description: 'Archives logs older than 30 days' },
+    { id: 'orphans', label: 'Prune orphaned blobs', description: 'Unreferenced uploads only' },
+  ],
+};
+
+const HEADING_MAP: Record<string, string | undefined> = {
+  'card-plan': 'Approve the plan steps',
+  'card-require': 'Choose maintenance steps',
+  'card-bounded': undefined,
+  'card-desc': 'Storage cleanup',
+};
+
+const HTML_SNIPPET = (def: TaskListCardData, cardId: string) => {
+  const heading = HEADING_MAP[cardId];
+  return `<kc-task-list${heading ? ` heading="${heading}"` : ''}></kc-task-list>
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const el = document.querySelector('kc-task-list');
+  // \`data\` is the CardEnvelope.data (set as a property).
+  el.data = ${JSON.stringify(def, null, 2)};
+
+  // Toggling rows is local; only CONFIRM emits — a single bubbling \`kc-card\` event.
+  el.addEventListener('kc-card', (e) => {
+    const ev = e.detail; // { kind:'submit-data', cardId, data:{ selected } } | ...
+    if (ev.kind === 'submit-data') console.log('selected', ev.data.selected);
+  });
+</script>`;
+};
+
+const meta = {
+  title: 'Generative UI/Cards/kc-task-list',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-task-list'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-task-list', [
+        "`<kc-task-list>` is a **selectable** task/plan list (set via the `data` **property**): checkbox rows + an optional select-all + a confirm button. The user picks a subset, confirms, and the card emits the Card contract's **`submit-data`** verb up a bubbling **`kc-card`** CustomEvent of `{ kind: 'submit-data', cardId, data: { selected } }` — the checked ids in **input order**. Toggling rows is local UI state; **only the final confirm emits** (the wire stays quiet, the result atomic).",
+        '**Gating:** confirm is enabled when `selectedCount >= (min ?? (allowEmpty ? 0 : 1))` and `<= (max ?? ∞)`. Select-all checks every toggleable (non-`disabled`) row and shows an **indeterminate** (`aria-checked="mixed"`) state when only some are checked. When `max` is reached, unchecked rows become non-toggleable. v1 is **select/approve only** (a future `mode:\'progress\'` is reserved in the schema).',
+        '**Events** (all frozen Card-contract verbs): `ready` on mount, `submit-data` on confirm, `error` for a malformed definition (renders the inline `kc-card` error). It **never invents events**. The same shapes flow over the remote iframe transport unchanged.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Select a plan (select-all on, a few pre-checked). */
+export const SelectAPlan: Story = {
+  render: () => <TaskListDemo def={PLAN} cardId="card-plan" heading="Approve the plan steps" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(PLAN, 'card-plan'), language: 'html' } } },
+};
+
+/** Require at least one (`allowEmpty:false`, the default) — confirm stays disabled until a row is checked. */
+export const RequireAtLeastOne: Story = {
+  render: () => <TaskListDemo def={REQUIRE_ONE} cardId="card-require" heading="Choose maintenance steps" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(REQUIRE_ONE, 'card-require'), language: 'html' } } },
+};
+
+/** Bounded (`min`/`max`) — confirm gating + max-reached row disabling. */
+export const Bounded: Story = {
+  render: () => <TaskListDemo def={BOUNDED} cardId="card-bounded" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(BOUNDED, 'card-bounded'), language: 'html' } } },
+};
+
+/** Rows with secondary descriptions (linked via aria-describedby). */
+export const WithDescriptions: Story = {
+  render: () => <TaskListDemo def={WITH_DESCRIPTIONS} cardId="card-desc" heading="Storage cleanup" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(WITH_DESCRIPTIONS, 'card-desc'), language: 'html' } } },
+};
+
+/** A malformed `data` (empty `tasks`) → the inline error state + an `error` event. */
+export const ErrorState: Story = {
+  render: () => <TaskListDemo def={{ tasks: [] } as unknown as TaskListCardData} cardId="card-bad" />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<kc-task-list></kc-task-list>
+<script type="module">
+  import '@kitnai/chat/elements';
+  const el = document.querySelector('kc-task-list');
+  // No tasks → inline error state + an \`error\` event.
+  el.data = { tasks: [] };
+  el.addEventListener('kc-card', (e) => {
+    if (e.detail.kind === 'error') console.warn('task-list error:', e.detail.message);
+  });
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/task-list-card.tsx

@@ -0,0 +1,40 @@
+import { defineWebComponent } from './define';
+import { TaskListCard, type TaskListCardData } from '../components/task-list-card';
+
+interface Props extends Record<string, unknown> {
+  /** The task-list definition (the CardEnvelope.data). Set as a JS PROPERTY:
+   *  `el.data = { tasks:[…], selectAll, confirmLabel, … }`. Import
+   *  `TaskListCardData` from `@kitnai/chat` for the full shape. */
+  data?: Record<string, unknown>;
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+}
+
+/**
+ * `<kc-task-list>` — a **selectable** task/plan list (set via the `data` property):
+ * checkbox rows + an optional select-all + a confirm button. Toggling rows is local
+ * UI state; only the final confirm emits the Card contract's **`submit-data`** verb
+ * up a bubbling **`kc-card`** CustomEvent (`{ kind:'submit-data', cardId,
+ * data:{ selected } }`) with the checked ids in input order. Also emits `ready` on
+ * mount and `error` for a malformed definition (inline error). v1 = select/approve
+ * mode only. Routes through a `CardProvider` when present, else the bubbling
+ * `kc-card` event. Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ */
+defineWebComponent<Props>(
+  'kc-task-list',
+  {
+    data: undefined,
+    cardId: undefined,
+    heading: undefined,
+  },
+  (props, { element }) => (
+    <TaskListCard
+      data={props.data as TaskListCardData | undefined}
+      cardId={props.cardId ?? (element.id || 'kc-task-list')}
+      heading={props.heading}
+      hostElement={element}
+    />
+  ),
+);

package/src/elements/{kitn-text-shimmer.stories.tsx → text-shimmer.stories.tsx}

@@ -1,14 +1,13 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-text-shimmer': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-text-shimmer': JSX.HTMLAttributes<HTMLElement> & {
         text?: string;
         duration?: number;
         spread?: number;
@@ -18,27 +17,25 @@ declare module 'solid-js' {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-text-shimmer text="Thinking…" duration="3" spread="20"></kitn-text-shimmer>
+<kc-text-shimmer text="Thinking…" duration="3" spread="20"></kc-text-shimmer>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-text-shimmer',
+  title: 'Web Components/kc-text-shimmer',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-text-shimmer'),
+  argTypes: argTypesFor('kc-text-shimmer'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-text-shimmer>` is the framework-agnostic **web component** for animated shimmering text — a gradient sweep across a label, isolated in **Shadow DOM**.',
+      description: specDescription('kc-text-shimmer', [
+          '`<kc-text-shimmer>` is the framework-agnostic **web component** for animated shimmering text — a gradient sweep across a label, isolated in **Shadow DOM**.',
           '**When to use:** signalling a quiet, in-progress state ("Thinking…", "Generating…") inline. In SolidJS, use the `TextShimmer` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` attribute, and tune `duration` (seconds) and `spread` (gradient width, 5–45).",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -46,17 +43,11 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-text-shimmer" />,
-  parameters: { layout: 'padded' },
-};
-
 /** Default shimmer. */
 export const Default: Story = {
   render: () => (
     <div style={{ padding: '24px', 'font-size': '18px' }}>
-      <kitn-text-shimmer text="Thinking…" />
+      <kc-text-shimmer text="Thinking…" />
     </div>
   ),
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
@@ -66,7 +57,7 @@ export const Default: Story = {
 export const Tuned: Story = {
   render: () => (
     <div style={{ padding: '24px', 'font-size': '18px' }}>
-      <kitn-text-shimmer text="Generating response…" duration={2} spread={35} />
+      <kc-text-shimmer text="Generating response…" duration={2} spread={35} />
     </div>
   ),
 };

package/src/elements/text-shimmer.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { TextShimmer } from '../components/text-shimmer';
 
 interface Props extends Record<string, unknown> {
@@ -13,10 +13,10 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-text-shimmer>` — animated shimmering text. Text via the `text`
+ * `<kc-text-shimmer>` — animated shimmering text. Text via the `text`
  * attribute; `duration`/`spread` tune the effect.
  */
-defineKitnElement<Props>('kitn-text-shimmer', {
+defineWebComponent<Props>('kc-text-shimmer', {
   text: '',
   as: 'span',
   duration: 4,

package/src/elements/{kitn-thinking-bar.stories.tsx → thinking-bar.stories.tsx}

@@ -1,14 +1,13 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-thinking-bar': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-thinking-bar': JSX.HTMLAttributes<HTMLElement> & {
         text?: string;
         stoppable?: boolean | string;
         'stop-label'?: string;
@@ -19,30 +18,28 @@ declare module 'solid-js' {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-thinking-bar text="Thinking" stoppable stop-label="Answer now"></kitn-thinking-bar>
+<kc-thinking-bar text="Thinking" stoppable stop-label="Answer now"></kc-thinking-bar>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 
-  document.querySelector('kitn-thinking-bar')
+  document.querySelector('kc-thinking-bar')
     .addEventListener('stop', () => console.log('user asked to stop'));
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-thinking-bar',
+  title: 'Web Components/kc-thinking-bar',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-thinking-bar'),
+  argTypes: argTypesFor('kc-thinking-bar'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-thinking-bar>` is the framework-agnostic **web component** for an animated "thinking" indicator with an optional stop affordance — a pure leaf element isolated in **Shadow DOM**. (`<kitn-chat>` does not surface this; compose it yourself.)',
+      description: specDescription('kc-thinking-bar', [
+          '`<kc-thinking-bar>` is the framework-agnostic **web component** for an animated "thinking" indicator with an optional stop affordance — a pure leaf element isolated in **Shadow DOM**. (`<kc-chat>` does not surface this; compose it yourself.)',
           '**When to use:** showing that the assistant is reasoning, optionally letting the user interrupt with "Answer now". In SolidJS, use the `ThinkingBar` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text`/`stop-label` attributes, add the `stoppable` flag to show the stop button, and listen for the `stop` **CustomEvent**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -50,17 +47,11 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-thinking-bar" />,
-  parameters: { layout: 'padded' },
-};
-
 /** A plain thinking indicator. */
 export const Default: Story = {
   render: () => (
     <div style={{ padding: '24px' }}>
-      <kitn-thinking-bar text="Thinking" />
+      <kc-thinking-bar text="Thinking" />
     </div>
   ),
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
@@ -70,7 +61,7 @@ export const Default: Story = {
 export const Stoppable: Story = {
   render: () => (
     <div style={{ padding: '24px' }}>
-      <kitn-thinking-bar
+      <kc-thinking-bar
         text="Reasoning"
         stoppable
         stop-label="Answer now"

package/src/elements/thinking-bar.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ThinkingBar } from '../components/thinking-bar';
 
 interface Props extends Record<string, unknown> {
@@ -10,18 +10,18 @@ interface Props extends Record<string, unknown> {
   stopLabel?: string;
 }
 
-/** Events fired by `<kitn-thinking-bar>`. */
+/** Events fired by `<kc-thinking-bar>`. */
 interface Events {
   /** The "stop / answer now" affordance was clicked. */
   stop: void;
 }
 
 /**
- * `<kitn-thinking-bar>` — a pure leaf element: an animated "thinking" indicator
- * (one of the primitives the batteries-included `<kitn-chat>` does NOT surface).
+ * `<kc-thinking-bar>` — a pure leaf element: an animated "thinking" indicator
+ * (one of the primitives the batteries-included `<kc-chat>` does NOT surface).
  * Config via attributes, the only interaction (`stop`) comes back as an event.
  */
-defineKitnElement<Props, Events>('kitn-thinking-bar', {
+defineWebComponent<Props, Events>('kc-thinking-bar', {
   text: 'Thinking',
   stoppable: false,
   stopLabel: 'Answer now',