@bridge-ui/vue 0.0.7 → 0.0.9

package/docs/components/Autocomplete.md

@@ -0,0 +1,212 @@
+# Autocomplete
+
+Combobox with single/multiple value, search, async data, and optional free-solo input.
+
+## Import
+
+```ts
+import { Autocomplete } from "@bridge-ui/vue/Components/Autocomplete";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Autocomplete
+  label="Country"
+  :options="countries"
+  placeholder="Choose a country"
+/>
+
+<Autocomplete
+  multiple
+  searchable
+  label="Frameworks"
+  v-model="selected"
+  :options="frameworks"
+/>
+
+<Autocomplete
+  error
+  label="Country"
+  error-message="Please select a valid country."
+/>
+```
+
+### Searchable
+
+```vue
+<Autocomplete
+  searchable
+  label="Country"
+  :options="countries"
+  placeholder="Type to filter..."
+/>
+```
+
+### Free solo
+
+Enabled by default. Type a value that is not in `options` and commit with Enter, Tab, or by closing the menu. Set `:free-solo="false"` to require picking from the list.
+
+```vue
+<Autocomplete label="Tag" :options="tags" placeholder="Pick or type a tag" />
+```
+
+### Async data
+
+```vue
+<Autocomplete
+  label="City (async)"
+  placeholder="Type to search cities..."
+  :async-data="{
+    search: asyncSearch,
+    resolve: asyncResolveSelected,
+  }"
+/>
+```
+
+### Custom option slot
+
+```vue
+<Autocomplete
+  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>
+</Autocomplete>
+```
+
+### Grouped options
+
+`options` may mix standalone options and section groups (`{ title, options, sticky? }`). Search filters within sections and drops empty ones.
+
+```vue
+<Autocomplete
+  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 `AutocompleteOption` 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
+<Autocomplete label="Status" v-model="status">
+  <ListSection sticky title="Workflow" />
+  <ListItem value="open" primary="Open" />
+  <ListItem value="closed" primary="Closed" />
+</Autocomplete>
+```
+
+### Overlay
+
+```vue
+<Autocomplete overlay="auto" label="Country" :options="countries" />
+
+<Autocomplete 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
+<Autocomplete
+  label="Country"
+  :options="countries"
+  placeholder="Choose a country"
+  :custom-props="{
+    root: { id: 'country-field' },
+    input: { name: 'country', autocomplete: 'country' },
+  }"
+/>
+```
+
+## Props
+
+### Autocomplete-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.                                                                    |
+| `freeSolo`          | `boolean`             | `true`                                | Allows committing typed text that is not in `options` (Enter, Tab, or closing the menu).                |
+| `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`             | `true`                                | 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.Autocomplete` (`size`, `color`, `rounded`, `variant`, …). Dropdown option tokens are nested under `components.Autocomplete.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/Avatar.md

@@ -0,0 +1,60 @@
+# Avatar
+
+Displays a user image, initials fallback, or icon.
+
+## Import
+
+```ts
+import { Avatar } from "@bridge-ui/vue/Components/Avatar";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Avatar fallback="JD" />
+
+<Avatar :icon="User" color="primary" />
+
+<Avatar alt="Jane Doe" :src="avatarSrc" />
+```
+
+### Classes
+
+```vue
+<Avatar
+  fallback="JP"
+  :classes="{
+    root: 'ring-2 ring-info-500',
+    fallback: 'font-bold tracking-widest',
+  }"
+/>
+```
+
+### Fallback slot
+
+```vue
+<Avatar>
+  <template #fallback>
+    <span class="text-xs font-semibold">Slot</span>
+  </template>
+</Avatar>
+```
+
+## Props
+
+| Prop       | Type            | Default   | Description                                              |
+| ---------- | --------------- | --------- | -------------------------------------------------------- |
+| `alt`      | `string`        | —         | The alt text for the avatar image.                       |
+| `classes`  | `AvatarClasses` | —         | The classes to apply to the avatar.                      |
+| `color`    | `AvatarColor`   | "primary" | The color to apply to the avatar fallback.               |
+| `fallback` | `string`        | —         | The fallback text to display when no image is available. |
+| `icon`     | `LucideIcon`    | —         | The icon to display as fallback.                         |
+| `rounded`  | `AvatarRounded` | "full"    | The roundedness of the avatar.                           |
+| `size`     | `AvatarSize`    | "md"      | The size of the avatar.                                  |
+| `src`      | `string`        | —         | The source URL for the avatar image.                     |
+
+## Related components
+
+Badge

package/docs/components/Badge.md

