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

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

@@ -0,0 +1,256 @@
+<!-- Generated from apps/docs/components/text-input.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Text Input
+
+The go-to component for collecting short text from users -- names, emails, search queries, and more. It handles labels, validation, prefix/suffix decorations, and can even stretch into a textarea when you need longer content.
+
+```ts
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+```
+
+## Basic Usage
+
+Wire up a text input with `v-model` and wrap it in a `CoarFormField` to add a label, placeholder, and optional hint to guide the user.
+
+**Demo — `text-input/demos/BasicTextInput.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Username" hint="Choose a unique username">
+      <CoarTextInput
+        v-model="value"
+        placeholder="Enter your username"
+      />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">Value: {{ value || 'empty' }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+
+const value = ref('');
+</script>
+```
+
+## Validation States
+
+Add `required` to both `CoarFormField` (for the asterisk) and the input (for the HTML attribute). Pass an `error` string to `CoarFormField` to surface validation feedback beneath the input.
+
+**Demo — `text-input/demos/TextInputValidation.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Email" hint="Required field" required>
+      <CoarTextInput
+        v-model="email"
+        placeholder="your@email.com"
+        :required="true"
+      />
+    </CoarFormField>
+    <CoarFormField label="Email" error="Please enter a valid email address">
+      <CoarTextInput
+        value="invalid-email"
+      />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+
+const email = ref('');
+</script>
+```
+
+## Disabled & Readonly
+
+Use `disabled` when the field should be completely non-interactive, and `readonly` when users should be able to see and copy the value but not change it.
+
+**Demo — `text-input/demos/TextInputDisabledReadonly.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Disabled">
+      <CoarTextInput value="Cannot edit" :disabled="true" />
+    </CoarFormField>
+    <CoarFormField label="Readonly">
+      <CoarTextInput value="View only" :readonly="true" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Prefix & Suffix
+
+Prefix and suffix slots help users understand the expected format -- think currency symbols, units, or domain names.
+
+**Demo — `text-input/demos/TextInputPrefixSuffix.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Website">
+      <CoarTextInput v-model="website" placeholder="example.com" prefix="https://" />
+    </CoarFormField>
+    <CoarFormField label="Price">
+      <CoarTextInput v-model="price" placeholder="0.00" suffix="EUR" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+
+const website = ref('');
+const price = ref('');
+</script>
+```
+
+## Clear Button
+
+When `clearable` is enabled, a small X button appears on hover or focus so users can quickly reset the field. It's **off by default** — set `clearable` to opt in.
+
+**Demo — `text-input/demos/TextInputClearable.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 320px;">
+    <CoarFormField label="Search">
+      <CoarTextInput
+        v-model="search"
+        placeholder="Type to search..."
+        :clearable="true"
+      />
+    </CoarFormField>
+    <span style="font-size: 13px; color: #64748b;">Value: {{ search || 'empty' }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+
+const search = ref('');
+</script>
+```
+
+## Sizes
+
+Four sizes let you match the input to its surroundings -- compact toolbars, standard forms, or spacious layouts.
+
+**Demo — `text-input/demos/TextInputSizes.vue`**
+
+```vue
+<template>
+  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px;">
+    <CoarFormField label="Extra Small">
+      <CoarTextInput size="xs" placeholder="27px" />
+    </CoarFormField>
+    <CoarFormField label="Small">
+      <CoarTextInput size="s" placeholder="32px" />
+    </CoarFormField>
+    <CoarFormField label="Medium">
+      <CoarTextInput size="m" placeholder="40px" />
+    </CoarFormField>
+    <CoarFormField label="Large">
+      <CoarTextInput size="l" placeholder="48px" />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+</script>
+```
+
+## Multiline (Textarea)
+
+Set `rows` to 2 or more and the input switches to a textarea, perfect for descriptions, notes, or any free-form content.
+
+**Demo — `text-input/demos/TextInputMultiline.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px; max-width: 400px;">
+    <CoarFormField label="Bio" hint="Max 500 characters">
+      <CoarTextInput
+        v-model="bio"
+        placeholder="Tell us about yourself..."
+        :rows="4"
+      />
+    </CoarFormField>
+    <CoarFormField label="6 Rows">
+      <CoarTextInput :rows="6" placeholder="Taller textarea..." />
+    </CoarFormField>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarTextInput, CoarFormField } from '@cocoar/vue-ui';
+
+const bio = ref('');
+</script>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Move focus to input |
+| `Shift + Tab` | Move focus backward |
+| `Escape` | Clear input (when clearable) |
+
+> **Info**
+>
+> Labels are automatically associated with their inputs. The required asterisk is announced by screen readers.
+
+### Screen Reader Support
+
+- Label text announces on focus
+- Required state properly communicated
+- Error messages are linked via `aria-describedby`
+- Hint text is accessible to assistive technology
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `v-model` | `string` | `''` | Current input value (two-way binding) |
+| `placeholder` | `string` | `''` | Placeholder text when empty |
+| `prefix` | `string` | `''` | Prefix text before the input |
+| `suffix` | `string` | `''` | Suffix text after the input |
+| `size` | `'xs' \| 's' \| 'm' \| 'l'` | `'m'` | Input size |
+| `rows` | `number` | `1` | Rows >= 2 enables textarea mode |
+| `clearable` | `boolean` | `false` | Show clear button when input has value |
+| `error` | `boolean` | `false` | Error state (auto-injected from `CoarFormField`) |
+| `disabled` | `boolean` | `false` | Disable the input |
+| `readonly` | `boolean` | `false` | Make read-only |
+| `required` | `boolean` | `false` | HTML required attribute |
+
+> **Tip**
+>
+> Label, hint, and error are provided by [`CoarFormField`](./form-field.md). Wrap inputs in a `CoarFormField` to add these features.
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.textInput.clear` | `'Clear'` | Clear button `aria-label` |

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

@@ -0,0 +1,160 @@
+<!-- Generated from apps/docs/components/toast.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Toast
+
+Non-blocking notification messages that slide in, deliver a brief update, and dismiss themselves. Toasts are perfect for confirming background actions -- a file uploaded, a record saved, or a network error encountered -- without interrupting the user's current workflow.
+
+```ts
+import { useToast } from '@cocoar/vue-ui';
+```
+
+## Variants
+
+Four semantic variants communicate the nature of the notification at a glance. Click each button below to see the corresponding toast.
+
+**Demo — `toast/demos/ToastVariants.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarButton variant="primary" @click="showSuccess">Success</CoarButton>
+    <CoarButton variant="danger" @click="showError">Error</CoarButton>
+    <CoarButton variant="secondary" @click="showWarning">Warning</CoarButton>
+    <CoarButton variant="ghost" @click="showInfo">Info</CoarButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, useToast } from '@cocoar/vue-ui';
+
+const toast = useToast();
+
+function showSuccess() {
+  toast.success('Changes saved successfully!', { title: 'Saved' });
+}
+function showError() {
+  toast.error('Something went wrong. Please try again.', { title: 'Error' });
+}
+function showWarning() {
+  toast.warning('Your session will expire in 5 minutes.', { title: 'Warning' });
+}
+function showInfo() {
+  toast.info('A new version is available. Refresh to update.', { title: 'Update Available' });
+}
+</script>
+```
+
+## Without Title
+
+For straightforward messages, skip the title entirely. A single-line toast keeps the notification compact and fast to read.
+
+**Demo — `toast/demos/ToastNoTitle.vue`**
+
+```vue
+<template>
+  <CoarButton @click="showNoTitle">Simple message</CoarButton>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, useToast } from '@cocoar/vue-ui';
+
+const toast = useToast();
+
+function showNoTitle() {
+  toast.success('File uploaded successfully.');
+}
+</script>
+```
+
+## Duration Control
+
+By default, toasts dismiss after 5 seconds (error toasts stay until dismissed). Pass a custom `duration` in milliseconds for longer messages, or set `duration: 0` to create a persistent toast that stays visible until the user explicitly dismisses it.
+
+**Demo — `toast/demos/ToastDuration.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarButton variant="secondary" @click="showLong">Long duration (6s)</CoarButton>
+    <CoarButton variant="secondary" @click="showPersistent">Persistent (no auto-dismiss)</CoarButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, useToast } from '@cocoar/vue-ui';
+
+const toast = useToast();
+
+function showLong() {
+  toast.info('This is a longer notification message that contains more detailed information about what just happened in the application.', {
+    title: 'Detailed Message',
+    duration: 6000,
+  });
+}
+
+function showPersistent() {
+  toast.warning('This notification stays until dismissed.', {
+    title: 'Persistent',
+    duration: 0,
+  });
+}
+</script>
+```
+
+## Setup
+
+Register the overlay plugin once in your app entry point:
+
+```ts
+// main.ts
+import { CoarOverlayPlugin } from '@cocoar/vue-ui';
+
+createApp(App)
+  .use(CoarOverlayPlugin)
+  .mount('#app');
+```
+
+Then add the toast container to your `App.vue`:
+
+```vue
+<template>
+  <RouterView />
+  <CoarToastContainer />
+</template>
+```
+
+`<CoarToastContainer />` needs no props — its `service` defaults to the `getToastService()` singleton that `CoarOverlayPlugin` registers (the same one `useToast()` wraps). Pass an explicit `:service` only for a non-singleton instance (e.g. an isolated test harness). If the plugin isn't installed it throws a clear "install `CoarOverlayPlugin`" error rather than rendering nothing.
+
+## API
+
+### `useToast()` Methods
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `toast.show(config)` | `ToastConfig` | Show a fully custom toast |
+| `toast.success(message, config?)` | `string, Partial<ToastConfig>?` | Show success toast |
+| `toast.error(message, config?)` | `string, Partial<ToastConfig>?` | Show error toast (persistent by default) |
+| `toast.warning(message, config?)` | `string, Partial<ToastConfig>?` | Show warning toast |
+| `toast.info(message, config?)` | `string, Partial<ToastConfig>?` | Show info toast |
+| `toast.dismissAll()` | — | Dismiss all visible toasts |
+
+### `ToastConfig`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `string` | — | Toast message (required for `show()`) |
+| `title` | `string` | `undefined` | Optional toast title |
+| `duration` | `number` | `5000` (errors: `0`) | Duration in ms (0 = persistent) |
+| `position` | `'top-right' \| 'top-left' \| 'top-center' \| 'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'top-right'` | Screen position |
+| `dismissible` | `boolean` | `true` | Show close button |
+| `showProgress` | `boolean` | `true` | Show progress bar |
+| `action` | `{ label: string; callback: () => void }` | `undefined` | Optional action button |
+
+## i18n Keys
+
+These keys can be translated via [`@cocoar/vue-localization`](../foundations/localization/translations.md).
+
+| Key | Default (English) | Used as |
+|-----|-------------------|---------|
+| `coar.ui.toast.dismiss` | `'Dismiss notification'` | Dismiss button `aria-label` |
+| `coar.ui.toast.notifications` | `'Notifications'` | Toast container region `aria-label` |

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

