@bspk/ui 1.1.34 → 1.3.0

package/src/rtl/hasNoBasicA11yIssues.tsx

@@ -0,0 +1,27 @@
+import { axe } from 'jest-axe';
+import { ReactElement } from 'react';
+import { render, waitFor } from '-/rtl/util';
+
+/**
+ * A utility function to test for basic accessibility issues using jest-axe.
+ *
+ * @example
+ *     import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+ *     import { MyComponent } from './MyComponent';
+ *
+ *     const TestBed = () => <MyComponent />;
+ *
+ *     describe('MyComponent', () => {
+ *         it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+ *     });
+ *
+ * @param TestBed - A React element representing the component to be tested.
+ * @returns An async function that performs the accessibility test.
+ */
+export const hasNoBasicA11yIssues = (TestBed: ReactElement) => {
+    return async () => {
+        const { container } = render(TestBed);
+        await waitFor(() => expect(container).toBeInTheDocument());
+        expect(await axe(container)).toHaveNoViolations();
+    };
+};

package/src/rtl/util.tsx

@@ -0,0 +1,10 @@
+/* eslint-disable import/export */
+import { render, RenderOptions } from '@testing-library/react';
+import { ReactElement } from 'react';
+import { UIProvider } from '-/components/UIProvider/UIProvider';
+
+const renderWithUiProvider = (ui: ReactElement, options?: Omit<RenderOptions, 'wrapper'>) =>
+    render(ui, { wrapper: UIProvider, ...options });
+
+export * from '@testing-library/react';
+export { renderWithUiProvider as render };

package/src/{base.scss → styles/base.scss}

@@ -22,6 +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;
@@ -58,89 +61,92 @@ body[data-bspk] {
     color: var(--foreground-neutral-on-surface);
     min-width: 343px;
 
-    a {
-        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);
-            }
-
-            &:active,
-            &[data-pseudo='active'] {
-                text-decoration: underline;
-                color: var(--foreground-link-text-subtle-pressed);
+        &[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);
+                }
             }
 
-            &: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);
         }
     }
 }
@@ -167,15 +173,11 @@ body[data-bspk] {
 }
 
 [data-sr-only] {
-    position: absolute;
-    width: 1px;
     height: 1px;
-    padding: 0;
-    margin: -1px;
     overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border-width: 0;
+    position: absolute !important;
+    width: 1px;
+    clip: rect(1px, 1px, 1px, 1px);
 }
 
 [data-touch-target] ~ * {
@@ -273,4 +275,79 @@ body[data-bspk] {
     }
 }
 
+[data-attachment-wrapper] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    position: relative;
+    width: fit-content;
+    height: fit-content;
+    flex-shrink: 0;
+
+    [data-attachment] {
+        position: absolute;
+        top: 0;
+        right: 0;
+        transform: scale(1) translate(50%, -50%);
+        transform-origin: 100% 0%;
+        z-index: 2;
+    }
+}
+
+@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/{index.ts → types/common.ts}

@@ -6,54 +6,11 @@
  * @bspk/ui/Txt".
  */
 
-import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef } from 'react';
-
-export const BRANDS: {
-    /** The title of the brand. */
-    title: string;
-    /** The slug of the brand, used in URLs and identifiers. */
-    slug: Brand;
-}[] = [
-    {
-        title: 'Anywhere',
-        slug: 'anywhere',
-    },
-    {
-        title: 'Better Homes & Gardens',
-        slug: 'better-homes-gardens',
-    },
-    {
-        title: 'Cartus',
-        slug: 'cartus',
-    },
-    {
-        title: 'Century 21',
-        slug: 'century-21',
-    },
-    {
-        title: 'Coldwell Banker',
-        slug: 'coldwell-banker',
-    },
-    {
-        title: 'Corcoran',
-        slug: 'corcoran',
-    },
-    {
-        title: 'Denali Boss',
-        slug: 'denali-boss',
-    },
-    {
-        title: 'ERA',
-        slug: 'era',
-    },
-    {
-        title: "Sotheby's",
-        slug: 'sothebys',
-    },
-] as const;
+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<
@@ -67,6 +24,8 @@ export type ElementConstructorProps<
     O extends string = '',
 > = Omit<ComponentPropsWithoutRef<E>, O>;
 
+export type DataProps = Record<`data-${string}`, string>;
+
 export type ButtonSize = 'large' | 'medium' | 'small' | 'x-small';
 
 export type CallToActionButton = {
@@ -86,12 +45,7 @@ export type CallToActionButton = {
     size?: ButtonSize;
 };
 
-/**
- * The props that are common to input elements.
- *
- * If an element is invalid it must have an errorMessage.
- */
-export type InvalidPropsLibrary = {
+export type CommonPropsLibrary = {
     /**
      * Marks the element as invalid and displays error state theme.
      *
@@ -100,17 +54,6 @@ export type InvalidPropsLibrary = {
      * @default false
      */
     invalid?: boolean;
-    /**
-     * Marks the element as invalid and displays error message.
-     *
-     * When an element is invalid it must display an error message explaining why it is invalid.
-     */
-    errorMessage?: string;
-};
-
-export type InvalidProps<K extends keyof InvalidPropsLibrary> = Pick<InvalidPropsLibrary, K>;
-
-export type CommonPropsLibrary = {
     /** The id of the element. If not provided one will be generated. */
     id?: string;
     /**
@@ -168,15 +111,30 @@ export type CommonPropsLibrary = {
      */
     'aria-label': string;
     /**
-     * This is a utility attribute used to identify the owning component of another component.
+     * Identifies the parent component. Helps with styling, debugging, and/or testing purposes.
      *
-     * This is used to identify the component in the UI library and is not intended for public use.
+     * @utility
      */
-    'data-bspk-owner'?: string;
+    owner?: string;
+    /**
+     * The ARIA role of the element.
+     *
+     * @type string
+     */
+    role?: AriaRole;
 };
 
 export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;
 
+export type RequiredCommonProps<K extends keyof CommonPropsLibrary> = Required<Pick<CommonPropsLibrary, K>>;
+
+export type FormFieldControlProps = {
+    /** The id of the control description. */
+    'aria-describedby'?: string;
+    /** The id of the error message */
+    'aria-errormessage'?: string;
+};
+
 export type Brand =
     | 'anywhere'
     | 'better-homes-gardens'

package/src/types/meta.ts

@@ -0,0 +1,101 @@
+/**
+ * This file is used to build the meta types for the project. It's used in the build-meta.ts file and also copied in to
+ * the meta output file.
+ */
+
+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
+    'UXReview', // components that are in UX Review
+    'Stable', // production ready
+];
+
+export const COMPONENT_PHASES: Record<
+    ComponentPhase,
+    {
+        title: string;
+        id: ComponentPhase;
+        description: string;
+    }
+> = {
+    Backlog: {
+        title: 'Backlog',
+        id: 'Backlog',
+        description:
+            'The component has been initiated but is currently on hold. It awaits further development and is not actively being worked on at this time.',
+    },
+    Dev: {
+        title: 'Development',
+        id: 'Dev',
+        description:
+            'The component is actively under development. This phase includes the creation of visual elements and integration tests to ensure comprehensive functionality.',
+    },
+    UXReview: {
+        title: 'UX Review',
+        id: 'UXReview',
+        description:
+            'The component is being carefully evaluated by our Bespoke UX team. They are ensuring that it aligns with our high standards of aesthetics and user experience and is accessible to all users.',
+    },
+    Stable: {
+        title: 'Stable',
+        id: 'Stable',
+        description:
+            'The component has successfully passed all reviews and is ready for use. It is now officially released and ready for use in a production environment.',
+    },
+    Utility: {
+        title: 'Utility',
+        id: 'Utility',
+        description: "The component progress isn't tracked as it's a utility component.",
+    },
+};
+
+export type BaseMeta = {
+    name: string;
+    description?: string;
+    file: string;
+    example?: string;
+};
+
+export type TypeMeta = BaseMeta & {
+    id: string;
+    references?: string[];
+    properties?: TypeProperty[];
+    components?: string[];
+};
+
+export type TypeProperty = {
+    name: string;
+    description?: string;
+    type?: string[] | string;
+    exampleType?: string;
+    default?: unknown;
+    required?: boolean;
+    options?: number[] | string[];
+    variants?: string[];
+    references?: string[];
+    minimum?: number;
+    maximum?: number;
+    example?: string;
+};
+
+export type ComponentMeta = BaseMeta & {
+    slug: string;
+    dependencies: string[];
+    css: string;
+    hasTouchTarget: boolean;
+    usage?: {
+        code: string;
+        description?: string;
+    };
+    phase: ComponentPhase;
+};
+
+export type UtilityMeta = BaseMeta & {
+    param?: string;
+    returns?: string;
+};
+
+export type ComponentPhase = 'Backlog' | 'Dev' | 'Stable' | 'Utility' | 'UXReview';
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/bound.ts

@@ -0,0 +1,30 @@
+/**
+ * A utility function to bound a number within a specified range. Allows for rollover behavior.
+ *
+ * @param params
+ * @param params.num The number to bound, can be a number, string, or undefined
+ * @param params.max The maximum value the number can be
+ * @param params.min The minimum value the number can be
+ * @param params.rollover If true, the number will wrap around when it exceeds the bounds
+ * @param params.defaultValue The default value to return if the input is invalid or undefined
+ * @returns The bounded number
+ */
+export function bound({
+    num,
+    max,
+    min,
+    rollover = false,
+    defaultValue = min,
+}: {
+    num: number | string | undefined;
+    max: number;
+    min: number;
+    rollover?: boolean;
+    defaultValue?: number;
+}): number {
+    const parsedNum = typeof num === 'number' ? num : parseInt(num as string, 10);
+    if (isNaN(parsedNum)) return defaultValue ?? min;
+    if (parsedNum > max) return rollover ? min : max;
+    if (parsedNum < min) return rollover ? max : min;
+    return parsedNum;
+}

package/src/utils/createExampleChildElement.tsx

@@ -0,0 +1,83 @@
+/* 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 { 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';
+import { Txt } from '-/components/Txt';
+
+type ExampleChildElementProps = {
+    exampleState: Record<string, any>;
+    name: string;
+    setState: DemoSetState;
+    action: DemoAction;
+    id?: string;
+};
+
+/**
+ * Returns example leading and trailing components for use in component examples. Allows which type of element is
+ * rendered to be determined by the example state.
+ */
+export function createExampleChildElement({ exampleState, name, setState, action, id }: ExampleChildElementProps): {
+    element: JSX.Element | null;
+    componentName?: string;
+} {
+    const componentName = exampleState[name];
+
+    if (componentName === 'Checkbox' || componentName === 'Radio' || componentName === 'Switch') {
+        let As: typeof Checkbox | typeof Radio | typeof Switch = Checkbox;
+        if (componentName === 'Radio') As = Radio;
+        else if (componentName === 'Switch') As = Switch;
+
+        const toggleName = `data-${name}-toggle-${id}`;
+
+        return {
+            element: (
+                <As
+                    aria-label={`${componentName} demo`}
+                    checked={exampleState[toggleName]}
+                    disabled={exampleState.disabled}
+                    name={`${name}-toggle`}
+                    onChange={(checked: boolean) => {
+                        setState({ [toggleName]: checked });
+                    }}
+                    onClick={() => action(`${name} ${componentName} clicked`)}
+                    readOnly={exampleState.readOnly}
+                    value={`${name}-${componentName}`}
+                />
+            ),
+            componentName,
+        };
+    }
+
+    if (componentName === 'ListItemButton')
+        return {
+            element: (
+                <ListItem.Button
+                    icon={<SvgContentCopy />}
+                    label="LI Button"
+                    onClick={() => action('ListItem button clicked')}
+                />
+            ),
+            componentName,
+        };
+
+    if (componentName === 'Img') return { element: <Img alt="placeholder" src="/placeholder.svg" /> };
+
+    if (componentName === 'Avatar') return { element: <Avatar hideTooltip={false} name="List Item" /> };
+
+    if (componentName === 'Tag') {
+        return { element: <Tag label="Tag" /> };
+    }
+
+    if (componentName === 'Txt') return { element: <Txt>Text</Txt> };
+
+    if (componentName === 'Icon') return { element: <SvgDiamond /> };
+
+    return { element: null };
+}