# thekeydev/gridpack architecture

> Architecture diagram of the GitHub repository thekeydev/gridpack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thekeydev/gridpack
- Repository: https://github.com/thekeydev/gridpack

## Overview

1. **What this repo is**
   - `gridpack` is a small React-oriented layout engine: it turns a single layout string into CSS Grid or Flexbox output.
   - The architectural center is a DSL compiler plus a rendering component, not a page framework or a state-heavy app.

2. **Top-level split: library vs. demo**
   - `src/` contains the publishable library code.
   - `demo/` is a self-contained documentation/playground app used to explain and exercise the DSL.
   - `build.mjs` appears to handle packaging/bundling for distribution and demo output.

3. **Public API boundary**
   - `src/index.js` is the main export surface for consumers.
   - The README shows the intended API shape: `Grid`, `Flex`, and `Layout`, plus extension helpers like `splitPane`, `scrollable`, `debug`, etc.
   - The package is designed so consumers mostly interact through one prop, `layout`, plus optional `vars`, `extensions`, and responsive breakpoints.

4. **Core DSL/compiler subsystem**
   - `src/grid-layout-dsl.js` is the core parser/compiler layer.
   - It takes the layout string grammar described in the README and turns it into a structured representation: map rows, legend/areas, sizes, flags, gaps, overlaps, and variable substitutions.
   - This layer is the main non-React boundary: it is responsible for interpreting syntax, not rendering DOM.

5. **Rendering subsystem**
   - `src/Grid.jsx` is the main React renderer.
   - It consumes the parsed layout output and emits the container plus one wrapper per child/area.
   - It also selects between rendering modes (`grid`, `flex`, or `auto`) and applies the derived CSS styles to the container and cells.

6. **Mode switching and layout behavior**
   - The library is built around two rendering models that share the same DSL:
     - **Grid mode** for explicit track/area layouts.
     - **Flex mode** for content-negotiated rows/columns and wrapping behavior.
   - `Layout` is the abstraction that can choose the mode automatically, while `Grid` and `Flex` are more direct entry points.

7. **Extension system as a plugin boundary**
   - Extensions are first-class behavioral plugins, not just helpers.
   - They can transform variables and parsed areas, inject DOM, wrap cells, override container rendering, and alter computed styles.
   - This makes the architecture intentionally layered: parsing stays generic, while behavior like split panes, tabs, masonry, overlays, and scroll handling is added outside the core parser.

8. **Data flow from prop to DOM**
   - The typical flow is: layout string and vars → DSL parse/transform → derived grid/flex model → container style + cell wrappers → rendered children.
   - Responsive props (`xs`/`sm`/`md`/`lg`/`xl`, plus custom `breaks`) swap in complete layout strings before rendering, so responsiveness is handled at the layout-definition level rather than by separate CSS files.

9. **Variable and annotation model**
   - The DSL supports `{var}` placeholders and floating `letter(mods)` annotations.
   - Those annotations feed the same parser output used by rendering and extensions, so metadata such as classes, aliases, z-index, or flex-basis is part of the layout description rather than external styling.

10. **Demo/documentation app**
   - `demo/` is a rich interactive documentation environment, not just a static example page.
   - Files like `Playground.jsx`, `Guide`, `Reference`, `LandingPage`, and the `presets/` directory suggest the demo is organized around live examples, curated layouts, and docs sections.
   - `demo/index.html`, `demo/index.jsx`, and `demo/index.js` indicate a bundled client app that mounts the docs/playground UI.

11. **Preset and URL-driven examples**
   - `demo/presets/` holds reusable example layouts that power the playground and docs.
   - `demo/urldsl.js` implies the demo can encode/decode DSL state in the URL, so examples are shareable and deep-linkable.
   - This makes the demo architecture stateful around example selection and layout source, but the state remains presentation-oriented.

12. **Testing boundary**
   - `src/grid-layout-dsl.test.mjs` is a focused test file for the parser/compiler layer.
   - That placement suggests the highest-risk logic is the DSL interpretation itself, and it is tested separately from the React rendering and demo UI.

13. **How to draw the architecture**
   - The clean diagram is: **consumer React app** → **gridpack public API** → **DSL parser/compiler** → **Grid/Flex renderer** → **DOM/CSS output**.
   - Off to the side sits the **extension pipeline**, which can intercept parsed data and rendering.
   - Separately, the **demo app** consumes the same library to provide docs, playgrounds, and presets.

