or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-udecode--plate-alignment

Text alignment plugin for Plate rich-text editor framework

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 4 months ago
Describes: pkg:npm/@udecode/plate-alignment@49.0.x

To install, run

npx @tessl/cli install tessl/npm-udecode--plate-alignment@49.0.0

Plate Alignment

Plate Alignment is a text alignment plugin for the Plate rich-text editor framework. It provides both headless core functionality and React components to enable text alignment capabilities (left, center, right, justify, start, end) in Plate-based editors. The plugin supports HTML parsing, integrates seamlessly with Plate's plugin system, and offers transform functions for programmatic alignment control.

Package Information

Package Name: @udecode/plate-alignment
Package Type: npm
Language: TypeScript
Installation: npm install @udecode/plate-alignment

Core Imports

import { BaseTextAlignPlugin, setAlign, type Alignment } from "@udecode/plate-alignment";

For React functionality:

import { TextAlignPlugin } from "@udecode/plate-alignment/react";

CommonJS:

const { BaseTextAlignPlugin, setAlign } = require("@udecode/plate-alignment");
const { TextAlignPlugin } = require("@udecode/plate-alignment/react");

Basic Usage

import { createPlateEditor } from "@udecode/plate";
import { BaseTextAlignPlugin, setAlign } from "@udecode/plate-alignment";

// Create editor with alignment plugin
const editor = createPlateEditor({
  plugins: [
    BaseTextAlignPlugin.configure({
      // Plugin configuration options
    }),
  ],
});

// Programmatically set alignment
setAlign(editor, "center");
setAlign(editor, "right");
setAlign(editor, "justify");

For React applications:

import { Plate } from "@udecode/plate/react";
import { TextAlignPlugin } from "@udecode/plate-alignment/react";

function MyEditor() {
  return (
    <Plate
      plugins={[
        TextAlignPlugin.configure({
          // Plugin configuration options
        }),
      ]}
    >
      {/* Editor components */}
    </Plate>
  );
}

Architecture

The package is structured around the Plate plugin architecture:

BaseTextAlignPlugin: Core headless plugin that provides the alignment functionality
TextAlignPlugin: React wrapper that extends the base plugin for React applications
Transform Functions: Programmatic API for setting alignment via setAlign function
HTML Support: Automatic parsing of textAlign CSS styles during HTML deserialization
Node Properties: Alignment stored as align property on editor nodes

Capabilities

Base Text Alignment Plugin

Core headless plugin that adds text alignment functionality to any Plate editor.

/**
 * Creates a plugin that adds alignment functionality to the editor.
 * Provides HTML parsing, node property management, and transform integration.
 */
const BaseTextAlignPlugin: SlatePlugin;

Plugin Configuration:

The plugin is created with these specific configuration options:

BaseTextAlignPlugin = createSlatePlugin({
  key: KEYS.textAlign,
  inject: {
    isBlock: true,
    nodeProps: {
      defaultNodeValue: 'start',
      nodeKey: 'align',
      styleKey: 'textAlign',
      validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
    },
    targetPlugins: [KEYS.p],
  },
});

Key: Uses KEYS.textAlign from Plate
Default Value: 'start' - when set to default, the property is removed
Valid Values: ['start', 'left', 'center', 'right', 'end', 'justify']
Target Plugins: Applies to paragraph plugins (KEYS.p) by default
Node Property: Stores alignment in align property on editor nodes
Style Mapping: Maps to CSS textAlign property during HTML parsing

HTML Deserialization: Automatically parses textAlign CSS styles from HTML elements during editor initialization.

Extended Transforms:

set: Transform function for setting alignment (bound to setAlign)

Set Alignment Transform

Programmatically sets text alignment on editor nodes.

/**
 * Transform function to set text alignment on editor nodes
 * @param editor - The Slate editor instance
 * @param value - The alignment value to set
 * @param setNodesOptions - Optional configuration for setNodes operation
 */
function setAlign(
  editor: SlateEditor,
  value: Alignment,
  setNodesOptions?: SetNodesOptions
): void;

Behavior:

