@bspk/ui 1.3.21 → 1.3.23

package/src/components/DatePickerField/DatePickerField.tsx

@@ -1,7 +1,8 @@
 import { DatePicker, DatePickerProps } from '-/components/DatePicker';
-import { FormField, FormFieldControlProps } from '-/components/FormField';
+import { Field, ComposedFieldProps, propsWithAria } from '-/components/Field';
+import { useId } from '-/hooks/useId';
 
-export type DatePickerFieldProps = FormFieldControlProps<DatePickerProps>;
+export type DatePickerFieldProps = ComposedFieldProps<DatePickerProps>;
 
 /**
  * A field wrapper for the DatePicker component.
@@ -9,7 +10,7 @@ export type DatePickerFieldProps = FormFieldControlProps<DatePickerProps>;
  * This component takes properties from the FormField and DatePicker components.
  *
  * @name DatePickerField
- * @phase Stable
+ * @phase UXReview
  *
  * @generated
  */
@@ -19,18 +20,22 @@ export function DatePickerField({
     labelTrailing,
     errorMessage,
     style,
+    id: idProp,
     ...controlProps
 }: DatePickerFieldProps) {
+    const id = useId(idProp);
     return (
-        <FormField
+        <Field
+            controlId={id}
             errorMessage={errorMessage}
             helperText={helperText}
             label={label}
             labelTrailing={labelTrailing}
+            required={controlProps.required}
             style={style}
         >
-            <DatePicker {...controlProps} />
-        </FormField>
+            <DatePicker {...propsWithAria({ id, controlProps, errorMessage, helperText })} />
+        </Field>
     );
 }
 

package/src/components/Dialog/Dialog.tsx

@@ -62,8 +62,7 @@ export type DialogProps = CommonProps<'id' | 'owner'> &
  * Also known as: Tray, Drawer, Flyout, Sheet
  *
  * @example
