Skip to content

docs(layout): name page:header as the canonical author key on the page-header docs (Phase 1)#5922

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 1 commit into from
Aug 24, 2026
Merged

docs(layout): name page:header as the canonical author key on the page-header docs (Phase 1) #5922

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions content/docs/guide/layout.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -228,6 +228,18 @@ Available values:
The `PageHeader` provides consistent page headers with a title, an optional subtitle,
an icon chip, and an action row.

> **The canonical author key is `page:header`; `page-header` is a legacy alias.** The
> snippets in this section are the `@object-ui/layout` component, which `registerLayout()`
> registers as `page-header` (plus its namespaced form `layout:page-header`) — that node
> still renders, so metadata already written this way is not stranded. The contract knows
> only `page:header`, though: that is the `PageComponentType` value and the
> `ComponentPropsMap` row binding `PageHeaderProps`, and it resolves to a different,
> record-aware renderer in `@object-ui/components`. Props written under the alias have no
> `ComponentPropsMap` row to dispatch, so nothing validates them — a misspelling there is
> neither rejected nor reported. Author metadata pages against `page:header`
> ([Slotted pages](/docs/guide/slotted-pages)); its props are not the ones below — see the
> [PageHeader reference](/docs/layout/page-header).

### Usage

```json
Expand Down
27 changes: 27 additions & 0 deletions content/docs/layout/page-header.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,33 @@ title: "PageHeader"
description: "Page header component with title, subtitle, and actions"
---

> **Canonical author key: `page:header`. This page's key, `page-header`, is a legacy alias
> — and it resolves to a different renderer.**
>
> Measured against the `@objectstack/spec` build this repo installs, `page:header` is the
> only spelling the contract knows: it is the `PageComponentType` value, and it is the
> `ComponentPropsMap` row that binds `PageHeaderProps` — whose own rejection messages name
> the surface `page:header`. Neither `page-header` nor `layout:page-header` appears in
> either place.
>
> The alias is **still accepted** — not retired, and not silently dropped.
> `registerLayout()` registers `page-header` (plus its namespaced form
> `layout:page-header`), so a node written that way renders today: it resolves to the
> `@object-ui/layout` component documented below, which is also what the demo on this page
> renders. What the alias does not carry is a contract. A node's props are validated by
> dispatching its `type` through `ComponentPropsMap`, `page-header` has no row there, and
> `PageComponentSchema.properties` is an open `z.record(z.string(), z.unknown())` bag — so
> a misspelled or retired key written under the alias is neither rejected nor reported.
> Under `page:header` the same key is refused by name.
>
> Author metadata pages against `page:header`. The canonical node is the record-aware
> renderer in `@object-ui/components`; [Slotted pages](/docs/guide/slotted-pages) shows it
> in place. Its props are **not** the props below — `icon`, `action` and `showBack` are this
> component's own, and `icon` is retired on the canonical node (Component Props, below).
> Everything on this page — Props, Styling, Examples, demo — is measured against this
> component, the alias's renderer; converting the page to the canonical node is tracked in
> objectui#3906.

The PageHeader component provides a consistent header for pages with title, subtitle, and action buttons.

## Basic Usage
Expand Down