starlight-mega-menu 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+---
+
+## Describe the Bug
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+
+A clear and concise description of what actually happened.
+
+## Environment
+
+- OS: [e.g., macOS 14.0, Ubuntu 22.04]
+- Browser: [e.g., Chrome 120, Firefox 121]
+- Version/Commit: [e.g., commit SHA or tag]
+
+## Additional Context
+
+Add any other context, screenshots, or log output about the problem here.

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []

package/.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,21 @@
+---
+name: Documentation
+description: Suggest a documentation improvement or report missing docs
+labels: ["documentation"]
+---
+
+## What Needs to Be Documented
+
+Describe the topic, feature, or area that needs documentation.
+
+## Current State
+
+Describe the current state of the documentation (missing, incomplete, outdated, unclear).
+
+## Suggested Improvement
+
+Describe what the documentation should cover or how it should be improved.
+
+## Additional Context
+
+Add any references, examples, or links that would help with the documentation.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+---
+
+## Feature Description
+
+A clear and concise description of the feature you'd like.
+
+## Use Case / Motivation
+
+Explain the problem this feature would solve or the value it would provide.
+
+## Proposed Solution
+
+Describe how you'd like this feature to work.
+
+## Alternatives Considered
+
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, mockups, or references about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+Brief description of the changes in this PR.
+
+## Related Issue
+
+Closes #
+
+## Changes
+
+-
+
+## Checklist
+
+- [ ] Linked to a GitHub issue (required — CI will block merge without it)
+- [ ] Tested locally
+- [ ] Follows project conventions

package/.github/workflows/auto-merge.yml

@@ -0,0 +1,15 @@
+name: Auto Merge
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    uses: robinmordasiewicz/f5xc-template/.github/workflows/auto-merge.yml@main
+    secrets:
+      REPO_ADMIN_TOKEN: ${{ secrets.REPO_ADMIN_TOKEN }}

package/.github/workflows/enforce-repo-settings.yml

