@bridge-ui/vue 0.0.7 → 0.0.9

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

package/docs/components/Select.md

@@ -0,0 +1,195 @@
+# Select
+
+Dropdown select with single/multiple value, search, and async data.
+
+## Import
+
+```ts
+import { Select } from "@bridge-ui/vue/Components/Select";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Select label="Country" :options="countries" placeholder="Select a country" />
+
+<Select
+  multiple
+  searchable
+  label="Frameworks"
+  v-model="selected"
+  :options="frameworks"
+/>
+
+<Select error label="Country" error-message="Please select a valid country." />
+```
+
+### Searchable
+
+```vue
+<Select
+  searchable
+  label="Country"
+  :options="countries"
+  placeholder="Type to filter..."
+/>
+```
+
+### Async data
+
+```vue
+<Select
+  label="City (async)"
+  placeholder="Type to search cities..."
+  :async-data="{
+    search: asyncSearch,
+    resolve: asyncResolveSelected,
+  }"
+/>
+```
+
+### Custom option slot
+
+```vue
+<Select
+  label="Framework"
+  :options="frameworks"
+  placeholder="Custom rendered options"
+>
+  <template #option="{ option, selected }">
+    <span class="flex w-full items-center justify-between gap-2">
+      <span class="truncate font-medium">{{ option.label }}</span>
+
+      <span v-if="selected" class="text-primary-600 shrink-0 text-xs font-semibold">
+        Selected
+      </span>
+    </span>
+  </template>
+</Select>
+```
+
+### Grouped options
+
+`options` may mix standalone options and section groups (`{ title, options, sticky? }`). Search filters within sections and drops empty ones.
+
+```vue
+<Select
+  searchable
+  label="Produce"
+  :options="[
+    {
+      title: 'Fruits',
+      sticky: true,
+      options: [
+        { label: 'Apple', value: 'apple' },
+        { label: 'Banana', value: 'banana' },
+      ],
+    },
+    {
+      title: 'Vegetables',
+      options: [{ label: 'Carrot', value: 'carrot' }],
+    },
+    { label: 'Other', value: 'other' },
+  ]"
+/>
+```
+
+### Composed list (default slot)
+
+Use the default slot with `ListSection` / `ListItem` to build the dropdown list manually. Set `value` on each `ListItem` so it registers as a selectable option. Declarative `SelectOption` children still feed the `options` data path; only `ListSection` / `ListItem` (and similar) count as composed list content. The `#option` slot remains for customizing items rendered from the `options` prop.
+
+```vue
+<Select label="Status" v-model="status">
+  <ListSection sticky title="Workflow" />
+  <ListItem value="open" primary="Open" />
+  <ListItem value="closed" primary="Closed" />
+</Select>
+```
+
+### Overlay
+
+```vue
+<Select overlay="auto" label="Country" :options="countries" />
+
+<Select label="Country" overlay="drawer" :options="countries" />
+```
+
+Default `overlay` is `auto`: `menu` on desktop and bottom `drawer` on mobile.
+When unset, `showFooter` defaults to `true` on mobile (`false` on desktop). Selection stays draft until Apply.
+
+### customProps
+
+```vue
+<Select
+  label="Country"
+  :options="countries"
+  placeholder="Select a country"
+  :custom-props="{
+    root: { id: 'country-field' },
+    input: { name: 'country', autocomplete: 'country' },
+  }"
+/>
+```
+
+## Props
+
+### Select-specific
+
+| Prop                | Type                  | Default                               | Description                                                                                             |
+| ------------------- | --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `asyncData`         | `SelectAsyncData`     | —                                     | Remote data source. Implies `searchable`.                                                               |
+| `clearable`         | `boolean`             | `true`                                | Whether the value can be cleared.                                                                       |
+| `defaultValue`      | `SelectModel`         | —                                     | Initial value when uncontrolled.                                                                        |
+| `disableMaxHeight`  | `boolean`             | `false`                               | When true, the dropdown options list is not height-limited. Forwarded to the internal `Listbox`.        |
+| `emptyMessage`      | `string`              | "No options"                          | Message when the filtered list is empty.                                                                |
+| `flipOptions`       | `boolean`             | `false`                               | Inverts the visual order of options.                                                                    |
+| `hideEmptyMessage`  | `boolean`             | `false`                               | Hides the empty-state message.                                                                          |
+| `loading`           | `boolean`             | —                                     | External or async loading state.                                                                        |
+| `maxHeight`         | `string`              | "max-h-60"                            | Tailwind max-height class for the dropdown options area. Forwarded to the internal `Listbox`.           |
+| `minItemsForSearch` | `number`              | 11                                    | Minimum option count before search UI is enabled.                                                       |
+| `multiple`          | `boolean`             | `false`                               | Whether multiple values can be selected.                                                                |
+| `optionDescription` | `string`              | "description"                         | Key used to read the description from option objects.                                                   |
+| `optionLabel`       | `string`              | "label"                               | Key used to read the label from option objects.                                                         |
+| `options`           | `ListboxOptionsInput` | —                                     | Options to display. May include section groups (`{ title, options, sticky? }`) mixed with flat options. |
+| `optionValue`       | `string`              | "value"                               | Key used to read the value from option objects.                                                         |
+| `overlay`           | `FieldOverlayMode`    | `"auto"`                              | Overlay shell: `menu`, `modal`, `drawer`, or `auto`.                                                    |
+| `placeholder`       | `string`              | —                                     | Placeholder shown when no value is selected.                                                            |
+| `searchable`        | `boolean`             | `false`                               | Whether options can be filtered via the trigger input.                                                  |
+| `showFooter`        | `boolean`             | `false` (`true` on mobile when unset) | Shows Cancel / Apply on the nested listbox. Selection stays draft until Apply.                          |
+
+### v-model
+
+| Prop / Event        | Type                                                    | Default | Description                                                                  |
+| ------------------- | ------------------------------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `SelectValue \| SelectValue[] \| null`                  | —       | Bound with `v-model`.                                                        |
+| `update:modelValue` | `(value: SelectValue \| SelectValue[] \| null) => void` | —       | Emitted when `v-model` should update. Listen with `v-on:update:model-value`. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md) (building-block chrome). Field tokens live on `components.Select` (`size`, `color`, `rounded`, `variant`, …). Dropdown option tokens are nested under `components.Select.tokens.listbox`.
+
+## Slots
+
+| Slot      | Scope                                         | Description                                                                                                |
+| --------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `default` | —                                             | Composed list content (`ListSection` / `ListItem` with `value`). Replaces mapped `options` in the listbox. |
+| `option`  | `{ option: SelectOption; selected: boolean }` | Custom option content when rendering from the `options` prop.                                              |
+
+## Events
+
+| Event           | Payload                  | Description                                                          |
+| --------------- | ------------------------ | -------------------------------------------------------------------- |
+| `v-on:cancel`   | —                        | Emitted when Cancel is pressed on the listbox footer (`showFooter`). |
+| `v-on:change`   | `(value: SelectModel)`   | Emitted when the selection changes.                                  |
+| `v-on:clear`    | —                        | Emitted when the value is cleared.                                   |
+| `v-on:close`    | —                        | Emitted when the menu closes.                                        |
+| `v-on:deselect` | `(option: SelectOption)` | Emitted when an option is deselected (multiple mode).                |
+| `v-on:open`     | —                        | Emitted when the menu opens.                                         |
+| `v-on:search`   | `(query: string)`        | Emitted when the search query changes.                               |
+| `v-on:select`   | `(option: SelectOption)` | Emitted when an option is selected.                                  |
+
+## Related components
+
+Menu, Modal, Drawer, FieldOverlay, List, ListItem, ListSection, FormField

