bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/source/BbSpinner.md

@@ -0,0 +1,127 @@
+# BbSpinner — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbSpinner.md](../BbSpinner.md).
+
+## Template & Script
+
+```vue
+<template>
+	<span v-if="label" role="status">
+		<BbIcon class="bb-spinner" :icon="spinnerSvg" :size="size" />
+		<span class="sr-only">{{ label }}</span>
+	</span>
+	<BbIcon v-else class="bb-spinner" :icon="spinnerSvg" :size="size" />
+</template>
+
+<script setup lang="ts">
+import spinnerSvg from '@/assets/svgs/spinner.svg?raw';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import type { BbSpinnerProps } from './types';
+import BbIcon from '../BbIcon/BbIcon.vue';
+
+withDefaults(defineProps<BbSpinnerProps>(), {
+	size: 'md',
+});
+
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbSpinner', removedPropsFor('BbSpinner'));
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { BbIconProps, BbIconSize as IconSize } from '../BbIcon/types';
+
+/**
+ * Maps size key strings to pixel dimensions. Re-exported for consumers that
+ * need to reference the size key union type.
+ */
+export type Size = IconSize;
+
+export type BbSpinnerProps = Pick<BbIconProps, 'size'> & {
+	/**
+	 * Accessible loading announcement. When set, the spinner is wrapped in a
+	 * `role="status"` element containing this text rendered `sr-only`, so
+	 * screen readers announce the loading state. When omitted the markup is
+	 * unchanged and the spinner is purely decorative.
+	 */
+	label?: string;
+};
+```
+
+## Styles
+
+```css
+/* @inherit --size — leaf primitive, sized by whichever component embeds it */
+.bb-spinner {
+	display: inline-block;
+	fill: currentColor;
+	width: var(--size);
+
+	/*
+	 * The dots pulse via `transform: scale()` — never via the `r` geometry
+	 * property. Animating `r` forces a layout pass on EVERY animation frame,
+	 * which janks every interaction on any page showing a spinner. Transforms
+	 * skip style/layout entirely; the circles keep a static r="2" in the SVG
+	 * and grow from scale(0), which renders identically.
+	 */
+	@keyframes bb-spin-animation {
+		0%,
+		50% {
+			animation-timing-function: cubic-bezier(0.27, 0.42, 0.37, 0.99);
+			transform: scale(0);
+		}
+		25% {
+			animation-timing-function: cubic-bezier(0.53, 0, 0.61, 0.73);
+			transform: scale(1);
+		}
+	}
+
+	.bb-spinner__circle {
+		animation: bb-spin-animation 1.2s infinite;
+		transform: scale(0);
+		/* Scale each dot around its own center, not the SVG origin. */
+		transform-box: fill-box;
+		transform-origin: center;
+	}
+	.circle--1 {
+		animation-delay: 0.1s;
+	}
+	.circle--3 {
+		animation-delay: 0.2s;
+	}
+	.circle--5 {
+		animation-delay: 0.3s;
+	}
+	.circle--7 {
+		animation-delay: 0.4s;
+	}
+	.circle--9 {
+		animation-delay: 0.5s;
+	}
+	.circle--11 {
+		animation-delay: 0.6s;
+	}
+	.circle--10 {
+		animation-delay: 0.7s;
+	}
+	.circle--8 {
+		animation-delay: 0.8s;
+	}
+	.circle--6 {
+		animation-delay: 0.9s;
+	}
+	.circle--4 {
+		animation-delay: 1s;
+	}
+	.circle--2 {
+		animation-delay: 1.1s;
+	}
+}
+```

package/dist/ai/source/BbSwitch.md

