smoodly 0.0.60 → 0.0.62

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 *Sections*.
+
+> **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 *Sections* 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.

package/docs/fields/link.md

@@ -0,0 +1,31 @@
+# Link
+
+A link is a text box that takes a full URL or a path on your site. Pair it with a label in an object to make a button.
+
+## The field
+
+`f.link()` stores a string and shows a text box. Editors type a full address, `https://example.com/pricing`, or a path on the site, `/company/about-us`. The view renders it as an `href`:
+
+File: `components/sections/Hero.schema.ts`
+
+```ts
+    buttons: f.list(f.object({ label: f.text(), href: f.link() })).max(2),
+```
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+                  <a key={i} className={i === 0 ? "button" : "button button--outline"} href={b.href}
+```
+
+The box takes only a target the site will render: `https://`, `http://`, `mailto:`, `tel:`, a path starting with `/`, `#` or `?`. Anything else, a `javascript:` address say, is marked under the box as the editor types, and Publish refuses it.
+
+A path is stored as typed, not looked up: on a multilingual site each language's link holds that language's own URL, such as `/fi/yritys`, and a link to a page does not follow it when its slug changes.
+
+A link with a label is an object of two fields, as above. A list of those objects is a row of buttons, capped with `.max()`.
+
+## Links inside richtext
+
+Text inside a [richtext](../fields/richtext.md) field links through the `link` mark of its toolset, which editors apply from the toolbar. On the site, `RichText` renders only safe targets: `http`, `https`, `mailto`, `tel`, and paths on the site. Anything else renders as plain text.
+
+Next, [Choices](../fields/choices.md).

package/docs/fields/list-and-object.md

@@ -0,0 +1,58 @@
+# List and object
+
+Group fields into one value with an object, or let editors repeat a value with a list. The two nest one level, which is as far as a sidebar form stays readable.
+
+## Object
+
+`f.object()` groups fields into one value. Editors see the group under one label; the view gets one object:
+
+File: `components/sections/ImageText.schema.ts`
+
+```ts
+    link: f.object({ label: f.text(), href: f.link() }).optional(),
+```
+
+File: `components/sections/ImageText.tsx`
+
+```tsx
+      {link?.href && <a className="link-accent" href={link.href} {...linkMarks.attrs} {...linkMarks.field("label")}>{link.label}</a>}
+```
+
+An optional object may be left empty as a whole. Without `.optional()`, its required fields are required.
+
+## List
+
+`f.list(item)` repeats any builder. Editors add, reorder and remove items; `.min()` and `.max()` count them, the form shows a counter, and *Add* stops at the limit:
+
+File: `components/sections/Points.schema.ts`
+
+```ts
+    points: f.list(f.object({
+      icon: f.select([{ value: "circle", label: "Circle" }, { value: "square", label: "Square" }, { value: "diamond", label: "Diamond" }]),
+      heading: f.text(),
+      text: f.text(),
+    })).min(1).max(6),
+```
+
+A list of objects is the common shape: buttons, points, team members typed by hand. A list of one builder works too, `f.list(f.text())` for a plain list of lines.
+
+## The limits
+
+- **A list never holds a list.** A list inside an object inside a list is still nested on screen, and a sidebar cannot show it legibly. A section that needs a grid of groups of lists is two sections, or a [collection](../collections/defining.md).
+- **No references inside.** `f.ref()` and `f.refList()` live at the top level of a schema, where the reference index can address them.
+- **Localize the whole value.** `.localized()` goes on the list or the object, not on a field inside it. The starter's footer localizes each link column as one value:
+
+File: `components/sections/Footer.schema.ts`
+
+```ts
+const column = () =>
+  f.object({ title: f.text(), links: f.list(f.object({ label: f.text(), href: f.link() })) }).localized();
+```
+
+Each limit is an error at startup, with the path that broke it.
+
+## In the canvas
+
+A list item and an object are scopes for [marks](../content-modeling/marks.md): `m.item("points", i)` and `m.object("link")` give you `attrs` for the item's root and `field()` for the fields inside, so each item's text edits in place. A mark for the whole list opens the repeater in the inspector.
+
+Next, [Reference and tags](../fields/reference-and-tags.md).

package/docs/fields/media.md

