@portabletext/plugin-input-rule 0.3.1 → 0.3.3

package/README.md

@@ -1,5 +1,245 @@
 # `@portabletext/plugin-input-rule`
 
-> Easily configure input rules in the Portable Text Editor
+> Easily configure Input Rules in the Portable Text Editor
 
-This plugin is currently a work in progress. Docs to come with the APIs have settled.
+> ⚠️ **Note:** `defineInputRule` and other APIs exposed by this plugin are still a work in progress and may change slightly. We are still ironing out some details before we can cut a stable release.
+
+Listening for inserted text patterns and performing actions based on them is incredibly common, but it comes with many challenges:
+
+1. How do you implement undo functionality correctly?
+2. What about smart undo with <kbd>Backspace</kbd>?
+3. Have you considered `insert.text` events that carry more than one character? (Android, anyone?)
+
+_This is why this plugin exists_. It brings the concept of "Input Rules" to the Portable Text Editor, allowing you to write text transformation logic as if they were Behaviors, without worrying about low-level details:
+
+```tsx
+import type {EditorSchema} from '@portabletext/editor'
+import {raise} from '@portabletext/editor/behaviors'
+import {getPreviousInlineObject} from '@portabletext/editor/selectors'
+import {defineInputRule} from '@portabletext/plugin-input-rule'
+
+const unorderedListRule = defineInputRule({
+  // Listen for a RegExp pattern instead of a raw event
+  on: /^(-|\*) /,
+  // The `event` carries useful information like the offsets of RegExp matches
+  // as well as information about the focused text block
+  guard: ({snapshot, event}) => {
+    // In theory, an Input Rule could return multiple matches, but in this
+    // case we only expect one
+    const match = event.matches.at(0)
+
+    if (!match) {
+      return false
+    }
+
+    return {match}
+  },
+  actions: [
+    ({event}, {match}) => [
+      // Turn the text block into a paragraph
+      raise({
+        type: 'block.unset',
+        props: ['style'],
+        at: event.focusTextBlock.path,
+      }),
+      // Then, turn it into a list item
+      raise({
+        type: 'block.set',
+        props: {
+          listItem: 'bullet',
+          level: event.focusTextBlock.node.level ?? 1,
+        },
+        at: event.focusTextBlock.path,
+      }),
+      // Finally, delete the matched text
+      raise({
+        type: 'delete',
+        at: match.targetOffsets,
+      }),
+    ],
+  ],
+})
+
+export function MyMarkdownPlugin() {
+  return <InputRulePlugin rules={[unorderedListRule]} />
+}
+```
+
+> 💡 **Tip:** The [`@portabletext/plugin-markdown-shortcuts`](../plugin-markdown-shortcuts/) package is already built using Input Rules and provides common markdown shortcuts out of the box.
+
+## Text Transformation Rules
+
+Text transformations are so common that the plugin provides a high-level `defineTextTransformRule` helper to configure them without any boilerplate:
+
+```tsx
+const emDashRule = defineTextTransformRule({
+  on: /--/,
+  transform: () => '—',
+})
+
+export function MyTypographyPlugin() {
+  return <InputRulePlugin rules={[emDashRule]} />
+}
+```
+
+In fact, the production-ready [`@portabletext/plugin-typography`](../plugin-typography/) is built on top of Input Rules and comes packed with common text transformations like this.
+
+## Advanced Examples
+
+Input Rules can handle more complex transformations. Here are two advanced examples:
+
+1. **Markdown Link**: Automatically convert `[text](url)` syntax into proper links
+2. **Stock Ticker**: Convert `{SYMBOL}` patterns into stock ticker objects
+
+### Markdown Link Rule
+
+This example shows how to convert markdown-style link syntax `[text](url)` into proper link annotations:
+
+```tsx
+const markdownLinkRule = defineInputRule({
+  on: /\[(.+)]\((.+)\)/,
+  actions: [
+    ({snapshot, event}) => {
+      const newText = event.textBefore + event.textInserted
+      let textLengthDelta = 0
+      const actions: Array<BehaviorAction> = []
+
+      for (const match of event.matches.reverse()) {
+        const textMatch = match.groupMatches.at(0)
+        const hrefMatch = match.groupMatches.at(1)
+
+        if (textMatch === undefined || hrefMatch === undefined) {
+          continue
+        }
+
+        textLengthDelta =
+          textLengthDelta -
+          (match.targetOffsets.focus.offset -
+            match.targetOffsets.anchor.offset -
+            textMatch.text.length)
+
+        const leftSideOffsets = {
+          anchor: match.targetOffsets.anchor,
+          focus: textMatch.targetOffsets.anchor,
+        }
+        const rightSideOffsets = {
+          anchor: textMatch.targetOffsets.focus,
+          focus: match.targetOffsets.focus,
+        }
+
+        actions.push(
+          raise({
+            type: 'select',
+            at: textMatch.targetOffsets,
+          }),
+        )
+        actions.push(
+          raise({
+            type: 'annotation.add',
+            annotation: {
+              name: 'link',
+              value: {
+                href: hrefMatch.text,
+              },
+            },
+          }),
+        )
+        actions.push(
+          raise({
+            type: 'delete',
+            at: rightSideOffsets,
+          }),
+        )
+        actions.push(
+          raise({
+            type: 'delete',
+            at: leftSideOffsets,
+          }),
+        )
+      }
+
+      const endCaretPosition = {
+        path: event.focusTextBlock.path,
+        offset: newText.length - textLengthDelta * -1,
+      }
+
+      return [
+        ...actions,
+        raise({
+          type: 'select',
+          at: {
+            anchor: endCaretPosition,
+            focus: endCaretPosition,
+          },
+        }),
+      ]
+    },
+  ],
+})
+```
+
+### Stock Ticker Rule
+
+This example demonstrates how to convert text patterns like `{AAPL}` into custom inline objects:
+
+```tsx
+const stockTickerRule = defineInputRule({
+  on: /\{(.+)\}/,
+  guard: ({snapshot, event}) => {
+    const match = event.matches.at(0)
+
+    if (!match) {
+      return false
+    }
+
+    const symbolMatch = match.groupMatches.at(0)
+
+    if (symbolMatch === undefined) {
+      return false
+    }
+
+    return {match, symbolMatch}
+  },
+  actions: [
+    ({snapshot, event}, {match, symbolMatch}) => {
+      const stockTickerKey = snapshot.context.keyGenerator()
+
+      return [
+        raise({
+          type: 'delete',
+          at: match.targetOffsets,
+        }),
+        raise({
+          type: 'insert.child',
+          child: {
+            _key: stockTickerKey,
+            _type: 'stock-ticker',
+            symbol: symbolMatch.text,
+          },
+        }),
+        raise({
+          type: 'select',
+          at: {
+            anchor: {
+              path: [
+                {_key: event.focusTextBlock.node._key},
+                'children',
+                {_key: stockTickerKey},
+              ],
+              offset: 0,
+            },
+            focus: {
+              path: [
+                {_key: event.focusTextBlock.node._key},
+                'children',
+                {_key: stockTickerKey},
+              ],
+              offset: 0,
+            },
+          },
+        }),
+      ]
+    },
+  ],
+})
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/plugin-input-rule",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Easily configure input rules in the Portable Text Editor",
   "keywords": [
     "portabletext",
@@ -53,12 +53,12 @@
     "typescript": "5.9.3",
     "typescript-eslint": "^8.41.0",
     "vitest": "^3.2.4",
-    "@portabletext/editor": "2.14.1",
+    "@portabletext/editor": "2.14.2",
     "@portabletext/schema": "1.2.0",
     "racejar": "1.3.1"
   },
   "peerDependencies": {
-    "@portabletext/editor": "^2.14.1",
+    "@portabletext/editor": "^2.14.2",
     "react": "^19.1.1"
   },
   "publishConfig": {

package/src/rule.stock-ticker.feature

@@ -0,0 +1,16 @@
+Feature: Stock Ticker Rule
+
+  Background:
+    Given the editor is focused
+    And a global keymap
+
+  Scenario Outline: Transforms plain text into stock ticker
+    Given the text <text>
+    When <inserted text> is inserted
+    And "{ArrowRight}" is pressed
+    And "new" is typed
+    Then the text is <new text>
+
+    Examples:
+      | text | inserted text | new text              |
+      | ""   | "{AAPL}"      | ",{stock-ticker},new" |

package/src/{rule.markdown-link.test.tsx → rule.stock-ticker.test.tsx}

@@ -8,14 +8,14 @@ import {defineSchema} from '@portabletext/schema'
 import {Before} from 'racejar'
 import {Feature} from 'racejar/vitest'
 import {InputRulePlugin} from './plugin.input-rule'
-import {createMarkdownLinkRule} from './rule.markdown-link'
-import markdownLinkFeature from './rule.markdown-link.feature?raw'
+import {createStockTickerRule} from './rule.stock-ticker'
+import stockTickerFeature from './rule.stock-ticker.feature?raw'
 
-const markdownLinkRule = createMarkdownLinkRule({
-  linkObject: (context) => ({
-    name: 'link',
+const stockTickerRule = createStockTickerRule({
+  stockTickerObject: (context) => ({
+    name: 'stock-ticker',
     value: {
-      href: context.href,
+      symbol: context.symbol,
     },
   }),
 })
@@ -26,7 +26,7 @@ Feature({
       const {editor, locator} = await createTestEditor({
         children: (
           <>
-            <InputRulePlugin rules={[markdownLinkRule]} />
+            <InputRulePlugin rules={[stockTickerRule]} />
           </>
         ),
         schemaDefinition: defineSchema({
@@ -40,7 +40,7 @@ Feature({
       context.editor = editor
     }),
   ],
-  featureText: markdownLinkFeature,
+  featureText: stockTickerFeature,
   stepDefinitions,
   parameterTypes,
 })

package/src/rule.stock-ticker.ts

@@ -0,0 +1,79 @@
+import type {EditorSchema} from '@portabletext/editor'
+import {raise} from '@portabletext/editor/behaviors'
+import {defineInputRule} from './input-rule'
+
+export function createStockTickerRule(config: {
+  stockTickerObject: (context: {
+    schema: EditorSchema
+    symbol: string
+  }) => {name: string; value?: {[prop: string]: unknown}} | undefined
+}) {
+  return defineInputRule({
+    on: /\{(.+)\}/,
+    guard: ({snapshot, event}) => {
+      const match = event.matches.at(0)
+
+      if (!match) {
+        return false
+      }
+
+      const symbolMatch = match.groupMatches.at(0)
+
+      if (symbolMatch === undefined) {
+        return false
+      }
+
+      const stockTickerObject = config.stockTickerObject({
+        schema: snapshot.context.schema,
+        symbol: symbolMatch.text,
+      })
+
+      if (!stockTickerObject) {
+        return false
+      }
+
+      return {match, stockTickerObject}
+    },
+    actions: [
+      ({snapshot, event}, {match, stockTickerObject}) => {
+        const stockTickerKey = snapshot.context.keyGenerator()
+
+        return [
+          raise({
+            type: 'delete',
+            at: match.targetOffsets,
+          }),
+          raise({
+            type: 'insert.child',
+            child: {
+              ...stockTickerObject.value,
+              _key: stockTickerKey,
+              _type: stockTickerObject.name,
+            },
+          }),
+          raise({
+            type: 'select',
+            at: {
+              anchor: {
+                path: [
+                  {_key: event.focusTextBlock.node._key},
+                  'children',
+                  {_key: stockTickerKey},
+                ],
+                offset: 0,
+              },
+              focus: {
+                path: [
+                  {_key: event.focusTextBlock.node._key},
+                  'children',
+                  {_key: stockTickerKey},
+                ],
+                offset: 0,
+              },
+            },
+          }),
+        ]
+      },
+    ],
+  })
+}

package/src/rule.markdown-link.feature

@@ -1,54 +0,0 @@
-Feature: Markdown Link Rule
-
-  Background:
-    Given the editor is focused
-    And a global keymap
-
-  Scenario Outline: Transform markdown Link into annotation
-    Given the text <text>
-    When <inserted text> is inserted
-    And "new" is typed
-    Then the text is <new text>
-    And <annotated> has marks "k4"
-
-    Examples:
-      | text        | inserted text | new text  | annotated |
-      | "[foo](bar" | ")"           | "foo,new" | "foo"     |
-
-  Scenario: Preserving decorator in link text
-    Given the text "[foo](bar"
-    And "strong" around "foo"
-    When ")" is inserted
-    And "new" is typed
-    Then the text is "foo,new"
-    And "foo" has marks "strong,k6"
-
-  Scenario: Preserving decorators in link text
-    Given the text "[foo](bar"
-    And "strong" around "foo"
-    And "em" around "oo"
-    When ")" is inserted
-    And "new" is typed
-    Then the text is "f,oo,new"
-    And "f" has marks "strong,k7"
-    And "oo" has marks "strong,em,k7"
-
-  Scenario: Overwriting other links
-    Given the text "[foo](bar"
-    And a "link" "l1" around "foo"
-    When the caret is put after "bar"
-    And ")" is inserted
-    And "new" is typed
-    Then the text is "foo,new"
-    And "foo" has an annotation different than "l1"
-
-  Scenario: Preserving other annotations
-    Given the text "[foo](bar"
-    And a "link" "l1" around "foo"
-    And a "comment" "c1" around "foo"
-    When the caret is put after "bar"
-    And ")" is inserted
-    And "new" is typed
-    Then the text is "foo,new"
-    And "foo" has an annotation different than "l1"
-    And "foo" has marks "c1,k9"

package/src/rule.markdown-link.ts

@@ -1,98 +0,0 @@
-import type {EditorSchema} from '@portabletext/editor'
-import {raise, type BehaviorAction} from '@portabletext/editor/behaviors'
-import {defineInputRule} from './input-rule'
-
-export function createMarkdownLinkRule(config: {
-  linkObject: (context: {
-    schema: EditorSchema
-    href: string
-  }) => {name: string; value?: {[prop: string]: unknown}} | undefined
-}) {
-  return defineInputRule({
-    on: /\[(.+)]\((.+)\)/,
-    actions: [
-      ({snapshot, event}) => {
-        const newText = event.textBefore + event.textInserted
-        let textLengthDelta = 0
-        const actions: Array<BehaviorAction> = []
-
-        for (const match of event.matches.reverse()) {
-          const textMatch = match.groupMatches.at(0)
-          const hrefMatch = match.groupMatches.at(1)
-
-          if (textMatch === undefined || hrefMatch === undefined) {
-            continue
-          }
-
-          textLengthDelta =
-            textLengthDelta -
-            (match.targetOffsets.focus.offset -
-              match.targetOffsets.anchor.offset -
-              textMatch.text.length)
-
-          const linkObject = config.linkObject({
-            schema: snapshot.context.schema,
-            href: hrefMatch.text,
-          })
-
-          if (!linkObject) {
-            continue
-          }
-
-          const leftSideOffsets = {
-            anchor: match.targetOffsets.anchor,
-            focus: textMatch.targetOffsets.anchor,
-          }
-          const rightSideOffsets = {
-            anchor: textMatch.targetOffsets.focus,
-            focus: match.targetOffsets.focus,
-          }
-
-          actions.push(
-            raise({
-              type: 'select',
-              at: textMatch.targetOffsets,
-            }),
-          )
-          actions.push(
-            raise({
-              type: 'annotation.add',
-              annotation: {
-                name: linkObject.name,
-                value: linkObject.value ?? {},
-              },
-            }),
-          )
-          actions.push(
-            raise({
-              type: 'delete',
-              at: rightSideOffsets,
-            }),
-          )
-          actions.push(
-            raise({
-              type: 'delete',
-              at: leftSideOffsets,
-            }),
-          )
-        }
-
-        const endCaretPosition = {
-          path: event.focusTextBlock.path,
-          offset: newText.length - textLengthDelta * -1,
-        }
-
-        return [
-          ...actions,
-          raise({
-            type: 'select',
-            at: {
-              anchor: endCaretPosition,
-              focus: endCaretPosition,
-            },
-          }),
-        ]
-      },
-    ],
-  })
-}