bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/source/BbForm.md

@@ -0,0 +1,100 @@
+# BbForm — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbForm.md](../BbForm.md).
+
+## Template & Script
+
+```vue
+<template>
+	<!--
+		`novalidate` is deliberate, not an oversight: vee-validate owns validation
+		here. Without it the browser's own constraint validation runs FIRST on any
+		field carrying a native `required`/`type="email"`/`min`, blocks the submit
+		event before this handler ever sees it, and shows a native bubble — so the
+		form's real messages never render and `@submit` silently never fires.
+		One validation system, one set of messages.
+	-->
+	<form ref="formEl" novalidate @submit="onSubmit">
+		<slot
+			:is-submitting="isSubmitting"
+			:reset-form="resetForm"
+			:submit-count="submitCount"
+			:validate="validate"
+			:values="values"
+			v-bind="meta"
+		/>
+	</form>
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef } from 'vue';
+import { useForm } from 'vee-validate';
+import { useBbFormContextHost } from '@/composables/useBbFormContext';
+
+const props = defineProps<{
+	/**
+	 * Explicit id, so anything outside the form can read and drive it through
+	 * `useBbFormContext(id)` — a dialog footer's submit button, a page toolbar,
+	 * a leave guard. Omit it when the form is self-contained: the slot scope
+	 * already carries the same state for chrome that lives inside.
+	 */
+	id?: string;
+}>();
+
+const emit = defineEmits<{
+	/** Fired only when every field passes; carries the collected form values. */
+	submit: [values: Record<string, unknown>];
+}>();
+
+const {
+	handleSubmit,
+	isSubmitting,
+	submitCount,
+	resetForm,
+	meta,
+	values,
+	errors,
+	validate,
+} = useForm();
+
+// Validates all fields on native submit; emits `submit` with the values only
+// when the form is valid (and preventDefault's the native navigation).
+const onSubmit = handleSubmit((formValues) => emit('submit', formValues));
+
+/**
+ * The rendered `<form>`, exposed as `$el` the way `BbButton` does it.
+ *
+ * A template ref on a component yields the component instance, never a DOM
+ * node, so `form.value.requestSubmit()` would be `undefined` — publishing `$el`
+ * explicitly makes the native element reachable AND typed
+ * (`HTMLFormElement | null` instead of `any`), which the implicit `$el` is not.
+ *
+ * This is the ONLY thing exposed: state and actions live on
+ * `useBbFormContext(id)`, so there is no second, instance-shaped API to keep in
+ * step with it.
+ */
+const formEl = useTemplateRef<HTMLFormElement>('formEl');
+
+// `submit()` routes through the same `onSubmit` the submit button uses, so
+// validation gates it in exactly one place.
+useBbFormContextHost(() => props.id, {
+	state: () => ({
+		valid: meta.value.valid,
+		dirty: meta.value.dirty,
+		touched: meta.value.touched,
+		pending: meta.value.pending,
+		submitting: isSubmitting.value,
+		submitCount: submitCount.value,
+		values: { ...values },
+		errors: { ...errors.value },
+	}),
+	actions: {
+		submit: () => void onSubmit(),
+		reset: () => resetForm(),
+		validate: async () => (await validate()).valid,
+	},
+});
+
+defineExpose({ $el: formEl });
+</script>
+```

package/dist/ai/source/BbIcon.md

