@milkdown/preset-gfm 7.0.0-next.0 → 7.0.0-next.1

package/src/node/table/index.ts

@@ -23,6 +23,7 @@ const originalSchema = tableNodes({
   },
 })
 
+/// Schema for table node.
 export const tableSchema = $nodeSchema('table', () => ({
   ...originalSchema.table,
   parseMarkdown: {
@@ -58,6 +59,7 @@ export const tableSchema = $nodeSchema('table', () => ({
 
 }))
 
+/// Schema for table row node.
 export const tableRowSchema = $nodeSchema('table_row', () => ({
   ...originalSchema.table_row,
   parseMarkdown: {
@@ -84,6 +86,7 @@ export const tableRowSchema = $nodeSchema('table_row', () => ({
   },
 }))
 
+/// Schema for table cell node.
 export const tableCellSchema = $nodeSchema('table_cell', () => ({
   ...originalSchema.table_cell,
   parseMarkdown: {
@@ -106,6 +109,7 @@ export const tableCellSchema = $nodeSchema('table_cell', () => ({
   },
 }))
 
+/// Schema for table header node.
 export const tableHeaderSchema = $nodeSchema('table_header', () => ({
   ...originalSchema.table_header,
   parseMarkdown: {
@@ -129,6 +133,8 @@ export const tableHeaderSchema = $nodeSchema('table_header', () => ({
   },
 }))
 
+/// A input rule for creating table.
+/// For example, `|2x2|` will create a 2x2 table.
 export const insertTableInputRule = $inputRule(() => new InputRule(
   /^\|(?<col>\d+)[xX](?<row>\d+)\|\s$/, (state, match, start, end) => {
     const $start = state.doc.resolve(start)
@@ -144,10 +150,15 @@ export const insertTableInputRule = $inputRule(() => new InputRule(
   },
 ))
 
+/// A command for moving cursor to previous cell.
 export const goToPrevTableCellCommand = $command('GoToPrevTableCell', () => () => goToNextCell(-1))
 
+/// A command for moving cursor to next cell.
 export const goToNextTableCellCommand = $command('GoToNextTableCell', () => () => goToNextCell(1))
 
+/// A command for splitting current table into two tables.
+/// If the selection is at the end of the table,
+/// it will just quit the table and insert a new paragraph node.
 export const breakTableCommand = $command('BreakTable', () => () => (state, dispatch) => {
   if (!isInTable(state))
     return false
@@ -162,6 +173,9 @@ export const breakTableCommand = $command('BreakTable', () => () => (state, disp
   return true
 })
 
+/// A command for inserting a table.
+/// You can specify the number of rows and columns.
+/// By default, it will insert a 3x3 table.
 export const insertTableCommand = $command('InsertTable', () => ({ row, col }: { row?: number; col?: number } = {}) => (state, dispatch) => {
   const { selection, tr } = state
   const { from } = selection
@@ -174,6 +188,8 @@ export const insertTableCommand = $command('InsertTable', () => ({ row, col }: {
   return true
 })
 
+/// A command for moving a row in a table.
+/// You should specify the `from` and `to` index.
 export const moveRowCommand = $command('MoveRow', () => ({ from, to }: { from?: number; to?: number } = {}) => (state, dispatch) => {
   const { tr } = state
   const result = dispatch?.(moveRow(tr, from ?? 0, to ?? 0, true))
@@ -181,6 +197,8 @@ export const moveRowCommand = $command('MoveRow', () => ({ from, to }: { from?:
   return Boolean(result)
 })
 
+/// A command for moving a column in a table.
+/// You should specify the `from` and `to` index.
 export const moveColCommand = $command('MoveCol', () => ({ from, to }: { from?: number; to?: number } = {}) => (state, dispatch) => {
   const { tr } = state
   const result = dispatch?.(moveCol(tr, from ?? 0, to ?? 0, true))
@@ -188,6 +206,7 @@ export const moveColCommand = $command('MoveCol', () => ({ from, to }: { from?:
   return Boolean(result)
 })
 
+/// A command for selecting a row.
 export const selectRowCommand = $command<number, 'SelectRow'>('SelectRow', () => (index = 0) => (state, dispatch) => {
   const { tr } = state
   const result = dispatch?.(selectRow(index)(tr))
@@ -195,6 +214,7 @@ export const selectRowCommand = $command<number, 'SelectRow'>('SelectRow', () =>
   return Boolean(result)
 })
 
+/// A command for selecting a column.
 export const selectColCommand = $command<number, 'SelectCol'>('SelectCol', () => (index = 0) => (state, dispatch) => {
   const { tr } = state
   const result = dispatch?.(selectCol(index)(tr))
@@ -202,6 +222,7 @@ export const selectColCommand = $command<number, 'SelectCol'>('SelectCol', () =>
   return Boolean(result)
 })
 
+/// A command for selecting a table.
 export const selectTableCommand = $command('SelectTable', () => () => (state, dispatch) => {
   const { tr } = state
   const result = dispatch?.(selectTable(tr))
@@ -209,6 +230,9 @@ export const selectTableCommand = $command('SelectTable', () => () => (state, di
   return Boolean(result)
 })
 
+/// A command for deleting selected cells.
+/// If the selection is a row or column, the row or column will be deleted.
+/// If all cells are selected, the table will be deleted.
 export const deleteSelectedCellsCommand = $command('DeleteSelectedCells', () => () => (state, dispatch) => {
   const { selection } = state
   if (!(selection instanceof CellSelection))
@@ -227,10 +251,13 @@ export const deleteSelectedCellsCommand = $command('DeleteSelectedCells', () =>
     return deleteRow(state, dispatch)
 })
 
+/// A command for adding a column before the current column.
 export const addColBeforeCommand = $command('AddColBefore', () => () => addColumnBefore)
 
+/// A command for adding a column after the current column.
 export const addColAfterCommand = $command('AddColAfter', () => () => addColumnAfter)
 
+/// A command for adding a row before the current row.
 export const addRowBeforeCommand = $command('AddRowBefore', () => () => (state, dispatch) => {
   if (!isInTable(state))
     return false
@@ -241,6 +268,7 @@ export const addRowBeforeCommand = $command('AddRowBefore', () => () => (state,
   return true
 })
 
+/// A command for adding a row after the current row.
 export const addRowAfterCommand = $command('AddRowAfter', () => () => (state, dispatch) => {
   if (!isInTable(state))
     return false
@@ -251,8 +279,15 @@ export const addRowAfterCommand = $command('AddRowAfter', () => () => (state, di
   return true
 })
 
+/// A command for setting alignment property for selected cells.
+/// You can specify the alignment as `left`, `center`, or `right`.
+/// It's `left` by default.
 export const setAlignCommand = $command<'left' | 'center' | 'right', 'SetAlign'>('SetAlign', () => (alignment = 'left') => setCellAttr('alignment', alignment))
 
+/// Keymap for table commands.
+/// - `<Mod-]>`/`<Tab>`: Move to the next cell.
+/// - `<Mod-[>`/`<Shift-Tab>`: Move to the previous cell.
+/// - `<Mod-Enter>`: Exit the table, and break it if possible.
 export const tableKeymap = $useKeymap('tableKeymap', {
   NextCell: {
     shortcuts: ['Mod-]', 'Tab'],

package/src/node/table/utils.ts

@@ -9,12 +9,14 @@ import { CellSelection, TableMap } from '@milkdown/prose/tables'
 
 import { tableCellSchema, tableHeaderSchema, tableRowSchema, tableSchema } from '.'
 
+/// @internal
 export interface CellPos {
   pos: number
   start: number
   node: Node
 }
 
+/// @internal
 export const createTable = (rowsCount = 3, colsCount = 3): Node => {
   const cells = Array(colsCount)
     .fill(0)
@@ -31,10 +33,12 @@ export const createTable = (rowsCount = 3, colsCount = 3): Node => {
   return tableSchema.type().create(null, rows)
 }
 
+/// Find the table node with position information for current selection.
 export const findTable = (selection: Selection) =>
   findParentNode(node => node.type.spec.tableRole === 'table')(selection)
 
-export const getCellsInColumn = (columnIndex: number, selection: Selection): CellPos[] | undefined => {
+/// Get cells in a column of a table.
+export const getCellsInCol = (columnIndex: number, selection: Selection): CellPos[] | undefined => {
   const table = findTable(selection)
   if (!table)
     return undefined
@@ -58,6 +62,7 @@ export const getCellsInColumn = (columnIndex: number, selection: Selection): Cel
     .filter((x): x is CellPos => x != null)
 }
 
+/// Get cells in a row of a table.
 export const getCellsInRow = (rowIndex: number, selection: Selection): CellPos[] | undefined => {
   const table = findTable(selection)
   if (!table)
@@ -82,6 +87,7 @@ export const getCellsInRow = (rowIndex: number, selection: Selection): CellPos[]
     .filter((x): x is CellPos => x != null)
 }
 
+/// Get all cells in a table.
 export const getAllCellsInTable = (selection: Selection) => {
   const table = findTable(selection)
   if (!table)
@@ -101,6 +107,7 @@ export const getAllCellsInTable = (selection: Selection) => {
   })
 }
 
+/// Select a possible table in current selection.
 export const selectTable = (tr: Transaction) => {
   const cells = getAllCellsInTable(tr.selection)
   if (cells && cells[0]) {
@@ -114,6 +121,7 @@ export const selectTable = (tr: Transaction) => {
   return tr
 }
 
+/// @internal
 export function addRowWithAlignment(tr: Transaction, { map, tableStart, table }: TableRect, row: number) {
   const rowPos = Array(row)
     .fill(0)
@@ -132,6 +140,7 @@ export function addRowWithAlignment(tr: Transaction, { map, tableStart, table }:
   return tr
 }
 
+/// @internal
 export const selectLine = (type: 'row' | 'col') => (index: number) => (tr: Transaction) => {
   const table = findTable(tr.selection)
   const isRowSelection = type === 'row'
@@ -157,7 +166,12 @@ export const selectLine = (type: 'row' | 'col') => (index: number) => (tr: Trans
   return tr
 }
 
+/// If the selection is in a table,
+/// select the {index} row.
 export const selectRow = selectLine('row')
+
+/// If the selection is in a table,
+/// select the {index} column.
 export const selectCol = selectLine('col')
 
 const transpose = <T>(array: T[][]) => {
@@ -201,7 +215,7 @@ const convertArrayOfRowsToTableNode = (tableNode: Node, arrayOfNodes: (Node | nu
   return newTable
 }
 
-export const convertTableNodeToArrayOfRows = (tableNode: Node) => {
+const convertTableNodeToArrayOfRows = (tableNode: Node) => {
   const map = TableMap.get(tableNode)
   const rows: (Node | null)[][] = []
   for (let rowIndex = 0; rowIndex < map.height; rowIndex++) {
@@ -289,7 +303,7 @@ const getSelectionRangeInColumn = (columnIndex: number, tr: Transaction) => {
 
   // looking for selection start column (startIndex)
   for (let i = columnIndex; i >= 0; i--) {
-    const cells = getCellsInColumn(i, tr.selection)
+    const cells = getCellsInCol(i, tr.selection)
     if (cells) {
       cells.forEach((cell) => {
         const maybeEndIndex = cell.node.attrs.colspan + i - 1
@@ -303,7 +317,7 @@ const getSelectionRangeInColumn = (columnIndex: number, tr: Transaction) => {
   }
   // looking for selection end column (endIndex)
   for (let i = columnIndex; i <= endIndex; i++) {
-    const cells = getCellsInColumn(i, tr.selection)
+    const cells = getCellsInCol(i, tr.selection)
     if (cells) {
       cells.forEach((cell) => {
         const maybeEndIndex = cell.node.attrs.colspan + i - 1
@@ -316,14 +330,14 @@ const getSelectionRangeInColumn = (columnIndex: number, tr: Transaction) => {
   // filter out columns without cells (where all rows have colspan > 1 in the same column)
   const indexes = []
   for (let i = startIndex; i <= endIndex; i++) {
-    const maybeCells = getCellsInColumn(i, tr.selection)
+    const maybeCells = getCellsInCol(i, tr.selection)
     if (maybeCells && maybeCells.length)
       indexes.push(i)
   }
   startIndex = indexes[0]!
   endIndex = indexes[indexes.length - 1]!
 
-  const firstSelectedColumnCells = getCellsInColumn(startIndex, tr.selection)!
+  const firstSelectedColumnCells = getCellsInCol(startIndex, tr.selection)!
   const firstRowCells = getCellsInRow(0, tr.selection)!
   const $anchor = tr.doc.resolve(
     firstSelectedColumnCells[firstSelectedColumnCells.length - 1]!.pos,
@@ -331,7 +345,7 @@ const getSelectionRangeInColumn = (columnIndex: number, tr: Transaction) => {
 
   let headCell: CellPos | undefined
   for (let i = endIndex; i >= startIndex; i--) {
-    const columnCells = getCellsInColumn(i, tr.selection)
+    const columnCells = getCellsInCol(i, tr.selection)
     if (columnCells && columnCells.length) {
       for (let j = firstRowCells.length - 1; j >= 0; j--) {
         if (firstRowCells[j]!.pos === columnCells[0]!.pos) {
@@ -384,7 +398,7 @@ const getSelectionRangeInRow = (rowIndex: number, tr: Transaction) => {
   endIndex = indexes[indexes.length - 1]!
 
   const firstSelectedRowCells = getCellsInRow(startIndex, tr.selection)!
-  const firstColumnCells = getCellsInColumn(0, tr.selection)!
+  const firstColumnCells = getCellsInCol(0, tr.selection)!
   const $anchor = tr.doc.resolve(firstSelectedRowCells[firstSelectedRowCells.length - 1]!.pos)
 
   let headCell: CellPos | undefined
@@ -406,6 +420,9 @@ const getSelectionRangeInRow = (rowIndex: number, tr: Transaction) => {
   return { $anchor, $head, indexes }
 }
 
+/// If the selection is in a table,
+/// Move the columns at `origin` to `target` in current table.
+/// The `select` is true by default, which means the selection will be set to the moved column.
 export function moveCol(tr: Transaction, origin: number, target: number, select = true) {
   const table = findTable(tr.selection)
   if (!table)
@@ -447,6 +464,9 @@ export function moveCol(tr: Transaction, origin: number, target: number, select
   return _tr.setSelection(createCellSelection($lastCell, $firstCell))
 }
 
+/// If the selection is in a table,
+/// Move the rows at `origin` and `target` in current table.
+/// The `select` is true by default, which means the selection will be set to the moved row.
 export function moveRow(tr: Transaction, origin: number, target: number, select = true) {
   const table = findTable(tr.selection)
   if (!table)

package/src/node/task-list-item.ts

@@ -2,6 +2,7 @@
 import { expectDomTypeError } from '@milkdown/exception'
 import { listItemSchema } from '@milkdown/preset-commonmark'
 
+/// This schema extends the [list item](/preset-commonmark#list-item) schema and add task list support for it.
 export const extendListItemSchemaForTask = listItemSchema.extendSchema((prev) => {
   return (ctx) => {
     const baseSchema = prev(ctx)

package/src/plugin/auto-insert-zero-space-plugin.ts

@@ -6,7 +6,8 @@ import { Plugin, PluginKey } from '@milkdown/prose/state'
 import { paragraphSchema } from '@milkdown/preset-commonmark'
 import { $prose } from '@milkdown/utils'
 
-// original discussion in https://discuss.prosemirror.net/t/ime-composing-problems-on-td-or-th-element-in-safari-browser/4501
+/// This plugin is used to fix the bug of IME composing in table in Safari browser.
+/// original discussion in https://discuss.prosemirror.net/t/ime-composing-problems-on-td-or-th-element-in-safari-browser/4501
 export const autoInsertZeroSpaceInTablePlugin = $prose(() => {
   const pluginKey = new PluginKey('MILKDOWN_AUTO_INSERT_ZERO_SPACE')
 

package/src/plugin/column-resizing-plugin.ts

@@ -1,4 +1,6 @@
 /* Copyright 2021, Milkdown by Mirone. */
 import { columnResizing } from '@milkdown/prose/tables'
 import { $prose } from '@milkdown/utils'
+
+/// This plugin is wrapping the `columnResizing` plugin from [prosemirror-tables](https://github.com/ProseMirror/prosemirror-tables).
 export const columnResizingPlugin = $prose(() => columnResizing({}))

package/src/plugin/remark-gfm-plugin.ts

@@ -2,4 +2,5 @@
 import { $remark } from '@milkdown/utils'
 import remarkGFM from 'remark-gfm'
 
+/// This plugin is wrapping the [remark-gfm](https://github.com/remarkjs/remark-gfm).
 export const remarkGFMPlugin = $remark(() => remarkGFM)

package/src/plugin/table-editing-plugin.ts

@@ -1,4 +1,6 @@
 /* Copyright 2021, Milkdown by Mirone. */
 import { tableEditing } from '@milkdown/prose/tables'
 import { $prose } from '@milkdown/utils'
+
+/// This plugin is wrapping the `tableEditing` plugin from [prosemirror-tables](https://github.com/ProseMirror/prosemirror-tables).
 export const tableEditingPlugin = $prose(() => tableEditing())