@sofidevo/astro-dynamic-header 4.0.0 → 5.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 A dynamic, responsive header component for Astro projects. Supports floating and fullscreen layouts, multi-level dropdown navigation, native CSS variable customization, dark mode, and TypeScript — all with zero external icon dependencies.
 
-As of v4.0.0 the component styles are shipped inside CSS cascade layers, so any utility class you pass to the component wins over the built-in styles **without `!important`**.
+As of v4.0.0 the component styles are shipped inside CSS cascade layers, so any utility class you pass to the component wins over the built-in styles **without `!important`**. As of v5.0.0 theming is CSS-variables-only (`--l-*`, `--d-*`, `--header-z-index`): the `theme` prop was removed and the component renders no inline styles.
 
 ## Features
 
@@ -12,9 +12,10 @@ As of v4.0.0 the component styles are shipped inside CSS cascade layers, so any
 - **Dark Mode Ready** — auto-detects `.dark` on `<html>`, or forces a state with `preset`.
 - **Inline SVG Icons** — no external CDNs, no extra network requests, no flash of missing icons.
 - **Slot Support** — inject your custom logo and header actions directly into slots.
-- **Pure CSS Customization** — customize background, blur, and colors using native CSS variables.
+- **Pure CSS Customization** — background, blur, colors, and z-index via native CSS variables.
 - **Cascade-layer friendly** — component styles live in `@layer components`, so your utility classes override them without `!important` and without `twMerge()`.
-- **Full TypeScript** — all props and config interfaces are fully typed.
+- **Dev diagnostics** — in dev, warns in the console (with the fix) when your overrides cannot win or an old v3.x install is detected.
+- **Full TypeScript** — all props and config interfaces are fully typed and documented (TSDoc).
 
 ### Live Demo
 
@@ -62,6 +63,64 @@ const navigation = { menuItems };
 
 ---
 
+## Breaking Changes in v5.0.0
+
+> [!WARNING]
+> v5.0.0 removes the JavaScript theming API. The component now has a single theming mechanism: CSS variables.
+
+### 1. The `theme` prop and `defaultThemes` were removed
+
+Colors, blur, and z-index are plain CSS variables — one mechanism instead of two, and no inline styles at all, so layered CSS and utilities can always win.
+
+Before (v4):
+
+```astro
+---
+import { defaultThemes } from '@sofidevo/astro-dynamic-header';
+
+const theme = { light: { ...defaultThemes.light, accentColor: "#7c3aed", zIndex: 60 } };
+---
+<Header theme={theme} />
+```
+
+After (v5):
+
+```css
+:root {
+  --l-accent: #7c3aed;
+  --header-z-index: 60;
+}
+```
+
+In dev, the component logs a migration warning when it detects the removed prop. The `DualThemeConfig` and `ThemeConfig` types and the `./defaults` export are gone; passing `theme` now fails type-checking.
+
+### 2. The container no longer renders an inline z-index
+
+| | v4.x | v5.0.0 |
+| --- | --- | --- |
+| Theming API | `theme` prop + CSS variables | CSS variables only |
+| Container z-index | inline `style="z-index: 10"` (no CSS could beat it) | `z-index: var(--header-z-index, 10)` in `@layer components` (utilities win) |
+| `defaultThemes` | exported from `./defaults` | removed |
+
+z-index utilities passed as `classNames.container` (for example `"z-50"`) now work as expected.
+
+### 3. Other changes in v5.0.0
+
+- **Dev diagnostics for override problems.** In dev the component checks the final cascade layer order after page load and logs a `console.warn` with the exact fix when your overrides cannot win (wrong layer order) or when an old v3.x install is detected. The check is stripped from production builds.
+- **The layer order statement also ships inline.** Next to the bundled statement, the component renders `<style is:inline>` with `@layer theme, base, components, utilities;`, so styles injected at runtime are ordered correctly too.
+- **TSDoc everywhere.** Every prop and exported interface is documented in English with usage examples, including hover states via `classNames` and `navigation.menu__link__class`.
+
+### Migration checklist (to v5)
+
+```md
+- [ ] Update the package: npm i -U @sofidevo/astro-dynamic-header
+- [ ] Replace every `theme={{ light: {...}, dark: {...} }}` with the matching CSS variables (see "CSS variable reference").
+- [ ] Replace `theme.zIndex` with `--header-z-index` (or pass a z-index utility via `classNames.container`).
+- [ ] Remove `defaultThemes` imports; the defaults live in the CSS variable table below.
+```
+
+---
+
 ## Breaking Changes in v4.0.0
 
 > [!WARNING]
@@ -104,11 +163,10 @@ Two practical consequences:
 
 ### 3. Other behavior changes
 
-- **`theme.dark.zIndex` is now honored.** The container z-index resolves as `theme.light.zIndex ?? theme.dark.zIndex ?? 10`; previously only `light.zIndex` was read.
 - **Forced theme rules no longer use `!important`.** `.header.header--force-light` / `.header.header--force-dark` rely on specificity instead, so they can be overridden by your own layered CSS if you ever need to.
 - **The mobile panel's `.active` rule no longer uses `!important`**, so active-link styles are overridable like everything else.
 - **`MobileNav` defaults to `type="floating"`** when rendered on its own (previously it produced an undefined modifier class).
