How thekeydev/gridpack works
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: index.js Public API · Grid.jsx Grid renderer · index.jsx Demo app · Playground.jsx Playground
Components 16
Library
Publishable React layout engine and parser/compiler.
- Public API · Main export surface for Grid, Flex, and Layout.
src/index.js - DSL parser · Parses layout strings, variables, annotations, sizes, and flags.
src/grid-layout-dsl.js - Grid renderer · Builds container and cell wrappers, choosing grid or flex behavior.
src/Grid.jsx - Grid mode · Explicit track and area-based rendering.
- Flex mode · Content-negotiated rows, columns, and wrapping.
- Extensions · Transforms variables, parsed areas, wrappers, DOM, and styles.
- Responsive props · Selects alternate layouts by breakpoint before render.
Demo
Interactive documentation and playground app.
- Demo app · Bundled playground and docs experience for the library.
demo/index.jsx - Demo boot · Browser mount and bundle entry for the demo.
demo/index.js - Docs pages · Guide, reference, landing, and example sections.
demo/Docs.jsx - Playground · Live layout editor used to exercise the DSL.
demo/Playground.jsx - Presets · Reusable example layouts for docs and playground.
demo/presets/grid-basics.jsx - URL DSL · Encodes and decodes example state in the URL.
demo/urldsl.js
Other components
- Consumer app · Host application that uses gridpack layouts.
- DOM/CSS output · Final container styles and rendered children.
Connections 21
- 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.