bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/source/GuidesComponent.md

@@ -0,0 +1,383 @@
+# GuidesComponent — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../GuidesComponent.md](../GuidesComponent.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<section aria-label="Component examples showcase" class="guides-component">
+		<header class="guides-component__header">
+			<div class="guides-component__intro">
+				<h2 class="guides-component__title">Component guides</h2>
+				<p class="guides-component__subtitle">
+					Companion SFCs from
+					<code class="guides-component__code">examples/*.vue</code>
+					— live preview and extractable source for AI and humans.
+				</p>
+			</div>
+
+			<div v-if="guideExamples.length" class="guides-component__controls">
+				<label
+					class="guides-component__select-label"
+					for="guides-component-select"
+				>
+					Component
+				</label>
+				<select
+					id="guides-component-select"
+					v-model="selectedComponentName"
+					class="guides-component__select"
+				>
+					<option
+						v-for="group in groupedGuideExamples"
+						:key="group.componentName"
+						:value="group.componentName"
+					>
+						{{ group.componentName }} ({{ group.examples.length }})
+					</option>
+				</select>
+			</div>
+		</header>
+
+		<p v-if="!guideExamples.length" class="guides-component__empty">
+			No example SFC files found.
+		</p>
+
+		<template v-else>
+			<nav
+				v-if="selectedComponentExamples.length"
+				aria-label="Component examples"
+				class="guides-component__tabs"
+				role="tablist"
+			>
+				<button
+					v-for="example in selectedComponentExamples"
+					:key="example.path"
+					:aria-label="`Open ${example.exampleName} example`"
+					:aria-selected="example.path === selectedExamplePath"
+					class="guides-component__tab"
+					:class="{
+						'guides-component__tab--active':
+							example.path === selectedExamplePath,
+					}"
+					role="tab"
+					tabindex="0"
+					type="button"
+					@click="onSelectExample(example.path)"
+					@keydown.enter="onSelectExample(example.path)"
+					@keydown.space.prevent="onSelectExample(example.path)"
+				>
+					{{ example.exampleName }}
+				</button>
+			</nav>
+
+			<section aria-live="polite" class="guides-component__content">
+				<template v-if="selectedExample">
+					<div class="guides-component__preview-card">
+						<div class="guides-component__panel-head">
+							<h3 class="guides-component__preview-title">Preview</h3>
+							<p class="guides-component__path">{{ selectedExample.path }}</p>
+						</div>
+						<div class="guides-component__preview">
+							<component :is="selectedExample.component" />
+						</div>
+					</div>
+
+					<div class="guides-component__source-card">
+						<div class="guides-component__panel-head">
+							<h3 class="guides-component__preview-title">Source</h3>
+						</div>
+						<pre
+							class="guides-component__source"
+							:data-example-path="selectedExample.path"
+						><code>{{ selectedExample.source }}</code></pre>
+					</div>
+				</template>
+			</section>
+		</template>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue';
+import type { Component } from 'vue';
+
+type ExampleRecord = {
+	path: string;
+	componentName: string;
+	exampleName: string;
+	component: Component;
+	source: string;
+};
+
+type ExampleGroup = {
+	componentName: string;
+	examples: ExampleRecord[];
+};
+
+const STORAGE_KEY_COMPONENT = 'guides-component:selected-component-name';
+const STORAGE_KEY_EXAMPLE = 'guides-component:selected-example-path';
+
+const componentModules = import.meta.glob<{ default: Component }>(
+	'/src/components/**/examples/*.vue',
+	{ eager: true }
+);
+
+const sourceModules = import.meta.glob<string>(
+	'/src/components/**/examples/*.vue',
+	{ eager: true, import: 'default', query: '?raw' }
+);
+
+const guideExamples = computed<ExampleRecord[]>(() => {
+	return Object.entries(componentModules)
+		.map(([path, module]) => {
+			const pathParts = path.split('/');
+			const componentName = pathParts[pathParts.length - 3] ?? 'Unknown';
+			const fileName = pathParts[pathParts.length - 1] ?? 'Example.vue';
+			const exampleName = fileName.replace(/\.vue$/u, '');
+
+			return {
+				path,
+				componentName,
+				exampleName,
+				component: module.default,
+				source: sourceModules[path] ?? '',
+			};
+		})
+		.sort(
+			(left, right) =>
+				left.componentName.localeCompare(right.componentName) ||
+				left.exampleName.localeCompare(right.exampleName)
+		);
+});
+
+const groupedGuideExamples = computed<ExampleGroup[]>(() => {
+	const groupedMap = new Map<string, ExampleRecord[]>();
+
+	for (const example of guideExamples.value) {
+		const group = groupedMap.get(example.componentName) ?? [];
+		group.push(example);
+		groupedMap.set(example.componentName, group);
+	}
+
+	return [...groupedMap.entries()]
+		.map(([componentName, examples]) => ({
+			componentName,
+			examples: [...examples].sort((left, right) =>
+				left.exampleName.localeCompare(right.exampleName)
+			),
+		}))
+		.sort((left, right) =>
+			left.componentName.localeCompare(right.componentName)
+		);
+});
+
+const selectedComponentName = ref('');
+const selectedExamplePath = ref('');
+
+const selectedComponentExamples = computed<ExampleRecord[]>(() => {
+	const selectedGroup = groupedGuideExamples.value.find(
+		(group) => group.componentName === selectedComponentName.value
+	);
+
+	return selectedGroup?.examples ?? [];
+});
+
+const selectedExample = computed<ExampleRecord | null>(() => {
+	if (!selectedComponentExamples.value.length) return null;
+
+	return (
+		selectedComponentExamples.value.find(
+			(example) => example.path === selectedExamplePath.value
+		) ?? selectedComponentExamples.value[0]
+	);
+});
+
+const onSelectExample = (examplePath: string): void => {
+	selectedExamplePath.value = examplePath;
+};
+
+const loadPersistedSelection = (storageKey: string): string | null => {
+	if (typeof window === 'undefined') return null;
+	return window.localStorage.getItem(storageKey);
+};
+
+const persistSelection = (storageKey: string, storageValue: string): void => {
+	if (!storageValue || typeof window === 'undefined') return;
+	window.localStorage.setItem(storageKey, storageValue);
+};
+
+const ensureValidSelectedExample = (): void => {
+	if (!selectedComponentExamples.value.length) return;
+	const hasCurrentExample = selectedComponentExamples.value.some(
+		(example) => example.path === selectedExamplePath.value
+	);
+	if (hasCurrentExample) return;
+	selectedExamplePath.value = selectedComponentExamples.value[0].path;
+};
+
+onMounted(() => {
+	if (!groupedGuideExamples.value.length) return;
+
+	const persistedComponentName = loadPersistedSelection(STORAGE_KEY_COMPONENT);
+	const hasPersistedComponent = groupedGuideExamples.value.some(
+		(group) => group.componentName === persistedComponentName
+	);
+	selectedComponentName.value = hasPersistedComponent
+		? (persistedComponentName as string)
+		: groupedGuideExamples.value[0].componentName;
+
+	const persistedExamplePath = loadPersistedSelection(STORAGE_KEY_EXAMPLE);
+	const hasPersistedExample = selectedComponentExamples.value.some(
+		(example) => example.path === persistedExamplePath
+	);
+	selectedExamplePath.value = hasPersistedExample
+		? (persistedExamplePath as string)
+		: selectedComponentExamples.value[0].path;
+});
+
+watch(selectedComponentName, () => {
+	ensureValidSelectedExample();
+	persistSelection(STORAGE_KEY_COMPONENT, selectedComponentName.value);
+});
+
+watch(selectedExamplePath, (examplePath) => {
+	persistSelection(STORAGE_KEY_EXAMPLE, examplePath);
+});
+</script>
+
+<style scoped lang="postcss">
+.guides-component {
+	@apply overflow-hidden border text-[color:var(--bb-text)];
+	background: var(--bb-panel);
+	border-color: var(--bb-border);
+	border-radius: var(--bb-radius-surface);
+	box-shadow: var(--bb-shadow);
+}
+
+.guides-component__header {
+	@apply flex flex-col gap-4 border-b p-4 sm:flex-row sm:items-end sm:justify-between sm:gap-6;
+	background: color-mix(in oklab, var(--bb-muted) 60%, var(--bb-panel));
+	border-color: var(--bb-border);
+}
+
+.guides-component__intro {
+	@apply min-w-0 flex-1;
+}
+
+.guides-component__title {
+	@apply text-[15px] font-semibold tracking-[-0.01em];
+}
+
+.guides-component__subtitle {
+	@apply mt-1 max-w-2xl text-[13px] leading-snug;
+	color: var(--bb-text-muted);
+}
+
+.guides-component__code {
+	@apply rounded px-1 py-0.5 font-mono text-[13px];
+	background: var(--bb-muted);
+	color: var(--bb-text);
+}
+
+.guides-component__controls {
+	@apply flex w-full flex-col gap-1.5 sm:w-72;
+}
+
+.guides-component__select-label {
+	@apply text-[11px] font-semibold uppercase tracking-[0.06em];
+	color: var(--bb-text-muted);
+}
+
+.guides-component__select {
+	@apply w-full px-3 py-2 text-sm outline-none;
+	background: var(--bb-panel);
+	border: var(--bb-border-w) solid var(--bb-border);
+	border-radius: var(--bb-radius);
+	color: var(--bb-text);
+}
+
+.guides-component__select:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+}
+
+.guides-component__tabs {
+	@apply flex items-center gap-1 overflow-x-auto border-b px-3 py-2;
+	background: var(--bb-panel);
+	border-color: var(--bb-border);
+}
+
+.guides-component__tab {
+	@apply whitespace-nowrap px-2.5 py-1.5 text-[13px] transition-colors;
+	border-radius: var(--bb-radius);
+	color: var(--bb-text-muted);
+}
+
+.guides-component__tab:hover {
+	background: var(--bb-hover);
+	color: var(--bb-text);
+}
+
+.guides-component__tab--active {
+	@apply font-semibold;
+	background: var(--bb-muted);
+	color: var(--bb-text);
+}
+
+.guides-component__tab:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+	outline: none;
+}
+
+.guides-component__content {
+	@apply grid gap-0 lg:grid-cols-2;
+	background: #fafafa;
+}
+
+.guides-component__preview-card,
+.guides-component__source-card {
+	@apply min-w-0 p-4;
+}
+
+.guides-component__preview-card {
+	@apply border-b lg:border-b-0 lg:border-r;
+	border-color: var(--bb-border);
+}
+
+.guides-component__panel-head {
+	@apply mb-3;
+}
+
+.guides-component__preview-title {
+	@apply text-[11px] font-semibold uppercase tracking-[0.06em];
+	color: var(--bb-text-muted);
+}
+
+.guides-component__path {
+	@apply mt-0.5 truncate font-mono text-[11px];
+	color: var(--bb-text-faint);
+}
+
+.guides-component__preview {
+	@apply p-4;
+	background: var(--bb-panel);
+	border: var(--bb-border-w) solid var(--bb-border);
+	border-radius: var(--bb-radius-surface);
+}
+
+.guides-component__source {
+	@apply m-0 max-h-[28rem] overflow-auto p-3 font-mono text-[13px] leading-relaxed;
+	background: color-mix(in oklab, var(--bb-text) 90%, transparent);
+	border-radius: var(--bb-radius);
+	color: color-mix(in oklab, var(--bb-panel) 90%, white);
+}
+
+.guides-component__empty {
+	@apply p-4 text-sm;
+	color: var(--bb-text-muted);
+}
+</style>
+```

package/dist/ai/source/ListBox.md

@@ -0,0 +1,238 @@
+# ListBox — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../ListBox.md](../ListBox.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<GroupedListBox
+		v-if="groups"
+		ref="child"
+		:compact="compact"
+		:groups="groups"
+		:header-height="headerHeight"
+		:loading="loading"
+		:loading-text="loadingText"
+		:multiple="multiple"
+		:no-data-text="noDataText"
+		:open="open"
+		:option-height="optionHeight"
+		:transition-duration="transitionDuration"
+		@focused:change="$emit('focused:change', $event)"
+		@option:selected="$emit('option:selected', $event)"
+		@option:unselected="$emit('option:unselected', $event)"
+	>
+		<template #options:prepend><slot name="options:prepend" /></template>
+		<template #loading><slot name="loading" /></template>
+		<template #no-data><slot name="no-data" /></template>
+		<template #options:append><slot name="options:append" /></template>
+		<template #option="data"><slot name="option" v-bind="data" /></template>
+		<template #group="data"><slot name="group" v-bind="data" /></template>
+	</GroupedListBox>
+	<FlatListBox
+		v-else
+		ref="child"
+		:compact="compact"
+		:loading="loading"
+		:loading-text="loadingText"
+		:multiple="multiple"
+		:no-data-text="noDataText"
+		:open="open"
+		:option-height="optionHeight"
+		:options="options ?? []"
+		:transition-duration="transitionDuration"
+		@focused:change="$emit('focused:change', $event)"
+		@option:selected="$emit('option:selected', $event)"
+		@option:unselected="$emit('option:unselected', $event)"
+	>
+		<template #options:prepend><slot name="options:prepend" /></template>
+		<template #loading><slot name="loading" /></template>
+		<template #no-data><slot name="no-data" /></template>
+		<template #options:append><slot name="options:append" /></template>
+		<template #option="data"><slot name="option" v-bind="data" /></template>
+	</FlatListBox>
+</template>
+
+<script setup lang="ts" generic="Item = any">
+import { ref } from 'vue';
+import type { Option } from '@/types/Option';
+import type {
+	ListBoxExposed,
+	ListBoxProps,
+	ListBoxEvents,
+	ListBoxSlots,
+} from './types';
+export type { ListBoxExposed, ListBoxProps, ListBoxEvents, ListBoxSlots };
+import FlatListBox from '../FlatListBox/FlatListBox.vue';
+import GroupedListBox from '../GroupedListBox/GroupedListBox.vue';
+
+defineProps<ListBoxProps<Item>>();
+
+defineEmits<ListBoxEvents>();
+
+defineSlots<ListBoxSlots<Item>>();
+
+const child = ref<ListBoxExposed>();
+
+defineExpose({
+	focusNext: () => child.value?.focusNext(),
+	focusPrevious: () => child.value?.focusPrevious(),
+	focusFirst: () => child.value?.focusFirst(),
+	focusFirstSelected: () => child.value?.focusFirstSelected(),
+	focusLast: () => child.value?.focusLast(),
+	focusLastSelected: () => child.value?.focusLastSelected(),
+	blur: () => child.value?.blur(),
+	confirmOption: () => child.value?.confirmOption(),
+	focusByHash: (hash: Option['valueHash']) => child.value?.focusByHash(hash),
+	getHighlighted: () => child.value?.getHighlighted(),
+	getActiveDescendantId: () => child.value?.getActiveDescendantId(),
+});
+</script>
+```
+
+## Types
+
+```ts
+import type { GroupedOptions, Option } from '@/types/Option';
+
+export type ListBoxExposed = {
+	focusNext: () => void;
+	focusPrevious: () => void;
+	focusFirst: () => void;
+	focusFirstSelected: () => void;
+	focusLast: () => void;
+	focusLastSelected: () => void;
+	blur: () => void;
+	confirmOption: () => void;
+	focusByHash: (hash: Option['valueHash']) => void;
+	getHighlighted: () => Option | undefined;
+	getActiveDescendantId: () => string | undefined;
+};
+
+export type ListBoxProps<Item = any> = {
+	/**
+	 * Sets the listbox in a compact state.
+	 */
+	compact?: boolean;
+	/**
+	 * Flat option list. Used when `groups` is not provided.
+	 */
+	options?: Array<Option<Item>>;
+	/**
+	 * Grouped option list. When provided, the grouped listbox is rendered.
+	 */
+	groups?: GroupedOptions[];
+	/**
+	 * Height of group headers in the listbox (px).
+	 */
+	headerHeight?: number;
+	/**
+	 * Whether the listbox is open (visible).
+	 */
+	open?: boolean;
+	/**
+	 * Shows the listbox in a loading state.
+	 */
+	loading?: boolean;
+	/**
+	 * Allows multiple options to be selected simultaneously.
+	 */
+	multiple?: boolean;
+	/**
+	 * Duration of open/close transition in milliseconds.
+	 */
+	transitionDuration?: number;
+	/**
+	 * Text shown while options are loading.
+	 */
+	loadingText?: string;
+	/**
+	 * Text shown when no options are available.
+	 */
+	noDataText?: string;
+	/**
+	 * Fixed height (in px) for each option row. Defaults to 40px (32px in compact mode).
+	 */
+	optionHeight?: number;
+};
+
+export type ListBoxEvents = {
+	/**
+	 * Emitted when an option is selected by the user.
+	 * @param option - The selected option.
+	 */
+	(e: 'option:selected', option: Option): void;
+	/**
+	 * Emitted when a previously selected option is deselected.
+	 * @param option - The deselected option.
+	 */
+	(e: 'option:unselected', option: Option): void;
+	/**
+	 * Emitted when the keyboard-focused option changes.
+	 * @param id - The accessible id of the focused option, or `undefined` when focus is cleared.
+	 */
+	(e: 'focused:change', id: string | undefined): void;
+};
+
+/** Props exposed by the `option` slot. */
+export type ListBoxOptionSlotProps<Item = any> = {
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** Whether this option currently has keyboard focus. */
+	focused: boolean;
+	/** Zero-based index of this option in the full list. */
+	index: number;
+	/** The raw item from the source list. */
+	item: Item;
+	/** Whether this option is currently selected. */
+	selected: boolean;
+	/** The resolved display text for this option. */
+	text: string;
+	/** The resolved value for this option. */
+	value: any;
+};
+
+/** Props exposed by the `group` slot (only used when `groups` is provided). */
+export type ListBoxGroupSlotProps<Item = any> = {
+	/** The display label for this group. */
+	text: string;
+	/** The raw group data item. */
+	item: Item;
+	/** Zero-based index of this group's first option. */
+	index: number;
+	/** Number of options in this group. */
+	length: number;
+	/** Whether all options in this group are disabled. */
+	disabled: boolean;
+};
+
+export type ListBoxSlots<Item = any> = {
+	/**
+	 * Content prepended inside the options list, before the first option or group.
+	 */
+	'options:prepend'?: (props: object) => any;
+	/**
+	 * Content shown while items are loading (replaces the default loading text).
+	 */
+	loading?: (props: object) => any;
+	/**
+	 * Content shown when no options are available (replaces the default "no data" text).
+	 */
+	'no-data'?: (props: object) => any;
+	/**
+	 * Replaces the default rendering of each option row.
+	 */
+	option?: (props: ListBoxOptionSlotProps<Item>) => any;
+	/**
+	 * Replaces the default group header (only used when `groups` is provided).
+	 */
+	group?: (props: ListBoxGroupSlotProps<Item>) => any;
+	/**
+	 * Content appended inside the options list, after the last option or group.
+	 */
+	'options:append'?: (props: object) => any;
+};
+```