@bspk/ui 1.3.20 → 1.3.22

package/src/components/DatePicker/DatePicker.tsx

@@ -4,8 +4,7 @@ import { format, startOfToday } from 'date-fns';
 import { useMemo, useState } from 'react';
 import { Button } from '-/components/Button';
 import { Calendar, parseDate } from '-/components/Calendar';
-import { useFieldInit } from '-/components/Field';
-import { InputElement, InputProps } from '-/components/Input';
+import { Input, InputProps } from '-/components/Input';
 import { useFloating } from '-/hooks/useFloating';
 import { useOutsideClick } from '-/hooks/useOutsideClick';
 import { FieldControlProps } from '-/types/common';
@@ -49,19 +48,15 @@ export type DatePickerProps = Omit<FieldControlProps, 'aria-label' | 'onChange'
  * For a more complete example with field usage, see the DatePickerField component.
  *
  * @example
- *     import { DatePicker } from '@bspk/ui/DatePicker';
- *     import { Field, FieldLabel } from '@bspk/ui/Field';
- *     import { useState } from 'react';
+ *     import { DatePicker } from '-/components/DatePicker';
  *
  *     () => {
  *         const [fieldDate, setFieldDate] = useState<string>();
  *
  *         return (
  *             <div style={{ width: 320 }}>
- *                 <Field>
- *                     <FieldLabel>Date</FieldLabel>
- *                     <DatePicker name="date1" onChange={setFieldDate} required value={fieldDate} />
- *                     <FieldDescription>The date picker allows you to select a date.</FieldDescription>
+ *                 <Field controlId="date1" helperText="The date picker allows you to select a date." label="Date">
+ *                     <DatePicker id="date1" name="date1" onChange={setFieldDate} required value={fieldDate} />
  *                 </Field>
  *             </div>
  *         );
@@ -78,20 +73,14 @@ export function DatePicker({
     closeCalendarOnChange = true,
     name,
     placeholder,
-    invalid: invalidProp,
+    invalid,
     required = false,
     size,
-    id: idProp,
+    id,
     'aria-label': ariaLabel = 'Enter or choose date',
+    'aria-describedby': ariaDescribedBy,
+    'aria-errormessage': ariaErrorMessage,
 }: DatePickerProps) {
-    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
-        idProp,
-        required,
-        disabled,
-        readOnly,
-        invalidProp,
-    });
-
     const [calendarVisible, setCalendarVisible] = useState(false);
 
     const { elements, floatingStyles } = useFloating({
@@ -118,7 +107,7 @@ export function DatePicker({
                 elements.setReference(node);
             }}
         >
-            <InputElement
+            <Input
                 aria-describedby={ariaDescribedBy || undefined}
                 aria-errormessage={ariaErrorMessage || undefined}
                 aria-label={ariaLabel}

package/src/components/DatePicker/DatePickerExample.tsx

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 import { DatePicker, DatePickerProps } from '.';
-import { Field, FieldLabel, FieldDescription } from '-/components/Field';
+import { Field } from '-/components/Field';
 import { ComponentExample } from '-/utils/demo';
 
 export const DatePickerExample: ComponentExample<DatePickerProps> = {
@@ -19,10 +19,8 @@ export const Usage = () => {
 
     return (
         <div style={{ width: 320 }}>
-            <Field>
-                <FieldLabel>Date</FieldLabel>
-                <DatePicker name="date1" onChange={setFieldDate} required value={fieldDate} />
-                <FieldDescription>The date picker allows you to select a date.</FieldDescription>
+            <Field controlId="date1" helperText="The date picker allows you to select a date." label="Date">
+                <DatePicker id="date1" name="date1" onChange={setFieldDate} required value={fieldDate} />
             </Field>
         </div>
     );

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

@@ -3,7 +3,7 @@ import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
 const TestBed = () => (
-    <DatePickerField label="Example field label" name="example-field-name" onChange={() => {}} value={undefined} />
+    <DatePickerField label="Example field label" name="example-field-name" onChange={() => {}} value="" />
 );
 
 describe('DatePickerField (RTL)', () => {

package/src/components/DatePickerField/DatePickerField.tsx

@@ -1,7 +1,8 @@
 import { DatePicker, DatePickerProps } from '-/components/DatePicker';
-import { FormField, FormFieldControlProps } from '-/components/FormField';
+import { Field, FieldControlProps, propsWithAria } from '-/components/Field';
+import { useId } from '-/hooks/useId';
 
-export type DatePickerFieldProps = FormFieldControlProps<DatePickerProps>;
+export type DatePickerFieldProps = FieldControlProps<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,21 @@ 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}
             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,35 +1,46 @@
 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> = {
+export type FieldControlProps<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 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 form field. This should be a control such as DatePicker, Input, InputNumber, InputPhone,
-     * Password, Select, Textarea, or TimePicker.
+     * 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;
 };
 
 /**
@@ -40,25 +51,22 @@ const isComponentName = (
  *
  * @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 +74,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,78 @@
+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, 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 (
+        <fieldset {...props} data-bspk-utility="field" role="group">
+            <legend data-field-label id={labelledById(id)}>
+                <span>{label}</span>
+                {required && <span data-required>{' (Required)'}</span>}
+                {labelTrailing && (
+                    <span aria-hidden data-trailing>
+                        {labelTrailing}
+                    </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>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/field.scss

@@ -6,40 +6,36 @@
     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-bspk-owner='field-error'] {
-    // Styles for FieldError component when used inside Field
+    [data-field-description] {
+        font: var(--body-small);
+        color: var(--foreground-neutral-on-surface-variant-01);
+        margin: 0;
+        padding: 0;
+    }
 }
 
 /** 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';