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

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

@@ -0,0 +1,186 @@
+<!-- Generated from apps/docs/components/popconfirm.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Popconfirm
+
+A lightweight confirmation bubble that appears right next to the trigger element. Use it for quick "are you sure?" moments -- deleting a row, removing a team member, or publishing a change -- without pulling the user out of context with a full-screen modal dialog.
+
+```ts
+import { CoarPopconfirm } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Wrap any button (or other trigger) in `CoarPopconfirm`. When the trigger is clicked, a small confirmation panel appears nearby with confirm and cancel actions.
+
+**Demo — `popconfirm/demos/PopconfirmBasic.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopconfirm
+      title="Delete item?"
+      message="This action cannot be undone."
+      @confirmed="lastAction = 'deleted'"
+      @cancelled="lastAction = 'cancelled'"
+    >
+      <CoarButton variant="danger" icon-start="trash-2">Delete</CoarButton>
+    </CoarPopconfirm>
+  </div>
+  <p style="margin-top: 8px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+    Last action: {{ lastAction || 'none' }}
+  </p>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarButton, CoarPopconfirm } from '@cocoar/vue-ui';
+
+const lastAction = ref('');
+</script>
+```
+
+## Variants
+
+Use `confirmVariant="danger"` for destructive operations to make the risk visually clear. The `"primary"` variant (default) suits non-destructive confirmations like publishing or saving.
+
+**Demo — `popconfirm/demos/PopconfirmVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopconfirm
+      title="Are you sure?"
+      message="This is a destructive action."
+      confirmVariant="danger"
+      @confirmed="lastAction = 'danger-confirmed'"
+    >
+      <CoarButton variant="danger">Danger</CoarButton>
+    </CoarPopconfirm>
+
+    <CoarPopconfirm
+      title="Confirm action"
+      message="This will apply the changes."
+      confirmVariant="primary"
+      @confirmed="lastAction = 'primary-confirmed'"
+    >
+      <CoarButton variant="primary">Primary</CoarButton>
+    </CoarPopconfirm>
+  </div>
+  <p style="margin-top: 8px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+    Last action: {{ lastAction || 'none' }}
+  </p>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarButton, CoarPopconfirm } from '@cocoar/vue-ui';
+
+const lastAction = ref('');
+</script>
+```
+
+## Custom Labels
+
+Replace the default "OK" / "Cancel" labels with language that describes the actual action. Specific labels like "Yes, remove" and "Keep member" help users make confident decisions.
+
+**Demo — `popconfirm/demos/PopconfirmLabels.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopconfirm
+      title="Remove from team?"
+      message="The user will lose access immediately."
+      confirmText="Yes, remove"
+      cancelText="Keep member"
+      confirmVariant="danger"
+      @confirmed="lastAction = 'removed'"
+    >
+      <CoarButton variant="danger">Remove Member</CoarButton>
+    </CoarPopconfirm>
+
+    <CoarPopconfirm
+      title="Publish changes?"
+      message="This will be visible to all users."
+      confirmText="Publish now"
+      cancelText="Not yet"
+      @confirmed="lastAction = 'published'"
+    >
+      <CoarButton variant="primary">Publish</CoarButton>
+    </CoarPopconfirm>
+  </div>
+  <p style="margin-top: 8px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+    Last action: {{ lastAction || 'none' }}
+  </p>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarButton, CoarPopconfirm } from '@cocoar/vue-ui';
+
+const lastAction = ref('');
+</script>
+```
+
+## Placement
+
+Control which side of the trigger the confirmation panel appears on. Pick the placement that best avoids clipping against viewport edges in your layout.
+
+**Demo — `popconfirm/demos/PopconfirmPlacement.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopconfirm title="Top placement" message="Appears above the trigger." placement="top" @confirmed="lastAction = 'top'">
+      <CoarButton variant="secondary">Top</CoarButton>
+    </CoarPopconfirm>
+    <CoarPopconfirm title="Bottom placement" message="Appears below the trigger." placement="bottom" @confirmed="lastAction = 'bottom'">
+      <CoarButton variant="secondary">Bottom</CoarButton>
+    </CoarPopconfirm>
+    <CoarPopconfirm title="Right placement" message="Appears to the right." placement="right" @confirmed="lastAction = 'right'">
+      <CoarButton variant="secondary">Right</CoarButton>
+    </CoarPopconfirm>
+  </div>
+  <p style="margin-top: 8px; font-size: 13px; color: var(--coar-text-neutral-secondary);">
+    Last action: {{ lastAction || 'none' }}
+  </p>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarButton, CoarPopconfirm } from '@cocoar/vue-ui';
+
+const lastAction = ref('');
+</script>
+```
+
+> **Info: Popconfirm vs Dialog**
+>
+> Use **Popconfirm** for quick inline confirmations that keep the user in context. Use **Dialog** when the confirmation needs a longer explanation, additional form fields, or when the action affects multiple items.
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `string` | required | Confirmation message body |
+| `title` | `string` | `''` | Optional title above the message |
+| `confirmText` | `string` | `'OK'` | Confirm button label |
+| `cancelText` | `string` | `'Cancel'` | Cancel button label |
+| `confirmVariant` | `'primary' \| 'danger'` | `'primary'` | Confirm button color variant |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred placement |
+| `disabled` | `boolean` | `false` | Disable the popconfirm trigger |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `confirmed` | Emitted when the confirm button is clicked |
+| `cancelled` | Emitted when the cancel button is clicked or overlay is dismissed |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The trigger element that opens the popconfirm |

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

@@ -0,0 +1,173 @@
+<!-- Generated from apps/docs/components/popover.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Popover
+
+Popovers display rich, interactive content anchored to a trigger element. Unlike tooltips (which are text-only and non-interactive), popovers can hold forms, menus, formatted text, and action buttons. They stay open until the user clicks away or presses Escape, giving people time to interact with the content inside.
+
+```ts
+import { CoarPopover } from '@cocoar/vue-ui';
+```
+
+## Basic Popover (Click)
+
+Set `mode="click"` to open the popover on click. This is the best mode for action menus and content that users need to interact with. Click outside the popover or press Escape to dismiss it.
+
+**Demo — `popover/demos/PopoverBasic.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopover mode="click">
+      <CoarButton>Open Popover</CoarButton>
+      <template #content>
+        <div style="padding: 16px; max-width: 240px;">
+          <h4 style="margin: 0 0 4px;">Popover Title</h4>
+          <p style="margin: 0; font-size: 13px;">This is rich content inside a popover. It can contain forms, lists, and other interactive components.</p>
+          <CoarButton variant="primary" size="s" style="margin-top: 8px;">Action</CoarButton>
+        </div>
+      </template>
+    </CoarPopover>
+
+    <CoarPopover mode="click">
+      <CoarButton variant="secondary">More options</CoarButton>
+      <template #content>
+        <div style="display: flex; flex-direction: column; padding: 4px; gap: 2px; min-width: 140px;">
+          <CoarButton variant="ghost" size="s">Edit</CoarButton>
+          <CoarButton variant="ghost" size="s">Duplicate</CoarButton>
+          <CoarButton variant="ghost" size="s">Archive</CoarButton>
+          <CoarButton variant="danger" size="s">Delete</CoarButton>
+        </div>
+      </template>
+    </CoarPopover>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, CoarPopover } from '@cocoar/vue-ui';
+</script>
+```
+
+## Hover Mode
+
+The default `mode="hover"` opens the popover when the pointer enters the trigger. Use `mode="both"` to support both hover preview and click-to-pin behavior -- the popover opens on hover and stays pinned after a click.
+
+**Demo — `popover/demos/PopoverHover.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopover mode="hover">
+      <CoarButton variant="ghost">Hover me</CoarButton>
+      <template #content>
+        <div style="padding: 16px; max-width: 240px;">
+          <p style="margin: 0; font-size: 13px;">This popover opens on hover. Great for supplementary information.</p>
+        </div>
+      </template>
+    </CoarPopover>
+
+    <CoarPopover mode="both">
+      <CoarButton variant="secondary">Hover or click</CoarButton>
+      <template #content>
+        <div style="padding: 16px; max-width: 240px;">
+          <p style="margin: 0; font-size: 13px;">Opens on hover. Click to pin it open — then click again to close.</p>
+        </div>
+      </template>
+    </CoarPopover>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, CoarPopover } from '@cocoar/vue-ui';
+</script>
+```
+
+## User Menu
+
+A classic application pattern: clicking an avatar reveals a small card with the user's identity and quick actions like profile, settings, and sign-out.
+
+**Demo — `popover/demos/PopoverUserMenu.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopover mode="click">
+      <CoarAvatar name="John Doe" size="s" style="cursor: pointer" />
+      <template #content>
+        <div style="min-width: 180px;">
+          <div style="padding: 8px 16px; border-bottom: 1px solid var(--coar-border-neutral-secondary); margin-bottom: 4px;">
+            <p style="margin: 0; font-weight: 600; font-size: 13px;">John Doe</p>
+            <p style="margin: 0; font-size: 13px; color: var(--coar-text-neutral-secondary);">john@example.com</p>
+          </div>
+          <div style="display: flex; flex-direction: column; padding: 4px; gap: 2px;">
+            <CoarButton variant="ghost" size="s">Profile</CoarButton>
+            <CoarButton variant="ghost" size="s">Settings</CoarButton>
+            <CoarButton variant="danger" size="s">Sign Out</CoarButton>
+          </div>
+        </div>
+      </template>
+    </CoarPopover>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, CoarPopover, CoarAvatar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Info Popover
+
+Attach a hover popover to an icon button to provide contextual help without navigating the user away from their current task. This works well for explaining features, showing rate limits, or surfacing inline guidance.
+
+**Demo — `popover/demos/PopoverInfo.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarPopover mode="hover">
+      <CoarButton variant="ghost" icon-start="circle-help" aria-label="More information" />
+      <template #content>
+        <div style="padding: 16px; max-width: 240px;">
+          <h4 style="margin: 0 0 4px;">How it works</h4>
+          <p style="margin: 0; font-size: 13px;">This feature uses your account's default timezone. You can change this in Settings &rarr; Preferences.</p>
+        </div>
+      </template>
+    </CoarPopover>
+
+    <CoarPopover mode="hover">
+      <CoarButton variant="ghost" icon-start="triangle-alert" aria-label="Warning details" />
+      <template #content>
+        <div style="padding: 16px; max-width: 240px;">
+          <h4 style="margin: 0 0 4px;">Rate limit approaching</h4>
+          <p style="margin: 0; font-size: 13px;">You've used 80% of your monthly API limit. Upgrade to increase your quota.</p>
+        </div>
+      </template>
+    </CoarPopover>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, CoarPopover } from '@cocoar/vue-ui';
+</script>
+```
+
+> **Info: Slot names**
+>
+> Place the trigger in the **default slot** and the content in **`#content`**. The popover auto-positions itself to stay within the viewport -- no placement prop needed.
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `'hover' \| 'click' \| 'both'` | `'hover'` | How the popover is triggered |
+| `disabled` | `boolean` | `false` | Prevent the popover from opening |
+| `interactive` | `boolean` | `true` | Whether the panel receives pointer events |
+| `offset` | `number` | `6` | Gap in px between trigger and panel |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The trigger element that opens the popover |
+| `#content` | The popover panel content |