- *     import { Dialog } from '@bspk/ui/Dialog';
- *     import { Button } from '@bspk/ui/Button';
+ *     import { Dialog } from '-/components/Dialog';
  *
  *     () => {
  *         const [open, setOpen] = useState(false);
@@ -74,7 +73,7 @@ export type DialogProps = CommonProps<'id' | 'owner'> &
  *                 <Dialog onClose={() => setOpen(false)} open={open}>
  *                     <div style={{ padding: 'var(--spacing-sizing-04)' }}>
  *                         <Flex align="center" justify="space-between">
- *                             <h4>Dialog Title</h4>
+ *                             <h1>Dialog Title</h1>
  *                             <Button
  *                                 icon={<SvgClose />}
  *                                 iconOnly

package/src/components/Fab/Fab.tsx

@@ -44,12 +44,15 @@ export type FabProps<As extends ElementType = ElementType> = Pick<
  * bottom right of a screen.
  *
  * @example
- *     import { SvgBolt } from '@bspk/icons/Bolt';
- *     import { Fab } from '@bspk/ui/Fab';
+ *     import { Fab } from '-/components/Fab';
  *
- *     <div style={{ width: '100%', height: 100 }}>
- *         <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />
- *     </div>;
+ *     () => {
+ *         return (
+ *             <div style={{ width: '100%', height: 100 }}>
+ *                 <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />
+ *             </div>
+ *         );
+ *     };
  *
  * @name Fab
  * @phase Stable

package/src/components/Fab/fab.scss

@@ -110,6 +110,7 @@
     [data-pseudo='focus'] > &,
     &:focus-visible {
         outline: solid 2px var(--stroke-neutral-focus);
+        isolation: isolate;
     }
 
     &[data-round] {

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

@@ -1,14 +1,16 @@
-import { Field, FieldDescription, FieldError, FieldLabel } from './';
+import { Field } 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
+        controlId="example-field-id"
+        errorMessage="This is an error message."
+        helperText="This is an example description."
+        label="Example label"
+    >
+        <Input id="example-field-id" name="example-text" onChange={() => {}} value="Input text" />
     </Field>
 );
 

package/src/components/Field/Field.tsx

@@ -1,64 +1,77 @@
 import './field.scss';
-import { Children, ElementType, isValidElement, ReactNode, useMemo, useState } from 'react';
+import { ReactNode } from 'react';
 
-import { describedById, errorMessageId, fieldContext, FieldContext, labelledById } from './utils';
-import { ElementProps } from '-/types/common';
-import { randomString } from '-/utils/random';
+import { labelledById, errorMessageId, describedById } from './utils';
+import { InlineAlert } from '-/components/InlineAlert';
+import { CommonProps } from '-/types/common';
 
-export type FieldProps<As extends ElementType = ElementType> = {
+/**
+ * Props for Composed Field components.
+ *
+ * These are props that combine FieldProps with the props of a specific control component.
+ */
+export type ComposedFieldProps<P extends Record<string, unknown>> = Omit<FieldProps, 'children' | 'controlId'> &
+    Omit<P, keyof FieldProps>;
+
+export type FieldProps = CommonProps<'style'> & {
+    /** Displays an error message and marks the field as invalid. */
+    errorMessage?: string;
     /**
-     * The children of the form field. This should be a control such as DatePicker, Input, InputNumber, InputPhone,
-     * Password, Select, Textarea, or TimePicker.
+     * The label of the field.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * 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?: string;
+    /** Marks the field as required. */
+    required?: boolean;
+    /**
+     * The children of the 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.
+     * The id attribute of the form control rendered in children (e.g., Input, Select, Textarea). Used to associate the
+     * label (htmlFor) with the control for accessibility. Must exactly match the control's id.
      *
-     * @default div
-     * @type ElementType
+     * @required
      */
-    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;
+    controlId: string;
 };
 
 /**
  * Wrapper component for form controls.
  *
- * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea, or
- * TimePicker.
+ * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea,
+ * RadioGroup, CheckboxGroup, or TimePicker.
  *
  * @example
  *     import { Input } from '@bspk/ui/Input';
- *     import { Field, FieldLabel, FieldDescription, FieldError } from '@bspk/ui/Field';
+ *     import { Field } from '@bspk/ui/Field';
  *
  *     () => {
  *         const [state, setState] = useState<string | undefined>(undefined);
- *         const [error, setError] = useState<string | undefined>(undefined);
  *
  *         return (
- *             <Field label="Example label">
- *                 <FieldLabel>Example label</FieldLabel>
+ *             <Field controlId="example-control-id" helperText="This is an example description." label="Example label">
  *                 <Input
  *                     aria-label="example aria-label"
+ *                     id="example-control-id"
  *                     name="example-text"
  *                     onChange={(next) => {
  *                         setState(next);
  *                     }}
  *                     value={state}
  *                 />
- *                 <FieldDescription>This is an example description.</FieldDescription>
- *                 {error && <FieldError>{error}</FieldError>}
  *             </Field>
  *         );
  *     };
@@ -66,43 +79,38 @@ const isComponentName = (
  * @name Field
  * @phase Utility
  */
-export function Field<As extends ElementType = ElementType>({
+export function Field({
     children,
-    as,
-    id: idProp,
+    label,
+    helperText,
+    labelTrailing,
+    errorMessage,
+    required,
+    controlId: id,
     ...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';
-
+}: FieldProps) {
     return (
-        <fieldContext.Provider
-            value={{
-                ...childContext,
-                ...contextState,
-                id,
-                setContext,
-            }}
-        >
-            <As {...props} data-bspk-utility="field" id={id} role="group">
-                {children}
-            </As>
-        </fieldContext.Provider>
+        <div {...props} data-bspk-utility="field" role="group">
+            <label data-field-label htmlFor={id} id={labelledById(id)}>
+                <span>{label}</span>
+                {required && <span data-required>{' (Required)'}</span>}
+                {labelTrailing && (
+                    <span aria-hidden data-trailing>
+                        {labelTrailing}
+                    </span>
+                )}
+            </label>
+            {children}
+            {errorMessage ? (
+                <InlineAlert id={errorMessageId(id)} label={errorMessage} owner="field-error" variant="error" />
+            ) : (
+                helperText && (
+                    <p data-field-description id={describedById(id)}>
+                        {helperText}
+                    </p>
+                )
+            )}
+        </div>
     );
 }
 

package/src/components/Field/FieldExample.tsx

@@ -1,4 +1,5 @@
-import { Field, FieldDescription, FieldError, FieldLabel, FieldProps } from './';
+import { useState } from 'react';
+import { Field, FieldProps } from './';
 import { Input } from '-/components/Input';
 import { ComponentExample } from '-/utils/demo';
 import { randomString } from '-/utils/random';
@@ -6,16 +7,37 @@ import { randomString } from '-/utils/random';
 export const FieldExample: ComponentExample<FieldProps & { value?: string }> = {
     render: ({ props, setState }) => {
         return (
-            <Field {...props}>
-                <FieldLabel>Example label</FieldLabel>
+            <Field
+                {...props}
+                errorMessage="This is an error message."
+                helperText="This is an example description."
+                label="Example label"
+            >
                 <Input
+                    id={props.controlId}
                     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>
         );
     },
 };
+
+export const Usage = () => {
+    const [state, setState] = useState<string | undefined>(undefined);
+
+    return (
+        <Field controlId="example-control-id" helperText="This is an example description." label="Example label">
+            <Input
+                aria-label="example aria-label"
+                id="example-control-id"
+                name="example-text"
+                onChange={(next) => {
+                    setState(next);
+                }}
+                value={state}
+            />
+        </Field>
+    );
+};

package/src/components/Field/Fieldset.tsx

@@ -0,0 +1,82 @@
+import './field.scss';
+
+import { FieldProps } from './Field';
+import { labelledById, errorMessageId, describedById } from './utils';
+import { InlineAlert } from '-/components/InlineAlert';
+
+/**
+ * Wrapper component for form controls.
+ *
+ * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea,
+ * RadioGroup, CheckboxGroup, or TimePicker.
+ *
+ * @example
+ *     import { Input } from '@bspk/ui/Input';
+ *     import { Fieldset } from '@bspk/ui/Field';
+ *
+ *     () => {
+ *         const [state, setState] = useState<string | undefined>(undefined);
+ *         const [error, setError] = useState<string | undefined>(undefined);
+ *
+ *         return (
+ *             <Fieldset
+ *                 label="Example label"
+ *                 helperText="This is an example description."
+ *                 errorMessage={error}
+ *                 required
+ *             >
+ *                 <Input
+ *                     aria-label="example aria-label"
+ *                     name="example-text"
+ *                     onChange={(next) => {
+ *                         setState(next);
+ *                     }}
+ *                     value={state}
+ *                 />
+ *             </Fieldset>
+ *         );
+ *     };
+ *
+ * @name Fieldset
+ * @phase Utility
+ */
+export function Fieldset({
+    children,
+    label,
+    helperText,
+    labelTrailing,
+    errorMessage,
+    required,
+    controlId: id,
+    ...props
+}: FieldProps) {
+    return (
+        <div {...props} data-bspk-utility="field">
+            <fieldset role="group">
+                <legend>
+                    <span data-field-label id={labelledById(id)}>
+                        <span>{label}</span>
+                        {required && <span data-required>{' (Required)'}</span>}
+                        {labelTrailing && (
+                            <span aria-hidden data-trailing>
+                                {labelTrailing}
+                            </span>
+                        )}
+                    </span>
+                </legend>
+                {children}
+                {errorMessage ? (
+                    <InlineAlert id={errorMessageId(id)} label={errorMessage} owner="field-error" variant="error" />
+                ) : (
+                    helperText && (
+                        <p data-field-description id={describedById(id)}>
+                            {helperText}
+                        </p>
+                    )
+                )}
+            </fieldset>
+        </div>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/field.scss

@@ -6,40 +6,41 @@
     border: none;
     max-width: 100%;
     min-inline-size: unset;
-}
 
-[data-bspk='field-label'] {
-    display: flex;
-    flex-direction: row;
-    align-items: center;
-    gap: var(--spacing-sizing-01);
+    [data-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);
+        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-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-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-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
+    fieldset,
+    legend {
+        display: contents;
+    }
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/index.tsx

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

package/src/components/Field/utils.ts

@@ -1,84 +1,22 @@
-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);
-
-/**
- * Retrieves the current Field context.
- *
- * Will return a default context if used outside of a Field component.
- */
-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,
+export function propsWithAria<T extends Record<string, unknown>>({
+    errorMessage,
+    helperText,
+    controlProps,
+    id,
 }: {
-    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]);
-
+    errorMessage?: string;
+    helperText?: string;
+    controlProps: T;
+    id: string;
+}) {
     return {
-        ...(context || {}),
-        invalid,
-        id: controlId,
+        ...controlProps,
+        id,
+        'aria-errormessage': errorMessage ? errorMessageId(id) : undefined,
+        'aria-describedby': helperText ? describedById(id) : undefined,
+        'aria-invalid': errorMessage ? true : undefined,
     };
 }

package/src/components/FileUpload/FileUpload.tsx

@@ -205,7 +205,7 @@ export function FileUpload({
                 />
                 <Button label="Browse" onClick={handleBrowseClick} />
                 {files.length === 1 && files[0].status === 'error' && (
-                    <InlineAlert variant="error">{files[0].errorMessage || DEFAULT_ERROR_MESSAGE}</InlineAlert>
+                    <InlineAlert label={files[0].errorMessage || DEFAULT_ERROR_MESSAGE} variant="error" />
                 )}
             </div>
             <div data-bspk-owner="file-upload" data-file-entries>

package/src/components/FileUploadItem/FileUploadItem.tsx

@@ -72,7 +72,7 @@ export function FileUploadItem({
             </div>
             <div data-status>
                 {status === 'error' ? (
-                    <InlineAlert variant="error">{errorMessage}</InlineAlert>
+                    <InlineAlert label={errorMessage} variant="error" />
                 ) : (
                     <ProgressBar
                         align="left"

package/src/components/Flex/Flex.tsx

@@ -44,13 +44,17 @@ export type FlexProps<As extends ElementType = ElementType> = {
  * Utility component used within other components for layout purposes.
  *
  * @example
- *     import { Flex } from '@bspk/ui/Flex';
+ *     import { Flex } from '-/components/Flex';
  *
- *     <Flex gap="24" justify="center" style={{ width: '100%' }}>
- *         <div>Alpha</div>
- *         <div>Beta</div>
- *         <div>Gamma</div>
- *     </Flex>;
+ *     () => {
+ *         return (
+ *             <Flex gap="24" justify="center" style={{ width: '100%' }}>
+ *                 <div>Alpha</div>
+ *                 <div>Beta</div>
+ *                 <div>Gamma</div>
+ *             </Flex>
+ *         );
+ *     };
  *
  * @name Flex
  * @phase Utility

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

@@ -2,7 +2,7 @@ import { InlineAlert } from './InlineAlert';
 import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
-const TestBed = () => <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
+const TestBed = () => <InlineAlert label="Example informational inline alert" variant="informational" />;
 
 describe('InlineAlert (RTL)', () => {
     it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));