@sofidevo/astro-dynamic-header 2.0.0 → 2.0.2

package/README.md

@@ -2,6 +2,9 @@
 
 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.
+
 ## Features
 
 - **Dynamic Styles**: Switch between floating and fullscreen header layouts
@@ -42,15 +45,15 @@ By default, the header uses `preset="auto"`, which automatically detects the the
 ---
 import Header from '@sofidevo/astro-dynamic-header/Header';
 
-const navigation = {
-  menuItems: [
+
+const =  menuItems: [
     { link: '/about', text: 'About' },
   ]
-};
+
 ---
 
 <!-- Detects .dark class on root automatically -->
-<Header navigation={navigation} />
+<Header navigation={{ menuItems }} />
 ```
 
 ### Advanced Usage (Dual-Theme Customization)
@@ -58,9 +61,14 @@ const navigation = {
 You can provide custom colors for both light and dark modes simultaneously.
 
 ```astro
+
 ---
 import Header from '@sofidevo/astro-dynamic-header/Header';
-
+const navigation = {
+  menuItems: [
+    { link: '/about', text: 'About' },
+  ]
+};
 const theme = {
   light: {
     accentColor: "#3e1c71",
@@ -104,14 +112,14 @@ const theme = {
 
 #### ThemeConfig
 
-| Propery                | Type     | Default          |
-| ---------------------- | -------- | ---------------- |
-| `backgroundColor`      | `string` | _Preset default_ |
-| `backgroundColorOpaque`| `string` | _Preset default_ |
-| `backdropBlur`         | `string` | `"blur(20px)"`   |
-| `zIndex`               | `number` | `10`             |
-| `textColor`            | `string` | _Preset default_ |
-| `accentColor`          | `string` | _Preset default_ |
+| Propery                 | Type     | Default          |
+| ----------------------- | -------- | ---------------- |
+| `backgroundColor`       | `string` | _Preset default_ |
+| `backgroundColorOpaque` | `string` | _Preset default_ |
+| `backdropBlur`          | `string` | `"blur(20px)"`   |
+| `zIndex`                | `number` | `10`             |
+| `textColor`             | `string` | _Preset default_ |
+| `accentColor`           | `string` | _Preset default_ |
 
 > [!IMPORTANT]
 > **Transparency vs Solid Submenus**: To ensure the best UI and avoid rendering bugs with `backdrop-filter` on nested elements, submenus and the mobile navigation panel are **solid/opaque**.
@@ -129,13 +137,70 @@ const theme = {
 
 #### CustomClassNames
 
-| 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 |
+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.
+
+| 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`). |
+
+##### Advanced 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.
+
+```astro
+<Header 
+  classNames={{ 
+    header: "shadow-xl border-b border-black/5 dark:border-white/10 transition-all duration-500",
+    container: "top-4 px-6"
+  }} 
+/>
+```
+
+**Custom Typography for Logo & Nav Spacing:**
+Perfect for matching the header with your brand's specific typography and layout requirements.
+
+```astro
+<Header 
+  classNames={{ 
+    logoText: "tracking-tighter font-black italic uppercase",
+    nav: "ml-auto gap-8" /* Moves menu to the right and increases gap */
+  }} 
+/>
+```
+
+> [!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          |
+
+#### MenuItem
+
+| Property  | Type                  | Description                         |
+| --------- | --------------------- | ----------------------------------- |
+| `link`    | `string`              | URL the menu item points to         |
+| `text`    | `string`              | Label text for the menu item        |
+| `submenu` | `SecondaryMenuItem[]` | Optional array of nested menu items |
 
 ## Slots Support
 
@@ -165,46 +230,64 @@ const navigation = {
 </Header>
 ```
 
-#### Styling Action Buttons
-
-```css
-.header-actions {
-  display: flex;
-  gap: 0.5em;
-  align-items: center;
-}
+## Comprehensive Example
 
-.btn {
-  padding: 0.5em 1em;
-  border: none;
-  border-radius: 6px;
-  cursor: pointer;
-  font-weight: 500;
-  text-decoration: none;
-  display: inline-flex;
-  align-items: center;
-  transition: all 0.2s ease;
-}
+Below is a complete implementation example showcasing custom logo configuration, navigation with a home URL, and theme overrides.
 
-.btn-outline {
-  background: transparent;
-  color: #ffffff;
-  border: 1px solid #ffffff;
-}
+```astro
+---
+import Header from '@sofidevo/astro-dynamic-header/Header';
 
-.btn-outline:hover {
-  background: #ffffff;
-  color: #000000;
-}
+const menuItems = [
+  {
+    link: "#",
+    text: "Services",
+    submenu: [
+      { link: "/design", text: "Design" },
+      { link: "/consulting", text: "Consulting" },
+      {
+        link: "#",
+        text: "Web Development",
+        submenu: [
+          { link: "/web/frontend", text: "Frontend" },
+          { link: "/web/backend", text: "Backend" },
+          { link: "/web/fullstack", text: "Full Stack" },
+        ],
+      },
+    ],
+  },
+  { link: "/about", text: "About" },
+  { link: "/contact", text: "Contact" },
+];
 
-.btn-primary {
-  background: #00ffff;
-  color: #000000;
-}
+const theme = {
+  light: {
+    accentColor: "#ff0000",
+    backgroundColor: "rgba(255, 255, 255, 0.8)",
+  },
+  dark: {
+    accentColor: "#00ffff",
+    backgroundColor: "rgba(20, 20, 20, 0.9)",
+  },
+};
+---
 
-.btn-primary:hover {
-  background: #00cccc;
-}
+<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,
+  }}
+  theme={theme}
+>
+  <button slot="actions">Login</button>
+</Header>
 ```
 
 ## Header Types
@@ -242,17 +325,17 @@ The package provides full TypeScript support. You can import types to ensure you
 ```astro
 ---
 import Header from '@sofidevo/astro-dynamic-header/Header';
-import type { 
-  NavConfig, 
-  DualThemeConfig, 
+import type {
+  NavConfig,
+  DualThemeConfig,
   MenuItem,
   SecondaryMenuItem
 } from '@sofidevo/astro-dynamic-header';
 
 const navigation: NavConfig = {
   menuItems: [
-    { 
-      link: '/products', 
+    {
+      link: '/products',
       text: 'Products',
       submenu: [
         { link: '/software', text: 'Software' },
@@ -276,25 +359,25 @@ const theme: DualThemeConfig = {
 };
 ---
 
-<Header 
-  navigation={navigation} 
-  theme={theme} 
-  preset="auto" 
+<Header
+  navigation={navigation}
+  theme={theme}
+  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`         | 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            |
 
 ## Browser Support
 
@@ -324,7 +407,7 @@ If you encounter import errors, try these solutions:
    // tsconfig.json
    {
      "compilerOptions": {
-       "moduleResolution": "bundler", 
+       "moduleResolution": "bundler",
        "allowImportingTsExtensions": true
      }
    }
@@ -341,47 +424,6 @@ If you encounter import errors, try these solutions:
 
 Visit our demo website to see the component in action with interactive examples and complete documentation.
 
-## Testing
-
-This project includes a comprehensive test suite with 34 tests covering all critical functionality.
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage report
-npm run test:coverage
-```
-
-### Test Coverage
-
-The test suite covers:
-
-#### Component Logic Tests
-
-- **Header Component** (4 tests): Hamburger controller functionality, menu toggle behavior
-- **HamburgerButton Component** (10 tests): Button states, responsive behavior, accessibility
-- **MobileNav Component** (7 tests): Dropdown structure, nested submenus, conditional rendering
-- **NavMenu Component** (6 tests): Dynamic positioning, submenu interactions, viewport adjustments
-
-#### Integration Tests (7 tests)
-
-- Component interaction flows
-- Responsive behavior between mobile/desktop
-- Keyboard navigation and accessibility
-- Menu state management during navigation
-
-### Test Technologies
-
-- **Vitest**: Fast testing framework
-- **jsdom**: DOM simulation for component testing
-- **TypeScript**: Type-safe test writing
-
 ## License
 
 MIT License - see the [LICENSE](./LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sofidevo/astro-dynamic-header",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A dynamic Astro header component that switches between floating and fullscreen styles",
   "type": "module",
   "main": "./src/index.ts",

package/src/HamburgerButton.astro

@@ -1,9 +1,11 @@
 ---
 export interface Props {
+  /** Override the default color of the hamburger lines */
   color?: string;
 }
 
-const { color = "var(--color-hamburger-lines, #fff)" } = Astro.props;
+const { color = "var(--text-color, var(--color-hamburger-lines, #fff))" } =
+  Astro.props;
 ---
 
 <button
@@ -23,14 +25,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 +65,10 @@ 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(
+      --hamburger-color,
+      var(--color-hamburger-lines, #fff)
+    );
     position: absolute;
     width: 40px;
     height: 4px;
@@ -88,12 +95,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 +116,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

@@ -11,11 +11,31 @@ import type {
 } 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 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" }
+   */
   classNames?: CustomClassNames;
 }
 
@@ -28,6 +48,20 @@ const {
   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.",
+    );
+  }
+}
+
 // Default theme configuration
 const defaultThemes = {
   light: {
@@ -119,7 +153,12 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
   style={{ zIndex: lightTheme.zIndex }}
 >
   <header
-    class:list={["header", `header--${headerType}`, forcedClass, classNames.header]}
+    class:list={[
+      "header",
+      `header--${headerType}`,
+      forcedClass,
+      classNames.header,
+    ]}
     style={{
       "--l-bg": lightTheme.backgroundColor,
       "--l-bg-opaque": lightTheme.backgroundColorOpaque,
@@ -151,7 +190,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
         )
       }
     </a>
-    
+
     <div class:list={["nav-menu-wrapper", classNames.nav]}>
       <NavMenu menuItems={menuItems} />
     </div>
@@ -163,13 +202,10 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
         </div>
       )
     }
-    
+
     <HamburgerButton />
-    
-    <MobileNav 
-      menuItems={menuItems} 
-      type={headerType} 
-    >
+
+    <MobileNav menuItems={menuItems} type={headerType}>
       {
         Astro.slots.has("actions") && (
           <div class="actions-mobile" slot="slot-panel">
@@ -198,7 +234,9 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
     backdrop-filter: var(--backdrop-blur);
     -webkit-backdrop-filter: var(--backdrop-blur);
     color: var(--text-color);
-    transition: background-color 0.3s ease, color 0.3s ease;
+    transition:
+      background-color 0.3s ease,
+      color 0.3s ease;
 
     @media (width < 768px) {
       align-self: flex-end;
@@ -284,7 +322,7 @@ const forcedClass = preset !== "auto" ? `header--force-${preset}` : "";
       font-weight: 600;
     }
   }
-  
+
   .header__logo {
     margin-right: 1em;
     object-fit: contain;

package/src/MobileNav.astro

@@ -2,9 +2,13 @@
 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;
 }
 
@@ -38,64 +42,73 @@ 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" />
@@ -122,7 +135,15 @@ const pagePathname = Astro.url.pathname;
     }
 
     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 +160,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,8 +2,23 @@
 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;
 }
 

package/src/index.ts

@@ -1,71 +1,192 @@
 
 
-// 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[];
 }
 
+/**
+ * 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[];
 }
 
+/**
+ * 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 deep customization.
+ */
 export interface CustomClassNames {
+  /** Class for the outermost fixed container */
   container?: string;
+  /** Class for the main header element */
   header?: string;
+  /** Class for the logo anchor tag */
   logo?: string;
+  /** Class for the logo span text */
   logoText?: string;
+  /** Class for the desktop navigation wrapper */
   nav?: string;
 }
 
+/**
+ * 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 configuration object. */
   logo?: LogoConfig;
+  /** Navigation links and structure. */
   navigation?: NavConfig;
+  /** Custom theme overrides. See @interface DualThemeConfig */
   theme?: DualThemeConfig;
+  /** 
+   * Custom CSS classes for injecting utility classes (e.g., Tailwind).
+   * @example { header: "shadow-lg", logoText: "font-bold" }
+   */
   classNames?: CustomClassNames;
 }