Main entry points: [`src/index.js`](https://github.com/thekeydev/gridpack/blob/main/src/index.js) (Public API), [`src/Grid.jsx`](https://github.com/thekeydev/gridpack/blob/main/src/Grid.jsx) (Grid renderer), [`demo/index.jsx`](https://github.com/thekeydev/gridpack/blob/main/demo/index.jsx) (Demo app), [`demo/Playground.jsx`](https://github.com/thekeydev/gridpack/blob/main/demo/Playground.jsx) (Playground)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_public_api["Public API<br/>entrypoint<br/>[index.js]"]
  node_dsl["DSL parser<br/>compiler<br/>[grid-layout-dsl.js]"]
  node_renderer["Grid renderer<br/>React component<br/>[Grid.jsx]"]
  node_grid_mode{{"Grid mode<br/>layout mode"}}
  node_flex_mode{{"Flex mode<br/>layout mode"}}
  node_extensions(("Extensions<br/>plugin layer"))
  node_responsive["Responsive props<br/>layout switching"]
end

subgraph group_demo["Demo"]
  node_demo_app["Demo app<br/>documentation app<br/>[index.jsx]"]
  node_demo_boot["Demo boot<br/>client entry<br/>[index.js]"]
  node_docs["Docs pages<br/>docs ui<br/>[Docs.jsx]"]
  node_playground["Playground<br/>interactive editor<br/>[Playground.jsx]"]
  node_presets["Presets<br/>examples<br/>[grid-basics.jsx]"]
  node_url_dsl["URL DSL<br/>state sync<br/>[urldsl.js]"]
end

subgraph group_tooling["Tooling"]
  node_build["Build<br/>packaging<br/>[build.mjs]"]
end

node_consumer(("Consumer app<br/>React app"))
node_rendered_dom[("DOM/CSS output")]

node_consumer -->|"imports"| node_public_api
node_public_api -->|"parses"| node_dsl
node_public_api -->|"exports"| node_renderer
node_public_api -->|"exposes"| node_extensions
node_responsive -->|"feeds"| node_public_api
node_dsl -->|"model"| node_renderer
node_renderer -->|"selects"| node_grid_mode
node_renderer -->|"selects"| node_flex_mode
node_extensions -.->|"transforms"| node_dsl
node_extensions -.->|"hooks"| node_renderer
node_grid_mode -->|"emits"| node_rendered_dom
node_flex_mode -->|"emits"| node_rendered_dom
node_public_api -->|"renders"| node_rendered_dom
node_demo_app -->|"mounts"| node_demo_boot
node_demo_app -->|"contains"| node_docs
node_demo_app -->|"contains"| node_playground
node_playground -->|"uses"| node_presets
node_playground -->|"syncs"| node_url_dsl
node_docs -->|"demonstrates"| node_public_api
node_build -->|"packages"| node_public_api
node_build -->|"bundles"| node_demo_app

click node_public_api "https://github.com/thekeydev/gridpack/blob/main/src/index.js"
click node_dsl "https://github.com/thekeydev/gridpack/blob/main/src/grid-layout-dsl.js"
click node_renderer "https://github.com/thekeydev/gridpack/blob/main/src/Grid.jsx"
click node_demo_app "https://github.com/thekeydev/gridpack/blob/main/demo/index.jsx"
click node_demo_boot "https://github.com/thekeydev/gridpack/blob/main/demo/index.js"
click node_docs "https://github.com/thekeydev/gridpack/blob/main/demo/Docs.jsx"
click node_playground "https://github.com/thekeydev/gridpack/blob/main/demo/Playground.jsx"
click node_presets "https://github.com/thekeydev/gridpack/blob/main/demo/presets/grid-basics.jsx"
click node_url_dsl "https://github.com/thekeydev/gridpack/blob/main/demo/urldsl.js"
click node_build "https://github.com/thekeydev/gridpack/blob/main/build.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_dsl,node_renderer,node_grid_mode,node_flex_mode,node_extensions,node_responsive toneBlue
class node_demo_app,node_demo_boot,node_docs,node_playground,node_presets,node_url_dsl toneAmber
class node_build toneMint
class node_consumer,node_rendered_dom toneNeutral
```

## Components

### Library

Publishable React layout engine and parser/compiler.

- [Public API](https://github.com/thekeydev/gridpack/blob/main/src/index.js): entrypoint · Main export surface for Grid, Flex, and Layout. · `src/index.js`
- [DSL parser](https://github.com/thekeydev/gridpack/blob/main/src/grid-layout-dsl.js): compiler · Parses layout strings, variables, annotations, sizes, and flags. · `src/grid-layout-dsl.js`
- [Grid renderer](https://github.com/thekeydev/gridpack/blob/main/src/Grid.jsx): React component · Builds container and cell wrappers, choosing grid or flex behavior. · `src/Grid.jsx`
- **Grid mode**: layout mode · Explicit track and area-based rendering.
- **Flex mode**: layout mode · Content-negotiated rows, columns, and wrapping.
- **Extensions**: plugin layer · Transforms variables, parsed areas, wrappers, DOM, and styles.
- **Responsive props**: layout switching · Selects alternate layouts by breakpoint before render.

### Demo

Interactive documentation and playground app.

- [Demo app](https://github.com/thekeydev/gridpack/blob/main/demo/index.jsx): documentation app · Bundled playground and docs experience for the library. · `demo/index.jsx`
- [Demo boot](https://github.com/thekeydev/gridpack/blob/main/demo/index.js): client entry · Browser mount and bundle entry for the demo. · `demo/index.js`
- [Docs pages](https://github.com/thekeydev/gridpack/blob/main/demo/Docs.jsx): docs ui · Guide, reference, landing, and example sections. · `demo/Docs.jsx`
- [Playground](https://github.com/thekeydev/gridpack/blob/main/demo/Playground.jsx): interactive editor · Live layout editor used to exercise the DSL. · `demo/Playground.jsx`
- [Presets](https://github.com/thekeydev/gridpack/blob/main/demo/presets/grid-basics.jsx): examples · Reusable example layouts for docs and playground. · `demo/presets/grid-basics.jsx`
- [URL DSL](https://github.com/thekeydev/gridpack/blob/main/demo/urldsl.js): state sync · Encodes and decodes example state in the URL. · `demo/urldsl.js`

### Tooling

Build and packaging entrypoints.

- [Build](https://github.com/thekeydev/gridpack/blob/main/build.mjs): packaging · Bundles library and demo for distribution. · `build.mjs`

### Other components

- **Consumer app**: React app · Host application that uses gridpack layouts.
- **DOM/CSS output**: output · Final container styles and rendered children.

## Connections

- Consumer app → Public API: imports · Application code consumes the package entry surface.
- Public API → DSL parser: parses · Exports the DSL compiler and layout-facing helpers.
- Public API → Grid renderer: exports · Re-exports the rendering components and mode abstractions.
- Public API → Extensions: exposes · Makes extension helpers available to consumers.
- Responsive props → Public API: feeds · Breakpoint-specific layout strings are resolved before render.
- DSL parser → Grid renderer: model · Parsed layout data becomes render-ready structure.
- Grid renderer → Grid mode: selects · Uses explicit grid rendering when layout demands it.
- Grid renderer → Flex mode: selects · Uses flex rendering when content flow is preferred.
- Extensions → DSL parser: transforms · Plugins can adjust variables and parsed areas.
- Extensions → Grid renderer: hooks · Plugins can wrap cells, inject DOM, or override styles.
- Grid mode → DOM/CSS output: emits · Produces final grid container and cell output.
- Flex mode → DOM/CSS output: emits · Produces final flex container and cell output.
- Public API → DOM/CSS output: renders · Public components culminate in DOM/CSS output.
- Demo app → Demo boot: mounts · The demo app is bootstrapped by the browser entry.
- Demo app → Docs pages: contains · Docs and landing content are part of the demo experience.
- Demo app → Playground: contains · Interactive playground is a major demo surface.
- Playground → Presets: uses · Preset layouts seed the playground and examples.
- Playground → URL DSL: syncs · Example state is encoded into the URL.
- Docs pages → Public API: demonstrates · Docs showcase the library API and layout modes.
- Build → Public API: packages · Build tooling bundles the publishable library.
- Build → Demo app: bundles · Build tooling also produces the demo output.
