bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/source/BbTree.md

@@ -0,0 +1,323 @@
+# BbTree — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbTree.md](../BbTree.md).
+
+## Template & Script
+
+```vue
+<template>
+	<!--
+	No `role="tree"`. BbTree is a nested **disclosure list**, not a WAI-ARIA tree:
+	each branch is a consumer-owned button (`expandProps`) that shows/hides its
+	children region. An APG tree makes the treeitem itself the single focusable
+	unit under a roving tabindex, which is irreconcilable with a slot-driven
+	component whose nodes hold the consumer's own links and buttons. Declaring the
+	role without its keyboard contract is worse than declaring nothing — it puts
+	AT into tree mode and promises Arrow/Home/End navigation that does not exist.
+	-->
+	<div class="bb-tree">
+		<BbTreeLevel :depth="0" :expandable="expandable" :items="items">
+			<template v-for="(_, name) in $slots" #[name]="data: any">
+				<slot :name="name" v-bind="data" />
+			</template>
+		</BbTreeLevel>
+	</div>
+</template>
+
+<script setup lang="ts" generic="Meta">
+import { provide, watch } from 'vue';
+import BbTreeLevel from './BbTreeLevel.vue';
+import { BbTreeContextKey, type BbTreeContext } from './context';
+import { useIndexById } from '@/composables/useIndexById';
+import { flattenTree } from '@/utilities/functions/flattenTree';
+import { hash } from '@/utilities/functions/hash';
+import type {
+	BbTreeEvents,
+	BbTreeItem,
+	BbTreeNodeSlotProps,
+	BbTreeProps,
+	BbTreeSlots,
+	TreeItem,
+} from './types';
+export type {
+	BbTreeEvents,
+	BbTreeItem,
+	BbTreeNodeSlotProps,
+	BbTreeProps,
+	BbTreeSlots,
+	TreeItem,
+};
+
+/**
+ * Live expansion state: the list of expanded node values (see `itemValue`).
+ * Branch nodes not explicitly collapsed via `expanded: false` seed the list
+ * when they first appear in `items`; from then on this model is the single
+ * source of truth.
+ *
+ * @defaultValue `[]`
+ */
+const expandedItems = defineModel<any[]>('expandedItems', {
+	required: false,
+	default: () => [],
+});
+
+const props = withDefaults(defineProps<BbTreeProps<Meta>>(), {
+	items: () => [],
+});
+
+defineSlots<BbTreeSlots<Meta>>();
+
+const { data: expandedItemsIndexedByHash } = useIndexById({
+	items: expandedItems,
+});
+
+const valueFor = (item: BbTreeItem<Meta>) => {
+	if (typeof props.itemValue === 'function') return props.itemValue(item.meta);
+	if (typeof props.itemValue === 'string')
+		return (item.meta as Record<string, any>)?.[props.itemValue];
+	return item.meta;
+};
+
+const hashFor = (item: BbTreeItem<Meta>) => hash(valueFor(item));
+
+/* Leaves have nothing to hide, so they always count as expanded. */
+const isExpanded = (item: BbTreeItem<Meta>) =>
+	!item.children?.length || hashFor(item) in expandedItemsIndexedByHash.value;
+
+const toggleExpanded = (item: BbTreeItem<Meta>) => {
+	const value = valueFor(item);
+	const valueHash = hash(value);
+	expandedItems.value =
+		valueHash in expandedItemsIndexedByHash.value
+			? expandedItems.value.filter((entry) => hash(entry) !== valueHash)
+			: [...expandedItems.value, value];
+};
+
+provide(BbTreeContextKey, {
+	valueFor,
+	hashFor,
+	isExpanded,
+	toggleExpanded,
+} as BbTreeContext);
+
+/*
+ * `item.expanded` is the initial state only: branch nodes join the model the
+ * first time they are seen, unless collapsed with `expanded: false` or
+ * already tracked. Later flips of the flag are ignored — the model owns the
+ * live state.
+ */
+const seeded = new Set<string>();
+watch(
+	() => props.items,
+	(items) => {
+		const additions: any[] = [];
+		for (const node of flattenTree<BbTreeItem<Meta>, BbTreeItem<Meta>>(
+			items ?? [],
+			'children'
+		)) {
+			const nodeHash = hashFor(node);
+			if (seeded.has(nodeHash)) continue;
+			seeded.add(nodeHash);
+			if (!node.children?.length) continue;
+			if (node.expanded === false) continue;
+			if (nodeHash in expandedItemsIndexedByHash.value) continue;
+			additions.push(valueFor(node));
+		}
+		if (additions.length)
+			expandedItems.value = [...expandedItems.value, ...additions];
+	},
+	{ deep: true, immediate: true }
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { ItemAccessor } from '@/types/ItemAccessor';
+
+/**
+ * A node of the tree. The structure is fixed (`meta` / `children` /
+ * `expanded` / `expandable`) so the component can reason about the tree,
+ * while `meta` carries any consumer data and flows to slots fully typed.
+ */
+export type BbTreeItem<Meta = any> = {
+	/**
+	 * Consumer data for this node. Passed to every node slot as `meta`,
+	 * typed from the `items` you provide.
+	 */
+	meta: Meta;
+	/**
+	 * Child nodes. A node with children is a branch; a node without
+	 * children is a leaf and always renders as expanded.
+	 */
+	children?: Array<BbTreeItem<Meta>>;
+	/**
+	 * Initial expansion state for branch nodes. Defaults to expanded.
+	 * The live state is `v-model:expandedItems`: branch nodes not
+	 * explicitly collapsed seed the model when they first appear.
+	 */
+	expanded?: boolean;
+	/**
+	 * Per-node override of the tree-level `expandable`.
+	 */
+	expandable?: BbTreeExpandable<Meta>;
+};
+
+/**
+ * @deprecated Use `BbTreeItem` instead.
+ */
+export type TreeItem<Meta = any> = BbTreeItem<Meta>;
+
+export type BbTreeExpandable<Meta = any> =
+	| boolean
+	| ((
+			item: BbTreeItem<Meta>,
+			depth: number,
+			parent?: BbTreeItem<Meta>
+	  ) => boolean);
+
+export type BbTreeProps<Meta = any> = {
+	/**
+	 * Tree-like structure of nodes to render.
+	 *
+	 * @defaultValue `[]`
+	 */
+	items: Array<BbTreeItem<Meta>>;
+	/**
+	 * Identity of a node, used to hash entries of `expandedItems` and to
+	 * name per-node slots. A string reads that key from `meta`; a function
+	 * receives `meta` and returns the value.
+	 *
+	 * @defaultValue the whole `meta` object
+	 */
+	itemValue?: ItemAccessor<Meta>;
+	/**
+	 * Defines nodes as expandable. It can be a global boolean, or a function
+	 * that receives the node, its depth, and its parent and returns a boolean.
+	 */
+	expandable?: BbTreeExpandable<Meta>;
+};
+
+export type BbTreeEvents =
+	/**
+	 * Emitted when the expansion state changes. The payload is the list of
+	 * expanded node values (see `itemValue`), usable with
+	 * `v-model:expandedItems`.
+	 */
+	(e: 'update:expandedItems', value: any[]) => void;
+
+/**
+ * Bind these onto an expand-toggle element to wire up click handling,
+ * aria attributes, and keyboard support.
+ *
+ * This is the disclosure control: it owns `aria-expanded` and points
+ * `aria-controls` at the node's children region. `BbTree` is a nested
+ * disclosure list, not a WAI-ARIA tree, so this button — not the node
+ * container — is the element that carries the expansion semantics.
+ */
+export type BbTreeExpandControllerProps = {
+	'aria-controls'?: string;
+	'aria-expanded': 'true' | 'false';
+	onClick: (event: MouseEvent) => void;
+	onKeydown: (event: KeyboardEvent) => void;
+};
+
+/** Props exposed by all tree node slots. */
+export type BbTreeNodeSlotProps<Meta = any> = {
+	/** The typed `meta` of this node. */
+	meta: Meta;
+	/** The full node, including `children`. */
+	item: BbTreeItem<Meta>;
+	/** The parent node, or `undefined` for root-level nodes. */
+	parent?: BbTreeItem<Meta>;
+	/** Zero-based index of this node among its siblings. */
+	index: number;
+	/** Nesting depth of this node, starting at `0` for the root level. */
+	depth: number;
+	/** The resolved identity of this node (see `itemValue`). */
+	value: any;
+	/** Whether this node is currently expanded (children visible). */
+	expanded: boolean;
+	/** Whether this node can be expanded. */
+	expandable: boolean;
+	/** Toggles the expanded state for this node. */
+	toggleExpanded: () => void;
+	/** Bind these onto an expand-toggle element for aria + keyboard wiring. */
+	expandProps: BbTreeExpandControllerProps;
+};
+
+export type BbTreeSlots<Meta = any> = {
+	/**
+	 * Named slots for tree nodes, resolved in priority order: `{value}`
+	 * (specific node, when its resolved value is a string or number),
+	 * `{depth}` (all nodes at that depth), `{value}-children` /
+	 * `{depth}-children` (children container), or `default`. The `{value}`
+	 * token is normalized (`slotKey`: spaces/punctuation → `_`, dashes kept,
+	 * lowercased), so a node valued `"In Progress"` is targeted by
+	 * `#in_progress`.
+	 */
+	[key: string]: ((props: BbTreeNodeSlotProps<Meta>) => any) | undefined;
+	default?: (props: BbTreeNodeSlotProps<Meta>) => any;
+};
+
+/**
+ * Internal recursion plumbing for `BbTreeLevel`. Not part of the public
+ * `BbTree` surface.
+ */
+export type BbTreeLevelProps<Meta = any> = {
+	items: Array<BbTreeItem<Meta>>;
+	depth: number;
+	parent?: BbTreeItem<Meta>;
+	expandable?: BbTreeExpandable<Meta>;
+};
+```
+
+## Styles
+
+```css
+.bb-tree {
+	/*
+	 * Layout knobs, sealed on the root. `--indent` shifts every children
+	 * container; `--gap` adds vertical rhythm between sibling nodes. Both
+	 * default to zero so the tree is layout-neutral out of the box.
+	 */
+	--indent: 0px;
+	--gap: 0px;
+
+	.bb-tree__node {
+		display: grid;
+		grid-template-rows: min-content 0fr;
+		transition: grid-template-rows var(--bb-transition-medium) var(--bb-ease);
+
+		& + .bb-tree__node {
+			margin-top: var(--gap);
+		}
+
+		&.bb-tree__node--expanded {
+			grid-template-rows: min-content 1fr;
+		}
+
+		> .bb-tree__row {
+			display: flex;
+
+			> .bb-tree__content {
+				flex-grow: 1;
+			}
+		}
+
+		> .bb-tree__children {
+			overflow: hidden;
+			padding-left: var(--indent);
+
+			> .bb-tree__node:first-child {
+				margin-top: var(--gap);
+			}
+		}
+	}
+}
+```

package/dist/ai/source/ChipsBox.md

@@ -0,0 +1,201 @@
+# ChipsBox — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../ChipsBox.md](../ChipsBox.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<!-- One badge per selection: `clearable` (removable) when interactive,
+	non-removable in disabled/readonly boxes. -->
+	<BbBadge
+		v-for="(item, index) in options"
+		:key="item.valueHash"
+		class="bb-chipsbox-item"
+		:class="{
+			'bb-badge--focused': !disabled && index === focusedIndex,
+		}"
+		:clearable="!disabled"
+		:size="size"
+		variant="secondary"
+		@click:clear.stop="emit('option:unselected', item)"
+		>{{ item.text }}</BbBadge
+	>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { hash } from '@/utilities/functions/hash';
+import { isNil } from '@/utilities/functions/isNil';
+import { ref } from 'vue';
+import { watch } from 'vue';
+import BbBadge from '../BbBadge/BbBadge.vue';
+import type { Option } from '@/types/Option';
+import type { ChipsBoxProps, ChipsBoxEvents } from './types';
+export type { ChipsBoxProps, ChipsBoxEvents };
+
+const props = defineProps<ChipsBoxProps>();
+
+const emit = defineEmits<ChipsBoxEvents>();
+
+/**
+ * START FOCUS HANDLING
+ */
+
+const focusedIndex = ref<null | number>(null);
+
+const canFocus = computed(() => props.options.some((o) => !o.disabled));
+
+const findNextAvailableIndex = (offset = 1) => {
+	const initialValue = isNil(focusedIndex.value) ? -1 : focusedIndex.value!;
+	let newIndex = (initialValue + offset) % props.options.length;
+	while (props.options[newIndex].disabled && newIndex !== initialValue) {
+		newIndex = findNextAvailableIndex(offset + 1);
+	}
+	return newIndex;
+};
+
+const focusNext = () => {
+	if (!canFocus.value) return;
+	const newIndex = findNextAvailableIndex();
+	focusedIndex.value = newIndex;
+};
+const findPreviousAvailableIndex = (offset = 1) => {
+	const initialValue = isNil(focusedIndex.value) ? 0 : focusedIndex.value!;
+	let newIndex =
+		(initialValue - offset + props.options.length) % props.options.length;
+	while (props.options[newIndex].disabled && newIndex !== initialValue) {
+		newIndex = findPreviousAvailableIndex(offset + 1);
+	}
+	return newIndex;
+};
+const focusPrevious = async () => {
+	if (!canFocus.value) return;
+	const newIndex = findPreviousAvailableIndex();
+	focusedIndex.value = newIndex;
+};
+
+const focusFirst = () => {
+	if (!canFocus.value) return;
+	let newIndex = 0;
+	while (props.options[newIndex].disabled) {
+		newIndex++;
+	}
+	focusedIndex.value = newIndex;
+};
+
+const focusLast = () => {
+	if (!canFocus.value) return;
+	let newIndex = props.options.length - 1;
+	while (props.options[newIndex].disabled && newIndex !== 0) {
+		newIndex--;
+	}
+	focusedIndex.value = newIndex;
+};
+const focusFirstSelected = () => {
+	if (!canFocus.value) return;
+	const index = props.options.findIndex((o) => o.selected);
+	// No selected option → clear the highlight instead of focusing an arbitrary
+	// one (a subsequent confirmOption would otherwise act on an unselected item).
+	focusedIndex.value = index >= 0 ? index : null;
+};
+const focusLastSelected = () => {
+	if (!canFocus.value) return;
+	let index = -1;
+	for (let i = props.options.length - 1; i >= 0; i--) {
+		if (props.options[i].selected) {
+			index = i;
+			break;
+		}
+	}
+	focusedIndex.value = index >= 0 ? index : null;
+};
+
+const focusByHash = (hash: Option['valueHash']) => {
+	if (!canFocus.value) return;
+	const linkedOptionIndex = props.options.findIndex(
+		(o) => o.valueHash === hash
+	);
+	if (linkedOptionIndex >= 0) {
+		focusedIndex.value = linkedOptionIndex;
+	}
+};
+
+const blur = () => {
+	focusedIndex.value = null;
+};
+
+/**
+ * END FOCUS HANDLING
+ */
+
+const confirmOption = () => {
+	if (isNil(focusedIndex.value)) return;
+	const option = props.options[focusedIndex.value!];
+	if (option.selected) {
+		emit('option:unselected', option);
+	}
+};
+
+const getHighlighted = () => {
+	if (isNil(focusedIndex.value)) return;
+	const option = props.options[focusedIndex.value!];
+	return option;
+};
+
+watch(
+	() => props.options,
+	(value, previous) => {
+		if (hash(value) !== hash(previous)) {
+			blur();
+		}
+	},
+	{
+		flush: 'post',
+	}
+);
+
+defineExpose({
+	focusNext,
+	focusPrevious,
+	focusFirst,
+	focusFirstSelected,
+	focusLast,
+	focusLastSelected,
+	blur,
+	confirmOption,
+	focusByHash,
+	getHighlighted,
+});
+</script>
+```
+
+## Types
+
+```ts
+import type { Option } from '@/types/Option';
+
+export type ChipsBoxProps = {
+	/**
+	 * Whether the component is disabled.
+	 */
+	disabled?: boolean;
+	/**
+	 * List of options to render as chips.
+	 */
+	options: Option[];
+	/**
+	 * The size of the chips.
+	 */
+	size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+};
+
+export type ChipsBoxEvents =
+	/**
+	 * Emitted when the user clears (removes) an option chip.
+	 * @param option - The option that was unselected.
+	 */
+	(e: 'option:unselected', option: Option) => void;
+```

