Arod Web Components Library#

A collection of modern, accessible web components for building content-rich websites with semantic HTML.

Components#

🗂️ Navigation Menu (arod-menu)#

A responsive navigation menu with mobile support and customizable branding.

Features:

• Responsive hamburger menu on mobile
• Active item highlighting
• Customizable logo/brand
• Action slots for search and theme toggle

🔍 Search Modal (arod-search)#

An expandable search interface with keyboard shortcuts and real-time results.

Features:

• Keyboard shortcut (⌘K / Ctrl+K) to open
• Real-time search with debouncing
• Keyboard navigation (arrow keys + enter)
• Customizable result display
• Event-based integration with any search backend

🎨 Theme Toggle (arod-theme)#

A theme switcher supporting light, dark, and system preferences.

Features:

• Light/Dark/System modes
• Persists preference in localStorage
• Respects system preferences
• Updates all components automatically
• Smooth transitions

📝 Sidenotes (article-sidenotes)#

A sophisticated sidenote system for rich annotations and margin notes.

Features:

• Automatic numbering
• Responsive: margin notes on desktop, inline on mobile
• Bidirectional hover highlighting
• Support for rich content (images, code blocks)
• Semantic HTML structure

Installation#

1. Copy the arod/ directory to your project
2. Include the component scripts you need:

<script src="arod/arod-menu.js"></script>
<script src="arod/arod-search.js"></script>
<script src="arod/arod-theme.js"></script>
<script src="arod/arod-sidenotes.js"></script>

Usage Examples#

Basic Navigation Setup#

<arod-menu>
  <menu-item href="/home">Home</menu-item>
  <menu-item href="/docs">Documentation</menu-item>
  <menu-item href="/about">About</menu-item>

  <arod-search slot="actions"></arod-search>
  <arod-theme slot="actions"></arod-theme>
</arod-menu>

Sidenotes in Articles#

<article-sidenotes>
  <p>
    Your article text with a reference<sidenote-ref for="note1"></sidenote-ref>
    to additional information.
  </p>

  <side-note id="note1">
    This appears in the margin on desktop and inline on mobile.
  </side-note>
</article-sidenotes>

Search Integration#

const search = document.querySelector('arod-search');

search.addEventListener('search', async (e) => {
  const query = e.detail.query;

  // Fetch results from your search backend
  const results = await fetchSearchResults(query);

  // Display results in the search modal
  search.displayResults(results);
});

Theme Integration#

// Listen for theme changes
document.querySelector('arod-theme').addEventListener('theme-change', (e) => {
  console.log('Theme changed to:', e.detail.theme);
  // Update any non-Arod components if needed
});

Styling#

Components use CSS custom properties for theming:

:root {
  --accent: #0066cc;
  --bg: #ffffff;
  --text: #222;
  --text-muted: #666;
  --border: #e0e0e0;
}

[data-theme="dark"] {
  --bg: #1a1a1a;
  --text: #e0e0e0;
  --text-muted: #999;
  --accent: #4db8ff;
  --border: #444;
}

Browser Support#

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Web Components APIs are required. Consider polyfills for older browsers.

Component Details#

Arod Menu Events#

• None (navigation handled via standard links)

Arod Search Events#

• search: Fired when user types (debounced)
• clear: Fired when search is cleared

Arod Theme Events#

• theme-change: Fired when theme changes

Article Sidenotes Events#

• sidenote-hover: Internal event for highlighting
• ref-hover: Internal event for highlighting

Architecture#

All components:

• Use Shadow DOM for style encapsulation
• Follow semantic HTML principles
• Support keyboard navigation
• Are ARIA compliant
• Work independently or together
• Use custom elements v1 specification

Examples#

See example.html for a complete working demo of all components.

License#

MIT

Contributing#

Contributions welcome! Please ensure new components:

• Follow the arod-[name] naming convention
• Use Shadow DOM for encapsulation
• Emit appropriate custom events
• Include keyboard support
• Are accessible (ARIA labels, roles, etc.)
• Work independently of other components