@bspk/ui 1.3.8 → 1.3.10

package/src/components/Fab/Fab.tsx

@@ -4,11 +4,13 @@ import { ButtonProps } from '-/components/Button';
 import { Tooltip, TooltipTriggerProps } from '-/components/Tooltip';
 import { ElementProps } from '-/types/common';
 
+export type FabSize = 'medium' | 'small';
+
 export type FabVariant = 'neutral' | 'primary' | 'secondary';
 
 export type FabProps<As extends ElementType = ElementType> = Pick<
     ButtonProps<As>,
-    'as' | 'icon' | 'iconOnly' | 'onClick' | 'toolTip'
+    'as' | 'icon' | 'iconOnly' | 'innerRef' | 'onClick' | 'toolTip'
 > &
     Required<Pick<ButtonProps<As>, 'label'>> & {
         /**
@@ -16,7 +18,7 @@ export type FabProps<As extends ElementType = ElementType> = Pick<
          *
          * @default small
          */
-        size?: 'medium' | 'small';
+        size?: FabSize;
         /**
          * The style variant of the button.
          *
@@ -45,9 +47,7 @@ export type FabProps<As extends ElementType = ElementType> = Pick<
  *     import { SvgBolt } from '@bspk/icons/Bolt';
  *     import { Fab } from '@bspk/ui/Fab';
  *
- *     function Example() {
- *         return <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
- *     }
+ *     <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
  *
  * @name Fab
  * @phase UXReview
@@ -63,6 +63,7 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
         label,
         icon,
         toolTip,
+        innerRef,
         ...otherProps
     } = props;
 
@@ -77,6 +78,7 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
             data-bspk="fab"
             data-container={container}
             data-placement={placement}
+            data-position={container === 'page' ? 'fixed' : 'absolute'}
             data-round={iconOnly || undefined}
             data-size={size}
             data-variant={variant}
@@ -96,6 +98,7 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
                 triggerProps.onMouseOver?.();
                 otherProps.onMouseOver?.(e);
             }}
+            ref={innerRef}
         >
             {!!icon && isValidElement(icon) && (
                 <span aria-hidden={true} data-fab-icon>

package/src/components/Fab/FabExample.tsx

@@ -1,10 +1,29 @@
+import { FabProps } from './Fab';
 import { ButtonExample } from '-/components/Button/ButtonExample';
 import { ComponentExample } from '-/utils/demo';
 
 export const presets = ButtonExample.presets || [];
 
-export const FabExample: ComponentExample = {
+export const FabExample: ComponentExample<FabProps> = {
     containerStyle: { display: 'block', height: '152px', width: '100%' },
-    presets,
-    variants: false,
+    presets: ButtonExample.presets?.map((preset) => ({
+        ...preset,
+        propState: {
+            ...preset.propState,
+            size: undefined,
+            variant: undefined,
+        },
+    })),
+    defaultState: {
+        container: 'local',
+        placement: 'bottom-right',
+    },
+    variants: {
+        container: false,
+        placement: false,
+        iconOnly: {
+            icon: 'MenuBook',
+            label: 'Menu Book',
+        },
+    },
 };

package/src/components/Field/Field.tsx

@@ -42,9 +42,9 @@ const isComponentName = (
  *     import { Input } from '@bspk/ui/Input';
  *     import { Field, FieldLabel, FieldDescription, FieldError } from '@bspk/ui/Field';
  *
- *     function Example() {
- *         const [state, setState] = React.useState<string | undefined>(undefined);
- *         const [error, setError] = React.useState<string | undefined>(undefined);
+ *     () => {
+ *         const [state, setState] = useState<string | undefined>(undefined);
+ *         const [error, setError] = useState<string | undefined>(undefined);
  *
  *         return (
  *             <Field label="Example label">
@@ -56,13 +56,12 @@ const isComponentName = (
  *                         setState(next);
  *                     }}
  *                     value={state}
- *                     {...fieldProps}
  *                 />
  *                 <FieldDescription>This is an example description.</FieldDescription>
  *                 {error && <FieldError>{error}</FieldError>}
  *             </Field>
  *         );
- *     }
+ *     };
  *
  * @name Field
  * @phase Utility

package/src/components/Field/FieldDescription.tsx

@@ -1,6 +1,12 @@
 import { useFieldContext, describedById } from './utils';
 
-function FieldDescription({ children }: { children?: string }) {
+/**
+ * FieldDescription component displays a description associated with a form field.
+ *
+ * @name FieldDescription
+ * @parent Field
+ */
+export function FieldDescription({ children }: { children?: string }) {
     const { id } = useFieldContext();
 
     return children ? (
@@ -9,7 +15,3 @@ function FieldDescription({ children }: { children?: string }) {
         </p>
     ) : null;
 }
-
-FieldDescription.displayName = 'FieldDescription';
-
-export { FieldDescription };

package/src/components/Field/FieldError.tsx

@@ -6,6 +6,12 @@ export type FieldErrorProps = {
     children?: string;
 };
 
+/**
+ * FieldError component displays an error message associated with a form field.
+ *
+ * @name FieldError
+ * @parent Field
+ */
 export function FieldError({ children }: FieldErrorProps) {
     const { id } = useFieldContext();
 

package/src/components/Field/FieldLabel.tsx

@@ -14,6 +14,12 @@ export type FieldLabelProps<As extends ElementType = ElementType> = Pick<FieldCo
     as?: As;
 };
 
+/**
+ * FieldLabel component displays a label associated with a form field.
+ *
+ * @name FieldLabel
+ * @parent Field
+ */
 export function FieldLabel<As extends ElementType = ElementType>({
     children,
     labelTrailing,

package/src/components/Field/utils.ts

@@ -28,6 +28,11 @@ export type FieldContext = FieldContextProps & {
 
 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) || {

package/src/components/FileUpload/FileUpload.tsx

@@ -73,7 +73,7 @@ export type FileUploadProps = Pick<FileUploadItemProps, 'cancelButtonLabel' | 'o
  * @example
  *     import { FileUpload } from '@bspk/ui/FileUpload';
  *
- *     function Example() {
+ *     () => {
  *         const [files, setFiles] = useState([]);
  *         return (
  *             <FileUpload
@@ -82,12 +82,12 @@ export type FileUploadProps = Pick<FileUploadItemProps, 'cancelButtonLabel' | 'o
  *                 acceptedFileTypes={['image/png', 'image/gif', 'image/svg+xml']}
  *                 files={files}
  *                 maxFileSize={5}
- *                 onError={(errorFiles) => console.log('Upload error:', errorFiles)}
+ *                 onError={(errorFiles) => sendSnackbar('Upload error:', errorFiles)}
  *                 onUpload={(uploadFiles) => setFiles(uploadFiles)}
  *                 uploadSubtitle="SVG, PNG, JPG or GIF (max. 5MB)"
  *             />
  *         );
- *     }
+ *     };
  *
  * @name FileUpload
  * @phase UXReview

package/src/components/FileUploadItem/FileUploadItem.tsx

@@ -30,16 +30,12 @@ export type FileUploadItemProps = FileEntry & {
  * @example
  *     import { FileUploadItem } from '@bspk/ui/FileUploadItem';
  *
- *     function Example() {
- *         return (
- *             <FileUploadItem
- *                 fileName="dunder-mifflin-paper-co.jpg"
- *                 fileSize="1.43 mb"
- *                 status="Uploading"
- *                 onCancel={() => console.log('Cancel item clicked!')}
- *             />
- *         );
- *     }
+ *     <FileUploadItem
+ *         fileName="dunder-mifflin-paper-co.jpg"
+ *         fileSize="1.43 mb"
+ *         status="Uploading"
+ *         onCancel={() => sendSnackbar('Cancel item clicked!')}
+ *     />;
  *
  * @name FileUploadItem
  * @phase UXReview

package/src/components/FormField/FormField.tsx

@@ -54,26 +54,15 @@ export type FormFieldProps<As extends ElementType = ElementType> = CommonProps<'
  *     import { Input } from '@bspk/ui/Input';
  *     import { FormField } from '@bspk/ui/FormField';
  *
- *     function Example() {
- *         const [state, setState] = React.useState<string | undefined>(undefined);
+ *     () => {
+ *         const [state, setState] = useState<string | undefined>(undefined);
+ *
  *         return (
  *             <FormField controlId="Example controlId" label="Example label">
- *                 {(fieldProps) => {
- *                     return (
- *                         <Input
- *                             aria-label="example aria-label"
- *                             name="example-text"
- *                             onChange={(next) => {
- *                                 setState(next);
- *                             }}
- *                             value={state}
- *                             {...fieldProps}
- *                         />
- *                     );
- *                 }}
+ *                 <Input name="example-text" onChange={(next) => setState(next)} value={state} />
  *             </FormField>
  *         );
- *     }
+ *     };
  *
  * @name FormField
  * @phase Utility

package/src/components/Img/Img.tsx

@@ -21,9 +21,7 @@ export type ImgProps = {
  * @example
  *     import { Img } from '@bspk/ui/Img';
  *
- *     function Example() {
- *         return <Img alt="Example alt" src="Example src" />;
- *     }
+ *     <Img alt="Example alt" src="Example src" />;
  *
  * @name Img
  * @phase Backlog

package/src/components/InlineAlert/InlineAlert.tsx

@@ -32,9 +32,7 @@ export type InlineAlertProps = CommonProps<'owner'> & {
  * @example
  *     import { InlineAlert } from '@bspk/ui/InlineAlert';
  *
- *     function Example() {
- *         return <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
- *     }
+ *     <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
  *
  * @name InlineAlert
  * @phase UXReview

package/src/components/InlineAlert/SvgWarningTwoTone.tsx

@@ -1,3 +1,9 @@
+/**
+ * SvgWarningTwoTone component renders a two-tone warning SVG icon.
+ *
+ * @name SvgWarningTwoTone
+ * @parent InlineAlert
+ */
 export function SvgWarningTwoTone() {
     return (
         <svg fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">

package/src/components/Input/Input.tsx

@@ -15,23 +15,23 @@ export type InputProps = Omit<InputElementProps, 'ariaDescribedBy' | 'ariaErrorM
  *     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>
+ *             <>
+ *                 // standalone input example
+ *                 <Input aria-label="Example Input" name="example-name" onChange={setValue} value={value} />
+ *                 <br />
+ *                 // input used within a field
+ *                 <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

package/src/components/Input/InputElement.tsx

@@ -67,16 +67,22 @@ export type InputElementProps = InputElementBaseProps & {
  *     import { InputElement } from '@bspk/ui/InputElement';
  *     import { Field, FieldLabel } from '@bspk/ui/Field';
  *
- *     function Example() {
+ *     () => {
  *         const [value, setValue] = useState('');
  *
  *         return (
- *             <Field>
- *                 <FieldLabel>Example Label</FieldLabel>
+ *             <>
+ *                 // standalone input element example
  *                 <InputElement name="example-name" onChange={setValue} value={value} />
- *             </Field>
+ *                 <br />
+ *                 // input element used within a field
+ *                 <Field>
+ *                     <FieldLabel>Example Label</FieldLabel>
+ *                     <InputElement name="example-name" onChange={setValue} value={value} />
+ *                 </Field>
+ *             </>
  *         );
- *     }
+ *     };
  *
  * @name InputElement
  * @phase Utility

package/src/components/InputNumber/IncrementButton.tsx

@@ -3,29 +3,39 @@ import { SvgRemove } from '@bspk/icons/Remove';
 import { useLongPress } from '-/hooks/useLongPress';
 
 export type IncrementButtonProps = {
+    /** Whether the button is disabled. */
     disabled: boolean;
-    increment: -1 | 1;
-    onIncrement: (increment: -1 | 1) => void;
+    /** The kind of increment button, either 'add' or 'remove'. */
+    kind: 'add' | 'remove';
+    /** The ID of the associated input element. */
     inputId: string;
+    /** Function to trigger the increment action. */
+    triggerIncrement: (kind: 'add' | 'remove') => boolean;
 };
 
-export function IncrementButton({ increment, disabled, onIncrement, inputId }: IncrementButtonProps) {
-    const add = increment === 1;
-
-    const { setTriggerElement, ...handlers } = useLongPress(() => onIncrement(increment), disabled);
+/**
+ * A button component for incrementing or decrementing the InputNumber.
+ *
+ * @name IncrementButton
+ * @parent InputNumber
+ */
+export function IncrementButton({ inputId, kind, disabled, triggerIncrement }: IncrementButtonProps) {
+    const { ...pressHandlers } = useLongPress({
+        callback: () => triggerIncrement(kind),
+    });
 
     return (
         <button
-            {...handlers}
+            {...pressHandlers}
             aria-controls={inputId}
-            aria-hidden="true"
-            data-increment={increment}
+            aria-label={kind === 'add' ? 'Increase value' : 'Decrease value'}
+            data-bspk="input-number--increment-button"
+            data-kind={kind}
             disabled={disabled}
-            ref={setTriggerElement}
             tabIndex={-1}
             type="button"
         >
-            {add ? <SvgAdd /> : <SvgRemove />}
+            {kind === 'add' ? <SvgAdd aria-hidden /> : <SvgRemove aria-hidden />}
         </button>
     );
 }

package/src/components/InputNumber/InputNumber.tsx

@@ -1,14 +1,16 @@
 import './input-number.scss';
-import { useMemo } from 'react';
+import { useEffect, useRef } from 'react';
 import { IncrementButton } from './IncrementButton';
 import { useFieldInit } from '-/components/Field';
 import { useId } from '-/hooks/useId';
 import { CommonProps, FieldControlProps } from '-/types/common';
 
-function isNumber(value: unknown, fallbackValue: number | undefined = undefined): number | undefined {
+function isNumber(value: unknown): number | undefined;
+function isNumber(value: unknown, fallbackValue: number): number;
+function isNumber(value: unknown, fallbackValue?: number): number | undefined {
     if (typeof value === 'number') return value;
     if (typeof value !== 'string') return fallbackValue;
-    const num = Number(value);
+    const num = parseFloat(value);
     return isNaN(num) ? fallbackValue : num;
 }
 
@@ -51,35 +53,35 @@ export type InputNumberProps = CommonProps<'size'> &
  * @example
  *     import { InputNumber } from '@bspk/ui/InputNumber';
  *
- *     function ExampleStandalone() {
- *         const [state, setState] = React.useState<number | undefined>();
+ *     () => {
+ *         const [state, setState] = useState<number | undefined>();
  *
  *         return (
- *             <InputNumber
- *                 aria-label="Example aria-label"
- *                 name="example-name"
- *                 onChange={(nextValue) => setState(nextValue)}
- *                 value={state}
- *             />
- *         );
- *     }
- *
- *     function ExampleWithField() {
- *         const [state, setState] = React.useState<number | undefined>();
- *
- *         return (
- *             <Field>
- *                 <FieldLabel>Example Input Number</FieldLabel>
+ *             <>
+ *                 // standalone input number example
  *                 <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>
+ *                 <br />
+ *                 // input number used within a field
+ *                 <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
@@ -108,14 +110,25 @@ export function InputNumber({
         readOnly,
         invalidProp,
     });
-
     const max = typeof maxProp === 'number' && maxProp >= min ? maxProp : Number.MAX_SAFE_INTEGER;
     const centered = align !== 'left';
     const inputId = useId(id);
-    const value = useMemo(() => isNumber(valueProp) || 0, [valueProp]);
+    const value = isNumber(valueProp, min);
+    const removeDisabled = disabled || value + step * -1 < min;
+    const addDisabled = disabled || value + step > max;
+
+    const valueRef = useRef(value);
 
-    const handleIncrement = (increment: -1 | 1) => {
-        onChange(value + increment * step);
+    useEffect(() => {
+        valueRef.current = value;
+    }, [value]);
+
+    const incrementHandler = (kind: 'add' | 'remove') => {
+        const increment = kind === 'add' ? step : step * -1;
+        const next = valueRef.current + increment;
+        if (next < min || next > max) return false;
+        onChange(next);
+        return true;
     };
 
     return (
@@ -128,14 +141,6 @@ export function InputNumber({
             data-size={size}
             data-stepper-input
         >
-            {!!centered && (
-                <IncrementButton
-                    disabled={disabled ? true : value + -1 < min}
-                    increment={-1}
-                    inputId={inputId}
-                    onIncrement={handleIncrement}
-                />
-            )}
             <input
                 {...inputElementProps}
                 aria-describedby={ariaDescribedBy || undefined}
@@ -151,32 +156,29 @@ export function InputNumber({
                 max={max}
                 min={min}
                 name={name}
+                onBlur={(e) => {
+                    const next = isNumber(e.target.value, min);
+                    e.target.value = next?.toString() || '';
+                    onChange(next);
+                }}
                 onChange={(e) => {
-                    onChange(isNumber(e.target.value));
+                    const next = isNumber(e.target.value, min);
+                    onChange(next);
                 }}
                 readOnly={readOnly}
                 required={required}
                 step={step}
                 type="number"
-                value={value}
+                value={value !== undefined ? value : ''}
             />
-            {!centered && (
-                <>
-                    <div aria-hidden data-divider />
-                    <IncrementButton
-                        disabled={!!disabled || value + -1 < min}
-                        increment={-1}
-                        inputId={inputId}
-                        onIncrement={handleIncrement}
-                    />
-                </>
-            )}
+            <div aria-hidden data-divider />
             <IncrementButton
-                disabled={!!disabled || value + 1 > max}
-                increment={1}
+                disabled={removeDisabled}
                 inputId={inputId}
-                onIncrement={handleIncrement}
+                kind="remove"
+                triggerIncrement={incrementHandler}
             />
+            <IncrementButton disabled={addDisabled} inputId={inputId} kind="add" triggerIncrement={incrementHandler} />
         </div>
     );
 }

package/src/components/InputNumber/InputNumberExample.tsx

@@ -6,4 +6,5 @@ export const InputNumberExample: ComponentExample<InputNumberProps> = {
         'aria-label': 'input number aria-label',
     },
     render: ({ props, Component }) => <Component {...props} />,
+    variants: false,
 };

package/src/components/InputNumber/input-number.scss

@@ -129,6 +129,16 @@
         --height: var(--spacing-sizing-12);
         --svg-width: var(--spacing-sizing-06);
     }
+
+    &[data-centered] {
+        button:first-of-type {
+            order: -1;
+        }
+
+        [data-divider] {
+            display: none;
+        }
+    }
 }
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/InputPhone/InputPhone.tsx

@@ -59,25 +59,30 @@ export type InputPhoneProps = FieldControlProps<string, SupportedCountryCode> &
  * @example
  *     import { InputPhone } from '@bspk/ui/InputPhone';
  *
- *     function ExampleStandalone() {
- *         const [value, onChange] = React.useState<number | undefined>();
- *
- *         return <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
- *     }
- *
- *     function ExampleWithField() {
- *         const [value, onChange] = React.useState<number | undefined>();
+ *     () => {
+ *         const [value, onChange] = useState<number | undefined>();
  *
  *         return (
- *             <Field>
- *                 <FieldLabel>Example Input Phone</FieldLabel>
- *                 <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />
- *                 <FieldDescription>
- *                     The phone input allows you to enter a phone number with country code.
- *                 </FieldDescription>
- *             </Field>
+ *             <>
+ *                 // standalone input phone example
+ *                 <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
+ *                 <br />
+ *                 // input phone used within a field
+ *                 <Field>
+ *                     <FieldLabel>Example Input Phone</FieldLabel>
+ *                     <InputPhone
+ *                         aria-label="Phone Number"
+ *                         initialCountryCode="US"
+ *                         value={value}
+ *                         onChange={onChange}
+ *                     />
+ *                     <FieldDescription>
+ *                         The phone input allows you to enter a phone number with country code.
+ *                     </FieldDescription>
+ *                 </Field>
+ *             </>
  *         );
- *     }
+ *     };
  *
  * @name InputPhone
  * @phase UXReview