If value equals the default alignment ('start'), calls editor.tf.unsetNodes() to remove the alignment property completely
Otherwise, calls editor.tf.setNodes() to set the alignment property on matching nodes
Uses getInjectMatch() to determine which nodes should be targeted based on the plugin's inject configuration
Supports all SetNodesOptions for advanced node targeting (at, match, etc.)

Usage Example:

import { setAlign } from "@udecode/plate-alignment";
import { useEditorRef } from "@udecode/plate/react";

function AlignmentControls() {
  const editor = useEditorRef();

  const handleAlign = (alignment: Alignment) => {
    setAlign(editor, alignment);
  };

  return (
    <div>
      <button onClick={() => handleAlign("left")}>Left</button>
      <button onClick={() => handleAlign("center")}>Center</button>
      <button onClick={() => handleAlign("right")}>Right</button>
      <button onClick={() => handleAlign("justify")}>Justify</button>
    </div>
  );
}

React Text Alignment Plugin

React-compatible version of the base alignment plugin for use in React applications.

/**
 * React-compatible text alignment plugin
 * Wraps BaseTextAlignPlugin with React-specific functionality
 */
const TextAlignPlugin: PlatePlugin;

Usage in React Editor:

import { useEditorRef } from "@udecode/plate/react";
import { TextAlignPlugin, setAlign } from "@udecode/plate-alignment/react";

function AlignmentToolbar() {
  const editor = useEditorRef();

  const handleAlign = (value: Alignment) => {
    setAlign(editor, value);
    // Focus editor after setting alignment
    editor.tf.focus();
  };

  return (
    <div>
      <button onClick={() => handleAlign("left")}>Align Left</button>
      <button onClick={() => handleAlign("center")}>Align Center</button>
      <button onClick={() => handleAlign("right")}>Align Right</button>
      <button onClick={() => handleAlign("justify")}>Justify</button>
    </div>
  );
}

Types

/**
 * Union type defining valid text alignment values
 */
type Alignment = 'center' | 'end' | 'justify' | 'left' | 'right' | 'start';

/**
 * Core Slate editor interface extended with Plate functionality
 * Includes plugin management, transforms, and API methods
 */
interface SlateEditor extends BaseEditor {
  api: EditorApi & UnionToIntersection<InferApi<CorePlugin>>;
  tf: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
  transforms: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
  plugins: Record<string, AnyEditorPlugin>;
  getPlugin<C extends AnyPluginConfig>(plugin: WithRequiredKey<C>): EditorPlugin<C>;
  // ... additional Plate-specific methods
}

/**
 * Options for setNodes operations supporting query matching and node targeting
 */
interface SetNodesOptions<V extends Value = Value> {
  /** Match specific nodes using predicates */
  match?: Predicate<NodeIn<V>>;
  /** Comparison function for property updates */
  compare?: PropsCompare;
  /** Merge function for combining properties */
  merge?: PropsMerge;
  /** Whether to split text nodes */
  split?: boolean;
  /** Apply only to text nodes in non-void nodes */
  marks?: boolean;
  /** Match by node ID */
  id?: boolean | string;
  /** Match block nodes only */
  block?: boolean;
  // ... additional query options
}

/**
 * Core headless plugin interface for Slate functionality
 */
interface SlatePlugin<C extends AnyPluginConfig = PluginConfig> extends BasePlugin<C> {
  /** Unique plugin identifier */
  key: C['key'];
  /** Extend editor with custom functionality */
  extendEditor?: ExtendEditor<WithAnyKey<C>>;
  /** Plugin injection configuration */
  inject: {
    nodeProps?: InjectNodeProps<WithAnyKey<C>>;
    targetPlugins?: string[];
    // ... additional injection options
  };
  /** Parser configuration for HTML/markdown */
  parsers: { /* parser configuration */ };
  // ... additional plugin properties
}

/**
 * React-compatible plugin interface extending SlatePlugin with React features
 */
interface PlatePlugin<C extends AnyPluginConfig = PluginConfig> extends SlatePlugin<C> {
  /** React hooks for component lifecycle */
  useHooks?: UseHooks<WithAnyKey<C>>;
  /** DOM event handlers */
  handlers: DOMHandlers<WithAnyKey<C>> & {
    onChange?: OnChange<WithAnyKey<C>>;
  };
  /** React component rendering */
  render: { /* render configuration */ };
  // ... additional React-specific properties
}