Part I: AppFlowy SimpleTable Flutter Implementation

1. Architecture Overview
2. Node/Data Model
3. Widget Hierarchy & Layout
4. Styling & Theming
5. Border System
6. Icons Reference
7. All Actions Catalog
8. New Row / New Column Actions (Deep Dive)
9. Keyboard Shortcuts
10. State Management (SimpleTableContext)
11. File Index

Part II: Open-Source React Document Table Research

12. Research Overview
13. Plate (Slate.js)
14. TipTap (ProseMirror)
15. Lexical (Meta)
16. BlockNote (ProseMirror/TipTap)
17. AFFiNE / BlockSuite
18. Other Notable Projects
19. Feature Comparison Matrix
20. Key Takeaways & Recommendations

The document table is called SimpleTable internally. It is a block-level editor plugin registered in AppFlowy's appflowy_editor system. The table is composed of three nested block types:

SimpleTableBlockWidget  (type: "simple_table")
  └── SimpleTableRowBlockWidget  (type: "simple_table_row")  ×N rows
        └── SimpleTableCellBlockWidget  (type: "simple_table_cell")  ×M columns
              └── [Any block content: paragraph, heading, image, code, etc.]

Key architectural points:

• The table is NOT the database grid. It lives purely inside the document editor.
• Operations are implemented as Dart extension methods on EditorState, using the editor's transaction system for undo/redo support.
• Desktop and mobile have separate rendering paths but share the same data model and operations.
• State is managed via SimpleTableContext, a collection of ValueNotifiers provided through Flutter's Provider.

Source: simple_table_block_component.dart

class SimpleTableBlockKeys {
  static const String type = 'simple_table';
  
  // Header toggles (bool, default false)
  static const String enableHeaderRow = 'enable_header_row';
  static const String enableHeaderColumn = 'enable_header_column';
  
  // Color maps: {index_string: color_hex_or_theme_name, ...}
  static const String columnColors = 'column_colors';
  static const String rowColors = 'row_colors';
  
  // Alignment maps: {index_string: 'left'|'center'|'right', ...}
  static const String columnAligns = 'column_aligns';
  static const String rowAligns = 'row_aligns';
  
  // Bold attribute maps: {index_string: true|false, ...}
  static const String columnBoldAttributes = 'column_bold_attributes';
  static const String rowBoldAttributes = 'row_bold_attributes';
  
  // Text color maps: {index_string: color_hex, ...}
  static const String columnTextColors = 'column_text_colors';
  static const String rowTextColors = 'row_text_colors';
  
  // Column width map: {index_string: width_double, ...}
  static const String columnWidths = 'column_widths';
  
  // Whether columns are distributed evenly (bool, default false)
  static const String distributeColumnWidthsEvenly = 'distribute_column_widths_evenly';
}

The /table slash command creates a 2x2 table and places the cursor in the first cell:

// simple_table_item.dart
final table = createSimpleTableBlockNode(columnCount: 2, rowCount: 2);

Source: _desktop_simple_table_widget.dart

SimpleTableBlockWidget
  ├── Transform.translate(offset: -tableLeftPadding)  // shift left 8px
  │   └── Align(topLeft)
  │       └── Provider(SimpleTableContext)
  │           └── MouseRegion(table block hover)
  │               └── DesktopSimpleTableWidget
  │                   └── MouseRegion(table area hover)
  │                       └── Stack
  │                           ├── MouseRegion(columns+rows hover tracking)
  │                           │   └── Scrollbar + SingleChildScrollView(horizontal)
  │                           │       └── Padding(tablePadding)
  │                           │           └── IntrinsicWidth
  │                           │               └── IntrinsicHeight
  │                           │                   └── Column(rows)
  │                           │                       ├── Row(cells) per row
  │                           │                       └── ...
  │                           ├── SimpleTableAddColumnHoverButton  (Positioned right)
  │                           ├── SimpleTableAddRowHoverButton     (Positioned bottom)
  │                           └── SimpleTableAddColumnAndRowHoverButton (Positioned bottom-right corner)
  └── BlockComponentActionWrapper (if showActions)

Source: simple_table_row_block_component.dart

IntrinsicHeight(
  child: Row(
    crossAxisAlignment: CrossAxisAlignment.stretch,
    children: [cell1, cell2, cell3, ...],  // each cell rendered by editorState.renderer
  ),
)

• If alwaysDistributeColumnWidths is true, cells are wrapped in Flexible.
• If borderType == table, SimpleTableRowDivider is inserted between cells.

