@bspk/ui 1.1.34 → 1.2.0

package/src/hooks/useTimeout.ts

@@ -1,5 +1,11 @@
 import { useRef, useEffect, useMemo } from 'react';
 
+type TimeoutHook = {
+    clear: () => void;
+    set: (callback: () => void, ms?: number) => void;
+    ref: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+};
+
 /**
  * A hook that creates a timeout that is automatically cleared when the component is unmounted.
  *
@@ -19,11 +25,15 @@ import { useRef, useEffect, useMemo } from 'react';
  *
  * @returns A ref object that can be used to store a timeout id.
  */
-export function useTimeout() {
+export function useTimeout(): TimeoutHook;
+export function useTimeout(initialCallback: () => void, durationMs: number): TimeoutHook;
+export function useTimeout(initialCallback?: () => void, durationMs = 1000): TimeoutHook {
     const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
     useEffect(() => {
         if (timeoutRef.current) clearTimeout(timeoutRef.current);
+        if (initialCallback) timeoutRef.current = setTimeout(initialCallback, durationMs);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- only run at mount
     }, []);
 
     return useMemo(
@@ -31,13 +41,13 @@ export function useTimeout() {
             clear: () => {
                 if (timeoutRef.current) clearTimeout(timeoutRef.current);
             },
-            set: (callback: () => void, durationMs: number) => {
+            set: (callback: () => void, ms = durationMs) => {
                 if (timeoutRef.current) clearTimeout(timeoutRef.current);
-                timeoutRef.current = setTimeout(callback, durationMs);
+                timeoutRef.current = setTimeout(callback, ms);
             },
             ref: timeoutRef,
         }),
-        [],
+        [durationMs],
     );
 }
 

package/src/{base.scss → styles/base.scss}

@@ -22,6 +22,7 @@
 }
 
 :root {
+    --z-index-focus: 9999;
     --z-index-tooltip-popover: 1100;
     --z-index-dialog: 1000;
     --z-index-dropdown: 1000;
@@ -58,7 +59,7 @@ body[data-bspk] {
     color: var(--foreground-neutral-on-surface);
     min-width: 343px;
 
-    a {
+    a:not([data-bspk='button'], [data-bspk='list-item']) {
         color: var(--foreground-link-text-default);
 
         &:not([disabled]) {
@@ -167,15 +168,11 @@ body[data-bspk] {
 }
 
 [data-sr-only] {
-    position: absolute;
-    width: 1px;
     height: 1px;
-    padding: 0;
-    margin: -1px;
     overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border-width: 0;
+    position: absolute !important;
+    width: 1px;
+    clip: rect(1px, 1px, 1px, 1px);
 }
 
 [data-touch-target] ~ * {
@@ -273,4 +270,23 @@ body[data-bspk] {
     }
 }
 
+[data-attachment-wrapper] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    position: relative;
+    width: fit-content;
+    height: fit-content;
+    flex-shrink: 0;
+
+    [data-attachment] {
+        position: absolute;
+        top: 0;
+        right: 0;
+        transform: scale(1) translate(50%, -50%);
+        transform-origin: 100% 0%;
+        z-index: 2;
+    }
+}
+
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/{index.ts → types/common.ts}

@@ -8,50 +8,6 @@
 
 import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef } from 'react';
 
-export const BRANDS: {
-    /** The title of the brand. */
-    title: string;
-    /** The slug of the brand, used in URLs and identifiers. */
-    slug: Brand;
-}[] = [
-    {
-        title: 'Anywhere',
-        slug: 'anywhere',
-    },
-    {
-        title: 'Better Homes & Gardens',
-        slug: 'better-homes-gardens',
-    },
-    {
-        title: 'Cartus',
-        slug: 'cartus',
-    },
-    {
-        title: 'Century 21',
-        slug: 'century-21',
-    },
-    {
-        title: 'Coldwell Banker',
-        slug: 'coldwell-banker',
-    },
-    {
-        title: 'Corcoran',
-        slug: 'corcoran',
-    },
-    {
-        title: 'Denali Boss',
-        slug: 'denali-boss',
-    },
-    {
-        title: 'ERA',
-        slug: 'era',
-    },
-    {
-        title: "Sotheby's",
-        slug: 'sothebys',
-    },
-] as const;
-
 export type AlertVariant = 'error' | 'informational' | 'success' | 'warning';
 
 export type SetRef<T> = (instance: T | null) => void;
@@ -67,6 +23,8 @@ export type ElementConstructorProps<
     O extends string = '',
 > = Omit<ComponentPropsWithoutRef<E>, O>;
 
+export type DataProps = Record<`data-${string}`, string>;
+
 export type ButtonSize = 'large' | 'medium' | 'small' | 'x-small';
 
 export type CallToActionButton = {
@@ -86,12 +44,7 @@ export type CallToActionButton = {
     size?: ButtonSize;
 };
 
-/**
- * The props that are common to input elements.
- *
- * If an element is invalid it must have an errorMessage.
- */
-export type InvalidPropsLibrary = {
+export type CommonPropsLibrary = {
     /**
      * Marks the element as invalid and displays error state theme.
      *
@@ -100,17 +53,6 @@ export type InvalidPropsLibrary = {
      * @default false
      */
     invalid?: boolean;
-    /**
-     * Marks the element as invalid and displays error message.
-     *
-     * When an element is invalid it must display an error message explaining why it is invalid.
-     */
-    errorMessage?: string;
-};
-
-export type InvalidProps<K extends keyof InvalidPropsLibrary> = Pick<InvalidPropsLibrary, K>;
-
-export type CommonPropsLibrary = {
     /** The id of the element. If not provided one will be generated. */
     id?: string;
     /**
@@ -171,12 +113,23 @@ export type CommonPropsLibrary = {
      * This is a utility attribute used to identify the owning component of another component.
      *
      * This is used to identify the component in the UI library and is not intended for public use.
+     *
+     * @utility
      */
-    'data-bspk-owner'?: string;
+    owner?: string;
 };
 
 export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;
 
+export type RequiredCommonProps<K extends keyof CommonPropsLibrary> = Required<Pick<CommonPropsLibrary, K>>;
+
+export type FormFieldControlProps = {
+    /** The id of the control description. */
+    'aria-describedby'?: string;
+    /** The id of the error message */
+    'aria-errormessage'?: string;
+};
+
 export type Brand =
     | 'anywhere'
     | 'better-homes-gardens'

package/src/types/meta.ts

@@ -0,0 +1,109 @@
+/**
+ * This file is used to build the meta types for the project. It's used in the build-meta.ts file and also copied in to
+ * the meta output file.
+ */
+
+export const COMPONENT_PHASE_ORDER: ComponentPhase[] = [
+    'Utility', // Utility components are not tracked in the progress
+    //
+    'Backlog', // components that are not actively being worked on
+    'Dev', // components that are actively being developed
+    'QA', // components that are undergoing QA
+    'UXReview', // components that are in UX Review
+    'Stable', // production ready
+];
+
+export const COMPONENT_PHASES: Record<
+    ComponentPhase,
+    {
+        title: string;
+        id: ComponentPhase;
+        description: string;
+    }
+> = {
+    Backlog: {
+        title: 'Backlog',
+        id: 'Backlog',
+        description:
+            'The component has been initiated but is currently on hold. It awaits further development and is not actively being worked on at this time.',
+    },
+    Dev: {
+        title: 'Development',
+        id: 'Dev',
+        description:
+            'The component is actively under development. This phase includes the creation of visual elements and integration tests to ensure comprehensive functionality.',
+    },
+    QA: {
+        title: 'Quality Assurance',
+        id: 'QA',
+        description:
+            'The component is being carefully evaluated by our Bespoke Engineering team. They are ensuring that it aligns with our high standards of functionality and performance.',
+    },
+    UXReview: {
+        title: 'UX Review',
+        id: 'UXReview',
+        description:
+            'The component is being carefully evaluated by our Bespoke UX team. They are ensuring that it aligns with our high standards of aesthetics and user experience and is accessible to all users.',
+    },
+    Stable: {
+        title: 'Stable',
+        id: 'Stable',
+        description:
+            'The component has successfully passed all reviews and is ready for use. It is now officially released and ready for use in a production environment.',
+    },
+    Utility: {
+        title: 'Utility',
+        id: 'Utility',
+        description: "The component progress isn't tracked as it's a utility component.",
+    },
+};
+
+export type BaseMeta = {
+    name: string;
+    description?: string;
+    file: string;
+    example?: string;
+};
+
+export type TypeMeta = BaseMeta & {
+    id: string;
+    references?: string[];
+    properties?: TypeProperty[];
+    components?: string[];
+};
+
+export type TypeProperty = {
+    name: string;
+    description?: string;
+    type?: string[] | string;
+    exampleType?: string;
+    default?: unknown;
+    required?: boolean;
+    options?: number[] | string[];
+    variants?: string[];
+    references?: string[];
+    minimum?: number;
+    maximum?: number;
+    example?: string;
+};
+
+export type ComponentMeta = BaseMeta & {
+    slug: string;
+    dependencies: string[];
+    css: string;
+    hasTouchTarget: boolean;
+    usage?: {
+        code: string;
+        description?: string;
+    };
+    phase: ComponentPhase;
+};
+
+export type UtilityMeta = BaseMeta & {
+    param?: string;
+    returns?: string;
+};
+
+export type ComponentPhase = 'Backlog' | 'Dev' | 'QA' | 'Stable' | 'Utility' | 'UXReview';
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/bound.ts

@@ -0,0 +1,30 @@
+/**
+ * A utility function to bound a number within a specified range. Allows for rollover behavior.
+ *
+ * @param params
+ * @param params.num The number to bound, can be a number, string, or undefined
+ * @param params.max The maximum value the number can be
+ * @param params.min The minimum value the number can be
+ * @param params.rollover If true, the number will wrap around when it exceeds the bounds
+ * @param params.defaultValue The default value to return if the input is invalid or undefined
+ * @returns The bounded number
+ */
+export function bound({
+    num,
+    max,
+    min,
+    rollover = false,
+    defaultValue = min,
+}: {
+    num: number | string | undefined;
+    max: number;
+    min: number;
+    rollover?: boolean;
+    defaultValue?: number;
+}): number {
+    const parsedNum = typeof num === 'number' ? num : parseInt(num as string, 10);
+    if (isNaN(parsedNum)) return defaultValue ?? min;
+    if (parsedNum > max) return rollover ? min : max;
+    if (parsedNum < min) return rollover ? max : min;
+    return parsedNum;
+}

package/src/utils/createExampleChildElement.tsx

@@ -0,0 +1,83 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */ import { SvgContentCopy } from '@bspk/icons/ContentCopy';
+import { SvgDiamond } from '@bspk/icons/Diamond';
+import { DemoAction, DemoSetState } from './demo';
+
+import { Avatar } from '-/components/Avatar';
+import { Checkbox } from '-/components/Checkbox';
+import { Img } from '-/components/Img';
+import { ListItem } from '-/components/ListItem';
+import { Radio } from '-/components/Radio';
+import { Switch } from '-/components/Switch';
+import { Tag } from '-/components/Tag';
+import { Txt } from '-/components/Txt';
+
+type ExampleChildElementProps = {
+    exampleState: Record<string, any>;
+    name: string;
+    setState: DemoSetState;
+    action: DemoAction;
+    id?: string;
+};
+
+/**
+ * Returns example leading and trailing components for use in component examples. Allows which type of element is
+ * rendered to be determined by the example state.
+ */
+export function createExampleChildElement({ exampleState, name, setState, action, id }: ExampleChildElementProps): {
+    element: JSX.Element | null;
+    componentName?: string;
+} {
+    const componentName = exampleState[name];
+
+    if (componentName === 'Checkbox' || componentName === 'Radio' || componentName === 'Switch') {
+        let As: typeof Checkbox | typeof Radio | typeof Switch = Checkbox;
+        if (componentName === 'Radio') As = Radio;
+        else if (componentName === 'Switch') As = Switch;
+
+        const toggleName = `data-${name}-toggle-${id}`;
+
+        return {
+            element: (
+                <As
+                    aria-label={`${componentName} demo`}
+                    checked={exampleState[toggleName]}
+                    disabled={exampleState.disabled}
+                    name={`${name}-toggle`}
+                    onChange={(checked: boolean) => {
+                        setState({ [toggleName]: checked });
+                    }}
+                    onClick={() => action(`${name} ${componentName} clicked`)}
+                    readOnly={exampleState.readOnly}
+                    value={`${name}-${componentName}`}
+                />
+            ),
+            componentName,
+        };
+    }
+
+    if (componentName === 'ListItemButton')
+        return {
+            element: (
+                <ListItem.Button
+                    icon={<SvgContentCopy />}
+                    label="LI Button"
+                    onClick={() => action('ListItem button clicked')}
+                />
+            ),
+            componentName,
+        };
+
+    if (componentName === 'Img') return { element: <Img alt="placeholder" src="/placeholder.svg" /> };
+
+    if (componentName === 'Avatar') return { element: <Avatar name="List Item" showTooltip={false} /> };
+
+    if (componentName === 'Tag') {
+        return { element: <Tag label="Tag" /> };
+    }
+
+    if (componentName === 'Txt') return { element: <Txt>Text</Txt> };
+
+    if (componentName === 'Icon') return { element: <SvgDiamond /> };
+
+    return { element: null };
+}

package/src/utils/demo.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { AlertVariant } from '-';
+import { AlertVariant } from '-/types/common';
+import { ComponentMeta } from '-/types/meta';
 
 export type TypeProperty = {
     name: string;
@@ -23,14 +24,6 @@ export type DemoSetState<Props = Record<string, unknown>> = (
     next: Partial<Props> | ((prev: Props) => Partial<Props>),
 ) => void;
 
-export type ComponentPhase =
-    | 'AccessibilityReview'
-    | 'Backlog'
-    | 'DesignReview'
-    | 'ProductionReady'
-    | 'Utility'
-    | 'WorkInProgress';
-
 export type TypePropertyDemo = Omit<TypeProperty, 'example'> & {
     libraryDefault?: TypeProperty['default'];
     label?: string;
@@ -50,9 +43,9 @@ export type ComponentExampleRenderProps<Props = Record<string, unknown>> = {
     preset?: DemoPreset;
     setState: DemoSetState<Props>;
     Component: React.ComponentType<Props>;
-    context?: {
-        [key: string]: unknown;
-        preset?: DemoPreset;
+    variant?: {
+        name: string;
+        value: unknown;
     };
     id: string;
 };
@@ -61,19 +54,28 @@ export type ComponentExampleRender<Props = Record<string, unknown>> = (
     params: ComponentExampleRenderProps<Props>,
 ) => React.ReactNode;
 
-export type ComponentExample<Props = Record<string, unknown>, PropName = keyof Props> = {
+type ComponentVariantOverride<Props> = {
+    [K in keyof Props]?: Props[K] | { options: Props[K][] };
+};
+
+export type ComponentVariantOverrides<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
+    [Key in PropName]?: ComponentVariantOverride<Props> | false | ((props: Props) => ComponentVariantOverride<Props>);
+};
+
+export type ComponentExample<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
     /**
      * The style of the wrapping component.
      *
-     * //
+     * @example
+     *     { width: '100%' },
      */
     containerStyle?: React.CSSProperties | ((propState: Props) => React.CSSProperties);
     /**
-     * True to hide all or a list of variants to hide.
+     * False to hide all or a record of variants to hide or modify props.
      *
-     * Helpful for hiding variants that can have unexpected collisions with the other examples.
+     * Helpful for hiding or setting static default props for specific variants
      */
-    hideVariants?: PropName[] | true;
+    variants?: ComponentVariantOverrides<Props> | boolean;
     /**
      * This is used to set the initial propState of the component.
      *
@@ -96,11 +98,17 @@ export type ComponentExample<Props = Record<string, unknown>, PropName = keyof P
     render?: ComponentExampleRender<Props>;
     /** We may not want certain props editable in the props table. */
     disableProps?: PropName[];
+    /** The sections of the example. */
+    sections?: {
+        title: string;
+        content: (params: { Component: React.ComponentType<Props>; props: Props }) => React.ReactNode;
+    }[];
 };
 
 export type ComponentExampleFn<Props = Record<string, unknown>> = (params: {
     setState: DemoSetState<Props>;
     action: DemoAction;
+    componentsMeta: ComponentMeta[];
 }) => ComponentExample<Props>;
 
 export type Preset<Props> = {

package/src/utils/fileUploads.ts

@@ -0,0 +1,73 @@
+export const DEFAULT_ERROR_MESSAGE = 'There was an error uploading the file. Please try again.';
+
+export type FileUploadStatus = 'complete' | 'error' | 'failed' | 'idle' | 'uploading';
+
+export type FileEntry = {
+    /**
+     * The unique identifier for the file entry.
+     *
+     * This is generated client-side and should be unique for each file.
+     *
+     * This is useful for tracking the file during upload and handling cancellation.
+     *
+     * @required
+     */
+    id: string;
+    /** The name of the file. */
+    fileName: string;
+    /**
+     * The status of the uploading file.
+     *
+     * @default idle
+     */
+    status?: FileUploadStatus;
+    /**
+     * The size of the file being uploaded in MB.
+     *
+     * @required
+     */
+    fileSize: number;
+    /**
+     * A number between 0 and 100 representing the percentage of the upload completed.
+     *
+     * @default 0
+     * @minimum 0
+     * @maximum 100
+     */
+    progress?: number;
+    /**
+     * The error message to display when the upload fails.
+     *
+     * If status is 'error', this message will be displayed by default: "There was an error uploading the file. Please
+     * try again."
+     */
+    errorMessage?: string;
+};
+
+/**
+ * Common MIME types
+ *
+ * This list includes commonly used MIME types for various file formats.
+ *
+ * This is not an exhaustive list, but it covers many of the most frequently used types and can be extended as needed.
+ */
+export type MimeType =
+    | 'application/json'
+    | 'application/octet-stream'
+    | 'application/pdf'
+    | 'application/x-www-form-urlencoded'
+    | 'application/xml'
+    | 'application/zip'
+    | 'audio/mpeg'
+    | 'audio/wav'
+    | 'image/gif'
+    | 'image/jpeg'
+    | 'image/png'
+    | 'image/svg+xml'
+    | 'image/webp'
+    | 'text/css'
+    | 'text/html'
+    | 'text/javascript'
+    | 'text/plain'
+    | 'video/mp4'
+    | 'video/webm';

package/src/utils/handleKeyDown.ts

@@ -0,0 +1,24 @@
+import { KeyboardEventCode } from './keyboard';
+
+export type KeysCallback = Partial<Record<KeyboardEventCode, (event: React.KeyboardEvent) => void>>;
+
+/**
+ * Handles multiple keydown events with specific callbacks for each key.
+ *
+ * @param keysCallback - An object where keys are keyboard event codes and values are callback functions.
+ * @returns A function that can be used as an event handler for keydown events.
+ */
+export function handleKeyDown(
+    keysCallback: KeysCallback,
+    { stopPropagation = true, preventDefault = true }: { stopPropagation?: boolean; preventDefault?: boolean } = {},
+) {
+    return (event: React.KeyboardEvent) => {
+        const callback = keysCallback[event.code as KeyboardEventCode];
+        if (callback) {
+            callback(event);
+            if (stopPropagation) event.stopPropagation();
+            if (preventDefault) event.preventDefault();
+        }
+        return !!callback;
+    };
+}

package/src/utils/keyboard.ts

@@ -242,7 +242,7 @@ export type KeyboardEventCode =
     | 'Space'
     | 'Tab';
 
-export const EVENT_KEY: Record<KeyboardEventKey, KeyboardEventKey> = Object.freeze({
+export const EVENT_KEY: Record<KeyboardEventKey, KeyboardEventKey> = {
     Backspace: 'Backspace',
     Tab: 'Tab',
     Enter: 'Enter',
@@ -377,6 +377,6 @@ export const EVENT_KEY: Record<KeyboardEventKey, KeyboardEventKey> = Object.free
     '<': '<',
     '>': '>',
     '?': '?',
-});
+} as const;
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/random.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns a random integer between min and max (inclusive).
+ *
+ * @param min - The minimum value (inclusive).
+ * @param max - The maximum value (inclusive).
+ * @returns A random integer between min and max.
+ */
+export function randomNumber(min = 0, max = 100): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Returns a random string of alphanumeric characters.
+ *
+ * @param length - The length of the random ID to generate.
+ * @returns A random string of the specified length containing alphanumeric characters.
+ */
+export function randomString(length: number = 8): string {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    const rand = new Uint32Array(length);
+    window.crypto.getRandomValues(rand);
+    for (let i = 0; i < length; i++) result += chars[rand[i] % chars.length];
+    return result;
+}

package/src/utils/scrollElementIntoView.ts

@@ -4,7 +4,9 @@
  * @param element -- The element to scroll into view.
  * @param container -- The container to scroll.
  */
-export function scrollElementIntoView(element: HTMLElement, container: HTMLElement): void {
+export function scrollElementIntoView(element?: Element | null, container?: Element | null): void {
+    if (!element || !container) return;
+
     const elementRect = element.getBoundingClientRect();
 
     const containerRect = container.getBoundingClientRect();