@bspk/ui 1.1.34 → 1.3.0

package/src/utils/demo.ts

@@ -1,6 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { AlertVariant } from '-';
+import { CSSProperties, ReactNode } from 'react';
+import { AlertVariant, DataProps } from '-/types/common';
+import { ComponentMeta } from '-/types/meta';
 
 export type TypeProperty = {
     name: string;
@@ -23,14 +25,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 +44,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 +55,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.
      *
@@ -94,22 +97,61 @@ export type ComponentExample<Props = Record<string, unknown>, PropName = keyof P
      * If you only need to update the props of the component, you can use renderProps.
      */
     render?: ComponentExampleRender<Props>;
-    /** We may not want certain props editable in the props table. */
-    disableProps?: PropName[];
+    /**
+     * We may not want certain props editable in the props table.
+     *
+     * Setting this to true will disable all props.
+     *
+     * Or you can pass an array of prop names to disable specific props.
+     */
+    disableProps?: PropName[] | true;
+    /** The sections of the example. */
+    sections?: {
+        title: string;
+        content: (params: {
+            Component: React.ComponentType<Props>;
+            props: Props;
+            CodeExample: CodeExample;
+            Syntax: Syntax;
+        }) => React.ReactNode;
+    }[];
 };
 
+export type Syntax = (params: {
+    code: string;
+    language?: PrettyParser;
+    style?: CSSProperties;
+    pretty?: boolean;
+}) => React.ReactNode;
+
+export type CodeExample = (
+    params: DataProps & {
+        containerStyle?: CSSProperties;
+        children: ReactNode;
+        accessibility?: boolean;
+        code?: {
+            language?: PrettyParser | undefined;
+            str: string;
+        };
+    },
+) => React.ReactNode;
+
+export type PrettyParser = 'css' | 'estree' | 'html' | 'scss' | 'typescript';
+
 export type ComponentExampleFn<Props = Record<string, unknown>> = (params: {
     setState: DemoSetState<Props>;
     action: DemoAction;
+    componentsMeta: ComponentMeta[];
 }) => ComponentExample<Props>;
 
+export type OnHandlers = `on${string}`;
+
 export type Preset<Props> = {
     /** The name of the preset. This is used to display the preset in the UI. */
     label: string;
     /** The props of the component. This is used to set props of the component. These values can't be changed in the UI. */
-    propState?: Partial<Props>;
-    /** Determines if the preset is the default preset. This is used to set the initial propState of the component. */
-    isDefault?: boolean;
+    propState: Omit<Props, OnHandlers> & Record<OnHandlers, unknown>;
+    otherState?: Record<string, Record<string, unknown> | unknown> & Record<string, unknown>;
 };
 
 export type DemoPreset<P = Record<string, unknown>> = Preset<P> & {

package/src/utils/dom.ts

@@ -0,0 +1,6 @@
+/** A safe way to get an element by ID that works in SSR environments or when the ID value is not considered valid. */
+export function getElementById<T extends HTMLElement = HTMLElement>(id?: string | null): T | null {
+    if (typeof document === 'undefined') return null;
+    if (!id) return null;
+    return document.querySelector<T>(`[id="${id}"]`);
+}

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,29 @@
+import { KeyboardEvent } from 'react';
+import { KeyboardEventCode } from './keyboard';
+
+export type KeysCallback = Partial<Record<KeyboardEventCode, ((event: KeyboardEvent) => void) | null>>;
+
+/**
+ * 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 = false, preventDefault = false }: { stopPropagation?: boolean; preventDefault?: boolean } = {},
+) {
+    return (event: KeyboardEvent) => {
+        let eventCode = event.code as KeyboardEventCode;
+        if (event.ctrlKey && event.altKey && event.code === 'Space') eventCode = 'Ctrl+Option+Space';
+
+        const callback = keysCallback[eventCode];
+
+        if (callback) {
+            callback(event);
+            if (stopPropagation) event.stopPropagation();
+            if (preventDefault) event.preventDefault();
+        }
+        return callback ? eventCode : null;
+    };
+}

package/src/utils/keyboard.ts

@@ -134,7 +134,10 @@ export type KeyboardEventKey =
     | 'z'
     | "'";
 
+export type KeyboardEventCodeCustom = 'Ctrl+Option+Space';
+
 export type KeyboardEventCode =
+    | KeyboardEventCodeCustom
     | 'AltLeft'
     | 'AltRight'
     | 'ArrowDown'
@@ -242,7 +245,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 +380,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();

package/src/utils/scrollListItemsStyle.ts

@@ -0,0 +1,29 @@
+import { CSSProperties } from 'react';
+
+export type ScrollListItemsStyleProps = {
+    /**
+     * The maximum number of ListItems to show before scrolling is enabled.
+     *
+     * Used in conjunction with scrollListItemsStyle utility.
+     */
+    scrollLimit?: number;
+};
+
+export function scrollListItemsStyle(scrollLimitProp: unknown, itemCount: unknown): CSSProperties {
+    const scrollLimit = Number(scrollLimitProp);
+
+    // Check:
+    // 1. scrollLimit is valid
+    // 2. itemCount is a number
+    // 3. scrollLimit is less than itemCount
+    // If any of these fail, return undefined (no scrolling)
+    if (Number.isNaN(scrollLimit) || scrollLimit <= 0 || typeof itemCount !== 'number' || scrollLimit > itemCount)
+        return {};
+
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        maxHeight: `calc(var(--list-item-height) * ${scrollLimit})`,
+        overflow: 'hidden auto',
+    };
+}

