@milkdown/preset-commonmark 7.0.0-next.0 → 7.0.0-next.2

package/src/node/list-item.ts

@@ -4,8 +4,10 @@ import { expectDomTypeError } from '@milkdown/exception'
 import { liftListItem, sinkListItem, splitListItem } from '@milkdown/prose/schema-list'
 import { $command, $nodeAttr, $nodeSchema, $useKeymap } from '@milkdown/utils'
 
+/// HTML attributes for list item node.
 export const listItemAttr = $nodeAttr('listItem')
 
+/// Schema for list item node.
 export const listItemSchema = $nodeSchema('list_item', ctx => ({
   group: 'listItem',
   content: 'paragraph block*',
@@ -67,10 +69,53 @@ export const listItemSchema = $nodeSchema('list_item', ctx => ({
   },
 }))
 
+/// The command to sink list item.
+///
+/// For example:
+/// ```md
+/// * List item 1
+/// * List item 2 <- cursor here
+/// ```
+/// Will get:
+/// ```md
+/// * List item 1
+///   * List item 2
+/// ```
 export const sinkListItemCommand = $command('SinkListItem', () => () => sinkListItem(listItemSchema.type()))
-export const splitListItemCommand = $command('SplitListItem', () => () => splitListItem(listItemSchema.type()))
+
+/// The command to lift list item.
+///
+/// For example:
+/// ```md
+/// * List item 1
+///   * List item 2 <- cursor here
+/// ```
+/// Will get:
+/// ```md
+/// * List item 1
+/// * List item 2
+/// ```
 export const liftListItemCommand = $command('SplitListItem', () => () => liftListItem(listItemSchema.type()))
 
+/// The command to split a list item.
+///
+/// For example:
+/// ```md
+/// * List item 1
+/// * List item 2 <- cursor here
+/// ```
+/// Will get:
+/// ```md
+/// * List item 1
+/// * List item 2
+/// * <- cursor here
+/// ```
+export const splitListItemCommand = $command('SplitListItem', () => () => splitListItem(listItemSchema.type()))
+
+/// Keymap for list item node.
+/// - `<Enter>`: Split the current list item.
+/// - `<Tab>/<Mod-]>`: Sink the current list item.
+/// - `<Shift-Tab>/<Mod-[>`: Lift the current list item.
 export const listItemKeymap = $useKeymap('listItemKeymap', {
   NextListItem: {
     shortcuts: 'Enter',

package/src/node/ordered-list.ts

@@ -5,8 +5,10 @@ import { wrapIn } from '@milkdown/prose/commands'
 import { wrappingInputRule } from '@milkdown/prose/inputrules'
 import { $command, $inputRule, $nodeAttr, $nodeSchema, $useKeymap } from '@milkdown/utils'
 
+/// HTML attributes for ordered list node.
 export const orderedListAttr = $nodeAttr('orderedList')
 
+/// Schema for ordered list node.
 export const orderedListSchema = $nodeSchema('ordered_list', ctx => ({
   content: 'listItem+',
   group: 'block',
@@ -58,6 +60,7 @@ export const orderedListSchema = $nodeSchema('ordered_list', ctx => ({
   },
 }))
 
+/// Input rule for wrapping a block in ordered list node.
 export const wrapInOrderedListInputRule = $inputRule(() => wrappingInputRule(
   /^\s*(\d+)\.\s$/,
   orderedListSchema.type(),
@@ -65,8 +68,11 @@ export const wrapInOrderedListInputRule = $inputRule(() => wrappingInputRule(
   (match, node) => node.childCount + node.attrs.order === Number(match[1]),
 ))
 
+/// Command for wrapping a block in ordered list node.
 export const wrapInOrderedListCommand = $command('WrapInOrderedList', () => () => wrapIn(orderedListSchema.type()))
 
+/// Keymap for ordered list node.
+/// - `Mod-Alt-7`: Wrap a block in ordered list.
 export const orderedListKeymap = $useKeymap('orderedListKeymap', {
   WrapInOrderedList: {
     shortcuts: 'Mod-Alt-7',

package/src/node/paragraph.ts

@@ -5,7 +5,10 @@ import type { Node } from '@milkdown/prose/model'
 import { Fragment } from '@milkdown/prose/model'
 import { $command, $nodeAttr, $nodeSchema, $useKeymap } from '@milkdown/utils'
 
+/// HTML attributes for paragraph node.
 export const paragraphAttr = $nodeAttr('paragraph')
+
+/// Schema for paragraph node.
 export const paragraphSchema = $nodeSchema('paragraph', ctx => ({
   content: 'inline*',
   group: 'block',
@@ -47,8 +50,11 @@ export const paragraphSchema = $nodeSchema('paragraph', ctx => ({
   },
 }))
 
+/// This command can turn the selected block into paragraph.
 export const turnIntoTextCommand = $command('TurnIntoText', () => () => setBlockType(paragraphSchema.type()))
 
+/// Keymap for paragraph node.
+/// - `<Mod-Alt-0>`: Turn the selected block into paragraph.
 export const paragraphKeymap = $useKeymap('paragraphKeymap', {
   TurnIntoText: {
     shortcuts: 'Mod-Alt-0',

package/src/node/text.ts

@@ -1,6 +1,7 @@
 /* Copyright 2021, Milkdown by Mirone. */
 import { $node } from '@milkdown/utils'
 
+/// The bottom-level node.
 export const textSchema = $node('text', () => ({
   group: 'inline',
   parseMarkdown: {

package/src/plugin/hardbreak-clear-mark-plugin.ts

@@ -4,6 +4,7 @@ import { AddMarkStep, ReplaceStep } from '@milkdown/prose/transform'
 import { $prose } from '@milkdown/utils'
 import { hardbreakSchema } from '../node/hardbreak'
 
+/// This plugin is used to clear the marks around the hardbreak node.
 export const hardbreakClearMarkPlugin = $prose(() => {
   return new Plugin({
     key: new PluginKey('MILKDOWN_HARDBREAK_MARKS'),

package/src/plugin/hardbreak-filter-plugin.ts

@@ -2,9 +2,11 @@
 import { Plugin, PluginKey } from '@milkdown/prose/state'
 import { $ctx, $prose } from '@milkdown/utils'
 
+/// This slice contains the nodes that within which the hardbreak will be ignored.
 export const hardbreakFilterNodes = $ctx(['table', 'code_block'], 'hardbreakFilterNodes')
 
-// If the hardbreak is going to be inserted within a node that is in the `hardbreakFilterNodes`, ignore it.
+/// This plugin is used to filter the hardbreak node.
+/// If the hardbreak is going to be inserted within a node that is in the `hardbreakFilterNodes`, ignore it.
 export const hardbreakFilterPlugin = $prose((ctx) => {
   const notIn = ctx.get(hardbreakFilterNodes.key)
   return new Plugin({

package/src/plugin/inline-nodes-cursor-plugin.ts

@@ -3,10 +3,7 @@ import { Plugin, PluginKey } from '@milkdown/prose/state'
 import { Decoration, DecorationSet } from '@milkdown/prose/view'
 import { $prose } from '@milkdown/utils'
 
-/**
- * This plugin is to solve the chrome 98 bug:
- * https://discuss.prosemirror.net/t/cursor-jumps-at-the-end-of-line-when-it-betweens-two-inline-nodes/4641
- */
+/// This plugin is to solve the [chrome 98 bug](https://discuss.prosemirror.net/t/cursor-jumps-at-the-end-of-line-when-it-betweens-two-inline-nodes/4641).
 export const inlineNodesCursorPlugin = $prose(() => {
   let lock = false
   const inlineNodesCursorPluginKey = new PluginKey('MILKDOWN_INLINE_NODES_CURSOR')

package/src/plugin/inline-sync-plugin/config.ts

@@ -6,6 +6,7 @@ import { $ctx } from '@milkdown/utils'
 
 import { swap } from './utils'
 
+/// @internal
 export type ShouldSyncNode = (context: {
   prevNode: Node
   nextNode: Node
@@ -14,12 +15,14 @@ export type ShouldSyncNode = (context: {
   text: string
 }) => boolean
 
+/// @internal
 export interface SyncNodePlaceholder {
   hole: string
   punctuation: string
   char: string
 }
 
+/// @internal
 export interface InlineSyncConfig {
   placeholderConfig: SyncNodePlaceholder
   shouldSyncNode: ShouldSyncNode
@@ -27,6 +30,7 @@ export interface InlineSyncConfig {
   movePlaceholder: (placeholderToMove: string, text: string) => string
 }
 
+/// @internal
 export const defaultConfig: InlineSyncConfig = {
   placeholderConfig: {
     hole: '∅',
@@ -54,5 +58,15 @@ export const defaultConfig: InlineSyncConfig = {
   },
 }
 
-// export const inlineSyncConfigCtx = createSlice<InlineSyncConfig, 'inlineSyncConfig'>(defaultConfig, 'inlineSyncConfig')
+/// A slice that contains the inline sync config.
+/// You can set value to this slice to change the config.
+///
+/// ```typescript
+/// ctx.update(inlineSyncConfigCtx, (prevCfg) => ({
+///   ...prevCfg,
+///   // your config
+/// }));
+/// ```
+///
+/// You can find the default config [here](https://github.com/Milkdown/milkdown/blob/main/packages/preset-commonmark/src/plugin/inline-sync-plugin/config.ts).
 export const inlineSyncConfig = $ctx<InlineSyncConfig, 'inlineSyncConfig'>(defaultConfig, 'inlineSyncConfig')

package/src/plugin/inline-sync-plugin/inline-sync-plugin.ts

@@ -8,6 +8,11 @@ import { inlineSyncConfig } from './config'
 import { getContextByState } from './context'
 import { runReplacer } from './replacer'
 
+/// This plugin is used to sync the inline mark.
+/// It will create and remove marks automatically according to the user input.
+///
+/// When users type something, the plugin will transform the line (for better performance) to real markdown AST by serializer
+/// and render the AST to dom by parser, thus the input texts can be displayed correctly.
 export const inlineSyncPlugin = $prose((ctx: Ctx) => {
   let requestId: number | null = null
   const inlineSyncPluginKey = new PluginKey('MILKDOWN_INLINE_SYNC')

package/src/plugin/remark-add-order-in-list-plugin.ts

@@ -3,6 +3,7 @@ import { $remark } from '@milkdown/utils'
 import type { Node, Parent } from 'unist'
 import { visit } from 'unist-util-visit'
 
+/// This plugin is used to add order in list for remark AST.
 export const remarkAddOrderInListPlugin = $remark(() => () => (tree: Node) => {
   visit(tree, 'list', (node: Parent & { ordered?: boolean; start?: number }) => {
     if (node.ordered) {

package/src/plugin/remark-inline-link-plugin.ts

@@ -2,4 +2,5 @@
 import { $remark } from '@milkdown/utils'
 import remarkInlineLinks from 'remark-inline-links'
 
+/// This plugin wraps [remark-inline-links](https://github.com/remarkjs/remark-inline-links).
 export const remarkInlineLinkPlugin = $remark(() => remarkInlineLinks)

package/src/plugin/remark-line-break.ts

@@ -3,6 +3,9 @@ import { $remark } from '@milkdown/utils'
 import type { Literal, Node, Parent } from 'unist'
 import { visit } from 'unist-util-visit'
 
+/// This plugin is used to add inline line break for remark AST.
+/// The inline line break should be treated as a `space`.
+/// And the normal line break should be treated as a `LF`.
 export const remarkLineBreak = $remark(() => () => (tree: Node) => {
   const find = /[\t ]*(?:\r?\n|\r)/g
   visit(tree, 'text', (node: Literal, index: number, parent: Parent) => {

package/src/plugin/sync-heading-id-plugin.ts

@@ -4,6 +4,8 @@ import type { EditorView } from '@milkdown/prose/view'
 import { $prose } from '@milkdown/utils'
 import { headingIdGenerator, headingSchema } from '../node/heading'
 
+/// This plugin is used to sync the heading id when the heading content changes.
+/// It will use the `headingIdGenerator` to generate the id.
 export const syncHeadingIdPlugin = $prose((ctx) => {
   const headingIdPluginKey = new PluginKey('MILKDOWN_HEADING_ID')
 

package/src/plugin/sync-list-order-plugin.ts

@@ -6,7 +6,7 @@ import { listItemSchema } from '../node/list-item'
 
 import { orderedListSchema } from '../node/ordered-list'
 
-// This plugin is used to keep the label of list item up to date in ordered list.
+/// This plugin is used to keep the label of list item up to date in ordered list.
 export const syncListOrderPlugin = $prose(() => {
   const walkThrough = (state: EditorState, callback: (tr: Transaction) => void) => {
     const orderedListType = orderedListSchema.type()