smoodly 0.0.60 → 0.0.61

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).

package/docs/fields/reference-and-tags.md

@@ -0,0 +1,62 @@
+# Reference and tags
+
+A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.
+
+## Reference
+
+`f.ref(() => collection)` picks one entry; `f.refList(() => collection)` picks several. The target is a function, so two collections can point at each other without an import cycle:
+
+File: `components/sections/FavouriteArticles.schema.ts`
+
+```ts
+import { articles } from "@/smoodly/collections";
+// …
+  fields: {
+    heading: f.text(),
+    items: f.refList(() => articles).max(6),
+  },
+```
+
+Editors see a search picker over the collection's entries in the language they are editing, each with its status. A list takes each entry once and stops at `.max()`.
+
+## What the view receives
+
+A reference resolves before render, in one batched read per collection, so the view gets the entry as `{ id, path, fields }` rather than an id:
+
+File: `components/sections/FavouriteArticles.tsx`
+
+```tsx
+          {(items ?? []).filter((a) => a !== null).map((a, i) => (
+            <ArticleCard key={i} article={a.fields} url={url(a.path!)} locale={locale} />
+          ))}
+```
+
+An entry that is unpublished, or was deleted after the page went live, resolves to `null`, which is why the view filters before it maps. The value's type follows the target collection's fields.
+
+The same rule holds in every read: sections, `q` lists and single reads, entry pages and globals. How deep a reference goes is the field's decision:
+
+| Declaration | The view gets |
+| --- | --- |
+| `f.ref(() => authors)` | `{ id, path, fields }`; the author's own references stay id strings. |
+| `.resolve("company")` | The named reference of the target resolved one level too. |
+| `.resolve()` | The whole chain resolved. |
+
+Types follow the depth, so `a.fields.company` is an id or a resolved entry as declared. One gap: where the chain meets a cycle it stops at ids, while the type says resolved.
+
+## Where references may go
+
+A reference lives at the top level of a section, element or collection schema. It cannot sit inside a list or an object, in a page field, or in an element that richtext embeds, because the reference index addresses fields by their top-level key. A schema that breaks the rule fails at startup with the path.
+
+## Tags
+
+`f.tags()` stores an array of short strings and shows them as chips. Editors type a tag and press Enter, or paste a comma-separated list, and pick from the tags other entries of the collection already use in that language:
+
+File: `smoodly/collections.ts`
+
+```ts
+    tags: f.tags().localized(),
+```
+
+Tags are trimmed, and two that differ only in case are one tag: typing `design` when `Design` exists reuses it. `.min()` and `.max()` count tags. Each entry keeps its own list; there is no tag collection to manage. The starter shows an article's first tag on its card and all of them on the article page.
+
+Next, [Conditional fields](../fields/conditional.md).

package/docs/fields/richtext.md

