@bridge-ui/vue 0.0.7 → 0.0.9

package/docs/components/List.md

@@ -0,0 +1,167 @@
+# List
+
+Vertical list container. Use with `ListItem` and `ListSection`.
+
+## Import
+
+```ts
+import { List } from "@bridge-ui/vue/Components/List";
+import { ListItem } from "@bridge-ui/vue/Components/ListItem";
+import { ListSection } from "@bridge-ui/vue/Components/ListSection";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<List>
+  <ListItem primary="Inbox" secondary="12 messages" />
+  <ListItem primary="Drafts" secondary="3 items" />
+  <ListItem primary="Sent" />
+</List>
+```
+
+### Sections
+
+```vue
+<List>
+  <ListSection title="Folders" />
+  <ListItem primary="Inbox" />
+  <ListItem primary="Drafts" />
+  <ListSection title="Labels" />
+  <ListItem primary="Important" />
+</List>
+```
+
+### Interactive
+
+```vue
+<List role="menu">
+  <ListItem
+    interactive
+    role="menuitem"
+    primary="Profile"
+    v-on:click="selected = 'profile'"
+    :selected="selected === 'profile'"
+  />
+  <ListItem
+    interactive
+    role="menuitem"
+    primary="Settings"
+    v-on:click="selected = 'settings'"
+    :selected="selected === 'settings'"
+  />
+</List>
+```
+
+### Start and end slots
+
+```vue
+<ListItem interactive primary="Inbox" secondary="12 unread messages">
+  <template #start>
+    <Mail class="text-secondary-500 size-5" />
+  </template>
+
+  <template #end>
+    <span class="text-secondary-400 text-xs">12</span>
+  </template>
+</ListItem>
+```
+
+### Selected icon
+
+Selected rows show a check icon by default. Customize it with `selectedIcon` on `ListItem`, or pass `null` to hide it. Providing the `#end` slot replaces the selected icon.
+
+```vue
+<List>
+  <ListItem selected interactive primary="Inbox" />
+  <ListItem selected interactive primary="Starred" :selected-icon="Star" />
+  <ListItem selected interactive primary="No icon" :selected-icon="null" />
+</List>
+```
+
+### Disabled and divider
+
+```vue
+<ListItem interactive primary="Available action" />
+<ListItem disabled interactive primary="Disabled action" />
+<ListItem divider primary="With divider" />
+```
+
+### Nested
+
+```vue
+<List>
+  <ListItem primary="Documents" />
+  <List nested>
+    <ListItem primary="Reports" />
+    <ListItem primary="Invoices" />
+  </List>
+  <ListItem primary="Settings" />
+</List>
+```
+
+### Sticky section
+
+With the default `as="li"`, sticky styles apply on the section root. The list (or a parent) needs a scroll container with a constrained height.
+
+```vue
+<div class="max-h-48 overflow-y-auto">
+  <List>
+    <ListSection sticky title="Section A" />
+    <ListItem primary="Item A1" />
+    <ListSection sticky title="Section B" />
+    <ListItem primary="Item B1" />
+  </List>
+</div>
+```
+
+### Inset section
+
+```vue
+<ListSection inset title="With icons below" />
+```
+
+## Props (`List`)
+
+| Prop          | Type                    | Default | Description                                                                        |
+| ------------- | ----------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `as`          | `"nav" \| "ol" \| "ul"` | "ul"    | The element to render as.                                                          |
+| `classes`     | `ListClasses`           | —       | The classes to apply to the list.                                                  |
+| `customProps` | `ListCustomProps`       | —       | Props forwarded to each list part.                                                 |
+| `dense`       | `boolean`               | `false` | Compact vertical spacing on items (`ListItem` / `ListSection`), not the list root. |
+| `nested`      | `boolean`               | `false` | When true, indents the list for nested navigation/submenus.                        |
+
+## Props (`ListItem`)
+
+| Prop           | Type                                 | Default  | Description                                                                        |
+| -------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------- |
+| `as`           | `"div" \| "li"`                      | "li"     | The element to render as.                                                          |
+| `classes`      | `ListItemClasses`                    | —        | The classes to apply to the item.                                                  |
+| `customProps`  | `ListItemCustomProps`                | —        | Props forwarded to each item part.                                                 |
+| `dense`        | `boolean`                            | —        | Compact vertical padding. Inherits `dense` from parent `List` when omitted.        |
+| `disabled`     | `boolean`                            | `false`  | When true, the item is not interactive and appears muted.                          |
+| `divider`      | `boolean`                            | `false`  | When true, renders a bottom divider on the item.                                   |
+| `interactive`  | `boolean`                            | `false`  | When true, applies hover/focus styles and `tabIndex={0}` on the inner wrapper.     |
+| `primary`      | `string`                             | —        | Primary label text.                                                                |
+| `role`         | `"button" \| "menuitem" \| "option"` | "button" | ARIA role for the interactive wrapper.                                             |
+| `secondary`    | `string`                             | —        | Secondary/description text below the primary line.                                 |
+| `selected`     | `boolean`                            | `false`  | When true, highlights the item as selected.                                        |
+| `selectedIcon` | `null \| LucideIcon`                 | `Check`  | Icon shown when `selected` is true. Use `null` to hide it. Replaced by `#end`.     |
+| `value`        | `ListboxValue`                       | —        | When set inside a `Select` / `Listbox`, registers this row as a selectable option. |
+
+## Props (`ListSection`)
+
+| Prop          | Type                     | Default | Description                                                                                                                                                  |
+| ------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `as`          | `"div" \| "li"`          | "li"    | The element to render as.                                                                                                                                    |
+| `classes`     | `ListSectionClasses`     | —       | The classes to apply to the section.                                                                                                                         |
+| `customProps` | `ListSectionCustomProps` | —       | Props forwarded to each section part.                                                                                                                        |
+| `inset`       | `boolean`                | `false` | When true, adds left padding to align with items that have leading icons.                                                                                    |
+| `sticky`      | `boolean`                | `false` | When true, sticks the heading while scrolling. On `as="li"` (default), sticky + opaque background apply to the root; on `as="div"`, they apply to the title. |
+| `title`       | `string`                 | —       | Section label text.                                                                                                                                          |
+
+## Related components
+
+Menu, Select

