@bridge-ui/vue 0.0.6 → 0.0.8

package/docs/components/Select.md

@@ -0,0 +1,181 @@
+# 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>
+```
+
+### 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.                                                         |
+| `placeholder`       | `string`              | —             | Placeholder shown when no value is selected.                                                            |
+| `searchable`        | `boolean`             | `false`       | Whether options can be filtered via the trigger input.                                                  |
+
+### 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: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, 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

package/docs/components/Snackbar.md

@@ -0,0 +1,99 @@
+# Snackbar
+
+Toast notification portaled to the viewport. Sets `role="status"` and `aria-live="polite"` by default.
+
+## Import
+
+```ts
+import { Snackbar } from "@bridge-ui/vue/Components/Snackbar";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Button v-on:click="open = true">Show snackbar</Button>
+
+<Snackbar
+  title="Saved"
+  v-model="open"
+  description="Your changes were saved successfully."
+/>
+```
+
+### Duration and progressbar
+
+```vue
+<Snackbar progressbar v-model="open" :duration="3000" title="Auto dismiss" />
+```
+
+### Slots
+
+```vue
+<Snackbar v-model="open">
+  <template #icon>
+    <Icon size="md" :icon="Info" />
+  </template>
+
+  <template #actions>
+    <Button size="sm" variant="flat" v-on:click="open = false">
+      Undo
+    </Button>
+  </template>
+
+  Custom children below the description.
+</Snackbar>
+```
+
+### customProps
+
+```vue
+<Snackbar
+  v-model="open"
+  title="customProps"
+  :custom-props="{
+    root: { id: 'snackbar-root' },
+    title: { id: 'snackbar-title' },
+  }"
+/>
+```
+
+## Props
+
+| Prop           | Type                      | Default         | Description                                                                    |
+| -------------- | ------------------------- | --------------- | ------------------------------------------------------------------------------ |
+| `classes`      | `SnackbarClasses`         | —               | The classes to apply to the snackbar.                                          |
+| `closeButton`  | `boolean`                 | `true`          | Whether to show the close button.                                              |
+| `color`        | `SnackbarColor`           | "primary"       | Tint color for the default icon.                                               |
+| `customProps`  | `SnackbarCustomProps`     | —               | Extra props for internal parts (`icon`, `title`, `description`, etc.).         |
+| `description`  | `string`                  | —               | Body text below the title.                                                     |
+| `duration`     | `number \| false`         | 5000            | Auto-dismiss delay in ms. `false` disables the timer.                          |
+| `icon`         | `LucideIcon \| null`      | —               | The icon to display. Use `null` to hide the icon.                              |
+| `img`          | `string`                  | —               | Avatar image URL (shown instead of icon when set).                             |
+| `onShowChange` | `(show: boolean) => void` | —               | Called when `v-model` visibility should change (controlled state).             |
+| `padding`      | `SnackbarPadding`         | "medium"        | Padding for the content area.                                                  |
+| `position`     | `SnackbarPosition`        | "bottom-center" | Viewport anchor when portaled (standalone). Ignored when `teleportTo={false}`. |
+| `progressbar`  | `boolean`                 | `true`          | Whether to show the countdown progress bar when `duration` is set.             |
+| `rounded`      | `SnackbarRounded`         | "lg"            | The roundedness of the snackbar panel.                                         |
+| `stackId`      | `string`                  | —               | Pre-assigned stack id (BridgeSnackbarHost).                                    |
+| `teleportTo`   | `string \| false`         | "body"          | Portal target. `false` renders inline without layer stack.                     |
+| `title`        | `string`                  | —               | Headline text.                                                                 |
+| `transition`   | `SnackbarTransition`      | "slide"         | Enter/leave animation preset.                                                  |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | `false` | Whether the snackbar 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 snackbar requests to close. |
+
+## Related components
+
+useSnackbarAction, Alert, Button

package/docs/components/Spinner.md

@@ -0,0 +1,61 @@
+# Spinner
+
+Circular progress indicator for determinate and indeterminate loading states.
+
+## Import
+
+```ts
+import { Spinner } from "@bridge-ui/vue/Components/Spinner";
+```
+
+## Examples
+
+### Indeterminate
+
+```vue
+<Spinner aria-label="Loading…" />
+```
+
+### Determinate
+
+```vue
+<Spinner :value="40" variant="determinate" aria-label="Export data" />
+```
+
+### With track
+
+```vue
+<Spinner enable-track aria-label="Loading…" />
+```
+
+### Disable shrink
+
+```vue
+<Spinner disable-shrink aria-label="Loading…" />
+```
+
+### Color and size
+
+```vue
+<Spinner size="lg" color="success" aria-label="Saving…" />
+```
+
+## Props
+
+| Prop            | Type                 | Default           | Description                                       |
+| --------------- | -------------------- | ----------------- | ------------------------------------------------- |
+| `classes`       | `SpinnerClasses`     | —                 | Classes for `root`, `svg`, `circle`, and `track`. |
+| `color`         | `SpinnerColor`       | `"primary"`       | Semantic color of the circle (and track).         |
+| `customProps`   | `SpinnerCustomProps` | —                 | Extra props for internal parts.                   |
+| `disableShrink` | `boolean`            | `false`           | Disables indeterminate circle shrink animation.   |
+| `enableTrack`   | `boolean`            | `false`           | Shows a subtle track circle behind the progress.  |
+| `size`          | `SpinnerSize`        | `"md"`            | Width/height of the spinner.                      |
+| `thickness`     | `number`             | `3.6`             | Stroke thickness of the circle.                   |
+| `value`         | `number`             | —                 | Progress 0–100 (`determinate` variant).           |
+| `variant`       | `SpinnerVariant`     | `"indeterminate"` | Visual mode of the indicator.                     |
+
+Pass `aria-label` or `aria-labelledby` for an accessible name.
+
+## Related components
+
+Progress, Skeleton

package/docs/components/Switch.md

@@ -0,0 +1,72 @@
+# Switch
+
+Toggle switch. Extends FormControl props.
+
+## Import
+
+```ts
+import { Switch } from "@bridge-ui/vue/Components/Switch";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Switch end-label="Dark mode" description="Use dark theme across the app." />
+
+<Switch v-model="enabled" end-label="Enable notifications" />
+```
+
+### Required and error
+
+```vue
+<Switch required end-label="Required field" />
+
+<Switch
+  error
+  end-label="Invalid option"
+  error-message="You must enable this setting."
+/>
+```
+
+### customProps
+
+```vue
+<Switch
+  end-label="Airplane mode"
+  :custom-props="{
+    input: { name: 'airplane' },
+    control: { 'data-testid': 'airplane-switch' },
+  }"
+/>
+```
+
+## Props
+
+### Switch-specific
+
+| Prop          | Type                | Default   | Description                                                                                |
+| ------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `checked`     | `boolean`           | —         | Whether the switch is on.                                                                  |
+| `classes`     | `SwitchClasses`     | —         | Classes for the form control chrome and the switch control.                                |
+| `color`       | `SwitchColor`       | "primary" | The color to apply to the switch.                                                          |
+| `customProps` | `SwitchCustomProps` | —         | Extra props for internal parts.                                                            |
+| `rounded`     | `SwitchRounded`     | "full"    | The roundedness of the switch track.                                                       |
+| `size`        | `SwitchSize`        | "md"      | Size of the control and of form control labels (`2xs` … `2xl`, same scale as `FormField`). |
+| `slots`       | `SwitchSlots`       | —         | 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
+
+Checkbox, FormControl