Source: simple_table_cell_block_component.dart

Each cell is a Stack containing:

Stack(clipBehavior: Clip.none)
  ├── _buildCell()  →  DecoratedBox(border + bg) → Container(padding + width) → Column(children)
  ├── [if columnIndex == 0] Positioned(left): Row more-action menu
  ├── [if rowIndex == 0]    Positioned(top): Column more-action menu
  ├── [if (0,0)]            Positioned(top-left): Table action menu (mobile only)
  └── Positioned(right):    Column resize handle

Desktop cells are wrapped in MouseRegion for hover tracking. Mobile cells have additional resize handles on both sides.

Cell Content Width:

• Fixed width from node.columnWidth (default 160.0 dp)
• If alwaysDistributeColumnWidths, width is null (flexible)
• Minimum constraint: 36.0 dp

Source: simple_table_constants.dart → SimpleTableConstants

static EdgeInsets get cellEdgePadding => const EdgeInsets.symmetric(
  horizontal: 9.0,
  vertical: 4.0,
);

static EdgeInsets get tablePadding => EdgeInsets.only(
  bottom: addRowButtonHeight + 3 * addRowButtonPadding,  // = 28.0
  left: tableLeftPadding,                                 // = 8.0 desktop
  right: addColumnButtonWidth + 2 * addColumnButtonPadding, // = 20.0
);

Source: simple_table_constants.dart → SimpleTableColors extension on BuildContext

Resolved in _buildBackgroundColor() in this order (first match wins):

1. Selecting table → Theme.colorScheme.primary at 10% opacity
2. Column color → from columnColors attribute map
3. Row color → from rowColors attribute map
4. Header color → simpleTableDefaultHeaderColor (if cell is in a header row/column)
5. Default → Colors.transparent

Priority: Column alignment > Row alignment > Default (Alignment.topLeft)

Supported values: left, center, right (maps to Alignment.topLeft, Alignment.topCenter, Alignment.topRight)

FlowyText.regular(
  action.name,
  fontSize: 14.0,
  figmaLineHeight: 18.0,
)

Source: simple_table_border_builder.dart

The default border render type is SimpleTableBorderRenderType.cell (each cell draws its own border).

if (!editable)             → buildCellBorder()
else if (isReordering)     → buildReorderingBorder()
else if (isSelectingTable) → buildSelectingTableBorder()
else if (columnSelected)   → buildColumnHighlightBorder()
else if (rowSelected)      → buildRowHighlightBorder()
else if (isEditingCell)    → buildEditingBorder()
else                       → buildCellBorder()

Source: simple_table_more_action.dart → SimpleTableMoreAction.leftIconSvg

Source: simple_table_more_action.dart

enum SimpleTableMoreAction {
  // Shared desktop + mobile
  insertLeft, insertRight, insertAbove, insertBelow,
  duplicate, clearContents, delete,
  align, backgroundColor,
  enableHeaderColumn, enableHeaderRow,
  setToPageWidth, distributeColumnsEvenly,
  divider,  // UI separator, not an action

  // Mobile-only
  duplicateRow, duplicateColumn, duplicateTable,
  cut, copy, paste,
  bold,
  textColor, textBackgroundColor,
  copyLinkToBlock,
}

Built by SimpleTableMoreActionType.buildDesktopActions():

For Rows:

insertAbove → insertBelow → [divider]
→ [enableHeaderRow (only if index==0)]
→ backgroundColor → align → [divider]
→ setToPageWidth → distributeColumnsEvenly → [divider]
→ duplicate → clearContents → [delete (if rowLength > 1)]

For Columns:

insertLeft → insertRight → [divider]
→ [enableHeaderColumn (only if index==0)]
→ backgroundColor → align → [divider]
→ setToPageWidth → distributeColumnsEvenly → [divider]
→ duplicate → clearContents → [delete (if columnLength > 1)]

Built by SimpleTableMoreActionType.buildMobileActions():

For Rows: (grouped sections)

Section 1: [enableHeaderRow] (only if index==0)
Section 2: [setToPageWidth, distributeColumnsEvenly]
Section 3: [duplicateRow, clearContents]

For Columns: (grouped sections)

Section 1: [enableHeaderColumn] (only if index==0)
Section 2: [setToPageWidth, distributeColumnsEvenly]
Section 3: [duplicateColumn, clearContents]

Additional mobile quick actions: cut, copy, paste, delete

