@bspk/ui 1.2.0 → 1.3.0

package/src/styles/base.scss

@@ -22,7 +22,9 @@
 }
 
 :root {
+    --z-index-snackbar: 1200;
     --z-index-focus: 9999;
+    --z-index-button-dock: 1150;
     --z-index-tooltip-popover: 1100;
     --z-index-dialog: 1000;
     --z-index-dropdown: 1000;
@@ -59,89 +61,92 @@ body[data-bspk] {
     color: var(--foreground-neutral-on-surface);
     min-width: 343px;
 
-    a:not([data-bspk='button'], [data-bspk='list-item']) {
-        color: var(--foreground-link-text-default);
-
-        &:not([disabled]) {
-            &:hover,
-            &[data-pseudo='hover'] {
-                color: var(--foreground-link-text-default-hovered);
-            }
-
-            &:active,
-            &[data-pseudo='active'] {
-                color: var(--foreground-link-text-default);
-                filter: brightness(80%);
+    a,
+    [data-bspk='link'] {
+        &:not([data-bspk='button'], [data-bspk='list-item']) {
+            color: var(--foreground-link-text-default);
+
+            &:not([disabled]) {
+                &:hover,
+                &[data-pseudo='hover'] {
+                    color: var(--foreground-link-text-default-hovered);
+                }
+
+                &:active,
+                &[data-pseudo='active'] {
+                    color: var(--foreground-link-text-default);
+                    filter: brightness(80%);
+                }
+
+                &:visited,
+                &[data-pseudo='visited'] {
+                    color: var(--foreground-link-text-default-visited);
+                }
             }
 
-            &:visited,
-            &[data-pseudo='visited'] {
-                color: var(--foreground-link-text-default-visited);
+            &[disabled] {
+                pointer-events: none;
+                cursor: text;
+                color: var(--foreground-link-text-default-disabled);
             }
         }
 
-        &[disabled] {
-            pointer-events: none;
-            cursor: text;
-            color: var(--foreground-link-text-default-disabled);
-        }
-    }
-
-    a[data-subtle] {
-        text-decoration: none;
-        color: var(--foreground-neutral-on-surface);
-
-        &:not([disabled]) {
-            &:hover,
-            &[data-pseudo='hover'] {
-                text-decoration: underline;
-                color: var(--foreground-link-text-subtle-hovered);
+        &[data-subtle] {
+            text-decoration: none;
+            color: var(--foreground-neutral-on-surface);
+
+            &:not([disabled]) {
+                &:hover,
+                &[data-pseudo='hover'] {
+                    text-decoration: underline;
+                    color: var(--foreground-link-text-subtle-hovered);
+                }
+
+                &:active,
+                &[data-pseudo='active'] {
+                    text-decoration: underline;
+                    color: var(--foreground-link-text-subtle-pressed);
+                }
+
+                &:visited,
+                &[data-pseudo='visited'] {
+                    color: var(--foreground-neutral-on-surface);
+                }
             }
 
-            &:active,
-            &[data-pseudo='active'] {
-                text-decoration: underline;
-                color: var(--foreground-link-text-subtle-pressed);
-            }
-
-            &:visited,
-            &[data-pseudo='visited'] {
-                color: var(--foreground-neutral-on-surface);
+            &[disabled] {
+                pointer-events: none;
+                color: var(--foreground-link-text-subtle-disabled);
             }
         }
 
-        &[disabled] {
-            pointer-events: none;
-            color: var(--foreground-link-text-subtle-disabled);
-        }
-    }
-
-    a[data-subtle-inverse] {
-        text-decoration: none;
-        color: var(--foreground-neutral-inverse-on-surface);
-
-        &:not([disabled]) {
-            &:hover,
-            &[data-pseudo='hover'] {
-                text-decoration: underline;
-                color: var(--foreground-link-text-subtle-inverse-hovered);
+        &[data-subtle-inverse] {
+            text-decoration: none;
+            color: var(--foreground-neutral-inverse-on-surface);
+
+            &:not([disabled]) {
+                &:hover,
+                &[data-pseudo='hover'] {
+                    text-decoration: underline;
+                    color: var(--foreground-link-text-subtle-inverse-hovered);
+                }
+
+                &:active,
+                &[data-pseudo='active'] {
+                    text-decoration: underline;
+                    color: var(--foreground-link-text-subtle-inverse-pressed);
+                }
+
+                &:visited,
+                &[data-pseudo='visited'] {
+                    color: var(--foreground-neutral-on-inverse-surface);
+                }
             }
 
-            &:active,
-            &[data-pseudo='active'] {
-                text-decoration: underline;
-                color: var(--foreground-link-text-subtle-inverse-pressed);
+            &[disabled] {
+                pointer-events: none;
+                color: var(--foreground-link-text-subtle-inversed-disabled);
             }
-
-            &:visited,
-            &[data-pseudo='visited'] {
-                color: var(--foreground-neutral-on-inverse-surface);
-            }
-        }
-
-        &[disabled] {
-            pointer-events: none;
-            color: var(--foreground-link-text-subtle-inversed-disabled);
         }
     }
 }
@@ -289,4 +294,60 @@ body[data-bspk] {
     }
 }
 
+@keyframes fade-in {
+    0% {
+        opacity: 0;
+        transform: translate(var(--spacing-sizing-01), var(--spacing-sizing-01));
+    }
+
+    100% {
+        opacity: 1;
+        transform: translate(0, 0);
+    }
+}
+
+@keyframes placement-left {
+    0% {
+        transform: translateX(-100vw);
+    }
+
+    100% {
+        transform: translateX(0);
+    }
+}
+
+@keyframes placement-right {
+    0% {
+        transform: translateX(100vw);
+    }
+
+    100% {
+        transform: translateX(0);
+    }
+}
+
+@keyframes placement-top {
+    0% {
+        transform: translateY(-100vh);
+    }
+
+    100% {
+        transform: translateY(0);
+    }
+}
+
+@keyframes placement-bottom {
+    0% {
+        transform: translateY(100vh);
+    }
+
+    100% {
+        transform: translateY(0);
+    }
+}
+
+[data-hidden] {
+    display: none !important;
+}
+
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/types/common.ts

@@ -6,10 +6,11 @@
  * @bspk/ui/Txt".
  */
 
-import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef } from 'react';
+import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef, AriaRole } from 'react';
 
 export type AlertVariant = 'error' | 'informational' | 'success' | 'warning';
 
+/** Sets a ref to the given element. */
 export type SetRef<T> = (instance: T | null) => void;
 
 export type ElementProps<
@@ -110,13 +111,17 @@ export type CommonPropsLibrary = {
      */
     'aria-label': string;
     /**
-     * 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.
+     * Identifies the parent component. Helps with styling, debugging, and/or testing purposes.
      *
      * @utility
      */
     owner?: string;
+    /**
+     * The ARIA role of the element.
+     *
+     * @type string
+     */
+    role?: AriaRole;
 };
 
 export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;

package/src/types/meta.ts

@@ -5,10 +5,8 @@
 
 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
 ];
@@ -33,12 +31,6 @@ export const COMPONENT_PHASES: Record<
         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',
@@ -104,6 +96,6 @@ export type UtilityMeta = BaseMeta & {
     returns?: string;
 };
 
-export type ComponentPhase = 'Backlog' | 'Dev' | 'QA' | 'Stable' | 'Utility' | 'UXReview';
+export type ComponentPhase = 'Backlog' | 'Dev' | 'Stable' | 'Utility' | 'UXReview';
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/createExampleChildElement.tsx

@@ -69,7 +69,7 @@ export function createExampleChildElement({ exampleState, name, setState, action
 
     if (componentName === 'Img') return { element: <Img alt="placeholder" src="/placeholder.svg" /> };
 
-    if (componentName === 'Avatar') return { element: <Avatar name="List Item" showTooltip={false} /> };
+    if (componentName === 'Avatar') return { element: <Avatar hideTooltip={false} name="List Item" /> };
 
     if (componentName === 'Tag') {
         return { element: <Tag label="Tag" /> };

package/src/utils/demo.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { AlertVariant } from '-/types/common';
+import { CSSProperties, ReactNode } from 'react';
+import { AlertVariant, DataProps } from '-/types/common';
 import { ComponentMeta } from '-/types/meta';
 
 export type TypeProperty = {
@@ -96,28 +97,61 @@ export type ComponentExample<Props = Record<string, unknown>, PropName extends k
      * 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 }) => React.ReactNode;
+        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/handleKeyDown.ts

@@ -1,6 +1,7 @@
+import { KeyboardEvent } from 'react';
 import { KeyboardEventCode } from './keyboard';
 
-export type KeysCallback = Partial<Record<KeyboardEventCode, (event: React.KeyboardEvent) => void>>;
+export type KeysCallback = Partial<Record<KeyboardEventCode, ((event: KeyboardEvent) => void) | null>>;
 
 /**
  * Handles multiple keydown events with specific callbacks for each key.
@@ -9,16 +10,20 @@ export type KeysCallback = Partial<Record<KeyboardEventCode, (event: React.Keybo
  * @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 } = {},
+    keysCallback: KeysCallback = {},
+    { stopPropagation = false, preventDefault = false }: { stopPropagation?: boolean; preventDefault?: boolean } = {},
 ) {
-    return (event: React.KeyboardEvent) => {
-        const callback = keysCallback[event.code as KeyboardEventCode];
+    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;
+        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'

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

@@ -37,9 +37,17 @@
             ],
             "-/constants/*": [
                 "./src/constants/*"
+            ],
+            "-/rtl/*": [
+                "./src/rtl/*"
             ]
         },
-        "moduleDetection": "auto"
+        "moduleDetection": "auto",
+        "types": [
+            "node",
+            "jest",
+            "@testing-library/jest-dom"
+        ]
     },
     "typeRoots": [
         "./node_modules/@types",

package/dist/components/Accordion/AccordionSection.d.ts

@@ -1,84 +0,0 @@
-import { ReactNode } from 'react';
-import './accordion.scss';
-export type AccordionSectionProps = {
-    /**
-     * The content of the accordion.
-     *
-     * @required
-     */
-    children: ReactNode;
-    /**
-     * The title of the accordion.
-     *
-     * @required
-     */
-    title: string;
-    /** The title of the accordion. */
-    subTitle?: string;
-    /**
-     * The leading element to display in the Accordion title.
-     *
-     * Leading elements may only be one of the following [Icon](/icons), Img, Avatar.
-     *
-     * @exampleType select
-     * @options Icon, Img, Avatar
-     */
-    leading?: ReactNode;
-    /**
-     * The trailing element to display in the accordion header.
-     *
-     * @exampleType select
-     * @options Tag
-     */
-    trailing?: ReactNode;
-    /**
-     * If the accordion is open.
-     *
-     * @default false
-     * @required
-     */
-    isOpen?: boolean;
-    /**
-     * Fires when the accordion state changes.
-     *
-     * @required
-     */
-    toggleOpen: () => void;
-    /**
-     * If true, a divider will be shown below the accordion header.
-     *
-     * @default true
-     */
-    divider?: boolean;
-    /**
-     * Indicates whether the accordion is disabled.
-     *
-     * @default false
-     */
-    disabled?: boolean;
-    /**
-     * The unique identifier for the accordion item.
-     *
-     * @required
-     */
-    id: string;
-};
-/**
- * A vertical stack of collapsible panels or that allows customers to expand or collapse each panel individually to
- * reveal or hide their content.
- *
- * @example
- *     import { Accordion } from '@bspk/ui/Accordion';
- *
- *     function Example() {
- *         return (
- *             <Accordion title="Accordion Title" subTitle="Accordion Subtitle">
- *                 Accordion Content
- *             </Accordion>
- *         );
- *     }
- *
- * @name Accordion
- * @phase WorkInProgress
- */
-export declare function AccordionSection({ children, title, subTitle, leading, isOpen, toggleOpen, divider, trailing, disabled, id, }: AccordionSectionProps): import("react/jsx-runtime").JSX.Element;