@a-type/ui 6.0.22 → 6.0.23

package/src/components/forms/CheckboxField.tsx

@@ -1,8 +1,8 @@
 import { useField } from 'formik';
+import { ReactNode } from 'react';
 import { useIdOrGenerated } from '../../hooks/useIdOrGenerated.js';
-import { Box } from '../box/Box.js';
 import { Checkbox } from '../checkbox/index.js';
-import { HorizontalFieldLabel } from './FieldLabel.js';
+import { Field } from './Field.js';
 
 export interface CheckboxFieldProps {
 	name: string;
@@ -10,6 +10,7 @@ export interface CheckboxFieldProps {
 	required?: boolean;
 	className?: string;
 	id?: string;
+	description?: ReactNode;
 }
 
 export function CheckboxField({
@@ -18,24 +19,31 @@ export function CheckboxField({
 	className,
 	required,
 	id: providedId,
+	description,
 	...rest
 }: CheckboxFieldProps) {
 	const [props, _, tools] = useField({ name, required, type: 'checkbox' });
 	const id = useIdOrGenerated(providedId);
 	return (
-		<Box gap="md" className={className}>
-			<Checkbox
-				{...props}
-				checked={props.checked}
-				onCheckedChange={(v) => {
-					tools.setValue(!!v);
-				}}
-				id={id}
-				{...rest}
-			/>
-			{label && (
-				<HorizontalFieldLabel htmlFor={id}>{label}</HorizontalFieldLabel>
+		<Field horizontal className={className}>
+			<Field.Control>
+				<Checkbox
+					{...props}
+					checked={props.checked}
+					onCheckedChange={(v) => {
+						tools.setValue(!!v);
+					}}
+					id={id}
+					aria-describedby={description ? `${id}-description` : undefined}
+					{...rest}
+				/>
+			</Field.Control>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
 			)}
-		</Box>
+		</Field>
 	);
 }

package/src/components/forms/EmojiField.tsx

@@ -1,19 +1,19 @@
 import { useField } from 'formik';
-import { useState } from 'react';
+import { ReactNode, useState } from 'react';
 import { useIdOrGenerated } from '../../hooks/useIdOrGenerated.js';
-import { Box } from '../box/Box.js';
 import { Button, ButtonProps } from '../button/Button.js';
 import { EmojiPicker } from '../emojiPicker/EmojiPicker.js';
 import { Icon } from '../icon/Icon.js';
 import { Popover } from '../popover/Popover.js';
 import cls from './EmojiField.module.css';
-import { HorizontalFieldLabel } from './FieldLabel.js';
+import { Field } from './Field.js';
 
 export type EmojiFieldProps = Omit<ButtonProps, 'className'> & {
 	name: string;
 	label?: string;
 	required?: string;
 	className?: string;
+	description?: ReactNode;
 };
 
 export function EmojiField({
@@ -22,44 +22,61 @@ export function EmojiField({
 	className,
 	required,
 	id: providedId,
+	description,
 	...rest
 }: EmojiFieldProps) {
 	const [props, _, tools] = useField({ name });
 	const id = useIdOrGenerated(providedId);
 	const [open, setOpen] = useState(false);
 	return (
-		<Box gap="md" className={className}>
-			<Popover open={open} onOpenChange={setOpen}>
-				<Popover.Trigger
-					render={
-						<Button id={id} aria-label="Select emoji" size="wrapper" {...rest}>
-							<Button.Icon className={cls.triggerIcon}>
-								{props.value || <Icon name="smile" />}
-							</Button.Icon>
-						</Button>
-					}
-				/>
-				<Popover.Content>
-					<EmojiPicker
-						onValueChange={(v) => {
-							tools.setValue(v);
-							setOpen(false);
-						}}
-						onClear={
-							required
-								? undefined
-								: () => {
-										tools.setValue('');
-										setOpen(false);
-								  }
-						}
+		<Field horizontal className={className}>
+			<Field.Control>
+				<Popover open={open} onOpenChange={setOpen}>
+					<input
+						type="hidden"
+						{...props}
 						id={id}
+						aria-describedby={description ? `${id}-description` : undefined}
+					/>
+					<Popover.Trigger
+						render={
+							<Button
+								id={`${id}-trigger`}
+								aria-label="Select emoji"
+								size="wrapper"
+								{...rest}
+							>
+								<Button.Icon className={cls.triggerIcon}>
+									{props.value || <Icon name="smile" />}
+								</Button.Icon>
+							</Button>
+						}
 					/>
-				</Popover.Content>
-			</Popover>
-			{label && (
-				<HorizontalFieldLabel htmlFor={id}>{label}</HorizontalFieldLabel>
+					<Popover.Content>
+						<EmojiPicker
+							onValueChange={(v) => {
+								tools.setValue(v);
+								setOpen(false);
+							}}
+							onClear={
+								required
+									? undefined
+									: () => {
+											tools.setValue('');
+											setOpen(false);
+									  }
+							}
+							id={id}
+						/>
+					</Popover.Content>
+				</Popover>
+			</Field.Control>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
 			)}
-		</Box>
+		</Field>
 	);
 }

package/src/components/forms/Field.module.css

@@ -0,0 +1,51 @@
+.root {
+	display: grid;
+	grid-template-areas: 'label' 'control' 'description';
+	justify-content: start;
+
+	&[data-horizontal] {
+		flex-direction: row;
+		align-items: center;
+		grid-template-areas: 'control label' 'description description';
+		grid-template-columns: auto 1fr;
+	}
+
+	&[data-stretch] {
+		align-self: stretch;
+		justify-content: stretch;
+	}
+}
+
+.control {
+	grid-area: control;
+}
+:where(.control) {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--m-space-sm);
+}
+
+.label {
+	grid-area: label;
+	@apply --mx-prose-ambient;
+	@apply --mx-fg(var(--m-color-neutral-heavy));
+	font-weight: var(--m-text-weight-bold);
+	margin-bottom: var(--m-space-xs);
+	margin-left: calc(var(--m-global-shape-roundness) * var(--m-space-md));
+
+	[data-horizontal] & {
+		@apply --mx-fg(var(--m-color-neutral-ink));
+		font-weight: var(--m-text-weight-normal);
+		margin-block-start: --fn-literal(5px);
+	}
+}
+
+.description {
+	grid-area: description;
+	@apply --mx-prose-ambient;
+	@apply --mx-fg(var(--m-color-neutral-heavy));
+	font-style: italic;
+	margin-top: var(--m-space-sm);
+	margin-left: calc(var(--m-global-shape-roundness) * var(--m-space-md));
+}

package/src/components/forms/Field.tsx

@@ -0,0 +1,43 @@
+import clsx from 'clsx';
+import { ComponentProps } from 'react';
+import { SlotDiv } from '../utility/SlotDiv.js';
+import cls from './Field.module.css';
+
+export interface FieldRootProps extends ComponentProps<'div'> {
+	horizontal?: boolean;
+	stretch?: boolean;
+}
+
+function FieldRoot({ className, horizontal, ...props }: FieldRootProps) {
+	return (
+		<SlotDiv
+			className={clsx(cls.root, className)}
+			data-horizontal={horizontal ? '' : undefined}
+			data-stretch={props.stretch ? '' : undefined}
+			{...props}
+		/>
+	);
+}
+
+function FieldControl({ className, ...props }: ComponentProps<typeof SlotDiv>) {
+	return <SlotDiv className={clsx(cls.control, className)} {...props} />;
+}
+
+function FieldLabel({ className, ...props }: ComponentProps<'label'>) {
+	return <label className={clsx(cls.label, className)} {...props} />;
+}
+
+function FieldDescription({ className, ...props }: ComponentProps<'div'>) {
+	return (
+		<div
+			className={clsx('@mode-dense', cls.description, className)}
+			{...props}
+		/>
+	);
+}
+
+export const Field = Object.assign(FieldRoot, {
+	Label: FieldLabel,
+	Description: FieldDescription,
+	Control: FieldControl,
+});

package/src/components/forms/Form.module.css

@@ -2,5 +2,5 @@
 	display: flex;
 	align-items: start;
 	flex-direction: column;
-	gap: var(--m-space-md);
+	gap: var(--m-space-lg);
 }

package/src/components/forms/FormikForm.stories.tsx

@@ -47,19 +47,39 @@ export const Default: Story = {
 					label="Email"
 					placeholder="you@example.com"
 				/>
-				<TextField name="password" type="password" label="Password" />
-				<NumberStepperField name="age" label="Age" min={13} max={100} />
-				<CheckboxField name="tos" label="I agree" />
-				<SwitchField name="newsletter" label="Subscribe to newsletter" />
+				<TextField
+					name="password"
+					type="password"
+					label="Password"
+					description="Make it a good one"
+				/>
+				<NumberStepperField
+					name="age"
+					label="Age"
+					min={13}
+					max={100}
+					description="You can mail your government ID to us, don't worry, we're the good guys"
+				/>
+				<CheckboxField
+					name="tos"
+					label="I agree"
+					description="To what? Not telling."
+				/>
+				<SwitchField
+					name="newsletter"
+					label="Subscribe to newsletter"
+					description="Don't worry, we don't bother you much"
+				/>
 				<ToggleGroupField
 					type="single"
 					name="plan"
 					label="Select your plan"
 					required
+					description="Please do the expensive one!!!"
 				>
 					<ToggleGroupField.Item value="basic">Basic</ToggleGroupField.Item>
 					<ToggleGroupField.Item value="pro">Pro</ToggleGroupField.Item>
-					<ToggleGroupField.Item value="enterprise">
+					<ToggleGroupField.Item value="enterprise" className="@mode-accent">
 						Enterprise
 					</ToggleGroupField.Item>
 				</ToggleGroupField>

package/src/components/forms/NumberStepperField.tsx

@@ -1,12 +1,11 @@
 import { useField } from 'formik';
-import { withClassName } from '../../hooks.js';
+import { ReactNode } from 'react';
 import { useIdOrGenerated } from '../../hooks/useIdOrGenerated.js';
 import {
 	NumberStepper,
 	NumberStepperProps,
 } from '../numberStepper/NumberStepper.js';
-import { FieldLabel } from './FieldLabel.js';
-import cls from './NumberStepperField.module.css';
+import { Field } from './Field.js';
 
 export interface NumberStepperFieldProps
 	extends Omit<NumberStepperProps, 'value' | 'onChange'> {
@@ -15,6 +14,7 @@ export interface NumberStepperFieldProps
 	className?: string;
 	id?: string;
 	onChange?: (value: number) => void;
+	description?: ReactNode;
 }
 
 export function NumberStepperField({
@@ -23,24 +23,31 @@ export function NumberStepperField({
 	className,
 	id: providedId,
 	onChange,
+	description,
 	...rest
 }: NumberStepperFieldProps) {
 	const [_, field, tools] = useField({ name });
 	const id = useIdOrGenerated(providedId);
 	return (
-		<FieldRoot className={className}>
-			{label && <FieldLabel htmlFor={id}>{label}</FieldLabel>}
-			<NumberStepper
-				value={field.value}
-				onChange={(v) => {
-					tools.setValue(v);
-					onChange?.(v);
-				}}
-				id={id}
-				{...rest}
-			/>
-		</FieldRoot>
+		<Field className={className} horizontal>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			<Field.Control>
+				<NumberStepper
+					value={field.value}
+					onChange={(v) => {
+						tools.setValue(v);
+						onChange?.(v);
+					}}
+					id={id}
+					aria-describedby={description ? `${id}-description` : undefined}
+					{...rest}
+				/>
+			</Field.Control>
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
+			)}
+		</Field>
 	);
 }
-
-const FieldRoot = withClassName('div', cls.root);

package/src/components/forms/SwitchField.tsx

@@ -1,8 +1,8 @@
 import { useField } from 'formik';
+import { ReactNode } from 'react';
 import { useIdOrGenerated } from '../../hooks/useIdOrGenerated.js';
-import { Box } from '../box/Box.js';
 import { Switch } from '../switch/Switch.js';
-import { HorizontalFieldLabel } from './FieldLabel.js';
+import { Field } from './Field.js';
 
 export interface SwitchFieldProps {
 	name: string;
@@ -10,6 +10,7 @@ export interface SwitchFieldProps {
 	required?: boolean;
 	className?: string;
 	id?: string;
+	description?: ReactNode;
 }
 
 export function SwitchField({
@@ -18,24 +19,31 @@ export function SwitchField({
 	className,
 	required,
 	id: providedId,
+	description,
 	...rest
 }: SwitchFieldProps) {
 	const [props, _, tools] = useField({ name, required, type: 'checkbox' });
 	const id = useIdOrGenerated(providedId);
 	return (
-		<Box gap="md" className={className}>
-			<Switch
-				{...props}
-				checked={props.checked}
-				onCheckedChange={(v) => {
-					tools.setValue(!!v);
-				}}
-				id={id}
-				{...rest}
-			/>
-			{label && (
-				<HorizontalFieldLabel htmlFor={id}>{label}</HorizontalFieldLabel>
+		<Field horizontal className={className}>
+			<Field.Control>
+				<Switch
+					{...props}
+					checked={props.checked}
+					onCheckedChange={(v) => {
+						tools.setValue(!!v);
+					}}
+					id={id}
+					aria-describedby={description ? `${id}-description` : undefined}
+					{...rest}
+				/>
+			</Field.Control>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
 			)}
-		</Box>
+		</Field>
 	);
 }

package/src/components/forms/TextField.tsx

@@ -3,17 +3,17 @@ import { useField, useFormikContext } from 'formik';
 import {
 	InputHTMLAttributes,
 	KeyboardEvent,
+	ReactNode,
 	Ref,
 	useCallback,
 	useEffect,
 	useRef,
 } from 'react';
-import { withClassName } from '../../hooks.js';
 import { useIdOrGenerated } from '../../hooks/useIdOrGenerated.js';
 import useMergedRef from '../../hooks/useMergedRef.js';
 import { Input, InputProps } from '../input/Input.js';
 import { TextArea, TextAreaProps } from '../textArea/TextArea.js';
-import { FieldLabel } from './FieldLabel.js';
+import { Field } from './Field.js';
 import cls from './TextField.module.css';
 
 export type TextFieldProps = {
@@ -24,6 +24,7 @@ export type TextFieldProps = {
 	inputRef?: Ref<HTMLInputElement>;
 	inputClassName?: string;
 	ref?: Ref<HTMLDivElement>;
+	description?: ReactNode;
 } & Omit<InputProps, 'ref'>;
 
 const emptyRef = (() => {}) as any;
@@ -41,6 +42,7 @@ export const TextField = function TextField({
 	onBlur,
 	id: providedId,
 	inputClassName,
+	description,
 	...rest
 }: TextFieldProps) {
 	const [props] = useField({
@@ -61,17 +63,27 @@ export const TextField = function TextField({
 	}, [autoFocusDelay]);
 
 	return (
-		<FieldRoot className={className} ref={ref}>
-			{label && <FieldLabel htmlFor={id}>{label}</FieldLabel>}
-			<Input
-				{...props}
-				{...rest}
-				id={id}
-				autoFocus={autoFocus}
-				className={clsx(cls.input, inputClassName)}
-				ref={useMergedRef(innerInputRef, inputRef || emptyRef)}
+		<Field className={className} stretch ref={ref}>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			<Field.Control
+				render={
+					<Input
+						{...props}
+						{...rest}
+						id={id}
+						autoFocus={autoFocus}
+						className={clsx(cls.input, inputClassName)}
+						ref={useMergedRef(innerInputRef, inputRef || emptyRef)}
+						aria-describedby={description ? `${id}-description` : undefined}
+					/>
+				}
 			/>
-		</FieldRoot>
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
+			)}
+		</Field>
 	);
 };
 
@@ -85,7 +97,9 @@ export type TextAreaFieldProps = {
 	inputRef?: Ref<HTMLTextAreaElement>;
 	submitOnEnter?: boolean;
 	textAreaClassName?: string;
-} & TextAreaProps;
+	description?: ReactNode;
+	ref?: Ref<HTMLDivElement>;
+} & Omit<TextAreaProps, 'ref'>;
 
 export function TextAreaField({
 	name,
@@ -96,6 +110,8 @@ export function TextAreaField({
 	submitOnEnter,
 	id: providedId,
 	textAreaClassName,
+	description,
+	ref,
 	...rest
 }: TextAreaFieldProps) {
 	const [props] = useField(name);
@@ -113,18 +129,26 @@ export function TextAreaField({
 	const id = useIdOrGenerated(providedId);
 
 	return (
-		<FieldRoot className={className}>
-			{label && <FieldLabel htmlFor={id}>{label}</FieldLabel>}
-			<TextArea
-				ref={inputRef as any}
-				{...props}
-				{...rest}
-				className={clsx('layer-composed:w-full', textAreaClassName)}
-				id={id}
-				onKeyDown={onKeyDownInner}
+		<Field stretch className={className} ref={ref}>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			<Field.Control
+				render={
+					<TextArea
+						ref={inputRef as any}
+						{...props}
+						{...rest}
+						className={clsx(cls.input, textAreaClassName)}
+						id={id}
+						onKeyDown={onKeyDownInner}
+						aria-describedby={description ? `${id}-description` : undefined}
+					/>
+				}
 			/>
-		</FieldRoot>
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
+			)}
+		</Field>
 	);
 }
-
-export const FieldRoot = withClassName('div', cls.root);

package/src/components/forms/ToggleGroupField.tsx

@@ -1,7 +1,7 @@
 import { useField } from 'formik';
+import { ReactNode } from 'react';
 import { ToggleGroup, ToggleGroupProps } from '../toggleGroup/toggleGroup.js';
-import { FieldLabel } from './FieldLabel.js';
-import { FieldRoot } from './TextField.js';
+import { Field } from './Field.js';
 
 export type ToggleGroupFieldProps<Value extends string> =
 	ToggleGroupProps<Value> & {
@@ -11,6 +11,7 @@ export type ToggleGroupFieldProps<Value extends string> =
 		className?: string;
 		id?: string;
 		type?: 'single' | 'multiple';
+		description?: ReactNode;
 	};
 
 function ToggleGroupFieldDefault({
@@ -20,29 +21,38 @@ function ToggleGroupFieldDefault({
 	className,
 	type = 'single',
 	multiple,
+	description,
 	id,
 	...props
 }: ToggleGroupFieldProps<string>) {
 	const [fieldProps, _, tools] = useField({ name, required, ...props });
 
 	return (
-		<FieldRoot>
-			{label && <FieldLabel htmlFor={id}>{label}</FieldLabel>}
-			<ToggleGroup
-				{...fieldProps}
-				onValueChange={(v) => {
-					if (multiple || type === 'multiple') {
-						tools.setValue(v);
-					} else {
-						tools.setValue(v[0]);
-					}
-				}}
-				multiple={multiple || type === 'multiple'}
-				{...props}
-				id={id}
-				className={className}
-			/>
-		</FieldRoot>
+		<Field>
+			{label && <Field.Label htmlFor={id}>{label}</Field.Label>}
+			<Field.Control>
+				<ToggleGroup
+					{...fieldProps}
+					onValueChange={(v) => {
+						if (multiple || type === 'multiple') {
+							tools.setValue(v);
+						} else {
+							tools.setValue(v[0]);
+						}
+					}}
+					multiple={multiple || type === 'multiple'}
+					{...props}
+					id={id}
+					className={className}
+					aria-describedby={description ? `${id}-description` : undefined}
+				/>
+			</Field.Control>
+			{description && (
+				<Field.Description id={`${id}-description`}>
+					{description}
+				</Field.Description>
+			)}
+		</Field>
 	);
 }
 

package/src/components/forms/index.tsx

@@ -1,5 +1,5 @@
 export * from './CheckboxField.js';
-export * from './FieldLabel.js';
+export * from './Field.js';
 export * from './Form.js';
 export * from './FormikForm.js';
 export * from './hooks.js';

package/src/components/switch/Switch.module.css

@@ -15,7 +15,7 @@
 	--mx-shadow-value: inset var(--m-shadow-sm);
 
 	@apply --mx-bg(var(--m-control-bg));
-	@apply --mx-borderColor(var(--m-control-border));
+	@apply --mx-borderColor(var(--m-control-borderColor));
 	border-radius: var(--m-radius-lg);
 
 	&[data-checked] {