Registry API reference UI

Platform spec article

Registry API reference UI

Back to api.json contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-api-json-primary-contract api.json primary Accepted

   api.json primary

   Context

   UI contract.

   Decision

   api.json is primary structured docs contract.

   Consequences

   Templates exempt.

   Verification anchors

   doc emission; pckg UI.

   Open full ADR page

2. 0002-hub-authority Hub authority Accepted

   Hub authority

   Context

   Informal notes.

   Decision

   Hub and ADRs supersede crate notes.

   Consequences

   Spec leads code.

   Verification anchors

   content verify.

   Open full ADR page

Articles

• Design model Schema v4 for api.json — full resolved API surface, signatures, and navigable type references. article Standard
• Registry API reference UI Normative layout and navigation for pckg package API documentation driven by api.json. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 4 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  api.json contract

  Parent feature hub

• Feature
  Design model

  Schema and library tree invariants

What this covers

How the pckg registry renders published package documentation as an API reference (Microsoft .NET API Docs–style), using api.json as the sole structure driver.

Page layout

Region	Content
Header	Package id, version, primary symbol search
Left rail	Library tree — collapsible modules, optional dependency groups, kind folders (Types, Enums, Contracts, Functions)
Center	Selected symbol: signature, type links, structured doc, docMarkdown body
Right rail	In-page table of contents from markdown headings
Overflow	Flat symbol grid and kind filters (secondary to the tree)

The main content column must stay aligned beside the left rail (not displaced below it).

URL routes

Route	Purpose
`/docs/{package}@{version}`	Package docs landing; default tree selection
`/docs/{package}@{version}/api/{qualifiedName}`	Deep link to one API row (qualifiedName percent-encoded)
`/docs/{package}@{version}/search/{query}`	Initial symbol search filter

The version segment may be latest or an exact registry version.

Library tree algorithm

1. Deserialize api.json with navigationModel: "graph-v1" and schemaVersion >= 3.
2. Build parent/child edges from parentId / memberIds only (design model).
3. Include only explorer kinds in the tree (module, type, enum, contract, function).
4. Under each module node, group explorer children into UI folders by kind.
5. When declaringPackage is present and differs from the page package, group under Dependencies → that package id before module nesting.

Legacy artifacts without module parenting may synthesize module edges from modulePath until re-published; emitters should not rely on this path.

Type and cross-package links

• In-package types: navigate via refItemId when set; otherwise select by qualifiedName.
• External types (declaringPackage ≠ current package): link to `/docs/{declaringPackage}@{version}/api/{qualifiedName}` (same version segment as the host page when possible).
• Markdown @ref links packed at publish time must use the same qualified-name rules as the design model.

Implementation anchors

• UI: pckg/src/Server/Components/Docs/ (PackageDocs, ApiDocNavigationBuilder, DocsView)
• API: GET /api/packages/{id}/versions/{ver}/docs/structured
• Pack: .beskid/docs/api.json inside .bpk artifacts