bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseColorInput.md

@@ -0,0 +1,461 @@
+# BaseColorInput
+
+## Template & Script
+
+```vue
+<template>
+	<CommonInputOuterContainer ref="wrapper" :class="classes">
+		<template #prepend-outer><slot name="prepend-outer"></slot></template>
+		<CommonInputInnerContainer
+			ref="innerContainer"
+			:append:icon="props['append:icon']"
+			:clearable="clearable && isNotNil(modelValue) && !readonly && !disabled"
+			:prepend:icon="props['prepend:icon']"
+			@click:clear="$emit('update:modelValue', null)"
+		>
+			<template #prepend><slot name="prepend" /></template>
+			<template #prefix><slot name="prefix" /></template>
+
+			<input
+				v-bind="eventListeners"
+				:id="id"
+				v-maska="options"
+				:aria-describedby="ariaDescribedby"
+				:aria-invalid="hasErrors ? true : undefined"
+				:autocomplete="autocomplete"
+				:autofocus="autofocus"
+				class="bb-base-color-input__input"
+				:disabled="disabled"
+				:name="name"
+				:placeholder="placeholder"
+				:readonly="readonly"
+				:required="required"
+				size="1"
+				type="text"
+				:value="modelValue"
+			/>
+
+			<template #append>
+				<BbColorPalette
+					:alpha="alpha"
+					:anchor="innerContainer"
+					:disabled="disabled || readonly"
+					:label="indicatorLabel"
+					:model-value="modelValue"
+					:picker="picker"
+					:swatches="swatches"
+					@update:model-value="emit('update:modelValue', $event)"
+					@update:open="shown = $event"
+				>
+					<template #activator="{ props: dotProps }">
+						<button
+							v-bind="dotProps"
+							class="bb-base-color-input__indicator"
+							:disabled="disabled || readonly"
+							:style="{ backgroundColor: props.modelValue ?? undefined }"
+							type="button"
+						/>
+					</template>
+				</BbColorPalette>
+				<slot name="append">
+					<span class="bb-common-input-inner-container__suffix">
+						<slot name="suffix"></slot>
+					</span>
+				</slot>
+			</template>
+		</CommonInputInnerContainer>
+
+		<template #append-outer><slot name="append-outer"></slot></template>
+	</CommonInputOuterContainer>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { isHex } from '@/utilities/functions/isHex';
+import { isNotNil } from '@/utilities/functions/isNotNil';
+import { ref } from 'vue';
+import { useId } from '@/composables/useId';
+import { useLocale } from '@/composables/useLocale';
+import { vMaska } from 'maska/vue';
+import BbColorPalette from '../BbColorPalette/BbColorPalette.vue';
+import CommonInputInnerContainer from '../CommonInputInnerContainer/CommonInputInnerContainer.vue';
+import CommonInputOuterContainer from '../CommonInputOuterContainer/CommonInputOuterContainer.vue';
+import type { MaskaDetail, MaskInputOptions } from 'maska';
+import type {
+	BaseColorInputEvents,
+	BaseColorInputProps,
+	BaseColorInputSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseColorInputProps>(), {
+	alpha: false,
+	autocomplete: 'off',
+	transitionDuration: 250,
+});
+
+const emit = defineEmits<BaseColorInputEvents>();
+
+defineSlots<BaseColorInputSlots>();
+
+const wrapper = ref<InstanceType<typeof CommonInputOuterContainer> | null>(
+	null
+);
+const innerContainer = ref<InstanceType<
+	typeof CommonInputInnerContainer
+> | null>(null);
+const id = props.id ?? `bb_${useId().id.value}`;
+
+const { t } = useLocale();
+
+const indicatorLabel = computed(() =>
+	props.modelValue
+		? t('colorInput.openPickerSelected', props.modelValue).value
+		: t('colorInput.openPicker').value
+);
+
+const classes = computed(() => ({
+	'bb-base-color-input': true,
+	'bb-base-color-input--disabled': props.disabled,
+	'bb-base-color-input--errors': props.hasErrors,
+	'bb-base-color-input--loading': props.loading,
+	'bb-base-color-input--readonly': props.readonly,
+	'bb-base-color-input--compact': props.compact,
+	'bb-base-color-input--active': shown.value,
+}));
+
+const handleMaska = (event: CustomEvent<MaskaDetail>): void => {
+	const detail = event.detail;
+	if (isHex(detail.masked)) {
+		emit('update:modelValue', detail.masked);
+	} else if (detail.masked === '') {
+		emit('update:modelValue', null);
+	}
+};
+
+/**
+ * These events are just propagated
+ */
+const eventListeners = {
+	onBlur: (event: FocusEvent) => emit('blur', event),
+	onChange: (event: Event) => emit('change', event),
+	onClick: (event: MouseEvent) => emit('click', event),
+	onFocus: (event: FocusEvent) => emit('focus', event),
+	onInput: (event: Event) => emit('input', event),
+	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onMaska: handleMaska,
+	onMousedown: (event: MouseEvent) => emit('mousedown', event),
+	onMouseup: (event: MouseEvent) => emit('mouseup', event),
+};
+
+const options = computed<MaskInputOptions>(() => ({
+	mask: props.alpha ? '!#HHHHHHHH' : '!#HHHHHH',
+	tokens: {
+		H: { pattern: /[0-9a-fA-F]/ },
+	},
+	eager: true,
+}));
+
+// Tracks palette open state (driven by BbColorPalette) for the --active CSS class
+const shown = ref(false);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { IconType } from '@/types/Icon';
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+
+/**
+ * Color input with hex value masking and an optional palette popover.
+ * Accepts and emits `#RRGGBB` (or `#RRGGBBAA` when `alpha` is enabled) values via v-model
+ * and supports full input chrome slots.
+ */
+export type BaseColorInputProps = {
+	/**
+	 * Enable the alpha channel. When true the picker shows an opacity slider and
+	 * emits / accepts `#RRGGBBAA` hex8 values.
+	 */
+	alpha?: boolean;
+	/**
+	 * Name of the icon to render at the right hand side of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'append:icon'?: IconType;
+	/**
+	 * Id(s) of element(s) describing this input for assistive tech (space-separated).
+	 * Typically includes the container hint id if used within a BaseInputContainer.
+	 */
+	ariaDescribedby?: InputHTMLAttributes['aria-describedby'];
+	/**
+	 * Autocomplete hint for the browser.
+	 * @default 'off'
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+	/**
+	 * Focus the input on mount.
+	 */
+	autofocus?: InputHTMLAttributes['autofocus'];
+	/**
+	 * Show a clear button when the input has a value.
+	 */
+	clearable?: boolean;
+	/**
+	 * Display the component in a compact layout.
+	 */
+	compact?: boolean;
+	/**
+	 * Disable all interactions.
+	 */
+	disabled?: boolean;
+	/**
+	 * Visually mark the component as invalid (also sets aria-invalid on the input).
+	 */
+	hasErrors?: boolean;
+	/**
+	 * The id attribute for the input element. Defaults to a generated `bb_<unique>` id when omitted.
+	 */
+	id?: HTMLAttributes['id'];
+	/**
+	 * Display the loading state.
+	 */
+	loading?: boolean;
+	/**
+	 * v-model value: `#RRGGBB` hex string or `null` when empty.
+	 * Example: `#1A2B3C`
+	 */
+	modelValue: string | null;
+	/**
+	 * Name attribute of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+	/**
+	 * Placeholder text when there is no value.
+	 */
+	placeholder?: InputHTMLAttributes['placeholder'];
+	/**
+	 * Name of the icon to render at the start of the input.
+	 */
+	// eslint-disable-next-line vue/prop-name-casing
+	'prepend:icon'?: IconType;
+	/**
+	 * Make the input read-only.
+	 */
+	readonly?: boolean;
+	/**
+	 * Mark the input as required.
+	 */
+	required?: boolean;
+	/**
+	 * Show an eyedropper button to sample any color on screen.
+	 * Uses the native EyeDropper API — hidden automatically on unsupported browsers.
+	 * @default false
+	 */
+	picker?: boolean;
+	/**
+	 * Controls swatches display in the picker:
+	 * - `true`       — show the built-in Material-palette swatches
+	 * - `string[][]` — show custom swatches (each inner array = a column of shades)
+	 * - `false` / omitted — no swatches section
+	 */
+	swatches?: boolean | string[][];
+	/**
+	 * Transition duration (ms) of the palette popover.
+	 * @default 250
+	 */
+	transitionDuration?: number;
+};
+
+/**
+ * Events emitted by the color input.
+ * - blur/change/click/focus/input/keydown/mousedown/mouseup: native input events (payload: original event)
+ * - update:modelValue: emits `#RRGGBB` when valid, `null` when cleared/invalid
+ */
+export type BaseColorInputEvents = {
+	/**
+	 * Emitted when the native text input loses focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the native text input fires a change event.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when the input area receives a click.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when the native text input gains focus.
+	 * Forwards the original DOM `FocusEvent`.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted on native input events from the text field.
+	 * Forwards the original DOM `Event`.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted for keyboard interaction on the input.
+	 * Forwards the original DOM `KeyboardEvent`.
+	 */
+	(e: 'keydown', event: KeyboardEvent): void;
+	/**
+	 * Emitted when a pointing device button is pressed over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mousedown', event: MouseEvent): void;
+	/**
+	 * Emitted when a pointing device button is released over the input.
+	 * Forwards the original DOM `MouseEvent`.
+	 */
+	(e: 'mouseup', event: MouseEvent): void;
+	/**
+	 * Emitted when the value becomes a valid hex color via typing/masking,
+	 * when the field is cleared, or when the palette selects a color.
+	 * Emits:
+	 * - `#RRGGBB` (or `#RRGGBBAA` when `alpha` is enabled) for valid values
+	 * - `null` when cleared
+	 */
+	(e: 'update:modelValue', value: string | null): void;
+};
+
+/**
+ * Slots to customize the input chrome.
+ * Use `prepend`/`append` for inline adornments; `prepend-outer`/`append-outer` for the outer container areas.
+ */
+export type BaseColorInputSlots = {
+	/**
+	 * Content rendered after the color picker indicator button, at the end of the inner container.
+	 * When provided, replaces the default suffix wrapper (use the `suffix` slot if you only need inline trailing text).
+	 * This slot receives no scoped props.
+	 */
+	append?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered after the entire input control, outside the input chrome.
+	 * This slot receives no scoped props.
+	 */
+	'append-outer'?: (props: Record<string, never>) => any;
+	/**
+	 * Inline content rendered at the start of the input field area, before the typed text.
+	 * This slot receives no scoped props.
+	 */
+	prefix?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered before the text input, at the start of the inner container.
+	 * This slot receives no scoped props.
+	 */
+	prepend?: (props: Record<string, never>) => any;
+	/**
+	 * Content rendered before the entire input control, outside the input chrome.
+	 * This slot receives no scoped props.
+	 */
+	'prepend-outer'?: (props: Record<string, never>) => any;
+	/**
+	 * Inline content rendered at the end of the input field area, after the typed text.
+	 * Renders inside the default `append` area's suffix wrapper.
+	 * This slot receives no scoped props.
+	 */
+	suffix?: (props: Record<string, never>) => any;
+};
+
+export type ColorPaletteProps = {
+	/**
+	 * Current color value bound via `v-model`.
+	 * Accepts `#RRGGBB` and `#RRGGBBAA` (alpha) formats, or `null` for no value.
+	 */
+	modelValue: string | null;
+	/**
+	 * Enable alpha channel support.
+	 * When true, an alpha slider is shown and emitted values include alpha as hex8.
+	 * @default false
+	 */
+	alpha?: boolean;
+	/**
+	 * Show an eyedropper button that lets the user sample any color on screen.
+	 * Uses the native EyeDropper API — hidden automatically on unsupported browsers.
+	 * @default false
+	 */
+	picker?: boolean;
+	/**
+	 * Controls swatches display:
+	 * - `true`      — show the built-in Material-palette swatches
+	 * - `string[][]` — show custom swatches (each inner array = a column of shades)
+	 * - `false` / omitted — no swatches section
+	 */
+	swatches?: boolean | string[][];
+};
+
+export type ColorPaletteEvents = {
+	/**
+	 * Emitted whenever the user changes color through:
+	 * - SV canvas dragging/keyboard
+	 * - hue slider dragging/keyboard
+	 * - alpha slider dragging/keyboard (when enabled)
+	 * - swatch selection
+	 * - eyedropper pick
+	 *
+	 * Payload format:
+	 * - `#RRGGBB` when `alpha` is disabled
+	 * - `#RRGGBBAA` when `alpha` is enabled
+	 */
+	(e: 'update:modelValue', value: string): void;
+};
+```
+
+## Styles
+
+```css
+.bb-base-color-input {
+	--bb-arrow: 0;
+	position: relative;
+	&--disabled {
+	}
+	&--errors {
+	}
+	&--loading {
+	}
+	&--readonly {
+	}
+
+	.bb-common-input-inner-container {
+		position: relative;
+		.bb-base-color-input__input {
+		}
+		.bb-base-color-input__indicator {
+			background-color: inherit;
+			border: 1px solid var(--bb-border);
+			border-radius: var(--bb-radius);
+			cursor: pointer;
+			display: inline-block;
+			height: var(--bb-input-icon);
+			outline: none;
+			width: var(--bb-input-icon);
+			isolation: isolate;
+
+			box-shadow: 0px 0px 0px 0px var(--bb-ring);
+			transition: box-shadow 150ms cubic-bezier(0.4, 0, 0.2, 1);
+			&:focus-visible {
+				box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+			}
+		}
+
+		&__prepend-icon,
+		&__append-icon {
+		}
+		.bb-spinner {
+		}
+		.bb-error-icon {
+		}
+		&__prefix,
+		&__suffix {
+		}
+	}
+}
+```