@@ -0,0 +1,47 @@
+# Badge
+
+Small label for counts, status, or tags.
+
+## Import
+
+```ts
+import { Badge } from "@bridge-ui/vue/Components/Badge";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Badge>New</Badge>
+
+<Badge density="mini">3</Badge>
+
+<Badge variant="flat" color="success">
+  Active
+</Badge>
+```
+
+### Custom classes
+
+```vue
+<Badge color="primary" class="tracking-widest uppercase shadow-md">
+  Styled
+</Badge>
+```
+
+## Props
+
+| Prop      | Type           | Default   | Description                        |
+| --------- | -------------- | --------- | ---------------------------------- |
+| `classes` | `BadgeClasses` | —         | The classes to apply to the badge. |
+| `color`   | `BadgeColor`   | "primary" | The color to apply to the badge.   |
+| `density` | `BadgeDensity` | "default" | The density of the badge.          |
+| `full`    | `boolean`      | `false`   | Whether the badge is full width.   |
+| `rounded` | `BadgeRounded` | "md"      | The roundedness of the badge.      |
+| `size`    | `BadgeSize`    | "sm"      | The size of the badge.             |
+| `variant` | `BadgeVariant` | "flat"    | The variant of the badge.          |
+
+## Related components
+
+Button

package/docs/components/BaseField.md

@@ -0,0 +1,126 @@
+# BaseField
+
+> Building block for composite field chrome. Prefer `OtpField` / `Slider` in apps; BaseField remains exported for advanced composition. Not a registry key — theme chrome via `tokens.baseField` on the public parent (e.g. `components.Slider.tokens.baseField`).
+
+Shared vertical field chrome (label, corner, start/end slots, description,
+error message) for OtpField, Slider, and similar controls.
+
+Control tokens stay on the parent (`tokens.size`, `tokens.invalidated`, …).
+
+## Import
+
+```ts
+import { BaseField, useBaseField } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Usage
+
+Compose with `useBaseField` and pass the returned API as `:field`:
+
+```vue
+<script setup lang="ts">
+import { BaseField, useBaseField } from "@bridge-ui/vue";
+
+const field = useBaseField(() => ({
+  label: "Verification code",
+  description: "Enter the code from your email.",
+}));
+</script>
+
+<template>
+  <BaseField :field="field">
+    <input type="text" aria-label="Code" />
+  </BaseField>
+</template>
+```
+
+### Label and corner
+
+```vue
+<BaseField
+  :field="
+    useBaseField(() => ({
+      label: 'Amount',
+      corner: 'Optional',
+    }))
+  "
+>
+  <input type="number" aria-label="Amount" />
+</BaseField>
+```
+
+### Adornment slots
+
+```vue
+<BaseField :field="useBaseField(() => ({ label: 'Code' }))">
+  <template #start>
+    <Lock aria-hidden="true" />
+  </template>
+
+  <input type="text" aria-label="Code" />
+
+  <template #end>
+    <button type="button">Resend</button>
+  </template>
+</BaseField>
+```
+
+### Error state
+
+```vue
+<BaseField
+  :field="
+    useBaseField(() => ({
+      error: true,
+      label: 'Email',
+      errorMessage: 'Invalid email address.',
+    }))
+  "
+>
+  <input type="email" aria-label="Email" />
+</BaseField>
+```
+
+### customProps
+
+```vue
+<BaseField
+  :field="
+    useBaseField(() => ({
+      label: 'Email',
+      description: 'We never share your email.',
+      customProps: {
+        group: { 'data-testid': 'email-group' },
+      },
+    }))
+  "
+>
+  <input type="email" aria-label="Email" />
+</BaseField>
+```
+
+## Props
+
+| Prop               | Type                   | Default | Description                                                                                  |
+| ------------------ | ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `classes`          | `BaseFieldClasses`     | —       | Classes for the field chrome and control group layout.                                       |
+| `controlId`        | `string`               | auto    | Id for the control group and related labels.                                                 |
+| `corner`           | `string`               | —       | Secondary header text at the inline end.                                                     |
+| `customProps`      | `BaseFieldCustomProps` | —       | Extra props for internal parts (`root`, `group`, `label`, …).                                |
+| `description`      | `string`               | —       | Helper text below the control group (hidden when invalid).                                   |
+| `disabled`         | `boolean`              | `false` | Disables the field control group.                                                            |
+| `error`            | `boolean`              | `false` | Invalid styling on the label and control group.                                              |
+| `errorMessage`     | `string`               | —       | Error message below the control group.                                                       |
+| `field`            | `UseBaseFieldReturn`   | —       | Pre-composed field chrome API from `useBaseField`. Used by `<BaseField :field="…" />`.       |
+| `hideErrorMessage` | `boolean`              | `false` | Hides the error message row and reserved space.                                              |
+| `label`            | `string`               | —       | Primary label above the control group.                                                       |
+| `readonly`         | `boolean`              | `false` | Read-only field control group.                                                               |
+| `required`         | `boolean`              | `false` | Shows a required asterisk on the label.                                                      |
+| `size`             | `BaseFieldSize`        | `"md"`  | Label typography and control group gap scale.                                                |
+| `slots`            | `BaseFieldSlots`       | —       | `#label`, `#corner`, `#description`, `#errorMessage`, `#start`, `#end`, and default control. |
+
+## Related components
+
+OtpField, Slider, Label

