@bspk/ui 1.0.0

package/src/Tooltip.tsx

@@ -0,0 +1,170 @@
+import { css } from '@emotion/react';
+import { cloneElement, ReactElement, useId, useMemo, useRef, useState } from 'react';
+
+import { Portal } from './Portal';
+import { Placement, useFloating } from './hooks/useFloating';
+
+export type TooltipProps = {
+    /**
+     * The placement of the tooltip.
+     *
+     * @default top
+     */
+    placement?: Placement;
+    /** The tooltip content. */
+    label: string;
+    /**
+     * A single element that will trigger the tooltip when hovered over.
+     *
+     * @type ReactElement
+     * @required
+     */
+    children: ReactElement;
+    /** Determines if the tooltip is disabled. */
+    disabled?: boolean;
+    /**
+     * Determines if the tooltip should hide the tail.
+     *
+     * @default true
+     */
+    tail?: boolean;
+};
+
+/**
+ * Brief message that provide additional guidance and helps users perform an action if needed.
+ *
+ * @name Tooltip
+ */
+function Tooltip({ placement = 'top', label, children, disabled = false, tail = true }: TooltipProps) {
+    const id = useId();
+    const [show, setShow] = useState(false);
+
+    const child = useMemo(
+        () =>
+            !disabled &&
+            children &&
+            cloneElement(children, {
+                onMouseOver: () => setShow(true),
+                onMouseLeave: () => setShow(false),
+                'aria-describedby': id,
+            }),
+        [children, disabled, id],
+    );
+
+    const arrowRef = useRef<HTMLElement | null>(null);
+
+    const { floatingStyles, middlewareData, elements } = useFloating({
+        placement: placement,
+        strategy: 'fixed',
+        offsetOptions: 8,
+        arrowRef,
+        hide: !show,
+    });
+
+    return disabled ? (
+        children
+    ) : (
+        <>
+            {child}
+            {label && (
+                <Portal>
+                    <div
+                        css={style}
+                        data-placement={middlewareData?.offset?.placement}
+                        data-tooltip=""
+                        id={id}
+                        ref={(node) => {
+                            elements.setFloating(node);
+                            elements.setTrigger(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                        }}
+                        role="tooltip"
+                        style={floatingStyles}
+                    >
+                        <span data-text>{label}</span>
+                        {tail !== false && (
+                            <span
+                                aria-hidden
+                                data-arrow
+                                ref={(node) => {
+                                    arrowRef.current = node;
+                                }}
+                                style={{
+                                    left: `${middlewareData?.arrow?.x}px`,
+                                    top: `${middlewareData?.arrow?.y}px`,
+                                }}
+                            />
+                        )}
+                    </div>
+                </Portal>
+            )}
+        </>
+    );
+}
+
+Tooltip.bspkName = 'Tooltip';
+
+export { Tooltip };
+
+export const style = css`
+    position: fixed;
+    pointer-events: none;
+    z-index: var(--z-index-tooltip-popover);
+
+    [data-text] {
+        display: block;
+        z-index: 2;
+        position: relative;
+        background-color: var(--surface-neutral-inverse);
+        border-radius: var(--radius-small);
+        color: var(--foreground-neutral-on-inverse-surface);
+        box-shadow: var(--drop-shadow-float);
+        font: var(--labels-small);
+        padding: var(--spacing-sizing-01) var(--spacing-sizing-02);
+        border: none;
+        transition: opacity 0.2s ease-in-out;
+        width: max-content;
+    }
+
+    --arrow-size: var(--spacing-sizing-01);
+    --arrow-offset: calc(var(--arrow-size) * -2);
+
+    [data-arrow] {
+        display: block;
+        z-index: 1;
+        position: absolute;
+        width: 0;
+        height: 0;
+        border-style: solid;
+        border-width: var(--arrow-size) var(--arrow-size) var(--arrow-size) var(--arrow-size);
+        border-color: transparent transparent transparent transparent;
+    }
+
+    &[data-placement^='bottom'] {
+        [data-arrow] {
+            top: var(--arrow-offset);
+            border-bottom-color: var(--surface-neutral-inverse);
+        }
+    }
+
+    &[data-placement^='top'] {
+        [data-arrow] {
+            border-top-color: var(--surface-neutral-inverse);
+        }
+    }
+
+    &[data-placement^='right'] {
+        [data-arrow] {
+            margin-left: var(--arrow-offset);
+            border-right-color: var(--surface-neutral-inverse);
+        }
+    }
+
+    &[data-placement^='left'] {
+        [data-arrow] {
+            right: var(--arrow-offset);
+            border-left-color: var(--surface-neutral-inverse);
+        }
+    }
+`;
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/TopNavigation.tsx

@@ -0,0 +1,29 @@
+import { css } from '@emotion/react';
+
+export type TopNavigationProps = {
+    /** The content of the top navigation. */
+    children: string;
+};
+
+/**
+ * Component description coming soon.
+ *
+ * @name TopNavigation
+ */
+function TopNavigation({ children }: TopNavigationProps) {
+    return (
+        <div css={style} data-top-navigation>
+            {children}
+        </div>
+    );
+}
+
+TopNavigation.bspkName = 'TopNavigation';
+
+export { TopNavigation };
+
+export const style = css`
+    display: flex;
+`;
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/Txt.tsx

@@ -0,0 +1,69 @@
+import { css } from '@emotion/react';
+import { ElementType } from 'react';
+
+import { TxtVariant } from './utils/txtVariants';
+
+import { ElementProps } from './';
+
+export type TxtProps<As extends ElementType = 'span'> = {
+    /**
+     * The element type to render as.
+     *
+     * @default span
+     * @type ElementType
+     */
+    as?: As;
+    /**
+     * The content to render.
+     *
+     * @type string
+     * @required
+     */
+    children: unknown;
+    /**
+     * The variant to use.
+     *
+     * @default body-base
+     */
+    variant?: TxtVariant;
+    /** The id of the element. */
+    id?: string;
+};
+
+/**
+ * A text component that applies the correct font styles based on the variant and size. variant
+ *
+ * @name Txt
+ */
+function Txt<As extends ElementType = 'span'>({
+    children,
+    as,
+    variant = 'body-base',
+    style: styleProp,
+    ...containerProps
+}: ElementProps<TxtProps<As>, As>) {
+    const content = children?.toString();
+
+    if (!content) return null;
+
+    const As: ElementType = as || 'span';
+
+    return (
+        <As
+            {...containerProps}
+            css={css`
+                font: var(--${variant});
+            `}
+            data-txt
+            style={styleProp}
+        >
+            {content}
+        </As>
+    );
+}
+
+Txt.bspkName = 'Txt';
+
+export { Txt };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useCheckboxGroupState.ts

@@ -0,0 +1,79 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { CheckboxProps } from '../Checkbox';
+
+/**
+ * A hook to manage the state of a group of checkboxes. Used alongside the CheckboxGroup component.
+ *
+ * @example
+ *     import { Checkbox } from "@bspk/ui/Checkbox";
+ *     import { useCheckboxGroupState } from "@bspk/ui/hooks/useCheckboxGroupState";
+ *
+ *     export function Example() {
+ *     const allValues = ["Red", "Orange", "Yellow", "Green"];
+ *
+ *     const { allCheckboxProps, checkboxProps, values } = useCheckboxGroupState(allValues, "fruits");
+ *
+ *     return (
+ *     <>
+ *     <pre>Selected Values: {values.join(", ")}</pre>
+ *     <Checkbox aria-label="All" {...allCheckboxProps} />
+ *     {allValues.map((value) => (
+ *     <Checkbox key={value} aria-label={value} {...checkboxProps(value)} />
+ *     ))}
+ *     </>
+ *     );
+ *     }
+ *
+ * @param allValues - The values of the checkboxes.
+ * @param name - The name of the checkboxes.
+ * @param externalState - The externally managed state of the checkboxes.
+ * @returns Properties to pass to the checkbox, other helper functions, and the state of the checkbox.
+ */
+export function useCheckboxGroupState(
+    allValues: string[],
+    name: string,
+    externalState?: [values: string[], setValues: (next: string[]) => void],
+) {
+    const localState = useState<string[]>([]);
+    const [values, setValues] = externalState || localState;
+
+    const toggleValue = useCallback(
+        (itemValue: string, checked: boolean) => {
+            setValues(
+                allValues.flatMap((value) => {
+                    if (value === itemValue) return checked ? value : [];
+                    return values.includes(value) ? value : [];
+                }),
+            );
+        },
+        [allValues, setValues, values],
+    );
+
+    const checkboxProps = useCallback(
+        (value: string): Pick<CheckboxProps, 'checked' | 'name' | 'onChange' | 'value'> => ({
+            checked: values.includes(value),
+            name,
+            onChange: (checked) => toggleValue(value, checked),
+            value,
+        }),
+        [values, name, toggleValue],
+    );
+
+    const allCheckboxProps = useMemo((): Pick<
+        CheckboxProps,
+        'checked' | 'indeterminate' | 'name' | 'onChange' | 'value'
+    > => {
+        return {
+            checked: allValues.length === values.length,
+            indeterminate: values.length > 0 && values.length < allValues.length,
+            name,
+            onChange: () => setValues(allValues.length === values.length ? [] : allValues),
+            value: 'all',
+        };
+    }, [allValues, values.length, name, setValues]);
+
+    return { toggleValue, allCheckboxProps, checkboxProps, values, setValues };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useCheckboxState.ts

@@ -0,0 +1,48 @@
+import { useState } from 'react';
+
+import { CheckboxProps } from '../Checkbox';
+
+/**
+ * A hook to manage the state of a single checkbox. Used alongside the Checkbox component.
+ *
+ * @example
+ *     import { Checkbox } from '@bspk/ui/Checkbox';
+ *     import { useCheckboxState } from '@bspk/ui/hooks/useCheckboxState';
+ *
+ *     export function Example() {
+ *     const { checkboxProps } = useCheckboxState('fruits');
+ *     return <Checkbox aria-label="cherry" {...checkboxProps('cherry')} />;
+ *     }
+ *
+ * @param name - The name of the checkbox.
+ * @param externalState - The externally managed state of the checkbox.
+ * @returns Properties to pass to the checkbox and the state of the checkbox.
+ */
+export function useCheckboxState(
+    name: string,
+    externalState?: [value: string[] | undefined, onChange: (next: string[]) => void],
+): {
+    checkboxProps: (value: string) => Pick<CheckboxProps, 'checked' | 'name' | 'onChange' | 'value'>;
+    value: string[] | undefined;
+    setValue: (next: string[]) => void;
+} {
+    const localState = useState<string[]>();
+    const [value, setValue] = externalState || localState;
+
+    const checkboxProps = (checkboxValue: string): Pick<CheckboxProps, 'checked' | 'name' | 'onChange' | 'value'> => {
+        return {
+            name,
+            checked: value?.includes(checkboxValue),
+            value: checkboxValue,
+            onChange: (checked) => {
+                const next = (value || []).filter((v) => v !== checkboxValue);
+                if (checked) next.push(checkboxValue);
+                setValue(next);
+            },
+        };
+    };
+
+    return { checkboxProps, value, setValue };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/hooks/useFloating.ts

@@ -0,0 +1,202 @@
+/**
+ * Custom hook to manage the positioning of a floating element relative to a reference element.
+ *
+ * @template ReferenceType - The type of the reference element, extending HTMLElement.
+ * @param {Object} params - The parameters for the hook.
+ * @param {Placement} params.placement - The preferred placement of the floating element.
+ * @param {React.MutableRefObject<HTMLElement | null>} [params.arrowRef] - A ref object for the arrow element.
+ * @param {Strategy} [params.strategy] - The positioning strategy ('absolute' or 'fixed').
+ * @param {OffsetOptions} [params.offsetOptions=0] - The offset options for the floating element. Default is `0`
+ * @param {boolean} [params.refWidth] - Whether to match the width of the floating element to the reference element.
+ * @param {boolean} [params.hide=false] - Whether to hide the floating element. Default is `false`
+ */
+import {
+    computePosition,
+    ComputePositionReturn,
+    Placement,
+    arrow,
+    Strategy,
+    offset,
+    flip,
+    autoUpdate,
+    MiddlewareData,
+    OffsetOptions,
+    size,
+    MiddlewareState,
+} from '@floating-ui/dom';
+import { useCallback, useEffect, useState } from 'react';
+
+import { useTimeout } from './useTimeout';
+
+export type { Placement, Strategy };
+
+const TRANSITION_DELAY = 250;
+
+/**
+ *
+ *
+ * @param param0
+ * @returns
+ */
+export function useFloating<TriggerElementType extends HTMLElement>({
+    placement,
+    arrowRef,
+    strategy,
+    offsetOptions = 0,
+    refWidth,
+    hide = false,
+}: {
+    placement: Placement;
+    arrowRef?: React.MutableRefObject<HTMLElement | null>;
+    strategy?: Strategy;
+    offsetOptions?: OffsetOptions;
+    refWidth?: boolean;
+    hide?: boolean;
+}) {
+    const [floatingStyles, setFloatingStylesState] = useState<React.CSSProperties>({
+        opacity: 0,
+        pointerEvents: 'none',
+        display: 'none',
+    });
+
+    const setFloatingStyles = (next: (prev: React.CSSProperties) => React.CSSProperties) => {
+        setFloatingStylesState((prev) => ({
+            transition: `opacity ${TRANSITION_DELAY}ms`,
+            ...next(prev),
+        }));
+    };
+
+    const [middlewareData, setMiddlewareData] = useState<MiddlewareData>({});
+
+    const [triggerElement, setTriggerElement] = useState<TriggerElementType | null>(null);
+
+    const [floatingElement, setFloatingElement] = useState<HTMLElement | null>(null);
+
+    // const elements: {
+    //   trigger: HTMLElement | null;
+    //   floating: HTMLElement | null;
+    //   setReference: (node: TriggerElementType | null) => void;
+    //   setFloating: (node: HTMLElement | null) => void;
+    // } = {
+    //   trigger: triggerElement,
+    //   floating: floatingElement,
+    //   setReference: setTriggerElement,
+    //   setFloating: setFloatingElement,
+    // };
+
+    const computeDebounce = useTimeout();
+    const transitionDelay = useTimeout();
+
+    const compute = useCallback(() => {
+        computeDebounce.clear();
+        transitionDelay.clear();
+
+        // check if the reference or floating element is null
+        if (triggerElement === null || floatingElement === null) return;
+
+        if (hide) {
+            if (floatingElement?.style.top)
+                setFloatingStyles((prev) => ({
+                    ...prev,
+                    display: undefined,
+                    opacity: 0,
+                    pointerEvents: 'none',
+                }));
+
+            transitionDelay.set(() => {
+                setFloatingStyles((prev) => ({
+                    ...prev,
+                    display: 'none',
+                }));
+            }, TRANSITION_DELAY);
+            return;
+        }
+
+        // debounce the computePosition call
+
+        computeDebounce.set(() => {
+            // check again if the reference or floating element is null
+            if (hide || triggerElement === null || floatingElement === null) return;
+
+            computePosition(triggerElement, floatingElement, {
+                placement: placement,
+                strategy,
+                middleware: [
+                    arrowRef?.current && arrow({ element: arrowRef.current, padding: 8 }),
+                    offset(offsetOptions),
+                    flip(),
+                    refWidth &&
+                        size({
+                            apply({ rects, elements }: MiddlewareState) {
+                                Object.assign(elements.floating.style, {
+                                    width: `${rects.reference.width}px`,
+                                });
+                            },
+                        }),
+                ],
+            }).then((value: ComputePositionReturn) => {
+                setFloatingStyles(() => ({
+                    top: value.y,
+                    left: value.x,
+                    position: value.strategy,
+                    opacity: 0,
+                    pointerEvents: 'none',
+                    display: undefined,
+                }));
+
+                transitionDelay.set(() => {
+                    setFloatingStyles((prev) => ({
+                        ...prev,
+                        opacity: 1,
+                        pointerEvents: 'auto',
+                        display: undefined,
+                    }));
+                }, 10);
+
+                setMiddlewareData(value.middlewareData);
+            });
+        }, 10);
+    }, [
+        computeDebounce,
+        transitionDelay,
+        triggerElement,
+        floatingElement,
+        hide,
+        placement,
+        strategy,
+        arrowRef,
+        offsetOptions,
+        refWidth,
+    ]);
+
+    useEffect(() => {
+        compute();
+        return () => {
+            computeDebounce.clear();
+            transitionDelay.clear();
+        };
+    }, [compute, computeDebounce, hide, transitionDelay]);
+
+    useEffect(() => {
+        if (hide || triggerElement === null || floatingElement === null) return;
+
+        const cleanup = autoUpdate(triggerElement, floatingElement, compute);
+
+        return () => {
+            cleanup();
+        };
+    }, [compute, hide, floatingElement, triggerElement]);
+
+    return {
+        elements: {
+            trigger: triggerElement,
+            floating: floatingElement,
+            setTrigger: setTriggerElement,
+            setFloating: setFloatingElement,
+        },
+        floatingStyles,
+        middlewareData,
+    };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */