@bridge-ui/vue 0.0.6 → 0.0.8

package/docs/components/Card.md

@@ -0,0 +1,287 @@
+# Card
+
+Surface container with optional title, action, and footer.
+
+## Import
+
+```ts
+import { Card } from "@bridge-ui/vue/Components/Card";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Card title="Card title">
+  Card body content goes here.
+</Card>
+
+<Card variant="outlined" title="Outlined card">
+  Outlined surface with a visible border.
+</Card>
+
+<Card title="Confirm changes">
+  Review your changes before saving.
+
+  <template #footer>
+    <div class="flex justify-end gap-2">
+      <Button size="sm" variant="flat">Cancel</Button>
+
+      <Button size="sm">Save</Button>
+    </div>
+  </template>
+</Card>
+```
+
+### Borderless
+
+```vue
+<div class="grid gap-4 sm:grid-cols-2">
+  <Card title="With dividers (default)">
+    Default card with header and footer dividers.
+
+    <template #footer>
+      <div class="flex justify-end gap-2">
+        <Button size="sm" variant="flat">Cancel</Button>
+
+        <Button size="sm">Save</Button>
+      </div>
+    </template>
+  </Card>
+
+  <Card borderless title="Borderless">
+    Header and footer borders are removed.
+
+    <template #footer>
+      <Button size="sm" variant="flat">Cancel</Button>
+
+        <Button size="sm">Save</Button>
+    </template>
+  </Card>
+</div>
+```
+
+### Title
+
+```vue
+<Card title="Via title prop">
+  Content rendered via the title prop.
+</Card>
+
+<Card>
+  <template #title>
+    <span class="text-primary-600">Custom title slot</span>
+  </template>
+
+  Content with a custom title slot.
+</Card>
+```
+
+### Action slot
+
+```vue
+<Card title="Card with actions">
+  <template #action>
+    <Button
+      size="sm"
+      variant="flat"
+      density="mini"
+      aria-label="More options"
+    >
+      <MoreHorizontal class="size-4" />
+    </Button>
+  </template>
+
+  Use the action slot for header controls.
+</Card>
+```
+
+### Footer slot
+
+```vue
+<Card title="Confirm changes">
+  Are you sure you want to proceed?
+
+  <template #footer>
+    <Button size="sm" variant="flat">Cancel</Button>
+
+      <Button size="sm" color="primary">Confirm</Button>
+  </template>
+</Card>
+```
+
+### Custom header slot
+
+```vue
+<Card>
+  <template #header>
+    <div
+      class="border-secondary-200 bg-primary-50 dark:border-secondary-600 dark:bg-primary-950/30 flex items-center gap-3 border-b px-4 py-3"
+    >
+      <div
+        class="bg-primary-500 flex size-10 items-center justify-center rounded-full text-sm font-semibold text-white"
+      >
+        JD
+      </div>
+      <div>
+        <p class="font-medium">Jane Doe</p>
+        <p class="text-secondary-500 text-sm">Custom header area</p>
+      </div>
+    </div>
+  </template>
+
+  Replaces the default title row entirely.
+</Card>
+```
+
+### Full composition
+
+```vue
+<Card shadow="lg" rounded="2xl" title="Project settings">
+  <template #action>
+    <Button size="sm" variant="outline">Edit</Button>
+  </template>
+
+  Title, action, body, and footer together with elevated styling.
+
+  <template #footer>
+    <Button size="sm" color="error" variant="flat">Delete</Button>
+
+      <Button size="sm" color="primary">Save changes</Button>
+  </template>
+</Card>
+```
+
+### Partial layouts
+
+```vue
+<Card title="Title only (no body children)" />
+
+<Card>Card with body content only.</Card>
+
+<Card>
+  <template #footer>
+    <p class="text-secondary-500 text-sm">Footer only</p>
+  </template>
+</Card>
+```
+
+### Classes
+
+```vue
+<Card
+  title="Styled parts"
+  :classes="{
+    footer: 'bg-secondary-50',
+    body: 'text-secondary-600',
+    root: 'ring-2 ring-primary-200',
+    title: 'text-xl font-bold tracking-tight',
+    header: 'bg-primary-50 dark:bg-primary-950/20',
+  }"
+>
+  Body text with custom classes applied.
+
+  <template #footer>
+    <span class="text-sm">Custom footer classes</span>
+  </template>
+</Card>
+```
+
+### customProps
+
+```vue
+<Card
+  title="Forwarded part attributes"
+  :custom-props="{
+    title: { id: 'card-demo-title' },
+    root: { 'data-testid': 'card-root' },
+    header: { 'aria-label': 'Card header' },
+    footer: { 'data-testid': 'card-footer' },
+    body: { role: 'region', 'aria-labelledby': 'card-demo-title' },
+  }"
+>
+  Card body with forwarded attributes on each part.
+
+  <template #footer>
+    <span>Inspect DOM for data attributes on each part.</span>
+  </template>
+</Card>
+```
+
+### Root HTML attributes
+
+```vue
+<Card
+  id="demo-card"
+  role="article"
+  class="max-w-md"
+  title="Root attrs"
+  aria-label="Demo card"
+>
+  class and other root HTML props are merged onto the root element.
+</Card>
+```
+
+### Combined
+
+```vue
+<Card
+  borderless
+  shadow="xl"
+  rounded="2xl"
+  padding="large"
+  variant="tonal"
+  title="Tonal card"
+  :classes="{ body: 'leading-relaxed' }"
+>
+  Large padding, 2xl rounded, xl shadow (elevated only — here variant is
+  tonal so shadow is ignored), borderless, and custom body classes.
+
+  <template #action>
+    <Button size="sm" variant="flat">Options</Button>
+  </template>
+
+  <template #footer>
+    <Button full size="sm">Continue</Button>
+  </template>
+</Card>
+```
+
+### customProps
+
+```vue
+<Card
+  title="Forwarded part attributes"
+  :custom-props="{
+    title: { id: 'card-demo-title' },
+    root: { 'data-testid': 'card-root' },
+    header: { 'aria-label': 'Card header' },
+    footer: { 'data-testid': 'card-footer' },
+    body: { role: 'region', 'aria-labelledby': 'card-demo-title' },
+  }"
+>
+  Card body with forwarded attributes on each part.
+
+  <template #footer>
+    <span>Inspect DOM for data attributes on each part.</span>
+  </template>
+</Card>
+```
+
+## Props
+
+| Prop          | Type              | Default    | Description                                                                                                                       |
+| ------------- | ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `borderless`  | `boolean`         | `false`    | Removes header and footer borders.                                                                                                |
+| `classes`     | `CardClasses`     | —          | The classes to apply to the card.                                                                                                 |
+| `customProps` | `CardCustomProps` | —          | Extra props for internal parts (`header`, `title`, `body`, `footer`, etc.). Root HTML attributes stay on the component top level. |
+| `padding`     | `CardPadding`     | "medium"   | Padding for header, body, and footer (horizontal alignment is shared).                                                            |
+| `rounded`     | `CardRounded`     | "sm"       | The roundedness of the card.                                                                                                      |
+| `shadow`      | `CardShadow`      | "sm"       | Shadow size. Only applied when `variant` is `elevated`.                                                                           |
+| `title`       | `string`          | —          | The title to apply to the card.                                                                                                   |
+| `variant`     | `CardVariant`     | "elevated" | Visual style of the card.                                                                                                         |
+
+## Related components
+
+Modal, List

package/docs/components/Checkbox.md

@@ -0,0 +1,87 @@
+# Checkbox
+
+Checkbox input with labels and form chrome. Extends FormControl props.
+
+## Import
+
+```ts
+import { Checkbox } from "@bridge-ui/vue/Components/Checkbox";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Checkbox
+  end-label="Accept terms"
+  description="Receive updates about your account."
+/>
+
+<Checkbox v-model="terms" end-label="Remember me" />
+
+<Checkbox indeterminate end-label="Select all" />
+```
+
+### Required and error
+
+```vue
+<Checkbox required end-label="Required field" />
+
+<Checkbox
+  error
+  end-label="Invalid option"
+  error-message="You must accept to continue."
+/>
+```
+
+### States
+
+```vue
+<Checkbox disabled :model-value="true" end-label="Disabled" />
+
+<Checkbox readonly :model-value="true" end-label="Read-only" />
+```
+
+### customProps
+
+```vue
+<Checkbox
+  end-label="Accept terms"
+  :custom-props="{
+    icon: { 'aria-hidden': true },
+    input: { name: 'terms', value: 'yes' },
+    control: { 'data-testid': 'terms-control' },
+  }"
+/>
+```
+
+## Props
+
+### Checkbox-specific
+
+| Prop            | Type                  | Default   | Description                                                                                |
+| --------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `checked`       | `boolean`             | —         | Whether the checkbox is checked.                                                           |
+| `classes`       | `CheckboxClasses`     | —         | Classes for the form control chrome and the checkbox control.                              |
+| `color`         | `CheckboxColor`       | "primary" | The color to apply to the checkbox.                                                        |
+| `customProps`   | `CheckboxCustomProps` | —         | Extra props for internal parts.                                                            |
+| `indeterminate` | `boolean`             | `false`   | Whether the checkbox is in an indeterminate state.                                         |
+| `rounded`       | `CheckboxRounded`     | "sm"      | The roundedness of the checkbox control.                                                   |
+| `size`          | `CheckboxSize`        | "md"      | Size of the control and of form control labels (`2xs` … `2xl`, same scale as `FormField`). |
+| `slots`         | `CheckboxSlots`       | —         | Chrome slots and the control slot.                                                         |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | —       | Bound with `v-model`.                                                        |
+| `update:modelValue` | `(value: boolean) => void` | —       | Emitted when `v-model` should update. Listen with `v-on:update:model-value`. |
+
+### Inherited from FormControl
+
+See [FormControl](./FormControl.md).
+
+## Related components
+
+FormControl, Radio, Switch

package/docs/components/Divider.md

@@ -0,0 +1,56 @@
+# Divider
+
+Horizontal or vertical separator for grouping content.
+
+## Import
+
+```ts
+import { Divider } from "@bridge-ui/vue/Components/Divider";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<div class="space-y-4">
+  <p>Section one</p>
+  <Divider />
+  <p>Section two</p>
+</div>
+```
+
+### Vertical
+
+```vue
+<div class="flex h-8 items-center gap-4">
+  <span>Left</span>
+  <Divider orientation="vertical" />
+  <span>Right</span>
+</div>
+```
+
+### Color
+
+```vue
+<Divider color="primary" />
+<Divider color="error" />
+```
+
+### Custom classes
+
+```vue
+<Divider class="my-6 h-0.5 bg-primary-500" />
+```
+
+## Props
+
+| Prop          | Type                 | Default        | Description                          |
+| ------------- | -------------------- | -------------- | ------------------------------------ |
+| `classes`     | `DividerClasses`     | —              | The classes to apply to the divider. |
+| `color`       | `DividerColor`       | `"dark"`       | The fill color of the divider.       |
+| `orientation` | `DividerOrientation` | `"horizontal"` | The orientation of the divider.      |
+
+## Related components
+
+Card, ListItem, Menu

package/docs/components/Drawer.md

