smoodly 0.0.62 → 0.0.63

package/dist/site.d.ts

@@ -12,6 +12,7 @@ import type { StyleValues, StyleValuesInput } from "./styles.ts";
 import type { CustomConfigInput, ResolvedCustom } from "./custom/index.ts";
 import type { PageRecord, PageStore } from "./store.ts";
 import type { PathHit } from "./path-index.ts";
+import type { SamplePicks } from "./sample-fill.ts";
 import type { EntryItem, PageItem, Seo } from "./read-shapes.ts";
 import type { SchemaOr } from "./registration.ts";
 import type { ResolvedConfig } from "./config.ts";
@@ -144,6 +145,16 @@ export interface ContentReads {
     targetPaths(target: PathTarget): Promise<Record<string, string>>;
     /** Everything the renderer needs for one target: null when it is a folder, unpublished (outside draft), or gone. */
     load(target: PathTarget, locale: string, path: string, options?: LoadOptions): Promise<SiteHit | null>;
+    /** The picker's rows for a zone of a page type, as raw nodes built from the registry's samples (sample-tree.ts):
+     *  what `loadSamples` is handed. A static: the service holds no samples. */
+    sampleTree(template: string, zone: string, picks?: SamplePicks): PageTree;
+    /** The collections the zone's offered sections reference (spec 2026-11-14 filled samples): the picks are their
+     *  first published entries, read before the tree is built. A static. */
+    sampleCollections(template: string, zone: string): string[];
+    /** The picker's samples (spec 2026-11-14 add section previews): the page's draft with `tree`'s zones resolved in
+     *  place of the stored ones, images, references and placed globals as a draft has them. Draft only; nothing is
+     *  stored. A placement names its item alone. Null for an entry, a page that is gone or not in `locale`. */
+    loadSamples(target: PathTarget, locale: string, path: string, tree: PageTree): Promise<SiteHit | null>;
     /** The published read of an address: one locate that tells a record to assemble from a redirect row, and the
      *  code-owned page where the index has no row. */
     lookup(locale: string, path: string): Promise<SiteHit | {
@@ -220,6 +231,8 @@ export declare function siteStatics(options: Omit<SiteOptions, "stores">): {
     custom: ResolvedCustom;
     cacheKey: string;
     codePage: (locale: string, path: string) => SitePage | null;
+    sampleTree: (template: string, zone: string, picks?: SamplePicks) => PageTree;
+    sampleCollections: (template: string, zone: string) => string[];
 };
 /** What createSmoodlySite takes, read off the config. */
 export declare function siteOptions(config: ResolvedConfig, stores?: SiteOptions["stores"]): SiteOptions;

package/dist/site.js

@@ -2,6 +2,7 @@ import { lastPart } from "./addresses.js";
 import { withDefaults } from "./field-defaults.js";
 import { modelKey } from "./model-key.js";
 import { SMOODLY_VERSION } from "./version.js";
+import { sampleTree as buildSampleTree, zoneSampleCollections } from "./sample-tree.js";
 import { pageSeo } from "./seo.js";
 import { pageFieldsOf, siteShape } from "./assemble.js";
 /** The `page` prop for a loaded page. `href` is the app's seam from a
@@ -60,7 +61,15 @@ export function siteStatics(options) {
             ...(withSeo ? { seo: pageSeo(undefined, spec.title) } : {}),
         };
     }
-    return { shape, locales, homePageSlug, styles, custom, cacheKey, codePage };
+    const sampleSource = {
+        sections: options.sections.map((x) => ("schema" in x ? x.schema : x)),
+        globals: (options.globals ?? []).map((g) => ({ name: g.name, ...(g.section !== undefined ? { section: g.section } : {}) })),
+    };
+    // A page type's schema carries its zones (page.ts); the site's own page type names only what the reads use.
+    const policyOf = (template, zone) => pageSchemas.find((x) => x.kind === "page" && x.name === template)?.zones?.[zone];
+    const sampleTree = (template, zone, picks) => buildSampleTree(sampleSource, policyOf(template, zone), zone, picks);
+    const sampleCollections = (template, zone) => zoneSampleCollections(sampleSource, policyOf(template, zone));
+    return { shape, locales, homePageSlug, styles, custom, cacheKey, codePage, sampleTree, sampleCollections };
 }
 /** What createSmoodlySite takes, read off the config. */
 export function siteOptions(config, stores) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SMOODLY_VERSION = "0.0.62";
+export declare const SMOODLY_VERSION = "0.0.63";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/write-version.mjs from package.json — do not edit.
-export const SMOODLY_VERSION = "0.0.62";
+export const SMOODLY_VERSION = "0.0.63";

package/docs/content-modeling/sections.md

@@ -32,7 +32,7 @@ export const heroSchema = smoodly.schema.section({
 | --- | --- |
 | `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. |
+| `description` | A line about the section, kept for later use: the admin does not show it today. 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. |
 
@@ -195,12 +195,28 @@ A registered section that no zone lists never appears in *Add section*. Lorem Co
 
 ## Sample content
 
-`sample` is what a section starts with, so a page never shows an empty one. Smoodly uses it twice:
+`sample` is what a section starts with, so a page never shows an empty one. Smoodly uses it three times:
 
+- *Add section* shows each section as your site draws it with its sample, so an editor sees what they are about to add.
 - 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.
+What Smoodly shows is what it inserts: the picture and the new section are built by the same rules.
+
+The sample always comes first. A field it sets is taken as it is, and nothing is added to it or inside it. A field it leaves out starts from its `.default()`. A field with neither is filled by Smoodly, so a section with a thin sample still looks like itself:
+
+| Name | Description |
+| --- | --- |
+| `f.text()` | Required: a short Latin phrase where the key reads as a title (title, heading, label, name, button and the like), else one sentence, cut to .max(n). Optional: empty. |
+| `f.richtext()` | Required: a heading, two paragraphs and a list where the toolset has them, else one paragraph. Optional: empty. |
+| `f.image()` | A placeholder picture, required or optional. It shows in the editor and in previews only, never on the live page; publishing treats it as no image, so a required image still asks for a photo. |
+| `f.ref(), f.refList()` | The collection's first published entries: one for a required f.ref, up to three for an f.refList, fewer if .max(n) is lower. |
+| `f.list(item)` | Required: .min(n) items, or three, never more than .max(n). Each item is filled the same way. |
+| `f.object({ … })` | Required: its fields, filled the same way. |
+
+Numbers, dates, links, videos and files are not filled (a number, a video and a file stay unset; a date and a link start empty), a list nothing fills starts as an empty list, and settings are never filled: they keep their defaults. An empty list in a sample (`people: []`) counts as left out. To choose the content yourself, put it in the sample.
+
+*Add section* has an *Insert filled* switch under its list. Turned off, a section arrives empty: without the sample and without anything generated. The picture still shows the filled section.
 
 The sample may set settings too, under their own keys.
 

package/docs/content-modeling/zones.md

@@ -58,7 +58,7 @@ The hero zone offers a choice of two openers and takes one of them. The body tak
 
 ## 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.
+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. The picker shows each section as your site draws it, filled where its `sample` is silent; its *Insert filled* switch, when turned off, inserts the section empty instead ([Sample content](../content-modeling/sections.md#sample-content)).
 
 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.
 
@@ -66,7 +66,7 @@ An empty zone shows as a box in the canvas so it can take a section. On the site
 
 ## 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.
+`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 *Globals* 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.
 

package/docs/getting-started/working-together.md

@@ -20,7 +20,7 @@ Editors sign in at smoodly.io, never on your site: `/admin` sends them there and
 
 ## Who is editing what
 
-A lock after a title in Pages, in a collection or in Sections means someone else has that item open in the language you are looking at. Hover it for their name. Opening the item anyway shows a line under the top bar: *aleksi is also editing this page.* Nothing is locked; it is a heads-up.
+A lock after a title in Pages, in a collection or in Globals means someone else has that item open in the language you are looking at. Hover it for their name. Opening the item anyway shows a line under the top bar: *aleksi is also editing this page.* Nothing is locked; it is a heads-up.
 
 Presence runs on Smoodly's service, over one connection per open admin tab. Without it the admin works exactly the same, minus the locks and the line; a tab that loses its connection reconnects on its own.
 

package/docs/globals/defining.md

@@ -45,7 +45,7 @@ Register the list in the config's `globals`. A visual global's section must be i
 
 ## In the admin
 
-*Sections*, under ⋮ in the admin's top bar, lists every global with its kind, *Visual* or *Fields*, and its status in the selected language. A *Fields* global opens a form like an entry's, the fields in schema order. A *Visual* global opens on a canvas: a page of the site that shows it, the home page for a `layout` global and otherwise the first page that places it, with the global selected and the rest of the page dimmed. Its fields sit beside the canvas under *Content* and *Settings*, text marked for inline editing can be typed in place, and when several pages place it, *Shown on* picks the page. A visual global no page shows yet opens as a form. Either way the page autosaves, and carries the same *Publish* control, *History* and *Discard changes* as a page.
+*Globals*, under ⋮ in the admin's top bar, lists every global with its kind, *Visual* or *Fields*, and its status in the selected language. A *Fields* global opens a form like an entry's, the fields in schema order. A *Visual* global opens on a canvas: a page of the site that shows it, the home page for a `layout` global and otherwise the first page that places it, with the global selected and the rest of the page dimmed. Its fields sit beside the canvas under *Content* and *Settings*, text marked for inline editing can be typed in place, and when several pages place it, *Shown on* picks the page. A visual global no page shows yet opens as a form. Either way the page autosaves, and carries the same *Publish* control, *History* and *Discard changes* as a page.
 
 A global exists in every language from the start, so there is nothing to add or delete. Publishing is per language, as for pages. A field's value is shared across languages unless it chains `.localized()`: the starter's contact email is one value, its address is translated.
 

package/docs/globals/header-and-footer.md

@@ -112,6 +112,6 @@ On a single-language site there are no links and the header shows the brand and
 
 ## Editing them
 
-Editors change the header and footer under *Sections*, or in any page's canvas: both are selectable there, tagged *global*, with their own form and their own *Publish* in the inspector. The header's navigation edits in place like any list with [marks](../content-modeling/marks.md). Publishing a page never publishes the footer, because a footer going live on every page is a deliberate click.
+Editors change the header and footer under *Globals*, or in any page's canvas: both are selectable there, tagged *global*, with their own form and their own *Publish* in the inspector. The header's navigation edits in place like any list with [marks](../content-modeling/marks.md). Publishing a page never publishes the footer, because a footer going live on every page is a deliberate click.
 
 Next, [The media library](../media/library.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoodly",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "Open-source, code-first CMS for Astro and Next.js: define a component once, it becomes a typed, editable building block.",
   "license": "MIT",
   "engines": {