@sovann72-dev/lynqify-ui 1.0.0

package/src/components/RichTextEditor/Extension/Indent/indent.handlers.ts

@@ -0,0 +1,121 @@
+import { TextSelection } from '@tiptap/pm/state';
+import type { CommandProps } from '@tiptap/react';
+
+import { isListParent, isTextNode } from './indent.types';
+import type { IndentHandler } from './indent.types';
+
+/**
+ * Multi-node selection handler: bulk-bump indent on all selected nodes.
+ * Triggers when >1 indentable node (text or list) exists in the selection range.
+ */
+export const handleIndentMultiNodeSelection: IndentHandler = (commands: CommandProps) => {
+  const { tr, state, dispatch } = commands;
+  const { selection } = state;
+  const { $from, $to } = selection;
+
+  if (selection.empty) return false;
+
+  // Search for indentable node
+  let indentableNodeCount = 0;
+
+  // Traverse for nodes in between the selection
+  state.doc.nodesBetween($from.pos, $to.pos, (node: any) => {
+    if (isListParent(node.type.name) || isTextNode(node.type.name)) indentableNodeCount++;
+  });
+
+  // Early return if can't find the indentable node
+  if (indentableNodeCount <= 1) return false;
+
+  // Construct set for processing the to-be indented positions
+  const processedPositions = new Set<number>();
+  let hasApplied = false;
+
+  // Traverse through again
+  state.doc.nodesBetween($from.pos, $to.pos, (node: any, pos: number) => {
+    // Target only list/text elements
+    const isTarget = isListParent(node.type.name) || isTextNode(node.type.name);
+    if (!isTarget || processedPositions.has(pos)) return true;
+
+    processedPositions.add(pos);
+    tr.setNodeAttribute(pos, 'indent', (node.attrs?.indent ?? 0) + 1);
+    hasApplied = true;
+    return false;
+  });
+
+  if (hasApplied) {
+    tr.setMeta('addToHistory', true);
+    dispatch?.(tr);
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * List handler: single-item lists get visual indent bump, multi-item lists get structural sink.
+ * Walks up the ancestor tree from cursor to find the nearest enclosing list.
+ */
+export const handleIndentList: IndentHandler = (commands: CommandProps) => {
+  const { tr, state, dispatch } = commands;
+  const { selection } = state;
+  const { $from } = selection;
+
+  // Walk up the ancestor tree from the cursor to find the nearest enclosing list.
+  let enclosingList: any = null;
+  let enclosingListItem: any = null;
+
+  for (let depth = $from.depth; depth > 0; depth--) {
+    const ancestor = $from.node(depth);
+    if (isListParent(ancestor.type.name)) {
+      enclosingList = { ...ancestor, pos: $from.before(depth) };
+      enclosingListItem = { ...$from.node(depth + 1), pos: $from.before(depth + 1) };
+      break;
+    }
+  }
+
+  if (!enclosingList || !enclosingListItem) return false;
+
+  // WHY: A list with only one item cannot be structurally sunk further (no sibling to nest under).
+  // We increase the visual indent attribute instead, which mirrors Google Docs behavior.
+  const listHasOnlyOneItem = enclosingList.content?.childCount === 1;
+  if (listHasOnlyOneItem && selection instanceof TextSelection) {
+    const existingIndent = enclosingList.attrs.indent ?? 0;
+    tr.setNodeAttribute(enclosingList.pos, 'indent', existingIndent + 1);
+    tr.setMeta('addToHistory', false);
+    dispatch?.(tr);
+    return true;
+  }
+
+  // WHY: For multi-item lists, we structurally sink the list item under its predecessor
+  // (standard list nesting). Lists don't require the cursor to be at line start.
+  commands
+    .chain()
+    .focus()
+    .sinkListItem('listItem')
+    .updateAttributes('bulletList', { indent: 1 })
+    .updateAttributes('orderedList', { indent: 1 })
+    .run();
+  return true;
+};
+
+/**
+ * Text node handler: bump indent on plain paragraphs and headings (not inside a list).
+ * Only triggers on a blinking cursor (TextSelection).
+ */
+export const handleIndentTextNode: IndentHandler = (commands: CommandProps) => {
+  const { tr, state, dispatch } = commands;
+  const { selection } = state;
+  const { $from } = selection;
+
+  const currentNode = $from.node();
+  const isIndentableTextNode =
+    isTextNode(currentNode.type.name) && selection instanceof TextSelection;
+
+  if (!isIndentableTextNode) return false;
+
+  const existingIndent = currentNode.attrs.indent ?? 0;
+  tr.setNodeAttribute($from.before($from.depth), 'indent', existingIndent + 1);
+  tr.setMeta('addToHistory', false);
+  dispatch?.(tr);
+  return true;
+};

package/src/components/RichTextEditor/Extension/Indent/indent.types.ts

@@ -0,0 +1,63 @@
+// Predicate utilities for node type classification
+export { isListParent, isList, isTextNode } from './indent.utils';
+
+/**
+ * The data snapshot passed into every keyboard-shortcut handler.
+ * Resolved once per keypress so each handler receives a stable, consistent view
+ * of the editor state — no handler can accidentally observe mid-chain mutations.
+ */
+export interface ShortcutContext {
+  editor: any;
+  state: any;
+  view: any;
+  $from: any;
+  $to: any;
+  selectionIsEmpty: boolean;
+  currentNode: any;
+}
+
+/**
+ * A single link in a Chain of Responsibility for keyboard shortcuts.
+ * Returns `true` if this handler consumed the event (chain stops),
+ * or `false` to pass control to the next handler in the chain.
+ */
+export type ShortcutHandler = (context: ShortcutContext) => boolean;
+
+/**
+ * Runs each handler in order. Stops and returns `true` as soon as one
+ * handler claims the event. Returns `false` if no handler matched.
+ */
+export function runChain(handlers: ShortcutHandler[], context: ShortcutContext): boolean {
+  for (const handler of handlers) {
+    if (handler(context)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * CommandProps is provided by TipTap's addCommands.
+ * Contains transaction, state, dispatch, and helper chains/commands.
+ */
+import type { CommandProps } from '@tiptap/react';
+
+/**
+ * A single link in a Chain of Responsibility for indent commands.
+ * Returns `true` if this handler consumed the command (chain stops),
+ * or `false` to pass control to the next handler in the chain.
+ */
+export type IndentHandler = (commands: CommandProps) => boolean;
+
+/**
+ * Runs each indent handler in order. Stops and returns `true` as soon as one
+ * handler claims the command. Returns `false` if no handler matched.
+ */
+export function runIndentChain(handlers: IndentHandler[], commands: CommandProps): boolean {
+  let index = 0;
+  for (const handler of handlers) {
+    index = index++;
+    if (handler(commands)) return true;
+  }
+  return false;
+}

package/src/components/RichTextEditor/Extension/Indent/indent.utils.ts

@@ -0,0 +1,8 @@
+/**
+ * Predicates that classify ProseMirror node types used throughout the indent logic.
+ * Kept as plain functions (not constants/enums) so TypeScript infers the correct
+ * string-narrowing type when used in conditional branches.
+ */
+export const isListParent = (name: string) => name === 'bulletList' || name === 'orderedList';
+export const isList = (name: string) => name === 'listItem';
+export const isTextNode = (name: string) => name === 'paragraph' || name === 'heading';

package/src/components/RichTextEditor/Extension/Indent/outdent.handlers.ts

@@ -0,0 +1,71 @@
+import { NodeRange } from '@tiptap/pm/model';
+import { liftTarget } from '@tiptap/pm/transform';
+
+import { ShortcutHandler, isListParent, isList, isTextNode } from './indent.types';
+
+/**
+ * WHY: When a user highlights across multiple lines or list items,
+ * we want to bulk-decrease their indentation level or lift them structurally out of nesting.
+ */
+export const handleOutdentMultiNodeSelection: ShortcutHandler = ({
+  state,
+  view,
+  $from,
+  $to,
+  selectionIsEmpty,
+}) => {
+  if (selectionIsEmpty) return false;
+
+  let selectedIndentableNodesCount = 0;
+  state.doc.nodesBetween($from.pos, $to.pos, (node: any) => {
+    if (isList(node.type.name) || isTextNode(node.type.name)) {
+      selectedIndentableNodesCount++;
+    }
+  });
+
+  const isMultiNodeSelection = selectedIndentableNodesCount > 1;
+  if (!isMultiNodeSelection) return false;
+
+  const { tr, doc } = state;
+  let hasAppliedAnyIndent = false;
+  const processedListPositions = new Set<number>();
+
+  doc.nodesBetween($from.pos, $to.pos, (node: any, pos: number) => {
+    if (isListParent(node.type.name) && (node.attrs.indent ?? 0) > 0) {
+      if (!processedListPositions.has(pos)) {
+        processedListPositions.add(pos);
+
+        const currentIndent = node.attrs.indent ?? 0;
+        tr.setNodeAttribute(pos, 'indent', Math.max(0, currentIndent - 1));
+        hasAppliedAnyIndent = true;
+
+        const $start = state.doc.resolve(pos);
+        const $end = state.doc.resolve(pos + node.nodeSize);
+        const range = new NodeRange($start, $end, $start.depth);
+        const target = liftTarget(range);
+
+        if (target != null) {
+          tr.lift(range, target);
+          hasAppliedAnyIndent = true;
+        }
+      }
+      return false; // Prevent recursing into children of processed nodes
+    }
+
+    if (isTextNode(node.type.name) && (node.attrs.indent ?? 0) > 0) {
+      const currentIndent = node.attrs.indent ?? 0;
+      tr.setNodeAttribute(pos, 'indent', Math.max(0, currentIndent - 1));
+      hasAppliedAnyIndent = true;
+    }
+
+    return true;
+  });
+
+  if (hasAppliedAnyIndent) {
+    tr.setMeta('addToHistory', true);
+    view.dispatch(tr);
+    return true;
+  }
+
+  return false;
+};

package/src/components/RichTextEditor/Extension/Indent/shifttab.indent.handlers.ts

@@ -0,0 +1,133 @@
+import { NodeRange } from '@tiptap/pm/model';
+import { TextSelection } from '@tiptap/pm/state';
+import { liftTarget } from '@tiptap/pm/transform';
+
+import { ShortcutHandler, isListParent, isList, isTextNode } from './indent.types';
+
+/**
+ * WHY: When a user highlights across multiple lines or list items,
+ * we want to bulk-decrease their indentation level or lift them structurally out of nesting.
+ */
+export const handleShiftTabMultiNodeSelection: ShortcutHandler = ({
+  state,
+  view,
+  $from,
+  $to,
+  selectionIsEmpty,
+}) => {
+  if (selectionIsEmpty) return false;
+
+  let selectedIndentableNodesCount = 0;
+  state.doc.nodesBetween($from.pos, $to.pos, (node: any) => {
+    if (isList(node.type.name) || isTextNode(node.type.name)) {
+      selectedIndentableNodesCount++;
+    }
+  });
+
+  const isMultiNodeSelection = selectedIndentableNodesCount > 1;
+  if (!isMultiNodeSelection) return false;
+
+  const { tr, doc } = state;
+  let hasAppliedAnyIndent = false;
+  const processedListPositions = new Set<number>();
+
+  doc.nodesBetween($from.pos, $to.pos, (node: any, pos: number) => {
+    if (isListParent(node.type.name) && (node.attrs.indent ?? 0) > 0) {
+      if (!processedListPositions.has(pos)) {
+        processedListPositions.add(pos);
+
+        const currentIndent = node.attrs.indent ?? 0;
+        tr.setNodeAttribute(pos, 'indent', Math.max(0, currentIndent - 1));
+        hasAppliedAnyIndent = true;
+
+        const $start = state.doc.resolve(pos);
+        const $end = state.doc.resolve(pos + node.nodeSize);
+        const range = new NodeRange($start, $end, $start.depth);
+        const target = liftTarget(range);
+
+        if (target != null) {
+          tr.lift(range, target);
+          hasAppliedAnyIndent = true;
+        }
+      }
+      return false; // Prevent recursing into children of processed nodes
+    }
+
+    if (isTextNode(node.type.name) && (node.attrs.indent ?? 0) > 0) {
+      const currentIndent = node.attrs.indent ?? 0;
+      tr.setNodeAttribute(pos, 'indent', Math.max(0, currentIndent - 1));
+      hasAppliedAnyIndent = true;
+    }
+
+    return true;
+  });
+
+  if (hasAppliedAnyIndent) {
+    tr.setMeta('addToHistory', true);
+    view.dispatch(tr);
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * WHY: A list item at the outermost structural level (no enclosing parent list) with no visual
+ * indent has nothing to reduce. Without this guard, the event falls through to TipTap's List
+ * extension which calls liftListItem and ejects the item out of the list entirely.
+ */
+export const handleShiftTabInTopLevelListItem: ShortcutHandler = ({ $from, selectionIsEmpty }) => {
+  if (!selectionIsEmpty) return false;
+
+  let foundList = false;
+  let hasParentList = false;
+  let enclosingListIndent = 0;
+
+  for (let d = $from.depth; d > 0; d--) {
+    const node = $from.node(d);
+    if (isListParent(node.type.name)) {
+      if (!foundList) {
+        foundList = true;
+        enclosingListIndent = node.attrs?.indent ?? 0;
+      } else {
+        hasParentList = true;
+        break;
+      }
+    }
+  }
+
+  const isInTopLevelList = foundList && !hasParentList;
+  if (!isInTopLevelList) return false;
+
+  return enclosingListIndent === 0;
+};
+
+/**
+ * WHY: An empty trailing paragraph after a list has no indent to reduce, so Shift-Tab
+ * falls through all handlers and the browser steals focus. We intercept and move the
+ * cursor into the last list item instead, which matches the user's intent of "go back in."
+ */
+export const handleShiftTabFromEmptyParagraphAfterList: ShortcutHandler = ({
+  state,
+  view,
+  $from,
+  currentNode,
+  selectionIsEmpty,
+}) => {
+  if (!selectionIsEmpty) return false;
+
+  const isEmptyParagraph = currentNode.type.name === 'paragraph' && currentNode.content.size === 0;
+  if (!isEmptyParagraph) return false;
+
+  const nodePos = $from.before($from.depth);
+  const prevNode = state.doc.resolve(nodePos).nodeBefore;
+  const isPrecededByList = prevNode != null && isListParent(prevNode.type.name);
+  if (!isPrecededByList) return false;
+
+  // WHY: nodePos - 1 is the last position inside the list's closing boundary.
+  // TextSelection.near with bias -1 resolves it to the end of the last list item's text content.
+  const $endOfList = state.doc.resolve(nodePos - 1);
+  const tr = state.tr.setSelection(TextSelection.near($endOfList, -1));
+  view.dispatch(tr);
+  return true;
+};

package/src/components/RichTextEditor/Extension/Indent/tab.indent.handlers.ts

@@ -0,0 +1,103 @@
+import { ShortcutHandler, isListParent, isList, isTextNode } from './indent.types';
+
+/**
+ * WHY: When a user highlights across multiple lines or list items,
+ * we want to bulk-increase their indentation level as a group.
+ */
+export const handleTabMultiNodeSelection: ShortcutHandler = ({
+  state,
+  view,
+  $from,
+  $to,
+  selectionIsEmpty,
+}) => {
+  if (selectionIsEmpty) return false;
+
+  let selectedIndentableNodesCount = 0;
+  state.doc.nodesBetween($from.pos, $to.pos, (node: any) => {
+    if (isList(node.type.name) || isTextNode(node.type.name)) {
+      selectedIndentableNodesCount++;
+    }
+  });
+
+  const isMultiNodeSelection = selectedIndentableNodesCount > 1;
+  if (!isMultiNodeSelection) return false;
+
+  const { tr, doc } = state;
+  let hasAppliedAnyIndent = false;
+  const processedListPositions = new Set<number>();
+
+  doc.nodesBetween($from.pos, $to.pos, (node: any, pos: number) => {
+    const isTargetNode = isListParent(node.type.name) || isTextNode(node.type.name);
+
+    if (isTargetNode && !processedListPositions.has(pos)) {
+      processedListPositions.add(pos);
+      const currentIndent = node.attrs.indent ?? 0;
+      tr.setNodeAttribute(pos, 'indent', currentIndent + 1);
+      hasAppliedAnyIndent = true;
+      return false; // Prevent recursing into children of processed nodes
+    }
+    return true;
+  });
+
+  if (hasAppliedAnyIndent) {
+    tr.setMeta('addToHistory', true);
+    view.dispatch(tr);
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * WHY: If a user has highlighted a specific word or phrase inside a single text line,
+ * pressing Tab shouldn't move the entire line layout. It should just overwrite the text with a \t.
+ */
+export const handleTabSingleNodeTextSelection: ShortcutHandler = ({
+  state,
+  view,
+  $from,
+  selectionIsEmpty,
+}) => {
+  if (selectionIsEmpty) return false;
+
+  // WHY: A selection inside a list item should indent the list, not insert a literal tab.
+  const isInsideList = $from.path.some((entry: any) => entry?.type?.name === 'listItem');
+  if (isInsideList) return false;
+
+  view.dispatch(state.tr.insertText('\t'));
+  return true;
+};
+
+/**
+ * WHY: If the user is currently typing inside a List Item but they haven't highlighted anything,
+ * let the List extension handle indenting structurally.
+ */
+export const handleTabInsideListItem: ShortcutHandler = ({ editor, currentNode, $from }) => {
+  const isLineEmpty = currentNode.content.size === 0;
+  const parentNode = $from.node($from.depth - 1);
+  const isInsideListItem = parentNode && isList(parentNode.type.name);
+
+  if (isInsideListItem && !isLineEmpty) {
+    editor.chain().focus().indent().focus().run();
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * WHY: If the cursor is right in the middle of a sentence, inject a literal Tab character.
+ * We only block-indent the whole line if the cursor is at the very beginning.
+ */
+export const handleTabMidTextCursor: ShortcutHandler = ({ state, view, $from, currentNode }) => {
+  const isCursorAtStart = $from.pos === $from.start();
+  const isLineEmpty = currentNode.content.size === 0;
+
+  if (!isCursorAtStart && !isLineEmpty) {
+    view.dispatch(state.tr.insertText('\t'));
+    return true;
+  }
+
+  return false;
+};

package/src/components/RichTextEditor/Extension/List/custom-list-item.extension.ts

@@ -0,0 +1,107 @@
+/**
+ * Custom List Extensions: Indent Attribute Support
+ *
+ * Extends TipTap list nodes (BulletList, OrderedList, ListItem) with indent attributes.
+ *
+ * Per FR-020: ListItem receives transferred indent from paragraph
+ * Per FR-021: Paragraph children inside lists must NOT have indent
+ * Per FR-022: List-level indent separate from item indent
+ * Per FR-030: Backward compatibility via attribute defaults
+ *
+ * @see specs/001-richtext-indent-lists/data-model.md
+ */
+
+import BulletList from '@tiptap/extension-bullet-list';
+import ListItem from '@tiptap/extension-list-item';
+import OrderedList from '@tiptap/extension-ordered-list';
+
+// CONVENTION - T009: Extend BulletList with indent attribute (FR-022)
+export const CustomBulletList = BulletList.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: {
+        default: 0, // Backward compatibility (FR-030)
+        parseHTML: (element) => parseInt(element.getAttribute('data-indent') || '0', 10),
+        renderHTML: (attributes) => {
+          if (!attributes.indent) return {};
+          return { 'data-indent': attributes.indent };
+        },
+      },
+    };
+  },
+
+  addNodeView() {
+    return ({ node }) => {
+      const indentLevel = node.attrs.indent || 0;
+      const dom = document.createElement('ul');
+      dom.setAttribute('data-indent', String(indentLevel));
+
+      // Apply padding based on indent level (20px per level)
+      if (indentLevel > 0) {
+        dom.style.paddingLeft = `${indentLevel * 20}px`;
+      }
+
+      const contentDOM = dom;
+      return { dom, contentDOM };
+    };
+  },
+});
+
+// CONVENTION - T010: Extend OrderedList with indent attribute (FR-022)
+export const CustomOrderedList = OrderedList.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: {
+        default: 0, // Backward compatibility (FR-030)
+        parseHTML: (element) => parseInt(element.getAttribute('data-indent') || '0', 10),
+        renderHTML: (attributes) => {
+          if (!attributes.indent) return {};
+          return { 'data-indent': attributes.indent };
+        },
+      },
+    };
+  },
+
+  addNodeView() {
+    return ({ node }) => {
+      const indentLevel = node.attrs.indent || 0;
+      const dom = document.createElement('ol');
+      dom.setAttribute('data-indent', String(indentLevel));
+
+      // Apply padding based on indent level (20px per level)
+      if (indentLevel > 0) {
+        dom.style.paddingLeft = `${indentLevel * 20}px`;
+      }
+
+      const contentDOM = dom;
+      return { dom, contentDOM };
+    };
+  },
+});
+
+// CONVENTION - T011: Extend ListItem with indent attribute (FR-020, FR-021)
+export const CustomListItem = ListItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      class: {
+        default: null,
+        parseHTML: (element: any) => element.getAttribute('class'),
+        renderHTML: (attributes: any) => {
+          if (!attributes.class) return {};
+          return { class: attributes.class, ...attributes };
+        },
+      },
+      indent: {
+        default: 0, // Backward compatibility (FR-030)
+        parseHTML: (element) => parseInt(element.getAttribute('data-indent') || '0', 10),
+        renderHTML: (attributes) => {
+          if (!attributes.indent) return {};
+          return { 'data-indent': attributes.indent };
+        },
+      },
+    };
+  },
+});