package/docs/components/Menu.md

@@ -0,0 +1,97 @@
+# Menu
+
+Anchored floating panel for actions and dropdowns. Control with `v-model` / `show`.
+
+## Import
+
+```ts
+import { Menu } from "@bridge-ui/vue/Components/Menu";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Menu v-model="open">
+  <template #trigger>
+    <Button v-on:click="open = true">Open menu</Button>
+  </template>
+
+  <MenuContent v-on:action="open = false" />
+</Menu>
+```
+
+### Placement
+
+```vue
+<Menu v-model="open" placement="bottom-end">
+  <template #trigger>
+    <Button v-on:click="open = true">Open menu</Button>
+  </template>
+
+  <MenuContent />
+</Menu>
+```
+
+### Persistent
+
+```vue
+<Menu persistent v-model="open">
+  <template #trigger>
+    <Button v-on:click="open = true">Open persistent</Button>
+  </template>
+
+  <MenuContent />
+</Menu>
+```
+
+### anchorEl
+
+```vue
+<div ref="anchorRef">
+  <Button v-on:click="open = true">External anchor</Button>
+</div>
+
+<Menu v-model="open" :anchor-el="anchorRef">
+  <MenuContent />
+</Menu>
+```
+
+## Props
+
+| Prop                | Type                      | Default        | Description                                                                                                                                                                                                                                                                          |
+| ------------------- | ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `anchorEl`          | `HTMLElement \| null`     | —              | Element that anchors the menu panel. When set, it is used for positioning and click-away instead of the `trigger` slot wrapper. Prefer this when the opener lives outside the `Menu` or is controlled manually. Not merged into Bridge defaults (DOM nodes must not be deep-merged). |
+| `classes`           | `MenuClasses`             | —              | The classes to apply to the menu.                                                                                                                                                                                                                                                    |
+| `closeOnClickAway`  | `boolean`                 | `true`         | Whether the menu closes when clicking outside the trigger and panel.                                                                                                                                                                                                                 |
+| `closeOnEscape`     | `boolean`                 | `true`         | Whether the menu closes on escape key press.                                                                                                                                                                                                                                         |
+| `customProps`       | `MenuCustomProps`         | —              | Props forwarded to each menu part.                                                                                                                                                                                                                                                   |
+| `disableAutoFocus`  | `boolean`                 | `false`        | When true, the menu does not auto-focus the first focusable item on open.                                                                                                                                                                                                            |
+| `disableScrollLock` | `boolean`                 | `true`         | When true, body scroll is not locked while the menu is open.                                                                                                                                                                                                                         |
+| `keepMounted`       | `boolean`                 | `false`        | When true, the menu stays mounted in the DOM after closing (hidden).                                                                                                                                                                                                                 |
+| `offset`            | `number`                  | 4              | Gap between the trigger and the menu panel (px).                                                                                                                                                                                                                                     |
+| `onShowChange`      | `(show: boolean) => void` | —              | Called when `show` should change (controlled state without `v-model`).                                                                                                                                                                                                               |
+| `persistent`        | `boolean`                 | `false`        | When true, escape and click-away do not close the menu.                                                                                                                                                                                                                              |
+| `placement`         | `PositionPlacement`       | "bottom-start" | Preferred placement of the menu relative to the anchor (Floating UI).                                                                                                                                                                                                                |
+| `rounded`           | `MenuRounded`             | "md"           | The roundedness of the menu panel.                                                                                                                                                                                                                                                   |
+| `shadow`            | `MenuShadow`              | "md"           | The shadow to apply to the menu panel.                                                                                                                                                                                                                                               |
+| `strategy`          | `PositionStrategy`        | "fixed"        | CSS position strategy for the floating panel.                                                                                                                                                                                                                                        |
+| `teleportTo`        | `string \| false`         | "body"         | Where to portal the menu panel. Pass `false` to render in place.                                                                                                                                                                                                                     |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | `false` | Whether the menu is open. 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 menu (Escape or click-away). Not emitted when the parent sets `v-model` to `false` directly. |
+
+## Related components
+
+List, ListItem, Select, Button