package/docs/components/BridgeUIProvider.md

@@ -0,0 +1,168 @@
+# BridgeUIProvider
+
+Root provider for theme, locale, direction, breakpoints, icon/i18n/date adapters, and component registry defaults.
+
+## Import
+
+```ts
+import { BridgeUIProvider, useBridgeUI } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<BridgeUIProvider
+  :global="{
+    theme: 'light',
+    locale: 'en-US',
+    breakpoints: {},
+    direction: 'ltr',
+    mobileBreakpoint: 'sm',
+  }"
+>
+  <App />
+</BridgeUIProvider>
+```
+
+### Icon adapter
+
+Provide `global.icons` when using semantic icon names (`"clear"`, `"check"`, …). Optional `normalize` converts library-native values (e.g. Font Awesome definitions) so `<Icon :icon="faCoffee" />` works. Ready samples in `packages/vue/docs/examples/` (Lucide, Heroicons, Tabler, Phosphor, Font Awesome).
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { createLucideIconAdapter } from "@examples/icon-lucide";
+
+const icons = createLucideIconAdapter();
+
+app.use(
+  createBridgeUI({
+    global: { icons },
+  }),
+);
+```
+
+### i18n adapter
+
+Provide `global.i18n` to translate Bridge chrome strings (`"Close"`, `"Hide password"`, …). Lookup is gettext-style (source English text is the key). Without an adapter, the source string is used. `setLocale` updates Bridge `locale` and calls optional `i18n.setLocale` (vue-i18n / i18next / dictionary). Persistence (localStorage, backend) stays in the app. Ready samples in `packages/vue/docs/examples/` (dictionary, vue-i18n). See [I18n](./I18n.md).
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { createDictionaryI18nAdapter } from "@examples/i18n-dictionary";
+
+const i18n = createDictionaryI18nAdapter();
+
+app.use(
+  createBridgeUI({
+    global: { i18n },
+  }),
+);
+```
+
+### Date adapter
+
+Provide `global.dates` to replace the native `Date` adapter used by calendars and pickers. Without one, Bridge uses `createNativeDateAdapter`. Ready samples in `packages/vue/docs/examples/` (Day.js, date-fns, Luxon, Moment).
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { createDayjsDateAdapter } from "@examples/date-dayjs";
+
+const dates = createDayjsDateAdapter();
+
+app.use(
+  createBridgeUI({
+    global: { dates },
+  }),
+);
+```
+
+### Form density defaults
+
+Set `global.formDefaults` to apply shared `size` / `rounded` to form controls (TextField, Select, Checkbox, Slider, OtpField, …). Does not affect Button, Progress, Modal, etc.
+
+Merge order: instance props → `components.{Name}.defaultProps` → `formDefaults` → library defaults.
+
+Radio and Switch receive `size` only — their `rounded` stays shape-driven (`full`) unless overridden per component.
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+
+app.use(
+  createBridgeUI({
+    global: {
+      formDefaults: { size: "lg", rounded: "md" },
+    },
+  }),
+);
+```
+
+### Nested chrome tokens
+
+Building blocks (`FormField`, `FormControl`, `BaseField`, `Listbox`) are not registry keys. Theme chrome under the public parent:
+
+```ts
+app.use(
+  createBridgeUI({
+    components: {
+      Slider: {
+        tokens: {
+          baseField: {
+            size: { md: { text: "text-base", group: "gap-3" } },
+          },
+        },
+      },
+      Checkbox: {
+        tokens: {
+          formControl: {
+            invalidated: {
+              errorMessage: "text-error-700 dark:text-error-300",
+            },
+          },
+        },
+      },
+      Select: {
+        tokens: {
+          listbox: {
+            size: {
+              md: {
+                option: "px-3 py-2 text-sm",
+                check: "size-4",
+                message: "text-xs",
+                primary: "font-medium",
+                secondary: "text-xs opacity-70",
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+);
+```
+
+### Runtime updates
+
+```ts
+const { setLocale, setTheme, setDirection, setGlobal } = useBridgeUI()!;
+
+setTheme("dark");
+setLocale("pt-BR"); // also calls global.i18n.setLocale when present
+setDirection("rtl");
+setGlobal({ mobileBreakpoint: "md" });
+```
+
+## Props
+
+| Prop         | Type                       | Default | Description                                                                                                 |
+| ------------ | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `components` | `BridgeUIComponentsConfig` | —       | Per-component defaults                                                                                      |
+| `global`     | `Partial<BridgeUIGlobal>`  | —       | `theme`, `locale`, `direction`, `mobileBreakpoint`, `breakpoints`, `icons`, `i18n`, `dates`, `formDefaults` |
+
+App content is passed via the **default slot** (see Usage above).
+
+**useBridgeUI():** `global`, `components`, `setGlobal`, `setComponents`, `setLocale`, `setTheme`, `setDirection`
+
+## Related components
+
+All components