@bridge-ui/vue 0.0.7 → 0.0.9

package/docs/components/FieldOverlay.md

@@ -0,0 +1,91 @@
+# FieldOverlay
+
+Switches between `Menu`, `Modal`, and `Drawer` shells for field pickers and listboxes.
+Dialog shells (`modal` / `drawer`) always center the picker and size the drawer
+panel to its content (up to `90dvh`) so dual-month and dual-time pickers are not
+clipped.
+
+## Import
+
+```ts
+import { FieldOverlay } from "@bridge-ui/vue/Components/FieldOverlay";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<FieldOverlay v-model="open" overlay="menu">
+  <PickerContent />
+</FieldOverlay>
+```
+
+### Overlay modes
+
+`overlay` accepts `menu` | `modal` | `drawer` | `auto`. Default is `auto` (`menu` on desktop, bottom `drawer` on mobile).
+
+```vue
+<FieldOverlay v-model="open" overlay="auto">
+  <PickerContent />
+</FieldOverlay>
+
+<FieldOverlay v-model="open" overlay="drawer">
+  <PickerContent />
+</FieldOverlay>
+```
+
+### customProps
+
+Forward props to the active shell via `customProps.menu`, `customProps.modal`, or `customProps.drawer`. Menu-only options such as `anchorEl`, `placement`, `disableAutoFocus`, and `rounded` go through `customProps.menu`.
+
+```vue
+<FieldOverlay
+  v-model="open"
+  overlay="menu"
+  :custom-props="{
+    menu: {
+      anchorEl,
+      rounded: 'lg',
+      placement: 'bottom-start',
+    },
+  }"
+>
+  <PickerContent />
+</FieldOverlay>
+
+<FieldOverlay
+  v-model="open"
+  overlay="modal"
+  :custom-props="{
+    modal: { size: 'sm', transition: 'none' },
+  }"
+>
+  <PickerContent />
+</FieldOverlay>
+```
+
+## Props
+
+| Prop          | Type                      | Default  | Description                                                |
+| ------------- | ------------------------- | -------- | ---------------------------------------------------------- |
+| `customProps` | `FieldOverlayCustomProps` | —        | Extra props for nested shells (`menu`, `modal`, `drawer`). |
+| `overlay`     | `FieldOverlayMode`        | `"auto"` | Overlay shell: `menu`, `modal`, `drawer`, or `auto`.       |
+
+### v-model
+
+| Prop / Event        | Type                       | Default | Description                                                                  |
+| ------------------- | -------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `modelValue`        | `boolean`                  | `false` | Whether the overlay is open. 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 overlay. |
+| `v-on:show-change` | `(show: boolean)` | Emitted when open state should change.       |
+
+## Related components
+
+Menu, Modal, Drawer, Select, Autocomplete, DateField, TimeField, DateTimeField, DateRangeField, TimeRangeField, DateTimeRangeField, Listbox

package/docs/components/FormControl.md

