# Declare sections and slots

Your shop says which sections editors build pages from and where they go. Editors build templates and pages from them in the admin.

OrbPage holds what editors write about your products: a category's story, the home page, an
imprint, the footer's menu. It never decides how that looks. Your shop declares the building
blocks in code, and editors arrange them in the admin's Content area:

| Word         | What it is                                                                                  | Who makes it |
| ------------ | ------------------------------------------------------------------------------------------- | ------------ |
| **Section**  | A building block with typed settings, such as a hero with a title, a picture and a button.  | The shop     |
| **Slot**     | A place on a kind of page that takes a list of sections, such as a category page's `top`.   | The shop     |
| **Palette**  | The shop's own colours, by name. Editors see swatches; the shop gets the name.              | The shop     |
| **Menu**     | A place the shop shows links an editor arranges, such as the footer.                        | The shop     |
| **Template** | What every category that follows it shows in each slot, built from the shop's sections.     | An editor    |
| **Page**     | A category's page, the home page or a page of the shop's own, built from the same sections. | An editor    |

## Declare them

`declare` from `@orbpage/client` takes the whole declaration and gives back OrbPage's contract
together with the types your renderers read. Nordgrat's, shortened:

```tsx
import { declare, setting } from "@orbpage/client";
import type { BodyOf, HomeSlotsOf, SectionOf, SlotItem, SlotsOf } from "@orbpage/client";

export const sections = declare({
  palette: {
    snow: { label: "Snow", value: "#f6f4ef" },
    moss: { label: "Moss", value: "#3e5a48" },
  },
  sections: {
    hero: {
      name: "Hero",
      settings: {
        title: setting.line("Title").describe("A few words that name the page."),
        text: setting.text("Text").optional(),
        picture: setting.picture("Picture").optional(),
        link: setting.link("Button link").optional(),
        label: setting.line("Button text").optional(),
        tone: setting.colour("Background"),
      },
    },
    text: {
      name: "Text",
      settings: {
        body: setting.text("Text"),
        width: setting.choice("Width", { narrow: "Narrow", wide: "Wide" }),
      },
    },
    productRow: {
      name: "Product row",
      settings: {
        title: setting.line("Title").optional(),
        products: setting.products("Products", { max: 12 }),
        columns: setting.number("Columns", { min: 2, max: 4 }).default(4),
      },
    },
  },
  slots: {
    category: {
      top: { name: "Top", sections: ["hero"] },
      main: { name: "Main", sections: ["text", "productRow"] },
    },
    page: {
      body: { name: "Body", sections: ["text"] },
    },
    home: {
      body: { name: "Body", sections: ["hero", "text", "productRow"] },
    },
  },
  menus: { footer: { name: "Footer" } },
});

/** A section as the shop renders it, by its type. */
export type Section = SectionOf<typeof sections>;
/** A category page's slots, each a list of sections. */
export type CategorySlots = SlotsOf<typeof sections>;
/** A page's body. */
export type PageSlots = BodyOf<typeof sections>;
/** The home page's slots. */
export type HomeSlots = HomeSlotsOf<typeof sections>;
```

A slot names only sections you declared, so a typo fails as you type. OrbPage's contract checks
the rest as the shop starts, never at a shopper's request.
The home page uses `slots.home`, independently of `slots.page` for other pages. Both default
to no slots when omitted. The editor, draft validation, publishing and delivery use the same
declaration; `home.get()` is typed from home slots and `pages.get()` from page slots.

## The settings a section can have

Each setting is delivered as the shop reads it, not as the editor stored it: a product is a card
with its title, address and picture, a link is an address, running text is safe HTML. A script
that [writes content](/docs/page/write-content) sends the stored form.

