@bspk/ui 1.1.31 → 1.1.33

package/src/components/FormField/form-field.scss

@@ -0,0 +1,19 @@
+[data-bspk='form-field'] {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-sizing-01);
+
+    header {
+        flex-grow: 1;
+        display: flex;
+        flex-direction: row;
+        justify-content: space-between;
+
+        label {
+            flex-grow: 1;
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FormField/index.tsx

@@ -0,0 +1 @@
+export * from './FormField';

package/src/components/Img/Img.tsx

@@ -0,0 +1,39 @@
+import { ElementProps } from '-';
+
+export type ImgProps = {
+    /**
+     * The URL of the image.
+     *
+     * @required
+     */
+    src: string;
+    /**
+     * The alternative text for the image.
+     *
+     * @required
+     */
+    alt: string;
+};
+
+/**
+ * The Img component is used to display images on the page.
+ *
+ * @example
+ *     import { Img } from '@bspk/ui/Img';
+ *
+ *     export function Example() {
+ *         return <Img alt="Example alt" src="Example src" />;
+ *     }
+ *
+ * @name Img
+ * @phase Backlog
+ */
+function Img({ alt, ...props }: ElementProps<ImgProps, 'img'>) {
+    return <img {...props} alt={alt} data-bspk="img" />;
+}
+
+Img.bspkName = 'Img';
+
+export { Img };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Img/index.tsx

@@ -0,0 +1 @@
+export * from './Img';

package/src/components/InlineAlert/InlineAlert.tsx

@@ -0,0 +1,80 @@
+import { SvgCheckCircleFill } from '@bspk/icons/CheckCircleFill';
+import { SvgErrorFill } from '@bspk/icons/ErrorFill';
+import { SvgInfoFill } from '@bspk/icons/InfoFill';
+import { ReactNode } from 'react';
+
+import { AlertVariant } from '-';
+import { Txt } from '-/components/Txt';
+import './inline-alert.scss';
+
+export type InlineAlertProps = {
+    /**
+     * The content of the inline alert.
+     *
+     * @type multiline
+     * @required
+     */
+    children: string;
+    /**
+     * The color variant of the inline alert.
+     *
+     * @default informational
+     */
+    variant?: AlertVariant;
+    /** The id of the inline alert. */
+    id?: string;
+};
+
+/**
+ * Inline alerts provide contextual feedback messages for typical user actions with a handful of available and flexible
+ * alert messages.
+ *
+ * @example
+ *     import { InlineAlert } from '@bspk/ui/InlineAlert';
+ *
+ *     export function Example() {
+ *         return <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
+ *     }
+ *
+ * @name InlineAlert
+ * @phase DesignReview
+ */
+function InlineAlert({ children, variant = 'informational', id }: InlineAlertProps) {
+    return (
+        <div data-bspk="inline-alert" data-variant={variant} id={id}>
+            {VARIANT_ICON[variant]}
+            <Txt variant="body-small">{children}</Txt>
+        </div>
+    );
+}
+
+InlineAlert.bspkName = 'InlineAlert';
+
+export { InlineAlert };
+
+// eslint-disable-next-line react/no-multi-comp
+const SvgWarningTwoTone = () => (
+    <svg fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+        <path
+            d="M2.72503 21C2.5417 21 2.37503 20.9542 2.22503 20.8625C2.07503 20.7708 1.95837 20.65 1.87503 20.5C1.7917 20.35 1.74587 20.1875 1.73753 20.0125C1.7292 19.8375 1.77503 19.6667 1.87503 19.5L11.125 3.5C11.225 3.33333 11.3542 3.20833 11.5125 3.125C11.6709 3.04167 11.8334 3 12 3C12.1667 3 12.3292 3.04167 12.4875 3.125C12.6459 3.20833 12.775 3.33333 12.875 3.5L22.125 19.5C22.225 19.6667 22.2709 19.8375 22.2625 20.0125C22.2542 20.1875 22.2084 20.35 22.125 20.5C22.0417 20.65 21.925 20.7708 21.775 20.8625C21.625 20.9542 21.4584 21 21.275 21H2.72503ZM12 18C12.2834 18 12.5209 17.9042 12.7125 17.7125C12.9042 17.5208 13 17.2833 13 17C13 16.7167 12.9042 16.4792 12.7125 16.2875C12.5209 16.0958 12.2834 16 12 16C11.7167 16 11.4792 16.0958 11.2875 16.2875C11.0959 16.4792 11 16.7167 11 17C11 17.2833 11.0959 17.5208 11.2875 17.7125C11.4792 17.9042 11.7167 18 12 18ZM12 15C12.2834 15 12.5209 14.9042 12.7125 14.7125C12.9042 14.5208 13 14.2833 13 14V11C13 10.7167 12.9042 10.4792 12.7125 10.2875C12.5209 10.0958 12.2834 10 12 10C11.7167 10 11.4792 10.0958 11.2875 10.2875C11.0959 10.4792 11 10.7167 11 11V14C11 14.2833 11.0959 14.5208 11.2875 14.7125C11.4792 14.9042 11.7167 15 12 15Z"
+            fill="currentColor"
+        />
+        <path
+            d="M12.7125 17.7125C12.5208 17.9042 12.2833 18 12 18C11.7167 18 11.4792 17.9042 11.2875 17.7125C11.0958 17.5208 11 17.2833 11 17C11 16.7167 11.0958 16.4792 11.2875 16.2875C11.4792 16.0958 11.7167 16 12 16C12.2833 16 12.5208 16.0958 12.7125 16.2875C12.9042 16.4792 13 16.7167 13 17C13 17.2833 12.9042 17.5208 12.7125 17.7125Z"
+            data-second-tone
+        />
+        <path
+            d="M12.7125 14.7125C12.5208 14.9042 12.2833 15 12 15C11.7167 15 11.4792 14.9042 11.2875 14.7125C11.0958 14.5208 11 14.2833 11 14V11C11 10.7167 11.0958 10.4792 11.2875 10.2875C11.4792 10.0958 11.7167 10 12 10C12.2833 10 12.5208 10.0958 12.7125 10.2875C12.9042 10.4792 13 10.7167 13 11V14C13 14.2833 12.9042 14.5208 12.7125 14.7125Z"
+            data-second-tone
+        />
+    </svg>
+);
+
+const VARIANT_ICON: Record<AlertVariant, ReactNode> = {
+    error: <SvgErrorFill />,
+    informational: <SvgInfoFill />,
+    success: <SvgCheckCircleFill />,
+    warning: <SvgWarningTwoTone />,
+};
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/InlineAlert/index.tsx

@@ -0,0 +1 @@
+export * from './InlineAlert';

package/src/components/Layout/Layout.tsx

@@ -0,0 +1,91 @@
+import { ElementType, ReactNode } from 'react';
+
+import { ElementProps } from '-';
+
+export type LayoutProps<As extends ElementType = 'div'> = {
+    /**
+     * The content of the Layout.
+     *
+     * @required
+     */
+    children?: ReactNode;
+    /**
+     * Determines if the flex-direction should be displayed as a column.
+     *
+     * @default false
+     */
+    column?: boolean;
+    /** The gap between the children. */
+    gap?: '4' | '16';
+    /**
+     * The element type to render as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+    /**
+     * Additional styles to apply to the Layout.
+     *
+     * @default flex-start
+     */
+    align?: 'center' | 'flex-end' | 'flex-start' | 'stretch';
+    /**
+     * Additional styles to apply to the Layout.
+     *
+     * @default flex-start
+     */
+    justify?: 'center' | 'flex-end' | 'flex-start' | 'stretch';
+};
+
+/**
+ * Utility component used within other components for layout purposes.
+ *
+ * @example
+ *     import { Layout } from '@bspk/ui/Layout';
+ *
+ *     export function Example() {
+ *         return <Layout>Low effort example</Layout>;
+ *     }
+ *
+ * @name Layout
+ * @phase Utility
+ */
+function Layout<As extends ElementType = 'div'>({
+    children,
+    column,
+    gap = '16',
+    style,
+    as,
+    align = 'flex-start',
+    justify = 'flex-start',
+    ...props
+}: ElementProps<LayoutProps<As>, As>) {
+    const As: ElementType = as || 'div';
+
+    const alignItems = align || 'flex-start';
+    const justifyContent = justify || 'flex-start';
+
+    return (
+        <As
+            {...props}
+            // data-bspk="layout" -- Utility components do not need a data-bspk attribute
+            style={{
+                ...style,
+                display: 'flex',
+                flexDirection: column ? 'column' : 'row',
+                gap: gap ? `${gap}px` : 'px',
+                alignItems,
+                justifyContent,
+            }}
+        >
+            {children}
+        </As>
+    );
+}
+
+Layout.bspkName = 'Layout';
+
+export { Layout };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Layout/index.tsx

@@ -0,0 +1 @@
+export * from './Layout';

package/src/components/Link/Link.tsx

@@ -0,0 +1,96 @@
+import { AnchorHTMLAttributes, ComponentType, lazy, LazyExoticComponent, Suspense } from 'react';
+
+import { CommonPropsLibrary, ElementProps } from '-';
+
+import './link.scss';
+
+export type LinkProps = Pick<CommonPropsLibrary, 'disabled'> & {
+    /**
+     * The label of the link.
+     *
+     * @required
+     */
+    label: string;
+    /** The variant of the link. Controls the icon that is displayed and link target. */
+    trailingIcon?: 'chevron' | 'external' | 'link';
+    /**
+     * The [href](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href) of the link.
+     *
+     * @example
+     *     https://bspk.dev
+     */
+    href: AnchorHTMLAttributes<unknown>['href'];
+    /**
+     * The size of the link.
+     *
+     * @default base
+     */
+    size?: 'base' | 'large' | 'small';
+    /**
+     * Change the color of the link to a subtle color. This is useful for links that are not primary actions, for
+     * example footer menus.
+     *
+     * @default default
+     */
+    variant?: 'default' | 'subtle-inverse' | 'subtle';
+    /**
+     * The [target](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target) of the link. If the
+     * `trailingIcon` is set to `external`, this will default to `_blank`.
+     *
+     * @default _self
+     */
+    target?: '_blank' | '_parent' | '_self' | '_top';
+};
+
+/**
+ * This is the standalone link component. Inline links can use the native `a` element.
+ *
+ * @example
+ *     import { Link } from '@bspk/ui/Link';
+ *
+ *     export function Example() {
+ *         return <Link href="https://bspk.dev" label="Example label" trailingIcon="external" />;
+ *     }
+ *
+ * @name Link
+ * @phase DesignReview
+ */
+function Link({ label, trailingIcon, size, variant, target = '_self', ...props }: ElementProps<LinkProps, 'a'>) {
+    let LazyIcon: LazyExoticComponent<ComponentType<unknown>> | undefined = undefined;
+
+    if (trailingIcon === 'external')
+        LazyIcon = lazy(() => import('@bspk/icons/OpenInNew').then((module) => ({ default: module.SvgOpenInNew })));
+
+    if (trailingIcon === 'chevron')
+        LazyIcon = lazy(() =>
+            import('@bspk/icons/ChevronRight').then((module) => ({ default: module.SvgChevronRight })),
+        );
+
+    if (trailingIcon === 'link')
+        LazyIcon = lazy(() => import('@bspk/icons/Link').then((module) => ({ default: module.SvgLink })));
+
+    return (
+        <a
+            {...props}
+            data-bspk="link"
+            data-size={size}
+            data-subtle={variant === 'subtle' || undefined}
+            data-subtle-inverse={variant === 'subtle-inverse' || undefined}
+            data-trailing-icon={trailingIcon || undefined}
+            target={trailingIcon === 'external' ? '_blank' : target}
+        >
+            <span>{label}</span>
+            {LazyIcon && (
+                <Suspense fallback={null}>
+                    <LazyIcon />
+                </Suspense>
+            )}
+        </a>
+    );
+}
+
+Link.bspkName = 'Link';
+
+export { Link };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Link/LinkExample.tsx

@@ -0,0 +1,91 @@
+import { Fragment, useId } from 'react';
+
+import { Txt } from '-/components/Txt';
+import { ComponentExample } from '-/utils/demo';
+
+import { LinkProps, Link } from '.';
+
+export const LinkExample: ComponentExample<LinkProps> = {
+    containerStyle: {
+        width: '100%',
+    },
+    render: ({ props, preset, Component }) => {
+        if (preset?.label === 'Pseudo States') return <LinkDemo props={props} />;
+
+        return (
+            <div
+                style={{
+                    display: 'flex',
+                    width: '100%',
+                    justifyContent: 'center',
+                    background: props.variant === 'subtle-inverse' ? 'black' : '',
+                    minHeight: 'var(--spacing-sizing-24)',
+                }}
+            >
+                <Component {...props} />
+            </div>
+        );
+    },
+    presets: [
+        {
+            label: 'Pseudo States',
+        },
+    ],
+};
+
+/**
+ * This component demonstrates the different pseudo states of the Link component.
+ *
+ * It is used in the LinkExample preset "Pseudo States", and also the Typography page.
+ */
+export function LinkDemo(params: { props?: LinkProps }) {
+    const states = ['default', 'hover', 'active', 'disabled', 'visited', 'focus'];
+
+    const id = useId();
+
+    return (
+        <div data-links-grid>
+            <div />
+            {states.map((state) => (
+                <Txt key={state} variant="labels-large">
+                    {state.charAt(0).toUpperCase() + state.slice(1)}
+                </Txt>
+            ))}
+            {['default', 'subtle', 'subtle-inverse'].map((kind) => (
+                <Fragment key={`${kind}-row`}>
+                    <Txt key={`${kind}-title`} variant="labels-large">
+                        {kind.charAt(0).toUpperCase() + kind.slice(1)}
+                    </Txt>
+                    {states.map((state) => {
+                        const attr: Record<string, unknown> = {};
+
+                        if (state === 'disabled') {
+                            attr['disabled'] = true;
+                        } else if (state !== 'default') {
+                            attr[`data-pseudo`] = state;
+                        }
+
+                        if (kind !== 'default') attr[`data-${kind}`] = true;
+
+                        return (
+                            <div data-kind={kind} key={`${kind}-${state}`}>
+                                {!params.props ? (
+                                    <a href={`https://bspk.dev/fake-link/${id}+${kind}+${state}`} {...attr}>
+                                        Link Text
+                                    </a>
+                                ) : (
+                                    <Link
+                                        {...params.props}
+                                        label="Link Text"
+                                        {...attr}
+                                        variant={kind as LinkProps['variant']}
+                                    />
+                                )}
+                            </div>
+                        );
+                    })}
+                </Fragment>
+            ))}
+        </div>
+    );
+}

package/src/components/Link/index.tsx

@@ -0,0 +1 @@
+export * from './Link';

package/src/components/ListItem/ListItem.tsx

@@ -0,0 +1,233 @@
+import { AnchorHTMLAttributes, ElementType, ReactNode, AriaRole } from 'react';
+
+import { CommonProps, ElementProps, SetRef } from '-';
+import { ButtonProps, Button } from '-/components/Button';
+import { Truncated } from '-/components/Truncated';
+import { ChildElement, getChildrenElements } from '-/utils/children';
+import { useErrorLogger } from '-/utils/errors';
+import './list-item.scss';
+
+export const LEADING_COMPONENTS = Object.freeze(['Icon', 'Img', 'Avatar']);
+
+export const TRAILING_COMPONENTS = Object.freeze([
+    'ListItemButton',
+    'Checkbox',
+    'Icon',
+    'Radio',
+    'Switch',
+    'Tag',
+    'Txt',
+    'string',
+]);
+
+export type ListItemProps<As extends ElementType = 'div', T = HTMLElement> = CommonProps<
+    'active' | 'disabled' | 'readOnly'
+> & {
+    /**
+     * The element type to render as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+    /**
+     * The leading element to display in the ListItem.
+     *
+     * Leading elements may only be one of the following [Icon](/icons), Img, Avatar.
+     *
+     * @exampleType select
+     * @options Icon, Img, Avatar
+     */
+    leading?: ReactNode;
+    /**
+     * The label to display in the ListItem.
+     *
+     * @required
+     */
+    label: string;
+    /** The subtext to display in the ListItem. */
+    subText?: string;
+    /**
+     * The trailing element to display in the ListItem.
+     *
+     * Trailing elements may only be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag,
+     * Txt.
+     *
+     * @exampleType select
+     * @options Checkbox, Icon, ListItemButton, Radio, Switch, Tag, Txt
+     */
+    trailing?: ReactNode;
+    /**
+     * The [href](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href) of the list item.
+     *
+     * If the href is provided, the ListItem will render as an anchor element (`<a>`).
+     */
+    href?: AnchorHTMLAttributes<unknown>['href'];
+    /** A ref to the list item div element. */
+    innerRef?: SetRef<T>;
+    /**
+     * Whether the ListItem is selected.
+     *
+     * @default false
+     */
+    selected?: boolean;
+};
+
+/**
+ * A hybrid interactive component that is used frequently to organize content and offers a wide range of control and
+ * navigation in most experiences.
+ *
+ * With its flexible and simple structure, the list item element is core and can meet the needs of many uses cases.
+ *
+ * The ListItem has three main elements: leading element, label, and trailing element.
+ *
+ * Leading elements may be one of the following [Icon](/icons), Img, Avatar.
+ *
+ * Trailing elements may be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag, Txt.
+ *
+ * The ListItemButton is a more limited Button with context specific options.
+ *
+ * @example
+ *     import { SvgSquare } from '@bspk/icons/Square';
+ *     import { ListItem } from '@bspk/ui/ListItem';
+ *
+ *     export function Example() {
+ *         return (
+ *             <ListItem
+ *                 label="Example label"
+ *                 leading={<SvgSquare />}
+ *                 subText="Example subtest"
+ *                 trailing={<ListItem.Button label="Click me" onClick={() => console.log('Hello world')} />}
+ *             />
+ *         );
+ *     }
+ *
+ * @subComponents ListItemButton
+ *
+ * @name ListItem
+ * @phase DesignReview
+ */
+function ListItem<As extends ElementType = 'div', T = HTMLElement>({
+    as,
+    disabled,
+    leading: leadingProp,
+    trailing: trailingProp,
+    label,
+    subText,
+    active,
+    readOnly,
+    innerRef,
+    selected = false,
+    role: roleProp,
+    ...props
+}: ElementProps<ListItemProps<As, T>, As>) {
+    let As: ElementType = as || 'div';
+    const role: AriaRole[] = ['option', roleProp || 'listitem'];
+    const AsInner: ElementType = 'span';
+
+    const { leading, trailing } = useChildren(leadingProp, trailingProp);
+
+    if (!label) return;
+
+    if (props.href) As = 'a';
+
+    if (trailing?.name) {
+        // if trailing is a ListItemButton and As is a button, change As to div
+        if (trailing?.name === 'ListItemButton') As = 'div';
+
+        if (['Checkbox', 'Radio', 'Switch'].includes(trailing.name)) {
+            As = 'div';
+            role.push('button');
+        }
+    }
+
+    if (!As && 'onClick' in props) As = 'button';
+
+    const actionable = ('onClick' in props || 'href' in props) && !disabled && !readOnly;
+
+    return (
+        <As
+            {...props}
+            aria-disabled={disabled || undefined}
+            aria-label={As === 'label' ? undefined : label}
+            aria-selected={selected || undefined}
+            data-action={actionable || undefined}
+            data-active={active || undefined}
+            data-bspk="list-item"
+            data-component={leading?.name || undefined}
+            data-readonly={readOnly || undefined}
+            ref={innerRef}
+            role="option"
+            tabIndex={0}
+        >
+            <AsInner data-inner>
+                {leading && (
+                    <span data-component={leading.name} data-leading>
+                        {leading.child}
+                    </span>
+                )}
+                <span data-item-label>
+                    <Truncated data-text>{label}</Truncated>
+                    {subText && <span data-sub-text>{subText}</span>}
+                </span>
+                {trailing && (
+                    <span data-component={trailing.name} data-trailing>
+                        {trailing.child}
+                    </span>
+                )}
+            </AsInner>
+        </As>
+    );
+}
+ListItem.bspkName = 'ListItem';
+
+/** A button that can be used as a trailing element in a ListItem. */
+// eslint-disable-next-line react/no-multi-comp
+function ListItemButton({ label, icon, ...buttonProps }: Pick<ButtonProps, 'icon' | 'label' | 'onClick'>) {
+    return <Button icon={icon} label={label} showLabel={false} {...buttonProps} size="large" variant="tertiary" />;
+}
+ListItemButton.bspkName = 'ListItemButton';
+ListItem.Button = ListItemButton;
+
+export { ListItem };
+
+function useChildren(
+    leadingProp: ReactNode,
+    trailingProp: ReactNode,
+): {
+    leading?: { child: ReactNode; name: string } | null;
+    trailing?: { child: ReactNode; name: string } | null;
+} {
+    const { logError } = useErrorLogger();
+
+    let leading: ChildElement | null = getChildrenElements(leadingProp)[0] || null;
+
+    const trailingElements = getChildrenElements(trailingProp);
+
+    let trailing: ChildElement | null = trailingElements[0] || null;
+
+    if (leading) {
+        const valid = LEADING_COMPONENTS.includes(leading.name);
+        if (!valid) leading = null;
+        logError(
+            !valid,
+            `ListItem - Leading child is invalid. Must be one of:${LEADING_COMPONENTS} Elements: ${leading?.name || 'None'}`,
+        );
+    }
+
+    if (trailing) {
+        const valid = TRAILING_COMPONENTS.includes(trailing.name);
+        if (!valid) trailing = null;
+        logError(
+            !valid,
+            `ListItem - Trailing child is invalid. Must be one of:${TRAILING_COMPONENTS} Elements: ${trailing?.name || 'None'}`,
+        );
+    }
+
+    return {
+        leading,
+        trailing,
+    };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */