paris 0.18.0 → 0.19.0

package/src/stories/markdowneditor/MarkdownEditor.stories.tsx

@@ -0,0 +1,223 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite';
+import { useState } from 'react';
+import { FixedToolbar } from './FixedToolbar';
+import { FloatingToolbar } from './FloatingToolbar';
+import { MarkdownEditor } from './MarkdownEditor';
+
+const meta: Meta<typeof MarkdownEditor> = {
+    title: 'Content/MarkdownEditor',
+    component: MarkdownEditor,
+    tags: ['autodocs'],
+    argTypes: {
+        size: {
+            control: 'select',
+            options: ['paragraphLarge', 'paragraphMedium', 'paragraphSmall', 'paragraphXSmall', 'paragraphXXSmall'],
+        },
+        status: {
+            control: 'select',
+            options: ['default', 'error', 'success'],
+        },
+    },
+};
+
+export default meta;
+type Story = StoryObj<typeof MarkdownEditor>;
+
+const sampleMarkdown = `# Getting Started
+
+This is a **WYSIWYG** markdown editor built on *Tiptap*.
+
+## Features
+
+- Bold, italic, and ~~strikethrough~~
+- [Links](https://paris.slingshot.fm) and \`inline code\`
+- Headings, blockquotes, and horizontal rules
+
+> Blockquotes render with Paris styling.
+
+### Task Lists
+
+- [x] Set up Tiptap
+- [x] Add markdown serialization
+- [ ] Style with Paris tokens
+
+\`\`\`typescript
+const [md, setMd] = useState('');
+\`\`\`
+
+---
+
+That's it! The editor outputs **markdown** on every change.`;
+
+/**
+ * Default editor with both FixedToolbar and FloatingToolbar.
+ * All features enabled.
+ */
+export const Default: Story = {
+    render: (args) => {
+        const [value, setValue] = useState(sampleMarkdown);
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue}>
+                    <FixedToolbar />
+                    <FloatingToolbar />
+                </MarkdownEditor>
+                <details style={{ marginTop: 16 }}>
+                    <summary
+                        style={{ cursor: 'pointer', fontSize: 12, color: 'var(--pte-new-colors-contentTertiary)' }}
+                    >
+                        Markdown output
+                    </summary>
+                    <pre
+                        style={{
+                            marginTop: 8,
+                            padding: 12,
+                            fontSize: 12,
+                            background: 'var(--pte-new-colors-backgroundSecondary)',
+                            borderRadius: 8,
+                            overflow: 'auto',
+                            whiteSpace: 'pre-wrap',
+                        }}
+                    >
+                        {value}
+                    </pre>
+                </details>
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'Start writing...',
+    },
+};
+
+/**
+ * Editor with only the FloatingToolbar (appears on text selection).
+ * Clean editing surface without a fixed toolbar.
+ */
+export const FloatingOnly: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('Select some text to see the floating toolbar.');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue}>
+                    <FloatingToolbar />
+                </MarkdownEditor>
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'Start writing...',
+    },
+};
+
+/**
+ * Editor with only the FixedToolbar.
+ */
+export const FixedOnly: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue}>
+                    <FixedToolbar />
+                </MarkdownEditor>
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'Start writing...',
+    },
+};
+
+/**
+ * Editor with a limited feature set — only bold, italic, heading, and link.
+ * Toolbar only shows buttons for enabled features.
+ */
+export const LimitedFeatures: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('Only **bold**, *italic*, headings, and links are available.');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue}>
+                    <FixedToolbar />
+                    <FloatingToolbar />
+                </MarkdownEditor>
+            </div>
+        );
+    },
+    args: {
+        features: ['bold', 'italic', 'heading', 'link'],
+        placeholder: 'Limited formatting...',
+    },
+};
+
+/**
+ * Read-only editor with pre-filled content.
+ * The editor is not editable — useful for preview modes.
+ */
+export const ReadOnly: Story = {
+    render: (args) => {
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={sampleMarkdown} editable={false} />
+            </div>
+        );
+    },
+};
+
+/**
+ * Editor with error status — shows error border styling.
+ */
+export const ErrorStatus: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue} status="error">
+                    <FixedToolbar />
+                </MarkdownEditor>
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'This field has an error...',
+    },
+};
+
+/**
+ * Editor with no toolbar — users rely on keyboard shortcuts and
+ * markdown input rules (e.g., type `## ` for heading 2).
+ */
+export const NoToolbar: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue} />
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'Type markdown shortcuts: # heading, **bold**, - list item...',
+    },
+};
+
+/**
+ * Editor with custom placeholder text.
+ */
+export const WithPlaceholder: Story = {
+    render: (args) => {
+        const [value, setValue] = useState('');
+        return (
+            <div style={{ maxWidth: 700 }}>
+                <MarkdownEditor {...args} value={value} onChange={setValue}>
+                    <FixedToolbar />
+                </MarkdownEditor>
+            </div>
+        );
+    },
+    args: {
+        placeholder: 'Write your thoughts here...',
+        size: 'paragraphMedium',
+    },
+};

