bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbIcon.md

@@ -1,237 +1,407 @@
 # BbIcon
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Data Display**
+- Description: Renders an icon either from the local icon folder or from a provider.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbIcon.md](./source/BbIcon.md)
+
+## Usage & Guidelines
+
+### When to reach for BbIcon
+
+Most components render icons for you through props — `BbButton` and `BbBadge`
+take `prepend:icon` / `append:icon` / `icon`; every batteries-included input
+takes `prepend:icon` / `append:icon`; `BbAlert`, `BbToast` take `icon`;
+`BbDropdown` items carry `'prepend:icon'` / `'append:icon'` fields. **Prefer
+those** — they place, size and color the glyph to match the control, and keep the
+markup declarative.
+
+A handful of components have **no icon prop** and take icons through **slots**
+instead — you place a `BbIcon` (or richer markup) yourself: `BbTabs` per-tab
+`label-{key}` (or the generic `label` fallback), `BbBreadcrumbs` `item:prepend` /
+`item:append` (or a per-`key` slot), `BbRating`'s `icon` slot, `BbSwitch`'s
+`icon` slot. These have no `icon` _field_ on their items — the slot is the seam.
+
+Reach for `BbIcon` **directly** only for standalone iconography the design owns:
+a status glyph in a table cell, empty-state art, a custom list marker, or a
+control you are composing yourself. Never wrap a `BbIcon` in your own `<button>`
+to rebuild a button — use `BbButton` with `icon` plus a label (slot or `text`).
+The full catalog of every icon-accepting surface lives in the **Icons Policy**
+(`./icons-policy.md`); this guide is the primitive itself.
+
+**Status glyph legend**
 
 ```vue
 <template>
-	<svg v-bind="iconAttributes" data-allow-mismatch v-html="content"></svg>
+	<div
+		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">API status</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Last checked 2 minutes ago
+			</p>
+		</div>
+		<ul class="flex flex-col gap-1.5 text-sm">
+			<li
+				v-for="row in rows"
+				:key="row.label"
+				class="flex items-center gap-2"
+				:class="row.tone"
+			>
+				<BbIcon :icon="row.icon" size="sm" />
+				<span class="min-w-0 flex-1 truncate font-medium">{{ row.host }}</span>
+				<span class="shrink-0 text-xs">{{ row.label }}</span>
+			</li>
+		</ul>
+	</div>
 </template>
 
 <script setup lang="ts">
-import {
-	computed,
-	inject,
-	ref,
-	getCurrentInstance,
-	onServerPrefetch,
-	onBeforeMount,
-	watch,
-} from 'vue';
-import { isCssColor } from '@/utilities/functions/isCssColor';
-import { get } from '@/utilities/functions/get';
-import { useLogger } from '@/composables/useLogger';
-import type { BbIconProps, Size } from './types';
-
-const props = withDefaults(defineProps<BbIconProps>(), {
-	size: 'md',
-});
-const logger = useLogger();
-let icons = ref<Record<string, () => Promise<string>>>();
-const icon = ref<string | null>(null);
-const content = computed(() => {
-	if (icon.value) {
-		return icon.value.replace(/<\/?svg[^>]*>/g, '');
-	}
-	return null;
-});
-
-// @ts-expect-error possibily undef
-const isNuxt = !!get(getCurrentInstance(), ['proxy', '$nuxt']);
-
-/**
- * Loads the icon registry based on the current environment (Nuxt or Vue).
- * In Nuxt, uses the injected $icons from the Nuxt context.
- * In Vue, uses the injected 'icons' provider.
- * Only loads icons once to prevent redundant operations.
- * Throws an error if icons cannot be loaded in the current environment.
- */
-const loadIcons = () => {
-	if (isNuxt) {
-		// @ts-expect-error possibily undef
-		icons.value = get(getCurrentInstance(), ['proxy', '$nuxt', '$icons']);
-		if (!icons.value) {
-			logger.throw(
-				'Failed to load Nuxt icons. Make sure the icon provider is properly configured.'
-			);
-		}
-		return;
-	}
-
-	icons.value = inject('icons');
-	if (!icons.value) {
-		logger.throw(
-			'Failed to inject icons. Make sure the icon provider is properly configured in the Vue app.'
-		);
-	}
-};
-
-/**
- * Retrieves and loads the SVG content for the specified icon type.
- * Throws an error if icons haven't been loaded or if the icon type doesn't exist.
- */
-const getIcon = async () => {
-	if (!icons.value) {
-		logger.throw('Icons have not been loaded');
-	}
-
-	const iconLoader = icons.value![props.type];
-	if (!iconLoader) {
-		logger.throw(`Icon "${props.type}" does not exist.`);
-	}
-
-	icon.value = await iconLoader();
-};
+import { BbIcon, type IconType } from 'bitboss-ui';
 
-onServerPrefetch(async () => {
-	loadIcons();
-	await getIcon();
-});
-
-onBeforeMount(async () => {
-	if (!icons.value) {
-		loadIcons();
-	}
-	if (!icon.value) {
-		await getIcon();
-	}
-});
-
-watch(() => props.type, getIcon);
-
-const sizeMap: Size = {
-	xs: 12,
-	sm: 16,
-	md: 24,
-	lg: 28,
-	xl: 36,
-	xxl: 40,
+type StatusRow = {
+	host: string;
+	label: string;
+	icon: IconType;
+	tone: string;
 };
 
-/**
- * Computes the width of the icon in pixels based on the size prop.
- * Supports predefined size keys, numeric values, or custom pixel strings.
- */
-const iconWidth = computed(() => {
-	if (typeof props.size === 'number') {
-		return `${props.size}px`;
-	}
-
-	if (typeof props.size === 'string') {
-		const mappedSize = sizeMap[props.size as keyof Size];
-		if (mappedSize !== undefined) {
-			return `${mappedSize}px`;
-		}
-		const parsed = parseInt(props.size, 10);
-		if (isNaN(parsed)) {
-			logger.throw(`Invalid size: "${props.size}"`);
-		}
-		return `${parsed}px`;
-	}
-
-	return '24px';
-});
-
-/**
- * Computes the attributes object for the icon span element.
- * Includes CSS classes, inline styles, and accessibility attributes.
- */
-const iconAttributes = computed(() => {
-	const classes: Record<string, boolean> = {
-		'bb-icon': true,
-	};
-	const style: Record<string, string> = {
-		'--bb-icon-dimensions-w': iconWidth.value,
-	};
-
-	if (props.color) {
-		if (isCssColor(props.color)) {
-			style.color = props.color;
-		} else {
-			classes[`bb-icon--${props.color}`] = true;
-		}
-	}
-
-	const inheritedAttributes: Record<string, any> = {};
-	if (icon.value) {
-		const attrString = icon.value.split('>')[0].substring(5); // all attributes in the opening svg tag
-		const attrRegex = /([\w-]+)="([^"]*)"/g;
-		let match;
-		while ((match = attrRegex.exec(attrString)) !== null) {
-			inheritedAttributes[match[1]] = match[2];
-		}
-	}
-
-	const base: Record<string, any> = {
-		viewBox: '0 0 1 1',
-		...inheritedAttributes,
-		class: classes,
-		style,
-	};
-
-	// Determine if the icon should be accessible to screen readers
-	const hasAccessibleLabel = props.label;
-
-	if (hasAccessibleLabel) {
-		// Icon has a meaningful label - make it accessible
-		base['role'] = 'img';
-		base['aria-label'] = props.label.trim();
-		// Add title as fallback for older screen readers and tooltip behavior
-		base['title'] = props.label.trim();
-	}
-
-	// Icons should never be focusable or keyboard navigable since they're not interactive
-	base['focusable'] = 'false';
-
-	return base;
-});
+// Status glyph legend: each row owns a lucide literal and paints via
+// `currentColor` on the parent — the design-owned BbIcon case. Glyphs are
+// decorative (label sits beside them), so no `label` prop.
+const rows: StatusRow[] = [
+	{
+		host: 'api.northwind.co',
+		label: 'Operational',
+		icon: 'lucide:circle-check',
+		tone: 'status--ok',
+	},
+	{
+		host: 'billing.northwind.co',
+		label: 'Degraded',
+		icon: 'lucide:triangle-alert',
+		tone: 'status--warn',
+	},
+	{
+		host: 'webhooks.northwind.co',
+		label: 'Major outage',
+		icon: 'lucide:circle-x',
+		tone: 'status--danger',
+	},
+	{
+		host: 'sandbox.northwind.co',
+		label: 'No data',
+		icon: 'lucide:circle-dashed',
+		tone: 'status--muted',
+	},
+];
 </script>
 
-<style lang="postcss">
-@import './index.css';
+<style scoped>
+/* Soft status accents mirror design-language.md § Using color (BbIndicator
+   hues). Local --accent only — never mint --bb-* tokens from examples. */
+.status--ok {
+	--accent: #16a34a;
+	color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+}
+
+.status--warn {
+	--accent: #d97706;
+	color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+}
+
+.status--danger {
+	color: var(--bb-danger);
+}
+
+.status--muted {
+	color: var(--bb-text-muted);
+}
 </style>
 ```
 
