@gridui/grid 2.3.5 → 3.0.0

package/docs/README.md

@@ -1,402 +1,23 @@
-# Grid contract
+# Grid guides
 
-See the [shared UI index](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/README.md) for
-cross-package ownership, style organization, and verification.
+[Public API reference](reference/README.md) lists the signatures of every exported component.
 
 ## Grid foundation
 
-Theme's `src/tokens.css`, loaded through `@gridui/theme/styles.css`, owns spacing, content widths, and semantic
-colors. Spacing values are `0 / 4 / 8 / 16 / 24 / 32 / 48 / 64`, expressed in rem
-except zero. The page gutter is 16 at the base breakpoint and 24 from 40rem.
-Sites may override tokens at their root; components do not add external margins.
-
-`@gridui/grid` exports grid primitives and page frame components;
-its `styles.css` is a separate explicit export. Follow the shared
-[stylesheet integration order](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/integration.md). Geometry
-uses owned component CSS alongside generated utility classes. Class composition
-uses clsx and tailwind-merge;
-container width and grid framing use typed CVA variants.
-
-- `Container` defines `full-start`, `content-start`, `content-end`, and
-  `full-end` lines. Direct children align to content by default; a direct child
-  with `data-width="full"` spans the whole container. Its `width` selects
-  `narrow` (48rem), `standard` (72rem), or `wide` (90rem).
-- `Grid` owns columns and gap. Supported column counts are 1, 2, 3, 4, 6, and
-  12. A nonempty track array combines `"1fr"` and `"auto"` tracks, for example
-  `["1fr", "1fr", "1fr", "1fr", "auto"]` for four equal fields and an
-  automatic-width action. Counts and track arrays support the same responsive
-  breakpoints. The default is one column with gap 16. `frame="cells"` creates shared
-  cell boundaries, sets gap to zero, and disallows a gap prop. Its direct
-  children must be `GridItem` components. `frame="internal"` also disallows
-  a gap prop but draws internal seams with a 1px gap and the grid's border-color
-  background. Its `GridItem` children have an opaque `--gridui-background` surface;
-  consumer background styles can override it. It does not clip content or
-  interaction outlines and needs no selectors that assume item order or spans.
-  Hovered items paint above ordinary neighbors. Items with visible focus on
-  themselves or a descendant paint above hovered items; retained pointer focus
-  alone does not raise an item. This priority uses the existing local content
-  and interaction layers, independently of selection state. Frame surfaces
-  containing an active internal grid paint above frame boundaries. Keep rows filled, using
-  spans where appropriate: unoccupied cells expose the grid's border-color
-  background. Menus continue to use portals for viewport positioning.
-  Optional `fillLastRow` expands the final item in each incomplete row, including
-  a row preceding a full-width item. It plans spans for every breakpoint from
-  rendered direct `GridItem` children, excluding null children. It requires
-  direct items with valid spans; wrappers whose rendered spans are unknown are
-  rejected. No browser measurement or business item-count calculation is needed.
-  Explicit item style overrides still take precedence.
-- `Grid columns="auto"` selects adaptive, unframed tracks. Required `minItemWidth`
-  accepts a positive number in pixels or a CSS length such as `"14rem"`, including
-  responsive values. The template uses `auto-fit` and caps its minimum at 100%
-  of the available space, so a narrow container never needs a wider track.
-  Gap retains its usual responsive behavior. Fixed/adaptive planning modes cannot
-  be mixed at breakpoints; change the adaptive minimum width instead.
-  Adaptive columns do not support `frame="cells"`, `frame="internal"`, or
-  `fillLastRow`: their track count is resolved by CSS, without measuring in JS.
-- `Grid asChild` merges its geometry, classes, styles, native props, handlers,
-  and refs onto one prop-forwarding child through Radix Slot. Use native `ul` or
-  `ol` roots with `GridItem asChild` and `li` children to retain list semantics.
-  Place host-specific attributes and refs on the child. Child styles take
-  precedence; child handlers run before Grid handlers. This does not introduce
-  cancellation or routing behavior. `asChild` cannot be combined with
-  `fillLastRow`, whose span planner requires direct React GridItem children.
-  Unsupported combinations fail at the type boundary and throw for JS callers.
-- `GridItem asChild` applies its geometry, native props, and merged refs to its
-  single child through Radix Slot. This supports interactive cells such as
-  SortableItem without adding a DOM layer. Keep GridItem as the direct React
-  child when using `fillLastRow`; the child must forward props and refs to its
-  root element. Grid does not own or import the child's interaction behavior.
-- `GridItem` owns its column span and internal padding. Span defaults to 1,
-  padding to 0. `span="full"` spans the explicitly defined columns. Numeric
-  spans must not exceed the parent column count at any breakpoint, or CSS
-  Grid will create implicit columns.
-- `Stack` owns vertical gap (default 16), without adding external margins
-  or changing the margins of children. Consumers own text resets.
-
-Responsive props accept a scalar or `{ base, md?, lg? }`. `md` starts at
-40rem and `lg` at 64rem. Missing values inherit from the preceding breakpoint.
-Import the shared `Space`, `Responsive<T>`, `resolveResponsive`, `spaceValue`,
-and `spacingVariables` from `@gridui/style-utils/responsive`. Grid exports its
-geometry types (`Columns`, `GridColumns`, `GridTrack`, and `Span`) and components.
-Columns, spans, gap, and padding are resolved through CSS, with no viewport
-JavaScript. Grid and GridItem render divs by default; use their `asChild` prop
-when retaining a semantic host. Other primitives follow their documented native
-hosts. Components forward native props, styles, and refs.
-
-```tsx
-<Container>
-    <div data-width="full" className="site-rule" />
-    <Grid columns={{ base: 1, md: 4 }} frame="cells">
-        <GridItem span={{ base: 1, md: 3 }} padding={{ base: 16, md: 24 }}>
-            <Stack gap={16}>...</Stack>
-        </GridItem>
-        <GridItem padding={16}>...</GridItem>
-    </Grid>
-</Container>
-```
-
-
-### Adaptive native lists
-
-```tsx
-<Grid asChild columns="auto" minItemWidth="14rem" gap={16}>
-    <ul aria-label="Resources" className="m-0 list-none p-0">
-        {resources.map((resource) => (
-            <GridItem key={resource.href} asChild padding={16}>
-                <li><a href={resource.href}>{resource.label}</a></li>
-            </GridItem>
-        ))}
-    </ul>
-</Grid>
-```
-
-The server output already contains the native list and CSS track plan. No
-hydration or viewport measurement is needed. `auto-fit` collapses unused tracks;
-this is distinct from filling the last row of a fixed-column plan. Adaptive
-items normally use the default span of one. Explicit numeric spans must fit the
-number of tracks available in their container or CSS can create implicit tracks.
-The application owns list markers/margins, labels, links, and data.
+Read [Grid and responsive tracks](guides/grid.md).
 
 ## Linear regions
 
