@cocoar/vue-ui 3.1.0 → 3.2.0-beta.6

package/skills/cocoar-vue-ui/references/components/data-grid/multi-select.md

@@ -0,0 +1,193 @@
+<!-- Generated from apps/docs/components/data-grid/multi-select.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Multi-Select & Tag-Select Columns (New in 2.0)
+
+Two column shortcuts for multi-value cells. Both store the cell value as `T[]` and share the same renderer — they differ only in the editor surface and which configurator options are available.
+
+| | Editor | When to use |
+|--|--|--|
+| **`col.multiSelect()`** | `<CoarMultiSelect>` — standard trigger, dropdown shows all options with checkboxes | Curated option lists where the user picks N of M known values. Supports search, "Select all". |
+| **`col.tagSelect()`** | `<CoarTagSelect>` — trigger renders selected values as removable chips inline; dropdown shows only not-yet-selected options | When the visual identity of selected values matters at-a-glance, or when you want `.allowCreate()` to let users add free-form values. |
+
+```ts
+import { CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+CoarGridBuilder.create<Person>().columns([
+  (col) => col.field('name').flex(1),
+
+  (col) => col.multiSelect('tags', s => s.options(TAGS).searchable().showSelectAll())
+              .editable(true),
+
+  (col) => col.tagSelect('skills', s => s.options(SKILLS).allowCreate().display('chips'))
+              .editable(true),
+])
+```
+
+## Edit-mode flow
+
+| Action | Result |
+|--------|--------|
+| Double-click cell (or Enter / F2) | Opens the editor and **auto-opens the dropdown** via `afterGuiAttached` |
+| Toggle a checkbox (multiSelect) / pick an option (tagSelect) | Updates the editor's working array. Dropdown stays open. |
+| Click outside the dropdown / Tab / Enter | Commits — AG Grid pulls the final array via `getValue()` |
+| Escape | Cancels (no commit) |
+
+Unlike `col.select()` (which auto-commits on every pick because the single-value edit is *one* click), multi-value editors deliberately keep the dropdown open so the user can complete the selection. Focus-preservation prevents AG Grid's `stopEditingWhenCellsLoseFocus` from committing the array prematurely when the user clicks options in the body-teleported dropdown.
+
+## Rendering
+
+Both columns default to a comma-separated label list. Switch to chips via the configurator:
+
+```ts
+col.multiSelect('tags', s => s.options(TAGS).display('chips'))
+col.tagSelect('skills', s => s.options(SKILLS).display('chips'))
+```
+
+The shared renderer (`CoarMultiSelectCellRenderer`) looks up labels from `options` — values that aren't in the option list (only possible via `col.tagSelect().allowCreate()`) fall back to `String(value)`.
+
+## Example
+
+**Demo — `data-grid/demos/GridMultiSelect.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="height: 380px;">
+      <CoarDataGrid :builder="builder" />
+    </div>
+    <div style="margin-top: 12px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+      Double-click <code>tags</code> for a checkbox-list dropdown (multi-select). Double-click <code>skills</code> for a chip-style trigger (tag-select). Both cells store <code>T[]</code>; commit happens on click-outside / Tab / Enter.
+    </div>
+    <div
+      v-if="lastChange"
+      style="margin-top: 8px; padding: 8px 12px; border-radius: 6px; background: var(--coar-surface-neutral-subtle); font-size: 13px;"
+    >
+      Last change: <strong>{{ lastChange.row }}</strong> —
+      <code>{{ lastChange.field }}</code> →
+      <strong>{{ lastChange.newValue }}</strong>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Person {
+  id: number;
+  name: string;
+  tags: string[];
+  skills: string[];
+}
+
+const TAGS = [
+  { value: 'priority', label: 'Priority' },
+  { value: 'remote',   label: 'Remote' },
+  { value: 'onsite',   label: 'Onsite' },
+  { value: 'lead',     label: 'Lead' },
+  { value: 'intern',   label: 'Intern' },
+];
+
+const SKILLS = [
+  { value: 'ts',  label: 'TypeScript' },
+  { value: 'vue', label: 'Vue' },
+  { value: 'go',  label: 'Go' },
+  { value: 'sql', label: 'SQL' },
+  { value: 'k8s', label: 'Kubernetes' },
+];
+
+const data = ref<Person[]>([
+  { id: 1, name: 'Alice Johnson',  tags: ['priority', 'remote'], skills: ['ts', 'vue'] },
+  { id: 2, name: 'Bob Smith',      tags: ['onsite'],             skills: ['go', 'sql'] },
+  { id: 3, name: 'Carol Williams', tags: ['lead', 'priority'],   skills: ['ts', 'k8s'] },
+  { id: 4, name: 'David Brown',    tags: [],                     skills: ['vue'] },
+]);
+
+const lastChange = shallowRef<{ row: string; field: string; newValue: string } | null>(null);
+
+const builder = CoarGridBuilder.create<Person>()
+  .columns([
+    (col) => col.field('name').header('Name').flex(1),
+
+    // col.multiSelect — checkbox-list dropdown, chips renderer
+    (col) =>
+      col
+        .multiSelect('tags', (s) =>
+          s.options(TAGS).searchable().showSelectAll().display('chips'),
+        )
+        .header('Tags (multiSelect)')
+        .width(260)
+        .editable(true),
+
+    // col.tagSelect — chip-style trigger, allow-create, text renderer (default)
+    (col) =>
+      col
+        .tagSelect('skills', (s) => s.options(SKILLS).allowCreate())
+        .header('Skills (tagSelect)')
+        .width(260)
+        .editable(true),
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus()
+  .onCellValueChanged((event) => {
+    if (!event.data || !event.colDef.field) return;
+    const next = event.newValue;
+    lastChange.value = {
+      row: event.data.name,
+      field: event.colDef.field,
+      newValue: Array.isArray(next) ? `[${next.join(', ')}]` : String(next),
+    };
+  });
+</script>
+```
+
+## Row-aware options
+
+Pass a function for per-row option lists — both renderer (label lookup) and editor (dropdown) call it with the current row:
+
+```ts
+col.multiSelect('perms', s => s.options(row => permsFor(row.role)))
+   .editable(true)
+```
+
+## API
+
+### `col.multiSelect(field, configurator)`
+
+Cell value type: `T[]`.
+
+| Configurator method | Type | Description |
+|---|---|---|
+| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
+| `.clearable(value?)` | `boolean = true` | Show a clear button in the editor |
+| `.searchable(value?)` | `boolean = true` | Enable search/filter in the dropdown |
+| `.showSelectAll(value?)` | `boolean = true` | Show a "Select all" row at the top of the dropdown |
+| `.placeholder(value)` | `string` | Placeholder shown when no values are selected |
+| `.searchPlaceholder(value)` | `string` | Search-input placeholder (used with `.searchable()`) |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
+| `.display(value)` | `'text' \| 'chips'` | Renderer display mode (default: `'text'`) |
+
+### `col.tagSelect(field, configurator)`
+
+Cell value type: `T[]`. The cell renderer is shared with `col.multiSelect()`; only the editor differs.
+
+| Configurator method | Type | Description |
+|---|---|---|
+| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
+| `.placeholder(value)` | `string` | Placeholder shown when no values are selected |
+| `.searchPlaceholder(value)` | `string` | Search-input placeholder |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
+| `.allowCreate(value?)` | `boolean = true` | Let the user type free-form values not in `options` |
+| `.display(value)` | `'text' \| 'chips'` | Renderer display mode (default: `'text'`) |
+
+`CoarSelectOption<T>` is `{ value: T, label: string, disabled?: boolean, group?: string, icon?: string }`.
+
+## Layered overrides
+
+Same escape-hatches as the other column shortcuts — chain `.cellEditorConfig(...)` or `.cellRendererConfig(...)` after the factory call to swap in custom components while keeping the rest of the column setup.
+
+```ts
+col.multiSelect('tags', s => s.options(TAGS))
+   .editable(true)
+   .cellEditorConfig(MyCustomMultiEditor, { /* ... */ })
+```

