@sofidevo/astro-dynamic-header 2.0.1 → 3.0.1

package/README.md

@@ -3,7 +3,13 @@
 A dynamic, responsive header component for Astro projects that can switch between floating and fullscreen styles with multi-level dropdown navigation support.
 
 > [!WARNING]
-> **Breaking Changes**: Version 2.0+ introduces a restructured configuration object. If you are upgrading from an older version, please review the [Component Props](#component-props) and the [Comprehensive Example](#comprehensive-example) to migrate your configuration.
+> **Breaking Changes — v2.2+**: The `logo` prop has been removed in favor of a much more flexible `logo` slot. The `color` prop has also been removed from the `HamburgerButton` component to ensure flawless dark mode synchronization. The `theme` property behavior was also refactored to prioritize native CSS variables, reducing DOM bloat and enabling purely CSS-based customization. See the [Changelog](#changelog) section below.
+
+> [!WARNING]
+> **Breaking Changes — v2.0+**: The `logo` and `navigation` props were restructured from strings/arrays to configuration objects. See the [Component Props](#component-props) and [Comprehensive Example](#comprehensive-example) to migrate.
+
+> [!NOTE]
+> **What's new — v2.1**: `CustomClassNames` has been renamed `HeaderClassNames` (the old name still works as an alias). New nested class props added to `LogoConfig` and `NavConfig`. New `mobileNav` slot in `HeaderClassNames`. `defaultThemes` is now exported for use outside the component. See the [Changelog](#changelog) section below.
 
 ## Features
 
@@ -12,7 +18,8 @@ A dynamic, responsive header component for Astro projects that can switch betwee
 - **Multi-level Dropdowns**: Support for nested navigation menus
 - **Slot Support**: Customizable slots for desktop header and mobile panel content
 - **TypeScript Support**: Full type safety and IntelliSense
-- **Customizable**: Extensive customization options for colors, sizes, and behavior
+- **Two-layer customization**: High-level `classNames` prop + fine-grained nested class props inside `navigation` and `logo`
+- **Exportable defaults**: Import and extend `defaultThemes` from your own code
 - **Astro Optimized**: Built specifically for Astro framework
 
 ### Live demo
@@ -45,11 +52,9 @@ By default, the header uses `preset="auto"`, which automatically detects the the
 ---
 import Header from '@sofidevo/astro-dynamic-header/Header';
 
-
-const =  menuItems: [
-    { link: '/about', text: 'About' },
-  ]
-
+const menuItems = [
+  { link: '/about', text: 'About' },
+];
 ---
 
 <!-- Detects .dark class on root automatically -->
@@ -92,14 +97,13 @@ const theme = {
 
 ### Header Component
 
-| Prop         | Type                          | Default      | Description                                |
-| ------------ | ----------------------------- | ------------ | ------------------------------------------ |
-| `headerType` | `"floating" \| "fullscreen"`  | `"floating"` | Header layout style                        |
-| `preset`     | `"light" \| "dark" \| "auto"` | `"auto"`     | Theme behavior. `auto` follows root class. |
-| `logo`       | `LogoConfig`                  | `{}`         | Logo configuration object                  |
-| `navigation` | `NavConfig`                   | `{}`         | Navigation configuration object            |
-| `theme`      | `DualThemeConfig`             | `{}`         | Custom theme overrides for light/dark      |
-| `classNames` | `CustomClassNames`            | `{}`         | Custom class names for CSS Modules         |
+| Prop         | Type                          | Default      | Description                                    |
+| ------------ | ----------------------------- | ------------ | ---------------------------------------------- |
+| `headerType` | `"floating" \| "fullscreen"`  | `"floating"` | Header layout style                            |
+| `preset`     | `"light" \| "dark" \| "auto"` | `"auto"`     | Theme behavior. `auto` follows root class.     |
+| `navigation` | `NavConfig`                   | `{}`         | Navigation configuration object                |
+| `theme`      | `DualThemeConfig`             | `{}`         | Custom theme overrides for light/dark          |
+| `classNames` | `HeaderClassNames`            | `{}`         | High-level class overrides for layout elements |
 
 ### Config Objects
 
@@ -135,33 +139,61 @@ const theme = {
 }} />
 ```
 
-#### CustomClassNames
+#### CustomClassNames → HeaderClassNames
+
+> [!NOTE]
+> `CustomClassNames` was renamed to `HeaderClassNames` in v2.1. The old name still works as a type alias — no migration required.
+
+The `classNames` prop targets the **structural wrapper elements** of the Header. For fine-grained control of individual nav links or the logo internals, use the nested `xxx__class` props inside the `navigation` or `logo` config objects instead.
+
+| Property    | Target Element                                | Purpose & Common Use Cases                                                                                      |
+| ----------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `container` | Outer `div` wrapping the header               | **Positioning & Layout**: `top-0`, `z-50`, `fixed`, adjusting `max-width` and `mx-auto` logic.                  |
+| `header`    | Inner `<header>` element                      | **Appearance**: Shadows (`shadow-md`), borders (`border-b`), or custom transition durations.                    |
+| `logo`      | `<a>` tag surrounding the logo                | **Interactions**: Hover states, custom focus rings, or adjusting the flex alignment of the logo group.          |
+| `logoText`  | `<span>` tag containing the logo text         | **Typography**: Font weights, text shadows, or specific tracking/leading classes.                               |
+| `nav`       | `<div>` wrapping the desktop navigation items | **Desktop Layout**: Spacing between the logo and the menu, or responsive visibility classes (`hidden md:flex`). |
+| `mobileNav` | Root `<nav>` of the mobile slide-in panel     | **Mobile Panel**: Extra backdrop blur, custom z-index, slide-in overrides.                                      |
+
+##### Usage Examples
+
+**Premium Shadow & Border:**
+
+```astro
+<Header
+  classNames={{
+    header: "shadow-xl border-b border-black/5 dark:border-white/10 transition-all duration-500",
+    container: "top-4 px-6",
+    mobileNav: "backdrop-blur-md",
+  }}
+/>
+```
+
+**Custom Typography & Nav Spacing:**
+
+```astro
+<Header
+  classNames={{
+    logoText: "tracking-tighter font-black italic uppercase",
+    nav: "ml-auto gap-8",
+  }}
+/>
+```
 
-| Propery     | Type     | Description                      |
-| ----------- | -------- | -------------------------------- |
-| `container` | `string` | Main container class             |
-| `header`    | `string` | Header element class             |
-| `logo`      | `string` | Logo link container class        |
-| `logoText`  | `string` | Logo text class                  |
-| `nav`       | `string` | Desktop navigation wrapper class |
+> [!TIP]
+> Since these classes are injected using Astro's `class:list`, you can also pass objects or arrays if you need conditional logic for your custom classes.
 
-#### LogoConfig
 
-| Property    | Type     | Description                                      |
-| ----------- | -------- | ------------------------------------------------ |
-| `src`       | `string` | URL of the logo image                            |
-| `alt`       | `string` | Alternative text for the logo image              |
-| `width`     | `string` | Width of the logo (e.g., "50px", "5rem")         |
-| `text`      | `string` | Text to display next to or instead of logo image |
-| `textSize`  | `string` | Font size for the logo text                      |
-| `textColor` | `string` | Color for the logo text                          |
 
 #### NavConfig
 
-| Property    | Type         | Description                             |
-| ----------- | ------------ | --------------------------------------- |
-| `homeUrl`   | `string`     | URL for the home link (defaults to `/`) |
-| `menuItems` | `MenuItem[]` | Array of navigation menu items          |
+| Property              | Type         | Description                                             |
+| --------------------- | ------------ | ------------------------------------------------------- |
+| `homeUrl`             | `string`     | URL for the home link (defaults to `/`)                 |
+| `menuItems`           | `MenuItem[]` | Array of navigation menu items                          |
+| `header__menu__class` | `string`     | Extra CSS class(es) for the desktop `<nav>` element     |
+| `header__item__class` | `string`     | Extra CSS class(es) for each top-level `<li>` menu item |
+| `menu__link__class`   | `string`     | Extra CSS class(es) for each top-level `<a>` link       |
 
 #### MenuItem
 
@@ -179,6 +211,7 @@ The Header component provides a flexible slot system that allows you to add addi
 
 | Slot Name | Location              | Visibility            | Description                              |
 | --------- | --------------------- | --------------------- | ---------------------------------------- |
+| `logo`    | Header Desktop/Mobile | Always                | Add your custom logo HTML/Components     |
 | `actions` | Header & Mobile panel | Responsive visibility | Add action buttons (login, signup, etc.) |
 
 ### Example with Slots
@@ -229,32 +262,38 @@ const menuItems = [
   { link: "/contact", text: "Contact" },
 ];
 
-const theme = {
-  light: {
-    accentColor: "#ff0000",
-    backgroundColor: "rgba(255, 255, 255, 0.8)",
-  },
-  dark: {
-    accentColor: "#00ffff",
-    backgroundColor: "rgba(20, 20, 20, 0.9)",
-  },
-};
+];
 ---
 
+<style is:inline>
+  :root {
+    /* Pure CSS Theming Configuration */
+    --l-accent: #ff0000;
+    --l-bg: rgba(255, 255, 255, 0.8);
+    
+    --d-accent: #00ffff;
+    --d-bg: rgba(20, 20, 20, 0.9);
+  }
+</style>
+
 <Header
   headerType="floating"
   preset="dark"
-  logo={{
-    src: "https://itssofi.dev/img/icons/sofi-icon.webp",
-    alt: "My Site Logo",
-    width: "44px",
-  }}
   navigation={{
     homeUrl: "/",
     menuItems: menuItems,
+    header__menu__class: "flex gap-6",
+    menu__link__class: "font-medium",
+  }}
+  classNames={{
+    header: "shadow-xl",
+    mobileNav: "backdrop-blur-md",
   }}
-  theme={theme}
 >
+  <a slot="logo" href="/" style="display: flex; align-items: center; gap: 10px; color: inherit; text-decoration: none;">
+    <img src="https://sofidev.blog/img/branding/logo.webp" alt="My Site Logo" width="44" />
+    <span style="font-weight: bold; font-size: 1.2rem;">SofiDev</span>
+  </a>
   <button slot="actions">Login</button>
 </Header>
 ```
@@ -294,9 +333,11 @@ The package provides full TypeScript support. You can import types to ensure you
 ```astro
 ---
 import Header from '@sofidevo/astro-dynamic-header/Header';
+import { defaultThemes } from '@sofidevo/astro-dynamic-header';
 import type {
   NavConfig,
   DualThemeConfig,
+  HeaderClassNames,
   MenuItem,
   SecondaryMenuItem
 } from '@sofidevo/astro-dynamic-header';
@@ -311,42 +352,43 @@ const navigation: NavConfig = {
         { link: '/hardware', text: 'Hardware' }
       ]
     }
-  ]
+  ],
+  header__menu__class: "flex gap-6",
 };
 
+// Prefer CSS custom properties globally rather than passing the `theme` object.
+// But you can still use the theme prop if needed:
 const theme: DualThemeConfig = {
-  light: {
-    accentColor: "#3e1c71",
-    backgroundColor: "rgba(255, 255, 255, 0.8)",
-    backgroundColorOpaque: "#ffffff"
-  },
-  dark: {
-    accentColor: "#00ffff",
-    backgroundColor: "rgba(10, 10, 10, 0.9)",
-    backgroundColorOpaque: "#0a0a0a"
-  }
+  light: { ...defaultThemes.light, accentColor: "#3e1c71" },
+  dark:  { ...defaultThemes.dark,  accentColor: "#00ffff", backgroundColor: "rgba(10, 10, 10, 0.9)" },
+};
+
+const classNames: HeaderClassNames = {
+  header: "shadow-xl",
+  mobileNav: "backdrop-blur-md",
 };
 ---
 
 <Header
   navigation={navigation}
-  theme={theme}
+  classNames={classNames}
   preset="auto"
 />
 ```
 
 ### Available Types
 
-| Type                | Description                                    |
-| ------------------- | ---------------------------------------------- |
-| `MenuItem`          | Top-level menu item with optional properties   |
-| `SecondaryMenuItem` | Second-level menu item                         |
-| `TertiaryMenuItem`  | Third-level menu item                          |
-| `NavConfig`         | Main navigation configuration object           |
-| `ThemeConfig`       | Individual theme settings (colors, blur, etc.) |
-| `DualThemeConfig`   | Combined settings for light and dark modes     |
-| `LogoConfig`        | Logo image and text configuration              |
-| `HeaderProps`       | Main props for the Header component            |
+| Type                | Description                                     |
+| ------------------- | ----------------------------------------------- |
+| `MenuItem`          | Top-level menu item with optional properties    |
+| `SecondaryMenuItem` | Second-level menu item                          |
+| `TertiaryMenuItem`  | Third-level menu item                           |
+| `NavConfig`         | Navigation config (items + nested class props)  |
+| `ThemeConfig`       | Individual theme settings (colors, blur, etc.)  |
+| `DualThemeConfig`   | Combined settings for light and dark modes      |
+| `HeaderClassNames`  | Class overrides for structural wrapper elements |
+| `CustomClassNames`  | **Deprecated alias** for `HeaderClassNames`     |
+| `HeaderProps`       | Main props for the Header component             |
 
 ## Browser Support
 
@@ -400,3 +442,64 @@ MIT License - see the [LICENSE](./LICENSE) file for details.
 ## Support
 
 If you find this package helpful, please consider giving it a star on GitHub!
+
+---
+
+## Changelog
+
+### v2.2 — Performance & DX Optimization
+
+#### Breaking changes
+
+- **Removed `logo` Object Configuration prop**: The `logo` property and `LogoConfig` interface have been removed. You should now use `<slot name="logo" />` to render your logo exactly as you need, passing native HTML or Astro components.
+- **Removed `color` prop from `HamburgerButton`**: The `HamburgerButton` now inherits `--text-color` natively via CSS, which fixes a bug where the button would not properly update its color when switching to dark mode. Any direct uses of `<HamburgerButton color="..." />` will fail to compile in TypeScript and should be updated to rely on global CSS variables or context inheritance.
+
+#### New features and enhancements
+
+- **Native CSS Variable Theming (Better DX)**: Redesigned how default styles are injected into the DOM. `Header.astro` no longer injects all default properties into `style={...}` attributes on load, solving the "DOM bloat" issue. You can now deeply customize the component purely by setting CSS variables like `--l-bg`, `--d-bg`, `--l-accent`, and `--d-accent` inside your `:root` style tag, removing the necessity to parse massive `theme` JS objects.
+- **Dead Code Elimination**: Cleaned up repetitive prop destructuring inside `MobileNav.astro`.
+
+### v2.1 — Style & Customization Refactor
+
+#### New features
+
+- **`HeaderClassNames`** replaces `CustomClassNames` (alias kept — no migration required).
+  New `mobileNav` slot targets the mobile slide-in `<nav>` panel.
+
+- **Nested class props** on `LogoConfig`:
+  | Prop | Targets |
+  |------|---------|
+  | `logo__container__class` | Logo `<a>` wrapper |
+  | `logo__text__class` | Logo text `<span>` |
+
+- **Nested class props** on `NavConfig`:
+  | Prop | Targets |
+  |------|---------|
+  | `header__menu__class` | Desktop `<nav>` element |
+  | `header__item__class` | Each top-level `<li>` |
+  | `menu__link__class` | Each top-level `<a>` |
+
+- **`defaultThemes` exported** — import and spread the built-in tokens to extend them:
+  ```ts
+  import { defaultThemes } from "@sofidevo/astro-dynamic-header";
+  const theme = { dark: { ...defaultThemes.dark, accentColor: "#f43f5e" } };
+  ```
+
+#### Internal improvements
+
+- Default theme tokens extracted to `src/defaults.ts` — easier to read and maintain.
+- `HamburgerButton` color is now explicitly wired from the resolved theme (no visual change).
+
+#### Deprecations
+
+- `CustomClassNames` — use `HeaderClassNames` instead. The alias will remain until the next major version.
+
+### v2.0 — Object-based Configuration API
+
+> [!WARNING]
+> Breaking change: `logo` changed from `string` to `LogoConfig`, `navigation` changed from `MenuItem[]` to `NavConfig`.
+
+- `logo` prop restructured to `LogoConfig` object (`src`, `alt`, `width`, `text`, `textSize`, `textColor`).
+- `navigation` prop restructured to `NavConfig` object (`homeUrl`, `menuItems`).
+- `classNames` prop introduced for CSS class injection (`CustomClassNames`).
+- Dual-theme support via `DualThemeConfig` (`light` + `dark`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sofidevo/astro-dynamic-header",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "A dynamic Astro header component that switches between floating and fullscreen styles",
   "type": "module",
   "main": "./src/index.ts",
@@ -53,10 +53,10 @@
     "astro": "^6.0.6"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.8",
+    "@astrojs/check": "^0.9.9",
     "@types/jsdom": "^21.1.7",
     "@vitest/coverage-v8": "^3.2.4",
-    "astro": "^6.0.6",
+    "astro": "^6.3.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.4"

package/src/HamburgerButton.astro

@@ -1,16 +1,11 @@
 ---
-export interface Props {
-  color?: string;
-}
-
-const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
+export interface Props {}
 ---
 
 <button
   class="hamburger hamburger--collapse"
   type="button"
   id="hamburger-btn"
-  style={`--hamburger-color: ${color};`}
 >
   <span class="hamburger-box">
     <span class="hamburger-inner"></span>
@@ -23,14 +18,16 @@ const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
     font: inherit;
     overflow: visible;
     margin: 0;
-    padding: 15px;
+    padding: 10px;
     cursor: pointer;
     transition-timing-function: linear;
     transition-duration: 0.15s;
-    transition-property: opacity, filter;
+    transition-property: opacity, filter, border-color;
     text-transform: none;
     color: inherit;
-    border: 0;
+    border: 1px solid
+      color-mix(in srgb, var(--text-color, #fff) 25%, transparent);
+    border-radius: 8px;
     background-color: transparent;
 
     @media screen and (max-width: 768px) {
@@ -61,7 +58,7 @@ const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
   .hamburger-inner,
   .hamburger-inner::before,
   .hamburger-inner::after {
-    background-color: var(--hamburger-color, var(--color-hamburger-lines, #fff));
+    background-color: var(--text-color, inherit);
     position: absolute;
     width: 40px;
     height: 4px;
@@ -88,12 +85,16 @@ const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
   }
 
   .hamburger--collapse .hamburger-inner:before {
-    transition: top 0.12s cubic-bezier(0.33333, 0.66667, 0.66667, 1) 0.2s, transform 0.13s cubic-bezier(0.55, 0.055, 0.675, 0.19);
+    transition:
+      top 0.12s cubic-bezier(0.33333, 0.66667, 0.66667, 1) 0.2s,
+      transform 0.13s cubic-bezier(0.55, 0.055, 0.675, 0.19);
   }
 
   .hamburger--collapse .hamburger-inner:after {
     top: -20px;
-    transition: top 0.2s cubic-bezier(0.33333, 0.66667, 0.66667, 1) 0.2s, opacity 0.1s linear;
+    transition:
+      top 0.2s cubic-bezier(0.33333, 0.66667, 0.66667, 1) 0.2s,
+      opacity 0.1s linear;
   }
 
   /* Animation */
@@ -105,13 +106,17 @@ const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
 
   .hamburger--collapse.is-active .hamburger-inner:before {
     top: 0;
-    transition: top 0.1s cubic-bezier(0.33333, 0, 0.66667, 0.33333) 0.16s, transform 0.13s cubic-bezier(0.215, 0.61, 0.355, 1) 0.25s;
+    transition:
+      top 0.1s cubic-bezier(0.33333, 0, 0.66667, 0.33333) 0.16s,
+      transform 0.13s cubic-bezier(0.215, 0.61, 0.355, 1) 0.25s;
     transform: rotate(-90deg);
   }
 
   .hamburger--collapse.is-active .hamburger-inner:after {
     top: 0;
-    transition: top 0.2s cubic-bezier(0.33333, 0, 0.66667, 0.33333), opacity 0.1s linear 0.22s;
+    transition:
+      top 0.2s cubic-bezier(0.33333, 0, 0.66667, 0.33333),
+      opacity 0.1s linear 0.22s;
     opacity: 0;
   }
 </style>

package/src/Header.astro

@@ -4,37 +4,52 @@ import NavMenu from "./NavMenu.astro";
 import MobileNav from "./MobileNav.astro";
 
 import type {
-  LogoConfig,
   NavConfig,
   DualThemeConfig,
-  CustomClassNames,
+  HeaderClassNames,
 } from "./index.js";
 
 export interface Props {
+  /**
+   * Layout style.
+   * - "floating": Centered with max-width and rounded corners.
+   * - "fullscreen": Full width with no border radius.
+   * @default "floating"
+   */
   headerType?: "floating" | "fullscreen";
+  /**
+   * Theme behavior.
+   * - "light": Force light mode.
+   * - "dark": Force dark mode.
+   * - "auto": Detects .dark class on the root element.
+   * @default "auto"
+   */
   preset?: "light" | "dark" | "auto";
-  logo?: LogoConfig;
+
+  /** Navigation links and structure. */
   navigation?: NavConfig;
+  /** Custom theme overrides for light and dark modes. */
   theme?: DualThemeConfig;
-  classNames?: CustomClassNames;
+  /**
+   * 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" }
+   */
+  classNames?: HeaderClassNames;
 }
 
 const {
   headerType = "floating",
   preset = "auto",
-  logo = {},
+
   navigation = {},
   theme = {},
   classNames = {},
 } = Astro.props;
 
 if (import.meta.env.DEV) {
-  // Check if logo is being passed as a string (legacy)
-  if (typeof logo === "string") {
-    console.warn(
-      "[@sofidevo/astro-dynamic-header] BREAKING CHANGE: The 'logo' prop now expects an object. Please use logo={{ src: '...' }} instead.",
-    );
-  }
+
   if (Array.isArray(navigation)) {
     console.warn(
       "[@sofidevo/astro-dynamic-header] BREAKING CHANGE: The 'navigation' prop now expects an object with 'menuItems'. Please use navigation={{ menuItems: [...] }} instead.",
@@ -42,42 +57,36 @@ if (import.meta.env.DEV) {
   }
 }
 
-// Default theme configuration
-const defaultThemes = {
-  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",
-  },
-};
-
-// Merge with user overrides
-const lightTheme = { ...defaultThemes.light, ...theme.light };
-const darkTheme = { ...defaultThemes.dark, ...theme.dark };
+// Map user theme overrides to CSS custom properties
+const inlineStyles: Record<string, string> = {};
 
-// Navigation configuration
-const { homeUrl = "/", menuItems = [] } = navigation;
+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;
+}
 
-// Logo configuration
+const zIndex = theme.light?.zIndex ?? 10;
+
+// Navigation configuration
 const {
-  src: logoSrc = "/logo.png",
-  alt: logoAlt = "Logo",
-  width: logoWidth = "55px",
-  text: logoText = "",
-  textSize: logoTextSize = "1em",
-  textColor: logoTextColor = "inherit", // Will inherit from theme text-color
-} = logo;
+  homeUrl = "/",
+  menuItems = [],
+  header__menu__class,
+  header__item__class,
+  menu__link__class,
+} = navigation;
+
+
 
 const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
 ---
@@ -130,7 +139,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
     `header__container--${headerType}`,
     classNames.container,
   ]}
-  style={{ zIndex: lightTheme.zIndex }}
+  style={{ zIndex }}
 >
   <header
     class:list={[
@@ -139,40 +148,17 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
       forcedClass,
       classNames.header,
     ]}
-    style={{
-      "--l-bg": lightTheme.backgroundColor,
-      "--l-bg-opaque": lightTheme.backgroundColorOpaque,
-      "--l-text": lightTheme.textColor,
-      "--l-accent": lightTheme.accentColor,
-      "--l-blur": lightTheme.backdropBlur,
-      "--d-bg": darkTheme.backgroundColor,
-      "--d-bg-opaque": darkTheme.backgroundColorOpaque,
-      "--d-text": darkTheme.textColor,
-      "--d-accent": darkTheme.accentColor,
-      "--d-blur": darkTheme.backdropBlur,
-    }}
+    style={Object.keys(inlineStyles).length > 0 ? inlineStyles : undefined}
   >
-    <a class:list={["logo__container", classNames.logo]} href={homeUrl}>
-      <img
-        class="header__logo"
-        src={logoSrc}
-        alt={logoAlt}
-        style={{ width: logoWidth }}
-      />
-      {
-        logoText && (
-          <span
-            class:list={["header__logo-text", classNames.logoText]}
-            style={{ color: logoTextColor, fontSize: logoTextSize }}
-          >
-            {logoText}
-          </span>
-        )
-      }
-    </a>
+    <slot name="logo" />
 
     <div class:list={["nav-menu-wrapper", classNames.nav]}>
-      <NavMenu menuItems={menuItems} />
+      <NavMenu
+        menuItems={menuItems}
+        header__menu__class={header__menu__class}
+        header__item__class={header__item__class}
+        menu__link__class={menu__link__class}
+      />
     </div>
 
     {
@@ -185,7 +171,11 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
 
     <HamburgerButton />
 
-    <MobileNav menuItems={menuItems} type={headerType}>
+    <MobileNav
+      menuItems={menuItems}
+      type={headerType}
+      mobileNav__class={classNames.mobileNav}
+    >
       {
         Astro.slots.has("actions") && (
           <div class="actions-mobile" slot="slot-panel">
@@ -199,11 +189,11 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
 
 <style is:inline>
   .header {
-    --bg-color: var(--l-bg);
-    --bg-color-opaque: var(--l-bg-opaque);
-    --text-color: var(--l-text);
-    --accent-color: var(--l-accent);
-    --backdrop-blur: var(--l-blur);
+    --bg-color: var(--l-bg, rgba(255, 255, 255, 0.9));
+    --bg-color-opaque: var(--l-bg-opaque, rgb(255, 255, 255));
+    --text-color: var(--l-text, #1a1a1a);
+    --accent-color: var(--l-accent, #3e1c71);
+    --backdrop-blur: var(--l-blur, blur(20px));
 
     display: flex;
     align-items: center;
@@ -227,28 +217,28 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
 
   /* Automatic dark mode detection via root class */
   :root.dark .header:not(.header--force-light) {
-    --bg-color: var(--d-bg);
-    --bg-color-opaque: var(--d-bg-opaque);
-    --text-color: var(--d-text);
-    --accent-color: var(--d-accent);
-    --backdrop-blur: var(--d-blur);
+    --bg-color: var(--d-bg, #0d0d0dcc);
+    --bg-color-opaque: var(--d-bg-opaque, #0d0d0d);
+    --text-color: var(--d-text, #ffffff);
+    --accent-color: var(--d-accent, #00ffff);
+    --backdrop-blur: var(--d-blur, blur(20px));
   }
 
   /* Forced themes */
   .header--force-dark {
-    --bg-color: var(--d-bg) !important;
-    --bg-color-opaque: var(--d-bg-opaque) !important;
-    --text-color: var(--d-text) !important;
-    --accent-color: var(--d-accent) !important;
-    --backdrop-blur: var(--d-blur) !important;
+    --bg-color: var(--d-bg, #0d0d0dcc) !important;
+    --bg-color-opaque: var(--d-bg-opaque, #0d0d0d) !important;
+    --text-color: var(--d-text, #ffffff) !important;
+    --accent-color: var(--d-accent, #00ffff) !important;
+    --backdrop-blur: var(--d-blur, blur(20px)) !important;
   }
 
   .header--force-light {
-    --bg-color: var(--l-bg) !important;
-    --bg-color-opaque: var(--l-bg-opaque) !important;
-    --text-color: var(--l-text) !important;
-    --accent-color: var(--l-accent) !important;
-    --backdrop-blur: var(--l-blur) !important;
+    --bg-color: var(--l-bg, rgba(255, 255, 255, 0.9)) !important;
+    --bg-color-opaque: var(--l-bg-opaque, rgb(255, 255, 255)) !important;
+    --text-color: var(--l-text, #1a1a1a) !important;
+    --accent-color: var(--l-accent, #3e1c71) !important;
+    --backdrop-blur: var(--l-blur, blur(20px)) !important;
   }
 
   .header__container {
@@ -293,20 +283,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
     }
   }
 
-  .logo__container {
-    display: flex;
-    align-items: center;
-    text-decoration: none;
-    color: inherit;
-    & span {
-      font-weight: 600;
-    }
-  }
 
-  .header__logo {
-    margin-right: 1em;
-    object-fit: contain;
-  }
 
   .actions-desktop {
     @media (width < 768px) {

package/src/MobileNav.astro

@@ -2,25 +2,34 @@
 import type { MenuItem, SecondaryMenuItem, TertiaryMenuItem } from "./index.js";
 
 export interface Props {
+  /** Header type for styling: "floating" or "fullscreen" */
   type?: "floating" | "fullscreen";
+  /** Array of menu items to display in the mobile menu */
   menuItems?: MenuItem[];
+  /** Whether to show the home link (defaults to true) */
   showHomeLink?: boolean;
+  /** Text for the home link (defaults to "Home") */
   homeText?: string;
+  /** Extra CSS class(es) for the root mobile `<nav>` panel. */
+  mobileNav__class?: string;
 }
 
-const { type } = Astro.props;
-
 const {
+  type,
+  mobileNav__class,
   menuItems = [],
   showHomeLink = true,
-  homeText = "Home",
+  homeText = "Home"
 } = Astro.props;
 
 const pagePathname = Astro.url.pathname;
 ---
 
 <nav
-  class={`mobile-header__menu mobile-header__menu--${type}`}
+  class:list={[
+    `mobile-header__menu mobile-header__menu--${type}`,
+    mobileNav__class,
+  ]}
   id="mobile-header-menu"
 >
   <ol class="mobile-menu">
@@ -38,64 +47,101 @@ const pagePathname = Astro.url.pathname;
       )
     }
     {
-      menuItems?.map((item: MenuItem) => (
-        <li>
-          {item.submenu ? (
-            <details class="mobile-details">
-              <summary class="menu__summary">
+      menuItems?.map((item: MenuItem) => {
+        const isActive = pagePathname === item.link;
+        return (
+          <li>
+            {item.submenu ? (
+              <details
+                class="mobile-details"
+                open={item.submenu.some((sub) => pagePathname === sub.link)}
+              >
+                <summary class:list={["menu__summary", { active: isActive }]}>
+                  {item.text}
+                  <iconify-icon
+                    class="iconify-arrow"
+                    icon="codicon:triangle-down"
+                    width="15"
+                    height="15"
+                    style="color: var(--accent-color);"
+                  />
+                </summary>
+                <ol class="mobile-submenu">
+                  {item?.submenu?.map((sub: SecondaryMenuItem) => {
+                    const isSubActive = pagePathname === sub.link;
+                    return (
+                      <li>
+                        {sub.submenu && sub.submenu.length > 0 ? (
+                          <details
+                            class="mobile-details"
+                            open={sub.submenu.some(
+                              (subsub) => pagePathname === subsub.link,
+                            )}
+                          >
+                            <summary
+                              class:list={[
+                                "menu__summary",
+                                { active: isSubActive },
+                              ]}
+                            >
+                              {sub.text}
+                              <iconify-icon
+                                class="iconify-arrow"
+                                icon="codicon:triangle-down"
+                                width="15"
+                                height="15"
+                                style="color: var(--accent-color);"
+                              />
+                            </summary>
+                            <ol class="mobile-subsubmenu">
+                              {sub.submenu.map((subsub: TertiaryMenuItem) => {
+                                const isSubSubActive =
+                                  pagePathname === subsub.link;
+                                return (
+                                  <li class="mobile-submenu__item secondary">
+                                    <a
+                                      class:list={[
+                                        "menu__link",
+                                        "mobile-menu__link",
+                                        { active: isSubSubActive },
+                                      ]}
+                                      href={subsub.link}
+                                    >
+                                      {subsub.text}
+                                    </a>
+                                  </li>
+                                );
+                              })}
+                            </ol>
+                          </details>
+                        ) : (
+                          <a
+                            class:list={[
+                              "menu__link",
+                              "mobile-menu__link",
+                              { active: isSubActive },
+                            ]}
+                            href={sub.link}
+                          >
+                            {sub.text}
+                          </a>
+                        )}
+                      </li>
+                    );
+                  })}
+                </ol>
+              </details>
+            ) : (
+              <a
+                class:list={["mobile-menu__link", { active: isActive }]}
+                href={item.link}
+              >
                 {item.text}
-                <iconify-icon
-                  class="iconify-arrow"
-                  icon="codicon:triangle-down"
-                  width="15"
-                  height="15"
-                  style="color: var(--accent-color);"
-                />
-              </summary>
-              <ol class="mobile-submenu">
-                {item?.submenu?.map((sub: SecondaryMenuItem) => (
-                  <li>
-                    {sub.submenu && sub.submenu.length > 0 ? (
-                      <details class="mobile-details">
-                        <summary class="menu__summary">
-                          {sub.text}
-                          <iconify-icon
-                            class="iconify-arrow"
-                            icon="codicon:triangle-down"
-                            width="15"
-                            height="15"
-                            style="color: var(--accent-color);"
-                          />
-                        </summary>
-                        <ol class="mobile-subsubmenu">
-                          {sub.submenu.map((subsub: TertiaryMenuItem) => (
-                            <li class="mobile-submenu__item secondary">
-                              <a
-                                class="menu__link mobile-menu__link"
-                                href={subsub.link}
-                              >
-                                {subsub.text}
-                              </a>
-                            </li>
-                          ))}
-                        </ol>
-                      </details>
-                    ) : (
-                      <a class="menu__link mobile-menu__link" href={sub.link}>
-                        {sub.text}
-                      </a>
-                    )}
-                  </li>
-                ))}
-              </ol>
-            </details>
-          ) : (
-            <a class="mobile-menu__link" href={item.link}>
-              {item.text}
-            </a>
-          )}
-        </li>
-      ))
+              </a>
+            )}
+          </li>
+        );
+      })
     }
   </ol>
   <slot name="slot-panel" />
@@ -115,14 +161,24 @@ const pagePathname = Astro.url.pathname;
       left: 0;
       background: var(--bg-color-opaque, #151515);
       z-index: 20;
-      transition: transform 0.3s ease-in-out, background-color 0.3s ease;
+      transition:
+        transform 0.3s ease-in-out,
+        background-color 0.3s ease;
       transform: translateX(100%);
       padding: 10rem 2rem 2rem;
       color: var(--text-color, #fff);
     }
 
     a {
-      color: var(--text-color, #fff);
+      color: color-mix(
+        in srgb,
+        var(--accent-color, #00ffff) 30%,
+        var(--text-color, #ffffff) 70%
+      );
+    }
+
+    .active {
+      color: var(--accent-color, #00ffff) !important;
     }
   }
 
@@ -139,7 +195,7 @@ const pagePathname = Astro.url.pathname;
 
   .mobile-menu li a {
     border: solid 1px
-      color-mix(in srgb, var(--accent-color, #00ffff) 20%, transparent);
+      color-mix(in srgb, var(--accent-color, #00ffff) 15%, transparent);
     border-radius: 4px;
     width: 100%;
     height: 4rem;

package/src/NavMenu.astro

@@ -2,12 +2,39 @@
 import type { MenuItem, SecondaryMenuItem, TertiaryMenuItem } from "./index.js";
 
 export interface Props {
+  /**
+   * Header type for styling.
+   * @example "floating"
+   */
+  type?: "floating" | "fullscreen";
+  /** Array of menu items to display. */
   menuItems?: MenuItem[];
+  /**
+   * Whether to show the home link in the menu.
+   * @default true
+   */
   showHomeLink?: boolean;
+  /**
+   * Text for the home link.
+   * @default "Home"
+   */
   homeText?: string;
+  /** Extra CSS class(es) for the `<nav>` element. */
+  header__menu__class?: string;
+  /** Extra CSS class(es) for each top-level `<li>` item. */
+  header__item__class?: string;
+  /** Extra CSS class(es) for each top-level menu `<a>` link. */
+  menu__link__class?: string;
 }
 
-const { menuItems = [], showHomeLink = true, homeText = "Home" } = Astro.props;
+const {
+  menuItems = [],
+  showHomeLink = true,
+  homeText = "Home",
+  header__menu__class,
+  header__item__class,
+  menu__link__class,
+} = Astro.props;
 
 const pagePathname = Astro.url.pathname;
 ---
@@ -114,12 +141,16 @@ const pagePathname = Astro.url.pathname;
   });
 </script>
 
-<nav class="header__menu" id="header-menu">
+<nav class:list={["header__menu", header__menu__class]} id="header-menu">
   <ul class="menu">
     {
       showHomeLink && pagePathname !== "/" && (
-        <li class="header__item">
-          <a class="menu__link" href="/" data-astro-prefetch="hover">
+        <li class:list={["header__item", header__item__class]}>
+          <a
+            class:list={["menu__link", menu__link__class]}
+            href="/"
+            data-astro-prefetch="hover"
+          >
             {homeText}
           </a>
         </li>
@@ -127,8 +158,8 @@ const pagePathname = Astro.url.pathname;
     }
     {
       menuItems.map((item: MenuItem) => (
-        <li class="menu__item">
-          <a class="menu__link" href={item.link}>
+        <li class:list={["menu__item", header__item__class]}>
+          <a class:list={["menu__link", menu__link__class]} href={item.link}>
             {item.text}
             {item.submenu && (
               <iconify-icon

package/src/defaults.ts

@@ -0,0 +1,36 @@
+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",
+  },
+};

package/src/index.ts

@@ -1,72 +1,194 @@
+export { defaultThemes } from "./defaults.js";
 
-
-// Types
+/**
+ * Represents a menu item in the navigation.
+ */
 export interface MenuItemType {
+  /** The URL path for the link */
   link: string;
+  /** The text label to display */
   text: string;
+  /** Optional nested submenu items */
   submenu?: MenuItemType[];
 }
 
+/**
+ * Represents a third-level menu item.
+ */
 export interface TertiaryMenuItem {
+  /** The URL path for the link */
   link: string;
+  /** The text label to display */
   text: string;
 }
 
+/**
+ * Represents a second-level menu item with optional nested tertiary items.
+ */
 export interface SecondaryMenuItem {
+  /** The URL path for the link */
   link: string;
+  /** The text label to display */
   text: string;
+  /** Optional nested tertiary menu items */
   submenu?: TertiaryMenuItem[];
 }
 
+/**
+ * Represents a top-level menu item with optional nested secondary items.
+ */
 export interface MenuItem {
+  /** The URL path for the link */
   link: string;
+  /** The text label to display */
   text: string;
+  /** Optional nested secondary menu items */
   submenu?: SecondaryMenuItem[];
 }
 
-export interface LogoConfig {
-  src?: string;
-  alt?: string;
-  width?: string;
-  text?: string;
-  textSize?: string;
-  textColor?: string;
-}
-
+/**
+ * Configuration for the main navigation.
+ */
 export interface NavConfig {
+  /**
+   * The URL for the home link.
+   * @default "/"
+   */
   homeUrl?: string;
+  /**
+   * Array of top-level menu items.
+   * @example [{ link: "/about", text: "About Us" }]
+   */
   menuItems?: MenuItem[];
+  /**
+   * Fine-grained class override for the desktop `<nav>` element.
+   * Use this when you want the class to live alongside the rest of the
+   * navigation configuration rather than in the top-level `classNames` prop.
+   * @example "flex gap-4"
+   */
+  header__menu__class?: string;
+  /**
+   * Fine-grained class override applied to every top-level `<li>` item
+   * in the desktop navigation.
+   * @example "px-2 py-1"
+   */
+  header__item__class?: string;
+  /**
+   * Fine-grained class override applied to every top-level `<a>` link
+   * in the desktop navigation.
+   * @example "hover:underline font-medium"
+   */
+  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;
 }
 
-export interface CustomClassNames {
+/**
+ * Custom CSS class names for high-level layout & appearance customization.
+ *
+ * These target the structural wrapper elements of the Header. For fine-grained
+ * control over individual nav links or the logo internals, use the nested
+ * `xxx__class` props inside the `navigation` or `logo` config objects instead.
+ *
+ * @example
+ * ```astro
+ * <Header classNames={{ header: "shadow-xl", container: "top-4 px-6" }} />
+ * ```
+ */
+export interface HeaderClassNames {
+  /** Outermost fixed `<div>` that positions the header on the page. */
   container?: string;
+  /** Inner `<header>` element — best place for shadows, borders, transitions. */
   header?: string;
+  /** Logo anchor `<a>` — add hover states or focus rings here. */
   logo?: string;
+  /** Logo text `<span>` — override typography here. */
   logoText?: string;
+  /** Desktop nav wrapper `<div>` — adjust spacing between logo and menu. */
   nav?: string;
+  /** Mobile nav panel `<nav>` — add slide-in overrides or z-index tweaks. */
+  mobileNav?: string;
 }
 
+/**
+ * @deprecated Use {@link HeaderClassNames} instead.
+ * Kept as an alias for backwards compatibility.
+ */
+export type CustomClassNames = HeaderClassNames;
+
+/**
+ * Main properties for the Header component.
+ */
 export interface HeaderProps {
+  /**
+   * Layout style.
+   * - "floating": Centered with max-width and rounded corners.
+   * - "fullscreen": Full width with no border radius.
+   * @default "floating"
+   */
   headerType?: "floating" | "fullscreen";
+  /**
+   * Theme behavior.
+   * - "light": Force light mode.
+   * - "dark": Force dark mode.
+   * - "auto": Detects .dark class on the root element.
+   * @default "auto"
+   */
   preset?: "light" | "dark" | "auto";
-  logo?: LogoConfig;
+
+  /** Navigation links and structure. */
   navigation?: NavConfig;
+  /** Custom theme overrides. See {@link DualThemeConfig} */
   theme?: DualThemeConfig;
-  classNames?: CustomClassNames;
+  /**
+   * 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" }
+   */
+  classNames?: HeaderClassNames;
 }
 
 export interface NavMenuProps {