@sofidevo/astro-dynamic-header 2.0.1 → 2.0.2

package/README.md

@@ -137,13 +137,44 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sofidevo/astro-dynamic-header",
-  "version": "2.0.1",
+  "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;
 }
 

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;
 }