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

package/skills/cocoar-vue-ui/references/components/switch.md

@@ -0,0 +1,195 @@
+<!-- Generated from apps/docs/components/switch.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Switch
+
+A toggle for boolean settings that take effect immediately -- think "Enable notifications" or "Dark mode". Unlike a [Checkbox](./checkbox.md), a switch signals instant action rather than a deferred choice that requires a submit button.
+
+```ts
+import { CoarSwitch } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Bind a boolean with `v-model` and provide a `label`. The switch flips on click or keyboard activation.
+
+**Demo — `switch/demos/BasicSwitch.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarSwitch v-model="darkMode" label="Dark mode" />
+    <span style="font-size: 13px; color: #64748b;">Value: {{ darkMode }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarSwitch } from '@cocoar/vue-ui';
+
+const darkMode = ref(false);
+</script>
+```
+
+## With Hint Text
+
+Wrap in `CoarFormField` with a `hint` prop to add a brief explanation, helping users understand the consequence of toggling.
+
+**Demo — `switch/demos/SwitchHint.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <CoarFormField hint="Receive notifications about account activity.">
+      <CoarSwitch v-model="notifications" label="Push notifications" />
+    </CoarFormField>
+    <CoarFormField hint="Automatically save changes every 5 minutes.">
+      <CoarSwitch v-model="autoSave" label="Auto-save" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarSwitch, CoarFormField } from '@cocoar/vue-ui';
+
+const notifications = ref(true);
+const autoSave = ref(false);
+</script>
+```
+
+## States
+
+Supports `disabled` (both on and off), `required`, and `error` states for complete form validation coverage.
+
+**Demo — `switch/demos/SwitchStates.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarSwitch :model-value="true" label="Disabled (on)" :disabled="true" />
+    <CoarSwitch :model-value="false" label="Disabled (off)" :disabled="true" />
+    <CoarSwitch :model-value="false" label="Required switch" :required="true" />
+    <CoarFormField error="This setting must be enabled">
+      <CoarSwitch :model-value="false" label="With error" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarSwitch, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Four sizes so the switch fits naturally alongside other controls at any density.
+
+**Demo — `switch/demos/SwitchSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <CoarSwitch :model-value="true" size="xs" label="Extra-small switch" />
+    <CoarSwitch :model-value="true" size="s" label="Small switch" />
+    <CoarSwitch :model-value="true" size="m" label="Medium switch (default)" />
+    <CoarSwitch :model-value="true" size="l" label="Large switch" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarSwitch } from '@cocoar/vue-ui';
+</script>
+```
+
+## Label Position
+
+Place the label before or after the switch with the `labelPosition` prop. Defaults to `'after'`.
+
+**Demo — `switch/demos/SwitchLabelPosition.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <CoarSwitch v-model="a" label="Label after (default)" label-position="after" />
+    <CoarSwitch v-model="b" label="Label before" label-position="before" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarSwitch } from '@cocoar/vue-ui';
+
+const a = ref(true);
+const b = ref(true);
+</script>
+```
+
+## Settings Panel Example
+
+Switches shine in settings panels where each row controls an independent feature. Here is a typical layout pattern.
+
+**Demo — `switch/demos/SwitchSettingsPanel.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; max-width: 360px;">
+    <div v-for="(item, i) in settings" :key="item.label" :style="{
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      padding: '10px 0',
+      borderBottom: i < settings.length - 1 ? '1px solid var(--coar-border-neutral-secondary)' : 'none'
+    }">
+      <div style="display: flex; flex-direction: column; gap: 2px;">
+        <span style="font-size: 14px; font-weight: 600;">{{ item.label }}</span>
+        <span style="font-size: 13px; color: #64748b;">{{ item.description }}</span>
+      </div>
+      <CoarSwitch :model-value="item.enabled" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarSwitch } from '@cocoar/vue-ui';
+
+const settings = [
+  { label: 'Email notifications', description: 'Get emails about activity', enabled: true },
+  { label: 'Marketing emails', description: 'Promotions and updates', enabled: false },
+  { label: 'Two-factor auth', description: 'Enhanced security', enabled: true },
+];
+</script>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move focus to switch |
+| `Space` | Toggle on/off state |
+| `Enter` | Toggle on/off state |
+
+> **Info**
+>
+> Switches use `role="switch"` with `aria-checked` to properly communicate state to screen readers.
+
+### Screen Reader Support
+
+- Label text announces on focus
+- On/off state properly communicated via `aria-checked`
+- Hint text accessible via `aria-describedby`
+- Error messages announced when present
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `boolean` | `false` | Switch on/off state |
+| `label` | `string` | `''` | Label text |
+| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Switch size |
+| `disabled` | `boolean` | `false` | Disable the switch |
+| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position relative to the switch |

package/skills/cocoar-vue-ui/references/components/table.md

@@ -0,0 +1,170 @@
+<!-- Generated from apps/docs/components/table.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Table
+
+A lightweight table wrapper that provides consistent styling, alternating row colors, and proper alignment out of the box. Use it whenever you need to present structured data -- user lists, order histories, configuration settings, or comparison grids.
+
+```ts
+import { CoarTable } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Wrap standard `thead`, `tbody`, `tr`, `th`, and `td` elements. Alternating row colors are applied automatically to improve readability in longer datasets.
+
+**Demo — `table/demos/TableBasic.vue`**
+
+```vue
+<template>
+  <CoarTable>
+    <thead>
+      <tr>
+        <th>ID</th>
+        <th>Name</th>
+        <th>Email</th>
+        <th>Role</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.id">
+        <td>{{ user.id }}</td>
+        <td>{{ user.name }}</td>
+        <td>{{ user.email }}</td>
+        <td>{{ user.role }}</td>
+        <td>
+          <CoarTag :variant="statusVariant[user.status]" size="s">{{ user.status }}</CoarTag>
+        </td>
+      </tr>
+    </tbody>
+  </CoarTable>
+</template>
+
+<script setup lang="ts">
+import { CoarTable, CoarTag } from '@cocoar/vue-ui';
+
+const users = [
+  { id: 1, name: 'Alice Johnson', role: 'Admin', status: 'active', email: 'alice@example.com' },
+  { id: 2, name: 'Bob Smith', role: 'Editor', status: 'active', email: 'bob@example.com' },
+  { id: 3, name: 'Carol White', role: 'Viewer', status: 'pending', email: 'carol@example.com' },
+  { id: 4, name: 'David Brown', role: 'Editor', status: 'inactive', email: 'david@example.com' },
+  { id: 5, name: 'Eva Martinez', role: 'Admin', status: 'active', email: 'eva@example.com' },
+];
+
+const statusVariant: Record<string, 'success' | 'warning' | 'neutral'> = {
+  active: 'success',
+  pending: 'warning',
+  inactive: 'neutral',
+};
+</script>
+```
+
+## Rich Cells
+
+Table cells aren't limited to plain text. Embed avatars, tags, badges, and other components directly in cells to create information-dense but scannable rows.
+
+**Demo — `table/demos/TableRichCells.vue`**
+
+```vue
+<template>
+  <CoarTable>
+    <thead>
+      <tr>
+        <th>User</th>
+        <th>Role</th>
+        <th>Status</th>
+        <th>Notifications</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.id">
+        <td>
+          <div style="display: flex; align-items: center; gap: 8px;">
+            <CoarAvatar :name="user.name" size="s" />
+            <div>
+              <div style="font-size: 14px; font-weight: 600;">{{ user.name }}</div>
+              <div style="font-size: 14px; color: #64748b;">{{ user.email }}</div>
+            </div>
+          </div>
+        </td>
+        <td>{{ user.role }}</td>
+        <td><CoarTag :variant="statusVariant[user.status]" size="s">{{ user.status }}</CoarTag></td>
+        <td><CoarBadge v-if="user.status === 'active'" variant="error" size="s" :content="user.notifs" /></td>
+      </tr>
+    </tbody>
+  </CoarTable>
+</template>
+
+<script setup lang="ts">
+import { CoarTable, CoarTag, CoarAvatar, CoarBadge } from '@cocoar/vue-ui';
+
+const users = [
+  { id: 1, name: 'Alice Johnson', role: 'Admin', status: 'active', email: 'alice@example.com', notifs: 3 },
+  { id: 2, name: 'Bob Smith', role: 'Editor', status: 'active', email: 'bob@example.com', notifs: 7 },
+  { id: 3, name: 'Carol White', role: 'Viewer', status: 'pending', email: 'carol@example.com', notifs: 0 },
+  { id: 4, name: 'David Brown', role: 'Editor', status: 'inactive', email: 'david@example.com', notifs: 0 },
+  { id: 5, name: 'Eva Martinez', role: 'Admin', status: 'active', email: 'eva@example.com', notifs: 2 },
+];
+
+const statusVariant: Record<string, 'success' | 'warning' | 'neutral'> = {
+  active: 'success',
+  pending: 'warning',
+  inactive: 'neutral',
+};
+</script>
+```
+
+## Variants
+
+The default striped style works well for most tables. Switch to `plain` for a minimal look, or `bordered` when you need explicit cell boundaries -- useful for dense data or comparison tables.
+
+**Demo — `table/demos/TableVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <div>
+      <p style="margin: 0 0 4px; font-size: 13px; color: #64748b;">Default (striped)</p>
+      <CoarTable>
+        <thead><tr><th>Name</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td>Alpha</td><td>1</td></tr>
+          <tr><td>Beta</td><td>2</td></tr>
+          <tr><td>Gamma</td><td>3</td></tr>
+        </tbody>
+      </CoarTable>
+    </div>
+    <div>
+      <p style="margin: 0 0 4px; font-size: 13px; color: #64748b;">Bordered</p>
+      <CoarTable variant="bordered">
+        <thead><tr><th>Name</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td>Alpha</td><td>1</td></tr>
+          <tr><td>Beta</td><td>2</td></tr>
+          <tr><td>Gamma</td><td>3</td></tr>
+        </tbody>
+      </CoarTable>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarTable } from '@cocoar/vue-ui';
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'default' \| 'plain' \| 'bordered'` | `'default'` | Table style variant |
+| `compact` | `boolean` | `false` | Use compact cell padding |
+| `hover` | `boolean` | `true` | Highlight rows on hover |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Native thead/tbody/tr/th/td elements |