package/docs/components/Modal.md

@@ -0,0 +1,154 @@
+# Modal
+
+Modal overlay with portal, backdrop, and focus management. Put `Card` or any content inside.
+
+## Import
+
+```ts
+import { Modal } from "@bridge-ui/vue/Components/Modal";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Button v-on:click="open = true">Open modal</Button>
+
+<Modal v-model="open">
+  <Card title="Confirm action" :on-close="() => (open = false)">
+    Are you sure you want to continue?
+  </Card>
+</Modal>
+```
+
+### Persistent
+
+```vue
+<Modal persistent v-model="open">
+  <Card title="Persistent modal" :on-close="() => (open = false)">
+    Clicking the backdrop or pressing Escape has no effect.
+  </Card>
+</Modal>
+```
+
+### Responsive align
+
+```vue
+<script setup>
+import { useBreakpoint } from "@bridge-ui/vue";
+
+const breakpoint = useBreakpoint();
+</script>
+
+<template>
+  <Modal
+    v-model="open"
+    :align="breakpoint.mobile ? 'bottom-center' : 'middle-center'"
+  >
+    <Card title="Responsive" :on-close="() => (open = false)">
+      Bottom sheet on mobile, centered from `sm` up.
+    </Card>
+  </Modal>
+</template>
+```
+
+> **Breaking:** `align` now applies on all breakpoints. Mobile no longer forces a bottom sheet — use `useBreakpoint` (as above) to restore that pattern.
+
+### Nested modals
+
+```vue
+<Modal size="lg" v-model="outerOpen">
+  <Card title="Outer modal" :on-close="() => (outerOpen = false)">
+    <Button size="sm" v-on:click="innerOpen = true">Open nested modal</Button>
+  </Card>
+
+  <Modal size="sm" v-model="innerOpen">
+    <Card title="Nested confirmation" :on-close="() => (innerOpen = false)">
+      Press Escape to close only this layer.
+    </Card>
+  </Modal>
+</Modal>
+```
+
+### Full composition (Card)
+
+```vue
+<Modal blur="md" size="lg" v-model="open" transition="slide-up">
+  <Card
+    borderless
+    shadow="lg"
+    rounded="2xl"
+    padding="large"
+    variant="elevated"
+    title="Edit profile"
+  >
+    Large modal 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>
+</Modal>
+```
+
+### customProps
+
+```vue
+<Modal
+  v-model="open"
+  :custom-props="{
+    root: { id: 'modal-root' },
+    panel: { id: 'modal-panel' },
+    overlay: { id: 'modal-overlay' },
+  }"
+>
+  <Card title="customProps" :on-close="() => (open = false)">
+    Inspect the DOM for ids on each modal part.
+  </Card>
+</Modal>
+```
+
+## Props
+
+| Prop                  | Type               | Default         | Description                                                                                                        |
+| --------------------- | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `align`               | `ModalAlign`       | "middle-center" | Panel position on all breakpoints (`{row}-{column}` grid). Use `useBreakpoint` for a different align per viewport. |
+| `autoFocus`           | `boolean`          | `false`         | When true, focuses the first focusable element inside the dialog on open.                                          |
+| `blur`                | `ModalBlur`        | "none"          | Backdrop blur on the overlay.                                                                                      |
+| `classes`             | `ModalClasses`     | —               | The classes to apply to the modal.                                                                                 |
+| `closeOnEscape`       | `boolean`          | `true`          | Whether the modal closes on escape key press.                                                                      |
+| `closeOnOverlay`      | `boolean`          | `true`          | Whether the modal closes on overlay click.                                                                         |
+| `customProps`         | `ModalCustomProps` | —               | Props forwarded to each modal part.                                                                                |
+| `disableEnforceFocus` | `boolean`          | `false`         | When true, focus is not trapped inside the modal 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 modal is open.                                                      |
+| `hideBackdrop`        | `boolean`          | `false`         | When true, the backdrop overlay is not rendered.                                                                   |
+| `keepMounted`         | `boolean`          | `false`         | When true, the modal stays mounted in the DOM after closing (hidden).                                              |
+| `persistent`          | `boolean`          | `false`         | When true, escape and overlay clicks do not close the modal.                                                       |
+| `scroll`              | `ModalScroll`      | "body"          | Where scroll happens: the page (`body`) or the dialog panel (`paper`).                                             |
+| `size`                | `ModalSize`        | "md"            | Max width of the dialog from the `sm` breakpoint up (`sm:max-w-*`).                                                |
+| `teleportTo`          | `string \| false`  | "body"          | Where to teleport the modal. Pass `false` to render in place.                                                      |
+| `transition`          | `ModalTransition`  | "fade"          | Enter/leave animation for overlay and panel.                                                                       |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | `false` | Whether the modal 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 modal (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, useModalAction

package/docs/components/NumberField.md

@@ -0,0 +1,80 @@
+# NumberField
+
+Numeric input with increment/decrement controls. Extends FormField props.
+
+## Import
+
+```ts
+import { NumberField } from "@bridge-ui/vue/Components/NumberField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<NumberField :min="0" :max="20" :step="1" placeholder="0" label="Quantity" />
+
+<NumberField
+  label="Units"
+  v-model="quantity"
+  description="Use the stepper or type a value."
+/>
+
+<NumberField
+  error
+  label="Amount"
+  error-message="Value must be between 0 and 100."
+/>
+```
+
+### Min, max, and step
+
+```vue
+<NumberField :min="1" :max="99" :step="5" label="Items" placeholder="0" />
+```
+
+### customProps
+
+```vue
+<NumberField
+  placeholder="0"
+  label="Quantity"
+  description="Input uses name via customProps."
+  :custom-props="{
+    input: { name: 'demo-quantity' },
+  }"
+/>
+```
+
+## Props
+
+### NumberField-specific
+
+| Prop      | Type                 | Default | Description                               |
+| --------- | -------------------- | ------- | ----------------------------------------- |
+| `classes` | `NumberFieldClasses` | —       | The classes to apply to the number field. |
+| `max`     | `number`             | —       | The maximum value.                        |
+| `min`     | `number`             | —       | The minimum value.                        |
+| `step`    | `number`             | 1       | The step increment value.                 |
+
+### v-model
+
+| Prop / Event        | Type                              | Default | Description                                                                  |
+| ------------------- | --------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `number \| null`                  | —       | Bound with `v-model`.                                                        |
+| `update:modelValue` | `(value: number \| null) => void` | —       | Emitted when `v-model` should update. Listen with `v-on:update:model-value`. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md).
+
+## Events
+
+| Event         | Payload           | Description                                     |
+| ------------- | ----------------- | ----------------------------------------------- |
+| `v-on:change` | `(value: number)` | Emitted with the numeric value when it changes. |
+
+## Related components
+
+TextField, FormField

