@labmgm/patterns 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @labmgm/patterns
+
+The signature geometric pattern engine for the MGM Laboratory Design System — deterministic seeded composition with algorithmic adjacency colour-graph enforcement.
+
+## Install
+
+```bash
+pnpm add @labmgm/patterns react
+```
+
+## Use
+
+```tsx
+import { Pattern, Logo, Wordmark } from "@labmgm/patterns";
+
+// Corner cluster, default 3×3 at 40 px per cell.
+<Pattern variant="corner" seed={42} />
+
+// Vertical auth-page banner.
+<Pattern variant="edge-strip" grid="9x2" cellSize={40} seed={1} />
+
+// The 8 px footer dado (brand spec §7.8) — strict colour cycle, no shapes.
+<Pattern variant="dado-footer" />
+
+// Tile-driven mode — use one of the curated SVGs in ./patterns as the cell.
+<Pattern variant="corner" seed={42} base="p-1" />
+<Pattern variant="corner" seed={42} pool={["p-1", "p-2", "p-10"]} />
+
+// Wordmark + signature mark.
+<Wordmark size={32} />
+<Logo size={24} />
+<Logo size={24} monochrome />
+```
+
+## What the engine guarantees
+
+- **Deterministic by seed.** `(variant, grid, seed, cellSize, base | pool)` → byte-identical SVG every time.
+- **Adjacency constraint enforced.** No two 4-connected cells share a background colour. Implemented with greedy graph-colouring + backtracking over a 5-colour palette (brand-blue / yellow / red / green + white). Verified by a Vitest suite that runs 100 seeds × 5 grid shapes per build.
+- **Brand-spec colour rules.** White-background cells get a coloured shape; coloured-background cells get a white shape (brand spec §5.2). The dado variant cycles strictly through blue → yellow → red → green and uses no shapes.
+- **Tile catalog.** 80 curated SVG tiles live in `./patterns`. The build script `pnpm gen:tiles` parses them into `src/tiles-catalog.ts`; the generator can render any cell from a named tile (`base`) or pick from a sub-pool (`pool`). Tile shapes are recoloured per cell so adjacency still holds.
+
+## Variants
+
+| Variant         | Default grid | Default cell | Where to use                                       |
+| --------------- | ------------ | ------------ | -------------------------------------------------- |
+| `corner`        | 3 × 3        | 40 px        | Top-left / top-right corner of a hero (≤ 30% area) |
+| `edge-strip`    | 9 × 2        | 40 px        | Auth-page vertical banner (brand spec §10.2)       |
+| `divider-strip` | 1 × 12       | 32 px        | Section dividers between two major sections        |
+| `dado-footer`   | 1 × 32       | 8 px         | Brand-spec §7.8 — 8 px alternating footer band     |
+| `full-scene`    | 5 × 6        | 80 px        | 404 / empty-state asymmetric 5/7 illustration      |
+
+## API
+
+| Export                  | Description                                                              |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `<Pattern>`             | React component. Decorative by default (`aria-hidden`).                  |
+| `<Logo>` / `<Wordmark>` | The brand mark + wordmark (brand spec §5.5). `monochrome` for one-tone.  |
+| `generatePatternData()` | Pure function — returns the structured cell list. Use for custom render. |
+| `generatePatternSvg()`  | Pure function — returns a paste-ready standalone SVG string.             |
+| `colourGrid()`          | Standalone adjacency solver (returned colours; no shapes).               |
+| `SHAPES` / `PALETTE`    | The fixed shape vocabulary + 5-colour palette.                           |
+| `TILES` / `TILE_BY_ID`  | Auto-generated catalog of the curated SVG tiles in `./patterns`.         |
+
+## License
+
+MIT © MGM Laboratory.

package/dist/generator-URuC3uDY.d.cts

