@byscott-io/pagelet 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 0.2.0 (2026-11-13)
+
+### npm `@byscott-io/pagelet`
+- **Page settings** (the page's own fields): a browser title, and a background
+  that follows the site's, is custom, or is none, with an overlay color and
+  **opacity %**. `pageSettings(document)` returns the title.
+- **Site background**, set in the theme: an image, overlay color and opacity,
+  `fit` (`cover`, or `photo` to show the whole photo), and `frame` (`none`, or
+  `card` for a bordered, rounded, padded frame).
+- **New blocks:** Quote (italic text plus a citation), Icon list (icon, text, an
+  optional link), Schedule (rows of day / time / what), and Embedded page.
+- **Embedded page** is offered only when the app names trusted hosts:
+  `createPalette({ embedHosts: ['example.org'] })`. https only, sandboxed.
+- **Right alignment** for Text, Heading, Button and the new blocks; Image gains
+  alignment and a width %; Section gains a background image with an overlay
+  color and opacity.
+- A built-in **icon set** (inline SVG): location, phone, email, video, calendar,
+  clock, link, Facebook, YouTube. `<Icon name>` is exported.
+- **`<PageletMenu>` and `<PageletLayout>`:** a site's menu from its settings
+  (a brand logo, items with optional icon and highlight, left and right groups,
+  external links in a new tab, a menu button on narrow screens) and the frame
+  around a page. Pass your router's link component as `linkComponent`.
+- The menu's brand link is a plain anchor for `tel:`/`mailto:` (like menu
+  items), never passed to the app's router.
+- **Client:** `getSite`, `updateSite`, and `getPublishedPage(path)` returning
+  `{ document, pagePath, rest }`; `createPage`/`updatePage` take `matchesSubpaths`.
+
+### gem `pagelet`
+- **Site settings** per owner (`Pagelet::Site`): the theme and the menu.
+  `GET /site` is public; `PATCH /site` needs `:publish`, since changes are live
+  at once. Shapes are checked (menu style, labels, links, groups, size).
+- **Pages that answer for sub-paths:** `matches_subpaths` on a page makes
+  `/messages` serve `/messages/43`. An exact page wins, then the longest such
+  prefix. `Page.published_match(owner, path)` returns the document, the page's
+  path and the remainder; `GET /published` returns them too.
+- **New migration:** run `bin/rails pagelet:install:migrations` and migrate
+  (see docs/UPGRADING.md).
+
+## 0.1.0 (2026-11-13)
+
+First release.
+
+### npm `@byscott-io/pagelet`
+- `createPalette`: the built-in blocks plus an app's own, with hiding and grouping.
+- `PageletPage`: renders a saved page. No editor code; works in server-side rendering.
+- `PageletEditor` (from `@byscott-io/pagelet/editor`): the visual editor, built on Puck 0.24.
+- Built-in blocks: Section, Columns, Spacer, Divider, Hero, Heading, Text, Button,
+  Call to action, Cards, FAQ, Image, Image with text, Video (YouTube/Vimeo).
+- Theming through CSS variables.
+- Versioned page documents (`{ pagelet: 1, data }`), upgraded when loaded.
+- `safeUrl` / `safeImageUrl`: user-entered links and images refuse unsafe schemes.
+- `createPageletClient`: the engine's API from the browser, with CSRF and
+  `PageletApiError` carrying the server's field errors.
+
+### gem `pagelet` (Rails engine)
+- Pages scoped to an owner the app supplies; another owner's page is a 404.
+- Drafts, numbered published versions (never edited after publishing), and
+  rollback by restoring an old version into the draft.
+- JSON API for the editor, behind the app's own `authorize` hook (`:edit`, `:publish`).
+- `Page.published_document(owner, path)` for server-side rendering, and
+  `Page.sitemap_entries(owner)`. Drafts never reach either.
+- Document checks: format version, shape, and a size limit.
+- `bin/rails generate pagelet:install`: initializer, migrations, route.
+
+## 0.0.1 (gem only)
+- Placeholder that reserves the name on RubyGems. No functionality.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Gibson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# pagelet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A page builder for React apps. Your users build pages by dragging blocks onto a
+canvas, and your site draws the saved pages with the same React components.
+
+- **A visual editor** for admin screens: drag, reorder, edit, undo, and preview
+  at phone and desktop widths.
+- **A small renderer** for public pages. It has no editor code in it, and it
+  works in server-side rendering, so search engines see real HTML.
+- **A standard set of blocks**: sections, columns, hero, headings, text,
+  quotes, icon lists, schedules, buttons, calls to action, cards, FAQ, images,
+  image with text, YouTube/Vimeo video, and (for hosts you allow) embedded pages.
+- **Page backgrounds**: a site-wide photo under a panel of any color and
+  opacity, which each page can follow, replace or turn off.
+- **Your own blocks**: register any React component and it appears in the
+  palette beside the built-in ones.
+- **Theming** through CSS variables: colors, fonts, corner radius, page width.
+- **A site menu and layout**: logo, items with icons and highlights, left and
+  right groups, and a menu button on phones, all from site settings.
+
+pagelet is built on [Puck](https://puckeditor.com), an MIT-licensed visual
+editor for React. Your app talks only to pagelet, which keeps Puck's upgrades in
+one place.
+
+> Not related to the older `pagelet` package on npm from the BigPipe project.
+
+**Status:** early (0.1.x); the API may still change. Two packages:
+
+- `@byscott-io/pagelet` (npm): the editor, renderer and blocks.
+- `pagelet` (gem): a Rails engine that stores pages, keeps every published
+  version, and serves the editor's API. See [docs/INTEGRATION.md](docs/INTEGRATION.md).
+
+## Install
+
+```sh
+yarn add @byscott-io/pagelet react react-dom
+```
+
+## Use
+
+**1. Define your palette once**, with any blocks of your own:
+
+```jsx
+import { createPalette } from '@byscott-io/pagelet';
+
+const Quote = {
+  label: 'Quote',
+  category: 'extras',
+  fields: { text: { type: 'textarea' }, author: { type: 'text' } },
+  render: ({ text, author }) => (
+    <blockquote>
+      {text}
+      <cite>{author}</cite>
+    </blockquote>
+  ),
+};
+
+export const palette = createPalette({
+  blocks: { Quote },                         // added beside the built-in blocks
+  categories: { extras: { title: 'Extras' } },
+  hide: ['Faq'],                             // built-in blocks you don't want
+});
+```
+
+**2. Edit pages** in your admin screens:
+
+```jsx
+import { PageletEditor } from '@byscott-io/pagelet/editor';
+import '@byscott-io/pagelet/editor.css';
+
+<PageletEditor
+  document={savedDocument}
+  palette={palette}
+  theme={siteTheme}
+  headerTitle="Home page"
+  onPublish={(document) => save(document)}
+/>;
+```
+
+**3. Render pages** on your site:
+
+```jsx
+import { PageletPage } from '@byscott-io/pagelet';
+
+<PageletPage document={savedDocument} palette={palette} theme={siteTheme} />;
+```
+
+`document` is plain JSON (`{ pagelet: 1, data: {...} }`). Store it as-is; pass
+it back to either component. Pages saved by an older pagelet are upgraded when
+they load.
+
+**4. With the Rails engine**, the client does the storing:
+
+```jsx
+import { createPageletClient } from '@byscott-io/pagelet';
+
+const pages = createPageletClient(); // same origin, mounted at /pagelet
+
+const { page } = await pages.getPage(id);
+<PageletEditor
+  document={page.draft_document}
+  palette={palette}
+  onChange={(document) => pages.saveDraft(id, document)}
+  onPublish={async (document) => {
+    await pages.saveDraft(id, document);
+    await pages.publish(id);
+  }}
+/>;
+```
+
+It sends the app's session cookie and the CSRF token from the page's
+`csrf-token` meta tag, and throws `PageletApiError` (with `status` and field
+`errors`) when the server refuses.
+
+## Theme
+
+Any subset of these tokens; the rest use the defaults:
+
+```js
+{
+  colorText, colorBackground, colorMuted,
+  colorAccent, colorAccentText,
+  fontBody, fontHeading,
+  radius, maxWidth, space,
+}
+```
+
+They become CSS variables (`--pagelet-color-accent`, …) on the page wrapper, so
+your own blocks can use them too: `color: var(--pagelet-color-accent)`.
+
+A site background goes in the theme too, and each page can follow it, use its
+own, or have none (the page's Background setting):
+
+```js
+background: {
+  image: '/images/building.jpg',
+  overlayColor: '#ffffff',
+  overlayOpacity: 85,   // percent
+  fit: 'photo',         // or 'cover'
+  frame: 'card',        // or 'none'
+  rounded: true,
+}
+```
+
+## Writing your own blocks
+
+A block is a [Puck component config](https://puckeditor.com/docs/api-reference/configuration/component-config)
+(`fields`, `defaultProps`, `render`) plus an optional `category`.
+
+- **Render on the server.** `render` must not touch `window` or `document`
+  while rendering. Add browser-only behavior in an effect.
+- **Treat every URL as untrusted.** Pass user-entered links through `safeUrl`
+  and images through `safeImageUrl` (both exported); they refuse `javascript:`
+  and other unsafe schemes.
+- A block with a built-in block's name replaces that block.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/editor.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var core = require('@puckeditor/core');
+var rsc = require('@puckeditor/core/rsc');
+
+const DOCUMENT_VERSION = 1;
+function emptyData() {
+  return { root: { props: {} }, content: [] };
+}
+function createDocument(data = emptyData()) {
+  return { pagelet: DOCUMENT_VERSION, data };
+}
+function upgradeDocument(document, palette) {
+  if (document == null) return createDocument();
+  if (typeof document !== "object") {
+    throw new TypeError("pagelet: a page document must be an object");
+  }
+  let doc = document;
+  if (!("pagelet" in doc)) {
+    if (!("content" in doc) && !("root" in doc)) {
+      throw new TypeError('pagelet: not a page document (no "pagelet" version and no Puck data)');
+    }
+    doc = createDocument(doc);
+  }
+  if (doc.pagelet > DOCUMENT_VERSION) {
+    throw new Error(
+      `pagelet: this page was saved by a newer pagelet (format ${doc.pagelet}); this version reads up to format ${DOCUMENT_VERSION}. Upgrade @byscott-io/pagelet.`
+    );
+  }
+  const data = { ...emptyData(), ...doc.data };
+  return createDocument(palette && needsPuckMigration(data) ? rsc.migrate(data, palette.config) : data);
+}
+function needsPuckMigration(data) {
+  const zones = data.zones ?? {};
+  if (Object.values(zones).some((content) => Array.isArray(content) && content.length > 0)) return true;
+  const root = data.root ?? {};
+  return Object.keys(root).some((key) => key !== "props" && key !== "readOnly");
+}
+
+function PageletEditor({ document, palette, theme, onPublish, onChange, headerTitle, ...rest }) {
+  if (!palette) throw new Error("pagelet: <PageletEditor> needs a palette (see createPalette)");
+  const { data } = upgradeDocument(document, palette);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    core.Puck,
+    {
+      ...rest,
+      config: palette.config,
+      data,
+      metadata: { pageletTheme: theme },
+      headerTitle,
+      onPublish: onPublish ? (next) => onPublish(createDocument(next)) : void 0,
+      onChange: onChange ? (next) => onChange(createDocument(next)) : void 0
+    }
+  );
+}
+
+exports.PageletEditor = PageletEditor;
+//# sourceMappingURL=editor.cjs.map

package/dist/editor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.cjs","sources":["../src/document.js","../src/PageletEditor.jsx"],"sourcesContent":["import { migrate } from '@puckeditor/core/rsc';\n\n// What an app stores for a page: Puck's data inside an envelope that carries\n// pagelet's own format version. The version lets a stored page be upgraded when\n// pagelet or Puck changes shape, so apps never hold raw Puck data whose format\n// they do not control.\nexport const DOCUMENT_VERSION = 1;\n\nexport function emptyData() {\n  return { root: { props: {} }, content: [] };\n}\n\nexport function createDocument(data = emptyData()) {\n  return { pagelet: DOCUMENT_VERSION, data };\n}\n\n// Bring a stored document up to the current format.\n//\n// Accepts bare Puck data too, since an app adopting pagelet may already hold\n// some. Passing the palette also runs Puck's own migrate(), which converts\n// older Puck structures (DropZone zones) into the current one (slots).\nexport function upgradeDocument(document, palette) {\n  if (document == null) return createDocument();\n  if (typeof document !== 'object') {\n    throw new TypeError('pagelet: a page document must be an object');\n  }\n\n  let doc = document;\n  if (!('pagelet' in doc)) {\n    if (!('content' in doc) && !('root' in doc)) {\n      throw new TypeError('pagelet: not a page document (no \"pagelet\" version and no Puck data)');\n    }\n    doc = createDocument(doc);\n  }\n\n  if (doc.pagelet > DOCUMENT_VERSION) {\n    throw new Error(\n      `pagelet: this page was saved by a newer pagelet (format ${doc.pagelet}); ` +\n        `this version reads up to format ${DOCUMENT_VERSION}. Upgrade @byscott-io/pagelet.`,\n    );\n  }\n\n  // Format migrations go here, one step per version:\n  //   if (doc.pagelet === 1) doc = migrateV1toV2(doc);\n\n  const data = { ...emptyData(), ...doc.data };\n  return createDocument(palette && needsPuckMigration(data) ? migrate(data, palette.config) : data);\n}\n\n// Puck's migrate() logs to the console every time it is given a config, even\n// when there is nothing to convert. On a public page that would be a log line\n// per page view, so only call it for data in an older Puck shape: DropZone\n// zones holding content, or a root whose fields sit outside `props`.\nexport function needsPuckMigration(data) {\n  const zones = data.zones ?? {};\n  if (Object.values(zones).some((content) => Array.isArray(content) && content.length > 0)) return true;\n  const root = data.root ?? {};\n  return Object.keys(root).some((key) => key !== 'props' && key !== 'readOnly');\n}\n\n// A page's own settings (title, background), for the app to use outside the\n// page body, e.g. the browser title.\nexport function pageSettings(document) {\n  const props = upgradeDocument(document)?.data?.root?.props ?? {};\n  return { title: props.title || '', background: props.background ?? 'site' };\n}\n","import { Puck } from '@puckeditor/core';\nimport { createDocument, upgradeDocument } from './document.js';\n\n// The visual editor. Import from \"@byscott-io/pagelet/editor\" (and its\n// stylesheet from \"@byscott-io/pagelet/editor.css\") in admin screens only.\n//\n// onPublish and onChange receive a pagelet document, ready to store as-is.\nexport function PageletEditor({ document, palette, theme, onPublish, onChange, headerTitle, ...rest }) {\n  if (!palette) throw new Error('pagelet: <PageletEditor> needs a palette (see createPalette)');\n  const { data } = upgradeDocument(document, palette);\n  return (\n    <Puck\n      {...rest}\n      config={palette.config}\n      data={data}\n      metadata={{ pageletTheme: theme }}\n      headerTitle={headerTitle}\n      onPublish={onPublish ? (next) => onPublish(createDocument(next)) : undefined}\n      onChange={onChange ? (next) => onChange(createDocument(next)) : undefined}\n    />\n  );\n}\n"],"names":["migrate","jsx","Puck"],"mappings":";;;;;;AAMO,MAAM,gBAAA,GAAmB,CAAA;AAEzB,SAAS,SAAA,GAAY;AAC1B,EAAA,OAAO,EAAE,MAAM,EAAE,KAAA,EAAO,EAAC,EAAE,EAAG,OAAA,EAAS,EAAC,EAAE;AAC5C;AAEO,SAAS,cAAA,CAAe,IAAA,GAAO,SAAA,EAAU,EAAG;AACjD,EAAA,OAAO,EAAE,OAAA,EAAS,gBAAA,EAAkB,IAAA,EAAK;AAC3C;AAOO,SAAS,eAAA,CAAgB,UAAU,OAAA,EAAS;AACjD,EAAA,IAAI,QAAA,IAAY,IAAA,EAAM,OAAO,cAAA,EAAe;AAC5C,EAAA,IAAI,OAAO,aAAa,QAAA,EAAU;AAChC,IAAA,MAAM,IAAI,UAAU,4CAA4C,CAAA;AAAA,EAClE;AAEA,EAAA,IAAI,GAAA,GAAM,QAAA;AACV,EAAA,IAAI,EAAE,aAAa,GAAA,CAAA,EAAM;AACvB,IAAA,IAAI,EAAE,SAAA,IAAa,GAAA,CAAA,IAAQ,EAAE,UAAU,GAAA,CAAA,EAAM;AAC3C,MAAA,MAAM,IAAI,UAAU,sEAAsE,CAAA;AAAA,IAC5F;AACA,IAAA,GAAA,GAAM,eAAe,GAAG,CAAA;AAAA,EAC1B;AAEA,EAAA,IAAI,GAAA,CAAI,UAAU,gBAAA,EAAkB;AAClC,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,wDAAA,EAA2D,GAAA,CAAI,OAAO,CAAA,mCAAA,EACjC,gBAAgB,CAAA,8BAAA;AAAA,KACvD;AAAA,EACF;AAKA,EAAA,MAAM,OAAO,EAAE,GAAG,WAAU,EAAG,GAAG,IAAI,IAAA,EAAK;AAC3C,EAAA,OAAO,cAAA,CAAe,OAAA,IAAW,kBAAA,CAAmB,IAAI,CAAA,GAAIA,YAAQ,IAAA,EAAM,OAAA,CAAQ,MAAM,CAAA,GAAI,IAAI,CAAA;AAClG;AAMO,SAAS,mBAAmB,IAAA,EAAM;AACvC,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,IAAS,EAAC;AAC7B,EAAA,IAAI,MAAA,CAAO,MAAA,CAAO,KAAK,CAAA,CAAE,KAAK,CAAC,OAAA,KAAY,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA,IAAK,OAAA,CAAQ,MAAA,GAAS,CAAC,GAAG,OAAO,IAAA;AACjG,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,IAAA,IAAQ,EAAC;AAC3B,EAAA,OAAO,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,IAAA,CAAK,CAAC,GAAA,KAAQ,GAAA,KAAQ,OAAA,IAAW,GAAA,KAAQ,UAAU,CAAA;AAC9E;;ACnDO,SAAS,aAAA,CAAc,EAAE,QAAA,EAAU,OAAA,EAAS,KAAA,EAAO,WAAW,QAAA,EAAU,WAAA,EAAa,GAAG,IAAA,EAAK,EAAG;AACrG,EAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,MAAM,8DAA8D,CAAA;AAC5F,EAAA,MAAM,EAAE,IAAA,EAAK,GAAI,eAAA,CAAgB,UAAU,OAAO,CAAA;AAClD,EAAA,uBACEC,cAAA;AAAA,IAACC,SAAA;AAAA,IAAA;AAAA,MACE,GAAG,IAAA;AAAA,MACJ,QAAQ,OAAA,CAAQ,MAAA;AAAA,MAChB,IAAA;AAAA,MACA,QAAA,EAAU,EAAE,YAAA,EAAc,KAAA,EAAM;AAAA,MAChC,WAAA;AAAA,MACA,SAAA,EAAW,YAAY,CAAC,IAAA,KAAS,UAAU,cAAA,CAAe,IAAI,CAAC,CAAA,GAAI,MAAA;AAAA,MACnE,QAAA,EAAU,WAAW,CAAC,IAAA,KAAS,SAAS,cAAA,CAAe,IAAI,CAAC,CAAA,GAAI;AAAA;AAAA,GAClE;AAEJ;;"}