@@ -0,0 +1,175 @@
+# BbSwitch — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbSwitch.md](../BbSwitch.md).
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-switch"
+		:description="description"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:has-warning="hasWarning"
+		:hide-label="hideLabel"
+		:hint="hint"
+		:input-position="inputPosition"
+		:label="label"
+		:label-position="labelPosition"
+		label-tag="span"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+		tag="label"
+		:warnings="warnings"
+	>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
+			<BaseSwitch
+				:id="id"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus"
+				:checked="checked"
+				:disabled="disabled"
+				:false-value="falseValue"
+				:has-errors="hasErrors"
+				:has-warning="hasWarning"
+				:indeterminate="indeterminate"
+				:model-value="modelValue"
+				:name="name"
+				:readonly="readonly"
+				:required="required"
+				:submit-when-false="submitWhenFalse"
+				:true-value="trueValue"
+				v-bind="eventListeners"
+			>
+				<template #icon="data"
+					><slot name="icon" v-bind="data" :text="label"
+				/></template>
+			</BaseSwitch>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts">
+import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
+import BaseSwitch from '../BbBaseSwitch/BbBaseSwitch.vue';
+import { computed, ref } from 'vue';
+import type { BbSwitchProps, BbSwitchEvents, BbSwitchSlots } from './types';
+export type { BbSwitchProps, BbSwitchEvents, BbSwitchSlots };
+
+const props = withDefaults(defineProps<BbSwitchProps>(), {
+	// booleanish `checked` — default: undefined so an unset prop isn't coerced to
+	// `false` and forwarded down; lets BaseSwitch derive it from `modelValue`.
+	checked: undefined,
+	direction: 'auto',
+	// Control-first: always left-align, like BbCheckbox/BbRadio (never right, even
+	// in a horizontal layout).
+	inputPosition: 'left',
+});
+
+const emit = defineEmits<BbSwitchEvents>();
+
+defineSlots<BbSwitchSlots>();
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+// We use the negative to avoid the awkward syntax of :reverse="false" from outside
+const reverse = computed(() => !props.reverse);
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => {
+		active.value = false;
+		emit('blur', event);
+	},
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus: (event: FocusEvent) => {
+		active.value = true;
+		emit('focus', event);
+	},
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { BaseCheckboxIconSlotProps } from '../BbBaseCheckbox/types';
+import type { BbCheckboxEvents, BbCheckboxProps } from '../BbCheckbox/types';
+
+/** Re-export of BbCheckboxProps for the switch variant. */
+export type BbSwitchProps = BbCheckboxProps;
+
+/** Re-export for consumers importing events type from BbSwitch. */
+export type BbSwitchEvents = BbCheckboxEvents;
+
+/** Props exposed by the `label` slot. */
+export type BbSwitchLabelSlotProps = {
+	/** The `label` prop value. */
+	text: string;
+	/** Whether the switch is in an error state. */
+	hasErrors: boolean;
+	/** Whether the switch is in a warning state (suppressed when errors). */
+	hasWarning: boolean;
+};
+
+/** Props exposed by the `icon` slot. Extends BaseSwitch icon slot with the label text. */
+export type BbSwitchIconSlotProps = BaseCheckboxIconSlotProps & {
+	/** The `label` prop value. */
+	text: string;
+};
+
+export type BbSwitchSlots = {
+	/**
+	 * Replaces the default label text rendered next to the switch.
+	 */
+	label?: (props: BbSwitchLabelSlotProps) => any;
+	/**
+	 * Replaces the default toggle track visual inside the switch. Receives `BaseSwitch` slot
+	 * attributes plus the label text.
+	 */
+	icon?: (props: BbSwitchIconSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-switch {
+	.bb-base-input-container__layout {
+		cursor: pointer;
+
+		&--horizontal {
+			align-items: center;
+			display: flex;
+		}
+	}
+
+	/* With a description the label block spans two lines: align the switch with
+	   the first line (the label text) instead of centering on the block. */
+	&.bb-base-input-container--description {
+		.bb-base-input-container__layout--horizontal {
+			align-items: flex-start;
+
+			.bb-base-input-container__control {
+				align-items: center;
+				display: inline-flex;
+				min-height: var(--bb-label-lh);
+			}
+		}
+	}
+}
+```

package/dist/ai/source/BbSwitchGroup.md

@@ -0,0 +1,240 @@
+# BbSwitchGroup — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbSwitchGroup.md](../BbSwitchGroup.md).
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-switch-group"
+		:compact="compact"
+		:description="description"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:has-warning="hasWarning"
+		:hide-label="hideLegend"
+		:hint="hint"
+		:input-position="inputPosition"
+		:label="legend"
+		:label-mode="legendMode"
+		:label-position="legendPosition"
+		label-tag="legend"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+		tag="fieldset"
+		:warnings="warnings"
+	>
+		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
+			<BaseSwitchGroup
+				:id="id"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus"
+				:dependencies="dependencies"
+				:deps-debounce-time="depsDebounceTime"
+				:direction="inputDirection"
+				:disabled="disabled"
+				:enforce-coherence="enforceCoherence"
+				:has-errors="hasErrors"
+				:has-warning="hasWarning"
+				:hide-label="hideLabel"
+				:item-text="<any>itemText"
+				:item-value="<any>itemValue"
+				:items="items"
+				:loading-text="loadingText"
+				:max="max"
+				:model-value="modelValue"
+				:model-value-debounce-time="modelValueDebounceTime"
+				:multiple="multiple"
+				:name="name"
+				:no-data-text="noDataText"
+				:readonly="readonly"
+				:selectable="selectable"
+				v-bind="eventListeners"
+			>
+				<template #prepend="data"
+					><slot name="prepend" v-bind="data"></slot></template
+				><template #loading="data"
+					><slot name="loading" v-bind="data"></slot></template
+				><template #no-data="data"
+					><slot name="no-data" v-bind="data"></slot></template
+				><template #icon="data"
+					><slot name="icon" v-bind="data"></slot></template
+				><template #label="data"
+					><slot name="label" v-bind="data"></slot></template
+				><template #append="data"
+					><slot name="append" v-bind="data"></slot
+				></template>
+			</BaseSwitchGroup>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
+import BaseSwitchGroup from '../BbBaseSwitchGroup/BbBaseSwitchGroup.vue';
+import { computed, ref } from 'vue';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import type {
+	BbSwitchGroupProps,
+	BbSwitchGroupEvents,
+	BbSwitchGroupSlots,
+} from './types';
+export type { BbSwitchGroupProps, BbSwitchGroupEvents, BbSwitchGroupSlots };
+
+const props = withDefaults(defineProps<BbSwitchGroupProps<T>>(), {
+	// Match BbCheckboxGroup: switch groups are multi-select by default, and an
+	// absent boolean-union prop would otherwise coerce to `false`.
+	multiple: true,
+	inputPosition: 'left',
+	selectable: true,
+});
+
+const emit = defineEmits<BbSwitchGroupEvents>();
+
+defineSlots<BbSwitchGroupSlots<T>>();
+
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbSwitchGroup', removedPropsFor('BbSwitchGroup'));
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus: (event: FocusEvent) => {
+		active.value = true;
+		emit('focus', event);
+	},
+	onActive: () => {
+		active.value = true;
+		emit('active');
+	},
+	onInactive: () => {
+		active.value = false;
+		emit('inactive');
+	},
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+	'onUpdate:modelValue': (event: any) => emit('update:modelValue', event),
+};
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { BaseCheckboxIconSlotProps } from '../BbBaseCheckbox/types';
+import type {
+	BbCheckboxGroupEvents,
+	BbCheckboxGroupProps,
+} from '../BbCheckboxGroup/types';
+
+/** Re-export of BbCheckboxGroupProps for the switch-group variant. */
+export type BbSwitchGroupProps<T = any> = BbCheckboxGroupProps<T>;
+
+/** Re-export for consumers importing events type from BbSwitchGroup. */
+export type BbSwitchGroupEvents = BbCheckboxGroupEvents;
+
+/** Props exposed by the `legend` slot. */
+export type BbSwitchGroupLegendSlotProps = {
+	/** The `legend` prop value. */
+	text: string;
+	/** Whether the group is in an error state. */
+	hasErrors: boolean;
+	/** Whether the group is in a warning state (suppressed when errors). */
+	hasWarning: boolean;
+};
+
+/** Props exposed by the `icon` slot. Extends BaseCheckbox icon slot with item and label text. */
+export type BbSwitchGroupIconSlotProps<T> = BaseCheckboxIconSlotProps & {
+	/** Original source item for this option. */
+	item: T;
+	/** Resolved display text for this option. */
+	text: string;
+};
+
+/** Props exposed by the `label` slot for each option. */
+export type BbSwitchGroupLabelSlotProps<T> = {
+	/** Original source item for this option. */
+	item: T;
+	/** Resolved display text for this option. */
+	text: string;
+	/** Whether this option is currently selected. */
+	checked: boolean;
+};
+
+export type BbSwitchGroupSlots<T> = {
+	/**
+	 * 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;
+	/**
+	 * Replaces the default switch track visual for each option. Receives all `BaseSwitch` slot
+	 * attributes plus the source item and its display text.
+	 */
+	icon?: (props: BbSwitchGroupIconSlotProps<T>) => any;
+	/**
+	 * Replaces the default label text for each option.
+	 */
+	label?: (props: BbSwitchGroupLabelSlotProps<T>) => any;
+	/**
+	 * Content rendered after the last option, inside the options container.
+	 */
+	append?: (props: object) => any;
+	/**
+	 * Replaces the default fieldset legend text for the group.
+	 */
+	legend?: (props: BbSwitchGroupLegendSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-switch-group {
+	.bb-base-input-container__layout--horizontal {
+		.bb-base-input-container__label {
+			float: left;
+		}
+	}
+
+	.bb-base-input-container__control--right {
+		.bb-cr-container__container {
+			justify-content: flex-end;
+		}
+	}
+	.bb-base-input-container__control--center {
+		.bb-cr-container__container {
+			justify-content: center;
+		}
+	}
+
+	&.bb-base-input-container--inside-label.bb-base-input-container--errors {
+		.bb-base-input-container__layout {
+			border-color: var(--bb-danger);
+		}
+	}
+}
+```