Blocks Portfolio Pack

Portfolio blocks for Tome: a practice that works project by project shows one featured project as the hero and files every project under its permanent job number. The blocks read the project records of @wabbit/tome-portfolio, so nothing a block prints is typed twice, and they are written for the Studio theme (neutral by default, restyled through public data-* hooks).

Status: preview. Five blocks: work-index (four layouts: feature, index, selected and next), title-block, service-rows, and the case-study pair project-hero and plate-sequence. register() adds them as the portfolio-pack bundle, tier free.

Block styles read --tome-* tokens, so load the design tokens once in your global CSS, as with every Tome pack.

Register the block configs into your registries:

// payload.config.ts
import { BlockRegistry, BundleRegistry } from '@wabbit/tome-blocks-core/registry'
import { register } from '@wabbit/tome-blocks-portfolio-pack'

const blockRegistry = new BlockRegistry()
const bundleRegistry = new BundleRegistry()

register(blockRegistry, bundleRegistry)

workIndexBlock.block({ projectsSlug }) takes the projects collection slug (default portfolio-projects); pass projectsSlug: null on a site without the portfolio layer and the block offers only its inline fields.

Register the renderers once at app startup:

import { registerRenderers } from '@wabbit/tome-blocks-portfolio-pack/render/register'

registerRenderers()

Blocks

The blocks are listed in the block catalog under the portfolio-pack bundle.

Where the data comes from

Each block carries a source field. collection (the default) reads the project records; inline uses the block's own fields, for a site with no Work collection.

The read is a virtual portfolioData field filled by an afterRead hook (makePortfolioReadHook), once per request and shared by every block on the page through req.context. The renderers stay pure: they receive plain data in a server component and in a client island alike. A failed read logs a warning and the block falls back to its inline fields; a page never fails because of the portfolio.

The hook reads @wabbit/tome-portfolio/server directly (listPortfolioProjects, featuredProject, getPortfolioProject, getPortfolioSettings), so there is nothing to wire. setPortfolioServer swaps that API for a wrapper or a test double, and setPortfolioServer(null) restores the layer's own.

A site can also pass entries it mapped itself (the studies precedent) and the route's parsed filter, as props on a wrapper around the renderer or through RenderBlocks({ context }):

Behavior worth knowing

• Numbers print as stored and are never renumbered. A gap (a project archived) stays a gap.
• Thresholds count visible projects. Under minForFilters (8) no filter UI renders and the count line stays; under minToShow (3) the whole index renders nothing.
• Filters work without script. Each chip is a button[aria-pressed] in its own form[method=get] carrying the query string the toggled state would produce. Counts are conditional: each facet ignores its own filter and applies the others.
• Never a made-up fact. A fact with no data drops its cell; an empty client prints the settings' "Private client", and a client the data does not say anything about (inline or mapped rows) drops.
• Accent is a mark, never text: a dot beside "New" and a square beside "Featured above" and the current plate, both aria-hidden.
• Filters apply in place. The index is one client island: a chip, a year or a place recomputes the list, the counts and the count line with the layer's own applyPortfolioFilter and facetPortfolioEntries, writes the URL with history.replaceState and restores from it on popstate. The serialized query comes from the layer's serializePortfolioFilter, so a shared link reproduces the state. A route that passes no filterState gets the URL (and the remembered view) applied after mount.
• The view is remembered. The Plates / Ledger toggle writes the cookie tome-portfolio-view (one year, SameSite=Lax, path /) and puts ?view= in the URL only when the choice differs from the block's default. A route reads it with readViewCookie(cookieHeader) (exported from ./render) into filterState.view, so the remembered view renders on the server with no swap.
• The phone sheet. Below 768px the band's chips give way to a Filter button that opens a dialog with every filter: type and status chips, two year selects and a place select, "Clear", and "Show N projects" (the live count). Focus moves in, Tab is trapped, Escape closes, and focus returns to the button. From 768px the button shows only when the sheet holds filters the band does not print (data-work-sheet-extra); a home slice that wants no sheet turns off facets.status, facets.years and facets.locality.
• The last filter is kept for the way back. The island writes the serialized filter to sessionStorage (tome-portfolio-last-filter); the next layout's "Back to the index" link reads the referrer, then that key, after mount. Every storage access is guarded: with storage or cookies blocked the page still renders and filters.
• `next` picks with the layer's walk. nextPortfolioEntry (from @wabbit/tome-portfolio/filters) is the same function the layer's nextPortfolioProject uses; the route passes currentProjectId, and withinFilter keeps the walk inside the filter the page was reached from.
• The morph is data on listing surfaces. Project links are plain <a> carrying data-project-id; the image carries data-transition-name="tome-project-<id>" and no view-transition-name, so a page never has two. A small head script in the theme names the clicked image at navigation time.

Public API

Server and client

Every renderer is a React server component except three client files: the index island (IndexIsland, filters, view toggle and the phone sheet), the next layout's BackLink, and the drawing viewer button and native <dialog> in plate-sequence (DrawingOpen.client.tsx, hidden until script runs; it opens a drawing at full size in a labelled, scrollable region, closes on Escape, the close button or the backdrop, and returns focus). None animates. Without JavaScript the ledger, the chips, the filtered state, the count line and the view toggle all work (the chips and the toggle submit GET forms); the phone sheet is the one piece that needs script, so its button appears only once the island runs.

Theming hooks

Public and stable (class names are scoped and are not): data-work-index with data-block-variant="feature|index|selected|next"; the index's data-work-view, data-work-view-toggle, data-work-view-option, data-work-sheet-open, data-work-sheet (and its -title, -close, -group, -label, -clear, -apply, data-work-year-from, data-work-year-to, data-work-locality), data-work-plates and data-work-tile (with -tile-image, -tile-caption, -tile-num, -tile-title, -tile-year, -tile-meta, -tile-credit); the selected rows' data-work-rhythm, data-work-straddle, data-work-selected-row (data-media-side, data-work-selected-scale), -text, -meta, -title, -teaser, -cta, -media, -credit and data-work-sample; the next teaser's data-work-next-media, -text, -label, -num, -title, -meta, -credit, -cta and data-work-back; the hero's data-work-feature-* and data-work-plate-count; the ledger's data-work-opener, data-work-tools, data-work-facet, data-work-chip, data-work-count, data-work-list, data-work-row (with data-project-id, data-status, data-new, data-featured-above), data-work-num, data-work-title, data-work-kind and data-work-thumb; the Title Block's data-title-block, data-tb-cell and data-tb-value; and the marks, data-mark="dot|square". The case-study blocks add project-hero's data-project-hero, -crumbs, -lead, -lead-image, -head, -plate-meta, -title, -summary, -about-label and -about; and plate-sequence's data-plate-sequence (with data-plate-mode and data-plate-surface), data-passage (-label, -number, -body, -figures, -sample), data-plate (with data-plate-size, data-plate-aspect, data-plate-pin, data-plate-caption-side, data-plate-kind), data-plate-images, data-plate-item, data-plate-image (with data-plate-number), data-plate-pair-label, data-plate-drawing, data-plate-caption, data-plate-count, data-plate-text, data-plate-credit, and the viewer's data-plate-open, data-plate-viewer (-bar, -title, -close, -scroll, -canvas). Drawings read --tome-drawing-ink, -muted, -surface and -font (with fallbacks), which a theme sets. The block's stylesheet places things on the page grid and sets a calm default look; a theme restyles through the hooks.