@seamlet/astro 0.12.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 1.1.0
+
+- Pages of records: `recordPages(schema, { collection, path: "/menu/[record]" })` gives every record of a collection a page, rendered by one component with `content`, `record` and `index`; `defineSeamletSite` takes them as `recordPages`, the site's description tells the CMS about them, and the preview shows them, a record the editor has just added too.
+- `slug({ label })`: the address of a record's page, checked as an address (`invalid-slug`) and as one of a kind in its collection (`taken-slug`); `slugOf` spells it from Russian words. A record without a slug has its page at its id.
+- `site.pageOf(rest, content)` and `site.staticPaths(content)` render every page of a site from one `[...page]` route, the pages of records too. `site.pageAt` renders the site's own pages only, and is deprecated.
+- The preview answers an address of no page at once, without asking the CMS or reading the draft.
+
+A site with a `slug` or pages of records needs a CMS that reads descriptions of 1.1 (cms.seamlet.ru from its release 1.1.0): an older one refuses the kind `slug`. Code with an exhaustive `switch` over `Field`, `ContentIssue`, `SchemaProblemReason` or `SiteDescriptionProblem` gets their new members to handle.
+
+## 1.0.0
+
+The first stable version. From here the package follows semver: what a site writes against it keeps building until the next major version.
+
+What is stable:
+
+- `@seamlet/astro` — the integration `seamlet()`, with the site's id, title and CMS in `seamlet.json` (`CMS_ORIGIN` takes the place of `cms`).
+- `@seamlet/astro/site` — `defineSeamletSite({ schema, initialContent, pages, photos })` with `pageAt`, `loadPublishedContent`, `ownPhotoAt` and `description`.
+- `@seamlet/astro/schema` — the field kinds and their builders, `ContentOf`, `defaultContent`, `parseContent`, `editable`, `resolveFieldPath`, formatted text (`richTextOf`, `plainTextOf`, `linesOf`), `safeHref`, `imagePosition`, the presets, record ids, `readSiteConfig`, `readSiteDescription`, `checkSiteDescription` and `checkFields`.
+- `@seamlet/astro/components/RichText.astro` and the routes the integration adds: the preview (`/preview`), the site's description (`/seamlet/site.json`), the photos taken from the CMS (`/media/<site>/<file>`) and the site's own photos for the editor (`/seamlet-photos/<address>`).
+- `@seamlet/astro/protocol` — the messages between the bridge and the CMS's editor at `PROTOCOL_VERSION` 2. A change the other side cannot read raises it; the editor speaks with the bridges of earlier versions it lists.
+- `npx @seamlet/astro init`.
+
+Since 0.12.1 nothing changed in the code.
+
+## 0.12.1
+
+- A field that became plain text keeps the words of a formatted text saved in it.
+
+## 0.12.0
+
+- `safeHref`: an address no link may have never reaches markup; `RichText` and the bridge use it.
+- A site the CMS would refuse stops its build with every reason (`checkSiteDescription`, `checkFields`); `readFields` refuses names with a dot or of digits, options of the wrong kind, references to a missing collection and an `itemTitle` that is no text or link.
+- Requests to the CMS are bounded in time and number; `/media` answers 502 when the CMS does not.
+- A draft rendered while a text is typed or the page pressed is shown once that is over.
+- `init` starts a site with a title of any length and writes its modules all or none.

package/README.md

@@ -67,7 +67,7 @@ npx astro add @seamlet/astro node                   # the integration, and an ad
    <h1 {...edit("title")}>{content.title}</h1>
    ```
 
-4. Describe the site for the CMS in `src/seamlet.ts`: its schema, the content it starts with, and its pages, each with the name the editor gives it and the component that renders it (it takes the content as its `content` prop). The home page `/` comes first; `searchTexts` names where the content holds a page's title and description for search engines, a group of a `title` and a `description` text (`seoFields`).
+4. Describe the site for the CMS in `src/seamlet.ts`: its schema, the content it starts with, and its pages, each with the name the editor gives it and the component that renders it (it takes the content as its `content` prop), and the pages of records if it has them (see «Pages of records»). The home page `/` comes first; `searchTexts` names where the content holds a page's title and description for search engines, a group of a `title` and a `description` text (`seoFields`).
 
    ```ts
    // src/seamlet.ts
@@ -98,6 +98,23 @@ npx astro add @seamlet/astro node                   # the integration, and an ad
    });
    ```
 
+A site renders all its pages, the pages of records too (below), from one route `src/pages/[...page].astro`: `site.staticPaths(content)` lists every page for a static build, and `site.pageOf(rest, content)` finds the one asked for on request; each gives the component and the props to render it with.
+
+```astro
+---
+// src/pages/[...page].astro, built as static pages
+import site from "../seamlet";
+
+export async function getStaticPaths() {
+  return site.staticPaths(await site.loadPublishedContent());
+}
+
+const { component: Page, props } = Astro.props;
+---
+
+<Page {...props} />
+```
+
 The site's pages take their published content with `site.loadPublishedContent()`: at build time for a static site, on request otherwise. Until the first publication, and while the CMS does not know the site yet (a site connected from its repository is built before that), it is the site's initial content; any other refusal of the CMS stops the build. A module that needs the content without importing every page takes it with `loadPublishedContent(schema)` of `@seamlet/astro/site`.
 
 ## Fields
@@ -109,6 +126,7 @@ The site's pages take their published content with `site.loadPublishedContent()`
 | `number({ label, min?, max? })`            | a number                                                                | `null`           |
 | `date({ label })`                          | `YYYY-MM-DD`                                                            | `null`           |
 | `time({ label })`                          | `HH:MM`, 00:00 to 23:59                                                 | `null`           |
+| `slug({ label })`                          | the address of a record's page, `latte` in `/menu/latte` (below)        | `""`             |
 | `image({ label })`                         | `{ src, alt }`                                                          | `null`           |
 | `link({ label })`                          | `{ text, href }`: a page of the site, another site, a phone or an email | `null`           |
 | `url({ label })`                           | a web address without a text: a booking widget, a map                   | `null`           |
@@ -239,6 +257,70 @@ const schema = defineSchema({
 
 A reference to a record removed since is kept, with the issue `missing-record`: the content is not saved until the person picks another one or clears it.
 
+## Pages of records
+
+A collection can have a page for each of its records: a product, a dish, an article. The site writes one component, and the owner who adds a record in the CMS gets its page, which the CMS's editor opens and edits like any other page (a CMS that reads descriptions of version 1.1, as cms.seamlet.ru does from its release 1.1.0). `recordPages` names the collection and the address of its pages, `[record]` standing for the record:
+
+```ts
+// src/schema.ts
+import { recordPages, slug } from "@seamlet/astro/schema";
+
+export const schema = defineSchema({
+  menu: collection({
+    label: "Меню",
+    itemTitle: "name",
+    item: {
+      name: text({ label: "Название" }),
+      price: number({ label: "Цена, ₽", min: 0 }),
+      slug: slug({ label: "Адрес страницы" }),
+    },
+  }),
+});
+
+export const drinkPages = recordPages(schema, {
+  collection: "menu",
+  path: "/menu/[record]",
+});
+```
+
+```ts
+// src/seamlet.ts
+export default defineSeamletSite({
+  schema,
+  initialContent,
+  pages: {
+    "/": { title: "Главная", component: HomePage },
+    "/menu": { title: "Меню", component: MenuPage },
+  },
+  recordPages: [{ pages: drinkPages, component: DrinkPage }],
+});
+```
+
+The component takes the content, the record and its place in its collection as `content`, `record` and `index`, so its markers point at the record's fields:
+
+```astro
+---
+// src/components/DrinkPage.astro
+import { editable } from "@seamlet/astro/schema";
+import type { Content } from "../schema";
+
+interface Props {
+  content: Content;
+  record: Content["menu"][number];
+  index: number;
+}
+
+const { record, index } = Astro.props;
+const edit = editable<Content>();
+---
+
+<h1 {...edit("menu", index, "name")}>{record.name}</h1>
+```
+
+`drinkPages.pathOf(drink)` gives the address of a record's page for a link to it: `/menu/latte`. The address is the record's `slug` when it has one, a field the owner fills in (lower-case Latin letters, digits and hyphens; the CMS spells it from the record's name), and its id otherwise, so a record has its page from the moment it is added, and keeps it when it is renamed or moved. A slug another record of the collection has, as its slug or as its id, is the issue `taken-slug`; a slug with other characters, `invalid-slug`. A collection is `catalog.products` through groups, its pages have one segment more than a page of the site (`/catalog/[record]`, never `/[record]`), a record has one page, and no page of the site may stand among the pages of records (`/menu/specials` beside `/menu/[record]`). `searchTexts` names a group of the record with a `title` and a `description` text for its page.
+
+Every record of the initial content needs an address of its own, a slug or an id, since its page is built before the CMS saves anything. The preview shows a page of a record the owner has just added, so the editor opens it before it is saved or published: under the pages of records, an address that could be an id and names no record shows a blank record, which the editor's draft replaces at once.
+
 ## What the page hides
 
 A field is edited where it is seen, so the editor opens what hides it when a person chooses it in the list of fields. A native `<details>` needs nothing: a click on its summary opens it in the editor too. Neither do tabs, filters and toggles made of radio buttons and checkboxes and shown with CSS: a click on one or its label flips it in the editor, and the page keeps it flipped after every edit. A part the site hides and shows by itself (its own accordion, a step of a quiz, a dialog, a tab) gets the attribute `data-cms-reveal` (`REVEAL_ATTRIBUTE`). When a field inside it is chosen, the bridge sets `data-cms-revealed` on it and sends it the event `cms:reveal`, which bubbles; the site shows the part with CSS or with its own script:
@@ -253,7 +335,7 @@ What was opened stays open while the page is rendered anew after every edit: a p
 
 ## What the integration adds
 
-- `/preview` and `/preview/<page>`: the preview the CMS's editor frames. `GET` shows the published content; `POST` with the content as JSON shows that content without saving it, which is how the editor shows every edit at once. Only the CMS may frame it (`Content-Security-Policy: frame-ancestors`), and it is never indexed or cached; its refusals (a page the site does not have, a draft that is not JSON or is over 1 MB) say the same.
+- `/preview` and `/preview/<page>`: the preview the CMS's editor frames, the pages of records too (at their address or at the record's id). `GET` shows the published content; `POST` with the content as JSON shows that content without saving it, which is how the editor shows every edit at once. Only the CMS may frame it (`Content-Security-Policy: frame-ancestors`), and it is never indexed or cached; its refusals (an address of no page, a record a draft does not have, a draft that is not JSON or is over 1 MB) say the same.
 - The bridge on the preview: it tells the editor where the marked elements are and what a person does on the page, and types texts in place, formatted ones too.
 - `/seamlet/site.json`: what the site tells the CMS about itself (`SITE_DESCRIPTION_PATH`): its id and name from `seamlet.json`, its schema, the content it starts with and its pages. The CMS reads it with `readSiteDescription` whenever the site is opened in its editor.
 - `/seamlet-photos/<address>`: the site's own photo at an address its content gives it, found by `photos` of `defineSeamletSite`, for the CMS's editor.

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
-import { F as Fields } from './parse-content-Eg8yRq_t.js';
-import { P as PageMessage, E as EditorMessage } from './messages-CvZhLRSE.js';
+import { F as Fields } from './parse-content-IOJxgKLB.js';
+import { P as PageMessage, E as EditorMessage } from './messages-Bqgs_mic.js';
 
 interface BridgeOptions {
     /** The origin of the CMS whose editor may frame the page, such as `https://cms.example.com`. */

package/dist/bridge.js

@@ -18,7 +18,7 @@ import {
   shortcutOf,
   toggleList,
   toggleMark
-} from "./chunk-SSECNMAD.js";
+} from "./chunk-PLNPM2D3.js";
 import {
   FIELD_PATH_ATTRIBUTE,
   REVEALED_ATTRIBUTE,
@@ -28,7 +28,7 @@ import {
   readRichText,
   resolveFieldPath,
   safeHref
-} from "./chunk-ZS32CW5F.js";
+} from "./chunk-I3HOJE3S.js";
 
 // src/bridge/typed-fields.ts
 function typedKindAt(schema, path) {
@@ -42,6 +42,7 @@ function typedKindAt(schema, path) {
     case "number":
     case "date":
     case "time":
+    case "slug":
     case "image":
     case "link":
     case "url":

package/dist/chunk-G6Z44LGA.js

@@ -0,0 +1,67 @@
+import {
+  HOME_PAGE_PATH,
+  PAGE_PATH_SEPARATOR,
+  collectionAt,
+  recordAddressOf,
+  recordAt,
+  recordPageAt,
+  recordPagePath
+} from "./chunk-I3HOJE3S.js";
+
+// src/site-pages.ts
+function pagePathOf(rest) {
+  return rest === void 0 ? HOME_PAGE_PATH : `${PAGE_PATH_SEPARATOR}${rest}`;
+}
+function pageParameterOf(path) {
+  return path === HOME_PAGE_PATH ? void 0 : path.slice(PAGE_PATH_SEPARATOR.length);
+}
+function renderedPageAt(site, path, content) {
+  const page = Object.hasOwn(site.pages, path) ? site.pages[path] : void 0;
+  if (page !== void 0) {
+    return { component: page.component, props: { content } };
+  }
+  return renderedRecordPageAt(site, path, content);
+}
+function staticPagesOf(site, content) {
+  const ownPages = Object.entries(site.pages).map(
+    ([path, page]) => staticPage(path, { component: page.component, props: { content } })
+  );
+  const recordPages = site.recordPages.flatMap(
+    (recordPage) => staticRecordPagesOf(site.schema, recordPage, content)
+  );
+  return [...ownPages, ...recordPages];
+}
+function renderedRecordPageAt(site, path, content) {
+  const described = site.recordPages.map((recordPage) => ({
+    ...recordPage.pages,
+    component: recordPage.component
+  }));
+  const found = recordPageAt(described, path);
+  if (found === void 0) return void 0;
+  const records = collectionAt(site.schema, content, found.page.collection);
+  if (records === void 0) return void 0;
+  const placed = recordAt(records.collection, records.records, found.address);
+  if (placed === void 0) return void 0;
+  const props = { content, record: placed.record, index: placed.index };
+  return { component: found.page.component, props };
+}
+function staticRecordPagesOf(schema, recordPage, content) {
+  const found = collectionAt(schema, content, recordPage.pages.collection);
+  if (found === void 0) return [];
+  return found.records.flatMap((record, index) => {
+    const address = recordAddressOf(found.collection, record);
+    if (address === void 0) return [];
+    const path = recordPagePath(recordPage.pages.path, address);
+    const props = { content, record, index };
+    return [staticPage(path, { component: recordPage.component, props })];
+  });
+}
+function staticPage(path, page) {
+  return { params: { page: pageParameterOf(path) }, props: page };
+}
+
+export {
+  pagePathOf,
+  renderedPageAt,
+  staticPagesOf
+};