@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/components/editor/extensions/Passage/label.spec.ts

@@ -0,0 +1,118 @@
+import { incrementLabel, decrementLabel } from './label';
+
+describe('incrementLabel', () => {
+  it('should increment the last component of a dotted label', () => {
+    expect(incrementLabel('1.5')).toBe('1.6');
+  });
+
+  it('should increment a single-component label', () => {
+    expect(incrementLabel('3')).toBe('4');
+  });
+
+  it('should increment a deeply nested label', () => {
+    expect(incrementLabel('1.2.3')).toBe('1.2.4');
+  });
+
+  it('should increment at a specific depth', () => {
+    expect(incrementLabel('1.5', 0)).toBe('2.5');
+  });
+
+  it('should increment the middle component of a three-part label', () => {
+    expect(incrementLabel('1.5.3', 1)).toBe('1.6.3');
+  });
+
+  it('should handle zero as the last component', () => {
+    expect(incrementLabel('1.0')).toBe('1.1');
+  });
+
+  it('should handle empty string', () => {
+    expect(incrementLabel('')).toBe('1');
+  });
+});
+
+describe('decrementLabel', () => {
+  it('should decrement the last component of a dotted label', () => {
+    expect(decrementLabel('1.5')).toBe('1.4');
+  });
+
+  it('should decrement a single-component label', () => {
+    expect(decrementLabel('3')).toBe('2');
+  });
+
+  it('should decrement a deeply nested label', () => {
+    expect(decrementLabel('1.2.3')).toBe('1.2.2');
+  });
+
+  it('should decrement at a specific depth', () => {
+    expect(decrementLabel('1.5', 0)).toBe('0.5');
+  });
+
+  it('should decrement the middle component of a three-part label', () => {
+    expect(decrementLabel('1.5.3', 1)).toBe('1.4.3');
+  });
+
+  it('should clamp at zero and not go negative', () => {
+    expect(decrementLabel('1.0')).toBe('1.0');
+  });
+
+  it('should clamp a single zero', () => {
+    expect(decrementLabel('0')).toBe('0');
+  });
+
+  it('should handle empty string', () => {
+    expect(decrementLabel('')).toBe('0');
+  });
+});
+
+describe('incrementLabel and decrementLabel are inverses', () => {
+  it('decrement after increment returns the original label', () => {
+    const original = '1.5';
+    expect(decrementLabel(incrementLabel(original))).toBe(original);
+  });
+
+  it('increment after decrement returns the original label', () => {
+    const original = '2.3';
+    expect(incrementLabel(decrementLabel(original))).toBe(original);
+  });
+
+  it('roundtrips at a specific depth', () => {
+    const original = '4.7.2';
+    expect(decrementLabel(incrementLabel(original, 1), 1)).toBe(original);
+  });
+});
+
+describe('normalizeLabelsAfter helpers', () => {
+  it('incrementLabel of empty string produces "1"', () => {
+    expect(incrementLabel('')).toBe('1');
+  });
+
+  it('repeated incrementLabel produces a contiguous sequence', () => {
+    let label = '1.2';
+    const sequence = [label];
+    for (let i = 0; i < 4; i++) {
+      label = incrementLabel(label);
+      sequence.push(label);
+    }
+    expect(sequence).toEqual(['1.2', '1.3', '1.4', '1.5', '1.6']);
+  });
+
+  it('repeated incrementLabel produces a contiguous sequence for single-component labels', () => {
+    let label = '3';
+    const sequence = [label];
+    for (let i = 0; i < 3; i++) {
+      label = incrementLabel(label);
+      sequence.push(label);
+    }
+    expect(sequence).toEqual(['3', '4', '5', '6']);
+  });
+
+  it('repeated incrementLabel produces a contiguous sequence for deeply nested labels', () => {
+    let label = '2.1.4';
+    const sequence = [label];
+    for (let i = 0; i < 3; i++) {
+      label = incrementLabel(label);
+      sequence.push(label);
+    }
+    expect(sequence).toEqual(['2.1.4', '2.1.5', '2.1.6', '2.1.7']);
+  });
+});