-- **Theme variable fallbacks now match `defaultThemes`** exactly (for example `rgba(255, 255, 255, 0.9)` for `--l-bg`).
+- **Theme variable fallbacks now match the documented defaults** exactly (for example `rgba(255, 255, 255, 0.9)` for `--l-bg`, see [CSS variable reference](#css-variable-reference)).
 
 ### Migration checklist
 
@@ -118,7 +176,6 @@ Two practical consequences:
 - [ ] Remove the `!important` declarations you added to override the header (they are no longer needed).
 - [ ] Move your global resets / element selectors into `@layer base`.
 - [ ] Using Tailwind v3? Read "Preflight changed my nav link colors" in the FAQ.
-- [ ] Setting only `dark.zIndex`? It now takes effect — double-check stacking.
 ```
 
 ---
@@ -132,9 +189,11 @@ Two practical consequences:
 | `headerType` | `"floating" \| "fullscreen"`  | `"floating"` | Layout style                                      |
 | `preset`     | `"light" \| "dark" \| "auto"` | `"auto"`     | Theme mode. `"auto"` follows `.dark` on `<html>`. |
 | `navigation` | `NavConfig`                   | `{}`         | Menu items, home link, and custom CSS classes     |
-| `theme`      | `DualThemeConfig`             | `{}`         | Optional theme overrides (prefer CSS variables)   |
 | `classNames` | `HeaderClassNames`            | `{}`         | Inject CSS classes into structural elements       |
 
+> [!NOTE]
+> There is no `theme` prop — it was removed in v5. Colors, blur, and z-index are CSS variables (see [CSS variable reference](#css-variable-reference)).
+
 ---
 
 ## Configuration Objects
@@ -233,7 +292,7 @@ Everything below assumes you want to change how the header looks or behaves. Pic
 | A different overall design (square, full-width, compact) | Your own CSS in `@layer utilities` |
 | Restyle nav links, dropdowns, or the mobile panel | Selectors targeting the internal class hooks |
 | Brand colors, blur, background | CSS variables (`--l-*` / `--d-*`) |
-| Per-instance tokens or z-index | `theme` prop |
+| Per-instance tokens or z-index | Scoped CSS variables (`--header-z-index`, `--l-*` on a wrapper) |
 | Logo / buttons markup | Slots |
 
 ### Style precedence
@@ -417,25 +476,36 @@ Scoped to one section (marketing page gets a purple tint, the docs stay neutral)
 
 Variables are inherited, so defining them on any ancestor of the header works.
 
-### Example: z-index and per-instance tokens with the `theme` prop
+### Example: z-index and per-instance tokens
 
-The container renders an **inline** `style="z-index: N"`, and inline styles beat any non-`!important` declaration — so `classNames.container="z-50"` (or any z-index utility) will not win. Use the prop:
+The container resolves its stacking level as `z-index: var(--header-z-index, 10)` inside `@layer components`, and there is no inline style — so z-index utilities passed as `classNames.container` win:
 
 ```astro
----
-import { defaultThemes } from '@sofidevo/astro-dynamic-header';
+<Header classNames={{ container: "z-50" }} />
+```
 
-const theme = {
-  light: { ...defaultThemes.light, zIndex: 60 },
-  dark: { ...defaultThemes.dark, zIndex: 60 },
-};
----
+Or set it once, globally or on a wrapper (variables are inherited):
 
-<Header theme={theme} classNames={{ header: "shadow-2xl" }} />
+```css
+:root {
+  --header-z-index: 60;
+}
 ```
 
-> [!NOTE]
-> `zIndex` resolves as `theme.light.zIndex ?? theme.dark.zIndex ?? 10`, so setting it in either block is enough. The value is a single inline number; it does not change between light and dark mode.
+Per-instance tokens work the same way:
+
+```astro
+<section class="marketing-hero">
+  <Header navigation={{ menuItems }} />
+</section>
+```
+
+```css
+.marketing-hero {
+  --l-bg: rgb(124 58 237 / 0.14);
+  --header-z-index: 60;
+}
+```
 
 ### Example: mobile panel
 
@@ -508,7 +578,8 @@ The sun and chevron icons use `currentColor`, so they follow the surrounding tex
 
 ### Styling caveats
 
-- **z-index is inline.** Use `theme.zIndex`, not a utility class, on `container`.
+- **Layer order is fixed by first appearance.** If your plain-CSS overrides lose even from `@layer utilities`, put `@layer theme, base, components, utilities;` at the very top of your global stylesheet — the dev console warning points it out.
+- **There are no inline styles.** The container z-index is `var(--header-z-index, 10)` in `@layer components`, so utilities beat it.
 - **`!important` in a layer still works** (important declarations reverse layer order), but you should not need it.
 - **Unlayered CSS beats everything layered.** If a global rule seems "too strong", that is why — move it into `@layer base`.
 - **Astro scopes component styles with `data-astro-cid-*` attributes.** Your selectors do not need them; plain class selectors work.
@@ -517,11 +588,11 @@ The sun and chevron icons use `currentColor`, so they follow the surrounding tex
 
 ## Customization & Theme Config
 
-You can fully customize the color scheme using **CSS Custom Properties** (recommended) or the `theme` prop.
+You can fully customize the color scheme using **CSS Custom Properties** — the only theming mechanism since v5.
 
 ### CSS variable reference
 
-Input variables (set them wherever the header lives — `:root`, a wrapper, or the `theme` prop):
+Input variables (set them wherever the header lives — `:root`, a wrapper, or a per-instance scope):
 
 | Variable | Used for | Light default | Dark default |
 | --- | --- | --- | --- |
@@ -530,6 +601,7 @@ Input variables (set them wherever the header lives — `:root`, a wrapper, or t
 | `--l-text` / `--d-text` | Text, hamburger lines, icons | `#1a1a1a` | `#ffffff` |
 | `--l-accent` / `--d-accent` | Hover underline, active links, dashed borders | `#3e1c71` | `#00ffff` |
 | `--l-blur` / `--d-blur` | `backdrop-filter` value | `blur(20px)` | `blur(20px)` |
+| `--header-z-index` | Stacking level of the fixed container | `10` | `10` |
 
 Derived variables (resolved by the component per theme state; override them only if you need to target internals directly):
 
@@ -541,7 +613,7 @@ Derived variables (resolved by the component per theme state; override them only
 | `--accent-color` | `--l-accent` or `--d-accent` |
 | `--backdrop-blur` | `--l-blur` or `--d-blur` |
 
-### Option 1: Native CSS Variables (Recommended)
+### Setting the variables
 
 ```css
 :root {
@@ -558,37 +630,18 @@ Derived variables (resolved by the component per theme state; override them only
   --d-bg-opaque: #0a0a0a;
   --d-text: #f5f5f5;
   --d-blur: blur(20px);
+
+  /* Stacking */
+  --header-z-index: 60;
 }
 ```
 
 The hamburger lines and the sun/chevron icons follow `--l-text` / `--d-text`, so text color drives them too. The moon glyph keeps its own white fill (`--svg-color--fff`, default `#fff`).
 
-### Option 2: JS Theme Prop
-
-```astro
----
-import { defaultThemes } from '@sofidevo/astro-dynamic-header';
-
-const theme = {
-  light: {
-    ...defaultThemes.light,
-    accentColor: "#7c3aed",
-    backgroundColor: "rgba(255, 255, 255, 0.85)",
-  },
-  dark: {
-    ...defaultThemes.dark,
-    accentColor: "#a78bfa",
-  }
-};
----
-
-<Header theme={theme} />
-```
-
-The prop writes the variables as inline styles on the header element, so it wins over `:root` values for that instance.
+Because there are no inline styles, your own layered CSS always beats these defaults — override any variable on a wrapper to scope it to one instance (see [z-index and per-instance tokens](#example-z-index-and-per-instance-tokens)).
 
 > [!IMPORTANT]
-> When using transparent backgrounds, always supply a solid fallback in `backgroundColorOpaque`. Submenus and mobile panels utilize this solid color to prevent visual glitches with nested blur effects.
+> When using transparent backgrounds, always supply a solid fallback in `--l-bg-opaque` / `--d-bg-opaque`. Submenus and mobile panels utilize this solid color to prevent visual glitches with nested blur effects.
 
 ---
 
@@ -663,11 +716,13 @@ import ChevronIcon from '@sofidevo/astro-dynamic-header/ChevronIcon';
 
 Check these in order:
 
+0. **Which version is installed?** Run `npm ls @sofidevo/astro-dynamic-header` (or the pnpm/yarn equivalent). v3.x ships unlayered styles that beat every layered override, so no amount of `@layer utilities` or Tailwind classes can win. Update to the latest version — in dev, the component logs a console warning when it detects this.
 1. **Which layer is your rule in?** Overrides belong in `@layer utilities`, or in a class passed through `classNames`. Rules in `@layer base` (and your resets) lose to the component by design.
-2. **Are you fighting the inline z-index?** `container` always renders `style="z-index: N"`. Use `theme.zIndex` instead of a z-index utility.
+2. **Did your CSS create `utilities` before the layer order statement ran?** Layers are ordered by their *first appearance* in the document; a later statement cannot reorder them. If your global CSS uses `@layer` but no statement comes first, add `@layer theme, base, components, utilities;` as its very first line (Tailwind v4 already emits this). In dev, the component logs a console warning with the exact fix when it detects this ordering.
 3. **Are you selecting the right hook?** See the [internal class hooks](#internal-class-hooks) table; plain class selectors are enough (you do not need `data-astro-cid-*`).
-4. **Is an inline style winning?** Inline styles beat every non-`!important` declaration, layered or not. The header renders inline styles for `z-index` and for any `theme` values you pass.
-5. **Tailwind v4?** Its layer order matches this component exactly, so utilities work automatically. Make sure `@import "tailwindcss"` comes first in your entry CSS.
+4. **Tailwind v4?** Its layer order matches this component exactly, so utilities work automatically. Make sure `@import "tailwindcss"` comes first in your entry CSS.
+
+Since v5 the component renders no inline styles at all — CSS variables (`--l-*`, `--d-*`, `--header-z-index`) and `@layer utilities` always win.
 
 ### Preflight changed my nav link colors (Tailwind v3)
 
@@ -694,7 +749,13 @@ Icons are rendered as inline SVG components. If you are upgrading from `v1.x` or
 
 ### The header sits behind my other content
 
-Set a z-index through the `theme` prop (`theme={{ light: { zIndex: 60 } }}`), not through a class on `container`. See [z-index and per-instance tokens](#example-z-index-and-per-instance-tokens-with-the-theme-prop).
+Raise it with `--header-z-index` (globally, on a wrapper, or via `classNames.container="z-50"` — utilities win since there is no inline z-index):
+
+```css
+:root {
+  --header-z-index: 60;
+}
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sofidevo/astro-dynamic-header",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "A dynamic Astro header component that switches between floating and fullscreen styles",
   "type": "module",
   "main": "./src/index.ts",
@@ -15,7 +15,6 @@
     "./MobileNav": "./src/MobileNav.astro",
     "./HamburgerButton": "./src/HamburgerButton.astro",
     "./ChevronIcon": "./src/ChevronIcon.astro",
-    "./defaults": "./src/defaults.ts",
     "./Header.astro": "./src/Header.astro",
     "./NavMenu.astro": "./src/NavMenu.astro",
     "./MobileNav.astro": "./src/MobileNav.astro",
@@ -28,6 +27,15 @@
     "src/*.astro",
     "README.md"
   ],
+  "scripts": {
+    "build": "astro build",
+    "dev": "astro dev",
+    "check": "astro check",
+    "check:watch": "astro check --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
   "keywords": [
     "astro",
     "component",
@@ -63,14 +71,5 @@
   "bugs": {
     "url": "https://github.com/SofiDevO/astro-dynamic-header/issues"
   },
-  "homepage": "https://base-astro-psi.vercel.app/fullscreen-demo",
-  "scripts": {
-    "build": "astro build",
-    "dev": "astro dev",
-    "check": "astro check",
-    "check:watch": "astro check --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  }
-}
+  "homepage": "https://header.sofidev.top"
+}

package/src/Header.astro

@@ -3,17 +3,80 @@ import HamburgerButton from "./HamburgerButton.astro";
 import NavMenu from "./NavMenu.astro";
 import MobileNav from "./MobileNav.astro";
 
-import type {
-  NavConfig,
-  DualThemeConfig,
-  HeaderClassNames,
-} from "./index.js";
+import type { NavConfig, HeaderClassNames } from "./index.js";
 
 export interface Props {
+  /**
+   * Layout style of the header.
+   * - `"floating"` — centered, max width, rounded corners (default).
+   * - `"fullscreen"` — full width, no border radius.
+   *
+   * @default "floating"
+   * @example
+   * ```astro
+   * <Header headerType="fullscreen" />
+   * ```
+   */
   headerType?: "floating" | "fullscreen";
+
+  /**
+   * Theme behavior of the header.
+   * - `"auto"` (default) — follows the `.dark` class on the root element.
+   * - `"light"` — always render the light theme (`header--force-light`).
+   * - `"dark"` — always render the dark theme (`header--force-dark`).
+   *
+   * Colors are controlled with CSS variables (see the README "CSS variable
+   * reference"), never with props.
+   *
+   * @default "auto"
+   * @example
+   * ```astro
+   * <Header preset="dark" />
+   * ```
+   */
   preset?: "light" | "dark" | "auto";
+
+  /**
+   * Navigation links, home link, and fine-grained classes for the desktop
+   * menu items.
+   *
+   * @example
+   * ```astro
+   * <Header
+   *   navigation={{
+   *     menuItems: [
+   *       { link: "/about", text: "About" },
+   *       { link: "/work", text: "Work", submenu: [{ link: "/ux", text: "UX" }] },
+   *     ],
+   *     menu__link__class: "hover:text-purple-400",
+   *   }}
+   * />
+   * ```
+   */
   navigation?: NavConfig;
-  theme?: DualThemeConfig;
+
+  /**
+   * CSS classes for the structural wrapper elements. The component styles
+   * live in `@layer components`, so any class passed here — Tailwind
+   * utilities included — wins over the built-in styles without `!important`.
+   *
+   * @example
+   * ```astro
+   * <Header classNames={{ header: "bg-red-500 shadow-xl", container: "top-4" }} />
+   * ```
+   *
+   * With plain CSS, put your own class in `@layer utilities` so it beats the
+   * component:
+   *
+   * ```astro
+   * <Header classNames={{ header: "custom-header-bg" }} />
+   * <style is:inline>
+   *   @layer utilities {
+   *     .custom-header-bg { background-color: red; }
+   *   }
+   * </style>
+   * ```
+   */
   classNames?: HeaderClassNames;
 }
 
@@ -22,11 +85,17 @@ const {
   preset = "auto",
 
   navigation = {},
-  theme = {},
   classNames = {},
 } = Astro.props;
 
 if (import.meta.env.DEV) {
+  const removedThemeProp = (Astro.props as Record<string, unknown>).theme;
+
+  if (removedThemeProp !== undefined) {
+    console.warn(
+      "[@sofidevo/astro-dynamic-header] BREAKING CHANGE: The 'theme' prop was removed in v5. Set the same tokens as CSS variables instead: --l-bg / --d-bg, --l-bg-opaque / --d-bg-opaque, --l-text / --d-text, --l-accent / --d-accent, --l-blur / --d-blur, and --header-z-index for the container z-index. See the README 'CSS variable reference'.",
+    );
+  }
 
   if (Array.isArray(navigation)) {
     console.warn(
@@ -35,26 +104,6 @@ if (import.meta.env.DEV) {
   }
 }
 
-
-const inlineStyles: Record<string, string> = {};
-
-if (theme.light) {
-  if (theme.light.backgroundColor) inlineStyles["--l-bg"] = theme.light.backgroundColor;
-  if (theme.light.backgroundColorOpaque) inlineStyles["--l-bg-opaque"] = theme.light.backgroundColorOpaque;
-  if (theme.light.textColor) inlineStyles["--l-text"] = theme.light.textColor;
-  if (theme.light.accentColor) inlineStyles["--l-accent"] = theme.light.accentColor;
-  if (theme.light.backdropBlur) inlineStyles["--l-blur"] = theme.light.backdropBlur;
-}
-if (theme.dark) {
-  if (theme.dark.backgroundColor) inlineStyles["--d-bg"] = theme.dark.backgroundColor;
-  if (theme.dark.backgroundColorOpaque) inlineStyles["--d-bg-opaque"] = theme.dark.backgroundColorOpaque;
-  if (theme.dark.textColor) inlineStyles["--d-text"] = theme.dark.textColor;
-  if (theme.dark.accentColor) inlineStyles["--d-accent"] = theme.dark.accentColor;
-  if (theme.dark.backdropBlur) inlineStyles["--d-blur"] = theme.dark.backdropBlur;
-}
-
-const zIndex = theme.light?.zIndex ?? theme.dark?.zIndex ?? 10;
-
 // Navigation configuration
 const {
   homeUrl = "/",
@@ -69,10 +118,19 @@ const {
 const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
 ---
 
+<style is:inline>
+  @layer theme, base, components, utilities;
+</style>
+
 <script>
   import { initHamburger } from "./scripts/hamburger.js";
+  import { initLayerDiagnostics } from "./scripts/layer-diagnostics.js";
 
   initHamburger();
+
+  if (import.meta.env.DEV) {
+    initLayerDiagnostics();
+  }
 </script>
 
 <div
@@ -81,7 +139,6 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
     `header__container--${headerType}`,
     classNames.container,
   ]}
-  style={{ zIndex }}
 >
   <header
     class:list={[
@@ -90,7 +147,6 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
       forcedClass,
       classNames.header,
     ]}
-    style={Object.keys(inlineStyles).length > 0 ? inlineStyles : undefined}
   >
     <slot name="logo" />
 
@@ -135,8 +191,9 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
   /*
    * Cascade layers keep this component overridable:
    *   base (resets/preflight) < components (ours) < utilities (your classNames)
-   * The order statement below makes that order deterministic no matter how
-   * the consumer's CSS is bundled. No `!important` is needed to override us.
+   * The order statement below fixes that order before any layer of ours is
+   * used; the dev-only diagnostic warns when a consumer's CSS created the
+   * layers in a different order first. No `!important` is needed to override us.
    */
   @layer theme, base, components, utilities;
 
@@ -201,6 +258,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
       align-items: center;
       margin: 0 auto;
       position: fixed;
+      z-index: var(--header-z-index, 10);
 
       @media (width < 768px) {
         justify-content: flex-end;

package/src/index.ts

@@ -1,14 +1,12 @@
-export { defaultThemes } from "./defaults.js";
-
 /**
- * Represents a menu item in the navigation.
+ * Represents a menu item in the navigation (top level).
  */
 export interface MenuItemType {
-  /** The URL path for the link */
+  /** The URL path for the link. */
   link: string;
-  /** The text label to display */
+  /** The text label to display. */
   text: string;
-  /** Optional nested submenu items */
+  /** Optional nested submenu items. */
   submenu?: MenuItemType[];
 }
 
@@ -16,9 +14,9 @@ export interface MenuItemType {
  * Represents a third-level menu item.
  */
 export interface TertiaryMenuItem {
-  /** The URL path for the link */
+  /** The URL path for the link. */
   link: string;
-  /** The text label to display */
+  /** The text label to display. */
   text: string;
 }
 
@@ -26,28 +24,50 @@ export interface TertiaryMenuItem {
  * Represents a second-level menu item with optional nested tertiary items.
  */
 export interface SecondaryMenuItem {
-  /** The URL path for the link */
+  /** The URL path for the link. */
   link: string;
-  /** The text label to display */
+  /** The text label to display. */
   text: string;
-  /** Optional nested tertiary menu items */
+  /** Optional nested tertiary menu items. */
   submenu?: TertiaryMenuItem[];
 }
 
 /**
  * Represents a top-level menu item with optional nested secondary items.
+ *
+ * @example
+ * ```ts
+ * const item: MenuItem = {
+ *   link: "/services",
+ *   text: "Services",
+ *   submenu: [
+ *     { link: "/design", text: "Design", submenu: [{ link: "/ux", text: "UX" }] },
+ *   ],
+ * };
+ * ```
  */
 export interface MenuItem {
-  /** The URL path for the link */
+  /** The URL path for the link. */
   link: string;
-  /** The text label to display */
+  /** The text label to display. */
   text: string;
-  /** Optional nested secondary menu items */
+  /** Optional nested secondary menu items. */
   submenu?: SecondaryMenuItem[];
 }
 
 /**
  * Configuration for the main navigation.
+ *
+ * @example
+ * ```astro
+ * <Header
+ *   navigation={{
+ *     homeUrl: "/",
+ *     menuItems: [{ link: "/about", text: "About" }],
+ *     menu__link__class: "hover:underline hover:text-purple-400",
+ *   }}
+ * />
+ * ```
  */
 export interface NavConfig {
   /**
@@ -75,56 +95,20 @@ export interface NavConfig {
   header__item__class?: string;
   /**
    * Fine-grained class override applied to every top-level `<a>` link
-   * in the desktop navigation.
+   * in the desktop navigation. This is the place for hover styles: the
+   * classes live in `@layer utilities`, so they beat the component's
+   * default link styles without `!important`.
    * @example "hover:underline font-medium"
+   * @example Plain CSS equivalent:
+   * ```css
+   * @layer utilities {
+   *   #header-menu a:hover { color: var(--d-accent, #00ffff); }
+   * }
+   * ```
    */
   menu__link__class?: string;
 }
 
-/**
- * Individual theme settings for a specific state (light/dark).
- */
-export interface ThemeConfig {
-  /**
-   * Main background color. Supports hex, rgb, rgba, etc.
-   * @example "rgba(255, 255, 255, 0.9)"
-   */
-  backgroundColor?: string;
-  /**
-   * Solid background color for submenus and mobile panels to ensure readability.
-   * @example "#ffffff"
-   */
-  backgroundColorOpaque?: string;
-  /**
-   * CSS backdrop-filter blur value.
-   * @default "blur(20px)"
-   */
-  backdropBlur?: string;
-  /**
-   * CSS z-index for the header container.
-   * @default 10
-   */
-  zIndex?: number;
-  /**
-   * Primary text color for navigation and logo.
-   */
-  textColor?: string;
-  /**
-   * Color for highlights, active states, underscores, and small borders.
-   */
-  accentColor?: string;
-}
-
-/**
- * Combined theme configuration for both light and dark modes.
- */
-export interface DualThemeConfig {
-  /** Settings applied when light mode is active. */
-  light?: ThemeConfig;
-  /** Settings applied when dark mode is active. */
-  dark?: ThemeConfig;
-}
-
 /**
  * Custom CSS class names for high-level layout & appearance customization.
  *
@@ -140,6 +124,23 @@ export interface DualThemeConfig {
  * ```astro
  * <Header classNames={{ header: "shadow-xl", container: "top-4 px-6" }} />
  * ```
+ *
+ * @example Tailwind hover states work out of the box:
+ * ```astro
+ * <Header classNames={{ header: "hover:shadow-2xl transition-shadow" }} />
+ * ```
+ *
+ * @example With plain CSS, define your class in `@layer utilities` (hover
+ * included) so it beats the component:
+ * ```astro
+ * <Header classNames={{ header: "custom-header-bg" }} />
+ * <style is:inline>
+ *   @layer utilities {
+ *     .custom-header-bg { background-color: red; }
+ *     .custom-header-bg:hover { background-color: darkred; }
+ *   }
+ * </style>
+ * ```
  */
 export interface HeaderClassNames {
   /** Outermost fixed `<div>` that positions the header on the page. */
@@ -160,6 +161,9 @@ export type CustomClassNames = HeaderClassNames;
 
 /**
  * Main properties for the Header component.
+ *
+ * Colors, blur, and z-index are plain CSS variables — see the README
+ * "CSS variable reference". There is no `theme` prop (removed in v5).
  */
 export interface HeaderProps {
   /**
@@ -167,6 +171,10 @@ export interface HeaderProps {
    * - "floating": Centered with max-width and rounded corners.
    * - "fullscreen": Full width with no border radius.
    * @default "floating"
+   * @example
+   * ```astro
+   * <Header headerType="fullscreen" />
+   * ```
    */
   headerType?: "floating" | "fullscreen";
   /**
@@ -175,42 +183,78 @@ export interface HeaderProps {
    * - "dark": Force dark mode.
    * - "auto": Detects .dark class on the root element.
    * @default "auto"
+   * @example
+   * ```astro
+   * <Header preset="dark" />
+   * ```
    */
   preset?: "light" | "dark" | "auto";
 
-  /** Navigation links and structure. */
+  /**
+   * Navigation links and structure.
+   * @example
+   * ```astro
+   * <Header navigation={{ menuItems: [{ link: "/about", text: "About" }] }} />
+   * ```
+   */
   navigation?: NavConfig;
-  /** Custom theme overrides. See {@link DualThemeConfig} */
-  theme?: DualThemeConfig;
   /**
    * High-level CSS class overrides for structural wrapper elements.
    * For fine-grained nav/logo element classes, use the nested `xxx__class`
    * props inside `navigation` or `logo` instead.
-   * @example { header: "shadow-lg", container: "top-4" }
+   * @example
+   * ```astro
+   * <Header classNames={{ header: "shadow-lg bg-red-500", container: "top-4" }} />
+   * ```
    */
   classNames?: HeaderClassNames;
 }
 
+/**
+ * Properties for the standalone {@link '/NavMenu'} desktop navigation
+ * component (the Header renders it internally).
+ */
 export interface NavMenuProps {
+  /** Layout variant, matches `HeaderProps.headerType`. */
   type?: "floating" | "fullscreen";
+  /** Top-level menu items with nested submenus. */
   menuItems?: MenuItem[];
+  /** Whether to render the home link (hidden automatically on `/`). */
   showHomeLink?: boolean;
+  /** Label for the home link. */
   homeText?: string;
+  /** Class override for the desktop `<nav>` element. */
   header__menu__class?: string;
+  /** Class override for every top-level `<li>`. */
   header__item__class?: string;
+  /** Class override for every top-level `<a>` — hover styles live here. */
   menu__link__class?: string;
 }
 
+/**
+ * Properties for the standalone {@link '/MobileNav'} slide-in panel
+ * (the Header renders it internally).
+ */
 export interface MobileNavProps {
+  /** Layout variant, matches `HeaderProps.headerType`. */
   type?: "floating" | "fullscreen";
+  /** Top-level menu items with nested submenus. */
   menuItems?: MenuItem[];
+  /** Whether to render the home link (hidden automatically on `/`). */
   showHomeLink?: boolean;
+  /** Label for the home link. */
   homeText?: string;
+  /** Class override for the mobile panel `<nav>`. */
   mobileNav__class?: string;
+  /** Accent color used by the panel's active states and icons. */
   accentColor?: string;
 }
 
+/**
+ * Properties for the standalone {@link '/HamburgerButton'} (the Header
+ * renders it internally on mobile viewports).
+ */
 export interface HamburgerButtonProps {
+  /** Text/stroke color; defaults to the current text color. */
   color?: string;
 }
-

package/src/scripts/layer-diagnostics.ts

@@ -0,0 +1,156 @@
+/**
+ * Dev-only cascade-layer order diagnostic.
+ *
+ * The component ships its styles inside `@layer components` and declares the
+ * order statement `@layer theme, base, components, utilities;` so that any
+ * consumer override in `@layer utilities` (or a Tailwind utility class passed
+ * through `classNames`) beats the built-in styles without `!important`.
+ *
+ * Two situations silently break that guarantee:
+ *
+ * 1. An old v3.x version is installed — v3 shipped unlayered styles, and
+ *    unlayered CSS beats every layered rule.
+ * 2. The consumer's CSS creates the `utilities` layer *before* any layer
+ *    order statement runs. Per the CSS Cascade spec, a later statement cannot
+ *    reorder already-created layers, so the component's `components` layer
+ *    ends up above `utilities` and consumer overrides lose.
+ *
+ * This module runs only in dev (the call site is guarded with
+ * `import.meta.env.DEV`) and warns with the exact fix instead of leaving the
+ * developer guessing why an override "does nothing".
+ */
+
+/** The canonical order statement this component guarantees. */
+export const LAYER_ORDER_STATEMENT = "@layer theme, base, components, utilities;";
+
+export type LayerProblem =
+  | { kind: "missing-components-layer" }
+  | { kind: "wrong-order"; componentsIndex: number; utilitiesIndex: number };
+
+/**
+ * Walks every readable stylesheet in the document and returns the layer names
+ * in the order they were first created (creation order = cascade order from
+ * weakest to strongest, per CSS Cascade 5 §6.4.3).
+ *
+ * Uses `cssText` parsing instead of `CSSLayerStatementRule`/`CSSLayerBlockRule`
+ * constructors so it also works in environments with partial CSSOM support.
+ */
+export function collectLayerOrder(doc: Document = document): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>();
+
+  const push = (rawName: string): void => {
+    const name = rawName.trim();
+    if (name.length > 0 && !seen.has(name)) {
+      seen.add(name);
+      order.push(name);
+    }
+  };
+
+  const walk = (rules: CSSRuleList): void => {
+    for (const rawRule of Array.from(rules)) {
+      const rule = rawRule as CSSRule & { cssRules?: CSSRuleList };
+      const cssText = rule.cssText ?? "";
+
+      if (cssText.startsWith("@layer")) {
+        const braceIndex = cssText.indexOf("{");
+        if (braceIndex === -1) {
+          // Order statement: "@layer theme, base, components, utilities;"
+          const list = cssText
+            .slice(cssText.indexOf("@layer") + "@layer".length, cssText.indexOf(";"))
+            .split(",");
+          list.forEach(push);
+        } else {
+          // Layer block: "@layer components { … }"
+          push(cssText.slice("@layer".length, braceIndex));
+        }
+      } else if (rule.cssRules) {
+        // @media / @supports / … — descend so nested layer usage still counts.
+        walk(rule.cssRules);
+      }
+    }
+  };
+
+  for (const sheet of Array.from(doc.styleSheets)) {
+    try {
+      const rules = sheet.cssRules;
+      if (rules) walk(rules);
+    } catch {
+      // Cross-origin stylesheets are unreadable — they cannot be ours anyway.
+    }
+  }
+
+  return order;
+}
+
+/**
+ * Compares the final layer order against the order the component guarantees
+ * and returns the first problem found, or `null` when everything is healthy.
+ */
+export function findLayerProblem(
+  doc: Document = document,
+): LayerProblem | null {
+  const order = collectLayerOrder(doc);
+  const componentsIndex = order.indexOf("components");
+  const utilitiesIndex = order.indexOf("utilities");
+
+  if (componentsIndex === -1) {
+    // Our styles always create `components`. If the header is rendered but the
+    // layer never appears, the shipped CSS is the old unlayered v3 styles.
+    const headerRendered = doc.querySelector(".header__container") !== null;
+    return headerRendered ? { kind: "missing-components-layer" } : null;
+  }
+
+  if (utilitiesIndex !== -1 && componentsIndex > utilitiesIndex) {
+    return { kind: "wrong-order", componentsIndex, utilitiesIndex };
+  }
+
+  return null;
+}
+
+/** Human-readable console message with the exact fix for each problem. */
+export function formatProblemMessage(problem: LayerProblem): string {
+  const banner = "[@sofidevo/astro-dynamic-header]";
+
+  if (problem.kind === "missing-components-layer") {
+    return (
+      `${banner} The component's styles were not found in \`@layer components\`. ` +
+      `This usually means an old v3.x version is installed, whose unlayered ` +
+      `styles beat every layered override. Run \`npm ls ` +
+      `@sofidevo/astro-dynamic-header\` (or the pnpm/yarn equivalent) and ` +
+      `update to the latest version.`
+    );
+  }
+
+  return (
+    `${banner} Wrong cascade layer order: \`utilities\` was created first ` +
+    `(position ${problem.utilitiesIndex}) and \`components\` after it ` +
+    `(position ${problem.componentsIndex}), so your overrides lose to the ` +
+    `component. Your CSS creates the \`utilities\` layer before any layer ` +
+    `order statement runs, and per the CSS Cascade spec a later statement ` +
+    `cannot reorder existing layers. Fix: add ` +
+    `\`@layer theme, base, components, utilities;\` as the very first line of ` +
+    `your global CSS, before any \`@layer\` usage (Tailwind v4 already ` +
+    `emits this).`
+  );
+}
+
+/**
+ * Schedules the check after `load` (plus a short delay so styles injected by
+ * dev tooling are included) and prints a `console.warn` when the order is
+ * broken. Call site guards this with `import.meta.env.DEV`.
+ */
+export function initLayerDiagnostics(): void {
+  const run = (): void => {
+    window.setTimeout(() => {
+      const problem = findLayerProblem(document);
+      if (problem) console.warn(formatProblemMessage(problem));
+    }, 250);
+  };
+
+  if (document.readyState === "complete") {
+    run();
+  } else {
+    window.addEventListener("load", run, { once: true });
+  }
+}

package/src/defaults.ts

@@ -1,36 +0,0 @@
-import type { DualThemeConfig } from "./index.js";
-
-/**
- * Built-in default theme tokens used by the Header component.
- * These are merged with any user-supplied `theme` overrides.
- *
- * You can import this object if you want to build on top of the defaults
- * rather than replacing them wholesale:
- *
- * @example
- * ```ts
- * import { defaultThemes } from '@sofidevo/astro-dynamic-header/defaults';
- * const theme = {
- *   light: { ...defaultThemes.light, accentColor: "#e11d48" },
- *   dark:  { ...defaultThemes.dark,  accentColor: "#f43f5e" },
- * };
- * ```
- */
-export const defaultThemes: Required<DualThemeConfig> = {
-  light: {
-    backgroundColor: "rgba(255, 255, 255, 0.9)",
-    backgroundColorOpaque: "rgb(255, 255, 255)",
-    backdropBlur: "blur(20px)",
-    zIndex: 10,
-    textColor: "#1a1a1a",
-    accentColor: "#3e1c71",
-  },
-  dark: {
-    backgroundColor: "#0d0d0dcc",
-    backgroundColorOpaque: "#0d0d0d",
-    backdropBlur: "blur(20px)",
-    zIndex: 10,
-    textColor: "#ffffff",
-    accentColor: "#00ffff",
-  },
-};