@@ -0,0 +1,168 @@
+# Richtext and elements
+
+Formatted text stored as structured data, the toolset that decides what editors may put in it, and the elements they can insert between the paragraphs.
+
+## The field
+
+`f.richtext()` shows a text editor and stores a document, never HTML. Render it with `RichText`.
+
+File: `components/sections/ImageText.schema.ts`
+
+```ts
+    text: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
+```
+
+**Astro**
+
+`RichText` comes from `smoodly/astro/components`:
+
+File: `src/sections/imageText.astro`
+
+```astro
+---
+import { Image, RichText, Section } from "smoodly/astro/components";
+// …
+---
+// …
+      <div class="prose" {...m.field("text")}><RichText doc={text} /></div>
+```
+
+**Next.js**
+
+`RichText` comes from the site's bound renderer, below:
+
+File: `components/sections/ImageText.tsx`
+
+```tsx
+import { RichText } from "@/smoodly/richtext";
+// …
+      <div className="prose" {...m.field("text")}><RichText doc={text} /></div>
+```
+
+`RichText` renders a fragment with no wrapper, so the element and class around it are yours. An empty document counts as missing, so a required richtext field must hold some text before publish. In the canvas, a marked richtext field edits in place with a floating toolbar.
+
+## Toolsets
+
+A toolset is what a richtext field offers: which formatting, which block types, which elements. Without one, a field gets bold, italic and links, headings two to four, both lists and blockquotes. Heading one is left out because the section or page owns the page's first heading.
+
+`smoodly.toolset()` builds one from three lists:
+
+| Name | Description |
+| --- | --- |
+| `marks` | bold, italic, link. |
+| `nodes` | h1 to h6, bulletList, orderedList, blockquote and image. image adds pictures from the media library, with a caption. |
+| `elements` | Registered elements, by value. |
+
+The starter keeps its toolsets in one file and imports them by value where a field needs them:
+
+File: `smoodly/toolsets.ts`
+
+```ts
+import { smoodly } from "smoodly";
+import { calloutSchema } from "../components/elements/Callout.schema";
+import { ctaSchema } from "../components/elements/Cta.schema";
+
+export const article = smoodly.toolset({
+  marks: ["bold", "italic", "link"],
+  nodes: ["h2", "h3", "h4", "bulletList", "orderedList", "blockquote", "image"],
+  elements: [calloutSchema, ctaSchema],
+});
+```
+
+A toolset limits what editors can create, not what the document may hold. Tightening one later leaves existing content as it is, so nothing is rewritten behind an editor's back.
+
+## Rendering with elements and images
+
+**Astro**
+
+The package's `RichText` knows your elements by file name and renders body images through Astro's image service, so there is nothing to bind. Links keep only safe targets: `http`, `https`, `mailto`, `tel` and site-relative paths.
+
+**Next.js**
+
+The `RichText` from `smoodly/react` renders text alone. A site that embeds elements or images binds its own renderer once, and imports it from there everywhere:
+
+File: `smoodly/richtext.tsx`
+
+```tsx
+import { createRichText } from "smoodly/richtext";
+import { Callout } from "@/components/elements/Callout";
+import { Cta } from "@/components/elements/Cta";
+
+export const RichText = createRichText({ elements: [Callout, Cta], sizes: "(min-width: 900px) 720px, 100vw" });
+```
+
+The bound renderer knows the elements a document may name and renders body images through `SmoodlyImage`, with `sizes` set to the text column's width. Links keep only safe targets: `http`, `https`, `mailto`, `tel` and site-relative paths.
+
+## Elements
+
+An element is a small component editors insert between paragraphs, from the *+* button on the toolbar or by typing `/`. It is defined like a section, with `contexts` saying where it may go:
+
+File: `components/elements/Callout.schema.ts`
+
+```ts
+export const calloutSchema = smoodly.schema.element({
+  name: "callout",
+  title: "Callout",
+  icon: "!",
+  description: "A highlighted note inside the text.",
+  contexts: ["richtext"],
+  fields: {
+    title: f.text().max(80),
+    body: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
+  },
+  settings: {
+    tone: f.select([{ value: "info", label: "Info" }, { value: "success", label: "Success" }, { value: "warning", label: "Warning" }]).default("info"),
+  },
+  // …
+});
+```
+
+**Astro**
+
+An element's view is `src/elements/<name>.astro`, named after the schema:
+
+File: `src/elements/callout.astro`
+
+```astro
+---
+// …
+const { title, body, settings } = Astro.props;
+---
+<aside class="callout" data-tone={settings.tone}>
+  <strong class="callout__title">{title}</strong>
+  <div class="callout__body"><RichText doc={body} /></div>
+</aside>
+```
+
+A link an editor types in an element goes through `safeHref` from `smoodly`, as in the starter's `cta.astro`.
+
+**Next.js**
+
+File: `components/elements/Callout.tsx`
+
+```tsx
+function CalloutView({ title, body, settings }: Props<typeof calloutSchema>) {
+  return (
+    <aside className="callout" data-tone={settings.tone}>
+      <strong className="callout__title">{title}</strong>
+      <div className="callout__body"><RichText doc={body} /></div>
+    </aside>
+  );
+}
+
+export const Callout = smoodly.element(calloutSchema, CalloutView);
+```
+
+An element renders with no wrapper of Smoodly's and has no styles or CSS box: spacing is the text column's job. It may not hold a reference. In the editor an inserted element is a card with its own fields, and its `sample` fills it on insert.
+
+Register an element's schema in `smoodly/elements.ts` and list it in the toolsets that may insert it. A toolset that names an element the config does not register fails at startup.
+
+**Astro**
+
+The view is the file; there is nothing else to list.
+
+**Next.js**
+
+Add its component to `smoodly/views.ts` and `smoodly/richtext.tsx` as well.
+
+Next, [Link](../fields/link.md).

