@mastors/gridder 1.2.0 → 1.2.2

package/README.md

@@ -1,592 +1,214 @@
 # @mastors/gridder
 
-> Complete CSS Grid utility class system for the Mastors ecosystem.
+> Complete CSS Grid utility class system + authoring mixins for the Mastors ecosystem.
 
-[![npm](https://img.shields.io/npm/v/@mastors/gridder.svg)](https://www.npmjs.com/package/@mastors/gridder)
+[![npm version](https://img.shields.io/npm/v/@mastors/gridder.svg)](https://www.npmjs.com/package/@mastors/gridder)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
-[![sass](https://img.shields.io/badge/requires-sass%20%3E%3D1.80-CC6699.svg)](https://sass-lang.com)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Utility Classes](#utility-classes)
-  - [Display](#display)
-  - [Grid Template Columns](#grid-template-columns)
-  - [Grid Template Rows](#grid-template-rows)
-  - [Grid Template Areas](#grid-template-areas)
-  - [Grid Auto Flow](#grid-auto-flow)
-  - [Grid Auto Columns](#grid-auto-columns)
-  - [Grid Auto Rows](#grid-auto-rows)
-  - [Column Span](#column-span)
-  - [Column Start & End](#column-start--end)
-  - [Row Span](#row-span)
-  - [Row Start & End](#row-start--end)
-  - [Grid Column Shorthand](#grid-column-shorthand)
-  - [Grid Row Shorthand](#grid-row-shorthand)
-  - [Justify Items](#justify-items)
-  - [Justify Self](#justify-self)
-  - [Align Items](#align-items)
-  - [Align Self](#align-self)
-  - [Place Items](#place-items)
-  - [Place Self](#place-self)
-  - [Gap](#gap)
-  - [Layout Presets](#layout-presets)
-- [Responsive Variants](#responsive-variants)
-- [Package Exports](#package-exports)
-- [Peer Dependencies](#peer-dependencies)
 
 ---
 
 ## Overview
 
-`@mastors/gridder` provides a complete set of atomic utility classes for CSS Grid — covering grid container setup, explicit and implicit track definitions, item placement, alignment, and named template area layouts. All utilities are generated via the core `generate-utilities()` engine and fully support responsive breakpoint prefixes.
-
-The package requires `@mastors/core` as a peer dependency and consumes its public API for the generator engine. It produces only utility classes — no reset, no base styles.
+`@mastors/gridder` delivers a full set of CSS Grid utility classes and authoring mixins built on top of `@mastors/core`. Every class has a responsive variant — just prefix with a breakpoint key (e.g. `.md:grid-cols-3`).
 
 ---
 
 ## Installation
 
 ```bash
-npm install @mastors/gridder @mastors/core sass
+npm install @mastors/gridder @mastors/core
 # or
-pnpm add @mastors/gridder @mastors/core sass
+pnpm add @mastors/gridder @mastors/core
+```
+
+Requires `sass >= 1.80.0`:
+
+```bash
+npm install --save-dev sass
 ```
 
 ---
 
 ## Usage
 
-### Import the full stylesheet
+### Import the stylesheet
 
 ```scss
 @use "@mastors/core/scss";
 @use "@mastors/gridder/scss";
 ```
 
-### Import a single partial
+Or import only the SCSS source to compile yourself:
 
 ```scss
-@use "@mastors/gridder/scss/utilities/grid-template-columns";
-```
-
-### HTML usage
-
-```html
-<!-- 3-column grid with gap -->
-<div class="grid grid-cols-3 gap-6">
-  <div class="col-span-2">Wide item</div>
-  <div>Narrow item</div>
-</div>
-
-<!-- Responsive grid — 1 col on mobile, 2 on md, 3 on lg -->
-<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-  <div>Item</div>
-  <div>Item</div>
-  <div>Item</div>
-</div>
-
-<!-- Item spanning full width -->
-<div class="grid grid-cols-12 gap-4">
-  <header class="col-span-full">Full-width header</header>
-  <aside class="col-span-3">Sidebar</aside>
-  <main class="col-span-9">Content</main>
-</div>
+@use "@mastors/gridder/scss/index";
 ```
 
----
-
-## Utility Classes
-
-### Display
-
-Sets `display` to a grid context.
-
-| Class | CSS |
-|---|---|
-| `.grid` | `display: grid` |
-| `.inline-grid` | `display: inline-grid` |
-
-Both support responsive prefixes.
-
----
-
-### Grid Template Columns
-
-Defines explicit column tracks.
-
-**Fixed column counts** (each track is `minmax(0, 1fr)`):
-
-| Class | CSS |
-|---|---|
-| `.grid-cols-1` | `grid-template-columns: repeat(1, minmax(0, 1fr))` |
-| `.grid-cols-2` | `grid-template-columns: repeat(2, minmax(0, 1fr))` |
-| `.grid-cols-3` | `grid-template-columns: repeat(3, minmax(0, 1fr))` |
-| `.grid-cols-4` | `grid-template-columns: repeat(4, minmax(0, 1fr))` |
-| `.grid-cols-5` | `grid-template-columns: repeat(5, minmax(0, 1fr))` |
-| `.grid-cols-6` | `grid-template-columns: repeat(6, minmax(0, 1fr))` |
-| `.grid-cols-7` | `grid-template-columns: repeat(7, minmax(0, 1fr))` |
-| `.grid-cols-8` | `grid-template-columns: repeat(8, minmax(0, 1fr))` |
-| `.grid-cols-9` | `grid-template-columns: repeat(9, minmax(0, 1fr))` |
-| `.grid-cols-10` | `grid-template-columns: repeat(10, minmax(0, 1fr))` |
-| `.grid-cols-11` | `grid-template-columns: repeat(11, minmax(0, 1fr))` |
-| `.grid-cols-12` | `grid-template-columns: repeat(12, minmax(0, 1fr))` |
-
-**Named variants:**
-
-| Class | CSS |
-|---|---|
-| `.grid-cols-none` | `grid-template-columns: none` |
-| `.grid-cols-subgrid` | `grid-template-columns: subgrid` |
-| `.grid-cols-auto` | `grid-template-columns: auto` |
-| `.grid-cols-min` | `grid-template-columns: min-content` |
-| `.grid-cols-max` | `grid-template-columns: max-content` |
-| `.grid-cols-fr` | `grid-template-columns: minmax(0, 1fr)` |
-
----
-
-### Grid Template Rows
-
-Defines explicit row tracks.
-
-**Fixed row counts:**
-
-| Class | CSS |
-|---|---|
-| `.grid-rows-1` | `grid-template-rows: repeat(1, minmax(0, 1fr))` |
-| `.grid-rows-2` | `grid-template-rows: repeat(2, minmax(0, 1fr))` |
-| `.grid-rows-3` | `grid-template-rows: repeat(3, minmax(0, 1fr))` |
-| `.grid-rows-4` | `grid-template-rows: repeat(4, minmax(0, 1fr))` |
-| `.grid-rows-5` | `grid-template-rows: repeat(5, minmax(0, 1fr))` |
-| `.grid-rows-6` | `grid-template-rows: repeat(6, minmax(0, 1fr))` |
-
-**Named variants:**
-
-| Class | CSS |
-|---|---|
-| `.grid-rows-none` | `grid-template-rows: none` |
-| `.grid-rows-subgrid` | `grid-template-rows: subgrid` |
-| `.grid-rows-auto` | `grid-template-rows: auto` |
-| `.grid-rows-min` | `grid-template-rows: min-content` |
-| `.grid-rows-max` | `grid-template-rows: max-content` |
-| `.grid-rows-fr` | `grid-template-rows: minmax(0, 1fr)` |
-
----
-
-### Grid Template Areas
-
-Named grid areas cannot be atomic utilities — the area strings are layout-specific. Gridder provides a SCSS mixin API and named placement helpers instead.
-
-#### SCSS mixin API
+### Use authoring mixins
 
 ```scss
-@use "@mastors/gridder/scss/utilities/grid-template-areas" as areas;
-
-.page-layout {
-  display: grid;
-  @include areas.define-areas(
-    "header header",
-    "sidebar main",
-    "footer footer"
+@use "@mastors/core/api" as m;
+@use "@mastors/gridder/scss/mixins" as grid;
+
+.layout {
+  @include grid.gridder-areas(
+    "header header header",
+    "sidebar main    main",
+    "footer footer  footer"
   );
-  grid-template-columns: 250px 1fr;
-  grid-template-rows: auto 1fr auto;
+  grid-template-columns: 240px 1fr;
+  gap: m.spacing(4);
 }
 
-.my-header  { @include areas.area(header); }
-.my-sidebar { @include areas.area(sidebar); }
-.my-main    { @include areas.area(main); }
-.my-footer  { @include areas.area(footer); }
+.layout__header  { @include grid.gridder("header"); }
+.layout__sidebar { @include grid.gridder("sidebar"); }
+.layout__main    { @include grid.gridder("main"); }
+.layout__footer  { @include grid.gridder("footer"); }
 ```
 
-#### Named area placement classes
-
-Assign child elements to their named areas:
-
-| Class | CSS |
-|---|---|
-| `.area-header` | `grid-area: header` |
-| `.area-nav` | `grid-area: nav` |
-| `.area-sidebar` | `grid-area: sidebar` |
-| `.area-main` | `grid-area: main` |
-| `.area-aside` | `grid-area: aside` |
-| `.area-footer` | `grid-area: footer` |
-
----
-
-### Grid Auto Flow
-
-Controls how the auto-placement algorithm fills the grid.
-
-| Class | CSS |
-|---|---|
-| `.grid-flow-row` | `grid-auto-flow: row` |
-| `.grid-flow-col` | `grid-auto-flow: column` |
-| `.grid-flow-dense` | `grid-auto-flow: dense` |
-| `.grid-flow-row-dense` | `grid-auto-flow: row dense` |
-| `.grid-flow-col-dense` | `grid-auto-flow: column dense` |
-
-Supports responsive prefixes.
-
 ---
 
-### Grid Auto Columns
-
-Sizes implicitly created columns.
-
-| Class | CSS |
-|---|---|
-| `.auto-cols-auto` | `grid-auto-columns: auto` |
-| `.auto-cols-min` | `grid-auto-columns: min-content` |
-| `.auto-cols-max` | `grid-auto-columns: max-content` |
-| `.auto-cols-fr` | `grid-auto-columns: minmax(0, 1fr)` |
-
----
-
-### Grid Auto Rows
-
-Sizes implicitly created rows.
-
-| Class | CSS |
-|---|---|
-| `.auto-rows-auto` | `grid-auto-rows: auto` |
-| `.auto-rows-min` | `grid-auto-rows: min-content` |
-| `.auto-rows-max` | `grid-auto-rows: max-content` |
-| `.auto-rows-fr` | `grid-auto-rows: minmax(0, 1fr)` |
-
----
-
-### Column Span
-
-Makes an item span multiple columns.
-
-| Class | CSS |
-|---|---|
-| `.col-span-1` | `grid-column: span 1 / span 1` |
-| `.col-span-2` | `grid-column: span 2 / span 2` |
-| … | … |
-| `.col-span-12` | `grid-column: span 12 / span 12` |
-| `.col-span-full` | `grid-column: 1 / -1` |
-| `.col-auto` | `grid-column: auto` |
-
----
-
-### Column Start & End
-
-Explicitly places an item at a grid column line.
-
-**Start lines** — `.col-start-1` through `.col-start-13`, `.col-start-auto`
-
-**End lines** — `.col-end-1` through `.col-end-13`, `.col-end-auto`
+## Package Exports
 
-```html
-<!-- Item starts at line 2 and ends at line 5 -->
-<div class="col-start-2 col-end-5">...</div>
+```json
+{
+  ".":        "./dist/mastors-gridder.css",
+  "./scss":   "./scss/index.scss",
+  "./scss/*": "./scss/*"
+}
 ```
 
 ---
 
-### Row Span
+## Utility Classes
 
-Makes an item span multiple rows.
+### Display
 
 | Class | CSS |
 |---|---|
-| `.row-span-1` | `grid-row: span 1 / span 1` |
-| … | … |
-| `.row-span-6` | `grid-row: span 6 / span 6` |
-| `.row-span-full` | `grid-row: 1 / -1` |
-| `.row-auto` | `grid-row: auto` |
-
----
-
-### Row Start & End
-
-Explicitly places an item at a grid row line.
+| `.grid` | `display: grid` |
+| `.inline-grid` | `display: inline-grid` |
 
-**Start lines** — `.row-start-1` through `.row-start-7`, `.row-start-auto`
+### Template Columns
 
-**End lines** — `.row-end-1` through `.row-end-7`, `.row-end-auto`
+`.grid-cols-1` through `.grid-cols-12` `.grid-cols-none`
 
 ```html
-<!-- Item starts at row 1, ends at row 3 -->
-<div class="row-start-1 row-end-3">...</div>
+<div class="grid grid-cols-3 md:grid-cols-6">...</div>
 ```
 
----
-
-### Grid Column Shorthand
-
-`grid-column` shorthand placement utilities.
-
-| Class | CSS |
-|---|---|
-| `.grid-col-auto` | `grid-column: auto` |
-| `.grid-col-1` | `grid-column: 1` |
-| … | … |
-| `.grid-col-12` | `grid-column: 12` |
-
----
-
-### Grid Row Shorthand
-
-`grid-row` shorthand placement utilities.
+### Template Rows
 
-| Class | CSS |
-|---|---|
-| `.grid-row-auto` | `grid-row: auto` |
-| `.grid-row-1` | `grid-row: 1` |
-| … | … |
-| `.grid-row-6` | `grid-row: 6` |
-
----
+`.grid-rows-1` through `.grid-rows-6` `.grid-rows-none`
 
-### Justify Items
+### Auto Flow
 
-Aligns all grid items along the **inline axis**.
-
-| Class | CSS |
-|---|---|
-| `.justify-items-start` | `justify-items: start` |
-| `.justify-items-end` | `justify-items: end` |
-| `.justify-items-center` | `justify-items: center` |
-| `.justify-items-stretch` | `justify-items: stretch` |
+`.grid-flow-row` `.grid-flow-col` `.grid-flow-dense` `.grid-flow-row-dense` `.grid-flow-col-dense`
 
-Supports responsive prefixes.
+### Auto Columns / Rows
 
----
-
-### Justify Self
-
-Aligns a **single** grid item along the inline axis.
-
-| Class | CSS |
-|---|---|
-| `.justify-self-auto` | `justify-self: auto` |
-| `.justify-self-start` | `justify-self: start` |
-| `.justify-self-end` | `justify-self: end` |
-| `.justify-self-center` | `justify-self: center` |
-| `.justify-self-stretch` | `justify-self: stretch` |
+`.auto-cols-auto` `.auto-cols-min` `.auto-cols-max` `.auto-cols-fr`
+`.auto-rows-auto` `.auto-rows-min` `.auto-rows-max` `.auto-rows-fr`
 
-Supports responsive prefixes.
-
----
-
-### Align Items
-
-Aligns all grid items along the **block axis**.
-
-| Class | CSS |
-|---|---|
-| `.items-start` | `align-items: start` |
-| `.items-end` | `align-items: end` |
-| `.items-center` | `align-items: center` |
-| `.items-stretch` | `align-items: stretch` |
-| `.items-baseline` | `align-items: baseline` |
-
-Supports responsive prefixes.
-
----
-
-### Align Self
+### Column Span
 
-Aligns a **single** grid item along the block axis.
+`.col-span-1` through `.col-span-12` `.col-span-full` `.col-auto`
 
-| Class | CSS |
-|---|---|
-| `.self-auto` | `align-self: auto` |
-| `.self-start` | `align-self: start` |
-| `.self-end` | `align-self: end` |
-| `.self-center` | `align-self: center` |
-| `.self-stretch` | `align-self: stretch` |
-| `.self-baseline` | `align-self: baseline` |
-
-Supports responsive prefixes.
+### Row Span
 
----
+`.row-span-1` through `.row-span-6` `.row-span-full` `.row-auto`
 
-### Place Items
+### Column Start / End
 
-Shorthand for `align-items` + `justify-items`.
+`.col-start-1` through `.col-start-13` `.col-start-auto`
+`.col-end-1` through `.col-end-13` `.col-end-auto`
 
-| Class | CSS |
-|---|---|
-| `.place-items-start` | `place-items: start` |
-| `.place-items-end` | `place-items: end` |
-| `.place-items-center` | `place-items: center` |
-| `.place-items-stretch` | `place-items: stretch` |
+### Row Start / End
 
-Supports responsive prefixes.
+`.row-start-1` through `.row-start-7` `.row-start-auto`
+`.row-end-1` through `.row-end-7` `.row-end-auto`
 
----
+### Justify Items / Content
 
-### Place Self
+`.justify-items-start` `.justify-items-end` `.justify-items-center` `.justify-items-stretch`
+`.justify-content-start` `.justify-content-end` `.justify-content-center` `.justify-content-between` `.justify-content-around` `.justify-content-evenly`
 
-Shorthand for `align-self` + `justify-self` on a single item.
+### Align Items / Content
 
-| Class | CSS |
-|---|---|
-| `.place-self-auto` | `place-self: auto` |
-| `.place-self-start` | `place-self: start` |
-| `.place-self-end` | `place-self: end` |
-| `.place-self-center` | `place-self: center` |
-| `.place-self-stretch` | `place-self: stretch` |
+`.items-start` `.items-end` `.items-center` `.items-stretch` `.items-baseline`
+`.content-start` `.content-end` `.content-center` `.content-between` `.content-around` `.content-evenly` `.content-stretch`
 
-Supports responsive prefixes.
+### Place Items / Content / Self
 
----
+`.place-items-start` `.place-items-center` `.place-items-end` `.place-items-stretch`
+`.place-content-start` `.place-content-center` `.place-content-between` `.place-content-stretch`
+`.place-self-auto` `.place-self-start` `.place-self-center` `.place-self-end` `.place-self-stretch`
 
 ### Gap
 
-Gap utilities (`.gap-*`, `.gap-x-*`, `.gap-y-*`) are provided by `@mastors/core` and work for both grid and flex containers. They are available whenever `@mastors/core` is imported.
-
-```html
-<div class="grid grid-cols-3 gap-6">...</div>
-<div class="grid grid-cols-2 gap-x-8 gap-y-4">...</div>
-```
-
-See the [`@mastors/core` spacing utilities](../core/README.md#utility-classes) for the full scale.
-
----
+`.gap-0` through `.gap-96` (follows the core spacing scale)
+`.gap-x-{n}` `.gap-y-{n}`
 
 ### Layout Presets
 
-Gridder ships three ready-made named-area layout classes for common full-page patterns.
+`.grid-sidebar` — two-column layout with a 240px sidebar and a `1fr` main area
+`.grid-holy-grail` — three-column holy grail layout
 
-#### Holy Grail
-
-Header / (nav + main + aside) / footer — three columns, three rows.
-
-```html
-<div class="layout-holy-grail">
-  <div class="area-header">Header</div>
-  <div class="area-nav">Nav</div>
-  <div class="area-main">Main</div>
-  <div class="area-aside">Aside</div>
-  <div class="area-footer">Footer</div>
-</div>
-```
+---
 
-Grid template: `"header header header" / "nav main aside" / "footer footer footer"`, columns `auto 1fr auto`.
+## Authoring Mixins
 
-#### Sidebar
+### `gridder($area, $col-start?, $col-end?, $row-start?, $row-end?, $align-self?, $justify-self?)`
 
-Two-column: fixed-width sidebar + fluid main area.
+Place an element in a named grid area or via explicit line numbers.
 
-```html
-<div class="layout-sidebar">
-  <div class="area-sidebar">Sidebar</div>
-  <div class="area-main">Content</div>
-</div>
+```scss
+// Named area (grid-template-areas mode)
+@include grid.gridder("sidebar");
+
+// Explicit lines
+@include grid.gridder(
+  $area:         null,
+  $col-start:    1,
+  $col-end:      3,
+  $row-start:    2,
+  $row-end:      4,
+  $align-self:   center,
+  $justify-self: stretch
+);
 ```
 
-Grid template: `"sidebar main"`, columns `auto 1fr`.
-
-#### Dashboard
+### `gridder-areas($rows...)`
 
-Header + (sidebar + content) + footer.
+Declare `grid-template-areas` from a variadic list of quoted row strings.
 
-```html
-<div class="layout-dashboard">
-  <div class="area-header">Header</div>
-  <div class="area-sidebar">Sidebar</div>
-  <div class="area-content">Content</div>
-  <div class="area-footer">Footer</div>
-</div>
+```scss
+@include grid.gridder-areas(
+  "header header",
+  "nav    main",
+  "footer footer"
+);
 ```
 
-Grid template: `"header header" / "sidebar content" / "footer footer"`, columns `auto 1fr`.
-
 ---
 
 ## Responsive Variants
 
-Every utility marked `responsive: true` generates breakpoint-prefixed variants using the pattern `.{bp}:{class}`.
-
-**Breakpoints:**
-
-| Prefix | Min-width |
-|---|---|
-| *(none)* | 0px (mobile base) |
-| `sm:` | 640px |
-| `md:` | 768px |
-| `lg:` | 1024px |
-| `xl:` | 1280px |
-| `2xl:` | 1536px |
-
-**Examples:**
+Every utility class ships a breakpoint-prefixed responsive variant:
 
 ```html
-<!-- 1 col → 2 col → 3 col as viewport grows -->
-<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-
-<!-- Switch auto-flow direction on large screens -->
-<div class="grid grid-flow-row lg:grid-flow-col">
-
-<!-- Center items on mobile, stretch on desktop -->
-<div class="grid place-items-center lg:place-items-stretch">
-
-<!-- Item spans full width on mobile, 8/12 on lg -->
-<div class="col-span-full lg:col-span-8">
-```
-
-Utilities with responsive support: `grid` display, `grid-auto-flow`, `justify-items`, `justify-self`, `align-items`, `align-self`, `place-items`, `place-self`.
-
----
-
-## Package Exports
-
-```json
-{
-  ".": "./dist/mastors-gridder.css",
-  "./scss": "./scss/index.scss",
-  "./scss/*": "./scss/*"
-}
+<div class="grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">...</div>
+<div class="col-span-full md:col-span-6">...</div>
+<div class="gap-4 xl:gap-8">...</div>
 ```
 
-```scss
-/* Full gridder stylesheet */
-@use "@mastors/gridder/scss";
-
-/* Individual partial */
-@use "@mastors/gridder/scss/utilities/grid-template-columns";
-
-/* Template areas mixin API */
-@use "@mastors/gridder/scss/utilities/grid-template-areas" as areas;
-```
-
----
-
-## Peer Dependencies
-
-| Package | Version |
-|---|---|
-| `@mastors/core` | `>= 1.0.0` |
-| `sass` | `>= 1.80.0` |
+Breakpoints: `sm:` `md:` `lg:` `xl:` `2xl:`
 
 ---
 
 ## Changelog
 
-### v1.2.0
-
-- **Added:** `gridder($area, ...)` mixin — named `grid-area` placement with optional `align-self` / `justify-self` overrides in the same call
-- **Added:** `gridder-areas($rows...)` mixin — declare `grid-template-areas` from a variadic list of quoted row strings, co-located with `gridder()` child calls
-- **Updated dependency:** `@mastors/core@1.2.0`
-
-### v1.1.0
-
-- Updated dependency: `@mastors/core@1.1.0`
-
-### v1.0.0
-
-- Initial public release — full CSS Grid utility set, layout presets, `generate-utilities()` engine, full responsive breakpoint support
-
----
+See the [root CHANGELOG](../../README.md#changelog).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastors/gridder",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Mastors Gridder — complete CSS Grid utility class system",
   "license": "MIT",
   "author": "Mastors Contributors",