wiki-formant 0.112.1 → 0.114.0

package/README.md

@@ -43,7 +43,7 @@ await store.save({ tagPath, slug, content, authorId, message, baseVersion: page.
 - **A save is one statement**: the page update and its revision in a CTE guarded on the version read. A lost race, a stale `baseVersion`, a page deleted since or a rename onto a taken slug writes nothing and throws a 409 `HttpError` whose body names the reason as `conflict`: `stale` and `deleted` mean reload, `taken` means another slug (`ConflictReason`).
 - **The bump is the diff's**: added, removed or moved blocks are `major`, changed prose or title `minor`; `change` overrides it. A metadata-only save moves no version and writes no revision.
 - **History is diffed on read.** A revision stores the page as saved. `history(pageId, { limit })` reads one row more than it returns, so the oldest entry shown has its real predecessor.
-- **Listings carry a snippet, not the article**: `list`, `recent` and `byIds` drop `content`.
+- **Listings carry a snippet, not the article**: `list`, `recent` and `byIds` drop `content`, and carry `banner`, the page's picture for its card (`metadata.banner`, or the `banner` option's reading).
 - **Search is four tiers**: title prefix, title, literal prose, then full text on `search_tsv` with Postgres' headline as the snippet. Hidden paths, and paths under them, are left out unless named.
 - `branch` is an agent's walk of a path and everything under it; `counts` is pages per tag path.
 - Copy the models with `npx prisma-models wiki` (`--tenant` for a tenant-keyed copy), then build the full-text column with `npx fts-ddl '"WikiPage"'`.
@@ -466,6 +466,26 @@ return new ImageResponse(<SocialCard {...{ title, eyebrow, description }} {...fi
 - Fonts stay with the site: Next traces a font file only from a literal path in the app, and satori reads TTF or OTF.
 - `wiki-formant/seeded`'s `hashStr` and `seededRandom` are the deterministic randomness the art draws from, identical on server and browser.
 
+## Page banners
+
+`wiki-formant/banner`: the banner a page is headed with, its own picture or art seeded by the page.
+
+```tsx
+import { PageBanner, CardBanner } from 'wiki-formant/banner';
+
+<PageBanner seed={page.title + page.tagPath} picture={banner && <Image src={banner} alt="" fill preload sizes="100vw" />}>
+  <Breadcrumbs items={crumbs} />
+  <h1>{page.title}</h1>
+</PageBanner>
+<CardBanner seed={page.title + page.tagPath} picture={card.banner && <Image src={card.banner} alt="" fill sizes="33vw" />} />
+```
+
+- Every page has a banner: a page without a picture gets art seeded by `seed`, the same on every render, server and browser. `CardBanner` is the same picture or art at the top of the page's card, cropped to 4:1; seed both alike, so a card and its page match.
+- A listing carries `banner`, the picture both show: `metadata.banner` unless the store's `banner` option reads it elsewhere, such as the article's first picture. `BannerArt` alone is the art for any other frame.
+- The art is inline SVG with a class per role, coloured by custom properties: `--banner-from` and `--banner-to` the gradient (transparent unset), `--banner-mid` the blobs and half the shapes (`--ui-muted` unset), `--banner-ink` the rest and the dots (`--ui-accent` unset), over `--banner-field` (`--ui-surface` unset). A category's palette or a section's band is a style on the frame.
+- `mark` replaces the triangle with a wiki's own shape, as a path from its anchor, size and generator. `fill-opacity` on a role's class dims it under a title.
+- The frame's 4:1 is a floor, not a height (`base.css`): the trail and title grow it rather than being cropped.
+
 ## Revisions and history
 
 `wiki-formant/revisions`: what changed between two versions of a page, and which bump to ask for. `wiki-formant/history`: what each revision changed, as a history view shows it.

package/dist/banner.d.ts

@@ -0,0 +1,48 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+/**
+ * The art's third kind of shape, as a path: a wiki's own mark. Given its
+ * anchor, its size and the generator, so a mark that turns draws its turn
+ * from the same sequence. The default is a triangle round the anchor.
+ */
+export type BannerMark = (x: number, y: number, size: number, rand: () => number) => string;
+/**
+ * The seeded field: a gradient at a seeded angle, three soft blobs, five to
+ * eight shapes, four bright dots. Its colours are custom properties
+ * (`base.css`): `--banner-from` and `--banner-to` the gradient, transparent
+ * unless set, `--banner-mid` the blobs and half the shapes, `--banner-ink`
+ * the other half and the dots.
+ */
+export declare function BannerArt({ seed, mark, className }: {
+    seed: string;
+    mark?: BannerMark;
+    className?: string;
+}): ReactElement;
+/**
+ * A page's header: its picture, else its art, with the page's trail and title
+ * over it. `picture` is the app's own image element (`next/image` with `fill`,
+ * say), since this package has no `next`; it fills the frame. The frame's
+ * height is a floor of 4:1 that grows with what sits on it (`base.css`), so a
+ * long title on a phone never loses its trail. `style` carries a palette's
+ * custom properties.
+ */
+export declare function PageBanner({ seed, picture, mark, className, style, children }: {
+    seed: string;
+    picture?: ReactNode;
+    mark?: BannerMark;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): ReactElement;
+/**
+ * The same banner at the top of a page's card: its picture, else its art,
+ * in a 4:1 frame (`base.css`). Seed it as the page's header is seeded, so a
+ * card and the page it opens wear the same art. Decorative: the card's title
+ * names it.
+ */
+export declare function CardBanner({ seed, picture, mark, className, style }: {
+    seed: string;
+    picture?: ReactNode;
+    mark?: BannerMark;
+    className?: string;
+    style?: CSSProperties;
+}): ReactElement;

package/dist/banner.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { hashStr, seededRandom } from './seeded.js';
+const W = 800;
+const H = 200;
+const px = (v) => Math.round(v);
+const op = (v) => v.toFixed(2);
+const triangle = (x, y, s, rand) => `M${Array.from({ length: 3 }, () => `${px(x + rand() * s * 2 - s)} ${px(y + rand() * s * 2 - s)}`).join('L')}Z`;
+// Static strings, so a class checker sees every one.
+const FILL = ['banner-art__mid', 'banner-art__ink'];
+const LINE = ['banner-art__mid-line', 'banner-art__ink-line'];
+/**
+ * The seeded field: a gradient at a seeded angle, three soft blobs, five to
+ * eight shapes, four bright dots. Its colours are custom properties
+ * (`base.css`): `--banner-from` and `--banner-to` the gradient, transparent
+ * unless set, `--banner-mid` the blobs and half the shapes, `--banner-ink`
+ * the other half and the dots.
+ */
+export function BannerArt({ seed, mark = triangle, className = 'banner-art' }) {
+    const hash = hashStr(seed);
+    const rand = seededRandom(hash);
+    const id = `banner-${hash.toString(36)}`;
+    const shapes = [];
+    const angle = Math.floor(rand() * 360);
+    for (let i = 0; i < 3; i++) {
+        shapes.push(_jsx("circle", { className: FILL[0], cx: px(rand() * W), cy: px(rand() * H), r: px(60 + rand() * 120), opacity: op(0.15 + rand() * 0.2) }, `blob${i}`));
+    }
+    const count = 5 + Math.floor(rand() * 4);
+    for (let i = 0; i < count; i++) {
+        const x = rand() * W;
+        const y = rand() * H;
+        const tone = i % 2 === 0 ? 1 : 0;
+        const opacity = op(0.12 + rand() * 0.25);
+        const kind = Math.floor(rand() * 4);
+        const key = `shape${i}`;
+        if (kind === 0) {
+            shapes.push(_jsx("circle", { className: FILL[tone], cx: px(x), cy: px(y), r: px(8 + rand() * 40), opacity: opacity }, key));
+        }
+        else if (kind === 1) {
+            const w = px(20 + rand() * 80), h = px(15 + rand() * 50), rx = px(rand() * 12);
+            const turn = px(rand() * 60 - 30);
+            shapes.push(_jsx("rect", { className: FILL[tone], x: px(x), y: px(y), width: w, height: h, rx: rx, opacity: opacity, transform: `rotate(${turn} ${px(x)} ${px(y)})` }, key));
+        }
+        else if (kind === 2) {
+            shapes.push(_jsx("path", { className: FILL[tone], d: mark(x, y, 15 + rand() * 35, rand), opacity: opacity }, key));
+        }
+        else {
+            const r = px(12 + rand() * 30);
+            shapes.push(_jsx("circle", { className: LINE[tone], cx: px(x), cy: px(y), r: r, strokeWidth: (2 + rand() * 4).toFixed(1), opacity: opacity }, key));
+        }
+    }
+    for (let i = 0; i < 4; i++) {
+        shapes.push(_jsx("circle", { className: FILL[1], cx: px(rand() * W), cy: px(rand() * H), r: px(2 + rand() * 6), opacity: op(0.4 + rand() * 0.4) }, `dot${i}`));
+    }
+    return (_jsxs("svg", { className: className, viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: "xMidYMid slice", "aria-hidden": true, focusable: "false", children: [_jsx("defs", { children: _jsxs("linearGradient", { id: id, gradientTransform: `rotate(${angle})`, children: [_jsx("stop", { offset: "0%", className: "banner-art__from" }), _jsx("stop", { offset: "100%", className: "banner-art__to" })] }) }), _jsx("rect", { width: W, height: H, fill: `url(#${id})` }), shapes] }));
+}
+/**
+ * A page's header: its picture, else its art, with the page's trail and title
+ * over it. `picture` is the app's own image element (`next/image` with `fill`,
+ * say), since this package has no `next`; it fills the frame. The frame's
+ * height is a floor of 4:1 that grows with what sits on it (`base.css`), so a
+ * long title on a phone never loses its trail. `style` carries a palette's
+ * custom properties.
+ */
+export function PageBanner({ seed, picture, mark, className, style, children }) {
+    return (_jsxs("div", { className: className ? `page-banner ${className}` : 'page-banner', style: style, children: [picture ?? _jsx(BannerArt, { seed: seed, mark: mark }), children && _jsx("div", { className: "page-banner__body", children: children })] }));
+}
+/**
+ * The same banner at the top of a page's card: its picture, else its art,
+ * in a 4:1 frame (`base.css`). Seed it as the page's header is seeded, so a
+ * card and the page it opens wear the same art. Decorative: the card's title
+ * names it.
+ */
+export function CardBanner({ seed, picture, mark, className, style }) {
+    return (_jsx("span", { className: className ? `card-banner ${className}` : 'card-banner', style: style, "aria-hidden": true, children: picture ?? _jsx(BannerArt, { seed: seed, mark: mark }) }));
+}

package/dist/base.css

@@ -463,6 +463,45 @@ tbody > tr:nth-child(even) > :is(th, td):not(.chart *) { background-image: linea
 }
 .breadcrumbs .separator { user-select: none; }
 
+/* ---- PageBanner, CardBanner and BannerArt -----------------------------------------------
+   4:1 is a floor, not a height: the ratio-holder and the body share one grid
+   cell, so the row is as tall as whichever needs more, and a long title on a
+   phone grows the banner rather than losing its trail off the top. The column
+   is minmax(0, 1fr), not auto, which would size to a long title's unwrapped
+   line. `max-height` caps only the picture, never the words. */
+.page-banner {
+  position: relative;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  overflow: hidden;
+  border-radius: var(--ui-radius);
+  background: var(--banner-field, var(--ui-surface));
+}
+.page-banner::before { content: ''; grid-area: 1 / 1; aspect-ratio: 4 / 1; max-height: 12rem; }
+.page-banner > :is(img, picture, svg) { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+/* `relative` only so it paints above the picture. */
+.page-banner__body {
+  grid-area: 1 / 1;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  min-width: 0;
+  padding: var(--ui-pad);
+}
+.page-banner__body > :is(h1, nav) { margin: 0; }
+/* CardBanner: the same picture or art at the top of a card, cropped to 4:1. */
+.card-banner { position: relative; display: block; aspect-ratio: 4 / 1; overflow: hidden; background: var(--banner-field, var(--ui-surface)); }
+.card-banner > :is(img, picture, svg) { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.banner-art { display: block; width: 100%; height: 100%; }
+.banner-art__from { stop-color: var(--banner-from, transparent); }
+.banner-art__to { stop-color: var(--banner-to, transparent); }
+.banner-art__mid { fill: var(--banner-mid, var(--ui-muted)); }
+.banner-art__ink { fill: var(--banner-ink, var(--ui-accent)); }
+.banner-art__mid-line { fill: none; stroke: var(--banner-mid, var(--ui-muted)); }
+.banner-art__ink-line { fill: none; stroke: var(--banner-ink, var(--ui-accent)); }
+
 /* ---- Pager and SnapDots -----------------------------------------------------
    One line that never wraps, the count in tabular figures so stepping does not
    shift it. A step is a bare control: its colour, size and hit area are the

package/dist/store.d.ts

@@ -26,6 +26,7 @@ export interface WikiPageRow<B = unknown> {
  */
 export type WikiPageListing = Omit<WikiPageRow, 'content'> & {
     snippet: string;
+    banner: string | null;
 };
 export interface WikiPageRef {
     tagPath: string;
@@ -72,6 +73,12 @@ export interface WikiStoreOptions<B extends DiffBlock> {
      * article's opening; a wiki that keeps a written summary in metadata says so.
      */
     snippet?: (page: Pick<WikiPageRow<B>, 'content' | 'metadata'>) => string;
+    /**
+     * The picture a page's banner and card show, if it has one. Defaults to
+     * `metadata.banner`; a wiki whose pages carry no banner of their own may
+     * read the article's first picture instead.
+     */
+    banner?: (page: Pick<WikiPageRow<B>, 'content' | 'metadata'>) => string | null | undefined;
 }
 export interface SaveInput<B> {
     tagPath: string;
@@ -173,6 +180,7 @@ export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreO
             createdAt: Date;
             updatedAt: Date;
             snippet: string;
+            banner: string | null;
         }[];
         total: number;
     }>;

package/dist/store.js

@@ -44,9 +44,10 @@ export function orderByIds(rows, ids) {
 export function wikiStore(o) {
     const site = o.siteId ?? '';
     const opening = o.snippet ?? ((page) => describe(openingText(page.content)));
+    const bannerOf = o.banner ?? ((page) => (typeof page.metadata?.banner === 'string' ? page.metadata.banner : null));
     const listing = (row) => {
         const { content: _, ...rest } = row;
-        return { ...rest, snippet: opening(row) };
+        return { ...rest, snippet: opening(row), banner: bannerOf(row) ?? null };
     };
     const hidden = [...(o.hidden ?? [])];
     const rows = async (query, ...values) => (await o.sql(query, ...values));
@@ -168,6 +169,7 @@ export function wikiStore(o) {
             ...row,
             ...(withContent ? { content: content } : {}),
             score: tier,
+            banner: bannerOf({ content: content, metadata: row.metadata }) ?? null,
             snippet: (headline ? decodeEntities(headline).replace(/\s+/g, ' ').trim() : '')
                 || matchSnippet(content, query, () => opening({ content: content, metadata: row.metadata })),
         }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.112.1",
+  "version": "0.114.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",
@@ -253,6 +253,11 @@
       "import": "./dist/seeded.js",
       "default": "./dist/seeded.js"
     },
+    "./banner": {
+      "types": "./dist/banner.d.ts",
+      "import": "./dist/banner.js",
+      "default": "./dist/banner.js"
+    },
     "./og": {
       "types": "./dist/og.d.ts",
       "import": "./dist/og.js",