@cssints/layout 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @cssints/layout
 
-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.
+Layout primitives for [cssints](../../README.md), after [Every Layout](https://every-layout.dev) and
+[smolcss](https://smolcss.dev): `stack()`, `cluster()`, `sidebar()`, `switcher()`, `cover()` and `autoGrid()`. Each one is a
+chain member of `cssints/plugin` `scope()`: a call gives the primitive's kernel classes, and each method sets one custom
+property. No runtime, no media queries: the layouts respond to the space they have.
+
+```ts
+import { cn, p } from "cssints" with { type: "cssints" };
+import {
+  autoGrid,
+  cluster,
+  sidebar,
+  stack,
+  switcher,
+} from "@cssints/layout" with { type: "cssints" };
+
+export const page = cn(stack().gap(6), p(4));
+export const toolbar = cluster().gap(2).justify("space-between");
+export const layout = sidebar().width("20rem").content("50%").gap(4);
+export const buttons = switcher().threshold("30rem");
+export const cards = autoGrid().min("16rem").gap(4);
+```
+
+```css
+@layer _.k {
+  ._layout-stack-core {
+    gap: var(--layout-stack-gap);
+    --layout-stack-gap: 1rem;
+    display: flex;
+    flex-direction: column;
+  }
+  ._layout-sidebar-core {
+    gap: var(--layout-sidebar-gap);
+    --layout-sidebar-gap: 1rem;
+    --layout-sidebar-width: auto;
+    --layout-sidebar-content: 50%;
+    --layout-sidebar-ff: 1 1 var(--layout-sidebar-width);
+    --layout-sidebar-fm: auto;
+    --layout-sidebar-lf: 999 1 0;
+    --layout-sidebar-lm: var(--layout-sidebar-content);
+    display: flex;
+    flex-wrap: wrap;
+  }
+  ._layout-sidebar-core > :first-child {
+    flex: var(--layout-sidebar-ff);
+    min-inline-size: var(--layout-sidebar-fm);
+  }
+  ._layout-sidebar-core > :last-child {
+    flex: var(--layout-sidebar-lf);
+    min-inline-size: var(--layout-sidebar-lm);
+  }
+  ._layout-switcher-core > * {
+    flex-grow: 1;
+    flex-basis: calc((var(--layout-switcher-threshold) - 100%) * 999);
+  }
+  ._layout-grid-core {
+    gap: var(--layout-grid-gap);
+    --layout-grid-min: 16rem;
+    --layout-grid-gap: 1rem;
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(var(--layout-grid-min), 100%), 1fr));
+  }
+  /* ... the other kernels */
+}
+@layer _.a {
+  ._x {
+    --layout-stack-gap: 1.5rem;
+  }
+  ._y {
+    --layout-sidebar-width: 20rem;
+  }
+  /* ... one class per method and value */
+}
+```
+
+## The primitives
+
+| Primitive    | Methods (each once, in any order)                                             | What it is                                                                                                                         |
+| ------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `stack()`    | `gap` (1rem)                                                                  | a flex column with a gap                                                                                                           |
+| `cluster()`  | `gap` (1rem), `justify` (`flex-start`), `align` (`center`)                    | a wrapping row: tags, buttons, a toolbar                                                                                           |
+| `sidebar()`  | `side` (`left`), `width` (`auto`, its content), `content` (50%), `gap` (1rem) | two children side by side; they stack when the content child would be narrower than `content` of the container                     |
+| `switcher()` | `threshold` (30rem), `gap` (1rem)                                             | its children in one row while the container is wider than `threshold`, else one column (Heydon Pickering's Flexbox Holy Albatross) |
+| `cover()`    | `minHeight` (100vh), `gap` (1rem)                                             | a flex column of a min height with its content centred vertically                                                                  |
+| `autoGrid()` | `min` (16rem), `gap` (1rem)                                                   | as many columns of at least `min` as fit, `repeat(auto-fit, minmax(min(min, 100%), 1fr))`, which never overflows                   |
+
+- **Values.** `gap` takes a length or a percentage, and a lone number is a step of the spacing scale (0.25rem), as in
+  `padding`. `width`, `minHeight` and `min` take a length or a percentage, `threshold` a length, `content` a percentage from
+  0 to 100. `justify` is `start | end | center | space-between | space-around | space-evenly`, `align` is `start | end |
+center | baseline | stretch`, `side` is `left | right`. Tokens go where a length does. The types check each method, and
+  the build checks it again (ranges included: `content("120%")` fails at the call).
+- **Conditions.** A method in `media()`, `hover()` and the others sets the custom property under that condition:
+  `media("(width >= 40rem)")(stack().gap(8))`.
+
+## Rules
+
+- **Kernels.** Each primitive is one kernel in layer `_.k`, once, written as styles: the defaults of its custom properties
+  on the element (`vars()`), the container's properties and, for `sidebar()` and `switcher()`, the rules of the children
+  (`nest("& > *")`). A call is its class (`_layout-stack-core`), and each method one class in `_.a` (or `_.b` under a
+  condition), which wins over the defaults.
+- **Conflicts.** A `cn()` that holds a primitive and a property its core sets is a build error at the call, derived from
+  the kernel: `cn(stack(), display("grid"))` is
+  `cssints: layout: kernel stack-core sets display, flex-direction, gap (this style also sets display)`, and `cn(autoGrid(), rowGap("1rem"))` fails as well (a longhand of `gap`). Padding, sizes and
+  colours do not conflict, nor do the properties the kernel sets on the children (`cn(switcher(), flexGrow(0))` is fine). Conflicts with an opaque runtime string in `cn()` are not seen, as for any plugin.
+- **No leak into nested primitives.** The defaults are set on every primitive, so a `stack()` inside a `stack().gap(8)`
+  has a gap of 1rem, not 2rem.
+- **The children.** `sidebar()` sizes its first and last child (the first is the sidebar, or the last with
+  `side("right")`; the order in the DOM stays the reading order), `switcher()` every child. Those rules are one class
+  strong in `_.k`, so a class on a child wins over them.
+
+## Limits
+
+- `sidebar()` and `switcher()` pass their settings to the children by inheritance. A child that is itself a sidebar
+  (or a switcher) reads its own defaults or settings in its role as a child, not its parent's: wrap it in a plain element
+  when the parent's values are not the defaults.
+- `cover()` centres all its content; Every Layout's centred child between a header and a footer is `margin-block: auto`
+  on that child, which you write yourself.
+- Not here: Every Layout's `center`, `box`, `frame`, `reel`, `imposter` and `icon` (`box` and `center` are a few plain
+  properties; `frame()` in cssints is the concentric radius), and the switcher's limit on the number of items.
+
+```bash
+cd packages/layout && bun run test   # fixtures through the engine (output, conflicts, build errors), and the type test via bun run typecheck
+```
+
+## Credits
+
+The primitives are those of [Every Layout](https://every-layout.dev) (Heydon Pickering and Andy Bell) and
+[smolcss](https://smolcss.dev) (Stephanie Eckles); the switcher is Heydon Pickering's Flexbox Holy Albatross. The CSS is
+written here as styles of `scope()`; no code is copied.

package/dist/index.d.mts

@@ -0,0 +1,77 @@
+//#region src/index.d.ts
+/**
+ * Layout primitives, each a chain whose methods are used once: `stack().gap(4)`, `cluster().gap(2).justify("space-between")
+ * .align("center")`, `sidebar().side("left").width("20rem").content("50%").gap(4)`, `switcher().threshold("30rem").gap(4)`,
+ * `cover().minHeight("100vh").gap(4)`, `autoGrid().min("16rem").gap(4)`. A lone number in `gap` is a step of the spacing
+ * scale. A primitive sets `display` and the container's properties, so a `cn()` that sets one of them too is a build error.
+ */
+export declare const stack: () => import("cssints/plugin").Chain<"stack", {
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+}, {}>, cluster: () => import("cssints/plugin").Chain<"cluster", {
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+  readonly justify: {
+    readonly args: "start | end | center | space-between | space-around | space-evenly";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly align: {
+    readonly args: "start | end | center | baseline | stretch";
+    readonly emit: (v: string) => [string, string][];
+  };
+}, {}>, sidebar: () => import("cssints/plugin").Chain<"sidebar", {
+  readonly side: {
+    readonly args: "left | right";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly width: {
+    readonly args: "<length-percentage [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly content: {
+    readonly args: "<percentage [0,100]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+}, {}>, switcher: () => import("cssints/plugin").Chain<"switcher", {
+  readonly threshold: {
+    readonly args: "<length [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+}, {}>, cover: () => import("cssints/plugin").Chain<"cover", {
+  readonly minHeight: {
+    readonly args: "<length-percentage [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+}, {}>, autoGrid: () => import("cssints/plugin").Chain<"autoGrid", {
+  readonly min: {
+    readonly args: "<length-percentage [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly gap: {
+    readonly emit: (v: string) => [string, string][];
+    readonly args: "<length-percentage [0,∞]>";
+    readonly spacing: true;
+  };
+}, {}>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,176 @@
+import { scope } from "cssints/plugin";
+//#region src/index.ts
+const space = "<length-percentage [0,∞]>";
+const gap = {
+	args: space,
+	spacing: true
+};
+const narrow = {
+	flex: "1 1 var(--_sidebar-width)",
+	min: "auto"
+};
+const wide = {
+	flex: "999 1 0",
+	min: "var(--_sidebar-content)"
+};
+const sides = (first, last) => Object.entries({
+	"--_sidebar-ff": first.flex,
+	"--_sidebar-fm": first.min,
+	"--_sidebar-lf": last.flex,
+	"--_sidebar-lm": last.min
+});
+/**
+* Layout primitives, each a chain whose methods are used once: `stack().gap(4)`, `cluster().gap(2).justify("space-between")
+* .align("center")`, `sidebar().side("left").width("20rem").content("50%").gap(4)`, `switcher().threshold("30rem").gap(4)`,
+* `cover().minHeight("100vh").gap(4)`, `autoGrid().min("16rem").gap(4)`. A lone number in `gap` is a step of the spacing
+* scale. A primitive sets `display` and the container's properties, so a `cn()` that sets one of them too is a build error.
+*/
+const { stack, cluster, sidebar, switcher, cover, autoGrid } = scope("layout", {
+	"#stack-core": { css: (css) => [
+		css.vars({ "--_stack-gap": "1rem" }),
+		css.display("flex"),
+		css.flexDirection("column"),
+		css.gap("var(--_stack-gap)")
+	] },
+	stack: {
+		uses: ["stack-core"],
+		chain: { gap: {
+			...gap,
+			emit: (v) => [["--_stack-gap", v]]
+		} }
+	},
+	"#cluster-core": { css: (css) => [
+		css.vars({
+			"--_cluster-gap": "1rem",
+			"--_cluster-justify": "flex-start",
+			"--_cluster-align": "center"
+		}),
+		css.display("flex"),
+		css.flexWrap("wrap"),
+		css.gap("var(--_cluster-gap)"),
+		css.justifyContent("var(--_cluster-justify)"),
+		css.alignItems("var(--_cluster-align)")
+	] },
+	cluster: {
+		uses: ["cluster-core"],
+		chain: {
+			gap: {
+				...gap,
+				emit: (v) => [["--_cluster-gap", v]]
+			},
+			justify: {
+				args: "start | end | center | space-between | space-around | space-evenly",
+				emit: (v) => [["--_cluster-justify", v]]
+			},
+			align: {
+				args: "start | end | center | baseline | stretch",
+				emit: (v) => [["--_cluster-align", v]]
+			}
+		}
+	},
+	"#sidebar-core": { css: (css) => [
+		css.vars({
+			"--_sidebar-gap": "1rem",
+			"--_sidebar-width": "auto",
+			"--_sidebar-content": "50%",
+			...Object.fromEntries(sides(narrow, wide))
+		}),
+		css.display("flex"),
+		css.flexWrap("wrap"),
+		css.gap("var(--_sidebar-gap)"),
+		css.nest("& > :first-child")(css.flex("var(--_sidebar-ff)"), css.minInlineSize("var(--_sidebar-fm)")),
+		css.nest("& > :last-child")(css.flex("var(--_sidebar-lf)"), css.minInlineSize("var(--_sidebar-lm)"))
+	] },
+	sidebar: {
+		uses: ["sidebar-core"],
+		chain: {
+			side: {
+				args: "left | right",
+				emit: (v) => v === "right" ? sides(wide, narrow) : sides(narrow, wide)
+			},
+			width: {
+				args: space,
+				emit: (v) => [["--_sidebar-width", v]]
+			},
+			content: {
+				args: "<percentage [0,100]>",
+				emit: (v) => [["--_sidebar-content", v]]
+			},
+			gap: {
+				...gap,
+				emit: (v) => [["--_sidebar-gap", v]]
+			}
+		}
+	},
+	"#switcher-core": { css: (css) => [
+		css.vars({
+			"--_switcher-gap": "1rem",
+			"--_switcher-threshold": "30rem"
+		}),
+		css.display("flex"),
+		css.flexWrap("wrap"),
+		css.gap("var(--_switcher-gap)"),
+		css.nest("& > *")(css.flexGrow(1), css.flexBasis("calc((var(--_switcher-threshold) - 100%) * 999)"))
+	] },
+	switcher: {
+		uses: ["switcher-core"],
+		chain: {
+			threshold: {
+				args: "<length [0,∞]>",
+				emit: (v) => [["--_switcher-threshold", v]]
+			},
+			gap: {
+				...gap,
+				emit: (v) => [["--_switcher-gap", v]]
+			}
+		}
+	},
+	"#cover-core": { css: (css) => [
+		css.vars({
+			"--_cover-min": "100vh",
+			"--_cover-gap": "1rem"
+		}),
+		css.display("flex"),
+		css.flexDirection("column"),
+		css.justifyContent("center"),
+		css.minBlockSize("var(--_cover-min)"),
+		css.gap("var(--_cover-gap)")
+	] },
+	cover: {
+		uses: ["cover-core"],
+		chain: {
+			minHeight: {
+				args: space,
+				emit: (v) => [["--_cover-min", v]]
+			},
+			gap: {
+				...gap,
+				emit: (v) => [["--_cover-gap", v]]
+			}
+		}
+	},
+	"#grid-core": { css: (css) => [
+		css.vars({
+			"--_grid-min": "16rem",
+			"--_grid-gap": "1rem"
+		}),
+		css.display("grid"),
+		css.gridTemplateColumns("repeat(auto-fit, minmax(min(var(--_grid-min), 100%), 1fr))"),
+		css.gap("var(--_grid-gap)")
+	] },
+	autoGrid: {
+		uses: ["grid-core"],
+		chain: {
+			min: {
+				args: space,
+				emit: (v) => [["--_grid-min", v]]
+			},
+			gap: {
+				...gap,
+				emit: (v) => [["--_grid-gap", v]]
+			}
+		}
+	}
+}).export();
+//#endregion
+export { autoGrid, cluster, cover, sidebar, stack, switcher };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/layout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Layout primitives for cssints: stack, cluster, sidebar, switcher, cover and autoGrid as chain members",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/layout"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}