@colletdev/docs 0.2.1

package/index.md

@@ -0,0 +1,53 @@
+# Collet Documentation
+
+48 accessible web components built in Rust, compiled to WASM, distributed as
+Custom Elements with first-class framework wrappers.
+
+## Packages
+
+| Package | Description | Peer Dependencies |
+|---------|-------------|-------------------|
+| `@collet/core` | Custom Elements + WASM runtime + CSS tokens | — |
+| `@collet/react` | React 18+ wrappers with typed refs and hooks | `react >= 18`, `@collet/core` |
+| `@collet/vue` | Vue 3.3+ wrappers with Volar support | `vue >= 3.3`, `@collet/core` |
+| `@collet/svelte` | Svelte 5 wrappers with runes and snippets | `svelte >= 5`, `@collet/core` |
+| `@collet/angular` | Angular 16+ standalone wrappers with CVA | `@angular/core >= 16`, `@collet/core` |
+
+## Quick Start
+
+```bash
+npm install @collet/core @collet/react  # or vue/svelte/angular
+```
+
+```tsx
+import { init } from '@collet/core';
+import { Button } from '@collet/react';
+
+await init();
+
+<Button label="Click me" variant="filled" onClick={(e) => console.log(e.detail)} />
+```
+
+## Documentation Files
+
+| File | Size | Contents |
+|------|------|----------|
+| [core.md](./core.md) | 22 KB | Initialization, theming, CSS architecture, SSR, events, slots, form integration |
+| [components.md](./components.md) | 64 KB | All 48 components: multi-framework imports, props, events, methods, types |
+| [react.md](./react.md) | 6 KB | React 18+ patterns: forwardRef, hooks, event callbacks, SSR |
+| [vue.md](./vue.md) | 5 KB | Vue 3.3+ patterns: Composition API, Volar, expose(), slots |
+| [svelte.md](./svelte.md) | 5 KB | Svelte 5 patterns: runes, callback props, snippets, migration |
+| [angular.md](./angular.md) | 6 KB | Angular 16+ patterns: standalone, CVA, OnPush, template binding |
+
+## Generation
+
+This documentation is auto-generated from the component manifest and kept
+in sync by the build pipeline. Regenerate with:
+
+```bash
+node scripts/generate-skill-docs.mjs
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@colletdev/docs",
+  "version": "0.2.1",
+  "description": "Collet component library documentation — API reference, framework guides, and AI agent setup",
+  "type": "module",
+  "bin": {
+    "collet-docs": "./cli.mjs"
+  },
+  "exports": {
+    ".": "./index.md",
+    "./components": "./components.md",
+    "./react": "./react.md",
+    "./vue": "./vue.md",
+    "./svelte": "./svelte.md",
+    "./angular": "./angular.md",
+    "./core": "./core.md"
+  },
+  "files": [
+    "*.md",
+    "cli.mjs"
+  ],
+  "keywords": [
+    "collet",
+    "documentation",
+    "web-components",
+    "react",
+    "vue",
+    "svelte",
+    "angular",
+    "rust",
+    "wasm"
+  ],
+  "author": "Dan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Danrozen87/collet",
+    "directory": "packages/docs"
+  }
+}

package/react.md

@@ -0,0 +1,290 @@
+# Collet React Reference
+
+React wrappers for the Collet component library. Auto-generated from
+`custom-elements.json` via `scripts/generate-react.mjs`.
+
+---
+
+## Package
+
+```
+@colletdev/react
+```
+
+**Peer dependencies:** `react >= 18.0.0`, `@colletdev/core >= 0.1.0`
+
+## Architecture
+
+React wrappers are thin `forwardRef` components that render the underlying
+`<cx-*>` Custom Element. They handle:
+
+- **Attribute serialization** — objects/arrays go through `JSON.stringify`
+- **Event bridging** — `on{Event}` props attach listeners for `cx-{event}` CustomEvents
+- **Slot projection** — named slots via `<div slot="name" style={{display:'contents'}}>`
+- **Typed imperative refs** — `useImperativeHandle` exposes typed methods
+
+### Package Structure
+
+```
+packages/react/
+  generated/          ← Auto-generated wrappers (DO NOT EDIT)
+    button.tsx
+    dialog.tsx
+    ...
+    index.ts          ← Barrel exports
+    types.ts          ← Shared TypeScript interfaces
+    elements.d.ts     ← JSX IntrinsicElements augmentation
+  dist/               ← Compiled output (JS + .d.ts)
+```
+
+---
+
+## Patterns
+
+### Basic Usage
+
+```tsx
+import { Button, Dialog, type DialogRef } from '@colletdev/react';
+
+function App() {
+  const dialogRef = useRef<DialogRef>(null);
+
+  return (
+    <>
+      <Button label="Open" onClick={() => dialogRef.current?.open()} />
+      <Dialog
+        ref={dialogRef}
+        title="Confirm"
+        onClose={(e) => console.log(e.detail.reason)}
+        footer={<Button label="OK" variant="filled" />}
+      >
+        <p>Are you sure?</p>
+      </Dialog>
+    </>
+  );
+}
+```
+
+### Event Callbacks
+
+All events use `on{PascalEvent}` naming. The callback receives a `CustomEvent<Detail>`:
+
+```tsx
+<TextInput
+  label="Email"
+  onInput={(e) => setValue(e.detail.value)}    // InputDetail
+  onChange={(e) => validate(e.detail.value)}    // InputDetail
+  onFocus={(e) => setFocused(true)}            // FocusDetail
+  onKeydown={(e) => {                          // KeyboardDetail
+    if (e.detail.key === 'Enter') submit();
+  }}
+/>
+```
+
+### Overlays (Dialog, Drawer)
+
+Overlays support both declarative and imperative control. **Always keep them
+mounted** — never conditionally render with `{show && <Dialog>}`. This matches
+MUI, Radix, Ant Design, and every major React UI library.
+
+**Declarative (recommended):**
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Button label="Open" onClick={() => setOpen(true)} />
+<Dialog
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Confirm"
+  footer={<Button label="OK" variant="filled" onClick={() => setOpen(false)} />}
+>
+  <p>Are you sure?</p>
+</Dialog>
+```
+
+**Imperative (ref-based):**
+
+```tsx
+const ref = useRef<DialogRef>(null);
+
+<Button label="Open" onClick={() => ref.current?.open()} />
+<Dialog ref={ref} title="Confirm" onClose={() => console.log('closed')}>
+  <p>Are you sure?</p>
+</Dialog>
+```
+
+Both patterns work for Dialog and Drawer. The component owns its animation
+lifecycle — open/close transitions play fully without being interrupted by
+React state changes.
+
+**Do NOT conditionally render overlays:**
+
+```tsx
+// WRONG — unmounting kills exit animation, breaks accessibility
+{isOpen && <Drawer open title="Settings">...</Drawer>}
+
+// CORRECT — always mounted, visibility controlled by open prop
+<Drawer open={isOpen} onClose={() => setIsOpen(false)} title="Settings">...</Drawer>
+```
+
+### Imperative Refs
+
+Components with `open/close/focus` methods expose typed refs:
+
+```tsx
+import { Select, type SelectRef } from '@colletdev/react';
+
+const ref = useRef<SelectRef>(null);
+ref.current?.open();   // Opens dropdown
+ref.current?.close();  // Closes dropdown
+ref.current?.focus();  // Focuses trigger
+```
+
+### Named Slots
+
+Named slots use React props that accept `ReactNode`:
+
+```tsx
+<Card
+  header={<h3>Title</h3>}
+  footer={<Button label="Action" />}
+>
+  <p>Body content (default slot)</p>
+</Card>
+```
+
+Under the hood, these render as `<div slot="name" style={{display:'contents'}}>`.
+
+### Complex Props (Structured Data)
+
+Props that accept arrays/objects are serialized to JSON attributes via `useEffect`:
+
+```tsx
+<Table
+  caption="Users"
+  columns={[
+    { id: 'name', header: 'Name', sortable: true },
+    { id: 'email', header: 'Email' },
+  ]}
+  rows={[
+    { id: '1', cells: { name: 'Alice', email: 'alice@example.com' } },
+  ]}
+  sorts={[{ column_id: 'name', direction: 'asc' }]}
+  onSort={(e) => handleSort(e.detail)}
+/>
+```
+
+### Form Integration
+
+Form-associated components work with uncontrolled forms via `name` prop:
+
+```tsx
+<form onSubmit={handleSubmit}>
+  <TextInput name="email" label="Email" required />
+  <Select name="country" label="Country" items={countries} />
+  <Button label="Submit" kind="submit" />
+</form>
+```
+
+For controlled forms, use event callbacks:
+
+```tsx
+const [value, setValue] = useState('');
+<TextInput
+  label="Name"
+  value={value}
+  onInput={(e) => setValue(e.detail.value)}
+/>
+```
+
+### DOM Collision Handling
+
+React 19 sets DOM properties directly on Custom Elements. The wrappers
+automatically route these through `useEffect` + `setAttribute`:
+
+- **HTML properties** (`title`, `width`, `loading`, `role`) — bypasses HTMLElement property setters
+- **Form properties** (`name`, `value`, `type`) — on form components (TextInput, Select, Slider, etc.)
+- **Numeric attributes** (`lines`, `min`, `max`, `step`, `duration`, `currentPage`, etc.) — ensures `attributeChangedCallback` fires for `_numericAttrs` coercion
+- **Complex data** (`columns`, `rows`, `items`, etc.) — JSON-serialized objects/arrays
+
+```tsx
+// All of these work correctly — routed through setAttribute automatically
+<Dialog title="My Dialog" />
+<Slider min={0} max={100} step={5} value={50} />
+<Skeleton variant="text" lines={3} />
+<Pagination currentPage={1} pageSize={10} totalItems={100} />
+```
+
+No special handling needed from consumers.
+
+### Markdown Support
+
+```tsx
+import { useMarkdown } from '@colletdev/react';
+import { MessagePart, type MessagePartRef } from '@colletdev/react';
+
+// Static markdown
+const html = useMarkdown('**Hello** world');
+
+// Streaming markdown (AI chat)
+const { ref, startStream, appendTokens, endStream } = useMarkdownStream();
+<MessagePart ref={ref} stream />
+```
+
+### Server Rendering
+
+```tsx
+// Next.js App Router — Server Component
+import { createRenderer } from '@colletdev/core/server';
+
+export default async function Page() {
+  const cx = await createRenderer();
+  const buttonHtml = cx.renderDSD('button', { label: 'Click', id: 'btn-1' });
+  return <div dangerouslySetInnerHTML={{ __html: buttonHtml }} />;
+}
+```
+
+---
+
+## TypeScript
+
+All props, events, and ref types are fully typed. Import types from `@colletdev/react`:
+
+```tsx
+import type {
+  // Structured data props
+  TableColumn, TableRow, SelectOption, MenuEntry,
+  // Event details
+  InputDetail, ClickDetail, CloseDetail,
+  // Ref types (from component exports)
+  DialogRef, SelectRef, TextInputRef,
+} from '@colletdev/react';
+```
+
+### JSX IntrinsicElements
+
+`@colletdev/react` augments `JSX.IntrinsicElements` with all `cx-*` elements
+for direct Custom Element usage when wrappers aren't needed:
+
+```tsx
+// Works with full type checking
+<cx-button label="Raw CE" variant="filled" />
+```
+
+---
+
+## Codegen
+
+React wrappers are generated by `scripts/generate-react.mjs`. Configuration
+lives in both the React generator (inline maps) and `scripts/component-config.mjs`
+(shared across all framework generators).
+
+**Do not edit** files in `packages/react/generated/` — they are overwritten
+by `bash scripts/build-packages.sh`.
+
+Custom files (preserved by codegen):
+- `generated/message-part.tsx` — streaming markdown support
+- `generated/use-markdown.ts` — `useMarkdown()` hook
+- `generated/use-markdown-stream.ts` — `useMarkdownStream()` hook
+- `generated/drawer.tsx` — custom drawer implementation