package/dist/ai/source/ClearableButton.md

@@ -0,0 +1,70 @@
+# ClearableButton — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../ClearableButton.md](../ClearableButton.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<button
+		:aria-label="props.label || t('common.clearLabel').value"
+		class="bb-clearable-button"
+		type="button"
+	>
+		<BbIcon :icon="clearIcon" />
+	</button>
+</template>
+
+<script setup lang="ts">
+import { useLocale } from '@/composables/useLocale';
+import BbIcon from '../BbIcon/BbIcon.vue';
+import clearIcon from '@/assets/svgs/clear.svg?raw';
+import type { ClearableButtonProps } from './types';
+
+const props = defineProps<ClearableButtonProps>();
+
+const { t } = useLocale();
+</script>
+
+<style lang="postcss">
+/* @inherit --ring-color — inherited from the host input, which themes its clear button */
+.bb-clearable-button {
+	align-items: center;
+	background: transparent;
+	border: 0;
+	border-radius: min(var(--bb-radius), 6px);
+	box-shadow: 0px 0px 0px 0px var(--ring-color);
+	display: inline-flex;
+	justify-content: center;
+	line-height: 0;
+	outline: 2px solid transparent;
+	outline-offset: 2px;
+	transition-duration: var(--bb-transition-fast);
+	transition-property:
+		color, background-color, border-color, text-decoration-color, box-shadow;
+	transition-timing-function: var(--bb-ease);
+
+	&:focus-visible {
+		box-shadow: 0px 0px 0px var(--bb-ring-size) var(--ring-color);
+	}
+}
+</style>
+```
+
+## Types
+
+```ts
+export type ClearableButtonProps = {
+	/**
+	 * Accessible label announced by screen readers.
+	 * Falls back to localized `common.clearLabel` when omitted.
+	 */
+	label?: string;
+};
+
+export type ClearableButtonEvents = Record<never, never>;
+
+export type ClearableButtonSlots = Record<never, never>;
+```