package/src/components/RichTextEditor/Extension/List/dynamic-bullet-styling.extension.ts

@@ -0,0 +1,40 @@
+import { Extension } from '@tiptap/core';
+import { Plugin, PluginKey } from 'prosemirror-state';
+
+// Dynamic bullet styling extension (assigns class based on nesting level)
+export const DynamicBulletStyling = Extension.create({
+  name: 'dynamicBulletStyling',
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey('dynamicBulletStyling'),
+        appendTransaction: (transactions, oldState, newState) => {
+          const tr = newState.tr;
+          let modified = false;
+          newState.doc.descendants((node, pos) => {
+            if (node.type.name === 'listItem') {
+              let nestingLevel = 0;
+
+              const $pos = newState.doc.resolve(pos);
+
+              for (let depth = $pos.depth; depth > 0; depth--) {
+                const nodeAtDepth = $pos.node(depth);
+                if (nodeAtDepth.type.name === 'bulletList') {
+                  nestingLevel = 1;
+                  break;
+                }
+              }
+
+              if (nestingLevel > 0) {
+                tr.setNodeAttribute($pos.pos, '[data-style]', 'line-height: inherit');
+                // tr.setDocAttribute('[data-style]', 'line-height: inherit');
+                modified = true;
+              }
+            }
+          });
+          return modified ? tr : null;
+        },
+      }),
+    ];
+  },
+});