{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "date-docs",
  "title": "Date",
  "description": "Inline void date elements with canonical and raw date storage.",
  "files": [
    {
      "path": "../../content/docs/(plugins)/(elements)/date.mdx",
      "content": "---\ntitle: Date\ndescription: Inline void date elements with canonical and raw date storage.\ndocs:\n  - route: /docs/components/date-node\n    title: Date Element\n  - route: https://pro.platejs.org/docs/components/date-node\n    title: Plus\n---\n\nDate adds inline void elements that display a date label inside text. Canonical dates are stored as `YYYY-MM-DD`; non-normalizable input is kept as `rawDate`. This page covers kit setup, insertion, value shape, picker behavior, Markdown serialization, and the small query API.\n\n<ComponentPreview name=\"date-demo\" />\n\n<PackageInfo>\n\n## Features\n\n- Inline void `date` element.\n- Bound `editor.tf.insert.date` transform.\n- Direct `insertDate(editor, options)` helper.\n- Canonical `date` storage with `rawDate` fallback.\n- Calendar editing in the registry UI.\n- Static renderer for read-only output.\n- Markdown round-trip through `<date value=\"YYYY-MM-DD\" />` and child-text date tags.\n\n</PackageInfo>\n\n## Fast Path\n\n<Steps>\n\n### Add The Kit\n\n`DateKit` installs `DatePlugin` with the registry `DateElement`.\n\n<ComponentSource name=\"date-kit\" />\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\n\nimport { DateKit } from '@/components/editor/plugins/date-kit';\n\nexport const editor = createPlateEditor({\n  plugins: DateKit,\n});\n```\n\n### Render The Element\n\n`date-node` owns the inline wrapper, display label, popover, calendar picker, and static element.\n\n<ComponentSource name=\"date-node\" />\n\n### Add An Insert Action\n\nThe registry insert toolbar maps `KEYS.date` to `insertDate(editor, { select: true })`.\n\n```tsx title=\"components/editor/transforms.ts\"\nimport { insertDate } from '@platejs/date';\nimport { KEYS } from 'platejs';\n\nexport const insertInlineMap = {\n  [KEYS.date]: (editor) => insertDate(editor, { select: true }),\n};\n```\n\n</Steps>\n\n## Ownership\n\n| Layer | Owner | What It Does |\n|-------|-------|--------------|\n| `@platejs/date` | Package | Exports `BaseDatePlugin`, `insertDate`, date value helpers, and `isPointNextToNode`. |\n| `@platejs/date/react` | Package | Exports `DatePlugin`. |\n| `date-kit` | Registry | Adds `DatePlugin.withComponent(DateElement)`. |\n| `date-base-kit` | Registry | Adds `BaseDatePlugin.withComponent(DateElementStatic)`. |\n| `date-node` | Registry UI | Renders the editable popover/calendar element and static element. |\n| `@platejs/markdown` | Package | Converts date MDX tags to canonical `date` or fallback `rawDate` values. |\n\n`BaseDatePlugin` is inline and void. The text child exists only to satisfy Slate's element shape.\n\n## Manual Setup\n\n<Steps>\n\n### Install Package\n\n```bash\nnpm install @platejs/date\n```\n\n### Add The Plugin\n\nUse the React plugin when the editor renders the calendar popover.\n\n```tsx\nimport { DatePlugin } from '@platejs/date/react';\nimport { createPlateEditor } from 'platejs/react';\n\nimport { DateElement } from '@/components/ui/date-node';\n\nexport const editor = createPlateEditor({\n  plugins: [DatePlugin.withComponent(DateElement)],\n});\n```\n\n### Add Static Rendering\n\nUse the base kit when rendering read-only output with `platejs/static`.\n\n<ComponentSource name=\"date-base-kit\" />\n\n### Insert A Date\n\n`DatePlugin` binds `insertDate` to `editor.tf.insert.date`.\n\n```tsx\neditor.tf.insert.date({\n  date: '2026-03-23',\n  select: true,\n});\n```\n\nUse the package helper directly when you are outside plugin-bound transform access.\n\n```tsx\nimport { insertDate } from '@platejs/date';\n\ninsertDate(editor, {\n  date: '2026-03-23',\n  select: true,\n});\n```\n\n</Steps>\n\n## Value Shape\n\nCanonical date values live in `date`. Invalid or intentionally loose date text lives in `rawDate`.\n\n```tsx\nconst value = [\n  {\n    children: [\n      { text: 'Due ' },\n      {\n        children: [{ text: '' }],\n        date: '2026-03-23',\n        type: 'date',\n      },\n      { text: '.' },\n    ],\n    type: 'p',\n  },\n];\n```\n\n| Field | Type | Notes |\n|-------|------|-------|\n| `type` | `'date'` | Plugin key and node type from `KEYS.date`. |\n| `children` | `[{ text: '' }]` | Required Slate child for the inline void element. |\n| `date` | `string` | Canonical `YYYY-MM-DD` value. |\n| `rawDate` | `string` | Fallback for non-normalizable input. |\n\n## Date Normalization\n\n`normalizeDateValue` decides which field is written.\n\n| Input | Stored Value |\n|-------|--------------|\n| `Date` object | `date: formatDateValue(value)` when the object is valid. |\n| `YYYY-MM-DD` | `date` when the calendar date is valid. |\n| Invalid canonical string | `rawDate`. |\n| `Mon Mar 23 2026` | `date: '2026-03-23'` when JavaScript can parse it. |\n| Blank string | no date fields. |\n| Other text | `rawDate`. |\n\n`getDateDisplayLabel` returns `Today`, `Yesterday`, `Tomorrow`, a localized long date, or the raw fallback string.\n\n## Picker Behavior\n\nThe registry element is display-only while read-only. In editable mode, clicking the inline label opens a calendar popover.\n\n| State | Behavior |\n|-------|----------|\n| `date` exists | The trigger shows `getDateDisplayLabel(element)`. |\n| `rawDate` exists | The trigger shows the raw string. |\n| no date fields | The trigger shows `Pick a date`. |\n| calendar selection | The node is set to `{ date: formatDateValue(date), rawDate: undefined }`. |\n\nThe registry element uses `contentEditable={false}` on the inline wrapper, so users edit the date through the calendar instead of typing inside the void node.\n\n## Markdown\n\nCanonical values serialize as a self-closing date tag with a `value` attribute.\n\n```mdx\nDate: <date value=\"2026-03-23\" />\n```\n\nRaw fallback values serialize as child text.\n\n```mdx\nDate: <date>sometime next week</date>\n```\n\nThe deserializer also accepts child text such as `<date>Mon Mar 23 2026</date>` and normalizes it to `date: '2026-03-23'` when the date is safe to parse.\n\n## API Reference\n\n| API | Package | Use |\n|-----|---------|-----|\n| `BaseDatePlugin` | `@platejs/date` | Headless inline void date plugin. |\n| `DatePlugin` | `@platejs/date/react` | React date plugin. |\n| `insertDate(editor, options)` | `@platejs/date` | Inserts a date element plus a trailing text space. |\n| `editor.tf.insert.date(options)` | plugin-bound transform | Bound transform registered by `BaseDatePlugin`. |\n| `normalizeDateValue(value)` | `@platejs/date` | Returns `{ date }`, `{ rawDate }`, or an empty object. |\n| `formatDateValue(date)` | `@platejs/date` | Formats a `Date` object as `YYYY-MM-DD`. |\n| `parseCanonicalDateValue(value)` | `@platejs/date` | Parses only valid canonical date strings. |\n| `getDateDisplayLabel(options)` | `@platejs/date` | Builds the visible date label. |\n| `isPointNextToNode(editor, options)` | `@platejs/date` | Checks whether a point is adjacent to a node type. Throws when neither `options.at` nor editor selection exists. |\n| `TDateElement` | `platejs` | Element shape with optional `date` and `rawDate`. |\n",
      "type": "registry:file",
      "target": "content/docs/plate/(plugins)/(elements)/date.mdx"
    }
  ],
  "type": "registry:file"
}