{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "api-utils-docs",
  "title": "Plate Utils",
  "description": "API reference for @platejs/utils.",
  "files": [
    {
      "path": "../../content/docs/api/utils.mdx",
      "content": "---\ntitle: Plate Utils\ndescription: API reference for @platejs/utils.\n---\n\n`@platejs/utils` contains Plate's shared key constants, editor value types, and\nsmall utility plugins. `@platejs/utils/react` adds React hooks and the block\nplaceholder plugin used by registry UI.\n\n## Installation\n\n```bash\nnpm install @platejs/utils\n```\n\nApplication code usually imports this surface from `platejs` and `platejs/react`.\nDirect package imports are useful inside packages that should not depend on the\numbrella `platejs` package.\n\n## Import Paths\n\n| Import | Re-exports | Use |\n| --- | --- | --- |\n| `@platejs/utils` | `plate-keys`, `plate-types`, utility plugins | Shared node keys, Plate element/mark types, and headless utility plugins. |\n| `@platejs/utils/react` | React hooks, `BlockPlaceholderPlugin` | Registry controls and React-only utility behavior. |\n| `platejs` | `@platejs/utils` | App-level imports for headless constants, types, and utility plugins. |\n| `platejs/react` | `@platejs/utils/react` | App-level imports for React hooks and `BlockPlaceholderPlugin`. |\n\n## Key Constants\n\n`KEYS` is the canonical key map used by Plate packages, registry components, and\nplugin configuration.\n\n| Export | Contains | Notes |\n| --- | --- | --- |\n| `NODES` | Element and mark node keys such as `p`, `blockquote`, `codeBlock`, `table`, `bold`, and `link` | `link` maps to the same node type as `a`. |\n| `STYLE_KEYS` | Style property keys such as `color`, `fontSize`, `indent`, and `textAlign` | Used by style plugins and registry controls. |\n| `KEYS` | `NODES`, `STYLE_KEYS`, and plugin keys such as `exitBreak`, `normalizeTypes`, `singleBlock`, and `trailingBlock` | Also includes grouped values such as `heading`. |\n| `NodeKey` | Union of values from `NODES` | Use for node-type values. |\n| `StyleKey` | Union of values from `STYLE_KEYS` | Use for style keys. |\n| `PlateKey` | Union of values from `KEYS` | Includes string values and grouped key arrays. |\n\n```ts title=\"Use Plate keys\"\nimport { KEYS, TrailingBlockPlugin } from 'platejs';\n\nexport const trailingBlock = TrailingBlockPlugin.configure({\n  options: {\n    type: KEYS.p,\n  },\n});\n```\n\n## Shared Types\n\n`plate-types` exports common element, prop, media, list, table, mark, and\nsuggestion shapes used across feature packages.\n\n| Type group | Examples | Use |\n| --- | --- | --- |\n| Block elements | `TCalloutElement`, `TCodeBlockElement`, `TColumnElement`, `TDateElement`, `TEquationElement` | Typed element props for feature packages and registry nodes. |\n| Media elements | `TImageElement`, `TAudioElement`, `TFileElement`, `TVideoElement`, `TMediaEmbedElement` | Media nodes with `url`, `id`, upload, provider, and source metadata. |\n| Table elements | `TTableElement`, `TTableRowElement`, `TTableCellElement`, `TTableCellBorder` | Table structure, spans, sizes, backgrounds, and borders. |\n| Shared props | `TIdProps`, `TCaptionProps`, `TIndentProps`, `TResizableProps`, `TListProps` | Reusable node property contracts. |\n| Marks | `TBasicMarks`, `TFontMarks`, `TCommentText`, `TSuggestionText` | Text marks and collaboration text state. |\n| Suggestions | `TSuggestionData`, `TInsertSuggestionData`, `TRemoveSuggestionData`, `TUpdateSuggestionData` | Suggestion metadata stored on elements or text. |\n\n```ts title=\"Type a media element\"\nimport type { TImageElement } from 'platejs';\n\nexport function getImageUrl(element: TImageElement) {\n  return element.url;\n}\n```\n\n## Utility Plugins\n\n| Plugin | Key | Behavior |\n| --- | --- | --- |\n| `ExitBreakPlugin` | `KEYS.exitBreak` | Adds `editor.tf.insert` and `editor.tf.insertBefore` wrappers around `insertExitBreak`. |\n| `NormalizeTypesPlugin` | `KEYS.normalizeTypes` | Normalizes configured root paths to a required `type` or `strictType`. |\n| `SingleBlockPlugin` | `KEYS.singleBlock` | Forces the editor value into one block and turns hard breaks into soft breaks. |\n| `SingleLinePlugin` | `KEYS.singleLine` | Forces one block and strips line-break characters from text nodes. |\n| `TrailingBlockPlugin` | `KEYS.trailingBlock` | Ensures a trailing block exists at the configured level and type. |\n| `withTrailingBlock` | Override editor helper | Implements the trailing block normalization logic used by `TrailingBlockPlugin`. |\n\nUse the plugin guide pages for options and examples:\n[Exit Break](/docs/exit-break), [Forced Layout](/docs/forced-layout),\n[Single Block](/docs/single-block), and [Trailing Block](/docs/trailing-block).\n\n## React Hooks\n\n| Hook | Returns | Use |\n| --- | --- | --- |\n| `useEditorString()` | `string` | Reads `editor.api.string([])` through `useEditorSelector`. |\n| `useFormInputProps(options?)` | `{ props }` | Adds an optional `onKeyDownCapture` handler that prevents Enter from submitting a wrapper form. |\n| `useMarkToolbarButtonState({ nodeType, clear? })` | `{ clear, nodeType, pressed }` | Reads whether a mark is active. |\n| `useMarkToolbarButton(state)` | `{ props }` | Provides `pressed`, `onClick`, and `onMouseDown` props that toggle a mark and focus the editor. |\n| `useRemoveNodeButton({ element })` | `{ props }` | Provides button props that remove an element by path. |\n| `useSelectionCollapsed()` | `boolean` | Selection is collapsed. |\n| `useSelectionExpanded()` | `boolean` | Selection is expanded. |\n| `useSelectionWithinBlock()` | `boolean` | Selection is inside one block. |\n| `useSelectionAcrossBlocks()` | `boolean` | Selection spans blocks. |\n| `useSelectionFragment()` | `Descendant[]` | Reads the selected fragment while unwrapping container types. |\n| `useSelectionFragmentProp(options?)` | `unknown` | Reads a property from the selected fragment. |\n\n```tsx title=\"registry/ui/mark-toolbar-button.tsx\"\nimport {\n  useMarkToolbarButton,\n  useMarkToolbarButtonState,\n} from 'platejs/react';\n\nexport function MarkToolbarButton({ nodeType }: { nodeType: string }) {\n  const state = useMarkToolbarButtonState({ nodeType });\n  const { props } = useMarkToolbarButton(state);\n\n  return <button type=\"button\" aria-pressed={props.pressed} {...props} />;\n}\n```\n\n## React Plugins\n\n| Plugin | Key | Behavior |\n| --- | --- | --- |\n| `BlockPlaceholderPlugin` | `KEYS.blockPlaceholder` | Tracks the current empty block and injects `placeholder` and optional `className` props into matching block components. |\n\n`BlockPlaceholderPlugin` defaults to paragraph placeholders and only targets a\nfocused, editable, collapsed selection. Configure `placeholders` by plugin key\nand `query` by node/path.\n\n```tsx title=\"components/editor/plugins/block-placeholder-kit.tsx\"\nimport { KEYS } from 'platejs';\nimport { BlockPlaceholderPlugin } from 'platejs/react';\n\nexport const blockPlaceholderPlugin = BlockPlaceholderPlugin.configure({\n  options: {\n    placeholders: {\n      [KEYS.p]: 'Type something...',\n    },\n    query: ({ path }) => path.length === 1,\n  },\n});\n```\n\n## Related APIs\n\n- [Plate](/docs/api/plate) covers the umbrella package that re-exports these APIs.\n- [Plate Core](/docs/api/core) covers editor creation, plugin contracts, and stores.\n- [React Utils](/docs/api/react-utils) covers `@udecode/react-utils`, which is re-exported through `platejs/react`.\n- [Toolbar](/docs/toolbar) covers registry controls that use the React hook helpers.\n",
      "type": "registry:file",
      "target": "content/docs/plate/api/utils.mdx"
    }
  ],
  "type": "registry:file"
}