Code Documentation: Grid Weaver By Mossawir Ahmed

A technical guide to the Grid Weaver application's architecture, core logic, and components.

← Back to Grid Weaver AppUser Documentation →
Introduction & Project Structure

Grid Weaver is a Next.js application built with React, TypeScript, ShadCN UI components, and Tailwind CSS. It uses Immer for immutable state management.

Key Folders:

  • /src/app: Next.js App Router pages (page.tsx, documentation/page.tsx, code-documentation/page.tsx). Global styles (globals.css) and layout (layout.tsx).
  • /src/components: Reusable React components. UI primitives in /ui, application-specific components otherwise.
  • /src/hooks: useGridGenerator.ts (core logic), use-toast.ts, use-mobile.ts.
  • /src/lib: Utility functions (utils.ts).
  • /src/types: TypeScript definitions (grid.ts).
Core Logic: useGridGenerator.ts
This hook manages all state and logic for grid configuration and code generation.

State Management (GridConfig):

  • rows, cols: Global grid dimensions (numbers).
  • Base (Desktop) Container Styles: rowGapValue, rowGapUnit, colGapValue, colGapUnit, justifyItems, alignItems.
  • responsiveContainerStyles: Optional object storing Partial<ContainerStyleProperties> for 'tablet' and 'mobile' overrides for container gaps and alignments.
  • items: Array of GridItemConfig objects. Each stores its base (desktop) layout and optionally, responsiveLayouts for tablet and mobile item-specific layout overrides.
  • nextItemId, selectedItemId, activeBreakpoint.

Key Functions & Their Roles:

  • setActiveBreakpoint(breakpoint): Switches editing context.
  • getEffectiveLayout(item, breakpoint): Computes item layout by layering base + responsive overrides.
  • getEffectiveContainerStyles(breakpoint): Computes container styles (gaps, alignments) by layering base + responsive overrides.
  • currentDisplayItems / currentEffectiveContainerStyles (Memoized): Provide data for the active breakpoint to UI components.
  • Setters for Global Config (Rows/Cols): setRows, setCols adjust item boundaries if needed.
  • Setters for Container Styles: setRowGapValue, setColGapUnit, setJustifyItems, etc. These update base (Desktop) styles or responsive overrides in responsiveContainerStyles based on activeBreakpoint. They prune overrides if they match the inherited value.
  • Item Management: addGridItem, updateGridItem (handles base item properties or responsive layout overrides), removeGridItem (deletes item or clears breakpoint layout).
  • clearGridItemsAndContainerStyles(): Contextual. Clears all desktop items & resets desktop container styles, or clears responsive overrides (items & container) for tablet/mobile.

Code Generation:

  • generatedCss (Memoized):
    • .grid-container styles (base from Desktop effective styles).
    • Base styles for each item class (from Desktop effective layout).
    • @media (max-width: 990px): Includes CSS for container style overrides (if different from Desktop) and item layout overrides (if different from Desktop).
    • @media (max-width: 767px): Similar for Mobile, comparing against effective Tablet styles.
  • generatedHtml (Memoized): Simple HTML with .grid-container and item divs with classes and inline background colors.
  • generatedTailwindMarkup (Memoized):
    • Container div gets responsive Tailwind classes for grid definition, gaps, justify-items, and align-items (mobile-first, with md: and lg: prefixes for differences).
    • Item divs get responsive Tailwind classes for position, span, and self-alignment (mobile-first with md:, lg: prefixes).
UI Components & Responsibilities
  • GridWeaverApp.tsx: Main app component, initializes hook, passes state/callbacks. Manages "Clear" button logic.
  • GridPreview.tsx: Renders interactive grid. Uses effective container styles for gaps. Handles item creation, selection, resizing.
  • GridControls.tsx: Inputs for grid parameters. Receives effective container styles for the active breakpoint. Calls setters from hook.
  • ItemControls.tsx: Inputs for selected item properties. Edits are contextual to activeBreakpoint.
  • ResponsiveControls.tsx: Buttons to switch activeBreakpoint.
  • Output Components: CssOutput, HtmlOutput, TailwindMarkupOutput display generated code.
Data Structures (src/types/grid.ts)
  • ContainerStyleProperties: Defines shape for rowGapValue, rowGapUnit, colGapValue, colGapUnit, justifyItems, alignItems.
  • GridConfig: Main state object. Holds global rows/cols, base (Desktop) container styles, and responsiveContainerStyles for tablet/mobile overrides. Also holds items array.
  • GridItemConfig: Core item interface. Includes base layout properties and responsiveLayouts for 'tablet'/'mobile' item overrides.
  • Other types: GridUnits, SelfAlignment, ItemLayoutProperties, BreakpointKey.
Responsive Design Implementation Flow

The responsive design uses a "Desktop-first, with overrides" model for both container styles and item layouts:

  1. Base Configuration (Desktop): Global rows/columns are set. Base container styles (gaps, alignments) and base item layouts/properties are defined here.
  2. Tablet Overrides: When in Tablet view:
    • Container styles (gaps, alignments) modified via GridControls are saved into gridConfig.responsiveContainerStyles.tablet.
    • Item layout modifications are saved into item.responsiveLayouts.tablet.
    • Only differing properties are stored as overrides.
  3. Mobile Overrides: Similar to tablet, for Mobile view. Overrides are stored in responsiveContainerStyles.mobile and item.responsiveLayouts.mobile.
  4. Effective Styles Calculation: getEffectiveContainerStyles and getEffectiveLayout compute the actual styles for any breakpoint by applying the hierarchy: Desktop -> Tablet Overrides -> Mobile Overrides.
  5. Code Generation: CSS and Tailwind reflect this hierarchy, generating base styles and then breakpoint-specific overrides (e.g., via media queries or md:/lg: prefixes).
Event Handling in GridPreview.tsx

Uses pointer events for item creation (Desktop only), selection, and resizing (with live snapping preview via resizePreviewLayout state).

Styling Approach
  • Tailwind CSS for layout and utility styling.
  • ShadCN UI for pre-built components.
  • globals.css for theme CSS variables.