lightview 1.8.2 → 2.0.0

package/docs/router.html

@@ -0,0 +1,285 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+<div class="section">
+    <div class="section-content" style="max-width: 800px;">
+        <h1>Lightview Router</h1>
+        <p class="text-secondary" style="font-size: 1.125rem;">
+            A lightweight, pipeline-based History API router with middleware support.
+        </p>
+
+        <h2>Overview</h2>
+        <p>
+            The Lightview Router provides a simple yet powerful way to handle client-side routing in your application.
+            It supports standard routes, wildcards, named parameters, and middleware pipelines.
+        </p>
+
+        <h3>Features</h3>
+        <ul>
+            <li>Pipeline-based routing (middleware style)</li>
+            <li>History API integration</li>
+            <li>Zero dependencies</li>
+            <li>Route parameters <code>/user/:id</code></li>
+            <li>Wildcard support <code>/api/*</code></li>
+            <li>Async handler support</li>
+            <li>Locale prefix handling</li>
+            <li>Markdown rendering</li>
+        </ul>
+
+        <h2>Basic Usage</h2>
+        <p>Initialize the router with a target element and define your routes.</p>
+
+        <div class="code-block">
+            <pre><code>import { LightviewRouter } from '/lightview-router.js';
+
+// 1. Initialize
+const appRouter = LightviewRouter.router({
+    contentEl: document.getElementById('app'), // Routes will render here automatically
+    
+    // Optional: Lifecycle hooks
+    // onStart: (path) => console.log('Loading...'),
+    // notFound: (path) => console.log('404 Not Found')
+});
+
+// 2. Register routes
+// Simple path mapping (fetches /index.html -> renders to #app)
+appRouter.use('/', '/index.html');
+
+// Self-mapping (fetches /about.html -> renders to #app)
+appRouter.use('/about.html');
+
+// Wildcards (fetches matching path -> renders to #app)
+appRouter.use('/docs/*');
+
+// 3. Start listening
+appRouter.start();</code></pre>
+        </div>
+
+        <h2>Middleware & Pipelines</h2>
+        <p>
+            Lightview Router uses a "chain of responsibility" pattern. When you register a route, you can provide
+            multiple handlers.
+        </p>
+        <p>
+            <strong>Automatic Rendering:</strong> If you provide <code>contentEl</code> and your route chain ends with a
+            string (or has no handlers),
+            the router automatically appends a handler that fetches the path and renders it to <code>contentEl</code>.
+        </p>
+        <p>
+            You can still define manual handlers for advanced logic:
+        </p>
+
+        <div class="feature-grid" style="margin: 2rem 0;">
+            <div class="feature-card">
+                <h3 class="feature-title">➡️ Continue Chain</h3>
+                <p>
+                    If a handler returns <strong>null</strong>, <strong>undefined</strong>, or a <strong>context
+                        object</strong>, the router continues to the next handler in the chain.
+                </p>
+                <p class="text-secondary" style="font-size: 0.875rem;">Use this for logging, auth checks, or
+                    transforming the path.</p>
+                <pre style="margin-top: 1rem;"><code>// Middleware
+const logger = (ctx) => {
+    console.log('Visiting:', ctx.path);
+    // Returns undefined, so routing continues
+};</code></pre>
+            </div>
+            <div class="feature-card">
+                <h3 class="feature-title">🛑 Stop & Return</h3>
+                <p>
+                    If a handler returns a <strong>Response</strong> object, the chain stops immediately, and the router
+                    considers the navigation complete.
+                </p>
+                <p class="text-secondary" style="font-size: 0.875rem;">Use this for custom API responses or redirects.
+                </p>
+                <pre style="margin-top: 1rem;"><code>// Final Handler
+const loadPage = async (ctx) => {
+    return await fetch(ctx.path);
+    // Returns Response, stops routing
+};</code></pre>
+            </div>
+        </div>
+
+        <h3>Example Pipeline</h3>
+        <div class="code-block">
+            <pre><code>appRouter.use('/admin/*', 
+    // 1. Authentication Middleware
+    (ctx) => {
+        if (!user.isLoggedIn) {
+            router.navigate('/login'); 
+            return new Response('Redirecting...'); // Stop chain
+        }
+        // User is logged in, continue...
+    },
+    
+    // 2. Logging Middleware
+    (ctx) => {
+        console.log('Admin access at', new Date());
+        // implicitly returns undefined, continues...
+    },
+
+    // 3. Implicit Fetch (if contentEl is set)
+    // The router automatically fetches /admin/* and renders it
+);</code></pre>
+        </div>
+
+        <h2>Advanced Usage</h2>
+
+        <h3>Functional Arguments</h3>
+        <p>
+            The <code>use(...)</code> method accepts a variadic list of arguments. While standard usage involves strings
+            for
+            matching and replacement, you can pass functions for any argument to achieve fine-grained control.
+        </p>
+        <p>
+            Internally, all strings and regexes are converted to functions. Passing a function directly gives you access
+            to the raw context pipeline.
+        </p>
+
+        <h3>Anatomy of a <code>use()</code> call</h3>
+        <p>
+            <code>appRouter.use(Matcher, ...Middleware);</code>
+        </p>
+        <ul>
+            <li><strong>Matcher (Arg 0):</strong> Determines if this chain runs. Returns a context object (continue) or
+                null (skip).</li>
+            <li><strong>Middleware (Args 1...n):</strong> Logic that executes if the matcher succeeds.</li>
+        </ul>
+
+        <div class="code-block">
+            <pre><code>appRouter.use(
+    // Argument 1: The Matcher
+    // Can be a string '/path', regex /path/, or function
+    (ctx) => {
+        // Custom matching logic
+        if (ctx.path.includes('secret') && user.isAdmin) {
+            return ctx; // Match!
+        }
+        return null; // No match, try next route
+    },
+
+    // Argument 2: Middleware / Logic
+    (ctx) => {
+        console.log('Secret route accessed');
+        // Modify the context for the next handler
+        return { ...ctx, path: '/admin/secret.html' };
+    }
+    // Note: If no implementation is provided and contentEl is set, 
+    // the router automatically appends a fetch handler for the final path.
+);</code></pre>
+        </div>
+
+        <h2>API Reference</h2>
+
+        <h3><code>LightviewRouter.router(options)</code></h3>
+        <p>Creates a new router instance.</p>
+        <p><strong>Options:</strong></p>
+        <ul>
+            <li><code>contentEl</code> (HTMLElement): Element to automatically render content into.</li>
+            <li><code>base</code> (string): Base path for the router.</li>
+            <li><code>onStart</code> (function): Callback when navigation begins.</li>
+            <li><code>onResponse</code> (function): Callback when a handler returns a response.</li>
+        </ul>
+
+        <h2>Built-in Middleware</h2>
+
+        <h3><code>localeHandler(ctx)</code></h3>
+        <p>
+            Extracts locale prefixes (e.g., <code>/en/about</code>) from the path. It modifies the context
+            by stripping the prefix (<code>/about</code>) and adding a <code>locale</code> property.
+        </p>
+        <p><strong>Usage:</strong> Add it early in your chain so subsequent handlers see the clean path.</p>
+        <div class="code-block">
+            <pre><code>import { localeHandler } from '/middleware/locale.js';
+
+appRouter.use('/*', localeHandler);
+
+// If user visits /en/about:
+// 1. localeHandler strips /en/, sets ctx.locale = 'en'
+// 2. Next handlers see ctx.path = '/about'</code></pre>
+        </div>
+
+        <h3><code>markdownHandler(ctx)</code></h3>
+        <p>
+            Intercepts requests for <code>.md</code> files, fetches the content, parses it using <code>marked.js</code>
+            (loaded on demand), and renders the resulting HTML.
+        </p>
+        <p><strong>Returns:</strong> A <code>Response</code> object (stops the route chain).</p>
+        <div class="code-block">
+            <pre><code>import { markdownHandler } from '/middleware/markdown.js';
+
+// Handle all markdown files
+appRouter.use('/*.md', markdownHandler);</code></pre>
+        </div>
+
+        <h3><code>notFound(options)</code></h3>
+        <p>A final middleware that handles 404 errors when no other route matches.</p>
+        <p><strong>Usage:</strong> Add it as the very last route in your configuration.</p>
+
+        <div class="code-block">
+            <pre><code>import { notFound } from '/middleware/notFound.js';
+
+appRouter.use(notFound({
+    // contentEl: inherited from router options,
+    html: '&lt;h1&gt;404 Not Found&lt;/h1&gt;' // Optional custom HTML
+}));</code></pre>
+        </div>
+
+        <h3><code>router.use(pattern, ...handlers)</code></h3>
+        <p>Registers a route or middleware.</p>
+
+        <p><strong>Pattern types:</strong></p>
+        <ul>
+            <li><strong>String literal:</strong> <code>'/about'</code> - Exact match.</li>
+            <li><strong>Wildcard:</strong> <code>'/api/*'</code> - Matches any path starting with /api/.</li>
+            <li><strong>Parameter:</strong> <code>'/user/:id'</code> - Captures <code>:id</code> as a parameter.</li>
+        </ul>
+
+        <h3><code>router.navigate(path)</code></h3>
+        <p>Programmatically navigate to a new path.</p>
+        <div class="code-block">
+            <pre><code>router.navigate('/profile/settings');</code></pre>
+        </div>
+
+        <h3>Context Object</h3>
+        <p>Handlers receive a <code>context</code> object containing:</p>
+        <ul>
+            <li><code>path</code>: The current normalized path.</li>
+            <li><code>params</code>: Object containing named parameters (if any).</li>
+            <li><code>wildcard</code>: Content of the wildcard match (if any).</li>
+            <li><code>contentEl</code>: The main content element (allows middleware to render content or override the
+                target).</li>
+        </ul>
+
+        <h2>Advanced Configuration</h2>
+        <p>
+            The <code>router()</code> constructor accepts an options object for lifecycle hooks and error handling.
+        </p>
+
+        <div class="code-block">
+            <pre><code>const appRouter = LightviewRouter.router({
+    contentEl: document.getElementById('app'),
+
+    // Lifecycle: Called when navigation triggers (e.g., click or back button)
+    // Good for starting loading spinners
+    onStart: (path) => {
+        document.getElementById('spinner').style.display = 'block';
+    },
+
+    // Lifecycle: Called AFTER auto-render completes
+    // Good for post-render logic like analytics or scroll position
+    onResponse: (response, path) => {
+        document.getElementById('spinner').style.display = 'none';
+        window.scrollTo(0, 0);
+        // Run additional logic here (analytics, etc.)
+    }
+});</code></pre>
+        </div>
+
+    </div>
+</div>

package/docs/styles/index.html

@@ -0,0 +1,190 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+<div class="section">
+    <div class="section-content" style="max-width: 1000px;">
+        <h1>Styles</h1>
+        <p class="text-lg opacity-70 mb-6">
+            Lightview components use <strong>DaisyUI</strong> for styling — a complete component library
+            built on top of Tailwind CSS with 12+ themes and 50+ components.
+        </p>
+
+        <!-- (DaisyUI Styles removed to prevent global conflicts. Content below uses Shadow DOM isolation) -->
+
+        <!-- Include DaisyUI -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Including DaisyUI</h2>
+            <p class="opacity-70 mb-4">DaisyUI and Tailwind pollute the global CSS space and redefine things like H1. By
+                default Lightview components isolate DaisyUI and Tailwind styles to Shadow DOM. If you would like to
+                use DaisyUI and Tailwind styles outside of Shadow DOM, add DaisyUI and Tailwind to your HTML:</p>
+            <pre class="bg-base-300 p-4 rounded-lg text-sm overflow-x-auto"><code>&lt;!-- DaisyUI + Tailwind CSS (CDN) --&gt;
+&lt;link href="https://cdn.jsdelivr.net/npm/daisyui@3.9.4/dist/full.min.css" rel="stylesheet" type="text/css" /&gt;
+&lt;script src="https://cdn.tailwindcss.com"&gt;&lt;/script&gt;</code></pre>
+        </section>
+
+        <!-- Themes -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Themes</h2>
+            <p class="opacity-70 mb-4">DaisyUI includes many built-in themes. You can try these themes by selecting a
+                theme using the dropdown in the top right corner of this page. This will impact the theme colors
+                globally across all components.</p>
+        </section>
+
+        <!-- Theme Colors Preview (Using Lightview Components) -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Theme Colors</h2>
+            <p class="opacity-70 mb-4">Each theme provides semantic color variables. Here is how they look in the
+                current theme:</p>
+            <div id="theme-colors-preview" class="mb-6"></div>
+        </section>
+
+        <!-- Base Colors (Using Reactive Cards) -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Base Colors</h2>
+            <p class="opacity-70 mb-4">Background and surface colors for consistent UI in the current theme:</p>
+            <div id="base-colors-preview" class="mb-6"></div>
+        </section>
+
+        <script type="module">
+            await import('/components/actions/button.js');
+            await import('/components/data-display/card.js');
+
+            // Wait for Lightview if loaded async
+            const init = () => {
+                if (!window.Lightview) return setTimeout(init, 50);
+
+                const { tags, $ } = Lightview;
+                const { div, span, p, Button, Card } = tags;
+
+                // Render Theme Colors Buttons
+                $('#theme-colors-preview').content(
+                    div({ style: 'display: flex; flex-wrap: wrap; gap: 0.5rem;' },
+                        Button({ color: 'primary' }, 'Primary'),
+                        Button({ color: 'secondary' }, 'Secondary'),
+                        Button({ color: 'accent' }, 'Accent'),
+                        Button({ color: 'neutral' }, 'Neutral'),
+                        Button({ color: 'info' }, 'Info'),
+                        Button({ color: 'success' }, 'Success'),
+                        Button({ color: 'warning' }, 'Warning'),
+                        Button({ color: 'error' }, 'Error')
+                    )
+                );
+
+                // Render Base Colors using actual Card components
+                const cardStyle = 'text-align: center;';
+
+                $('#base-colors-preview').content(
+                    div({ style: 'display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 1.5rem;' },
+                        Card({ bg: 'base-100', useShadow: true, class: 'border border-base-300' },
+                            Card.Body({ style: 'align-items: center; text-align: center;' },
+                                Card.Title({ style: 'font-size: 1rem;' }, 'base-100'),
+                                p({ style: 'font-size: 0.875rem; opacity: 0.7;' }, 'Main Background')
+                            )
+                        ),
+                        Card({ bg: 'base-200', useShadow: true },
+                            Card.Body({ style: 'align-items: center; text-align: center;' },
+                                Card.Title({ style: 'font-size: 1rem;' }, 'base-200'),
+                                p({ style: 'font-size: 0.875rem; opacity: 0.7;' }, 'Secondary')
+                            )
+                        ),
+                        Card({ bg: 'base-300', useShadow: true },
+                            Card.Body({ style: 'align-items: center; text-align: center;' },
+                                Card.Title({ style: 'font-size: 1rem;' }, 'base-300'),
+                                p({ style: 'font-size: 0.875rem; opacity: 0.7;' }, 'Tertiary')
+                            )
+                        ),
+                        Card({ bg: 'base-content', class: 'text-base-100', useShadow: true },
+                            Card.Body({ style: 'align-items: center; text-align: center;' },
+                                Card.Title({ style: 'font-size: 1rem;' }, 'base-content'),
+                                p({ style: 'font-size: 0.875rem; opacity: 0.7;' }, 'Content/Text')
+                            )
+                        )
+                    )
+                );
+            };
+
+            init();
+        </script>
+
+        <!-- Registering Stylesheets -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Registering Stylesheets</h2>
+            <p class="opacity-70 mb-4">
+                When using Shadow DOM, global styles are not inherited. <code>LightviewX</code> provides methods to
+                register stylesheets that can be adopted by components or applied globally to all components.
+            </p>
+
+            <h3 class="text-xl font-bold mb-2">Named Stylesheets</h3>
+            <p class="opacity-70 mb-4">
+                Register a stylesheet by name, and components can then request it by ID. You can register styles from a
+                string, a URL, or an existing <code>&lt;style&gt;</code> tag.
+            </p>
+            <pre class="bg-base-300 p-4 rounded-lg text-sm overflow-x-auto mb-6"><code>// From a CSS string
+LightviewX.registerStyleSheet('custom-vars', ':host { --my-color: #ff00ff; }');
+
+// From a URL
+LightviewX.registerStyleSheet('/styles/extra.css');
+
+// From an existing style tag in the document
+LightviewX.registerStyleSheet('#global-overrides');</code></pre>
+
+            <h3 class="text-xl font-bold mb-2">Global Theme Stylesheets</h3>
+            <p class="opacity-70 mb-4">
+                To apply a stylesheet to every Shadow DOM component automatically (like a global theme override),
+                use <code>registerThemeSheet</code>.
+            </p>
+            <pre class="bg-base-300 p-4 rounded-lg text-sm overflow-x-auto mb-6"><code>// This sheet will be adopted by all components
+LightviewX.registerThemeSheet('/styles/theme-overrides.css');</code></pre>
+
+            <p class="opacity-70">
+                For more details on these functions, see the <a href="../api/" class="link">API Reference</a>.
+            </p>
+        </section>
+
+        <!-- Controlling Themes -->
+        <section class="mb-12">
+            <h2 class="text-2xl font-bold mb-4">Controlling Themes Programmatically</h2>
+            <p class="opacity-70 mb-4">You can control the active theme globally using <code>LightviewX</code>.</p>
+
+            <h3 class="text-xl font-bold mb-2">Setting the Theme</h3>
+            <p class="opacity-70 mb-4">Use <code>setTheme</code> to change the active theme. This updates the
+                <code>themeSignal</code> and persists the choice to LocalStorage.
+            </p>
+            <pre class="bg-base-300 p-4 rounded-lg text-sm overflow-x-auto mb-6"><code>// Set theme to 'dark'
+LightviewX.setTheme('dark');
+
+// Set theme to 'cyberpunk'
+LightviewX.setTheme('cyberpunk');</code></pre>
+
+            <h3 class="text-xl font-bold mb-2">Reactive Theme Signal</h3>
+            <p class="opacity-70 mb-4">Access the current theme reactively using <code>LightviewX.themeSignal</code>.
+            </p>
+            <pre class="bg-base-300 p-4 rounded-lg text-sm overflow-x-auto"><code>const { themeSignal } = LightviewX;
+
+// Build a reactive component that logs the theme
+const ThemeLogger = () => {
+    return div({}, () => `Current theme is: ${themeSignal.value}`);
+};</code></pre>
+        </section>
+
+        <!-- DaisyUI Documentation Link -->
+        <div class="alert alert-info">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+                class="h-6 w-6 shrink-0 stroke-current">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                    d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path>
+            </svg>
+            <div>
+                <h3 class="font-bold">Full DaisyUI Documentation</h3>
+                <div class="text-sm">For complete styling options, themes, and utilities, visit the
+                    <a href="https://daisyui.com" target="_blank" rel="noopener" class="link">DaisyUI documentation</a>.
+                </div>
+            </div>
+        </div>
+    </div>
+</div>

package/functions/_middleware.js

@@ -0,0 +1,32 @@
+
+import { marked } from 'marked';
+
+export const onRequest = async (context) => {
+    const url = new URL(context.request.url);
+
+    // Intercept requests for .md files
+    if (url.pathname.endsWith('.md')) {
+
+        // Fetch the asset (the actual markdown file)
+        const response = await context.next();
+
+        // If the file exists and was retrieved successfully
+        if (response.ok) {
+            const text = await response.text();
+
+            // Convert markdown to HTML
+            // marked.parse is synchronous by default but can be async
+            const html = await marked.parse(text);
+
+            return new Response(html, {
+                status: 200,
+                headers: {
+                    'content-type': 'text/html;charset=UTF-8',
+                }
+            });
+        }
+    }
+
+    // Pass through for all other requests
+    return context.next();
+};