Astro Helpers

1. Build-Time vs Runtime State Mismatch

SSG sites generate HTML at build time, but user preferences (like sidebar collapsed state or theme) only exist at runtime. This creates an unavoidable gap between what's built and what the user expects to see.

2. No Server-Side Rendering for User Preferences

Unlike SSR frameworks that can read cookies server-side and render personalized HTML, SSG sites serve the same static HTML to everyone. User-specific state can only be applied client-side after the page loads.

3. Performance Goals Conflict with Dynamic State

SSG sites are optimized for instant first paint with minimal JavaScript. But this means dynamic state management loads later, creating visible transitions between the initial static render and the hydrated interactive version.

4. CDN Caching Amplifies the Problem

SSG sites are typically served from CDNs with aggressive caching. This means the static HTML loads incredibly fast, making any FOUC even more noticeable compared to slower SSR responses where rendering delays mask the transition.

getInlineStorageScript

Generates a blocking script that reads a value from cookies or localStorage and sets it as a data attribute on the HTML element.

import { getInlineStorageScript } from '@sofondo/react';

const script = getInlineStorageScript('sidebar:collapsed', 'auto');
// Reads the 'sidebar:collapsed' cookie/localStorage
// and sets data-sidebar-collapsed attribute

getActiveStateScript & getActiveStateCSS

These helpers work together to prevent flash of active navigation states. The script determines which menu item is active based on the current URL, and the CSS styles it appropriately.

Critical: These helpers implement the three important fixes documented below to handle CSS Module scoping, header/sidebar conflicts, and submenu items.

import {
  getActiveStateScript,
  getActiveStateCSS
} from '@sofondo/react';

const sections = [{ id: 'docs', href: '/docs' }];
const menuItems = [
  { href: '/docs', exact: true },
  { href: '/docs/components' }
];

const script = getActiveStateScript(sections, menuItems);
const css = getActiveStateCSS(sections, menuItems);
// Sets data-active-section and data-active-path on HTML element

getMenuExpansionScript & getMenuExpansionCSS

Generates scripts and CSS for multiple collapsible menu sections to prevent flash of incorrect expanded/collapsed states.

import {
  getMenuExpansionScript,
  getMenuExpansionCSS
} from '@sofondo/react';

const menuLabels = ['Examples', 'Components'];
const script = getMenuExpansionScript(menuLabels, 'auto');
const css = getMenuExpansionCSS(menuLabels);
// Sets data-menu-expanded-examples and
// data-menu-expanded-components attributes

Fix #1: Header Selector Scoping

Problem: The active section CSS selector was matching BOTH header AND sidebar navigation, causing the sidebar to display incorrect active states.

// This matches ANY <nav> element, including sidebar!
html[data-active-section="docs"] nav a[href="/docs"] {
  background: var(--accent-primary);
  color: white;
  font-weight: 600;
}

// Properly scoped to header > nav only
html[data-active-section="docs"] header nav a[href="/docs"] {
  background: var(--accent-primary);
  color: white;
  font-weight: 600;
}

Implementation: In packages/react/src/utils/sidebarStorage.ts:384, the selector was updated to include header to prevent matching sidebar elements.

Fix #2: CSS Module Scoping with Attribute Selectors

Problem: CSS Modules generate scoped class names like ._link_cizzh_47 at build time. Inline CSS cannot reference these dynamic class names, causing active states to not apply.

// CSS Module class names are unknown at SSR time
html[data-active-path="/docs"] aside nav .link {
  color: var(--text-primary);  // Won't match!
}

html[data-active-path="/docs"] aside nav .link::before {
  background: rgba(66, 133, 244, 0.1);  // Won't match!
}

// Use href attribute selector instead of class names
html[data-active-path="/docs"] aside nav a[href="/docs"] {
  color: var(--text-primary);
  font-weight: 500;
}

html[data-active-path="/docs"] aside nav a[href="/docs"]::before {
  background: rgba(66, 133, 244, 0.1);
}

html[data-active-path="/docs"] aside nav a[href="/docs"]::after {
  content: '';
  position: absolute;
  left: -12px;
  top: 12px;
  width: 3px;
  height: 20px;
  background: var(--accent-primary);
  border-radius: 0 4px 4px 0;
}

Key Insight: Instead of trying to match CSS Module class names, we match the href attribute which is stable and known at render time.

Implementation: In packages/react/src/utils/sidebarStorage.ts:394-410, all CSS selectors were updated from .className to a[href="..."].

Fix #3: Missing Submenu CSS Generation

Problem: The getActiveStateCSS function only generated CSS for top-level menu items, not for nested submenu children. This caused submenu items like "Examples › Toast" to flash without proper active states.

export function getActiveStateCSS(sections, menuItems) {
  // Only processes top-level items
  const css = menuItems
    .filter(item => item.href)  // Skips items with children!
    .map(item => `
html[data-active-path="${item.href}"] aside nav a[href="${item.href}"] {
  color: var(--text-primary);
}
    `)
    .join('\n');

  return css;
}

export function getActiveStateCSS(sections, menuItems) {
  // First, generate CSS for top-level items
  const topLevelCSS = menuItems
    .filter(item => item.href)
    .map(item => `/* CSS for item */`)
    .join('\n');

  // Then, generate CSS for ALL submenu children
  const submenuCSS = menuItems
    .filter(item => item.children && item.children.length > 0)
    .flatMap(parent => parent.children!)  // Flatten all children
    .filter(child => child.href)  // Only children with hrefs
    .map(child => `
html[data-active-path="${child.href}"] aside nav a[href="${child.href}"] {
  color: var(--text-primary);
  font-weight: 500;
}

html[data-active-path="${child.href}"] aside nav a[href="${child.href}"]::before {
  background: rgba(66, 133, 244, 0.1);
}

html[data-active-path="${child.href}"] aside nav a[href="${child.href}"]::after {
  content: '';
  position: absolute;
  left: -12px;
  top: 12px;
  width: 3px;
  height: 20px;
  background: var(--accent-primary);
  border-radius: 0 4px 4px 0;
}
    `)
    .join('\n');

  return topLevelCSS + '\n' + submenuCSS;
}

Key Insight: Use .flatMap() to flatten nested menu structures, then generate CSS for each child independently.

Implementation: In packages/react/src/utils/sidebarStorage.ts:412-437, a new code block was added to process submenu children separately.

---
import {
  getInlineStorageScript,
  getMenuExpansionScript,
  getMenuExpansionCSS,
  getActiveStateScript,
  getActiveStateCSS
} from '@sofondo/react';

// 1. Generate inline scripts and CSS to prevent flash
const sidebarScript = getInlineStorageScript('sidebar:collapsed', 'auto');
const menuExpansionScript = getMenuExpansionScript(['Examples'], 'auto');
const menuExpansionCSS = getMenuExpansionCSS(['Examples']);
const activeStateScript = getActiveStateScript(sections, menuItems);
const activeStateCSS = getActiveStateCSS(sections, menuItems);
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Inline CSS FIRST (executed before render) -->
    <style is:inline set:html={menuExpansionCSS}></style>
    <style is:inline set:html={activeStateCSS}></style>

    <!-- Inline scripts SECOND (executed before render) -->
    <script is:inline set:html={sidebarScript}></script>
    <script is:inline set:html={menuExpansionScript}></script>
    <script is:inline set:html={activeStateScript}></script>
  </head>
  <body>
    <slot />
  </body>
</html>

Key Points:

• Order matters: CSS must come before scripts in the <head>
• Use is:inline: Astro's is:inline and set:html inject inline content
• Blocking execution: Scripts execute synchronously before page render