bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/composables/useBbConfig.md

@@ -0,0 +1,80 @@
+---
+title: useBbConfig
+summary: Patch the library's runtime-editable configuration — today that is exactly one key, locale.
+type: composable
+---
+
+# useBbConfig
+
+## Summary
+
+`useBbConfig` exposes `setConfig`, which patches the library's **runtime-editable**
+configuration. The editable surface is deliberately tiny: `DynamicConfig`
+contains only `locale`. Everything else (label modes, size maps, variants, link
+component names, `toastPosition`, …) is fixed at build time through the Vite
+plugin (`bitbossUi({ ... })`) and cannot be changed at runtime.
+
+Use it for exactly one job: switching the locale of locale-aware components
+(built-in labels, close buttons, table/pagination strings) while the app runs.
+
+## Import
+
+```ts
+import { useBbConfig } from 'bitboss-ui';
+
+const { setConfig } = useBbConfig();
+```
+
+## API
+
+### `setConfig(patch)`
+
+```ts
+declare function setConfig(patch: Partial<DynamicConfig>): void;
+// DynamicConfig = { locale: 'it' | 'en' }
+```
+
+Merges the patch into the live config object. The change is global, immediate,
+and reactive — every mounted component that reads the key updates.
+
+## Usage example
+
+```vue
+<template>
+	<BbButton
+		prepend:icon="lucide:languages"
+		size="sm"
+		variant="ghost"
+		@click="toggleLocale"
+	>
+		{{ locale === 'it' ? 'English' : 'Italiano' }}
+	</BbButton>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, useBbConfig } from 'bitboss-ui';
+
+const { setConfig } = useBbConfig();
+const locale = ref<'it' | 'en'>('it');
+
+const toggleLocale = () => {
+	locale.value = locale.value === 'it' ? 'en' : 'it';
+	setConfig({ locale: locale.value });
+};
+</script>
+```
+
+## Anti-patterns
+
+- Don't try to patch plugin options (`defaultInputLabelMode`, `mobileMaxWidth`,
+  `dialogDefaultSizes`, variant registries, …) through `setConfig` — they are
+  not part of `DynamicConfig` and the types will reject them. Set them once in
+  `vite.config.ts`.
+- Don't call `setConfig` to scope a change to one page: the config is a global
+  singleton, not per-component state.
+
+## Related
+
+- [Installation and plugin setup](../guides/installation-and-plugin-setup.md) —
+  every plugin option, including the compile-time ones, with defaults.

package/dist/ai/composables/useBbFormContext.md

