CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-udecode--plate-list

List plugin for Plate rich-text editor providing indent-based list functionality with comprehensive transforms, queries, and React hooks.

—

Pending
Overview
Eval results
Files

normalizers.mddocs/

List Normalizers

Normalizer functions that automatically maintain consistent list structure and numbering. These functions are called automatically by the editor to ensure list integrity.

Capabilities

normalizeListStart

Normalizes list start numbering based on previous list items and restart markers.

/**
 * Normalizes list start numbering based on previous items and restart markers
 * @param editor - The Slate editor instance
 * @param entry - The list entry to normalize
 * @param options - Options for sibling list queries
 * @returns True if normalization was applied, false otherwise
 */
function normalizeListStart<N extends ElementOf<E>, E extends Editor = Editor>(
  editor: E,
  entry: ElementEntryOf<E>,
  options?: Partial<GetSiblingListOptions<N, E>>
): boolean;

Usage Example:

import { normalizeListStart } from "@udecode/plate-list";

// Typically called automatically by the editor
const normalized = normalizeListStart(editor, listEntry);
if (normalized) {
  console.log('List numbering was updated');
}

normalizeListNotIndented

Removes list formatting from nodes that no longer have indentation.

/**
 * Removes list formatting from nodes without indentation
 * @param editor - The Slate editor instance
 * @param entry - The node entry to check and normalize
 * @returns True if normalization was applied, false otherwise
 */
function normalizeListNotIndented(
  editor: Editor,
  entry: NodeEntry
): boolean;

Usage Example:

import { normalizeListNotIndented } from "@udecode/plate-list";

// Remove list formatting from unindented nodes
const wasNormalized = normalizeListNotIndented(editor, nodeEntry);

withInsertBreakList

Editor override that handles line breaks within todo lists, ensuring new todo items are created with unchecked state.

/**
 * Editor override for handling line breaks in todo lists
 * @param context - The editor context with transforms
 * @returns Override object with insertBreak transform
 */
function withInsertBreakList(context: {
  editor: Editor;
  tf: { insertBreak: () => void };
}): {
  transforms: {
    insertBreak(): void;
  };
};

getListExpectedListStart

Utility function that calculates the expected start number for a list item based on restart markers and previous items.

/**
 * Calculates expected list start number
 * @param entry - The current list entry
 * @param prevEntry - The previous list entry (optional)
 * @returns The expected start number
 */
function getListExpectedListStart(
  entry: NodeEntry,
  prevEntry?: NodeEntry
): number;

Usage Example:

import { getListExpectedListStart, getPreviousList } from "@udecode/plate-list";

const currentEntry = getListAbove(editor);
if (currentEntry) {
  const previousEntry = getPreviousList(editor, currentEntry);
  const expectedStart = getListExpectedListStart(currentEntry, previousEntry);
  console.log(`This list item should start at: ${expectedStart}`);
}

Normalization Flow

Automatic Normalization

The Plate List plugin automatically runs normalizers when:

  1. Insert Operations: Adding new list items
  2. Remove Operations: Deleting list items
  3. Set Operations: Changing list properties
  4. Merge/Split Operations: Combining or splitting list items

Normalization Sequence

  1. Structure Normalization: normalizeListNotIndented removes list formatting from unindented nodes
  2. Numbering Normalization: normalizeListStart updates list numbering based on sequence and restart markers
  3. Break Handling: withInsertBreakList manages line breaks in todo lists

Manual Normalization

While normalization typically happens automatically, you can trigger it manually:

import { normalizeListStart, normalizeListNotIndented } from "@udecode/plate-list";

// Normalize a specific list entry
const listEntry = getListAbove(editor);
if (listEntry) {
  // Check and fix indentation first
  normalizeListNotIndented(editor, listEntry);
  
  // Then fix numbering
  normalizeListStart(editor, listEntry);
}

List Restart Behavior

listRestart Property

Forces immediate restart of list numbering:

// This will start numbering from 5 regardless of previous items
editor.tf.setNodes({
  listRestart: 5
}, { at: listItemPath });

listRestartPolite Property

Only restarts numbering if at the beginning of a list:

// This will only restart at 1 if this is the first item in a list sequence
editor.tf.setNodes({
  listRestartPolite: 1
}, { at: listItemPath });

Expected Start Calculation

The getListExpectedListStart function follows this priority:

  1. listRestart: Always takes precedence
  2. listRestartPolite: Only applies if no previous list item
  3. Sequential: Previous item's start + 1
  4. Default: Start at 1

Integration with Editor

Plugin Integration

Normalizers are automatically integrated through the BaseListPlugin:

import { BaseListPlugin } from "@udecode/plate-list";
import { createPlateEditor } from "@udecode/plate";

const editor = createPlateEditor({
  plugins: [BaseListPlugin], // Normalizers are included automatically
});

Custom Normalization Options

Configure normalization behavior through plugin options:

const editor = createPlateEditor({
  plugins: [
    BaseListPlugin.configure({
      options: {
        getSiblingListOptions: {
          breakOnEqIndentNeqListStyleType: true,
          breakOnLowerIndent: true,
          // Custom normalization behavior
        }
      }
    })
  ],
});

Performance Considerations

  • Normalizers run within withoutNormalizing blocks to batch changes
  • Only affected list items are normalized, not the entire document
  • Normalization is skipped when no changes are needed

Common Normalization Scenarios

Fixing Broken List Sequences

// After deleting list items, numbering may be inconsistent
// Normalizers automatically fix this:
// Before: 1, 2, 4, 5 (item 3 was deleted)
// After:  1, 2, 3, 4 (automatically renumbered)

Handling Indentation Changes

// When outdenting removes all indentation:
// Before: Indented list item with listStyleType
// After:  Regular paragraph (list formatting removed)

Todo List Line Breaks

// When pressing Enter in a todo list:
// Creates new todo item with checked: false
// Maintains proper list structure

Install with Tessl CLI

npx tessl i tessl/npm-udecode--plate-list

docs

index.md

normalizers.md

plugins.md

queries.md

react-hooks.md

transforms.md

types.md

tile.json