feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,45 @@
+---
+title: Application shell
+description: Assemble the shared header, sidebar, breadcrumbs, chat, and notification surfaces.
+order: 11
+toc:
+  - id: render-app-layout
+    title: Render AppLayout
+  - id: layout-inputs
+    title: Layout inputs
+  - id: optional-preset
+    title: Optional preset
+---
+
+## Render AppLayout {#render-app-layout}
+
+`AppLayout` is the integration point for the rest of this tutorial:
+
+```tsx
+import { AppLayout } from "@workspace/blocks/layout"
+
+export function WorkspaceLayout() {
+  return (
+    <AppLayout
+      navigationGroups={navigationGroups}
+      notifications={{
+        queryKey: ["notifications"],
+        queryFn: loadNotifications,
+      }}
+      chatThreads={chatThreads}
+    >
+      <Outlet />
+    </AppLayout>
+  )
+}
+```
+
+## Layout inputs {#layout-inputs}
+
+The shell composes `AppSidebar`, `AppBreadcrumb`, `AppQueryIndicator`, `UserMenu`, a notification sheet, and chat threads. Pass `headerActions` when the product needs additional global controls.
+
+The route content remains the layout's `children`, so the package does not constrain the router used by the application.
+
+## Optional preset {#optional-preset}
+
+`@workspace/blocks/layouts/vega` provides an optional visual shell. It lives on a separate entry point so the standard layout does not include preset-specific code.
@@ -0,0 +1,40 @@
+---
+title: Installation
+description: Add the package, its styles, and the providers required by the tutorial.
+order: 10
+toc:
+  - id: add-the-package
+    title: Add the package
+  - id: import-styles
+    title: Import styles
+  - id: application-providers
+    title: Application providers
+---
+
+## Add the package {#add-the-package}
+
+Add the workspace dependency to the consuming application:
+
+```json
+{
+  "dependencies": {
+    "@workspace/blocks": "workspace:*"
+  }
+}
+```
+
+Blocks use `@workspace/ui`, React Query, and the workspace internationalization runtime. The workspace package manager resolves those dependencies for local applications.
+
+## Import styles {#import-styles}
+
+Import the block stylesheet once from the application entry:
+
+```ts
+import "@workspace/blocks/globals.css"
+```
+
+Keep feature imports on their explicit subpaths. For example, importing `@workspace/blocks/media` does not pull chat into the same module graph.
+
+## Application providers {#application-providers}
+
+The full shell expects React Query and internationalization to be available above it. Add those providers before the route tree, then continue to the application-shell chapter.
@@ -0,0 +1,46 @@
+---
+title: Navigation
+description: Define navigation groups once and connect them to desktop and mobile surfaces.
+order: 12
+toc:
+  - id: define-groups
+    title: Define groups
+  - id: provide-navigation
+    title: Provide navigation
+  - id: route-state
+    title: Route state
+---
+
+## Define groups {#define-groups}
+
+Start with typed `NavigationGroup` values. Items may represent direct routes or nested navigation branches.
+
+```ts
+import type { NavigationGroup } from "@workspace/blocks/navigation"
+
+export const navigationGroups: NavigationGroup[] = [
+  {
+    id: "workspace",
+    label: "Workspace",
+    items: [
+      { id: "dashboard", label: "Dashboard", to: "/dashboard" },
+      { id: "media", label: "Media", to: "/media" },
+    ],
+  },
+]
+```
+
+## Provide navigation {#provide-navigation}
+
+`AppLayout` already mounts the provider and the responsive navigation surfaces. For a custom shell, compose them directly:
+
+```tsx
+<NavigationProvider groups={navigationGroups}>
+  <PrimaryNavigation groups={navigationGroups} />
+  <MobileNavigationSheet groups={navigationGroups} />
+</NavigationProvider>
+```
+
+## Route state {#route-state}
+
+Use `resolveNavigationRouteState` for the standard route model. Applications with custom routing can supply a `GetNavigationRouteState` implementation while keeping the same navigation UI.