bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbCheckbox.md

@@ -0,0 +1,280 @@
+# BbCheckbox
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-checkbox"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		: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'"
+	>
+		<template #label="data"><slot name="label" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, ariaDescribedby }">
+			<BaseCheckbox
+				:id="id"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus"
+				:checked="checked"
+				:color="color"
+				:disabled="disabled"
+				:false-value="falseValue"
+				:has-errors="hasErrors"
+				: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
+			></BaseCheckbox>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts">
+import BaseCheckbox from '../BaseCheckbox/BaseCheckbox.vue';
+import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
+import { ref, computed } from 'vue';
+import type {
+	BbCheckboxProps,
+	BbCheckboxEvents,
+	BbCheckboxSlots,
+} from './types';
+export type { BbCheckboxProps, BbCheckboxEvents, BbCheckboxSlots };
+
+const props = withDefaults(defineProps<BbCheckboxProps>(), {
+	direction: 'auto',
+	reverse: true,
+	inputPosition: 'left',
+});
+
+const emit = defineEmits<BbCheckboxEvents>();
+
+defineSlots<BbCheckboxSlots>();
+
+const active = ref(false);
+const showHint = computed(() => props.persistentHint || active.value);
+
+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 { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type {
+	BaseCheckboxEvents,
+	BaseCheckboxIconSlotProps,
+} from '../BaseCheckbox/types';
+
+export type BbCheckboxProps = {
+	/**
+	 * Sets autofocus on page load.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Defines the input as checked.
+	 */
+	checked?: boolean | 'true' | 'false';
+
+	/**
+	 * Define a color for the component.
+	 *
+	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
+	 */
+	color?: string;
+
+	/**
+	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
+	 *
+	 * @defaultValue `'auto'`
+	 */
+	direction?: 'horizontal' | 'vertical' | 'auto' | string;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Can be a string or an array of string containing the messages to display.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Value of the input when unchecked. It handles any kind of serializable object.
+	 */
+	falseValue?: any;
+
+	/**
+	 * 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;
+
+	/**
+	 * Text box to be displayed near the input, usually to indicate instructions.
+	 */
+	hint?: string;
+
+	/**
+	 * The identifier of the component.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Sets the input in an indeterminate state.
+	 */
+	indeterminate?: InputHTMLAttributes['indeterminate'];
+
+	/**
+	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
+	 *
+	 * @defaultValue `'left'`
+	 */
+	inputPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Text content of the label of the element.
+	 */
+	label: string;
+
+	/**
+	 * Sets the text alignment of the label.
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Used by v-model. Can be any serializable type.
+	 */
+	modelValue?: any;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Keeps the hint displayed.
+	 */
+	persistentHint?: boolean;
+
+	/**
+	 * Sets the input in a readonly state.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Sets the input as required.
+	 */
+	required?: boolean;
+
+	/**
+	 * Reverses the layout. Applicable in every direction the order of the label and the input is swapped.
+	 *
+	 * @defaultValue `true`
+	 */
+	reverse?: boolean;
+
+	/**
+	 * Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted.
+	 */
+	submitWhenFalse?: boolean;
+
+	/**
+	 * Value of the input when checked. It handles any kind of serializable object.
+	 */
+	trueValue?: any;
+};
+
+/** Re-export for consumers importing events type from BbCheckbox. */
+export type BbCheckboxEvents = BaseCheckboxEvents;
+
+/** Props exposed by the `label` slot. */
+export type BbCheckboxLabelSlotProps = {
+	/** The `label` prop value. */
+	text: string;
+	/** Whether the checkbox is in an error state. */
+	hasErrors: boolean;
+};
+
+/** Props exposed by the `icon` slot. Extends BaseCheckbox icon slot with the label text. */
+export type BbCheckboxIconSlotProps = BaseCheckboxIconSlotProps & {
+	/** The `label` prop value. */
+	text: string;
+};
+
+export type BbCheckboxSlots = {
+	/**
+	 * Replaces the default label text rendered next to the checkbox.
+	 */
+	label?: (props: BbCheckboxLabelSlotProps) => any;
+	/**
+	 * Replaces the default checkmark SVG inside the checkbox box. Receives `BaseCheckbox` slot
+	 * attributes plus the label text.
+	 */
+	icon?: (props: BbCheckboxIconSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-checkbox {
+	.bb-base-input-container {
+		cursor: pointer;
+
+		&--horizontal {
+			align-items: center;
+			display: flex;
+		}
+
+		.bb-base-input-container__input {
+			margin-bottom: -7px;
+		}
+	}
+}
+```

package/dist/ai/BbCheckboxGroup.md

@@ -0,0 +1,387 @@
+# BbCheckboxGroup
+
+## Template & Script
+
+```vue
+<template>
+	<BaseInputContainer
+		:id="id"
+		class="bb-checkbox-group"
+		:compact="compact"
+		:direction="direction"
+		:errors="errors"
+		:has-errors="hasErrors"
+		:hide-label="hideLegend"
+		:hint="hint"
+		:input-position="inputPosition"
+		:label="legend"
+		:label-position="labelPosition"
+		:label-tag="'legend'"
+		:name="name"
+		:reverse="reverse"
+		:show-hint="showHint"
+		:tag="'fieldset'"
+	>
+		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
+		<template #input="{ id, hasErrors, ariaDescribedby }">
+			<BaseCheckboxGroup
+				:id="id"
+				:aria-describedby="ariaDescribedby"
+				:autofocus="autofocus"
+				:color="color"
+				:dependencies="dependencies"
+				:deps-debounce-time="depsDebounceTime"
+				:direction="inputDirection"
+				:disabled="disabled"
+				:enforce-coherence="enforceCoherence"
+				:has-errors="hasErrors"
+				: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"
+				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 #option:prepend="data"
+					><slot name="option:prepend" 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 #option:append="data"
+					><slot name="option:append" v-bind="data"></slot></template
+				><template #append="data"
+					><slot name="append" v-bind="data"></slot
+				></template>
+			</BaseCheckboxGroup>
+		</template>
+	</BaseInputContainer>
+</template>
+
+<script setup lang="ts" generic="T = any">
+import BaseCheckboxGroup from '../BaseCheckboxGroup/BaseCheckboxGroup.vue';
+import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
+import { ref, computed } from 'vue';
+import type {
+	BbCheckboxGroupProps,
+	BbCheckboxGroupEvents,
+	BbCheckboxGroupSlots,
+} from './types';
+export type {
+	BbCheckboxGroupProps,
+	BbCheckboxGroupEvents,
+	BbCheckboxGroupSlots,
+};
+
+const props = withDefaults(defineProps<BbCheckboxGroupProps<T>>(), {
+	inputPosition: 'left',
+	multiple: true,
+});
+
+const emit = defineEmits<BbCheckboxGroupEvents>();
+
+defineSlots<BbCheckboxGroupSlots<T>>();
+
+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);
+	},
+	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 { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { NestedKeyOf } from '@/types/NestedKeyOf';
+import type { BaseCheckboxGroupEvents } from '../BaseCheckboxGroup/types';
+import type {
+	BaseCheckboxGroupIconSlotProps,
+	BaseCheckboxGroupLabelSlotProps,
+	BaseCheckboxGroupOptionAffixSlotProps,
+} from '../BaseCheckboxGroup/types';
+
+export type BbCheckboxGroupProps<T> = {
+	/**
+	 * Sets autofocus on page load.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+
+	/**
+	 * Define a color for the component.
+	 *
+	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
+	 */
+	color?: string;
+
+	/**
+	 * Displays the component in a compact version.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Defines an array of dependencies that will trigger actions in the component upon change.
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Timeout used to debounce response to changes to dependencies.
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
+	 */
+	direction?: 'horizontal' | 'vertical' | 'auto' | string;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * If coherence is enforced the input cannot have a modelValue that is incoherent with its current items.
+	 *
+	 * e.g. You cannot set v-model to a user that is not present in the items passed.
+	 *
+	 * modelValue will be reset upon incoherence.
+	 */
+	enforceCoherence?: boolean;
+
+	/**
+	 * Can be a string or an array of string containing the messages to display.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * 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;
+
+	/**
+	 * Visually hides the legend of the fieldset while maintaining accessibility.
+	 */
+	hideLegend?: boolean;
+
+	/**
+	 * Text box to be displayed near the input, usually to indicate instructions.
+	 */
+	hint?: string;
+
+	/**
+	 * The identifier of the component.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Defines the direction of the inputs in the fieldset.
+	 */
+	inputDirection?: 'horizontal' | 'vertical';
+
+	/**
+	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
+	 *
+	 * @defaultValue `'left'`
+	 */
+	inputPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Used to retrieve items; can be an array or a function.
+	 */
+	items:
+		| T[]
+		| ((prefill: boolean, modelValue?: any) => Promise<T[]>)
+		| ((prefill: boolean, modelValue?: any) => T[]);
+
+	/**
+	 * Defines a path that returns a property of the object to use as text or a function that returns a string.
+	 */
+	itemText?: T extends object
+		? NestedKeyOf<T> | ((item: T) => string)
+		: ((item: T) => string) | undefined;
+
+	/**
+	 * Defines a path that returns a property of the object to use as value or a function that returns any value.
+	 */
+	itemValue?: T extends object
+		? NestedKeyOf<T> | ((item: T) => string)
+		: ((item: T) => any) | undefined;
+
+	/**
+	 * Sets the text alignment of the label.
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Text content of the legend.
+	 */
+	legend: string;
+
+	/**
+	 * String displayed while items are being loaded.
+	 */
+	loadingText?: string;
+
+	/**
+	 * Maximum number of selected items.
+	 */
+	max?: number;
+
+	/**
+	 * Used by v-model. Can be an array of any serializable type.
+	 */
+	modelValue: any;
+
+	/**
+	 * Enables multi-selection behavior.
+	 * When true, `modelValue` must be an array.
+	 * When false, `modelValue` should be a single value.
+	 *
+	 * @defaultValue `true`
+	 */
+	multiple?: boolean;
+
+	/**
+	 * Timeout used to debounce response to changes to modelValue.
+	 */
+	modelValueDebounceTime?: number;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * String displayed when there are no items to display.
+	 */
+	noDataText?: string;
+
+	/**
+	 * Keeps the hint displayed.
+	 */
+	persistentHint?: boolean;
+
+	/**
+	 * Sets the input in a readonly state.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Reverses the layout. Applicable in every direction the order of the label and the input is swapped.
+	 */
+	reverse?: boolean;
+};
+
+/** Re-export for consumers importing events type from BbCheckboxGroup. */
+export type BbCheckboxGroupEvents = BaseCheckboxGroupEvents;
+
+/** Props exposed by the `legend` slot. */
+export type BbCheckboxGroupLegendSlotProps = {
+	/** The `legend` prop value. */
+	text: string;
+	/** Whether the group is in an error state. */
+	hasErrors: boolean;
+};
+
+export type BbCheckboxGroupSlots<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;
+	/**
+	 * Content rendered before each option's checkbox.
+	 */
+	'option:prepend'?: (props: BaseCheckboxGroupOptionAffixSlotProps<T>) => any;
+	/**
+	 * Replaces the default checkmark icon for each checkbox option.
+	 */
+	icon?: (props: BaseCheckboxGroupIconSlotProps<T>) => any;
+	/**
+	 * Replaces the default label text for each option.
+	 */
+	label?: (props: BaseCheckboxGroupLabelSlotProps<T>) => any;
+	/**
+	 * Content rendered after each option's checkbox and label.
+	 */
+	'option:append'?: (props: BaseCheckboxGroupOptionAffixSlotProps<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: BbCheckboxGroupLegendSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-checkbox-group {
+	.bb-base-input-container--horizontal {
+		.bb-base-input-container__label {
+			float: left;
+		}
+	}
+
+	.bb-base-input-container__input--right {
+		.bb-cr-container__container {
+			justify-content: flex-end;
+		}
+	}
+	.bb-base-input-container__input--center {
+		.bb-cr-container__container {
+			justify-content: center;
+		}
+	}
+}
+```