@@ -0,0 +1,212 @@
+# BbIcon — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbIcon.md](../BbIcon.md).
+
+## Template & Script
+
+```vue
+<template>
+	<!-- eslint-disable-next-line vue/no-v-html -- content is library-controlled SVG markup, never user input -->
+	<svg v-bind="iconAttributes" data-allow-mismatch v-html="content"></svg>
+</template>
+
+<script setup lang="ts">
+import {
+	computed,
+	inject,
+	ref,
+	onServerPrefetch,
+	onBeforeMount,
+	watch,
+} from 'vue';
+import { useLogger } from '@/composables/useLogger';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import { parseSize } from '@/utilities/functions/parseSize';
+import {
+	ICONS_INJECTION_KEY,
+	ICONS_LEGACY_KEY,
+	type IconRegistry,
+} from '@/utilities/misc/iconsInjectionKey';
+import { config } from 'virtual:bitboss-ui/config';
+import type { BbIconProps, BbIconSize } from './types';
+export type { BbIconProps, BbIconSize as Size };
+
+const props = withDefaults(defineProps<BbIconProps>(), {
+	size: 'md',
+});
+
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbIcon', removedPropsFor('BbIcon'));
+
+const logger = useLogger();
+const icons = ref<IconRegistry>();
+const icon = ref<string | null>(null);
+const content = computed(() => {
+	if (icon.value) {
+		return icon.value
+			.replace(/<\?xml[^?]*\?>/gi, '')
+			.replace(/<!DOCTYPE[^>]*>/gi, '')
+			.replace(/<\/?svg[^>]*>/gi, '');
+	}
+	return null;
+});
+
+const loadIcons = () => {
+	// Prefer the typed Symbol key; fall back to the legacy string key for one
+	// release so hand-rolled `provide('icons', …)` still resolves.
+	icons.value =
+		inject(ICONS_INJECTION_KEY) ?? inject<IconRegistry>(ICONS_LEGACY_KEY);
+	if (!icons.value) {
+		logger.throw(
+			'Failed to load icons. Make sure the plugin for your platform (Vue, Nuxt, or Inertia) is installed.'
+		);
+	}
+};
+
+const isSvgPayload = (value: string) => /<svg[\s>]/i.test(value);
+
+const getIcon = async () => {
+	if (isSvgPayload(props.icon)) {
+		icon.value = props.icon;
+		return;
+	}
+
+	if (!icons.value) {
+		logger.throw('Icons have not been loaded');
+	}
+
+	const key = props.icon.includes(':') ? props.icon : `local:${props.icon}`;
+	const iconLoader = icons.value![key];
+	if (!iconLoader) {
+		logger.throw(`Icon "${key}" does not exist.`);
+	}
+
+	icon.value = await iconLoader();
+};
+
+onServerPrefetch(async () => {
+	if (!isSvgPayload(props.icon)) loadIcons();
+	await getIcon();
+});
+
+onBeforeMount(async () => {
+	if (!icons.value && !isSvgPayload(props.icon)) {
+		loadIcons();
+	}
+	if (!icon.value) {
+		await getIcon();
+	}
+});
+
+watch(() => props.icon, getIcon);
+
+/**
+ * Computes the width of the icon in pixels based on the size prop.
+ * Supports configured size keys, numeric values, or custom CSS dimension strings.
+ */
+const iconWidth = computed(() => {
+	try {
+		return parseSize(props.size, config.iconDefaultSizes);
+	} catch {
+		logger.warn(
+			`Invalid size: "${props.size}" in BbIcon. Falling back to "md".`
+		);
+		return `${config.iconDefaultSizes.md}px`;
+	}
+});
+
+/**
+ * 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> = {
+		'--w': iconWidth.value,
+	};
+
+	const inheritedAttributes: Record<string, any> = {};
+	if (icon.value) {
+		const svgTag = icon.value.match(/<svg([^>]*)>/i);
+		if (svgTag) {
+			const attrRegex = /([\w-]+)="([^"]*)"/g;
+			let match;
+			while ((match = attrRegex.exec(svgTag[1])) !== 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();
+	} else {
+		// Decorative icon - hide it from assistive tech entirely
+		base['aria-hidden'] = 'true';
+	}
+
+	// Icons should never be focusable or keyboard navigable since they're not interactive
+	base['focusable'] = 'false';
+
+	return base;
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { Size as S } from '@/types/CommonProps';
+import type { IconType } from '@/types/Icon';
+import type { Sizes } from '@/types/SizeScale';
+
+export type BbIconSize = Sizes;
+
+export interface BbIconProps extends S<BbIconSize> {
+	/**
+	 * Label of the icon for accessibility.
+	 */
+	label?: string;
+	/**
+	 * Name of a registered icon to use, or a full raw `<svg>` string
+	 * (e.g. an SVG file imported with `?raw`).
+	 */
+	icon: IconType;
+}
+```
+
+## Styles
+
+```css
+.bb-icon {
+	/* `--w` is set inline by BbIcon from the size prop. The `initial` default
+	   seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge)
+	   would inherit in and size the icon. The `--size` indirection stays so
+	   higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. */
+	--w: initial;
+	--size: var(--w);
+	height: var(--size);
+	pointer-events: none;
+	width: var(--size);
+}
+```

package/dist/ai/source/BbIndicator.md

