@puckeditor/cli 0.24.0-canary.10b39dc7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (372) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +54 -0
  3. package/dist/bin.mjs +10343 -0
  4. package/dist/docs/api-reference/actions.md +63 -0
  5. package/dist/docs/api-reference/components/action-bar-action.md +35 -0
  6. package/dist/docs/api-reference/components/action-bar-group.md +24 -0
  7. package/dist/docs/api-reference/components/action-bar-label.md +25 -0
  8. package/dist/docs/api-reference/components/action-bar-separator.md +16 -0
  9. package/dist/docs/api-reference/components/action-bar.md +32 -0
  10. package/dist/docs/api-reference/components/auto-field.md +63 -0
  11. package/dist/docs/api-reference/components/drawer-item.md +75 -0
  12. package/dist/docs/api-reference/components/drawer.md +29 -0
  13. package/dist/docs/api-reference/components/drop-zone.md +232 -0
  14. package/dist/docs/api-reference/components/field-label.md +138 -0
  15. package/dist/docs/api-reference/components/inline-text-field.md +77 -0
  16. package/dist/docs/api-reference/components/puck-components.md +19 -0
  17. package/dist/docs/api-reference/components/puck-fields.md +39 -0
  18. package/dist/docs/api-reference/components/puck-layout.md +27 -0
  19. package/dist/docs/api-reference/components/puck-outline.md +19 -0
  20. package/dist/docs/api-reference/components/puck-preview.md +39 -0
  21. package/dist/docs/api-reference/components/puck.md +561 -0
  22. package/dist/docs/api-reference/components/render.md +94 -0
  23. package/dist/docs/api-reference/components/rich-text-menu-control.md +87 -0
  24. package/dist/docs/api-reference/components/rich-text-menu-group.md +27 -0
  25. package/dist/docs/api-reference/components/rich-text-menu.md +99 -0
  26. package/dist/docs/api-reference/components.md +32 -0
  27. package/dist/docs/api-reference/configuration/component-config.md +569 -0
  28. package/dist/docs/api-reference/configuration/config.md +108 -0
  29. package/dist/docs/api-reference/configuration.md +4 -0
  30. package/dist/docs/api-reference/data-model/app-state.md +168 -0
  31. package/dist/docs/api-reference/data-model/component-data.md +62 -0
  32. package/dist/docs/api-reference/data-model/data.md +95 -0
  33. package/dist/docs/api-reference/data-model/item-selector.md +34 -0
  34. package/dist/docs/api-reference/data-model/root-data.md +59 -0
  35. package/dist/docs/api-reference/data-model.md +8 -0
  36. package/dist/docs/api-reference/dictionary.md +172 -0
  37. package/dist/docs/api-reference/field-transforms.md +51 -0
  38. package/dist/docs/api-reference/fields/array.md +211 -0
  39. package/dist/docs/api-reference/fields/base.md +96 -0
  40. package/dist/docs/api-reference/fields/custom.md +193 -0
  41. package/dist/docs/api-reference/fields/external.md +413 -0
  42. package/dist/docs/api-reference/fields/number.md +132 -0
  43. package/dist/docs/api-reference/fields/object.md +78 -0
  44. package/dist/docs/api-reference/fields/radio.md +82 -0
  45. package/dist/docs/api-reference/fields/richtext.md +422 -0
  46. package/dist/docs/api-reference/fields/select.md +79 -0
  47. package/dist/docs/api-reference/fields/slot.md +302 -0
  48. package/dist/docs/api-reference/fields/text.md +93 -0
  49. package/dist/docs/api-reference/fields/textarea.md +93 -0
  50. package/dist/docs/api-reference/fields.md +16 -0
  51. package/dist/docs/api-reference/functions/migrate.md +204 -0
  52. package/dist/docs/api-reference/functions/register-overlay-portal.md +45 -0
  53. package/dist/docs/api-reference/functions/resolve-all-data.md +27 -0
  54. package/dist/docs/api-reference/functions/set-deep.md +55 -0
  55. package/dist/docs/api-reference/functions/transform-props.md +51 -0
  56. package/dist/docs/api-reference/functions/use-get-puck.md +24 -0
  57. package/dist/docs/api-reference/functions/use-puck.md +43 -0
  58. package/dist/docs/api-reference/functions/walk-tree.md +88 -0
  59. package/dist/docs/api-reference/functions.md +8 -0
  60. package/dist/docs/api-reference/overrides/action-bar.md +35 -0
  61. package/dist/docs/api-reference/overrides/component-overlay.md +41 -0
  62. package/dist/docs/api-reference/overrides/drawer-item.md +24 -0
  63. package/dist/docs/api-reference/overrides/drawer.md +19 -0
  64. package/dist/docs/api-reference/overrides/field-label.md +18 -0
  65. package/dist/docs/api-reference/overrides/field-types.md +51 -0
  66. package/dist/docs/api-reference/overrides/fields.md +19 -0
  67. package/dist/docs/api-reference/overrides/header-actions.md +24 -0
  68. package/dist/docs/api-reference/overrides/header.md +29 -0
  69. package/dist/docs/api-reference/overrides/iframe.md +32 -0
  70. package/dist/docs/api-reference/overrides/outline.md +19 -0
  71. package/dist/docs/api-reference/overrides/preview.md +19 -0
  72. package/dist/docs/api-reference/overrides/puck.md +19 -0
  73. package/dist/docs/api-reference/overrides.md +28 -0
  74. package/dist/docs/api-reference/permissions.md +55 -0
  75. package/dist/docs/api-reference/plugin.md +112 -0
  76. package/dist/docs/api-reference/plugins/blocks-plugin.md +57 -0
  77. package/dist/docs/api-reference/plugins/fields-plugin.md +68 -0
  78. package/dist/docs/api-reference/plugins/legacy-side-bar-plugin.md +54 -0
  79. package/dist/docs/api-reference/plugins/outline-plugin.md +57 -0
  80. package/dist/docs/api-reference/puck-api.md +278 -0
  81. package/dist/docs/api-reference/theming/action-bar.md +32 -0
  82. package/dist/docs/api-reference/theming/button.md +65 -0
  83. package/dist/docs/api-reference/theming/canvas.md +20 -0
  84. package/dist/docs/api-reference/theming/computed-values.md +194 -0
  85. package/dist/docs/api-reference/theming/drawer.md +34 -0
  86. package/dist/docs/api-reference/theming/fields.md +70 -0
  87. package/dist/docs/api-reference/theming/global.md +127 -0
  88. package/dist/docs/api-reference/theming/header.md +19 -0
  89. package/dist/docs/api-reference/theming/icon-button.md +28 -0
  90. package/dist/docs/api-reference/theming/outline.md +35 -0
  91. package/dist/docs/api-reference/theming/plugin-bar.md +24 -0
  92. package/dist/docs/api-reference/theming/sidebar.md +19 -0
  93. package/dist/docs/api-reference/theming/slot.md +27 -0
  94. package/dist/docs/cli.md +284 -0
  95. package/dist/docs/extending-puck/composition.md +54 -0
  96. package/dist/docs/extending-puck/custom-fields.md +133 -0
  97. package/dist/docs/extending-puck/field-transforms.md +89 -0
  98. package/dist/docs/extending-puck/internal-puck-api.md +96 -0
  99. package/dist/docs/extending-puck/plugins.md +159 -0
  100. package/dist/docs/extending-puck/theming.md +88 -0
  101. package/dist/docs/extending-puck/ui-overrides.md +134 -0
  102. package/dist/docs/getting-started.md +68 -0
  103. package/dist/docs/guides/migrations/dropzones-to-slots.md +138 -0
  104. package/dist/docs/index.json +466 -0
  105. package/dist/docs/index.md +37 -0
  106. package/dist/docs/integrating-puck/categories.md +92 -0
  107. package/dist/docs/integrating-puck/component-configuration.md +159 -0
  108. package/dist/docs/integrating-puck/data-migration.md +86 -0
  109. package/dist/docs/integrating-puck/dynamic-fields.md +86 -0
  110. package/dist/docs/integrating-puck/dynamic-props.md +137 -0
  111. package/dist/docs/integrating-puck/external-data-sources.md +149 -0
  112. package/dist/docs/integrating-puck/feature-toggling.md +121 -0
  113. package/dist/docs/integrating-puck/localization.md +228 -0
  114. package/dist/docs/integrating-puck/multi-column-layouts.md +226 -0
  115. package/dist/docs/integrating-puck/overlay-portals.md +25 -0
  116. package/dist/docs/integrating-puck/rich-text-editing.md +230 -0
  117. package/dist/docs/integrating-puck/root-configuration.md +171 -0
  118. package/dist/docs/integrating-puck/server-components.md +199 -0
  119. package/dist/docs/integrating-puck/styling.md +117 -0
  120. package/dist/docs/integrating-puck/viewports.md +75 -0
  121. package/dist/templates/astro/README.md +52 -0
  122. package/dist/templates/astro/_gitignore +24 -0
  123. package/dist/templates/astro/astro.config.mjs +14 -0
  124. package/dist/templates/astro/database.json +1 -0
  125. package/dist/templates/astro/package.json +25 -0
  126. package/dist/templates/astro/public/favicon.svg +9 -0
  127. package/dist/templates/astro/src/lib/pages.ts +21 -0
  128. package/dist/templates/astro/src/lib/resolve-puck-path.ts +19 -0
  129. package/dist/templates/astro/src/pages/[...puckPath].astro +25 -0
  130. package/dist/templates/astro/src/pages/api/pages.ts +18 -0
  131. package/dist/templates/astro/src/puck/editor.tsx +32 -0
  132. package/dist/templates/astro/src/puck/pages.ts +15 -0
  133. package/dist/templates/astro/src/puck/render.tsx +9 -0
  134. package/dist/templates/astro/src/puck.config.tsx +23 -0
  135. package/dist/templates/astro/tsconfig.json +14 -0
  136. package/dist/templates/astro-ai/README.md +64 -0
  137. package/dist/templates/astro-ai/_gitignore +24 -0
  138. package/dist/templates/astro-ai/astro.config.mjs +21 -0
  139. package/dist/templates/astro-ai/database.json +1 -0
  140. package/dist/templates/astro-ai/package.json +27 -0
  141. package/dist/templates/astro-ai/public/favicon.svg +9 -0
  142. package/dist/templates/astro-ai/src/lib/pages.ts +21 -0
  143. package/dist/templates/astro-ai/src/lib/resolve-puck-path.ts +19 -0
  144. package/dist/templates/astro-ai/src/pages/[...puckPath].astro +25 -0
  145. package/dist/templates/astro-ai/src/pages/api/pages.ts +18 -0
  146. package/dist/templates/astro-ai/src/pages/api/puck/[...all].ts +36 -0
  147. package/dist/templates/astro-ai/src/puck/editor.tsx +53 -0
  148. package/dist/templates/astro-ai/src/puck/pages.ts +15 -0
  149. package/dist/templates/astro-ai/src/puck/render.tsx +10 -0
  150. package/dist/templates/astro-ai/src/puck.config.tsx +23 -0
  151. package/dist/templates/astro-ai/tsconfig.json +14 -0
  152. package/dist/templates/express/README.md +66 -0
  153. package/dist/templates/express/_gitignore +16 -0
  154. package/dist/templates/express/database.json +1 -0
  155. package/dist/templates/express/package.json +20 -0
  156. package/dist/templates/express/src/index.ts +15 -0
  157. package/dist/templates/express/src/puck/pages.ts +44 -0
  158. package/dist/templates/express/tsconfig.json +12 -0
  159. package/dist/templates/express-ai/README.md +81 -0
  160. package/dist/templates/express-ai/_gitignore +16 -0
  161. package/dist/templates/express-ai/database.json +1 -0
  162. package/dist/templates/express-ai/package.json +22 -0
  163. package/dist/templates/express-ai/src/index.ts +17 -0
  164. package/dist/templates/express-ai/src/puck/cloud.ts +71 -0
  165. package/dist/templates/express-ai/src/puck/pages.ts +44 -0
  166. package/dist/templates/express-ai/tsconfig.json +12 -0
  167. package/dist/templates/hono/README.md +66 -0
  168. package/dist/templates/hono/_gitignore +32 -0
  169. package/dist/templates/hono/database.json +1 -0
  170. package/dist/templates/hono/package.json +20 -0
  171. package/dist/templates/hono/src/index.ts +21 -0
  172. package/dist/templates/hono/src/puck/pages.ts +32 -0
  173. package/dist/templates/hono/tsconfig.json +13 -0
  174. package/dist/templates/hono-ai/README.md +81 -0
  175. package/dist/templates/hono-ai/_gitignore +32 -0
  176. package/dist/templates/hono-ai/database.json +1 -0
  177. package/dist/templates/hono-ai/package.json +22 -0
  178. package/dist/templates/hono-ai/src/index.ts +23 -0
  179. package/dist/templates/hono-ai/src/puck/cloud.ts +30 -0
  180. package/dist/templates/hono-ai/src/puck/pages.ts +32 -0
  181. package/dist/templates/hono-ai/tsconfig.json +13 -0
  182. package/dist/templates/manifest.json +7 -0
  183. package/dist/templates/next/README.md +112 -0
  184. package/dist/templates/next/_gitignore +35 -0
  185. package/dist/templates/next/app/[...puckPath]/client.tsx +9 -0
  186. package/dist/templates/next/app/[...puckPath]/page.tsx +49 -0
  187. package/dist/templates/next/app/favicon.ico +0 -0
  188. package/dist/templates/next/app/layout.tsx +13 -0
  189. package/dist/templates/next/app/page.tsx +1 -0
  190. package/dist/templates/next/app/puck/[...puckPath]/client.tsx +20 -0
  191. package/dist/templates/next/app/puck/[...puckPath]/page.tsx +55 -0
  192. package/dist/templates/next/app/puck/api/route.ts +25 -0
  193. package/dist/templates/next/app/puck/page.tsx +3 -0
  194. package/dist/templates/next/app/styles.css +3 -0
  195. package/dist/templates/next/database.json +1 -0
  196. package/dist/templates/next/lib/get-page.ts +11 -0
  197. package/dist/templates/next/next.config.js +3 -0
  198. package/dist/templates/next/package.json +25 -0
  199. package/dist/templates/next/proxy.ts +27 -0
  200. package/dist/templates/next/puck.config.tsx +25 -0
  201. package/dist/templates/next/tsconfig/base.json +20 -0
  202. package/dist/templates/next/tsconfig/nextjs.json +21 -0
  203. package/dist/templates/next/tsconfig.json +8 -0
  204. package/dist/templates/next-ai/README.md +169 -0
  205. package/dist/templates/next-ai/_gitignore +35 -0
  206. package/dist/templates/next-ai/app/[...puckPath]/client.tsx +12 -0
  207. package/dist/templates/next-ai/app/[...puckPath]/page.tsx +49 -0
  208. package/dist/templates/next-ai/app/api/pages/route.ts +26 -0
  209. package/dist/templates/next-ai/app/api/puck/[...all]/route.ts +31 -0
  210. package/dist/templates/next-ai/app/layout.tsx +13 -0
  211. package/dist/templates/next-ai/app/page.tsx +1 -0
  212. package/dist/templates/next-ai/app/puck/[...puckPath]/client.tsx +38 -0
  213. package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +57 -0
  214. package/dist/templates/next-ai/app/puck/page.tsx +3 -0
  215. package/dist/templates/next-ai/app/styles.css +3 -0
  216. package/dist/templates/next-ai/database.json +1 -0
  217. package/dist/templates/next-ai/lib/get-page.ts +11 -0
  218. package/dist/templates/next-ai/next.config.js +3 -0
  219. package/dist/templates/next-ai/package.json +27 -0
  220. package/dist/templates/next-ai/proxy.ts +27 -0
  221. package/dist/templates/next-ai/public/favicon.ico +0 -0
  222. package/dist/templates/next-ai/puck.config.tsx +25 -0
  223. package/dist/templates/next-ai/tsconfig/base.json +20 -0
  224. package/dist/templates/next-ai/tsconfig/nextjs.json +21 -0
  225. package/dist/templates/next-ai/tsconfig.json +8 -0
  226. package/dist/templates/react-router/README.md +113 -0
  227. package/dist/templates/react-router/_gitignore +6 -0
  228. package/dist/templates/react-router/app/components/puck-render.tsx +8 -0
  229. package/dist/templates/react-router/app/lib/pages.server.ts +29 -0
  230. package/dist/templates/react-router/app/lib/resolve-puck-path.server.ts +19 -0
  231. package/dist/templates/react-router/app/root.tsx +65 -0
  232. package/dist/templates/react-router/app/routes/_index.tsx +31 -0
  233. package/dist/templates/react-router/app/routes/puck-splat.tsx +95 -0
  234. package/dist/templates/react-router/app/routes.ts +7 -0
  235. package/dist/templates/react-router/database.json +1 -0
  236. package/dist/templates/react-router/package.json +33 -0
  237. package/dist/templates/react-router/public/favicon.ico +0 -0
  238. package/dist/templates/react-router/puck.config.tsx +23 -0
  239. package/dist/templates/react-router/react-router.config.ts +7 -0
  240. package/dist/templates/react-router/tsconfig.json +29 -0
  241. package/dist/templates/react-router/vite.config.ts +10 -0
  242. package/dist/templates/react-router-ai/README.md +172 -0
  243. package/dist/templates/react-router-ai/_gitignore +6 -0
  244. package/dist/templates/react-router-ai/app/components/puck-render.tsx +11 -0
  245. package/dist/templates/react-router-ai/app/lib/pages.server.ts +29 -0
  246. package/dist/templates/react-router-ai/app/lib/resolve-puck-path.server.ts +19 -0
  247. package/dist/templates/react-router-ai/app/root.tsx +65 -0
  248. package/dist/templates/react-router-ai/app/routes/_index.tsx +31 -0
  249. package/dist/templates/react-router-ai/app/routes/api.puck.ts +34 -0
  250. package/dist/templates/react-router-ai/app/routes/puck-splat.tsx +119 -0
  251. package/dist/templates/react-router-ai/app/routes.ts +8 -0
  252. package/dist/templates/react-router-ai/database.json +1 -0
  253. package/dist/templates/react-router-ai/package.json +35 -0
  254. package/dist/templates/react-router-ai/public/favicon.ico +0 -0
  255. package/dist/templates/react-router-ai/puck.config.tsx +25 -0
  256. package/dist/templates/react-router-ai/react-router.config.ts +7 -0
  257. package/dist/templates/react-router-ai/tsconfig.json +29 -0
  258. package/dist/templates/react-router-ai/vite.config.ts +10 -0
  259. package/dist/templates/tanstack-start/README.md +113 -0
  260. package/dist/templates/tanstack-start/_gitignore +12 -0
  261. package/dist/templates/tanstack-start/database.json +1 -0
  262. package/dist/templates/tanstack-start/package.json +26 -0
  263. package/dist/templates/tanstack-start/puck.config.tsx +23 -0
  264. package/dist/templates/tanstack-start/src/components/puck-render.tsx +8 -0
  265. package/dist/templates/tanstack-start/src/lib/pages.server.ts +26 -0
  266. package/dist/templates/tanstack-start/src/lib/pages.ts +39 -0
  267. package/dist/templates/tanstack-start/src/lib/resolve-puck-path.ts +19 -0
  268. package/dist/templates/tanstack-start/src/routeTree.gen.ts +86 -0
  269. package/dist/templates/tanstack-start/src/router.tsx +19 -0
  270. package/dist/templates/tanstack-start/src/routes/$.tsx +41 -0
  271. package/dist/templates/tanstack-start/src/routes/__root.tsx +42 -0
  272. package/dist/templates/tanstack-start/src/routes/index.tsx +18 -0
  273. package/dist/templates/tanstack-start/src/styles.css +13 -0
  274. package/dist/templates/tanstack-start/tsconfig.json +24 -0
  275. package/dist/templates/tanstack-start/vite.config.ts +15 -0
  276. package/dist/templates/tanstack-start-ai/README.md +171 -0
  277. package/dist/templates/tanstack-start-ai/_gitignore +12 -0
  278. package/dist/templates/tanstack-start-ai/database.json +1 -0
  279. package/dist/templates/tanstack-start-ai/package.json +28 -0
  280. package/dist/templates/tanstack-start-ai/puck.config.tsx +23 -0
  281. package/dist/templates/tanstack-start-ai/src/components/puck-render.tsx +11 -0
  282. package/dist/templates/tanstack-start-ai/src/lib/pages.server.ts +26 -0
  283. package/dist/templates/tanstack-start-ai/src/lib/pages.ts +39 -0
  284. package/dist/templates/tanstack-start-ai/src/lib/resolve-puck-path.ts +19 -0
  285. package/dist/templates/tanstack-start-ai/src/routeTree.gen.ts +104 -0
  286. package/dist/templates/tanstack-start-ai/src/router.tsx +19 -0
  287. package/dist/templates/tanstack-start-ai/src/routes/$.tsx +73 -0
  288. package/dist/templates/tanstack-start-ai/src/routes/__root.tsx +42 -0
  289. package/dist/templates/tanstack-start-ai/src/routes/api/puck/$.ts +39 -0
  290. package/dist/templates/tanstack-start-ai/src/routes/index.tsx +18 -0
  291. package/dist/templates/tanstack-start-ai/src/styles.css +13 -0
  292. package/dist/templates/tanstack-start-ai/tsconfig.json +24 -0
  293. package/dist/templates/tanstack-start-ai/vite.config.ts +15 -0
  294. package/dist/templates/vinext/README.md +112 -0
  295. package/dist/templates/vinext/_gitignore +33 -0
  296. package/dist/templates/vinext/app/[...puckPath]/client.tsx +9 -0
  297. package/dist/templates/vinext/app/[...puckPath]/page.tsx +49 -0
  298. package/dist/templates/vinext/app/favicon.ico +0 -0
  299. package/dist/templates/vinext/app/layout.tsx +13 -0
  300. package/dist/templates/vinext/app/page.tsx +1 -0
  301. package/dist/templates/vinext/app/puck/[...puckPath]/client.tsx +20 -0
  302. package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +55 -0
  303. package/dist/templates/vinext/app/puck/api/route.ts +25 -0
  304. package/dist/templates/vinext/app/puck/page.tsx +3 -0
  305. package/dist/templates/vinext/app/styles.css +3 -0
  306. package/dist/templates/vinext/database.json +1 -0
  307. package/dist/templates/vinext/lib/get-page.ts +11 -0
  308. package/dist/templates/vinext/package.json +30 -0
  309. package/dist/templates/vinext/proxy.ts +27 -0
  310. package/dist/templates/vinext/puck.config.tsx +25 -0
  311. package/dist/templates/vinext/tsconfig.json +30 -0
  312. package/dist/templates/vinext/vite.config.ts +6 -0
  313. package/dist/templates/vinext-ai/README.md +169 -0
  314. package/dist/templates/vinext-ai/_gitignore +33 -0
  315. package/dist/templates/vinext-ai/app/[...puckPath]/client.tsx +12 -0
  316. package/dist/templates/vinext-ai/app/[...puckPath]/page.tsx +49 -0
  317. package/dist/templates/vinext-ai/app/api/pages/route.ts +26 -0
  318. package/dist/templates/vinext-ai/app/api/puck/[...all]/route.ts +31 -0
  319. package/dist/templates/vinext-ai/app/layout.tsx +13 -0
  320. package/dist/templates/vinext-ai/app/page.tsx +1 -0
  321. package/dist/templates/vinext-ai/app/puck/[...puckPath]/client.tsx +38 -0
  322. package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +57 -0
  323. package/dist/templates/vinext-ai/app/puck/page.tsx +3 -0
  324. package/dist/templates/vinext-ai/app/styles.css +3 -0
  325. package/dist/templates/vinext-ai/database.json +1 -0
  326. package/dist/templates/vinext-ai/lib/get-page.ts +11 -0
  327. package/dist/templates/vinext-ai/package.json +32 -0
  328. package/dist/templates/vinext-ai/proxy.ts +27 -0
  329. package/dist/templates/vinext-ai/public/favicon.ico +0 -0
  330. package/dist/templates/vinext-ai/puck.config.tsx +25 -0
  331. package/dist/templates/vinext-ai/tsconfig.json +30 -0
  332. package/dist/templates/vinext-ai/vite.config.ts +9 -0
  333. package/dist/templates/vite/README.md +56 -0
  334. package/dist/templates/vite/_gitignore +24 -0
  335. package/dist/templates/vite/database.json +1 -0
  336. package/dist/templates/vite/index.html +12 -0
  337. package/dist/templates/vite/package.json +29 -0
  338. package/dist/templates/vite/server/index.ts +13 -0
  339. package/dist/templates/vite/server/prod.ts +18 -0
  340. package/dist/templates/vite/server/puck/pages.ts +32 -0
  341. package/dist/templates/vite/src/App.tsx +11 -0
  342. package/dist/templates/vite/src/main.tsx +12 -0
  343. package/dist/templates/vite/src/puck/editor.tsx +28 -0
  344. package/dist/templates/vite/src/puck/page.tsx +27 -0
  345. package/dist/templates/vite/src/puck/pages.ts +15 -0
  346. package/dist/templates/vite/src/puck/root.tsx +27 -0
  347. package/dist/templates/vite/src/puck.config.tsx +23 -0
  348. package/dist/templates/vite/tsconfig.app.json +26 -0
  349. package/dist/templates/vite/tsconfig.json +7 -0
  350. package/dist/templates/vite/tsconfig.node.json +23 -0
  351. package/dist/templates/vite/vite.config.ts +14 -0
  352. package/dist/templates/vite-ai/README.md +67 -0
  353. package/dist/templates/vite-ai/_gitignore +24 -0
  354. package/dist/templates/vite-ai/database.json +1 -0
  355. package/dist/templates/vite-ai/index.html +12 -0
  356. package/dist/templates/vite-ai/package.json +31 -0
  357. package/dist/templates/vite-ai/server/index.ts +15 -0
  358. package/dist/templates/vite-ai/server/prod.ts +18 -0
  359. package/dist/templates/vite-ai/server/puck/cloud.ts +30 -0
  360. package/dist/templates/vite-ai/server/puck/pages.ts +32 -0
  361. package/dist/templates/vite-ai/src/App.tsx +11 -0
  362. package/dist/templates/vite-ai/src/main.tsx +12 -0
  363. package/dist/templates/vite-ai/src/puck/editor.tsx +49 -0
  364. package/dist/templates/vite-ai/src/puck/page.tsx +28 -0
  365. package/dist/templates/vite-ai/src/puck/pages.ts +15 -0
  366. package/dist/templates/vite-ai/src/puck/root.tsx +27 -0
  367. package/dist/templates/vite-ai/src/puck.config.tsx +23 -0
  368. package/dist/templates/vite-ai/tsconfig.app.json +26 -0
  369. package/dist/templates/vite-ai/tsconfig.json +7 -0
  370. package/dist/templates/vite-ai/tsconfig.node.json +23 -0
  371. package/dist/templates/vite-ai/vite.config.ts +14 -0
  372. package/package.json +52 -0
