paris 0.2.2 → 0.4.0

package/src/stories/drawer/Drawer.tsx

@@ -0,0 +1,339 @@
+'use client';
+
+import {
+    Fragment, useMemo, useState,
+} from 'react';
+import type { ReactNode } from 'react';
+import { Dialog, Transition } from '@headlessui/react';
+import clsx from 'clsx';
+import type { CSSLength } from '@ssh/csstypes';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { faClose, faChevronLeft, faChevronRight } from '@fortawesome/free-solid-svg-icons';
+import { Simulate } from 'react-dom/test-utils';
+import styles from './Drawer.module.scss';
+import { Text } from '../text';
+import { VisuallyHidden } from '../utility/VisuallyHidden';
+import { TextWhenString } from '../utility/TextWhenString';
+import { Button } from '../button';
+import { pvar } from '../theme';
+import { RemoveFromDOM } from '../utility/RemoveFromDOM';
+import type { PaginationState } from '../pagination';
+import {
+    ChevronLeft, ChevronRight, Close, Icon,
+} from '../icon';
+
+export const DrawerSizePresets = ['content', 'default', 'full'] as const;
+
+export type DrawerProps<T extends string[] | readonly string[] = string[]> = {
+    /**
+     * The dialog's open state.
+     */
+    isOpen?: boolean;
+    /**
+     * A callback that will be called when the user closes the drawer by clicking the close button or the backdrop overlay.
+     *
+     * @param value {boolean} - The new open state of the dialog.
+     */
+    onClose?: (value: boolean) => void | Promise<void>;
+    /**
+     * The title of the drawer. Required for accessibility, but can be hidden with the `hideTitle` prop.
+     *
+     * If pagination is enabled, the title should instead describe the entire drawer, not any single page. The title will be visually hidden on all pages.
+     *
+     * If a string is passed, it will be wrapped in a {@link Text} component with `headingXSmall` styling.
+     */
+    title: ReactNode;
+    /**
+     * Whether the title should be hidden. If `true`, the title will be visually hidden but still accessible to screen readers.
+     *
+     * If you're hiding the title to add a custom header, you may also want to hide the close button and render your own by using the `hideCloseButton` prop.
+     *
+     * When pagination is enabled, the title is always hidden regardless of this prop.
+     *
+     * @default false
+     */
+    hideTitle?: boolean;
+    /**
+     * Whether the close button should be hidden. This will entirely remove the close button from the DOM, so you should provide your own way to close the dialog.
+     *
+     * @default false
+     */
+    hideCloseButton?: boolean;
+    /**
+     * The direction from which the Drawer will appear.
+     */
+    from?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * The size of the Drawer, either a preset or a valid {@link CSSLength} string.
+     *
+     * 'content' is the size of the Drawer's content. 'default' is the default size (360px). 'full' is the size of the viewport, minus the panel container's padding.
+     *
+     * @see DrawerSizePresets
+     * @default 'default'
+     */
+    size?: typeof DrawerSizePresets[number] | CSSLength;
+    /**
+     * An optional pagination state. If provided, each child of the Drawer will be rendered in its own page, and the Drawer will contain back and next buttons that will be used to navigate between pages.
+     *
+     * The state should be created using the {@link usePagination} hook and the entire state should be passed to the Drawer. For example:
+     * ```tsx
+     * const pagination = usePagination<['step1', 'step2', 'step3']>();
+     * // ...
+     * <Drawer pagination={pagination}>
+     *     <div key="step1">Step 1</div>
+     *     <div key="step2">Step 2</div>
+     *     <div key="step3">Step 3</div>
+     * </Drawer>
+     * ```
+     *
+     * @see {@link PaginationState} for more information on the pagination state and available methods
+     * @see {@link usePagination} for more information on how to create the pagination state
+     * @default false
+     */
+    pagination?: PaginationState<T>;
+    /** The contents of the Drawer. */
+    children?: ReactNode | ReactNode[];
+};
+
+/**
+* Drawers are panels that slide in from the edge of the screen to reveal additional content.
+*
+* <hr />
+*
+* To use this component, import it as follows:
+*
+* ```js
+* import { Drawer } from 'paris/drawer';
+* ```
+* @constructor
+*/
+export const Drawer = <T extends string[] | readonly string[] = string[]>({
+    isOpen = false,
+    onClose = () => {},
+    title,
+    hideTitle = false,
+    hideCloseButton = false,
+    from = 'right',
+    size = 'default',
+    pagination,
+    children,
+}: DrawerProps<T>) => {
+    // Check if the drawer is on the x-axis.
+    const xAxisDrawer = useMemo(() => ['left', 'right'].includes(from), [from]);
+
+    // Check if the size is a preset.
+    const sizeIsPreset = useMemo(() => (DrawerSizePresets as readonly string[]).includes(size), [size]);
+
+    // Check if pagination is enabled.
+    const isPaginated = useMemo(() => Boolean(pagination), [pagination]);
+
+    const [loadedPage, setLoadedPage] = useState<string | null>(pagination?.history[0] || null);
+
+    // Decide what children to render.
+    const currentChild: ReactNode = useMemo(() => {
+        // If no children are provided, render nothing.
+        if (!children) {
+            return (<></>);
+        }
+
+        // If pagination is enabled, and multiple children are provided, render the currently active child by matching its key against `pagination.currentPage`.
+        if (pagination && Array.isArray(children) && children.length > 0) {
+            const found = children.find((child) => {
+                if (!(child && typeof child === 'object' && 'key' in child)) {
+                    console.warn('Drawer: Pagination is enabled, but the following child is missing a `key` prop. Pagination will likely not work as expected and this child will never be rendered.', child);
+                    return false;
+                }
+                return child.key === pagination.currentPage;
+            });
+            if (found) {
+                return found;
+            }
+        }
+
+        // As a fallback, render all children.
+        return children;
+    }, [children, pagination]);
+
+    return (
+        <Transition show={isOpen} as={Fragment}>
+            <Dialog
+                as="div"
+                className={clsx(
+                    styles.root,
+                )}
+                onClose={onClose}
+            >
+                <div
+                    className={styles.overlayContainer}
+                >
+                    <Transition.Child
+                        as={Fragment}
+                        enter={styles.enter}
+                        enterFrom={styles.enterFrom}
+                        enterTo={styles.enterTo}
+                        leave={styles.leave}
+                        leaveFrom={styles.leaveFrom}
+                        leaveTo={styles.leaveTo}
+                    >
+                        <Dialog.Overlay
+                            className={clsx(
+                                styles.overlay,
+                            )}
+                        />
+                    </Transition.Child>
+                </div>
+
+                <div
+                    className={clsx(
+                        styles.panelContainer,
+                        styles[`from-${from}`],
+                        { [styles[`size-${size}`]]: sizeIsPreset },
+                    )}
+                    style={!sizeIsPreset ? {
+                        [xAxisDrawer ? 'width' : 'height']: size,
+                    } : {}}
+                >
+                    <Transition.Child
+                        as={Fragment}
+                        enter={styles.enter}
+                        enterFrom={styles.enterFrom}
+                        enterTo={styles.enterTo}
+                        leave={styles.leave}
+                        leaveFrom={styles.leaveFrom}
+                        leaveTo={styles.leaveTo}
+                    >
+                        <Dialog.Panel
+                            className={clsx(
+                                styles.panel,
+                                styles[`from-${from}`],
+                            )}
+                        >
+                            {/* Dialog title */}
+                            <VisuallyHidden
+                                // Hide when requested, or when pagination is enabled (the title isn't relevant to any specific page).
+                                when={hideTitle || isPaginated}
+                            >
+                                <Dialog.Title as="h2">
+                                    <TextWhenString kind="headingXXSmall">
+                                        {title}
+                                    </TextWhenString>
+                                </Dialog.Title>
+                            </VisuallyHidden>
+
+                            {/* Close button */}
+                            <RemoveFromDOM
+                                // Hide when requested, or when pagination is enabled (the page navigation bar will render its own close button).
+                                when={hideCloseButton || isPaginated}
+                            >
+                                <Button
+                                    kind="tertiary"
+                                    shape="circle"
+                                    onClick={() => onClose(false)}
+                                    startEnhancer={(
+                                        <FontAwesomeIcon icon={faClose} color={pvar('colors.contentPrimary')} />
+                                    )}
+                                    data-title-hidden={hideTitle}
+                                    className={clsx(
+                                        styles.closeButton,
+                                    )}
+                                >
+                                    Close dialog
+                                </Button>
+                            </RemoveFromDOM>
+
+                            {/* Pagination Navbar */}
+                            <RemoveFromDOM
+                                // Hide when pagination is not enabled.
+                                when={!isPaginated}
+                            >
+                                <div
+                                    className={clsx(
+                                        styles.paginationNav,
+                                    )}
+                                >
+                                    <div
+                                        className={clsx(
+                                            styles.paginationButtons,
+                                        )}
+                                    >
+                                        <Button
+                                            className={clsx(
+                                                styles.navButton,
+                                            )}
+                                            kind="tertiary"
+                                            shape="circle"
+                                            onClick={() => pagination?.back()}
+                                            disabled={!pagination?.canGoBack()}
+                                            startEnhancer={(
+                                                <Icon icon={ChevronLeft} size={20} />
+                                            )}
+                                        >
+                                            Go to previous page in this modal
+                                        </Button>
+                                        <Button
+                                            className={clsx(
+                                                styles.navButton,
+                                            )}
+                                            kind="tertiary"
+                                            shape="circle"
+                                            onClick={() => pagination?.forward()}
+                                            disabled={!pagination?.canGoForward()}
+                                            startEnhancer={(
+                                                <Icon icon={ChevronRight} size={20} />
+                                            )}
+                                        >
+                                            Go to next page in this modal
+                                        </Button>
+                                    </div>
+                                    <Button
+                                        kind="tertiary"
+                                        shape="circle"
+                                        onClick={() => onClose(false)}
+                                        startEnhancer={(
+                                            <Icon icon={Close} size={20} />
+                                        )}
+                                        data-title-hidden={hideTitle}
+                                        className={clsx(
+                                            styles.closeButton,
+                                        )}
+                                    >
+                                        Close dialog
+                                    </Button>
+                                </div>
+                            </RemoveFromDOM>
+                            {/* <Transition.Child */}
+                            {/*    as={Fragment} */}
+                            {/*    enter={styles.enter} */}
+                            {/*    enterFrom={styles.enterFrom} */}
+                            {/*    enterTo={styles.enterTo} */}
+                            {/*    leave={styles.leave} */}
+                            {/*    leaveFrom={styles.leaveFrom} */}
+                            {/*    leaveTo={styles.leaveTo} */}
+                            {/* > */}
+                            {/*    {currentChild} */}
+                            {/* </Transition.Child> */}
+                            {(isPaginated && Array.isArray(children)) ? children.map((child) => (child && typeof child === 'object' && 'key' in child) && (
+                                <Transition
+                                    show={child.key === pagination?.currentPage && loadedPage === child.key}
+                                    key={`transition_${child.key}`}
+                                    as="div"
+                                    enter={styles.paginationEnter}
+                                    enterFrom={styles.enterFromOpacity}
+                                    enterTo={styles.enterToOpacity}
+                                    leave={styles.paginationLeave}
+                                    leaveFrom={styles.leaveFromOpacity}
+                                    leaveTo={styles.leaveToOpacity}
+                                    afterLeave={() => {
+                                        setLoadedPage(pagination?.currentPage || null);
+                                    }}
+                                >
+                                    {child}
+                                </Transition>
+                            )) : children}
+                        </Dialog.Panel>
+                    </Transition.Child>
+                </div>
+            </Dialog>
+        </Transition>
+    );
+};

