bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/dist/ai/source/BbTag.md

@@ -158,6 +158,7 @@ import {
 	formControlPtActive,
 	TEXT_CONTROL_NATIVE_ATTRS,
 	usePassthrough,
+	variantPt,
 } from '@/composables/usePassthrough';
 import { useBaseOptions } from '@/composables/useBaseOptions';
 import { useConfig } from '@/composables/useConfig';
@@ -175,7 +176,11 @@ import {
 	type BbTagSlots,
 } from './types';
 
-defineOptions({ inheritAttrs: false });
+defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_TAG_PT)],
+	inheritAttrs: false,
+});
 const declaredProps = withDefaults(defineProps<BbTagProps>(), {
 	autocomplete: 'off',
 	divider: 'Enter',
@@ -258,6 +263,11 @@ const passthrough = usePassthrough({
 	parts: BB_TAG_PT.parts,
 	states: BB_TAG_PT.states,
 	active: formControlPtActive(props, () => hasValue.value),
+	variant: {
+		...BB_TAG_PT.variant,
+		// CommonFieldInput's default.
+		current: () => props.variant ?? 'outline',
+	},
 });
 
 const logger = useLogger();
@@ -655,7 +665,12 @@ onBeforeUnmount(leave);
 
 ```ts
 import type { Responsive } from '@/types/ResponsiveSize';
-import type { InputVariantType } from '@/types/InputVariant';
+import {
+	INPUT_VARIANTS,
+	type InputVariantBuiltIn,
+	type InputVariantRegistry,
+	type InputVariantType,
+} from '@/types/InputVariant';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
 import {
 	type FormControlPtState,
@@ -666,6 +681,7 @@ import {
 	type PtValue,
 	TEXT_CONTROL_PT_PARTS,
 	type TextControlPtPart,
+	type PtVariantAttrs,
 } from '@/types/passthrough';
 import type { FieldCrossAlign, FieldLayout } from '@/types/FieldLayout';
 import type { IconType } from '@/types/Icon';
@@ -714,7 +730,19 @@ export const BB_TAG_PT = {
 	/** `rowStates` are declared on `rowParts` only. */
 	rowParts: ['badge', 'comma'],
 	rowStates: ['highlighted'],
+	// The input `variant` is a state on the field's parts (Q76.7), below
+	// the real states; a picker's panel and rows are not the field's.
+	variant: {
+		names: INPUT_VARIANTS,
+		option: 'inputVariants',
+		parts: TEXT_CONTROL_PT_PARTS,
+	},
 } as const satisfies {
+	variant: {
+		names: readonly InputVariantBuiltIn[];
+		option: string;
+		parts: readonly TextControlPtPart[];
+	};
 	parts: readonly BbTagPtPart[];
 	states: readonly BbTagPtState[];
 	rowParts: readonly BbTagPtPart[];
@@ -731,238 +759,244 @@ export type BbTagProps = {
 		| `pt:${TextControlPtPart}`
 		| `pt:${BbTagPtPart}:${FormControlPtState}`
 		| 'pt:badge:highlighted'
-		| 'pt:comma:highlighted']?: PtValue;
-} & {
-	// The tag parts also take a per-item function, called with the tag — a
-	// literal function type, not `PtItemFn` (T23).
-	[K in `pt:${BbTagItemPtPart}`]?:
-		| PtValue
-		| ((ctx: PtItemCtx<string, BbTagPtState>) => PtItemResult);
-} & {
-	/**
-	 * Passthrough, object form: the same keys as the `pt:*` attributes
-	 * without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtMap<TextControlPtPart, FormControlPtState> & {
-		[K in
-			| `${BbTagItemPtPart}:${FormControlPtState}`
-			| 'badge:highlighted'
-			| 'comma:highlighted']?: PtValue;
+		| 'pt:comma:highlighted'
+		| `pt:${TextControlPtPart}:${InputVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	TextControlPtPart,
+	keyof InputVariantRegistry
+> & {
+		// The tag parts also take a per-item function, called with the tag — a
+		// literal function type, not `PtItemFn` (T23).
+		[K in `pt:${BbTagItemPtPart}`]?:
+			| PtValue
+			| ((ctx: PtItemCtx<string, BbTagPtState>) => PtItemResult);
 	} & {
-		[K in BbTagItemPtPart]?: PtValue | PtItemFn<string, BbTagPtState>;
-	};
-	/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
-	/**
-	 * Name of the icon to be added at the end of the input.
-	 */
-
-	'append:icon'?: IconType;
-
-	/**
-	 * Guides to the browser as to the type of information expected in the field.
-	 *
-	 * @defaultValue `'off'`
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Compares tags case-sensitively when rejecting duplicates (`Vue` and `vue`
-	 * both allowed); by default case folds. A tag keeps the casing typed either
-	 * way, and entries are trimmed first.
-	 *
-	 * @defaultValue `false`
-	 */
-	caseSensitive?: boolean;
-
-	/**
-	 * Sets the display model for selected values to a list of comma separated string.
-	 * In this mode the user cannot deselect an option by pressing the close button.
-	 */
-	comma?: boolean;
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Compact density: the field uses the `-compact` twins of `--bb-input-h`,
-	 * `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on
-	 * the component is ignored while it is on. Size a compact field with
-	 * `--bb-input-h-compact` (and `--bb-input-py-compact`).
-	 */
-	compact?: boolean;
-
-	/**
-	 * The field box's look, with `BbButton`'s names and tokens. Colours only,
-	 * so a form never reflows; `'ghost'` has no border in any state, `'none'`
-	 * no look at all (you own hover, focus and the states). Register more with
-	 * the plugin's `inputVariants`.
-	 *
-	 * @defaultValue `'outline'`
-	 */
-	variant?: InputVariantType;
-
-	/**
-	 * Text between the label and the input. Unlike the hint it is always
-	 * visible; it joins the input's `aria-describedby` after any `errors` /
-	 * `warnings`, before the `hint`.
-	 */
-	description?: string;
-
-	/**
-	 * How label and input sit together: `'vertical'`, `'horizontal'` (50/50),
-	 * `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a
-	 * per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`).
-	 */
-	layout?: Responsive<FieldLayout>;
-
-	/**
-	 * Vertical position of the label block in a side-by-side row; not
-	 * `labelPosition`, the horizontal one. Omitted, the label's first line
-	 * meets the control's.
-	 */
-	labelAlign?: FieldCrossAlign;
-
-	/**
-	 * Vertical position of the control in a side-by-side row; not
-	 * `inputPosition`, the horizontal one. Omitted, the control's first line
-	 * meets the label's.
-	 */
-	inputAlign?: FieldCrossAlign;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * The divider key used to separate values from one another. By default it is "Enter".
-	 * Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them
-	 * commits the current text, split on every single-character divider in the
-	 * set into one tag per trimmed, non-empty piece.
-	 *
-	 * @defaultValue `'Enter'`
-	 */
-	divider?: KeyboardEvent['key'] | Array<KeyboardEvent['key']>;
-
-	/**
-	 * Error messages under the field, a string or array, in an
-	 * `aria-live="polite"` region and first in the control's
-	 * `aria-describedby`, so they are re-read when it regains focus.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Warning messages under the field, a string or array: amber, in their own
-	 * `aria-live` region and in the control's `aria-describedby` after the
-	 * errors. Non-empty turns on the warning state; errors win when both are
-	 * set.
-	 */
-	warnings?: string | string[];
-
-	/**
-	 * Define if the component should be in a warning state.
-	 * Same chrome as errors with `--bb-warn`; errors take priority.
-	 */
-	hasWarnings?: 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 `id` of the native control; the label's `for` and the description
-	 * and message ids derive from it. Generated when omitted.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Where the label sits relative to the field: `outside` above it, `inside`
-	 * within the control, or `floating` (starts inside, lifts on focus/value).
-	 * Defaults to `config.defaultInputLabelMode`, like the other inputs.
-	 */
-	labelMode?: 'outside' | 'floating' | 'inside';
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * Maximum number of selected items.
-	 */
-	max?: number;
-
-	/**
-	 * Used by v-model. Contains all selected tags.
-	 */
-	modelValue?: string[];
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * Text shown while the field is empty.
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-
-	'prepend:icon'?: IconType;
-
-	/**
-	 * 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.
-	 */
-	reverse?: boolean;
-} & FormFieldProps<string[]>;
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		pt?: PtMap<TextControlPtPart, FormControlPtState> & {
+			[K in
+				| `${BbTagItemPtPart}:${FormControlPtState}`
+				| 'badge:highlighted'
+				| 'comma:highlighted']?: PtValue;
+		} & {
+			[K in BbTagItemPtPart]?: PtValue | PtItemFn<string, BbTagPtState>;
+		} & {
+			[K in `${TextControlPtPart}:${InputVariantBuiltIn | keyof InputVariantRegistry}`]?: PtValue;
+		};
+		/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+		/**
+		 * Name of the icon to be added at the end of the input.
+		 */
+
+		'append:icon'?: IconType;
+
+		/**
+		 * Guides to the browser as to the type of information expected in the field.
+		 *
+		 * @defaultValue `'off'`
+		 */
+		autocomplete?: InputHTMLAttributes['autocomplete'];
+
+		/**
+		 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
+		 */
+		autofocus?: InputHTMLAttributes['autofocus'];
+
+		/**
+		 * Compares tags case-sensitively when rejecting duplicates (`Vue` and `vue`
+		 * both allowed); by default case folds. A tag keeps the casing typed either
+		 * way, and entries are trimmed first.
+		 *
+		 * @defaultValue `false`
+		 */
+		caseSensitive?: boolean;
+
+		/**
+		 * Sets the display model for selected values to a list of comma separated string.
+		 * In this mode the user cannot deselect an option by pressing the close button.
+		 */
+		comma?: boolean;
+
+		/**
+		 * Displays a clear button when the input has a value and is being interacted with.
+		 */
+		clearable?: boolean;
+
+		/**
+		 * Compact density: the field uses the `-compact` twins of `--bb-input-h`,
+		 * `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on
+		 * the component is ignored while it is on. Size a compact field with
+		 * `--bb-input-h-compact` (and `--bb-input-py-compact`).
+		 */
+		compact?: boolean;
+
+		/**
+		 * The field box's look, with `BbButton`'s names and tokens. Colours only,
+		 * so a form never reflows; `'ghost'` has no border in any state, `'none'`
+		 * no look at all (you own hover, focus and the states). Register more with
+		 * the plugin's `inputVariants`.
+		 *
+		 * @defaultValue `'outline'`
+		 */
+		variant?: InputVariantType;
+
+		/**
+		 * Text between the label and the input. Unlike the hint it is always
+		 * visible; it joins the input's `aria-describedby` after any `errors` /
+		 * `warnings`, before the `hint`.
+		 */
+		description?: string;
+
+		/**
+		 * How label and input sit together: `'vertical'`, `'horizontal'` (50/50),
+		 * `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a
+		 * per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`).
+		 */
+		layout?: Responsive<FieldLayout>;
+
+		/**
+		 * Vertical position of the label block in a side-by-side row; not
+		 * `labelPosition`, the horizontal one. Omitted, the label's first line
+		 * meets the control's.
+		 */
+		labelAlign?: FieldCrossAlign;
+
+		/**
+		 * Vertical position of the control in a side-by-side row; not
+		 * `inputPosition`, the horizontal one. Omitted, the control's first line
+		 * meets the label's.
+		 */
+		inputAlign?: FieldCrossAlign;
+
+		/**
+		 * Disables the component.
+		 */
+		disabled?: boolean;
+
+		/**
+		 * The divider key used to separate values from one another. By default it is "Enter".
+		 * Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them
+		 * commits the current text, split on every single-character divider in the
+		 * set into one tag per trimmed, non-empty piece.
+		 *
+		 * @defaultValue `'Enter'`
+		 */
+		divider?: KeyboardEvent['key'] | Array<KeyboardEvent['key']>;
+
+		/**
+		 * Error messages under the field, a string or array, in an
+		 * `aria-live="polite"` region and first in the control's
+		 * `aria-describedby`, so they are re-read when it regains focus.
+		 */
+		errors?: string | string[];
+
+		/**
+		 * Define if the component should be in an error state.
+		 * It usually attaches a CSS class for styling purposes.
+		 */
+		hasErrors?: boolean;
+
+		/**
+		 * Warning messages under the field, a string or array: amber, in their own
+		 * `aria-live` region and in the control's `aria-describedby` after the
+		 * errors. Non-empty turns on the warning state; errors win when both are
+		 * set.
+		 */
+		warnings?: string | string[];
+
+		/**
+		 * Define if the component should be in a warning state.
+		 * Same chrome as errors with `--bb-warn`; errors take priority.
+		 */
+		hasWarnings?: 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 `id` of the native control; the label's `for` and the description
+		 * and message ids derive from it. Generated when omitted.
+		 */
+		id?: HTMLAttributes['id'];
+
+		/**
+		 * Text content of the label of the element.
+		 */
+		label: string;
+
+		/**
+		 * Where the label sits relative to the field: `outside` above it, `inside`
+		 * within the control, or `floating` (starts inside, lifts on focus/value).
+		 * Defaults to `config.defaultInputLabelMode`, like the other inputs.
+		 */
+		labelMode?: 'outside' | 'floating' | 'inside';
+
+		/**
+		 * Sets the text alignment of the label.
+		 */
+		labelPosition?: 'left' | 'center' | 'right';
+
+		/**
+		 * Sets the component in a loading state, usually triggering some visual styles.
+		 */
+		loading?: boolean;
+
+		/**
+		 * Maximum number of selected items.
+		 */
+		max?: number;
+
+		/**
+		 * Used by v-model. Contains all selected tags.
+		 */
+		modelValue?: string[];
+
+		/**
+		 * Defines the name of the input.
+		 */
+		name?: InputHTMLAttributes['name'];
+
+		/**
+		 * Keeps the hint displayed.
+		 */
+		persistentHint?: boolean;
+
+		/**
+		 * Text shown while the field is empty.
+		 */
+		placeholder?: InputHTMLAttributes['placeholder'];
+
+		/**
+		 * Name of the icon to be added at the start of the input.
+		 */
+
+		'prepend:icon'?: IconType;
+
+		/**
+		 * 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.
+		 */
+		reverse?: boolean;
+	} & FormFieldProps<string[]>;
 
 export type BbTagEvents = {
 	/** Emitted when the native input loses focus. Forwards the original DOM `FocusEvent`. */