bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/ListBox.md

@@ -0,0 +1,234 @@
+# ListBox
+
+## 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"
+		@option:selected="$emit('option:selected', $event)"
+		@option:unselected="$emit('option:unselected', $event)"
+		@focused:change="$emit('focused:change', $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"
+		:options="options ?? []"
+		:option-height="optionHeight"
+		:transition-duration="transitionDuration"
+		@option:selected="$emit('option:selected', $event)"
+		@option:unselected="$emit('option:unselected', $event)"
+		@focused:change="$emit('focused:change', $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 { GroupedOptions, 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?: 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;
+};
+```

package/dist/ai/OptionsContainer.md

@@ -0,0 +1,257 @@
+# OptionsContainer
+
+## Template & Script
+
+```vue
+<template>
+	<span
+		ref="container"
+		class="bb-cr-container"
+		:class="{
+			'bb-cr-container--errors': hasErrors,
+			'bb-cr-container--horizontal': direction === 'horizontal',
+			'bb-cr-container--vertical': direction === 'vertical',
+		}"
+	>
+		<span class="bb-cr-container__container">
+			<slot name="prepend"></slot>
+			<span
+				v-if="!options.length && loading"
+				class="bb-cr-container__loading-container"
+			>
+				<slot :name="'loading'">{{
+					loadingText || t('common.loadingText')
+				}}</slot></span
+			>
+			<span
+				v-else-if="!options.length"
+				class="bb-cr-container__no-data-container"
+				><slot :name="'no-data'">{{
+					noDataText || t('common.noDataText')
+				}}</slot></span
+			>
+			<template
+				v-for="(option, index) in options"
+				:key="option?.valueHash || index"
+			>
+				<slot
+					:id="option.valueHash"
+					:checked="!!option.selected"
+					:disabled="!!option.disabled"
+					:item="option.item"
+					name="option:prepend"
+					:text="option.text"
+				></slot>
+				<label
+					class="bb-cr-container-option"
+					:class="{ 'bb-base-radio-selected': option.selected }"
+				>
+					<slot :index="index" name="input" :option="option" />
+					<span
+						:class="{
+							'bb-cr-container-option__text': true,
+							'sr-only': hideLabel,
+						}"
+						><slot
+							:checked="!!option.selected"
+							:item="option.item"
+							name="label"
+							:text="option.text"
+							>{{ option.text }}</slot
+						></span
+					>
+				</label>
+				<slot
+					:id="option.valueHash"
+					:checked="!!option.selected"
+					:disabled="!!option.disabled"
+					:item="option.item"
+					name="option:append"
+					:text="option.text"
+				></slot>
+			</template>
+			<slot name="append"></slot>
+		</span>
+	</span>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import { useLocale } from '@/composables/useLocale';
+import type { Option } from '@/types/Option';
+import type { OptionsContainerProps, OptionsContainerSlots } from './types';
+export type { OptionsContainerProps, OptionsContainerSlots };
+
+const props = defineProps<OptionsContainerProps<T>>();
+
+defineSlots<OptionsContainerSlots<T>>();
+
+const { t } = useLocale();
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { Option } from '@/types/Option';
+
+export type OptionsContainerProps<T = any> = {
+	/**
+	 * Direction of the layout of the inputs inside the fieldset.
+	 */
+	direction?: 'horizontal' | 'vertical';
+
+	/**
+	 * Define if the component should be in an error state.
+	 * It usually attaches a CSS class for styling purposes.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Visually hides the label of the input while maintaining accessibility.
+	 */
+	hideLabel?: boolean;
+
+	/**
+	 * String displayed while items are being loaded.
+	 */
+	loadingText?: any;
+
+	/**
+	 * Shows the container in a loading state.
+	 */
+	loading?: boolean;
+
+	/**
+	 * String displayed when there are no items to display.
+	 */
+	noDataText?: any;
+
+	/**
+	 * List of options to render.
+	 */
+	options: Option<T>[];
+};
+
+export type OptionsContainerEvents = Record<never, never>;
+
+/** Props exposed by the `option:prepend` and `option:append` slots. */
+export type OptionsContainerOptionAffixSlotProps<T = any> = {
+	/** Whether this option is currently selected. */
+	checked: boolean;
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** The option's value hash used as an accessible id. */
+	id: string;
+	/** The raw item for this option. */
+	item: T;
+	/** The display text for this option. */
+	text: string;
+};
+
+/** Props exposed by the `input` slot. */
+export type OptionsContainerInputSlotProps<T = any> = {
+	/** Zero-based index of this option. */
+	index: number;
+	/** The full internal Option object for this row. */
+	option: Option<T>;
+};
+
+/** Props exposed by the `label` slot. */
+export type OptionsContainerLabelSlotProps<T = any> = {
+	/** Whether this option is currently selected. */
+	checked: boolean;
+	/** The raw item for this option. */
+	item: T;
+	/** The resolved display text for this option. */
+	text: string;
+};
+
+export type OptionsContainerSlots<T = any> = {
+	/**
+	 * Content rendered before the first option, inside the options container.
+	 */
+	prepend?: (props: object) => any;
+	/**
+	 * Content shown while options 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;
+	/**
+	 * Content rendered before each option's input.
+	 */
+	'option:prepend'?: (props: OptionsContainerOptionAffixSlotProps<T>) => any;
+	/**
+	 * The actual input element for each option (e.g. radio or checkbox).
+	 */
+	input?: (props: OptionsContainerInputSlotProps<T>) => any;
+	/**
+	 * Replaces the default label text for each option.
+	 */
+	label?: (props: OptionsContainerLabelSlotProps<T>) => any;
+	/**
+	 * Content rendered after each option's input and label.
+	 */
+	'option:append'?: (props: OptionsContainerOptionAffixSlotProps<T>) => any;
+	/**
+	 * Content rendered after the last option, inside the options container.
+	 */
+	append?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-cr-container {
+	&--horizontal {
+		.bb-cr-container-option {
+			/* No styles were applied for horizontal options */
+		}
+	}
+
+	&--vertical {
+		.bb-cr-container-option {
+			display: flex;
+			width: 100%;
+		}
+	}
+
+	&__container {
+		align-items: center;
+		column-gap: 24px;
+		display: flex;
+		flex-wrap: wrap;
+		row-gap: 10px;
+	}
+
+	&-option {
+		align-items: center;
+		column-gap: var(--bb-label-spacing-x);
+		cursor: pointer;
+		display: inline-flex;
+
+		> .bb-base-checkbox {
+			/* No additional styles were applied */
+		}
+
+		&__text {
+			color: var(--bb-text);
+			font-size: var(--bb-label-size);
+			font-weight: var(--bb-label-weight);
+			transition-duration: 150ms;
+			transition-property: color;
+			transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+
+			&--hidden {
+			}
+		}
+	}
+}
+```

package/dist/ai/index.md

@@ -0,0 +1,124 @@
+# AI Knowledge Base
+
+This index helps agents quickly find component intent and authored guides before opening full files.
+
+## Components (Consumer API)
+
+### Data Display
+
+- [BbAvatar](./BbAvatar.md) - Displays an avatar and has a fallback content slot.
+- [BbIcon](./BbIcon.md) - Renders an svg defined in the icon folder.
+- [BbTable](./BbTable.md) - Displays tabular data, configurable columns and data mapper.
+
+### Feedback
+
+- [BbAlert](./BbAlert.md) - Shows contextual status messages.
+- [BbBadge](./BbBadge.md) - Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbChip](./BbChip.md) - Shows compact labeled tokens with optional clear action.
+- [BbProgress](./BbProgress.md) - Visualizes task or operation progress state.
+- [BbSpinner](./BbSpinner.md) - Indicates ongoing loading or pending operations.
+- [BbToast](./BbToast.md) - Shows transient notification messages.
+
+### Inputs
+
+- [BaseButton](./BaseButton.md) - Foundational button primitive used by higher-level buttons, it can become a router button, an inertia link, or a button.
+- [BaseColorInput](./BaseColorInput.md) - Foundational color input primitive.
+- [BaseDatePicker](./BaseDatePicker.md) - Foundational calendar-based date picking primitive.
+- [BaseDatePickerInput](./BaseDatePickerInput.md) - Foundational date input and picker composition primitive.
+- [BaseNumberInput](./BaseNumberInput.md) - Foundational numeric input primitive.
+- [BaseTag](./BaseTag.md) - Foundational tag/token input primitive.
+- [BaseTextarea](./BaseTextarea.md) - Foundational multiline input primitive.
+- [BaseTextInput](./BaseTextInput.md) - Foundational text input primitive.
+- [BbButton](./BbButton.md) - Wrapper around BaseButton, with loading, tooltip, and icon support.
+- [BbColorInput](./BbColorInput.md) - Captures color values through input controls.
+- [BbDatePickerInput](./BbDatePickerInput.md) - Combines date selection with text input behavior.
+- [BbDropzone](./BbDropzone.md) - Supports drag-and-drop file input flows.
+- [BbNumberInput](./BbNumberInput.md) - Captures and validates numeric form values.
+- [BbTag](./BbTag.md) - Captures and displays tag-like token values.
+- [BbTextarea](./BbTextarea.md) - Captures multi-line text values.
+- [BbTextInput](./BbTextInput.md) - Captures single-line text values.
+
+### Layout & Utility
+
+- [BbRows](./BbRows.md) - Organizes content into row-based layout blocks.
+- [BbSmoothHeight](./BbSmoothHeight.md) - Animates height transitions for dynamic content.
+
+### Navigation
+
+- [BbAccordion](./BbAccordion.md) - Expands and collapses a content panel.
+- [BbBreadcrumbs](./BbBreadcrumbs.md) - Renders hierarchical navigation paths.
+- [BbCollapsible](./BbCollapsible.md) - Toggles visibility of collapsible content blocks.
+- [BbPagination](./BbPagination.md) - Navigates paginated data sets by page index.
+- [BbTab](./BbTab.md) - Switches between tabbed content views.
+- [BbTree](./BbTree.md) - Renders hierarchical expandable tree structures.
+
+### Overlay
+
+- [BbColorPalette](./BbColorPalette.md) - Opens an anchored popover color palette for color picking interactions.
+- [BbConfirm](./BbConfirm.md) - Prompts users to confirm or cancel critical actions.
+- [BbDialog](./BbDialog.md) - Presents modal dialogs for focused user interactions.
+- [BbDropdown](./BbDropdown.md) - Displays contextual action menus and menu content.
+- [BbDropdownButton](./BbDropdownButton.md) - A button with primary action and all other actions collected in a dropdown.
+- [BbOffCanvas](./BbOffCanvas.md) - Shows side-panel overlay content outside normal layout flow.
+- [BbPopover](./BbPopover.md) - Anchors floating content to reference elements.
+- [BbTooltip](./BbTooltip.md) - Displays contextual helper text on interaction.
+
+### Selection
+
+- [BbCheckbox](./BbCheckbox.md) - Toggles a single boolean option.
+- [BbCheckboxGroup](./BbCheckboxGroup.md) - Manages multiple checkbox options as a group.
+- [BbRadio](./BbRadio.md) - Represents a single choice in exclusive options.
+- [BbRadioGroup](./BbRadioGroup.md) - Coordinates exclusive selection among radio options.
+- [BbRating](./BbRating.md) - Collects scalar ratings through interactive icons.
+- [BbSelect](./BbSelect.md) - Selects one or many options from structured data.
+- [BbSelectPopover](./BbSelectPopover.md) - Provides popover-driven option selection and search.
+- [BbSlider](./BbSlider.md) - Selects numeric values across a bounded range.
+- [BbSwitch](./BbSwitch.md) - Toggles two-state values with switch semantics.
+- [BbSwitchGroup](./BbSwitchGroup.md) - Manages grouped switch options with shared behavior.
+
+## Components (Reference Only - Internal)
+
+Do not under any circumstance use these components directly, they are documented for internal context and composition details. They are documented for styling and behavioral details.
+
+### Feedback
+
+- [ErrorIcon](./ErrorIcon.md) - Renders the reusable error-state icon glyph used in validation UIs.
+
+### Inputs
+
+- [ClearableButton](./ClearableButton.md) - Action button for clearing current input value.
+
+### Layout & Utility
+
+- [BaseInputContainer](./BaseInputContainer.md) - Foundational wrapper for labels, hints, and error states in input controls.
+- [BbIntersection](./BbIntersection.md) - Observes element visibility via intersection events.
+- [BbRatio](./BbRatio.md) - Maintains constrained aspect-ratio containers.
+- [ChipsBox](./ChipsBox.md) - Layout helper for rendering chip collections.
+- [CommaBox](./CommaBox.md) - Utility for comma-separated content rendering.
+- [CommonInputInnerContainer](./CommonInputInnerContainer.md) - Shared inner wrapper for composed input controls.
+- [CommonInputOuterContainer](./CommonInputOuterContainer.md) - Shared outer wrapper for composed input controls.
+- [OptionsContainer](./OptionsContainer.md) - Container utility for option list composition.
+
+### Overlay
+
+- [BaseDialog](./BaseDialog.md) - Foundational modal dialog primitive.
+- [CommonPopover](./CommonPopover.md) - Shared popover behavior and structure primitive.
+
+### Selection
+
+- [BaseCheckbox](./BaseCheckbox.md) - Foundational checkbox control primitive.
+- [BaseCheckboxGroup](./BaseCheckboxGroup.md) - Foundational grouped checkbox selection primitive.
+- [BaseRadio](./BaseRadio.md) - Foundational radio option primitive.
+- [BaseRadioGroup](./BaseRadioGroup.md) - Foundational radio group primitive.
+- [BaseRating](./BaseRating.md) - Foundational rating input primitive.
+- [BaseSelect](./BaseSelect.md) - Foundational option selection primitive.
+- [BaseSlider](./BaseSlider.md) - Foundational range slider primitive.
+- [BaseSwitch](./BaseSwitch.md) - Foundational switch/toggle primitive.
+- [BaseSwitchGroup](./BaseSwitchGroup.md) - Foundational grouped switch primitive.
+- [FlatListBox](./FlatListBox.md) - Flat listbox renderer for selectable option lists.
+- [GroupedListBox](./GroupedListBox.md) - Grouped listbox renderer for categorized options.
+- [ListBox](./ListBox.md) - Accessible listbox interaction primitive.
+
+## Guides
+
+- No guides found yet. Add markdown files under `ai/guides` to populate this section.