package/docs/fields/text.md

@@ -0,0 +1,152 @@
+# Text, number, date and time
+
+The plain values: a line of text, a number, a date, a date with a time, and the slug that becomes part of an entry's URL.
+
+## Text
+
+`f.text()` is a single line. `.max(n)` limits it in characters, and publish enforces the limit. There is no multi-line text field: paragraphs are [richtext](../fields/richtext.md), which keeps formatting as data rather than as line breaks.
+
+File: `components/elements/Cta.schema.ts`
+
+```ts
+  fields: {
+    heading: f.text().max(80),
+    text: f.text().max(200).optional(),
+    label: f.text().max(40),
+    href: f.link(),
+  },
+```
+
+Text is the one field editors can change in place in the canvas, when its element carries a [mark](../content-modeling/marks.md).
+
+## Number
+
+`f.number()` shows a number box and stores a number. An empty box stores nothing, so an optional number is `undefined` in the view, not `0`.
+
+## Date and time
+
+`f.date()` is a calendar: a text box the editor may type into, and a calendar button that opens a month grid. It stores the day as `2026-09-02`, and publish refuses anything else — `2.9.2026` or a February 30th never reach the site. The view formats it for the reader; the starter formats in the page's language:
+
+File: `components/articles.ts`
+
+```ts
+export const formatDate = (iso: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone: "UTC" }).format(new Date(iso));
+```
+
+`f.datetime()` is the same calendar with an hour and a minute beside it. It stores a moment in time as a UTC instant, `2026-09-02T14:30:00Z`, so an event start or a publish-at means the same thing in every zone and sorts as a string. The editor picks in the site's time zone, and a hint under the field names it.
+
+The site's zone is one line of config, an IANA name:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  locales: { default: routing.defaultLocale, supported: [...routing.locales] },
+  // Editors pick dates and times in this zone; the views format with it (an IANA name, never an offset).
+  timeZone: "Europe/Helsinki",
+  // …
+});
+```
+
+Name a city, never an offset. `"+3"` is wrong half the year; `Europe/Helsinki` carries the daylight-saving rules, and the browser and Node apply them from their own zone database. `defineConfig` refuses a name the runtime does not know. Without `timeZone`, editors pick in their own browser's zone, and the hint says so.
+
+A view formats a datetime with the same zone:
+
+File: `components/articles.ts`
+
+```ts
+export const formatDateTime = (iso: string, locale: string, timeZone: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short", timeZone }).format(new Date(iso));
+```
+
+Pass `config.timeZone` from your config file. A collection can order its entries by either field, as the starter's articles do with `order: { by: "date", direction: "desc" }`.
+
+### Time zones in Europe
+
+The value to put in `timeZone`, country by country. A country with several zones has its capital first.
+
+| Country | timeZone |
+| --- | --- |
+| `Albania` | Europe/Tirane |
+| `Andorra` | Europe/Andorra |
+| `Austria` | Europe/Vienna |
+| `Belarus` | Europe/Minsk |
+| `Belgium` | Europe/Brussels |
+| `Bosnia and Herzegovina` | Europe/Sarajevo |
+| `Bulgaria` | Europe/Sofia |
+| `Croatia` | Europe/Zagreb |
+| `Cyprus` | Asia/Nicosia |
+| `Czechia` | Europe/Prague |
+| `Denmark` | Europe/Copenhagen |
+| `Estonia` | Europe/Tallinn |
+| `Faroe Islands` | Atlantic/Faroe |
+| `Finland` | Europe/Helsinki |
+| `Åland` | Europe/Mariehamn |
+| `France` | Europe/Paris |
+| `Germany` | Europe/Berlin (Büsingen: Europe/Busingen) |
+| `Gibraltar` | Europe/Gibraltar |
+| `Greece` | Europe/Athens |
+| `Guernsey` | Europe/Guernsey |
+| `Hungary` | Europe/Budapest |
+| `Iceland` | Atlantic/Reykjavik |
+| `Ireland` | Europe/Dublin |
+| `Isle of Man` | Europe/Isle_of_Man |
+| `Italy` | Europe/Rome |
+| `Jersey` | Europe/Jersey |
+| `Kosovo` | Europe/Belgrade |
+| `Latvia` | Europe/Riga |
+| `Liechtenstein` | Europe/Vaduz |
+| `Lithuania` | Europe/Vilnius |
+| `Luxembourg` | Europe/Luxembourg |
+| `Malta` | Europe/Malta |
+| `Moldova` | Europe/Chisinau |
+| `Monaco` | Europe/Monaco |
+| `Montenegro` | Europe/Podgorica |
+| `Netherlands` | Europe/Amsterdam |
+| `North Macedonia` | Europe/Skopje |
+| `Norway` | Europe/Oslo (Svalbard: Arctic/Longyearbyen) |
+| `Poland` | Europe/Warsaw |
+| `Portugal` | Europe/Lisbon (Azores: Atlantic/Azores, Madeira: Atlantic/Madeira) |
+| `Romania` | Europe/Bucharest |
+| `Russia` | Europe/Moscow (also Europe/Kaliningrad, Europe/Samara, Europe/Astrakhan, Europe/Saratov, Europe/Ulyanovsk, Europe/Volgograd, Europe/Kirov) |
+| `San Marino` | Europe/San_Marino |
+| `Serbia` | Europe/Belgrade |
+| `Slovakia` | Europe/Bratislava |
+| `Slovenia` | Europe/Ljubljana |
+| `Spain` | Europe/Madrid (Canary Islands: Atlantic/Canary) |
+| `Sweden` | Europe/Stockholm |
+| `Switzerland` | Europe/Zurich |
+| `Turkey` | Europe/Istanbul |
+| `Ukraine` | Europe/Kyiv (Crimea: Europe/Simferopol) |
+| `United Kingdom` | Europe/London |
+| `Vatican City` | Europe/Vatican |
+
+Outside Europe the same rule holds — a city name from the IANA database, such as `America/New_York` or `Asia/Tokyo`. The full list is `Intl.supportedValuesOf("timeZone")` in any modern runtime.
+
+## Slug
+
+`f.slug()` is a text box shown with the entry's URL prefix in front, such as `/posts/`. It belongs on a collection, and the field must be named `slug`: that is the name the URL is built from, so `collection()` refuses `f.slug()` under any other name.
+
+File: `smoodly/collections.ts`
+
+```ts
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  // …
+  fields: {
+    title: f.text().localized(),
+    // …
+    slug: f.slug({ from: "title" }),
+    // …
+  },
+});
+```
+
+The starter passes `from: "title"`: the admin fills the slug from the title as the editor types it, until they type a slug of their own. It stops at the first publish, so a live URL never changes by itself. A slug is tidied when the box loses focus, so `Hello World` becomes `hello-world`, and publish refuses anything that is still not a valid slug. A slug is per language without `.localized()`, because each language has its own URL. Two entries under the same parent cannot share one. Pages have no slug field: a page's slug is set in the admin when it is created and renamed under *Settings*.
+
+Next, [Richtext and elements](../fields/richtext.md).