| Setting                               | Stored as                                            | Delivered as                                             | Empty?             |
| ------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- | ------------------ |
| `setting.line(label)`                 | a string of at most 300 characters                   | a string                                                 | with `.optional()` |
| `setting.text(label)`                 | a [document](/docs/page/write-content#write-running-text) | `{ html }`, an HTML fragment safe to insert              | with `.optional()` |
| `setting.picture(label)`              | `{ media, decorative? }`, a library file's id        | `{ url, width, height, alt, srcset?, focalPoint? }`      | with `.optional()` |
| `setting.link(label)`                 | a link, such as `{ kind: "page", id }`               | `{ href }`, to a product, a category, a page or a URL    | with `.optional()` |
| `setting.products(label, { max })`    | picked `refs`, or a category's `ref` and `limit`     | product cards, picked or a category's first ones         | an empty list      |
| `setting.categories(label, { max })`  | the catalog's category refs                          | category cards                                           | an empty list      |
| `setting.pages(label, { max })`       | `pag_` ids, never the home page's                    | page cards, in the order picked                          | an empty list      |
| `setting.form(label)`                 | a `frm_` id                                          | one of the site's forms, with its fields                 | with `.optional()` |
| `setting.choice(label, options)`      | an option key                                        | one of the option keys; the first is the default         | never              |
| `setting.toggle(label)`               | a boolean                                            | a boolean, off unless `.default(true)`                   | never              |
| `setting.number(label, { min, max })` | a whole number                                       | a whole number, `min` unless `.default(n)`               | never              |
| `setting.colour(label)`               | a palette name                                       | a palette name; its first colour unless `.default(name)` | never              |

A link stores its target by identity: `{ kind: "page", id }`, `{ kind: "category", ref }`,
`{ kind: "product", ref }`, `{ kind: "path", path }` or `{ kind: "url", href }`. A category or a
product is always named by the catalog's `ref`, never its slug, so a renamed address still
resolves. Products store `{ kind: "references", refs }` or `{ kind: "category", ref, limit }`.

A page card holds `id`, `title`, `href` and `publishedAt`, when the page was first published in
that locale. It carries no picture and no description.

`.describe(help)` puts a line of help beside the setting in the editor. A line, a text or a
picture may also come from the catalog: on a category's page an empty title is the category's
name, an empty picture its picture. Such a setting stores `{ "follow": "name" }`,
`{ "follow": "description" }` or `{ "follow": "picture" }`; only a category's page may follow.

## Write long texts

An editable writing area grows with short text, up to 60% of the dynamic viewport height.
Longer text scrolls inside it while its formatting toolbar stays above the text, without
covering the selection or the admin header. Formatting, links and block insertion keep the
current selection. Native scrolling continues through the page at the writing area's edge;
the toolbar leaves with its editor. Read-only text remains fully expanded.

## Render a slot

`Section` is a discriminated union, so a `switch` over its `type` is exhaustive and each case
reads its own settings, typed:

```tsx continues
import { PageLayout } from "@orbpage/react";

function Slot({ sections }: { sections: readonly SlotItem<Section>[] }) {
  return (
    <PageLayout items={sections}>{(section) => <ContentSection section={section} />}</PageLayout>
  );
}

function ContentSection({ section }: { section: Section }) {
  switch (section.type) {
    case "hero":
      return <h1 className={`tone-${section.settings.tone}`}>{section.settings.title}</h1>;
    case "text":
      return <div dangerouslySetInnerHTML={{ __html: section.settings.body?.html ?? "" }} />;
    case "productRow":
      return (
        <ul>
          {section.settings.products.map((product) => (
            <li key={product.ref}>
              <a href={product.url}>{product.title}</a>
            </li>
          ))}
        </ul>
      );
  }
}
```

A section of a type your code does not know yet is left out of the answer, and a slot it does
not know of is empty. A deploy that adds a section never breaks a page the older code renders.

## Arrange rows

Editors may leave sections directly in a slot or add explicit rows. Existing pages keep their
flat shape. A row carries `kind: "row"`, a stable `row_…` id, a named `layout` and `columns`:
each column is an ordered list of the slot's existing section types, never another row.

The presets are `full`, `halves`, `thirds`, `quarters`, `oneTwo` (1:2) and `twoOne` (2:1).
Four equal columns are exact quarters. `PageLayout` renders these proportions and stacks all
columns in content order when its container becomes too narrow, independently of window size.
The default column gap is 1.5rem, customizable with `--orbpage-row-gap`.

Preview and published delivery carry the same layout. Keep each section's preview mark inside
`PageLayout` so clicking it still opens its editor. A text setting's HTML fragment remains
just that text; layout lives in the surrounding row, not in its HTML. Markdown reads columns
in content order without visual layout markup.

Add row chooses a preset. Move to sends an existing section to a row's column or outside rows;
ordinary move controls reorder sections and rows. Reducing the column count appends the removed
columns' contents to the last remaining column, without changing section ids. Structural edits
can be undone. The 100-section slot limit includes all columns. Category templates have the same
rows and the same follow/reset behavior as flat content, not a separate page-template system.

## Push them to OrbPage

Your deploy pushes the declaration, as Nordgrat's `pnpm content` does. With `check`, OrbPage only
reports what would change and which drafts and live versions would no longer fit:

```tsx continues
import { declareSections } from "@orbpage/client";

const options = { baseUrl: process.env.ORBPAGE_URL, token: process.env.ORBPAGE_STAFF_TOKEN };

const checked = await declareSections(sections, { ...options, check: true });
if (!checked.ok) throw new Error(`OrbPage refused the check: ${checked.problem.code}`);
for (const { change, what, name } of checked.content.changes) console.log(change, what, name);
for (const { kind, key, state } of checked.content.misfits) {
  console.log(`No longer fits: the ${state} ${kind} ${key}`);
}

const declared = await declareSections(sections, options);
if (!declared.ok) throw new Error(`OrbPage refused the sections: ${declared.problem.code}`);
```

The token is a staff token with Content edit, as the admin's `/api/auth/token` answers once you
are signed in; [Write content from code](/docs/page/write-content#sign-in-from-a-script) shows how a
script gets one. `declareSections` and `manageContent(options).declare(declarations, key)` are the
same operation. `declareSections` takes what `declare` returned; `manageContent` sends
`sections.declarations` with an idempotency key, checks with `checkDeclarations`, and also takes
an operator key. Content that no longer fits stays stored; delivery shows only what still fits, and
a setting with a default holds it until an editor picks another.

## Templates

Editors build templates in the admin from the sections a category's slots take. Every category
follows the default template until an editor picks another. A slot shows the template's sections
until the editor changes that slot for one category; from then on the slot is the category's own,
and a reset gives it back to the template. The shop never sees the difference: it reads the
category's page, slot by slot, and the answer names the `template` it follows.

How the shop reads pages, menus and previews: [Read the content](/docs/shop/content).

## Size an image in running text

Each image block has its own **Display width**: full width, 50%, one third, 25%, or a custom
positive whole pixel width. **Original appearance** removes the choice and leaves the image
as it appeared before. The same library image can therefore be a small logo on one page and
full width on another.

The chosen width survives saving, preview and publishing. The delivered HTML fragment sizes
the complete figure, keeps its caption and link, preserves image proportions and never makes
it wider than its container. Custom pixel widths must be positive safe integers; unfinished
or invalid input remains in the draft so the editor can correct it before publishing.