package/src/stories/drawer/index.ts

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

package/src/stories/dropdown/Dropdown.module.scss

@@ -0,0 +1,23 @@
+.transition {
+    transition: var(--pte-animations-interaction);
+}
+
+.enterFrom {
+    opacity: 0;
+    transform: translateY(-8px);
+}
+
+.enterTo {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+.leaveFrom {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+.leaveTo {
+    opacity: 0;
+    transform: translateY(-8px);
+}

package/src/stories/field/Field.module.scss

@@ -0,0 +1,5 @@
+.content {
+    background-color: pink;
+    color: white;
+    height: 2rem;
+}

package/src/stories/field/Field.stories.ts

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { createElement } from 'react';
+import { Field } from './Field';
+
+const meta: Meta<typeof Field> = {
+    title: 'Inputs/Field',
+    component: Field,
+    tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Field>;
+
+export const Default: Story = {
+    args: {
+        label: 'Label',
+        description: 'Description.',
+        children: createElement('div', {
+            style: {
+                backgroundColor: 'var(--pte-colors-backgroundSecondary)',
+                height: '36px',
+                width: '100%',
+                display: 'flex',
+                flexDirection: 'row',
+                alignItems: 'center',
+                justifyContent: 'flex-start',
+                paddingLeft: '12px',
+                border: '1px solid pink',
+            },
+        }, 'Children are inserted here.'),
+    },
+};

package/src/stories/field/Field.tsx

@@ -0,0 +1,106 @@
+import type { FC, PropsWithChildren, ComponentPropsWithoutRef } from 'react';
+import clsx from 'clsx';
+import styles from '../input/Input.module.scss';
+import type { TextProps } from '../text';
+import { Text } from '../text';
+
+export type FieldProps = {
+    /**
+     * The ID of the child input.
+     */
+    htmlFor?: string;
+    /**
+     * A label for the field. Can be visually hidden using the `hideLabel` prop.
+     */
+    label?: string;
+    /**
+     * Visually hide the label (while keeping it accessible to screen readers).
+     * @default false
+     */
+    hideLabel?: boolean;
+    /**
+     * A description of the field. Can be visually hidden using the `hideDescription` prop.
+     */
+    description?: string;
+    /**
+     * Visually hide the description while keeping it accessible to screen readers.
+     * @default false
+     */
+    hideDescription?: boolean;
+    /**
+     * Disables the field, disallowing user interaction.
+     */
+    disabled?: boolean;
+    overrides?: {
+        container?: ComponentPropsWithoutRef<'div'>;
+        label?: TextProps<'label'>;
+        description?: TextProps<'p'>;
+    }
+};
+
+/**
+* A Field component wraps a form input component with an accessible label and description.
+*
+* <hr />
+*
+* To use this component, import it as follows:
+*
+* ```js
+* import { Field } from 'paris/field';
+* ```
+* @constructor
+*/
+export const Field: FC<PropsWithChildren<FieldProps>> = ({
+    htmlFor,
+    disabled,
+    children,
+    ...props
+}) => (
+    // Disable a11y rules because the container doesn't need to be focusable for screen readers; the input itself should receive focus instead.
+    // The container is only made clickable for usability purposes.
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events,jsx-a11y/no-static-element-interactions
+    <div
+        {...props.overrides?.container}
+        className={clsx(
+            props.overrides?.container?.className,
+            styles.container,
+        )}
+        onClick={(e) => {
+            e.preventDefault();
+            if (typeof window !== 'undefined' && htmlFor) {
+                const input = document.getElementById(htmlFor);
+                if (input && !disabled) {
+                    if (input.tagName === 'BUTTON') input.click();
+                    else input.focus();
+                }
+            }
+        }}
+    >
+        <Text
+            {...props.overrides?.label}
+            as="label"
+            kind="paragraphSmall"
+            htmlFor={htmlFor}
+            className={clsx(
+                styles.label,
+                { [styles.hidden]: props.hideLabel },
+            )}
+        >
+            {props.label}
+        </Text>
+        {children}
+        <Text
+            id={`${htmlFor}-description`}
+            {...props.overrides?.description}
+            as="p"
+            kind="paragraphXSmall"
+            className={clsx(
+                styles.description,
+                { [styles.hidden]: !props.description || props.hideDescription },
+                props.overrides?.description?.className,
+            )}
+        >
+            {props.description}
+        </Text>
+    </div>
+);

package/src/stories/field/index.ts

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

package/src/stories/icon/ChevronLeft.tsx

@@ -0,0 +1,11 @@
+import { memo } from 'react';
+import type { IconDefinition } from './Icon';
+
+export const ChevronLeft: IconDefinition = memo(({ size }) => (
+    <svg width={size} height={size} viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path
+            d="M5.46875 9.46875L11.4688 3.5C11.75 3.1875 12.2188 3.1875 12.5312 3.5C12.8125 3.78125 12.8125 4.25 12.5312 4.53125L7.03125 10L12.5 15.5C12.8125 15.7812 12.8125 16.25 12.5 16.5312C12.2188 16.8438 11.75 16.8438 11.4688 16.5312L5.46875 10.5312C5.15625 10.25 5.15625 9.78125 5.46875 9.46875Z"
+            fill="currentColor"
+        />
+    </svg>
+));

package/src/stories/icon/ChevronRight.tsx

@@ -0,0 +1,11 @@
+import { memo } from 'react';
+import type { IconDefinition } from './Icon';
+
+export const ChevronRight: IconDefinition = memo(({ size }) => (
+    <svg width={size} height={size} viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path
+            d="M14.5312 9.46875C14.8125 9.78125 14.8125 10.25 14.5312 10.5312L8.53125 16.5312C8.21875 16.8438 7.75 16.8438 7.46875 16.5312C7.15625 16.25 7.15625 15.7812 7.46875 15.5L12.9375 10.0312L7.46875 4.53125C7.15625 4.25 7.15625 3.78125 7.46875 3.5C7.75 3.1875 8.21875 3.1875 8.5 3.5L14.5312 9.46875Z"
+            fill="currentColor"
+        />
+    </svg>
+));

package/src/stories/icon/Close.tsx

@@ -0,0 +1,11 @@
+import { memo } from 'react';
+import type { IconDefinition } from './Icon';
+
+export const Close: IconDefinition = memo(({ size }) => (
+    <svg width={size} height={size} viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path
+            d="M14.7812 6.28125L11.0312 10.0312L14.75 13.75C15.0625 14.0312 15.0625 14.5 14.75 14.7812C14.4688 15.0938 14 15.0938 13.7188 14.7812L9.96875 11.0625L6.25 14.7812C5.96875 15.0938 5.5 15.0938 5.21875 14.7812C4.90625 14.5 4.90625 14.0312 5.21875 13.7188L8.9375 10L5.21875 6.28125C4.90625 6 4.90625 5.53125 5.21875 5.21875C5.5 4.9375 5.96875 4.9375 6.28125 5.21875L10 8.96875L13.7188 5.25C14 4.9375 14.4688 4.9375 14.7812 5.25C15.0625 5.53125 15.0625 6 14.7812 6.28125Z"
+            fill="currentColor"
+        />
+    </svg>
+));

package/src/stories/icon/Icon.module.scss

@@ -0,0 +1,5 @@
+.content {
+    background-color: pink;
+    color: white;
+    height: 2rem;
+}

package/src/stories/icon/Icon.stories.ts

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import type { IconDefinition } from './Icon';
+import { Icon } from './Icon';
+import * as Icons from './index';
+import { pvar } from '../theme';
+
+const meta: Meta<typeof Icon> = {
+    title: 'Content/Icon',
+    component: Icon,
+    tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Icon>;
+
+const getArgs = (icon: IconDefinition): Story => ({
+    args: {
+        icon,
+        size: 20,
+        style: {
+            color: pvar('colors.contentPrimary'),
+        },
+    },
+});
+
+export const Close: Story = getArgs(Icons.Close);
+export const ChevronLeft: Story = getArgs(Icons.ChevronLeft);
+export const ChevronRight: Story = getArgs(Icons.ChevronRight);

package/src/stories/icon/Icon.tsx

@@ -0,0 +1,46 @@
+import type { ComponentPropsWithoutRef, NamedExoticComponent } from 'react';
+import { createElement, memo } from 'react';
+
+export type IconDefinitionProps = {
+    /**
+     * The size of the Icon, in pixels.
+     */
+    size: number;
+};
+export type IconDefinition = NamedExoticComponent<IconDefinitionProps>;
+
+export type IconProps<T extends keyof JSX.IntrinsicElements = 'span'> = IconDefinitionProps & {
+    icon: IconDefinition;
+    as?: T;
+    overrides?: {
+        icon?: ComponentPropsWithoutRef<'svg'>
+    }
+} & ComponentPropsWithoutRef<T>;
+
+/**
+* Paris comes with a set of simple UI icons that can be used in your application. Icons are MIT-licensed and can be used in any project.
+*
+* <hr />
+*
+* To use this component, import the parent `Icon` component and the icon you want to use:
+*
+* ```tsx
+* import { Icon, Close } from 'paris/icon';
+ *
+ * <Icon icon={Close} size={20} />
+* ```
+* @constructor
+*/
+export const Icon = memo<IconProps>(({
+    as = 'span',
+    icon,
+    size,
+    overrides = { icon: {} },
+    ...props
+}) => (
+    createElement(
+        as,
+        props,
+        createElement(icon, { size, ...overrides.icon }),
+    )
+));

package/src/stories/icon/index.ts

@@ -0,0 +1,4 @@
+export * from './Icon';
+export { Close } from './Close';
+export { ChevronLeft } from './ChevronLeft';
+export { ChevronRight } from './ChevronRight';