@bspk/ui 1.3.3 → 1.3.5

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}

package/src/components/Input/InputExample.tsx

@@ -0,0 +1,57 @@
+import { InputProps } from '.';
+import { ComponentExample } from '-/utils/demo';
+
+type InputExampleProps = InputProps & { label: string; description?: string };
+
+export const InputExample: ComponentExample<InputExampleProps> = {
+    defaultState: {
+        label: 'Property Description',
+        description: 'This is a description of the property.',
+        placeholder: 'Waterfront condo with great views',
+    },
+    render: ({ props, Component }) => <Component {...props} />,
+    presets: [
+        {
+            label: 'Currency',
+            propState: {
+                value: '',
+                type: 'number',
+                leading: '$',
+                trailing: undefined,
+                placeholder: '0.00',
+                name: 'currency',
+                label: 'Balance',
+                description: 'Enter the current balance',
+            },
+        },
+        {
+            label: 'Percent',
+            propState: {
+                value: '',
+                type: 'number',
+                leading: undefined,
+                trailing: '%',
+                placeholder: '0',
+                name: 'percent',
+                label: 'Growth Rate',
+                description: 'Enter the expected growth rate',
+            },
+        },
+        {
+            label: 'Dimension',
+            propState: {
+                value: '',
+                type: 'number',
+                leading: undefined,
+                placeholder: '0',
+                trailing: 'Acre(s)',
+                name: 'dimension',
+                label: 'Land Size',
+                description: 'Enter the size of the land',
+            },
+        },
+    ],
+    variants: {
+        type: false,
+    },
+};

package/src/components/Input/index.tsx

@@ -0,0 +1,2 @@
+export * from './Input';
+export * from './InputElement';

package/src/components/{TextInput/text-input.scss → Input/input.scss}

@@ -1,4 +1,4 @@
-[data-bspk='text-input'] {
+[data-bspk='input'] {
     --border-color: var(--stroke-neutral-base);
 
     display: flex;
@@ -62,6 +62,12 @@
         --border-color: var(--status-error);
     }
 
+    &:focus-within {
+        --border-color: var(--stroke-neutral-focus);
+
+        outline: 1px solid var(--stroke-neutral-focus);
+    }
+
     &[data-size='small'] {
         --field-padding: var(--spacing-sizing-02);
         --field-height: var(--spacing-sizing-08);
@@ -114,12 +120,6 @@
             display: none;
         }
     }
-
-    &:focus-within {
-        --border-color: var(--stroke-neutral-focus);
-
-        outline: 1px solid var(--stroke-neutral-focus);
-    }
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

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

