bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseInputContainer.md

@@ -0,0 +1,570 @@
+# BaseInputContainer
+
+## Template & Script
+
+```vue
+<template>
+	<div
+		class="bb-base-input-outer-container"
+		:class="{
+			'bb-base-input-outer-container--errors': hasErrors,
+			'bb-base-input-outer-container--hint': showHint,
+			'bb-base-input-outer-container--compact': props.compact,
+		}"
+	>
+		<component :is="tag" v-bind="containerAttributes">
+			<component :is="labelTag" v-bind="labelAttributes">
+				<slot name="label" v-bind="{ text: label, hasErrors }">{{
+					label
+				}}</slot>
+			</component>
+			<span v-bind="inputAttributes">
+				<slot
+					name="input"
+					v-bind="{ id, name, hasErrors, ariaDescribedby: hintId }"
+				></slot>
+			</span>
+		</component>
+		<Transition name="hint">
+			<span
+				v-if="showHint"
+				:id="hintId"
+				class="bb-base-input-container__hint-container"
+			>
+				<span class="bb-base-input-container__hint">{{ hint }}</span>
+			</span>
+		</Transition>
+		<span ref="errorsContainer" class="bb-base-input-container__errors-outer">
+			<TransitionGroup
+				name="error"
+				tag="span"
+				aria-live="polite"
+				class="bb-base-input-container__errors"
+			>
+				<span
+					v-for="error in computedErrors"
+					:key="error"
+					class="bb-base-input-container__error"
+					>{{ error }}</span
+				>
+			</TransitionGroup>
+		</span>
+	</div>
+</template>
+
+<script setup lang="ts">
+import {
+	computed,
+	Transition,
+	TransitionGroup,
+	ref,
+	nextTick,
+	watchPostEffect,
+} from 'vue';
+import { deburr } from '@/utilities/functions/deburr';
+import { getAsPercentage } from '@/utilities/functions/percentage';
+import { noop } from '@/utilities/functions/noop';
+import { useId } from '@/composables/useId';
+import type { BaseInputContainerProps, BaseInputContainerSlots } from './types';
+
+const props = withDefaults(defineProps<BaseInputContainerProps>(), {
+	direction: 'vertical',
+	inputPosition: 'right',
+	labelPosition: 'left',
+	labelTag: 'label',
+	reverse: false,
+	tag: 'span',
+});
+
+defineSlots<BaseInputContainerSlots>();
+
+// Always provide an id so that inputs can be focussed by clicking oin the label
+const id = props.id || useId().id.value;
+
+/**
+ * Hint management
+ */
+const hintId = props.hint ? `hint_${id}` : undefined;
+const showHint = computed(() => props.showHint && !!props.hint);
+const resolvedDirection = computed<
+	NonNullable<BaseInputContainerProps['direction']>
+>(() => (props.labelMode ? 'vertical' : props.direction));
+
+// If no name is passed use a normalized version of the label
+const name = computed(() => {
+	if (props.name) return props.name;
+	let noAccents = deburr(props.label);
+	let nospace = noAccents.replace(/\s+/g, '');
+	return nospace.toLowerCase();
+});
+
+const containerAttributes = computed(() => {
+	const initial: { [name: string]: any } = {
+		class: {
+			'bb-base-input-container': true,
+			'bb-base-input-container--hidden-label': props.reverse,
+			'bb-base-input-container--horizontal':
+				resolvedDirection.value !== 'vertical',
+			'bb-base-input-container--reverse': props.reverse,
+			'bb-base-input-container--vertical':
+				resolvedDirection.value === 'vertical',
+			'bb-base-input-container--errors': hasErrors.value,
+			'bb-base-input-container--label-mode-floating':
+				props.labelMode === 'floating',
+		},
+	};
+	if (props.tag === 'label') initial.for = id;
+	return initial;
+});
+
+const labelAttributes = computed(() => {
+	let initial: { [name: string]: any } = {
+		class: {
+			'bb-base-input-container__label': true,
+			'bb-base-input-container__label--hidden': props.hideLabel,
+			[`bb-base-input-container__label--${props.labelPosition}`]:
+				props.labelPosition,
+		},
+		style: {
+			width: widths.value.label,
+		},
+	};
+	if (props.labelTag === 'label') initial.for = id;
+	return initial;
+});
+
+const inputAttributes = computed(() => {
+	let initial: { [name: string]: any } = {
+		class: {
+			'bb-base-input-container__input': true,
+			[`bb-base-input-container__input--${props.inputPosition}`]:
+				props.inputPosition,
+		},
+		style: {
+			width: widths.value.input,
+		},
+	};
+	return initial;
+});
+
+const widths = computed(() => {
+	let initial: { [target: string]: string } = {
+		label: 'auto',
+		input: 'auto',
+	};
+	if (resolvedDirection.value === 'auto') {
+		noop();
+	} else if (resolvedDirection.value === 'vertical') {
+		initial.label = initial.input = 100 + '%';
+	} else if (resolvedDirection.value === 'horizontal') {
+		initial.label = initial.input = 50 + '%';
+	} else if (/^[\S]+\s[\S]+$/g.test(resolvedDirection.value)) {
+		const [firstLength, secondLength] = resolvedDirection.value
+			.split(/\s+/)
+			.map((string) => string.length);
+		const first =
+			getAsPercentage(firstLength, firstLength + secondLength) + '%';
+		const second =
+			getAsPercentage(secondLength, secondLength + firstLength) + '%';
+		if (props.reverse) {
+			initial.label = second;
+			initial.input = first;
+		} else {
+			initial.label = first;
+			initial.input = second;
+		}
+	} else {
+		throw new Error('Horizontal pattern is malformed');
+	}
+	return initial;
+});
+
+const computedErrors = computed(() => {
+	return props.errors ? ([] as string[]).concat(props.errors) : [];
+});
+
+const hasErrors = computed(
+	() => Boolean(computedErrors.value.length) || props.hasErrors
+);
+
+/**
+ * Smooth height transition for errors container
+ */
+const errorsContainer = ref<HTMLElement | null>(null);
+
+watchPostEffect(() => {
+	// Track when errors change
+	computedErrors.value;
+
+	// Update height after DOM updates
+	nextTick(() => {
+		const container = errorsContainer.value;
+		const content = container?.querySelector(
+			'.bb-base-input-container__errors'
+		);
+		if (container && content) {
+			const min = Math.min(content.clientHeight, content.scrollHeight);
+			container.style.height = `${min}px`;
+		}
+	});
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+
+/**
+ * Wrapper responsible for aligning labels, inputs, hints, and error messages consistently across form controls.
+ */
+export type BaseInputContainerProps = {
+	/**
+	 * Apply the compact density variant to the container.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Controls label/input layout.
+	 * Accepts `'vertical'`, `'horizontal'`, `'auto'`, or a custom pattern such as `"xx xxxxx"` to size columns by word length.
+	 * @defaultValue `'vertical'`
+	 */
+	direction?: 'horizontal' | 'vertical' | 'auto' | string;
+
+	/**
+	 * Messages displayed beneath the input. Accepts a string or array; values are rendered one per line.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Forces the error state independently of `errors`, useful to pre-style the container.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Hide the visual label while keeping it available to assistive technology.
+	 */
+	hideLabel?: boolean;
+
+	/**
+	 * Hint text rendered below the input. When present, its id is exposed to the input slot via `ariaDescribedby`.
+	 */
+	hint?: string;
+
+	/**
+	 * Explicit id for the container and associated input. Falls back to an auto-generated id when omitted.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Horizontal alignment of the input column when direction is horizontal or custom.
+	 * @defaultValue `'right'`
+	 */
+	inputPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Visible label text for the field. Also used to derive a fallback name.
+	 */
+	label: string;
+
+	/**
+	 * Horizontal alignment for the label column.
+	 * @defaultValue `'left'`
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Label rendering mode.
+	 */
+	labelMode?: 'outside' | 'floating' | 'inside';
+
+	/**
+	 * Tag used for the label element. Defaults to `label`, but can be set to `legend` for grouped inputs.
+	 * @defaultValue `'label'`
+	 */
+	labelTag?: string;
+
+	/**
+	 * Value forwarded for v-model support. Accepts any serializable value.
+	 */
+	modelValue?: any;
+
+	/**
+	 * Explicit name attribute forwarded to the input. When omitted, a slug derived from `label` is used.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Swap the label and input columns.
+	 * @defaultValue `false`
+	 */
+	reverse?: boolean;
+
+	/**
+	 * Keep the hint permanently visible, regardless of focus.
+	 */
+	showHint?: boolean;
+
+	/**
+	 * Tag used for the outer wrapper. Defaults to `span` to remain inline.
+	 * @defaultValue `'span'`
+	 */
+	tag?: string;
+};
+
+/**
+ * Props exposed by the `input` slot.
+ */
+export type BaseInputContainerInputSlotProps = {
+	/**
+	 * The resolved `id` for the input element; matches the `for` attribute on the label.
+	 */
+	id: string;
+	/**
+	 * The resolved `name` for the input, derived from the `label` prop when not set explicitly.
+	 */
+	name: string;
+	/**
+	 * Whether the container is in an error state (from `errors` or `hasErrors` props).
+	 */
+	hasErrors: boolean;
+	/**
+	 * The `id` of the hint element when a `hint` is configured; pass as `aria-describedby` to the inner input.
+	 */
+	ariaDescribedby: string | undefined;
+};
+
+/**
+ * Props exposed by the `label` slot.
+ */
+export type BaseInputContainerLabelSlotProps = {
+	/**
+	 * The `label` prop value.
+	 */
+	text: string;
+	/**
+	 * Whether the container is in an error state.
+	 */
+	hasErrors: boolean;
+};
+
+export type BaseInputContainerSlots = {
+	/**
+	 * The form control to render, positioned in the input column. Receives pre-computed
+	 * wiring attributes so the inner input can be correctly associated with the label and hint.
+	 */
+	input?: (props: BaseInputContainerInputSlotProps) => any;
+	/**
+	 * Replaces the default label text. The outer label element and its `for` association are always rendered.
+	 */
+	label?: (props: BaseInputContainerLabelSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-input-outer-container {
+	display: flex;
+	flex-direction: column;
+
+	&.bb-base-input-outer-container--errors {
+		.bb-base-input-container__errors {
+		}
+	}
+	&.bb-base-input-outer-container--hint {
+		.bb-base-input-container__errors {
+		}
+	}
+	&.bb-base-input-outer-container--compact {
+		--bb-label-spacing-y: var(--bb-label-compact-spacing-y);
+		--bb-input-prefix-w: var(--bb-input-compact-prefix-w);
+	}
+
+	/* Circumvent flex bug on fieldset element */
+	fieldset.bb-base-input-container {
+		> :not(:last-child) {
+			margin-bottom: var(--bb-label-spacing-y);
+		}
+	}
+	.bb-base-input-container {
+		column-gap: var(--bb-label-spacing-x);
+		display: flex;
+		row-gap: var(--bb-label-spacing-y);
+
+		&--vertical {
+			flex-direction: column;
+			&.bb-base-input-container--reverse {
+				& > *:first-child {
+					order: 2;
+				}
+			}
+		}
+		&--horizontal {
+			&.bb-base-input-container--reverse {
+				& > *:first-child {
+					order: 2;
+				}
+			}
+		}
+
+		&:has(+ .bb-base-input-container__hint-container),
+		&:has(
+			+ .bb-base-input-container__errors-outer
+				.bb-base-input-container__errors:not(:empty)
+		) {
+			margin-bottom: 6px;
+		}
+
+		&__label {
+			color: var(--bb-text);
+			display: inline-block;
+			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);
+
+			&--left {
+				text-align: left;
+			}
+			&--center {
+				text-align: center;
+			}
+			&--right {
+				text-align: right;
+			}
+			&--hidden {
+				border-width: 0 !important;
+				clip: rect(0, 0, 0, 0) !important;
+				height: 1px !important;
+				margin: -1px !important;
+				overflow: hidden !important;
+				padding: 0 !important;
+				position: absolute !important;
+				white-space: nowrap !important;
+				width: 1px !important;
+			}
+		}
+		&__input {
+			display: inline-block;
+
+			& > [class*='bb'] {
+				display: block;
+				width: 100%;
+			}
+
+			&--left {
+				text-align: left;
+			}
+			&--center {
+				text-align: center;
+			}
+			&--right {
+				text-align: right;
+			}
+		}
+
+		&--label-mode-floating {
+			position: relative;
+			.bb-base-input-container__label {
+				position: absolute;
+				transition: translate 300ms cubic-bezier(0.4, 0, 0.2, 1);
+				opacity: 0.6;
+				top: 0;
+				left: 0;
+				translate: var(--bb-input-px) calc(var(--bb-input-h) / 2 - 50%);
+			}
+
+			&:focus-within,
+			&:has([class*='--has-value']) {
+				.bb-base-input-container__label {
+					top: 0;
+					translate: 0 calc((var(--bb-label-spacing-y) + 100%) * -1);
+				}
+			}
+		}
+
+		&__hint-container {
+			color: var(--bb-hint);
+			font-size: 14px;
+			line-height: 18px;
+			position: relative;
+			.bb-base-input-container__hint {
+			}
+		}
+		&__errors-outer {
+			display: block;
+			height: 0;
+			overflow: hidden;
+			transition: height 300ms cubic-bezier(0.4, 0, 0.2, 1);
+			width: 100%;
+		}
+		&__errors {
+			color: var(--bb-danger);
+			display: block;
+			font-size: 14px;
+			line-height: 18px;
+			width: 100%;
+			position: relative;
+		}
+		&__error {
+			display: inline-block;
+			width: 100%;
+		}
+	}
+
+	/* Hint transition */
+	.hint-enter-active,
+	.hint-leave-active {
+		display: grid;
+		grid-template-rows: 1fr;
+		overflow: hidden;
+		transition:
+			grid-template-rows 200ms ease,
+			opacity 300ms ease,
+			margin 200ms ease;
+	}
+
+	.hint-enter-from,
+	.hint-leave-to {
+		grid-template-rows: 0fr;
+		margin-top: 0;
+		opacity: 0;
+	}
+
+	.hint-enter-active > *,
+	.hint-leave-active > * {
+		min-height: 0;
+		transition: opacity 300ms ease;
+	}
+
+	.hint-enter-from > *,
+	.hint-leave-to > * {
+		opacity: 0;
+	}
+
+	/* Individual error item transitions */
+	.error-move,
+	.error-enter-active,
+	.error-leave-active {
+		transition: all 300ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+
+	.error-enter-from,
+	.error-leave-to {
+		opacity: 0;
+		transform: translateY(-4px);
+	}
+
+	.error-leave-active {
+		position: absolute;
+		width: 100%;
+	}
+}
+```