package/src/lib/components/editor/extensions/Passage/label.ts

@@ -0,0 +1,39 @@
+/**
+ * Increment the numeric component of a passage label at the given depth.
+ * If depth is -1 (default), increments the last component.
+ *
+ * Examples:
+ *   incrementLabel("1.5")      → "1.6"
+ *   incrementLabel("3")        → "4"
+ *   incrementLabel("1.5", 0)   → "2.5"
+ */
+export const incrementLabel = (label: string, depth = -1) => {
+  const labelParts: (string | number)[] = ((label as string) || '').split('.');
+  const index = depth === -1 ? labelParts.length - 1 : depth;
+  const toIncrement = `${labelParts[index]}` || '0';
+  const newVal = Number.parseInt(toIncrement) + 1;
+  labelParts[index] = newVal;
+
+  return labelParts.join('.');
+};
+
+/**
+ * Decrement the numeric component of a passage label at the given depth.
+ * If depth is -1 (default), decrements the last component.
+ * Guards against going below 0.
+ *
+ * Examples:
+ *   decrementLabel("1.5")      → "1.4"
+ *   decrementLabel("3")        → "2"
+ *   decrementLabel("1.0")      → "1.0"  (clamped at 0)
+ *   decrementLabel("1.5", 0)   → "0.5"
+ */
+export const decrementLabel = (label: string, depth = -1) => {
+  const labelParts: (string | number)[] = ((label as string) || '').split('.');
+  const index = depth === -1 ? labelParts.length - 1 : depth;
+  const toDecrement = `${labelParts[index]}` || '0';
+  const newVal = Math.max(0, Number.parseInt(toDecrement) - 1);
+  labelParts[index] = newVal;
+
+  return labelParts.join('.');
+};

package/src/lib/components/editor/extensions/Placeholder.ts

@@ -0,0 +1,9 @@
+import { cn } from '@eightyfourthousand/lib-utils';
+import { Placeholder } from '@tiptap/extensions';
+
+export default Placeholder.configure({
+  placeholder: 'Type / for commands...',
+  emptyEditorClass: cn('is-editor-empty text-gray-400'),
+  emptyNodeClass: cn('is-empty text-gray-400'),
+  includeChildren: true,
+});

package/src/lib/components/editor/extensions/SlashCommand/SlashCommand.ts