package/skills/cocoar-vue-ui/references/components/progress-bar.md

@@ -0,0 +1,178 @@
+<!-- Generated from apps/docs/components/progress-bar.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Progress Bar
+
+Progress bars keep users informed about ongoing operations -- file uploads, multi-step workflows, or background tasks. They reduce uncertainty by showing either a concrete completion percentage or an animated indicator when the duration is unknown.
+
+```ts
+import { CoarProgressBar } from '@cocoar/vue-ui';
+```
+
+## Basic Progress
+
+Bind a numeric `value` (0--100) to show determinate progress. Ideal for file uploads, form completion, or any task where you can measure how much work remains.
+
+**Demo — `progress-bar/demos/ProgressBarBasic.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <CoarProgressBar :value="progress" />
+    <div style="display: flex; gap: 8px; align-items: center;">
+      <button class="adj-btn" @click="progress = Math.max(0, progress - 10)">-10</button>
+      <span style="min-width: 40px; text-align: center; font-size: 14px;">{{ progress }}%</span>
+      <button class="adj-btn" @click="progress = Math.min(100, progress + 10)">+10</button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarProgressBar } from '@cocoar/vue-ui';
+
+const progress = ref(65);
+</script>
+
+<style scoped>
+.adj-btn {
+  padding: 4px 12px;
+  border: 1px solid var(--coar-border-neutral-secondary);
+  border-radius: 6px;
+  background: var(--coar-background-neutral-secondary);
+  color: var(--coar-text-neutral-primary);
+  cursor: pointer;
+  font-size: 14px;
+}
+.adj-btn:hover {
+  background: var(--coar-background-neutral-tertiary);
+}
+</style>
+```
+
+## Indeterminate
+
+When you can't predict how long an operation will take -- network requests, server-side processing -- switch to indeterminate mode for a continuous animation that signals "working on it."
+
+**Demo — `progress-bar/demos/ProgressBarIndeterminate.vue`**
+
+```vue
+<template>
+  <CoarProgressBar indeterminate />
+</template>
+
+<script setup lang="ts">
+import { CoarProgressBar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Color Variants
+
+Match the bar color to its context: `accent` (default) for standard progress, `success` for completed uploads, `warning` for approaching limits, `error` for failed operations.
+
+**Demo — `progress-bar/demos/ProgressBarVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Accent (default)</span>
+      <CoarProgressBar :value="75" />
+    </div>
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Success</span>
+      <CoarProgressBar :value="75" variant="success" />
+    </div>
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Warning</span>
+      <CoarProgressBar :value="75" variant="warning" />
+    </div>
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Error</span>
+      <CoarProgressBar :value="75" variant="error" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarProgressBar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Sizes
+
+Three heights give you flexibility. Use `s` inside compact cards or table rows, `m` for standard layouts, and `l` when the progress bar is the focal point.
+
+**Demo — `progress-bar/demos/ProgressBarSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Small</span>
+      <CoarProgressBar :value="60" size="s" />
+    </div>
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Medium (default)</span>
+      <CoarProgressBar :value="60" size="m" />
+    </div>
+    <div>
+      <span style="font-size: 13px; color: #64748b;">Large</span>
+      <CoarProgressBar :value="60" size="l" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarProgressBar } from '@cocoar/vue-ui';
+</script>
+```
+
+## Live Progress
+
+A continuously animating example that shows how the bar transitions smoothly as the value changes.
+
+**Demo — `progress-bar/demos/ProgressBarAnimated.vue`**
+
+```vue
+<template>
+  <div>
+    <div style="display: flex; justify-content: space-between; margin-bottom: 4px;">
+      <span style="font-size: 14px;">Processing...</span>
+      <span style="font-size: 14px;">{{ animatedProgress }}%</span>
+    </div>
+    <CoarProgressBar :value="animatedProgress" variant="info" size="l" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue';
+import { CoarProgressBar } from '@cocoar/vue-ui';
+
+const animatedProgress = ref(0);
+let interval: ReturnType<typeof setInterval> | null = null;
+
+onMounted(() => {
+  interval = setInterval(() => {
+    animatedProgress.value = (animatedProgress.value + 1) % 101;
+  }, 50);
+});
+
+onUnmounted(() => {
+  if (interval) clearInterval(interval);
+});
+</script>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | `0` | Current progress value |
+| `max` | `number` | `100` | Maximum progress value |
+| `indeterminate` | `boolean` | `false` | Show animated indeterminate state |
+| `variant` | `'accent' \| 'success' \| 'warning' \| 'error'` | `'accent'` | Color variant |
+| `size` | `'s' \| 'm' \| 'l'` | `'m'` | Bar height |
+| `label` | `string` | `''` | Accessible label for screen readers |
+| `showValue` | `boolean` | `false` | Display the percentage value next to the bar |