@@ -0,0 +1,103 @@
+# Image, video and file
+
+The three media fields, the resolved values your view receives, and the components that render them.
+
+## Image
+
+`f.image()` opens the media picker: drop a file to upload it, or pick one from the library. `aspect` names one ratio, or several the crop tool may lock to, so the component knows its box before the image loads:
+
+File: `components/sections/Hero.schema.ts`
+
+```ts
+    image: f.image({ aspect: "4:5" }),
+```
+
+For art direction, name a crop per shape the layout needs instead: `f.image({ crops: { desktop: "16:9", mobile: "4:5" } })`. Editors frame each named crop on its own, all sharing one focus point, and a crop nobody framed follows the focus point at its ratio, so most images need no second look. The first crop is the field's main crop: the resolved value's `crop` and `aspect` are the first one's, and `crops` holds every one by name with its `crop`, `aspect` and pixel `width` and `height`. `crops` and `aspect` are exclusive, a name is a lowercase identifier, and a name removed from the schema leaves its stored frame unread. `quality` and `maxWidth` set how this kind of image is served, such as `f.image({ quality: 95 })` for a portfolio's photos; [Quality and width](../media/images-and-crops.md#quality-and-width) has the rules.
+
+**Astro**
+
+File: `src/sections/hero.astro`
+
+```astro
+    {image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+Editors pick a crop and a focus point per use under *Edit*, and can give this use its own alt text; otherwise the asset's own alt from the library applies. What the view receives is resolved: the URL, the dimensions, the alt and the crop. Render it with `Image` from `smoodly/astro/components`:
+
+| Prop | Use |
+| --- | --- |
+| `image` | The resolved value. |
+| `aspect` | Overrides the value's ratio for this placement, such as a 21:9 header over a 3:2 card. |
+| `media` | Where each named crop applies, a media query per name in order: `{ mobile: "(max-width: 767px)" }`. |
+| `sizes, priority, loading` | Set sizes to what the layout gives the image, and priority on the one above the fold. |
+| `quality, maxWidth` | This placement's quality (50, 60, 75, 85, 95 or 100) and the widest cut its `srcset` lists, over the field's and the project's: [Quality and width](../media/images-and-crops.md#quality-and-width). |
+| `class, style` | Land on the wrapper box, which holds the aspect ratio. |
+| `data-*` | Land on the wrapper too, so a field mark selects the image in the canvas. |
+
+The box keeps its ratio and nothing shifts as it loads. The image is plain HTML whose `srcset` lists the framed area cut at a fixed list of widths on Smoodly's media host, in AVIF or WebP; [Images and crops](../media/images-and-crops.md) has the details.
+
+**Next.js**
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+        {image && <SmoodlyImage image={image} className="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+Editors pick a crop and a focus point per use under *Edit*, and can give this use its own alt text; otherwise the asset's own alt from the library applies. What the view receives is resolved: the URL, the dimensions, the alt and the crop. Render it with `SmoodlyImage` from `smoodly/image`:
+
+| Prop | Use |
+| --- | --- |
+| `image` | The resolved value. |
+| `aspect` | Overrides the value's ratio for this placement, such as a 21:9 header over a 3:2 card. |
+| `media` | Where each named crop applies, a media query per name in order: `{ mobile: "(max-width: 767px)" }`. |
+| `sizes, priority, loading` | Set sizes to what the layout gives the image, and priority on the one above the fold. |
+| `quality, maxWidth` | This placement's quality (50, 60, 75, 85, 95 or 100) and the widest cut its `srcset` lists, over the field's and the project's: [Quality and width](../media/images-and-crops.md#quality-and-width). |
+| `className, style` | Land on the wrapper box, which holds the aspect ratio. |
+| `data-*` | Land on the wrapper too, so a field mark selects the image in the canvas. |
+
+The box keeps its ratio and nothing shifts as it loads. The image is a plain `<img>`, not `next/image`, whose `srcset` lists the framed area cut at a fixed list of widths on Smoodly's media host, in AVIF or WebP; [Images and crops](../media/images-and-crops.md) has the details.
+
+## Video and file
+
+`f.video()` and `f.file()` use the same picker. A video resolves to its URL, dimensions and, when the library has one, a poster image.
+
+**Astro**
+
+`Video` from `smoodly/astro/components` renders it as a `video` element with the poster and size set, and passes every other attribute through: `<Video video={video} controls muted />`. A file is a link to its `url`.
+
+**Next.js**
+
+`SmoodlyVideo` from `smoodly/image` renders it as a `video` element with the poster and size set, and passes every other attribute through:
+
+File: `components/sections/Reel.tsx`
+
+```tsx
+import { f, smoodly, type Props } from "smoodly/react";
+import { SmoodlyVideo } from "smoodly/image";
+
+export const reelSchema = smoodly.schema.section({
+  name: "reel",
+  title: "Reel",
+  fields: { video: f.video(), brochure: f.file().optional() },
+});
+
+function ReelView({ video, brochure, styles }: Props<typeof reelSchema>) {
+  return (
+    <smoodly.Section styles={styles} className="reel">
+      <SmoodlyVideo video={video} controls muted />
+      {brochure && <a href={brochure.url} download={brochure.filename}>{brochure.title ?? brochure.filename}</a>}
+    </smoodly.Section>
+  );
+}
+
+export const Reel = smoodly.section(reelSchema, ReelView);
+```
+
+A file resolves to its URL, filename, size and mime type, plus a title when the value carries one. Videos are served as uploaded, with no transcoding.
+
+## Where media lives
+
+Uploads go to the media library, one place for the whole site, and a field stores a reference to an asset plus its own crop and alt. *Replace* on a field picks a different asset for that field alone, and the library shows where each asset is used. [The media library](../media/library.md) covers uploads, limits and usage.
+
+Next, [List and object](../fields/list-and-object.md).

package/docs/fields/overview.md

@@ -0,0 +1,56 @@
+# All fields
+
+Every field builder on f, what editors see for each, and the chain of modifiers they share. The pages that follow take them a few at a time.
+
+## The builders
+
+| Field | Editor sees | Value in the view |
+| --- | --- | --- |
+| `f.text()` | A single-line text box. | string |
+| `f.richtext({ toolset })` | A text editor with the toolset's formatting and elements. | A document for <RichText> |
+| `f.link()` | A text box for a URL or a site path. | string |
+| `f.slug()` | A text box with the URL prefix in front. Name the field slug. | string |
+| `f.number()` | A number box. | number |
+| `f.date()` | A calendar. Stored as 2026-09-02. | string |
+| `f.datetime()` | A calendar with a time, in the site's zone. Stored as a UTC instant. | string |
+| `f.boolean()` | A switch. | boolean |
+| `f.select([…])` | A dropdown. | One of the option values |
+| `f.radio([…])` | A row of pills. | One of the option values |
+| `f.checkboxes([…])` | A checkbox list. | An array of option values |
+| `f.tags()` | Chips, with suggestions from existing entries. | string[] |
+| `f.image({ aspect })` | The media picker, with a crop tool. | A resolved image for the image component |
+| `f.video()` | The media picker. | A resolved video for the video component |
+| `f.file()` | The media picker. | A resolved file: url, filename, size, mime |
+| `f.object({ … })` | A group of fields. | An object |
+| `f.list(item)` | A repeater: add, reorder, remove. | An array of the item's value |
+| `f.ref(() => coll)` | A search picker over one collection. | The entry's fields, or null |
+| `f.refList(() => coll)` | The same picker, taking several. | An array of entries |
+
+Every field is required unless it chains `.optional()`. A boolean is never required, and an object whose fields are all optional may be left empty. Publish reports what is missing; drafts save regardless.
+
+## The chain
+
+Every builder shares these modifiers. Chaining never changes the builder in place, so a shared builder is safe to reuse.
+
+| Name | Description |
+| --- | --- |
+| `.optional()` | The field may be empty. Its type in the view gains undefined. |
+| `.default(value)` | The value a new section or entry starts with, and what the form shows while the field is empty. |
+| `.min(n), .max(n)` | Counts items on a list, a reference list and tags. .max(n) also limits a text's length in characters. |
+| `.localized()` | The field has its own value per language on an entry or a global. Page content is per language already. |
+| `.hidden(f.when(path).is(value))` | Leaves the form while the condition holds. See Conditional fields. |
+| `.resolve()` | On a ref: how far to follow the target's own references. See Reference and tags. |
+
+## Where a field may go
+
+The same builders serve every schema, with a few limits that keep the admin simple:
+
+| Place | Limits |
+| --- | --- |
+| `Section and element fields` | Any builder. A ref lives at the top level, never inside a list or an object. A list never holds a list. |
+| `Settings` | Any builder, but never .localized(): a layout choice is the same in every language. |
+| `Page fields` | No ref, list or richtext, and no .localized(), because page fields are per language already. |
+| `Collection fields` | Any builder. Name a text field slug to give entries their own URL part. |
+| `Elements in richtext` | Any builder except a ref. |
+
+Next, [Text, number and date](../fields/text.md).