@@ -0,0 +1,15 @@
+import { InputField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <InputField label="Example field label" name="example-field-name" onChange={() => {}} value="" />;
+
+describe('InputField (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/InputField/InputField.tsx

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

package/src/components/InputField/index.tsx

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

package/src/components/{NumberInput/NumberInput.rtl.test.tsx → InputNumber/InputNumber.rtl.test.tsx}

@@ -1,10 +1,10 @@
-import { NumberInput } from './NumberInput';
+import { InputNumber } 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 = () => <InputNumber aria-label="Example label" name="example-name" onChange={() => {}} value={24} />;
 
-describe('NumberInput (RTL)', () => {
+describe('InputNumber (RTL)', () => {
     it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
 
     it('renders', () => {

package/src/components/{NumberInput/NumberInput.tsx → InputNumber/InputNumber.tsx}

@@ -1,8 +1,9 @@
-import './number-input.scss';
+import './input-number.scss';
 import { useMemo } from 'react';
 import { IncrementButton } from './IncrementButton';
+import { useFieldInit } from '-/components/Field';
 import { useId } from '-/hooks/useId';
-import { CommonProps, FormFieldControlProps } from '-/types/common';
+import { CommonProps, FieldControlProps } from '-/types/common';
 
 function isNumber(value: unknown, fallbackValue: number | undefined = undefined): number | undefined {
     if (typeof value === 'number') return value;
@@ -11,18 +12,8 @@ function isNumber(value: unknown, fallbackValue: number | undefined = undefined)
     return isNaN(num) ? fallbackValue : num;
 }
 
-export type NumberInputProps = CommonProps<
-    'aria-label' | 'disabled' | 'id' | 'invalid' | 'name' | 'readOnly' | 'size'
-> &
-    FormFieldControlProps & {
-        /** The value of the control. */
-        value?: number;
-        /**
-         * Callback when the value changes.
-         *
-         * @required
-         */
-        onChange: (value: number | string | undefined) => void;
+export type InputNumberProps = CommonProps<'size'> &
+    FieldControlProps<number> & {
         /**
          * The alignment of the input box. Centered between the plus and minus buttons or to the left of the buttons.
          *
@@ -55,26 +46,45 @@ export type NumberInputProps = CommonProps<
  *
  * The value of the input is a number. The value is clamped to the min and max values if they are provided.
  *
+ * For a more complete example with field usage, see the InputNumberField component.
+ *
  * @example
- *     import { NumberInput } from '@bspk/ui/NumberInput';
+ *     import { InputNumber } from '@bspk/ui/InputNumber';
  *
- *     export function Example() {
- *         const [state, setState] = React.useState<number>();
+ *     function ExampleStandalone() {
+ *         const [state, setState] = React.useState<number | undefined>();
  *
  *         return (
- *             <NumberInput
+ *             <InputNumber
  *                 aria-label="Example aria-label"
- *                 name="Example name"
+ *                 name="example-name"
  *                 onChange={(nextValue) => setState(nextValue)}
  *                 value={state}
  *             />
  *         );
  *     }
  *
- * @name NumberInput
- * @phase Utility
+ *     function ExampleWithField() {
+ *         const [state, setState] = React.useState<number | undefined>();
+ *
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Example Input Number</FieldLabel>
+ *                 <InputNumber
+ *                     aria-label="Example aria-label"
+ *                     name="example-name"
+ *                     onChange={(nextValue) => setState(nextValue)}
+ *                     value={state}
+ *                 />
+ *                 <FieldDescription>The input number allows you to increment or decrement a value.</FieldDescription>
+ *             </Field>
+ *         );
+ *     }
+ *
+ * @name InputNumber
+ * @phase UXReview
  */
-export function NumberInput({
+export function InputNumber({
     value: valueProp,
     onChange,
     align = 'center',
@@ -82,19 +92,26 @@ export function NumberInput({
     disabled = false,
     readOnly = false,
     name,
-    id: inputIdProp,
-    'aria-label': ariaLabel,
+    id: idProp,
+    'aria-label': ariaLabel = 'Input number',
     max: maxProp,
     min = 0,
-    invalid,
-    'aria-describedby': ariaDescribedBy,
-    'aria-errormessage': ariaErrorMessage,
+    invalid: invalidProp = false,
     step = 1,
+    required = false,
     ...inputElementProps
-}: NumberInputProps) {
+}: InputNumberProps) {
+    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
+        idProp,
+        required,
+        disabled,
+        readOnly,
+        invalidProp,
+    });
+
     const max = typeof maxProp === 'number' && maxProp >= min ? maxProp : Number.MAX_SAFE_INTEGER;
     const centered = align !== 'left';
-    const inputId = useId(inputIdProp);
+    const inputId = useId(id);
     const value = useMemo(() => isNumber(valueProp) || 0, [valueProp]);
 
     const handleIncrement = (increment: -1 | 1) => {
@@ -103,7 +120,7 @@ export function NumberInput({
 
     return (
         <div
-            data-bspk="number-input"
+            data-bspk="input-number"
             data-centered={centered || undefined}
             data-disabled={disabled || undefined}
             data-invalid={invalid || undefined}
@@ -138,6 +155,7 @@ export function NumberInput({
                     onChange(isNumber(e.target.value));
                 }}
                 readOnly={readOnly}
+                required={required}
                 step={step}
                 type="number"
                 value={value}

package/src/components/{NumberInput/NumberInputExample.tsx → InputNumber/InputNumberExample.tsx}

@@ -1,6 +1,6 @@
-import { NumberInputProps } from './NumberInput';
+import { InputNumberProps } from './InputNumber';
 import { ComponentExample } from '-/utils/demo';
 
-export const NumberInputExample: ComponentExample<NumberInputProps> = {
+export const InputNumberExample: ComponentExample<InputNumberProps> = {
     render: ({ props, Component }) => <Component {...props} />,
 };

package/src/components/InputNumber/index.tsx

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

package/src/components/{NumberInput/number-input.scss → InputNumber/input-number.scss}

@@ -1,4 +1,4 @@
-[data-bspk='number-input'] {
+[data-bspk='input-number'] {
     // medium is the default size
     --font: var(--body-base);
     --height: var(--spacing-sizing-10);

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

@@ -0,0 +1,17 @@
+import { InputNumberField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <InputNumberField label="Example field label" name="example-field-name" onChange={() => {}} value={0} />
+);
+
+describe('InputNumberField (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/InputNumberField/InputNumberField.tsx

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

package/src/components/InputNumberField/index.tsx

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