@gridui/grid 2.3.6 → 3.0.0

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.

package/docs/guides/grid.md

@@ -0,0 +1,126 @@
+# Grid and responsive tracks
+
+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="all"` draws the outer perimeter and 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, without an outer perimeter. 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="all"`, `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, sm?, md?, lg? }`. `sm` starts at
+40rem, `md` at 48rem, 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, sm: 4 }} frame="all">
+        <GridItem span={{ base: 1, sm: 3 }} padding={{ base: 16, sm: 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.
+
+## 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.

package/docs/guides/page-frame.md

@@ -0,0 +1,137 @@
+# 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, sm: 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, sm: 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, sm: 2 }} frame="internal">
+            <GridItem padding={{ base: 16, sm: 24 }}>...</GridItem>
+            <GridItem padding={{ base: 16, sm: 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.

package/docs/guides/split.md

@@ -0,0 +1,49 @@
+# Split and 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. Split resets the structural borders of
+following direct regions before assigning the owned seam. A direct region must
+therefore not rely on its own border for control appearance.
+
+Each structural edge has one owner. The enclosing frame owns the outer perimeter;
+Split owns the boundary between regions; a nested Grid uses `frame="internal"`
+for its own cell seams. A standalone Grid uses `frame="all"`. Do not place a Grid
+with `frame="all"` flush inside another frame or directly on a Split-owned edge.
+Keep a bordered input, button, or standalone table inside a region with spacing;
+its functional border is independent and must not be removed globally.
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `direction` | `row`, `column`, `row-reverse`, `column-reverse`, or responsive values | `row` |
+| `seam` | `line`, `none`, or responsive values | `line` |
+
+Both use `{ base, sm?, md?, lg? }` with 40rem, 48rem, 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", sm: "row" }}
+    seam={{ base: "none", sm: "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.

package/docs/reference/README.md

@@ -0,0 +1,21 @@
+<!-- Generated by pnpm docs:storybook. -->
+# Component reference
+
+- [Container](container.md)
+- [DashboardFrame](dashboard-frame.md)
+- [FrameBoundary](frame-boundary.md)
+- [FrameFooter](frame-footer.md)
+- [FrameHeader](frame-header.md)
+- [FrameRail](frame-rail.md)
+- [FrameRailGroup](frame-rail-group.md)
+- [FrameRegion](frame-region.md)
+- [FrameRegionRow](frame-region-row.md)
+- [FrameSection](frame-section.md)
+- [FrameSections](frame-sections.md)
+- [FrameTexture](frame-texture.md)
+- [Grid](grid.md)
+- [GridItem](grid-item.md)
+- [PageFrame](page-frame.md)
+- [Row](row.md)
+- [Split](split.md)
+- [Stack](stack.md)

package/docs/reference/container.md

@@ -0,0 +1,63 @@
+<!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
+# Container
+
+Constrains and aligns a content region. Use it to keep page content within a consistent width.
+
+Import from ``@gridui/grid`` and load Theme before this family's stylesheet.
+
+```tsx
+import { Container } from "@gridui/grid";
+import "@gridui/theme/styles.css";
+import "@gridui/grid/styles.css";
+```
+
+Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/README.md) for shared behavior and stylesheet dependencies.
+
+The [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/stories/container.stories.tsx) demonstrates required context, state, and related components. Use View code in Storybook to inspect the actual implementation.
+
+## API
+
+The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
+
+### children
+
+``ReactNode`` · Optional
+
+Content rendered inside the component.
+
+### onFocus
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onBlur
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onChange
+
+``(event: ChangeEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onSubmit
+
+``(event: SubmitEvent<HTMLDivElement>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onClick
+
+``(event: MouseEvent<HTMLDivElement, MouseEvent>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### width
+
+``ContainerWidth | undefined`` · Optional
+
+Default: ``"standard"``
+

package/docs/reference/dashboard-frame.md

@@ -0,0 +1,99 @@
+<!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
+# DashboardFrame
+
+Public DashboardFrame component from @gridui/grid. See the package guide for its composition contract.
+
+Import from ``@gridui/grid`` and load Theme before this family's stylesheet.
+
+```tsx
+import { DashboardFrame } from "@gridui/grid";
+import "@gridui/theme/styles.css";
+import "@gridui/grid/styles.css";
+```
+
+Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/README.md) for shared behavior and stylesheet dependencies.
+
+The [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/storybook/scenarios/layout/dashboard-frame.stories.tsx) demonstrates required context, state, and related components. Use View code in Storybook to inspect the actual implementation.
+
+## API
+
+The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
+
+### children
+
+``ReactNode`` · Optional
+
+Content rendered inside the component.
+
+### onFocus
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onBlur
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onChange
+
+``(event: ChangeEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onSubmit
+
+``(event: SubmitEvent<HTMLDivElement>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onClick
+
+``(event: MouseEvent<HTMLDivElement, MouseEvent>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### decoration
+
+``FrameDecorationStyle | undefined`` · Optional
+
+Default: ``"none"``
+
+### startDecoration
+
+``FrameDecorationStyle | undefined`` · Optional
+
+Default: ``decoration``
+
+### endDecoration
+
+``FrameDecorationStyle | undefined`` · Optional
+
+Default: ``decoration``
+
+### startSize
+
+``DashboardFrameSize | undefined`` · Optional
+
+Default: ``"medium"``
+
+### endSize
+
+``DashboardFrameSize | undefined`` · Optional
+
+Default: ``"medium"``
+
+### compactStartSize
+
+``DashboardFrameSize | undefined`` · Optional
+
+Default: ``"small"``
+
+### compactEndSize
+
+``DashboardFrameSize | undefined`` · Optional
+
+Default: ``"small"``
+

package/docs/reference/frame-boundary.md

@@ -0,0 +1,61 @@
+<!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
+# FrameBoundary
+
+Public FrameBoundary component from @gridui/grid. See the package guide for its composition contract.
+
+Import from ``@gridui/grid`` and load Theme before this family's stylesheet.
+
+```tsx
+import { FrameBoundary } from "@gridui/grid";
+import "@gridui/theme/styles.css";
+import "@gridui/grid/styles.css";
+```
+
+Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/grid/README.md) for shared behavior and stylesheet dependencies.
+
+## API
+
+The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
+
+### onFocus
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onBlur
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onChange
+
+``(event: ChangeEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onSubmit
+
+``(event: SubmitEvent<HTMLDivElement>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onClick
+
+``(event: MouseEvent<HTMLDivElement, MouseEvent>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### boundary
+
+``FrameBoundaryStyle | undefined`` · Optional
+
+Default: ``"line"``
+
+### extent
+
+``"content" | "frame" | undefined`` · Optional
+
+Default: ``"content"``
+