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

package/dist/ai/source/BbTextInput.md

@@ -138,6 +138,7 @@ import {
 	formControlPtActive,
 	TEXT_CONTROL_NATIVE_ATTRS,
 	usePassthrough,
+	variantPt,
 } from '@/composables/usePassthrough';
 import { hash } from '@/utilities/functions/hash';
 import { isNotEmpty } from '@/utilities/functions/isNotEmpty';
@@ -148,7 +149,11 @@ import {
 	type BbTextInputSlots,
 } from './types';
 
-defineOptions({ inheritAttrs: false });
+defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_TEXT_INPUT_PT)],
+	inheritAttrs: false,
+});
 const declaredProps = withDefaults(defineProps<BbTextInputProps<E>>(), {
 	type: 'text',
 });
@@ -227,6 +232,11 @@ const passthrough = usePassthrough({
 		nearLimit: () => characterCounter.value?.state === 'near',
 		atLimit: () => characterCounter.value?.state === 'limit',
 	},
+	variant: {
+		...BB_TEXT_INPUT_PT.variant,
+		// CommonFieldInput's default.
+		current: () => props.variant ?? 'outline',
+	},
 });
 
 const input = ref<HTMLInputElement | null>(null);
@@ -449,7 +459,12 @@ const inputBindings = computed(() =>
 
 ```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 { FieldCrossAlign, FieldLayout } from '@/types/FieldLayout';
 import type { MaskInputOptions } from 'maska';
@@ -464,6 +479,7 @@ import {
 	type PtMap,
 	type PtValue,
 	type TextControlPtPart,
+	type PtVariantAttrs,
 } from '@/types/passthrough';
 import type { FormFieldProps } from '@/composables/useFormBinding';
 import type {
@@ -494,7 +510,19 @@ export const BB_TEXT_INPUT_PT = {
 		...COUNTER_PT_STATES,
 		...FORM_CONTROL_PT_STATES.slice(1),
 	],
+	// 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 BbTextInputPtPart[];
 	states: readonly BbTextInputPtState[];
 };
@@ -510,229 +538,237 @@ type AppPolicy = RegisteredNullValue<'BbTextInput'>;
 export type BbTextInputProps<E extends NullValuePolicy = AppPolicy> = {
 	[K in
 		| `pt:${BbTextInputPtPart}`
-		| `pt:${BbTextInputPtPart}:${BbTextInputPtState}`]?: PtValue;
-} & {
-	/**
-	 * Passthrough, object form: `{ box: '…', 'box:errors': '…' }` — the same
-	 * keys as the `pt:*` attributes without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtMap<BbTextInputPtPart, BbTextInputPtState>;
-	/**
-	 * 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.
-	 */
-	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'];
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Shows a character count at the end of the hint row: `42`, or `42 / 140`
-	 * with the native `maxlength` (which also stops input). It brightens from
-	 * 90 % and takes the warning colour at the limit; screen readers hear it
-	 * only when it crosses 90 % or the limit.
-	 */
-	counter?: 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;
-
-	/**
-	 * Emits the masked value of the input.
-	 */
-	emitMasked?: boolean;
-
-	/**
-	 * 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'];
-
-	/**
-	 * The inputmode of the input.
-	 */
-	inputMode?: InputHTMLAttributes['inputmode'];
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Label rendering mode.
-	 */
-	labelMode?: 'outside' | 'floating' | 'inside';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * A maska options object, not a string: `{ mask: '#### #### #### ####' }`.
-	 * Please visit https://beholdr.github.io/maska/v3 for syntax examples.
-	 */
-	mask?: MaskInputOptions;
-
-	/**
-	 * Used by v-model.
-	 */
-	modelValue?: string | null;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * What the field emits once emptied (typing, the clear button, an empty
-	 * mask): `'null'` emits `null`, `'string'` emits `''`. Unset:
-	 * `formControls.textInputNullValue` (`'null'`). With `'string'`, the
-	 * `update:modelValue` payload types as `string`.
-	 */
-	nullValue?: E;
-
-	/**
-	 * 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 native `required` attribute, for a plain `<form>`. Inside a `BbForm` it is an error (nothing enforces it): use `rules="required"` or the form `schema` instead.
-	 */
-	required?: boolean;
-
-	/**
-	 * Reverses the layout. Applicable in every direction the order of the label and
-	 * the input is swapped.
-	 */
-	reverse?: boolean;
-
-	/**
-	 * Type of the input. Restricted to the textual input types this component
-	 * supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates.
-	 *
-	 * @defaultValue `'text'`
-	 */
-	type?: 'text' | 'email' | 'url' | 'tel' | 'search' | 'password';
-} & FormFieldProps<string | null>;
+		| `pt:${BbTextInputPtPart}:${BbTextInputPtState}`
+		| `pt:${TextControlPtPart}:${InputVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	TextControlPtPart,
+	keyof InputVariantRegistry
+> & {
+		/**
+		 * Passthrough, object form: `{ box: '…', 'box:errors': '…' }` — the same
+		 * keys as the `pt:*` attributes without the prefix. See the `pt:<part>` row.
+		 */
+		/* eslint-disable @typescript-eslint/consistent-indexed-object-style -- mapped, never Record (T23) */
+		pt?: PtMap<BbTextInputPtPart, BbTextInputPtState> & {
+			[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.
+		 */
+		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'];
+
+		/**
+		 * Displays a clear button when the input has a value and is being interacted with.
+		 */
+		clearable?: boolean;
+
+		/**
+		 * Shows a character count at the end of the hint row: `42`, or `42 / 140`
+		 * with the native `maxlength` (which also stops input). It brightens from
+		 * 90 % and takes the warning colour at the limit; screen readers hear it
+		 * only when it crosses 90 % or the limit.
+		 */
+		counter?: 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;
+
+		/**
+		 * Emits the masked value of the input.
+		 */
+		emitMasked?: boolean;
+
+		/**
+		 * 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'];
+
+		/**
+		 * The inputmode of the input.
+		 */
+		inputMode?: InputHTMLAttributes['inputmode'];
+
+		/**
+		 * Text content of the label of the element.
+		 */
+		label: string;
+
+		/**
+		 * Sets the text alignment of the label.
+		 */
+		labelPosition?: 'left' | 'center' | 'right';
+
+		/**
+		 * Label rendering mode.
+		 */
+		labelMode?: 'outside' | 'floating' | 'inside';
+
+		/**
+		 * Sets the component in a loading state, usually triggering some visual styles.
+		 */
+		loading?: boolean;
+
+		/**
+		 * A maska options object, not a string: `{ mask: '#### #### #### ####' }`.
+		 * Please visit https://beholdr.github.io/maska/v3 for syntax examples.
+		 */
+		mask?: MaskInputOptions;
+
+		/**
+		 * Used by v-model.
+		 */
+		modelValue?: string | null;
+
+		/**
+		 * Defines the name of the input.
+		 */
+		name?: InputHTMLAttributes['name'];
+
+		/**
+		 * What the field emits once emptied (typing, the clear button, an empty
+		 * mask): `'null'` emits `null`, `'string'` emits `''`. Unset:
+		 * `formControls.textInputNullValue` (`'null'`). With `'string'`, the
+		 * `update:modelValue` payload types as `string`.
+		 */
+		nullValue?: E;
+
+		/**
+		 * 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 native `required` attribute, for a plain `<form>`. Inside a `BbForm` it is an error (nothing enforces it): use `rules="required"` or the form `schema` instead.
+		 */
+		required?: boolean;
+
+		/**
+		 * Reverses the layout. Applicable in every direction the order of the label and
+		 * the input is swapped.
+		 */
+		reverse?: boolean;
+
+		/**
+		 * Type of the input. Restricted to the textual input types this component
+		 * supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates.
+		 *
+		 * @defaultValue `'text'`
+		 */
+		type?: 'text' | 'email' | 'url' | 'tel' | 'search' | 'password';
+	} & FormFieldProps<string | null>;
 
 export type BbTextInputEvents<E extends NullValuePolicy = AppPolicy> = {
 	/**