@@ -0,0 +1,66 @@
+# FormControl
+
+> Building block for toggle-row chrome. Prefer `Checkbox`, `Radio`, and `Switch` in apps; FormControl remains exported for advanced composition. Not a registry key — theme chrome via `tokens.formControl` on the public parent (e.g. `components.Checkbox.tokens.formControl`).
+
+Low-level form control chrome (labels, description, error) for Checkbox, Radio, and Switch.
+
+Control tokens stay on the parent (`tokens.color`, `tokens.invalidated`, …).
+
+## Import
+
+```ts
+import { FormControl } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<FormControl
+  end-label="Email notifications"
+  description="Receive product updates."
+>
+  <Checkbox :default-checked="true" />
+</FormControl>
+```
+
+### customProps
+
+```vue
+<FormControl
+  end-label="Email notifications"
+  description="Receive product updates."
+  :custom-props="{
+    root: { id: 'notify-control' },
+    endLabel: { id: 'notify-label' },
+    description: { id: 'notify-desc', 'aria-live': 'polite' },
+  }"
+>
+  <Checkbox :default-checked="true" />
+</FormControl>
+```
+
+## Props
+
+| Prop               | Type                     | Default | Description                                                                                                                          |
+| ------------------ | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `classes`          | `FormControlClasses`     | —       | Classes for labels, description, error, and layout chrome.                                                                           |
+| `controlId`        | `string`                 | —       | Associates labels and helper text with a form control. When omitted, an id is generated automatically.                               |
+| `customProps`      | `FormControlCustomProps` | —       | Extra props for internal parts (`row`, `endLabel`, `description`, …).                                                                |
+| `description`      | `string`                 | —       | Helper text below the control row (hidden when invalid).                                                                             |
+| `disabled`         | `boolean`                | `false` | Whether the control is disabled.                                                                                                     |
+| `endLabel`         | `string`                 | —       | Inline-end label after the control (right in LTR, left in RTL).                                                                      |
+| `error`            | `boolean`                | `false` | When `true`, applies invalid styling on labels and hides description.                                                                |
+| `errorMessage`     | `string`                 | —       | Error message below the control row.                                                                                                 |
+| `field`            | `UseFormControlReturn`   | —       | Pre-composed form control API from a parent composable. Used by `<FormControl :field="…" />`; not set on Checkbox, Radio, or Switch. |
+| `hideErrorMessage` | `boolean`                | `false` | When `true`, does not reserve space below the row for error messages.                                                                |
+| `readonly`         | `boolean`                | `false` | Whether the control is read-only.                                                                                                    |
+| `required`         | `boolean`                | `false` | Sets the native `required` attribute on the control and shows a required asterisk on labels.                                         |
+| `size`             | `LabelSize`              | "md"    | Typography scale for labels, description, and error text (aligned with `FormField` / `Label`).                                       |
+| `slots`            | `FormControlSlots`       | —       | Chrome slots (`startLabel`, `endLabel`, `description`, `errorMessage`, …) and the control.                                           |
+| `startLabel`       | `string`                 | —       | Inline-start label before the control (left in LTR, right in RTL).                                                                   |
+
+## Related components
+
+Checkbox, Radio, Switch, Label

package/docs/components/FormField.md

