@bspk/ui 1.3.3 → 1.3.4

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/{NumberInput/NumberInput.rtl.test.tsx → Input/Input.rtl.test.tsx}

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

package/src/components/Input/Input.tsx

@@ -0,0 +1,99 @@
+import './input.scss';
+import { DEFAULT, InputElement, InputElementProps } from './InputElement';
+import { useFieldInit } from '-/components/Field';
+import { ElementProps } from '-/types/common';
+
+export type InputProps = Omit<InputElementProps, 'ariaDescribedBy' | 'ariaErrorMessage'>;
+
+/**
+ * An input that allows users to enter text, numbers or symbols in a singular line.
+ *
+ * For a more complete example with field usage, see the InputField component.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Input } from '@bspk/ui/Input';
+ *     import { Field, FieldLabel } from '@bspk/ui/Field';
+ *
+ *     function Example() {
+ *         const [value, setValue] = useState('');
+ *
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Example Label</FieldLabel>
+ *                 <Input name="example-name" onChange={setValue} value={value} />
+ *                 <FieldDescription>This is an example input field.</FieldDescription>
+ *             </Field>
+ *         );
+ *     }
+ *
+ *     function ExampleWithAriaLabel() {
+ *         const [value, setValue] = useState('');
+ *
+ *         return <Input aria-label="Example Input" name="example-name" onChange={setValue} value={value} />;
+ *     }
+ *
+ * @name Input
+ * @phase UXReview
+ */
+export function Input({
+    invalid: invalidProp,
+    onChange,
+    size = DEFAULT.size,
+    value = DEFAULT.value,
+    name,
+    'aria-label': ariaLabel = 'Input',
+    inputRef,
+    required = false,
+    placeholder,
+    id: idProp,
+    leading,
+    trailing,
+    type = DEFAULT.type,
+    readOnly,
+    disabled,
+    autoComplete = DEFAULT.autoComplete,
+    containerRef,
+    showClearButton: showClearButtonProp = true,
+    owner,
+    inputProps,
+    ...props
+}: ElementProps<InputProps, 'div'>) {
+    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
+        idProp,
+        required,
+        disabled,
+        readOnly,
+        invalidProp,
+    });
+
+    return (
+        // data-bspk="input" -- because InputElement already has it :)
+        <InputElement
+            {...props}
+            aria-label={ariaLabel}
+            ariaDescribedBy={ariaDescribedBy}
+            ariaErrorMessage={ariaErrorMessage}
+            autoComplete={autoComplete}
+            containerRef={containerRef}
+            disabled={disabled}
+            id={id}
+            inputProps={inputProps}
+            inputRef={inputRef}
+            invalid={invalid}
+            leading={leading}
+            name={name}
+            onChange={onChange}
+            owner={owner}
+            placeholder={placeholder}
+            readOnly={readOnly}
+            showClearButton={showClearButtonProp}
+            size={size}
+            trailing={trailing}
+            type={type}
+            value={value}
+        />
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/{TextInput/TextInput.tsx → Input/InputElement.tsx}

@@ -1,10 +1,10 @@
-import './text-input.scss';
+import './input.scss';
 import { SvgCancel } from '@bspk/icons/Cancel';
-import { ChangeEvent, HTMLInputTypeAttribute, ReactNode, useMemo, useRef, useState } from 'react';
+import { HTMLInputTypeAttribute, ReactNode, useMemo, useRef, useState } from 'react';
 import { Button } from '-/components/Button';
-import { useId } from '-/hooks/useId';
+import { FieldContextProps } from '-/components/Field';
 import { useTimeout } from '-/hooks/useTimeout';
-import { CommonProps, ElementProps, FormFieldControlProps, SetRef } from '-/types/common';
+import { CommonProps, ElementProps, SetRef, FieldControlProps } from '-/types/common';
 
 export const DEFAULT = {
     size: 'medium',
@@ -13,89 +13,85 @@ export const DEFAULT = {
     autoComplete: 'off',
 } as const;
 
-type TextInputBaseProps = {
-    /**
-     * Callback when the value of the field changes.
-     *
-     * @required
-     */
-    onChange: (next: string, event?: ChangeEvent<HTMLInputElement>) => void;
-    /** The ref of the container. */
-    containerRef?: SetRef<HTMLDivElement>;
-    /** The ref of the input. */
-    inputRef?: SetRef<HTMLInputElement>;
-    /**
-     * The trailing element to display in the field.
-     *
-     * @exampleType string
-     */
-    trailing?: ReactNode;
-    /**
-     * The leading element to display in the field.
-     *
-     * @exampleType string
-     */
-    leading?: ReactNode;
-    /** The placeholder of the field. */
-    placeholder?: string;
-    /**
-     * The type of the input.
-     *
-     * @default text
-     */
-    type?: Extract<HTMLInputTypeAttribute, 'number' | 'password' | 'text'>;
-    /**
-     * Specifies if user agent has any permission to provide automated assistance in filling out form field values
-     *
-     * @default off
-     */
-    autoComplete?: '' | 'off' | 'on';
-    /**
-     * Specifies if the clear button should be shown. This should almost always be true, but can be set to false.
-     *
-     * @default true
-     */
-    showClearButton?: boolean;
-};
-
-export type TextInputProps = CommonProps<
-    'aria-label' | 'disabled' | 'id' | 'invalid' | 'name' | 'owner' | 'readOnly' | 'required' | 'size' | 'value'
-> &
-    FormFieldControlProps &
-    TextInputBaseProps & {
-        inputProps?: Omit<React.InputHTMLAttributes<HTMLInputElement>, keyof TextInputBaseProps>;
+type InputElementBaseProps = CommonProps<'owner' | 'size'> &
+    FieldControlProps &
+    Pick<FieldContextProps, 'ariaDescribedBy' | 'ariaErrorMessage'> & {
+        /** The ref of the container. */
+        containerRef?: SetRef<HTMLDivElement>;
+        /** The ref of the input. */
+        inputRef?: SetRef<HTMLInputElement>;
+        /**
+         * The trailing element to display in the field.
+         *
+         * @exampleType string
+         */
+        trailing?: ReactNode;
+        /**
+         * The leading element to display in the field.
+         *
+         * @exampleType string
+         */
+        leading?: ReactNode;
+        /** The placeholder of the field. */
+        placeholder?: string;
+        /**
+         * The type of the input.
+         *
+         * @default text
+         */
+        type?: Extract<HTMLInputTypeAttribute, 'number' | 'password' | 'text'>;
+        /**
+         * Specifies if user agent has any permission to provide automated assistance in filling out form field values
+         *
+         * @default off
+         */
+        autoComplete?: 'off' | 'on';
+        /**
+         * Specifies if the clear button should be shown. This should almost always be true, but can be set to false.
+         *
+         * @default true
+         */
+        showClearButton?: boolean;
     };
 
+export type InputElementProps = InputElementBaseProps & {
+    inputProps?: Omit<React.InputHTMLAttributes<HTMLInputElement>, keyof InputElementBaseProps>;
+};
+
 /**
- * A text input that allows users to enter text, numbers or symbols in a singular line. This is the base element and is
- * not intended to be used directly. Use the TextField component.
+ * An input that allows users to enter text, numbers or symbols in a singular line. This is a utility element and is not
+ * intended to be used directly but rather through the Input, and other components.
  *
  * @example
  *     import { useState } from 'react';
- *     import { TextInput } from '@bspk/ui/TextInput';
+ *     import { InputElement } from '@bspk/ui/InputElement';
+ *     import { Field, FieldLabel } from '@bspk/ui/Field';
  *
- *     export function Example() {
- *         const [value, setValue] = useState<string>('');
+ *     function Example() {
+ *         const [value, setValue] = useState('');
  *
- *         return <TextInput aria-label="Example aria-label" name="Example name" onChange={setValue} value={value} />;
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Example Label</FieldLabel>
+ *                 <InputElement name="example-name" onChange={setValue} value={value} />
+ *             </Field>
+ *         );
  *     }
  *
- * @element
- *
- * @name TextInput
+ * @name InputElement
  * @phase Utility
  */
-export function TextInput({
-    invalid: invalidProp,
+export function InputElement({
+    invalid,
     onChange,
     size = DEFAULT.size,
     value = DEFAULT.value,
     name,
-    'aria-label': ariaLabel,
+    'aria-label': ariaLabel = 'Input',
     inputRef,
-    required,
+    required = false,
     placeholder,
-    id: idProp,
+    id,
     leading,
     trailing,
     type = DEFAULT.type,
@@ -105,15 +101,11 @@ export function TextInput({
     containerRef,
     showClearButton: showClearButtonProp = true,
     owner,
-    'aria-describedby': ariaDescribedBy,
-    'aria-errormessage': ariaErrorMessage,
     inputProps,
+    ariaDescribedBy,
+    ariaErrorMessage,
     ...props
-}: ElementProps<TextInputProps, 'div'>) {
-    const id = useId(idProp);
-
-    const invalid = !readOnly && !disabled && invalidProp;
-
+}: ElementProps<InputElementProps, 'div'>) {
     const [focused, setFocused] = useState(false);
 
     const showClearButton = useMemo(
@@ -128,7 +120,7 @@ export function TextInput({
     return (
         <div
             {...props}
-            data-bspk="text-input"
+            data-bspk="input"
             data-bspk-owner={owner || undefined}
             data-disabled={disabled || undefined}
             data-empty={!value.toString().length || undefined}