@bridge-ui/vue 0.0.7 → 0.0.8

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

package/docs/components/PasswordField.md

@@ -0,0 +1,82 @@
+# PasswordField
+
+Password input with visibility toggle. Extends FormField props.
+
+## Import
+
+```ts
+import { PasswordField } from "@bridge-ui/vue/Components/PasswordField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<PasswordField label="Password" placeholder="Enter password..." />
+
+<PasswordField
+  v-model="password"
+  label="New password"
+  description="Use at least 8 characters."
+/>
+
+<PasswordField error label="Password" error-message="Password is too weak." />
+```
+
+### Controlled visibility
+
+```vue
+<PasswordField
+  label="Password"
+  :visible="visible"
+  placeholder="••••••••"
+  v-on:visibility-change="visible = $event"
+  description="visible is bound to parent state."
+/>
+```
+
+### customProps
+
+```vue
+<PasswordField
+  label="Password"
+  placeholder="••••••••"
+  :custom-props="{
+    input: {
+      name: 'demo-password',
+      autocomplete: 'new-password',
+    },
+  }"
+/>
+```
+
+## Props
+
+### PasswordField-specific
+
+| Prop      | Type                   | Default | Description                                                  |
+| --------- | ---------------------- | ------- | ------------------------------------------------------------ |
+| `classes` | `PasswordFieldClasses` | —       | The classes to apply to the password field.                  |
+| `visible` | `boolean \| null`      | —       | Whether the password is visible. Omit for uncontrolled mode. |
+
+### v-model
+
+| Prop / Event        | Type                              | Default | Description                                                                  |
+| ------------------- | --------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `string \| null`                  | —       | Bound with `v-model`.                                                        |
+| `update:modelValue` | `(value: string \| 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:visibility-change` | `(visible: boolean)` | Emitted when password visibility changes. |
+
+## Related components
+
+TextField, FormField

package/docs/components/Progress.md

@@ -0,0 +1,68 @@
+# Progress
+
+Linear progress indicator for determinate, indeterminate, buffer, and query loading states.
+
+## Import
+
+```ts
+import { Progress } from "@bridge-ui/vue/Components/Progress";
+```
+
+## Examples
+
+### Indeterminate
+
+```vue
+<Progress aria-label="Loading…" />
+```
+
+### Determinate
+
+```vue
+<Progress :value="40" variant="determinate" aria-label="Export data" />
+```
+
+### Buffer
+
+```vue
+<Progress
+  :value="30"
+  variant="buffer"
+  :value-buffer="60"
+  aria-label="Loading…"
+/>
+```
+
+### Query
+
+```vue
+<Progress variant="query" aria-label="Loading…" />
+```
+
+### Color and size
+
+```vue
+<Progress size="lg" color="success" aria-label="Saving…" />
+<Progress size="2xs" rounded="md" aria-label="Syncing…" />
+```
+
+`size` uses the shared scale (`2xs` … `2xl`). `rounded` uses the shared radius scale (`none` / `xs` … `4xl` / `full`).
+
+## Props
+
+| Prop          | Type                  | Default           | Description                                       |
+| ------------- | --------------------- | ----------------- | ------------------------------------------------- |
+| `classes`     | `ProgressClasses`     | —                 | Classes for `root`, `track`, `bar`, and `buffer`. |
+| `color`       | `ProgressColor`       | `"primary"`       | Semantic color of the bar and track.              |
+| `customProps` | `ProgressCustomProps` | —                 | Extra props for internal parts.                   |
+| `rounded`     | `ProgressRounded`     | `"full"`          | Border radius of the bar.                         |
+| `size`        | `ProgressSize`        | `"md"`            | Height of the progress bar.                       |
+| `value`       | `number`              | —                 | Progress 0–100 (`determinate` / `buffer`).        |
+| `valueBuffer` | `number`              | —                 | Buffer 0–100 (`buffer` variant).                  |
+| `variant`     | `ProgressVariant`     | `"indeterminate"` | Visual mode of the indicator.                     |
+
+Pass `aria-label` or `aria-labelledby` for an accessible name.
+
+## Related components
+
+Spinner, Skeleton, Snackbar

package/docs/components/Radio.md

@@ -0,0 +1,91 @@
+# Radio
+
+Radio input for mutually exclusive choices. Extends FormControl props.
+
+## Import
+
+```ts
+import { Radio } from "@bridge-ui/vue/Components/Radio";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Radio
+  name="plan"
+  v-model="plan"
+  value="starter"
+  end-label="Starter"
+  description="Free tier for individuals."
+/>
+
+<Radio
+  name="plan"
+  value="pro"
+  v-model="plan"
+  end-label="Pro"
+  description="For growing teams."
+/>
+```
+
+### Required and error
+
+```vue
+<Radio required value="req" name="required" end-label="Required field" />
+
+<Radio
+  error
+  value="err"
+  name="error"
+  end-label="Invalid option"
+  error-message="Please select a valid option."
+/>
+```
+
+### customProps
+
+```vue
+<Radio
+  name="plan"
+  value="pro"
+  end-label="Pro plan"
+  :custom-props="{
+    input: { id: 'plan-pro' },
+    dot: { 'aria-hidden': true },
+    control: { 'data-testid': 'plan-pro-control' },
+  }"
+/>
+```
+
+## Props
+
+### Radio-specific
+
+| Prop          | Type               | Default   | Description                                                                                |
+| ------------- | ------------------ | --------- | ------------------------------------------------------------------------------------------ |
+| `checked`     | `boolean`          | —         | Whether the radio is checked.                                                              |
+| `classes`     | `RadioClasses`     | —         | Classes for the form control chrome and the radio control.                                 |
+| `color`       | `RadioColor`       | "primary" | The color to apply to the radio.                                                           |
+| `customProps` | `RadioCustomProps` | —         | Extra props for internal parts.                                                            |
+| `name`        | `string`           | —         | The `name` attribute shared by radios in the same group.                                   |
+| `rounded`     | `RadioRounded`     | "full"    | The roundedness of the radio control.                                                      |
+| `size`        | `RadioSize`        | "md"      | Size of the control and of form control labels (`2xs` … `2xl`, same scale as `FormField`). |
+| `slots`       | `RadioSlots`       | —         | Chrome slots and the control slot.                                                         |
+| `value`       | `string \| number` | —         | The value of this radio option.                                                            |
+
+### v-model
+
+| Prop / Event        | Type                                | Default | Description                                                                  |
+| ------------------- | ----------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `string \| number`                  | —       | Bound with `v-model`.                                                        |
+| `update:modelValue` | `(value: string \| number) => void` | —       | Emitted when `v-model` should update. Listen with `v-on:update:model-value`. |
+
+### Inherited from FormControl
+
+See [FormControl](./FormControl.md).
+
+## Related components
+
+Checkbox, FormControl