@@ -0,0 +1,110 @@
+---
+title: useBbFormContext
+summary: Read and drive a BbForm from anywhere by id — validity, dirtiness, values, errors, plus submit/reset/validate — with no template ref and no shared subtree.
+type: composable
+---
+
+# useBbFormContext
+
+## Summary
+
+`useBbFormContext` gives you a live handle on a `<BbForm>` addressed by its
+`id`: whether it is valid, dirty, touched, pending or submitting, its current
+`values` and `errors`, and the three things you can ask it to do — `submit()`,
+`reset()`, `validate()`.
+
+Reach for it when the chrome that reads or drives the form lives **outside** the
+`<form>` element: a dialog footer whose submit button sits below the content, a
+page toolbar, a "discard changes" affordance in a header, a route-leave guard
+that needs to know whether anything is dirty.
+
+For chrome **inside** the form, prefer the default slot's scope — it carries the
+same state without an id.
+
+This is `BbForm`'s **only** outside handle: the component intentionally has no
+`defineExpose`, so nothing reaches into the instance. Same id-context pattern as
+[`useBbTableContext`](./useBbTableContext.md) and `useBbDropdownContext`.
+
+## Import
+
+```ts
+import { useBbFormContext } from 'bitboss-ui/validated';
+```
+
+It ships from the `validated` entrypoint alongside the controls it belongs to,
+and needs the `vee-validate` peer dependency like the rest of that layer.
+
+## Usage
+
+Give the form an explicit `id`, then address it from anywhere:
+
+```vue
+<script setup lang="ts">
+import { BbButton, BbDialog } from 'bitboss-ui';
+import { BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui/validated';
+
+const invite = useBbFormContext('invite-teammate');
+</script>
+
+<template>
+	<BbDialog v-model="open" title="Invite teammate">
+		<BbForm id="invite-teammate" @submit="sendInvite">
+			<BbTextInput label="Email" rules="required|email" type="email" />
+		</BbForm>
+
+		<template #footer>
+			<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+			<BbButton
+				:loading="invite.submitting.value"
+				variant="primary"
+				@click="invite.submit()"
+			>
+				Invite
+			</BbButton>
+		</template>
+	</BbDialog>
+</template>
+```
+
+`submit()` routes through the same handler the form's own submit button would
+trigger, so validation gates the request in exactly one place and `@submit`
+stays the only place the work happens.
+
+## The handle
+
+| Field         | Type                                               | Meaning                                                      |
+| ------------- | -------------------------------------------------- | ------------------------------------------------------------ |
+| `isReady`     | `ComputedRef<boolean>`                             | A form with this id is mounted.                              |
+| `valid`       | `ComputedRef<boolean>`                             | Every field currently passes.                                |
+| `dirty`       | `ComputedRef<boolean>`                             | At least one field differs from its initial value.           |
+| `touched`     | `ComputedRef<boolean>`                             | At least one field has been interacted with.                 |
+| `pending`     | `ComputedRef<boolean>`                             | An async rule is in flight.                                  |
+| `submitting`  | `ComputedRef<boolean>`                             | A submit handler is running.                                 |
+| `submitCount` | `ComputedRef<number>`                              | Submission attempts so far.                                  |
+| `values`      | `ComputedRef<Record<string, unknown>>`             | Current values, keyed by field name (`vid` or from `label`). |
+| `errors`      | `ComputedRef<Record<string, string \| undefined>>` | Current messages, keyed by field name.                       |
+| `submit()`    | `() => void`                                       | Ask the form to submit (validation still gates it).          |
+| `reset()`     | `() => void`                                       | Reset every field to its initial value.                      |
+| `validate()`  | `() => Promise<boolean>`                           | Validate now; resolves to whether the form is valid.         |
+
+## Rules and gotchas
+
+- **The id must be explicit.** Auto-generated ids cannot be targeted, and a form
+  without an `id` simply has no outside handle — the right default for a
+  self-contained form.
+- **Callable before the form mounts.** Every field reads a stable baseline
+  (`false`, `0`, `{}`) and every action is a no-op until `isReady` flips true, so
+  a footer that renders ahead of its dialog's content is safe. Watch `isReady`
+  when you need to distinguish "not mounted" from "mounted and invalid".
+- **Read-only state, imperative actions.** The fields are computeds; you change
+  values through the controls' own `v-model`s, not through the handle.
+- **Client-side only.** The registry is module-level and deliberately not
+  populated during SSR (it would leak across requests).
+- **Ids should be unique per mounted form.** Two mounted forms sharing one id
+  both mirror into the same node, so the handle reports whichever wrote last.
+
+## See also
+
+- [Validated Forms](../guides/validated-forms.md) — the whole
+  `bitboss-ui/validated` layer: setup, rules, the added props, controls.
+- [`useBbTableContext`](./useBbTableContext.md) — the same pattern for `BbTable`.

package/dist/ai/composables/useBbTableContext.md