-Import `Split`, `SplitProps`, and `SplitDirection` from `@gridui/grid`.
-Split renders one div and lays out its direct children as a single flex sequence.
-It does not wrap the sequence or add wrappers around individual children.
-Use direct child region elements such as `section`, `nav`, or `div`; place
-buttons, inputs, tables, and other components with functional borders inside
-those regions. Split owns region edge styles and must not be applied directly
-to those components' bordered roots.
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `direction` | `row`, `column`, `row-reverse`, `column-reverse`, or responsive values | `row` |
-| `seam` | `line`, `none`, or responsive values | `line` |
-
-Both use `{ base, md?, lg? }` with 40rem and 64rem breakpoints and preceding-value
-fallback. A line is one logical edge between visible sibling regions, without
-an outer frame. Reversed directions move the seam to the corresponding edge;
-they change visual order, not DOM, reading, or keyboard order. Regions with the
-native `hidden` attribute do not contribute seams. CSS-only responsive hiding
-is not detectable by sibling selectors: when only one region remains visible,
-set the owning Split to `seam={{ base: "none", lg: "line" }}` (using the same
-breakpoint as visibility). Keep the DOM order meaningful.
-
-```tsx
-import { Split } from "@gridui/grid";
-
-<Split
-    direction={{ base: "column", md: "row" }}
-    seam={{ base: "none", md: "line" }}
->
-    <section aria-label="Overview">...</section>
-    <section aria-label="Details">...</section>
-</Split>
-```
-
-Children control their content size and flex sizing; Split does not assign equal
-widths. Use Grid/GridItem for two-dimensional tracks or wrapping rows. A parent
-frame supplies outer edges. Layout compositions choose these primitives instead
-of drawing duplicate seams.
+Read [Split and linear regions](guides/split.md).
 
 ## Page frames
 
