docs: adds code examples for how to fully implement textStateFeature (#16053)

Adds a "Rendering on the frontend" section under `TextStateFeature` with
clear examples:

- a shared config file
- how to reference that shared config when setting up TextStateFeature
in your field
- custom text JSX converter

Author: zubricks

docs/rich-text/official-features.mdx

@@ -478,3 +478,121 @@ This is what the example above will look like:
   srcLight="https://payloadcms.com/images/docs/text-state-feature.png"
   alt="Example usage in light and dark mode for TextStateFeature with defaultColors and some custom styles"
 />
+
+#### Rendering on the frontend
+
+When Lexical serializes a text node that has state applied, the state is stored under a `"$"` key in the node object. To apply the styles when rendering rich text on your frontend, you need a custom `text` JSX converter that reads from this key and maps the values back to your CSS config.
+
+**Step 1 — Share your state config**
+
+Extract your `TextStateFeature` state into a file with no package imports so it can be safely imported in both server and client contexts:
+
+```ts
+// src/fields/textStateConfig.ts
+
+export const textStateConfig = {
+  color: {
+    'text-red': {
+      label: 'Red',
+      css: {
+        color:
+          'light-dark(oklch(0.577 0.245 27.325), oklch(0.704 0.191 22.216))',
+      },
+    },
+    'text-blue': {
+      label: 'Blue',
+      css: {
+        color:
+          'light-dark(oklch(0.546 0.245 262.881), oklch(0.707 0.165 254.624))',
+      },
+    },
+    // ...other colors
+  },
+} as const
+```
+
+Then reference it in your field config:
+
+```ts
+// src/blocks/Content/config.ts
+
+import { TextStateFeature, lexicalEditor } from '@payloadcms/richtext-lexical'
+import { textStateConfig } from '@/fields/textStateConfig'
+
+{
+  name: 'richText',
+  type: 'richText',
+  editor: lexicalEditor({
+    features: ({ rootFeatures }) => [
+      ...rootFeatures,
+      TextStateFeature({
+        state: {
+          color: textStateConfig.color,
+        },
+      }),
+    ],
+  }),
+}
+```
+
+**Step 2 — Add a custom text converter**
+
+When using [`RichText` from `@payloadcms/richtext-lexical/react`](/docs/rich-text/lexical#rendering-lexical-content-in-react), override the default `text` converter to read the `"$"` key and apply the corresponding CSS as inline styles:
+
+```tsx
+// src/components/RichText/index.tsx
+
+import { textStateConfig } from '@/fields/textStateConfig'
+import {
+  JSXConvertersFunction,
+  RichText as ConvertRichText,
+} from '@payloadcms/richtext-lexical/react'
+
+// Lexical serializes node state under the "$" key.
+const NODE_STATE_KEY = '$'
+
+// React's style prop requires camelCase, but TextStateFeature CSS uses hyphen-case.
+function hyphenToCamel(str: string): string {
+  return str.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+}
+
+const jsxConverters: JSXConvertersFunction = ({ defaultConverters }) => ({
+  ...defaultConverters,
+  text: (args) => {
+    const { node } = args
+
+    // Render standard formatting (bold, italic, etc.) using the default converter
+    let text =
+      typeof defaultConverters.text === 'function'
+        ? defaultConverters.text(args)
+        : node.text
+
+    // Apply TextStateFeature styles from the "$" key in the serialized node
+    const nodeState = (node as any)[NODE_STATE_KEY] as
+      | Record<string, string>
+      | undefined
+    if (nodeState) {
+      const styles: React.CSSProperties = {}
+      for (const [stateKey, stateValue] of Object.entries(nodeState)) {
+        const css = (textStateConfig as any)[stateKey]?.[stateValue]?.css
+        if (css) {
+          for (const [prop, value] of Object.entries(css)) {
+            ;(styles as any)[hyphenToCamel(prop)] = value
+          }
+        }
+      }
+      if (Object.keys(styles).length > 0) {
+        text = <span style={styles}>{text}</span>
+      }
+    }
+
+    return text
+  },
+})
+
+export default function RichText({ data, ...rest }) {
+  return <ConvertRichText converters={jsxConverters} data={data} {...rest} />
+}
+```
+
+The key insight is that `textStateConfig` is the single source of truth — it is passed directly to `TextStateFeature` in your field config and also imported by your frontend converter to resolve the CSS values at render time.