package/src/utils/snackbarContext.tsx

@@ -0,0 +1,43 @@
+import { createContext } from 'react';
+
+export interface SnackbarData {
+    /** Automatically set unique identifier. */
+    id: string;
+    /** The main body text of the snackbar */
+    text: string;
+    /**
+     * The variant of the snackbar.
+     *
+     * @default 'default'
+     */
+    variant?: 'default' | 'error' | 'success' | 'warning';
+    /** Time in milliseconds after which the snackbar will auto dismiss. You can also set a default at the UIProvider */
+    timeout?: number | null;
+    /** Optional action button */
+    button?: {
+        /**
+         * The button text
+         *
+         * @default 'dismiss'
+         */
+        label: string;
+        /**
+         * Either 'close' or a callback function that is called when the button is clicked. If 'close' is provided the
+         * snackbar will close when the button is clicked.
+         *
+         * @default 'close'
+         */
+        onClick: 'close' | (() => void);
+    };
+}
+
+export type SnackbarInput = Omit<SnackbarData, 'id'>;
+
+export type SnackbarContextProps = {
+    snackbars: SnackbarData[];
+    sendSnackbar: (data: Omit<SnackbarData, 'id'>) => void;
+    clearSnackbar: (id: SnackbarData['id']) => void;
+    clearAll: () => void;
+};
+
+export const SnackbarContext = createContext<SnackbarContextProps | undefined>(undefined);

package/src/utils/uiContext.ts

@@ -1,15 +1,18 @@
-import { createContext } from 'react';
+import { AriaAttributes, createContext } from 'react';
 
 export const COLOR_THEMES = ['light', 'dark'] as const;
 
 export type ColorTheme = (typeof COLOR_THEMES)[number];
 
+export type AriaLiveMessage = { message: string; live?: Exclude<AriaAttributes['aria-live'], 'off' | undefined> };
+
 export type UIContextProps = {
     theme: ColorTheme;
     setTheme: (theme: ColorTheme) => void;
     isMobile: boolean;
     isTablet: boolean;
     isDesktop: boolean;
+    sendAriaLiveMessage: (message: string, live?: AriaLiveMessage['live']) => void;
 };
 
 export const UIContext = createContext<UIContextProps | undefined>(undefined);

package/src/utils/useIds.ts

