update readme and layout grid logic

Author: CFsylvester

README.md

@@ -34,8 +34,9 @@
 - [Scripts](#scripts)
 - [Grid Overlay Toggle](#grid-overlay-toggle)
   - [Breakpoints Configuration](#breakpoints-configuration)
+  - [Layout Root (Dynamic SCSS Variables)](#layout-root-dynamic-scss-variables)
   - [Grid Calculations](#grid-calculations)
-  - [Grid Layout (SCSS Variables)](#grid-layout-scss-variables)
+  - [Layout SCSS](#layout-scss)
   - [Grid Overlay SCSS](#grid-overlay-scss)
   - [Component Structure](#component-structure)
   - [GridOverlayToggle Component](#gridoverlaytoggle-component)
@@ -219,37 +220,7 @@ The grid system uses the following breakpoints (defined in `tailwind.config.cjs`
 }
 ```
 
-### Grid Calculations
-
-With a hardcoded variable of `--layout-gap: theme('spacing.4')` (16px), the grid remains fully responsive and divisible by multiples of 2.
-
-- **Responsive Columns & Padding:**
-
-  - **xs** (`320px`): `--layout-cols: 4;` / `--layout-padding: theme('spacing.4')` (16px)
-  - **sm** (`480px`): `--layout-cols: 4;` / `--layout-padding: theme('spacing.4')` (16px)
-  - **md** (`592px`): `--layout-cols: 6;` / `--layout-padding: theme('spacing.6')` (24px)
-  - **lg** (`784px`): `--layout-cols: 8;` / `--layout-padding: theme('spacing.8')` (32px)
-  - **xl** (`976px`): `--layout-cols: 10;` / `--layout-padding: theme('spacing.10')` (40px)
-  - **2xl** (`1168px`): `--layout-cols: 12;` / `--layout-padding: theme('spacing.12')` (48px)
-  - **3xl** (`1360px`): `--layout-cols: 14;` / `--layout-padding: theme('spacing.14')` (56px)
-  - **4xl** (`1552px`): `--layout-cols: 16;` / `--layout-padding: theme('spacing.16')` (64px)
-
-- **Clamp Layout Column Width:**
-
-```scss
---layout-col-width: clamp(
-  60px,
-  calc(
-    (100vw - (2 * var(--layout-padding)) - ((var(--layout-cols) - 1) * var(--layout-gap))) /
-      var(--layout-cols)
-  ),
-  124px
-);
-```
-
-This expression dynamically adjusts the column width based on the current `--layout-padding` and `--layout-cols` values at each breakpoint.
-
-### Grid Layout (SCSS Variables)
+### Layout Root (Dynamic SCSS Variables)
 
 The grid system relies on dynamic scss variables updated at the above breakpoints to coincide with a responsive layout that is always divisible by multiples of 2. These dynamic, responsive, variables are used in both the `.layout` and `[data-grid-overlay]` scss selectors.
 
@@ -304,11 +275,39 @@ The grid system relies on dynamic scss variables updated at the above breakpoint
 }
 ```
 
-### Grid Overlay SCSS
+### Grid Calculations
 
-A purely css driven grid overlay that coincides with the layout class and it's breakpoints. When the data-overlay-grid is set to active, the grid overlay fades into visibility.
+With a hardcoded variable of `--layout-gap: theme('spacing.4')` (16px), the grid remains fully responsive and divisible by multiples of 2.
 
-- **Layout**
+- **Responsive Columns & Padding:**
+
+  - **xs** (`320px`): `--layout-cols: 4;` / `--layout-padding: theme('spacing.4')` (16px)
+  - **sm** (`480px`): `--layout-cols: 4;` / `--layout-padding: theme('spacing.4')` (16px)
+  - **md** (`592px`): `--layout-cols: 6;` / `--layout-padding: theme('spacing.6')` (24px)
+  - **lg** (`784px`): `--layout-cols: 8;` / `--layout-padding: theme('spacing.8')` (32px)
+  - **xl** (`976px`): `--layout-cols: 10;` / `--layout-padding: theme('spacing.10')` (40px)
+  - **2xl** (`1168px`): `--layout-cols: 12;` / `--layout-padding: theme('spacing.12')` (48px)
+  - **3xl** (`1360px`): `--layout-cols: 14;` / `--layout-padding: theme('spacing.14')` (56px)
+  - **4xl** (`1552px`): `--layout-cols: 16;` / `--layout-padding: theme('spacing.16')` (64px)
+
+- **Clamp Layout Column Width:**
+
+```scss
+--layout-col-width: clamp(
+  60px,
+  calc(
+    (100vw - (2 * var(--layout-padding)) - ((var(--layout-cols) - 1) * var(--layout-gap))) /
+      var(--layout-cols)
+  ),
+  124px
+);
+```
+
+This expression dynamically adjusts the column width based on the current `--layout-padding` and `--layout-cols` values at each breakpoint.
+
+### Layout SCSS
+
+A responsive grid container that adapts to the dynamic variables defined in the layout.scss `:root`. It is utilized on the main element in the server rendered `layout.tsx` found in the app directory.
 
 ```scss
 .layout {
@@ -330,36 +329,44 @@ A purely css driven grid overlay that coincides with the layout class and it's b
       @apply my-auto;
     }
   }
+
+  //... &[data-grid-overlay] logic below
 }
 ```
 
-- **[Data-Grid-Overlay]**
-
-```scss
-[data-grid-overlay] {
-  @apply mx-auto bg-repeat-x z-10;
+### Grid Overlay SCSS
 
-  width: calc(
-    var(--layout-cols) * var(--layout-col-width) + (var(--layout-cols) - 1) * var(--layout-gap)
-  );
+A purely css driven grid overlay that coincides with the layout class and it's breakpoints. When the data-overlay-grid is set to active, the grid overlay fades into visibility. It is dependent on being used on the same element as the `.layout` class. This is utilized on the main element in the server rendered `layout.tsx` found in the app directory.
 
-  background-image: repeating-linear-gradient(
-    to right,
-    rgba(255, 0, 0, 0.2) 0,
-    rgba(255, 0, 0, 0.2) var(--layout-col-width),
-    transparent var(--layout-col-width),
-    transparent calc(var(--layout-col-width) + var(--layout-gap))
-  );
-  background-size: calc(var(--layout-col-width) + var(--layout-gap)) 100%;
-  opacity: 0;
-  visibility: hidden;
-  transition:
-    opacity 0.3s ease-in-out,
-    visibility 0.3s ease-in-out;
-
-  &[data-grid-overlay='active'] {
-    opacity: 1;
-    visibility: visible;
+```scss
+.layout {
+  // ...layout logic above
+
+  &[data-grid-overlay] {
+    @apply mx-auto bg-repeat-x z-10;
+
+    width: calc(
+      var(--layout-cols) * var(--layout-col-width) + (var(--layout-cols) - 1) * var(--layout-gap)
+    );
+
+    background-image: repeating-linear-gradient(
+      to right,
+      rgba(255, 0, 0, 0.2) 0,
+      rgba(255, 0, 0, 0.2) var(--layout-col-width),
+      transparent var(--layout-col-width),
+      transparent calc(var(--layout-col-width) + var(--layout-gap))
+    );
+    background-size: calc(var(--layout-col-width) + var(--layout-gap)) 100%;
+    opacity: 0;
+    visibility: hidden;
+    transition:
+      opacity 0.3s ease-in-out,
+      visibility 0.3s ease-in-out;
+
+    &[data-grid-overlay='active'] {
+      opacity: 1;
+      visibility: visible;
+    }
   }
 }
 ```
@@ -372,35 +379,35 @@ A purely css driven grid overlay that coincides with the layout class and it's b
   - Displays the active breakpoint label
   - Shows a grid icon with an active/inactive state
 
-- **GridOverlay**: A purely CSS-driven overlay that:
+- **[data-grid-overlay]**: A purely CSS-driven overlay that:
   - Uses CSS variables (`--layout-cols`, `--layout-col-width`, `--layout-gap`, etc.) to match the current layout
   - Renders semi‑transparent columns across the viewport
-  - Transitions in/out when `data-grid-overlay="active"`
+  - Transitions in/out when `data-grid-overlay="active"` is set by the GridOverlayToggle
 
 ### GridOverlayToggle Component
 
 A client side button that triggers the css overlay grid. Updates the main element data-grid-overlay with the active state.
 
 ```tsx
 const [active, setActive] = useState(false);
-const mainRef = useRef<HTMLElement | null>(null);
+const overlayRef = useRef<HTMLElement | null>(null);
 
-// Grab <main> once on mount
+// Grab the element with [data-grid-overlay] once on mount
 useEffect(() => {
-  mainRef.current = document.querySelector('main');
+  overlayRef.current = document.querySelector('[data-grid-overlay]');
 }, []);
 
-// Update data-grid-overlay on <main> when `active` changes
+// Update the attribute whenever `active` changes
 useEffect(() => {
-  if (mainRef.current) {
-    mainRef.current.setAttribute('data-grid-overlay', active ? 'active' : '');
+  if (overlayRef.current) {
+    overlayRef.current.setAttribute('data-grid-overlay', active ? 'active' : '');
   }
 }, [active]);
 ```
 
 ### Implementation
 
-Add the grid system to your server render layout:
+Add the grid system to your server render layout found in `layout.tsx` within the app directory:
 
 ```tsx
 <body>

src/components/GridOverlayToggle/index.tsx

@@ -16,17 +16,17 @@ const breakpoints = [
 
 const GridOverlayToggle: React.FC = () => {
   const [active, setActive] = useState(false);
-  const mainRef = useRef<HTMLElement | null>(null);
+  const overlayRef = useRef<HTMLElement | null>(null);
 
-  // Get main element reference once on mount
+  // Grab the element with [data-grid-overlay] once on mount
   useEffect(() => {
-    mainRef.current = document.querySelector('main');
+    overlayRef.current = document.querySelector('[data-grid-overlay]');
   }, []);
 
-  // Toggle grid overlay
+  // Update the attribute whenever `active` changes
   useEffect(() => {
-    if (mainRef.current) {
-      mainRef.current.setAttribute('data-grid-overlay', active ? 'active' : '');
+    if (overlayRef.current) {
+      overlayRef.current.setAttribute('data-grid-overlay', active ? 'active' : '');
     }
   }, [active]);
 

src/styles/utilities/layout.scss

@@ -69,31 +69,31 @@
       @apply my-auto;
     }
   }
-}
-
-[data-grid-overlay] {
-  @apply mx-auto bg-repeat-x z-10;
-
-  width: calc(
-    var(--layout-cols) * var(--layout-col-width) + (var(--layout-cols) - 1) * var(--layout-gap)
-  );
 
-  background-image: repeating-linear-gradient(
-    to right,
-    rgba(255, 0, 0, 0.2) 0,
-    rgba(255, 0, 0, 0.2) var(--layout-col-width),
-    transparent var(--layout-col-width),
-    transparent calc(var(--layout-col-width) + var(--layout-gap))
-  );
-  background-size: calc(var(--layout-col-width) + var(--layout-gap)) 100%;
-  opacity: 0;
-  visibility: hidden;
-  transition:
-    opacity 0.3s ease-in-out,
-    visibility 0.3s ease-in-out;
-
-  &[data-grid-overlay='active'] {
-    opacity: 1;
-    visibility: visible;
+  &[data-grid-overlay] {
+    @apply mx-auto bg-repeat-x z-10;
+
+    width: calc(
+      var(--layout-cols) * var(--layout-col-width) + (var(--layout-cols) - 1) * var(--layout-gap)
+    );
+
+    background-image: repeating-linear-gradient(
+      to right,
+      rgba(255, 0, 0, 0.2) 0,
+      rgba(255, 0, 0, 0.2) var(--layout-col-width),
+      transparent var(--layout-col-width),
+      transparent calc(var(--layout-col-width) + var(--layout-gap))
+    );
+    background-size: calc(var(--layout-col-width) + var(--layout-gap)) 100%;
+    opacity: 0;
+    visibility: hidden;
+    transition:
+      opacity 0.3s ease-in-out,
+      visibility 0.3s ease-in-out;
+
+    &[data-grid-overlay='active'] {
+      opacity: 1;
+      visibility: visible;
+    }
   }
 }