@@ -0,0 +1,179 @@
+/**
+ * The fixed 5-colour palette used by every pattern block.
+ *
+ * Brand spec §5.2: "Use all four brand colors plus white. Never substitute
+ * or omit one." The colours themselves come from spec §2.1.
+ */
+type PaletteColor = "blue" | "yellow" | "red" | "green" | "white";
+declare const PALETTE: readonly PaletteColor[];
+/** CSS-variable hooks so the palette switches with the active theme. */
+declare const PALETTE_VAR: Record<PaletteColor, string>;
+/** Hard-coded hex for stand-alone SVG (no CSS-var support). */
+declare const PALETTE_HEX: Record<PaletteColor, string>;
+
+/**
+ * Adjacency colour-graph solver.
+ *
+ * Brand spec §5.2: "No two adjacent cells share the same dominant color."
+ *
+ * Given a grid of cells (4-connected) and a palette of 5 colours, we want
+ * to assign every cell a background colour so no neighbour matches. With
+ * 5 colours on a rectangular grid this is always solvable — but we want
+ * the assignment to be *deterministic by seed* so the same `(grid, seed)`
+ * always renders identically.
+ *
+ * Algorithm: greedy with backtracking.
+ *   1. Visit cells in a seed-shuffled order.
+ *   2. Try each palette colour, also in seed-shuffled order.
+ *   3. Skip colours that match any already-assigned neighbour.
+ *   4. If no colour fits, backtrack to the previous cell and pick the next
+ *      candidate. With 5 colours and ≤ 4 neighbours, a fit is always
+ *      reachable from any prefix — we still cap recursion at `MAX_DEPTH`
+ *      to guard against pathological inputs.
+ */
+
+interface GridCell {
+    row: number;
+    col: number;
+}
+interface ColouredCell extends GridCell {
+    background: PaletteColor;
+}
+interface SolverOptions {
+    rows: number;
+    cols: number;
+    seed: number;
+}
+declare function colourGrid({ rows, cols, seed }: SolverOptions): ColouredCell[];
+
+/**
+ * The geometric shape vocabulary — brand spec §5.1.
+ *
+ * Each shape is a pure SVG body function returning the inner markup for a
+ * single cell of size `cellSize`. The cell's background is rendered by the
+ * pattern composer; shapes draw on top in `shapeColor`.
+ */
+type ShapeName = "circle" | "circle-ring" | "square" | "square-inset" | "triangle" | "x" | "plus" | "quarter-disc" | "half-disc" | "flower" | "diamond";
+declare const SHAPES: readonly ShapeName[];
+interface RenderArgs {
+    /** Cell side in user units (the cell origin is at 0,0). */
+    size: number;
+    /** Fill / stroke colour for the shape. */
+    color: string;
+}
+/**
+ * Returns the inner SVG markup for the named shape, sized to `size`.
+ * Coordinates are local to the cell — the composer translates the result
+ * to its final grid position.
+ */
+declare function renderShape(name: ShapeName, args: RenderArgs): string;
+
+/**
+ * Auto-generated tile catalog. Do not edit by hand — run `pnpm gen:tiles`.
+ *
+ * Each entry maps a file in ./patterns/ to the data the generator needs:
+ *   - `background` — palette name of the tile's original background.
+ *   - `shapeColor` — palette name of the tile's original shape colour.
+ *   - `shapeMarkup` — the inner SVG (paths/circles/rects) with the original
+ *     background <rect> removed and every occurrence of the original shape
+ *     colour replaced by the placeholder `{{SHAPE_COLOR}}`. Renderers
+ *     substitute a contrast-aware palette colour at composition time.
+ *
+ * All tiles share the same 100×100 viewBox.
+ */
+
+interface Tile {
+    id: string;
+    background: PaletteColor;
+    shapeColor: PaletteColor;
+    shapeMarkup: string;
+}
+declare const TILE_VIEWBOX_SIZE = 100;
+declare const TILES: readonly Tile[];
+declare const TILE_BY_ID: Readonly<Record<string, Tile>>;
+
+/**
+ * Shape variants — the placement contexts brand spec §5.3 allows.
+ *
+ *   - `corner`       — square / rectangular cluster anchored at a corner.
+ *   - `edge-strip`   — vertical strip along one side (auth-page banner).
+ *   - `divider-strip`— horizontal strip between two sections.
+ *   - `dado-footer`  — the 8 px alternating row at the bottom of every page.
+ *   - `full-scene`   — 404 / empty-state illustration (left half of asymmetric 5/7).
+ */
+
+type PatternVariant = "corner" | "edge-strip" | "divider-strip" | "dado-footer" | "full-scene";
+type GridShape = `${number}x${number}`;
+
+/**
+ * Pattern SVG generator.
+ *
+ * Two render modes share the same adjacency-safe colour-graph backbone:
+ *
+ *   1. **Procedural shape mode** (default) — picks a shape from `SHAPES` per
+ *      cell and renders it via `renderShape()`. The historical behaviour.
+ *
+ *   2. **Tile mode** — when the caller supplies `base` (single id) or `pool`
+ *      (list of ids), every cell renders one of those tiles from the
+ *      auto-generated catalog (./tiles-catalog.ts, sourced from
+ *      ./patterns/*.svg). The tile's shape markup is recoloured to contrast
+ *      against the cell's assigned background.
+ *
+ * Output is deterministic by `(variant, grid, seed, cellSize, base | pool)`.
+ */
+
+interface PatternOptions {
+    variant: PatternVariant;
+    /** Override the default grid dimensions for the variant. */
+    grid?: GridShape;
+    /** Override the cell side in pixels. */
+    cellSize?: number;
+    /** Determinism seed. */
+    seed?: number;
+    /** Use raw hex (`#3a6dc5`) instead of CSS variables — useful when the SVG is exported. */
+    useHex?: boolean;
+    /**
+     * Render every cell from the named tile in ./patterns (e.g. `"p-1"`).
+     * The tile's shape is recoloured per-cell so it contrasts the adjacency-safe
+     * background the colour-graph picks.
+     */
+    base?: string;
+    /**
+     * Like `base` but the generator picks one of the listed tiles per cell.
+     * Ignored when `base` is also supplied.
+     */
+    pool?: readonly string[];
+}
+interface PatternCell extends ColouredCell {
+    shape: ShapeName | null;
+    shapeColor: string;
+    backgroundColor: string;
+    /** Set when the cell was rendered from a tile (tile mode). */
+    tile: Tile | null;
+    /** Inline SVG markup for the tile's shape, recoloured. Empty in procedural mode. */
+    tileMarkup: string;
+}
+interface PatternData {
+    cells: PatternCell[];
+    width: number;
+    height: number;
+    rows: number;
+    cols: number;
+    cellSize: number;
+    viewBox: string;
+    /** True when cells were rendered from the tile catalog. */
+    tileMode: boolean;
+    /** When `tileMode` is true, the tile viewBox edge length (always 100). */
+    tileViewBox: number;
+}
+declare function generatePatternData(options: PatternOptions): PatternData;
+/**
+ * Render the pattern to a standalone SVG string.
+ *
+ * Useful for the docs site's "Copy SVG" affordance — produces a paste-ready
+ * `<svg>` block with hex colours baked in (`useHex: true`) so the artwork
+ * renders without our CSS variables.
+ */
+declare function generatePatternSvg(options: PatternOptions): string;
+
+export { type ColouredCell as C, type GridShape as G, PALETTE as P, SHAPES as S, TILES as T, PALETTE_HEX as a, PALETTE_VAR as b, type PaletteColor as c, type PatternCell as d, type PatternData as e, type PatternOptions as f, type PatternVariant as g, type ShapeName as h, TILE_BY_ID as i, TILE_VIEWBOX_SIZE as j, type Tile as k, colourGrid as l, generatePatternData as m, generatePatternSvg as n, renderShape as r };

