enya-agent 0.1.0

package/docs/themes/tanuki/examples/book/content/chapter-4.md

@@ -0,0 +1,224 @@
++++
+title = "Chapter 4: Performance"
+description = "Optimizing web application performance."
+weight = 4
++++
+
+# Chapter 4: Performance
+
+Performance is a feature. Slow websites lose users, reduce conversions, and rank lower in search results. This chapter covers the key strategies for building fast web applications.
+
+## Understanding Performance Metrics
+
+Modern performance measurement focuses on user-centric metrics:
+
+| Metric | What It Measures | Target |
+|--------|------------------|--------|
+| **LCP** (Largest Contentful Paint) | Loading performance | < 2.5s |
+| **FID** (First Input Delay) | Interactivity | < 100ms |
+| **CLS** (Cumulative Layout Shift) | Visual stability | < 0.1 |
+| **TTFB** (Time to First Byte) | Server response | < 200ms |
+| **FCP** (First Contentful Paint) | Initial render | < 1.8s |
+
+## Optimizing Loading Performance
+
+### Critical Rendering Path
+
+The browser must complete several steps before rendering:
+
+1. Parse HTML → Build DOM
+2. Parse CSS → Build CSSOM
+3. Combine → Render Tree
+4. Layout → Paint → Composite
+
+```html
+<!-- Inline critical CSS -->
+<style>
+    /* Only what's needed for above-the-fold content */
+    body { font-family: system-ui; }
+    .hero { height: 100vh; }
+</style>
+
+<!-- Defer non-critical CSS -->
+<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+```
+
+### Resource Hints
+
+Tell the browser about resources you'll need:
+
+```html
+<!-- DNS prefetch for external origins -->
+<link rel="dns-prefetch" href="//api.example.com">
+
+<!-- Preconnect for critical third parties -->
+<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>
+
+<!-- Preload critical resources -->
+<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
+
+<!-- Prefetch likely next pages -->
+<link rel="prefetch" href="/about">
+```
+
+## Image Optimization
+
+Images are often the largest assets on a page.
+
+### Modern Formats
+
+```html
+<picture>
+    <source srcset="image.avif" type="image/avif">
+    <source srcset="image.webp" type="image/webp">
+    <img src="image.jpg" alt="Description" loading="lazy">
+</picture>
+```
+
+### Responsive Images
+
+```html
+<img
+    srcset="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
+    sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
+    src="medium.jpg"
+    alt="Description"
+    loading="lazy"
+    decoding="async"
+>
+```
+
+## JavaScript Performance
+
+### Code Splitting
+
+Load only what's needed:
+
+```javascript
+// Dynamic imports
+const module = await import('./heavy-module.js');
+
+// Route-based splitting (framework example)
+const routes = {
+    '/': () => import('./pages/Home.js'),
+    '/about': () => import('./pages/About.js'),
+    '/dashboard': () => import('./pages/Dashboard.js'),
+};
+```
+
+### Debouncing and Throttling
+
+Control how often functions execute:
+
+```javascript
+// Debounce: wait until action stops
+function debounce(fn, delay) {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => fn(...args), delay);
+    };
+}
+
+// Throttle: limit execution rate
+function throttle(fn, limit) {
+    let inThrottle;
+    return (...args) => {
+        if (!inThrottle) {
+            fn(...args);
+            inThrottle = true;
+            setTimeout(() => inThrottle = false, limit);
+        }
+    };
+}
+
+// Usage
+const handleScroll = throttle(() => {
+    console.log('Scroll position:', window.scrollY);
+}, 100);
+
+window.addEventListener('scroll', handleScroll);
+```
+
+### Web Workers
+
+Offload heavy computation:
+
+```javascript
+// main.js
+const worker = new Worker('worker.js');
+
+worker.postMessage({ data: largeArray });
+
+worker.onmessage = (event) => {
+    console.log('Result:', event.data);
+};
+
+// worker.js
+self.onmessage = (event) => {
+    const result = heavyComputation(event.data);
+    self.postMessage(result);
+};
+```
+
+## Caching Strategies
+
+### Service Worker Caching
+
+```javascript
+// sw.js
+const CACHE_NAME = 'v1';
+const ASSETS = [
+    '/',
+    '/styles.css',
+    '/app.js',
+    '/offline.html',
+];
+
+self.addEventListener('install', (event) => {
+    event.waitUntil(
+        caches.open(CACHE_NAME)
+            .then(cache => cache.addAll(ASSETS))
+    );
+});
+
+self.addEventListener('fetch', (event) => {
+    event.respondWith(
+        caches.match(event.request)
+            .then(response => response || fetch(event.request))
+    );
+});
+```
+
+## Measuring Performance
+
+Use the Performance API:
+
+```javascript
+// Measure custom timings
+performance.mark('start-operation');
+
+// ... do work ...
+
+performance.mark('end-operation');
+performance.measure('operation', 'start-operation', 'end-operation');
+
+// Get measurements
+const measures = performance.getEntriesByName('operation');
+console.log(`Operation took ${measures[0].duration}ms`);
+```
+
+## Summary
+
+Performance optimization requires attention to:
+
+- Core Web Vitals (LCP, FID, CLS)
+- Critical rendering path optimization
+- Image optimization and modern formats
+- JavaScript code splitting and async loading
+- Effective caching strategies
+- Continuous measurement and monitoring
+
+> **Golden Rule**: Measure first, optimize second. Don't guess where performance problems are—use real data from real users.
+
+In our final chapter, we'll cover accessibility and inclusive design.

