@bspk/ui 1.0.0

package/src/utils/children.ts

@@ -0,0 +1,80 @@
+import { Children, Fragment, isValidElement, ReactNode } from 'react';
+
+export function isValidIcon(child: unknown) {
+    return isChildNamed(child, 'Icon');
+}
+
+export function getChildName(child: unknown): string {
+    if (!child) return '';
+
+    const typeChild = typeof child;
+    if (['string', 'number', 'boolean', 'bigint'].includes(typeChild)) return typeChild;
+    return (isValidElement(child) ? (child.type as { bspkName?: string })?.bspkName : '') || '';
+}
+
+export function getChildTypeName(child: unknown): string {
+    if (!child) return '';
+    const typeChild = typeof child;
+
+    if (['string', 'number', 'boolean', 'bigint'].includes(typeChild)) return typeChild;
+
+    if (isValidElement(child)) {
+        if (typeof child.type === 'string') return child.type;
+        return child.type.name || '';
+    }
+
+    return '';
+}
+
+export function isChildNamed(child: unknown, name: string): boolean {
+    return getChildName(child) === name;
+}
+
+export function isReactFragment(node: unknown): node is ReactNode {
+    return isValidElement(node) && node.type === Fragment;
+}
+
+/**
+ * Convert children to a flat array of children elements, removing any fragment wrappers in the process.
+ *
+ * @param children The children to convert to an array.
+ * @param ignoreParent If true, ignore parent elements and only return the children
+ */
+export function childrenToArray(children: ReactNode): ReactNode[] {
+    return Children.toArray(children).flatMap((child) => {
+        if (isValidElement(child)) {
+            if (isReactFragment(child) && child.props.children) return childrenToArray(child.props.children);
+            return child;
+        }
+        if (Array.isArray(child)) return childrenToArray(child);
+        if (child !== null && child !== undefined) return child;
+        return [];
+    }, []);
+}
+
+export type ChildElement =
+    | {
+          child: ReactNode;
+          name: string;
+      }
+    | {
+          child: string;
+          name: string;
+      };
+
+/**
+ * Get the children of a component as an array of objects with the child and the name of the child.
+ *
+ * Filter out unknown empty strings or non-truthy children other than zeros.
+ *
+ * @param children The children to get the elements from.
+ */
+export function getChildrenElements(children: ReactNode): ChildElement[] {
+    return (Array.isArray(children) ? children : childrenToArray(children))
+        .filter((child) => {
+            return (typeof child === 'string' && child.trim() !== '') || child === 0 || child;
+        })
+        .map((child) => ({ child, name: getChildName(child) }));
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/colorVariants.ts

@@ -0,0 +1,74 @@
+export type ColorVariant =
+    | 'blue'
+    | 'green'
+    | 'grey'
+    | 'lime'
+    | 'magenta'
+    | 'orange'
+    | 'pink'
+    | 'primary'
+    | 'purple'
+    | 'red'
+    | 'secondary'
+    | 'teal'
+    | 'white'
+    | 'yellow';
+
+export const COLOR_VARIABLES: Record<ColorVariant, { foreground: string; surface: string }> = {
+    grey: {
+        foreground: '--foreground-neutral-on-surface-variant-01',
+        surface: '--surface-neutral-t2-lowest',
+    },
+    white: {
+        foreground: '--foreground-neutral-on-surface-variant-01',
+        surface: '--surface-neutral-t1-base',
+    },
+    primary: {
+        foreground: '--foreground-brand-primary-depth',
+        surface: '--surface-brand-primary-highlight',
+    },
+    secondary: {
+        foreground: '--foreground-brand-secondary-depth',
+        surface: '--surface-brand-secondary-highlight',
+    },
+    blue: {
+        foreground: '--foreground-spectrum-blue',
+        surface: '--surface-spectrum-blue',
+    },
+    green: {
+        foreground: '--foreground-spectrum-green',
+        surface: '--surface-spectrum-green',
+    },
+    lime: {
+        foreground: '--foreground-spectrum-lime',
+        surface: '--surface-spectrum-lime',
+    },
+    magenta: {
+        foreground: '--foreground-spectrum-magenta',
+        surface: '--surface-spectrum-magenta',
+    },
+    orange: {
+        foreground: '--foreground-spectrum-orange',
+        surface: '--surface-spectrum-orange',
+    },
+    pink: {
+        foreground: '--foreground-spectrum-pink',
+        surface: '--surface-spectrum-pink',
+    },
+    purple: {
+        foreground: '--foreground-spectrum-purple',
+        surface: '--surface-spectrum-purple',
+    },
+    red: {
+        foreground: '--foreground-spectrum-red',
+        surface: '--surface-spectrum-red',
+    },
+    teal: {
+        foreground: '--foreground-spectrum-teal',
+        surface: '--surface-spectrum-teal',
+    },
+    yellow: {
+        foreground: '--foreground-spectrum-yellow',
+        surface: '--surface-spectrum-yellow',
+    },
+} as const;

package/src/utils/errors.tsx

@@ -0,0 +1,104 @@
+/**
+ * ERROR LOGGING
+ *
+ * When an error is logged it is stored in a buffer.
+ *
+ * After a debounce period all errors are merged and of they no longer exist are cleared.
+ *
+ * These errors are grouped by contextId and dispatched as a custom event.
+ *
+ * At this point the buffer is cleared.
+ */
+
+import { createContext, useContext, useEffect, useState } from 'react';
+
+export type ErrorDetail = {
+    message: string;
+    data?: unknown;
+    contextId?: string;
+    location: Location;
+    exists: boolean;
+};
+
+export const bspkErrorType = (contextId: string) => `bspk-error-${contextId}`;
+
+export type LogError = (exists: boolean, log: string | { message: string; data: unknown }) => boolean;
+
+let logBuffer: Record<string, ErrorDetail[]> = {};
+let logDebounce: ReturnType<typeof setTimeout> | null = null;
+
+export function logError(detail: Pick<ErrorDetail, 'contextId' | 'data' | 'exists' | 'message'>): boolean {
+    if (!detail.contextId) return detail.exists;
+
+    const bufferKey = `${detail.contextId}-${detail.message}`;
+
+    logBuffer[bufferKey] = logBuffer[bufferKey] || [];
+    logBuffer[bufferKey].push({ ...detail, location: document.location });
+
+    if (logDebounce) clearTimeout(logDebounce);
+
+    logDebounce = setTimeout(() => {
+        const contextErrors: Record<string, ErrorDetail[]> = {};
+
+        Object.values(logBuffer).flatMap((siblingErrors) => {
+            const lastSiblingError = siblingErrors[siblingErrors.length - 1];
+
+            const nextErrors = lastSiblingError.exists ? [lastSiblingError] : [];
+
+            if (lastSiblingError.contextId) {
+                // we send all errors to the contextId even if they are empty so we can clear the errors
+                contextErrors[lastSiblingError.contextId] = contextErrors[lastSiblingError.contextId] || [];
+                contextErrors[lastSiblingError.contextId].push(...nextErrors);
+            } else if (nextErrors.length) {
+                // eslint-disable-next-line no-console
+                nextErrors.forEach((e) => console.error(e));
+            }
+        });
+
+        logBuffer = {};
+
+        Object.entries(contextErrors).forEach(([contextId, errors]) => {
+            globalThis.dispatchEvent(new CustomEvent(bspkErrorType(contextId), { detail: errors }));
+        });
+    }, 500);
+
+    return detail.exists;
+}
+
+const errorContext = createContext(undefined as string | undefined);
+
+export function useErrorLogger(): {
+    logError: LogError;
+} {
+    const contextId = useContext(errorContext);
+
+    return {
+        logError: (exists: boolean, message: string, data?: unknown) => logError({ exists, contextId, message, data }),
+    };
+}
+
+export function ErrorLogContext({ children, id }: { children: React.ReactNode; id: string }) {
+    return <errorContext.Provider value={id}>{children}</errorContext.Provider>;
+}
+
+export function useErrorLog() {
+    const [errors, setErrors] = useState<ErrorDetail[]>([]);
+    const contextId = useContext(errorContext);
+
+    useEffect(() => {
+        if (!contextId) return;
+
+        const listener = (event: CustomEvent<ErrorDetail[]>) => {
+            // eslint-disable-next-line no-console
+            event.detail.forEach(console.error);
+            setErrors(event.detail);
+        };
+
+        globalThis.addEventListener(bspkErrorType(contextId), listener);
+        return () => globalThis.removeEventListener(bspkErrorType(contextId), listener);
+    }, [contextId]);
+
+    return { errors, contextId };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/getValidNode.ts

@@ -0,0 +1,7 @@
+import { isValidElement } from 'react';
+
+export function getValidNode<T = unknown>(node: T): T | undefined {
+    return isValidElement(node) || typeof node === 'string' || typeof node === 'number' ? node : undefined;
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/keyboard.ts

@@ -0,0 +1,382 @@
+export type KeyboardEventKey =
+    | ' '
+    | '_'
+    | '-'
+    | ';'
+    | ':'
+    | '!'
+    | '?'
+    | '.'
+    | ''
+    | '"'
+    | '('
+    | ')'
+    | '['
+    | ']'
+    | '{'
+    | '}'
+    | '@'
+    | '*'
+    | '/'
+    | '\\'
+    | '&'
+    | '#'
+    | '%'
+    | '`'
+    | '^'
+    | '+'
+    | '<'
+    | '='
+    | '>'
+    | '|'
+    | '~'
+    | '$'
+    | '0'
+    | '1'
+    | '2'
+    | '3'
+    | '4'
+    | '5'
+    | '6'
+    | '7'
+    | '8'
+    | '9'
+    | 'A'
+    | 'a'
+    | 'Alt'
+    | 'ArrowDown'
+    | 'ArrowLeft'
+    | 'ArrowRight'
+    | 'ArrowUp'
+    | 'AudioVolumeDown'
+    | 'AudioVolumeMute'
+    | 'AudioVolumeUp'
+    | 'B'
+    | 'b'
+    | 'Backspace'
+    | 'C'
+    | 'c'
+    | 'CapsLock'
+    | 'ContextMenu'
+    | 'Control'
+    | 'D'
+    | 'd'
+    | 'Delete'
+    | 'E'
+    | 'e'
+    | 'End'
+    | 'Enter'
+    | 'Escape'
+    | 'F'
+    | 'f'
+    | 'F1'
+    | 'F2'
+    | 'F3'
+    | 'F4'
+    | 'F5'
+    | 'F6'
+    | 'F7'
+    | 'F8'
+    | 'F9'
+    | 'F10'
+    | 'F11'
+    | 'F12'
+    | 'G'
+    | 'g'
+    | 'H'
+    | 'h'
+    | 'Home'
+    | 'I'
+    | 'i'
+    | 'Insert'
+    | 'J'
+    | 'j'
+    | 'K'
+    | 'k'
+    | 'L'
+    | 'l'
+    | 'M'
+    | 'm'
+    | 'Meta'
+    | 'N'
+    | 'n'
+    | 'NumLock'
+    | 'O'
+    | 'o'
+    | 'P'
+    | 'p'
+    | 'PageDown'
+    | 'PageUp'
+    | 'Pause'
+    | 'PrintScreen'
+    | 'Q'
+    | 'q'
+    | 'R'
+    | 'r'
+    | 'S'
+    | 's'
+    | 'ScrollLock'
+    | 'Shift'
+    | 'T'
+    | 't'
+    | 'Tab'
+    | 'U'
+    | 'u'
+    | 'V'
+    | 'v'
+    | 'W'
+    | 'w'
+    | 'X'
+    | 'x'
+    | 'Y'
+    | 'y'
+    | 'Z'
+    | 'z'
+    | "'";
+
+export type KeyboardEventCode =
+    | 'AltLeft'
+    | 'AltRight'
+    | 'ArrowDown'
+    | 'ArrowLeft'
+    | 'ArrowRight'
+    | 'ArrowUp'
+    | 'AudioVolumeDown'
+    | 'AudioVolumeMute'
+    | 'AudioVolumeUp'
+    | 'Backquote'
+    | 'Backslash'
+    | 'Backspace'
+    | 'BracketLeft'
+    | 'BracketRight'
+    | 'CapsLock'
+    | 'Comma'
+    | 'ContextMenu'
+    | 'ControlLeft'
+    | 'ControlRight'
+    | 'Delete'
+    | 'Digit0'
+    | 'Digit1'
+    | 'Digit2'
+    | 'Digit3'
+    | 'Digit4'
+    | 'Digit5'
+    | 'Digit6'
+    | 'Digit7'
+    | 'Digit8'
+    | 'Digit9'
+    | 'End'
+    | 'Enter'
+    | 'Equal'
+    | 'Escape'
+    | 'F1'
+    | 'F2'
+    | 'F3'
+    | 'F4'
+    | 'F5'
+    | 'F6'
+    | 'F7'
+    | 'F8'
+    | 'F9'
+    | 'F10'
+    | 'F11'
+    | 'F12'
+    | 'Home'
+    | 'Insert'
+    | 'KeyA'
+    | 'KeyB'
+    | 'KeyC'
+    | 'KeyD'
+    | 'KeyE'
+    | 'KeyF'
+    | 'KeyG'
+    | 'KeyH'
+    | 'KeyI'
+    | 'KeyJ'
+    | 'KeyK'
+    | 'KeyL'
+    | 'KeyM'
+    | 'KeyN'
+    | 'KeyO'
+    | 'KeyP'
+    | 'KeyQ'
+    | 'KeyR'
+    | 'KeyS'
+    | 'KeyT'
+    | 'KeyU'
+    | 'KeyV'
+    | 'KeyW'
+    | 'KeyX'
+    | 'KeyY'
+    | 'KeyZ'
+    | 'MetaLeft'
+    | 'MetaRight'
+    | 'Minus'
+    | 'NumLock'
+    | 'Numpad0'
+    | 'Numpad1'
+    | 'Numpad2'
+    | 'Numpad3'
+    | 'Numpad4'
+    | 'Numpad5'
+    | 'Numpad6'
+    | 'Numpad7'
+    | 'Numpad8'
+    | 'Numpad9'
+    | 'NumpadAdd'
+    | 'NumpadDecimal'
+    | 'NumpadDivide'
+    | 'NumpadMultiply'
+    | 'NumpadSubtract'
+    | 'PageDown'
+    | 'PageUp'
+    | 'Pause'
+    | 'Period'
+    | 'PrintScreen'
+    | 'Quote'
+    | 'ScrollLock'
+    | 'Semicolon'
+    | 'ShiftLeft'
+    | 'ShiftRight'
+    | 'Slash'
+    | 'Space'
+    | 'Tab';
+
+export const EVENT_KEY: Record<KeyboardEventKey, KeyboardEventKey> = Object.freeze({
+    Backspace: 'Backspace',
+    Tab: 'Tab',
+    Enter: 'Enter',
+    Shift: 'Shift',
+    Control: 'Control',
+    Alt: 'Alt',
+    Pause: 'Pause',
+    CapsLock: 'CapsLock',
+    Escape: 'Escape',
+    ' ': ' ',
+    PageUp: 'PageUp',
+    PageDown: 'PageDown',
+    End: 'End',
+    Home: 'Home',
+    ArrowLeft: 'ArrowLeft',
+    ArrowUp: 'ArrowUp',
+    ArrowRight: 'ArrowRight',
+    ArrowDown: 'ArrowDown',
+    PrintScreen: 'PrintScreen',
+    Insert: 'Insert',
+    Delete: 'Delete',
+    '0': '0',
+    '1': '1',
+    '2': '2',
+    '3': '3',
+    '4': '4',
+    '5': '5',
+    '6': '6',
+    '7': '7',
+    '8': '8',
+    '9': '9',
+    A: 'A',
+    B: 'B',
+    C: 'C',
+    D: 'D',
+    E: 'E',
+    F: 'F',
+    G: 'G',
+    H: 'H',
+    I: 'I',
+    J: 'J',
+    K: 'K',
+    L: 'L',
+    M: 'M',
+    N: 'N',
+    O: 'O',
+    P: 'P',
+    Q: 'Q',
+    R: 'R',
+    S: 'S',
+    T: 'T',
+    U: 'U',
+    V: 'V',
+    W: 'W',
+    X: 'X',
+    Y: 'Y',
+    Z: 'Z',
+    a: 'a',
+    b: 'b',
+    c: 'c',
+    d: 'd',
+    e: 'e',
+    f: 'f',
+    g: 'g',
+    h: 'h',
+    i: 'i',
+    j: 'j',
+    k: 'k',
+    l: 'l',
+    m: 'm',
+    n: 'n',
+    o: 'o',
+    p: 'p',
+    q: 'q',
+    r: 'r',
+    s: 's',
+    t: 't',
+    u: 'u',
+    v: 'v',
+    w: 'w',
+    x: 'x',
+    y: 'y',
+    z: 'z',
+    Meta: 'Meta',
+    ContextMenu: 'ContextMenu',
+    AudioVolumeMute: 'AudioVolumeMute',
+    AudioVolumeDown: 'AudioVolumeDown',
+    AudioVolumeUp: 'AudioVolumeUp',
+    F1: 'F1',
+    F2: 'F2',
+    F3: 'F3',
+    F4: 'F4',
+    F5: 'F5',
+    F6: 'F6',
+    F7: 'F7',
+    F8: 'F8',
+    F9: 'F9',
+    F10: 'F10',
+    F11: 'F11',
+    F12: 'F12',
+    NumLock: 'NumLock',
+    ScrollLock: 'ScrollLock',
+    ';': ';',
+    '=': '=',
+    '': '',
+    '-': '-',
+    '.': '.',
+    '/': '/',
+    '`': '`',
+    '[': '[',
+    '\\': '\\',
+    ']': ']',
+    "'": "'",
+    '~': '~',
+    '!': '!',
+    '@': '@',
+    '#': '#',
+    $: '$',
+    '%': '%',
+    '^': '^',
+    '&': '&',
+    '*': '*',
+    '(': '(',
+    ')': ')',
+    _: '_',
+    '+': '+',
+    '{': '{',
+    '}': '}',
+    '|': '|',
+    ':': ':',
+    '"': '"',
+    '<': '<',
+    '>': '>',
+    '?': '?',
+});
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/placeholder.test.ts

@@ -0,0 +1,7 @@
+describe('placeholder', () => {
+    test('', () => {
+        expect(1).toBe(1);
+    });
+});
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/ref.ts

@@ -0,0 +1,11 @@
+import { MutableRefObject, RefCallback } from 'react';
+
+export type InnerRef<T extends HTMLElement | null> = MutableRefObject<T> | RefCallback<T>;
+
+/** Sets a ref using either a ref callback or a ref object */
+export function setRef<T extends HTMLElement | null>(ref: InnerRef<T>, node: T): void {
+    if (typeof ref === 'function') return ref(node);
+    ref.current = node;
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/scrollElementIntoView.ts

@@ -0,0 +1,29 @@
+/**
+ * Scrolls the container to make the element visible.
+ *
+ * @param element -- The element to scroll into view.
+ * @param container -- The container to scroll.
+ */
+export function scrollElementIntoView(element: HTMLElement, container: HTMLElement): void {
+    const elementRect = element.getBoundingClientRect();
+
+    const containerRect = container.getBoundingClientRect();
+
+    if (elementRect.top < containerRect.top) {
+        // Element is above the visible area
+        container.scrollTop -= containerRect.top - elementRect.top;
+    } else if (elementRect.bottom > containerRect.bottom) {
+        // Element is below the visible area
+        container.scrollTop += elementRect.bottom - containerRect.bottom;
+    }
+
+    if (elementRect.left < containerRect.left) {
+        // Element is to the left of the visible area
+        container.scrollLeft -= containerRect.left - elementRect.left;
+    } else if (elementRect.right > containerRect.right) {
+        // Element is to the right of the visible area
+        container.scrollLeft += elementRect.right - containerRect.right;
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */