paris 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # paris
 
+## 0.4.0
+
+### Minor Changes
+
+- 0a23074: Allow rendering `Button`s as anchors by passing `href` prop
+- 6e5ea2c: `Tilt` component
+- 50ab5e3: `Icon` component for included icons
+- 50ab5e3: `Drawer` component
+- 6e5ea2c: `Card` component
+- dcd9bb6: `Combobox` component
+- 05903f0: `Checkbox` component
+- b758949: `Dialog` component
+
+### Patch Changes
+
+- bbe60be: `Field` component for generic form fields with a label and description
+- 50ab5e3: Drawer pagination
+- bbe60be: Add label/description for Select
+- 50ab5e3: Glassmorphic Dialog variant
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -2,7 +2,7 @@
   "name": "paris",
   "author": "Sanil Chawla <sanil@slingshot.fm> (https://sanil.co)",
   "description": "Paris is Slingshot's React design system. It's a collection of reusable components, design tokens, and guidelines that help us build consistent, accessible, and performant user interfaces.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "homepage": "https://paris.slingshot.fm",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,20 @@
   "exports": {
     "./*": "./src/stories/*"
   },
+  "dependencies": {
+    "@ariakit/react": "^0.2.3",
+    "@headlessui/react": "^1.7.14",
+    "@radix-ui/react-checkbox": "^1.0.4",
+    "clsx": "^1.2.1",
+    "pte": "^0.4.9",
+    "react-parallax-tilt": "^1.7.144",
+    "ts-deepmerge": "^6.0.3"
+  },
   "peerDependencies": {
+    "@fortawesome/fontawesome-svg-core": "^6.4.0",
+    "@fortawesome/free-regular-svg-icons": "^6.4.0",
+    "@fortawesome/free-solid-svg-icons": "^6.4.0",
+    "@fortawesome/react-fontawesome": "^0.2.0",
     "react": "^18.x || ^17.x",
     "react-dom": "^18.x || ^17.x",
     "sass": "^1.x",
@@ -39,10 +52,6 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.1",
-    "@fortawesome/fontawesome-svg-core": "^6.4.0",
-    "@fortawesome/free-regular-svg-icons": "^6.4.0",
-    "@fortawesome/free-solid-svg-icons": "^6.4.0",
-    "@fortawesome/react-fontawesome": "^0.2.0",
     "@ssh/csstypes": "^1.1.0",
     "@ssh/eslint-config": "^1.0.0",
     "@storybook/addon-essentials": "^7.0.18",
@@ -84,13 +93,6 @@
     "type-fest": "^3.10.0",
     "typescript": "^5.0.2"
   },
