@kitnai/chat 0.6.0 → 0.8.0

package/src/elements/embed.stories.tsx

@@ -0,0 +1,197 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount, onCleanup, type JSX } from 'solid-js';
+import './embed'; // side effect: registers <kc-embed>
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { EmbedCardData } from '../primitives/embed-providers';
+import { configureEmbedAllowlist } from '../primitives/embed-providers';
+
+// Custom DOM element — declare the tag for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-embed': JSX.HTMLAttributes<HTMLElement> & {
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+/** A sized box the embed sits in. */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ width: '100%', 'max-width': '560px' }}>{props.children}</div>;
+}
+
+/** Mount a kc-embed, set its `data` property, and route `open` to a console log. */
+function Embed(props: { cardId: string; data: EmbedCardData }) {
+  let el: HTMLElement & { cardId?: string; data?: EmbedCardData };
+  const onCard = (e: Event) => {
+    const ev = (e as CustomEvent).detail;
+    // eslint-disable-next-line no-console
+    console.log('[kc-card]', ev);
+    if (ev.kind === 'open' && ev.target === 'tab') {
+      window.open(ev.url, '_blank', 'noopener,noreferrer');
+    }
+  };
+  onMount(() => {
+    if (el) {
+      el.cardId = props.cardId;
+      el.data = props.data;
+    }
+    document.addEventListener('kc-card', onCard);
+    onCleanup(() => document.removeEventListener('kc-card', onCard));
+  });
+  return (
+    <Frame>
+      <kc-embed ref={(e) => (el = e as HTMLElement & { cardId?: string; data?: EmbedCardData })} />
+    </Frame>
+  );
+}
+
+const YT_ENVELOPE = {
+  type: 'embed',
+  id: 'card-embed-1',
+  title: 'Intro video',
+  data: { provider: 'youtube', id: 'dQw4w9WgXcQ', title: 'Product intro', aspectRatio: '16:9' },
+} satisfies { type: string; id: string; title: string; data: EmbedCardData };
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kc-embed id="em"></kc-embed>
+
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const em = document.getElementById('em');
+  em.cardId = 'card-embed-1';
+  // \`data\` is a JS property (the CardEnvelope \`data\`):
+  em.data = { provider: 'youtube', id: 'dQw4w9WgXcQ', title: 'Product intro' };
+
+  // NO network to YouTube until the user clicks play (privacy-first lazy facade).
+  // The optional "Open on YouTube" affordance bubbles a composed \`kc-card\` open event:
+  document.addEventListener('kc-card', (e) => {
+    const ev = e.detail;
+    if (ev.kind === 'open' && ev.target === 'tab') {
+      window.open(ev.url, '_blank', 'noopener,noreferrer');
+    }
+  });
+</script>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kc-embed',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-embed'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-embed', [
+        '`<kc-embed>` is a **privacy-first lazy media embed** (YouTube / Vimeo / allowlisted generic player) for the generative-UI feature. It speaks the **Card Contract**: data down (an `embed` `CardEnvelope`), events up (only the `open` verb, plus lifecycle `ready` / failure `error`).',
+        '**Lazy facade:** the initial render is just a **poster + play button** — NO provider iframe, NO third-party JS, NO cookies until the user clicks play. YouTube loads via `youtube-nocookie.com`; Vimeo with `dnt=1`. This buys privacy (no tracking until opt-in) and performance (no player JS on load).',
+        '**Security:** `generic` embeds frame an arbitrary https URL, so they are **rejected unless the app allowlists their origin** with `configureEmbedAllowlist([...])` (defaults to empty — an agent cannot frame an arbitrary origin). The player iframe is sandboxed for a *trusted provider* (`allow-scripts allow-same-origin` on a cross-origin player) — contrast `<kc-artifact>`, which trusts nothing.',
+        '**Never a dead end:** a persistent "Open on {provider}" affordance dispatches the `open` verb (so a provider that refuses framing still has a way out). Set `data` as a JS property; `card-id` via attribute.',
+        'See the **Code** tab for the `CardEnvelope` JSON + HTML wiring.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** YouTube (lazy) — poster + play; the iframe loads (youtube-nocookie) only on click. */
+export const YouTube: Story = {
+  name: 'YouTube (lazy)',
+  render: () => <Embed cardId={YT_ENVELOPE.id} data={YT_ENVELOPE.data} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Vimeo — supply a `poster` (Vimeo has no static thumbnail URL). */
+export const Vimeo: Story = {
+  render: () => (
+    <Embed
+      cardId="card-embed-2"
+      data={{
+        provider: 'vimeo',
+        id: '76979871',
+        title: 'Vimeo staff pick',
+        poster: 'https://placehold.co/1280x720/1ab7ea/ffffff/png?text=Vimeo',
+      }}
+    />
+  ),
+};
+
+/** Generic player — an https embed URL whose origin the app has allowlisted. */
+export const Generic: Story = {
+  name: 'Generic player',
+  render: () => {
+    configureEmbedAllowlist(['https://www.youtube-nocookie.com']);
+    return (
+      <Embed
+        cardId="card-embed-3"
+        data={{
+          provider: 'generic',
+          url: 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ',
+          title: 'Generic embed',
+          poster: 'https://placehold.co/1280x720/444/fff/png?text=Generic+player',
+        }}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `import { configureEmbedAllowlist } from '@kitnai/chat';
+
+// Generic embeds are blocked by default — allowlist the trusted origin first:
+configureEmbedAllowlist(['https://your-player.example.com']);
+
+em.data = {
+  provider: 'generic',
+  url: 'https://your-player.example.com/embed/abc',
+  title: 'Generic embed',
+  poster: 'https://your-cdn.example.com/poster.jpg',
+};`,
+        language: 'ts',
+      },
+    },
+  },
+};
+
+/** Custom aspect ratio — a vertical 9:16 short. */
+export const CustomAspectRatio: Story = {
+  name: 'Custom aspect ratio (9:16)',
+  render: () => (
+    <div style={{ width: '100%', 'max-width': '280px' }}>
+      <EmbedRaw
+        cardId="card-embed-4"
+        data={{ provider: 'youtube', id: 'dQw4w9WgXcQ', title: 'Short', aspectRatio: '9:16' }}
+      />
+    </div>
+  ),
+};
+
+/** Blocked-embed fallback — the "Open on provider" affordance is always present. */
+export const BlockedFallback: Story = {
+  name: 'Blocked-embed fallback',
+  render: () => <Embed cardId="card-embed-5" data={{ provider: 'youtube', id: 'dQw4w9WgXcQ', title: 'Maybe blocked' }} />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Some providers refuse framing (X-Frame-Options / CSP `frame-ancestors`). We can\'t detect that cross-origin in JS, so the **"Open on {provider}"** affordance is *always* available — a blocked embed is never a dead end.',
+      },
+    },
+  },
+};
+
+// A frame-less variant so the 9:16 story controls its own width.
+function EmbedRaw(props: { cardId: string; data: EmbedCardData }) {
+  let el: HTMLElement & { cardId?: string; data?: EmbedCardData };
+  onMount(() => {
+    if (el) {
+      el.cardId = props.cardId;
+      el.data = props.data;
+    }
+  });
+  return <kc-embed ref={(e) => (el = e as HTMLElement & { cardId?: string; data?: EmbedCardData })} />;
+}

