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

package/skills/cocoar-vue-ui/references/components/context-menu.md

@@ -0,0 +1,355 @@
+<!-- Generated from apps/docs/components/context-menu.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Context Menu
+
+Open a menu at the pointer position on right-click. The `useContextMenu` composable manages open/close state and cursor coordinates, while `CoarContextMenu` renders the menu as a floating overlay with automatic viewport clamping.
+
+```ts
+import { useContextMenu, CoarContextMenu } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Call `useContextMenu()` to get a controller, bind `menu.open` to `@contextmenu`, and place your menu items inside `<CoarContextMenu>`. The menu closes automatically when an item is clicked, when clicking outside, pressing Escape, or scrolling.
+
+**Demo — `context-menu/demos/ContextMenuBasic.vue`**
+
+```vue
+<template>
+  <div>
+    <div
+      class="target-area"
+      @contextmenu="menu.open"
+    >
+      Right-click anywhere in this area
+    </div>
+
+    <CoarContextMenu :menu="menu">
+      <CoarMenuItem icon="copy" label="Copy" @clicked="onAction('Copy')" />
+      <CoarMenuItem icon="clipboard" label="Paste" @clicked="onAction('Paste')" />
+      <CoarMenuDivider />
+      <CoarMenuItem icon="pencil" label="Rename" @clicked="onAction('Rename')" />
+      <CoarMenuItem icon="trash-2" label="Delete" @clicked="onAction('Delete')" />
+    </CoarContextMenu>
+
+    <p class="status">Last action: {{ lastAction || 'none' }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useContextMenu, CoarContextMenu, CoarMenuItem, CoarMenuDivider } from '@cocoar/vue-ui';
+
+const menu = useContextMenu();
+const lastAction = ref('');
+
+function onAction(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<style scoped>
+.target-area {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 160px;
+  border: 2px dashed var(--coar-border-neutral-tertiary);
+  border-radius: var(--coar-radius-m);
+  color: var(--coar-text-neutral-secondary);
+  font-size: var(--coar-font-size-s);
+  user-select: none;
+}
+
+.status {
+  margin-top: 8px;
+  font-size: 13px;
+  color: var(--coar-text-neutral-secondary);
+}
+</style>
+```
+
+## With Headings & Submenus
+
+All standard menu features work inside context menus — headings, dividers, icons, and inline submenus via `CoarSubExpand`.
+
+**Demo — `context-menu/demos/ContextMenuSubmenus.vue`**
+
+```vue
+<template>
+  <div>
+    <div
+      class="target-area"
+      @contextmenu="menu.open"
+    >
+      Right-click for a menu with headings and submenus
+    </div>
+
+    <CoarContextMenu :menu="menu">
+      <CoarMenuHeading label="Edit" />
+      <CoarMenuItem icon="scissors" label="Cut" @clicked="onAction('Cut')" />
+      <CoarMenuItem icon="copy" label="Copy" @clicked="onAction('Copy')" />
+      <CoarMenuItem icon="clipboard" label="Paste" @clicked="onAction('Paste')" />
+      <CoarMenuDivider />
+      <CoarSubExpand label="Sort by" icon="arrow-up-down">
+        <CoarMenuItem label="Name" @clicked="onAction('Sort by Name')" />
+        <CoarMenuItem label="Date" @clicked="onAction('Sort by Date')" />
+        <CoarMenuItem label="Size" @clicked="onAction('Sort by Size')" />
+      </CoarSubExpand>
+      <CoarMenuDivider />
+      <CoarMenuItem icon="settings" label="Preferences" @clicked="onAction('Preferences')" />
+    </CoarContextMenu>
+
+    <p class="status">Last action: {{ lastAction || 'none' }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  useContextMenu,
+  CoarContextMenu,
+  CoarMenuItem,
+  CoarMenuDivider,
+  CoarMenuHeading,
+  CoarSubExpand,
+} from '@cocoar/vue-ui';
+
+const menu = useContextMenu();
+const lastAction = ref('');
+
+function onAction(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<style scoped>
+.target-area {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 160px;
+  border: 2px dashed var(--coar-border-neutral-tertiary);
+  border-radius: var(--coar-radius-m);
+  color: var(--coar-text-neutral-secondary);
+  font-size: var(--coar-font-size-s);
+  user-select: none;
+}
+
+.status {
+  margin-top: 8px;
+  font-size: 13px;
+  color: var(--coar-text-neutral-secondary);
+}
+</style>
+```
+
+## Flyout Submenus
+
+Use `CoarSubFlyout` inside a context menu for nested flyout panels — useful for status changes, priority selectors, etc.
+
+**Demo — `context-menu/demos/ContextMenuFlyout.vue`**
+
+```vue
+<template>
+  <div>
+    <div class="target-area" @contextmenu="menu.open">
+      Right-click for a menu with flyout submenus
+    </div>
+
+    <CoarContextMenu :menu="menu">
+      <CoarMenuItem icon="pencil" label="Edit" @clicked="onAction('Edit')" />
+      <CoarMenuDivider />
+      <CoarSubFlyout label="Set Status" icon="circle-alert">
+        <CoarMenu>
+          <CoarMenuItem label="New" @clicked="onAction('Status: New')" />
+          <CoarMenuItem label="In Progress" @clicked="onAction('Status: In Progress')" />
+          <CoarMenuItem label="Done" @clicked="onAction('Status: Done')" />
+        </CoarMenu>
+      </CoarSubFlyout>
+      <CoarSubFlyout label="Priority" icon="flag">
+        <CoarMenu>
+          <CoarMenuItem label="Low" @clicked="onAction('Priority: Low')" />
+          <CoarMenuItem label="Medium" @clicked="onAction('Priority: Medium')" />
+          <CoarMenuItem label="High" @clicked="onAction('Priority: High')" />
+        </CoarMenu>
+      </CoarSubFlyout>
+      <CoarMenuDivider />
+      <CoarMenuItem icon="trash-2" label="Delete" @clicked="onAction('Delete')" />
+    </CoarContextMenu>
+
+    <p class="status">Last action: {{ lastAction || 'none' }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  useContextMenu,
+  CoarContextMenu,
+  CoarMenu,
+  CoarMenuItem,
+  CoarMenuDivider,
+  CoarSubFlyout,
+} from '@cocoar/vue-ui';
+
+const menu = useContextMenu();
+const lastAction = ref('');
+
+function onAction(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<style scoped>
+.target-area {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 160px;
+  border: 2px dashed var(--coar-border-neutral-tertiary);
+  border-radius: var(--coar-radius-m);
+  color: var(--coar-text-neutral-secondary);
+  font-size: var(--coar-font-size-s);
+  user-select: none;
+}
+
+.status {
+  margin-top: 8px;
+  font-size: 13px;
+  color: var(--coar-text-neutral-secondary);
+}
+</style>
+```
+
+## Data Grid Integration
+
+Use separate `useContextMenu()` instances for cell and viewport right-clicks. The data grid builder provides `onCellContextMenu` and `onViewportContextMenu` handlers that give you the mouse event to pass into `menu.open()`.
+
+**Demo — `context-menu/demos/ContextMenuDataGrid.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="height: 300px;">
+      <CoarDataGrid :builder="builder" />
+    </div>
+
+    <!-- Cell context menu (right-click on a row) -->
+    <CoarContextMenu :menu="cellMenu">
+      <CoarMenuItem icon="pencil" label="Edit" @clicked="onCellAction('Edit', selectedUser)" />
+      <CoarMenuItem icon="copy" label="Duplicate" @clicked="onCellAction('Duplicate', selectedUser)" />
+      <CoarMenuDivider />
+      <CoarMenuItem icon="trash-2" label="Delete" @clicked="onCellAction('Delete', selectedUser)" />
+    </CoarContextMenu>
+
+    <!-- Viewport context menu (right-click on empty area) -->
+    <CoarContextMenu :menu="viewportMenu">
+      <CoarMenuItem icon="plus" label="Add user" @clicked="onViewportAction('Add user')" />
+      <CoarMenuItem icon="refresh-cw" label="Refresh" @clicked="onViewportAction('Refresh')" />
+    </CoarContextMenu>
+
+    <p class="status">Last action: {{ lastAction || 'none' }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+import type { CellContextMenuEvent } from '@cocoar/vue-data-grid';
+import { useContextMenu, CoarContextMenu, CoarMenuItem, CoarMenuDivider } from '@cocoar/vue-ui';
+
+interface User {
+  name: string;
+  email: string;
+  role: string;
+}
+
+const data: User[] = [
+  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Engineer' },
+  { name: 'Bob Smith', email: 'bob@example.com', role: 'Designer' },
+  { name: 'Carol Williams', email: 'carol@example.com', role: 'Manager' },
+  { name: 'David Brown', email: 'david@example.com', role: 'Engineer' },
+  { name: 'Eve Davis', email: 'eve@example.com', role: 'Designer' },
+];
+
+const cellMenu = useContextMenu();
+const viewportMenu = useContextMenu();
+const selectedUser = ref<User | null>(null);
+const lastAction = ref('');
+
+const builder = CoarGridBuilder.create<User>()
+  .columns([
+    (col) => col.field('name').header('Name').flex(1),
+    (col) => col.field('email').header('Email').flex(1),
+    (col) => col.field('role').header('Role').width(120),
+  ])
+  .rowData(data)
+  .onCellContextMenu((event: CellContextMenuEvent<User>) => {
+    selectedUser.value = event.data ?? null;
+    if (event.event) {
+      cellMenu.open(event.event as MouseEvent);
+    }
+  })
+  .onViewportContextMenu((event: MouseEvent) => {
+    viewportMenu.open(event);
+  });
+
+function onCellAction(action: string, user: User | null) {
+  lastAction.value = `${action}: ${user?.name ?? 'unknown'}`;
+}
+
+function onViewportAction(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<style scoped>
+.status {
+  margin-top: 8px;
+  font-size: 13px;
+  color: var(--coar-text-neutral-secondary);
+}
+</style>
+```
+
+## Keeping the Menu Open
+
+By default, clicking a `CoarMenuItem` closes the entire context menu. Call `keepMenuOpen()` on the click event to prevent this — useful for toggles or multi-select actions.
+
+```vue
+<CoarMenuItem
+  label="Toggle dark mode"
+  icon="moon"
+  @clicked="(e) => { e.keepMenuOpen(); toggleDarkMode(); }"
+/>
+```
+
+## API
+
+### `useContextMenu()`
+
+Returns a `ContextMenuContext` object:
+
+| Property   | Type                          | Description                                    |
+|------------|-------------------------------|------------------------------------------------|
+| `isOpen`   | `Readonly<Ref<boolean>>`      | Whether the menu is currently visible          |
+| `position` | `Readonly<Ref<{x, y}>>`      | Cursor position where the menu was opened      |
+| `open`     | `(event: MouseEvent) => void` | Open at the event's cursor position            |
+| `close`    | `() => void`                  | Close the menu                                 |
+
+### `<CoarContextMenu>`
+
+| Prop   | Type                 | Required | Description                              |
+|--------|----------------------|----------|------------------------------------------|
+| `menu` | `ContextMenuContext` | Yes      | Controller returned by `useContextMenu()` |
+
+**Slot:** `default` — menu items (`CoarMenuItem`, `CoarMenuDivider`, `CoarMenuHeading`, `CoarSubExpand`, etc.)
+
+### Behavior
+
+- **Viewport clamping** — the menu repositions to stay within the window
+- **Click outside** — closes the menu
+- **Escape** — closes the menu
+- **Scroll** — closes the menu
+- **Auto-close on item click** — unless `keepMenuOpen()` is called

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

@@ -0,0 +1,213 @@
+<!-- Generated from apps/docs/components/data-grid/checkbox.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Checkbox Column
+
+`col.checkbox(field, configurator?)` renders a `<CoarCheckbox>` in each cell — same visual language as forms, just sized to fit the row. The renderer is **always read-only**; interactivity comes from edit-mode, exactly like text/number/select columns.
+
+```ts
+import { CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+CoarGridBuilder.create<Task>().columns([
+  (col) => col.checkbox('done').editable(true),
+  (col) => col.field('title').flex(1),
+])
+```
+
+## Edit-mode flow
+
+Without `.editable()` the checkbox is a read-only indicator. Adding `.editable(true)` (or a row-predicate) opts the column into AG Grid's standard edit-mode flow:
+
+| Action | Result |
+|--------|--------|
+| Double-click cell (or Enter / F2) | Opens `CoarCheckboxCellEditor` — interactive `<CoarCheckbox>` with focus on the input |
+| Space | Toggles the checkbox |
+| Tab | Commits + moves focus to the next editable cell, **opening its editor automatically** |
+| Enter | Commits + stays |
+| Escape | Cancels |
+
+The Tab-through-edit-mode pattern is AG Grid's native data-entry workflow — keyboard users can fly through editable cells without ever touching the mouse. Pair with `gridBuilder.stopEditingWhenCellsLoseFocus()` so clicking outside also commits.
+
+Toggles fire `cellValueChanged` like any other editor commit, so a single `gridBuilder.onCellValueChanged()` handler covers all column types — checkbox, text, number, custom editors.
+
+## Editable + per-row gating
+
+Pass a row-predicate to `.editable()` to disable the editor for individual rows. Locked rows render a read-only checkbox and can't be entered.
+
+**Demo — `data-grid/demos/GridCheckbox.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 "done" cell to enter edit mode. <strong>Space</strong> toggles, <strong>Tab</strong> commits and moves to the next editable cell, <strong>Escape</strong> cancels. Locked rows can't be entered.
+    </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.task }}</strong> —
+      <code>done</code> →
+      <strong>{{ lastChange.value ? 'true' : 'false' }}</strong>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Task {
+  id: number;
+  task: string;
+  done: boolean;
+  locked: boolean;
+}
+
+const data = ref<Task[]>([
+  { id: 1, task: 'Write specification',     done: true,  locked: false },
+  { id: 2, task: 'Implement renderer',      done: false, locked: false },
+  { id: 3, task: 'Ship to production',      done: false, locked: true  },
+  { id: 4, task: 'Update changelog',        done: true,  locked: false },
+  { id: 5, task: 'Archive (legacy)',        done: true,  locked: true  },
+]);
+
+const lastChange = shallowRef<{ task: string; value: boolean } | null>(null);
+
+const builder = CoarGridBuilder.create<Task>()
+  .columns([
+    (col) => col.checkbox('done').width(70).editable((row) => !row.locked),
+    (col) => col.field('task').header('Task').flex(1),
+    (col) => col.checkbox('locked').width(90),
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus()
+  .onCellValueChanged((event) => {
+    if (event.colDef.field !== 'done' || !event.data) return;
+    lastChange.value = { task: event.data.task, value: event.newValue };
+  });
+</script>
+```
+
+```ts
+CoarGridBuilder.create<Task>().columns([
+  (col) => col.checkbox('done').editable(row => !row.locked),
+  (col) => col.field('task').flex(1),
+  (col) => col.checkbox('locked'),                              // read-only indicator
+])
+.stopEditingWhenCellsLoseFocus()
+.onCellValueChanged((event) => {
+  if (event.colDef.field === 'done') save(event.data);
+});
+```
+
+## States — read-only, editable, indeterminate
+
+Three independent states, all using the same `col.checkbox()` shortcut:
+
+- **Read-only:** omit `.editable()` — checkbox is rendered, edit-mode never opens.
+- **Editable:** add `.editable(true)` or `.editable(row => …)`.
+- **Indeterminate (tri-state):** pass `c.indeterminate(row => …)` in the configurator. Useful for "partial" or "in-progress" states where the row's value isn't a clean true/false. The indeterminate state is shown in both renderer and editor.
+
+**Demo — `data-grid/demos/GridCheckboxStates.vue`**
+
+```vue
+<template>
+  <div style="height: 320px;">
+    <CoarDataGrid :builder="builder" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarDataGrid, CoarGridBuilder } from '@cocoar/vue-data-grid';
+
+interface Feature {
+  id: number;
+  name: string;
+  enabled: boolean;
+  rolloutComplete: boolean;
+  partial: boolean;
+}
+
+const data = ref<Feature[]>([
+  { id: 1, name: 'Dark mode',       enabled: true,  rolloutComplete: true,  partial: false },
+  { id: 2, name: 'Calendar view',   enabled: true,  rolloutComplete: false, partial: true  },
+  { id: 3, name: 'Bulk export',     enabled: false, rolloutComplete: false, partial: false },
+  { id: 4, name: 'Beta dashboard',  enabled: true,  rolloutComplete: false, partial: true  },
+]);
+
+const builder = CoarGridBuilder.create<Feature>()
+  .columns([
+    (col) => col.field('name').header('Feature').flex(1),
+    // editable, no label
+    (col) =>
+      col
+        .checkbox('enabled')
+        .header('Enabled')
+        .width(110)
+        .editable(true),
+    // editable + tri-state indeterminate when partial rollout
+    (col) =>
+      col
+        .checkbox('rolloutComplete', (c) => c.indeterminate((row) => row.partial && !row.rolloutComplete))
+        .header('Rollout')
+        .width(110)
+        .editable(true),
+    // read-only indicator (no .editable())
+    (col) =>
+      col
+        .checkbox('partial')
+        .header('Partial')
+        .width(110),
+  ])
+  .rowDataRef(data)
+  .stopEditingWhenCellsLoseFocus();
+</script>
+```
+
+```ts
+col.checkbox('rolloutComplete', c => c
+  .indeterminate(row => row.partial && !row.rolloutComplete)
+).editable(true)
+```
+
+## Layered overrides
+
+The shortcut bundles renderer + editor with the configurator's options. Subsequent calls on the chain override (last-write-wins):
+
+```ts
+// Replace the renderer entirely (drops the configurator)
+col.checkbox('done').cellRenderer(MyOwnCheckbox)
+
+// Replace just the editor (e.g. a select-style "yes/no/maybe" widget)
+col.checkbox('done').editable(true).cellEditorConfig(MyTriStateEditor, { ... })
+
+// Keep the bundled renderer + editor, override editable
+col.checkbox('done').editable(false)
+```
+
+## API
+
+### `col.checkbox(field, configurator?)`
+
+| Configurator method | Type | Description |
+|--------|------|-------------|
+| `.label(value)` | `string \| (row) => string` | Optional label rendered next to the checkbox (in both renderer and editor) |
+| `.indeterminate(predicate)` | `(row) => boolean` | Tri-state indicator per row |
+| `.size(value)` | `'xs' \| 's' \| 'm' \| 'l'` | Checkbox size (default: `'s'`) |
+
+The configurator config is passed identically to both `CoarCheckboxCellRenderer` and `CoarCheckboxCellEditor`, so display and edit look the same — only behavior changes.
+
+Interactive state comes from the outer chain:
+
+| Outer chain | Result |
+|-------------|--------|
+| no `.editable()` | Read-only — edit-mode never opens |
+| `.editable(true)` | Edit-mode opens on double-click / Enter / F2 |
+| `.editable(false)` | Read-only |
+| `.editable(row => …)` | Per-row predicate — edit-mode opens only when `true` |
+
+Commit behavior: the editor exposes `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 the editor also commits.