package/src/stories/markdowneditor/MarkdownEditor.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import { EditorContent } from '@tiptap/react';
+import { clsx } from 'clsx';
+import type { ComponentPropsWithoutRef, FC, ReactNode } from 'react';
+import { useMemo } from 'react';
+import type { MarkdownSize } from '../markdown';
+import type { MarkdownEditorFeature } from './features';
+import { ALL_FEATURES } from './features';
+import styles from './MarkdownEditor.module.scss';
+import { MarkdownEditorContext } from './MarkdownEditorContext';
+import { useMarkdownEditor } from './useMarkdownEditor';
+
+export type MarkdownEditorProps = {
+    /** The markdown string value (controlled). */
+    value: string;
+    /** Fires with the updated markdown string on every edit. */
+    onChange?: (value: string) => void;
+    /** Whitelist of formatting features to enable. Defaults to all features. */
+    features?: MarkdownEditorFeature[];
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /**
+     * Base text size for body content, matching the Markdown component's size prop.
+     * @default 'paragraphSmall'
+     */
+    size?: MarkdownSize;
+    /** Whether the editor is editable. @default true */
+    editable?: boolean;
+    /** Whether to autofocus the editor on mount. @default false */
+    autofocus?: boolean;
+    /** An optional CSS class name for the root wrapper. */
+    className?: string;
+    /** Visual status for the editor container (follows Input pattern). */
+    status?: 'default' | 'error' | 'success';
+    /** Prop overrides for sub-elements. */
+    overrides?: {
+        root?: ComponentPropsWithoutRef<'div'>;
+        editorContainer?: ComponentPropsWithoutRef<'div'>;
+    };
+    /**
+     * Children are placed inside the context provider, before the editor content.
+     * This is where toolbar components should be placed.
+     */
+    children?: ReactNode;
+};
+
+/**
+ * A WYSIWYG markdown editor built on Tiptap, styled with Paris design tokens.
+ * It pairs with the read-only `<Markdown>` component as its write counterpart.
+ *
+ * The editor uses a compound component pattern — toolbar components are passed
+ * as children and communicate with the editor via React context.
+ *
+ * <hr />
+ *
+ * To use this component, import it as follows:
+ *
+ * ```tsx
+ * import { MarkdownEditor, FixedToolbar, FloatingToolbar } from 'paris/markdowneditor';
+ *
+ * export const Example: FC = () => {
+ *     const [md, setMd] = useState('');
+ *     return (
+ *         <MarkdownEditor value={md} onChange={setMd} placeholder="Start writing...">
+ *             <FixedToolbar />
+ *             <FloatingToolbar />
+ *         </MarkdownEditor>
+ *     );
+ * };
+ * ```
+ *
+ * @constructor
+ */
+export const MarkdownEditor: FC<MarkdownEditorProps> = ({
+    value,
+    onChange,
+    features = ALL_FEATURES,
+    placeholder,
+    size = 'paragraphSmall',
+    editable = true,
+    autofocus = false,
+    className,
+    status = 'default',
+    overrides,
+    children,
+}) => {
+    const { editor, featureSet } = useMarkdownEditor({
+        value,
+        onChange,
+        features,
+        placeholder,
+        editable,
+        autofocus,
+    });
+
+    const contextValue = useMemo(() => ({ editor, features: featureSet }), [editor, featureSet]);
+
+    return (
+        <MarkdownEditorContext.Provider value={contextValue}>
+            <div {...overrides?.root} className={clsx(styles.root, className, overrides?.root?.className)}>
+                <div
+                    {...overrides?.editorContainer}
+                    className={clsx(styles.editorContainer, overrides?.editorContainer?.className)}
+                    data-status={status}
+                    data-disabled={!editable}
+                >
+                    {children}
+                    <div
+                        className={styles.editorContent}
+                        style={
+                            {
+                                '--markdown-base-font-size': `var(--pte-new-typography-styles-${size}-fontSize)`,
+                            } as React.CSSProperties
+                        }
+                    >
+                        <EditorContent editor={editor} />
+                    </div>
+                </div>
+            </div>
+        </MarkdownEditorContext.Provider>
+    );
+};

package/src/stories/markdowneditor/MarkdownEditorContext.tsx