-Named areas such as `filters`, `results`, or `methodology` belong in site CSS,
-where their responsive order can be defined. The shared package owns geometry
-and never imports or names business regions. The page shell is shared rather
-than implemented in website CSS:
-
-- `PageFrame` takes optional `header` and `footer` slots, a content width, and any number
-  of sections as children. It renders one main landmark and a flexible framed
-  filler inside main before the footer. Main fills the remaining page height.
-  Short pages fill at least 100svh without stretching
-  content sections. On longer pages the filler shrinks to zero.
-- `FrameHeader` and `FrameFooter` render native landmarks with a full-width
-  boundary and an aligned inner region. Their padding defaults to 16 at base
-  and 24 at md/lg; `padding` accepts the same responsive values as GridItem.
-  Chrome children wrap instead of overflowing narrow screens. `FrameHeader`
-  defaults to `justify="between"`; use `justify="start"` for an adjacent brand
-  and navigation row. `FrameFooter` defaults to `contentLayout="flex"`; use
-  `contentLayout="block"` when its children own their internal layout.
-  Its `signatureAppearance="cropped"` selects the cropped signature treatment
-  through a public prop; the default is `standard`.
-- `FrameSection` renders a semantic section, full-width leading boundary, and
-  aligned vertical edges. Compose it with `Grid frame="internal"` so the
-  section owns the outer borders and the grid owns internal seams.
-  `paddingInline` and `paddingBlock` accept responsive spacing tokens and default
-  to zero. They pad the inner content surface without moving its leading boundary
-  or inline edges. Use these props instead of targeting private frame elements.
-- `FrameSections` groups sections from a dynamic React view and forwards native
-  div props. It inherits page tracks without adding a landmark. The shared
-  stylesheet supports React section groups. Framework host elements require an
-  application-owned adapter; see the [Astro migration example](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/framework-adapters.md).
-
-Keep inline-size containment, including `container-type: inline-size`, off roots
-that propagate the frame's column subgrid. Applying it to `FrameSections` or a
-`FrameSection` breaks inherited track sizing. Put query containers on
-application-owned content wrappers inside the section instead; tune Grid tracks
-with the public responsive props. See
-[narrative pages and artwork](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/narrative-pages.md#keep-query-containers-inside-the-frame)
-for a complete composition and the corresponding browser fixture.
-
-`FrameRail` supplies the narrow surface and forwards native div props, including
-accessible labels or `aria-hidden` for decorative content. Its default
-`placement="start"` keeps content at the top. Callers own text direction and
-control layout; the shared rail does not force vertical text.
-`placement="sticky-bottom"` places content at the natural bottom and uses CSS
-sticky with a viewport-bottom inset and safe-area allowance. The control stays
-inside its group's bounds. The rail does not clip focus outlines or create a
-scroll container.
-
-`FrameRailGroup` scopes a rail to consecutive children. Multiple sibling groups
-describe disjoint ranges without adding landmarks, querying positions, or
-measuring heights. Each group defines gutter, rail, and content columns once.
-The rail track is a normal-flow grid item beside the content column, spanning
-the group's body row. The body uses column subgrid so sections inherit the same
-tracks, including full-width boundaries that cross the rail and both gutters.
-Boundary layers paint above the rail surface; controls retain native focus.
-
-`PageFrame` accepts the same `rail` and `railWidth` props. Its default
-`railScope="page"` covers header through footer. `railScope="main"` covers main's
-content and filler, excluding header and footer. Page rows allocate natural
-header/footer heights and remaining space to main. Main separates natural-height
-sections from a flexible filler, which collapses to zero on long pages.
-No viewport/chrome measurements are needed. A main without a rail does not add a
-second rail group. Choose a page or main rail, or local section groups; do not
-nest rail-bearing groups. Group width comes from the surrounding frame, falling
-back to the standard content width.
-
-`railWidth` accepts responsive spacing tokens and defaults to `{ base: 0, md: 32 }`.
-Zero hides the rail, including its contents, and reserves no space. Missing
-breakpoints inherit. The rail column sits inside the existing content boundary,
-reducing content width while retaining outer gutters, right alignment, full-width
-bands, and exterior marks. Column subgrid is part of the modern CSS baseline for
-the frame. No hydration or measurement is required. FrameRail owns surface and
-placement; the group owns width and range.
-`--gridui-page-gutter-start` optionally overrides only the start gutter; the end
-gutter continues to use `--gridui-page-gutter`. Sites can make small-screen rails
-flush with the viewport without changing header/footer gutters.
-
-```tsx
-<PageFrame header={header} footer={footer}>
-    <FrameRailGroup
-        rail={<FrameRail><span className="site-vertical-label">Research</span></FrameRail>}
-        railWidth={{ base: 0, md: 24, lg: 32 }}
-    >
-        <FrameSection>Overview</FrameSection>
-        <FrameSection>Resources</FrameSection>
-    </FrameRailGroup>
-    <FrameSection>Outside the rail range</FrameSection>
-</PageFrame>
-```
-
-`FrameBoundary` is a public primitive from `@gridui/grid`. It accepts `boundary`
-(default `line`), native div props and a ref; it has no children. Its CVA variants
-own only appearance and normal-flow height. Parent layouts choose its width and
-Grid span. It is inert, hidden from assistive technology and pointer-transparent.
-Landing sections and Sidebar regions use this same renderer; no package-private
-imports or duplicate line implementations are needed.
-
-Standalone and nested boundaries use the current palette's border color.
-Only a section or footer's direct leading boundary applies the adjacent-region
-seam color. This keeps section transitions from recoloring internal dividers.
-
-Each section and footer own their leading boundary through FrameBoundary. A line
-uses one top rule; a band adds its tint and bottom rule in normal flow. A stripe
-uses the same band height and rules with a repeating brand-colored diagonal pattern.
-Space reserves `--gridui-boundary-space-size` (2.5rem) without a rule or fill; none
-renders no boundary and reserves no space. These choices do not change content
-padding or inline edges. Stripe and space default to no decoration. The header
-has no trailing rule. The filler paints a top rule only when it has visible
-height, so a collapsed filler contributes no extra seam. No negative margin,
-rail-bottom correction, or last-section selector is needed. Vertical edges stay
-with each content surface. Websites own copy, semantic heading levels, and
-responsive column/span choices. The frame owns alignment, chrome padding,
-boundaries, and footer placement.
-
-`src/shared/page.css` owns page rows, subgrid propagation, and remaining height.
-`src/shared/rail.css` owns rail tracks, surfaces, and sticky placement. Boundary,
-decoration, and texture keep their own styles. The public stylesheet imports
-these owners; sites do not depend on private paths.
-
-```tsx
-<PageFrame
-    header={<FrameHeader>Site name</FrameHeader>}
-    footer={<FrameFooter>Source notes</FrameFooter>}
->
-    <FrameSection aria-label="Overview">
-        <Grid columns={{ base: 1, md: 2 }} frame="internal">
-            <GridItem padding={{ base: 16, md: 24 }}>...</GridItem>
-            <GridItem padding={{ base: 16, md: 24 }}>...</GridItem>
-        </Grid>
-    </FrameSection>
-</PageFrame>
-```
-
-SSR tests cover breakpoint inheritance, prop forwarding, framed gaps, and
-class overrides. Browser checks must confirm actual alignment and reflow;
-serialized styles alone do not prove the grid works.
-
-## Segmented filter bars
-
-Keep framed filter cells stretched to the same row height so seams remain
-continuous. Bottom-align their contents with `flex flex-col justify-end` on
-`GridItem`; do not bottom-align the grid items themselves. Fields keep their
-full available width. This aligns controls and action rows when labels wrap.
-Use equal fractional tracks for fields and an automatic track for actions,
-stacking or spanning the action cell at smaller breakpoints.
-
-Within a table cell, pair primary content and a trailing action with a full-width
-flex row, centered cross-axis alignment, `justify-between`, and a spacing-token
-gap. Keep icon actions non-shrinking and retain the cell's existing padding.
+Read [Page frames](guides/page-frame.md).
 
 ## Dashboard frames
 
-`DashboardFrame` is a full-height, full-width page host with inline gutters and
-structural edges. Unlike `PageFrame`, it renders no `main`; the composed workspace
-owns that landmark. Give its parent a definite height. Four independent CVA
-variants configure its logical start and end gutters:
-
-| Prop | Applies to | Default |
-| --- | --- | --- |
-| `startSize` | Start gutter from 40rem | `medium` |
-| `endSize` | End gutter from 40rem | `medium` |
-| `compactStartSize` | Start gutter below 40rem | `small` |
-| `compactEndSize` | End gutter below 40rem | `small` |
-
-Every option accepts `none`, `small`, `medium`, or `large`. `none` is exactly 0px;
-the other options use spacing tokens 8, 16, and 24. Start/end mean left/right in LTR and right/left in RTL. Configure both
-wide-screen options for symmetric gutters; compact defaults remain independent.
-The breakpoint is viewport-based, like the other Grid frame styles. Nonzero size
-options retain at least the theme hover/focus outline extent, even when spacing
-tokens are reduced. `none` bypasses that minimum and disables ornaments on that
-edge; the structural border remains. `DashboardFrameSize` exports the common size
-type.
+Read [Dashboard frames](guides/dashboard-frame.md).
 
-### Composed frame regions
-
-`FrameRegion` declares which physical frame edge a composition touches through
-`edge="left" | "right" | "both" | "none"` (default `none`). It does not change
-its host's layout. Use `asChild` to retain a semantic element. Grid resolves the
-adjacent gutter and structural-border distances; consumers do not calculate
-negative offsets or read frame capacity variables. Nested regions start with no
-outer-frame capacity unless a new `DashboardFrame` establishes it.
-
-`FrameRegionRow` is a grid canvas within that region. It extends through the
-selected outer gutter and owns these public grid lines:
-
-| Lines | Purpose |
-| --- | --- |
-| `frame-left / frame-right` (or `1 / -1`) | Entire canvas, including the gutter |
-| `surface-left / surface-right` | Original composition surface |
-| `content-left / content-right` | Default child content column |
-| `accessory-left / surface-right` | Intrinsic column at the physical right edge |
-
-`contentInset` accepts a CSS length or pixel number (default 0). It reserves a
-right content inset before the accessory column and any left inset that the
-outer gutter cannot supply. An accessory such as a scrollbar sizes its column
-intrinsically. Row text keeps its inherited direction; physical line names and
-accessory placement stay stable in RTL. Rows support `asChild`, including a
-scroll-area root, and nested CSS subgrids can reuse these lines.
-
-`FrameBoundary extent="frame"` spans the full row. Its default `"content"`
-uses the content column. These are normal-flow grid spans, not translated
-pseudo-elements. Sidebar composes these primitives for fixed and scrolling
-boundaries and uses an unframed region for its Drawer and main content.
-
-`Split order="physical"` keeps row/row-reverse ordering and seams at the same
-physical edges in RTL; its default `"logical"` follows writing direction.
-Column ordering is unaffected. Sidebar uses physical ordering because its
-`side="left" | "right"` API describes physical positions.
-
-`decoration` accepts `none` (default), `nodes`, `marks`, `corners`, or `ticks`
-and supplies the default for both edges. `startDecoration` and `endDecoration`
-accept the same styles and override only their logical edge; an explicit `none`
-hides that edge's ornament without changing its gutter width or structural border.
-Omitted overrides inherit `decoration`. Start/end follow the same LTR/RTL mapping
-as the size options. Both sides still hide their ornaments below 40rem.
-Dashboard and Landing frames use the same package-local single-edge decoration
-renderer and styles. Each ornament paints only its own edge; zero-width gutters
-produce a zero-width ornament. Dashboard constrains their outsets to its gutter width and viewport
-height, including small, asymmetric gutters; it hides ornaments below 40rem while preserving
-outline clearance. Decorations are inert and never intercept pointer events.
-
-It owns no navigation, collapse state, scroll region, or application header.
-
-```tsx
-<DashboardFrame
-    startSize="large"
-    endSize="small"
-    compactStartSize="small"
-    compactEndSize="medium"
-    decoration="ticks"
-    endDecoration="corners"
->
-    <SidebarLayout>
-        <Sidebar>{navigation}</Sidebar>
-        <SidebarMain>{content}</SidebarMain>
-    </SidebarLayout>
-</DashboardFrame>
-```
+## Segmented filter bars
 
-Import `DashboardFrame` from `@gridui/grid`; Sidebar components belong to
-`@gridui/sidebar`. Sidebar and main scroll independently inside the fixed frame.
+Read [segmented filter bars](guides/grid.md#segmented-filter-bars).

package/docs/catalog.json

@@ -1,13 +1,36 @@
 {
   "schemaVersion": 1,
   "name": "@gridui/grid",
-  "version": "2.3.5",
+  "version": "3.0.0",
   "category": "layout",
   "description": "GridUI React grid",
   "usage": "`@gridui/grid` owns Container, Grid, GridItem, Split, Stack, Row, PageFrame, FrameSections, FrameSection, frame chrome, rails, textures, FrameRegion/FrameRegionRow for composed edge geometry, and the public FrameBoundary primitive for structural boundaries. It does not know website routes or domain state. Load its explicit `styles.css` export after Theme and before styles of composed families. Theme supplies token values; `@gridui/style-utils/responsive` supplies the React-free spacing and breakpoint-value calculations.",
   "documentation": [
     "README.md",
-    "docs/README.md"
+    "docs/README.md",
+    "docs/guides/dashboard-frame.md",
+    "docs/guides/grid.md",
+    "docs/guides/page-frame.md",
+    "docs/guides/split.md",
+    "docs/reference/README.md",
+    "docs/reference/container.md",
+    "docs/reference/dashboard-frame.md",
+    "docs/reference/frame-boundary.md",
+    "docs/reference/frame-footer.md",
+    "docs/reference/frame-header.md",
+    "docs/reference/frame-rail-group.md",
+    "docs/reference/frame-rail.md",
+    "docs/reference/frame-region-row.md",
+    "docs/reference/frame-region.md",
+    "docs/reference/frame-section.md",
+    "docs/reference/frame-sections.md",
+    "docs/reference/frame-texture.md",
+    "docs/reference/grid-item.md",
+    "docs/reference/grid.md",
+    "docs/reference/page-frame.md",
+    "docs/reference/row.md",
+    "docs/reference/split.md",
+    "docs/reference/stack.md"
   ],
   "exports": [
     {
@@ -246,9 +269,21 @@
     "@gridui/grid/styles.css"
   ],
   "examples": [
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/adaptive-lists.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/boundaries-textures.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/flow-layouts.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/framed-cells.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/linear-regions.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/page-frames.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/rails.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/responsive-grids.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/container.stories.tsx",
     "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/frame-section.stories.tsx",
     "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/grid.stories.tsx",
     "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/page-frame.stories.tsx",
-    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/primitives.stories.tsx"
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/primitives.stories.tsx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/row.stories.tsx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/split.stories.tsx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/stack.stories.tsx"
   ]
 }

package/docs/guides/dashboard-frame.md

@@ -0,0 +1,91 @@
+# Dashboard frames
+
+`DashboardFrame` is a full-height, full-width page host with inline gutters and
+structural edges. Unlike `PageFrame`, it renders no `main`; the composed workspace
+owns that landmark. Give its parent a definite height. Four independent CVA
+variants configure its logical start and end gutters:
+
+| Prop | Applies to | Default |
+| --- | --- | --- |
+| `startSize` | Start gutter from 40rem | `medium` |
+| `endSize` | End gutter from 40rem | `medium` |
+| `compactStartSize` | Start gutter below 40rem | `small` |
+| `compactEndSize` | End gutter below 40rem | `small` |
+
+Every option accepts `none`, `small`, `medium`, or `large`. `none` is exactly 0px;
+the other options use spacing tokens 8, 16, and 24. Start/end mean left/right in LTR and right/left in RTL. Configure both
+wide-screen options for symmetric gutters; compact defaults remain independent.
+The breakpoint is viewport-based, like the other Grid frame styles. Nonzero size
+options retain at least the theme hover/focus outline extent, even when spacing
+tokens are reduced. `none` bypasses that minimum and disables ornaments on that
+edge; the structural border remains. `DashboardFrameSize` exports the common size
+type.
+
+## Composed frame regions
+
+`FrameRegion` declares which physical frame edge a composition touches through
+`edge="left" | "right" | "both" | "none"` (default `none`). It does not change
+its host's layout. Use `asChild` to retain a semantic element. Grid resolves the
+adjacent gutter and structural-border distances; consumers do not calculate
+negative offsets or read frame capacity variables. Nested regions start with no
+outer-frame capacity unless a new `DashboardFrame` establishes it.
+
+`FrameRegionRow` is a grid canvas within that region. It extends through the
+selected outer gutter and owns these public grid lines:
+
+| Lines | Purpose |
+| --- | --- |
+| `frame-left / frame-right` (or `1 / -1`) | Entire canvas, including the gutter |
+| `surface-left / surface-right` | Original composition surface |
+| `content-left / content-right` | Default child content column |
+| `accessory-left / surface-right` | Intrinsic column at the physical right edge |
+
+`contentInset` accepts a CSS length or pixel number (default 0). It reserves a
+right content inset before the accessory column and any left inset that the
+outer gutter cannot supply. An accessory such as a scrollbar sizes its column
+intrinsically. Row text keeps its inherited direction; physical line names and
+accessory placement stay stable in RTL. Rows support `asChild`, including a
+scroll-area root, and nested CSS subgrids can reuse these lines.
+
+`FrameBoundary extent="frame"` spans the full row. Its default `"content"`
+uses the content column. These are normal-flow grid spans, not translated
+pseudo-elements. Sidebar composes these primitives for fixed and scrolling
+boundaries and uses an unframed region for its Drawer and main content.
+
+`Split order="physical"` keeps row/row-reverse ordering and seams at the same
+physical edges in RTL; its default `"logical"` follows writing direction.
+Column ordering is unaffected. Sidebar uses physical ordering because its
+`side="left" | "right"` API describes physical positions.
+
+`decoration` accepts `none` (default), `nodes`, `marks`, `corners`, or `ticks`
+and supplies the default for both edges. `startDecoration` and `endDecoration`
+accept the same styles and override only their logical edge; an explicit `none`
+hides that edge's ornament without changing its gutter width or structural border.
+Omitted overrides inherit `decoration`. Start/end follow the same LTR/RTL mapping
+as the size options. Both sides still hide their ornaments below 40rem.
+Dashboard and Landing frames use the same package-local single-edge decoration
+renderer and styles. Each ornament paints only its own edge; zero-width gutters
+produce a zero-width ornament. Dashboard constrains their outsets to its gutter width and viewport
+height, including small, asymmetric gutters; it hides ornaments below 40rem while preserving
+outline clearance. Decorations are inert and never intercept pointer events.
+
+It owns no navigation, collapse state, scroll region, or application header.
+
+```tsx
+<DashboardFrame
+    startSize="large"
+    endSize="small"
+    compactStartSize="small"
+    compactEndSize="medium"
+    decoration="ticks"
+    endDecoration="corners"
+>
+    <SidebarLayout>
+        <Sidebar>{navigation}</Sidebar>
+        <SidebarMain>{content}</SidebarMain>
+    </SidebarLayout>
+</DashboardFrame>
+```
+
+Import `DashboardFrame` from `@gridui/grid`; Sidebar components belong to
+`@gridui/sidebar`. Sidebar and main scroll independently inside the fixed frame.