@bspk/ui 1.3.3 → 1.3.4

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

@@ -0,0 +1,17 @@
+import { DatePickerField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <DatePickerField label="Example field label" name="example-field-name" onChange={() => {}} value={undefined} />
+);
+
+describe('DatePickerField (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getAllByLabelText } = render(<TestBed />);
+
+        expect(getAllByLabelText('Example field label')[0]).toBeInTheDocument();
+    });
+});

package/src/components/DatePickerField/DatePickerField.tsx

@@ -0,0 +1,30 @@
+import { DatePicker, DatePickerProps } from '-/components/DatePicker';
+import { FormField, FormFieldControlProps } from '-/components/FormField';
+
+export type DatePickerFieldProps = FormFieldControlProps<DatePickerProps>;
+
+/**
+ * A field wrapper for the DatePicker component.
+ *
+ * This component takes properties from the FormField and DatePicker components.
+ *
+ * @name DatePickerField
+ * @phase UXReview
+ *
+ * @generated
+ */
+export function DatePickerField({
+    label,
+    helperText,
+    labelTrailing,
+    errorMessage,
+    ...controlProps
+}: DatePickerFieldProps) {
+    return (
+        <FormField errorMessage={errorMessage} helperText={helperText} label={label} labelTrailing={labelTrailing}>
+            <DatePicker {...controlProps} />
+        </FormField>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/DatePickerField/index.tsx

@@ -0,0 +1 @@
+export * from './DatePickerField';

package/src/components/Drawer/Drawer.tsx

@@ -52,7 +52,7 @@ export type DrawerProps = Pick<DialogProps, 'container' | 'disableFocusTrap' | '
  *     import { Button } from '@bspk/ui/Button';
  *     import { Drawer } from '@bspk/ui/Drawer';
  *
- *     export function Example() {
+ *     function Example() {
  *         const [open, setOpen] = React.useState(false);
  *
  *         return (

package/src/components/Drawer/DrawerExample.tsx

@@ -5,11 +5,11 @@ import { ComponentExampleFn, Preset } from '-/utils/demo';
 export const presets: Preset<DrawerProps>[] = [
     {
         label: 'Left Responsive',
-        propState: { closeButton: true, modal: false, placement: 'left', children: <></> },
+        propState: { closeButton: true, modal: false, placement: 'left', children: null },
     },
     {
         label: 'Right Responsive',
-        propState: { closeButton: true, modal: false, placement: 'right', children: <></> },
+        propState: { closeButton: true, modal: false, placement: 'right', children: null },
     },
 ];
 

package/src/components/EmptyState/EmptyState.tsx

@@ -41,7 +41,7 @@ export type EmptyStateProps = {
  * @example
  *     import { EmptyState } from '@bspk/ui/EmptyState';
  *
- *     export function Example() {
+ *     function Example() {
  *         return (
  *             <EmptyState body="Example body" header="Example header">
  *                 Example EmptyState

package/src/components/Fab/Fab.tsx

@@ -45,7 +45,7 @@ export type FabProps<As extends ElementType = 'button'> = Pick<
  *     import { SvgBolt } from '@bspk/icons/Bolt';
  *     import { Fab } from '@bspk/ui/Fab';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
  *     }
  *

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

@@ -0,0 +1,23 @@
+import { Field, FieldDescription, FieldError, FieldLabel } from './';
+import { Input } from '-/components/Input';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <Field>
+        <FieldLabel>Example label</FieldLabel>
+        <Input name="example-text" onChange={() => {}} value="Input text" />
+        <FieldDescription>This is an example description.</FieldDescription>
+        <FieldError>This is an error message.</FieldError>
+    </Field>
+);
+
+describe('Field (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/Field/Field.tsx

@@ -0,0 +1,110 @@
+import './field.scss';
+import { Children, ElementType, isValidElement, ReactNode, useMemo, useState } from 'react';
+
+import { describedById, errorMessageId, fieldContext, FieldContext, labelledById } from './utils';
+import { ElementProps } from '-/types/common';
+import { randomString } from '-/utils/random';
+
+export type FieldProps<As extends ElementType = ElementType> = {
+    /**
+     * The children of the form field. This should be a control such as DatePicker, Input, InputNumber, InputPhone,
+     * Password, Select, Textarea, or TimePicker.
+     *
+     * @required
+     */
+    children: ReactNode;
+    /**
+     * The element type to render the field as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+    /** The unique id for the field. */
+    id?: string;
+};
+
+const isComponentName = (
+    child: React.ReactElement<unknown, React.JSXElementConstructor<unknown> | string> | React.ReactPortal,
+    name: string,
+) => {
+    const componentType = child.type as { name?: string; displayName?: string };
+    return componentType.displayName === name || componentType.name === name;
+};
+
+/**
+ * Wrapper component for form controls.
+ *
+ * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea, or
+ * TimePicker.
+ *
+ * @example
+ *     import { Input } from '@bspk/ui/Input';
+ *     import { Field, FieldLabel, FieldDescription, FieldError } from '@bspk/ui/Field';
+ *
+ *     function Example() {
+ *         const [state, setState] = React.useState<string | undefined>(undefined);
+ *         const [error, setError] = React.useState<string | undefined>(undefined);
+ *
+ *         return (
+ *             <Field label="Example label">
+ *                 <FieldLabel>Example label</FieldLabel>
+ *                 <Input
+ *                     aria-label="example aria-label"
+ *                     name="example-text"
+ *                     onChange={(next) => {
+ *                         setState(next);
+ *                     }}
+ *                     value={state}
+ *                     {...fieldProps}
+ *                 />
+ *                 <FieldDescription>This is an example description.</FieldDescription>
+ *                 {error && <FieldError>{error}</FieldError>}
+ *             </Field>
+ *         );
+ *     }
+ *
+ * @name Field
+ * @phase Utility
+ */
+export function Field<As extends ElementType = ElementType>({
+    children,
+    as,
+    id: idProp,
+    ...props
+}: ElementProps<FieldProps<As>, As>) {
+    const id = useMemo(() => idProp || `field-${randomString(8)}`, [idProp]);
+
+    const childContext = useMemo(() => {
+        const next: Pick<FieldContext, 'ariaDescribedBy' | 'ariaErrorMessage' | 'ariaLabelledBy'> = {};
+        Children.forEach(children, (child) => {
+            if (!isValidElement(child) || typeof child.type === 'string' || !child.props.children) return;
+
+            if (isComponentName(child, 'FieldError')) next.ariaErrorMessage = errorMessageId(id);
+            else if (isComponentName(child, 'FieldLabel')) next.ariaLabelledBy = labelledById(id);
+            else if (isComponentName(child, 'FieldDescription')) next.ariaDescribedBy = describedById(id);
+        });
+        return next;
+    }, [children, id]);
+
+    const [contextState, setContext] = useState<Pick<FieldContext, 'htmlFor' | 'required'>>({});
+
+    const As = as || 'div';
+
+    return (
+        <fieldContext.Provider
+            value={{
+                ...childContext,
+                ...contextState,
+                id,
+                setContext,
+            }}
+        >
+            <As {...props} data-bspk-utility="field" id={id} role="group">
+                {children}
+            </As>
+        </fieldContext.Provider>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/FieldDescription.tsx

@@ -0,0 +1,15 @@
+import { useFieldContext, describedById } from './utils';
+
+function FieldDescription({ children }: { children?: string }) {
+    const { id } = useFieldContext();
+
+    return children ? (
+        <p data-bspk="field-description" id={describedById(id)}>
+            {children}
+        </p>
+    ) : null;
+}
+
+FieldDescription.displayName = 'FieldDescription';
+
+export { FieldDescription };

package/src/components/Field/FieldError.tsx

@@ -0,0 +1,19 @@
+import { errorMessageId, useFieldContext } from './utils';
+import { InlineAlert } from '-/components/InlineAlert';
+
+export type FieldErrorProps = {
+    /** The error message text. */
+    children?: string;
+};
+
+export function FieldError({ children }: FieldErrorProps) {
+    const { id } = useFieldContext();
+
+    return (
+        children && (
+            <InlineAlert id={errorMessageId(id)} owner="field-error" variant="error">
+                {children}
+            </InlineAlert>
+        )
+    );
+}

package/src/components/Field/FieldExample.tsx

@@ -0,0 +1,21 @@
+import { Field, FieldDescription, FieldError, FieldLabel, FieldProps } from './';
+import { Input } from '-/components/Input';
+import { ComponentExample } from '-/utils/demo';
+import { randomString } from '-/utils/random';
+
+export const FieldExample: ComponentExample<FieldProps & { value?: string }> = {
+    render: ({ props, setState }) => {
+        return (
+            <Field {...props}>
+                <FieldLabel>Example label</FieldLabel>
+                <Input
+                    name={`example-${randomString(6)}`}
+                    onChange={(next: string) => setState({ value: next })}
+                    value={props.value}
+                />
+                <FieldDescription>This is an example description.</FieldDescription>
+                <FieldError>This is an error message.</FieldError>
+            </Field>
+        );
+    },
+};

package/src/components/Field/FieldLabel.tsx

@@ -0,0 +1,38 @@
+import { ElementType } from 'react';
+import { FieldContext, useFieldContext, labelledById } from './utils';
+import { ElementProps } from '-/types/common';
+
+export type FieldLabelProps<As extends ElementType = ElementType> = Pick<FieldContext, 'labelTrailing' | 'required'> & {
+    /** The label text. */
+    children: string;
+    /**
+     * The element type to render as.
+     *
+     * @default label
+     * @type ElementType
+     */
+    as?: As;
+};
+
+export function FieldLabel<As extends ElementType = ElementType>({
+    children,
+    labelTrailing,
+    as,
+    ...props
+}: ElementProps<FieldLabelProps<As>, As>) {
+    const As = as || 'label';
+
+    const { required, id, htmlFor, ...context } = useFieldContext();
+
+    return (
+        <As data-bspk="field-label" htmlFor={As === 'label' ? htmlFor : undefined} id={labelledById(id)} {...props}>
+            <span>{children}</span>
+            {required && <span data-required>{' (Required)'}</span>}
+            {(labelTrailing || context.labelTrailing) && (
+                <span aria-hidden data-trailing>
+                    {labelTrailing || context.labelTrailing}
+                </span>
+            )}
+        </As>
+    );
+}

package/src/components/Field/field.scss

@@ -0,0 +1,43 @@
+[data-bspk-utility='field'] {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-sizing-01);
+    border: none;
+}
+
+[data-bspk='field-label'] {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: var(--spacing-sizing-01);
+
+    span {
+        font: var(--labels-small);
+        color: var(--foreground-neutral-on-surface);
+
+        &[data-required] {
+            font: var(--body-small);
+            color: var(--foreground-neutral-on-surface-variant-01);
+        }
+
+        &[data-trailing] {
+            font: var(--body-small);
+            color: var(--foreground-neutral-on-surface-variant-02);
+            margin-left: auto;
+        }
+    }
+}
+
+[data-bspk='field-description'] {
+    font: var(--body-small);
+    color: var(--foreground-neutral-on-surface-variant-01);
+    margin: 0;
+    padding: 0;
+}
+
+[data-bspk-owner='field-error'] {
+    // Styles for FieldError component when used inside Field
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/index.tsx

@@ -0,0 +1,5 @@
+export * from './Field';
+export * from './FieldLabel';
+export * from './FieldDescription';
+export * from './FieldError';
+export * from './utils';

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,11 @@
-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';
 
-// 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> = {
+    /** Displays an error message and marks the field as invalid. */
     errorMessage?: string;
     /**
      * The label of the field.
@@ -16,37 +13,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) => {
@@ -64,54 +77,19 @@ export type FormFieldProps = CommonProps<'invalid' | 'required'> & {
  * @name FormField
  * @phase Utility
  */
-export function FormField({
-    label,
-    invalid,
-    errorMessage: errorMessageProp,
-    helperText: helperTextProp,
-    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;
+export function FormField({ label, errorMessage, helperText, children, labelTrailing, required, as }: 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}>
+            <FieldLabel as={labelAs} labelTrailing={labelTrailing} required={required}>
+                {label}
+            </FieldLabel>
+            {children}
+            {!errorMessage && helperText && <FieldDescription>{helperText}</FieldDescription>}
+            <FieldError>{errorMessage}</FieldError>
+        </Field>
     );
 }