@@ -0,0 +1,71 @@
+# FormField
+
+> Building block for field chrome. Prefer public fields (`TextField`, `Select`, …) in apps; FormField remains exported for advanced composition. Not a `BridgeUIComponentsConfig` key — theme via the public parent (`components.TextField`, `components.Select`, …).
+
+Form field chrome (label, adornments, error) used by TextField, Select, and other inputs.
+
+## Import
+
+```ts
+import { FormField } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<FormField label="Email" description="We never share your email.">
+  <input type="email" class="w-full rounded border px-3 py-2" />
+</FormField>
+```
+
+### customProps
+
+```vue
+<FormField
+  label="Email"
+  description="We never share your email."
+  :custom-props="{
+    root: { id: 'email-field' },
+    description: { id: 'email-desc' },
+    label: { id: 'email-label', for: 'email-input' },
+    input: { id: 'email-input', autocomplete: 'email', name: 'email' },
+  }"
+>
+  <input type="email" class="w-full rounded border px-3 py-2" />
+</FormField>
+```
+
+## Props
+
+| Prop               | Type                   | Default     | Description                                                                                                                                             |
+| ------------------ | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `classes`          | `FormFieldClasses`     | —           | Classes for the field chrome and the control (includes label, container, adornments).                                                                   |
+| `color`            | `FormFieldColor`       | "primary"   | The color to apply to the field control.                                                                                                                |
+| `controlId`        | `string`               | —           | Associates labels and helper text with a form control. When omitted, an id is generated automatically.                                                  |
+| `corner`           | `string`               | —           | Secondary label text at the inline end of the header row.                                                                                               |
+| `customProps`      | `FormFieldCustomProps` | —           | Extra props for internal parts (`header`, `label`, `input`, `container`, …).                                                                            |
+| `description`      | `string`               | —           | Helper text below the control (hidden when the field is invalid).                                                                                       |
+| `disabled`         | `boolean`              | `false`     | Whether the control is disabled.                                                                                                                        |
+| `end`              | `string`               | —           | Inline-end text inside the field (suffix), e.g. `@mail.com`.                                                                                            |
+| `endIcon`          | `LucideIcon`           | —           | Icon at the **inline end** (physical right in `ltr`, physical left in `rtl`).                                                                           |
+| `error`            | `boolean`              | `false`     | When `true`, applies invalid styling on the label and hides description.                                                                                |
+| `errorIcon`        | `LucideIcon`           | CircleAlert | Icon used when `showErrorIcon` is enabled and the field is invalid.                                                                                     |
+| `errorMessage`     | `string`               | —           | Error message below the control. Shown only when set (or via `#errorMessage` slot).                                                                     |
+| `field`            | `UseFormFieldReturn`   | —           | Pre-composed field API from a parent composable (e.g. `useTextField`). Used by `<FormField :field="…" />`; not set on field wrappers such as TextField. |
+| `hideErrorMessage` | `boolean`              | `false`     | When `true`, does not reserve space below the control for error messages.                                                                               |
+| `label`            | `string`               | —           | The primary label text above the control.                                                                                                               |
+| `readonly`         | `boolean`              | `false`     | Whether the control is read-only.                                                                                                                       |
+| `required`         | `boolean`              | `false`     | Shows a red asterisk on the label.                                                                                                                      |
+| `rounded`          | `FormFieldRounded`     | "md"        | The roundedness of the field control.                                                                                                                   |
+| `showErrorIcon`    | `boolean`              | `true`      | When `true` and the field is invalid, shows an error icon at the inline end when no `endIcon` or `end` slot is present.                                 |
+| `size`             | `FormFieldSize`        | "md"        | Typography scale for label, corner, description, and error message, and control sizing (input, container, icons).                                       |
+| `slots`            | `FormFieldSlots`       | —           | Chrome slots (`label`, `description`, `errorMessage`, …) via `#slot` or prop; inline adornments use `#start` / `#end`.                                  |
+| `start`            | `string`               | —           | Inline-start text inside the field (prefix), e.g. `https://`.                                                                                           |
+| `startIcon`        | `LucideIcon`           | —           | Icon at the **inline start** (physical left in `ltr`, physical right in `rtl`).                                                                         |
+| `variant`          | `FormFieldVariant`     | "outline"   | The visual variant of the field shell and control.                                                                                                      |
+
+## Related components
+
+TextField, Select, NumberField, Textarea, PasswordField

package/docs/components/I18n.md