package/skills/cocoar-vue-ui/references/components/data-grid/number.md

@@ -0,0 +1,147 @@
+<!-- Generated from apps/docs/components/data-grid/number.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Number Column
+
+`col.number(field, …)` is locale-aware in both display and editing. Two forms — pick by need:
+
+| Form | Effect |
+|------|--------|
+| `col.number('amount')` or `col.number('amount', { decimals: 2 })` | **Renderer only** — locale-formatted number, no editor (legacy / display-only) |
+| `col.number('amount', n => n.decimals(2).min(0).max(100))` | **Renderer + editor** — same formatting plus `CoarNumberCellEditor` for in-cell editing |
+
+The callback form bundles `CoarNumberCellEditor` automatically. Adding `.editable(true)` on the outer chain enables it.
+
+## Example
+
+**Demo — `data-grid/demos/GridNumber.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="height: 320px;">
+      <CoarDataGrid :builder="builder" />
+    </div>
+    <div style="margin-top: 12px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+      Double-click any quantity or price cell. Locale-aware parsing — try <code>1.234,56</code> in German or <code>1,234.56</code> in English.
+    </div>
+    <div
+      v-if="lastChange"
+      style="margin-top: 8px; padding: 8px 12px; border-radius: 6px; background: var(--coar-surface-neutral-subtle); font-size: 13px;"
+    >
+      Last change: <strong>{{ lastChange.field }}</strong> on
+      <strong>{{ lastChange.row }}</strong> →
+      <code>{{ lastChange.newValue }}</code>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Item {
+  id: number;
+  product: string;
+  qty: number;
+  price: number;
+}
+
+const data = ref<Item[]>([
+  { id: 1, product: 'Widget A', qty: 12, price: 49.95 },
+  { id: 2, product: 'Widget B', qty: 0,  price: 19.50 },
+  { id: 3, product: 'Widget C', qty: 5,  price: 199.00 },
+  { id: 4, product: 'Widget D', qty: 28, price: 7.25 },
+]);
+
+const lastChange = shallowRef<{ row: string; field: string; newValue: number } | null>(null);
+
+const builder = CoarGridBuilder.create<Item>()
+  .columns([
+    (col) => col.field('product').header('Product').flex(1),
+    (col) =>
+      col
+        .number('qty', (n) => n.decimals(0).min(0).max(9999).step(1).stepperButtons('both').size('s'))
+        .header('Qty')
+        .width(140)
+        .editable(true),
+    (col) =>
+      col
+        .number('price', (n) => n.decimals(2).min(0).step(0.01))
+        .header('Price')
+        .width(140)
+        .editable(true),
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus()
+  .onCellValueChanged((event) => {
+    if (!event.data || !event.colDef.field) return;
+    lastChange.value = {
+      row: event.data.product,
+      field: event.colDef.field,
+      newValue: event.newValue,
+    };
+  });
+</script>
+```
+
+```ts
+CoarGridBuilder.create<Item>().columns([
+  (col) => col.field('product').flex(1),
+  (col) =>
+    col
+      .number('qty', n => n.min(0).max(9999).step(1).stepperButtons('both'))
+      .editable(true),
+  (col) =>
+    col
+      .number('price', n => n.decimals(2).min(0).step(0.01))
+      .editable(true),
+])
+.stopEditingWhenCellsLoseFocus()
+.onCellValueChanged(event => save(event.data, event.colDef.field, event.newValue));
+```
+
+The renderer uses `useL10n().fmtNumber()` so the display reactively follows the active locale (try the locale switcher in the docs nav). The editor uses Maskito for locale-aware parsing — `1.234,56` in `de-AT` and `1,234.56` in `en-US` both yield the same numeric value.
+
+## Edit-mode flow
+
+| Action | Result |
+|--------|--------|
+| Double-click cell (or Enter / F2) | Opens `CoarNumberCellEditor` with focus, existing value selected |
+| Type a digit / `.` / `,` / `-` on a focused cell | Opens editor seeded with that key |
+| Tab | Commits + moves to the next editable cell |
+| Enter | Commits + stays |
+| Escape | Cancels |
+
+## Layered overrides
+
+```ts
+// Override editor (e.g. add custom validation)
+col.number('qty', n => n.min(0)).editable(true).cellEditorConfig(MyOwnEditor, { ... })
+
+// Override editable per-row
+col.number('qty', n => n.min(0)).editable(row => !row.archived)
+```
+
+## API
+
+### `col.number(field, configOrCallback?)`
+
+**Config-object form** (legacy — renderer only):
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `decimals` | `number` | Number of decimal places |
+
+**Callback form** (renderer + editor — `NumberColumnConfigurator`):
+
+| Method | Type | Renderer / Editor | Description |
+|--------|------|-------------------|-------------|
+| `.decimals(value)` | `number` | both | Decimal places |
+| `.min(value)` | `number` | editor | Minimum allowed value |
+| `.max(value)` | `number` | editor | Maximum allowed value |
+| `.step(value)` | `number` | editor | Step increment for arrows / stepper |
+| `.stepperButtons(value)` | `'none' \| 'increment' \| 'decrement' \| 'both'` | editor | Stepper button mode |
+| `.placeholder(value)` | `string` | editor | Placeholder text |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | editor | Input size (default: `'s'`) |
+
+Editor commits via `getValue()` returning a `number | null`. Combine with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.

