@bspk/ui 1.3.19 → 1.3.20

package/dist/utils/demo.d.ts

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactNode } from 'react';
 import { AlertVariant, DataProps } from '-/types/common';
-import { ComponentMeta, TypeProperty } from '-/types/meta';
+import { BlockConfig, ComponentMeta, TypeProperty } from '-/types/meta';
 export type DemoAction = (message: string, variant?: AlertVariant) => void;
 export type DemoSetState<Props = Record<string, unknown>> = (next: Partial<Props> | ((prev: Props) => Partial<Props>)) => void;
 export type TypePropertyDemo = Omit<TypeProperty, 'example'> & {
@@ -32,11 +32,13 @@ export type ComponentVariantOverride<Props> = {
     };
 };
 export type ComponentPageSection<Props = Record<string, unknown>> = {
-    title: string;
-    content: (params: {
+    title?: string;
+    description?: string;
+    content?: (params: {
         Component?: React.ComponentType<Props>;
         props: Props;
         CodeExample: CodeExample;
+        CodePlayground: CodePlayground;
         Syntax: Syntax;
     }) => React.ReactNode;
     location?: 'afterDemo' | 'beforeDemo';
@@ -44,7 +46,7 @@ export type ComponentPageSection<Props = Record<string, unknown>> = {
 export type ComponentVariantOverrides<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
     [Key in PropName]?: ComponentVariantOverride<Props> | false;
 };
-export type ComponentExample<Props = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
+export type ComponentExample<Props extends Record<string, unknown> = Record<string, unknown>, PropName extends keyof Props = keyof Props> = {
     /**
      * The style of the wrapping component.
      *
@@ -100,6 +102,14 @@ export type ComponentExample<Props = Record<string, unknown>, PropName extends k
      * @default false
      */
     hideDemo?: boolean;
+    /**
+     * Hide the usage section entirely.
+     *
+     * @default false
+     */
+    hideUsage?: boolean;
+    /** Block Configs */
+    blockConfigs?: BlockConfig[];
 };
 export type Syntax = (params: {
     code: string;
@@ -107,7 +117,7 @@ export type Syntax = (params: {
     style?: CSSProperties;
     pretty?: boolean;
 }) => React.ReactNode;
-export type CodeExample = (params: DataProps & {
+export type CodeExample = (params: DataProps & any & {
     containerStyle?: CSSProperties;
     children: ReactNode;
     accessibility?: boolean;
@@ -115,9 +125,15 @@ export type CodeExample = (params: DataProps & {
         language?: PrettyParser | undefined;
         str: string;
     };
-}) => React.ReactNode;
+    style?: CSSProperties;
+}) => JSX.Element;
+export type CodePlaygroundProps = {
+    defaultCode: string;
+    defaultShowCode?: boolean;
+};
+export type CodePlayground = (params: CodePlaygroundProps) => JSX.Element;
 export type PrettyParser = 'css' | 'estree' | 'html' | 'scss' | 'typescript';
-export type ComponentExampleFn<Props = Record<string, unknown>> = (params: {
+export type ComponentExampleFn<Props extends Record<string, unknown> = Record<string, unknown>> = (params: {
     setState: DemoSetState<Props>;
     action: DemoAction;
     componentsMeta: ComponentMeta[];
@@ -134,13 +150,21 @@ export type Preset<Props> = {
     /** The props of the component. This is used to set props of the component. These values can't be changed in the UI. */
     propState: Omit<Props, OnHandlers> & Record<OnHandlers, unknown>;
     /**
-     * Hide the demo for this preset.
+     * Hide the demo option for this preset.
      *
      * @default false
      */
-    hideDemo?: boolean;
+    hideDemoOption?: boolean;
+    /** Hide the playground for this preset. */
+    hidePlayground?: boolean;
+    /** Preset used for block examples. */
+    block?: boolean;
 };
 export type DemoPreset<P = Record<string, unknown>> = Preset<P> & {
     value: string;
 };
 export declare function createUid(prefix?: string): string;
+export declare function reactElementToString(element: React.ReactElement): string;
+export declare function componentToString<Props extends Record<string, any> = Record<string, any>>(componentName: string, propState: Props, propsMeta?: TypePropertyDemo[]): string;
+export declare function kebabCase(str: string): string;
+export declare function convertReactToCodeString(element: React.ReactElement): string;

package/dist/utils/demo.js

@@ -1,4 +1,102 @@
+import { isValidElement } from 'react';
 export function createUid(prefix = 'uid') {
     return `${prefix}-${Math.random().toString(36).substring(2, 9)}`;
 }
+export function reactElementToString(element) {
+    if (!isReactElement(element))
+        return '';
+    const subComponentName = typeof element.type === 'string' ? element.type : element.type.name || 'Component';
+    return componentToString(subComponentName, element.props);
+}
+export function componentToString(componentName, propState, propsMeta) {
+    const propsString = Object.entries(propState)
+        .map(([key, value]) => {
+        const propMeta = propsMeta?.find((prop) => prop.name === key);
+        let formattedValue;
+        if (typeof value === 'string') {
+            formattedValue = `"${value}"`;
+            if (propMeta?.type === 'BspkIcon')
+                formattedValue = `{<Svg${value} />}`;
+        }
+        else if (typeof value === 'boolean' || typeof value === 'number') {
+            formattedValue = `{${value}}`;
+        }
+        else if (isReactElement(value)) {
+            const subComponentName = typeof value.type === 'string' ? value.type : value.type.name || 'Component';
+            formattedValue = `{${componentToString(subComponentName, value.props)}}`;
+        }
+        else if (Array.isArray(value)) {
+            return ` ${key}={[${value
+                .map((item) => (isValidElement(item) ? convertReactToCodeString(item) : '...')) // Simplified for brevity
+                .join(', ')}]}`;
+        }
+        else if (typeof value === 'object') {
+            formattedValue = `{${JSON.stringify(value, null, 2)}}`;
+        }
+        else if (value === null) {
+            formattedValue = '{null}';
+        }
+        else if (value === undefined) {
+            return ''; // skip undefined props
+        }
+        else {
+            formattedValue = `{${value.toString()}}`;
+        }
+        return `    ${key}=${formattedValue}`;
+    })
+        .filter(Boolean)
+        .join('\n');
+    return `<${componentName}\n${propsString}\n/>`;
+}
+function isReactElement(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        (value.$$typeof === Symbol.for('react.element') ||
+            (value.type && (typeof value.type === 'string' || typeof value.type === 'function'))));
+}
+export function kebabCase(str) {
+    return (str
+        .normalize('NFD') // Normalize to decompose accents
+        .replace(/[\u0300-\u036f&()']/g, '') // Remove accents
+        // Handle camelCase by inserting hyphens between lowercase and uppercase
+        .replace(/([a-zA-Z])([A-Z][a-z])/g, '$1-$2')
+        // do it again for the next uppercase letter
+        .replace(/([a-zA-Z])([A-Z][a-z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-') // Replace non-alphanumeric characters with hyphens
+        .replace(/^-+|-+$/g, '') // Trim leading or trailing hyphens
+        .replace(/--+/g, '-') // Replace multiple hyphens with a single hyphen
+        .toLowerCase()); // Convert to lowercase
+}
+export function convertReactToCodeString(element) {
+    return `<${element.type}${Object.entries(element.props)
+        .map(([key, value]) => {
+        if (typeof value === 'string') {
+            return ` ${key}="${value}"`;
+        }
+        else if (typeof value === 'number' || typeof value === 'boolean') {
+            return ` ${key}={${value}}`;
+        }
+        else if (typeof value === 'function') {
+            return ` ${key}={() => {}}`;
+        }
+        else if (isValidElement(value)) {
+            return ` ${key}={${convertReactToCodeString(value)}}`;
+        }
+        else if (Array.isArray(value)) {
+            return ` ${key}={[${value
+                .map((item) => (isValidElement(item) ? convertReactToCodeString(item) : '...')) // Simplified for brevity
+                .join(', ')}]}`;
+        }
+        else if (value === null) {
+            return ` ${key}={null}`;
+        }
+        else if (value === undefined) {
+            return ` ${key}={undefined}`;
+        }
+        else {
+            return ` ${key}={${JSON.stringify(value)}}`;
+        }
+    })
+        .join('')}>${element.props.children ? '...' : ''}</${element.type}>`;
+}
 //# sourceMappingURL=demo.js.map

package/dist/utils/demo.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/utils/demo.ts"],"names":[],"mappings":"AA6KA,MAAM,UAAU,SAAS,CAAC,SAAiB,KAAK;IAC5C,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC"}
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/utils/demo.ts"],"names":[],"mappings":"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"}

package/meta.ts

@@ -14,7 +14,7 @@ import { fileURLToPath } from 'url';
 
 import * as TJS from 'typescript-json-schema';
 
-import { ComponentMeta, TypeProperty, UtilityMeta, TypeMeta, ComponentPhase } from './src/types/meta';
+import { ComponentMeta, TypeProperty, UtilityMeta, TypeMeta, ComponentPhase, BlockConfig } from './src/types/meta';
 
 const COMPONENT_PHASE_ORDER: ComponentPhase[] = [
     'Utility', // Utility components are not tracked in the progress
@@ -201,6 +201,15 @@ function generateComponentMeta({
           }
         : undefined;
 
+    const blockFilePath =
+        //
+        path.join(srcDir, 'components', name, `${name}BlockConfigs.tsx`);
+
+    let blockConfigs: BlockConfig[] | undefined;
+    if (fs.existsSync(blockFilePath)) {
+        blockConfigs = generateBlocksMeta(blockFilePath);
+    }
+
     return {
         description: componentDoc.description,
         file: componentFile.split(srcDir)[1],
@@ -214,6 +223,7 @@ function generateComponentMeta({
             ? componentDoc.phase
             : 'Backlog') as ComponentPhase,
         generated: 'generated' in componentDoc,
+        blockConfigs,
     } as ComponentMeta;
 }
 
@@ -608,6 +618,34 @@ async function main() {
     process.exit(0);
 }
 
+function generateBlocksMeta(blockFilePath: string) {
+    const blockFileContent = fs.readFileSync(path.resolve(blockFilePath), 'utf-8');
+
+    const exampleContent = blockFileContent.matchAll(/<BlockExample\s([\s\S]*?)<\/BlockExample>/g);
+
+    const blocks: BlockConfig[] = [...exampleContent].map((match) => {
+        const blockString = match[1];
+
+        const nameMatch = blockString.match(/name=["|'](.*?)["|']/);
+        const name = nameMatch ? nameMatch[1] : 'Unnamed Block';
+
+        const componentMatch = blockString.match(
+            /<BlockExample\.Component>\s*([\s\S]*?)\s*<\/BlockExample\.Component>/,
+        );
+        const component = componentMatch ? componentMatch[1].trim() : '';
+
+        const patternMatch = blockString.match(/<BlockExample\.Pattern>\s*([\s\S]*?)\s*<\/BlockExample\.Pattern>/);
+        const pattern = patternMatch ? patternMatch[1].trim() : '';
+
+        return {
+            name,
+            component,
+            pattern,
+        };
+    });
+
+    return blocks;
+}
 main();
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bspk/ui",
-    "version": "1.3.19",
+    "version": "1.3.20",
     "license": "CC-BY-4.0",
     "type": "module",
     "files": [
@@ -93,8 +93,6 @@
         "./Dialog/*": "./dist/components/Dialog/*.js",
         "./Divider": "./dist/components/Divider/index.js",
         "./Divider/*": "./dist/components/Divider/*.js",
-        "./Drawer": "./dist/components/Drawer/index.js",
-        "./Drawer/*": "./dist/components/Drawer/*.js",
         "./EmptyState": "./dist/components/EmptyState/index.js",
         "./EmptyState/*": "./dist/components/EmptyState/*.js",
         "./ExamplePlaceholder": "./dist/components/ExamplePlaceholder/index.js",

package/src/components/Accordion/AccordionExample.tsx

@@ -51,7 +51,7 @@ export const presets: Preset<AccordionProps>[] = [
     },
     {
         label: '1 disabled and open (but not showing)',
-        hideDemo: true,
+        hideDemoOption: true,
         propState: {
             items: [
                 {

package/src/components/BannerAlert/BannerAlert.tsx

@@ -94,7 +94,7 @@ export function BannerAlert({
             </div>
             <div data-content>
                 {(header || onClose) && (
-                    <header>
+                    <div data-header>
                         <span>{header}</span>
                         {typeof onClose === 'function' && (
                             <Button
@@ -106,7 +106,7 @@ export function BannerAlert({
                                 variant="tertiary"
                             />
                         )}
-                    </header>
+                    </div>
                 )}
                 <div data-body>
                     <span>{body}</span>

package/src/components/BannerAlert/banner-alert.scss

@@ -46,7 +46,7 @@
         flex-direction: column;
         padding: var(--spacing-sizing-02) var(--spacing-sizing-02) var(--spacing-sizing-02) var(--spacing-sizing-04);
 
-        header {
+        [data-header] {
             display: flex;
             flex-direction: row;
             gap: var(--spacing-sizing-03);

package/src/components/CheckboxOption/CheckboxOption.tsx

@@ -1,8 +1,22 @@
 import { CheckboxProps, Checkbox } from '-/components/Checkbox';
-import { ToggleOption, ToggleOptionControlProps } from '-/components/ToggleOption';
+import { ListItem } from '-/components/ListItem';
 import { CommonProps } from '-/types/common';
 
-export type CheckboxOptionProps = CommonProps<'style'> & ToggleOptionControlProps<CheckboxProps>;
+export type CheckboxOptionProps = CheckboxProps &
+    CommonProps<'style'> & {
+        /**
+         * The label of the option. Also used as the aria-label of the control.
+         *
+         * @required
+         */
+        label: string;
+        /**
+         * The description of the option.
+         *
+         * @type multiline
+         */
+        description?: string;
+    };
 
 /**
  * A control that allows users to choose one or more items from a list or turn an feature on or off.
@@ -39,20 +53,18 @@ export function CheckboxOption({
     style,
     ...checkboxProps
 }: CheckboxOptionProps) {
-    const label = labelProp || description;
     const ariaLabel = description ? `${labelProp} - ${description}` : labelProp;
     return (
-        label && (
-            <ToggleOption
-                data-bspk="checkbox-option"
-                description={description}
-                disabled={disabled}
-                label={label}
-                style={style}
-            >
-                <Checkbox {...checkboxProps} aria-label={ariaLabel} disabled={disabled} />
-            </ToggleOption>
-        )
+        <ListItem
+            aria-disabled={disabled || undefined}
+            as="label"
+            label={labelProp}
+            leading={<Checkbox {...checkboxProps} aria-label={ariaLabel} disabled={disabled} />}
+            owner="checkbox-option"
+            style={style}
+            subText={description}
+            width="hug"
+        />
     );
 }
 

package/src/components/Dialog/Dialog.tsx

@@ -54,11 +54,12 @@ export type DialogProps = CommonProps<'id' | 'owner'> &
     };
 
 /**
- * Dialogs display important information that users need to acknowledge. They appear over the interface and block
+ * Dialogs display important information that users need to acknowledge. They appear over the interface and may block
  * further interactions until an action is selected.
  *
- * This is a low-level component that provides the container and functionality for dialogs. You will typically want to
- * use a higher-level component that provides a consistent UI and behavior for dialogs such as Modal.
+ * The Modal component is a higher-level component built on top of Dialog that includes standard dialog UI and behavior.
+ *
+ * Also known as: Tray, Drawer, Flyout, Sheet
  *
  * @example
  *     import { Dialog } from '@bspk/ui/Dialog';
@@ -70,11 +71,20 @@ export type DialogProps = CommonProps<'id' | 'owner'> &
  *         return (
  *             <>
  *                 <Button label="Open Dialog" onClick={() => setOpen(true)} />
- *                 <Dialog open={open} onClose={() => setOpen(false)}>
+ *                 <Dialog onClose={() => setOpen(false)} open={open}>
  *                     <div style={{ padding: 'var(--spacing-sizing-04)' }}>
- *                         <h1>Dialog Title</h1>
+ *                         <Flex align="center" justify="space-between">
+ *                             <h4>Dialog Title</h4>
+ *                             <Button
+ *                                 icon={<SvgClose />}
+ *                                 iconOnly
+ *                                 label="Close dialog"
+ *                                 onClick={() => setOpen(false)}
+ *                                 variant="tertiary"
+ *                             />
+ *                         </Flex>
  *                         <p>This is the content of the dialog.</p>
- *                         <Button label="Cancel" variant="secondary" onClick={() => setOpen(false)} />
+ *                         <Button label="Cancel" onClick={() => setOpen(false)} variant="secondary" />
  *                     </div>
  *                 </Dialog>
  *             </>
@@ -82,7 +92,7 @@ export type DialogProps = CommonProps<'id' | 'owner'> &
  *     };
  *
  * @name Dialog
- * @phase Utility
+ * @phase Stable
  */
 export function Dialog({
     children,
@@ -119,6 +129,7 @@ export function Dialog({
                     {...containerProps}
                     data-bspk="dialog"
                     data-bspk-owner={owner || undefined}
+                    data-contained={!!container || undefined}
                     data-placement={placement}
                     id={id}
                     ref={innerRef}
@@ -144,9 +155,8 @@ export function Dialog({
                     </FocusTrap>
                 </div>
                 <Scrim
-                    onClick={() => {
-                        onClose();
-                    }}
+                    contained={!!container || undefined}
+                    onClick={() => onClose()}
                     owner="dialog"
                     visible={showScrim !== false}
                 />

package/src/components/Dialog/DialogExample.tsx

@@ -1,8 +1,9 @@
-import { DialogProps } from '.';
+import { SvgClose } from '@bspk/icons/Close';
+import { useRef, useState } from 'react';
+import { Dialog, DialogProps } from '.';
 import { Button } from '-/components/Button';
-import { ComponentExample, Preset } from '-/utils/demo';
-
-export const presets: Preset<DialogProps>[] = [];
+import { Flex } from '-/components/Flex';
+import { ComponentExample } from '-/utils/demo';
 
 export const DialogExample: ComponentExample<DialogProps> = {
     render: ({ props, setState, Component }) => {
@@ -11,11 +12,108 @@ export const DialogExample: ComponentExample<DialogProps> = {
             <>
                 <Button label={label} onClick={() => setState({ open: true })} />
                 <Component data-example-component {...props} id="exampleId" onClose={() => setState({ open: false })}>
-                    <div style={{ padding: 'var(--spacing-sizing-04)' }}>Hello, I am a ({props.placement}) dialog!</div>
+                    <div style={{ padding: 'var(--spacing-sizing-04)' }}>
+                        <Flex
+                            align="center"
+                            justify="space-between"
+                            style={{
+                                width: '100%',
+                                marginBottom: 'var(--spacing-sizing-04)',
+                            }}
+                        >
+                            <h4>Dialog</h4>
+                            <Button
+                                icon={<SvgClose />}
+                                iconOnly
+                                label="Close dialog"
+                                onClick={() => setState({ open: false })}
+                                variant="tertiary"
+                            />
+                        </Flex>
+                        <p>Hello, I am a ({props.placement}) dialog!</p>
+                    </div>
                 </Component>
             </>
         );
     },
     variants: false,
-    presets,
+    sections: [
+        {
+            title: 'Contained Dialog',
+            location: 'beforeDemo',
+            content: function ContainedDialog() {
+                const [open, setOpen] = useState(false);
+
+                const container = useRef<HTMLDivElement | undefined>(undefined);
+
+                return (
+                    <div
+                        ref={(node) => (container.current = node || undefined)}
+                        style={{
+                            border: '1px solid var(--stroke-neutral-base)',
+                            padding: 'var(--spacing-sizing-04)',
+                            minHeight: 200,
+                            position: 'relative',
+                            overflow: 'hidden',
+                        }}
+                    >
+                        <Button label="Open Dialog" onClick={() => setOpen(true)} />
+                        <Dialog
+                            container={container.current}
+                            onClose={() => setOpen(false)}
+                            open={open}
+                            placement="right"
+                        >
+                            <div style={{ padding: 'var(--spacing-sizing-04)' }}>
+                                <Flex
+                                    align="center"
+                                    justify="space-between"
+                                    style={{
+                                        marginBottom: 'var(--spacing-sizing-04)',
+                                    }}
+                                >
+                                    <h4>Contained</h4>
+                                    <Button
+                                        icon={<SvgClose />}
+                                        iconOnly
+                                        label="Close dialog"
+                                        onClick={() => setOpen(false)}
+                                        variant="tertiary"
+                                    />
+                                </Flex>
+                                <p>Hello, I am a contained dialog!</p>
+                            </div>
+                        </Dialog>
+                    </div>
+                );
+            },
+        },
+    ],
+};
+
+// eslint-disable-next-line react/no-multi-comp
+export const Usage = () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+        <>
+            <Button label="Open Dialog" onClick={() => setOpen(true)} />
+            <Dialog onClose={() => setOpen(false)} open={open}>
+                <div style={{ padding: 'var(--spacing-sizing-04)' }}>
+                    <Flex align="center" justify="space-between">
+                        <h1>Dialog Title</h1>
+                        <Button
+                            icon={<SvgClose />}
+                            iconOnly
+                            label="Close dialog"
+                            onClick={() => setOpen(false)}
+                            variant="tertiary"
+                        />
+                    </Flex>
+                    <p>This is the content of the dialog.</p>
+                    <Button label="Cancel" onClick={() => setOpen(false)} variant="secondary" />
+                </div>
+            </Dialog>
+        </>
+    );
 };