@@ -0,0 +1,137 @@
+# Drawer
+
+Drawer overlay docked to a viewport edge, with portal, backdrop, and focus management. Put any content inside.
+
+## Import
+
+```ts
+import { Drawer } from "@bridge-ui/vue/Components/Drawer";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Button v-on:click="open = true">Open drawer</Button>
+
+<Drawer v-model="open">
+  <Card title="Filters" :on-close="() => (open = false)">
+    Drawer content goes here.
+  </Card>
+</Drawer>
+```
+
+### Persistent
+
+```vue
+<Drawer persistent v-model="open">
+  <Card title="Persistent drawer" :on-close="() => (open = false)">
+    Clicking the backdrop or pressing Escape has no effect.
+  </Card>
+</Drawer>
+```
+
+### Placement
+
+```vue
+<Drawer v-model="open" placement="right">
+  <Card title="Right drawer" :on-close="() => (open = false)">
+    Docks to the right edge instead of the default left.
+  </Card>
+</Drawer>
+```
+
+### Bottom sheet
+
+```vue
+<Drawer v-model="open" placement="bottom">
+  <Card title="Bottom sheet" :on-close="() => (open = false)">
+    Docks to the bottom edge; `size` controls the sheet height.
+  </Card>
+</Drawer>
+```
+
+### Full composition (Card)
+
+```vue
+<Drawer blur="md" size="lg" v-model="open" transition="slide">
+  <Card
+    borderless
+    shadow="lg"
+    rounded="none"
+    padding="large"
+    variant="elevated"
+    title="Edit filters"
+  >
+    Large drawer with Card title, body, and footer slots.
+
+    <template #footer>
+      <Button size="sm" color="error" variant="flat" v-on:click="open = false">
+        Discard
+      </Button>
+
+      <Button size="sm" color="primary" v-on:click="open = false">Save</Button>
+    </template>
+  </Card>
+</Drawer>
+```
+
+### customProps
+
+```vue
+<Drawer
+  v-model="open"
+  :custom-props="{
+    root: { id: 'drawer-root' },
+    panel: { id: 'drawer-panel' },
+    overlay: { id: 'drawer-overlay' },
+  }"
+>
+  <Card title="customProps" :on-close="() => (open = false)">
+    Inspect the DOM for ids on each drawer part.
+  </Card>
+</Drawer>
+```
+
+## Props
+
+| Prop                  | Type                | Default | Description                                                                                |
+| --------------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `ariaLabel`           | `string`            | —       | Accessible name for the dialog (`aria-label`).                                             |
+| `ariaLabelledBy`      | `string`            | —       | Id of the element that labels the dialog (`aria-labelledby`).                              |
+| `autoFocus`           | `boolean`           | `false` | When true, focuses the first focusable element inside the drawer on open.                  |
+| `blur`                | `DrawerBlur`        | "none"  | Backdrop blur on the overlay.                                                              |
+| `classes`             | `DrawerClasses`     | —       | The classes to apply to the drawer.                                                        |
+| `closeOnEscape`       | `boolean`           | `true`  | Whether the drawer closes on escape key press.                                             |
+| `closeOnOverlay`      | `boolean`           | `true`  | Whether the drawer closes on overlay click.                                                |
+| `customProps`         | `DrawerCustomProps` | —       | Props forwarded to each drawer part.                                                       |
+| `disableEnforceFocus` | `boolean`           | `false` | When true, focus is not trapped inside the drawer while open.                              |
+| `disableRestoreFocus` | `boolean`           | `false` | When true, focus is not restored to the previously focused element on close.               |
+| `disableScrollLock`   | `boolean`           | `false` | When true, body scroll is not locked while the drawer is open.                             |
+| `hideBackdrop`        | `boolean`           | `false` | When true, the backdrop overlay is not rendered.                                           |
+| `keepMounted`         | `boolean`           | `false` | When true, the drawer stays mounted in the DOM after closing (hidden).                     |
+| `persistent`          | `boolean`           | `false` | When true, escape and overlay clicks do not close the drawer.                              |
+| `placement`           | `DrawerPlacement`   | "left"  | Edge the panel docks to.                                                                   |
+| `scroll`              | `DrawerScroll`      | "paper" | Where scroll happens: the page (`body`) or the drawer panel (`paper`).                     |
+| `size`                | `DrawerSize`        | "md"    | Panel size along the placement axis (width for `left`/`right`, height for `top`/`bottom`). |
+| `teleportTo`          | `string \| false`   | "body"  | Where to teleport the drawer. Pass `false` to render in place.                             |
+| `transition`          | `DrawerTransition`  | "slide" | Enter/leave animation for overlay and panel.                                               |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | `false` | Whether the drawer is visible. Bound with `v-model`.                         |
+| `update:modelValue` | `(value: boolean) => void` | —       | Emitted when `v-model` should update. Listen with `v-on:update:model-value`. |
+
+## Events
+
+| Event              | Payload           | Description                                                                                                                     |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `v-on:close`       | —                 | Emitted when the user dismisses the drawer (overlay or Escape). Not emitted when the parent sets `v-model` to `false` directly. |
+| `v-on:show-change` | `(show: boolean)` | Emitted when visibility should change (controlled state). Listen with `v-on:show-change`.                                       |
+
+## Related components
+
+Card, useDialogAction, useDrawerAction, useModalAction