package/skills/cocoar-vue-ui/references/components/data-grid/select.md

@@ -0,0 +1,202 @@
+<!-- Generated from apps/docs/components/data-grid/select.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Select Column
+
+`col.select(field, configurator)` declares a select column whose renderer shows the **label** of the matched option and whose editor is `<CoarSelect>` — same visual language as forms, with the dropdown teleported to `<body>` so it can overflow the cell freely.
+
+```ts
+import { CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+const ROLES = [
+  { value: 'eng', label: 'Engineer' },
+  { value: 'des', label: 'Designer' },
+  { value: 'mgr', label: 'Manager' },
+];
+
+CoarGridBuilder.create<Person>().columns([
+  (col) => col.field('name').flex(1),
+  (col) => col.select('role', s => s.options(ROLES)).editable(true),
+])
+```
+
+The configurator's `options` is required — there's no useful "select column without options".
+
+## Edit-mode flow
+
+| Action | Result |
+|--------|--------|
+| Double-click cell (or Enter / F2) | Opens `CoarSelectCellEditor` and **auto-opens the dropdown** via `afterGuiAttached` |
+| Click an option (or Enter on highlighted) | Auto-commits + exits edit mode in one step |
+| Up / Down | Highlight previous / next option |
+| Type a character (when `searchable: true`) | Filters the option list |
+| Escape | Closes dropdown; pressing again cancels edit |
+
+The auto-commit is intentional — for a select, picking an option **is** the edit. Tab-through-edit-mode still works on the surrounding cells; the select cell just commits faster than free-form text would.
+
+## Example
+
+**Demo — `data-grid/demos/GridSelect.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="height: 320px;">
+      <CoarDataGrid :builder="builder" />
+    </div>
+    <div style="margin-top: 12px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+      Double-click any role / status / country cell to open the dropdown. Selecting an option auto-commits.
+    </div>
+    <div
+      v-if="lastChange"
+      style="margin-top: 8px; padding: 8px 12px; border-radius: 6px; background: var(--coar-surface-neutral-subtle); font-size: 13px;"
+    >
+      Last change: <strong>{{ lastChange.row }}</strong> —
+      <code>{{ lastChange.field }}</code> →
+      <strong>{{ lastChange.newValue }}</strong>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Person {
+  id: number;
+  name: string;
+  role: 'eng' | 'des' | 'mgr';
+  status: 'active' | 'pending' | 'archived';
+  country: string;
+}
+
+const ROLES = [
+  { value: 'eng', label: 'Engineer' },
+  { value: 'des', label: 'Designer' },
+  { value: 'mgr', label: 'Manager' },
+];
+
+const STATUSES = [
+  { value: 'active',   label: 'Active' },
+  { value: 'pending',  label: 'Pending' },
+  { value: 'archived', label: 'Archived' },
+];
+
+const COUNTRIES = [
+  { value: 'AT', label: 'Austria' },
+  { value: 'DE', label: 'Germany' },
+  { value: 'CH', label: 'Switzerland' },
+  { value: 'IT', label: 'Italy' },
+  { value: 'FR', label: 'France' },
+  { value: 'ES', label: 'Spain' },
+  { value: 'PT', label: 'Portugal' },
+  { value: 'NL', label: 'Netherlands' },
+  { value: 'BE', label: 'Belgium' },
+  { value: 'SE', label: 'Sweden' },
+];
+
+const data = ref<Person[]>([
+  { id: 1, name: 'Alice Johnson',  role: 'eng', status: 'active',   country: 'AT' },
+  { id: 2, name: 'Bob Smith',      role: 'des', status: 'pending',  country: 'DE' },
+  { id: 3, name: 'Carol Williams', role: 'mgr', status: 'active',   country: 'CH' },
+  { id: 4, name: 'David Brown',    role: 'eng', status: 'archived', country: 'FR' },
+]);
+
+const lastChange = shallowRef<{ row: string; field: string; newValue: string } | null>(null);
+
+const builder = CoarGridBuilder.create<Person>()
+  .columns([
+    (col) => col.field('name').header('Name').flex(1),
+    (col) =>
+      col
+        .select('role', (s) => s.options(ROLES))
+        .header('Role')
+        .width(140)
+        .editable(true),
+    (col) =>
+      col
+        .select('status', (s) => s.options(STATUSES).clearable())
+        .header('Status')
+        .width(140)
+        .editable((row) => row.status !== 'archived'),
+    (col) =>
+      col
+        .select('country', (s) =>
+          s.options(COUNTRIES).searchable().searchPlaceholder('Filter countries…'),
+        )
+        .header('Country')
+        .width(160)
+        .editable(true),
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus()
+  .onCellValueChanged((event) => {
+    if (!event.data || !event.colDef.field) return;
+    lastChange.value = {
+      row: event.data.name,
+      field: event.colDef.field,
+      newValue: String(event.newValue),
+    };
+  });
+</script>
+```
+
+```ts
+CoarGridBuilder.create<Person>().columns([
+  (col) => col.field('name').flex(1),
+
+  // simple
+  (col) => col.select('role', s => s.options(ROLES)).editable(true),
+
+  // clearable + per-row gating (archived rows are read-only)
+  (col) =>
+    col.select('status', s => s.options(STATUSES).clearable())
+       .editable(row => row.status !== 'archived'),
+
+  // searchable for long lists
+  (col) =>
+    col.select('country', s => s.options(COUNTRIES).searchable())
+       .editable(true),
+])
+.stopEditingWhenCellsLoseFocus();
+```
+
+## Row-aware options
+
+Pass a function instead of a static array to compute options per row:
+
+```ts
+col.select('parent', s =>
+  s.options(row => allowedParents(row.type))
+).editable(true)
+```
+
+Both renderer (label lookup) and editor (dropdown options) call the function with the current row, so display and edit stay consistent.
+
+## Layered overrides
+
+```ts
+// Replace the editor entirely (drops the configurator)
+col.select('role', s => s.options(ROLES))
+   .editable(true)
+   .cellEditorConfig(MyCustomSelect, { … })
+
+// Keep the bundled renderer + editor, override editable
+col.select('role', s => s.options(ROLES)).editable(false)
+```
+
+## API
+
+### `col.select(field, configurator)`
+
+| Configurator method | Type | Description |
+|--------|------|-------------|
+| `.options(value)` | `CoarSelectOption<T>[] \| (row) => CoarSelectOption<T>[]` | **Required.** Static array or per-row function. |
+| `.clearable(value?)` | `boolean = true` | Show a clear button in the editor |
+| `.searchable(value?)` | `boolean = true` | Enable search/filter in the dropdown |
+| `.placeholder(value)` | `string` | Placeholder shown when no value is selected |
+| `.searchPlaceholder(value)` | `string` | Search-input placeholder (used with `.searchable()`) |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Trigger size (default: `'s'`) |
+
+`CoarSelectOption<T>` is `{ value: T, label: string, disabled?: boolean, group?: string, icon?: string }`.
+
+Editor commits via `getValue()` returning the option `value`. The dropdown panel is teleported to `<body>` (Coar overlay-host) so it can extend past the cell / grid boundaries without clipping.

