@gridui/grid 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# Grid foundation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See the usage handbook and
+pages and grids guide for practical usage.
+
+`@gridui/grid` owns Container, Grid, GridItem, Stack, Row, responsive
+spacing, PageFrame, FrameSections, FrameSection, frame chrome, rails, textures,
+and structural boundaries. It does not know website routes or domain state.
+Load its explicit `styles.css` export after theme styles and before Layout.
+
+FrameSection and FrameFooter accept `tone="neutral" | "brand" | "warning" | "danger"`.
+Non-neutral tones scope background, foreground, muted text, borders, controls,
+and focus colors to that region. Theme owns the paired light/dark tokens;
+Grid owns their inherited application. Nested non-neutral tones establish their own palette; neutral inherits its surroundings.
+
+FrameSection owns its leading separator and inline frame edges. Use
+`boundary="none"` and `edges="none"` when an enclosing region owns them.
+Both FrameSection and FrameFooter accept these leading boundary styles:
+
+| `boundary` | Appearance |
+| --- | --- |
+| `line` (default) | One thin rule |
+| `band` | Theme-tinted 12px band with top and bottom rules |
+| `stripe` | The same band geometry with continuous 135-degree brand-colored stripes |
+| `space` | Transparent 40px spacing with no rules or fill |
+| `none` | No boundary element or extra spacing |
+
+`--gridui-band-size` owns band and stripe height; `--gridui-boundary-space-size`
+owns whitespace height. Stripe and space default to no edge decoration.
+Band still defaults to nodes. Set `decoration` explicitly to choose an edge treatment.
+
+```tsx
+<FrameSection boundary="stripe">Next chapter</FrameSection>
+<FrameSection boundary="space">Related reading</FrameSection>
+```
+
+At a section seam, a non-neutral tone takes precedence over neutral; between
+two non-neutral tones, the lower section supplies the color. The lower section
+still draws the only separator. This works across Astro islands and section
+groups without changing either region's content palette. The page filler uses
+the final section's tone for its leading line.
+Grid `frame="cells"` owns outer and cell edges; `frame="internal"` owns seams
+inside an existing frame. Use `fillLastRow` with direct GridItem children to
+fill incomplete rows at every breakpoint. Explicit gaps are disallowed in
+framed grids. Hover/focus outlines paint above neighboring seams and page lines.
+Table cell lines remain Data-owned and control borders remain Controls-owned.
+
+See the [Grid contract](docs/README.md#grid-foundation) for geometry and API.
+
+## Source organization
+
+The package root `src/index.ts` declares the public API, and `src/styles.css`
+imports component styles. Neither entry point contains component implementation.
+
+- `primitives/` groups Container, Grid/GridItem with track planning, Stack, and
+  Row with their own styles. Shared `responsive.ts` and `types.ts` remain at the
+  primitive level. `geometry.css` owns the shared Container/frame-rail tracks.
+- `frame/` groups page hosts, chrome, rails, boundaries, decorations, and
+  textures with their CSS and variants. `section.tsx` composes those groups.
+  Only shared content styles and tone variants remain in `frame/style.ts`;
+  `tone.css` owns inherited region colors. Primitives never import Frame.
+
+Browser boundary checks live in `test/browser/frame-boundaries.tsx`. The shared
+Layout browser fixture calls them through the explicit test-only
+`@gridui/grid/testing/frame-boundaries` export; production consumers
+use the component and stylesheet exports.
+
+Unit tests mirror these owners under `test/unit/primitives/` and
+`test/unit/frame/`. Tests can combine public primitives to protect their
+collaboration. Keep ordinary presentation in the owner's CVA `style.ts`. Retain
+track resolution, seams, and decorative geometry in colocated CSS imported by
+the root stylesheet. See the shared
+style organization contract.
+Consumers use the package root and explicit stylesheet export; internal file
+paths are private, and moved implementations have no forwarding aliases.

package/dist/frame/boundary/boundary.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Boundary
+ * @description Boundary
+ */
+import type { FC } from "react";
+export type FrameBoundaryStyle = "none" | "line" | "band" | "stripe" | "space";
+export type FrameBoundaryProps = {
+    readonly boundary: FrameBoundaryStyle;
+};
+export declare const FrameBoundary: FC<FrameBoundaryProps>;

package/dist/frame/chrome/chrome.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Chrome
+ * @description Chrome
+ */
+import type { Responsive, Space } from "../../primitives/responsive";
+import type { FrameBoundaryStyle } from "../boundary/boundary";
+import type { FrameDecorationStyle } from "../decoration/decoration";
+import type { FrameTone } from "../style";
+import type { ComponentPropsWithRef, FC, ReactNode } from "react";
+export type ChromeProps = {
+    readonly padding?: Responsive<Space>;
+};
+export type FrameHeaderProps = ComponentPropsWithRef<"header"> & ChromeProps & {
+    readonly wrap?: boolean;
+    readonly gap?: Space;
+};
+export declare const FrameHeader: FC<FrameHeaderProps>;
+export type FrameFooterProps = ComponentPropsWithRef<"footer"> & ChromeProps & {
+    readonly tone?: FrameTone;
+    readonly boundary?: FrameBoundaryStyle;
+    readonly decoration?: FrameDecorationStyle;
+    readonly signature?: ReactNode;
+    readonly signatureAppearance?: "standard" | "cropped";
+};
+export declare const FrameFooter: FC<FrameFooterProps>;

package/dist/frame/chrome/style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Chrome
+ * @description Style
+ */
+export declare const frameChromeStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const frameSignatureStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const frameSignatureCroppedStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;

package/dist/frame/decoration/decoration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Decoration
+ * @description Decoration
+ */
+import type { FrameBoundaryStyle } from "../boundary/boundary";
+import type { FC } from "react";
+export type FrameDecorationStyle = "none" | "nodes" | "marks" | "corners" | "ticks";
+export declare const resolveFrameDecoration: (boundary: FrameBoundaryStyle, decoration?: FrameDecorationStyle) => FrameDecorationStyle;
+export type FrameDecorationProps = {
+    readonly decoration: FrameDecorationStyle;
+};
+export declare const FrameDecoration: FC<FrameDecorationProps>;

package/dist/frame/export.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame
+ * @description Export
+ */
+export type { FrameBoundaryStyle } from "./boundary/boundary";
+export type { FrameFooterProps, FrameHeaderProps } from "./chrome/chrome";
+export { FrameFooter, FrameHeader } from "./chrome/chrome";
+export type { FrameDecorationStyle } from "./decoration/decoration";
+export type { FrameSectionsProps, PageFrameProps } from "./page/page";
+export { FrameSections, PageFrame } from "./page/page";
+export type { FrameRailGroupProps, FrameRailProps } from "./rail/rail";
+export { FrameRail, FrameRailGroup } from "./rail/rail";
+export type { FrameSectionProps } from "./section";
+export { FrameSection } from "./section";
+export type { FrameTone } from "./style";
+export type { FrameTextureStyle } from "./texture/texture";
+export { FrameTexture } from "./texture/texture";

package/dist/frame/page/page.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Page
+ * @description Page
+ */
+import type { ContainerProps } from "../../primitives/container/container";
+import type { Responsive, Space } from "../../primitives/responsive";
+import type { FrameRailGroupProps } from "../rail/rail";
+import type { ComponentPropsWithRef, FC, ReactNode } from "react";
+export type PageFrameProps = FrameRailGroupProps & {
+    readonly width?: ContainerProps["width"];
+    readonly header?: ReactNode;
+    readonly footer?: ReactNode;
+    readonly railScope?: "page" | "main";
+    readonly mainGutterStart?: Responsive<Space>;
+};
+export type FrameSectionsProps = ComponentPropsWithRef<"div">;
+export declare const FrameSections: FC<FrameSectionsProps>;
+export declare const PageFrame: FC<PageFrameProps>;

package/dist/frame/page/style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Page
+ * @description Style
+ */
+export declare const pageFrameVariants: (props?: ({
+    width?: "standard" | "narrow" | "wide" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/frame/rail/rail.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Rail
+ * @description Rail
+ */
+import type { Responsive, Space } from "../../primitives/responsive";
+import type { ComponentPropsWithRef, FC, ReactNode } from "react";
+export type FrameRailProps = ComponentPropsWithRef<"div"> & {
+    readonly placement?: "start" | "sticky-bottom";
+};
+export declare const FrameRail: FC<FrameRailProps>;
+export type FrameRailGroupProps = ComponentPropsWithRef<"div"> & {
+    readonly rail?: ReactNode;
+    readonly railWidth?: Responsive<Space>;
+};
+export declare const FrameRailGroup: FC<FrameRailGroupProps>;

package/dist/frame/rail/style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Rail
+ * @description Style
+ */
+export declare const frameRailStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const frameRailContentStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const frameRailStickyBottomStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;

package/dist/frame/section.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame
+ * @description Section
+ */
+import type { FrameBoundaryStyle } from "./boundary/boundary";
+import type { FrameDecorationStyle } from "./decoration/decoration";
+import type { FrameTone } from "./style";
+import type { FrameTextureStyle } from "./texture/texture";
+import type { ComponentPropsWithRef, FC } from "react";
+export type FrameSectionProps = ComponentPropsWithRef<"section"> & {
+    readonly tone?: FrameTone;
+    readonly boundary?: FrameBoundaryStyle;
+    readonly decoration?: FrameDecorationStyle;
+    readonly texture?: FrameTextureStyle;
+    readonly edges?: "frame" | "none";
+};
+export declare const FrameSection: FC<FrameSectionProps>;

package/dist/frame/style.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame
+ * @description Style
+ */
+export type FrameTone = "neutral" | "brand" | "warning" | "danger";
+export declare const frameToneStyles: (props?: ({
+    tone?: "neutral" | "brand" | "warning" | "danger" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const frameContentStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;

package/dist/frame/texture/texture.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Frame_Texture
+ * @description Texture
+ */
+import type { FC } from "react";
+export type FrameTextureStyle = "none" | "grid" | "dots" | "lines";
+export type FrameTextureProps = {
+    readonly texture: FrameTextureStyle;
+};
+export declare const FrameTexture: FC<FrameTextureProps>;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @author WMXPY
+ * @package Grid
+ * @namespace Root
+ * @description Index
+ */
+export * from "./frame/export";
+export * from "./primitives/export";