@bspk/ui 1.3.8 → 1.3.9

package/src/components/Tooltip/Tooltip.tsx

@@ -44,13 +44,9 @@ export type TooltipProps = {
  *     import { Tooltip } from '@bspk/ui/Tooltip';
  *     import { Button } from '@bspk/ui/Button';
  *
- *     function Example() {
- *         return (
- *             <Tooltip label="I explain what this button does" placement="top">
- *                 {(triggerProps) => <Button {...triggerProps}>Click me</Button>}
- *             </Tooltip>
- *         );
- *     }
+ *     <Tooltip label="I explain what this button does" placement="top">
+ *         {(triggerProps) => <Button {...triggerProps}>Click me</Button>}
+ *     </Tooltip>;
  *
  * @name Tooltip
  * @phase UXReview

package/src/components/Tooltip/TooltipExample.tsx

@@ -1,17 +1,29 @@
 import { TooltipProps } from './Tooltip';
-import { Button } from '-/components/Button';
 import { ComponentExample } from '-/utils/demo';
 
 export const TooltipExample: ComponentExample<TooltipProps> = {
-    render: ({ props: state, Component }) => {
-        return (
-            <Component
-                {...state}
-                label={`Hover over me ${state.label || ''}`}
-                placement={[state.placement].flat()[0] || 'top'}
-            >
-                {(triggerProps) => <Button {...triggerProps} label="Hover over me" variant="secondary" />}
-            </Component>
-        );
+    defaultState: {
+        children: (triggerProps) => <span {...triggerProps}>Hover me</span>,
+    },
+    presets: [
+        {
+            label: 'Long Label Tooltip',
+            propState: {
+                label: 'This is a longer tooltip label to demonstrate how the tooltip handles more content.',
+                placement: 'top',
+                children: (triggerProps) => <span {...triggerProps}>Long Tooltip Label</span>,
+            },
+        },
+        {
+            label: 'No Label',
+            propState: {
+                label: '',
+                placement: 'top',
+                children: (triggerProps) => <span {...triggerProps}>No Label</span>,
+            },
+        },
+    ],
+    render: ({ props, Component }) => {
+        return <Component {...props}>{props.children || (() => <span>No Hover</span>)}</Component>;
     },
 };

package/src/components/Txt/Txt.tsx

@@ -49,9 +49,7 @@ export type TxtProps<As extends ElementType = ElementType> = {
  * @example
  *     import { Txt } from '@bspk/ui/Txt';
  *
- *     function Example() {
- *         return <Txt>Example Txt</Txt>;
- *     }
+ *     <Txt>Example Txt</Txt>;
  *
  * @name Txt
  * @phase UXReview

package/src/components/UIProvider/AriaLiveMessageHandler.tsx

@@ -3,8 +3,10 @@ import { useEventListener } from '-/hooks/useAddEventListener';
 import { useTimeout } from '-/hooks/useTimeout';
 import { AriaLiveMessage } from '-/utils/uiContext';
 
+const CUSTOM_EVENT_NAME = 'bspk-aria-live';
+
 export function sendAriaLiveMessage(message: string, live: 'assertive' | 'polite' = 'polite') {
-    document.dispatchEvent(new CustomEvent('aria-live', { detail: { message, live } }));
+    document.dispatchEvent(new CustomEvent(CUSTOM_EVENT_NAME, { detail: { message, live } }));
 }
 
 /**
@@ -24,7 +26,7 @@ export function AriaLiveMessageHandler() {
     const timeout = useTimeout();
 
     useEventListener(
-        'aria-live',
+        CUSTOM_EVENT_NAME,
         (event: CustomEvent) => {
             const { message, live } = event.detail;
             // Clear any existing message to ensure that screen readers read the new message

package/src/hooks/useAddEventListener.ts

@@ -2,15 +2,13 @@ import { useRef } from 'react';
 
 import { useIsomorphicEffect } from './useIsomorphicEffect';
 
-export type CustomEventName = 'aria-live';
-
 export function useEventListener<
     KW extends keyof WindowEventMap,
     KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
     KM extends keyof MediaQueryListEventMap,
     T extends Document | HTMLElement | MediaQueryList | SVGAElement | Window = HTMLElement,
 >(
-    eventName: CustomEventName | KH | KM | KW,
+    eventName: KH | KM | KW | string,
     handler: (
         event:
             | Event

package/src/hooks/useTimeout.ts

@@ -25,15 +25,11 @@ export type TimeoutHook = {
  *
  * @returns A ref object that can be used to store a timeout id.
  */
-export function useTimeout(): TimeoutHook;
-export function useTimeout(initialCallback: () => void, durationMs: number): TimeoutHook;
-export function useTimeout(initialCallback?: () => void, durationMs = 1000): TimeoutHook {
+export function useTimeout(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(

package/src/types/common.ts

@@ -6,6 +6,7 @@
  * @bspk/ui/Txt".
  */
 
+import { IconName } from '@bspk/icons';
 import {
     JSXElementConstructor,
     ReactNode,
@@ -40,6 +41,9 @@ export type DataProps = Record<`data-${string}`, string>;
 
 export type ButtonSize = 'large' | 'medium' | 'small' | 'x-small';
 
+/** The name of an icon in the Bspk icon library. */
+export type BspkIcon = IconName;
+
 export type CallToActionButton = {
     /**
      * The label of the call to action button.

package/src/types/meta.ts

@@ -77,6 +77,7 @@ export type TypeProperty = {
     minimum?: number;
     maximum?: number;
     example?: string;
+    arrayType?: string;
 };
 
 export type ComponentMeta = BaseMeta & {

package/src/utils/createCustomEvent.ts

@@ -0,0 +1,35 @@
+import { useEventListener } from '-/hooks/useAddEventListener';
+
+export type CustomEventDetail =
+    | Array<CustomEventDetail>
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    | Function
+    | boolean
+    | number
+    | string
+    | { [key: string]: CustomEventDetail }
+    | null
+    | undefined;
+
+export type CustomEventHandler<TDetail extends CustomEventDetail> = (detail: TDetail) => void;
+
+/**
+ * Like React.createContext but for custom events using the DOM's CustomEvent system.
+ *
+ * This allows for communication between components without using React.Context, which can cause unnecessary re-renders.
+ *
+ * This generator ensures only safe detail types are used. !important;
+ */
+export function createCustomEvent<TDetail extends CustomEventDetail>(
+    /** The name of the custom event to create. Prefix with 'bspk-' to avoid conflicts. */
+    eventName: string,
+) {
+    return {
+        send(detail: TDetail) {
+            document.dispatchEvent(new CustomEvent<TDetail>(eventName, { detail }));
+        },
+        useEventListener(listener: CustomEventHandler<TDetail>) {
+            useEventListener(eventName, (event) => listener((event as CustomEvent<TDetail>).detail), document);
+        },
+    };
+}

package/src/utils/createExampleChildElement.tsx

@@ -1,11 +1,10 @@
 /* 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 { Button } from '-/components/Button';
 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';
@@ -55,14 +54,10 @@ export function createExampleChildElement({ exampleState, name, setState, action
         };
     }
 
-    if (componentName === 'ListItemButton')
+    if (componentName === 'Button')
         return {
             element: (
-                <ListItem.Button
-                    icon={<SvgContentCopy />}
-                    label="LI Button"
-                    onClick={() => action('ListItem button clicked')}
-                />
+                <Button icon={<SvgContentCopy />} label="LI Button" onClick={() => action('ListItem button clicked')} />
             ),
             componentName,
         };

package/src/utils/demo.ts

@@ -2,22 +2,7 @@
 
 import { CSSProperties, ReactNode } from 'react';
 import { AlertVariant, DataProps } from '-/types/common';
-import { ComponentMeta } from '-/types/meta';
-
-export type TypeProperty = {
-    name: string;
-    description?: string;
-    type?: string[] | string;
-    default?: unknown;
-    required?: boolean;
-    options?: number[] | string[];
-    variants?: string[];
-    references?: string[];
-    minimum?: number;
-    maximum?: number;
-    example?: string;
-    exampleType?: string;
-};
+import { ComponentMeta, TypeProperty } from '-/types/meta';
 
 export type DemoAction = (message: string, variant?: AlertVariant) => void;
 
@@ -59,8 +44,24 @@ export type ComponentVariantOverride<Props> = {
     [K in keyof Props]?: Props[K] | { options: Props[K][] };
 };
 
+export type ComponentPageSection<Props = Record<string, unknown>> = {
+    title: string;
+    content: (params: {
+        Component?: React.ComponentType<Props>;
+        props: Props;
+        CodeExample: CodeExample;
+        Syntax: Syntax;
+    }) => React.ReactNode;
+    location?: 'afterDemo' | 'beforeDemo';
+};
+
 export type ComponentVariantOverrides<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
-    [Key in PropName]?: ComponentVariantOverride<Props> | false | ((props: Props) => ComponentVariantOverride<Props>);
+    /**
+     * Hide the variant entirely by setting to false.
+     *
+     * Set specific prop overrides for the variant. e.g. when demoing iconOnly, we want to set the icon prop.
+     */
+    [Key in PropName]?: ComponentVariantOverride<Props> | false;
 };
 
 export type ComponentExample<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
@@ -106,16 +107,7 @@ export type ComponentExample<Props = Record<string, unknown>, PropName extends k
      */
     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;
-        location?: 'afterDemo' | 'beforeDemo';
-    }[];
+    sections?: ComponentPageSection<Props>[];
 };
 
 export type Syntax = (params: {
@@ -148,6 +140,11 @@ export type ComponentExampleFn<Props = Record<string, unknown>> = (params: {
 export type OnHandlers = `on${string}`;
 
 export type Preset<Props> = {
+    /**
+     * A description of the design pattern this preset demonstrates. When applied, it showcases the specific use case or
+     * behavior of the component.
+     */
+    designPattern?: string;
     /** 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. */

package/dist/components/ListItem/ListItemButton.d.ts

@@ -1,2 +0,0 @@
-import { ButtonProps } from '-/components/Button';
-export declare function ListItemButton({ label, icon, ...buttonProps }: Pick<ButtonProps, 'icon' | 'label' | 'onClick'>): import("react/jsx-runtime").JSX.Element;

package/dist/components/ListItem/ListItemButton.js

@@ -1,7 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { Button } from '../Button';
-// A button that can be used as a trailing element in a ListItem.
-export function ListItemButton({ label, icon, ...buttonProps }) {
-    return _jsx(Button, { icon: icon, iconOnly: true, label: label, ...buttonProps, size: "large", variant: "tertiary" });
-}
-//# sourceMappingURL=ListItemButton.js.map

package/dist/components/ListItem/ListItemButton.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ListItemButton.js","sourceRoot":"","sources":["../../../src/components/ListItem/ListItemButton.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAe,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE1D,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,EAAmD;IAC3G,OAAO,KAAC,MAAM,IAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,QAAC,KAAK,EAAE,KAAK,KAAM,WAAW,EAAE,IAAI,EAAC,OAAO,EAAC,OAAO,EAAC,UAAU,GAAG,CAAC;AAC1G,CAAC"}

package/dist/components/Pagination/PageInput.d.ts

@@ -1,4 +0,0 @@
-import { FC } from 'react';
-import { PaginationProps } from './Pagination';
-export type PageInputProps = Pick<PaginationProps, 'numPages' | 'onChange' | 'value'>;
-export declare const PageInput: FC<PageInputProps>;

package/dist/components/Pagination/PageInput.js

@@ -1,36 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
-import { Input } from '../Input';
-import { Txt } from '../Txt';
-export const PageInput = ({ numPages, onChange, value }) => {
-    const [page, setPage] = useState(String(value));
-    useEffect(() => {
-        const stringValue = String(value);
-        if (stringValue !== page) {
-            setPage(stringValue);
-        }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [value]);
-    const handleChange = (val) => {
-        const pageNumber = parseInt(val, 10);
-        const isValidPageNumber = !isNaN(pageNumber) && pageNumber >= 1 && pageNumber <= numPages;
-        if (isValidPageNumber || val === '') {
-            setPage(val);
-        }
-    };
-    const handleSubmit = () => {
-        const pageNumber = parseInt(page, 10);
-        if (!isNaN(pageNumber) && pageNumber >= 1 && pageNumber <= numPages) {
-            onChange(pageNumber);
-        }
-        else {
-            setPage(String(value));
-        }
-    };
-    const pageCountMessage = `of ${numPages}`;
-    return (_jsx("form", { onSubmit: (e) => {
-            e.preventDefault();
-            handleSubmit();
-        }, style: { display: 'contents' }, children: _jsxs("div", { "data-bspk": "page-input", children: [_jsx(Input, { "aria-label": "Page input", name: "page-input", onBlur: handleSubmit, onChange: handleChange, showClearButton: false, size: "small", value: page }), _jsx(Txt, { variant: "body-small", children: pageCountMessage })] }) }));
-};
-//# sourceMappingURL=PageInput.js.map

package/dist/components/Pagination/PageInput.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"PageInput.js","sourceRoot":"","sources":["../../../src/components/Pagination/PageInput.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAM,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGhD,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAIvC,MAAM,CAAC,MAAM,SAAS,GAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;IAC3E,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAS,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAExD,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAElC,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,CAAC,WAAW,CAAC,CAAC;QACzB,CAAC;QACD,uDAAuD;IAC3D,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,EAAE;QACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACrC,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,UAAU,IAAI,QAAQ,CAAC;QAE1F,IAAI,iBAAiB,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,GAAG,EAAE;QACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAEtC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAClE,QAAQ,CAAC,UAAU,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3B,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,gBAAgB,GAAG,MAAM,QAAQ,EAAE,CAAC;IAE1C,OAAO,CACH,eACI,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE;YACZ,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,YAAY,EAAE,CAAC;QACnB,CAAC,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,YAE9B,4BAAe,YAAY,aACvB,KAAC,KAAK,kBACS,YAAY,EACvB,IAAI,EAAC,YAAY,EACjB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,eAAe,EAAE,KAAK,EACtB,IAAI,EAAC,OAAO,EACZ,KAAK,EAAE,IAAI,GACb,EAEF,KAAC,GAAG,IAAC,OAAO,EAAC,YAAY,YAAE,gBAAgB,GAAO,IAChD,GACH,CACV,CAAC;AACN,CAAC,CAAC"}

package/dist/hooks/usePaginationState.d.ts

@@ -1,4 +0,0 @@
-export declare const usePaginationState: (numPages: number, initialPage?: number) => {
-    currentPage: number;
-    setCurrentPage: (page: number) => void;
-};

package/dist/hooks/usePaginationState.js

@@ -1,22 +0,0 @@
-import { useState } from 'react';
-/*
-    * A hook to manage the state of pagination.
-
-    * @param numPages - The total number of pages.
-    * @param initialPage - The initial page to start on (default is 1).
-    * @returns An object containing the current page and a function to set the current page.
-    */
-export const usePaginationState = (numPages, initialPage) => {
-    const [currentPage, setCurrentPage] = useState(initialPage || 1);
-    const setPage = (page) => {
-        if (page < 1 || page > numPages) {
-            return;
-        }
-        setCurrentPage(page);
-    };
-    return {
-        currentPage,
-        setCurrentPage: setPage,
-    };
-};
-//# sourceMappingURL=usePaginationState.js.map

package/dist/hooks/usePaginationState.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"usePaginationState.js","sourceRoot":"","sources":["../../src/hooks/usePaginationState.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;MAMM;AACN,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAE,WAAoB,EAAE,EAAE;IACzE,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;IAEjE,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE;QAC7B,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;YAC9B,OAAO;QACX,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;IAEF,OAAO;QACH,WAAW;QACX,cAAc,EAAE,OAAO;KAC1B,CAAC;AACN,CAAC,CAAC"}

package/src/components/ListItem/ListItemButton.tsx

@@ -1,6 +0,0 @@
-import { ButtonProps, Button } from '-/components/Button';
-
-// A button that can be used as a trailing element in a ListItem.
-export function ListItemButton({ label, icon, ...buttonProps }: Pick<ButtonProps, 'icon' | 'label' | 'onClick'>) {
-    return <Button icon={icon} iconOnly label={label} {...buttonProps} size="large" variant="tertiary" />;
-}

package/src/components/Pagination/PageInput.tsx

@@ -1,65 +0,0 @@
-import { FC, useEffect, useState } from 'react';
-
-import { PaginationProps } from './Pagination';
-import { Input } from '-/components/Input';
-import { Txt } from '-/components/Txt';
-
-export type PageInputProps = Pick<PaginationProps, 'numPages' | 'onChange' | 'value'>;
-
-export const PageInput: FC<PageInputProps> = ({ numPages, onChange, value }) => {
-    const [page, setPage] = useState<string>(String(value));
-
-    useEffect(() => {
-        const stringValue = String(value);
-
-        if (stringValue !== page) {
-            setPage(stringValue);
-        }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [value]);
-
-    const handleChange = (val: string) => {
-        const pageNumber = parseInt(val, 10);
-        const isValidPageNumber = !isNaN(pageNumber) && pageNumber >= 1 && pageNumber <= numPages;
-
-        if (isValidPageNumber || val === '') {
-            setPage(val);
-        }
-    };
-
-    const handleSubmit = () => {
-        const pageNumber = parseInt(page, 10);
-
-        if (!isNaN(pageNumber) && pageNumber >= 1 && pageNumber <= numPages) {
-            onChange(pageNumber);
-        } else {
-            setPage(String(value));
-        }
-    };
-
-    const pageCountMessage = `of ${numPages}`;
-
-    return (
-        <form
-            onSubmit={(e) => {
-                e.preventDefault();
-                handleSubmit();
-            }}
-            style={{ display: 'contents' }}
-        >
-            <div data-bspk="page-input">
-                <Input
-                    aria-label="Page input"
-                    name="page-input"
-                    onBlur={handleSubmit}
-                    onChange={handleChange}
-                    showClearButton={false}
-                    size="small"
-                    value={page}
-                />
-
-                <Txt variant="body-small">{pageCountMessage}</Txt>
-            </div>
-        </form>
-    );
-};

package/src/hooks/usePaginationState.tsx

@@ -1,24 +0,0 @@
-import { useState } from 'react';
-
-/*
-    * A hook to manage the state of pagination.
-
-    * @param numPages - The total number of pages.
-    * @param initialPage - The initial page to start on (default is 1).
-    * @returns An object containing the current page and a function to set the current page.
-    */
-export const usePaginationState = (numPages: number, initialPage?: number) => {
-    const [currentPage, setCurrentPage] = useState(initialPage || 1);
-
-    const setPage = (page: number) => {
-        if (page < 1 || page > numPages) {
-            return;
-        }
-        setCurrentPage(page);
-    };
-
-    return {
-        currentPage,
-        setCurrentPage: setPage,
-    };
-};