@bspk/ui 1.1.31 → 1.1.33

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,152 @@
+import { SvgPerson } from '@bspk/icons/Person';
+import { useMemo } from 'react';
+
+import { Tooltip } from '-/components/Tooltip';
+import { ColorVariant } from '-/utils/colorVariants';
+import './avatar.scss';
+
+const DEFAULT = {
+    size: 'small',
+    color: 'grey',
+    showTooltip: true,
+} as const;
+
+export type SizeVariant =
+    | 'large'
+    | 'medium'
+    | 'small'
+    | 'x-large'
+    | 'x-small'
+    | 'xx-large'
+    | 'xxx-large'
+    | 'xxxx-large'
+    | 'xxxxx-large';
+
+export type AvatarProps = {
+    /**
+     * The name of the person or entity represented by the avatar. This is used for accessibility purposes.
+     *
+     * @example
+     *     Andre Giant
+     *
+     * @required
+     */
+    name: string;
+    /**
+     * The size of the avatar.
+     *
+     * @default small
+     */
+    size?: SizeVariant;
+    /**
+     * The color of the avatar.
+     *
+     * @default grey
+     */
+    color?: Exclude<ColorVariant, 'white'>;
+    /**
+     * The initials to display in the avatar limited to 2 characters.
+     *
+     * If not provided, the first two letters of the name will be used as initials.
+     *
+     * @example
+     *     AG;
+     */
+    initials?: string;
+    /**
+     * Whether to show the icon in the avatar.
+     *
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * The url to the image to display in the avatar.
+     *
+     * @example
+     *     /profile.jpg
+     */
+    image?: string;
+    /**
+     * Whether to show the represeneetd user's name as a tooltip.
+     *
+     * @default true
+     */
+    showTooltip?: boolean;
+};
+
+/**
+ * An avatar is a visual representation of a user or entity. It can be used to display an initials, icon, or image.
+ *
+ * @example
+ *     import { Avatar } from '@bspk/ui/Avatar';
+ *     import { SvgPerson } from '@bspk/icons/Person';
+ *
+ *     function Example() {
+ *         return (
+ *             <Avatar
+ *                 color="blue"
+ *                 icon={<SvgPerson />}
+ *                 image="/profile.jpg"
+ *                 initials="AR"
+ *                 name="Andre Giant"
+ *                 showTooltip={true}
+ *                 size="large"
+ *             />
+ *         );
+ *     }
+ *
+ * @exampleDescription The image if provided is displayed first, followed by the icon if provided, and finally the initials. If no initials are provided, the first two letters of the name will be used as initials.
+ *
+ * @name Avatar
+ * @phase DesignReview
+ */
+function Avatar({
+    initials: initialsProp,
+    color = DEFAULT.color,
+    size = DEFAULT.size,
+    showIcon,
+    image,
+    name: ariaLabel,
+    showTooltip = DEFAULT.showTooltip,
+}: AvatarProps) {
+    const children = useMemo(() => {
+        if (image) return <img alt={ariaLabel} src={image} />;
+
+        if (showIcon)
+            return (
+                <span data-icon>
+                    <SvgPerson />
+                </span>
+            );
+
+        let initials = initialsProp;
+
+        if (ariaLabel && !initials)
+            initials = ariaLabel
+                .split(' ')
+                .map((word) => word.charAt(0))
+                .slice(0, 2)
+                .join('')
+                .toUpperCase();
+
+        if (initials) return <span data-initials>{initials.slice(0, 2)}</span>;
+
+        return null;
+    }, [ariaLabel, showIcon, image, initialsProp]);
+
+    if (!children) return null;
+
+    const avatar = (
+        <div aria-label={ariaLabel} data-bspk="avatar" data-color={color} data-size={size}>
+            {children}
+        </div>
+    );
+
+    return showTooltip ? <Tooltip label={ariaLabel}>{avatar}</Tooltip> : avatar;
+}
+
+Avatar.bspkName = 'Avatar';
+
+export { Avatar };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Avatar/AvatarExample.tsx