@@ -0,0 +1,125 @@
+# i18n
+
+Bridge chrome strings (aria-labels, empty/loading copy) resolve through an optional i18n adapter on `BridgeUIProvider` / `createBridgeUI` (`global.i18n`). Without an adapter, the English source string is returned as-is.
+
+Lookup is **gettext-style**: the source English text is the key. Multi-locale
+adapters can keep the active locale internally via optional `setLocale`.
+
+```ts
+const resolveMessage = useResolveMessage();
+
+resolveMessage("Hide password");
+```
+
+`useResolveMessage` reads the active adapter from context. **Interpolation and
+pluralization are the adapter’s job** (vue-i18n, i18next, or a custom `t`).
+Bridge `setLocale` updates `global.locale` and calls optional `adapter.setLocale`
+— persistence (localStorage, backend) stays in the app.
+
+Implement `I18nAdapter` as a plain object — Bridge only defines the interface.
+
+## Import
+
+```ts
+import { useResolveMessage, type I18nAdapter } from "@bridge-ui/vue";
+```
+
+## Examples
+
+### Resolve in a component
+
+```vue
+<script setup lang="ts">
+import { useResolveMessage } from "@bridge-ui/vue";
+
+const resolveMessage = useResolveMessage();
+</script>
+
+<template>
+  <button type="button" :aria-label="resolveMessage('Clear selection')">
+    Clear
+  </button>
+</template>
+```
+
+### Dictionary adapter
+
+Locale-keyed source→string map (no replace/plural). Optional `setLocale`
+updates the active locale used by `t`.
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { createDictionaryI18nAdapter } from "@examples/i18n-dictionary";
+
+const i18n = createDictionaryI18nAdapter();
+
+const bridge = createBridgeUI({
+  global: { i18n, locale: "pt-BR" },
+});
+```
+
+### Custom adapter
+
+```ts
+import { get } from "es-toolkit/compat";
+import type { I18nAdapter } from "@bridge-ui/vue";
+
+const messages: Record<string, Record<string, string>> = {
+  "pt-BR": {
+    Close: "Fechar",
+    "Hide password": "Ocultar senha",
+    "Clear selection": "Limpar seleção",
+  },
+};
+
+let locale = "en-US";
+
+const i18n: I18nAdapter = {
+  setLocale(next) {
+    locale = next;
+  },
+  t(message) {
+    return get(messages, [locale, message], message);
+  },
+};
+```
+
+### vue-i18n (replace & plural)
+
+```ts
+import { createI18n } from "vue-i18n";
+import { createVueI18nAdapter } from "@examples/i18n-vue-i18n";
+
+const vueI18n = createI18n({ legacy: false, locale: "en-US", messages: {} });
+const i18n = createVueI18nAdapter(vueI18n.global);
+
+const resolveMessage = useResolveMessage();
+resolveMessage("{count} item", { count: 3 });
+// → vue-i18n handles interpolation / plural rules
+
+setLocale("pt-BR"); // Bridge locale + i18n.locale via adapter.setLocale
+```
+
+Other ready examples:
+
+| File                 | Library              | Replace / plural |
+| -------------------- | -------------------- | ---------------- |
+| `i18n-dictionary.ts` | In-memory dictionary | No (static map)  |
+| `i18n-vue-i18n.ts`   | vue-i18n             | Yes (via lib)    |
+
+## Chrome strings
+
+| Source (key)      |
+| ----------------- |
+| `Close`           |
+| `Loading...`      |
+| `No options`      |
+| `Show password`   |
+| `Hide password`   |
+| `Clear selection` |
+| `Increment value` |
+| `Decrement value` |
+
+## Related components
+
+BridgeUIProvider, PasswordField, NumberField, Select, Listbox, Snackbar

package/docs/components/Icon.md

@@ -0,0 +1,88 @@
+# Icon
+
+Renders an icon from a semantic name (via the icon adapter) or a concrete icon component, with design-system sizing.
+
+Semantic names require an icon adapter on `BridgeUIProvider` / `createBridgeUI` (`global.icons`). Bridge only defines the `IconAdapter` interface — copy an example from `packages/vue/docs/examples/`.
+
+## Import
+
+```ts
+import { Icon } from "@bridge-ui/vue/Components/Icon";
+```
+
+## Examples
+
+### Icon component
+
+```ts
+import { Info } from "@lucide/vue";
+```
+
+```vue
+<Icon size="md" :icon="Info" />
+```
+
+### Semantic name + adapter
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { createLucideIconAdapter } from "@examples/icon-lucide";
+
+const icons = createLucideIconAdapter();
+
+app.use(
+  createBridgeUI({
+    global: { icons },
+  }),
+);
+```
+
+```vue
+<Icon size="md" icon="info" />
+```
+
+Other ready examples (same `create*IconAdapter()` shape):
+
+| File                  | Library                     |
+| --------------------- | --------------------------- |
+| `icon-lucide.ts`      | Lucide                      |
+| `icon-heroicons.ts`   | Heroicons (24 outline)      |
+| `icon-tabler.ts`      | Tabler Icons                |
+| `icon-phosphor.ts`    | Phosphor Icons              |
+| `icon-fontawesome.ts` | Font Awesome 6 (free solid) |
+
+### Font Awesome definitions
+
+With the Font Awesome adapter, pass definitions directly — `normalize` wraps them:
+
+```ts
+import { createBridgeUI } from "@bridge-ui/vue";
+import { faCoffee } from "@fortawesome/free-solid-svg-icons";
+import { createFontAwesomeIconAdapter } from "@examples/icon-fontawesome";
+
+const icons = createFontAwesomeIconAdapter();
+
+app.use(
+  createBridgeUI({
+    global: { icons },
+  }),
+);
+```
+
+```vue
+<Icon :icon="faCoffee" />
+<Icon icon="info" />
+```
+
+The example also exports `wrapFaIcon` if you need a component outside `<Icon />`.
+
+## Props
+
+| Prop   | Type         | Default | Description                                                                  |
+| ------ | ------------ | ------- | ---------------------------------------------------------------------------- |
+| `icon` | `IconSource` | —       | Semantic name, icon component, or adapter-normalized native value (e.g. FA). |
+| `size` | `IconSize`   | "md"    | The size of the icon.                                                        |
+
+## Related components
+
+Button, Alert, TextField, BridgeUIProvider

package/docs/components/Label.md

@@ -0,0 +1,31 @@
+# Label
+
+Accessible label element with required and error styling.
+
+## Import
+
+```ts
+import { Label } from "@bridge-ui/vue/Components/Label";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Label required for="email">Email</Label>
+```
+
+## Props
+
+| Prop       | Type           | Default | Description                                         |
+| ---------- | -------------- | ------- | --------------------------------------------------- |
+| `classes`  | `LabelClasses` | —       | The classes to apply to the label.                  |
+| `error`    | `boolean`      | `false` | Applies error label colors.                         |
+| `for`      | `string`       | —       | Associates the label with a form control.           |
+| `required` | `boolean`      | `false` | Shows a red required asterisk after the label text. |
+| `size`     | `LabelSize`    | "md"    | Typography scale aligned with TextField sizes.      |
+
+## Related components
+
+FormField, FormControl

package/docs/components/Link.md

@@ -0,0 +1,71 @@
+# Link
+
+Styled anchor for in-app and external navigation.
+
+## Import
+
+```ts
+import { Link } from "@bridge-ui/vue/Components/Link";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<Link href="/dashboard">Dashboard</Link>
+
+<Link color="primary" underline="hover" href="https://example.com">
+  External link
+</Link>
+
+<Link href="#" :left-icon="Info">
+  With icon
+</Link>
+```
+
+### States
+
+```vue
+<Link disabled href="/button">
+  Disabled
+</Link>
+
+<Link external href="https://example.com">
+  External
+</Link>
+```
+
+### customProps
+
+```vue
+<Link
+  href="#"
+  :left-icon="ExternalLink"
+  :custom-props="{
+    leftIcon: { 'aria-hidden': true },
+    root: { id: 'docs-link', target: '_blank', rel: 'noopener noreferrer' },
+  }"
+>
+  Open documentation
+</Link>
+```
+
+## Props
+
+| Prop          | Type              | Default   | Description                                                                                                           |
+| ------------- | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `classes`     | `LinkClasses`     | —         | The classes to apply to the link.                                                                                     |
+| `color`       | `LinkColor`       | "primary" | The color to apply to the link.                                                                                       |
+| `customProps` | `LinkCustomProps` | —         | Extra props for internal parts (`leftIcon`, `rightIcon`, etc.). Root HTML attributes stay on the component top level. |
+| `disabled`    | `boolean`         | `false`   | Whether the link is disabled.                                                                                         |
+| `external`    | `boolean`         | `false`   | Whether the link opens in a new tab.                                                                                  |
+| `href`        | `string`          | —         | The URL the link points to.                                                                                           |
+| `leftIcon`    | `LucideIcon`      | —         | The icon to display before the link text.                                                                             |
+| `rightIcon`   | `LucideIcon`      | —         | The icon to display after the link text.                                                                              |
+| `size`        | `LinkSize`        | "md"      | The size of the link.                                                                                                 |
+| `underline`   | `LinkUnderline`   | "hover"   | The underline behavior of the link.                                                                                   |
+
+## Related components
+
+Button