@colletdev/docs 0.2.1

package/README.md

@@ -0,0 +1,60 @@
+# @collet/docs
+
+API reference and framework integration guides for the Collet component library -- 48 accessible web components built in Rust/WASM.
+
+## Install
+
+```bash
+npm install @collet/docs
+```
+
+## Contents
+
+| File | Export | Description |
+|------|--------|-------------|
+| `index.md` | `@collet/docs` | Library overview and architecture |
+| `components.md` | `@collet/docs/components` | All 48 components: props, events, slots, ARIA |
+| `core.md` | `@collet/docs/core` | `init()` options, theming, CSS architecture, SSR |
+| `react.md` | `@collet/docs/react` | React 18+ wrappers, hooks, ref types, events |
+| `vue.md` | `@collet/docs/vue` | Vue 3.3+ wrappers, Volar setup, emits |
+| `svelte.md` | `@collet/docs/svelte` | Svelte 5 runes wrappers, callback props |
+| `angular.md` | `@collet/docs/angular` | Angular 16+ standalone components, forms |
+
+## Usage
+
+Import the markdown content directly:
+
+```js
+import components from '@collet/docs/components';
+import react from '@collet/docs/react';
+```
+
+This package ships `.md` files and a CLI. Use it to build documentation sites, power in-app help, or set up AI agent context.
+
+## AI Agent Setup
+
+Set up Collet knowledge for your AI coding assistant:
+
+```bash
+npx @collet/docs init            # auto-detect (Claude Code by default)
+npx @collet/docs init --claude   # Claude Code (.claude/skills/collet/)
+npx @collet/docs init --codex    # OpenAI Codex (AGENTS.md)
+npx @collet/docs init --cursor   # Cursor AI (.cursor/rules/collet.md)
+npx @collet/docs init --all      # All formats
+```
+
+The CLI auto-detects your framework from `package.json` and generates context-aware agent configuration with the full 48-component API reference.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| `@collet/core` | Custom Elements + WASM runtime |
+| `@collet/react` | React 18+ wrappers |
+| `@collet/vue` | Vue 3.3+ wrappers |
+| `@collet/svelte` | Svelte 5 wrappers |
+| `@collet/angular` | Angular 16+ wrappers |
+
+## License
+
+MIT -- [github.com/Danrozen87/collet](https://github.com/Danrozen87/collet)

package/angular.md

@@ -0,0 +1,254 @@
+# Collet Angular Reference
+
+Angular wrappers for the Collet component library. Auto-generated from
+`custom-elements.json` via `scripts/generate-angular.mjs`.
+
+---
+
+## Package
+
+```
+@colletdev/angular
+```
+
+**Peer dependencies:** `@angular/core >= 16.0.0`, `@angular/forms >= 16.0.0` (optional), `@colletdev/core >= 0.1.0`
+
+Ships raw TypeScript source — consumers compile with their own Angular toolchain.
+
+## Architecture
+
+Angular wrappers are standalone components with `CUSTOM_ELEMENTS_SCHEMA`,
+`ChangeDetectionStrategy.OnPush`, and `c.detach()` for zero change detection
+overhead. They handle:
+
+- **Attribute serialization** — objects/arrays synced via `ngOnChanges` + `setAttribute`
+- **Event bridging** — `@Output()` EventEmitters for `cx-{event}` CustomEvents
+- **Slot projection** — `<ng-content>` with `select="[slot=name]"` for named slots
+- **ControlValueAccessor** — form-associated components support `formControlName` and `ngModel`
+- **Imperative methods** — public methods on the component class delegating to the CE
+
+### Package Structure
+
+```
+packages/angular/
+  src/                        ← Auto-generated wrappers (DO NOT EDIT)
+    button.component.ts
+    dialog.component.ts
+    ...
+    index.ts                  ← Barrel exports
+    types.ts                  ← Shared TypeScript interfaces
+```
+
+### Selector Pattern
+
+```
+cx-{name}[collet]
+```
+
+The `[collet]` attribute disambiguates the Angular wrapper from the bare
+Custom Element. This means Angular components must add the `collet` attribute:
+
+```html
+<cx-button collet label="Click me" />
+```
+
+---
+
+## Patterns
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { CxButton, CxDialog } from '@colletdev/angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [CxButton, CxDialog],
+  template: `
+    <cx-button collet label="Open" (cxClick)="dialog.open()" />
+    <cx-dialog collet
+      #dialog
+      title="Confirm"
+      (cxClose)="onClose($event)"
+    >
+      <p>Are you sure?</p>
+      <div slot="footer">
+        <cx-button collet label="OK" variant="filled" />
+      </div>
+    </cx-dialog>
+  `,
+})
+export class AppComponent {
+  onClose(e: CustomEvent) {
+    console.log(e.detail.reason);
+  }
+}
+```
+
+### Event Handling
+
+Events use `(cxEventName)` syntax:
+
+```html
+<cx-text-input collet
+  label="Email"
+  (cxInput)="onInput($event)"
+  (cxChange)="onChange($event)"
+  (cxFocus)="onFocus($event)"
+  (cxKeydown)="onKeydown($event)"
+/>
+```
+
+```typescript
+onInput(e: CustomEvent<InputDetail>) {
+  this.value = e.detail.value;
+}
+```
+
+### Imperative Methods
+
+Access methods directly on the component instance via template ref:
+
+```html
+<cx-select collet #selectRef label="Country" [items]="countries" />
+<button (click)="selectRef.open()">Open</button>
+```
+
+Or via `@ViewChild`:
+
+```typescript
+@ViewChild('selectRef') selectRef!: CxSelect;
+
+openSelect() {
+  this.selectRef.open();
+}
+```
+
+### Named Slots
+
+Project content into named slots using the `slot` attribute:
+
+```html
+<cx-card collet>
+  <div slot="header"><h3>Title</h3></div>
+  <p>Body content</p>
+  <div slot="footer">
+    <cx-button collet label="Action" />
+  </div>
+</cx-card>
+```
+
+The wrapper template includes `<ng-content select="[slot=name]">` for each
+named slot, so Angular's content projection passes through to Shadow DOM.
+
+### Complex Props (Structured Data)
+
+Props accepting arrays/objects use `[attr]` binding. The wrapper watches for
+changes and serializes via `JSON.stringify` + `setAttribute`:
+
+```html
+<cx-table collet
+  caption="Users"
+  [columns]="columns"
+  [rows]="rows"
+  [sorts]="[{ column_id: 'name', direction: 'asc' }]"
+  (cxSort)="handleSort($event)"
+/>
+```
+
+### Reactive Forms (ControlValueAccessor)
+
+Form-associated components implement `ControlValueAccessor` for Angular
+Reactive Forms and `ngModel`:
+
+```typescript
+import { ReactiveFormsModule, FormGroup, FormControl } from '@angular/forms';
+import { CxTextInput, CxSelect, CxCheckbox } from '@colletdev/angular';
+
+@Component({
+  imports: [ReactiveFormsModule, CxTextInput, CxSelect, CxCheckbox],
+  template: `
+    <form [formGroup]="form">
+      <cx-text-input collet formControlName="email" label="Email" />
+      <cx-select collet formControlName="country" label="Country" [items]="countries" />
+      <cx-checkbox collet formControlName="agree" label="I agree" />
+    </form>
+  `,
+})
+export class FormComponent {
+  form = new FormGroup({
+    email: new FormControl(''),
+    country: new FormControl(''),
+    agree: new FormControl(false),
+  });
+}
+```
+
+**CVA components:** TextInput, Select, Checkbox, RadioGroup, Switch, Slider,
+Autocomplete, ToggleGroup, DatePicker, SearchBar, ChatInput.
+
+The CVA implementation:
+- `writeValue()` — sets the CE's `value` (or `checked` for checkbox/switch)
+- `registerOnChange()` — listens to `cx-change` events
+- `registerOnTouched()` — listens to `focusout`
+- `setDisabledState()` — toggles the `disabled` attribute
+
+### DOM Collision Handling
+
+Attributes like `title`, `width`, `loading` are bound via `[attr.name]` to
+avoid Angular setting them as DOM properties:
+
+```html
+<!-- Works correctly -->
+<cx-dialog collet [attr.title]="dialogTitle" />
+<cx-table collet [attr.loading]="loadPercent" />
+```
+
+---
+
+## TypeScript
+
+### Type Imports
+
+```typescript
+import type {
+  TableColumn, TableRow, SelectOption, MenuEntry,
+  InputDetail, ClickDetail, CloseDetail, FocusDetail,
+} from '@colletdev/angular';
+```
+
+### Component Classes
+
+All wrappers export PascalCase classes prefixed with `Cx`:
+
+```typescript
+import {
+  CxButton,      // <cx-button collet>
+  CxDialog,      // <cx-dialog collet>
+  CxTextInput,   // <cx-text-input collet>
+  CxTable,       // <cx-table collet>
+} from '@colletdev/angular';
+```
+
+---
+
+## Performance
+
+The wrappers use `ChangeDetectionStrategy.OnPush` with `c.detach()` in the
+constructor, so Angular's change detection never runs for these components.
+All reactivity is handled by the Custom Element itself and the `watch` /
+`ngOnChanges` attribute syncing.
+
+---
+
+## Codegen
+
+Angular wrappers are generated by `scripts/generate-angular.mjs`. Configuration
+lives in `scripts/component-config.mjs` (shared across all framework generators).
+
+**Do not edit** files in `packages/angular/src/` — they are overwritten by
+`bash scripts/build-packages.sh`.
+
+Raw TypeScript ships to consumers (compile with `tsc` or `ng-packagr`).

package/cli.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// @colletdev/docs CLI — Set up AI agent context for Collet components
+//
+// Usage:
+//   npx @colletdev/docs init              # auto-detect AI tool
+//   npx @colletdev/docs init --claude     # Claude Code skills
+//   npx @colletdev/docs init --codex      # OpenAI Codex AGENTS.md
+//   npx @colletdev/docs init --cursor     # Cursor rules
+//   npx @colletdev/docs init --generic    # Plain COLLET.md
+//   npx @colletdev/docs init --all        # All formats
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, cpSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CWD = process.cwd();
+
+// ─── Resolve doc files (from this package's directory) ───
+
+function docPath(name) {
+  return resolve(__dirname, name);
+}
+
+function readDoc(name) {
+  return readFileSync(docPath(name), 'utf8');
+}
+
+// ─── Detect which AI tools are in use ───
+
+function detectTools() {
+  const tools = [];
+  if (existsSync(resolve(CWD, '.claude')) || process.argv.includes('--claude')) tools.push('claude');
+  if (existsSync(resolve(CWD, 'AGENTS.md')) || process.argv.includes('--codex')) tools.push('codex');
+  if (existsSync(resolve(CWD, '.cursor')) || process.argv.includes('--cursor')) tools.push('cursor');
+  if (process.argv.includes('--generic')) tools.push('generic');
+  if (process.argv.includes('--all')) return ['claude', 'codex', 'cursor', 'generic'];
+  if (tools.length === 0) tools.push('claude'); // default
+  return [...new Set(tools)];
+}
+
+// ─── Detect framework from package.json ───
+
+function detectFramework() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(CWD, 'package.json'), 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+    if (deps['@colletdev/react'] || deps['react']) return 'react';
+    if (deps['@colletdev/vue'] || deps['vue']) return 'vue';
+    if (deps['@colletdev/svelte'] || deps['svelte']) return 'svelte';
+    if (deps['@colletdev/angular'] || deps['@angular/core']) return 'angular';
+  } catch { /* no package.json */ }
+  return null;
+}
+
+// ─── Generate Claude Code skills ───
+
+function setupClaude(framework) {
+  const skillDir = resolve(CWD, '.claude/skills/collet');
+  const refDir = resolve(skillDir, 'references');
+  mkdirSync(refDir, { recursive: true });
+
+  // SKILL.md — adapted for consumer projects (no build/gallery references)
+  const skillMd = `---
+name: collet
+description: >
+  Collet component library — 48 accessible Custom Element + WASM components
+  with typed ${framework ? framework.charAt(0).toUpperCase() + framework.slice(1) : 'framework'} wrappers.
+---
+
+# Collet
+
+48 accessible web components built in Rust/WASM. Distributed as Custom Elements
+with first-class React, Vue, Svelte, and Angular wrappers.
+
+## Context Detection
+
+Read the reference that matches the user's context:
+
+| Signal | Load |
+|--------|------|
+| .tsx / .jsx / React | core.md + react.md |
+| .vue / Vue | core.md + vue.md |
+| .svelte / Svelte | core.md + svelte.md |
+| .component.ts / Angular | core.md + angular.md |
+| Custom Elements / @colletdev/core | core.md only |
+| Component API question | components.md |
+
+Always read core.md first, then the framework-specific reference.
+
+## Quick Reference
+
+- **Install:** \`npm install @colletdev/core @colletdev/{react,vue,svelte,angular}\`
+- **Prefix:** \`cx-\` (e.g., \`<cx-button>\`, \`<cx-dialog>\`)
+- **Init:** \`import { init } from '@colletdev/core'; await init();\`
+- **Theming:** CSS custom properties via custom \`tokens.css\`
+- **Docs:** \`@colletdev/docs\` package or references/ in this directory
+`;
+
+  writeFileSync(resolve(skillDir, 'SKILL.md'), skillMd);
+
+  // Copy all reference docs
+  for (const file of ['core.md', 'components.md', 'react.md', 'vue.md', 'svelte.md', 'angular.md']) {
+    const src = docPath(file);
+    if (existsSync(src)) {
+      writeFileSync(resolve(refDir, file), readDoc(file));
+    }
+  }
+
+  console.log(`  Claude Code: .claude/skills/collet/ (SKILL.md + 6 references)`);
+
+  // Add to .claude/CLAUDE.md if it exists and doesn't already mention collet
+  const claudeMd = resolve(CWD, '.claude/CLAUDE.md');
+  if (existsSync(claudeMd)) {
+    const content = readFileSync(claudeMd, 'utf8');
+    if (!content.includes('@collet') && !content.includes('collet')) {
+      const snippet = `\n\n## Collet Components\n\nThis project uses Collet UI components. Read \`.claude/skills/collet/SKILL.md\` for the skill router that loads framework-specific references.\n`;
+      writeFileSync(claudeMd, content + snippet);
+      console.log(`  Updated .claude/CLAUDE.md with Collet reference`);
+    }
+  }
+}
+
+// ─── Generate Codex AGENTS.md ───
+
+function setupCodex(framework) {
+  const agentsMd = resolve(CWD, 'AGENTS.md');
+  const fwRef = framework ? readDoc(`${framework}.md`) : '';
+  const coreRef = readDoc('core.md');
+
+  // Trim to essential sections for context window efficiency
+  const lang = framework === 'react' ? 'tsx' : framework === 'vue' ? 'vue' : framework === 'svelte' ? 'svelte' : 'typescript';
+  const importLine = framework === 'react' ? "import { Button } from '@colletdev/react';"
+    : framework === 'vue' ? "import { Button } from '@colletdev/vue';"
+    : framework === 'svelte' ? "import { Button } from '@colletdev/svelte';"
+    : framework === 'angular' ? "import { CxButton } from '@colletdev/angular';"
+    : '';
+
+  const content = `# Collet Component Library
+
+This project uses Collet — 48 accessible web components built in Rust/WASM.
+
+## Setup
+
+\`\`\`bash
+npm install @colletdev/core${framework ? ` @colletdev/${framework}` : ''}
+\`\`\`
+
+\`\`\`${lang}
+import { init } from '@colletdev/core';${importLine ? '\n' + importLine : ''}
+await init();
+\`\`\`
+
+## Key Conventions
+
+- Custom Element prefix: \`cx-\` (e.g., \`<cx-button>\`, \`<cx-dialog>\`)
+- All props are typed with union literals (variant, intent, size, shape)
+- Events use \`cx-\` prefix: \`cx-click\`, \`cx-change\`, \`cx-input\`
+- Structured data props (items, columns, etc.) accept typed arrays or JSON strings
+- Components with imperative methods expose typed refs (open, close, focus, etc.)
+
+## Full API Reference
+
+The complete component reference is in \`node_modules/@colletdev/docs/components.md\`.
+Framework guide: \`node_modules/@colletdev/docs/${framework || 'core'}.md\`.
+
+Read these files for props, events, methods, and types for all 48 components.
+`;
+
+  if (existsSync(agentsMd)) {
+    const existing = readFileSync(agentsMd, 'utf8');
+    if (existing.includes('Collet')) {
+      console.log(`  Codex: AGENTS.md already contains Collet section (skipped)`);
+      return;
+    }
+    writeFileSync(agentsMd, existing + '\n\n' + content);
+    console.log(`  Codex: Appended Collet section to existing AGENTS.md`);
+  } else {
+    writeFileSync(agentsMd, content);
+    console.log(`  Codex: AGENTS.md created`);
+  }
+}
+
+// ─── Generate Cursor rules ───
+
+function setupCursor(framework) {
+  const rulesDir = resolve(CWD, '.cursor/rules');
+  mkdirSync(rulesDir, { recursive: true });
+
+  const content = `# Collet Component Library
+
+This project uses Collet — 48 accessible web components (Rust/WASM).
+
+## Import Pattern
+${framework === 'react' ? "```tsx\nimport { Button, TextInput, Dialog } from '@colletdev/react';\n```"
+    : framework === 'vue' ? "```typescript\nimport { Button, TextInput, Dialog } from '@colletdev/vue';\n```"
+    : framework === 'svelte' ? "```typescript\nimport { Button, TextInput, Dialog } from '@colletdev/svelte';\n```"
+    : framework === 'angular' ? "```typescript\nimport { CxButton, CxTextInput, CxDialog } from '@colletdev/angular';\n```"
+    : "```typescript\nimport { init } from '@colletdev/core';\n```"}
+
+## Conventions
+- Prefix: \`cx-\` for Custom Elements
+- Events: \`cx-click\`, \`cx-change\`, \`cx-input\`, \`cx-close\`, etc.
+- Structured data: typed arrays (SelectOption[], TableColumn[], MenuEntry[])
+- Sizing: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+- Variants: 'filled' | 'outline' | 'ghost' | 'soft'
+- Intent: 'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'danger'
+
+## Reference
+Full API docs: \`node_modules/@colletdev/docs/components.md\`
+Framework guide: \`node_modules/@colletdev/docs/${framework || 'core'}.md\`
+`;
+
+  writeFileSync(resolve(rulesDir, 'collet.md'), content);
+  console.log(`  Cursor: .cursor/rules/collet.md created`);
+}
+
+// ─── Generate generic COLLET.md ───
+
+function setupGeneric(framework) {
+  const content = `# Collet Components
+
+This project uses [Collet](https://github.com/Danrozen87/collet) — 48 accessible
+web components built in Rust/WASM with ${framework ? framework.charAt(0).toUpperCase() + framework.slice(1) : 'framework'} wrappers.
+
+## API Reference
+
+The full component reference (props, events, methods, types) is available at:
+
+\`\`\`
+node_modules/@colletdev/docs/components.md  — 48 components, all props/events/methods
+node_modules/@colletdev/docs/core.md        — Init, theming, CSS, SSR, event conventions
+node_modules/@colletdev/docs/${framework || 'react'}.md     — Framework-specific patterns
+\`\`\`
+
+Or install the docs package directly: \`npm install @colletdev/docs\`
+`;
+
+  writeFileSync(resolve(CWD, 'COLLET.md'), content);
+  console.log(`  Generic: COLLET.md created`);
+}
+
+// ─── Main ───
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args[0] === 'purge') {
+    console.log('');
+    console.log('To purge stale Collet artifacts, run:');
+    console.log('  npx collet-purge');
+    console.log('  # or: npx @colletdev/core purge');
+    console.log('');
+    console.log('This clears Vite caches, stale WASM copies, and old @collet/ scope packages.');
+    process.exit(0);
+  }
+
+  if (args[0] !== 'init') {
+    console.log('Usage:');
+    console.log('  npx @colletdev/docs init [--claude|--codex|--cursor|--generic|--all]');
+    console.log('  npx @colletdev/docs purge  (alias for npx collet-purge)');
+    console.log('');
+    console.log('Commands:');
+    console.log('  init     Set up AI agent context for Collet components');
+    console.log('  purge    Clear stale WASM/CSS/Vite caches after upgrading');
+    console.log('');
+    console.log('Options (init):');
+    console.log('  --claude   Claude Code skills (.claude/skills/collet/)');
+    console.log('  --codex    OpenAI Codex (AGENTS.md)');
+    console.log('  --cursor   Cursor AI (.cursor/rules/collet.md)');
+    console.log('  --generic  Plain COLLET.md at project root');
+    console.log('  --all      All formats');
+    console.log('');
+    console.log('Default: auto-detects from project structure (falls back to --claude)');
+    process.exit(0);
+  }
+
+  const tools = detectTools();
+  const framework = detectFramework();
+
+  console.log('');
+  console.log(`Collet AI Setup — ${framework ? framework.charAt(0).toUpperCase() + framework.slice(1) + ' project' : 'no framework detected'}`);
+  console.log('─'.repeat(50));
+
+  for (const tool of tools) {
+    switch (tool) {
+      case 'claude': setupClaude(framework); break;
+      case 'codex': setupCodex(framework); break;
+      case 'cursor': setupCursor(framework); break;
+      case 'generic': setupGeneric(framework); break;
+    }
+  }
+
+  console.log('');
+  console.log('Done. Your AI agent now has full Collet component knowledge.');
+  console.log('Reference: 7 doc files from @colletdev/docs (108 KB total)');
+  console.log('');
+}
+
+main();