@colletdev/docs 0.2.1

package/vue.md

@@ -0,0 +1,195 @@
+# Collet Vue Reference
+
+Vue 3 wrappers for the Collet component library. Auto-generated from
+`custom-elements.json` via `scripts/generate-vue.mjs`.
+
+---
+
+## Package
+
+```
+@colletdev/vue
+```
+
+**Peer dependencies:** `vue >= 3.3.0`, `@colletdev/core >= 0.1.0`
+
+## Architecture
+
+Vue wrappers use `defineComponent` with typed props, emits, and `expose()`.
+They handle:
+
+- **Attribute serialization** — objects/arrays synced via `watch` + `setAttribute`
+- **Event bridging** — `@cx-{event}` emits typed CustomEvents
+- **Slot projection** — named slots via `h('div', { slot: 'name' }, slots.name())`
+- **Typed expose** — `expose()` provides imperative methods + raw element ref
+
+### Package Structure
+
+```
+packages/vue/
+  src/                ← Auto-generated wrappers (DO NOT EDIT)
+    button.ts
+    dialog.ts
+    ...
+    index.ts          ← Barrel exports + type re-exports
+    types.ts          ← Shared TypeScript interfaces
+    global.d.ts       ← Volar GlobalComponents augmentation
+  dist/               ← Compiled output (JS + .d.ts)
+```
+
+---
+
+## Patterns
+
+### Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Dialog, type DialogRef } from '@colletdev/vue';
+
+const dialogRef = ref<DialogRef | null>(null);
+</script>
+
+<template>
+  <Button label="Open" @cx-click="dialogRef?.open()" />
+  <Dialog
+    ref="dialogRef"
+    title="Confirm"
+    @cx-close="console.log($event.detail.reason)"
+  >
+    <p>Are you sure?</p>
+    <template #footer>
+      <Button label="OK" variant="filled" />
+    </template>
+  </Dialog>
+</template>
+```
+
+### Event Handling
+
+Events use `@cx-{name}` syntax. The `$event` is a typed `CustomEvent<Detail>`:
+
+```vue
+<TextInput
+  label="Email"
+  @cx-input="(e) => value = e.detail.value"
+  @cx-change="(e) => validate(e.detail.value)"
+  @cx-focus="focused = true"
+  @cx-keydown="(e) => e.detail.key === 'Enter' && submit()"
+/>
+```
+
+### Imperative Methods
+
+Components with methods expose them via `expose()`. Access through template refs:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select, type SelectRef } from '@colletdev/vue';
+
+const selectRef = ref<SelectRef | null>(null);
+const open = () => selectRef.value?.open();
+</script>
+
+<template>
+  <Select ref="selectRef" label="Country" :items="countries" />
+  <button @click="open">Open dropdown</button>
+</template>
+```
+
+### Named Slots
+
+Vue named slots map to Shadow DOM slots:
+
+```vue
+<Card>
+  <template #header><h3>Title</h3></template>
+  <p>Body content (default slot)</p>
+  <template #footer>
+    <Button label="Action" />
+  </template>
+</Card>
+```
+
+Under the hood, the wrapper renders `h('div', { slot: 'name' }, slots.name())`.
+
+### Complex Props (Structured Data)
+
+Props accepting arrays/objects are synced via `watch` + `setAttribute(JSON.stringify())`:
+
+```vue
+<Table
+  caption="Users"
+  :columns="[
+    { id: 'name', header: 'Name', sortable: true },
+    { id: 'email', header: 'Email' },
+  ]"
+  :rows="rows"
+  :sorts="[{ column_id: 'name', direction: 'asc' }]"
+  @cx-sort="handleSort"
+/>
+```
+
+The `:prop` binding passes the object; the wrapper serializes it automatically.
+
+### Form Integration
+
+Form-associated components work with `v-model` (coming) and template-driven forms:
+
+```vue
+<form @submit.prevent="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 `watch` +
+`setAttribute` to avoid Vue setting them as DOM properties:
+
+```vue
+<!-- Works correctly — title goes through setAttribute -->
+<Dialog title="My Dialog" />
+<Table :loading="75" />
+```
+
+---
+
+## TypeScript & Volar
+
+### Type Imports
+
+```ts
+import type {
+  TableColumn, TableRow, SelectOption, MenuEntry,
+  InputDetail, ClickDetail, CloseDetail,
+  DialogRef, SelectRef,
+} from '@colletdev/vue';
+```
+
+### Volar Autocomplete
+
+Import `@colletdev/vue/global` in your `env.d.ts` or `shims-vue.d.ts`:
+
+```ts
+/// <reference types="@colletdev/vue/global" />
+```
+
+This registers all Collet components in `GlobalComponents`, giving Volar
+full autocomplete and type checking in templates without explicit imports.
+
+---
+
+## Codegen
+
+Vue wrappers are generated by `scripts/generate-vue.mjs`. Configuration
+lives in `scripts/component-config.mjs` (shared across all framework generators).
+
+**Do not edit** files in `packages/vue/src/` — they are overwritten by
+`bash scripts/build-packages.sh`.
+
+Compiled output goes to `packages/vue/dist/` via `tsc`.