package/docs/components/Skeleton.md

@@ -0,0 +1,38 @@
+# Skeleton
+
+Placeholder block for loading states. Size it with Tailwind height/width classes.
+
+## Import
+
+```ts
+import { Skeleton } from "@bridge-ui/vue/Components/Skeleton";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Skeleton class="h-4 w-32" />
+
+<Skeleton rounded="full" class="h-10 w-10" />
+
+<Skeleton rounded="lg" class="h-24 w-full" />
+```
+
+### Custom classes
+
+```vue
+<Skeleton class="h-4 w-48 bg-primary-200 dark:bg-primary-800" />
+```
+
+## Props
+
+| Prop      | Type              | Default | Description                           |
+| --------- | ----------------- | ------- | ------------------------------------- |
+| `classes` | `SkeletonClasses` | —       | The classes to apply to the skeleton. |
+| `rounded` | `SkeletonRounded` | `"md"`  | The roundedness of the skeleton.      |
+
+## Related components
+
+Avatar, Card

package/docs/components/Slider.md

@@ -0,0 +1,140 @@
+# Slider
+
+Horizontal slider for selecting a single value or a range. Label, corner,
+start/end slots, description, and error chrome are rendered via the shared
+`BaseField` layout; tooltips and stop marks are optional.
+
+## Import
+
+```ts
+import { Slider } from "@bridge-ui/vue/Components/Slider";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Slider label="Volume" />
+
+<Slider
+  v-model="opacity"
+  label="Opacity"
+  corner="%"
+  description="Adjust transparency."
+/>
+
+<Slider error label="Volume" error-message="Value is required." />
+```
+
+### Range
+
+```vue
+<Slider range v-model="range" label="Price range" />
+
+<Slider range :default-value="[20, 80]" label="Range" />
+```
+
+### Min, max, and step
+
+```vue
+<Slider :min="0" :max="100" :step="10" label="Rating" />
+```
+
+### Colors and sizes
+
+```vue
+<Slider color="primary" label="Primary" />
+<Slider color="secondary" label="Secondary" />
+<Slider size="sm" label="Small" />
+<Slider size="lg" label="Large" />
+```
+
+### Stops and tooltips
+
+```vue
+<Slider
+  show-stops
+  label="Rating"
+  :stops="[
+    { value: 0, label: 'Low' },
+    { value: 100, label: 'High' },
+  ]"
+/>
+
+<Slider :show-tooltip="false" label="Volume" />
+```
+
+### customProps
+
+```vue
+<Slider
+  label="Volume"
+  description="Track uses name via customProps."
+  :custom-props="{
+    track: { 'data-testid': 'volume-track' },
+  }"
+/>
+```
+
+## Props
+
+### Slider-specific
+
+| Prop           | Type                         | Default     | Description                                             |
+| -------------- | ---------------------------- | ----------- | ------------------------------------------------------- |
+| `classes`      | `SliderClasses`              | —           | Classes for the field chrome and slider control.        |
+| `color`        | token                        | `"primary"` | Bar and thumb color.                                    |
+| `defaultValue` | `number \| [number, number]` | min         | Initial value when `v-model` is unbound.                |
+| `max`          | `number`                     | `100`       | Maximum value.                                          |
+| `min`          | `number`                     | `0`         | Minimum value.                                          |
+| `range`        | `boolean`                    | `false`     | Two-thumb range selection.                              |
+| `rounded`      | token                        | `"full"`    | Track and bar border radius.                            |
+| `showStops`    | `boolean`                    | `false`     | Render stop marks on the track.                         |
+| `showTooltip`  | `boolean`                    | `true`      | Show value tooltip on each thumb while focused/hovered. |
+| `size`         | token                        | `"md"`      | Track/thumb size and chrome typography.                 |
+| `step`         | `number`                     | `1`         | Step increment between values.                          |
+| `stops`        | `SliderStopInput[]`          | —           | Custom stop marks (numbers become `{ value }`).         |
+
+### Binding
+
+| Prop         | Type                         | Default | Description                |
+| ------------ | ---------------------------- | ------- | -------------------------- |
+| `modelValue` | `number \| [number, number]` | —       | Current value (`v-model`). |
+
+### Field chrome
+
+| Prop               | Type      | Default | Description                             |
+| ------------------ | --------- | ------- | --------------------------------------- |
+| `controlId`        | `string`  | auto    | Id for the control and related labels.  |
+| `corner`           | `string`  | —       | Secondary header text.                  |
+| `customProps`      | object    | —       | Extra props for internal parts.         |
+| `description`      | `string`  | —       | Helper text below the control.          |
+| `disabled`         | `boolean` | `false` | Disables interaction.                   |
+| `error`            | `boolean` | `false` | Invalid styling.                        |
+| `errorMessage`     | `string`  | —       | Error message below the control.        |
+| `hideErrorMessage` | `boolean` | `false` | Hides the error message row.            |
+| `label`            | `string`  | —       | Primary label above the control.        |
+| `readonly`         | `boolean` | `false` | Read-only (no pointer interaction).     |
+| `required`         | `boolean` | `false` | Shows a required asterisk on the label. |
+
+## Slots
+
+| Slot            | Description                              |
+| --------------- | ---------------------------------------- |
+| `#label`        | Primary label content.                   |
+| `#corner`       | Secondary header text at the inline end. |
+| `#description`  | Helper text below the control.           |
+| `#errorMessage` | Error message below the control.         |
+| `#thumb`        | Custom thumb content (replaces knob).    |
+
+## Events
+
+| Event               | Payload                      | Description                     |
+| ------------------- | ---------------------------- | ------------------------------- |
+| `change`            | `number \| [number, number]` | Emitted when the value changes. |
+| `update:modelValue` | `number \| [number, number]` | Emitted for `v-model` updates.  |
+
+## Related components
+
+BaseField, OtpField, NumberField, Label