@sudajs/cli 0.18.9 → 0.18.10

package/templates/theme/docs/agent-guides/templates-and-locales.md

@@ -0,0 +1,206 @@
+# Templates and Locales
+
+Read this guide before changing CMS templates, post resources, starter pages,
+authored page data, editor locales, preview content locales, or language links.
+The root `AGENTS.md` rules still apply.
+
+## Authored page data
+
+- Wrap hand-authored data with `defineSudaPageData(pageConfig, data)` when
+  practical.
+- Every page uses `root: { props: {} }` and a `content` array.
+- Every top-level `content[].type` must exactly match a public key in
+  `pageConfig.components`.
+- Every top-level item needs a stable `props.id`.
+- Do not put `id` in component `defaultProps`, local block `defaultProps`,
+  `defaultBlocks`, or block-slot nested items.
+- Nested block-slot items use the short kind from
+  `blockSlots.<slotName>.blocks`, such as `"button"`, `"copy"`, or `"cards"`.
+  Never author `__suda_local_block__/...`.
+- Use public authored props exactly as typed. Do not guess alternate field
+  names or add compatibility fallbacks.
+
+```ts
+defineSudaPageData(pageConfig, {
+  root: { props: {} },
+  content: [
+    {
+      type: "Hero",
+      props: {
+        id: "Hero-1",
+        title: "Welcome",
+        actions: [{ type: "button", props: { label: "Contact us", href: "/contact" } }],
+      },
+    },
+  ],
+});
+```
+
+## CMS contract
+
+Suda CMS is a fixed post system. Themes provide exactly four entries through
+`cmsTemplates`:
+
+- `posts`: list at `/posts`.
+- `post`: detail at `/posts/:slug`.
+- `tags`: tag/category list at `/tags`.
+- `tag`: posts for one tag at `/tags/:slug`.
+
+Each entry is `{ title: string; data: PageData }`, not raw `PageData`:
+
+```ts
+export const cmsTemplates: ThemeCmsTemplates = {
+  posts: { title: "Posts", data: postIndexTemplate },
+  post: { title: "Post", data: postDetailTemplate },
+  tags: { title: "Tags", data: tagIndexTemplate },
+  tag: { title: "Tag", data: tagDetailTemplate },
+};
+```
+
+Do not bypass the contract with intersection casts. Do not create variants such
+as `post.default`, `post.modern`, or `posts.magazine`, arbitrary collection
+types, or manual data-source binding contracts.
+
+CMS-only main sections:
+
+- `MainPosts`: `placement: { cmsTemplates: ["posts", "tag"] }` when shared;
+  render `cms.posts`, `cms.pagination`, and optional `cms.currentTag`.
+- `MainPost`: only `post`; render when `cms.type === "post"`.
+- `MainTags`: only `tags`; render when `cms.type === "tags"`.
+- A separate `MainTagPosts` is valid when clearer than sharing `MainPosts`.
+
+Read CMS data through `getCmsContent(puck?.metadata)`. CMS main sections must
+not declare a `posts` field.
+
+For pagination, use the exact platform fields:
+
+- `cms.pagination.page`
+- `cms.pagination.totalPages`
+- `cms.pagination.hasPreviousPage`
+- `cms.pagination.hasNextPage`
+- `cms.pagination.previousUrl`
+- `cms.pagination.nextUrl`
+
+Use `cmsPaginationUrl(cms.pagination, targetPage)` for numbered links so current
+filter/search parameters survive. Do not hand-build query strings.
+
+## Ordinary page post sections
+
+Provide at least one reusable ordinary-page post section such as
+`FeaturedPosts`, `LatestPosts`, or `TopicPosts`. It has exactly one top-level
+`posts` field and a default query on the same prop:
+
+```ts
+fields: {
+  postList: { type: "posts", label: t("sections.featuredPosts.fields.posts") },
+},
+defaultProps: {
+  postList: { strategy: "featured", limit: 3 },
+},
+```
+
+Supported strategies are `latest`, `featured`, `by_tag`, and `manual`. Manual
+queries contain only `items` and must not contain `limit`.
+
+Resolve data with the exact component id and field key:
+
+```ts
+const posts = getPostResource(puck?.metadata, {
+  componentId: props.id,
+  fieldKey: "postList",
+});
+```
+
+The platform keys resources from both values. Do not import Prisma, call
+platform APIs, or query a database from theme code. Do not add
+`resourceQuery`, `resource_query`, assume the field is named `query`, nest a
+posts field, or declare more than one posts field on a section.
+
+For returned posts, prefer `post.url`. If missing, derive only from `post.slug`
+as `/posts/${encodeURIComponent(post.slug)}`; if neither exists, use `#`. Do not
+probe guessed fields such as `href`, `path`, `permalink`, `postUrl`, or
+`canonicalUrl`.
+
+## Starter pages
+
+- Define realistic starter pages in `src/templates.ts`; do not ship placeholder
+  pages or a mechanical list of every component.
+- Include one home/index page with `isHome: true`.
+- A strong theme usually includes several purposeful pages such as `index`,
+  `about-us`, `contact-us`, `services`, and `team`, but only the home page is a
+  hard requirement.
+- Reuse conversion sections when they support the visitor journey, but vary
+  page purpose, copy, proof, media, and ordering so pages are not interchangeable.
+- Use only registered public component keys, stable top-level ids, and short
+  block-slot kinds.
+- Use `themeAsset("assets/...")` for bundled media.
+- Starter slugs preview at root-like paths: `index` is `/index`, `contact-us`
+  is `/contact-us`. Never use `/pages/...`.
+
+## Editor labels
+
+The host localizes editor configuration through `src/i18n.ts`.
+
+- Use `t("stable.dot.path")` for component, category, field, nested field,
+  local-block, and option labels.
+- Add every key to `src/locales/en.json`, the required reference locale.
+- Locale JSON must be nested objects with string leaves. Arrays, numbers,
+  booleans, and null are invalid.
+- Every additional `src/locales/<locale>.json` must have exactly the same leaf
+  keys as `en.json`; missing or extra keys fail validation and publishing.
+- The CLI copies locale files into `dist/locales/`. Never edit dist copies.
+- Do not use editor `t(...)` in public content, starter copy, default prop
+  values, or public-site text.
+
+Installed legacy themes may show translation keys when locale files are absent;
+new themes must still pass locale validation.
+
+## Starter preview content locales
+
+Use the separate `src/preview-i18n.ts` helper only in starter page templates for
+visitor-visible titles, headings, descriptions, list copy, and button labels.
+
+- Keep URLs, slugs, ids, component types, and asset paths as direct strings.
+- Do not use preview translations in component labels, fields, `defaultProps`,
+  layout configuration, or CMS templates.
+- When `manifest.previewLocales` exists, it must include `en`, and
+  `src/locales/en.content.json` is required.
+- Every declared preview locale needs a matching
+  `src/locales/<locale>.content.json` with exactly the same string leaf keys as
+  `en.content.json`.
+- Undeclared, missing, extra, or partial content locale files fail validation
+  and publishing.
+
+Files named `<locale>.json` are editor messages. Files named
+`<locale>.content.json` are starter preview content. Keep the two namespaces
+separate.
+
+## Public language links
+
+Read language targets with `getSiteLocale(puck?.metadata)` from
+`@sudajs/theme-engine/runtime`. Render the host-provided `label` and `href`.
+Do not derive language names or construct locale URLs in theme code.
+
+```tsx
+const siteLocale = getSiteLocale(puck?.metadata);
+
+return siteLocale?.locales.map((item) => (
+  <a key={item.locale} href={item.href} lang={item.locale}>
+    {item.label}
+  </a>
+));
+```
+
+## Verification
+
+After changing templates or locales, run:
+
+```bash
+pnpm typecheck
+pnpm build
+pnpm validate
+suda theme check
+```
+
+Open every starter and CMS preview route and verify content, links, empty states,
+pagination, and locale variants.