@bspk/ui 1.1.32 → 1.1.34

package/src/components/Textarea/Textarea.tsx

@@ -0,0 +1,164 @@
+import { ChangeEvent, useRef } from 'react';
+
+import { CommonProps, InvalidPropsLibrary, SetRef } from '-';
+import { useId } from '-/hooks/useId';
+import { cssWithVars } from '-/utils/cwv';
+import './textarea.scss';
+
+const DEFAULT = {
+    minRows: 3,
+    maxRows: 10,
+    textSize: 'medium',
+} as const;
+
+export type TextareaProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'readOnly' | 'required'> &
+    InvalidPropsLibrary & {
+        /**
+         * Callback when the value of the field changes.
+         *
+         * @type (next: String, Event) => void
+         * @required
+         */
+        onChange: (next: string, event?: ChangeEvent<HTMLTextAreaElement>) => void;
+        /**
+         * The text size of the field.
+         *
+         * @default medium
+         */
+        textSize?: 'large' | 'medium' | 'small';
+        /**
+         * The value of the field.
+         *
+         * @type multiline
+         */
+        value?: string;
+        /**
+         * The textarea control name of the field.
+         *
+         * @required
+         */
+        name: string;
+        /** The ref of the field. */
+        innerRef?: SetRef<HTMLTextAreaElement>;
+        /** The placeholder of the field. */
+        placeholder?: string;
+        /**
+         * The maximum number of characters that the field will accept.
+         *
+         * @minimum 1
+         */
+        maxLength?: number;
+        /**
+         * The minimum number of rows that the textarea will show.
+         *
+         * @default 3
+         * @minimum 3
+         * @maximum 10
+         */
+        minRows?: number;
+        /**
+         * The maximum number of rows that the textarea will show.
+         *
+         * When set the textarea will automatically adjust its height to fit the content up to this limit.
+         *
+         * @default 3
+         * @minimum 3
+         * @maximum 10
+         */
+        maxRows?: number;
+    };
+
+/**
+ * A component that allows users to input large amounts of text that could span multiple lines.
+ *
+ * This component gives you a textarea HTML element that automatically adjusts its height to match the length of the
+ * content within maximum and minimum rows. A character counter when a maxLength is set to show the number of characters
+ * remaining below the limit.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Textarea } from '@bspk/ui/Textarea';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>('');
+ *
+ *         return <Textarea aria-label="Example aria-label" name="Example name" onChange={setValue} value={value} />;
+ *     }
+ *
+ * @element
+ *
+ * @name Textarea
+ * @phase DesignReview
+ */
+function Textarea({
+    invalid: invalidProp,
+    onChange,
+    textSize = DEFAULT.textSize,
+    value = '',
+    name,
+    'aria-label': ariaLabel,
+    innerRef,
+    placeholder,
+    id: idProp,
+    minRows: minRowsProp = DEFAULT.minRows,
+    maxRows: maxRowsProp = DEFAULT.maxRows,
+    errorMessage,
+    ...otherProps
+}: TextareaProps) {
+    const id = useId(idProp);
+    const invalid = !otherProps.readOnly && !otherProps.disabled && invalidProp;
+    // ensure minRows and maxRows are within bounds
+    const minRows = Math.min(DEFAULT.maxRows, Math.max(minRowsProp, DEFAULT.minRows));
+    const maxRows = Math.max(DEFAULT.minRows, Math.min(maxRowsProp, DEFAULT.maxRows));
+
+    const onInput = () => {
+        const target = textareaElement.current;
+        if (!target) return;
+        // we know the textarea was resized, so we don't want to auto-size it
+        if (target.style.height) return;
+        (target.nextSibling as HTMLElement).innerText = `${target.value}\n`;
+    };
+
+    const textareaElement = useRef<HTMLTextAreaElement | null>(null);
+
+    return (
+        <div
+            data-bspk="textarea"
+            data-size={textSize}
+            style={cssWithVars({
+                '--min-rows': minRows,
+                '--max-rows': maxRows,
+            })}
+        >
+            <textarea
+                {...otherProps}
+                aria-errormessage={errorMessage || undefined}
+                aria-invalid={invalid || undefined}
+                aria-label={ariaLabel}
+                id={id}
+                name={name}
+                onBlur={(event) => {
+                    const target = event.target as HTMLTextAreaElement;
+                    target.scrollTop = 0;
+                }}
+                onChange={(event) => onChange(event.target.value, event)}
+                onInput={onInput}
+                placeholder={placeholder}
+                ref={(node) => {
+                    innerRef?.(node);
+                    textareaElement.current = node;
+                    onInput();
+                }}
+                value={value}
+                wrap="hard"
+            />
+            <div aria-hidden data-replicated-value />
+        </div>
+    );
+}
+
+Textarea.bspkName = 'Textarea';
+
+export { Textarea };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Textarea/TextareaExample.tsx