@@ -0,0 +1,284 @@
1
+ # CLI
2
+
3
+ The Puck CLI sets up Puck and [Puck Cloud](https://cloud.puckeditor.com) in a new or existing app. It's built for coding agents, and works interactively for humans.
4
+
5
+ ```sh
6
+ npx @puckeditor/cli init
7
+ ```
8
+
9
+ `init` inspects your project and makes the smallest set of changes needed to reach a working Puck app, with Puck AI if you choose it:
10
+
11
+ - **No app yet**: creates a Next.js, React Router, TanStack Start, vinext, Vite or Astro app, or a Hono or Express server, from the Puck [recipes](https://github.com/puckeditor/puck#recipes)
12
+ - **App without Puck**: installs `@puckeditor/core` and adds an editor at `/edit`
13
+ - **Puck without Puck AI** (when you choose it): installs `@puckeditor/cloud-client` and `@puckeditor/plugin-ai`, adds the `/api/puck` route and the Puck AI plugin, and connects your Puck Cloud account
14
+ - **Already set up**: verifies the setup and changes nothing
15
+
16
+ With Puck AI, the only manual step is logging in to Puck Cloud and approving the connection in your browser. When it's done, the CLI starts your dev server and opens the editor.
17
+
18
+ Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) are optional. Each uses Puck Cloud, so choosing any of them sets up Puck Cloud too. `init` asks which to include, with all three selected. To choose up front, pass `--ai`, `--pages` or `--auth` to include only those, `--no-ai`, `--no-pages` or `--no-auth` to include all but those, or `--editor-only` for none.
19
+
20
+ ## Supported projects
21
+
22
+ - Next.js 15+ using the App Router (`app/` or `src/app/`)
23
+ - React Router 7+ in framework mode. New apps use React Router 8, or React Router 7 on Node.js older than 22.22, which React Router 8 requires
24
+ - [TanStack Start](https://tanstack.com/start) 1.132+
25
+ - [vinext](https://github.com/cloudflare/vinext) 1+ using the App Router
26
+ - [Vite](https://vite.dev) 6+ React apps (see [Vite and Astro](#vite-and-astro))
27
+ - [Astro](https://astro.build) 7+ (see [Vite and Astro](#vite-and-astro))
28
+ - [Hono](https://hono.dev) 4+ and [Express](https://expressjs.com) 4.16+ servers (see [Servers](#servers))
29
+ - npm, pnpm, Yarn and Bun, including workspaces
30
+ - TypeScript projects
31
+
32
+ Run `npx @puckeditor/cli frameworks` to see what the CLI sets up for each framework. Older versions fail with `PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION`.
33
+
34
+ When the CLI can't safely change something, like an existing `middleware.ts`, it leaves the file alone and tells you exactly what to add.
35
+
36
+ ## Vite and Astro
37
+
38
+ A Vite app, or an Astro site without a server adapter, has nowhere to save pages or run Puck Cloud. The CLI asks where that server comes from. Agents get a `choose_backend` action; pass `--backend` to choose up front:
39
+
40
+ - `--backend add`: in Vite, adds a Hono server in `server/`, run by Vite in development with `@hono/vite-dev-server` and by `npm start` in production. In Astro, runs `astro add node` so pages and API routes are served on demand
41
+ - `--backend external --backend-url <url>`: proxies `/api` to a server that runs elsewhere, e.g. a [Hono or Express server](#servers) set up by the CLI. Puck Cloud and `PUCK_API_KEY` live on that server
42
+ - `--backend none`: saves pages in the browser's `localStorage`. Puck AI isn't available without a server
43
+
44
+ In Vite, the editor opens at any URL ending in `/edit`: `<PuckRoot>` wraps your app in `src/main.tsx` and renders the editor instead. Render published pages with `<PuckPage path={...} />` wherever your app renders pages.
45
+
46
+ In Astro with an adapter, `src/pages/[...puckPath].astro` renders the editor at `/edit` URLs and published pages everywhere else, on the server. Without one, the editor is a static page at `/edit?path=/your/page`. The CLI runs `astro add react` when React isn't set up yet.
47
+
48
+ ## Servers
49
+
50
+ In a Hono or Express project, the CLI sets up the APIs a Puck editor in another app talks to:
51
+
52
+ - `/api/pages`: loads (`GET ?path=/about`) and saves (`POST { path, data }`) pages, in `src/puck/pages.ts`
53
+ - `/api/puck/*`: the Puck Cloud route for Puck AI, in `src/puck/cloud.ts`, when you choose Puck AI
54
+
55
+ With [Puck Pages](#puck-pages), `/api/pages` serves pages published in Puck Cloud instead, and only loads them.
56
+
57
+ It mounts both on your app before it starts serving, so your own middleware runs first. Node doesn't load `.env` files, so the CLI adds `--env-file-if-exists=.env.local` to a `tsx` or `node` dev script. Bun loads `.env.local` itself. On Cloudflare Workers, put `PUCK_API_KEY` in `.dev.vars` instead.
58
+
59
+ Add the Puck AI plugin in the app with the editor. If that app runs on another origin, proxy `/api` to the server in development, or pass `host` to `createAiPlugin`.
60
+
61
+ ## For coding agents
62
+
63
+ Run with `--yes --json`. The CLI never prompts, and prints exactly one JSON document to stdout.
64
+
65
+ ```sh
66
+ npx @puckeditor/cli init --yes --json
67
+ ```
68
+
69
+ When `status` is `action_required`, nothing has been changed yet. Show each entry in `actions` to the developer, then run its `rerun` command. Without any of those flags, the first run returns a `choose_capabilities` action, so the developer can choose which of Puck AI, Puck Pages and Puck Auth to add. With `--ai`, the first run asks the developer to log in:
70
+
71
+ ```json
72
+ {
73
+ "status": "action_required",
74
+ "message": "Puck Cloud login required. No changes have been made yet.",
75
+ "actions": [
76
+ {
77
+ "type": "browser_login",
78
+ "url": "https://cloud.puckeditor.com/cli/connect#code=BCDF-GHJK",
79
+ "userCode": "BCDF-GHJK",
80
+ "rerun": "npx @puckeditor/cli init --yes --json --ai"
81
+ }
82
+ ]
83
+ }
84
+ ```
85
+
86
+ After the developer approves, the same command completes the setup:
87
+
88
+ ```json
89
+ {
90
+ "status": "success",
91
+ "project": { "framework": "next", "packageManager": "pnpm" },
92
+ "puck": { "installed": true, "configured": true },
93
+ "cloud": { "configured": true, "verified": "remote" },
94
+ "ai": { "installed": true, "configured": true },
95
+ "filesModified": [".env.local", "app/api/puck/[...all]/route.ts"]
96
+ }
97
+ ```
98
+
99
+ Start with `npx @puckeditor/cli status --json` to see what's already set up and which command to run next.
100
+
101
+ ### Statuses
102
+
103
+ | Status | Meaning |
104
+ | ----------------- | --------------------------------------------------------------------------------------- |
105
+ | `success` | The project is set up. `changed` is `false` if there was nothing to do. |
106
+ | `action_required` | Input or approval is needed. Nothing was changed. Complete `actions`, then run `rerun`. |
107
+ | `partial` | Changes were applied, but some `actions` must be completed by hand. |
108
+ | `error` | Something went wrong. See `error.code` and `error.message`. |
109
+
110
+ ### Actions
111
+
112
+ | Type | What to do |
113
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
114
+ | `browser_login` | Ask the developer to open `url`, confirm `userCode` and approve |
115
+ | `provide_api_key` | Ask for a Puck API key, then re-run with `PUCK_API_KEY` set |
116
+ | `confirm_plan` | Review `plan.steps`, then re-run with `--yes` |
117
+ | `choose_capabilities` | Ask the developer which of `choices` to add, then re-run `init` with each one's flag, or `none` (`--editor-only`) for none |
118
+ | `choose_backend` | Ask the developer, then re-run with `--backend add`, `--backend external --backend-url <url>` or `--backend none` |
119
+ | `choose_framework` | Re-run `init` with `--framework` and one of `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
120
+ | `provide_app_name` | Re-run `init` with `--name <name>` |
121
+ | `choose_workspace_package` | Re-run with `--workspace <dir>` for one of `choices` |
122
+ | `manual_edit` | Apply `snippet` to `file` as described in `instructions` |
123
+ | `set_environment_variable` | Set `PUCK_API_KEY` wherever the app runs |
124
+
125
+ ### Exit codes
126
+
127
+ | Code | Meaning |
128
+ | ---- | ----------------------------------------------- |
129
+ | 0 | Success |
130
+ | 2 | Invalid arguments or API key |
131
+ | 3 | Unsupported or ambiguous project |
132
+ | 4 | File conflict |
133
+ | 5 | Package manager failure |
134
+ | 6 | `doctor` found problems |
135
+ | 7 | Puck Cloud couldn't complete a login or request |
136
+ | 10 | Action required |
137
+ | 11 | Partially set up |
138
+
139
+ ### Reading the docs
140
+
141
+ The CLI includes these docs as markdown, matching its release. Use the version of the CLI that matches the project's `@puckeditor/core`:
142
+
143
+ ```sh
144
+ npx @puckeditor/cli docs ls # every page
145
+ npx @puckeditor/cli docs find "dynamic fields" # find pages by title or heading
146
+ npx @puckeditor/cli docs grep resolveData # search page content
147
+ npx @puckeditor/cli docs cat api-reference/fields/text
148
+ ```
149
+
150
+ The latest docs are indexed at [llms.txt](https://puckeditor.com/llms.txt), and any page is available as markdown by adding `.md` to its URL. Agents with skill support can also install the [Puck skill](https://github.com/puckeditor/skills):
151
+
152
+ ```sh
153
+ npx skills add puckeditor/skills --skill puck
154
+ ```
155
+
156
+ ## Commands
157
+
158
+ | Command | Description |
159
+ | --------------------- | ------------------------------------------------------------------------------ |
160
+ | `init` | Set up Puck, optionally with Puck AI, creating an app if needed |
161
+ | `add editor` | Add the Puck editor |
162
+ | `add cloud` | Connect Puck Cloud (adds the editor first if needed) |
163
+ | `add ai` | Add the Puck AI plugin (adds Puck Cloud first if needed) |
164
+ | `add pages` | Store and publish pages in Puck Cloud (adds Puck Cloud first if needed) |
165
+ | `add auth` | Require Sign in with Puck to edit (adds Puck Cloud first if needed) |
166
+ | `pages import <file>` | Publish pages from a JSON file to Puck Cloud |
167
+ | `connect [branch]` | Log in to Puck Cloud again and replace `PUCK_API_KEY`, optionally for a branch |
168
+ | `status` | Show what's installed and configured |
169
+ | `doctor` | Diagnose problems and suggest fixes. Never makes changes |
170
+ | `frameworks` | Show the supported frameworks and versions |
171
+ | `docs` | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
172
+ | `telemetry` | Show or change anonymous usage data collection |
173
+
174
+ ## Flags
175
+
176
+ | Flag | Description |
177
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
178
+ | `--json` | Machine-readable output |
179
+ | `--yes`, `-y` | Apply the plan without prompting |
180
+ | `--dry-run` | Show the plan without changing anything or logging in |
181
+ | `--cwd <path>` | Run against another directory |
182
+ | `--workspace <name\|dir>` | Choose an app when running from a monorepo root |
183
+ | `--api-key <key>` | Use an existing API key instead of logging in |
184
+ | `--no-env-write` | Don't write `PUCK_API_KEY` to a file |
185
+ | `--ai`, `--pages`, `--auth` | Include only these of Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) (`init`) |
186
+ | `--no-ai`, `--no-pages`, `--no-auth` | Include all of them except these (`init`) |
187
+ | `--editor-only` | Include none of them (`init`) |
188
+ | `--canary` | Install the latest canaries of `@puckeditor/core`, `cloud-client` and the plugins, pinned to exact versions (`init` and `add`). `PUCK_CANARY=1` does the same. Private packages are read with your npm login |
189
+ | `--backend <choice>` | Where a Vite app's server comes from: `add`, `external` or `none` |
190
+ | `--backend-url <url>` | The server for `--backend external` |
191
+ | `--wait` | Wait for login approval instead of returning `action_required` |
192
+ | `--framework <name>` | Framework for a new app: `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
193
+ | `--name <name>` | Directory for a new app |
194
+ | `--package-manager <name>` | Override the detected package manager |
195
+ | `--offline` | Skip the Puck Cloud connection check (`doctor`) |
196
+
197
+ ## API keys
198
+
199
+ The CLI writes `PUCK_API_KEY` to `.env.local`, and makes sure it's ignored by git. If a key already exists in `.env.development.local`, it's updated there instead. Keys are never written to `.env`, and never printed.
200
+
201
+ To use an existing key, prefer the environment over `--api-key`, which is visible in your shell history:
202
+
203
+ ```sh
204
+ PUCK_API_KEY=your-key npx @puckeditor/cli add cloud --yes
205
+ ```
206
+
207
+ To log in again, for example to replace a revoked key, run `connect`. It always starts a new login and replaces the existing key, without changing any code:
208
+
209
+ ```sh
210
+ npx @puckeditor/cli connect
211
+ ```
212
+
213
+ Each key is for one branch of a Puck Cloud project. When you approve the login, you choose the project and branch, which defaults to the project's default branch. To connect to another branch, for example for a preview deployment, name it:
214
+
215
+ ```sh
216
+ npx @puckeditor/cli connect feature/new-hero
217
+ ```
218
+
219
+ Puck Cloud preselects that branch, or offers to create it from the default branch.
220
+
221
+ Remember to set `PUCK_API_KEY` in your production environment too. `react-router-serve` and Cloudflare Workers don't load `.env` files; on Workers, use `wrangler secret put PUCK_API_KEY`.
222
+
223
+ The `/api/puck` route and the editor are public by default. Add [Puck Auth](#puck-auth), or your own authentication, before deploying.
224
+
225
+ ## Puck AI
226
+
227
+ `init` and `add ai` add the Puck AI plugin to the editor, allow design mode in the `/api/puck` route, and wrap your config with `withDynamicConfig` so components designed by Puck AI render on your pages. If your editor has been customised, the CLI leaves it alone and prints the code to add.
228
+
229
+ ## Puck Pages
230
+
231
+ `add pages`, or `init --pages`, stores pages in Puck Cloud with the [Pages plugin](https://puckeditor.com/docs/pages/overview), which adds page management, drafts, publishing and version history to the editor:
232
+
233
+ - The editor opens at `/puck`, with the page to edit in the `path` query parameter, e.g. `/puck?path=/about`. URLs ending in `/edit` redirect there
234
+ - Published pages are rendered from Puck Cloud with `getPage` from `@puckeditor/cloud-client`. In Vite apps and on [servers](#servers), `/api/pages` serves them read-only
235
+ - `@puckeditor/cloud-client` is updated to a version with Puck Pages, and the `/api/puck` route gets the `authenticate` option it requires
236
+
237
+ Pages in `database.json`, or wherever your app saved them, aren't moved automatically. Import them with `pages import`, then delete the old routes.
238
+
239
+ Until you add [Puck Auth](#puck-auth), anyone who can reach `/api/puck` can edit, publish and delete pages using your API key.
240
+
241
+ ### Importing pages
242
+
243
+ ```sh
244
+ npx @puckeditor/cli pages import database.json
245
+ ```
246
+
247
+ `pages import` publishes a JSON object of Puck data keyed by route, like a recipe's `database.json`. Pages that already exist in Puck Cloud are kept. It uses `--api-key`, `PUCK_API_KEY` in the environment, or the key in the env files where it runs, so run it from your app. The API key decides which project and branch the pages go to.
248
+
249
+ Agents pass `--yes --json`. If Puck Cloud fails part way, the status is `partial` and `pagesImport.notImported` lists the routes left. Run the command again to import them.
250
+
251
+ ## Puck Auth
252
+
253
+ `add auth`, or `init --auth`, requires [Sign in with Puck](https://puckeditor.com/docs/auth/overview) to edit:
254
+
255
+ - The `/api/puck` route passes `authenticate` from `@puckeditor/cloud-client/auth` to `puckHandler`, which serves the sign-in routes under `/api/puck/auth` and rejects requests from anyone not signed in to your Puck Cloud organization
256
+ - The editor sends signed-out visitors to sign in. Server-rendered apps check before rendering it. Vite apps, and Astro sites without a server, check in the browser with `<RequireSession>`
257
+ - The Puck Auth plugin adds an account menu to the editor
258
+
259
+ Without Puck Pages, the editor still saves pages through your own route, which Sign in with Puck doesn't protect. On a Hono or Express server, `add auth` only changes the Cloud route, so run it in the editor's app too.
260
+
261
+ Members sign in to the API key's project and edit its branch. Set `PUCK_API_KEY` on each deployment to a key for the branch it should edit, so a preview deployment can't edit production.
262
+
263
+ ## Telemetry
264
+
265
+ The CLI collects anonymous usage data to help us improve it. The first time it runs without `--json`, it prints a notice.
266
+
267
+ Each command sends one event to Puck Cloud with:
268
+
269
+ - The command, what `add` was asked for, the result status, error and warning codes, the actions it returned, the exit code and how long it took
270
+ - Whether it was a dry run, made changes, ran interactively, used `--json` or ran in CI
271
+ - The CLI version, operating system, CPU architecture and Node.js version
272
+ - The name of the coding agent running it, if it's a known one, such as `claude-code`
273
+ - The framework and its major version, the package manager, the `--backend` choice, whether the project is in a monorepo, and whether the Puck editor, Puck Cloud and Puck AI are set up
274
+ - A random ID, stored in `~/.config/puck/telemetry.json`
275
+
276
+ It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys. When you log in to Puck Cloud with `connect`, the random ID is linked to your account.
277
+
278
+ To turn telemetry off, run:
279
+
280
+ ```sh
281
+ npx @puckeditor/cli telemetry disable
282
+ ```
283
+
284
+ Or set `PUCK_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` in your environment. `telemetry status` shows whether it's on, and `PUCK_TELEMETRY_DEBUG=1` prints each event instead of sending it.
@@ -0,0 +1,54 @@
1
+ # Composition
2
+
3
+ Puck uses compositional patterns enable completely custom editor interfaces. [See an example](https://demo.puckeditor.com/custom-ui/edit/).
4
+
5
+ ## Using composition
6
+
7
+ Composition can be achieved by providing [`children`](/docs/api-reference/components/puck#children) to the [`<Puck>` component](/docs/api-reference/components/puck):
8
+
9
+ ```tsx
10
+ import { Puck } from "@puckeditor/core";
11
+
12
+ export function Editor() {
13
+ return (
14
+ <Puck>
15
+ <div
16
+ style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gridGap: 16 }}
17
+ >
18
+ <div>
19
+ {/* Render the drag-and-drop preview */}
20
+ <Puck.Preview />
21
+ </div>
22
+ <div>
23
+ {/* Render the component list */}
24
+ <Puck.Components />
25
+ </div>
26
+ </div>
27
+ </Puck>
28
+ );
29
+ }
30
+ ```
31
+
32
+ ## Compositional components
33
+
34
+ Puck exposes its core components, allowing you to compose them together to create new layouts:
35
+
36
+ - [`<Puck.Components>`](/docs/api-reference/components/puck-components) - A draggable list of components.
37
+ - [`<Puck.Fields>`](/docs/api-reference/components/puck-fields) - The fields for the currently selected item.
38
+ - [`<Puck.Outline>`](/docs/api-reference/components/puck-outline) - An interactive outline.
39
+ - [`<Puck.Preview>`](/docs/api-reference/components/puck-preview) - A drag-and-drop preview.
40
+
41
+ The internal UI for these components can also be changed by implementing [UI overrides](/docs/extending-puck/ui-overrides) or [theming](/docs/extending-puck/theming).
42
+
43
+ ### Helper components
44
+
45
+ Puck also exposes helper components for even deeper customization:
46
+
47
+ - [`<Drawer>`](/docs/api-reference/components/drawer) - A reference list of items that can be dragged into a droppable area, normally `<Puck.Preview>`.
48
+ - [`<Drawer.Item>`](/docs/api-reference/components/drawer-item) - An item that can be dragged from a `<Drawer>`.
49
+ - [`<FieldLabel>`](/docs/api-reference/components/field-label) - A styled label for creating inputs.
50
+
51
+ ## Further reading
52
+
53
+ - [Internal Puck API](/docs/extending-puck/internal-puck-api)
54
+ - [UI overrides](/docs/extending-puck/ui-overrides)
@@ -0,0 +1,133 @@
1
+ # Custom Fields
2
+
3
+ Puck can be extended with completely custom fields for different use-cases.
4
+
5
+ ## Creating a custom field
6
+
7
+ Creating a custom field is possible using the [`custom` field type](/docs/api-reference/fields/custom):
8
+
9
+ ```tsx
10
+ const config = {
11
+ components: {
12
+ Example: {
13
+ fields: {
14
+ title: {
15
+ type: "custom",
16
+ render: ({ name, onChange, value }) => (
17
+ <input
18
+ defaultValue={value}
19
+ name={name}
20
+ onChange={(e) => onChange(e.currentTarget.value)}
21
+ style={{ border: "1px solid black", padding: 4 }}
22
+ />
23
+ ),
24
+ },
25
+ },
26
+ render: ({ title }) => {
27
+ return <p>{title}</p>;
28
+ },
29
+ },
30
+ },
31
+ };
32
+ ```
33
+
34
+ The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) updates the Puck data payload for the field name, in this case "title".
35
+
36
+ ## Adding a label
37
+
38
+ You can add your own label, but it's recommended to use the [`<FieldLabel>` component](/docs/api-reference/components/field-label) provided by Puck to seamlessly integrate into the Puck field UI.
39
+
40
+ ```tsx
41
+ import { FieldLabel } from "@puckeditor/core";
42
+
43
+ const config = {
44
+ components: {
45
+ Example: {
46
+ fields: {
47
+ title: {
48
+ type: "custom",
49
+ label: "Label Example",
50
+ render: ({ field }) => (
51
+ <FieldLabel label={field.label}>
52
+ <input {/*...*/} />
53
+ </FieldLabel>
54
+ ),
55
+ },
56
+ },
57
+ // ...
58
+ },
59
+ },
60
+ };
61
+ ```
62
+
63
+ ## Rendering Puck fields internally
64
+
65
+ Use the [`<AutoField>` component](/docs/api-reference/components/auto-field) to render Puck fields within your custom field.
66
+
67
+ ```tsx
68
+ import { AutoField } from "@puckeditor/core";
69
+
70
+ const config = {
71
+ components: {
72
+ Example: {
73
+ fields: {
74
+ title: {
75
+ type: "custom",
76
+ label: "Label Example",
77
+ render: ({ field, value, onChange }) => (
78
+ <FieldLabel label={field.label}>
79
+ <AutoField
80
+ field={{ type: "text" }}
81
+ onChange={(value) => onChange(value)}
82
+ value={value}
83
+ />
84
+ </FieldLabel>
85
+ ),
86
+ },
87
+ // ...
88
+ },
89
+ },
90
+ },
91
+ };
92
+ ```
93
+
94
+ ## Updating the UI state
95
+
96
+ The [`onChange` function](/docs/api-reference/fields/custom#onchangevalue-ui) can also be used to modify the [Puck UI state](/docs/api-reference/data-model/app-state#ui) at the same time as updating the field value:
97
+
98
+ ```tsx
99
+ const config = {
100
+ components: {
101
+ Example: {
102
+ fields: {
103
+ title: {
104
+ type: "custom",
105
+ render: ({ name, onChange, value }) => (
106
+ <input
107
+ defaultValue={value}
108
+ name={name}
109
+ onChange={(e) =>
110
+ onChange(
111
+ e.currentTarget.value,
112
+ // Close the left side bar when this field is changed
113
+ { leftSideBarVisible: false }
114
+ )
115
+ }
116
+ style={{ border: "1px solid black", padding: 4 }}
117
+ />
118
+ ),
119
+ },
120
+ },
121
+ render: ({ title }) => {
122
+ return <p>{title}</p>;
123
+ },
124
+ },
125
+ },
126
+ };
127
+ ```
128
+
129
+ ## Further reading
130
+
131
+ - [The `<AutoField>` API reference](/docs/api-reference/components/auto-field)
132
+ - [The `<FieldLabel>` API reference](/docs/api-reference/components/field-label)
133
+ - [The `custom` field API reference](/docs/api-reference/fields/custom)
@@ -0,0 +1,89 @@
1
+ # Field Transforms
2
+
3
+ Puck lets you modify props before rendering in the editor via the [`FieldTransforms` API](/docs/api-reference/field-transforms).
4
+
5
+ Use this API to implement custom rendering behavior for specific field types, which can be used to implement features such as inline text editing.
6
+
7
+ > **Note:** Field transforms only apply to components rendered in `<Puck>` and will not be applied to `<Render>`.
8
+
9
+ ## Implementing a transform
10
+
11
+ Specify a transforms object for the fields you want to modify before rendering:
12
+
13
+ ```tsx
14
+ const fieldTransforms = {
15
+ text: ({ value }) => value.toUpperCase(), // Transform text fields to uppercase
16
+ };
17
+
18
+ const Example = () => <Puck fieldTransforms={fieldTransforms} />;
19
+ ```
20
+
21
+ ## Making it interactive
22
+
23
+ Combine transforms with [Overlay Portals](/docs/integrating-puck/overlay-portals) to make them interactive.
24
+
25
+ ```tsx
26
+ import { registerOverlayPortal } from "@puckeditor/core";
27
+
28
+ const EditableText = ({ value }) => {
29
+ const ref = useRef(null);
30
+
31
+ useEffect(() => {
32
+ if (ref.current) {
33
+ // Register the element as an overlay portal
34
+ registerOverlayPortal(ref.current);
35
+ }
36
+ }, [ref.current]);
37
+
38
+ return (
39
+ // Mark the element as editable for inline text editing
40
+ <p ref={ref} contentEditable>
41
+ {value}
42
+ </p>
43
+ );
44
+ };
45
+
46
+ const fieldTransforms = {
47
+ text: (props) => <EditableText {...props} />,
48
+ };
49
+
50
+ const Example = () => <Puck fieldTransforms={fieldTransforms} />;
51
+ ```
52
+
53
+ Because Puck calls transforms as functions, render components that use hooks from the transform instead of passing them directly.
54
+
55
+ ## Define new fields
56
+
57
+ As with [field type overrides](/docs/extending-puck/ui-overrides#introducing-new-field-types), field transforms let you define your own field types:
58
+
59
+ ```tsx
60
+ const fieldTransforms = {
61
+ example: () => <div />,
62
+ };
63
+ ```
64
+
65
+ ## Distributing field transforms as plugins
66
+
67
+ Distribute transforms as plugins to package up custom behavior.
68
+
69
+ ```tsx
70
+ const plugin = {
71
+ fieldTransforms: {
72
+ example: ({ value }) => <div>{value}</div>, // Wrap all example fields with divs
73
+ },
74
+
75
+ // This example combines transforms with overrides
76
+ overrides: {
77
+ fieldTypes: {
78
+ example: () => <input />, // Define a field interface
79
+ },
80
+ },
81
+ };
82
+
83
+ const Example = () => <Puck plugins={[plugin]} />;
84
+ ```
85
+
86
+ ## Further reading
87
+
88
+ - [Field Transforms API reference](/docs/api-reference/field-transforms)
89
+ - [Overlay Portals API reference](/docs/integrating-puck/overlay-portals)
@@ -0,0 +1,96 @@
1
+ # Internal Puck API
2
+
3
+ Puck exposes its internal API as [`PuckApi`](/docs/api-reference/puck-api) for extending Puck with custom functionality within [custom fields](/docs/extending-puck/custom-fields), [compositional interfaces](/docs/extending-puck/composition) or [UI overrides](/docs/extending-puck/ui-overrides).
4
+
5
+ ## Accessing the internal API
6
+
7
+ You can access [`PuckApi`](/docs/api-reference/puck-api) via two hooks:
8
+
9
+ - [`usePuck`](/docs/api-reference/functions/use-puck) - returns `PuckApi` as part of your component render lifecycle
10
+ - [`useGetPuck`](/docs/api-reference/functions/use-get-puck) - returns a function to access the latest `PuckApi` at call time
11
+
12
+ ### Within the render lifecycle
13
+
14
+ To access the API within your render lifecycle, use the `usePuck` hook. You can use a selector to limit re-rendering to a specific part of the API.
15
+
16
+ ```tsx
17
+ import { createUsePuck } from "@puckeditor/core";
18
+
19
+ const usePuck = createUsePuck();
20
+
21
+ const Example = () => {
22
+ // Use a selector so you only re-render when the selected type changes
23
+ const type = usePuck((s) => s.selectedItem?.type || "Nothing");
24
+
25
+ return <h2>{type} selected</h2>;
26
+ };
27
+ ```
28
+
29
+ See the [`usePuck`](/docs/api-reference/functions/use-puck) docs for a full API reference.
30
+
31
+ ### Outside of the render lifecycle
32
+
33
+ Often it's not necessary to re-render your component when the PuckApi changes. Puck provides the `useGetPuck` hook for accessing the latest `PuckApi` at call time.
34
+
35
+ ```tsx
36
+ import { useGetPuck } from "@puckeditor/core";
37
+
38
+ const Example = () => {
39
+ const getPuck = useGetPuck();
40
+
41
+ const handleClick = useCallback(() => {
42
+ // Get the latest PuckApi value
43
+ const { appState } = getPuck();
44
+
45
+ console.log(appState);
46
+ }, [getPuck]);
47
+
48
+ return <button onClick={handleClick}>Click me</button>;
49
+ };
50
+ ```
51
+
52
+ See the [`useGetPuck`](/docs/api-reference/functions/use-get-puck) docs for a full API reference.
53
+
54
+ ## Usage in practice
55
+
56
+ Generally, you'll want to combine this with composition, UI overrides or custom fields.
57
+
58
+ Here's an example using the internal API to log the page data as JSON while retaining the standard Puck UI:
59
+
60
+ ```tsx
61
+ import { Puck, createUsePuck } from "@puckeditor/core";
62
+
63
+ const usePuck = createUsePuck();
64
+
65
+ const JSONLogger = ({ children }) => {
66
+ const appState = usePuck((s) => s.appState);
67
+
68
+ useEffect(() => {
69
+ console.log(appState);
70
+ }, [appState]);
71
+
72
+ return <>{children}</>;
73
+ };
74
+
75
+ export function Editor() {
76
+ return (
77
+ // Render the Puck context
78
+ <Puck>
79
+ <JSONLogger>
80
+ {/* Since we're overriding Puck's children, we restore the standard Puck UI */}
81
+ <Puck.Layout />
82
+ </JSONLogger>
83
+ </Puck>
84
+ );
85
+ }
86
+ ```
87
+
88
+ ## Further reading
89
+
90
+ - [`PuckApi` API reference](/docs/api-reference/puck-api)
91
+ - [`usePuck` API reference](/docs/api-reference/functions/use-puck)
92
+ - [`useGetPuck` API reference](/docs/api-reference/functions/use-get-puck)
93
+ - [`<Puck.Layout>` API reference](/docs/api-reference/components/puck-layout)
94
+ - [Composition](/docs/extending-puck/composition)
95
+ - [Custom fields](/docs/extending-puck/custom-fields)
96
+ - [UI overrides](/docs/extending-puck/ui-overrides)