@@ -0,0 +1,42 @@
+import { ComponentExample } from '-/utils/demo';
+
+import { AvatarProps } from '.';
+
+export const AvatarExample: ComponentExample<AvatarProps> = {
+    presets: [
+        {
+            label: 'Name Only',
+            propState: {
+                name: 'Andre Giant',
+                image: undefined, // Ensure no image is set
+                initials: undefined, // Ensure no initials are set
+                showIcon: false,
+            },
+        },
+        {
+            label: 'With Initials',
+            propState: {
+                name: 'Andre Giant',
+                initials: 'GA',
+                image: undefined, // Ensure no image is set
+                showIcon: false,
+            },
+        },
+        {
+            label: 'With Icon',
+            propState: {
+                name: 'Andre Giant',
+                showIcon: true,
+                image: undefined, // Ensure no image is set
+            },
+        },
+        {
+            label: 'With Image',
+            propState: {
+                name: 'Andre Giant',
+                image: '/profile.jpg',
+                showIcon: false,
+            },
+        },
+    ],
+};

package/src/components/Avatar/avatar.scss

@@ -0,0 +1,101 @@
+[data-bspk='avatar'] {
+    --height: var(--spacing-sizing-10);
+    --font: var(--labels-base);
+    --svg-size: var(--spacing-sizing-10);
+
+    &:not([data-color]) {
+        --foreground: var(--foreground-neutral-on-surface);
+        --background: var(--surface-neutral-t3-low);
+    }
+
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    padding: 0;
+    height: var(--height);
+    width: var(--height);
+    aspect-ratio: 1 / 1;
+    border-radius: 999px;
+    background-color: var(--background);
+    color: var(--foreground);
+    font: var(--font);
+
+    &:has(img) {
+        overflow: hidden;
+        align-items: start;
+        justify-content: start;
+    }
+
+    img {
+        vertical-align: top;
+        max-width: 100%;
+    }
+
+    svg {
+        width: var(--svg-size);
+        height: var(--svg-size);
+    }
+
+    [data-icon] {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+    }
+
+    &[data-size='x-small'] {
+        --height: var(--spacing-sizing-06);
+        --font: var(--labels-x-small);
+        --svg-size: var(--spacing-sizing-04);
+    }
+
+    &[data-size='small'] {
+        --height: var(--spacing-sizing-08);
+        --font: var(--labels-small);
+        --svg-size: var(--spacing-sizing-05);
+    }
+
+    &[data-size='medium'] {
+        --height: var(--spacing-sizing-10);
+        --font: var(--labels-base);
+        --svg-size: var(--spacing-sizing-05);
+    }
+
+    &[data-size='large'] {
+        --height: var(--spacing-sizing-12);
+        --font: var(--labels-large);
+        --svg-size: var(--spacing-sizing-06);
+    }
+
+    &[data-size='x-large'] {
+        --height: var(--spacing-sizing-14);
+        --font: var(--subheader-x-large);
+        --svg-size: var(--spacing-sizing-08);
+    }
+
+    &[data-size='xx-large'] {
+        --height: var(--spacing-sizing-17);
+        --font: var(--subheader-xx-large);
+        --svg-size: var(--spacing-sizing-12);
+    }
+
+    &[data-size='xxx-large'] {
+        --height: var(--spacing-sizing-19);
+        --font: var(--display-regular-small);
+        --svg-size: var(--spacing-sizing-15);
+    }
+
+    &[data-size='xxxx-large'] {
+        --height: var(--spacing-sizing-21);
+        --font: var(--display-regular-medium);
+        --svg-size: var(--spacing-sizing-17);
+    }
+
+    &[data-size='xxxxx-large'] {
+        --height: var(--spacing-sizing-23);
+        --font: var(--display-regular-large);
+        --svg-size: var(--spacing-sizing-18);
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Avatar/index.tsx

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

package/src/components/AvatarGroup/AvatarGroup.tsx

@@ -0,0 +1,86 @@
+import { Avatar, AvatarProps, SizeVariant } from '-/components/Avatar';
+import './avatar-group.scss';
+
+export type AvatarItem = Pick<AvatarProps, 'color' | 'image' | 'initials' | 'name' | 'showIcon'>;
+
+export type AvatarGroupProps = {
+    /**
+     * The avatars to display in the group.
+     *
+     * @example
+     *     [
+     *         { name: 'Jane Doe', image: '/profile.jpg' },
+     *         { name: 'John Smith', initials: 'JS' },
+     *     ];
+     *
+     * @type Array<AvatarItem>
+     * @required
+     */
+    items: AvatarItem[];
+    /**
+     * Size of the avatar group.
+     *
+     * @default small
+     */
+    size?: Extract<SizeVariant, 'large' | 'medium' | 'small' | 'x-small'>;
+    /**
+     * The maximum number of avatars to display before showing the overflowCount.
+     *
+     * This is used to limit the number of avatars displayed in the group.
+     *
+     * @minimum 3
+     * @maximum 5
+     */
+    max?: number;
+    /**
+     * The variant of the avatar group.
+     *
+     * @default spread
+     */
+    variant?: 'spread' | 'stacked';
+};
+
+/**
+ * AvatarGroup component displays a group of avatars.
+ *
+ * @example
+ *     import { AvatarGroup } from '@bspk/ui/AvatarGroup';
+ *
+ *     export function Example() {
+ *         return (
+ *             <AvatarGroup
+ *                 items={[
+ *                     { name: 'Jane Doe', image: '/path/to/image.jpg' },
+ *                     { name: 'John Smith', initials: 'JS' },
+ *                 ]}
+ *             />
+ *         );
+ *     }
+ *
+ * @name AvatarGroup
+ * @phase Backlog
+ */
+function AvatarGroup({ items, size = 'small', max = 5, variant }: AvatarGroupProps) {
+    if (!Array.isArray(items) || !items?.length) return null;
+
+    const overFlowCount = items.length - max;
+
+    return (
+        <div data-bspk="avatar-group" data-max={max} data-size={size} data-variant={variant}>
+            <div data-wrap>
+                {items.map((item, index) => (
+                    <Avatar key={index} {...item} size={size} />
+                ))}
+                {overFlowCount > 0 && (
+                    <div aria-hidden data-bspk="avatar" data-color="white" data-size={size}>
+                        <span data-overflow-count>+{overFlowCount}</span>
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}
+
+AvatarGroup.bspkName = 'AvatarGroup';
+
+export { AvatarGroup };

package/src/components/AvatarGroup/avatar-group.scss

@@ -0,0 +1,13 @@
+[data-bspk='avatar-group'] {
+    width: 100%;
+
+    [data-wrap] {
+        width: 100%;
+        display: flex;
+        flex-direction: row;
+        align-items: end;
+        justify-content: end;
+        gap: var(--spacing-sizing-02);
+        overflow: hidden;
+    }
+}

package/src/components/AvatarGroup/index.tsx

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

package/src/components/Badge/Badge.tsx

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+
+import { tryIntParse } from '-/utils/tryIntPsrse';
+
+import './badge.scss';
+
+export type BadgeProps = {
+    /**
+     * The content of the badge. If larger than 99, the badge will display '99+'. If null or undefined, the badge will
+     * be hidden.
+     *
+     * @example
+     *     5;
+     *
+     * @default 1
+     *
+     * @type number
+     * @minimum 1
+     */
+    count?: number;
+    /**
+     * The size of the badge.
+     *
+     * @default small
+     */
+    size?: 'small' | 'x-small';
+    /**
+     * The color variant of the badge.
+     *
+     * @default primary
+     */
+    variant?: 'primary' | 'secondary';
+    /**
+     * Whether the badge should have a border that matches the surface color.
+     *
+     * @default false
+     */
+    surfaceBorder?: boolean;
+    /**
+     * The context for which the badge is applied.
+     *
+     * Could be a button, link, or any other element that the badge is associated with.
+     *
+     * @type
+     */
+    children?: ReactNode;
+};
+
+/**
+ * Visual indicator for new items within a parent page represented with a numerical count of new items.
+ *
+ * @example
+ *     import { Badge } from '@bspk/ui/badge';
+ *
+ *     function Example() {
+ *         return <Badge count={5} size="small" variant="primary" />;
+ *     }
+ *
+ * @exampleDescription This example shows a badge with a count of 5, size small, and primary variant.
+ *
+ * @name Badge
+ * @phase DesignReview
+ */
+function Badge({ count: countProp, size = 'small', variant = 'primary', surfaceBorder, children }: BadgeProps) {
+    const count: number | null = tryIntParse(countProp);
+
+    if (count === null) return;
+
+    const badge = (
+        <sup data-bspk="badge" data-size={size} data-surface-border={surfaceBorder || undefined} data-variant={variant}>
+            {count > 99 ? '99+' : count}
+        </sup>
+    );
+
+    if (children) {
+        return (
+            <span data-bspk="badge-wrapper">
+                {children}
+                {badge}
+            </span>
+        );
+    }
+
+    return badge;
+}
+
+Badge.bspkName = 'Badge';
+
+export { Badge };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Badge/BadgeExample.tsx

@@ -0,0 +1,73 @@
+import { Avatar } from '-/components/Avatar';
+import { ComponentExample } from '-/utils/demo';
+
+import { BadgeProps } from '.';
+
+export const BadgeExample: ComponentExample<BadgeProps> = {
+    containerStyle: { width: '100%' },
+    render: ({ props, Component, preset }) => {
+        if (preset?.label === 'Borders') return <ExampleBadgeVariants Component={Component} props={props} />;
+
+        if (preset?.label === 'With Context') {
+            return (
+                <>
+                    <Component {...props}>
+                        <Avatar image="/profile.jpg" name="Andre Giant" />
+                    </Component>
+                </>
+            );
+        }
+        return <Component {...props} />;
+    },
+    presets: [
+        {
+            label: 'With Context',
+        },
+        {
+            label: 'Borders',
+        },
+    ],
+};
+
+function ExampleBadgeVariants({
+    Component,
+    ...props
+}: {
+    Component: React.ComponentType<Record<string, unknown>>;
+    props: BadgeProps;
+}) {
+    const cells = [
+        ['', 'Small', 'X-Small'],
+        ['None', { size: 'small', surfaceBorder: false }, { size: 'x-small', surfaceBorder: false }],
+        ['Border', { size: 'small', surfaceBorder: true }, { size: 'x-small', surfaceBorder: true }],
+    ] as (BadgeProps | string)[][];
+
+    let border = false;
+    return (
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '16px' }}>
+            {cells.flat().map((content, idx) => {
+                if (typeof content === 'string' && content === 'Border') border = true;
+                return (
+                    <div
+                        key={idx}
+                        style={{
+                            display: 'flex',
+                            flexDirection: 'row',
+                            alignItems: 'center',
+                            gap: '8px',
+                            padding: '8px',
+                            background:
+                                typeof content !== 'string' && border ? 'var(--surface-neutral-t3-low)' : 'transparent',
+                        }}
+                    >
+                        {typeof content === 'string'
+                            ? content
+                            : [9, 99, 999].map((count, idx2) => (
+                                  <Component count={count} key={idx2} {...props} {...(content as BadgeProps)} />
+                              ))}
+                    </div>
+                );
+            })}
+        </div>
+    );
+}

package/src/components/Badge/badge.scss

@@ -0,0 +1,51 @@
+[data-bspk='badge'] {
+    --size: var(--spacing-sizing-06);
+
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: var(--radius-circular);
+    height: var(--size);
+    width: fit-content;
+    min-width: var(--size);
+    font: var(--labels-x-small);
+    color: var(--foreground-brand-on-primary);
+    background: var(--surface-brand-primary);
+    padding: 0 var(--spacing-sizing-02);
+
+    &[data-size='x-small'] {
+        --size: var(--spacing-sizing-05);
+
+        padding: 2px var(--spacing-sizing-01);
+    }
+
+    &[data-variant='secondary'] {
+        color: var(--foreground-brand-on-secondary);
+        background: var(--surface-brand-secondary);
+    }
+
+    &[data-surface-border] {
+        border: 2px solid var(--surface-neutral-t1-base);
+    }
+}
+
+[data-bspk='badge-wrapper'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    position: relative;
+    width: fit-content;
+    height: fit-content;
+    flex-shrink: 0;
+
+    [data-bspk='badge'] {
+        position: absolute;
+        top: 0;
+        right: 0;
+        transform: scale(1) translate(50%, -50%);
+        transform-origin: 100% 0%;
+        z-index: 2;
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Badge/index.tsx

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