@sofidevo/astro-dynamic-header 2.0.2 → 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,64 +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 allows you to inject custom CSS classes (such as Tailwind CSS utility classes) into specific high-level elements of the Header component. This provides a bridge between the component's internal styles and your project's global styling system.
+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**: Use for `top-0`, `z-50`, `fixed`, or adjusting the `max-width` and `mx-auto` logic.           |
-| `header`    | Inner `<header>` element                        | **Appearance**: The best place for shadows (`shadow-md`), borders (`border-b`), or custom transition durations.          |
-| `logo`      | `<a>` tag surrounding the logo                  | **Interactions**: Add hover states, custom focus rings, or adjust the flex alignment of the logo group.                  |
-| `logoText`  | `<span>` tag containing the logo text           | **Typography**: Override font weights, apply text shadows, or use specific tracking/leading classes.                       |
-| `nav`       | `div` wrapping the desktop navigation items      | **Desktop Layout**: Adjust spacing between the logo and the menu, or add responsive visibility classes (`hidden md:flex`). |
+| 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.                                      |
 
-##### Advanced Usage Examples
+##### Usage Examples
 
-**Implementing a Premium Shadow & Border (Tailwind):**
-Ideal for creating a modern "glass" effect with a subtle border and shadow that adapts to dark mode.
+**Premium Shadow & Border:**
 
 ```astro
-<Header 
-  classNames={{ 
+<Header
+  classNames={{
     header: "shadow-xl border-b border-black/5 dark:border-white/10 transition-all duration-500",
-    container: "top-4 px-6"
-  }} 
+    container: "top-4 px-6",
+    mobileNav: "backdrop-blur-md",
+  }}
 />
 ```
 
-**Custom Typography for Logo & Nav Spacing:**
-Perfect for matching the header with your brand's specific typography and layout requirements.
+**Custom Typography & Nav Spacing:**
 
 ```astro
-<Header 
-  classNames={{ 
+<Header
+  classNames={{
     logoText: "tracking-tighter font-black italic uppercase",
-    nav: "ml-auto gap-8" /* Moves menu to the right and increases gap */
-  }} 
+    nav: "ml-auto gap-8",
+  }}
 />
 ```
 
 > [!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
 
@@ -210,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
@@ -260,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>
 ```
@@ -325,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';
@@ -342,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
 
@@ -431,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.2",
+  "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,18 +1,11 @@
 ---
-export interface Props {
-  /** Override the default color of the hamburger lines */
-  color?: string;
-}
-
-const { color = "var(--text-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>
@@ -65,10 +58,7 @@ const { color = "var(--text-color, var(--color-hamburger-lines, #fff))" } =
   .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;

package/src/Header.astro

@@ -4,21 +4,20 @@ 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.
@@ -26,35 +25,31 @@ export interface Props {
    * @default "auto"
    */
   preset?: "light" | "dark" | "auto";
-  /** Logo configuration object (src, alt, text, etc.) */
-  logo?: LogoConfig;
+
   /** Navigation links and structure. */
   navigation?: NavConfig;
   /** Custom theme overrides for light and dark modes. */
   theme?: DualThemeConfig;
-  /** 
-   * Custom CSS classes for specific internal elements.
-   * @example { header: "shadow-lg", nav: "ml-auto" }
+  /**
+   * 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?: CustomClassNames;
+  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.",
@@ -62,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}` : "";
 ---
@@ -150,7 +139,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
     `header__container--${headerType}`,
     classNames.container,
   ]}
