@graview/pages

@graview/pages is one of the 14 npm packages of Graview, a TypeScript framework that derives an app’s interface, permissions and agent tools from one declaration. The traditional face: a routed webapp derived from the same declaration that drives the scene.

pnpm add @graview/pages

Entry points: @graview/pages, @graview/pages/static, @graview/pages/device, @graview/pages/visitor-form, @graview/pages/splash

What it is

The traditional face: a routed webapp derived from the same declaration that drives the spatial scene. From one defineApp — schema, mutations, invariants, permissions, op log — this package serves lists, records, forms, problems and history as ordinary linked pages: / the gallery, /:plural per kind, /:plural/:id per node, /places/:as per picture, /map the relations, /problems.

  • One store, no second path. Pages read through the same Store and write through the same mutations with the same principal; withheld actions render disabled with their refusal. recordFacts composes the derivations the scene already uses (labels, readable fields, violations touching, derived affordances) — the parity tests hold a record page and the spatial detail to identical facts.
  • The page registry mirrors the view registry. (kind × page-type) → component, defaults overridable per cell; the shell, home and problems pages are themselves registrations (registry.surface(...)).
  • Forms are derived. formFields (in @graview/core/forms) walks a mutation's zod input into a control tree — scalars, dates, node pickers over real candidates, nested objects, discriminated unions as a type picker plus that arm's fields, arrays as repeatable rows — and DerivedForm renders it. Nothing renderable is hand-written; anything unrenderable says so instead of hiding.
  • One bar: the scene or the pages, and the place you are on. The shell is the one app bar (FR-131): the app's mark and name — the page's one heading, the way home — then the switch, "Scene" and "Pages" (FR-137; the scene at its own address on a face that owns its page), then the place you are on as one control that opens every place: the home, the Lists, the Pictures (FR-138) — or, where the bar has room, the places themselves on the row, the rest under "More" (FR-145); then Find, the standing and the person. A page keeps only its own links — a picture its kind as a list, a record "In the scene ↗" to its stop there. Under an embed's bar the shell draws none of it, and the face's Find goes in that bar. A design's own shell stands under the bar too (context.barAbove), drawing only what is its own; surface("shell", Shell, { without: ["bar"] }) makes it the whole window. Each page's own title is said a level under the app's name. See apps/todo for both mounted from one declaration (/ scene, /pages routed).
  • A page says where you are. Each derived list, record and picture opens with a trail — a nav called "You are here": the section the kind's pages are in, the kind's list, and the page itself last, aria-current="page" and out of sight, since its heading says it — on one line at a phone's width, its links under the face's base. `registry.section(kinds, label, { path })` names the section ("Plan" over change plans and their steps), and sectionOf(kind) reads it back. A design's own shell asks usePlaceHere() — `{ as, kind, id, label, section, trail }` — to light its own tab and draw its own trail, or places <PageTrail />, which the derived pages then leave to it; without: ["trail"] goes without. A bar outside the face's router reads placeHere(context, path).
  • The scene may live elsewhere. A page's links into the scene go to / unless the host says where the scene is: set sceneHref in the PagesApp context (sceneHref: "/scene/places/overview") when it is not at /, and pass the same to spatialHref(id, sceneHref) and placeHref(as, sceneHref) in a page of your own.
  • The host may own the history. basename mounts the face under a path; onNavigate(path, how) tells a host each page the face opens ("push", "replace" or "pop"), and path sends it back to one, so a host that keeps its own history keeps the face's too.
  • Mobile is an acceptance criterion. pnpm pages runs the phone-width harness (390×844): no sideways scroll, named links, labeled controls, and a derived form that actually applies.
  • It lands on a gallery. The home opens with the standing as its headline — "2 gardeners, 3 plots and 1 planting.", or "Nothing here yet." and which act begins it — then every picture the app has as a large live card, two across at a desk and one on a phone: the lens itself, drawn inert at a scale measured from the card, captioned with its name and how much it is over. Handed the scene's view registry (views in the context), every titled lens is a page at /places/<as> and a card on the home; a kind with no titled lens is drawn anyway, as a contact sheet of its members, so a new app lands on a gallery on its first afternoon. The kinds follow as one row of counts, the relations as one line that opens /map ("Connections"), and Recently stays short at the foot. The app bar is one row on a desk and two on a phone; a new address opens at its top. How many problems there are is said once, by the bar's standing; the home says only that rules are broken and links to what would fix them.
  • It reads like the product's own site. A list opens with the plural and its description, a record with its title and its kind's describe, controls receding below the content. Typography rides the brand's display and body faces at a real scale; the brand's mark, name and per-kind accents (hueFor, from @graview/core) carry through every page. Still derivation: nothing here is a per-app template, and an app overrides a cell the same way it overrides a view.
  • A form for a visitor. @graview/pages/visitor-form's VisitorFormPage draws one act's form alone — the declaration's forms.<name>, its title, intro and the fields it names — over the store as the visitor is served it, runs the act as them, and says it was received in the declaration's own words. @graview/embed/form mounts it.
  • A page is also a string (FR-174). @graview/pages/static renders a place without a browser: renderPlace(store, declaration, place, { viewer, look }) answers `{ html, css, title, found }` — a list, a record, a declared place or the home as one self-contained document in the app's look, with no script, under the viewer's sight, printable (each section of a place a page of its own). It imports no React, so a Worker re-renders a fixed link — a schedule as a PDF — on each change. staticCss is its sheet alone. See docs/static-pages.md.
  • A place on a fixed screen, and what each part of it does. @graview/pages/device's renderScreen(store, declaration, place, { profile: "eink", viewport, viewer, page }) draws a place for an e-ink reader at the viewport its host names — its colors the sixteen grays (the host quantizes the picture to its panel), no motion, no hover, no script, nothing fetched, type for arm's length, every press at least 64 px — at a fixed layout the framework works out itself, a long place on pages. It answers { html, css, title, found, renderId, page, taps }: taps is each pressable region's rectangle in the viewport's pixels and what it does (go, open, act, page, refresh), exactly where the browser draws it. tapAt finds the region under a point; resolveTap says what it does now — a place to hand back to renderScreen, never a URL to follow — answers only a press the screen still offers, and runs an act only on the screen the app still draws for that seat. The strip along its foot is the declaration's devices.screens, else the home and its jobs, else its bar. It imports no React, so a Worker draws it; the host's browser takes the picture. See docs/static-pages.md.
  • An opening screen, from the document. @graview/pages/splash's `splashHtml(brand, { scheme?, name?, title?, kicker?, fade? }) draws a document's brand.splash — plain, editorial, shader` (one of a few shaders shipped here, named by shader, never written in a document) or ascii, with an image as the logo takes one, a title and a kicker — as `{ html, css, script }`: a host inlines the three in its first HTML before the app's root, and the script takes the screen away once a place says data-graview-drawn (or the page fails, or fifteen seconds pass), still under reduced motion. It imports nothing — not React, not the framework — so a page's first paint never waits on the bundle the screen covers for. graview preview inlines it; a brand with no splash answers empty strings. The screen is a status named by its title; title and kicker say a page's own words over the brand's, and fade: false takes it away at once, as automation (navigator.webdriver) does. The shaders are drift, ripple, veil and caustics (light through water).

The host applies themeCss from @graview/primitives (or supplies its own --graview-* tokens); the default pages render entirely from those tokens.

What it exports (66)

Read off the package's own barrel, so this is what is there today.

  • actsBeyondFacts
  • ARRANGE_FROM
  • beginningsFor
  • beginningsFrom
  • blankWritable
  • createPageRegistry
  • DefaultHomePage
  • DefaultListPage
  • DefaultMapPage
  • DefaultPlacePage
  • DefaultPlacesPage
  • DefaultProblemsPage
  • DefaultRecordPage
  • DefaultSearchPage
  • DefaultShell
  • DerivedForm
  • FactSheet
  • foldedActs
  • Gallery
  • GalleryCard
  • galleryOf
  • kindFacts
  • kindMap
  • KindMapSection
  • kindOfSlug
  • LARGE_LIST
  • lastChangeOf
  • Link
  • ListPage
  • listPageViewOf
  • MemoryRouter
  • NavLink
  • ONE_FACE_ARRIVING
  • PageFind
  • PageMain
  • PageQuickAsk
  • PagesApp
  • PagesRoutes
  • pageStyles
  • PageTrail
  • PageUndo
  • pathOfPlace
  • PlaceCard
  • placeHere
  • placeHref
  • placePath
  • PlacePicture
  • pluralSlug
  • rankedRepairs
  • recordFacts
  • RecordField
  • recordPath
  • relationFacts
  • Repairs
  • SceneLink
  • SearchToCreate
  • spatialHref
  • StartFreshLink
  • titleFieldOf
  • useLocation
  • useNavigate
  • useParams
  • usePlaceHere
  • useSearchParams
  • useStoreTick
  • WhyLine