package/docs/components/FormControl.md

@@ -0,0 +1,66 @@
+# FormControl
+
+> Building block for toggle-row chrome. Prefer `Checkbox`, `Radio`, and `Switch` in apps; FormControl remains exported for advanced composition. Not a registry key — theme chrome via `tokens.formControl` on the public parent (e.g. `components.Checkbox.tokens.formControl`).
+
+Low-level form control chrome (labels, description, error) for Checkbox, Radio, and Switch.
+
+Control tokens stay on the parent (`tokens.color`, `tokens.invalidated`, …).
+
+## Import
+
+```ts
+import { FormControl } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<FormControl
+  end-label="Email notifications"
+  description="Receive product updates."
+>
+  <Checkbox :default-checked="true" />
+</FormControl>
+```
+
+### customProps
+
+```vue
+<FormControl
+  end-label="Email notifications"
+  description="Receive product updates."
+  :custom-props="{
+    root: { id: 'notify-control' },
+    endLabel: { id: 'notify-label' },
+    description: { id: 'notify-desc', 'aria-live': 'polite' },
+  }"
+>
+  <Checkbox :default-checked="true" />
+</FormControl>
+```
+
+## Props
+
+| Prop               | Type                     | Default | Description                                                                                                                          |
+| ------------------ | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `classes`          | `FormControlClasses`     | —       | Classes for labels, description, error, and layout chrome.                                                                           |
+| `controlId`        | `string`                 | —       | Associates labels and helper text with a form control. When omitted, an id is generated automatically.                               |
+| `customProps`      | `FormControlCustomProps` | —       | Extra props for internal parts (`row`, `endLabel`, `description`, …).                                                                |
+| `description`      | `string`                 | —       | Helper text below the control row (hidden when invalid).                                                                             |
+| `disabled`         | `boolean`                | `false` | Whether the control is disabled.                                                                                                     |
+| `endLabel`         | `string`                 | —       | Inline-end label after the control (right in LTR, left in RTL).                                                                      |
+| `error`            | `boolean`                | `false` | When `true`, applies invalid styling on labels and hides description.                                                                |
+| `errorMessage`     | `string`                 | —       | Error message below the control row.                                                                                                 |
+| `field`            | `UseFormControlReturn`   | —       | Pre-composed form control API from a parent composable. Used by `<FormControl :field="…" />`; not set on Checkbox, Radio, or Switch. |
+| `hideErrorMessage` | `boolean`                | `false` | When `true`, does not reserve space below the row for error messages.                                                                |
+| `readonly`         | `boolean`                | `false` | Whether the control is read-only.                                                                                                    |
+| `required`         | `boolean`                | `false` | Sets the native `required` attribute on the control and shows a required asterisk on labels.                                         |
+| `size`             | `LabelSize`              | "md"    | Typography scale for labels, description, and error text (aligned with `FormField` / `Label`).                                       |
+| `slots`            | `FormControlSlots`       | —       | Chrome slots (`startLabel`, `endLabel`, `description`, `errorMessage`, …) and the control.                                           |
+| `startLabel`       | `string`                 | —       | Inline-start label before the control (left in LTR, right in RTL).                                                                   |
+
+## Related components
+
+Checkbox, Radio, Switch, Label