wiki-formant 0.106.0 → 0.107.0

package/README.md

@@ -445,6 +445,7 @@ export const generateMetadata = () => ({
 ```
 
 - Next replaces `openGraph` and `twitter` per segment rather than merging, so `pageMetadata` sets both; `sitePageMetadata({ siteName, handle })` binds the fields every page's card needs.
+- `sitePageMetadata({ ..., card: `${SITE_URL}/og` })` binds the site's card route, and a page then passes `card: { title, eyebrow, description, banner }` in place of `image`. `cardUrl(base, fields)` is the same address for JSON-LD: empty fields left out, the order fixed, so one card has one URL.
 - `articleLd` requires `image`. `collectionLd` is an index over an `ItemList`. `siteGraphLd` is the Organization, WebSite and `WebAPI` `@graph` for the root layout, and `siteRefs(url)` hands out the same `@id`s for a page's `publisher` and `isPartOf`.
 - `questionPairs(html)` reads a FAQ from headings ending in `?`; `faqPageLd(pairs, url)` is null under two pairs.
 - `describe(text)` is a meta description from any prose within `DESCRIPTION_LIMIT` (160): whole sentences where they fill half, else cut at a word with an ellipsis.

package/dist/metadata.d.ts

@@ -209,7 +209,10 @@ export declare function sitePageMetadata(site: {
     siteName: string;
     locale?: string;
     handle?: string;
-}): (o: Omit<PageMetadataOptions, "siteName" | "locale" | "handle">) => {
+    card?: string;
+}): ({ card, ...o }: Omit<PageMetadataOptions, "siteName" | "locale" | "handle"> & {
+    card?: CardFields;
+}) => {
     openGraph: {
         publishedTime?: string;
         modifiedTime?: string;
@@ -243,6 +246,26 @@ export declare function sitePageMetadata(site: {
         canonical: string;
     } | undefined;
 };
+/**
+ * What a generated card draws: the text, and a banner that replaces its art.
+ * Any other key is a parameter only one site's route reads, such as the palette
+ * a radix-wiki section picks.
+ */
+export interface CardFields {
+    title?: string;
+    eyebrow?: string;
+    description?: string;
+    banner?: string | null;
+    [param: string]: string | null | undefined;
+}
+/**
+ * The address of a card route drawing `fields`, e.g. `cardUrl(`${SITE_URL}/og`, { title })`.
+ * Empty fields are left out, and the order is fixed (title, eyebrow,
+ * description, any site key, banner) whatever order the caller wrote, so one
+ * card has one URL and the CDN and X cache it once. Three wikis each built this
+ * query string by hand; the route that reads it is each site's own.
+ */
+export declare function cardUrl(base: string, fields: CardFields): string;
 /** The `@id` references a page's own node points at for `publisher` and `isPartOf`. */
 export declare function siteRefs(url: string): {
     organization: LdNode;

package/dist/metadata.js

@@ -257,8 +257,30 @@ export function describe(text, limit = DESCRIPTION_LIMIT) {
  * locale at all of them.
  */
 export function sitePageMetadata(site) {
-    const bound = { locale: 'en_US', ...site };
-    return (o) => pageMetadata({ ...o, ...bound });
+    const { card: base, ...rest } = site;
+    const bound = { locale: 'en_US', ...rest };
+    return ({ card, ...o }) => {
+        if (card && !base)
+            throw new Error('sitePageMetadata: a page passed `card` but the site bound no card route');
+        return pageMetadata({ ...o, ...(card ? { image: cardUrl(base, card) } : {}), ...bound });
+    };
+}
+const CARD_HEAD = ['title', 'eyebrow', 'description'];
+/**
+ * The address of a card route drawing `fields`, e.g. `cardUrl(`${SITE_URL}/og`, { title })`.
+ * Empty fields are left out, and the order is fixed (title, eyebrow,
+ * description, any site key, banner) whatever order the caller wrote, so one
+ * card has one URL and the CDN and X cache it once. Three wikis each built this
+ * query string by hand; the route that reads it is each site's own.
+ */
+export function cardUrl(base, fields) {
+    const keys = [...CARD_HEAD, ...Object.keys(fields).filter(k => !CARD_HEAD.includes(k) && k !== 'banner'), 'banner'];
+    const q = new URLSearchParams();
+    for (const k of keys)
+        if (fields[k])
+            q.set(k, fields[k]);
+    const query = q.toString();
+    return query ? `${base}?${query}` : base;
 }
 /** The `@id` references a page's own node points at for `publisher` and `isPartOf`. */
 export function siteRefs(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.106.0",
+  "version": "0.107.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",