@@ -0,0 +1,65 @@
+import { Editor, Extension, Range } from '@tiptap/core';
+import { PluginKey } from '@tiptap/pm/state';
+import Suggestion, { SuggestionOptions } from '@tiptap/suggestion';
+
+type OnCommandSelect = (props: { editor: Editor; range: Range }) => void;
+
+export interface SuggestionItem {
+  title: string;
+  description: string;
+  keywords: string[];
+  command: OnCommandSelect;
+}
+
+export interface SlashCommandNodeAttributes {
+  command: OnCommandSelect;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface SlashCommandOptions<Item extends SuggestionItem = any> {
+  /**
+   * The suggestion options.
+   *
+   * @default {}
+   * @example { char: '/', pluginKey: slashCommandPluginKey, command: ({editor, range, props}) => { ... } }
+   */
+  suggestion: Omit<
+    SuggestionOptions<Item, SlashCommandNodeAttributes>,
+    'editor'
+  >;
+}
+
+/**
+ * The pluging key for the slash command extension.
+ * @default 'slashCommand'
+ */
+export const slashCommandPluginKey = new PluginKey('slashCommand');
+
+export const SlashCommand = Extension.create<SlashCommandOptions>({
+  name: 'slashCommand',
+
+  addOptions() {
+    return {
+      suggestion: {
+        char: '/',
+        pluginKey: slashCommandPluginKey,
+        command: ({ editor, range, props }) => {
+          props.command({ editor, range });
+        },
+        allow: () => {
+          // Add exceptions to when the suggestion should not be shown here.
+          return true;
+        },
+      },
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      Suggestion({
+        editor: this.editor,
+        ...this.options.suggestion,
+      }),
+    ];
+  },
+});

package/src/lib/components/editor/extensions/SlashCommand/SuggestionList.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { SlashCommandNodeAttributes, SuggestionItem } from './SlashCommand';
+import { cn } from '@eightyfourthousand/lib-utils';
+import { SuggestionKeyDownProps, SuggestionProps } from '@tiptap/suggestion';
+import { LucideIcon } from 'lucide-react';
+import { forwardRef, useEffect, useImperativeHandle, useState } from 'react';
+
+export interface CommandSuggestionItem extends SuggestionItem {
+  icon: LucideIcon;
+}
+
+export interface SuggestionListHandle {
+  onKeyDown: (props: SuggestionKeyDownProps) => boolean;
+}
+
+export type SuggestionListProps = SuggestionProps<
+  CommandSuggestionItem,
+  SlashCommandNodeAttributes
+>;
+
+const SuggestionList = forwardRef<SuggestionListHandle, SuggestionListProps>(
+  (props, ref) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const selectItem = (index: number) => {
+      const item = props.items[index];
+      if (item) {
+        props.command(item);
+      }
+    };
+
+    const incrementUp = () => {
+      setSelectedIndex(
+        (selectedIndex + props.items.length - 1) % props.items.length,
+      );
+    };
+
+    const incrementDown = () => {
+      setSelectedIndex((selectedIndex + 1) % props.items.length);
+    };
+
+    const onEnter = () => {
+      selectItem(selectedIndex);
+    };
+
+    useEffect(() => {
+      setSelectedIndex(0);
+    }, [props.items]);
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown: ({ event }) => {
+        if (event.key === 'ArrowUp') {
+          incrementUp();
+          return true;
+        }
+        if (event.key === 'ArrowDown') {
+          incrementDown();
+          return true;
+        }
+        if (event.key === 'Enter') {
+          onEnter();
+          return true;
+        }
+        return false;
+      },
+    }));
+
+    return (
+      <div
+        className={cn(
+          'z-50 bg-popover flex flex-col space-y-1 rounded-md border shadow-md transition-all p-1 max-h-[320px] w-72 overflow-y-auto',
+        )}
+      >
+        {props.items.length > 0 ? (
+          props.items.map((item, index) => (
+            <div
+              key={index}
+              className={cn(
+                'flex space-x-2 hover:bg-muted p-1 rounded-md cursor-pointer text-foreground',
+                {
+                  'bg-muted': index === selectedIndex,
+                },
+              )}
+              onClick={() => {
+                props.command(item);
+              }}
+            >
+              <div className="size-10 flex items-center justify-center border bg-popover rounded-md">
+                <item.icon className="size-4" />
+              </div>
+              <div className="flex flex-col">
+                <p className="font-medium text-sm">{item.title}</p>
+                <span className="text-xs text-muted-foreground">
+                  {item.description}
+                </span>
+              </div>
+            </div>
+          ))
+        ) : (
+          <div className="px-3 py-2 text-sm text-muted-foreground">
+            No results
+          </div>
+        )}
+      </div>
+    );
+  },
+);
+
+export default SuggestionList;

package/src/lib/components/editor/extensions/SlashCommand/Suggestions.ts

