@bridge-ui/vue 0.0.7 → 0.0.8

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,151 @@
+# BridgeUIProvider
+
+Root provider for theme, locale, direction, breakpoints, icon/i18n 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 },
+  }),
+);
+```
+
+### 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`, `formDefaults` |
+
+App content is passed via the **default slot** (see Usage above).
+
+**useBridgeUI():** `global`, `components`, `setGlobal`, `setComponents`, `setLocale`, `setTheme`, `setDirection`
+
+## Related components
+
+All components

package/docs/components/Button.md

@@ -0,0 +1,93 @@
+# Button
+
+Primary action control. Renders as `button`, `a`, or `span` via the `as` prop.
+
+## Import
+
+```ts
+import { Button } from "@bridge-ui/vue/Components/Button";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Button color="primary">Click me</Button>
+
+<Button variant="outline" :start-icon="Plus">
+  With icon
+</Button>
+
+<Button as="a" href="https://example.com">
+  External link
+</Button>
+```
+
+### Density
+
+```vue
+<Button density="mini" :icon="Settings" aria-label="Settings" />
+```
+
+### States
+
+```vue
+<Button loading>Loading</Button>
+<Button disabled>Disabled</Button>
+```
+
+### Slots
+
+```vue
+<Button>
+  <template #start>
+    <span class="text-xs opacity-80">◀</span>
+  </template>
+
+  With slots
+
+  <template #end>
+    <span class="text-xs opacity-80">▶</span>
+  </template>
+</Button>
+```
+
+### customProps
+
+```vue
+<Button
+  :icon="Plus"
+  :custom-props="{
+    startIcon: { 'aria-hidden': true },
+    root: { id: 'add-btn', type: 'button' },
+  }"
+>
+  Add item
+</Button>
+```
+
+## Props
+
+| Prop          | Type                        | Default   | Description                                                                                                                         |
+| ------------- | --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `as`          | `"a" \| "span" \| "button"` | "button"  | The element to render as.                                                                                                           |
+| `classes`     | `ButtonClasses`             | —         | The classes to apply to the button.                                                                                                 |
+| `color`       | `ButtonColor`               | "primary" | The color to apply to the button.                                                                                                   |
+| `customProps` | `ButtonCustomProps`         | —         | Extra props for internal parts (`startIcon`, `endIcon`, slot wrappers, etc.). Root HTML attributes stay on the component top level. |
+| `density`     | `ButtonDensity`             | "default" | The density of the button.                                                                                                          |
+| `disabled`    | `boolean`                   | `false`   | Whether the button is disabled.                                                                                                     |
+| `endIcon`     | `LucideIcon`                | —         | Icon at the **inline end** (physical right in `ltr`, physical left in `rtl`).                                                       |
+| `full`        | `boolean`                   | `false`   | Whether the button is full width.                                                                                                   |
+| `href`        | `string`                    | —         | The href to apply to the button.                                                                                                    |
+| `icon`        | `LucideIcon`                | —         | Icon for mini density (replaces label and start/end icons).                                                                         |
+| `loading`     | `boolean`                   | `false`   | Whether the button is loading.                                                                                                      |
+| `rounded`     | `ButtonRounded`             | "md"      | The roundedness of the button.                                                                                                      |
+| `size`        | `ButtonSize`                | "md"      | The size of the button.                                                                                                             |
+| `startIcon`   | `LucideIcon`                | —         | Icon at the **inline start** (physical left in `ltr`, physical right in `rtl`).                                                     |
+| `text`        | `string`                    | —         | Label text when the default slot is not used.                                                                                       |
+| `variant`     | `ButtonVariant`             | "solid"   | The variant of the button.                                                                                                          |
+
+## Related components
+
+Link, Icon