@@ -0,0 +1,16 @@
+import { useMemo } from 'react';
+
+/** A hook that generates unique IDs for a list of items. */
+export function useIds<T>(prefix: string, items: T[]): (T & { id: string })[] {
+    return useMemo(
+        () =>
+            items.map((item, index) => ({
+                ...item,
+                id:
+                    item && typeof item === 'object' && 'id' in item && item.id
+                        ? String(item.id)
+                        : `${prefix}-item-${index}`,
+            })),
+        [items, prefix],
+    );
+}

package/tsconfig.build.json

@@ -0,0 +1,21 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    },
+    "include": [
+        "src/**/*",
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "**/*.spec.ts",
+        "**/*.test.ts",
+        "**/*.spec.tsx",
+        "**/*.test.tsx",
+        "**/rtl/**",
+        "BUILD_CONFIG"
+    ]
+}

package/tsconfig.json

@@ -4,7 +4,7 @@
         "target": "ES2020",
         "lib": [
             "es5",
-            "dom",
+            "dom"
         ],
         "jsx": "react-jsx",
         "moduleResolution": "node",
@@ -32,14 +32,29 @@
             "-/utils/*": [
                 "./src/utils/*"
             ],
-            "-": [
-                "./src/index.ts"
+            "-/types/*": [
+                "./src/types/*"
             ],
+            "-/constants/*": [
+                "./src/constants/*"
+            ],
+            "-/rtl/*": [
+                "./src/rtl/*"
+            ]
         },
         "moduleDetection": "auto",
+        "types": [
+            "node",
+            "jest",
+            "@testing-library/jest-dom"
+        ]
     },
