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,37 @@
+---
+title: Overview
+description: Build consistent page structure with router-neutral atomic components.
+order: 1
+toc:
+  - id: role
+    title: Package role
+  - id: components
+    title: Components
+  - id: boundaries
+    title: Design boundaries
+---
+
+## Package role {#role}
+
+`@workspace/page` provides structural components for application content pages: headings, descriptions, actions, breadcrumbs, route tabs, and sections. It owns semantics, responsive layout, and visual conventions without creating routes or managing application data.
+
+## Components {#components}
+
+- `PageContainer` is the vertical page container.
+- `PageInfo` and `usePageInfo` share optional page metadata with structural components.
+- `PageHeader` and `PageHeading` organize primary heading content.
+- `PageTitle`, `PageSubtitle`, and `PageDescription` provide semantic heading information.
+- `PageHeadingExtra` places arbitrary content at the start or end of the heading.
+- `PageHeaderExtra` provides an unrestricted region below the heading.
+- `PageBackButton` provides history, native-link, and router-link navigation.
+- `PageBreadcrumb` renders item paths with an overflow menu or reuses the compositional Breadcrumb API from `@workspace/ui`.
+- `PageTabs` manages controlled or uncontrolled values, orientation, and keyboard interaction.
+- `PageTabsList`, `PageTabsTrigger`, and `PageTabsIndicator` compose a four-sided tab list with multiple active styles.
+- `PageTabsExtra` places one or more page actions at the start or end edge of the list.
+- `PageTabsContent` renders the panel matching a Trigger value.
+- `PageSection` marks an independent semantic content region.
+- `PagesManager` and `PageTitlePortal` optionally mount titles into an external layout.
+
+## Design boundaries {#boundaries}
+
+`PageInfo` supplies presentation metadata rather than router state. Explicit component content overrides matching metadata, and missing values render nothing. Page Tabs use Base UI to manage values, panel visibility, keyboard navigation, and indicator positioning without creating application routes. Synchronize `value` and `onValueChange` at the application layer when tabs map to routes. `PagesManager` does not own a page stack; it only provides a title container to its subtree.