package/skills/cocoar-vue-ui/references/components/data-grid/text.md

@@ -0,0 +1,127 @@
+<!-- Generated from apps/docs/components/data-grid/text.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Text Column
+
+`col.text(field, configurator?)` declares a text column whose editor is `<CoarTextInput>` — same visual language as forms, fitted into the cell.
+
+```ts
+import { CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+CoarGridBuilder.create<Person>().columns([
+  (col) => col.text('name').editable(true),
+  (col) => col.text('email', t => t.placeholder('user@example.com').maxLength(120)).editable(true),
+])
+```
+
+Read-only display uses AG Grid's default text rendering — same as plain `.field()`. The shortcut adds:
+- A configurable `CoarTextCellEditor` that opens on double-click / Enter / F2
+- `sortable: true` by default
+
+## Edit-mode flow
+
+| Action | Result |
+|--------|--------|
+| Double-click cell (or Enter / F2) | Opens `CoarTextCellEditor` with focus on the input, existing value selected |
+| Type a printable key on a focused cell | Opens editor seeded with that key (replace mode) |
+| Tab | Commits + moves focus to the next editable cell, opening its editor automatically |
+| Enter | Commits + stays |
+| Escape | Cancels |
+
+Toggles fire `cellValueChanged` like any other commit, so a single grid-level handler covers all column types.
+
+## Example
+
+**Demo — `data-grid/demos/GridText.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="height: 320px;">
+      <CoarDataGrid :builder="builder" />
+    </div>
+    <div style="margin-top: 12px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+      Double-click any name or email cell. <strong>Tab</strong> commits and moves to the next editable cell, <strong>Enter</strong> commits, <strong>Escape</strong> cancels.
+    </div>
+    <div
+      v-if="lastChange"
+      style="margin-top: 8px; padding: 8px 12px; border-radius: 6px; background: var(--coar-surface-neutral-subtle); font-size: 13px;"
+    >
+      Last change: <strong>{{ lastChange.field }}</strong> on
+      <strong>{{ lastChange.row }}</strong> →
+      <code>{{ lastChange.newValue }}</code>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Person {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const data = ref<Person[]>([
+  { id: 1, name: 'Alice Johnson',  email: 'alice@example.com',  role: 'Engineer' },
+  { id: 2, name: 'Bob Smith',      email: 'bob@example.com',    role: 'Designer' },
+  { id: 3, name: 'Carol Williams', email: 'carol@example.com',  role: 'Manager' },
+  { id: 4, name: 'David Brown',    email: 'david@example.com',  role: 'Engineer' },
+]);
+
+const lastChange = shallowRef<{ row: string; field: string; newValue: string } | null>(null);
+
+const builder = CoarGridBuilder.create<Person>()
+  .columns([
+    (col) => col.text('name', (t) => t.placeholder('Name').maxLength(80)).header('Name').flex(1).editable(true),
+    (col) => col.text('email', (t) => t.placeholder('user@example.com').maxLength(120)).header('Email').flex(1).editable(true),
+    (col) => col.field('role').header('Role').width(140),       // not editable
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus()
+  .onCellValueChanged((event) => {
+    if (!event.data || !event.colDef.field) return;
+    lastChange.value = {
+      row: event.data.name,
+      field: event.colDef.field,
+      newValue: String(event.newValue),
+    };
+  });
+</script>
+```
+
+```ts
+CoarGridBuilder.create<Person>().columns([
+  (col) => col.text('name', t => t.placeholder('Name').maxLength(80)).editable(true),
+  (col) => col.text('email', t => t.placeholder('user@example.com').maxLength(120)).editable(true),
+  (col) => col.field('role'),                                  // not editable
+])
+.stopEditingWhenCellsLoseFocus()
+.onCellValueChanged(event => save(event.data, event.colDef.field, event.newValue));
+```
+
+## Layered overrides
+
+```ts
+// Replace the editor (drops the configurator)
+col.text('name').editable(true).cellEditorConfig(MyCustomEditor, { ... })
+
+// Keep the bundled editor, override editable
+col.text('name').editable(row => !row.locked)
+```
+
+## API
+
+### `col.text(field, configurator?)`
+
+| Configurator method | Type | Description |
+|--------|------|-------------|
+| `.placeholder(value)` | `string` | Placeholder shown when input is empty |
+| `.maxLength(value)` | `number` | Max input length |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Input size (default: `'s'`) |
+| `.prefix(value)` | `string` | Text shown before the input value |
+| `.suffix(value)` | `string` | Text shown after the input value |
+
+Editor commits via `getValue()` per AG Grid's contract — Tab / Enter / Escape are handled by AG Grid's native edit-mode logic. Combine with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.