@cssints/masonry 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,107 @@
-# Temporary Holding Version
+# @cssints/masonry
 
-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.
+A masonry layout for [cssints](../../README.md): `masonry()`, a chain member of `cssints/plugin` `scope()`. Items of
+different heights are packed into as many columns as fit, each item under the shortest column, with no row gaps. It is
+CSS Grid Level 3's grid lanes (`display: grid-lanes`) where the browser has them, and CSS multi-column layout where it
+does not. No JavaScript, no media queries.
+
+```ts
+import { cn, p } from "cssints" with { type: "cssints" };
+import { masonry } from "@cssints/masonry" with { type: "cssints" };
+
+export const photos = masonry();
+export const wall = cn(masonry().columns("12rem").gap(4), p(2));
+```
+
+```css
+@layer _.k {
+  ._masonry-lanes {
+    columns: var(--masonry-min);
+    gap: var(--masonry-gap);
+    --masonry-min: 16rem;
+    --masonry-gap: 1rem;
+    display: grid-lanes;
+    grid-template-columns: repeat(auto-fill, minmax(min(var(--masonry-min), 100%), 1fr));
+  }
+  /* only when a browserslist target lacks grid lanes */
+  @supports not (display: grid-lanes) {
+    ._masonry-lanes > * {
+      display: inline-block;
+      inline-size: 100%;
+      vertical-align: top;
+      break-inside: avoid;
+      margin-block-end: var(--masonry-gap);
+    }
+  }
+}
+@layer _.a {
+  ._x {
+    --masonry-min: 12rem;
+  }
+  ._y {
+    --masonry-gap: 1rem;
+  }
+}
+```
+
+## Methods
+
+Each once, in any order:
+
+| Method    | Default | What it is                                                                                    |
+| --------- | ------- | --------------------------------------------------------------------------------------------- |
+| `columns` | 16rem   | the least width of a column: as many columns as fit, never wider than the container           |
+| `gap`     | 1rem    | the space between columns and between an item and the next in its column (one value for both) |
+
+Both take a length (no percentage: the fallback's `columns` and margins cannot use one the same way). A lone number in
+`gap` is a step of the spacing scale (0.25rem), as in `padding`. Tokens go where a length does. The types check each
+method, and the build checks it again. A method in `media()` or another condition sets the custom property under it.
+
+## Browsers
+
+- **Native: grid lanes.** `display: grid-lanes` is the syntax the CSS Working Group settled on for masonry (CSS Grid
+  Level 3, 2025), in place of `grid-template-rows: masonry` and `display: masonry`. Safari 26.4 ships it; Chrome and Edge
+  (since 140) and Firefox (since 77, still on the old `grid-template-*: masonry` syntax) have it only behind a flag (October
+  2026). `@mdn/browser-compat-data` knows it as `css.properties.display.grid-lanes`.
+- **Fallback: columns.** The kernel's `columns` is the fallback: a browser that has grid lanes ignores it (a grid lanes
+  container is not a block container), one that lacks them drops `display: grid-lanes` and lays the items out in
+  columns. For a target that lacks grid lanes (the default targets do: Chrome and Firefox), the build adds the
+  `@supports not` rule above for the items: a fallback of CSS only, so it reaches every target and covers the support
+  warning of `display: grid-lanes` (its `polyfills` name the same BCD key). For targets that all have grid lanes (`safari
+26.4`), the rules are not in the sheet.
+- Checked in Chrome 154 and Firefox 155 (columns) and Playwright's WebKit 26.6 (grid lanes, and the columns with the native
+  value hidden): `bun run test:browsers`.
+
+## Rules
+
+- **Kernel.** One kernel in layer `_.k`, once, written as styles (`css.display("grid-lanes")`, `gridTemplateColumns`,
+  `gap`, `columns`): the defaults of the custom properties on the element (a nested masonry does not inherit its
+  parent's values), `display`, the columns and the gap. A call is its class (`_masonry-lanes`), and
+  each method one class in `_.a` (or `_.b` under a condition), which wins over the defaults.
+- **Conflicts**, derived from the kernel. A `cn()` that holds `masonry()` and `display`, `grid`, `grid-template`,
+  `grid-template-columns`, `gap`, `row-gap`, `column-gap`, `columns`, `column-width` or `column-count` is a build error
+  at the call:
+  `cssints: masonry: kernel lanes sets display, grid-template-columns, gap, columns (this style also sets display)`.
+  Padding, sizes and colours do not conflict. Conflicts with an opaque runtime string in `cn()` are not seen, as for any plugin.
+
+## Limits
+
+- **The order differs.** Grid lanes put each item in the shortest column, so the items read across, roughly row by row.
+  The columns fallback fills the first column top to bottom, then the next: item 2 sits under item 1, not beside it.
+  When the order matters (a feed, a timeline sorted by date), the fallback shows it down the columns.
+- **The fallback sets the items' box.** Each child is an inline block as wide as its column, with a bottom margin of
+  `gap` (a block's margin before a column break moves the next column down in WebKit). An item shorter than its line
+  height gets that height; a `display` of your own on an item replaces the inline block, and in Safari before 26.4 its
+  column may then start a gap lower. The columns are balanced, so the last items may leave one column longer.
+- Not here: `flow-tolerance` (cssints has it, `flowTolerance()`, Safari 26.4 only: set it beside `masonry()`), rows as lanes (`grid-template-rows`, a horizontal masonry), items that span lanes, and a
+  JavaScript polyfill (masonic, solid-mason: too heavy for a fallback that CSS gives).
+
+```bash
+cd packages/masonry && bun run test   # fixtures through the engine (output for both kinds of targets, conflicts, build errors, a build), and the type test via bun run typecheck
+bun run test:browsers                 # Chrome, Firefox and WebKit through playwright-core: items pack with no row gaps
+```
+
+## Credits
+
+The layout is CSS Grid Layout Module Level 3 (the W3C CSS Working Group), `display: grid-lanes` as WebKit ships
+it. Nothing is copied.

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+//#region src/index.d.ts
+/**
+ * A masonry layout, `masonry().columns("16rem").gap(4)`: as many columns of at least `columns` as fit (16rem), items
+ * packed into the shortest column, `gap` between them (1rem; a lone number is a step of the spacing scale). Native grid
+ * lanes where the browser has them, CSS columns elsewhere (items ordered down each column). It sets `display`, the columns
+ * and the gap, so a `cn()` that also sets one of them is a build error.
+ */
+export declare const masonry: () => import("cssints/plugin").Chain<"masonry", {
+  readonly columns: {
+    readonly args: "<length [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly gap: {
+    readonly args: "<length [0,∞]>";
+    readonly spacing: true;
+    readonly emit: (v: string) => [string, string][];
+  };
+}, {}>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,40 @@
+import { scope } from "cssints/plugin";
+//#region src/index.ts
+/**
+* A masonry layout, `masonry().columns("16rem").gap(4)`: as many columns of at least `columns` as fit (16rem), items
+* packed into the shortest column, `gap` between them (1rem; a lone number is a step of the spacing scale). Native grid
+* lanes where the browser has them, CSS columns elsewhere (items ordered down each column). It sets `display`, the columns
+* and the gap, so a `cn()` that also sets one of them is a build error.
+*/
+const { masonry } = scope("masonry", {
+	"#lanes": { css: (css) => [
+		css.vars({
+			"--_min": "16rem",
+			"--_gap": "1rem"
+		}),
+		css.display("grid-lanes"),
+		css.gridTemplateColumns("repeat(auto-fill,minmax(min(var(--_min),100%),1fr))"),
+		css.gap("var(--_gap)"),
+		css.columns("var(--_min)")
+	] },
+	"#columns": {
+		polyfills: ["css.properties.display.grid-lanes"],
+		css: "@supports not (display:grid-lanes){&>*{display:inline-block;inline-size:100%;vertical-align:top;break-inside:avoid;margin-block-end:var(--_gap)}}"
+	},
+	masonry: {
+		uses: ["lanes", "columns"],
+		chain: {
+			columns: {
+				args: "<length [0,∞]>",
+				emit: (v) => [["--_min", v]]
+			},
+			gap: {
+				args: "<length [0,∞]>",
+				spacing: true,
+				emit: (v) => [["--_gap", v]]
+			}
+		}
+	}
+}).export();
+//#endregion
+export { masonry };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/masonry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Masonry for cssints: display grid-lanes with a CSS columns fallback, as a chain member",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/masonry"
+  },
+  "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"
+  }
+}