@bspk/ui 1.3.3 → 1.3.5

package/src/components/Field/utils.ts

@@ -0,0 +1,79 @@
+import { createContext, useContext, useEffect, useMemo } from 'react';
+import { useId } from '-/hooks/useId';
+import { CommonProps } from '-/types/common';
+
+export const errorMessageId = (id: string) => `${id}-field-error`;
+export const labelledById = (id: string) => `${id}-label`;
+export const describedById = (id: string) => `${id}-description`;
+
+/** The props that are provided via context to all Field subcomponents. */
+export type FieldContextProps = CommonProps<'required'> & {
+    /** The aria-describedby attribute value that should be applied to the field input element. */
+    ariaDescribedBy?: string;
+    /** The aria-errormessage attribute value that should be applied to the field input element. */
+    ariaErrorMessage?: string;
+    /** Text that appears after the label, but before the input (e.g. "optional"). */
+    labelTrailing?: string;
+    /** The aria-labelledby attribute value that should be applied to the field input element. */
+    ariaLabelledBy?: string;
+    /** The htmlFor attribute value that should be applied to the field label element. */
+    htmlFor?: string;
+    /** The id of the field. */
+    id: string;
+};
+
+export type FieldContext = FieldContextProps & {
+    setContext: (next: Pick<FieldContextProps, 'htmlFor' | 'required'>) => void;
+};
+
+export const fieldContext = createContext<FieldContext | null>(null);
+
+export function useFieldContext(): FieldContext {
+    return (
+        useContext(fieldContext) || {
+            id: undefined as unknown as string,
+            setContext: () => {},
+        }
+    );
+}
+
+/**
+ * Initializes field-related attributes and state for a form control component.
+ *
+ * Creates id if not provided, manages invalid state, and syncs with Field context.
+ */
+export function useFieldInit({
+    idProp,
+    required,
+    disabled,
+    readOnly,
+    invalidProp,
+}: {
+    idProp: string | undefined;
+    required: boolean | undefined;
+    disabled: boolean | undefined;
+    readOnly: boolean | undefined;
+    invalidProp: boolean | undefined;
+}): Pick<FieldContext, 'ariaDescribedBy' | 'ariaErrorMessage'> & { invalid: boolean; id: string } {
+    const context = useContext(fieldContext);
+    const controlId = useId(idProp || context?.htmlFor);
+
+    const invalid = useMemo(
+        () => !disabled && !readOnly && (invalidProp || !!context?.ariaErrorMessage),
+        [disabled, readOnly, invalidProp, context?.ariaErrorMessage],
+    );
+
+    useEffect(() => {
+        if (!context) return;
+
+        if (controlId !== context?.htmlFor || !!required !== !!context?.required) {
+            context.setContext({ htmlFor: controlId, required: required });
+        }
+    }, [context, controlId, required]);
+
+    return {
+        ...(context || {}),
+        invalid,
+        id: controlId,
+    };
+}

package/src/components/FormField/FormField.rtl.test.tsx

@@ -1,30 +1,20 @@
-import { FormField } from './FormField';
-import { TextInput } from '-/components/TextInput';
+import { FormFieldExampleRender, presets } from './FormFieldExample';
 import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
-const TestBed = () => (
-    <FormField controlId="Example controlId" label="Example label">
-        {(fieldProps) => {
-            return (
-                <TextInput
-                    aria-label="example aria-label"
-                    name="example-text"
-                    onChange={() => {}}
-                    value="Input text"
-                    {...fieldProps}
-                />
-            );
-        }}
-    </FormField>
-);
-
 describe('FormField (RTL)', () => {
-    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+    presets.forEach((preset) => {
+        it(
+            `has no basic a11y issues - ${preset.label}`,
+            hasNoBasicA11yIssues(<FormFieldExampleRender {...preset.propState} />),
+        );
+    });
 
     it('renders', () => {
-        const { getByLabelText } = render(<TestBed />);
+        const { getByText } = render(<FormFieldExampleRender {...presets[0].propState} />);
 
-        expect(getByLabelText('example aria-label')).toBeInTheDocument();
+        expect(getByText('InputPhone')).toBeInTheDocument();
     });
 });
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FormField/FormField.tsx