-## Types
+### Names: collections, local icons and the resolution grammar
+
+The `icon` prop takes a name in one of three forms:
+
+- **`provider:name`** — a glyph from an installed Iconify collection. This project
+  ships no icon package of its own — install the ones you want. Prefer `lucide:`
+  for UI glyphs when no direction is given, so one visual language stays
+  consistent.
+- **`local:name`** — an SVG in the configured `iconDir` (brand marks, custom
+  illustrations). Each `.svg` file becomes `local:<basename>`.
+- **bare `name`** — an unprefixed name **normalizes to `local:`**; it never
+  searches provider sets.
+
+Discovery-first: **only use names you have verified exist** — a missing icon
+**throws at mount** (dev shows an actionable Vite overlay with the exact
+`npm install` fix). Never guess a name. See the Icons Policy for the discovery
+workflow and the heroicons `-20-`/`-16-` size-variant caveat.
+
+**The same glyph across collections, plus a local icon**
+
+```vue
+<div class="flex items-center gap-3">
+	<div class="flex flex-col items-center gap-1">
+		<BbIcon icon="lucide:heart" size="lg" />
+		<span class="text-xs text-[color:var(--bb-text-muted)]">lucide</span>
+	</div>
+	<div class="flex flex-col items-center gap-1">
+		<BbIcon icon="heroicons:heart" size="lg" />
+		<span class="text-xs text-[color:var(--bb-text-muted)]">heroicons</span>
+	</div>
+	<div class="flex flex-col items-center gap-1">
+		<BbIcon icon="mdi:heart" size="lg" />
+		<span class="text-xs text-[color:var(--bb-text-muted)]">mdi</span>
+	</div>
+	<div class="flex flex-col items-center gap-1">
+		<BbIcon icon="local:sparkles" size="lg" />
+		<span class="text-xs text-[color:var(--bb-text-muted)]">local</span>
+	</div>
+</div>
+```
+
+`local:*` is for brand art in `iconDir`. The deploy card below cycles stages
+with full `local:` literals from that folder — the canonical brand-mark demo.
+
+**Brand marks via local: — deploy stages**
 