All operations are extension methods on EditorState:

Source: simple_table_add_row_button.dart

Widget: SimpleTableAddRowHoverButton → wraps SimpleTableAddRowButton

Visibility Logic:

• Shows when hovering on the table area AND the mouse is over the last row (enableHoveringLogicV2)
• Also shows when actively dragging to expand rows (isDraggingRow)

Positioning:

Positioned(
  bottom: 2 * addRowButtonPadding,  // = 8.0 dp from bottom
  left: tableLeftPadding - cellBorderWidth,  // = 7.0 dp
  right: addRowButtonRightPadding,  // = 20.0 dp (space for column button)
)

Appearance:

• Height: 16.0 dp
• Margin: 2.0 dp vertical
• Background: simpleTableMoreActionBackgroundColor (#F2F3F5 light / #2D3036 dark)
• Border radius: 4.0 dp
• Icon: FlowySvgs.add_s (plus icon, centered)
• Cursor: SystemMouseCursors.click
• Tooltip: LocaleKeys.document_plugins_simpleTable_clickToAddNewRow

Actions:

1. Tap → calls editorState.addRowInTable(tableNode) which appends a new row at the end
2. Vertical drag → experimental drag-to-expand feature (currently disabled: enableDragToExpandTable = false)
   • Tracks startDraggingOffset and calculates row delta based on drag distance / defaultRowHeight
   • Dynamically inserts or deletes rows via insertRowInTable / deleteRowInTable with inMemoryUpdate: true

Source: simple_table_add_column_button.dart

Widget: SimpleTableAddColumnHoverButton → wraps SimpleTableAddColumnButton

Visibility Logic:

• Shows when hovering on the table area AND the mouse is over the last column
• Uses Opacity(0.0) to hide (still occupies space) vs SizedBox.shrink for the row button

Positioning:

Positioned(
  top: tableHitTestTopPadding - cellBorderWidth,  // = 7.0 dp
  bottom: addColumnButtonBottomPadding,  // = 28.0 dp
  right: 0,
)

Appearance:

• Width: 16.0 dp
• Margin: 2.0 dp horizontal
• Background: simpleTableMoreActionBackgroundColor
• Border radius: 4.0 dp
• Icon: FlowySvgs.add_s
• Cursor: SystemMouseCursors.click
• Tooltip: LocaleKeys.document_plugins_simpleTable_clickToAddNewColumn

Actions:

1. Tap → calls editorState.addColumnInTable(tableNode) which appends a new column at the end
2. Horizontal drag → experimental drag-to-expand feature (disabled)

Source: simple_table_add_column_and_row_button.dart

Widget: SimpleTableAddColumnAndRowHoverButton → wraps SimpleTableAddColumnAndRowButton

Visibility Logic:

• Shows when hovering on the last cell of the table (isLastCellInTable)

Positioning:

Positioned(
  bottom: addColumnAndRowButtonBottomPadding,  // = 10.0 dp
  right: addColumnButtonPadding,               // = 2.0 dp
)

Appearance:

• Width: 16.0 dp, Height: 16.0 dp (square)
• Background: simpleTableMoreActionBackgroundColor
• Border radius: 8.0 dp (fully circular)
• Icon: FlowySvgs.add_s
• Cursor: SystemMouseCursors.click
• Tooltip: LocaleKeys.document_plugins_simpleTable_clickToAddNewRowAndColumn

Action:

• Tap → calls editorState.addColumnAndRowInTable(node) which sequentially calls addColumnInTable then addRowInTable

From simple_table_more_action_popup.dart:

All four actions:

1. Clear the current selection first
2. Call the insert operation
3. Get the newly created cell node
4. Set editorState.selection to a collapsed position at the new cell's first child

insertColumnInTable(node, index):

1. Compute mapTableAttributes to remap attribute indices (colors, aligns, widths, bold, text colors)
2. Create a transaction
3. For each row: insert a simpleTableCellBlockNode() at the target column index
4. Update table node attributes with remapped values
5. Apply transaction (supports inMemoryUpdate flag for drag operations)

insertRowInTable(node, index):

1. Compute mapTableAttributes to remap row attribute indices
2. Create a new simpleTableRowBlockNode with N empty cells (matching column count)
3. Insert the row at the target path
4. Update table node attributes with remapped values
5. Apply transaction

Source: simple_table_shortcuts/simple_table_commands.dart and individual command files

Helper extensions in simple_table_command_extension.dart:

• isCurrentSelectionInTableCell() - checks if cursor is inside a table cell
• moveToPreviousCell() - Shift+Tab navigation logic
• moveToNextCell() - Tab navigation logic

Source: simple_table_constants.dart

SimpleTableContext is provided via Flutter's Provider and contains these ValueNotifiers:

Non-notifier fields:

• isDraggingRow / isDraggingColumn (bool) — drag-to-expand state
• horizontalScrollController (ScrollController?) — table scroll controller
• isReordering (computed getter) — true if any reordering is active

This section surveys open-source React (and React-compatible) projects that implement a document table component -- a table block living inside a rich-text/block editor, similar to AppFlowy's SimpleTable. This is NOT about data grids or spreadsheet libraries.

The following projects were evaluated for feature parity with AppFlowy's SimpleTable. The core features being compared:

• Rich cell content -- Can cells contain arbitrary block-level content (headings, images, code blocks)?
• Add row/column UI -- Hover buttons or inline controls to insert rows/columns
• Column resize -- Drag-to-resize column widths
• Row/column reorder -- Drag-and-drop to rearrange rows or columns
• Header row/column -- Toggle first row/column as header with distinct styling
• Per-row/column styling -- Background color, text color, bold, alignment per row or column
• Cell merge/split -- Colspan/rowspan support
• Keyboard navigation -- Tab, Shift+Tab, arrow keys between cells
• Undo/redo -- Transaction-based history
• Mobile support -- Responsive or adaptive table UI

• GitHub: https://github.com/udecode/plate
• Stars: ~16,100
• Framework: Slate.js + React (with shadcn/ui components)
• License: MIT
• Status: Very active (updated daily, 73k+ npm downloads/week)

Plugin-based. Composed of TablePlugin, TableRowPlugin, TableCellPlugin, and TableCellHeaderPlugin bundled into a TableKit. Higher-order editor functions enhance the Slate editor:

• withNormalizeTable -- table structure normalization
• withDeleteTable -- delete behavior in tables
• withGetFragmentTable -- copy/paste handling
• withInsertFragmentTable -- paste into table
• withSelectionTable -- selection behavior

Data model follows Slate's nested node tree:

table (element)
  └── table_row (element)
        └── table_cell / table_header_cell (element)
              └── [arbitrary Slate content]

Ships with pre-built shadcn/ui React components for immediate use.

• Same nested block architecture (Table > Row > Cell > Content) as AppFlowy
• Operations are editor-level transforms, similar to AppFlowy's EditorState extensions
• Rich cell content (not inline-only)
• Row/column drag reorder support
• Active community and npm-installable

• GitHub: https://github.com/ueberdosis/tiptap
• Stars: ~36,000
• Framework: ProseMirror + React (also Vue, Svelte, plain JS)
• License: MIT (table extension is free/open-source as of 2025)
• Status: Very active (updated daily)

Extension-based. The Table, TableRow, TableCell, and TableHeader extensions register ProseMirror nodes. Built on top of the foundational prosemirror-tables module. The TableKit bundles all table-related extensions.

Schema follows ProseMirror's node hierarchy:

table
  └── table_row
        └── table_cell / table_header (supports colspan, rowspan)
              └── [block content]

The table node component provides an enhanced UI with row/column handles, add/delete/move/duplicate buttons, and cell alignment controls.

• GitHub: https://github.com/ProseMirror/prosemirror-tables (~319 stars, MIT)
• Provides: schema extension for rowspan/colspan, cell selection, table normalization, column resizing, commands (addRowBefore/After, deleteRow, addColumnBefore/After, deleteColumn, mergeCells, splitCell, toggleHeaderRow/Column/Cell)
• Does NOT provide: row/column reorder, hover add buttons, React UI components

• GitHub: https://github.com/facebook/lexical (@lexical/table, @lexical/react)
• Stars: ~23,200
• Framework: Lexical (Meta's custom framework) + React
• License: MIT
• Status: Very active (Meta-backed, updated daily)

Node-based. TableNode, TableRowNode, and TableCellNode mirror DOM <table>/<tr>/<td> elements:

TableNode
  └── TableRowNode
        └── TableCellNode (supports colSpan, rowSpan, headerState)
              └── [Lexical nodes]

The LexicalTablePlugin (React component) registers the nodes and enables features. TableCellResizerPlugin is a separate plugin for resize. The TableObserver manages cell selection state. Everything integrates through Lexical's command system.

Key limitation: No nested table support (explicitly blocked).

• GitHub: https://github.com/TypeCellOS/BlockNote
• Stars: ~9,300
• Framework: ProseMirror + TipTap + React
• License: MPL-2.0 (core, free for any project) / GPL-3.0 (XL packages, free for open source)
• Status: Very active (updated daily)

Block-based. Tables are a built-in block type with TableContent:

{
  "type": "table",
  "content": {
    "columnWidths": [100, 200, 150],
    "headerRows": 1,
    "headerCols": 0,
    "rows": [
      {
        "cells": [
          {
            "type": "tableCell",
            "content": [/* inline content only */],
            "props": {
              "backgroundColor": "#f0f0f0",
              "textColor": "#333",
              "textAlignment": "center",
              "colspan": 1,
              "rowspan": 1
            }
          }
        ]
      }
    ]
  }
}

Advanced features (merge/split, colors) are disabled by default and enabled via editor config. Built on TipTap's extension system under the hood.

Cells only support inline content -- no images, code blocks, headings, or other block-level elements inside a cell. This is a significant gap compared to AppFlowy's SimpleTable, where cells can contain any document block.

• GitHub (AFFiNE): https://github.com/toeverything/AFFiNE (~66,900 stars)
• GitHub (BlockSuite): https://github.com/toeverything/blocksuite (~5,750 stars)
• Framework: BlockSuite (custom framework, Web Components -- NOT React)
• License: AFFiNE: custom (NOASSERTION), BlockSuite: MPL-2.0
• Status: Very active (updated daily)

@blocksuite/affine-block-table provides the table block. Components include TableDataManager and TableSelection. The data layer is natively built on Yjs CRDT.

BlockSuite uses Web Components, not React. It cannot be directly used as a React component without a wrapper layer. It is the editor behind AFFiNE (similar to how Monaco is behind VSCode). Architecturally it's the most similar to AppFlowy's approach (custom framework, block-based, collaborative), but the technology stack differs.

• GitHub: https://github.com/yoopta-editor/Yoopta-Editor (~2,970 stars)
• Framework: Slate.js + React
• License: MIT
• Table plugin: @yoopta/table
• Features: Insert/delete rows and columns, move rows and columns, update column widths, toggle header rows/columns, horizontal scroll support
• Architecture: Plugin-based. Static methods on the table plugin for all operations. Headless with optional shadcn theme preset.

• GitHub: https://github.com/steven-tey/novel (~16,100 stars)
• Framework: TipTap + React + Next.js + Tailwind
• License: Apache-2.0
• Table support: Delegates to TipTap extensions. Not a table implementation itself. Focused on AI-powered writing, not comprehensive table editing.

• GitHub: https://github.com/outline/outline (~37,900 stars)
• Framework: ProseMirror + React
• License: BSL (Business Source License)
• Table features: Add row/column UI, column resize, header row/column toggle, cell merge/split, keyboard navigation
• Caveat: Editor is deeply integrated into Outline's codebase (not extractable as standalone library). The old standalone editor repo is archived.

• GitHub: https://github.com/AppFlowy-IO/AppFlowy-Web-Editor (~10 stars)
• Framework: Slate.js + React
• Status: Early stage. Has GFM table parsing dependencies but full SimpleTable parity with the Flutter version is not yet implemented.

Plate (Slate.js) has the most feature parity: rich block content in cells, drag reorder for rows and columns, column resize, header toggle, per-cell styling, and keyboard navigation. It's MIT licensed and installable via npm. If building an AppFlowy-like table in React, Plate is the strongest starting point.

Built on prosemirror-tables (the gold standard for document tables), TipTap has the largest ecosystem and most production deployments. Merge/split is a standout feature. The main gap is row/column drag reorder, which is not natively supported.

BlockNote provides the most polished Notion-like editing experience, with per-cell styling, merge/split (opt-in), and collaborative editing via Y.js. However, cells only support inline content (no images, code blocks, etc.), which is a significant gap vs AppFlowy.

The combination of these features is unique to AppFlowy:

• Per-row and per-column styling (background color, text color, bold, alignment)
• Row/column duplicate and copy/paste to clipboard
• "Set to page width" and "distribute columns evenly" layout actions
• Separate desktop hover UI vs mobile bottom sheet UI

All projects use the same fundamental data model:

Table Node → Row Node → Cell Node → [Content]

Operations are implemented as editor-level transforms (Slate transforms, ProseMirror transactions, Lexical commands). This validates AppFlowy's architecture as aligned with industry patterns.