@@ -1,14 +1,12 @@
-import './form-field.scss';
-import { InlineAlert } from '-/components/InlineAlert';
-import { Txt } from '-/components/Txt';
-import { CommonProps, ElementProps, FormFieldControlProps } from '-/types/common';
+import { ElementType, ReactNode } from 'react';
+import { Field, FieldLabel, FieldDescription, FieldError } from '-/components/Field';
+import { CommonProps } from '-/types/common';
 
-// omits are usually a code smell, but in this case, we need to ensure we get all the props from child components
-export type FormFieldWrapProps<T extends Record<string, unknown>> = Omit<FormFieldProps, keyof T | 'children'> &
-    Omit<T, 'aria-describedby' | 'aria-errormessage'>;
+export type FormFieldControlProps<P extends Record<string, unknown>> = Omit<FormFieldProps, 'children'> &
+    Omit<P, keyof FormFieldProps>;
 
-export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
-    /** The error message to display when the field is invalid. */
+export type FormFieldProps<As extends ElementType = ElementType> = CommonProps<'style'> & {
+    /** Displays an error message and marks the field as invalid. */
     errorMessage?: string;
     /**
      * The label of the field.
@@ -16,37 +14,53 @@ export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
      * @required
      */
     label: string;
-    /** The id of the control. */
-    controlId: string;
     /**
-     * The children of the form field. This should be a control such as TextInput, Select, DateInput, or TimeInput.
+     * The children of the form field. This should at least contain a FieldLabel component and a control such as
+     * DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea, or TimePicker.
+     *
+     * Other components such as FieldDescription and FieldError can also be included.
      *
-     * @type (childProps: FormFieldControlProps) => JSX.Element
      * @required
      */
-    children: (childProps: FormFieldControlProps) => JSX.Element;
-    /** The helperText of the field. */
+    children: ReactNode;
+    /**
+     * This text provides additional context or instructions for the field.
+     *
+     * If an errorMessage is present, the helperText will not be displayed.
+     */
     helperText?: string;
     /** The trailing element of the label. */
-    labelTrailing?: React.ReactNode;
+    labelTrailing?: string;
+    /** Marks the field as required. */
+    required?: boolean;
+    /**
+     * The element type to render as.
+     *
+     * With grouped fields, this is typically set to "fieldset".
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
 };
 
 /**
  * Wrapper component for form controls.
  *
- * Children should be one of the following: TextInput, Select, DateInput or TimeInput.
+ * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea, or
+ * TimePicker.
  *
  * @example
- *     import { TextInput } from '@bspk/ui/TextInput';
+ *     import { Input } from '@bspk/ui/Input';
  *     import { FormField } from '@bspk/ui/FormField';
  *
- *     export function Example() {
+ *     function Example() {
  *         const [state, setState] = React.useState<string | undefined>(undefined);
  *         return (
  *             <FormField controlId="Example controlId" label="Example label">
  *                 {(fieldProps) => {
  *                     return (
- *                         <TextInput
+ *                         <Input
  *                             aria-label="example aria-label"
  *                             name="example-text"
  *                             onChange={(next) => {
@@ -66,52 +80,26 @@ export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
  */
 export function FormField({
     label,
-    invalid,
-    errorMessage: errorMessageProp,
-    helperText: helperTextProp,
+    errorMessage,
+    helperText,
     children,
     labelTrailing,
-    controlId,
     required,
-    ...props
-}: ElementProps<FormFieldProps, 'div'>) {
-    const errorMessage = invalid && errorMessageProp ? errorMessageProp : undefined;
-    const errorMessageId = errorMessage ? `${controlId}-error-message` : undefined;
-    const helperText = !errorMessage && helperTextProp ? helperTextProp : undefined;
-    const helperTextId = !errorMessage && helperText ? `${controlId}-helper-text` : undefined;
-
-    if (typeof children !== 'function') return null;
+    as,
+    style,
+}: FormFieldProps) {
+    const fieldAs = as || 'div';
 
+    const labelAs = fieldAs === 'fieldset' ? 'legend' : undefined;
     return (
-        <div {...props} data-bspk-utility="form-field" data-invalid={invalid || undefined}>
-            <header>
-                <label htmlFor={controlId}>
-                    <Txt as="span" variant="labels-small">
-                        {label}
-                    </Txt>
-                    {required && (
-                        <Txt as="span" variant="body-small">
-                            {' (Required)'}
-                        </Txt>
-                    )}
-                </label>
-                {labelTrailing}
-            </header>
-            {children({
-                'aria-describedby': helperTextId,
-                'aria-errormessage': errorMessageId,
-            })}
-            {errorMessage && (
-                <InlineAlert id={errorMessageId} variant="error">
-                    {errorMessage}
-                </InlineAlert>
-            )}
-            {helperText && (
-                <Txt id={helperTextId} variant="body-small">
-                    {helperText}
-                </Txt>
-            )}
-        </div>
+        <Field as={fieldAs} style={style}>
+            <FieldLabel as={labelAs} labelTrailing={labelTrailing} required={required}>
+                {label}
+            </FieldLabel>
+            {children}
+            {!errorMessage && helperText && <FieldDescription>{helperText}</FieldDescription>}
+            <FieldError>{errorMessage}</FieldError>
+        </Field>
     );
 }
 