@@ -0,0 +1,121 @@
+<!-- Generated from apps/docs/components/tooltip.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Tooltip
+
+Tooltips are small, text-only hints that appear on hover or focus. They are the simplest way to add contextual labels to icon buttons, truncated text, or any element that benefits from a brief explanation. Use the `v-tooltip` directive on any element -- no wrapper component needed.
+
+```ts
+import { vTooltip } from '@cocoar/vue-ui';
+```
+
+## Basic Tooltip
+
+Pass a string directly to `v-tooltip` for the quickest setup. Hover over any button below to see its tooltip.
+
+**Demo — `tooltip/demos/TooltipBasic.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarButton v-tooltip="'Save your changes'">Save</CoarButton>
+    <CoarButton variant="danger" v-tooltip="'This action cannot be undone'">Delete</CoarButton>
+    <CoarButton variant="ghost" v-tooltip="'Cancel and go back'">Cancel</CoarButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, vTooltip } from '@cocoar/vue-ui';
+</script>
+```
+
+## Placements
+
+By default, tooltips appear above the trigger. Use the options object form to position them on any side. Pick the placement that avoids clipping in your layout.
+
+**Demo — `tooltip/demos/TooltipPlacements.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 16px 0;">
+    <CoarButton v-tooltip="{ text: 'Top tooltip', placement: 'top' }">Top</CoarButton>
+    <CoarButton v-tooltip="{ text: 'Bottom tooltip', placement: 'bottom' }">Bottom</CoarButton>
+    <CoarButton v-tooltip="{ text: 'Left tooltip', placement: 'left' }">Left</CoarButton>
+    <CoarButton v-tooltip="{ text: 'Right tooltip', placement: 'right' }">Right</CoarButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, vTooltip } from '@cocoar/vue-ui';
+</script>
+```
+
+## On Icon Buttons
+
+Icon-only buttons look clean, but their meaning can be ambiguous. Adding a tooltip provides both a visual hint for sighted users and an accessible label for screen readers -- making tooltips essential for any icon-only control.
+
+**Demo — `tooltip/demos/TooltipIcons.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <CoarButton variant="ghost" icon-start="plus" v-tooltip="'Add new item'" aria-label="Add new item" />
+    <CoarButton variant="ghost" icon-start="copy" v-tooltip="'Copy to clipboard'" aria-label="Copy" />
+    <CoarButton variant="ghost" icon-start="trash-2" v-tooltip="'Delete selected'" aria-label="Delete" />
+    <CoarButton variant="ghost" icon-start="settings" v-tooltip="'Open settings'" aria-label="Settings" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarButton, vTooltip } from '@cocoar/vue-ui';
+</script>
+```
+
+## On Any Element
+
+`v-tooltip` is a directive, so it works on any HTML element -- spans, icons, code snippets, or custom components. No special wrapper needed.
+
+**Demo — `tooltip/demos/TooltipElements.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
+    <span
+      v-tooltip="'This is a span'"
+      style="padding: 4px 8px; border: 1px solid var(--coar-border-neutral-secondary); border-radius: 4px; font-size: 13px; cursor: default;"
+    >Hover me (span)</span>
+    <CoarIcon name="circle-help" size="l" v-tooltip="'Help: Click for more info'" style="cursor: help" />
+    <code
+      v-tooltip="'CSS custom property'"
+      style="cursor: default; background: var(--coar-background-neutral-tertiary); padding: 2px 6px; border-radius: 3px; font-size: 13px;"
+    >--coar-spacing-m</code>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarIcon, vTooltip } from '@cocoar/vue-ui';
+</script>
+```
+
+> **Tip: Tooltip vs Popover**
+>
+> Use **Tooltip** for short, non-interactive text hints on hover or focus. Use **Popover** for rich interactive content that opens on click. Tooltips are text-only and disappear when the pointer leaves; popovers can hold buttons, forms, and full HTML.
+
+## API
+
+### `v-tooltip` Options
+
+The directive accepts either a plain string or an options object:
+
+```vue
+<!-- String shorthand -->
+<CoarButton v-tooltip="'Save changes'">Save</CoarButton>
+
+<!-- Options object -->
+<CoarButton v-tooltip="{ text: 'Delete item', placement: 'top' }">Delete</CoarButton>
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `text` | `string` | -- | Tooltip text (or pass string directly to the directive) |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred tooltip placement |
+| `disabled` | `boolean` | `false` | Disable the tooltip |