package/docs/themes/tanuki/examples/book/content/chapter-5.md

@@ -0,0 +1,297 @@
++++
+title = "Chapter 5: Accessibility"
+description = "Building inclusive web experiences for everyone."
+weight = 5
++++
+
+# Chapter 5: Accessibility
+
+Accessibility (often abbreviated as a11y) ensures that websites work for everyone, including people with disabilities. It's not just about compliance—it's about creating better experiences for all users.
+
+## Why Accessibility Matters
+
+Consider these statistics:
+
+- ~15% of the world's population has some form of disability
+- Many more have temporary or situational impairments
+- Accessible sites often have better SEO and usability for everyone
+
+> **Remember**: Accessibility is a spectrum, not a checkbox. Every improvement helps.
+
+## Semantic HTML
+
+The foundation of accessibility is semantic HTML:
+
+```html
+<!-- Bad: Divs for everything -->
+<div class="header">
+    <div class="nav">
+        <div class="nav-item">Home</div>
+    </div>
+</div>
+
+<!-- Good: Semantic elements -->
+<header>
+    <nav aria-label="Main navigation">
+        <a href="/">Home</a>
+    </nav>
+</header>
+```
+
+### Key Semantic Elements
+
+| Element | Purpose |
+|---------|---------|
+| `<header>` | Introductory content |
+| `<nav>` | Navigation links |
+| `<main>` | Primary content |
+| `<article>` | Self-contained content |
+| `<section>` | Thematic grouping |
+| `<aside>` | Tangentially related content |
+| `<footer>` | Footer content |
+
+## ARIA: When HTML Isn't Enough
+
+ARIA (Accessible Rich Internet Applications) enhances semantics:
+
+```html
+<!-- Role: Define what an element is -->
+<div role="dialog" aria-labelledby="dialog-title">
+    <h2 id="dialog-title">Confirm Action</h2>
+    <p>Are you sure you want to proceed?</p>
+</div>
+
+<!-- State: Communicate dynamic changes -->
+<button aria-expanded="false" aria-controls="menu">
+    Open Menu
+</button>
+<ul id="menu" hidden>...</ul>
+
+<!-- Properties: Provide additional context -->
+<input
+    type="search"
+    aria-label="Search products"
+    aria-describedby="search-help"
+>
+<p id="search-help">Enter product name or SKU</p>
+```
+
+### Common ARIA Patterns
+
+```html
+<!-- Live regions: Announce dynamic content -->
+<div aria-live="polite" aria-atomic="true">
+    Item added to cart
+</div>
+
+<!-- Error messages -->
+<input
+    type="email"
+    aria-invalid="true"
+    aria-describedby="email-error"
+>
+<p id="email-error" role="alert">
+    Please enter a valid email address
+</p>
+```
+
+## Keyboard Navigation
+
+All functionality must be accessible via keyboard:
+
+```javascript
+// Custom keyboard navigation
+document.addEventListener('keydown', (event) => {
+    const { key } = event;
+
+    switch (key) {
+        case 'Escape':
+            closeModal();
+            break;
+        case 'ArrowDown':
+            focusNextItem();
+            event.preventDefault();
+            break;
+        case 'ArrowUp':
+            focusPreviousItem();
+            event.preventDefault();
+            break;
+    }
+});
+```
+
+### Focus Management
+
+```css
+/* Never hide focus entirely */
+:focus {
+    outline: 2px solid var(--color-focus);
+    outline-offset: 2px;
+}
+
+/* Use :focus-visible for mouse users */
+:focus:not(:focus-visible) {
+    outline: none;
+}
+
+:focus-visible {
+    outline: 2px solid var(--color-focus);
+}
+```
+
+```javascript
+// Manage focus when content changes
+function openModal() {
+    modal.hidden = false;
+    modal.querySelector('[autofocus]').focus();
+}
+
+function closeModal() {
+    modal.hidden = true;
+    triggerButton.focus(); // Return focus to trigger
+}
+```
+
+## Color and Contrast
+
+Ensure sufficient color contrast:
+
+| Context | Minimum Ratio (WCAG AA) |
+|---------|-------------------------|
+| Normal text | 4.5:1 |
+| Large text (18px+ bold, 24px+) | 3:1 |
+| UI components | 3:1 |
+
+```css
+/* Good contrast */
+.text {
+    color: #1a1a1a;
+    background: #ffffff;
+    /* Contrast ratio: 16.1:1 */
+}
+
+/* Don't rely on color alone */
+.error {
+    color: #dc2626;
+    border-left: 4px solid #dc2626;
+}
+
+.error::before {
+    content: "⚠ Error: ";
+    font-weight: bold;
+}
+```
+
+## Images and Media
+
+```html
+<!-- Informative images need alt text -->
+<img src="chart.png" alt="Sales increased 25% in Q4 2024">
+
+<!-- Decorative images should be hidden -->
+<img src="decorative.svg" alt="" role="presentation">
+
+<!-- Complex images need longer descriptions -->
+<figure>
+    <img src="diagram.png" alt="System architecture diagram" aria-describedby="diagram-desc">
+    <figcaption id="diagram-desc">
+        The system consists of three main components:
+        the API gateway, the processing service, and the database layer...
+    </figcaption>
+</figure>
+
+<!-- Video with captions -->
+<video controls>
+    <source src="tutorial.mp4" type="video/mp4">
+    <track kind="captions" src="captions.vtt" srclang="en" label="English">
+</video>
+```
+
+## Forms
+
+Accessible forms are crucial:
+
+```html
+<form>
+    <div class="field">
+        <label for="name">Full Name *</label>
+        <input
+            type="text"
+            id="name"
+            name="name"
+            required
+            aria-required="true"
+            autocomplete="name"
+        >
+    </div>
+
+    <fieldset>
+        <legend>Notification Preferences</legend>
+
+        <div>
+            <input type="checkbox" id="email-notify" name="notify" value="email">
+            <label for="email-notify">Email notifications</label>
+        </div>
+
+        <div>
+            <input type="checkbox" id="sms-notify" name="notify" value="sms">
+            <label for="sms-notify">SMS notifications</label>
+        </div>
+    </fieldset>
+
+    <button type="submit">Subscribe</button>
+</form>
+```
+
+## Testing for Accessibility
+
+### Automated Testing
+
+```javascript
+// Example with axe-core
+import { axe } from 'axe-core';
+
+async function runAccessibilityTests() {
+    const results = await axe.run();
+    console.log('Violations:', results.violations);
+}
+```
+
+### Manual Testing Checklist
+
+- [ ] Navigate the entire page using only keyboard
+- [ ] Test with a screen reader (VoiceOver, NVDA)
+- [ ] Zoom to 200% and verify layout
+- [ ] Check with Windows High Contrast mode
+- [ ] Verify all images have appropriate alt text
+- [ ] Confirm form errors are announced
+
+## Summary
+
+Building accessible websites requires:
+
+- Semantic HTML as the foundation
+- ARIA for enhanced semantics where needed
+- Full keyboard navigation support
+- Sufficient color contrast
+- Alternative text for images
+- Accessible forms with proper labeling
+- Regular testing with assistive technologies
+
+> **Final Thought**: Accessibility benefits everyone. Curb cuts help wheelchair users, but also parents with strollers, travelers with luggage, and delivery workers with carts. Digital accessibility works the same way.
+
+---
+
+## Conclusion
+
+Congratulations on completing "The Art of Web Development"! You've learned:
+
+1. The foundational triad of HTML, CSS, and JavaScript
+2. Modern CSS layout techniques with Flexbox and Grid
+3. JavaScript essentials for interactive applications
+4. Performance optimization strategies
+5. Accessibility best practices for inclusive design
+
+The web is constantly evolving, but these fundamentals remain constant. Master them, and you'll be prepared for whatever comes next.
+
+Happy coding!

