@od-labs/payloadcms-dynamic-value-richtext 1.0.2 → 1.0.3

package/README.md

@@ -1,96 +1,128 @@
-# Payload Dynamic Value Rich Text Plugin
-
-A powerful [Payload CMS](https://payloadcms.com) plugin for the Lexical editor that allows you to designate field values as dynamic variables. These variables can be reused throughout your rich text content and are visually represented as interactive badges.
-
-## Features
-
-- **Inline Autocomplete**: Trigger a searchable list of available dynamic fields using `@` (default) or a custom character (like `#`).
-- **Visual Badges**: Variables appear in the editor as clean, non-editable badges with a "VAR" prefix, making them distinct from regular text.
-- **Automatic Field Resolution**: Pull fields automatically from specified Collections and Globals, or provide manually defined fields.
-- **Unit Tokenization**: Variables are treated as single units—selecting or deleting them happens in a single action.
-- **Clipboard Support**: Copy and paste dynamic values between editors or documents while maintaining their data integrity.
-- **Light & Dark Mode**: Seamlessly integrates with Payload's admin UI theme.
-
-## Installation
-
-```bash
-pnpm add @od-labs/payloadcms-dynamic-value-richtext
-# or
-npm install @od-labs/payloadcms-dynamic-value-richtext
-```
-
-## Basic Setup
-
-Add the plugin to your `payload.config.ts`:
-
-```typescript
-import { buildConfig } from 'payload'
-import { dynamicValuePlugin } from '@od-labs/payloadcms-dynamic-value-richtext'
-
-export default buildConfig({
-  plugins: [
-    dynamicValuePlugin({
-      collections: ['company-settings', 'sites'],
-      globals: ['contact-info'],
-      trigger: '@',
-    }),
-  ],
-  // ... rest of config
-})
-```
-
-## Configuration
-
-In your Lexical editor configuration, add the `DynamicValueFeature` to your list of features:
-
-```typescript
-import { DynamicValueFeature } from '@od-labs/payloadcms-dynamic-value-richtext'
-
-// In your collection/global field definition:
-{
-  name: 'content',
-  type: 'richText',
-  editor: lexicalEditor({
-    features: ({ defaultFeatures }) => [
-      ...defaultFeatures,
-      DynamicValueFeature(),
-    ],
-  }),
-}
-```
-
-### Plugin Options
-
-| Option        | Type               | Description                                                             |
-| :------------ | :----------------- | :---------------------------------------------------------------------- |
-| `collections` | `CollectionSlug[]` | Automatically extract all text-based fields from these collections.     |
-| `globals`     | `GlobalSlug[]`     | Automatically extract all text-based fields from these globals.         |
-| `fields`      | `Field[]`          | Manually provide a list of Payload fields to be used as dynamic values. |
-| `trigger`     | `string`           | The character that triggers the autocomplete popup. Defaults to `@`.    |
-
-## How it Works
-
-1. **Resolution**: The plugin recursively flattens the fields of your chosen collections and globals. For example, if you have a Global `contact-info` with a field `email`, it becomes available as `contact-info.email`.
-2. **Injection**: When you type the trigger character in the editor, a popup appears showing all available fields.
-3. **Storage**: The variable is stored as a custom `DecoratorNode` in Lexical, which holds a reference to the field path (`value`) and the display label.
-
-## Development
-
-To run the development environment:
-
-1. Clone the repository
-2. Install dependencies: `pnpm install`
-3. Create a `.env` in the `dev` folder (see `.env.example`)
-4. Run development: `pnpm dev`
-
-## Ownership
-
-Created & Owned by **OD LABS**. This plugin is open and free for use to all under the MIT License.
-
-## Contributions
-
-Contributions are welcome! If you have ideas for improvements or find any issues, feel free to open a Pull Request or create an Issue.
-
-## License
-
-MIT
+# Payload Dynamic Value Rich Text Plugin
+
+A powerful [Payload CMS](https://payloadcms.com) plugin for the Lexical editor that allows you to designate field values as dynamic variables. These variables can be reused throughout your rich text content and are visually represented as interactive badges.
+
+## Features
+
+- **Inline Autocomplete**: Trigger a searchable list of available dynamic fields using `@` (default) or a custom character (like `#`).
+- **Visual Badges**: Variables appear in the editor as clean, non-editable badges with a "VAR" prefix, making them distinct from regular text.
+- **Automatic Field Resolution**: Pull fields automatically from specified Collections and Globals, or provide manually defined fields.
+- **Unit Tokenization**: Variables are treated as single units—selecting or deleting them happens in a single action.
+- **Clipboard Support**: Copy and paste dynamic values between editors or documents while maintaining their data integrity.
+- **Light & Dark Mode**: Seamlessly integrates with Payload's admin UI theme.
+
+## Installation
+
+```bash
+pnpm add @od-labs/payloadcms-dynamic-value-richtext
+# or
+npm install @od-labs/payloadcms-dynamic-value-richtext
+```
+
+## Basic Setup
+
+Add the plugin to your `payload.config.ts`:
+
+```typescript
+import { buildConfig } from 'payload'
+import { dynamicValuePlugin } from '@od-labs/payloadcms-dynamic-value-richtext'
+
+export default buildConfig({
+  plugins: [
+    dynamicValuePlugin({
+      collections: ['company-settings', 'sites'],
+      globals: ['contact-info'],
+      trigger: '@',
+    }),
+  ],
+  // ... rest of config
+})
+```
+
+## Configuration
+
+In your Lexical editor configuration, add the `DynamicValueFeature` to your list of features:
+
+```typescript
+import { DynamicValueFeature } from '@od-labs/payloadcms-dynamic-value-richtext'
+
+// In your collection/global field definition:
+{
+  name: 'content',
+  type: 'richText',
+  editor: lexicalEditor({
+    features: ({ defaultFeatures }) => [
+      ...defaultFeatures,
+      DynamicValueFeature(),
+    ],
+  }),
+}
+```
+
+### Plugin Options
+
+| Option        | Type               | Description                                                             |
+| :------------ | :----------------- | :---------------------------------------------------------------------- |
+| `collections` | `CollectionSlug[]` | Automatically extract all text-based fields from these collections.     |
+| `globals`     | `GlobalSlug[]`     | Automatically extract all text-based fields from these globals.         |
+| `fields`      | `Field[]`          | Manually provide a list of Payload fields to be used as dynamic values. |
+| `trigger`     | `string`           | The character that triggers the autocomplete popup. Defaults to `@`.    |
+
+## How it Works
+
+1. **Resolution**: The plugin recursively flattens the fields of your chosen collections and globals. For example, if you have a Global `contact-info` with a field `email`, it becomes available as `contact-info.email`.
+2. **Injection**: When you type the trigger character in the editor, a popup appears showing all available fields.
+3. **Storage**: The variable is stored as a custom `DecoratorNode` in Lexical, which holds a reference to the field path (`value`) and the display label.
+
+## Frontend Rendering (Important)
+
+If you render Lexical content on your website with `RichText`, you must provide this plugin's JSX converters.
+Without this, Payload will show custom nodes as `unknown node`.
+
+### Option A: automatic (recommended)
+
+Use the plugin-provided wrapper component that injects converters for you:
+
+```tsx
+import { DynamicValueRichText } from '@od-labs/payloadcms-dynamic-value-richtext/react'
+
+;<DynamicValueRichText data={page.content} payloadData={page} />
+```
+
+### Option B: manual converters
+
+```tsx
+import { RichText } from '@payloadcms/richtext-lexical/react'
+import { DynamicValueJSXConverters } from '@od-labs/payloadcms-dynamic-value-richtext/jsx'
+
+;<RichText data={page.content} converters={DynamicValueJSXConverters} />
+```
+
+If you want to resolve the dynamic value from real document data at render time:
+
+```tsx
+import { createDynamicValueJSXConverters } from '@od-labs/payloadcms-dynamic-value-richtext/jsx'
+
+const converters = createDynamicValueJSXConverters({ data: page })
+```
+
+## Development
+
+To run the development environment:
+
+1. Clone the repository
+2. Install dependencies: `pnpm install`
+3. Create a `.env` in the `dev` folder (see `.env.example`)
+4. Run development: `pnpm dev`
+
+## Ownership
+
+Created & Owned by **OD LABS**. This plugin is open and free for use to all under the MIT License.
+
+## Contributions
+
+Contributions are welcome! If you have ideas for improvements or find any issues, feel free to open a Pull Request or create an Issue.
+
+## License
+
+MIT

package/dist/exports/jsx.d.ts

@@ -0,0 +1,13 @@
+import type { JSXConverters } from '@payloadcms/richtext-lexical/react';
+import React from 'react';
+import type { SerializedDynamicValueNode } from '../nodes/DynamicValueNode/index.js';
+/**
+ * JSX converters for dynamic value nodes. Includes both the current node type and
+ * the legacy type to keep older content working.
+ */
+export declare const DynamicValueJSXConverters: JSXConverters;
+export declare const withDynamicValueJSXConverters: (converters?: JSXConverters) => JSXConverters;
+export declare function createDynamicValueJSXConverters(options: {
+    data?: Record<string, unknown>;
+    fallback?: (node: SerializedDynamicValueNode) => React.ReactNode;
+}): JSXConverters;

package/dist/exports/jsx.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { DYNAMIC_VALUE_NODE_TYPE, LEGACY_DYNAMIC_VALUE_NODE_TYPE } from '../nodes/DynamicValueNode/index.js';
+const renderDynamicValueLabel = (node)=>{
+    return /*#__PURE__*/ _jsx("span", {
+        "data-payload-dynamic-field": node.field,
+        "data-payload-dynamic-value": "true",
+        children: node.label
+    }, node.field);
+};
+const dynamicValueJSXConverter = ({ node })=>{
+    const dynamicNode = node;
+    return renderDynamicValueLabel(dynamicNode);
+};
+/**
+ * JSX converters for dynamic value nodes. Includes both the current node type and
+ * the legacy type to keep older content working.
+ */ export const DynamicValueJSXConverters = {
+    [DYNAMIC_VALUE_NODE_TYPE]: dynamicValueJSXConverter,
+    [LEGACY_DYNAMIC_VALUE_NODE_TYPE]: dynamicValueJSXConverter
+};
+export const withDynamicValueJSXConverters = (converters)=>({
+        ...converters || {},
+        ...DynamicValueJSXConverters
+    });
+export function createDynamicValueJSXConverters(options) {
+    const { data = {}, fallback } = options;
+    const converter = ({ node })=>{
+        const dynamicNode = node;
+        const resolvedValue = dynamicNode.field.split('.').reduce((current, key)=>{
+            if (current && typeof current === 'object' && key in current) {
+                return current[key];
+            }
+            return undefined;
+        }, data);
+        if (resolvedValue !== undefined && resolvedValue !== null && resolvedValue !== '') {
+            return /*#__PURE__*/ _jsx("span", {
+                "data-payload-dynamic-field": dynamicNode.field,
+                "data-payload-dynamic-value": "true",
+                children: String(resolvedValue)
+            }, dynamicNode.field);
+        }
+        if (fallback) {
+            return /*#__PURE__*/ _jsx(React.Fragment, {
+                children: fallback(dynamicNode)
+            }, dynamicNode.field);
+        }
+        return renderDynamicValueLabel(dynamicNode);
+    };
+    return {
+        [DYNAMIC_VALUE_NODE_TYPE]: converter,
+        [LEGACY_DYNAMIC_VALUE_NODE_TYPE]: converter
+    };
+}
+
+//# sourceMappingURL=jsx.js.map

package/dist/exports/jsx.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/exports/jsx.tsx"],"sourcesContent":["import type { JSXConverters } from '@payloadcms/richtext-lexical/react'\r\n\r\nimport React from 'react'\r\n\r\nimport type { SerializedDynamicValueNode } from '../nodes/DynamicValueNode/index.js'\r\n\r\nimport {\r\n  DYNAMIC_VALUE_NODE_TYPE,\r\n  LEGACY_DYNAMIC_VALUE_NODE_TYPE,\r\n} from '../nodes/DynamicValueNode/index.js'\r\n\r\nconst renderDynamicValueLabel = (node: SerializedDynamicValueNode) => {\r\n  return (\r\n    <span\r\n      data-payload-dynamic-field={node.field}\r\n      data-payload-dynamic-value=\"true\"\r\n      key={node.field}\r\n    >\r\n      {node.label}\r\n    </span>\r\n  )\r\n}\r\n\r\nconst dynamicValueJSXConverter = ({ node }: { node: unknown }) => {\r\n  const dynamicNode = node as SerializedDynamicValueNode\r\n  return renderDynamicValueLabel(dynamicNode)\r\n}\r\n\r\n/**\r\n * JSX converters for dynamic value nodes. Includes both the current node type and\r\n * the legacy type to keep older content working.\r\n */\r\nexport const DynamicValueJSXConverters: JSXConverters = {\r\n  [DYNAMIC_VALUE_NODE_TYPE]: dynamicValueJSXConverter,\r\n  [LEGACY_DYNAMIC_VALUE_NODE_TYPE]: dynamicValueJSXConverter,\r\n}\r\n\r\nexport const withDynamicValueJSXConverters = (converters?: JSXConverters): JSXConverters => ({\r\n  ...(converters || {}),\r\n  ...DynamicValueJSXConverters,\r\n})\r\n\r\nexport function createDynamicValueJSXConverters(options: {\r\n  data?: Record<string, unknown>\r\n  fallback?: (node: SerializedDynamicValueNode) => React.ReactNode\r\n}): JSXConverters {\r\n  const { data = {}, fallback } = options\r\n\r\n  const converter = ({ node }: { node: unknown }) => {\r\n    const dynamicNode = node as SerializedDynamicValueNode\r\n    const resolvedValue = dynamicNode.field.split('.').reduce<unknown>((current, key) => {\r\n      if (current && typeof current === 'object' && key in (current as Record<string, unknown>)) {\r\n        return (current as Record<string, unknown>)[key]\r\n      }\r\n\r\n      return undefined\r\n    }, data)\r\n\r\n    if (resolvedValue !== undefined && resolvedValue !== null && resolvedValue !== '') {\r\n      return (\r\n        <span\r\n          data-payload-dynamic-field={dynamicNode.field}\r\n          data-payload-dynamic-value=\"true\"\r\n          key={dynamicNode.field}\r\n        >\r\n          {String(resolvedValue)}\r\n        </span>\r\n      )\r\n    }\r\n\r\n    if (fallback) {\r\n      return <React.Fragment key={dynamicNode.field}>{fallback(dynamicNode)}</React.Fragment>\r\n    }\r\n\r\n    return renderDynamicValueLabel(dynamicNode)\r\n  }\r\n\r\n  return {\r\n    [DYNAMIC_VALUE_NODE_TYPE]: converter,\r\n    [LEGACY_DYNAMIC_VALUE_NODE_TYPE]: converter,\r\n  }\r\n}\r\n"],"names":["React","DYNAMIC_VALUE_NODE_TYPE","LEGACY_DYNAMIC_VALUE_NODE_TYPE","renderDynamicValueLabel","node","span","data-payload-dynamic-field","field","data-payload-dynamic-value","label","dynamicValueJSXConverter","dynamicNode","DynamicValueJSXConverters","withDynamicValueJSXConverters","converters","createDynamicValueJSXConverters","options","data","fallback","converter","resolvedValue","split","reduce","current","key","undefined","String","Fragment"],"mappings":";AAEA,OAAOA,WAAW,QAAO;AAIzB,SACEC,uBAAuB,EACvBC,8BAA8B,QACzB,qCAAoC;AAE3C,MAAMC,0BAA0B,CAACC;IAC/B,qBACE,KAACC;QACCC,8BAA4BF,KAAKG,KAAK;QACtCC,8BAA2B;kBAG1BJ,KAAKK,KAAK;OAFNL,KAAKG,KAAK;AAKrB;AAEA,MAAMG,2BAA2B,CAAC,EAAEN,IAAI,EAAqB;IAC3D,MAAMO,cAAcP;IACpB,OAAOD,wBAAwBQ;AACjC;AAEA;;;CAGC,GACD,OAAO,MAAMC,4BAA2C;IACtD,CAACX,wBAAwB,EAAES;IAC3B,CAACR,+BAA+B,EAAEQ;AACpC,EAAC;AAED,OAAO,MAAMG,gCAAgC,CAACC,aAA+C,CAAA;QAC3F,GAAIA,cAAc,CAAC,CAAC;QACpB,GAAGF,yBAAyB;IAC9B,CAAA,EAAE;AAEF,OAAO,SAASG,gCAAgCC,OAG/C;IACC,MAAM,EAAEC,OAAO,CAAC,CAAC,EAAEC,QAAQ,EAAE,GAAGF;IAEhC,MAAMG,YAAY,CAAC,EAAEf,IAAI,EAAqB;QAC5C,MAAMO,cAAcP;QACpB,MAAMgB,gBAAgBT,YAAYJ,KAAK,CAACc,KAAK,CAAC,KAAKC,MAAM,CAAU,CAACC,SAASC;YAC3E,IAAID,WAAW,OAAOA,YAAY,YAAYC,OAAQD,SAAqC;gBACzF,OAAO,AAACA,OAAmC,CAACC,IAAI;YAClD;YAEA,OAAOC;QACT,GAAGR;QAEH,IAAIG,kBAAkBK,aAAaL,kBAAkB,QAAQA,kBAAkB,IAAI;YACjF,qBACE,KAACf;gBACCC,8BAA4BK,YAAYJ,KAAK;gBAC7CC,8BAA2B;0BAG1BkB,OAAON;eAFHT,YAAYJ,KAAK;QAK5B;QAEA,IAAIW,UAAU;YACZ,qBAAO,KAAClB,MAAM2B,QAAQ;0BAA0BT,SAASP;eAA7BA,YAAYJ,KAAK;QAC/C;QAEA,OAAOJ,wBAAwBQ;IACjC;IAEA,OAAO;QACL,CAACV,wBAAwB,EAAEkB;QAC3B,CAACjB,+BAA+B,EAAEiB;IACpC;AACF"}

package/dist/exports/react.d.ts

@@ -0,0 +1,19 @@
+import type { JSXConverters } from '@payloadcms/richtext-lexical/react';
+import React from 'react';
+type DynamicValueRichTextProps = {
+    className?: string;
+    converters?: JSXConverters;
+    data: any;
+    disableContainer?: boolean;
+    disableIndent?: boolean | string[];
+    disableTextAlign?: boolean | string[];
+    payloadData?: Record<string, unknown>;
+};
+/**
+ * Drop-in RichText renderer that always includes dynamic-value converters.
+ *
+ * This prevents "unknown node" output for DynamicValueNode even if the
+ * consuming app forgets to pass plugin converters manually.
+ */
+export declare const DynamicValueRichText: React.FC<DynamicValueRichTextProps>;
+export {};

package/dist/exports/react.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RichText } from '@payloadcms/richtext-lexical/react';
+import React from 'react';
+import { createDynamicValueJSXConverters } from './jsx.js';
+/**
+ * Drop-in RichText renderer that always includes dynamic-value converters.
+ *
+ * This prevents "unknown node" output for DynamicValueNode even if the
+ * consuming app forgets to pass plugin converters manually.
+ */ export const DynamicValueRichText = ({ converters, payloadData, ...props })=>{
+    return /*#__PURE__*/ _jsx(RichText, {
+        ...props,
+        converters: {
+            ...converters || {},
+            ...createDynamicValueJSXConverters({
+                data: payloadData || props.data || {}
+            })
+        }
+    });
+};
+
+//# sourceMappingURL=react.js.map

package/dist/exports/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/exports/react.tsx"],"sourcesContent":["import type { JSXConverters } from '@payloadcms/richtext-lexical/react'\r\n\r\nimport { RichText } from '@payloadcms/richtext-lexical/react'\r\nimport React from 'react'\r\n\r\nimport { createDynamicValueJSXConverters } from './jsx.js'\r\n\r\ntype DynamicValueRichTextProps = {\r\n  className?: string\r\n  converters?: JSXConverters\r\n  data: any\r\n  disableContainer?: boolean\r\n  disableIndent?: boolean | string[]\r\n  disableTextAlign?: boolean | string[]\r\n  payloadData?: Record<string, unknown>\r\n}\r\n\r\n/**\r\n * Drop-in RichText renderer that always includes dynamic-value converters.\r\n *\r\n * This prevents \"unknown node\" output for DynamicValueNode even if the\r\n * consuming app forgets to pass plugin converters manually.\r\n */\r\nexport const DynamicValueRichText: React.FC<DynamicValueRichTextProps> = ({\r\n  converters,\r\n  payloadData,\r\n  ...props\r\n}) => {\r\n  return (\r\n    <RichText\r\n      {...props}\r\n      converters={{\r\n        ...(converters || {}),\r\n        ...createDynamicValueJSXConverters({ data: payloadData || props.data || {} }),\r\n      }}\r\n    />\r\n  )\r\n}\r\n"],"names":["RichText","React","createDynamicValueJSXConverters","DynamicValueRichText","converters","payloadData","props","data"],"mappings":";AAEA,SAASA,QAAQ,QAAQ,qCAAoC;AAC7D,OAAOC,WAAW,QAAO;AAEzB,SAASC,+BAA+B,QAAQ,WAAU;AAY1D;;;;;CAKC,GACD,OAAO,MAAMC,uBAA4D,CAAC,EACxEC,UAAU,EACVC,WAAW,EACX,GAAGC,OACJ;IACC,qBACE,KAACN;QACE,GAAGM,KAAK;QACTF,YAAY;YACV,GAAIA,cAAc,CAAC,CAAC;YACpB,GAAGF,gCAAgC;gBAAEK,MAAMF,eAAeC,MAAMC,IAAI,IAAI,CAAC;YAAE,EAAE;QAC/E;;AAGN,EAAC"}

package/dist/exports/rsc.d.ts

@@ -0,0 +1 @@
+export { createDynamicValueJSXConverters, DynamicValueJSXConverters } from './jsx.js';

package/dist/exports/rsc.js

@@ -0,0 +1,3 @@
+export { createDynamicValueJSXConverters, DynamicValueJSXConverters } from './jsx.js';
+
+//# sourceMappingURL=rsc.js.map

package/dist/exports/rsc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/exports/rsc.tsx"],"sourcesContent":["export { createDynamicValueJSXConverters, DynamicValueJSXConverters } from './jsx.js'\r\n"],"names":["createDynamicValueJSXConverters","DynamicValueJSXConverters"],"mappings":"AAAA,SAASA,+BAA+B,EAAEC,yBAAyB,QAAQ,WAAU"}

package/dist/features/DynamicValue/feature.client.d.ts

@@ -1,8 +1,4 @@
-import type { DynamicValueOption } from './types.js';
-export declare const DynamicValueFeatureClient: import("@payloadcms/richtext-lexical").FeatureProviderProviderClient<{
-    options: DynamicValueOption[];
-    trigger: string;
-}, {
-    options: DynamicValueOption[];
-    trigger: string;
-}>;
+import { type LexicalNode } from '@payloadcms/richtext-lexical/lexical';
+import { DynamicValueNode } from '../../nodes/DynamicValueNode/index.js';
+export declare function $isDynamicValueNode(node: LexicalNode | null | undefined): node is DynamicValueNode;
+export declare const DynamicValueFeatureClient: import("@payloadcms/richtext-lexical").FeatureProviderProviderClient<undefined, any>;