@@ -0,0 +1,185 @@
+import {
+  Heading1Icon,
+  Heading2Icon,
+  Heading3Icon,
+  LetterTextIcon,
+  ListIcon,
+  ListOrderedIcon,
+  TextQuoteIcon,
+} from 'lucide-react';
+import tippy, { Instance } from 'tippy.js';
+import { SlashCommandNodeAttributes } from './SlashCommand';
+import SuggestionList, {
+  CommandSuggestionItem,
+  SuggestionListHandle,
+  SuggestionListProps,
+} from './SuggestionList';
+import { SuggestionOptions } from '@tiptap/suggestion';
+import { ReactRenderer } from '@tiptap/react';
+
+type SuggestionType = Omit<
+  SuggestionOptions<CommandSuggestionItem, SlashCommandNodeAttributes>,
+  'editor'
+>;
+
+export const TextSuggestion: CommandSuggestionItem = {
+  title: 'Text',
+  description: 'Just start typing',
+  keywords: ['text', 'paragraph', 'p'],
+  icon: LetterTextIcon,
+  command: ({ editor }) => {
+    editor.chain().focus().toggleNode('paragraph', 'paragraph').run();
+  },
+};
+
+export const Heading1Suggestion: CommandSuggestionItem = {
+  title: 'Heading 1',
+  description: 'Big section heading.',
+  keywords: ['title', 'big', 'large', 'heading'],
+  icon: Heading1Icon,
+  command: ({ editor, range }) => {
+    editor
+      .chain()
+      .focus()
+      .deleteRange(range)
+      .setNode('heading', { level: 1 })
+      .run();
+  },
+};
+
+export const Heading2Suggestion: CommandSuggestionItem = {
+  title: 'Heading 2',
+  description: 'Medium section heading.',
+  keywords: ['subtitle', 'medium', 'heading'],
+  icon: Heading2Icon,
+  command: ({ editor, range }) => {
+    editor
+      .chain()
+      .focus()
+      .deleteRange(range)
+      .setNode('heading', { level: 2 })
+      .run();
+  },
+};
+
+export const Heading3Suggestion: CommandSuggestionItem = {
+  title: 'Heading 3',
+  description: 'Small section heading.',
+  keywords: ['subtitle', 'small', 'heading'],
+  icon: Heading3Icon,
+  command: ({ editor, range }) => {
+    editor
+      .chain()
+      .focus()
+      .deleteRange(range)
+      .setNode('heading', { level: 3 })
+      .run();
+  },
+};
+
+export const BulletListSuggestion: CommandSuggestionItem = {
+  title: 'Bullet List',
+  description: 'Create a simple bullet list.',
+  keywords: ['unordered', 'list', 'bullet'],
+  icon: ListIcon,
+  command: ({ editor, range }) => {
+    editor.chain().focus().deleteRange(range).toggleBulletList().run();
+  },
+};
+
+export const NumberListSuggestion: CommandSuggestionItem = {
+  title: 'Numbered List',
+  description: 'Create a list with numbering.',
+  keywords: ['ordered', 'list'],
+  icon: ListOrderedIcon,
+  command: ({ editor, range }) => {
+    editor.chain().focus().deleteRange(range).toggleOrderedList().run();
+  },
+};
+
+export const QuoteSuggestion: CommandSuggestionItem = {
+  title: 'Quote',
+  description: 'Capture a quote.',
+  keywords: ['blockquote'],
+  icon: TextQuoteIcon,
+  command: ({ editor, range }) =>
+    editor
+      .chain()
+      .focus()
+      .deleteRange(range)
+      .toggleNode('paragraph', 'paragraph')
+      .toggleBlockquote()
+      .run(),
+};
+
+const defaultSuggestions: CommandSuggestionItem[] = [
+  TextSuggestion,
+  Heading1Suggestion,
+  Heading2Suggestion,
+  Heading3Suggestion,
+  BulletListSuggestion,
+  NumberListSuggestion,
+  QuoteSuggestion,
+];
+
+export const getSuggestion = (
+  suggestions: CommandSuggestionItem[] = defaultSuggestions,
+): SuggestionType => {
+  return {
+    items: ({ query }) => {
+      return suggestions.filter((item: CommandSuggestionItem) => {
+        return item.keywords.some((kwd) => kwd.startsWith(query.toLowerCase()));
+      });
+    },
+    render: () => {
+      let component: ReactRenderer<SuggestionListHandle, SuggestionListProps>;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let popup: Instance<any>[];
+      return {
+        onStart: (props) => {
+          component = new ReactRenderer(SuggestionList, {
+            props,
+            editor: props.editor,
+          });
+
+          const clientRect = props.clientRect?.();
+          const getReferenceClientRect = clientRect ? () => clientRect : null;
+          popup = tippy('body', {
+            getReferenceClientRect,
+            content: component.element,
+            showOnCreate: true,
+            interactive: true,
+            trigger: 'manual',
+            placement: 'bottom-start',
+            appendTo: () => document.body,
+          });
+        },
+
+        onUpdate(props) {
+          component.updateProps(props);
+
+          if (!props.clientRect) {
+            return;
+          }
+
+          popup[0].setProps({
+            getReferenceClientRect: props.clientRect,
+          });
+        },
+
+        onKeyDown(props) {
+          if (props.event.key === 'Escape') {
+            popup[0].hide();
+            return true;
+          }
+          return component.ref?.onKeyDown(props) ?? false;
+        },
+
+        onExit() {
+          component.destroy();
+          popup[0].destroy();
+        },
+      };
+    },
+  };
+};