package/src/elements/embed.tsx

@@ -0,0 +1,35 @@
+import { defineWebComponent } from './define';
+import { Embed } from '../components/embed';
+import type { EmbedCardData } from '../primitives/embed-providers';
+import { emitCardEvent } from '../primitives/card-routing';
+
+interface Props extends Record<string, unknown> {
+  /** Stable card id correlating every emitted event. Set as an attribute or property. */
+  cardId?: string;
+  /** The embed payload (provider + id/url + options). Set as a JS **property** (object). */
+  data?: EmbedCardData;
+}
+
+/**
+ * `<kc-embed>` — a privacy-first **lazy media embed** (YouTube / Vimeo / allowlisted
+ * generic player). Initial render is a poster + play button: NO provider iframe, JS,
+ * or cookies until the user clicks play (YouTube via `youtube-nocookie`, Vimeo with
+ * `dnt=1`). A persistent "Open on {provider}" affordance dispatches the contract
+ * `open` verb via the bubbling `kc-card` event. `generic` URLs are rejected unless
+ * their origin was allowlisted with `configureEmbedAllowlist`. Set `data` as a JS
+ * property; `card-id` via attribute.
+ */
+defineWebComponent<Props>(
+  'kc-embed',
+  {
+    cardId: undefined,
+    data: undefined,
+  },
+  (props, { element }) => (
+    <Embed
+      cardId={props.cardId ?? ''}
+      data={props.data ?? ({ provider: 'generic' } as EmbedCardData)}
+      onEmit={(event) => emitCardEvent(element, event)}
+    />
+  ),
+);

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

