wiki-formant 0.59.0 → 0.60.0

package/README.md

@@ -60,7 +60,7 @@ const letters = taxonomy.alphaControls('ecosystem', all, state); // [] below the
 Every control arrives as `{value, label, count, href, active}`, its `href` already built through your one builder with **every other axis carried along** — the arithmetic that, done by hand, drops the reader's letter the first time they press a chip.
 
 - **The reset control leads the row**, flagged `reset`, so a consumer that maps the array cannot ship a narrowed view with nothing to press to widen it.
-- **`alphaControls` returns `[]` below the index threshold**, folding in `needsAlphaIndex` — one call is either the index you needed or nothing, rather than a decision each caller makes and one caller forgets.
+- **`alphaControls` returns `[]` below the index threshold**, folding in `needsAlphaIndex` — one call is either the index you needed or nothing, rather than a decision each caller makes and one caller forgets. A hub's sort toggle reads the same predicate over the same unfiltered count (`needsAlphaIndex(all.length)`; 40 pages unless `alphaIndexMinPages` says otherwise), so a set small enough to need no index offers no sort either.
 - **`resolveLetter` drops a letter no page starts with.** A stray `?letter=Q` would otherwise empty the grid with no control marked to explain why.
 
 
@@ -367,7 +367,7 @@ are unit-tested without a DOM.
 `wiki-formant/react` carries `'use client'`, and that is a module-level boundary: anything exported from it hydrates in the consumer's tree whether or not it uses a hook. `wiki-formant/react-server` is the same React, without the directive — for the parts of a wiki that are pure functions of their props and should ship no JavaScript at all.
 
 `FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
-`FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
+`FacetBar` takes a `count` class to render each count as its own element, and `alphaFirst` to lead with the A–Z row. A chip row above the grid and a panel beside it are the same markup laid out by different stylesheets, so the class names are what tell them apart: `letterRow`, `letterControl` and `letterControlActive` style the A–Z row apart from the facet rows (each falls back to `row`, `control` or `controlActive`); a `text` class wraps each label in its own element and gives a facet option its value as `title`, so a long value can truncate while its count stays in view; and `letterCounts="title"` keeps each letter a bare glyph with its count in the tooltip. With none of them set the markup is what it was. Its JSON-LD goes out through `JsonLd`, which is exported for every other payload a page emits: it re-encodes each `<` as `\u003c`, because these payloads carry authored titles and an authored `</script>` would otherwise close the tag.
 
 `PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
 

package/dist/react-server.d.ts

@@ -31,15 +31,35 @@ export declare const Anchor: WikiLinkComponent;
  * tree, which is a shared convention, these are each design system's own words
  * for a chip and a row. Defaults are given so a consumer that shares them writes
  * nothing.
+ *
+ * Whether the bar is a chip row above the grid or a panel beside it is decided
+ * here and nowhere else: the markup is the same, the stylesheet behind these
+ * names lays it out.
  */
 export interface FacetBarClassNames {
     root?: string;
+    /** Each facet's row, and the A–Z row unless `letterRow` is set. */
     row?: string;
+    /** A row's heading: the facet's label, or `alphaLabel`. */
     label?: string;
+    /** A facet option, and a letter unless `letterControl` is set. */
     control?: string;
     controlActive?: string;
     /** Set it and each count is its own `<span>` with this class, not ` (n)` text. */
     count?: string;
+    /**
+     * Set it and each control's text is its own `<span>` with this class, and a
+     * facet option carries its value as `title`: the hook for truncating a long
+     * value while its count stays in view, with the full value one hover away.
+     */
+    text?: string;
+    /**
+     * The A–Z row and its letters, which a panel draws as a block of glyphs
+     * while its facet options run full width. Each falls back to its shared key.
+     */
+    letterRow?: string;
+    letterControl?: string;
+    letterControlActive?: string;
 }
 export interface FacetBarProps {
     link: WikiLinkComponent;
@@ -49,6 +69,11 @@ export interface FacetBarProps {
     alphaLabel?: string;
     /** Lead with the A–Z row: two lines against a facet block's twenty. */
     alphaFirst?: boolean;
+    /**
+     * Where a letter's count goes. `'inline'` prints it like an option's;
+     * `'title'` keeps the letter a bare glyph and puts its count in the tooltip.
+     */
+    letterCounts?: 'inline' | 'title';
     classNames?: FacetBarClassNames;
     /** The landmark's accessible name. */
     label?: string;
@@ -63,7 +88,7 @@ export interface FacetBarProps {
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, classNames, label: navLabel, }: FacetBarProps): import("react").JSX.Element | null;
+export declare function FacetBar({ link: Link, facets, letters, alphaLabel, alphaFirst, letterCounts, classNames, label: navLabel, }: FacetBarProps): import("react").JSX.Element | null;
 export interface FacetSummaryProps {
     shown: number;
     total: number;

package/dist/react-server.js

@@ -28,7 +28,8 @@ import { blockLocation } from './revisions.js';
  * Exported because `block-views` renders links too and had declared the same
  * three lines; a default that exists twice is a default that can diverge.
  */
-export const Anchor = ({ href, className, children }) => _jsx("a", { href: href, className: className, children: children });
+export const Anchor = (props) => _jsx("a", { ...props });
+const pagesPhrase = (n) => `${n} page${n === 1 ? '' : 's'}`;
 /**
  * The section's second axis, as pressable chips.
  *
@@ -39,20 +40,16 @@ export const Anchor = ({ href, className, children }) => _jsx("a", { href: href,
  * `aria-current`, not `aria-pressed`: a link is not a toggle button and does not
  * take that attribute.
  */
-export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, classNames = {}, label: navLabel = 'Filter pages', }) {
+export function FacetBar({ link: Link, facets, letters, alphaLabel = 'A–Z', alphaFirst = false, letterCounts = 'inline', classNames = {}, label: navLabel = 'Filter pages', }) {
     if (!facets.length && !letters.length)
         return null;
-    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, } = classNames;
-    const chip = (c) => (_jsxs(Link, { href: c.href, className: c.active ? controlActive : control, "aria-current": c.active ? 'true' : undefined, ...(c.title ? { title: c.title } : {}), children: [c.text, count ? _jsx("span", { className: count, children: c.n }) : ` (${c.n})`] }, c.key));
-    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip({ key: o.value, href: o.href, active: o.active, text: o.value, n: o.count }))] }, facet.key)));
+    const { root = 'stack tight', row = 'cluster', label = 'form-label', control = 'tag', controlActive = 'tag tag-removable', count, text, letterRow = row, letterControl = control, letterControlActive = controlActive, } = classNames;
+    const chip = (c, classes, opts) => (_jsxs(Link, { href: c.href, className: c.active ? classes.active : classes.idle, "aria-current": c.active ? 'true' : undefined, ...(opts.title ? { title: opts.title } : {}), children: [text ? _jsx("span", { className: text, children: c.label }) : c.label, opts.showCount && (count ? _jsx("span", { className: count, children: c.count }) : ` (${c.count})`)] }, c.value || 'all'));
+    const facetRows = facets.map(facet => (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: facet.label }), facet.options.map(o => chip(o, { idle: control, active: controlActive }, { title: text ? o.label : undefined, showCount: true }))] }, facet.key)));
     // The reset control leads the letters and says what it resets to.
-    const alphaRow = letters.length > 0 && (_jsxs("div", { className: row, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip({
-                key: l.value || 'all',
-                href: l.href,
-                active: l.active,
-                text: l.label,
-                n: l.count,
-                ...(l.reset ? { title: `All ${l.count} pages` } : {}),
+    const alphaRow = letters.length > 0 && (_jsxs("div", { className: letterRow, children: [_jsx("span", { className: label, children: alphaLabel }), letters.map(l => chip(l, { idle: letterControl, active: letterControlActive }, {
+                title: l.reset ? `All ${l.count} pages` : letterCounts === 'title' ? pagesPhrase(l.count) : undefined,
+                showCount: letterCounts === 'inline',
             }))] }, "alpha"));
     // A landmark: every control in it narrows the list below, and a screen
     // reader user skipping between regions should be able to land on it.

package/dist/taxonomy.d.ts

@@ -149,7 +149,11 @@ export interface Taxonomy {
     metadataRows: (tagPath: string, page: {
         metadata?: unknown;
     }) => MetadataRow[];
-    /** Whether a set has outgrown a grid and needs the A–Z index. */
+    /**
+     * Whether a set has outgrown a grid: the one size rule a hub's browsing
+     * controls read. `alphaControls` applies it; a sort toggle reads it too, with
+     * the same unfiltered count, so the two appear and vanish together.
+     */
     needsAlphaIndex: (pageCount: number) => boolean;
     href: (tagPath: string, state: CategoryState) => string;
     rankRelated: <T extends FacetablePage>(page: T, siblings: T[], tagPath: string, limit?: number) => RelatedRanking<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.59.0",
+  "version": "0.60.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",