package/dist/generator-URuC3uDY.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The fixed 5-colour palette used by every pattern block.
+ *
+ * Brand spec §5.2: "Use all four brand colors plus white. Never substitute
+ * or omit one." The colours themselves come from spec §2.1.
+ */
+type PaletteColor = "blue" | "yellow" | "red" | "green" | "white";
+declare const PALETTE: readonly PaletteColor[];
+/** CSS-variable hooks so the palette switches with the active theme. */
+declare const PALETTE_VAR: Record<PaletteColor, string>;
+/** Hard-coded hex for stand-alone SVG (no CSS-var support). */
+declare const PALETTE_HEX: Record<PaletteColor, string>;
+
+/**
+ * Adjacency colour-graph solver.
+ *
+ * Brand spec §5.2: "No two adjacent cells share the same dominant color."
+ *
+ * Given a grid of cells (4-connected) and a palette of 5 colours, we want
+ * to assign every cell a background colour so no neighbour matches. With
+ * 5 colours on a rectangular grid this is always solvable — but we want
+ * the assignment to be *deterministic by seed* so the same `(grid, seed)`
+ * always renders identically.
+ *
+ * Algorithm: greedy with backtracking.
+ *   1. Visit cells in a seed-shuffled order.
+ *   2. Try each palette colour, also in seed-shuffled order.
+ *   3. Skip colours that match any already-assigned neighbour.
+ *   4. If no colour fits, backtrack to the previous cell and pick the next
+ *      candidate. With 5 colours and ≤ 4 neighbours, a fit is always
+ *      reachable from any prefix — we still cap recursion at `MAX_DEPTH`
+ *      to guard against pathological inputs.
+ */
+
+interface GridCell {
+    row: number;
+    col: number;
+}
+interface ColouredCell extends GridCell {
+    background: PaletteColor;
+}
+interface SolverOptions {
+    rows: number;
+    cols: number;
+    seed: number;
+}
+declare function colourGrid({ rows, cols, seed }: SolverOptions): ColouredCell[];
+
+/**
+ * The geometric shape vocabulary — brand spec §5.1.
+ *
+ * Each shape is a pure SVG body function returning the inner markup for a
+ * single cell of size `cellSize`. The cell's background is rendered by the
+ * pattern composer; shapes draw on top in `shapeColor`.
+ */
+type ShapeName = "circle" | "circle-ring" | "square" | "square-inset" | "triangle" | "x" | "plus" | "quarter-disc" | "half-disc" | "flower" | "diamond";
+declare const SHAPES: readonly ShapeName[];
+interface RenderArgs {
+    /** Cell side in user units (the cell origin is at 0,0). */
+    size: number;
+    /** Fill / stroke colour for the shape. */
+    color: string;
+}
+/**
+ * Returns the inner SVG markup for the named shape, sized to `size`.
+ * Coordinates are local to the cell — the composer translates the result
+ * to its final grid position.
+ */
+declare function renderShape(name: ShapeName, args: RenderArgs): string;
+
+/**
+ * Auto-generated tile catalog. Do not edit by hand — run `pnpm gen:tiles`.
+ *
+ * Each entry maps a file in ./patterns/ to the data the generator needs:
+ *   - `background` — palette name of the tile's original background.
+ *   - `shapeColor` — palette name of the tile's original shape colour.
+ *   - `shapeMarkup` — the inner SVG (paths/circles/rects) with the original
+ *     background <rect> removed and every occurrence of the original shape
+ *     colour replaced by the placeholder `{{SHAPE_COLOR}}`. Renderers
+ *     substitute a contrast-aware palette colour at composition time.
+ *
+ * All tiles share the same 100×100 viewBox.
+ */
+
+interface Tile {
+    id: string;
+    background: PaletteColor;
+    shapeColor: PaletteColor;
+    shapeMarkup: string;
+}
+declare const TILE_VIEWBOX_SIZE = 100;
+declare const TILES: readonly Tile[];
+declare const TILE_BY_ID: Readonly<Record<string, Tile>>;
+
+/**
+ * Shape variants — the placement contexts brand spec §5.3 allows.
+ *
+ *   - `corner`       — square / rectangular cluster anchored at a corner.
+ *   - `edge-strip`   — vertical strip along one side (auth-page banner).
+ *   - `divider-strip`— horizontal strip between two sections.
+ *   - `dado-footer`  — the 8 px alternating row at the bottom of every page.
+ *   - `full-scene`   — 404 / empty-state illustration (left half of asymmetric 5/7).
+ */
+
+type PatternVariant = "corner" | "edge-strip" | "divider-strip" | "dado-footer" | "full-scene";
+type GridShape = `${number}x${number}`;
+
+/**
+ * Pattern SVG generator.
+ *
+ * Two render modes share the same adjacency-safe colour-graph backbone:
+ *
+ *   1. **Procedural shape mode** (default) — picks a shape from `SHAPES` per
+ *      cell and renders it via `renderShape()`. The historical behaviour.
+ *
+ *   2. **Tile mode** — when the caller supplies `base` (single id) or `pool`
+ *      (list of ids), every cell renders one of those tiles from the
+ *      auto-generated catalog (./tiles-catalog.ts, sourced from
+ *      ./patterns/*.svg). The tile's shape markup is recoloured to contrast
+ *      against the cell's assigned background.
+ *
+ * Output is deterministic by `(variant, grid, seed, cellSize, base | pool)`.
+ */
+
+interface PatternOptions {
+    variant: PatternVariant;
+    /** Override the default grid dimensions for the variant. */
+    grid?: GridShape;
+    /** Override the cell side in pixels. */
+    cellSize?: number;
+    /** Determinism seed. */
+    seed?: number;
+    /** Use raw hex (`#3a6dc5`) instead of CSS variables — useful when the SVG is exported. */
+    useHex?: boolean;
+    /**
+     * Render every cell from the named tile in ./patterns (e.g. `"p-1"`).
+     * The tile's shape is recoloured per-cell so it contrasts the adjacency-safe
+     * background the colour-graph picks.
+     */
+    base?: string;
+    /**
+     * Like `base` but the generator picks one of the listed tiles per cell.
+     * Ignored when `base` is also supplied.
+     */
+    pool?: readonly string[];
+}
+interface PatternCell extends ColouredCell {
+    shape: ShapeName | null;
+    shapeColor: string;
+    backgroundColor: string;
+    /** Set when the cell was rendered from a tile (tile mode). */
+    tile: Tile | null;
+    /** Inline SVG markup for the tile's shape, recoloured. Empty in procedural mode. */
+    tileMarkup: string;
+}
+interface PatternData {
+    cells: PatternCell[];
+    width: number;
+    height: number;
+    rows: number;
+    cols: number;
+    cellSize: number;
+    viewBox: string;
+    /** True when cells were rendered from the tile catalog. */
+    tileMode: boolean;
+    /** When `tileMode` is true, the tile viewBox edge length (always 100). */
+    tileViewBox: number;
+}
+declare function generatePatternData(options: PatternOptions): PatternData;
+/**
+ * Render the pattern to a standalone SVG string.
+ *
+ * Useful for the docs site's "Copy SVG" affordance — produces a paste-ready
+ * `<svg>` block with hex colours baked in (`useHex: true`) so the artwork
+ * renders without our CSS variables.
+ */
+declare function generatePatternSvg(options: PatternOptions): string;
+
+export { type ColouredCell as C, type GridShape as G, PALETTE as P, SHAPES as S, TILES as T, PALETTE_HEX as a, PALETTE_VAR as b, type PaletteColor as c, type PatternCell as d, type PatternData as e, type PatternOptions as f, type PatternVariant as g, type ShapeName as h, TILE_BY_ID as i, TILE_VIEWBOX_SIZE as j, type Tile as k, colourGrid as l, generatePatternData as m, generatePatternSvg as n, renderShape as r };