@@ -0,0 +1,19 @@
+name: Enforce Repository Settings
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'
+  push:
+    branches: [main]
+    paths:
+      - '.github/config/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  enforce:
+    uses: robinmordasiewicz/f5xc-template/.github/workflows/enforce-repo-settings.yml@main
+    secrets:
+      repo-admin-token: ${{ secrets.REPO_ADMIN_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '.github/**'
+      - '.editorconfig'
+      - '.gitignore'
+      - 'CLAUDE.md'
+      - 'CONTRIBUTING.md'
+      - 'README.md'
+      - 'LICENSE'
+      - 'release.config.js'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, 'chore(release):')"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install semantic-release
+        run: >
+          npm install --no-save
+          semantic-release
+          @semantic-release/commit-analyzer
+          @semantic-release/release-notes-generator
+          @semantic-release/npm
+          @semantic-release/github
+
+      - name: Run semantic-release
+        run: |
+          max_attempts=3
+          attempt=1
+          delay=10
+          while [ $attempt -le $max_attempts ]; do
+            echo "Attempt $attempt of $max_attempts"
+            if npx semantic-release; then
+              echo "semantic-release succeeded"
+              exit 0
+            fi
+            if [ $attempt -eq $max_attempts ]; then
+              echo "semantic-release failed after $max_attempts attempts"
+              exit 1
+            fi
+            echo "Retrying in ${delay}s..."
+            sleep $delay
+            delay=$((delay * 2))
+            attempt=$((attempt + 1))
+          done
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_ADMIN_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/require-linked-issue.yml

@@ -0,0 +1,23 @@
+name: Require Linked Issue
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  issues: read
+  pull-requests: write
+
+jobs:
+  check-linked-issue:
+    runs-on: ubuntu-latest
+    name: Check linked issues
+    steps:
+      - uses: nearform-actions/github-action-check-linked-issues@v1
+        with:
+          exclude-branches: "dependabot/**"
+          custom-message: >-
+            This PR must be linked to a GitHub issue. Use 'Closes #123'
+            in the PR description, or link an issue from the sidebar.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,35 @@
+# Claude Code Project Instructions
+
+## Repository Workflow
+
+This repo enforces a strict governance workflow. Follow it exactly:
+
+1. **Create a GitHub issue** before making any changes
+2. **Create a feature branch** from `main` — never commit to `main` directly
+3. **Open a PR** that links to the issue using `Closes #N`
+4. **CI must pass** — the "Check linked issues" check blocks PRs without a linked issue
+5. **Merge** — squash merge preferred, branch auto-deletes after merge
+
+## Use the `/ship` Skill
+
+When available, use `/ship` to handle the full workflow (issue creation, branch, commit, PR) in one step.
+
+## Branch Naming
+
+Use the format `<prefix>/<issue-number>-short-description`:
+
+- `feature/42-add-grid-layout`
+- `fix/17-correct-animation`
+- `docs/8-update-guide`
+
+## Rules
+
+- Never push directly to `main`
+- Never force push
+- Every PR must link to an issue
+- Fill out the PR template completely
+- Follow conventional commit messages (`feat:`, `fix:`, `docs:`)
+
+## Reference
+
+Read `CONTRIBUTING.md` for full governance details.

package/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing
+
+This document describes the workflow and rules that all contributors — human and AI — must follow.
+
+## Workflow Overview
+
+Every change follows this path:
+
+```
+Issue → Branch → PR (linked to issue) → CI passes → Merge → Branch auto-deleted
+```
+
+No exceptions. PRs without a linked issue will be blocked by CI.
+
+## Step 1: Create an Issue
+
+Every change starts with a GitHub issue. Use one of the provided templates:
+
+- **Bug Report** — for bugs and unexpected behavior
+- **Feature Request** — for new features and improvements
+- **Documentation** — for docs improvements or missing content
+
+Blank issues are disabled. Pick the template that best fits your change.
+
+## Step 2: Create a Feature Branch
+
+Branch from `main` using one of these naming conventions:
+
+| Prefix | Use for | Example |
+|--------|---------|---------|
+| `feature/` | New features | `feature/42-add-grid-layout` |
+| `fix/` | Bug fixes | `fix/17-correct-animation-timing` |
+| `docs/` | Documentation | `docs/8-update-setup-guide` |
+
+Format: `<prefix>/<issue-number>-short-description`
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/42-add-grid-layout
+```
+
+## Step 3: Make Changes and Commit
+
+- Write small, focused commits
+- Use conventional commit messages:
+  - `feat: add grid layout support`
+  - `fix: correct animation timing`
+  - `docs: update setup guide`
+
+## Step 4: Open a Pull Request
+
+1. Push your branch and open a PR against `main`
+2. **Link the issue** — use `Closes #42` in the PR description, or link from the sidebar
+3. Fill out the PR template (it loads automatically)
+4. The **"Check linked issues"** CI check will block merge if no issue is linked
+
+## Step 5: Review and Merge
+
+- All CI checks must pass before merge
+- Auto-merge is enabled — PRs merge automatically once all checks pass
+- Squash merge is preferred
+- The branch is automatically deleted after merge (`delete_branch_on_merge` is enabled)
+
+## Branch Protection Rules
+
+The `main` branch is protected. The following rules are enforced:
+
+- No direct pushes to `main` — all changes go through PRs
+- No force pushes
+- Required status check: **"Check linked issues"** must pass
+- Admin enforcement enabled — these rules apply to everyone
+
+## AI Assistant Guidelines
+
+If you are Claude Code, Copilot, or another AI coding assistant, follow these rules:
+
+1. **Always create a GitHub issue before writing code.** No issue = no work.
+2. **Always work on a feature branch.** Never commit directly to `main`.
+3. **Always link the PR to the issue.** Use `Closes #N` in the PR description.
+4. **Use the `/ship` skill** when available — it handles the full Issue → Branch → PR flow.
+5. **Never force push** or attempt to bypass branch protection.
+6. **Fill out the PR template checklist** completely.
+7. **Follow the branch naming convention**: `feature/<issue>-desc`, `fix/<issue>-desc`, `docs/<issue>-desc`.
+8. **Respect CODEOWNERS** — `@robinmordasiewicz` is the default reviewer.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robin Mordasiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/components/Header.astro

@@ -0,0 +1,125 @@
+---
+import config from 'virtual:starlight/user-config';
+
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+import megaMenuConfig from 'virtual:starlight-mega-menu/config';
+import MegaMenu from './MegaMenu.tsx';
+import MegaMenuMobile from './MegaMenuMobile.tsx';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<div class="header sl-mega-menu-header">
+	<div class="title-wrapper sl-flex">
+		<SiteTitle />
+	</div>
+	<nav class="smm-desktop-nav">
+		<MegaMenu client:load config={megaMenuConfig} />
+	</nav>
+	<div class="sl-flex print:hidden">
+		{shouldRenderSearch && <Search />}
+	</div>
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<div class="sl-flex social-icons">
+			<SocialIcons />
+		</div>
+		<ThemeSelect />
+		<LanguageSelect />
+	</div>
+	<div class="smm-mobile-toggle">
+		<MegaMenuMobile client:load config={megaMenuConfig} />
+	</div>
+</div>
+
+<style>
+	@layer starlight.core {
+		.header {
+			display: flex;
+			gap: var(--sl-nav-gap);
+			justify-content: space-between;
+			align-items: center;
+			height: 100%;
+		}
+
+		.title-wrapper {
+			/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
+			overflow: clip;
+			/* Avoid clipping focus ring around link inside title wrapper. */
+			padding: 0.25rem;
+			margin: -0.25rem;
+			min-width: 0;
+		}
+
+		.right-group,
+		.social-icons {
+			gap: 1rem;
+			align-items: center;
+		}
+		.social-icons::after {
+			content: '';
+			height: 2rem;
+			border-inline-end: 1px solid var(--sl-color-gray-5);
+		}
+
+		/* Desktop nav is hidden on small screens */
+		.smm-desktop-nav {
+			display: none;
+		}
+
+		/* Mobile toggle is visible on small screens */
+		.smm-mobile-toggle {
+			display: flex;
+			align-items: center;
+		}
+
+		@media (min-width: 50rem) {
+			:global(:root[data-has-sidebar]) {
+				--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+			}
+			:global(:root:not([data-has-toc])) {
+				--__toc-width: 0rem;
+			}
+			.header {
+				--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+				--__main-column-fr: calc(
+					(
+							100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+								(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+								var(--sl-content-width)
+						) / 2
+				);
+				display: grid;
+				grid-template-columns:
+					/* 1 (site title) */
+					auto
+					/* 2 (mega-menu nav) */
+					1fr
+					/* 3 (search box) */
+					auto
+					/* 4 (right items) */
+					auto;
+				align-content: center;
+			}
+
+			/* Show desktop nav, hide mobile toggle */
+			.smm-desktop-nav {
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				min-width: 0;
+			}
+
+			.smm-mobile-toggle {
+				display: none;
+			}
+		}
+	}
+</style>

package/components/MegaMenu.tsx

@@ -0,0 +1,137 @@
+import * as NavigationMenu from '@radix-ui/react-navigation-menu';
+import type { MegaMenuConfig, MegaMenuPanel, MegaMenuCategory, MegaMenuLink as MegaMenuLinkType, MegaMenuFooter } from '../types';
+
+function ChevronDown({ className }: { className?: string }) {
+  return (
+    <svg
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      aria-hidden="true"
+    >
+      <path
+        d="M2.5 4.5L6 8L9.5 4.5"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function PanelContent({ panel }: { panel: MegaMenuPanel }) {
+  const layout = panel.layout ?? 'list';
+  const columns = panel.columns ?? 2;
+
+  return (
+    <div
+      className="smm-panel"
+      data-layout={layout}
+      style={layout === 'grid' ? { '--smm-columns': columns } as React.CSSProperties : undefined}
+    >
+      {panel.categories?.map((category) => (
+        <CategorySection key={category.title} category={category} />
+      ))}
+      {panel.footer && <PanelFooter footer={panel.footer} />}
+    </div>
+  );
+}
+
+function CategorySection({ category }: { category: MegaMenuCategory }) {
+  return (
+    <div className="smm-category">
+      <h3 className="smm-category-title">{category.title}</h3>
+      <ul className="smm-category-list">
+        {category.items.map((item) => (
+          <li key={item.href}>
+            <LinkItem item={item} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function LinkItem({ item }: { item: MegaMenuLinkType }) {
+  return (
+    <NavigationMenu.Link className="smm-menu-link" href={item.href}>
+      {item.icon && (
+        <span className="smm-link-icon" dangerouslySetInnerHTML={{ __html: item.icon }} />
+      )}
+      <span className="smm-link-text">
+        <span className="smm-link-label">{item.label}</span>
+        {item.description && (
+          <span className="smm-link-description">{item.description}</span>
+        )}
+      </span>
+    </NavigationMenu.Link>
+  );
+}
+
+function PanelFooter({ footer }: { footer: MegaMenuFooter }) {
+  return (
+    <div className="smm-panel-footer">
+      <NavigationMenu.Link className="smm-footer-link" href={footer.href}>
+        <span className="smm-footer-label">{footer.label}</span>
+        {footer.description && (
+          <span className="smm-footer-description">{footer.description}</span>
+        )}
+        <svg
+          className="smm-footer-arrow"
+          xmlns="http://www.w3.org/2000/svg"
+          width="14"
+          height="14"
+          viewBox="0 0 14 14"
+          fill="none"
+          aria-hidden="true"
+        >
+          <path
+            d="M1.75 7H12.25M12.25 7L7.875 2.625M12.25 7L7.875 11.375"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      </NavigationMenu.Link>
+    </div>
+  );
+}
+
+export default function MegaMenu({ config }: { config: MegaMenuConfig }) {
+  return (
+    <NavigationMenu.Root className="smm-root" delayDuration={200} skipDelayDuration={300}>
+      <NavigationMenu.List className="smm-list">
+        {config.items.map((item) =>
+          item.content ? (
+            <NavigationMenu.Item key={item.label} value={item.label}>
+              <NavigationMenu.Trigger className="smm-trigger">
+                {item.label}
+                <ChevronDown className="smm-chevron" />
+              </NavigationMenu.Trigger>
+              <NavigationMenu.Content className="smm-content">
+                <PanelContent panel={item.content} />
+              </NavigationMenu.Content>
+            </NavigationMenu.Item>
+          ) : (
+            <NavigationMenu.Item key={item.label}>
+              <NavigationMenu.Link className="smm-link" href={item.href}>
+                {item.label}
+              </NavigationMenu.Link>
+            </NavigationMenu.Item>
+          )
+        )}
+        <NavigationMenu.Indicator className="smm-indicator">
+          <div className="smm-arrow" />
+        </NavigationMenu.Indicator>
+      </NavigationMenu.List>
+      <div className="smm-viewport-wrapper">
+        <NavigationMenu.Viewport className="smm-viewport" />
+      </div>
+    </NavigationMenu.Root>
+  );
+}