package/docs/components/OtpField.md

@@ -0,0 +1,133 @@
+# OtpField
+
+One-time password / PIN input with individual pin cells. Label, description, and
+error chrome are rendered via the shared `BaseField` layout; variants style each
+pin.
+
+## Import
+
+```ts
+import { OtpField } from "@bridge-ui/vue/Components/OtpField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<OtpField label="Verification code" />
+
+<OtpField
+  v-model="code"
+  :length="4"
+  label="PIN"
+  description="Enter the 4-digit code from your email."
+/>
+
+<OtpField error label="Code" error-message="Invalid or expired code." />
+```
+
+### Length and type
+
+```vue
+<OtpField :length="4" label="PIN" />
+
+<OtpField :length="8" type="alphanumeric" label="Backup code" />
+```
+
+### Variants
+
+```vue
+<OtpField variant="outline" label="Outline" />
+<OtpField variant="filled" label="Filled" />
+<OtpField variant="underlined" label="Underlined" />
+<OtpField variant="stacked" label="Stacked" />
+<OtpField variant="notched" label="Notched" />
+```
+
+### Masked
+
+```vue
+<OtpField mask label="Secure code" />
+```
+
+### Adornment slots
+
+```vue
+<OtpField label="Code">
+  <template #start>
+    <Lock aria-hidden="true" />
+  </template>
+  <template #end>
+    <button type="button">Resend</button>
+  </template>
+</OtpField>
+```
+
+### customProps
+
+```vue
+<OtpField
+  label="Code"
+  description="Pins use name via customProps."
+  :custom-props="{
+    input: { name: 'demo-otp' },
+  }"
+/>
+```
+
+## Props
+
+### OtpField-specific
+
+| Prop           | Type                          | Default     | Description                                 |
+| -------------- | ----------------------------- | ----------- | ------------------------------------------- |
+| `autoFocus`    | `boolean`                     | `false`     | Focus the first empty pin on mount.         |
+| `classes`      | `OtpFieldClasses`             | —           | Classes for the field chrome and pin cells. |
+| `defaultValue` | `string`                      | —           | Initial value when `v-model` is unbound.    |
+| `length`       | `number`                      | `6`         | Number of pin slots.                        |
+| `mask`         | `boolean`                     | `false`     | Mask pin values (password-style).           |
+| `placeholder`  | `string`                      | —           | Placeholder character in empty pins.        |
+| `type`         | `"numeric" \| "alphanumeric"` | `"numeric"` | Character set accepted by each pin.         |
+| `variant`      | `OtpFieldVariant`             | `"outline"` | Visual variant applied to each pin cell.    |
+
+### Binding
+
+| Prop         | Type     | Default | Description                         |
+| ------------ | -------- | ------- | ----------------------------------- |
+| `modelValue` | `string` | —       | Concatenated OTP value (`v-model`). |
+
+### Field chrome
+
+Label, corner, description, error message, and start/end adornment slots use the
+same `BaseField` layout as other field components. Pin-specific props (`length`,
+`mask`, `variant`, …) apply only to the pin row.
+
+| Prop               | Type      | Default     | Description                                                             |
+| ------------------ | --------- | ----------- | ----------------------------------------------------------------------- |
+| `color`            | token     | `"primary"` | Focus color on each pin.                                                |
+| `controlId`        | `string`  | auto        | Id for the pin group and related labels.                                |
+| `corner`           | `string`  | —           | Secondary header text.                                                  |
+| `customProps`      | object    | —           | Extra props for internal parts.                                         |
+| `description`      | `string`  | —           | Helper text below the pins.                                             |
+| `disabled`         | `boolean` | `false`     | Disables all pins.                                                      |
+| `error`            | `boolean` | `false`     | Invalid styling.                                                        |
+| `errorMessage`     | `string`  | —           | Error message below the pins.                                           |
+| `hideErrorMessage` | `boolean` | `false`     | Hides the error message row.                                            |
+| `label`            | `string`  | —           | Primary label above the pins.                                           |
+| `readonly`         | `boolean` | `false`     | Makes all pins read-only.                                               |
+| `required`         | `boolean` | `false`     | Shows a required asterisk on the label.                                 |
+| `rounded`          | token     | `"md"`      | Border radius of each pin.                                              |
+| `size`             | token     | `"md"`      | Pin size and label typography (`2xs` … `2xl`).                          |
+| `slots`            | —         | —           | `#label`, `#corner`, `#description`, `#errorMessage`, `#start`, `#end`. |
+
+## Events
+
+| Event      | Payload  | Description                          |
+| ---------- | -------- | ------------------------------------ |
+| `change`   | `string` | Emitted when the OTP string changes. |
+| `complete` | `string` | Emitted when every pin is filled.    |
+
+## Related components
+
+BaseField, TextField, FormField, NumberField