smoodly 0.0.59 → 0.0.61

package/docs/content-modeling/sections.md

@@ -0,0 +1,264 @@
+# Defining a section
+
+A section is a full-width component editors place in a zone. You describe its fields once, in a schema file, and Smoodly derives the editor form, the Add section entry and the TypeScript props from that one definition. This page walks through the Lorem Co. starter's Hero.
+
+## The schema
+
+A section is two files. `Hero.schema.ts` holds the schema: `smoodly.schema.section()` with a name, the title editors see, and a `fields` map built from the `f` helpers. The view, below, renders it. The schema is the same file in every framework; in an Astro project it lives under `src/components/sections/`.
+
+File: `components/sections/Hero.schema.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+
+export const heroSchema = smoodly.schema.section({
+  name: "hero",
+  title: "Hero",
+  description: "The home page opener: heading, text, buttons and a photo.",
+  fields: {
+    kicker: f.text().optional(),
+    heading: f.text(),
+    text: f.text(),
+    buttons: f.list(f.object({ label: f.text(), href: f.link() })).max(2),
+    image: f.image({ aspect: "4:5" }),
+  },
+  sample: {
+    // …
+  },
+});
+```
+
+| Name | Description |
+| --- | --- |
+| `name` | What the content stores for every placed Hero, so keep it stable once pages exist. |
+| `title` | The label in Add section and in the inspector. |
+| `description` | One line under the title in Add section. Optional, like icon. |
+| `fields` | What editors fill. Field order is form order: editors see Kicker, Heading, Text, Buttons, Image, top to bottom. |
+| `sample` | What a new Hero starts with. See Sample content below. |
+
+Every field is required unless it chains `.optional()`. `.max()` and `.min()` limit a length or a count, `.default()` sets a starting value, and `.localized()` gives a field its own value per language. The full list is on [All fields](../fields/overview.md).
+
+## The view
+
+**Astro**
+
+The view is an `.astro` file named after the schema: `src/sections/hero.astro` renders the section named `hero`. It imports the schema, and `Props<typeof heroSchema>` types `Astro.props`: the fields flat, plus `settings` and `styles`.
+
+File: `src/sections/hero.astro`
+
+```astro
+---
+import { safeHref, smoodly, type Props as SmoodlyProps } from "smoodly";
+import { Image, Section } from "smoodly/astro/components";
+import { heroSchema } from "@/components/sections/Hero.schema";
+
+type Props = SmoodlyProps<typeof heroSchema>;
+const { kicker, heading, text, buttons, image, styles } = Astro.props;
+const m = smoodly.marks(heroSchema);
+---
+<Section styles={styles} class="hero">
+  // …
+      <h1 class="hero__heading" {...m.field("heading")}>{heading}</h1>
+      // …
+          {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>;
+          })}
+      // …
+    {image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+  // …
+</Section>
+```
+
+Three things make this a section rather than a plain component:
+
+- **`Section` is the root element.** It comes from `smoodly/astro/components`. Pass it `styles`, and it renders the spacing and width steps an editor picks, plus the attribute the canvas uses to select the section. `as="header"` changes the tag; `class`, `id` and `data-` attributes pass through. The section's own CSS is yours, in `src/styles/global.css` like the starter's.
+- **Marks make fields click-to-edit.** `smoodly.marks(heroSchema)` returns typed helpers. Spread `m.field("heading")` on the element that renders the heading, and clicking it in the canvas opens that field. For a list, `m.item("buttons", i)` gives a scope: spread its `attrs` on the item's root and mark the fields inside with `field()`. `m.object()` does the same for an object field. Outside the admin the marks are plain `data-` attributes. [Marks and inline editing](../content-modeling/marks.md) has the details.
+- **The file name pairs the two.** There is no pairing line and no list of views. The server names a schema with no file, and a file with no schema, at the first request.
+
+A link an editor typed goes through `safeHref` from `smoodly`: Astro writes an attribute as given, so a `javascript:` URL would reach the page. `safeHref` passes http(s), mailto, tel and site paths, and gives `null` for anything else, so the link renders with no `href`.
+
+**Next.js**
+
+The view is an ordinary React component in `Hero.tsx`, beside the schema. It imports the schema, and `Props<typeof heroSchema>` types it: the fields flat, plus `settings` and `styles`.
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+const m = smoodly.marks(heroSchema);
+
+function HeroView({ kicker, heading, text, buttons, image, styles }: Props<typeof heroSchema>) {
+  return (
+    <smoodly.Section styles={styles} className="hero">
+      <div className="container hero__grid">
+        <div className="hero__copy">
+          {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>
+          {buttons?.length > 0 && (
+            <div className="hero__buttons">
+              {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>
+                );
+              })}
+            </div>
+          )}
+        </div>
+        {image && <SmoodlyImage image={image} className="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+      </div>
+    </smoodly.Section>
+  );
+}
+
+export const Hero = smoodly.section(heroSchema, HeroView);
+```
+
+Three things make this a section rather than a plain component:
+
+- **`smoodly.Section` is the root element.** Pass it `styles`, and it renders the spacing and width steps an editor picks, plus the attribute the canvas uses to select the section. `as="header"` changes the tag; `className`, `id` and `data-` attributes pass through. The section's own CSS is yours, in `app/globals.css` like the starter's.
+- **Marks make fields click-to-edit.** `smoodly.marks(heroSchema)` returns typed helpers. Spread `m.field("heading")` on the element that renders the heading, and clicking it in the canvas opens that field. For a list, `m.item("buttons", i)` gives a scope: spread its `attrs` on the item's root and mark the fields inside with `field()`. `m.object()` does the same for an object field. Outside the admin the marks are plain `data-` attributes. [Marks and inline editing](../content-modeling/marks.md) has the details.
+- **`smoodly.section()` pairs the two.** Rename a field in the schema and this line fails to compile until the view follows. The export is the component you list in `smoodly/views.ts`. It renders as a normal component too, so you can place a section in your own JSX with its fields as props.
+
+### When a section throws
+
+If a section's own code throws, for example on data it didn't expect, the page still renders and that section is left out. The error goes to the server log, and the editor's canvas shows a placeholder in its place. The editor names it too, and Publish asks before a page with a broken section goes live.
+
+**Astro**
+
+The zone renders each section through `Astro.slots.render` inside a try/catch, so a throw anywhere inside the section, a component it renders included, leaves the section out and the page renders.
+
+**Next.js**
+
+`next dev` shows the placeholder too. A throw inside a component the section renders, or in a `'use client'` section, still fails the live page, but in the canvas it is caught and named the same way, so it shows up before anyone publishes.
+
+## Registering it
+
+**Astro**
+
+Add the schema to `src/smoodly/sections.ts`, which the config registers. The view is the file; there is nothing else to list. Editors can place the section only once a zone lists it, which is the next step:
+
+File: `src/smoodly/sections.ts`
+
+```ts
+import { heroSchema } from "@/components/sections/Hero.schema";
+// …
+export const sections = [heroSchema, pageHeroSchema, imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema, headerSchema, footerSchema];
+```
+
+**Next.js**
+
+A section is registered in two lists. Add its schema to `smoodly/sections.ts`, which the config registers, and its component to `sections` in `smoodly/views.ts`. The config imports no component, so the CLI, a seed script and an agent can read your content model without loading React. Editors can place the section only once a zone lists it, which is the next step:
+
+File: `smoodly/sections.ts`
+
+```ts
+import { heroSchema } from "@/components/sections/Hero.schema";
+// …
+export const sections = [heroSchema, pageHeroSchema, imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema, headerSchema, footerSchema];
+```
+
+File: `smoodly/views.ts`
+
+```ts
+import { Hero } from "@/components/sections/Hero";
+// …
+export const views = () =>
+  defineViews(config, {
+    sections: [Hero, PageHero, ImageText, Points, FavouriteArticles, People, Quote, Header, Footer],
+    // …
+  });
+```
+
+A schema with no component in `smoodly/views.ts` stops the first render with a named error: `smoodly: section "hero" is registered in the config but has no view — add its component to defineViews({ sections }).`
+
+Registering makes the section known; a page type's zones decide where editors may use it. Lorem Co.'s home page locks its hero and lets the body take five sections:
+
+File: `components/pages/Home.schema.ts`
+
+```ts
+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 }),
+  },
+  // …
+});
+```
+
+A registered section that no zone lists never appears in *Add section*. Lorem Co.'s Header and Footer are registered that way, because the layout renders them as [globals](../globals/header-and-footer.md). The three policies are on [Zones and freedom](../content-modeling/zones.md).
+
+## Sample content
+
+`sample` is what a section starts with, so a page never shows an empty one. Smoodly uses it twice:
+
+- When an editor picks the section in *Add section*, the new section carries the sample.
+- When a page opens with an empty locked zone, Smoodly fills the zone from the locked section's sample.
+
+Fields the sample leaves out start from their `.default()`, or empty. A missing image or number stays unset rather than showing a broken picture or a stray zero. Make the sample a complete value in plain copy: it is what editors see first, and what they overwrite.
+
+The sample may set settings too, under their own keys.
+
+## Settings
+
+Fields are content. Settings are your own options for how the section looks, which the view alone interprets. Lorem Co.'s *Image and text* lets editors put the photo on either side:
+
+File: `components/sections/ImageText.schema.ts`
+
+```ts
+export const imageTextSchema = smoodly.schema.section({
+  name: "imageText",
+  title: "Image and text",
+  // …
+  settings: {
+    imageSide: f.radio([{ value: "left", label: "Image left" }, { value: "right", label: "Image right" }]).default("left"),
+  },
+  // …
+});
+```
+
+**Astro**
+
+File: `src/sections/imageText.astro`
+
+```astro
+---
+// …
+const { image, heading, text, link, settings, styles } = Astro.props;
+// …
+---
+<Section styles={styles} class="image-text" data-image-side={settings.imageSide}>
+```
+
+**Next.js**
+
+File: `components/sections/ImageText.tsx`
+
+```tsx
+function ImageTextView({ image, heading, text, link, settings, styles }: Props<typeof imageTextSchema>) {
+  // …
+    <smoodly.Section styles={styles} className="image-text" data-image-side={settings.imageSide}>
+```
+
+The view receives `settings` with defaults filled, so `settings.imageSide` is always a value. Settings use the same `f` builders as fields, with one rule: they are never localized, because a layout choice is the same in every language.
+
+In the inspector, fields are on the *Content* tab and settings on the *Settings* tab, above Smoodly's own *Spacing & layout* group. [Settings, styles and CSS](../content-modeling/styles-and-settings.md) covers that group, `styles: false` for a section that should not offer it, and the custom CSS box.
+
+## The fields used here
+
+| Field | Editor sees | Notes |
+| --- | --- | --- |
+| `f.text()` | Single line | .max(n) limits the length in characters. |
+| `f.link()` | Text box | A full URL or a site path such as /company/about-us. |
+| `f.image({ aspect })` | Media picker | Upload or pick from the library, then crop to the aspect for this use. |
+| `f.list(item)` | Repeater | Editors add, reorder and remove items. .min(n) and .max(n) count items; lists cannot nest. |
+| `f.object({ … })` | A group of fields | One value with named parts, such as a button's label and href. |
+| `f.richtext({ toolset })` | Text editor | Formatted text; the toolset decides which formatting and elements it offers. |
+| `f.radio([…])` | Pills | One value from a closed set. f.select([…]) shows the same set as a dropdown. |
+
+Next, [Page types](../content-modeling/page-types.md) shows where zones come from, and [Zones and freedom](../content-modeling/zones.md) how to set each zone's policy.

package/docs/content-modeling/styles-and-settings.md

@@ -0,0 +1,184 @@
+# Settings, styles and CSS
+
+Beyond its fields, a placed section carries three more things editors can change: the settings you declare, Smoodly's own spacing and width steps, and a custom CSS box you can turn on. All three sit on the Settings tab.
+
+## What a section carries
+
+Every section on a page stores four groups of values:
+
+| Group | Who defines it | Where editors find it |
+| --- | --- | --- |
+| `fields` | You, in the schema. The content. | The Content tab. |
+| `settings` | You, in the schema. Options for how the section looks. | The Settings tab, at the top. |
+| `styles` | Smoodly. Spacing, width and alignment steps. | The Settings tab, under Spacing & layout. |
+| `css` | Smoodly, when the config turns it on. A CSS snippet for this one section. | The Settings tab, under Advanced. |
+
+The view receives the first three as props: the fields flat, then `settings` and `styles`. The CSS never reaches the view; the section wrapper renders it.
+
+## Settings
+
+Settings use the same `f` builders as fields. The starter's Quote offers two backgrounds:
+
+File: `components/sections/Quote.schema.ts`
+
+```ts
+export const quoteSchema = smoodly.schema.section({
+  name: "quote",
+  title: "Quote",
+  // …
+  settings: {
+    background: f.radio([{ value: "paper", label: "Paper" }, { value: "ink", label: "Ink" }]).default("paper"),
+  },
+  // …
+});
+```
+
+**Astro**
+
+File: `src/sections/quote.astro`
+
+```astro
+---
+// …
+const { text, attribution, settings, styles } = Astro.props;
+// …
+---
+<Section styles={styles} class="quote" data-background={settings.background}>
+```
+
+**Next.js**
+
+File: `components/sections/Quote.tsx`
+
+```tsx
+function QuoteView({ text, attribution, settings, styles }: Props<typeof quoteSchema>) {
+  return (
+    <smoodly.Section styles={styles} className="quote" data-background={settings.background}>
+```
+
+The view alone interprets a setting. Here it becomes a data attribute that the stylesheet reads; it could as well pick a class or a layout branch. `settings` arrives with defaults filled, so `settings.background` is always one of the two values.
+
+Two rules set settings apart from fields. They are never localized, because a layout choice is the same in every language, and `.localized()` on a setting throws at startup. And a sample may set them under their own keys, next to the fields.
+
+## Hiding a field on a condition
+
+A field or setting can leave the form while a condition holds. A media section that shows either a photo or a video needs only one of its two fields at a time:
+
+**Astro**
+
+The schema goes in `src/components/sections/Media.schema.ts`, written as in the Next.js tab: a schema is the same in every framework. Its view, `src/sections/media.astro`, renders `<Section styles={styles} class="media" data-kind={settings.kind}>` and shows the video or the image by `settings.kind`.
+
+**Next.js**
+
+File: `components/sections/Media.tsx`
+
+```tsx
+import { f, smoodly, type Props } from "smoodly/react";
+
+export const mediaSchema = smoodly.schema.section({
+  name: "media",
+  title: "Media",
+  fields: {
+    image: f.image({ aspect: "16:9" }).hidden(f.when("settings.kind").is("video")),
+    video: f.video().hidden(f.when("settings.kind").is("image")),
+    caption: f.text().optional(),
+  },
+  settings: {
+    kind: f.radio([{ value: "image", label: "Photo" }, { value: "video", label: "Video" }]).default("image"),
+  },
+});
+
+function MediaView({ image, video, caption, settings, styles }: Props<typeof mediaSchema>) {
+  return (
+    <smoodly.Section styles={styles} className="media" data-kind={settings.kind}>
+      {settings.kind === "video" ? <video src={video?.url} controls /> : <img src={image?.url} alt={image?.alt ?? ""} />}
+      {caption && <p className="media__caption">{caption}</p>}
+    </smoodly.Section>
+  );
+}
+
+export const Media = smoodly.section(mediaSchema, MediaView);
+```
+
+`f.when(path)` reads a value and offers `.is()`, `.isNot()`, `.in([…])`, `.isEmpty()` and `.isNotEmpty()`. A bare path names a sibling at the same level, so inside an object or a list item it reads that item. A path prefixed `fields.` or `settings.` reads a top-level key of that group. A hidden field is skipped at publish, and its stored value stays, so switching back restores it. A condition that names a field that does not exist fails at startup, not in the form.
+
+## Smoodly's styles
+
+Every section gets four steps under *Spacing & layout*, whatever its schema says:
+
+| Step | Options | Renders as |
+| --- | --- | --- |
+| `Spacing top, Spacing bottom` | Default · 0 · S · M · L | padding-top and padding-bottom, inline on the section root. |
+| `Width` | Default · Narrow · Wide · Full | The --smd-width variable on the section root; your container reads it. |
+| `Align` | Default · Left · Center · Right | text-align on the section root. |
+
+*Default* stores and renders nothing, so a section looks exactly as you wrote it until an editor reaches for a step. *0* is a real step, because two dark sections meeting need your padding removed, not added. Editors never see pixels or breakpoints.
+
+The config supplies the CSS behind each step. The starter points them at variables its stylesheet defines per breakpoint:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  styles: {
+    spacing: { sm: "var(--space-sm)", md: "var(--space-md)", lg: "var(--space-lg)" },
+    width: { narrow: "var(--width-narrow)", wide: "var(--width-wide)", full: "none" },
+  },
+  // …
+});
+```
+
+File: `app/globals.css`
+
+```css
+:root {
+  --space-sm: 24px; --space-md: 48px; --space-lg: 72px;
+  --width-narrow: 640px; --width-wide: 1440px;
+  --container: 1200px;
+}
+@media (min-width: 768px) { :root { --space-sm: 32px; --space-md: 64px; --space-lg: 96px; } }
+
+/* The container reads the editor's width step; without one, the design's width. */
+.container { max-width: var(--smd-width, var(--container)); width: 100%; margin: 0 auto; padding-inline: 32px; }
+```
+
+Width is a variable rather than a `max-width` on the section, so a section with a background stays full-bleed while its content narrows. Only your container knows it is the container, so give it the rule above. Without a `styles` entry in the config the package's own fallbacks apply.
+
+Two things make the steps work in a view: the root element is Smoodly's section wrapper, and it receives the `styles` prop. A section that renders its own root gets no steps.
+
+**Astro**
+
+The wrapper is `<Section styles={styles}>` from `smoodly/astro/components`.
+
+**Next.js**
+
+The wrapper is `<smoodly.Section styles={styles}>` from `smoodly/react`.
+
+To take the group away from a section, set `styles: false` in its schema, as the starter's header and footer do, or `styles: { omit: ["align"] }` to drop some steps. Elements never have styles: spacing is their container's job.
+
+## Custom CSS
+
+Turn the box on for the whole site in the config:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  css: true,
+  // …
+});
+```
+
+Every section then has a *Custom CSS* box under *Advanced* on its Settings tab, and `css: false` in a schema opts one section out. What an editor types is nested inside the section's own selector, so declarations apply to the section root and nested selectors reach inside it:
+
+```css
+background: var(--ink);
+color: var(--paper);
+h2 { font-size: 40px; }
+```
+
+The snippet is scoped, so it cannot restyle another section or the page. It is also checked as it is typed and again at publish, and refused when it uses `@import`, `url()`, `expression()` or `behavior:`, contains `</`, leaves a brace unclosed, or runs past 4000 characters. The layout of the [custom section](../content-modeling/custom-section.md) is emitted the same way, before the editor's own snippet, so the box still wins.
+
+Next, [The custom section](../content-modeling/custom-section.md) covers the one layout editors build themselves.

package/docs/content-modeling/zones.md

@@ -0,0 +1,80 @@
+# Zones and freedom
+
+A zone is a place in a page type where editors add sections. Its policy sets how much they may change there, from filling one section's fields to placing any section in any order.
+
+## The three policies
+
+Every zone in `smoodly.schema.page()` takes one policy from `z`:
+
+| Name | Description |
+| --- | --- |
+| `z.locked(heroSchema)` | Exactly one Hero, always. Editors fill its fields but cannot add, move or remove it. |
+| `z.sections([heroSchema, pageHeroSchema])` | Any number of the listed sections, in any order. .max(n) caps how many. |
+| `z.freeform({ sections: [...] })` | The same, plus custom: true to offer the custom section. sections: "*" allows every registered section. |
+
+Policies name components, not strings, so a typo is a type error. One page type can mix all three:
+
+**Astro**
+
+The schema is the same file as in any framework. Its view, `src/page-types/landing.astro`, renders each zone with `<Zone of={zones.hero} />` from `smoodly/astro/components`, as on [Page types](../content-modeling/page-types.md); a zone locked to a global renders the global's section.
+
+**Next.js**
+
+File: `components/pages/Landing.tsx`
+
+```tsx
+import { smoodly, z, Zone, type Props } from "smoodly/react";
+import { heroSchema } from "@/components/sections/Hero.schema";
+import { pageHeroSchema } from "@/components/sections/PageHero.schema";
+import { quote } from "@/smoodly/globals";
+
+export const landingSchema = smoodly.schema.page({
+  name: "landing",
+  title: "Landing",
+  zones: {
+    hero: z.sections([heroSchema, pageHeroSchema]).max(1),
+    body: z.freeform({ sections: "*", custom: true }),
+    closing: z.locked(quote),
+  },
+  seo: true,
+});
+
+function LandingView({ zones }: Props<typeof landingSchema>) {
+  return (
+    <>
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+      <Zone of={zones.closing} />
+    </>
+  );
+}
+
+export const LandingPage = smoodly.page(landingSchema, LandingView);
+```
+
+The hero zone offers a choice of two openers and takes one of them. The body takes anything. The closing zone always shows the site's one quote, edited under *Site*.
+
+> **Note:** `sections: "*"` includes every registered section, the header and footer too. List the sections instead when some are only meant for the layout.
+
+## What editors see
+
+In the canvas, *Add section* appears between the sections of a zone and at its end. It opens a picker with the sections the policy allows, then *Custom section* where `custom: true`, then a *Global* group with the globals whose section is allowed there. A zone capped with `.max(n)` loses its *Add section* once it is full.
+
+A section's toolbar moves it up or down, duplicates it or removes it. In a locked zone the section is tagged *locked* and the toolbar says *fields only*. Smoodly fills the zone from the section's `sample` the first time the page opens.
+
+An empty zone shows as a box in the canvas so it can take a section. On the site it renders nothing.
+
+## Locking a zone to a global
+
+`z.locked()` also takes a global with a section, as `closing` does above. The zone then shows that one global on every page of the type. Editors change it once, under *Site* or right in any canvas that shows it, and every page follows. The starter's header and footer take a different route: the layout renders them directly, so they need no zone.
+
+A global can also be placed by hand. The starter lists Quote in its body zones, so the picker's *Global* group offers the site quote there, and an editor may still add a one-off Quote from the sections list.
+
+## Choosing a policy
+
+- **Lock** what the design needs exactly once, in one place: the opener of every page type in the starter is a locked hero.
+- **Sections with a list** for a slot with a few right answers: a hero zone that takes one of two openers.
+- **Freeform** for the body. Most sites need it in one zone, with the sections you have built and `custom: true` for the layouts you have not.
+- **Your own JSX** for what editors should never touch. It renders in the canvas but cannot be selected.
+
+Next, [Settings, styles and CSS](../content-modeling/styles-and-settings.md) covers what editors can change on a placed section beyond its fields.

package/docs/fields/choices.md

@@ -0,0 +1,42 @@
+# Choices
+
+A switch, a dropdown, a row of pills or a checkbox list: the fields that pick from a closed set you declare.
+
+## Options
+
+`f.select()`, `f.radio()` and `f.checkboxes()` take a list of options. Each option is a `value`, which is stored and what the view compares against, and a `label`, which editors read:
+
+File: `components/sections/Points.schema.ts`
+
+```ts
+      icon: f.select([{ value: "circle", label: "Circle" }, { value: "square", label: "Square" }, { value: "diamond", label: "Diamond" }]),
+```
+
+A bare string is shorthand for an option whose label is its value: `f.radio(["left", "center"])`. The value's type in the view is the union of the option values, so a `switch` over it is exhaustive. An empty option list is an error at startup, and publish refuses a stored value that is not in the list.
+
+## The four fields
+
+| Field | Editor sees | Value |
+| --- | --- | --- |
+| `f.boolean()` | A switch. | true or false. Never required: an untouched switch is false. |
+| `f.select([…])` | A dropdown. .optional() adds an empty choice. | One option value. |
+| `f.radio([…])` | Pills in a row. .optional() adds a None pill that stores nothing. | One option value. |
+| `f.checkboxes([…])` | A checkbox per option. | An array of option values, in option order whatever order they were ticked. |
+
+Choose `f.radio()` for two to four options that fit on a row, and `f.select()` for longer lists. Smoodly's own styles use pills, so a radio in your settings looks the same.
+
+## Defaults
+
+A choice usually has a right answer to start from. `.default()` sets it, and the form shows it while the field is untouched:
+
+File: `components/sections/ImageText.schema.ts`
+
+```ts
+  settings: {
+    imageSide: f.radio([{ value: "left", label: "Image left" }, { value: "right", label: "Image right" }]).default("left"),
+  },
+```
+
+A boolean page field follows the same rule; the starter's `showInNavigation` defaults to `true`, so a new page appears in its parent's sub-navigation until an editor turns it off.
+
+Next, [Image, video and file](../fields/media.md).

package/docs/fields/conditional.md

@@ -0,0 +1,72 @@
+# Conditional fields
+
+Hide a field while another field has a certain value, so editors see only the fields that apply.
+
+## The condition
+
+Every field and setting takes `.hidden(condition)`, and `f.when(path)` builds the condition:
+
+| Name | Description |
+| --- | --- |
+| `f.when(path).is(value)` | Hidden while the field at path equals value. |
+| `f.when(path).isNot(value)` | Hidden while it differs. |
+| `f.when(path).in([a, b])` | Hidden while it is one of the listed values. |
+| `f.when(path).isEmpty()` | Hidden while it is empty: unset, an empty string or list, or an image with no asset. |
+| `f.when(path).isNotEmpty()` | Hidden while it has a value. |
+
+A hidden field leaves the form and is skipped at publish, so a required field that is hidden is not required. Its stored value stays, and comes back when the condition stops holding.
+
+## Paths
+
+A bare path names a sibling: a field at the same level as the one being hidden. Inside an object or a list item, that is the item's own fields. A path prefixed with `fields.` or `settings.` names a top-level key of that group from anywhere.
+
+A link that is either a page on the site or an external address:
+
+**Astro**
+
+The schema goes in `src/components/sections/Banner.schema.ts`, written as in the Next.js tab. Its view, `src/sections/banner.astro`, picks the link the same way, through `safeHref` since an editor typed it: `href={safeHref(cta.kind === "external" ? cta.url : cta.path)}`.
+
+**Next.js**
+
+File: `components/sections/Banner.tsx`
+
+```tsx
+import { f, smoodly, type Props } from "smoodly/react";
+
+export const bannerSchema = smoodly.schema.section({
+  name: "banner",
+  title: "Banner",
+  fields: {
+    heading: f.text(),
+    cta: f.object({
+      label: f.text(),
+      kind: f.radio([{ value: "internal", label: "Page" }, { value: "external", label: "Address" }]).default("internal"),
+      path: f.link().hidden(f.when("kind").is("external")),
+      url: f.link().hidden(f.when("kind").is("internal")),
+      newTab: f.boolean().hidden(f.when("kind").is("internal")),
+    }),
+  },
+  settings: {
+    tone: f.radio([{ value: "light", label: "Light" }, { value: "dark", label: "Dark" }]).default("light"),
+    background: f.image().optional().hidden(f.when("settings.tone").is("light")),
+  },
+});
+
+function BannerView({ heading, cta, settings, styles }: Props<typeof bannerSchema>) {
+  const href = cta.kind === "external" ? cta.url : cta.path;
+  return (
+    <smoodly.Section styles={styles} className="banner" data-tone={settings.tone}>
+      <h2>{heading}</h2>
+      <a href={href} target={cta.newTab ? "_blank" : undefined} rel={cta.newTab ? "noopener" : undefined}>{cta.label}</a>
+    </smoodly.Section>
+  );
+}
+
+export const Banner = smoodly.section(bannerSchema, BannerView);
+```
+
+Inside `cta`, `kind` is a sibling of `path` and `url`, so the bare path reads it. The background setting reads `settings.tone` with the prefix. A condition that names a field the schema does not have fails at startup, not in the form.
+
+The view still receives hidden fields as typed, so the sample above branches on `kind` itself rather than trusting that one of the two links is empty.
+
+Next, the [Pages](../pages/page-tree.md) group covers what editors do with pages once the shapes exist.