package/src/components/FormField/FormFieldExample.tsx

@@ -1,41 +1,278 @@
-import { FormFieldWrapProps, FormField } from './FormField';
-import { TextInput, TextInputProps } from '-/components/TextInput';
-import { ComponentExample } from '-/utils/demo';
-
-export const FormFieldExample: ComponentExample<FormFieldWrapProps<TextInputProps>> = {
-    render: ({ props, setState }) => {
-        const {
-            invalid,
-            errorMessage,
+import { useState } from 'react';
+import { FormField, FormFieldProps } from '.';
+import { Button } from '-/components/Button';
+import { CheckboxGroup } from '-/components/CheckboxGroup';
+import { DatePicker } from '-/components/DatePicker';
+import { Input } from '-/components/Input';
+import { InputNumber } from '-/components/InputNumber';
+import { InputPhone } from '-/components/InputPhone';
+import { Password } from '-/components/Password';
+import { RadioGroup } from '-/components/RadioGroup';
+import { Select } from '-/components/Select';
+import { SwitchOption } from '-/components/SwitchOption';
+import { Textarea } from '-/components/Textarea';
+import { TimePicker } from '-/components/TimePicker';
+import { FieldControlProps } from '-/types/common';
+import { ComponentExample, Preset, Syntax } from '-/utils/demo';
+
+type ExampleProps = Partial<FieldControlProps & FormFieldProps>;
+
+export const presets: Preset<Partial<ExampleProps>>[] = [
+    {
+        label: 'Control Disabled',
+        propState: { disabled: true },
+    },
+];
+
+export const FormFieldExample: ComponentExample<ExampleProps> = {
+    containerStyle: { width: '100%' },
+    defaultState: {},
+    disableProps: [],
+    presets: presets as Preset<ExampleProps>[],
+    render: ({ props, Component }) => (
+        <Component {...props}>
+            <Input name="input" onChange={() => {}} placeholder="Example input" value="" />
+        </Component>
+    ),
+    sections: [
+        {
+            title: 'Form Field Example',
+            content: ({ Syntax: syntax, props }) => (
+                <>
+                    <p>
+                        This example demonstrates the FormField component wrapping various form controls including
+                        CheckboxGroup, RadioGroup, DatePicker, Input, InputNumber, InputPhone, Password, Select,
+                        Textarea, and TimePicker. It showcases how to manage state and handle form submissions.
+                    </p>
+                    <p>
+                        All the controls have a HTML input element inside of them so they will work with form
+                        submissions natively. You can see the raw submitted{' '}
+                        <a href="https://developer.mozilla.org/en-US/docs/Web/API/FormData">FormData</a> at the bottom
+                        after clicking the Submit button.
+                    </p>
+                    <FormFieldExampleRender {...props} syntax={syntax} />
+                </>
+            ),
+            location: 'afterDemo',
+        },
+    ],
+    variants: false,
+};
+
+export function FormFieldExampleRender({ ...props }: ExampleProps & { syntax?: Syntax }) {
+    const [value, setValueState] = useState<{ [key: string]: unknown }>({});
+
+    const setValue = (next: { [key: string]: unknown }) => {
+        setValueState((prev) => ({ ...prev, ...next }));
+    };
+
+    const [formValues, setFormValues] = useState<{ [key: string]: unknown }>({});
+
+    const [disabled, setDisabled] = useState(!!props.disabled);
+    const [required, setRequired] = useState(!!props.required);
+
+    const [fieldProps, setFieldProps] = useState<{
+        errorMessage: boolean;
+        description: boolean;
+    }>({
+        errorMessage: false,
+        description: false,
+    });
+
+    const internalProps = (label: string) => {
+        return {
+            errorMessage: fieldProps.errorMessage ? `This is an error message for the ${label}.` : undefined,
+            helperText: fieldProps.description ? `This is a description for the ${label}.` : undefined,
             label,
-            controlId = 'example-control-id',
-            helperText,
-            labelTrailing,
-            ...inputProps
-        } = props;
-
-        return (
-            <FormField
-                controlId={controlId}
-                errorMessage={errorMessage}
-                helperText={helperText}
-                invalid={invalid}
-                label={label}
-                labelTrailing={labelTrailing}
+        };
+    };
+
+    return (
+        <>
+            <div
+                style={{
+                    display: 'flex',
+                    flexDirection: 'row',
+                }}
             >
-                {(fieldProps) => {
-                    return (
-                        <TextInput
-                            {...inputProps}
-                            {...fieldProps}
-                            aria-label={label}
-                            invalid={invalid}
-                            onChange={(next: string) => setState({ value: next })}
-                            value={props.value}
-                        />
-                    );
+                <SwitchOption
+                    checked={fieldProps.errorMessage}
+                    label="Has Error"
+                    name="hasError"
+                    onChange={(checked) => setFieldProps((prev) => ({ ...prev, errorMessage: checked }))}
+                    value="hasError"
+                />
+                <SwitchOption
+                    checked={disabled}
+                    label="Disabled"
+                    name="disabled"
+                    onChange={setDisabled}
+                    value="disabled"
+                />
+                <SwitchOption
+                    checked={required}
+                    label="Required"
+                    name="required"
+                    onChange={setRequired}
+                    value="required"
+                />
+                <SwitchOption
+                    checked={!!fieldProps.description}
+                    label="With Description"
+                    name="description"
+                    onChange={(checked) => setFieldProps((prev) => ({ ...prev, description: checked }))}
+                    value="description"
+                />
+            </div>
+            <form
+                onReset={() => {
+                    setValueState({});
+                    setFormValues({});
                 }}
-            </FormField>
-        );
-    },
-};
+                onSubmit={(e) => {
+                    e.preventDefault();
+                    const formData = new FormData(e.currentTarget);
+                    const next: { [key: string]: unknown[] | unknown } = {};
+                    // handle multiple form entries with the same name
+                    formData.forEach((fieldValue, key) => {
+                        if (next[key]) {
+                            if (Array.isArray(next[key])) {
+                                (next[key] as unknown[]).push(fieldValue);
+                            } else {
+                                next[key] = [next[key], fieldValue];
+                            }
+                        } else {
+                            next[key] = fieldValue;
+                        }
+                    });
+                    setFormValues(next);
+                }}
+                style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-sizing-04)', width: '400px' }}
+            >
+                <FormField {...props} as="fieldset" {...internalProps('CheckboxGroup')}>
+                    <CheckboxGroup
+                        disabled={disabled}
+                        name="checkbox-group"
+                        onChange={(next) => setValue({ 'checkbox-group': next })}
+                        options={[
+                            { label: 'Option 1', value: 'option1' },
+                            { label: 'Option 2', value: 'option2' },
+                            { label: 'Option 3', value: 'option3' },
+                        ]}
+                        required={required}
+                        value={value['checkbox-group'] as string[]}
+                    />
+                </FormField>
+                <FormField {...props} as="fieldset" {...internalProps('RadioGroup')}>
+                    <RadioGroup
+                        disabled={disabled}
+                        name="radio-group"
+                        onChange={(next) => setValue({ 'radio-group': next })}
+                        options={[
+                            { label: 'Option 1', value: 'option1' },
+                            { label: 'Option 2', value: 'option2' },
+                            { label: 'Option 3', value: 'option3' },
+                        ]}
+                        required={required}
+                        value={value['radio-group'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('DatePicker')}>
+                    <DatePicker
+                        disabled={disabled}
+                        name="date-picker"
+                        onChange={(next) => setValue({ 'date-picker': next })}
+                        placeholder="Example input"
+                        required={required}
+                        value={value['date-picker'] as Date}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('Input')}>
+                    <Input
+                        disabled={disabled}
+                        name="input"
+                        onChange={(next) => setValue({ input: next })}
+                        placeholder="Example input"
+                        required={required}
+                        value={value['input'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('InputNumber')}>
+                    <InputNumber
+                        disabled={disabled}
+                        name="input-number"
+                        onChange={(next) => setValue({ 'input-number': next })}
+                        required={required}
+                        value={value['input-number'] as number}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('InputPhone')}>
+                    <InputPhone
+                        disabled={disabled}
+                        name="input-phone"
+                        onChange={(next) => setValue({ 'input-phone': next })}
+                        required={required}
+                        value={value['input-phone'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('Password')}>
+                    <Password
+                        disabled={disabled}
+                        name="password"
+                        onChange={(next) => setValue({ password: next })}
+                        required={required}
+                        value={value['password'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('Select')}>
+                    <Select
+                        disabled={disabled}
+                        name="select"
+                        onChange={(next) => setValue({ select: next })}
+                        options={[
+                            { label: 'Option 1', value: 'option1' },
+                            { label: 'Option 2', value: 'option2' },
+                            { label: 'Option 3', value: 'option3' },
+                        ]}
+                        placeholder="Example input"
+                        required={required}
+                        value={value['select'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('Textarea')}>
+                    <Textarea
+                        disabled={disabled}
+                        name="textarea"
+                        onChange={(next) => setValue({ textarea: next })}
+                        placeholder="Example input"
+                        required={required}
+                        value={value['textarea'] as string}
+                    />
+                </FormField>
+                <FormField {...props} {...internalProps('TimePicker')}>
+                    <TimePicker
+                        disabled={disabled}
+                        name="time-picker"
+                        onChange={(next) => setValue({ 'time-picker': next })}
+                        required={required}
+                        value={value['time-picker'] as string}
+                    />
+                </FormField>
+                <div style={{ display: 'flex', flexDirection: 'row', gap: 'var(--spacing-sizing-02)' }}>
+                    <Button label="Reset" type="reset" variant="secondary" />
+                    <Button label="Submit" type="submit" variant="primary" />
+                </div>
+                <code
+                    style={{
+                        background: 'var(--surface-neutral-t3-low)',
+                        // fontWeight: 'bold',
+                        padding: 'var(--spacing-sizing-02)',
+                        borderRadius: 'var(--radius-sm)',
+                    }}
+                >
+                    <pre>{`// Raw FormData\n\n${JSON.stringify(formValues, null, 2)}`}</pre>
+                </code>
+            </form>
+        </>
+    );
+}

package/src/components/Img/Img.tsx

@@ -21,7 +21,7 @@ export type ImgProps = {
  * @example
  *     import { Img } from '@bspk/ui/Img';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Img alt="Example alt" src="Example src" />;
  *     }
  *

package/src/components/InlineAlert/InlineAlert.tsx

@@ -5,9 +5,9 @@ import { SvgInfoFill } from '@bspk/icons/InfoFill';
 import { ReactNode } from 'react';
 import { SvgWarningTwoTone } from './SvgWarningTwoTone';
 import { Txt } from '-/components/Txt';
-import { AlertVariant } from '-/types/common';
+import { AlertVariant, CommonProps } from '-/types/common';
 
-export type InlineAlertProps = {
+export type InlineAlertProps = CommonProps<'owner'> & {
     /**
      * The content of the inline alert.
      *
@@ -32,16 +32,16 @@ export type InlineAlertProps = {
  * @example
  *     import { InlineAlert } from '@bspk/ui/InlineAlert';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
  *     }
  *
  * @name InlineAlert
  * @phase UXReview
  */
-export function InlineAlert({ children, variant = 'informational', id }: InlineAlertProps) {
+export function InlineAlert({ children, variant = 'informational', id, owner }: InlineAlertProps) {
     return (
-        <div data-bspk="inline-alert" data-variant={variant} id={id} role="alert">
+        <div data-bspk="inline-alert" data-bspk-owner={owner || undefined} data-variant={variant} id={id} role="alert">
             {VARIANT_ICON[variant]}
             <Txt variant="body-small">{children}</Txt>
         </div>

package/src/components/{MenuButton/MenuButton.rtl.test.tsx → Input/Input.rtl.test.tsx}

@@ -1,10 +1,10 @@
-import { MenuButton } from './MenuButton';
+import { Input } from './';
 import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
-const TestBed = () => <MenuButton aria-label="Example label" />;
+const TestBed = () => <Input aria-label="Example label" name="input-name" onChange={() => {}} value="text value" />;
 
-describe('MenuButton (RTL)', () => {
+describe('Input (RTL)', () => {
     it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
 
     it('renders', () => {