bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbAlert.md

@@ -1,225 +1,408 @@
 # BbAlert
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Feedback**
+- Description: Shows contextual status messages.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbAlert.md](./source/BbAlert.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbAlert` when a message belongs _to the page_ and must remain
+visible until the user reads or dismisses it: a form-level error summary, a
+plan/quota warning, an inline "changes saved" confirmation on a settings panel.
+
+Choose a sibling when the shape is different:
+
+- Transient, floating, self-dismissing feedback after an action → `BbToast`
+  (paired with `useToast`).
+- A small count or status marker _on_ another element → `BbBadge`.
+- A yes/no decision the user must take → `BbConfirm` + `useConfirm`, not an
+  alert with buttons.
+
+`BbAlert` renders in normal document flow (no portal, no fixed position, no
+teleport), so it pushes surrounding content, reads top-to-bottom like the rest
+of the page, and is safe to server-render as-is in Nuxt/Inertia apps. It has no
+size prop: it fills its container's width, so control width with the layout
+around it (`max-w-md` etc.).
+
+### The variant ladder
+
+Pick a variant by intent, not decoration. `outline` is the quietest (neutral
+info); `primary` carries a branded, actionable note; `warning` flags something
+the user should attend to; `destructive` reports a failure or dangerous state.
+An alert reads far better with a matching leading `icon`, so treat variant and
+icon as a pair.
+
+**Semantic variants, each with a fitting icon**
+
+```vue
+<div class="flex max-w-md flex-col gap-3">
+	<BbAlert
+		variant="outline"
+		icon="lucide:info"
+		title="Note"
+		text="Outline is the quietest variant — use it for neutral info."
+		hide-close
+	/>
+	<BbAlert
+		variant="primary"
+		icon="lucide:rocket"
+		title="Update available"
+		text="Version 2.4.0 is ready to install."
+		hide-close
+	/>
+	<BbAlert
+		variant="warning"
+		icon="lucide:triangle-alert"
+		title="Storage almost full"
+		text="You have used 92% of your quota."
+		hide-close
+	/>
+	<BbAlert
+		variant="destructive"
+		icon="lucide:circle-x"
+		title="Payment failed"
+		text="Your card was declined. Try another method."
+		hide-close
+	/>
+</div>
+```
+
+The default variant is `outline`. `warning` and `destructive` are treated as
+high-priority for accessibility (see below).
+
+#### Registering project variants
+
+Variants are an open registry, not a closed enum. The vite/nuxt plugin's
+`alertVariants` option appends names to the typed union
+(`outline | primary | destructive | warning` by default), and each variant
+renders a `bb-alert--<name>` class hook. Registered custom variants ship **no
+styles** — you provide the CSS, setting the same tokens the built-ins use:
+
+```ts
+// vite.config.ts
+bitbossUi({
+	iconDir: './src/icons',
+	alertVariants: ['success'],
+});
+```
+
+```css
+.bb-alert--success {
+	--main-color: #15803d; /* title + icon */
+	--muted-color: color-mix(
+		in oklab,
+		var(--main-color) 75%,
+		transparent
+	); /* body + close */
+	background-color: transparent;
+	border-color: var(--bb-border);
+}
+```
+
+One a11y catch: only `warning` and `destructive` are hard-coded as
+high-priority. A custom variant — however alarming its name — announces as
+`role="status"` / `aria-live="polite"` unless you also pass `role="alert"` /
+`aria-live="assertive"` on urgent instances.
+
+### Dismissal and v-model
+
+The close button is rendered by default. Clicking it sets the model to `false`
+(emitting `update:modelValue`) and the alert animates out. Note that this works
+_even without a `v-model`_ — the internal model defaults to `true`, so an
+unbound alert can still be dismissed; you just can't observe or restore it.
+Bind `v-model` when the visibility matters to you:
+
+**Dismiss and restore a banner**
 
 ```vue
 <template>
-	<BbCollapsible
-		class="bb-alert"
-		:class="{ [`bb-alert--${theme}`]: theme }"
-		:model-value="innerValue"
+	<div
+		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
 	>
-		<div class="bb-alert__inner-container" role="alert">
-			<div class="bb-alert__icon-container">
-				<BbIcon
-					v-if="icon"
-					class="bb-alert__icon"
-					:size="iconSize"
-					:type="icon"
-				/>
-			</div>
-			<div class="bb-alert__content">
-				<button
-					v-if="showClose"
-					:aria-label="closeLabel || t('common.closeLabel').value"
-					block
-					class="bb-alert__close"
-					type="button"
-					@click="onClickClose"
-				>
-					<svg
-						fill="none"
-						viewBox="0 0 24 24"
-						xmlns="http://www.w3.org/2000/svg"
-					>
-						<path
-							d="M23 23L1 1M23 1L1 23"
-							stroke="currentColor"
-							stroke-linecap="round"
-							stroke-width="2"
-						/>
-					</svg>
-				</button>
-				<div class="bb-alert__title">
-					<slot name="title" v-bind="{ text: title }">{{ title }}</slot>
-				</div>
-				<div class="bb-alert__text">
-					<slot name="text" v-bind="{ text: text }">{{ text }}</slot>
-				</div>
-			</div>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Account</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Confirm your email to invite teammates and manage billing.
+			</p>
 		</div>
-	</BbCollapsible>
+
+		<BbAlert
+			v-if="showBanner"
+			v-model="showBanner"
+			close-label="Dismiss email verification reminder"
+			icon="lucide:mail"
+			text="We sent a link to alex@northwind.co. Confirm within 24 hours or the invite link expires."
+			title="Verify your email"
+			variant="primary"
+		/>
+		<BbButton
+			v-else
+			prepend:icon="lucide:mail"
+			variant="ghost"
+			@click="showBanner = true"
+		>
+			Show the reminder again
+		</BbButton>
+	</div>
 </template>
 
 <script setup lang="ts">
-import { ref, watch } from 'vue';
-import BbCollapsible from '../BbCollapsible/BbCollapsible.vue';
-import BbIcon from '../BbIcon/BbIcon.vue';
-import { useLocale } from '@/composables/useLocale';
-import type { BbAlertProps, BbAlertEvents, BbAlertSlots } from './types';
-
-const props = withDefaults(defineProps<BbAlertProps>(), {
-	theme: 'default',
-});
+import { ref } from 'vue';
+import { BbAlert, BbButton } from 'bitboss-ui';
 
-const emit = defineEmits<BbAlertEvents>();
+const showBanner = ref(true);
+</script>
+```
 
-defineSlots<BbAlertSlots>();
+- `hide-close` removes the close button entirely — the only way to make an
+  alert truly permanent (e.g. a blocking error that clears itself when the
+  underlying condition resolves).
+- `close-label` overrides the close button's accessible name (it defaults to a
+  localised "Close"/"Chiudi" from the plugin `locale`).
+- `transition-duration` (ms, default 250) tunes the enter/leave fade+slide;
+  `prefers-reduced-motion` collapses it automatically. Setting the model back
+  to `true` re-enters with the same transition, so a restored banner doesn't
+  pop.
 
-const { t } = useLocale();
+### Icons
 
-const innerValue = ref(
-	props.modelValue === undefined ? true : !!props.modelValue
-);
+`icon` renders a leading icon tinted with the variant's main colour; `iconSize`
+(default `'16'`, any `BbIcon` size) scales it. No variant implies an icon —
+always pass one explicitly and keep it semantically aligned with the variant
+(see the ladder example above). The icon is reinforcement only: the message
+must read correctly from `title`/`text` alone.
 
-watch(
-	() => props.modelValue,
-	(value) => {
-		if (innerValue.value !== !!value) {
-			innerValue.value = !!value;
-		}
-	}
-);
+### Rich content with slots
 
-const onClickClose = () => {
-	innerValue.value = false;
-	emit('update:modelValue', false);
-};
-</script>
+`title` and `text` cover the common case. When the body needs emphasis, a link,
+or inline markup, use the `title` / `text` slots. Each slot receives
+`{ text }` — the corresponding prop's value — so a slot can decorate the plain
+prop instead of replacing it. Offload navigation to a real anchor; never wire a
+click handler for something a link can do.
+
+**Custom body with an inline link**
 
-<style lang="postcss">
-@import './index.css';
-</style>
+```vue
+<div class="max-w-md">
+	<BbAlert variant="primary" icon="lucide:sparkles" hide-close>
+		<template #title>You're on the <strong>Free</strong> plan</template>
+		<template #text>
+			Upgrade to unlock unlimited projects.
+			<a href="#pricing" class="font-medium underline">Compare plans</a>
+		</template>
+	</BbAlert>
+</div>
 ```
 
-## Types
+These are the only two slots — there is no default or actions slot. A short
+inline link in `#text` (as above) is fine; anything more interactive belongs
+outside the alert, or in a `BbDialog`.
 
-```ts
-import type { CommonProps } from '@/types/CommonProps';
-import type { BbIconProps } from '../BbIcon/types';
-
-export type BbAlertProps = Pick<
-	CommonProps,
-	'closeLabel' | 'showClose' | 'text' | 'theme' | 'title'
-> & {
-	/**
-	 * Name of the icon to use.
-	 */
-	icon?: BbIconProps['type'];
-	/**
-	 * Size of the icon to use.
-	 */
-	iconSize?: BbIconProps['size'];
-	/**
-	 * Used by v-model, set type to any to avoid Vue casting it as false.
-	 */
-	modelValue?: any;
-};
+#### Brand art via a raw SVG
 
-export type BbAlertEvents = {
-	/**
-	 * Emitted when the alert is dismissed via the close button.
-	 */
-	(e: 'update:modelValue', value: boolean): void;
-};
+When the message concerns a third-party product — an integration that broke,
+an app that needs reauthorising — the alert reads faster with that product's
+logomark inline. Keep the `icon` prop for the semantic status glyph and place
+the brand art in the `#title` slot as a standalone `BbIcon`: its `icon` prop
+also accepts a full raw `<svg>` string, so a `?raw` import of the asset feeds
+it directly, no icon-registry entry needed. Reserve this escape hatch for
+genuine brand art; everything semantic stays a provider icon.
 
-/** Props exposed by the `title` slot. */
-export type BbAlertTitleSlotProps = {
-	/** The `title` prop value. */
-	text: BbAlertProps['title'];
-};
+**Integration incident notice with a brand mark**
 
-/** Props exposed by the `text` slot. */
-export type BbAlertTextSlotProps = {
-	/** The `title` prop value passed to the text slot. */
-	text: BbAlertProps['title'];
-};
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Integrations</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Connected payment providers for Northwind Billing.
+			</p>
+		</div>
 
-export type BbAlertSlots = {
-	/**
-	 * Replaces the default alert title text.
-	 */
-	title?: (props: BbAlertTitleSlotProps) => any;
-	/**
-	 * Replaces the default alert body text.
-	 */
-	text?: (props: BbAlertTextSlotProps) => any;
-};
+		<BbAlert hide-close icon="lucide:triangle-alert" variant="warning">
+			<template #title>
+				<span class="inline-flex items-center gap-1.5">
+					<BbIcon :icon="acmeMark" label="Acme Payments" size="sm" />
+					Acme Payments needs to be reconnected
+				</span>
+			</template>
+			<template #text>
+				The OAuth token expired on 8 Jul, so payment webhooks are paused.
+				<a class="font-medium underline" href="#integrations">
+					Reconnect in Integrations
+				</a>
+			</template>
+		</BbAlert>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAlert, BbIcon } from 'bitboss-ui';
+import acmeMark from './acme-mark.svg?raw';
+</script>
 ```
 
-## Styles
+### Validation summaries
 
-```css
-.bb-alert {
-	--color: var(--bb-primary);
-	--gap: 8px;
-	--padding-x: 16px;
-	--padding-y: 12px;
-	background-color: color-mix(in srgb, var(--color) 20%, transparent);
-	border-radius: var(--bb-radius);
-
-	.bb-alert__inner-container {
-		align-items: start;
-		display: grid;
-		gap: 0 var(--gap);
-		grid-template-columns: auto 1fr;
-		padding: var(--padding-y) var(--padding-x);
-
-		&:has(.bb-alert__icon-container:empty) {
-			grid-template-columns: 1fr;
-		}
-
-		.bb-alert__icon {
-			color: var(--color);
-		}
-
-		.bb-alert__content {
-			.bb-alert__title {
-				align-items: center;
-				color: color-mix(in srgb, var(--color) 75%, var(--bb-text));
-				column-gap: var(--gap);
-				display: flex;
-				font-size: 16px;
-				font-weight: 600;
-			}
-
-			.bb-alert__text {
-				color: color-mix(in srgb, var(--bb-text) 70%, transparent);
-				font-size: 14px;
-			}
-		}
-
-		.bb-alert__close {
-			border-radius: var(--bb-radius);
-			box-shadow: 0px 0px 0px 0px var(--bb-ring);
-			color: color-mix(in srgb, var(--bb-text) 80%, transparent);
-			float: right;
-			isolation: isolate;
-			/* This margin is done to allow the ring to be visible when user navigates through keyboard to the button */
-			margin: calc(var(--padding-y) * -1 + var(--bb-ring-size))
-				calc(var(--padding-x) * -1 + var(--bb-ring-size))
-				calc(var(--padding-y) * -1) 0px;
-			outline: none;
-			padding: 12px;
-			transition-duration: 150ms;
-			transition-property:
-				color, background-color, border-color, text-decoration-color, box-shadow;
-			transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-			width: fit-content;
-
-			&:hover {
-				color: var(--bb-primary);
-			}
-
-			&:focus-visible {
-				box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
-				color: var(--bb-primary);
-			}
-
-			svg {
-				width: 12px;
-			}
-		}
-	}
-}
+The classic form pattern: a `destructive` alert above the form that appears on
+a failed submit and lists what's missing. Use `hide-close` — the user clears it
+by fixing the input, not by dismissing the message. Because `destructive`
+defaults to `role="alert"`, showing it interrupts the screen reader
+appropriately, and `aria-atomic` re-announces the whole message whenever the
+list of problems changes.
+
+**Publish blocked until the checklist passes**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Publish checklist</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Northwind Q3 release notes — blocked until both items are done.
+			</p>
+		</div>
+
+		<BbAlert
+			v-if="attempted && missing.length"
+			hide-close
+			icon="lucide:circle-x"
+			title="Can't publish yet"
+			variant="destructive"
+		>
+			<template #text>
+				Fix these before publishing:
+				<ul class="mt-1 list-inside list-disc text-sm">
+					<li v-for="step in missing" :key="step">{{ step }}</li>
+				</ul>
+			</template>
+		</BbAlert>
+
+		<div class="flex flex-col gap-2">
+			<BbCheckbox v-model="hasTitle" label="Add a release title" />
+			<BbCheckbox v-model="hasCover" label="Attach the hero screenshot" />
+		</div>
+
+		<BbButton
+			class="self-start"
+			prepend:icon="lucide:send"
+			variant="primary"
+			@click="publish"
+		>
+			Publish
+		</BbButton>
+
+		<BbAlert
+			v-if="published"
+			v-model="published"
+			icon="lucide:circle-check"
+			text="Release notes are live on the changelog."
+			title="Published"
+			variant="primary"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbAlert, BbButton, BbCheckbox } from 'bitboss-ui';
+
+const hasTitle = ref(false);
+const hasCover = ref(false);
+const attempted = ref(false);
+const published = ref(false);
+
+const missing = computed(() => [
+	...(hasTitle.value ? [] : ['Add a release title']),
+	...(hasCover.value ? [] : ['Attach the hero screenshot']),
+]);
+
+const publish = () => {
+	attempted.value = true;
+	published.value = missing.value.length === 0;
+};
+</script>
 ```
+
+### Works well with
+
+- `BbToast` — pair them: the toast confirms _the action_ ("Saved"), the alert
+  reflects _the resulting page state_ (an unresolved quota warning stays).
+- `BbConfirm` / `useConfirm` — when the message is really a decision, ask;
+  don't display an alert and hope.
+- Form components (`BbTextInput`, `BbCheckbox`, …) — alert above the form for
+  the summary, per-field errors on the inputs themselves.
+
+### Gotchas & anti-patterns
+
+- **There is no default slot.** `<BbAlert>some text</BbAlert>` renders
+  nothing — Vue drops an unconsumed default slot silently, with no warning.
+  Use `title`/`text` (or `#title`/`#text`, see above).
+- **Omitting `v-model` does not make an alert permanent** — the close button
+  still dismisses it locally. Use `hide-close` for that.
+- Don't rebuild dismissal with your own button + `v-if`; the built-in close
+  button gives you the transition, the localised label, and the event.
+- Don't stack several `assertive` alerts that appear together — they talk over
+  each other. One summary alert beats five fragments.
+- A custom registered variant is polite by default; pass `role="alert"` on the
+  instances that are genuinely urgent.
+- `modelValue` is typed `any` on purpose (so Vue doesn't coerce an absent
+  binding to `false`); treat it as a boolean in your own state.
+
+### Accessibility
+
+- The container's ARIA role and live-region politeness derive from the
+  variant: `warning` / `destructive` announce as `role="alert"` /
+  `aria-live="assertive"`; every other variant (built-in or custom) uses
+  `role="status"` / `aria-live="polite"`. Override per instance with the
+  `role` / `aria-live` props only with a specific reason.
+- The alert is `aria-atomic`, so updating its text re-announces the whole
+  message rather than a fragment.
+- The close button ships with a localised label (plugin `locale`); pass
+  `close-label` to override it per alert.
+- Reserve `assertive`/`role="alert"` for genuinely urgent messages so you
+  don't talk over the user's screen reader.
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
+| `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
+| `hideClose` | `boolean \| undefined` |  |  | Defines whether to hide the close button. |
+| `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
+| `iconSize` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
+| `modelValue` | `any` | `true` |  | Used by v-model, set type to any to avoid Vue casting it as false. Alerts are visible on mount; the model dismisses them. |
+| `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
+| `text` | `string \| undefined` |  |  | Text content of the alert body. |
+| `title` | `string \| undefined` |  |  | Text content of the alert title. |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Transition duration in milliseconds for enter/leave. |
+| `variant` | `keyof AlertVariantRegistry \| undefined` | `"outline"` |  | Visual variant of the alert. |
+
+## Events
+
+- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+
+## Slots
+
+- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text.
+- `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.
+
+## See Also
+
+- [BbToast](./BbToast.md) — Shows transient notification messages.

package/dist/ai/BbAsterisk.md

@@ -0,0 +1,46 @@
+# BbAsterisk
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Other**
+- Description: Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbAsterisk.md](./source/BbAsterisk.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbAsterisk` is the small red `*` that marks a field as required. It is purely
+presentational — it has no props, slots, or events, and it does not read
+`required` or drive validation. You render it yourself wherever you build custom
+label content, so the marker matches the library's styling (`--bb-danger`).
+
+Most consumers never place it by hand: the `bitboss-ui/validated` form controls
+render it for you in their `#label` slot when a field is `required`/has rules and
+`config.requiredAsterisk` is enabled. Reach for `BbAsterisk` directly only when
+you compose a bespoke label outside those controls.
+
+```vue
+<BbTextInput label="Email">
+	<template #label="{ text }">
+		{{ text }}<BbAsterisk />
+	</template>
+</BbTextInput>
+```
+
+Wrap it in an element with your own spacing if the default `margin-inline-start`
+doesn't suit the layout; the glyph inherits nothing else from its surroundings.
+
+## Props
+
+- None.
+
+## Events
+
+- None.
+
+## Slots
+
+- None.