feat(page): add composable page primitives

2026-09-28 23:13:49 +08:00
parent 0ec968c344
commit d23deca0e7
18 changed files with 1979 additions and 0 deletions
@@ -0,0 +1,94 @@
+---
+title: Page composition
+description: Compose headings, page actions, breadcrumbs, and content sections.
+order: 10
+toc:
+  - id: stylesheet
+    title: Stylesheet
+  - id: basic-page
+    title: Basic page
+  - id: page-info
+    title: Page information
+  - id: breadcrumb
+    title: Breadcrumbs
+---
+
+## Stylesheet {#stylesheet}
+
+Add the package source to the application's Tailwind stylesheet:
+
+```css
+@import "@workspace/page/globals.css";
+```
+
+## Basic page {#basic-page}
+
+```tsx
+import {
+  PageBackButton,
+  PageBreadcrumb,
+  PageContainer,
+  PageDescription,
+  PageHeader,
+  PageHeaderExtra,
+  PageHeading,
+  PageHeadingExtra,
+  PageSection,
+  PageSubtitle,
+  PageTitle,
+} from "@workspace/page"
+import { Button } from "@workspace/ui/components/button"
+
+export function ProductsPage() {
+  return (
+    <PageContainer
+      info={{
+        breadcrumb: [
+          { label: "Home", href: "/" },
+          { label: "Catalog", href: "/products" },
+          { label: "Products" },
+        ],
+        description: "Manage products, pricing, and availability.",
+        subtitle: "Catalog",
+        title: "Products",
+      }}
+    >
+      <PageHeader>
+        <PageBreadcrumb />
+        <PageHeading>
+          <PageHeadingExtra align="start">
+            <PageBackButton href="/products">Products</PageBackButton>
+          </PageHeadingExtra>
+          <PageTitle />
+          <PageSubtitle />
+          <PageDescription />
+          <PageHeadingExtra align="end">
+            <Button>New product</Button>
+          </PageHeadingExtra>
+        </PageHeading>
+        <PageHeaderExtra>
+          <ProductStatus />
+        </PageHeaderExtra>
+      </PageHeader>
+
+      <PageSection aria-label="Product list">
+        <ProductsTable />
+      </PageSection>
+    </PageContainer>
+  )
+}
+```
+
+## Page information {#page-info}
+
+`PageContainer.info` accepts `Partial<PageInfo>` and exposes the resolved value through `usePageInfo()`. When a surrounding `PagesManager` supplies `getPageInfo`, the function receives this partial value and may complete it with route or layout metadata. `PageTitle`, `PageSubtitle`, `PageDescription`, and `PageBreadcrumb` use matching information when their own content or items are omitted. Explicit component content takes precedence. A component returns `null` when neither source supplies renderable content, so optional metadata does not leave empty elements in the page.
+
+`PageHeadingExtra` accepts `align="start | end"`. Multiple extras on the same side retain source order, while `PageHeaderExtra` provides an unrestricted region below the heading. Every container retains `className` and its native HTML props.
+
+`PageBackButton` uses browser history when no destination is supplied. Pass `href` for a native link, or `render` for a router-specific Link. Preventing the custom `onClick` event also prevents the default history navigation.
+
+## Breadcrumbs {#breadcrumb}
+
+Pass a root-to-current-page `items` path to `PageBreadcrumb`. The last item is rendered as the current page; items with `href` use native anchors, while `render` accepts a router-specific Link. When the path exceeds `maxItems` (default `4`), middle items move into an accessible overflow menu.
+
+Omit `items` to use the original compositional API with Breadcrumb Item, Link, and Separator components from `@workspace/ui/components/breadcrumb`.