+    "typeRoots": [
+        "./node_modules/@types",
+        "./types"
+    ],
     "include": [
-        "src/**/*",
+        "src/**/*"
     ],
     "exclude": [
         "node_modules",

package/dist/components/Chip/Chip.d.ts

@@ -1,64 +0,0 @@
-import { CSSProperties, ReactNode } from 'react';
-import { CommonProps } from '../../index.js';
-import './chip.scss';
-export type ChipProps = CommonProps<'disabled'> & {
-    /**
-     * The content of the chip.
-     *
-     * @required
-     */
-    children: ReactNode | string;
-    /**
-     * Whether the chip should wrap its content.
-     *
-     * (Not recommended)
-     *
-     * @default false
-     */
-    wrap?: boolean;
-    /**
-     * The variant of the chip.
-     *
-     * @default filter
-     */
-    variant?: 'filter';
-    /**
-     * Is the chip elevated or flat. If flat the drop shadow is removed.
-     *
-     * @default false
-     */
-    flat?: boolean;
-    /**
-     * Whether the chip is currently selected.
-     *
-     * @default false
-     */
-    selected?: boolean;
-    /** The style of the chip. */
-    style?: CSSProperties;
-    /** The function to call when the chip is clicked. */
-    onClick?: (event: React.MouseEvent<HTMLSpanElement, MouseEvent>) => void;
-};
-/**
- * Dynamically generated options that are suggested to the user as responses or prompts.
- *
- * @example
- *     import { Chip } from '@bspk/ui/Chip';
- *
- *     function Example() {
- *         return (
- *             <Chip variant="filter" onClick={() => console.log('Chip clicked!')}>
- *                 Example Chip
- *             </Chip>
- *         );
- *     }
- *
- * @name Chip
- * @phase DesignReview
- */
-declare function Chip({ children, wrap, variant, flat, disabled, selected, onClick, style: styleProp, }: ChipProps): import("react/jsx-runtime").JSX.Element;
-declare namespace Chip {
-    var bspkName: string;
-}
-export { Chip };
-/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/dist/components/Chip/Chip.js

@@ -1,33 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import './chip.css.js';
-/**
- * Dynamically generated options that are suggested to the user as responses or prompts.
- *
- * @example
- *     import { Chip } from '@bspk/ui/Chip';
- *
- *     function Example() {
- *         return (
- *             <Chip variant="filter" onClick={() => console.log('Chip clicked!')}>
- *                 Example Chip
- *             </Chip>
- *         );
- *     }
- *
- * @name Chip
- * @phase DesignReview
- */
-function Chip({ children = '', wrap = false, variant = 'filter', flat = false, disabled = false, selected = false, onClick, style: styleProp, }) {
-    let additionalProps = {};
-    if (variant === 'filter') {
-        additionalProps = {
-            onClick,
-            role: 'button',
-            tabIndex: 0,
-        };
-    }
-    return (_jsx("span", { "data-bspk": "chip", "data-disabled": disabled || undefined, "data-flat": flat || undefined, "data-selected": selected || undefined, "data-variant": variant, "data-wrap": wrap || undefined, style: styleProp, ...additionalProps, children: children }));
-}
-Chip.bspkName = 'Chip';
-export { Chip };
-//# sourceMappingURL=Chip.js.map

package/dist/components/Chip/Chip.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Chip.js","sourceRoot":"","sources":["../../../src/components/Chip/Chip.tsx"],"names":[],"mappings":";AAIA,OAAO,aAAa,CAAC;AA0CrB;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,IAAI,CAAC,EACV,QAAQ,GAAG,EAAE,EACb,IAAI,GAAG,KAAK,EACZ,OAAO,GAAG,QAAQ,EAClB,IAAI,GAAG,KAAK,EACZ,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,OAAO,EACP,KAAK,EAAE,SAAS,GACR;IACR,IAAI,eAAe,GAAG,EAAE,CAAC;IAEzB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvB,eAAe,GAAG;YACd,OAAO;YACP,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,CAAC;SACd,CAAC;IACN,CAAC;IAED,OAAO,CACH,4BACc,MAAM,mBACD,QAAQ,IAAI,SAAS,eACzB,IAAI,IAAI,SAAS,mBACb,QAAQ,IAAI,SAAS,kBACtB,OAAO,eACV,IAAI,IAAI,SAAS,EAC5B,KAAK,EAAE,SAAS,KACZ,eAAe,YAElB,QAAQ,GACN,CACV,CAAC;AACN,CAAC;AAED,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;AAEvB,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/components/Chip/chip.css

@@ -1,44 +0,0 @@
-[data-bspk=chip] {
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  width: fit-content;
-  height: var(--spacing-sizing-06);
-  padding: 0 var(--spacing-sizing-02);
-  font: var(--labels-small);
-  color: var(--foreground-neutral-on-surface-variant-01);
-  background-color: var(--surface-neutral-t1-base);
-  border: 1px solid var(--stroke-neutral-low);
-  border-radius: var(--radius-sm);
-}
-[data-bspk=chip]:not([data-flat]) {
-  box-shadow: var(--drop-shadow-raise);
-}
-[data-bspk=chip][data-variant=filter] {
-  cursor: pointer;
-}
-[data-bspk=chip][data-wrap] {
-  height: auto;
-}
-[data-bspk=chip][data-disabled] {
-  color: var(--foreground-neutral-disabled-on-surface);
-  cursor: not-allowed;
-  border-color: var(--stroke-neutral-disabled-light);
-  background-image: linear-gradient(var(--interactions-disabled-opacity), var(--interactions-disabled-opacity)), linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
-}
-[data-bspk=chip]:not([data-disabled]):hover {
-  background-image: linear-gradient(var(--interactions-neutral-hover-opacity), var(--interactions-neutral-hover-opacity)), linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
-}
-[data-bspk=chip]:not([data-disabled]):active {
-  background-image: linear-gradient(var(--interactions-neutral-press-opacity), var(--interactions-neutral-press-opacity)), linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
-}
-[data-bspk=chip]:not([data-disabled]):focus {
-  outline: 1px solid var(--stroke-neutral-focus);
-  border-color: var(--stroke-neutral-focus);
-}
-[data-bspk=chip][data-selected] {
-  background-color: var(--surface-brand-primary-highlight);
-  border-color: var(--stroke-brand-primary);
-}
-
-/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */