smoodly 0.0.60 → 0.0.61

package/docs/content-modeling/changing-schemas.md

@@ -0,0 +1,79 @@
+# When the schema changes
+
+Sites change after launch: a section goes, a field is renamed, a zone gets stricter. This page covers what stored content keeps when the code moves on, how the admin shows it, and what Publish refuses until an editor fixes it.
+
+## What a change leaves behind
+
+Smoodly never rewrites stored content when you deploy. A page, an entry or a global keeps what it held, and the admin compares it with the code you deployed. What it finds falls into two kinds: **broken** content blocks the next publish, **left over** content is only reported.
+
+| Change | What stays stored | Publish |
+| --- | --- | --- |
+| `Remove a section` | Every placed copy of it. The canvas shows a placeholder; the site renders nothing for it. | Refused |
+| `Rename or remove a field` | The old key and its value. The admin lists it under No longer in the schema; the new field starts empty. | Allowed, unless the new field is required: then Required until it is filled |
+| `Change a field's type` | The old value. When it doesn't fit the new type, such as text in f.number(), the field shows an error. | Refused when it doesn't fit |
+| `Remove a select option` | The value. It no longer fits the field. | Refused |
+| `Tighten a zone` | Sections the zone no longer allows, and sections over its .max(). | Refused |
+| `Remove a zone from a page type` | The zone's sections, no longer shown. | Allowed |
+| `Remove an element` | Every copy of it inside richtext. Its card in the editor says the code no longer registers it. | Refused |
+| `Drop an element from a toolset` | Every copy of it. It still renders, because a toolset only decides what editors can insert. | Allowed |
+| `Remove a page type` | Its pages. The canvas shows the site's 404 until the page gets another type. | Refused |
+| `Remove a collection` | Its entries. The admin has no editor for them, so register it again or delete them. | No editor |
+| `Toggle .localized()` | Every value. See Localized fields. | Allowed |
+
+An empty value always fits: a new required field on old content is a *Required* error, as it is for new content.
+
+## Content health
+
+*Settings › Content health* lists every page, entry and global that doesn't match the code. Every member can open it, because editors do most of the fixing. It checks when it opens and when you press *Rescan*.
+
+Findings come in two sections, *Blocks publishing* and *Left over*. Each group is one change you made, like "Field `title` no longer in section `hero`", with the documents it touches under it. A row names the document, its languages and where the problem sits:
+
+- *Draft* only: the next publish will be refused until it is fixed.
+- *Live* only: the site runs on content the code no longer describes, and the draft is already fixed. Publishing clears it.
+- Both: fix it in the draft, then publish.
+
+*Open* goes to the document's editor. The page only points; fixes happen in the editors.
+
+## In the editor
+
+A document with findings shows a notice under the top bar: "2 problems block publishing · 1 left over from an older schema". The page editor marks each affected section in the *Page Outline*, red for broken and grey for left over, and the fixes are where the problems are:
+
+- **An unknown section** shows as a placeholder on the canvas. Select it to see its stored values, each with *Copy*, and *Remove section*.
+- **A value that doesn't fit** is an error on its field. Typing a new value replaces it.
+- **Left-over keys** sit in a collapsed *No longer in the schema* group at the foot of the form, each with *Copy* and *Clear*.
+- **A removed zone** is listed after the real zones with *Clear zone*.
+
+Every fix is an ordinary draft edit: it autosaves, and *Discard changes* or the history undoes it.
+
+## What Publish refuses
+
+Publish refuses broken content with the problems listed, the same way it refuses an empty required field. Left-over content never blocks it. The check runs on the server, so an editor can't publish around it.
+
+Live pages are not rewritten. After a deploy the stored live version stays as it was, and a section the code no longer registers renders nothing on the site. The next publish takes the fixed draft live.
+
+## Renaming a field
+
+Rename a field in two steps, so no editor loses a value. First put the new field in the schema where the old one was, and deploy:
+
+File: `components/elements/Callout.schema.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+
+export const calloutSchema = smoodly.schema.section({
+  name: "callout",
+  title: "Callout",
+  fields: {
+    // was `title`: stored values stay under the old key until an editor moves them
+    heading: f.text(),
+  },
+});
+```
+
+Then, for each page *Content health* lists under "Field `title` no longer in section `callout`": copy the value from the *No longer in the schema* group into *Heading*, *Clear* the old key and publish.
+
+There is no bulk rename in the admin yet. A tool that rewrote every page at once could break every live page with one wrong mapping, so its shape is still an open question. For many pages, a script can do it for your own site: walk `pages.list()`, read each page with `getTree`, move the value, write it back with `setTree` and publish, as [Content from code](../getting-started/content-from-code.md) shows. Until it runs, a required field under the new name renders empty on the live site; nothing warns a visitor.
+
+A rename also fails the type check wherever code writes the old name (`npx tsc --noEmit`; `npx astro check` on Astro, whose `astro build` does not type-check; a dev server or a build pushes the renamed schema to the space when it starts), such as the starter's `scripts/seed.ts`: its `node()` calls are typed from the section. The seed has already run, so update the name there or delete the script.
+
+Next, [Localized fields](../languages/localized-fields.md).