@@ -0,0 +1,17 @@
+'use client';
+
+import type { Editor } from '@tiptap/react';
+import { createContext, useContext } from 'react';
+import type { MarkdownEditorFeature } from './features';
+
+export type MarkdownEditorContextValue = {
+    editor: Editor | null;
+    features: Set<MarkdownEditorFeature>;
+};
+
+export const MarkdownEditorContext = createContext<MarkdownEditorContextValue>({
+    editor: null,
+    features: new Set(),
+});
+
+export const useMarkdownEditorContext = () => useContext(MarkdownEditorContext);

package/src/stories/markdowneditor/ToolbarButton.module.scss

@@ -0,0 +1,35 @@
+.button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    border: none;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--pte-new-colors-contentSecondary);
+    cursor: pointer;
+    padding: 0;
+    font-size: 13px;
+    font-family: inherit;
+    transition:
+        background-color var(--pte-new-animations-interaction, 150ms) ease,
+        color var(--pte-new-animations-interaction, 150ms) ease;
+    flex-shrink: 0;
+
+    &:hover {
+        background-color: var(--pte-new-colors-backgroundSecondary);
+        color: var(--pte-new-colors-contentPrimary);
+    }
+
+    &[data-active='true'] {
+        background-color: var(--pte-new-colors-borderSubtle);
+        color: var(--pte-new-colors-contentPrimary);
+    }
+
+    &:disabled {
+        color: var(--pte-new-colors-contentDisabled);
+        cursor: not-allowed;
+        background: transparent;
+    }
+}

package/src/stories/markdowneditor/ToolbarButton.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import { clsx } from 'clsx';
+import type { ComponentPropsWithoutRef, FC, ReactNode } from 'react';
+import styles from './ToolbarButton.module.scss';
+
+export type ToolbarButtonProps = {
+    /** Whether the button is currently active (e.g., bold is on). */
+    isActive?: boolean;
+    /** The action to perform when clicked. */
+    onAction: () => void;
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+    /** Icon or label content. */
+    children: ReactNode;
+    /** Optional tooltip text. */
+    tooltip?: string;
+    /** Prop overrides for the button element. */
+    overrides?: {
+        button?: ComponentPropsWithoutRef<'button'>;
+    };
+};
+
+/**
+ * A toolbar button used in FixedToolbar and FloatingToolbar.
+ * Uses onMouseDown instead of onClick to prevent stealing editor focus.
+ */
+export const ToolbarButton: FC<ToolbarButtonProps> = ({
+    isActive = false,
+    onAction,
+    disabled = false,
+    children,
+    tooltip,
+    overrides,
+}) => {
+    return (
+        <button
+            type="button"
+            title={tooltip}
+            disabled={disabled}
+            data-active={isActive}
+            {...overrides?.button}
+            className={clsx(styles.button, overrides?.button?.className)}
+            onMouseDown={(e) => {
+                e.preventDefault();
+                if (!disabled) onAction();
+            }}
+        >
+            {children}
+        </button>
+    );
+};

package/src/stories/markdowneditor/features.ts

@@ -0,0 +1,92 @@
+import Image from '@tiptap/extension-image';
+import Placeholder from '@tiptap/extension-placeholder';
+import { Table } from '@tiptap/extension-table';
+import TableCell from '@tiptap/extension-table-cell';
+import TableHeader from '@tiptap/extension-table-header';
+import TableRow from '@tiptap/extension-table-row';
+import TaskItem from '@tiptap/extension-task-item';
+import TaskList from '@tiptap/extension-task-list';
+import { Markdown } from '@tiptap/markdown';
+import type { Extensions } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+
+export const FEATURES = [
+    'bold',
+    'italic',
+    'strikethrough',
+    'heading',
+    'blockquote',
+    'horizontalRule',
+    'bulletList',
+    'orderedList',
+    'taskList',
+    'codeBlock',
+    'code',
+    'link',
+    'image',
+    'table',
+] as const;
+
+export type MarkdownEditorFeature = (typeof FEATURES)[number];
+
+export const ALL_FEATURES: MarkdownEditorFeature[] = [...FEATURES];
+
+/**
+ * Builds the Tiptap extensions array based on enabled features.
+ * Always includes: Document, Paragraph, Text, History, Markdown, Placeholder.
+ * Conditionally includes StarterKit sub-extensions and standalone extensions.
+ */
+export function buildExtensions(features: Set<MarkdownEditorFeature>, placeholder?: string): Extensions {
+    const extensions: Extensions = [
+        StarterKit.configure({
+            bold: features.has('bold') ? {} : false,
+            italic: features.has('italic') ? {} : false,
+            strike: features.has('strikethrough') ? {} : false,
+            heading: features.has('heading') ? { levels: [1, 2, 3, 4, 5, 6] } : false,
+            blockquote: features.has('blockquote') ? {} : false,
+            horizontalRule: features.has('horizontalRule') ? {} : false,
+            bulletList: features.has('bulletList') ? {} : false,
+            orderedList: features.has('orderedList') ? {} : false,
+            listItem: features.has('bulletList') || features.has('orderedList') ? {} : false,
+            codeBlock: features.has('codeBlock') ? {} : false,
+            code: features.has('code') ? {} : false,
+            link: features.has('link')
+                ? {
+                      openOnClick: false,
+                      HTMLAttributes: {
+                          rel: 'noopener noreferrer',
+                          target: '_blank',
+                      },
+                  }
+                : false,
+        }),
+        Markdown,
+        Placeholder.configure({
+            placeholder: placeholder ?? '',
+            showOnlyCurrent: false,
+        }),
+    ];
+
+    if (features.has('taskList')) {
+        extensions.push(TaskList);
+        extensions.push(TaskItem.configure({ nested: true }));
+    }
+
+    if (features.has('table')) {
+        extensions.push(Table.configure({ resizable: false }));
+        extensions.push(TableRow);
+        extensions.push(TableCell);
+        extensions.push(TableHeader);
+    }
+
+    if (features.has('image')) {
+        extensions.push(
+            Image.configure({
+                inline: false,
+                allowBase64: true,
+            }),
+        );
+    }
+
+    return extensions;
+}