-  style={{ zIndex: lightTheme.zIndex }}
+  style={{ zIndex }}
 >
   <header
     class:list={[
@@ -159,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>
 
     {
@@ -205,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">
@@ -219,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;
@@ -247,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 {
@@ -313,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

@@ -10,21 +10,26 @@ export interface Props {
   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">
@@ -47,7 +52,10 @@ const pagePathname = Astro.url.pathname;
         return (
           <li>
             {item.submenu ? (
-              <details class="mobile-details" open={item.submenu.some(sub => pagePathname === sub.link)}>
+              <details
+                class="mobile-details"
+                open={item.submenu.some((sub) => pagePathname === sub.link)}
+              >
                 <summary class:list={["menu__summary", { active: isActive }]}>
                   {item.text}
                   <iconify-icon
@@ -64,8 +72,18 @@ const pagePathname = Astro.url.pathname;
                     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 }]}>
+                          <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"
@@ -77,11 +95,16 @@ const pagePathname = Astro.url.pathname;
                             </summary>
                             <ol class="mobile-subsubmenu">
                               {sub.submenu.map((subsub: TertiaryMenuItem) => {
-                                const isSubSubActive = pagePathname === subsub.link;
+                                const isSubSubActive =
+                                  pagePathname === subsub.link;
                                 return (
                                   <li class="mobile-submenu__item secondary">
                                     <a
-                                      class:list={["menu__link", "mobile-menu__link", { active: isSubSubActive }]}
+                                      class:list={[
+                                        "menu__link",
+                                        "mobile-menu__link",
+                                        { active: isSubSubActive },
+                                      ]}
                                       href={subsub.link}
                                     >
                                       {subsub.text}
@@ -92,7 +115,14 @@ const pagePathname = Astro.url.pathname;
                             </ol>
                           </details>
                         ) : (
-                          <a class:list={["menu__link", "mobile-menu__link", { active: isSubActive }]} href={sub.link}>
+                          <a
+                            class:list={[
+                              "menu__link",
+                              "mobile-menu__link",
+                              { active: isSubActive },
+                            ]}
+                            href={sub.link}
+                          >
                             {sub.text}
                           </a>
                         )}
@@ -102,7 +132,10 @@ const pagePathname = Astro.url.pathname;
                 </ol>
               </details>
             ) : (
-              <a class:list={["mobile-menu__link", { active: isActive }]} href={item.link}>
+              <a
+                class:list={["mobile-menu__link", { active: isActive }]}
+                href={item.link}
+              >
                 {item.text}
               </a>
             )}
@@ -128,7 +161,9 @@ 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);

package/src/NavMenu.astro

@@ -18,11 +18,23 @@ export interface Props {
    * 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;
 ---
@@ -129,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>
@@ -142,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,4 +1,4 @@
-
+export { defaultThemes } from "./defaults.js";
 
 /**
  * Represents a menu item in the navigation.
@@ -46,87 +46,70 @@ export interface MenuItem {
   submenu?: SecondaryMenuItem[];
 }
 
-/**
- * Configuration for the site logo.
- */
-export interface LogoConfig {
-  /** 
-   * The URL of the logo image.
-   * @example "/assets/logo.png"
-   * @default "/logo.png"
-   */
-  src?: string;
-  /** Alternative text for the logo image */
-  alt?: string;
-  /** 
-   * CSS width for the logo.
-   * @example "150px" or "4rem"
-   * @default "55px"
-   */
-  width?: string;
-  /** 
-   * Optional text to display next to the logo image.
-   * @example "My Awesome Site"
-   */
-  text?: string;
-  /** 
-   * CSS font-size for the logo text.
-   * @default "1em"
-   */
-  textSize?: string;
-  /** 
-   * CSS color for the logo text. 
-   * If not provided, it will inherit from the theme's text color.
-   * @default "inherit"
-   */
-  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;
@@ -143,33 +126,50 @@ export interface DualThemeConfig {
 }
 
 /**
- * Custom CSS class names for deep customization.
+ * 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 CustomClassNames {
-  /** Class for the outermost fixed container */
+export interface HeaderClassNames {
+  /** Outermost fixed `<div>` that positions the header on the page. */
   container?: string;
-  /** Class for the main header element */
+  /** Inner `<header>` element — best place for shadows, borders, transitions. */
   header?: string;
-  /** Class for the logo anchor tag */
+  /** Logo anchor `<a>` — add hover states or focus rings here. */
   logo?: string;
-  /** Class for the logo span text */
+  /** Logo text `<span>` — override typography here. */
   logoText?: string;
-  /** Class for the desktop navigation wrapper */
+  /** 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.
@@ -177,17 +177,18 @@ export interface HeaderProps {
    * @default "auto"
    */
   preset?: "light" | "dark" | "auto";
-  /** Logo configuration object. */
-  logo?: LogoConfig;
+
   /** Navigation links and structure. */
   navigation?: NavConfig;
-  /** Custom theme overrides. See @interface DualThemeConfig */
+  /** Custom theme overrides. See {@link DualThemeConfig} */
   theme?: DualThemeConfig;
-  /** 
-   * Custom CSS classes for injecting utility classes (e.g., Tailwind).
-   * @example { header: "shadow-lg", logoText: "font-bold" }
+  /**
+   * 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?: CustomClassNames;
+  classNames?: HeaderClassNames;
 }
 
 export interface NavMenuProps {