@getquick/content 0.1.0 → 0.3.0

package/README.md

@@ -2,8 +2,8 @@
 
 The configured content runtime for WordPress HTML and WPGraphQL. This slice
 provides pure helpers, the configured WordPress client, durable delivery and
-installed SQL migrations, and event/refresh HTTP handlers. This is not a
-completed or published 0.1.0 release pair.
+installed SQL migrations, and event/refresh HTTP handlers. It is released as a
+pair with the Composer package `getquick/gq-content`, at the same version and tag.
 
 ```ts
 import { renderWordPressBlocks, htmlLang } from "@getquick/content";
@@ -37,8 +37,8 @@ manual redirects and an eight-second deadline; failed reads return unavailable,
 confirmed absence returns missing, and successful reads return found.
 
 The root entry contains pure helpers and public structural types. The server
-entry exports `createContentRuntime`, `ContentConfig`, `ContentBindings`,
-`ContentRuntime` and `WordPressClient`. Runtime properties contain languages,
+entry exports `createContentRuntime`, `ContentConfig`, `ContentExtension`,
+`ExtensionNode`, `CollectionConfig`, `ContentBindings`, `ContentRuntime` and `WordPressClient`. Runtime properties contain languages,
 routing functions and the WordPress methods; credentials/configuration are kept
 in closures. Language configuration retains the source's normalization policy,
 and routing returns the same language objects held in that instance's array.
@@ -50,7 +50,9 @@ The reusable client methods retain their argument order:
 - `getDesignPresets()`
 - `getPublishedEntries()`
 - `getPublishedRoutes()`
-- `getSiteChrome(siteOrigin?, { location?, language? }?)`
+- `getArchives()`
+- `getSiteChrome(siteOrigin?, { location?, language? }?)` (menu, logo, icon,
+  header and footer patterns)
 
 From the repository root, use `vp install` and `vp run validate`. Validation
 builds compiled ESM/declarations through Vite+ Pack, checks formatting/lint/types,
@@ -62,7 +64,8 @@ untracked. The npm tarball allowlist contains only compiled output, the five ori
 separate consent database migrations and package metadata (npm also includes this README).
 
 The public delivery methods are `publishedHome(siteOrigin?, language?)`,
-`publishedEntry(path, siteOrigin?)` and `pageChrome(siteOrigin?)`. Supply a
+`publishedEntry(path, siteOrigin?)`, `pageChrome(siteOrigin?)` and
+`designPresets()`. Supply a
 `PUBLICATION_DB` structural binding to serve durable publications. Stored reads
 need no event or refresh secret and retain last-known-good content without an
 age limit. Cold entry lookups read the CMS once, preserving missing versus
@@ -72,6 +75,152 @@ Production without a store returns unavailable (chrome returns null). Only
 activates that fallback. All public reads guard server context before bindings
 or transport.
 
+`designPresets()` returns the stored design presets for a page that isn't a
+publication (live only in explicit development, null otherwise), and
+`internalOrigins(siteOrigin?)` the origins `menuItemHref` treats as this Site's.
+`blockPresetStyles(spacing, colors, scope?)` scopes the preset classes to a
+container (`.prose-wp` by default); `presetRootStyle(spacing, colors)` declares
+the presets on `:root`.
+
+## A Site's own content
+
+A Site whose WordPress plugin adds fields to its pages and posts declares them
+as an `extension`. The runtime reads them with each front page, page and post
+(with its blocks), stores the Site's value with the publication and serves it,
+typed, through outages:
+
+```ts
+const content = createContentRuntime<SiteBlocks>({
+  // …the configuration above…
+  extension: {
+    fields: { page: "wpBlocksJson pageBackgroundColor", post: "wpBlocksJson" },
+    // The Site's value for a node WordPress returned, or undefined for none.
+    read: ({ kind, fields }) => siteBlocks(fields.wpBlocksJson, fields.pageBackgroundColor),
+    // The stored value (JSON) read back, or undefined when it can't be served.
+    parse: (stored) => storedSiteBlocks.safeParse(stored).data,
+  },
+});
+const page = await content.publishedEntry("/about/");
+if (page.kind === "found" && page.content.entry.extension) {
+  // Render page.content.entry.extension (SiteBlocks); the front page's is
+  // home.page.extension.
+}
+```
+
+Rows stored before the Site declared it serve without it; a refresh stores it.
+A read throwing fails as WordPress's answer not matching the schema, and a read
+without its blocks stores nothing, so the stored page stays served. See ADR 0004.
+
+## Header and footer patterns
+
+The chrome also carries `header` and `footer`: the synced patterns GQ Design's
+Header & Footer selects for the design route `designTemplate` (default
+`"page"`; also `"front-page"`, `"home"`, `"archive"`, `"single-post"` or a
+Site-defined route). Each is `{ title, blocks }`, or null when the region uses
+a template part or nothing published is selected: keep the Site's own header
+or footer then. They are stored, refreshed and reconciled with the chrome, so
+visitors keep the last-known-good regions through CMS outages. A selected
+pattern GQ Design resolves to no blocks fails the chrome read and keeps what
+is stored. A `patterns` settings event refreshes the chrome. See
+[ADR 0006](../docs/adr/0006-serve-cms-selected-header-and-footer-patterns-with-site-chrome.md).
+
+The configured route is shared globally, including the homepage and posts;
+Content does not choose a different Design route for each visitor URL. Use a
+key registered in Design's manifest: an unknown key also returns null, and
+Content never retries another key.
+
+**Required GQ Design: 0.4.1 or newer** for the default `page` (`single` and
+`search` need 0.4.2). GQ Design 0.2.17 to 0.4.0 answer null for `page`, so the
+Site keeps its own regions. A GQ Design without `designPattern` at all (before
+0.2.17) doesn't fail the chrome: it is read without patterns, both null, and a
+warning names GQ Design and the version it needs (`WordPress: GQ Design has no
+designPattern field …`). Public selection excludes unpublished
+route/part sources and unpublished, protected or unsynced final patterns.
+Authoritative null removes a previous selection on a successful refresh;
+failed or malformed reads retain it.
+
+The ordinary menu and publication-store row remain language-specific, but
+`designPattern` takes no language. Every language receives the same unqualified
+pattern selection and its serialized data. Translated pattern trees are blocked
+by [gq-design #53](https://github.com/Quick-Release/gq-design/issues/53).
+
+Render a pattern with the Site's block renderers. Blocks with saved HTML
+render it with their children inside; `core/site-logo` has a built-in
+renderer; any other block without HTML (a dynamic or Site block) needs a
+renderer. Containers receive a basic WordPress wrapper, and GQ Design's
+`getquick-design/container` its layout (width, gap, padding) as content's
+containers do; unresolved dynamic leaves render nothing and are reported to
+`onUnrendered`:
+
+```ts
+import { designMenuItems, escapeHtml, type DesignBlockRenderer } from "@getquick/content";
+
+const headerNavigation: DesignBlockRenderer = (block, { href }) =>
+  `<nav aria-label="Primary"><ul>${designMenuItems(block.attributes.menuItems, href)
+    .map((item) => `<li><a href="${escapeHtml(item.href)}">${escapeHtml(item.label)}</a></li>`)
+    .join("")}</ul></nav>`;
+
+const header = content.renderDesignPattern(chrome?.header, {
+  siteOrigin: Astro.site?.origin,
+  home: language.home,
+  blocks: { "getquick/header-navigation": headerNavigation },
+  onUnrendered: (block) => console.warn(`No renderer for ${block.name}`),
+});
+```
+
+A renderer receives the block (`name`, `attributes`, `content`, `children`)
+and a context: `children` (rendered on demand), `render(blocks)`,
+`ancestors`, `home` and `href(url)`, which serves CMS and Site links as paths
+and replaces unsafe schemes with `#`. Its output is inserted as HTML: escape
+CMS text with `escapeHtml`. Saved HTML is trusted published CMS markup,
+not sanitized by this helper; full custom spacing/layout styling needs a Site
+renderer. With `consent` configured, the saved HTML in served patterns has its
+embeds rewritten into consent placeholders, as bodies do; a renderer building
+an embed from attributes uses `embedPlaceholder` (`@getquick/content/consent`)
+itself. The pure `renderDesignPattern` from the root entry
+takes `internalOrigins` instead of `siteOrigin`.
+
+## Collections and archive Pages
+
+A Site stores its custom post types' items as collections, and lists them from
+the publication store alone (never WordPress), for an archive Page's listing
+block:
+
+```ts
+const content = createContentRuntime({
+  // …the configuration above…
+  collections: {
+    biblioteca: {
+      postType: "biblioteca", // WordPress's name
+      graphqlType: "Biblioteca", // its graphql_single_name
+      taxonomies: ["categoria_biblioteca"], // each show_in_graphql
+    },
+  },
+});
+const page = await content.list({
+  collection: "biblioteca",
+  terms: { categoria_biblioteca: ["legislacao"] }, // any slug; every taxonomy given slugs
+  search: "lei", // title and excerpt, ignoring case and accents
+  page: 1, // a number (or numeric string); anything else throws
+  perPage: 12,
+});
+// { kind: "found", items: [{ uri, title, date, modifiedAt, excerpt,
+//   featuredImage, terms, extension?, language? }], total, page, pages }
+// or { kind: "unavailable", failure }
+const filters = await content.terms("biblioteca", "categoria_biblioteca");
+// { kind: "found", terms: [{ slug, name, count }] }
+const archive = await content.archiveUri("biblioteca"); // "/biblioteca/" or null
+```
+
+Items are entries: events, withdrawals and reconciliation keep them, and
+`publishedEntry` serves them with `entry.collection` (`name`, `terms`). The
+extension's `fields.collections[<name>]` selects an item's own fields (`read`
+gets `kind: "item"` and `collection`). In WordPress, GETQUICK → Archives
+assigns each type a Page, which takes over the type's archive address; saving
+it reads every archive address again. A type or taxonomy WPGraphQL doesn't
+show, a `graphqlType` that isn't the type's, or a taxonomy not connected to
+it fails the archives read, by name. See ADR 0005.
+
 Infrastructure imports the Node-only migration entry separately:
 
 ```ts

package/dist/consent-astro.js

@@ -1,6 +1,6 @@
 import { S as SERVICE_CATALOG, T as copyLanguage, c as grantedCategories, d as promptReason, f as readConsentCookie, x as OPTIONAL_CATEGORIES } from "./state-BYWc5TUB.js";
 import { a as CONSENT_COPY, c as legalRevisions, r as escapeHtml } from "./embeds-p9SyGNZI.js";
-import { t as CONSENT_UI_VERSION } from "./version-Dn6VLZJO.js";
+import { t as CONSENT_UI_VERSION } from "./version-D_Ao31D3.js";
 import { t as CONSENT_CONFIG_ID } from "./client-config-B3LNSOxl.js";
 import { t as CONSENT_PATH } from "./paths-Cmzzof3v.js";
 //#region frontend/src/consent/astro.ts

package/dist/consent.js

@@ -1,5 +1,5 @@
 import { C as SERVICE_IDS, D as hostMatches, E as embedService, O as hostService, S as SERVICE_CATALOG, T as copyLanguage, _ as consentConfiguration, a as consentCookie, b as COPY_LANGUAGES, c as grantedCategories, d as promptReason, f as readConsentCookie, g as MEASUREMENT_ID, h as CONSENT_COPY_REVISION, i as DECISION_VALIDITY_MS, k as isServiceId, l as isConsentId, m as serviceGranted, n as CONSENT_COOKIE, o as decide, p as serializeConsentState, r as CONSENT_COOKIE_MAX_AGE_SECONDS, s as denyAll, t as CONSENT_ACTIONS, u as parseConsentState, v as needsBanner, w as catalogService, x as OPTIONAL_CATEGORIES, y as CONSENT_CATEGORIES } from "./state-BYWc5TUB.js";
 import { a as parseConsentRecordRequest, i as isRecordToken, n as consentRecordRequest, r as isLegalRoleName, t as MAX_RECORD_BYTES } from "./records-Dumrz759.js";
 import { a as CONSENT_COPY, c as legalRevisions, i as rewriteEmbeds, l as parseLegalLanguage, n as embedPlaceholder, o as LEGAL_ROLES, r as escapeHtml, s as REQUIRED_LEGAL_ROLES, t as blockedPlaceholder } from "./embeds-p9SyGNZI.js";
-import { t as CONSENT_UI_VERSION } from "./version-Dn6VLZJO.js";
+import { t as CONSENT_UI_VERSION } from "./version-D_Ao31D3.js";
 export { CONSENT_ACTIONS, CONSENT_CATEGORIES, CONSENT_COOKIE, CONSENT_COOKIE_MAX_AGE_SECONDS, CONSENT_COPY, CONSENT_COPY_REVISION, CONSENT_UI_VERSION, COPY_LANGUAGES, DECISION_VALIDITY_MS, LEGAL_ROLES, MAX_RECORD_BYTES, MEASUREMENT_ID, OPTIONAL_CATEGORIES, REQUIRED_LEGAL_ROLES, SERVICE_CATALOG, SERVICE_IDS, blockedPlaceholder, catalogService, consentConfiguration, consentCookie, consentRecordRequest, copyLanguage, decide, denyAll, embedPlaceholder, embedService, escapeHtml, grantedCategories, hostMatches, hostService, isConsentId, isLegalRoleName, isRecordToken, isServiceId, legalRevisions, needsBanner, parseConsentRecordRequest, parseConsentState, parseLegalLanguage, promptReason, readConsentCookie, rewriteEmbeds, serializeConsentState, serviceGranted };