@@ -0,0 +1,167 @@
+---
+title: useBbTableContext
+summary: Drive and read a BbTable's state (selection, sort, highlight, pagination) from anywhere by id — no prop drilling, no template refs.
+type: composable
+---
+
+# useBbTableContext
+
+## Summary
+
+`useBbTableContext` gives you a live, two-way handle on a `BbTable`'s state —
+selection, select-all, unselected items, **sort**, **highlight**, and paging —
+addressed by the table's `id`. Any component (a toolbar, a details panel, a
+parent page, `BbPagination`) can read or drive that state without being in the
+table's subtree and without prop drilling.
+
+It works **alongside** the table's v-models, not instead of them: the table
+keeps its bound props in sync with the context in both directions, so you can
+use props, the context, or both at once.
+
+Use it when the thing that reads or changes table state lives **outside** the
+table — a bulk-action bar above the table, a detail drawer that highlights the
+active row, a "clear filters" button that resets sort, a pagination control
+rendered elsewhere.
+
+## Import
+
+```ts
+import { useBbTableContext } from 'bitboss-ui';
+```
+
+## API
+
+```ts
+declare function useBbTableContext(
+	id: MaybeRefOrGetter<string | undefined>,
+	initial?: BbTableContextInitial
+): BbTableContext;
+```
+
+- **`id`** — `string | Ref<string> | () => string`. Must match the `id` prop
+  you pass to `<BbTable id="…">`. This is the rendezvous key; a typo silently
+  produces an orphan handle that syncs with nothing (see Gotchas).
+- **`initial`** — optional partial state seed: an object with any of the
+  handle's writable fields (`selected`, `unselected`, `all`, `highlighted`,
+  `sort`, `page`, `perPage`, `total`, `totalPages`). Fields you
+  provide are injected into the table on mount (e.g. setting
+  `page`/`perPage`/`total` activates the table's `aria-rowcount` /
+  `aria-rowindex` accessibility exactly as the equivalent props would); fields
+  you omit are filled in by the table from its own props.
+
+### Returned handle
+
+The handle's type is exported as `BbTableContext`. Every field is a
+`WritableComputedRef` — read `.value`, assign `.value` to drive the table.
+
+| Field         | Type                                   | Mirrors (table)            | Empty baseline |
+| ------------- | -------------------------------------- | -------------------------- | -------------- |
+| `selected`    | `any` (array in multiple mode)         | `v-model`                  | `[]`           |
+| `unselected`  | `any[]`                                | `v-model:unselected-items` | `[]`           |
+| `all`         | `boolean`                              | `v-model:select-all`       | `false`        |
+| `highlighted` | `any` (array with `highlightMultiple`) | `v-model:highlighted`      | `null`         |
+| `sort`        | `BbTableSortEntry[]`                   | `v-model:sort`             | `[]`           |
+| `page`        | `number`                               | `page` / `BbPagination`    | `1`            |
+| `perPage`     | `number`                               | `perPage`                  | `0`            |
+| `total`       | `number`                               | `totalItems`               | `0`            |
+| `totalPages`  | `number`                               | derived / `totalPages`     | `1`            |
+| `isReady`     | `ComputedRef<boolean>` (read-only)     | —                          | —              |
+
+**Stable baselines.** Every field reads its empty baseline (never `undefined`)
+even before the table mounts or on a handle nobody hosts — so you can read,
+iterate, and bind immediately without guards. An explicit `null` (a cleared
+single-mode selection/highlight) passes through unchanged.
+
+**`totalPages`** is derived (`ceil(total / perPage)`) whenever a real `total`
+is known; otherwise it reads the seeded page count (a `totalPages` prop on
+`BbTable` or `BbPagination`, an `initial`, or a write here). Assigning it
+stores such a seed — it never overrides a derivation backed by a real `total`.
+An array table's inferred `total` (its `items.length`) does not count as real:
+an explicit seed outranks it.
+
+**`isReady`** is `true` once the context can answer the page count — a real
+`total` (your `initial`, the table's props, or a write) or a seeded
+`totalPages` — rather than fallback defaults. It answers "is paging data real
+yet", **not** "is a table attached".
+
+## Usage Example — bulk actions from a toolbar
+
+```vue
+<template>
+	<div class="flex flex-col gap-3">
+		<!-- Toolbar OUTSIDE the table subtree, driven by the context -->
+		<div v-if="selectedCount" class="flex items-center gap-2">
+			<span class="text-sm">{{ selectedCount }} selected</span>
+			<BbButton
+				prepend:icon="lucide:trash-2"
+				size="sm"
+				variant="destructive"
+				@click="deleteSelected"
+			>
+				Delete
+			</BbButton>
+			<BbButton size="sm" variant="ghost" @click="clearSelection">
+				Clear
+			</BbButton>
+		</div>
+
+		<BbTable
+			id="members-table"
+			v-model="selected"
+			caption="Members"
+			:columns="[
+				{ key: 'name', label: 'Name' },
+				{ key: 'role', label: 'Role' },
+			]"
+			:items="fetchMembers"
+			selectable
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbTable, useBbTableContext } from 'bitboss-ui';
+
+const selected = ref<string[]>([]);
+const fetchMembers = () => api.members.list();
+
+// Same id as the table. No prop drilling to the toolbar.
+const ctx = useBbTableContext('members-table');
+
+const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
+const clearSelection = () => (ctx.selected.value = []);
+const deleteSelected = async () => {
+	await api.members.deleteMany(ctx.selected.value);
+	ctx.selected.value = [];
+};
+</script>
+```
+
+## Gotchas
+
+- **The `id` is a rendezvous key — a mismatch does not error, it orphans.**
+  `useBbTableContext('users-tabel')` (typo) and `<BbTable id="users-table">`
+  create two independent state nodes. Your handle still returns stable
+  baselines and your `initial` still seeds _it_, so the panel looks alive —
+  but nothing flows to or from the table. If a context "works" but the table
+  never reacts, check the id spelling first. `isReady` being `true` only means
+  your `initial` set paging values; it does **not** confirm a table is
+  attached.
+- **Client-side only.** During SSR the handle operates on a detached, unshared
+  state (the table still renders from its props). Cross-component wiring is
+  hydration-time onward.
+- **Creation order does not matter.** Whoever references the id first (this
+  composable, the table, or a `BbPagination` with a matching `table-id`)
+  creates the shared node; the rest join it. Call `useBbTableContext` before
+  or after the table mounts.
+- **`sort` does not reorder data.** The context mirrors the model; you apply
+  it to your data source (see the BbTable contract and the Sortable columns
+  recipe variation).
+
+## Related
+
+- [BbTable](../BbTable.md) — the props/events/slots this mirrors.
+- [BbPagination](../BbPagination.md) — joins the same context via its `table-id` prop.
+- [Recipe: CRUD listing page](../recipes/inertia/records-workspace.md) — full server-driven table assembly.
+- [useBbTabsContext](./useBbTabsContext.md) — the same by-id pattern for `BbTabs`.

package/dist/ai/composables/useBbTabsContext.md

@@ -0,0 +1,118 @@
+---
+title: useBbTabsContext
+summary: Read and drive a BbTabs/BbTabsRoot group from anywhere by id — writable current tab, goTo/select, no template refs.
+type: composable
+---
+
+# useBbTabsContext
+
+## Summary
+
+`useBbTabsContext(id)` gives you a live handle on a mounted `BbTabs` /
+`BbTabsRoot` group, addressed by the same `id` you gave the component. Any
+component on the client — a page header, a "Next section" button in a footer, a
+keyboard shortcut handler — can read the active tab or change it without
+template refs and without being in the tabs' subtree.
+
+It is the tabs sibling of [`useBbTableContext`](./useBbTableContext.md): same
+id-rendezvous pattern, same "call it before or after the component mounts"
+ergonomics.
+
+## Import
+
+```ts
+import { useBbTabsContext } from 'bitboss-ui';
+```
+
+## API
+
+```ts
+const tabs = useBbTabsContext<K>(id); // `K` is optional and defaults to `string`
+```
+
+- **`id`** — must match the `id` prop on `<BbTabs id="…">` or
+  `<BbTabsRoot id="…">`. Give the component an explicit `id`; auto-generated
+  ids are not addressable.
+- **`K`** — optional union of the tab keys, narrowing `current` and `select`.
+
+### Returned handle (`BbTabsContextHandle<K>`)
+
+Individual computed refs and functions — safe to destructure.
+
+| Member         | Type                                                     | Description                                                                                                                                                                         |
+| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isReady`      | `ComputedRef<boolean>`                                   | Whether a tabs instance with this id is currently mounted.                                                                                                                          |
+| `current`      | `WritableComputedRef<K \| null>`                         | Active tab key (`null` until the tabs mount). **Writable**: assigning a key selects it, exactly like `select(key)`. Setting `null` warns and is ignored — a tab is always selected. |
+| `currentIndex` | `ComputedRef<number>`                                    | Zero-based index of the active tab (`-1` until mount).                                                                                                                              |
+| `isFirst`      | `ComputedRef<boolean>`                                   | Active tab is the first item.                                                                                                                                                       |
+| `isLast`       | `ComputedRef<boolean>`                                   | Active tab is the last item.                                                                                                                                                        |
+| `goTo`         | `(t: 'first' \| 'previous' \| 'next' \| 'last') => void` | Relative navigation; skips `disabled` tabs.                                                                                                                                         |
+| `select`       | `(key: K) => void`                                       | Select by key. Unknown keys warn and leave the selection untouched.                                                                                                                 |
+
+Selection through the handle goes through the tabs' full pipeline: the
+component's `v-model` is emitted, and URL / Inertia navigation runs when the
+tabs have `navigation` — identical to clicking the trigger.
+
+## Usage example — steer tabs from outside
+
+```vue
+<template>
+	<div class="flex items-center justify-between">
+		<h2 class="text-lg font-semibold">Project settings</h2>
+		<BbButton
+			append:icon="lucide:arrow-right"
+			:disabled="isLast"
+			size="sm"
+			variant="outline"
+			@click="goTo('next')"
+		>
+			Next section
+		</BbButton>
+	</div>
+
+	<BbTabs
+		id="settings-tabs"
+		:items="[
+			{ key: 'general', label: 'General' },
+			{ key: 'security', label: 'Security' },
+			{ key: 'billing', label: 'Billing' },
+		]"
+	>
+		<!-- one pane slot per key -->
+	</BbTabs>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbTabs, useBbTabsContext } from 'bitboss-ui';
+
+// Same id as the tabs. Works from any component on the page.
+const { current, goTo, isLast } = useBbTabsContext<
+	'general' | 'security' | 'billing'
+>('settings-tabs');
+
+// current is writable: current.value = 'billing' jumps straight there.
+</script>
+```
+
+## Behavior and gotchas
+
+- **Callable before the tabs mount.** The handle starts empty (`isReady`
+  `false`, `current` `null`, `currentIndex` `-1`) and auto-populates when the
+  tabs render; it empties again on unmount. Actions (`select`, `goTo`, writing
+  `current`) on an unmounted id warn and no-op.
+- **The id is a rendezvous key.** A typo doesn't error — it just never becomes
+  ready. If actions warn about no mounted instance, check the id spelling
+  against the component's `id` prop.
+- **Duplicate ids are an error.** Two mounted tab groups with the same id log
+  an error; the handle resolves to the most recently mounted one.
+- **Client-side only.** During SSR the registry stays empty; wire cross-
+  component behavior from hydration onward.
+- **Don't rebuild navigation on top of it.** For URL-driven tabs use the
+  component's own `navigation` / `query-key` / `href` support — the handle then
+  rides along. Never `router.push` manually to change a tab.
+
+## Related
+
+- [BbTabs](../BbTabs.md) — batteries-included tabs (strip + panes).
+- [BbTabsRoot](../BbTabsRoot.md) — renderless root for split strip/panes layouts; its default slot exposes the same `select` / `goTo` / `isFirst` / `isLast` inside the subtree.
+- [useBbTableContext](./useBbTableContext.md) — the same by-id pattern for `BbTable`.

package/dist/ai/composables/useBroadcastChannelInstance.md

@@ -0,0 +1,97 @@
+---
+title: useBroadcastChannelInstance
+summary: Typed cross-tab messaging via the BroadcastChannel API with per-component subscriber lifecycle.
+type: composable
+---
+
+# useBroadcastChannelInstance
+
+## Summary
+
+`useBroadcastChannelInstance` creates a typed factory for `BroadcastChannel` communication between browser tabs or windows sharing the same origin. Each call to the returned `useBroadCastChannel()` factory creates a scoped channel handle that auto-removes listeners on component unmount.
+
+Use it to synchronise state (auth, notifications, config changes) across tabs without polling.
+
+## Import
+
+```ts
+import { useBroadcastChannelInstance } from 'bitboss-ui';
+```
+
+## API
+
+### Factory setup
+
+Create a typed channel factory, typically once per message contract (e.g. in a composable or store):
+
+```ts
+const { useBroadCastChannel } = useBroadcastChannelInstance<MessageMap>(name); // `name` is optional
+```
+
+- `MessageMap` — a type map of `{ eventName: payloadType }`. Use `void` for events with no payload.
+- `name` — channel name (default: `'bitboss-ui'`). All tabs using the same name share the channel.
+
+### Channel handle methods
+
+Each call to `useBroadCastChannel()` returns:
+
+| Method                        | Description                                                                                         |
+| ----------------------------- | --------------------------------------------------------------------------------------------------- |
+| `post(type, params?)`         | Broadcast a message to all other tabs on the same channel.                                          |
+| `on(type, handler, options?)` | Subscribe to incoming messages of a given type. Auto-removed on unmount by default.                 |
+| `close()`                     | Release this handle. The channel resources are freed once every handle from the factory has closed. |
+
+### `on` options
+
+```ts
+on(type, handler, ({ removeonUnmount: boolean } = { removeonUnmount: true }));
+```
+
+Set `removeonUnmount: false` to keep the subscription alive after the component unmounts (e.g. in a global store).
+
+## Defining a message contract
+
+```ts
+type AppMessages = {
+	'auth:logout': void; // no payload
+	'cart:updated': { count: number }; // typed payload
+	'theme:changed': { theme: string };
+};
+
+// Create the factory once, export it for reuse
+export const { useBroadCastChannel } =
+	useBroadcastChannelInstance<AppMessages>('my-app');
+```
+
+## Usage Example
+
+```vue
+<script setup lang="ts">
+import { useToast } from 'bitboss-ui';
+import { useBroadCastChannel } from '@/composables/channel'; // your re-export
+
+const channel = useBroadCastChannel();
+const { toast } = useToast();
+
+// A checkout completed in another tab — surface it here too.
+channel.on('cart:updated', ({ count }) => {
+	toast({ title: `Cart updated (${count} items)`, variant: 'info' });
+});
+
+// Session ended elsewhere: mirror it in this tab.
+channel.on('auth:logout', () => router.push({ name: 'login' }));
+
+// Broadcast cart update to other tabs
+function updateCart(count: number) {
+	cart.count = count;
+	channel.post('cart:updated', { count });
+}
+</script>
+```
+
+## Notes
+
+- The `BroadcastChannel` API is not available during SSR — the composable catches the failure (the handle becomes inert), but only create handles in client-side code paths (`setup` of rendered components is fine).
+- Messages are only received by _other_ tabs, not the sender.
+- Each `useBroadCastChannel()` call increments an internal reference count; resources are released only when all handles call `close()`.
+- Handlers registered with `removeonUnmount: true` (default) are cleaned up automatically via `onBeforeUnmount` — so call `on(...)` inside component `setup`.