package/docs/content-modeling/custom-section.md

@@ -0,0 +1,94 @@
+# The custom section
+
+The one section editors lay out themselves: rows of richtext columns on a 12-column grid, offered where a zone allows it. You turn it on, pick what its columns may hold, and style the result; Smoodly owns the grid.
+
+To write a section of your own in code, see [Sections](../content-modeling/sections.md).
+
+## Turning it on
+
+A zone offers the custom section when its policy says so. The starter's body zones do:
+
+File: `components/pages/Home.schema.ts`
+
+```ts
+  zones: {
+    hero: z.locked(heroSchema),
+    body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
+  },
+```
+
+Only `z.freeform()` takes `custom: true`. *Custom section* then appears in *Add section* after the listed sections.
+
+What a column may hold comes from the config's toolset. The starter gives the columns its article toolset, so a column can hold headings, lists, images and the two elements:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  custom: { toolset: article },
+});
+```
+
+**Astro**
+
+The columns render through the package's own richtext view, with images through Astro's image service and your elements by file name. There is nothing to bind.
+
+**Next.js**
+
+`smoodly/views.ts` binds the richtext renderer, so images render through the site's image component:
+
+File: `smoodly/views.ts`
+
+```ts
+export const views = () =>
+  defineViews(config, {
+    // …
+    RichText,
+  });
+```
+
+Without `custom` in the config, the columns take the richtext default plus images. `breakpoint` sets where rows stack; the default is `48rem`.
+
+## What editors get
+
+A new custom section is one row with one column. Each row is a card in the inspector:
+
+| Name | Description |
+| --- | --- |
+| `Columns` | A stepper from one to six. Removing a column folds its content into the last one, so nothing is lost. |
+| `Widths` | A bar dragged in twelfths, with presets such as 1/2 · 1/2 and 1/3 · 2/3. Spans always add up to 12. |
+| `Gap` | S, M or L between the columns. |
+| `Vertical align` | Top, Center, Bottom or Stretch. |
+| `Reverse on mobile` | Flips the column order when the row stacks, so a photo can sit right on desktop and first on a phone. |
+| `Column 1, Column 2, …` | A richtext editor per column, with the toolset from the config. |
+
+Rows move up and down, and a section keeps at least one. In the canvas the section is labeled by its first row, *Custom section · 2 columns*, and clicking a column reveals its editor in the inspector. Like any section it has *Spacing & layout* and, when the config allows, *Custom CSS* on its Settings tab.
+
+## How it renders
+
+The section renders through the same wrapper as yours, so spacing, width, selection and the CSS box come free. Smoodly adds one scoped style per custom section, computed from the stored numbers only:
+
+- Each row is a grid, `.smd-row`, with its spans as `fr` tracks, its gap and its vertical alignment. Rows sit 2rem apart.
+- A row's width is `var(--smd-width, var(--container, none))`, with `var(--smd-gutter, 1rem)` at the sides, so define `--container` and `--smd-gutter` once and rows line up with your other sections.
+- Below the breakpoint every row stacks to one column, and a reversed row stacks bottom-up.
+
+Your stylesheet styles the content. Each column is a `.smd-col`; the starter gives it the same rules as its prose:
+
+File: `app/globals.css`
+
+```css
+/* The custom section's columns (.smd-col) read like prose. */
+.prose, .smd-col { display: flex; flex-direction: column; gap: 20px; font-size: 17px; line-height: 1.65; color: var(--muted); }
+.prose h2, .smd-col h2 { font-size: 32px; margin-top: 8px; }
+```
+
+Nothing else is required: a site with no rules for `.smd-col` still gets working columns.
+
+## What it cannot do
+
+A column holds richtext: text, headings, lists, images and elements. It never holds a section or another row, so the nesting stays one level deep and the canvas, drag and drop and history keep working. A layout that needs more than columns of text is a section you write.
+
+At publish, Smoodly checks that each row has one to six columns and that its spans add up to 12. An empty column is allowed; it is spacing.
+
+Next, [Marks and inline editing](../content-modeling/marks.md) explains how the canvas knows what to make click-to-edit.

package/docs/content-modeling/marks.md

@@ -0,0 +1,97 @@
+# Marks and inline editing
+
+Marks are the attributes a section spreads on the elements that render its fields. They tell the canvas which field an editor clicked, so text edits in place and everything else opens in the inspector.
+
+## What a mark is
+
+`smoodly.marks(heroSchema)` returns typed helpers for one schema. `m.field("heading")` is an object with one `data-` attribute naming the field; spread it on the element that renders the heading. The section root, rendered by Smoodly's section wrapper, carries the section's own id. From a click the canvas walks up from the marked element to that root and knows which field of which section was meant.
+
+Outside the admin the marks are plain data attributes and do nothing. The typed helpers exist so a renamed field is a type error rather than a dead click.
+
+## Marking a field
+
+Put the mark on the element that shows the value as stored:
+
+**Astro**
+
+File: `src/sections/hero.astro`
+
+```astro
+---
+// …
+const m = smoodly.marks(heroSchema);
+---
+// …
+      {kicker && <p class="kicker" {...m.field("kicker")}>{kicker}</p>}
+      <h1 class="hero__heading" {...m.field("heading")}>{heading}</h1>
+      <p class="hero__text" {...m.field("text")}>{text}</p>
+      // …
+    {image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+**Next.js**
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+const m = smoodly.marks(heroSchema);
+// …
+          {kicker && <p className="kicker" {...m.field("kicker")}>{kicker}</p>}
+          <h1 className="hero__heading" {...m.field("heading")}>{heading}</h1>
+          <p className="hero__text" {...m.field("text")}>{text}</p>
+// …
+        {image && <SmoodlyImage image={image} className="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+Hovering a marked element outlines it in the canvas. What a click does depends on the field:
+
+| Field | On click |
+| --- | --- |
+| `f.text()` | Edits in place. The element becomes editable, and each keystroke updates the draft. Escape or a click elsewhere ends it. |
+| `f.richtext()` | Edits in place, with the richtext toolbar floating above the selection. |
+| `Everything else` | Opens the inspector on that field: the media picker for an image, the repeater for a list, the pills for a choice. |
+
+In-place text editing needs an element with nothing but text inside. A mark on an element with child elements, such as a paragraph holding a link, falls through to the inspector. So does a mark on an element that shows the value transformed, in effect: the canvas would write the stored value over the formatted one. Leave a formatted date unmarked, or mark its container.
+
+The image component passes data attributes to its wrapper, so a mark on it selects the image box.
+
+## Lists and objects
+
+A list item or an object field is a scope of its own. `m.item("buttons", i)` returns a helper for one item: spread its `attrs` on the item's root element and use its `field()` for the fields inside. The starter's Hero buttons put both on the same anchor:
+
+**Astro**
+
+File: `src/sections/hero.astro`
+
+```astro
+          {buttons.map((b, i) => {
+            const button = m.item("buttons", i);
+            return <a class={i === 0 ? "button" : "button button--outline"} href={safeHref(b.href)} {...button.attrs} {...button.field("label")}>{b.label}</a>;
+          })}
+```
+
+**Next.js**
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+              {buttons.map((b, i) => {
+                const button = m.item("buttons", i);
+                return (
+                  <a key={i} className={i === 0 ? "button" : "button button--outline"} href={b.href}
+                    {...button.attrs} {...button.field("label")}>{b.label}</a>
+                );
+              })}
+```
+
+`m.object("link")` works the same way for an object field. A scope nests: `m.item("points", i).object("author")` reaches a field inside an object inside a list item.
+
+A mark for the whole list, such as `m.field("people")` on the grid that renders a reference list, opens the list in the inspector.
+
+## What the canvas checks
+
+A click on a mark that names a field the schema does not have logs a warning in development, naming the section and the path, and then does nothing. Check the `data-smd-field` and `data-smd-item` attributes it names.
+
+Globals in the canvas, such as the starter's header, footer and quote, are marked the same way. Selecting one shows its own fields in the inspector, tagged *global*, with its own *Publish*, because publishing a footer to every page is a deliberate click. [Globals](../globals/defining.md) has the details.
+
+Next, the [Fields](../fields/overview.md) group lists every field type and what editors see for each.

package/docs/content-modeling/overview.md

@@ -0,0 +1,55 @@
+# Modeling content
+
+The five things you register, what each one holds, and where it lives in your project. Read this once; the rest of the group takes them one at a time.
+
+## Registration is the model
+
+Smoodly has no schema screens. Each schema sits in a file beside the component that renders it, is paired with that view, and is listed once in `smoodly/config.ts`. From that one definition Smoodly derives the editor form, the entry in *Add section*, the TypeScript props and the checks it runs at publish.
+
+Change a field in code and the form changes with it. Nothing an editor does changes the code: editors fill fields and arrange sections inside the limits you set.
+
+## The five types
+
+| Type | Registered with | What it is |
+| --- | --- | --- |
+| `Page type` | smoodly.page() | A page component. It declares zones and renders them among your own JSX. Editors pick one when they create a page. |
+| `Section` | smoodly.section() | A full-width component editors place in a zone: a hero, a row of cards, a quote. |
+| `Element` | smoodly.element() | A small component editors insert inside richtext: a callout, a call to action. |
+| `Collection` | smoodly.collection() | A content type with a fixed shape and many entries: posts, people. An entry page, smoodly.entryPage(), renders one entry at its own URL. |
+| `Global` | smoodly.global() | Content that exists once and appears on many pages: the header, the footer, contact details. |
+
+The custom section is the sixth piece and is built in: rows of richtext columns editors lay out themselves, offered only where a zone allows it.
+
+In the Lorem Co. starter that is nine sections, four page types, two entry pages, three collections, four globals and two elements. Page types, sections and elements live in `components/`, two files each: the schema and the view. Collections and globals are lists in `smoodly/collections.ts` and `smoodly/globals.ts`.
+
+## How they nest
+
+Containment is short and fixed:
+
+```
+Page type → zone → section
+                 → custom section → rows → columns of richtext → elements
+```
+
+A section never holds another section. A section that needs columns builds them in code, and editors who need a free layout get the custom section. That cap is what keeps drag and drop, rendering and the canvas simple.
+
+Around the zones, a page type renders whatever JSX you like: navigation, a grid of the newest posts, a form. That JSX shows in the canvas but is not selectable, so it stays yours.
+
+## Content, settings and styles
+
+Everything editors change is stored per page, in three groups:
+
+- **Fields** are content: the heading, the photo, the list of buttons. They can be localized.
+- **Settings** are the options you declare on a section for how it looks, like which side the image sits on. The view alone interprets them.
+- **Styles** are Smoodly's own spacing, width and alignment steps, offered on every section unless you turn them off.
+
+Editors see fields on the *Content* tab and the other two on the *Settings* tab.
+
+## Reading order
+
+1. [Sections](../content-modeling/sections.md): a schema, a view, marks and registration.
+2. [Page types](../content-modeling/page-types.md): zones, fixed and open pages, the page prop.
+3. [Zones and freedom](../content-modeling/zones.md): the three zone policies.
+4. [Settings, styles and CSS](../content-modeling/styles-and-settings.md), [The custom section](../content-modeling/custom-section.md) and [Marks and inline editing](../content-modeling/marks.md).
+
+Then [Fields](../fields/overview.md) for every field type, and [Collections](../collections/defining.md) and [Globals](../globals/defining.md) for the two types that live outside pages.

package/docs/content-modeling/page-types.md

@@ -0,0 +1,237 @@
+# Defining a page type
+
+A page type is a page component with zones: the places where editors add sections. This page walks through the Lorem Co. starter's Home and Page types, and what a page type learns about its place in the site.
+
+## The schema
+
+A page type starts with `smoodly.schema.page()`: a name, a title, and a `zones` map that gives each zone a policy. The schema is the same file in every framework; in an Astro project it lives under `src/components/pages/`.
+
+File: `components/pages/Home.schema.ts`
+
+```ts
+import { smoodly, z } from "smoodly";
+import { heroSchema } from "../sections/Hero.schema";
+// …
+export const homeSchema = smoodly.schema.page({
+  name: "home",
+  title: "Home",
+  slug: "home",
+  zones: {
+    hero: z.locked(heroSchema),
+    body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
+  },
+  seo: true,
+});
+```
+
+| Name | Description |
+| --- | --- |
+| `name` | What a page record stores as its type. Keep it stable once pages exist. |
+| `title` | What editors see in the Page type column and when they create a page. |
+| `slug` | Makes the page type fixed: one page, at this URL. Leave it out and editors create as many as they like. See below. |
+| `zones` | One entry per zone, each with a policy from z. Zones and freedom covers the three. |
+| `seo` | `true` gives the page an SEO & Social tab: title, description, social image and a switch to hide it from search engines. |
+| `fields` | The page type's own fields, edited on the page's Settings tab. See below. |
+
+## The view
+
+**Astro**
+
+The view is `src/page-types/home.astro`, named after the schema. It receives `page`, `zones` and `head`. Render each zone with `<Zone>` wherever it belongs, among your own markup:
+
+File: `src/page-types/home.astro`
+
+```astro
+---
+import { Zone } from "smoodly/astro/components";
+// …
+const { page, zones, head } = Astro.props;
+---
+<Layout head={head} locale={page.locale} locales={page.locales}>
+  <Zone of={zones.hero} />
+  <Zone of={zones.body} />
+</Layout>
+```
+
+`Layout` is the starter's own component: the document, the site header and footer. Anything you render around the zones shows in the canvas but cannot be selected, so editors cannot move or remove it. `head` is what `Head` writes into the document head: the title, the canonical link and the rest.
+
+Register the schema in the `pages` list of `src/smoodly/config.ts`; the view is the file, with nothing else to list:
+
+File: `src/smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  registry: {
+    sections,
+    // …
+    pages: [homeSchema, articlesSchema, pageSchema, newsSchema],
+  },
+  // …
+});
+```
+
+**Next.js**
+
+The view lives beside the schema, in `Home.tsx`. It receives `zones` and `page`. Render each zone with `<Zone>` wherever it belongs, among your own JSX:
+
+File: `components/pages/Home.tsx`
+
+```tsx
+function HomeView({ zones, page }: Props<typeof homeSchema>) {
+  return (
+    <PageFrame locale={page.locale} locales={page.locales}>
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+    </PageFrame>
+  );
+}
+
+export const HomePage = smoodly.page(homeSchema, HomeView);
+```
+
+`PageFrame` is the starter's own component: the site header and a `main` element. Anything you render around the zones shows in the canvas but cannot be selected, so editors cannot move or remove it.
+
+Register the schema in the `pages` list of `smoodly/config.ts`, and the component in `pages` in `smoodly/views.ts`:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  registry: {
+    sections,
+    // …
+    pages: [homeSchema, articlesSchema, pageSchema, newsSchema],
+  },
+  // …
+});
+```
+
+File: `smoodly/views.ts`
+
+```ts
+export const views = () =>
+  defineViews(config, {
+    // …
+    pages: [HomePage, ArticlesPage, StandardPage, ArticlePage, NewsPage, NewsPostPage],
+    // …
+  });
+```
+
+## Fixed and open
+
+A page type with a `slug` is **fixed**: it owns exactly one page, at that URL, in every language. Smoodly creates the page the first time the admin loads, so a fresh site has a home page before anyone signs in. Editors can edit it but never create another, rename it, move it or delete it. The slug `home` is special: `homePageSlug` in `defineConfig()` names it, and that page is served at `/`.
+
+A fixed slug can differ per language. The starter's Articles index sits at `/posts` in English and `/artikkelit` in Finnish:
+
+File: `components/pages/Articles.schema.ts`
+
+```ts
+export const articlesSchema = smoodly.schema.page({
+  name: "articlesIndex",
+  title: "Articles",
+  slug: { en: "posts", fi: "artikkelit" },
+  zones: {
+    hero: z.locked(pageHeroSchema),
+  },
+  seo: true,
+});
+```
+
+A page type without a `slug` is **open**: editors create as many pages of it as they like, anywhere the page tree allows. When they click *+ New page*, the admin asks which open page type to use. With one open type, as in the starter, it does not ask.
+
+Lorem Co. has three fixed types, Home, Articles and News, and one open type, Page. A fixed page is live as soon as its code is deployed, with empty zones until an editor fills them. Its row appears in *Pages* the next time someone opens the admin. Article and News post are [entry pages](../collections/entry-pages.md), which render one entry each.
+
+## The page prop
+
+`page` tells the view where the page sits, so breadcrumbs and sub-navigation need no query:
+
+| Name | Description |
+| --- | --- |
+| `page.title, page.locale` | The page's title and the language it is rendered in. |
+| `page.path, page.url` | The page's URL within the site, and the same address through your framework's locale routing. On a single-language site they are equal. |
+| `page.ancestors` | Links to the pages above it, root first. |
+| `page.children` | Links to the pages below it. |
+| `page.locales` | One key per language: the page's address there, or null where it does not exist or is unpublished. What a language switcher links to. |
+| `page.fields` | The page type's own fields, typed from the schema. |
+
+Each link carries `title`, `path`, `url`, `hasPage` and `fields`. A path in the page tree, which groups pages without being one, has `hasPage` false. The starter's Page type uses both lists:
+
+**Astro**
+
+File: `src/page-types/page.astro`
+
+```astro
+---
+// …
+const shown = page.children.filter((c) => c.hasPage && c.fields.showInNavigation === true);
+---
+<Layout head={head} locale={page.locale} locales={page.locales}>
+  {page.ancestors.length > 0 && (
+    <nav class="container breadcrumb" aria-label="Breadcrumb">
+      {page.ancestors.map((a) => <span>{a.hasPage ? <a href={a.url}>{a.title}</a> : a.title} / </span>)}
+      {page.title}
+    </nav>
+  )}
+  {shown.length > 0 && (
+    <nav class="container subnav" aria-label="Pages in this section">
+      {shown.map((c) => <a href={c.url}>{c.title}</a>)}
+    </nav>
+  )}
+  <Zone of={zones.hero} />
+  <Zone of={zones.body} />
+</Layout>
+```
+
+**Next.js**
+
+File: `components/pages/Page.tsx`
+
+```tsx
+function PageView({ zones, page }: Props<typeof pageSchema>) {
+  const shown = page.children.filter((c) => c.hasPage && c.fields.showInNavigation === true);
+  return (
+    <PageFrame locale={page.locale} locales={page.locales}>
+      {page.ancestors.length > 0 && (
+        <nav className="container breadcrumb" aria-label="Breadcrumb">
+          {page.ancestors.map((a) => (
+            <span key={a.path}>{a.hasPage ? <Link href={a.url}>{a.title}</Link> : a.title} / </span>
+          ))}
+          {page.title}
+        </nav>
+      )}
+      {shown.length > 0 && (
+        <nav className="container subnav" aria-label="Pages in this section">
+          {shown.map((c) => <Link key={c.path} href={c.url}>{c.title}</Link>)}
+        </nav>
+      )}
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+    </PageFrame>
+  );
+}
+```
+
+## Page fields
+
+A page type can declare fields of its own, for values that belong to the page rather than to a section. The starter's Page type has one:
+
+File: `components/pages/Page.schema.ts`
+
+```ts
+export const pageSchema = smoodly.schema.page({
+  name: "page",
+  title: "Page",
+  zones: {
+    hero: z.locked(pageHeroSchema),
+    body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
+  },
+  seo: true,
+  fields: { showInNavigation: f.boolean().default(true) },
+});
+```
+
+Editors find it on the page's *Settings* tab, next to the title and slug. The view reads it as `page.fields.showInNavigation`, and every link in `ancestors` and `children` carries the linked page's fields, which is how the sub-navigation above filters without a query.
+
+Page fields are a settings form, not content: text, link, date, number, boolean, the choice fields, tags, media and objects. Refs, lists and richtext are not allowed, and `.localized()` is not needed because page fields are already stored per language.
+
+Next, [Zones and freedom](../content-modeling/zones.md) explains the three policies a zone can have.