package/svelte.md

@@ -0,0 +1,234 @@
+# Collet Svelte Reference
+
+Svelte 5 wrappers for the Collet component library. Auto-generated from
+`custom-elements.json` via `scripts/generate-svelte.mjs`.
+
+---
+
+## Package
+
+```
+@colletdev/svelte
+```
+
+**Peer dependencies:** `svelte >= 5.0.0`, `@colletdev/core >= 0.1.0`
+
+Ships raw `.svelte` source files — consumers compile with their own Svelte toolchain.
+
+## Architecture
+
+Svelte wrappers use Svelte 5 runes (`$props`, `$effect`) for reactive prop
+syncing and event bridging. They handle:
+
+- **Attribute serialization** — objects/arrays synced via `$effect` + `setAttribute`
+- **Event bridging** — callback props (`onClick`, `onChange`) wired via `$effect` listeners
+- **Slot projection** — `{@render children?.()}` for default, `{@render footer?.()}` for named
+- **Imperative methods** — `export function open()` exposed to consumers
+
+### Package Structure
+
+```
+packages/svelte/
+  src/                    ← Auto-generated wrappers (DO NOT EDIT)
+    button.svelte
+    button.svelte.d.ts
+    dialog.svelte
+    dialog.svelte.d.ts
+    ...
+    index.ts              ← Barrel exports + type re-exports
+    types.ts              ← Shared TypeScript interfaces
+    elements.d.ts         ← SvelteHTMLElements augmentation
+```
+
+---
+
+## Patterns
+
+### Basic Usage
+
+```svelte
+<script lang="ts">
+  import Button from '@colletdev/svelte/button.svelte';
+  import Dialog from '@colletdev/svelte/dialog.svelte';
+
+  let dialog: { open: () => void; close: () => void };
+</script>
+
+<Button label="Open" onClick={() => dialog.open()} />
+<Dialog
+  bind:this={dialog}
+  title="Confirm"
+  onClose={(e) => console.log(e.detail.reason)}
+>
+  <p>Are you sure?</p>
+  {#snippet footer()}
+    <Button label="OK" variant="filled" />
+  {/snippet}
+</Dialog>
+```
+
+### Event Callbacks
+
+Svelte 5 uses callback props instead of `on:event` directives:
+
+```svelte
+<TextInput
+  label="Email"
+  onInput={(e) => value = e.detail.value}
+  onChange={(e) => validate(e.detail.value)}
+  onFocus={(e) => focused = true}
+  onKeydown={(e) => {
+    if (e.detail.key === 'Enter') submit();
+  }}
+/>
+```
+
+Callback props are typed: `(event: CustomEvent<InputDetail>) => void`.
+
+### Imperative Methods
+
+Components expose methods via `export function`. Access through `bind:this`:
+
+```svelte
+<script lang="ts">
+  import Select from '@colletdev/svelte/select.svelte';
+
+  let select: { open: () => void; close: () => void; focus: () => void };
+</script>
+
+<Select bind:this={select} label="Country" items={countries} />
+<button onclick={() => select.open()}>Open dropdown</button>
+```
+
+### Named Slots (Snippets)
+
+Svelte 5 uses `{#snippet}` for named slots:
+
+```svelte
+<Card>
+  {#snippet header()}
+    <h3>Title</h3>
+  {/snippet}
+
+  <p>Body content (default slot via children)</p>
+
+  {#snippet footer()}
+    <Button label="Action" />
+  {/snippet}
+</Card>
+```
+
+The wrapper renders snippets inside `<div slot="name">` wrappers for
+Shadow DOM slot projection.
+
+### Complex Props (Structured Data)
+
+Props accepting arrays/objects are synced via `$effect` + `setAttribute(JSON.stringify())`:
+
+```svelte
+<Table
+  caption="Users"
+  columns={[
+    { id: 'name', header: 'Name', sortable: true },
+    { id: 'email', header: 'Email' },
+  ]}
+  rows={rows}
+  sorts={[{ column_id: 'name', direction: 'asc' }]}
+  onSort={(e) => handleSort(e.detail)}
+/>
+```
+
+### Form Integration
+
+```svelte
+<form onsubmit={handleSubmit}>
+  <TextInput name="email" label="Email" required />
+  <Select name="country" label="Country" items={countries} />
+  <Button label="Submit" kind="submit" />
+</form>
+```
+
+### DOM Collision Handling
+
+Attributes like `title`, `width`, `loading` are routed through `$effect` +
+`setAttribute` to avoid Svelte setting them as DOM properties:
+
+```svelte
+<!-- Works correctly -->
+<Dialog title="My Dialog" />
+<Table loading={75} />
+```
+
+---
+
+## TypeScript
+
+### Type Imports
+
+```ts
+import type {
+  TableColumn, TableRow, SelectOption, MenuEntry,
+  InputDetail, ClickDetail, CloseDetail,
+} from '@colletdev/svelte';
+```
+
+### Component Types
+
+Each `.svelte` file has a `.svelte.d.ts` companion with full prop types:
+
+```ts
+import type { Component } from 'svelte';
+
+interface ButtonProps {
+  label?: string;
+  variant?: 'filled' | 'ghost' | 'outline' | 'underline' | 'side-indicator';
+  // ... all props typed
+  onClick?: (event: CustomEvent<ClickDetail>) => void;
+}
+
+declare const Button: Component<ButtonProps, { /* exports */ }>;
+```
+
+### SvelteHTMLElements Augmentation
+
+`@colletdev/svelte` augments `SvelteHTMLElements` for direct Custom Element usage:
+
+```svelte
+<!-- Type-checked cx-* elements -->
+<cx-button label="Raw CE" variant="filled" />
+```
+
+Import the augmentation in `app.d.ts`:
+
+```ts
+/// <reference types="@colletdev/svelte/elements" />
+```
+
+---
+
+## Svelte 5 Migration Notes
+
+The wrappers are Svelte 5 native. Key differences from Svelte 4:
+
+| Svelte 4 | Svelte 5 (Collet) |
+|----------|-------------------|
+| `export let prop` | `let { prop } = $props()` |
+| `on:click` | `onclick` callback prop |
+| `<slot />` | `{@render children?.()}` |
+| `<slot name="x" />` | `{@render x?.()}` |
+| `onMount(() => {})` | `$effect(() => { ... })` |
+| `$: derived` | `let derived = $derived(...)` |
+| `SvelteComponent` | `Component` type |
+| `createEventDispatcher` | Callback props |
+
+---
+
+## Codegen
+
+Svelte wrappers are generated by `scripts/generate-svelte.mjs`. Configuration
+lives in `scripts/component-config.mjs` (shared across all framework generators).
+
+**Do not edit** files in `packages/svelte/src/` — they are overwritten by
+`bash scripts/build-packages.sh`.
+
+Raw source ships to consumers (no pre-compilation needed).