@bspk/ui 1.3.11 → 1.3.17

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

@@ -0,0 +1,19 @@
+import { Grid } from './Grid';
+import { GridExample } from './GridExample';
+
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const testBed = () => <Grid {...GridExample.defaultState}>{GridExample.defaultState?.children}</Grid>;
+
+describe('Grid (RTL)', () => {
+    it(`has no basic a11y issues - ${GridExample.defaultState}`, hasNoBasicA11yIssues(testBed()));
+
+    it('renders', () => {
+        const { getByText } = render(testBed());
+        expect(getByText('Cell 1')).toBeInTheDocument();
+        expect(getByText('Cell 2')).toBeInTheDocument();
+    });
+});
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,75 @@
+import { ReactNode } from 'react';
+import { SizingPixels, numToSizingVar } from '-/utils/sizing';
+
+export type GridProps = {
+    /**
+     * The content of the grid.
+     *
+     * @required
+     */
+    children: ReactNode;
+    /**
+     * The number of columns in the grid or an array of column widths in fractions or other CSS units.
+     *
+     * Values may be "100px, auto, 2fr, 20%" for four columns with specific widths.
+     *
+     * @default 1
+     *
+     * @exampleType string
+     */
+    columns?: (number | string)[] | number;
+    /** The gap between the children. */
+    gap?: SizingPixels;
+    /** Additional styles for the grid container. */
+    style?: React.CSSProperties;
+    /**
+     * The minimum width of each column.
+     *
+     * @default auto
+     */
+    minColumnWidth?: string;
+};
+
+/**
+ * A utility component that arranges its children in a grid layout.
+ *
+ * @example
+ *     import { Grid } from '@bspk/ui/Grid';
+ *
+ *     <Grid columns={4} gap="8">
+ *         <ExamplePlaceholder label="Cell 1" />
+ *         <ExamplePlaceholder label="Cell 2" />
+ *         <ExamplePlaceholder label="Cell 3" />
+ *         <ExamplePlaceholder label="Cell 4" />
+ *     </Grid>;
+ *
+ * @name Grid
+ * @phase Utility
+ */
+export function Grid({ columns = 1, children, gap, style, minColumnWidth = 'auto' }: GridProps) {
+    let gridTemplateColumns = `repeat(auto-fit, minmax(${minColumnWidth}, 1fr))`;
+
+    // If columns is an array, map it to a string of fractions
+    if (Array.isArray(columns))
+        gridTemplateColumns =
+            columns?.map((width) => (typeof width === 'string' ? width : `${width}fr`)).join(' ') || 'auto';
+    // If columns is not an array, use the default repeat pattern
+    else gridTemplateColumns = `repeat(${columns}, minmax(${minColumnWidth}, 1fr))`;
+
+    return (
+        <div
+            data-bspk-utility="grid"
+            style={{
+                width: '100%',
+                display: 'grid',
+                gridTemplateColumns,
+                gap: numToSizingVar(gap),
+                ...style,
+            }}
+        >
+            {children}
+        </div>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Grid/GridExample.tsx

@@ -0,0 +1,42 @@
+import { GridProps } from '.';
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExample } from '-/utils/demo';
+
+export const GridExample: ComponentExample<GridProps> = {
+    defaultState: {
+        children: (
+            <>
+                <div>Cell 1</div>
+                <div>Cell 2</div>
+            </>
+        ),
+        columns: [1, 2],
+    },
+    render: ({ Component, props }) => {
+        const columns = convertColumns(`${props.columns}`);
+
+        return (
+            <Component {...props} columns={columns.value}>
+                {[...Array(columns.count)].map((_, index) => (
+                    <ExamplePlaceholder key={index}>Cell {index + 1}</ExamplePlaceholder>
+                ))}
+            </Component>
+        );
+    },
+};
+
+const convertColumns = (columns: string): { value: (number | string)[] | number; count: number } => {
+    let value: (number | string)[] | number = 1;
+
+    if (columns.includes(','))
+        value = columns
+            .split(',')
+            .filter((col) => !!col.trim())
+            .map((col) => {
+                if (/^\d+$/.test(col.trim())) return parseInt(col.trim(), 10) || 1;
+                return col.trim();
+            });
+    else value = parseInt(columns, 10) || 1;
+
+    return { value, count: Array.isArray(value) ? value.length : value };
+};

package/src/components/Grid/index.tsx

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

package/src/components/InlineAlert/InlineAlert.tsx

@@ -35,7 +35,7 @@ export type InlineAlertProps = CommonProps<'owner'> & {
  *     <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
  *
  * @name InlineAlert
- * @phase UXReview
+ * @phase Stable
  */
 export function InlineAlert({ children, variant = 'informational', id, owner }: InlineAlertProps) {
     return (

package/src/components/Input/Input.tsx

@@ -13,23 +13,19 @@ export type InputProps = Omit<InputElementProps, 'ariaDescribedBy' | 'ariaErrorM
  * @example
  *     import { useState } from 'react';
  *     import { Input } from '@bspk/ui/Input';
- *     import { Field, FieldLabel } from '@bspk/ui/Field';
+ *     import { Field, FieldLabel, FieldDescription } from '@bspk/ui/Field';
  *
  *     () => {
- *         const [value, setValue] = useState('');
+ *         const [fieldDate, setFieldDate] = useState<string>();
  *
  *         return (
- *             <>
- *                 // standalone input example
- *                 <Input aria-label="Example Input" name="example-name" onChange={setValue} value={value} />
- *                 <br />
- *                 // input used within a field
+ *             <div style={{ width: 320 }}>
  *                 <Field>
  *                     <FieldLabel>Example Label</FieldLabel>
- *                     <Input name="example-name" onChange={setValue} value={value} />
+ *                     <Input name="example-name" onChange={setFieldDate} value={fieldDate} />
  *                     <FieldDescription>This is an example input field.</FieldDescription>
  *                 </Field>
- *             </>
+ *             </div>
  *         );
  *     };
  *

package/src/components/Input/InputElement.tsx

@@ -1,6 +1,6 @@
 import './input.scss';
 import { SvgCancel } from '@bspk/icons/Cancel';
-import { HTMLInputTypeAttribute, ReactNode, useMemo, useRef, useState } from 'react';
+import { HTMLInputTypeAttribute, ReactNode, useMemo, useRef } from 'react';
 import { Button } from '-/components/Button';
 import { FieldContextProps } from '-/components/Field';
 import { useTimeout } from '-/hooks/useTimeout';
@@ -112,11 +112,9 @@ export function InputElement({
     ariaErrorMessage,
     ...props
 }: ElementProps<InputElementProps, 'div'>) {
-    const [focused, setFocused] = useState(false);
-
     const showClearButton = useMemo(
-        () => !!(showClearButtonProp !== false && !readOnly && !disabled && value?.toString().length && focused),
-        [showClearButtonProp, readOnly, disabled, value, focused],
+        () => showClearButtonProp !== false && !readOnly && !disabled && !!value?.toString().length,
+        [showClearButtonProp, readOnly, disabled, value],
     );
 
     const inputRefInternal = useRef<HTMLInputElement | null>(null);
@@ -150,14 +148,12 @@ export function InputElement({
                 id={id}
                 name={name}
                 onBlur={(event) => {
-                    focusTimeout.set(() => setFocused(false), 750);
                     inputProps?.onBlur?.(event);
                 }}
                 onChange={(event) => {
                     onChange(event.target.value, event);
                 }}
                 onFocus={(event) => {
-                    focusTimeout.set(() => setFocused(true), 0);
                     inputProps?.onFocus?.(event);
                 }}
                 placeholder={placeholder || ' '}
@@ -174,6 +170,7 @@ export function InputElement({
             {trailing && <span data-trailing>{trailing}</span>}
             {showClearButton && (
                 <Button
+                    data-clear-button
                     icon={<SvgCancel />}
                     iconOnly
                     label="Clear"

package/src/components/Input/InputExample.tsx

@@ -1,9 +1,12 @@
-import { InputProps } from '.';
+import { useState } from 'react';
+import { Input, InputProps } from '.';
+import { Field, FieldLabel, FieldDescription } from '-/components/Field';
 import { ComponentExample } from '-/utils/demo';
 
 export type InputExampleProps = InputProps & { label: string; description?: string };
 
 export const InputExample: ComponentExample<InputExampleProps> = {
+    containerStyle: { width: 320, padding: 0 },
     defaultState: {
         label: 'Property Description',
         'aria-label': 'input aria-label',
@@ -55,4 +58,19 @@ export const InputExample: ComponentExample<InputExampleProps> = {
     variants: {
         type: false,
     },
+    sections: [],
+};
+
+export const Usage = () => {
+    const [fieldDate, setFieldDate] = useState<string>();
+
+    return (
+        <div style={{ width: 320 }}>
+            <Field>
+                <FieldLabel>Example Label</FieldLabel>
+                <Input name="example-name" onChange={setFieldDate} value={fieldDate} />
+                <FieldDescription>This is an example input field.</FieldDescription>
+            </Field>
+        </div>
+    );
 };

package/src/components/Input/input.scss

@@ -3,6 +3,8 @@
 
     display: flex;
     flex-flow: row nowrap;
+    justify-content: center;
+    align-items: center;
     background-color: var(--surface-neutral-t1-base);
     border: solid 1px var(--border-color);
     height: var(--field-height);
@@ -11,7 +13,7 @@
     gap: var(--spacing-sizing-01);
     width: 100%;
 
-    &[data-show-clear-button] {
+    &[data-show-clear-button]:focus-within {
         padding-right: 0;
     }
 
@@ -62,6 +64,12 @@
         --border-color: var(--status-error);
     }
 
+    &:not(:focus-within) {
+        [data-clear-button] {
+            display: none;
+        }
+    }
+
     &:focus-within {
         --border-color: var(--stroke-neutral-focus);
 

package/src/components/InputField/InputField.tsx

@@ -9,7 +9,7 @@ export type InputFieldProps = FormFieldControlProps<InputProps>;
  * This component takes properties from the FormField and Input components.
  *
  * @name InputField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/InputNumber/InputNumber.tsx

@@ -54,37 +54,28 @@ export type InputNumberProps = CommonProps<'size'> &
  *     import { InputNumber } from '@bspk/ui/InputNumber';
  *
  *     () => {
- *         const [state, setState] = useState<number | undefined>();
+ *         const [value, setValue] = useState<number | undefined>();
  *
  *         return (
- *             <>
- *                 // standalone input number example
- *                 <InputNumber
- *                     aria-label="Example aria-label"
- *                     name="example-name"
- *                     onChange={(nextValue) => setState(nextValue)}
- *                     value={state}
- *                 />
- *                 <br />
- *                 // input number used within a field
+ *             <div style={{ width: 320 }}>
  *                 <Field>
  *                     <FieldLabel>Example Input Number</FieldLabel>
  *                     <InputNumber
  *                         aria-label="Example aria-label"
  *                         name="example-name"
- *                         onChange={(nextValue) => setState(nextValue)}
- *                         value={state}
+ *                         onChange={(nextValue) => setValue(nextValue)}
+ *                         value={value}
  *                     />
  *                     <FieldDescription>
  *                         The input number allows you to increment or decrement a value.
  *                     </FieldDescription>
  *                 </Field>
- *             </>
+ *             </div>
  *         );
  *     };
  *
  * @name InputNumber
- * @phase UXReview
+ * @phase Stable
  */
 export function InputNumber({
     value: valueProp,

package/src/components/InputNumber/InputNumberExample.tsx

@@ -1,4 +1,6 @@
-import { InputNumberProps } from './InputNumber';
+import { useState } from 'react';
+import { InputNumber, InputNumberProps } from './InputNumber';
+import { Field, FieldLabel, FieldDescription } from '-/components/Field';
 import { ComponentExample } from '-/utils/demo';
 
 export const InputNumberExample: ComponentExample<InputNumberProps> = {
@@ -7,4 +9,25 @@ export const InputNumberExample: ComponentExample<InputNumberProps> = {
     },
     render: ({ props, Component }) => <Component {...props} />,
     variants: false,
+    sections: [],
+    containerStyle: { width: 320, padding: 0 },
+};
+
+export const Usage = () => {
+    const [value, setValue] = useState<number | undefined>();
+
+    return (
+        <div style={{ width: 320 }}>
+            <Field>
+                <FieldLabel>Example Input Number</FieldLabel>
+                <InputNumber
+                    aria-label="Example aria-label"
+                    name="example-name"
+                    onChange={(nextValue) => setValue(nextValue)}
+                    value={value}
+                />
+                <FieldDescription>The input number allows you to increment or decrement a value.</FieldDescription>
+            </Field>
+        </div>
+    );
 };

package/src/components/InputNumberField/InputNumberField.tsx

@@ -9,7 +9,7 @@ export type InputNumberFieldProps = FormFieldControlProps<InputNumberProps>;
  * This component takes properties from the FormField and InputNumber components.
  *
  * @name InputNumberField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/InputPhone/InputPhone.tsx

@@ -10,13 +10,13 @@ import { Menu } from '-/components/Menu';
 import { useArrowNavigation } from '-/hooks/useArrowNavigation';
 import { useFloating } from '-/hooks/useFloating';
 import { useOutsideClick } from '-/hooks/useOutsideClick';
-import { useUIContext } from '-/hooks/useUIContext';
 import { FieldControlProps } from '-/types/common';
 import { countryCodeData, countryCodes, SupportedCountryCode } from '-/utils/countryCodes';
 import { getElementById } from '-/utils/dom';
 import { guessUserCountryCode } from '-/utils/guessUserCountryCode';
 import { handleKeyDown } from '-/utils/handleKeyDown';
 import { scrollListItemsStyle, ScrollListItemsStyleProps } from '-/utils/scrollListItemsStyle';
+import { sendAriaLiveMessage } from '-/utils/sendAriaLiveMessage';
 import { useIds } from '-/utils/useIds';
 
 const SELECT_OPTIONS = countryCodes.map((code) => {
@@ -58,34 +58,32 @@ export type InputPhoneProps = FieldControlProps<string, SupportedCountryCode> &
  *
  * @example
  *     import { InputPhone } from '@bspk/ui/InputPhone';
+ *     import { Field, FieldDescription, FieldLabel } from '@bspk/ui/Field';
  *
  *     () => {
- *         const [value, onChange] = useState<number | undefined>();
+ *         const [value, onChange] = useState<string | undefined>();
  *
  *         return (
- *             <>
- *                 // standalone input phone example
- *                 <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
- *                 <br />
- *                 // input phone used within a field
+ *             <div style={{ width: 320 }}>
  *                 <Field>
  *                     <FieldLabel>Example Input Phone</FieldLabel>
  *                     <InputPhone
  *                         aria-label="Phone Number"
  *                         initialCountryCode="US"
- *                         value={value}
+ *                         name="example-name"
  *                         onChange={onChange}
+ *                         value={value}
  *                     />
  *                     <FieldDescription>
  *                         The phone input allows you to enter a phone number with country code.
  *                     </FieldDescription>
  *                 </Field>
- *             </>
+ *             </div>
  *         );
  *     };
  *
  * @name InputPhone
- * @phase UXReview
+ * @phase Stable
  */
 export function InputPhone({
     value,
@@ -155,19 +153,17 @@ export function InputPhone({
     }, [countryCode]);
 
     const handleChange = (newValue: string) => {
-        let rawNumber = newValue.replace(/\D/g, '');
-        if (rawNumber === value) return;
+        const numericChange = value?.replace(/\D/g, '') !== newValue?.replace(/\D/g, '');
 
-        if (!disableFormatting) {
+        // only format if the numeric value has changed
+        if (!disableFormatting && numericChange) {
             const formatter = new AsYouType(countryCode);
-            rawNumber = formatter.input(`${rawNumber}`);
+            newValue = formatter.input(`${newValue}`);
         }
 
-        onChange(rawNumber, countryCode);
+        onChange(newValue, countryCode);
     };
 
-    const { sendAriaLiveMessage } = useUIContext();
-
     return (
         <>
             <div
@@ -186,6 +182,7 @@ export function InputPhone({
                     containerRef={elements.setReference}
                     disabled={disabled}
                     id={id}
+                    inputMode="tel"
                     inputRef={(node) => {
                         inputRef?.(node);
                         inputInternalRef.current = node;
@@ -239,6 +236,10 @@ export function InputPhone({
                     }
                     name={name}
                     onChange={handleChange}
+                    onKeyDown={(event) => {
+                        // ignore non numeric keys
+                        if (event.key.length === 1 && !/[0-9]/.test(event.key)) event.preventDefault();
+                    }}
                     owner="input-phone"
                     readOnly={readOnly}
                     required={required}

package/src/components/InputPhone/InputPhoneExample.tsx

@@ -1,12 +1,37 @@
-import { InputPhoneProps } from '.';
-import { ComponentExample, Preset } from '-/utils/demo';
+import { useState } from 'react';
+import { InputPhone, InputPhoneProps } from '.';
+import { Field, FieldDescription, FieldLabel } from '-/components/Field';
+import { Preset, ComponentExample } from '-/utils/demo';
 
 export const presets: Preset<InputPhoneProps>[] = [];
 
 export const InputPhoneExample: ComponentExample<InputPhoneProps> = {
+    containerStyle: { width: 320, padding: 0 },
     defaultState: {
         'aria-label': 'input phone aria-label',
     },
     render: ({ props, Component }) => <Component {...props} />,
     variants: true,
 };
+
+export const Usage = () => {
+    const [value, onChange] = useState<string | undefined>();
+
+    return (
+        <div style={{ width: 320 }}>
+            <Field>
+                <FieldLabel>Example Input Phone</FieldLabel>
+                <InputPhone
+                    aria-label="Phone Number"
+                    initialCountryCode="US"
+                    name="example-name"
+                    onChange={onChange}
+                    value={value}
+                />
+                <FieldDescription>
+                    The phone input allows you to enter a phone number with country code.
+                </FieldDescription>
+            </Field>
+        </div>
+    );
+};

package/src/components/InputPhoneField/InputPhoneField.tsx

@@ -9,7 +9,7 @@ export type InputPhoneFieldProps = FormFieldControlProps<InputPhoneProps>;
  * This component takes properties from the FormField and InputPhone components.
  *
  * @name InputPhoneField
- * @phase UXReview
+ * @phase Stable
  *
  * @generated
  */

package/src/components/Link/Link.tsx

@@ -49,7 +49,7 @@ export type LinkProps = Pick<CommonPropsLibrary, 'disabled'> & {
  *     <Link href="https://anywhere.re" label="Example label" trailingIcon="external" />;
  *
  * @name Link
- * @phase UXReview
+ * @phase Stable
  */
 export function Link({ label, trailingIcon, size, variant, target = '_self', ...props }: ElementProps<LinkProps, 'a'>) {
     let LazyIcon: LazyExoticComponent<ComponentType<unknown>> | undefined = undefined;

package/src/components/ListItem/ListItem.tsx

@@ -133,7 +133,7 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<'a
  *     </div>;
  *
  * @name ListItem
- * @phase UXReview
+ * @phase Stable
  */
 function ListItem<As extends ElementType = ElementType>({
     active,

package/src/components/Menu/Menu.tsx

@@ -42,8 +42,6 @@ export type MenuProps<As extends ElementType = ElementType> = CommonProps<'id' |
  * A container housing a simple list of options presented to the customer to select one option at a time.
  *
  * @example
- *     import React from 'react';
- *
  *     import { Menu } from '@bspk/ui/Menu';
  *
  *     <Menu>
@@ -53,7 +51,7 @@ export type MenuProps<As extends ElementType = ElementType> = CommonProps<'id' |
  *     </Menu>;
  *
  * @name Menu
- * @phase UXReview
+ * @phase Stable
  */
 export function Menu({ as, innerRef, id: idProp, children, owner, label, ...props }: ElementProps<MenuProps, 'div'>) {
     const menuId = useId(idProp);

package/src/components/Modal/Modal.tsx

@@ -4,8 +4,8 @@ import { ReactNode, useMemo, useRef } from 'react';
 import { Button, ButtonProps } from '-/components/Button';
 import { DialogProps, Dialog } from '-/components/Dialog';
 import { Txt } from '-/components/Txt';
-import { useEventListener } from '-/hooks/useAddEventListener';
 import { useDebounceCallback } from '-/hooks/useDebounceCallback';
+import { useEventListener } from '-/hooks/useEventListener';
 import { useUIContext } from '-/hooks/useUIContext';
 import { CallToActionButton } from '-/types/common';
 
@@ -109,8 +109,6 @@ export type ModalProps = Pick<
  * footer for the dialog.
  *
  * @example
- *     import React from 'react';
- *
  *     import { Button } from '@bspk/ui/Button';
  *     import { Modal } from '@bspk/ui/Modal';
  *
@@ -133,7 +131,7 @@ export type ModalProps = Pick<
  *     };
  *
  * @name Modal
- * @phase UXReview
+ * @phase Stable
  */
 export function Modal({
     header,

package/src/components/OTPInput/OTPInput.tsx

@@ -46,7 +46,7 @@ export type OTPInputProps = CommonProps<'aria-label' | 'id' | 'invalid' | 'name'
  *     };
  *
  * @name OTPInput
- * @phase UXReview
+ * @phase Stable
  */
 export function OTPInput({
     value: valueProp,

package/src/components/OTPInput/OTPInputExample.tsx

@@ -21,7 +21,6 @@ export const presets: Preset<OTPInputProps>[] = [
 ];
 
 export const OTPInputExample: ComponentExample<OTPInputProps> = {
-    containerStyle: { width: '100%' },
     defaultState: {
         value: '',
         length: 6,

package/src/components/PageControl/PageControl.tsx

@@ -43,7 +43,7 @@ export type DotSize = 'medium' | 'small' | 'x-small';
  *     <PageControl value={1} numPages={3} />;
  *
  * @name PageControl
- * @phase UXReview
+ * @phase Stable
  */
 export function PageControl({ currentPage: currentProp, numPages: numPagesProp, variant = 'flat' }: PageControlProps) {
     const numPages = Number(numPagesProp);

package/src/components/PageControl/PageControlExample.tsx

@@ -26,7 +26,6 @@ export const presets: Preset<PageControlProps>[] = [
 ];
 
 export const PageControlExample: ComponentExample<PageControlProps> = {
-    containerStyle: { width: '100%' },
     defaultState: {},
     disableProps: [],
     presets,