-  "dependencies": {
-    "@ariakit/react": "^0.2.3",
-    "@headlessui/react": "^1.7.14",
-    "clsx": "^1.2.1",
-    "pte": "^0.4.7",
-    "ts-deepmerge": "^6.0.3"
-  },
   "scripts": {
     "dev": "next dev",
     "build": "next build",

package/src/pages/_app.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable react/jsx-props-no-spreading */
-import '@/styles/globals.css';
+import 'src/styles/globals.css';
 import type { AppProps } from 'next/app';
 
 export default function App({ Component, pageProps }: AppProps) {

package/src/pages/index.tsx

@@ -1,7 +1,7 @@
 import Head from 'next/head';
 import Image from 'next/image';
 import { Inter } from 'next/font/google';
-import styles from '@/styles/Home.module.css';
+import styles from 'src/styles/Home.module.css';
 
 const inter = Inter({ subsets: ['latin'] });
 

package/src/stories/Pagination.mdx

@@ -0,0 +1,73 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Surfaces/Pagination" />
+
+# Paginating Drawers
+
+Paris contains a mechanism for creating pagination within a single surface. This is useful for complex or multi-step processes that would otherwise require a lot of scrolling or complicate the UI.
+
+> This API currently supports `Drawer`, and will soon be expanded to support pagination of any surface.
+
+## Usage
+
+Paris provides a hook for pagination called `usePagination`. This hook functions as a router that allows you to control pagination state and navigate between pages.
+
+To enable pagination:
+
+1. Instantiate a pagination router using `usePagination`.
+2. Pass the pagination object to the Drawer using the `pagination` prop.
+3. Pass your pages as children to the Drawer. Each must have a key that is unique across all pages, which can then be passed to `pagination.open` to navigate to that page.
+
+The pagination object returned by `usePagination` has the following properties:
+
+- `open`: A function that takes a page key and navigates to that page.
+- `currentPage`: The key of the current page.
+- `history`: An array of page keys that are currently in the navigable history stack.
+- `back`: A function that navigates to the previous page.
+- `forward`: A function that navigates to the next page.
+- `canGoBack`: A boolean indicating whether the user can go back.
+- `canGoForward`: A boolean indicating whether the user can go forward.
+
+The hook creates a shared state object between your parent component and the drawer. This means that you can use the `pagination` object's methods to control the drawer from your parent component, or from pages passed to the drawer.
+
+## Example
+
+```tsx
+import { Drawer } from 'paris/drawer';
+import { Button } from 'paris/button';
+import { usePagination } from 'paris/pagination';
+
+const MyComponent = () => {
+    const pages = ['page1', 'page2', 'page3'] as const;
+
+    const pagination = usePagination<typeof pages>('step1');
+
+    return (
+        <Drawer
+            title="User creation flow"
+            open={true}
+            onClose={() => {}}
+            // Pass the entire pagination object to the Drawer to enable pagination
+            pagination={pagination}
+        >
+            <div key={pages[0]}>
+                Page 1
+                <Button
+                    onClick={() => {
+                        // Navigate to the next page using `open`
+                        pagination.open('page2');
+                    }}
+                >
+                    Next Page
+                </Button>
+            </div>
+            <div key={pages[1]}>
+                Page 2
+            </div>
+            <div key={pages[2]}>
+                Page 3
+            </div>
+        </Drawer>
+    );
+};
+```

package/src/stories/button/Button.module.scss

@@ -2,7 +2,7 @@
  * Main styles
  */
 .button {
-    user-select: none;
+    user-select: var(--pte-utils-defaultUserSelect);
 
     border: 1px solid;
 
@@ -96,6 +96,11 @@
     padding: 4px 15px;
 }
 
+.xs {
+    height: 16px;
+    padding: 2px 8px;
+}
+
 
 /*
  * SHAPE
@@ -131,4 +136,9 @@
         width: 20px;
         padding: 4px;
     }
+
+    &.xs {
+        width: 16px;
+        padding: 2px;
+    }
 }

package/src/stories/button/Button.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type {
-    FC, MouseEventHandler, ReactNode,
+    FC, HTMLAttributeAnchorTarget, MouseEventHandler, ReactNode,
 } from 'react';
 import type { ButtonProps as AriaButtonProps } from '@ariakit/react';
 import { Button as AriaButton } from '@ariakit/react';
@@ -13,7 +13,8 @@ import { MemoizedEnhancer, renderEnhancer } from '../../helpers/renderEnhancer';
 
 const EnhancerSizes = {
     large: 13,
-    small: 9,
+    small: 11,
+    xs: 9,
 };
 
 export type ButtonProps = {
@@ -26,7 +27,7 @@ export type ButtonProps = {
      * The size of the Button.
      * @default large
      */
-    size?: 'large' | 'small';
+    size?: 'large' | 'small' | 'xs';
     /**
      * The shape of the Button.
      * @default pill
@@ -51,6 +52,14 @@ export type ButtonProps = {
      * The interaction handler for the Button.
      */
     onClick?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Optionally, the Button can be rendered as an anchor element by passing an `href` prop. To use a Next.js Link component, use the `render` prop directly.
+     */
+    href?: string;
+    /**
+     * Optionally, the target of the anchor element can be specified (defaults to `_self`).
+     */
+    hrefTarget?: HTMLAttributeAnchorTarget;
     /**
      * The contents of the Button.
      *
@@ -73,45 +82,59 @@ export type ButtonProps = {
  * @constructor
  */
 export const Button: FC<ButtonProps> = ({
-    kind,
-    size,
-    shape,
-    type,
+    kind = 'primary',
+    size = 'large',
+    shape = 'pill',
+    type = 'button',
     startEnhancer,
     endEnhancer,
     onClick,
     children,
     disabled,
+    href,
     ...props
 }) => (
     <AriaButton
         {...props}
         className={clsx(
             styles.button,
-            styles[kind || 'primary'],
-            styles[shape || 'pill'],
-            styles[size || 'large'],
+            styles[kind],
+            styles[shape],
+            styles[size],
             props?.className,
         )}
         aria-disabled={disabled ?? false}
-        type={type || 'button'}
+        type={type}
         aria-details={children}
-        onClick={!disabled ? onClick : () => {}}
+        onClick={!disabled && !href ? onClick : () => {}}
         disabled={false}
+        {...href ? {
+            render: (properties) => (
+                // eslint-disable-next-line jsx-a11y/anchor-has-content
+                <a
+                    {...properties}
+                    href={href}
+                    target={props.hrefTarget ?? '_self'}
+                    rel={props.hrefTarget === '_self' ? undefined : 'noreferrer'}
+                />
+            ),
+        } : {}}
     >
         {!!startEnhancer && (
             <MemoizedEnhancer
                 enhancer={startEnhancer}
-                size={EnhancerSizes[size || 'large']}
+                size={EnhancerSizes[size]}
             />
         )}
-        <Text kind="labelXSmall">
-            {children || 'Button'}
-        </Text>
+        {!['circle', 'square'].includes(shape) && (
+            <Text kind="labelXSmall">
+                {children || 'Button'}
+            </Text>
+        )}
         {!!endEnhancer && (
             <MemoizedEnhancer
                 enhancer={endEnhancer}
-                size={EnhancerSizes[size || 'large']}
+                size={EnhancerSizes[size]}
             />
         )}
     </AriaButton>

package/src/stories/card/Card.module.scss

@@ -0,0 +1,14 @@
+.container {
+    border: 1px solid var(--pte-borders-dropdown-color);
+    border-radius: var(--pte-borders-radius-rounded);
+    box-shadow: var(--pte-lighting-subtlePopup);
+
+    user-select: var(--pte-utils-defaultUserSelect);
+    width: max-content;
+    padding: 16px;
+
+    &.flat {
+        box-shadow: none;
+        border-color: var(--pte-colors-borderOpaque);
+    }
+}

package/src/stories/card/Card.stories.ts

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Card } from './Card';
+
+const meta: Meta<typeof Card> = {
+    title: 'Surfaces/Card',
+    component: Card,
+    tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+/**
+ * By default, the card has a shadow and parallax tilt effect. You may want to adjust the max tilt angles through the `overrides.tilt.tiltMaxAngle(X|Y)` props to provide a good experience depending on the size of the content. See the [Tilt component](/docs/surfaces-tilt--docs) for all available props.
+ */
+export const Default: Story = {
+    args: {
+        children: 'Revenue: $3000',
+    },
+};
+
+/**
+ * Setting the `kind` prop to `flat` will remove the shadow from the card.
+ *
+ * This example also disables the `tilt` effect by setting the `tilt` prop to `false`, but by default the `tilt` prop will remain set to `true`.
+ */
+export const Flat: Story = {
+    args: {
+        kind: 'flat',
+        tilt: false,
+        children: 'Revenue: $3000',
+    },
+};

package/src/stories/card/Card.tsx

@@ -0,0 +1,60 @@
+import type { FC, ReactNode } from 'react';
+import clsx from 'clsx';
+import { createElement, Fragment } from 'react';
+import styles from './Card.module.scss';
+import type { TiltProps } from '../tilt';
+import { Tilt } from '../tilt';
+
+export type CardProps = {
+    /**
+     * The visual variant of the Card.
+     *
+     * @default "hover"
+     */
+    kind?: 'hover' | 'flat';
+    /**
+     * Whether the Card should tilt on hover.
+     *
+     * @default true
+     */
+    tilt?: boolean;
+    /** The contents of the Card. */
+    children?: ReactNode | ReactNode[];
+    /**
+     * Overrides for nested components.
+     */
+    overrides?: {
+        tilt?: TiltProps;
+    }
+};
+
+/**
+ * A Card component.
+ *
+ * <hr />
+ *
+ * To use this component, import it as follows:
+ *
+ * ```js
+ * import { Card } from 'paris/card';
+ * ```
+ * @constructor
+ */
+export const Card: FC<CardProps> = ({
+    kind = 'hover',
+    tilt = true,
+    children,
+    overrides,
+}) => (
+    <Tilt
+        disableTilt={!tilt}
+        {...overrides?.tilt}
+        className={clsx(
+            styles.container,
+            styles[kind],
+            overrides?.tilt?.className,
+        )}
+    >
+        {children}
+    </Tilt>
+);

package/src/stories/card/index.ts

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

package/src/stories/checkbox/Checkbox.module.scss

@@ -0,0 +1,57 @@
+.container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 12px;
+    user-select: var(--pte-utils-defaultUserSelect);
+    cursor: default;
+    &button {
+        all: unset;
+    }
+}
+
+.root {
+    background-color: var(--pte-colors-backgroundPrimary);
+    width: 14px;
+    height: 14px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    border: 2px solid var(--pte-colors-contentPrimary);
+    border-radius: var(--pte-borders-radius-rectangle);
+    box-shadow: var(--pte-lighting-shallowBelow);
+
+    &:hover {
+        //background-color: ;
+    }
+    &:focus-visible {
+        outline: 1px solid var(--pte-colors-contentTertiary);
+    }
+
+    position: relative;
+    &:after {
+        content: "";
+        width: 100%;
+        height: 100%;
+        position: absolute;
+        background-color: var(--pte-colors-backgroundPrimary);
+        transition: var(--pte-animations-interaction);
+        transition-delay: 50ms;
+    }
+
+    &[data-state="checked"], &[data-state="indeterminate"] {
+        &:after {
+            opacity: 0;
+        }
+    }
+
+    & span {
+        transition: var(--pte-animations-interaction);
+    }
+}
+
+.indicator {
+    cursor: default;
+}

package/src/stories/checkbox/Checkbox.stories.ts

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { createElement, useState } from 'react';
+import { Checkbox } from './Checkbox';
+
+const meta: Meta<typeof Checkbox> = {
+    title: 'Inputs/Checkbox',
+    component: Checkbox,
+    tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {
+    args: {
+        children: 'I agree to the terms of service',
+    },
+    render: (args) => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const [checked, setChecked] = useState(false);
+        return createElement(Checkbox, {
+            ...args,
+            checked,
+            onChange: (e) => setChecked(!!e),
+        });
+    },
+};

package/src/stories/checkbox/Checkbox.tsx

@@ -0,0 +1,58 @@
+import type { FC } from 'react';
+import { useId } from 'react';
+import * as RadixCheckbox from '@radix-ui/react-checkbox';
+import styles from './Checkbox.module.scss';
+import { pvar } from '../theme';
+
+export type CheckboxProps = {
+    checked?: boolean;
+    onChange?: (checked: boolean | 'indeterminate') => void;
+    disabled?: boolean;
+    /** The contents of the Checkbox. */
+    children?: string;
+};
+
+/**
+* A Checkbox component.
+*
+* <hr />
+*
+* To use this component, import it as follows:
+*
+* ```js
+* import { Checkbox } from 'paris/checkbox';
+* ```
+* @constructor
+*/
+export const Checkbox: FC<CheckboxProps> = ({
+    checked,
+    onChange,
+    disabled,
+    children,
+}) => {
+    const inputID = useId();
+    return (
+        <label
+            htmlFor={inputID}
+            className={styles.container}
+        >
+            <RadixCheckbox.Root
+                id={inputID}
+                className={styles.root}
+                checked={checked}
+                onCheckedChange={onChange}
+                data-disabled={disabled}
+            >
+                <RadixCheckbox.Indicator className={styles.indicator}>
+                    <svg width={14} height={14} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+                        <path
+                            d="M0.333374 0.333252V13.6666H13.6667V0.333252H0.333374ZM6.00004 10.3999L2.26672 6.66658L3.66671 5.26658L5.93339 7.53325L10.2 3.26658L11.6001 4.66659L6.00004 10.3999Z"
+                            fill={pvar('colors.contentPrimary')}
+                        />
+                    </svg>
+                </RadixCheckbox.Indicator>
+            </RadixCheckbox.Root>
+            {children}
+        </label>
+    );
+};

package/src/stories/checkbox/index.ts

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

package/src/stories/combobox/Combobox.module.scss

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

package/src/stories/combobox/Combobox.stories.ts

@@ -0,0 +1,84 @@
+/* eslint-disable react-hooks/rules-of-hooks,react/no-children-prop */
+import type { Meta, StoryObj } from '@storybook/react';
+import { createElement, useState } from 'react';
+import type { Option } from './Combobox';
+import { Combobox } from './Combobox';
+import { Text } from '../text';
+
+const meta: Meta<typeof Combobox> = {
+    title: 'Inputs/Combobox',
+    component: Combobox,
+    tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Combobox>;
+
+export const Default: Story = {
+    args: {
+        label: 'Share',
+        description: 'Search for a friend to share this document with.',
+        placeholder: 'Search...',
+        options: [
+            {
+                id: '1',
+                node: createElement(Text, {
+                    kind: 'paragraphSmall',
+                    children: "Billie O'Connell",
+                }),
+                metadata: {
+                    name: "Billie O'Connell",
+                },
+            },
+            {
+                id: '2',
+                node: createElement(Text, {
+                    kind: 'paragraphSmall',
+                    children: "Finneas O'Connell",
+                }),
+                metadata: {
+                    name: "Finneas O'Connell",
+                },
+            },
+            {
+                id: '3',
+                node: createElement(Text, {
+                    kind: 'paragraphSmall',
+                    children: 'Taylor Alison Swift',
+                }),
+                metadata: {
+                    name: 'Taylor Alison Swift',
+                },
+            },
+            {
+                id: '4',
+                node: createElement(Text, {
+                    kind: 'paragraphSmall',
+                    children: 'Taylor Alison Swift',
+                }),
+                metadata: {
+                    name: 'Taylor Alison Swift',
+                },
+            },
+        ],
+    },
+    render: (args) => {
+        const [selected, setSelected] = useState<Option | null>(null);
+        const [inputValue, setInputValue] = useState<string>('');
+        return createElement('div', {
+            style: { minHeight: '200px' },
+        }, createElement(Combobox<{ name: string }>, {
+            ...args,
+            value: (selected?.id === null) ? {
+                id: null,
+                node: inputValue,
+                metadata: {
+                    name: inputValue,
+                },
+            } : selected as Option<{ name: string }> | null,
+            options: (args.options as Option<{ name: string }>[]).filter((o) => (o.metadata?.name as string || '').toLowerCase().includes(inputValue.toLowerCase())),
+            onChange: (e) => setSelected(e),
+            onInputChange: (e) => setInputValue(e),
+        }));
+    },
+};