-```ts
-import type { Size as S } from '@/types/CommonProps';
-import type { IconType } from '@/types/Icon';
+```vue
+<template>
+	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+		<div class="flex items-center justify-between gap-3">
+			<div class="min-w-0">
+				<p class="truncate text-sm font-medium">acme/storefront</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					Deploy #482 · production · {{ index + 1 }}/{{ stages.length }}
+				</p>
+			</div>
+			<BbButton size="xs" variant="outline" @click="onAdvance"
+				>Advance</BbButton
+			>
+		</div>
+		<div class="mt-2 flex items-center gap-1.5 text-sm" :class="current.tone">
+			<BbIcon :icon="current.icon" size="sm" />
+			<span class="font-medium">{{ current.label }}</span>
+		</div>
+	</div>
+</template>
 
-export type Size = {
-	xs: number;
-	sm: number;
-	md: number;
-	lg: number;
-	xl: number;
-	xxl: number;
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbIcon, type IconType } from 'bitboss-ui';
+
+type Stage = {
+	label: string;
+	icon: IconType;
+	tone: string;
 };
 
-export interface BbIconProps extends S<Size> {
-	/**
-	 * Define a color for the component.
-	 *
-	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
-	 */
-	color?: string;
-	/**
-	 * Label of the icon for accessibility.
-	 */
-	label?: string;
-	/**
-	 * Name of the icon to use.
-	 *
-	 * @defaultValue `'md'`
-	 */
-	type: IconType;
+// Brand marks via `local:*` (files in iconDir). Each stage owns a full static
+// literal so the production scanner bundles it — never `local:${name}`. The
+// glyph is decorative beside the stage label, so no `label` prop.
+const stages: Stage[] = [
+	{ label: 'Queued', icon: 'local:clock', tone: 'stage--muted' },
+	{ label: 'Building', icon: 'local:loader', tone: 'stage--active' },
+	{ label: 'Deployed', icon: 'local:check_circle', tone: 'stage--active' },
+	{ label: 'Failed', icon: 'local:alert_circle', tone: 'stage--danger' },
+];
+
+const index = ref(0);
+const current = computed(() => stages[index.value]);
+
+const onAdvance = () => {
+	index.value = (index.value + 1) % stages.length;
+};
+</script>
+
+<style scoped>
+.stage--muted {
+	color: var(--bb-text-muted);
 }
-```
 
-## Styles
+.stage--active {
+	color: var(--bb-primary);
+}
 
-```css
-.bb-icon {
-	--size: var(--bb-icon-dimensions-w);
-	width: var(--size);
-	pointer-events: none;
+.stage--danger {
+	color: var(--bb-danger);
 }
+</style>
+```
+
+#### The static-literal production constraint
+
+Icon names **must be static string literals**. Production builds scan source for
+`provider:name` literals and bundle only those — a name assembled at runtime
+(`` `lucide:${kind}` ``) is invisible to the scanner and **missing in
+production**. Map dynamic state to full literals instead — a lookup object of
+complete names, exactly as the deploy-stages companion does (`stages[i].icon`
+holds `'local:clock'`, not a concatenation). An icon used only in a
+`.stories.ts` / `.test.ts` must also appear as a literal in a scanned source
+file, since those are excluded from the scan.
+
+```vue
+<script setup lang="ts">
+// Correct: full literals behind a lookup — the scanner sees each one.
+const STATUS_ICON = {
+	paid: 'lucide:circle-check',
+	pending: 'lucide:clock',
+	failed: 'lucide:circle-x',
+} as const;
+// Wrong: `lucide:${status}` — never bundled, broken in production.
+</script>
+
+<template>
+	<BbIcon :icon="STATUS_ICON[status]" size="sm" />
+</template>
+```
+
+#### Raw-SVG escape hatch
+
+The `icon` prop **also accepts a full `<svg>…</svg>` string** — a public escape
+hatch for a one-off brand mark that lives in no collection. Import the asset with
+`?raw` and pass it straight through; `BbIcon` detects the SVG payload (it skips
+the icon registry entirely), strips the outer `<svg>`/XML/doctype wrapper, and
+re-renders the paths inside its own sized element, inheriting the source SVG's
+`viewBox`. Use it sparingly — a real `local:` asset is preferable when the mark
+will be reused. Here an empty state renders an app-bundled member mark (the
+same asset `BbAvatar` uses as its fallback) at `2xl`; sizing and `currentColor`
+behave exactly as with registry icons.
+
+**Raw-SVG import as empty-state art**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col items-center gap-2 rounded-[var(--bb-radius)] border p-4 text-center"
+	>
+		<span class="text-[color:var(--bb-text-muted)]">
+			<BbIcon :icon="memberMark" size="2xl" />
+		</span>
+		<p class="text-sm font-medium">No members yet</p>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Invite your team to start assigning issues on Northwind.
+		</p>
+		<BbButton variant="primary">Invite member</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbIcon } from 'bitboss-ui';
+// One-off brand art outside any collection: `?raw` yields a full `<svg>`
+// string that BbIcon accepts on `icon`. Outer wrapper is stripped; viewBox
+// and `currentColor` still apply (muted parent here). Decorative under the
+// headline — no `label`.
+import memberMark from '@/assets/svgs/user.svg?raw';
+</script>
+```
+
+### Sizing
+
+`size` takes the icon scale `xs`–`2xl`, a number (px), or a CSS dimension string
+(`"1.5rem"`, `"2em"`). The scale defaults to **12 / 16 / 24 / 28 / 36 / 40 px**
+(`xs`→`2xl`) and is the same scale `BbAvatar` and the icon-bearing components
+read; consumers can retune it **library-wide** via the plugin's
+`iconDefaultSizes` option (`config.iconDefaultSizes`), so prefer the named scale
+over hard pixel numbers to stay consistent with any override. An invalid `size`
+logs a warning and falls back to `md`.
+
+**The size scale**
+
+```vue
+<div class="flex items-end gap-3">
+	<BbIcon icon="lucide:rocket" size="xs" />
+	<BbIcon icon="lucide:rocket" size="sm" />
+	<BbIcon icon="lucide:rocket" size="md" />
+	<BbIcon icon="lucide:rocket" size="lg" />
+	<BbIcon icon="lucide:rocket" size="xl" />
+	<BbIcon icon="lucide:rocket" size="2xl" />
+</div>
 ```
+
+### Color: currentColor inheritance
+
+Icons paint in `currentColor`, so they inherit the **text color of their
+container**. Never set `color`/`fill` on the icon element — color the **parent**
+via a token-driven utility class (or a soft status accent mixed toward
+`--bb-panel` / `--bb-text`), and the glyph follows. The status legend and
+deploy-stages companions both color the row wrapper; the icon tracks it.
+
+### Config and platform
+
+- **`iconDefaultSizes`** (Vite plugin / Nuxt module) — remaps the `xs`–`2xl`
+  scale library-wide; the defaults above apply when unset.
+- **Plugin required** — `BbIcon` resolves names through the
+  `virtual:bitboss-ui/icons` module the platform plugin provides; without the
+  Vue/Nuxt/Inertia plugin installed it throws a "Failed to load icons" error.
+  Provider sets (`@iconify-json/*`) are auto-discovered from `node_modules`;
+  `local:*` comes from `iconDir` (default `./assets/icons` on Nuxt).
+- **SSR / Nuxt** — icons resolve during `onServerPrefetch`, so server-rendered
+  markup contains the glyph on first paint (no hydration flash). `BbIcon` carries
+  no navigation surface — it is a pure visual primitive.
+
+### Works well with
+
+- `BbButton` / `BbBadge` / inputs / `BbAlert` — prefer their icon
+  props over a hand-placed `BbIcon`; the host sizes and aligns the glyph.
+- `BbTabs` / `BbBreadcrumbs` / `BbRating` / `BbSwitch` — the slot surfaces where
+  `BbIcon` is the intended way to inject a glyph (no icon field on their items).
+- `BbAvatar` — shares the `iconDefaultSizes` scale, so icon and avatar sizes line
+  up on the same scale keys.
+
+### Gotchas & anti-patterns
+
+- Hand-placing `BbIcon` where a component already accepts an icon via a prop or
+  item field (only slots without an icon field are fair game).
+- Runtime-composed names (template strings / concatenation) — invisible to the
+  build scanner, broken in production. Use a lookup of full literals.
+- Setting `color`/`fill` on the icon element instead of on the parent container.
+- Wrapping `BbIcon` in a raw `<button>` — use `BbButton` with `icon` plus a
+  label (default slot or `text`; `aria-label` only to override that name).
+- Inventing icon names or assuming a provider set is installed without checking
+  `package.json`.
+
+### Accessibility
+
+A meaningful icon needs a `label`: it adds `role="img"` and an `aria-label` —
+no native `title`, so no browser tooltip ever appears; when a hover tooltip is
+wanted, attach the `v-bb-tooltip` directive. Omit `label` for **decorative** icons that
+sit beside a visible text label, so assistive tech does not announce the same
+thing twice. `BbIcon` is **never focusable** (`focusable="false"` is always set)
+— it is not interactive; interactivity belongs to the `BbButton`/`BbBaseButton`
+wrapping it.
+
+**Meaningful vs decorative**
+
+```vue
+<div class="flex items-center gap-3">
+	<BbIcon icon="lucide:triangle-alert" size="lg" label="Warning" />
+	<BbIcon icon="lucide:star" size="lg" />
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `icon` | `string` |  | yes | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
+| `label` | `string \| undefined` |  |  | Label of the icon for accessibility. |
+| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
+
+## Events
+
+- None.
+
+## Slots
+
+- None.
+
+## See Also
+
+- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
+- [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.