@echothink-ui/layout 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @echothink-ui/layout
+
+Layout-template library for EchoThink UI. Build any frontend as **layout
+template + pages of components**, with the _look_ selected by a style preset.
+
+Templates and region parts read **only** the Tier-2 contract tokens (see
+`TOKEN_CONTRACT.md`) plus a small set of layout-owned region/breakpoint tokens.
+Switching the preset restyles every template without touching its markup.
+
+## The three orthogonal axes
+
+`StyleScope` (re-exported here) applies all three to a subtree:
+
+| Axis          | Prop        | Values                                        | Drives                                                    |
+| ------------- | ----------- | --------------------------------------------- | --------------------------------------------------------- |
+| **preset**    | `preset`    | `ethStylePresets` (e.g. `carbon`, `glass`, …) | colors, surfaces, borders, radius, shadows, glass effects |
+| **density**   | `density`   | `compact` \| `standard` \| `comfortable`      | the `--eth-space-*` spacing scale                         |
+| **typeScale** | `typeScale` | `compact` \| `standard` \| `large`            | the `--eth-text-scale` typography multiplier              |
+
+```tsx
+import { StyleScope, AppShell, PageHeader } from "@echothink-ui/layout";
+import "@echothink-ui/layout/styles.css";
+
+<StyleScope preset="glass" density="comfortable" typeScale="large">
+  <AppShell topbar={<TopBar />} nav={<Nav />} footer={<Footer />}>
+    <PageHeader title="Overview" description="…" />
+    {/* pages of components */}
+  </AppShell>
+</StyleScope>;
+```
+
+## Templates
+
+| Component          | Slots / props                                              | Use                                                      |
+| ------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
+| `AppShell`         | `topbar`, `nav`, `aside`, `footer`, `children`, `navWidth` | default product frame; nav collapses under `--eth-bp-lg` |
+| `DashboardLayout`  | `children`, `minColumn`                                    | responsive auto-fit grid of regions                      |
+| `ListDetailLayout` | `list`, `detail`, `listWidth`, `detailEmpty`               | master-detail; stacks under `--eth-bp-md`                |
+| `SplitPaneLayout`  | `primary`, `secondary`, `ratio`, `orientation`             | editors, tools                                           |
+| `SettingsLayout`   | `nav`, `children`, `navWidth`                              | two-pane settings                                        |
+| `CenteredLayout`   | `children`, `maxWidth`                                     | auth / empty / error                                     |
+| `CanvasLayout`     | `stage`, `panels`, `toolbar`                               | full-bleed canvas + floating panels                      |
+
+## Region parts
+
+`PageHeader` (`title`, `description`, `actions`, `breadcrumbs`), `Toolbar`
+(`start`, `end`, `children`), `Breadcrumbs` (`items: {label, href?}[]`).
+
+## Breakpoint contract
+
+`--eth-bp-sm` 36rem · `--eth-bp-md` 48rem · `--eth-bp-lg` 64rem · `--eth-bp-xl`
+80rem. Exposed to JS as `ethBreakpoints` (CSS media queries can't read custom
+properties, so the literal `rem` values are mirrored in the stylesheet).
+
+## Region tokens
+
+Layout owns these chrome tokens; they default to contract tokens so a preset
+still drives them, but they can be themed independently:
+`--eth-region-topbar-bg`, `--eth-region-topbar-color`,
+`--eth-region-sidebar-bg`, `--eth-region-canvas-bg`.
+
+## Preview utilities
+
+`StylePresetPicker`, `StylePresetLayout`, `ComponentPreviewLayout` are
+docs/preview helpers. `StylePresetLayout` and `ComponentPreviewLayout` accept
+`density` and `typeScale` and forward them to `StyleScope`.
+
+## Page Template Preview
+
+Run the layout preview from the pnpm workspace root
+`/Users/wangqihang/wkspace/echothink-UI/echothink-UI-components`, which includes
+`../echothink-UI-layout`:
+
+```bash
+pnpm --filter @echothink-ui/layout dev:preview
+```
+
+Or run it from anywhere with:
+
+```bash
+pnpm --dir /Users/wangqihang/wkspace/echothink-UI/echothink-UI-components --filter @echothink-ui/layout dev:preview
+```
+
+Then open the printed local URL, for example `http://127.0.0.1:5174/`.
+The preview reads `pageTemplateCatalog` and lets you browse every registered
+template. You can link directly to one template with a hash, for example:
+
+```text
+http://127.0.0.1:5174/#glass-flowchart
+```
+
+Current generated preview screenshots live in `snapshots/`.