bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/source/BbBaseColorInput.md

@@ -1,431 +0,0 @@
-# BbBaseColorInput — Implementation Source
-
-> Full implementation for deep dives. For everyday usage read the typed contract: [../BbBaseColorInput.md](../BbBaseColorInput.md).
->
-> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
-
-## Template & Script
-
-```vue
-<template>
-	<CommonInputWrapper
-		ref="wrapperRef"
-		:append:icon="props['append:icon']"
-		class="bb-base-color-input"
-		:clearable="clearable && isNotNil(modelValue) && !readonly && !disabled"
-		:compact="props.compact"
-		:disabled="props.disabled"
-		:has-errors="props.hasErrors"
-		:has-value="isNotNil(modelValue)"
-		:has-warning="props.hasWarning"
-		:loading="props.loading"
-		:prepend:icon="props['prepend:icon']"
-		:readonly="props.readonly"
-		@click:clear="$emit('update:modelValue', null)"
-	>
-		<template #prepend-outer><slot name="prepend-outer"></slot></template>
-		<template #prepend><slot name="prepend" /></template>
-		<template v-if="$slots.prefix" #prefix><slot name="prefix" /></template>
-
-		<input
-			v-bind="eventListeners"
-			:id="id"
-			v-maska="options"
-			:aria-describedby="ariaDescribedby"
-			:aria-disabled="disabled || undefined"
-			:aria-invalid="hasErrors ? true : undefined"
-			:aria-readonly="readonly || 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
-				:adaptive="adaptive"
-				:alpha="alpha"
-				:anchor="wrapperRef"
-				:disabled="disabled || readonly"
-				:eye-dropper="eyeDropper"
-				:label="indicatorLabel"
-				:model-value="modelValue"
-				:swatches="swatches"
-				:transition-duration="transitionDuration"
-				@update:model-value="emit('update:modelValue', $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 v-if="$slots.suffix" class="common-input-wrapper__suffix">
-					<slot name="suffix" />
-				</span>
-			</slot>
-		</template>
-
-		<template #append-outer><slot name="append-outer"></slot></template>
-	</CommonInputWrapper>
-</template>
-
-<script setup lang="ts">
-import { computed, ref } from 'vue';
-import { isHex } from '@/utilities/functions/isHex';
-import { isNotNil } from '@/utilities/functions/isNotNil';
-import { useId } from '@/composables/useId';
-import { useLocale } from '@/composables/useLocale';
-import { vMaska } from 'maska/vue';
-import BbColorPalette from '../BbColorPalette/BbColorPalette.vue';
-import CommonInputWrapper from '../CommonInputWrapper/CommonInputWrapper.vue';
-import type { MaskaDetail, MaskInputOptions } from 'maska';
-import type {
-	BaseColorInputEvents,
-	BaseColorInputProps,
-	BaseColorInputSlots,
-} from './types';
-
-const props = withDefaults(defineProps<BaseColorInputProps>(), {
-	// `undefined` (declared, not omitted) keeps `adaptive` three-state: it
-	// disables Vue's absent→`false` Boolean cast so BbColorPalette's
-	// `props.adaptive ?? config.adaptive` can reach the config default, while
-	// keeping the Boolean type so the valueless `adaptive` shorthand → `true`.
-	adaptive: undefined,
-	alpha: false,
-	autocomplete: 'off',
-});
-
-const emit = defineEmits<BaseColorInputEvents>();
-
-defineSlots<BaseColorInputSlots>();
-
-const wrapperRef = ref<InstanceType<typeof CommonInputWrapper> | 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 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);
-	}
-};
-
-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),
-	onKeyup: (event: KeyboardEvent) => emit('keyup', event),
-	onMaska: handleMaska,
-	onMousedown: (event: MouseEvent) => emit('mousedown', event),
-	onMouseup: (event: MouseEvent) => emit('mouseup', event),
-	onPaste: (event: ClipboardEvent) => emit('paste', event),
-	onCompositionstart: (event: CompositionEvent) =>
-		emit('compositionstart', event),
-	onCompositionend: (event: CompositionEvent) => emit('compositionend', event),
-};
-
-const options = computed<MaskInputOptions>(() => ({
-	mask: props.alpha ? '!#HHHHHHHH' : '!#HHHHHH',
-	tokens: {
-		H: { pattern: /[0-9a-fA-F]/ },
-	},
-	eager: true,
-}));
-</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 = {
-	/**
-	 * When `true`, the palette opens as a bottom off-canvas sheet on mobile
-	 * viewports instead of a floating popover. Forwarded to `BbColorPalette`,
-	 * which resolves the fallback.
-	 *
-	 * When unset, falls back to the global `config.adaptive`.
-	 * @defaultValue `config.adaptive` (`true`)
-	 */
-	adaptive?: boolean;
-	/**
-	 * Enable the alpha channel. When true the picker shows an opacity slider and
-	 * emits / accepts `#RRGGBBAA` hex8 values.
-	 *
-	 * @defaultValue `false`
-	 */
-	alpha?: boolean;
-	/**
-	 * Name of the icon to render at the right hand side of the input.
-	 */
-
-	'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.
-	 * @defaultValue `'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;
-	/**
-	 * Apply warning styling (same chrome as errors, `--bb-warn` color).
-	 * Suppressed when `hasErrors` is also set.
-	 */
-	hasWarning?: 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.
-	 */
-
-	'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.
-	 * @defaultValue `false`
-	 */
-	eyeDropper?: 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.
-	 * Forwarded to `BbColorPalette`, which supplies the default.
-	 * @defaultValue `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;
-	(e: 'keyup', 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;
-	/** Native clipboard paste. Forwards the original DOM `ClipboardEvent`. */
-	(e: 'paste', event: ClipboardEvent): void;
-	/** IME composition start/end. Forwards the original DOM `CompositionEvent`. */
-	(e: 'compositionstart', event: CompositionEvent): void;
-	(e: 'compositionend', event: CompositionEvent): 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.
-	 * Mutually exclusive with `suffix`: the `suffix` slot renders inside this
-	 * slot's default content, so providing `append` replaces the suffix
-	 * rendering entirely and any `suffix` content is silently dropped.
-	 * 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 — mutually
-	 * exclusive with `append`: if an `append` slot is provided it replaces this
-	 * wrapper and the `suffix` content is not rendered.
-	 * This slot receives no scoped props.
-	 */
-	suffix?: (props: Record<string, never>) => any;
-};
-```
-
-## Styles
-
-```css
-.bb-base-color-input {
-	--bb-arrow: 0;
-	position: relative;
-
-	.common-input-wrapper__inner {
-		position: relative;
-	}
-	&__indicator {
-		background-color: inherit;
-		border: 1px solid var(--bb-border);
-		border-radius: 999px;
-		box-shadow: 0px 0px 0px 0px var(--bb-ring);
-		cursor: pointer;
-		display: inline-block;
-		height: var(--bb-input-icon);
-		isolation: isolate;
-		outline: none;
-		transition: box-shadow color background-color var(--bb-transition-fast)
-			var(--bb-ease);
-		width: var(--bb-input-icon);
-
-		&:focus-visible {
-			box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
-		}
-	}
-	.bb-common-popover {
-		overflow: visible;
-		/* Match the dropdown's popover drop shadow. */
-		.bb-common-popover__bubble {
-			box-shadow: var(--bb-shadow);
-		}
-	}
-}
-```