@portabletext/plugin-input-rule 0.3.2 → 0.3.4

package/README.md

@@ -2,15 +2,15 @@
 
 > Easily configure Input Rules in the Portable Text Editor
 
-> ⚠️ Please note that `defineInputRule` and other APIs exposed by this plugin are still WIP and might change slightly. We are still ironing out some details before can cut a stable release.
+> ⚠️ **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 an inserted text pattern to then perform a set of actions is incredibly common, but also carries many footguns:
+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. And have you considered `insert.text` events that carry more than one character? (Android says hello.)
+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 to allow you to write text transformation logic as if they were Behaviors, without having to worry about low-level details:
+_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'
@@ -19,13 +19,13 @@ import {getPreviousInlineObject} from '@portabletext/editor/selectors'
 import {defineInputRule} from '@portabletext/plugin-input-rule'
 
 const unorderedListRule = defineInputRule({
-  // Instead of an event, we listen for a RegExp pattern
+  // 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.
+  // 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 match.
+    // 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) {
@@ -42,7 +42,7 @@ const unorderedListRule = defineInputRule({
         props: ['style'],
         at: event.focusTextBlock.path,
       }),
-      // Then, turn it into a list ite
+      // Then, turn it into a list item
       raise({
         type: 'block.set',
         props: {
@@ -65,11 +65,11 @@ export function MyMarkdownPlugin() {
 }
 ```
 
-🤫 [`@portabletext/plugin-markdown-shortcuts`](../plugin-markdown-shortcuts/) already exists and is powered by Input Rules.
+> 💡 **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
 
-Because text transformations are so common, the plugin exposes a high-level `defineTextTransformRule` to configure these without the need for any boilerplate:
+Text transformations are so common that the plugin provides a high-level `defineTextTransformRule` helper to configure them without any boilerplate:
 
 ```tsx
 const emDashRule = defineTextTransformRule({
@@ -78,20 +78,22 @@ const emDashRule = defineTextTransformRule({
 })
 
 export function MyTypographyPlugin() {
-  return <InputRulePlugin rules={[emDasRule]} />
+  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.
 
-## Other Examples
+## Advanced Examples
 
-Other ideas that can easily be realized with Input Rules:
+Input Rules can handle more complex transformations. Here are two advanced examples:
 
-1. Automatically turning `"[Sanity](https://sanity.io)" into a link.
-2. Listening for text patterns like `"{AAPL}"` and turn that into a stock ticker.
+1. **Markdown Link**: Automatically convert `[text](url)` syntax into proper links
+2. **Stock Ticker**: Convert `{SYMBOL}` patterns into stock ticker objects
 
-### Markdown Link
+### Markdown Link Rule
+
+This example shows how to convert markdown-style link syntax `[text](url)` into proper link annotations:
 
 ```tsx
 const markdownLinkRule = defineInputRule({
@@ -176,7 +178,9 @@ const markdownLinkRule = defineInputRule({
 })
 ```
 
-## Stock Ticker Rule
+### Stock Ticker Rule
+
+This example demonstrates how to convert text patterns like `{AAPL}` into custom inline objects:
 
 ```tsx
 const stockTickerRule = defineInputRule({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/plugin-input-rule",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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.3",
     "@portabletext/schema": "1.2.0",
     "racejar": "1.3.1"
   },
   "peerDependencies": {
-    "@portabletext/editor": "^2.14.1",
+    "@portabletext/editor": "^2.14.3",
     "react": "^19.1.1"
   },
   "publishConfig": {

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.test.tsx

@@ -1,46 +0,0 @@
-import {parameterTypes} from '@portabletext/editor/test'
-import {
-  createTestEditor,
-  stepDefinitions,
-  type Context,
-} from '@portabletext/editor/test/vitest'
-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'
-
-const markdownLinkRule = createMarkdownLinkRule({
-  linkObject: (context) => ({
-    name: 'link',
-    value: {
-      href: context.href,
-    },
-  }),
-})
-
-Feature({
-  hooks: [
-    Before(async (context: Context) => {
-      const {editor, locator} = await createTestEditor({
-        children: (
-          <>
-            <InputRulePlugin rules={[markdownLinkRule]} />
-          </>
-        ),
-        schemaDefinition: defineSchema({
-          decorators: [{name: 'strong'}, {name: 'em'}],
-          annotations: [{name: 'link'}, {name: 'comment'}],
-          inlineObjects: [{name: 'stock-ticker'}],
-        }),
-      })
-
-      context.locator = locator
-      context.editor = editor
-    }),
-  ],
-  featureText: markdownLinkFeature,
-  stepDefinitions,
-  parameterTypes,
-})

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,
-            },
-          }),
-        ]
-      },
-    ],
-  })
-}