package/docs/themes/tanuki/examples/book/content/print.md

@@ -0,0 +1,6 @@
++++
+title = "Print Version"
+template = "print.html"
+weight = 999
+render = true
++++

package/docs/themes/tanuki/examples/docs/config.toml

@@ -0,0 +1,28 @@
+# Tanuki Theme - Documentation Mode Example
+base_url = "/tanuki/docs"
+title = "Acme SDK"
+description = "Official documentation for the Acme SDK"
+theme = "tanuki"
+compile_sass = true
+build_search_index = true
+generate_feeds = false
+
+[markdown]
+highlight_code = true
+highlight_theme = "css"
+insert_anchor_links = "left"
+
+[extra]
+mode = "docs"
+github = "https://github.com/raskell-io/tanuki"
+edit_url = "https://github.com/raskell-io/tanuki/edit/main/examples/docs/content"
+show_theme_toggle = true
+
+# Version picker (docs mode only)
+[extra.versions]
+current = "1.2.0"
+list = [
+    { version = "1.2.0", url = "/tanuki/docs/", label = "latest" },
+    { version = "1.1.0", url = "/tanuki/docs/v1.1/" },
+    { version = "1.0.0", url = "/tanuki/docs/v1.0/" },
+]

package/docs/themes/tanuki/examples/docs/content/_index.md

@@ -0,0 +1,20 @@
++++
+title = "Documentation"
+description = "Official documentation for the Acme SDK."
+sort_by = "weight"
+template = "section.html"
++++
+
+# Acme SDK Documentation
+
+Welcome to the official Acme SDK documentation. This guide covers everything you need to know to build powerful applications with Acme.
+
+> **You're viewing docs for v1.2.0** — Use the version picker above to switch between releases.
+
+## What's New in 1.2.0
+
+- **Async Support**: All API methods now support async/await
+- **Improved Performance**: 40% faster response times
+- **New Widgets API**: Build custom UI components
+
+See the [full changelog](https://github.com/acme/sdk/releases) for details.