bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BaseInputContainer.md

@@ -1,570 +0,0 @@
-# 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%;
-	}
-}
-```