@@ -0,0 +1,5 @@
+import { ComponentExample } from '-/utils/demo';
+
+import { TextareaProps } from '.';
+
+export const TextareaExample: ComponentExample<TextareaProps> = {};

package/src/components/Textarea/index.tsx

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

package/src/components/Textarea/textarea.scss

@@ -0,0 +1,96 @@
+[data-bspk='textarea'] {
+    /*! 
+    --min-rows: is set via inline style 
+    --max-rows: is set via inline style
+    */
+
+    display: grid;
+    width: 100%;
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-sm);
+    overflow: hidden;
+
+    --border-color: var(--stroke-neutral-base);
+
+    // &[data-size='medium']
+    --font: var(--body-base);
+    --line-height: 20px;
+    --padding: var(--spacing-sizing-03);
+
+    &[data-size='small'] {
+        --font: var(--body-small);
+        --line-height: 20px;
+        --padding: var(--spacing-sizing-02);
+    }
+
+    &[data-size='large'] {
+        --font: var(--body-large);
+        --line-height: 24px;
+        --padding: var(--spacing-sizing-03);
+    }
+
+    &:has(textarea:focus-within) {
+        --border-color: var(--stroke-neutral-focus);
+    }
+
+    &:has(textarea[aria-invalid]) {
+        --border-color: var(--status-error);
+    }
+
+    [data-replicated-value] {
+        white-space: pre-wrap;
+        visibility: hidden;
+        overflow-y: hidden;
+    }
+
+    textarea,
+    [data-replicated-value] {
+        width: 100%;
+        font: var(--font);
+        padding: var(--padding);
+        border: none;
+        background: transparent;
+        grid-area: 1 / 1 / 2 / 2;
+        min-height: calc((var(--line-height) * var(--min-rows)) + (var(--padding) * 2));
+        max-height: calc((var(--line-height) * var(--max-rows)) + (var(--padding) * 2));
+        max-width: 100%;
+    }
+
+    textarea {
+        text-wrap: break-word;
+
+        &::placeholder {
+            color: var(--foreground-neutral-on-surface-variant-03);
+        }
+
+        resize: none;
+        color: var(--foreground-neutral-on-surface);
+        background-color: var(--surface-neutral-t1-base);
+
+        &:focus-within {
+            outline: none;
+            color: var(--foreground-neutral-on-surface);
+        }
+
+        &:disabled {
+            pointer-events: none;
+            background: 
+    // multiple colors
+
+                linear-gradient(var(--interactions-disabled-opacity), var(--interactions-disabled-opacity)),
+                linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+
+        &:read-only {
+            background: 
+    // multiple colors
+
+                linear-gradient(var(--interactions-disabled-opacity), var(--interactions-disabled-opacity)),
+                linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
+            cursor: not-allowed;
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/TextareaField/TextareaField.tsx

@@ -0,0 +1,104 @@
+import { FormFieldProps, FormField } from '-/components/FormField';
+import { TextareaProps, Textarea } from '-/components/Textarea';
+import { Txt } from '-/components/Txt';
+import { tryIntParse } from '-/utils/tryIntPsrse';
+
+export type TextareaFieldProps = Pick<FormFieldProps, 'controlId' | 'helperText' | 'label'> &
+    TextareaProps & {
+        /**
+         * Whether the character count should be displayed.
+         *
+         * @default true
+         */
+        characterCount?: boolean;
+    };
+/**
+ * A component that allows users to input large amounts of text that could span multiple lines.
+ *
+ * This component takes properties from the FormField and Textarea components.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TextareaField } from '@bspk/ui/TextareaField';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>();
+ *
+ *         return (
+ *             <TextareaField
+ *                 aria-label="Example aria-label"
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={setValue}
+ *                 value={value}
+ *             />
+ *         );
+ *     }
+ *
+ * @name TextareaField
+ * @phase DesignReview
+ */
+function TextareaField({
+    label,
+    errorMessage: errorMessageProp,
+    helperText,
+    controlId: id,
+    onChange,
+    maxLength: maxLengthProp,
+    invalid,
+    readOnly,
+    disabled,
+    required,
+    characterCount = true,
+    ...textareaProps
+}: TextareaFieldProps) {
+    const maxLength = tryIntParse(maxLengthProp) || -1;
+    const errorMessage = (!readOnly && !disabled && errorMessageProp) || undefined;
+
+    if (typeof onChange !== 'function') return null;
+
+    return (
+        <FormField
+            controlId={id}
+            data-bspk="textarea-field"
+            errorMessage={errorMessage}
+            helperText={helperText}
+            invalid={invalid}
+            label={label}
+            labelTrailing={
+                characterCount && (
+                    <Txt
+                        style={{
+                            color: 'var(--foreground-neutral-on-surface-variant-02)',
+                        }}
+                        variant="body-small"
+                    >
+                        {`${textareaProps?.value?.length || 0}${maxLength > 0 ? `/${maxLength}` : ''}`}
+                    </Txt>
+                )
+            }
+            required={required}
+        >
+            {(fieldProps) => (
+                <Textarea
+                    {...textareaProps}
+                    {...fieldProps}
+                    aria-label={textareaProps['aria-label'] || label}
+                    id={id}
+                    invalid={invalid}
+                    onChange={(next, event) => {
+                        onChange(next, event);
+                    }}
+                    required={required}
+                />
+            )}
+        </FormField>
+    );
+}
+
+TextareaField.bspkName = 'TextareaField';
+
+export { TextareaField };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/TextareaField/TextareaFieldExample.tsx

@@ -0,0 +1,19 @@
+import { ComponentExample } from '-/utils/demo';
+
+import { TextareaFieldProps } from '.';
+
+export const TextareaFieldExample: ComponentExample<TextareaFieldProps> = {
+    render: ({ Component, props }) => {
+        const tooManyCharacters = Boolean(props.value && props.maxLength && props.value?.length > props.maxLength);
+
+        const invalid = props.invalid || tooManyCharacters;
+
+        return (
+            <Component
+                {...props}
+                errorMessage={invalid ? props.errorMessage || 'Too Many characters' : ''}
+                invalid={invalid}
+            />
+        );
+    },
+};

package/src/components/TextareaField/index.tsx

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

package/src/components/ToggleOption/ToggleOption.tsx

@@ -0,0 +1,44 @@
+import { ReactElement } from 'react';
+import './toggle-option.scss';
+
+export type ToggleOptionProps = {
+    /**
+     * The label of the option. Also used as the aria-label of the checkbox.
+     *
+     * @required
+     */
+    label: string;
+    /**
+     * The description of the option.
+     *
+     * @type multiline
+     * @type multiline
+     */
+    description?: string;
+    /** The control element to use. */
+    children?: ReactElement;
+};
+
+/**
+ * A utility component that wraps a checkbox, radio, and switch.
+ *
+ * @name ToggleOption
+ * @phase Utility
+ */
+function ToggleOption({ label, description, children }: ToggleOptionProps) {
+    return (
+        <label data-bspk="toggle-option">
+            <span data-control>{children}</span>
+            <span data-content>
+                <span data-label>{label}</span>
+                {description && <span data-description>{description}</span>}
+            </span>
+        </label>
+    );
+}
+
+ToggleOption.bspkName = 'ToggleOption';
+
+export { ToggleOption };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ToggleOption/index.tsx

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

package/src/components/ToggleOption/toggle-option.scss

@@ -0,0 +1,60 @@
+[data-bspk='toggle-option'] {
+    display: flex;
+    width: 100%;
+    flex-direction: row;
+    padding: var(--spacing-sizing-03) var(--spacing-sizing-01) 0 0;
+    gap: var(--spacing-sizing-02);
+    user-select: none;
+    background: unset;
+    border: unset;
+    cursor: pointer;
+    min-height: var(--spacing-sizing-08);
+    align-items: flex-start;
+    justify-content: flex-start;
+    max-width: 100%;
+
+    &:has([data-description]) {
+        align-items: unset;
+    }
+
+    // this media query targets touch devices
+    @media (any-pointer: coarse) {
+        min-height: var(--spacing-sizing-12);
+    }
+
+    [data-content] {
+        display: flex;
+        flex-direction: column;
+        padding: 2px 0;
+    }
+
+    [data-label] {
+        color: var(--foreground-neutral-on-surface);
+        font: var(--labels-base);
+    }
+
+    [data-description] {
+        font: var(--body-small);
+        color: var(--foreground-neutral-on-surface-variant-01);
+    }
+
+    &:not(:has(:disabled)) {
+        [data-pseudo='focus'] &,
+        &:focus-visible,
+        &:has(*:focus-visible) {
+            outline: var(--stroke-neutral-focus) 2px solid;
+        }
+    }
+
+    &:has(:disabled) {
+        [data-label] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+
+        [data-description] {
+            color: var(--foreground-neutral-disabled-on-surface);
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,132 @@
+import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+
+import { Portal } from '-/components/Portal';
+import { Placement, useFloating } from '-/hooks/useFloating';
+import './tooltip.scss';
+
+const DEFAULT = {
+    placement: 'top',
+    showTail: true,
+    disabled: false,
+} as const;
+
+export type TooltipProps = {
+    /**
+     * The placement of the tooltip.
+     *
+     * @default top
+     */
+    placement?: Extract<Placement, 'bottom' | 'left' | 'right' | 'top'>;
+    /** The tooltip content. */
+    label: string;
+    /**
+     * A single element that will trigger the tooltip when hovered over.
+     *
+     * @type ReactElement
+     * @required
+     */
+    children: ReactElement;
+    /** Determines if the tooltip is disabled. */
+    disabled?: boolean;
+    /**
+     * Determines if the tooltip should hide the tail.
+     *
+     * @default true
+     */
+    showTail?: boolean;
+};
+
+/**
+ * Brief message that provide additional guidance and helps users perform an action if needed.
+ *
+ * @example
+ *     import { Tooltip } from '@bspk/ui/Tooltip';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     export function Example() {
+ *         return (
+ *             <Tooltip label="I explain what this button does" placement="top">
+ *                 <Button>Click me</Button>
+ *             </Tooltip>
+ *         );
+ *     }
+ *
+ * @name Tooltip
+ * @phase DesignReview
+ */
+function Tooltip({
+    placement = DEFAULT.placement,
+    label,
+    children,
+    disabled = DEFAULT.disabled,
+    showTail = DEFAULT.showTail,
+}: TooltipProps) {
+    const id = useId();
+    const [show, setShow] = useState(false);
+
+    const child = useMemo(
+        () =>
+            !disabled &&
+            children &&
+            cloneElement(children, {
+                onMouseOver: () => setShow(true),
+                onMouseLeave: () => setShow(false),
+                'aria-describedby': id,
+            }),
+        [children, disabled, id],
+    );
+
+    const arrowRef = useRef<HTMLElement | null>(null);
+
+    const { floatingStyles, middlewareData, elements } = useFloating({
+        placement,
+        strategy: 'fixed',
+        offsetOptions: showTail ? 8 : 4,
+        arrowRef,
+        hide: !show,
+    });
+
+    return disabled ? (
+        children
+    ) : (
+        <>
+            {child}
+            {label && (
+                <Portal>
+                    <div
+                        data-bspk="tooltip"
+                        data-placement={middlewareData?.offset?.placement}
+                        id={id}
+                        ref={(node) => {
+                            elements.setFloating(node);
+                            elements.setReference(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                        }}
+                        role="tooltip"
+                        style={floatingStyles}
+                    >
+                        <span data-text>{label}</span>
+                        <span
+                            aria-hidden
+                            data-arrow
+                            ref={(node) => {
+                                arrowRef.current = node;
+                            }}
+                            style={{
+                                zIndex: 1000,
+                                opacity: showTail ? 1 : 0,
+                                left: middlewareData.arrow?.x != null ? `${middlewareData.arrow?.x}px` : '',
+                                top: middlewareData.arrow?.y != null ? `${middlewareData.arrow?.y}px` : '',
+                            }}
+                        />
+                    </div>
+                </Portal>
+            )}
+        </>
+    );
+}
+
+Tooltip.bspkName = 'Tooltip';
+
+export { Tooltip };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Tooltip/TooltipExample.tsx

@@ -0,0 +1,17 @@
+import { Button } from '-/components/Button';
+import { ComponentExample } from '-/utils/demo';
+
+export const TooltipExample: ComponentExample = {
+    render: ({ props: state, Component }) => {
+        return (
+            <>
+                <Component label="Tooltip text" {...state} placement={[state.placement].flat()[0] || 'top'}>
+                    <Button
+                        label={`Hover over me ${'data-variant-value' in state ? `(${state['data-variant-value']})` : ''}`}
+                        variant="secondary"
+                    />
+                </Component>
+            </>
+        );
+    },
+};

package/src/components/Tooltip/index.tsx

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