@bspk/ui 1.3.10 → 1.3.16

package/src/components/ExamplePlaceholder/ExamplePlaceholder.tsx

@@ -1,4 +1,4 @@
-import { useRef } from 'react';
+import { ReactNode } from 'react';
 
 import { Txt } from '-/components/Txt';
 import { ElementProps } from '-/types/common';
@@ -6,12 +6,6 @@ import { ElementProps } from '-/types/common';
 const dimension = (value: number | string) => (typeof value === 'number' ? `${value}px` : `${value}`);
 
 export type ExamplePlaceholderProps = {
-    /**
-     * Whether to hide the size text.
-     *
-     * @default false
-     */
-    hideSize?: boolean;
     /**
      * The height of the placeholder.
      *
@@ -26,12 +20,10 @@ export type ExamplePlaceholderProps = {
      * @type string
      */
     width?: number | string;
-    /**
-     * The direction of the placeholder.
-     *
-     * @default 'row'
-     */
-    direction?: 'column' | 'row';
+    /** An optional label for the placeholder. */
+    label?: string;
+    /** Optional children to display inside the placeholder instead of the label. */
+    children?: ReactNode;
 };
 
 /**
@@ -41,28 +33,31 @@ export type ExamplePlaceholderProps = {
  * @phase Utility
  */
 export function ExamplePlaceholder({
-    hideSize = false,
     height = 100,
     width = '100%',
-    direction = 'row',
+    label,
+    children,
     ...props
 }: ElementProps<ExamplePlaceholderProps, 'div'>) {
-    const ref = useRef<HTMLDivElement | null>(null);
-
     return (
         <div
             {...props}
             data-bspk-utility="example-placeholder"
-            data-example-placeholder
-            ref={ref}
             style={{
-                ...props.style,
+                flexDirection: 'column',
+                gap: 'var(--spacing-sizing-01)',
                 width: dimension(width),
                 height: dimension(height),
-                flexDirection: direction,
+                background: 'var(--surface-neutral-t3-low)',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                textAlign: 'center',
+                font: 'var(--body-x-small)',
+                ...props.style,
             }}
         >
-            {!hideSize && (
+            {children || label || (
                 <>
                     <Txt variant="labels-large">{dimension(width)}</Txt>
                     <Txt>&times;</Txt>

package/src/components/Fab/Fab.tsx

@@ -10,7 +10,7 @@ export type FabVariant = 'neutral' | 'primary' | 'secondary';
 
 export type FabProps<As extends ElementType = ElementType> = Pick<
     ButtonProps<As>,
-    'as' | 'icon' | 'iconOnly' | 'innerRef' | 'onClick' | 'toolTip'
+    'aria-label' | 'as' | 'icon' | 'iconOnly' | 'innerRef' | 'onClick' | 'tooltip'
 > &
     Required<Pick<ButtonProps<As>, 'label'>> & {
         /**
@@ -47,13 +47,16 @@ export type FabProps<As extends ElementType = ElementType> = Pick<
  *     import { SvgBolt } from '@bspk/icons/Bolt';
  *     import { Fab } from '@bspk/ui/Fab';
  *
- *     <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
+ *     <div style={{ width: '100%', height: 100 }}>
+ *         <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />
+ *     </div>;
  *
  * @name Fab
- * @phase UXReview
+ * @phase Stable
  */
 export function Fab<As extends ElementType = ElementType>(props: AriaAttributes & ElementProps<FabProps<As>, As>) {
     const {
+        'aria-label': ariaLabel,
         size = 'small',
         variant = 'primary',
         iconOnly: iconOnlyProp = false,
@@ -62,7 +65,7 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
         container = 'local',
         label,
         icon,
-        toolTip,
+        tooltip,
         innerRef,
         ...otherProps
     } = props;
@@ -74,7 +77,7 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
         <As
             {...otherProps}
             {...triggerProps}
-            aria-label={label}
+            aria-label={ariaLabel || label}
             data-bspk="fab"
             data-container={container}
             data-placement={placement}
@@ -109,9 +112,9 @@ export function Fab<As extends ElementType = ElementType>(props: AriaAttributes
         </As>
     );
 
-    if (toolTip || iconOnly)
+    if (tooltip || iconOnly)
         return (
-            <Tooltip label={toolTip || label} placement="top">
+            <Tooltip label={tooltip || label} placement="top">
                 {button}
             </Tooltip>
         );

package/src/components/Fab/FabExample.tsx

@@ -1,4 +1,5 @@
-import { FabProps } from './Fab';
+import { SvgBolt } from '@bspk/icons/Bolt';
+import { Fab, FabProps } from './Fab';
 import { ButtonExample } from '-/components/Button/ButtonExample';
 import { ComponentExample } from '-/utils/demo';
 
@@ -27,3 +28,11 @@ export const FabExample: ComponentExample<FabProps> = {
         },
     },
 };
+
+export const Usage = () => {
+    return (
+        <div style={{ width: '100%', height: 100 }}>
+            <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />
+        </div>
+    );
+};

package/src/components/FileUpload/FileUpload.tsx

@@ -90,7 +90,7 @@ export type FileUploadProps = Pick<FileUploadItemProps, 'cancelButtonLabel' | 'o
  *     };
  *
  * @name FileUpload
- * @phase UXReview
+ * @phase Stable
  */
 export function FileUpload({
     dragAndDrop = false,

package/src/components/FileUploadItem/FileUploadItem.tsx

@@ -38,7 +38,7 @@ export type FileUploadItemProps = FileEntry & {
  *     />;
  *
  * @name FileUploadItem
- * @phase UXReview
+ * @phase Stable
  */
 export function FileUploadItem({
     fileName = '',

package/src/components/{Layout/Layout.rtl.test.tsx → Flex/Flex.rtl.test.tsx}

@@ -1,10 +1,10 @@
-import { Layout } from './Layout';
+import { Flex } from './Flex';
 import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
-const TestBed = () => <Layout>Example layout</Layout>;
+const TestBed = () => <Flex>Example layout</Flex>;
 
-describe('Layout (RTL)', () => {
+describe('Flex (RTL)', () => {
     it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
 
     it('renders', () => {

package/src/components/Flex/Flex.tsx

@@ -0,0 +1,100 @@
+import { CSSProperties, ElementType, ReactNode } from 'react';
+import { ElementProps } from '-/types/common';
+import { SizingPixels, numToSizingVar } from '-/utils/sizing';
+
+export type FlexProps<As extends ElementType = ElementType> = {
+    /**
+     * The content of the Flex.
+     *
+     * @required
+     */
+    children?: ReactNode;
+    /** The gap between the children. */
+    gap?: SizingPixels | 'auto';
+    /**
+     * The element type to render as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+    /**
+     * The align-items style to apply to the Flex.
+     *
+     * @default flex-start
+     */
+    align?: CSSProperties['alignItems'] | 'end' | 'start';
+    /**
+     * The justification style to apply to the Flex.
+     *
+     * @default flex-start
+     */
+    justify?: CSSProperties['justifyContent'];
+    /** The flex-wrap style to apply to the Flex. */
+    wrap?: CSSProperties['flexWrap'];
+    /** The flex-direction style to apply to the Flex. */
+    direction?: 'column-reverse' | 'column' | 'row-reverse' | 'row';
+    /** The padding to apply to the Flex. */
+    padding?: SizingPixels | SizingPixels[];
+};
+
+/**
+ * Utility component used within other components for layout purposes.
+ *
+ * @example
+ *     import { Flex } from '@bspk/ui/Flex';
+ *
+ *     <Flex gap="24" justify="center" style={{ width: '100%' }}>
+ *         <div>Alpha</div>
+ *         <div>Beta</div>
+ *         <div>Gamma</div>
+ *     </Flex>;
+ *
+ * @name Flex
+ * @phase Utility
+ */
+export function Flex<As extends ElementType = ElementType>({
+    children,
+    gap,
+    style,
+    as,
+    align = 'flex-start',
+    justify = 'flex-start',
+    wrap,
+    direction = 'row',
+    padding,
+    ...props
+}: ElementProps<FlexProps<As>, As>) {
+    const As: ElementType = as || 'div';
+
+    const alignItems = align === 'start' ? 'flex-start' : align === 'end' ? 'flex-end' : align;
+
+    const paddingValue = getPaddingValue(padding);
+
+    return (
+        <As
+            {...props}
+            data-bspk-utility="flex"
+            style={{
+                display: 'flex',
+                flexDirection: direction,
+                gap: numToSizingVar(gap),
+                alignItems,
+                justifyContent: justify || 'flex-start',
+                flexWrap: wrap ? 'wrap' : 'nowrap',
+                padding: paddingValue,
+                ...style,
+            }}
+        >
+            {children}
+        </As>
+    );
+}
+
+function getPaddingValue(padding?: SizingPixels | SizingPixels[]): string | undefined {
+    if (!padding) return undefined;
+
+    return (!Array.isArray(padding) ? [padding] : padding).map((p) => numToSizingVar(p)).join(' ');
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Flex/FlexExample.tsx

@@ -0,0 +1,27 @@
+import { Flex, FlexProps } from './Flex';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<FlexProps>[] = [];
+
+export const FlexExample: ComponentExample<FlexProps> = {
+    render: ({ props, Component }) => {
+        return (
+            <Component {...props}>
+                <div>Alpha</div>
+                <div>Beta</div>
+                <div>Gamma</div>
+            </Component>
+        );
+    },
+    presets,
+};
+
+export const Usage = () => {
+    return (
+        <Flex gap="24" justify="center" style={{ width: '100%' }}>
+            <div>Alpha</div>
+            <div>Beta</div>
+            <div>Gamma</div>
+        </Flex>
+    );
+};

package/src/components/Flex/index.tsx

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

package/src/components/FormField/FormFieldExample.tsx

@@ -25,7 +25,6 @@ export const presets: Preset<Partial<ExampleProps>>[] = [
 ];
 
 export const FormFieldExample: ComponentExample<ExampleProps> = {
-    containerStyle: { width: '100%' },
     defaultState: {},
     disableProps: [],
     presets: presets as Preset<ExampleProps>[],
@@ -184,7 +183,7 @@ export function FormFieldExampleRender({ ...props }: ExampleProps & { syntax?: S
                         onChange={(next) => setValue({ 'date-picker': next })}
                         placeholder="Example input"
                         required={required}
-                        value={value['date-picker'] as Date}
+                        value={value['date-picker'] as string}
                     />
                 </FormField>
                 <FormField {...props} {...internalProps('Input')}>

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
  */