package/src/lib/components/editor/extensions/SmallCaps.ts

@@ -0,0 +1,110 @@
+import { Mark, mergeAttributes } from '@tiptap/core';
+import { v4 as uuidv4 } from 'uuid';
+
+export interface SmallCapsOptions {
+  /**
+   * HTML attributes to add to the small caps element.
+   * @default {}
+   * @example { class: 'foo' }
+   */
+  HTMLAttributes: Record<string, unknown>;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    smallCaps: {
+      /**
+       * Set a small caps mark
+       * @example editor.commands.setSmallCaps()
+       */
+      setSmallCaps: () => ReturnType;
+      /**
+       * Toggle a small caps mark
+       * @example editor.commands.toggleSmallCaps()
+       */
+      toggleSmallCaps: () => ReturnType;
+      /**
+       * Unset a small caps mark
+       * @example editor.commands.unsetSmallCaps()
+       */
+      unsetSmallCaps: () => ReturnType;
+    };
+  }
+}
+
+/**
+ * This extension allows you to create small caps text.
+ */
+export const SmallCaps = Mark.create<SmallCapsOptions>({
+  name: 'smallCaps',
+  addAttributes() {
+    return {
+      type: {
+        default: undefined,
+        parseHTML: (element) => element.getAttribute('data-type'),
+        renderHTML(attributes) {
+          return mergeAttributes(attributes, { 'data-type': attributes.type });
+        },
+      },
+      textStyle: {
+        default: undefined,
+        parseHTML: (element) => element.getAttribute('data-text-style'),
+        renderHTML(attributes) {
+          return mergeAttributes(attributes, {
+            'data-text-style': attributes.textStyle,
+          });
+        },
+      },
+    };
+  },
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'sm[type="small-caps"]',
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      'sm',
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
+        class: 'uppercase',
+      }),
+      0,
+    ];
+  },
+
+  addCommands() {
+    return {
+      setSmallCaps:
+        () =>
+        ({ commands }) => {
+          return commands.setMark(this.name, { uuid: uuidv4() });
+        },
+      toggleSmallCaps:
+        () =>
+        ({ commands }) => {
+          return commands.toggleMark(this.name, { uuid: uuidv4() });
+        },
+      unsetSmallCaps:
+        () =>
+        ({ commands }) => {
+          return commands.unsetMark(this.name);
+        },
+    };
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      'Mod-+': () => this.editor.commands.toggleSmallCaps(),
+    };
+  },
+});

package/src/lib/components/editor/extensions/StarterKit.ts

@@ -0,0 +1,36 @@
+import {
+  StarterKitOptions,
+  StarterKit as TiptapStarterKit,
+} from '@tiptap/starter-kit';
+import { BLOCKQUOTE_STYLE, CODE_STYLE, OL_STYLE } from '@eightyfourthousand/design-system';
+
+export const STARTER_KIT_CONFIG: Partial<StarterKitOptions> = {
+  document: false,
+  heading: false,
+  paragraph: false,
+  italic: false,
+  link: false,
+  underline: false,
+  bold: false,
+  bulletList: false,
+  listItem: false,
+  code: {
+    HTMLAttributes: {
+      class: CODE_STYLE,
+    },
+  },
+  orderedList: {
+    HTMLAttributes: {
+      class: OL_STYLE,
+    },
+  },
+  blockquote: {
+    HTMLAttributes: {
+      class: BLOCKQUOTE_STYLE,
+    },
+  },
+};
+
+export const StarterKit = TiptapStarterKit.configure(STARTER_KIT_CONFIG);
+
+export default StarterKit;