package/src/stories/markdowneditor/index.ts

@@ -0,0 +1,11 @@
+export type { FixedToolbarProps } from './FixedToolbar';
+export { FixedToolbar } from './FixedToolbar';
+export type { FloatingToolbarProps } from './FloatingToolbar';
+export { FloatingToolbar } from './FloatingToolbar';
+export type { MarkdownEditorFeature } from './features';
+export { ALL_FEATURES, FEATURES } from './features';
+export type { MarkdownEditorProps } from './MarkdownEditor';
+export { MarkdownEditor } from './MarkdownEditor';
+export { useMarkdownEditorContext } from './MarkdownEditorContext';
+export type { ToolbarButtonProps } from './ToolbarButton';
+export { ToolbarButton } from './ToolbarButton';

package/src/stories/markdowneditor/useMarkdownEditor.ts

@@ -0,0 +1,75 @@
+'use client';
+
+import { useEditor } from '@tiptap/react';
+import { useEffect, useMemo, useRef } from 'react';
+import type { MarkdownEditorFeature } from './features';
+import { ALL_FEATURES, buildExtensions } from './features';
+
+export type UseMarkdownEditorOptions = {
+    /** The markdown string value (controlled). */
+    value: string;
+    /** Fires with the updated markdown string on every edit. */
+    onChange?: (value: string) => void;
+    /** Whitelist of formatting features. Defaults to ALL_FEATURES. */
+    features?: MarkdownEditorFeature[];
+    /** Placeholder text when the editor is empty. */
+    placeholder?: string;
+    /** Whether the editor is editable. @default true */
+    editable?: boolean;
+    /** Whether to autofocus the editor on mount. @default false */
+    autofocus?: boolean;
+};
+
+export function useMarkdownEditor({
+    value,
+    onChange,
+    features = ALL_FEATURES,
+    placeholder,
+    editable = true,
+    autofocus = false,
+}: UseMarkdownEditorOptions) {
+    const featureSet = useMemo(() => new Set(features), [features]);
+    const extensions = useMemo(() => buildExtensions(featureSet, placeholder), [featureSet, placeholder]);
+
+    // Track the last value we sent via onChange to prevent circular updates
+    const lastOnChangeValue = useRef(value);
+
+    const editor = useEditor({
+        extensions,
+        // Empty strings produce no DOM nodes with contentType: 'markdown',
+        // which breaks the placeholder. Only use markdown parsing for non-empty content.
+        content: value || undefined,
+        contentType: value ? 'markdown' : undefined,
+        editable,
+        autofocus,
+        immediatelyRender: false,
+        onUpdate: ({ editor: ed }) => {
+            const markdown = ed.getMarkdown();
+            lastOnChangeValue.current = markdown;
+            onChange?.(markdown);
+        },
+    });
+
+    // Sync external value changes into the editor (controlled mode)
+    useEffect(() => {
+        if (!editor || editor.isDestroyed) return;
+
+        // Skip if this value came from our own onChange
+        if (value === lastOnChangeValue.current) return;
+
+        const currentMarkdown = editor.getMarkdown();
+        if (value !== currentMarkdown) {
+            editor.commands.setContent(value, { contentType: 'markdown', emitUpdate: false });
+            lastOnChangeValue.current = value;
+        }
+    }, [editor, value]);
+
+    // Sync editable state
+    useEffect(() => {
+        if (editor && !editor.isDestroyed) {
+            editor.setEditable(editable);
+        }
+    }, [editor, editable]);
+
+    return { editor, featureSet };
+}