@@ -1,19 +1,20 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+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-empty': JSX.HTMLAttributes<HTMLElement>;
+      'kc-empty': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-empty
+<kc-empty
   empty-title="No conversations yet"
   description="Start a new chat to see it appear here."
 >
@@ -37,26 +38,25 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
     </svg>
     New chat
   </button>
-</kitn-empty>
+</kc-empty>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-empty',
+  title: 'Web Components/kc-empty',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-empty'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-empty>` is the framework-agnostic **web component** for an empty-state block — an icon, a title, a description, and actions — isolated in **Shadow DOM**.',
+      description: specDescription('kc-empty', [
+          '`<kc-empty>` is the framework-agnostic **web component** for an empty-state block — an icon, a title, a description, and actions — isolated in **Shadow DOM**.',
           '**When to use:** placeholder UI for an empty list/thread in a non-Solid app. In SolidJS, compose the `Empty*` primitives.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set `empty-title` (note `empty-title`, not `title`) and `description` via attributes, and use the **slots** (\"Route 2\") to project your own icon (`slot=\"media\"`) and actions (the default slot).",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -64,7 +64,7 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Render the actual `<kitn-empty>` custom element with slotted children. */
+/** Render the actual `<kc-empty>` custom element with slotted children. */
 function EmptyElement() {
   let el: HTMLElement | undefined;
   onMount(() => {
@@ -73,7 +73,7 @@ function EmptyElement() {
     el.setAttribute('description', 'Start a new chat to see it appear here.');
   });
   return (
-    <kitn-empty ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px' }}>
+    <kc-empty ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px' }}>
       <svg slot="media" width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
         <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
       </svg>
@@ -99,7 +99,7 @@ function EmptyElement() {
         </svg>
         New chat
       </button>
-    </kitn-empty>
+    </kc-empty>
   );
 }
 

package/src/elements/empty.tsx

@@ -1,5 +1,5 @@
 import { Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent } from '../components/empty';
 
 interface Props extends Record<string, unknown> {
@@ -10,11 +10,11 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-empty>` — an empty-state block. `empty-title`/`description` via
+ * `<kc-empty>` — an empty-state block. `empty-title`/`description` via
  * attributes; slot your own icon into `slot="media"` and actions into the
  * default slot (Route 2 slots).
  */
-defineKitnElement<Props>('kitn-empty', {
+defineWebComponent<Props>('kc-empty', {
   emptyTitle: '',
   description: '',
 }, (props) => (

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

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
+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-feedback-bar': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-feedback-bar': JSX.HTMLAttributes<HTMLElement> & {
         'bar-title'?: string;
         'on:helpful'?: (e: CustomEvent) => void;
         'on:nothelpful'?: (e: CustomEvent) => void;
@@ -17,31 +18,30 @@ declare module 'solid-js' {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-feedback-bar bar-title="Was this helpful?"></kitn-feedback-bar>
+<kc-feedback-bar bar-title="Was this helpful?"></kc-feedback-bar>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 
-  const bar = document.querySelector('kitn-feedback-bar');
+  const bar = document.querySelector('kc-feedback-bar');
   bar.addEventListener('helpful', () => console.log('👍'));
   bar.addEventListener('nothelpful', () => console.log('👎'));
   bar.addEventListener('close', () => bar.remove());
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-feedback-bar',
+  title: 'Web Components/kc-feedback-bar',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-feedback-bar'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-feedback-bar>` is the framework-agnostic **web component** for an inline thumbs up/down feedback banner with a dismiss button — isolated in **Shadow DOM**.',
+      description: specDescription('kc-feedback-bar', [
+          '`<kc-feedback-bar>` is the framework-agnostic **web component** for an inline thumbs up/down feedback banner with a dismiss button — isolated in **Shadow DOM**.',
           '**When to use:** collecting a quick reaction after an answer or a completed task. In SolidJS, use the `FeedbackBar` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the label via the `bar-title` attribute (`title` is avoided — it's a global HTML attribute), and listen for the `helpful` / `nothelpful` / `close` **CustomEvents**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -53,7 +53,7 @@ type Story = StoryObj;
 export const Default: Story = {
   render: () => (
     <div style={{ padding: '24px', 'max-width': '480px' }}>
-      <kitn-feedback-bar
+      <kc-feedback-bar
         on:helpful={() => console.log('helpful')}
         on:nothelpful={() => console.log('not helpful')}
         on:close={() => console.log('closed')}
@@ -67,7 +67,7 @@ export const Default: Story = {
 export const CustomTitle: Story = {
   render: () => (
     <div style={{ padding: '24px', 'max-width': '480px' }}>
-      <kitn-feedback-bar bar-title="Did this answer your question?" />
+      <kc-feedback-bar bar-title="Did this answer your question?" />
     </div>
   ),
 };

package/src/elements/feedback-bar.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { FeedbackBar } from '../components/feedback-bar';
 
 interface Props extends Record<string, unknown> {
@@ -7,7 +7,7 @@ interface Props extends Record<string, unknown> {
   barTitle?: string;
 }
 
-/** Events fired by `<kitn-feedback-bar>`. */
+/** Events fired by `<kc-feedback-bar>`. */
 interface Events {
   /** The user clicked thumbs-up. */
   helpful: void;
@@ -18,10 +18,10 @@ interface Events {
 }
 
 /**
- * `<kitn-feedback-bar>` — an inline thumbs up/down feedback banner. Emits
+ * `<kc-feedback-bar>` — an inline thumbs up/down feedback banner. Emits
  * `helpful` / `nothelpful` / `close`.
  */
-defineKitnElement<Props, Events>('kitn-feedback-bar', {
+defineWebComponent<Props, Events>('kc-feedback-bar', {
   barTitle: 'Was this helpful?',
 }, (props, { dispatch }) => (
   <FeedbackBar

package/src/elements/file-tree.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { FileTreeFile } from '../components/file-tree';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-file-tree': JSX.HTMLAttributes<HTMLElement> & {
+        'active-file'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+const FILES: FileTreeFile[] = [
+  { path: 'index.html', type: 'html' },
+  { path: 'about.html', type: 'html' },
+  { path: 'css/site.css', type: 'other', language: 'css' },
+  { path: 'src/app.ts', type: 'other', language: 'ts' },
+  { path: 'src/lib/format.ts', type: 'other', language: 'ts' },
+  { path: 'src/lib/parse.ts', type: 'other', language: 'ts' },
+  { path: 'assets/logo.svg', type: 'image' },
+  { path: 'assets/report.pdf', type: 'pdf' },
+];
+
+/** A bordered, sized box the tree fills + scrolls within. */
+function Frame(props: { children: JSX.Element }) {
+  return (
+    <div
+      style={{
+        height: '320px',
+        width: '280px',
+        border: '1px solid var(--color-border, #e4e4e7)',
+        'border-radius': '10px',
+        overflow: 'hidden',
+      }}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kc-file-tree style="display:block;height:320px"></kc-file-tree>
+
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const tree = document.querySelector('kc-file-tree');
+  // \`files\` is a JS property (array). Folders are derived from \`/\` in each path.
+  tree.files = [
+    { path: 'index.html', type: 'html' },
+    { path: 'src/app.ts', type: 'other' },
+    { path: 'src/lib/format.ts', type: 'other' },
+    { path: 'assets/logo.svg', type: 'image' },
+  ];
+  tree.setAttribute('active-file', 'src/app.ts');
+  tree.addEventListener('select', (e) => console.log('selected', e.detail.path));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kc-file-tree',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-file-tree'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-file-tree', [
+        '`<kc-file-tree>` is the framework-agnostic **web component** for a collapsible, keyboard-navigable **file explorer** built from a flat list of `/`-delimited paths (nested folders are derived automatically). ARIA `tree`/`treeitem`. Isolated in **Shadow DOM**.',
+        '**When to use:** any time you need a file/folder tree — the Code tab of `<kc-artifact>` uses it, but it ships public so you can reuse it standalone (a project explorer, an attachments browser, a doc outline).',
+        "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `files` **property** (a JS array of `{ path, url?, code?, language?, type? }`). Folders come from the `/` in each `path`; `type` picks the icon. Set `active-file` to highlight a row, `default-expanded` to control which folders open. Listen for **`select`** (`detail.path`). Arrow keys navigate; Enter/Space selects or toggles.",
+        '**Placement:** a sidebar/explorer column — inside `<kc-artifact>`, a `<kc-resizable>` panel, or any file-picker surface. It **fills** its container, so give the parent (or the element) a height.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Interactive playground — click rows, use arrow keys / Enter to navigate. */
+export const Playground: Story = {
+  render: () => {
+    const [selected, setSelected] = createSignal('src/app.ts');
+    let el: HTMLElement & { files?: FileTreeFile[] };
+    onMount(() => {
+      if (!el) return;
+      el.files = FILES;
+      el.addEventListener('select', (e) => {
+        const path = (e as CustomEvent).detail.path as string;
+        setSelected(path);
+        el.setAttribute('active-file', path);
+      });
+    });
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <Frame>
+          <kc-file-tree
+            ref={(e) => (el = e as HTMLElement & { files?: FileTreeFile[] })}
+            active-file={selected()}
+          />
+        </Frame>
+        <span style={{ 'font-size': '13px', color: 'var(--color-muted-foreground, #71717a)' }}>
+          Selected: <code>{selected()}</code>
+        </span>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A deeper, nested layout with mixed file types. */
+export const Nested: Story = {
+  render: () => {
+    let el: HTMLElement & { files?: FileTreeFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kc-file-tree
+          ref={(e) => (el = e as HTMLElement & { files?: FileTreeFile[] })}
+          active-file="src/lib/format.ts"
+        />
+      </Frame>
+    );
+  },
+};

package/src/elements/file-tree.tsx

@@ -0,0 +1,52 @@
+import { defineWebComponent } from './define';
+import { FileTree, type FileTreeFile } from '../components/file-tree';
+
+interface Props extends Record<string, unknown> {
+  /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type? }`). */
+  files: FileTreeFile[];
+  /** Selected file path — highlighted in the tree. */
+  activeFile?: string;
+  /** Folder paths expanded initially. Omit to start with all folders open. */
+  defaultExpanded?: string[];
+}
+
+interface Events extends Record<string, unknown> {
+  /** Fired when a file is selected. `detail.path` = the file's path. */
+  select: { path: string };
+}
+
+/**
+ * `<kc-file-tree>` — a collapsible, keyboard-navigable file explorer built from a
+ * flat list of `/`-delimited paths (folders are derived). ARIA `tree`/`treeitem`.
+ * Selecting a file fires a `select` event (`detail.path`). Fills its container.
+ */
+defineWebComponent<Props, Events>('kc-file-tree', {
+  files: [],
+  activeFile: undefined,
+  defaultExpanded: undefined,
+}, (props, { dispatch }) => (
+  <>
+    {/* Fill the container + own the scroll (see resizable.tsx fill technique:
+        a definite `1fr` grid cell scoped to a wrapper, NOT :host, so the facade's
+        sibling portal-mount div can't steal a grid track). */}
+    <style>{':host{display:block;height:100%;min-height:0}'}</style>
+    <div
+      style={{
+        display: 'grid',
+        'grid-template-rows': 'minmax(0, 1fr)',
+        'grid-template-columns': 'minmax(0, 1fr)',
+        height: '100%',
+        'min-height': '0',
+      }}
+    >
+      <div class="overflow-auto scrollbar-thin py-1.5" style={{ 'min-height': '0' }}>
+        <FileTree
+          files={props.files}
+          activeFile={props.activeFile}
+          defaultExpanded={props.defaultExpanded}
+          onSelect={(path) => dispatch('select', { path })}
+        />
+      </div>
+    </div>
+  </>
+));