@@ -0,0 +1,298 @@
+# BbIndicator — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbIndicator.md](../BbIndicator.md).
+
+## Template & Script
+
+```vue
+<template>
+	<span :class="rootClasses">
+		<slot />
+		<!-- `appear` scales the bubble in on first render; it scales back out when
+		removed (e.g. a count dropping to zero). -->
+		<Transition appear name="bb-indicator-bubble">
+			<span
+				v-if="showIndicator"
+				:aria-atomic="props.dot ? undefined : 'true'"
+				:aria-hidden="props.dot || undefined"
+				:aria-live="props.dot ? undefined : 'polite'"
+				class="bb-indicator__indicator"
+				:role="props.dot ? undefined : 'status'"
+			>
+				<template v-if="!props.dot">{{ displayText }}</template>
+			</span>
+		</Transition>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useLogger } from '@/composables/useLogger';
+import { isNil } from '@/utilities/functions/isNil';
+import type { BbIndicatorProps, BbIndicatorSlots } from './types';
+
+const props = withDefaults(defineProps<BbIndicatorProps>(), {
+	size: 'md',
+	variant: 'default',
+});
+defineSlots<BbIndicatorSlots>();
+const logger = useLogger();
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const;
+
+const normalizedSize = computed(() => {
+	if (!SIZES.includes(props.size)) {
+		logger.warn(
+			`Invalid size: "${props.size}" in BbIndicator. Expected one of: ${SIZES.join(', ')}. Falling back to "md".`
+		);
+		return 'md';
+	}
+	return props.size;
+});
+
+// Render the bubble for a dot, or whenever textual content is present. A count
+// of `0` is content — consumers hide the indicator by omitting `text`.
+const showIndicator = computed(() => props.dot || !isNil(props.text));
+
+// Clamp numeric counts to `max`, rendering `${max}+` for overflow (e.g. `99+`).
+// Strings and non-positive maxes pass through untouched.
+const displayText = computed(() => {
+	if (
+		typeof props.text === 'number' &&
+		!isNil(props.max) &&
+		props.max > 0 &&
+		props.text > props.max
+	) {
+		return `${props.max}+`;
+	}
+	return props.text;
+});
+
+const rootClasses = computed(() => [
+	'bb-indicator',
+	`bb-indicator--${normalizedSize.value}`,
+	props.variant && `bb-indicator--${props.variant}`,
+	{
+		'bb-indicator--dot': props.dot,
+		'bb-indicator--bottom': props.bottom,
+		'bb-indicator--left': props.left,
+	},
+]);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { Sizes } from '@/types/SizeScale';
+import type { IndicatorVariantType } from '@/types/IndicatorVariant';
+
+export type BbIndicatorProps = {
+	/**
+	 * Content shown inside the indicator bubble. A `number` is accepted for count
+	 * ergonomics (e.g. `:text="unread"`). When omitted the indicator renders only
+	 * if `dot` is set.
+	 */
+	text?: string | number;
+	/**
+	 * Caps a numeric `text` count: values above `max` render as `${max}+`
+	 * (e.g. `max: 99` shows `99+`). Ignored for string `text`.
+	 */
+	max?: number;
+	/**
+	 * Renders a small contentless dot instead of a labelled bubble. Takes
+	 * precedence over `text`.
+	 */
+	dot?: boolean;
+	/**
+	 * Anchors the indicator to the bottom edge of the wrapped element instead of
+	 * the top.
+	 */
+	bottom?: boolean;
+	/**
+	 * Anchors the indicator to the left edge of the wrapped element instead of
+	 * the right.
+	 */
+	left?: boolean;
+	/**
+	 * Preset size of the indicator.
+	 * @defaultValue `md`
+	 */
+	size?: keyof Sizes;
+	/**
+	 * Visual variant. `default` uses the primary color; `success`, `info`,
+	 * `warning` and `destructive` map to the shared status colors.
+	 * Register more via the vite plugin `indicatorVariants` option and style
+	 * `.bb-indicator--<variant>`.
+	 * @defaultValue `'default'`
+	 */
+	variant?: IndicatorVariantType;
+};
+
+export type BbIndicatorSlots = {
+	/**
+	 * The element the indicator is anchored to.
+	 */
+	default?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+/* Anchored notification indicator. Wraps its default-slot element and paints a
+   positioned bubble (count/short text) or a dot over one corner. The color is
+   driven by local `--bg` / `--color` / `--border-*` tokens — override them on
+   the element (or via a class) for one-off colors, or use a `variant`. */
+.bb-indicator {
+	--bg: var(--bb-primary);
+	--color: var(--bb-primary-fg);
+	--radius: 999px;
+	--border-width: 0px;
+	--border-color: transparent;
+	--font-size: 10px;
+	--min-size: calc(var(--font-size) * 1.4);
+	--dot-size: 6px;
+	--gap: 3px;
+	--padding-inline: 4px;
+	--offset: calc(var(--min-size) * 0.35);
+	--dot-offset: calc(var(--dot-size) * 0.2);
+	--position-offset: var(--offset);
+
+	display: inline-flex;
+	position: relative;
+	width: fit-content;
+
+	/* ── Size variants ───────────────────────────────────── */
+	&.bb-indicator--xs {
+		--font-size: 8px;
+		--min-size: 12px;
+		--dot-size: 4px;
+		--gap: 2px;
+		--padding-inline: 3px;
+	}
+
+	&.bb-indicator--sm {
+		--font-size: 9px;
+		--min-size: 14px;
+		--dot-size: 5px;
+		--gap: 2px;
+		--padding-inline: 3px;
+	}
+
+	&.bb-indicator--lg {
+		--font-size: 11px;
+		--min-size: 18px;
+		--dot-size: 7px;
+		--padding-inline: 5px;
+	}
+
+	&.bb-indicator--xl {
+		--font-size: 12px;
+		--min-size: 20px;
+		--dot-size: 8px;
+		--padding-inline: 6px;
+	}
+
+	&.bb-indicator--2xl {
+		--font-size: 13px;
+		--min-size: 22px;
+		--dot-size: 9px;
+		--padding-inline: 6px;
+	}
+
+	/* ── The bubble ──────────────────────────────────────── */
+	& .bb-indicator__indicator {
+		align-items: center;
+		background-color: var(--bg);
+		border: var(--border-width) solid var(--border-color);
+		border-radius: var(--radius);
+		bottom: auto;
+		color: var(--color);
+		display: inline-flex;
+		font-size: var(--font-size);
+		font-weight: 500;
+		gap: var(--gap);
+		justify-content: center;
+		left: auto;
+		line-height: 1;
+		min-height: var(--min-size);
+		min-width: var(--min-size);
+		padding: 0 var(--padding-inline);
+		position: absolute;
+		right: calc(0% - var(--position-offset));
+		top: calc(0% - var(--position-offset));
+		transition:
+			color 0.2s,
+			background-color 0.2s;
+		white-space: nowrap;
+	}
+
+	/* Scale the bubble in on first render (`appear`) and whenever it (re)appears,
+	   and scale it back out when it is removed (e.g. a count dropping to zero). */
+	& .bb-indicator-bubble-enter-active,
+	& .bb-indicator-bubble-leave-active {
+		transition:
+			transform var(--bb-transition-fast) var(--bb-ease),
+			opacity var(--bb-transition-fast) var(--bb-ease);
+	}
+
+	& .bb-indicator-bubble-enter-from,
+	& .bb-indicator-bubble-leave-to {
+		opacity: 0;
+		transform: scale(0);
+	}
+
+	/* ── Position overrides ──────────────────────────────── */
+	&.bb-indicator--bottom .bb-indicator__indicator {
+		bottom: calc(0% - var(--position-offset));
+		top: auto;
+	}
+
+	&.bb-indicator--left .bb-indicator__indicator {
+		left: calc(0% - var(--position-offset));
+		right: auto;
+	}
+
+	/* ── Dot sub-mode ────────────────────────────────────── */
+	&.bb-indicator--dot {
+		--position-offset: var(--dot-offset);
+
+		& .bb-indicator__indicator {
+			border-radius: 999px;
+			min-height: var(--dot-size);
+			min-width: var(--dot-size);
+			padding: 0;
+		}
+	}
+
+	/* ── Variants (color tokens) ─────────────────────────── */
+	&.bb-indicator--default {
+		--bg: var(--bb-primary);
+		--color: var(--bb-primary-fg);
+	}
+
+	&.bb-indicator--success {
+		--bg: #16a34a;
+		--color: #fff;
+	}
+
+	&.bb-indicator--info {
+		--bg: #2563eb;
+		--color: #fff;
+	}
+
+	&.bb-indicator--warning {
+		--bg: #d97706;
+		--color: #fff;
+	}
+
+	&.bb-indicator--destructive {
+		--bg: var(--bb-danger);
+		--color: #fff;
+	}
+}
+```