@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc02

package/src/examples/css/style.css

@@ -0,0 +1,30 @@
+/* ==============================================================================
+   KMWC EXAMPLES KIT — MAIN ENTRY POINT
+   ==============================================================================
+   Loaded automatically on every example page by the kmwc Vite plugin.
+
+   Everything lives in `@layer kmwc`, so ANY unlayered rule — a page's own
+   <style>, a repo's `examples-local.css`, a light-DOM component's styles —
+   wins regardless of load order or specificity. The universal reset is
+   layered too, so it can never clobber a component (css-structure.md "The
+   unlayered-reset footgun").
+
+     • colours  → tokens (tokens.css) read through --base-*; per-site accent via
+                  package.json#kmwc.theme
+     • a rule   → write the selector unlayered in examples-local.css
+     • missing  → if two components need it, add it HERE, not locally
+
+   Page vocabulary (.card, .controls, .note, …) is authored by pages and stays
+   unprefixed; DOM the kit generates is prefixed BEM (kmwc-chapter-nav__item…). */
+@layer kmwc;
+
+@import './tokens.css';
+@import './base.css';
+@import './controls.css';
+@import './content.css';
+@import './widgets.css';
+@import './demo.css';
+@import './copy-link.css';
+@import './chapter-nav.css';
+@import './theme-switch.css';
+@import './index-page.css';

package/src/examples/css/theme-switch.css

@@ -0,0 +1,38 @@
+/* ==============================================================================
+   EXAMPLES KIT — THEME SWITCH
+   ==============================================================================
+   Fixed light / dark / auto button (theme-switch.js), top-right corner. */
+@layer kmwc {
+    .kmwc-theme-switch {
+        position: fixed;
+        top: 0.75rem;
+        right: 0.75rem;
+        z-index: 9000;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 36px;
+        height: 36px;
+        padding: 0;
+        border-radius: 50%;
+        border: 1px solid var(--kmwc-border-color);
+        background: var(--kmwc-main-bg);
+        color: var(--kmwc-text-color-1);
+        box-shadow: 0 2px 6px var(--kmwc-shadow-color);
+        cursor: pointer;
+    }
+
+    .kmwc-theme-switch:hover {
+        background: var(--kmwc-hover-bg);
+    }
+
+    .kmwc-theme-switch:focus-visible {
+        outline: 2px solid var(--kmwc-accent-color);
+        outline-offset: 2px;
+    }
+
+    .kmwc-theme-switch__icon {
+        font-size: 1.1rem;
+        line-height: 1;
+    }
+}

package/src/examples/css/tokens.css

@@ -0,0 +1,124 @@
+/* ==============================================================================
+   EXAMPLES KIT — TOKENS
+   ==============================================================================
+   The page-chrome counterpart of a component's variables.css. Same two-layer
+   model as the rulebook (base-variables.md): every --kmwc-* token reads through
+   the cross-component --base-* hook with a light-dark() fallback, so
+
+     • a theme-designer theme (:root --base-*) restyles the demo page AND the
+       component together — demo pages demonstrate cross-component theming;
+     • with no --base-* set, the page still looks right, in light and dark.
+
+   Fallbacks are the contract's own (@keenmate/base-css-variables): an input
+   falls back to its default, a derived token to the contract formula on the
+   --kmwc-* tokens, so a page looks the same with and without the contract.
+   `npm run check:contract` (base-contract-check) enforces it.
+
+   Unlike component variables (theme-container.md: never on :root), page
+   tokens DO live on :root — the page is the scope here. Feature files read
+   only --kmwc-* tokens; colour literals live in this file alone.
+
+   Re-theme a component's example site via package.json#kmwc.theme (injected
+   as --kmwc-accent-color / --kmwc-accent-end-color) — never by copying CSS. */
+@layer kmwc {
+    /* ==========================================================================
+       COLOR SCHEME — driven by <html data-theme> (theme switch)
+       ==========================================================================
+       light (default) / dark force the scheme; auto follows the OS. Components
+       on the page inherit color-scheme and see the same data-theme signal via
+       :host-context([data-theme="…"]). */
+    :root {
+        color-scheme: light;
+    }
+
+    :root[data-theme="dark"] {
+        color-scheme: dark;
+    }
+
+    :root[data-theme="auto"] {
+        color-scheme: light dark;
+    }
+
+    :root {
+        /* ======================================================================
+           COLORS — ACCENT
+           ====================================================================== */
+        --kmwc-accent-color: var(--base-primary-color, #3b82f6);
+        --kmwc-accent-end-color: oklch(from var(--kmwc-accent-color) calc(l - 0.12) c calc(h + 25));  /* header gradient end */
+        --kmwc-accent-color-hover: var(--base-primary-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-accent-color)), color-mix(in srgb, white 15%, var(--kmwc-accent-color))));
+        --kmwc-accent-color-active: var(--base-primary-color-active, light-dark(color-mix(in srgb, black 30%, var(--kmwc-accent-color)), color-mix(in srgb, white 30%, var(--kmwc-accent-color))));
+        --kmwc-accent-light-bg: var(--base-primary-bg-subtle, light-dark(color-mix(in srgb, var(--kmwc-accent-color) 10%, transparent), color-mix(in srgb, var(--kmwc-accent-color) 20%, transparent)));
+        --kmwc-accent-light-bg-hover: var(--base-primary-bg-subtle-hover, light-dark(color-mix(in srgb, var(--kmwc-accent-color) 15%, transparent), color-mix(in srgb, var(--kmwc-accent-color) 30%, transparent)));
+        --kmwc-accent-border-color: color-mix(in srgb, var(--kmwc-accent-color) 40%, transparent);
+        --kmwc-accent-shadow-color: color-mix(in srgb, var(--kmwc-accent-color) 35%, transparent);
+        --kmwc-text-color-on-accent: var(--base-on-primary-text-color, color(from color(from var(--kmwc-accent-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
+        --kmwc-header-bg: linear-gradient(135deg, var(--kmwc-accent-color) 0%, var(--kmwc-accent-end-color) 100%);
+
+        /* ======================================================================
+           COLORS — TEXT
+           ====================================================================== */
+        --kmwc-text-color-1: var(--base-text-color-1, light-dark(#334155, #f1f5f9));
+        --kmwc-text-color-2: var(--base-text-color-2, color-mix(in srgb, var(--kmwc-text-color-1) 75%, var(--kmwc-main-bg)));
+        --kmwc-text-color-3: var(--base-text-color-3, color-mix(in srgb, var(--kmwc-text-color-1) 55%, var(--kmwc-main-bg)));
+        --kmwc-text-color-4: var(--base-text-color-4, color-mix(in srgb, var(--kmwc-text-color-1) 40%, var(--kmwc-main-bg)));
+
+        /* ======================================================================
+           COLORS — SURFACE
+           ====================================================================== */
+        --kmwc-page-bg: var(--base-page-bg, light-dark(#f8f9fa, #0f172a));
+        --kmwc-main-bg: var(--base-main-bg, light-dark(#ffffff, #1e293b));
+        --kmwc-elevated-bg: var(--base-elevated-bg, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.03) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.06) c h)));
+        --kmwc-hover-bg: var(--base-hover-bg, light-dark(color-mix(in oklch, oklch(from var(--kmwc-main-bg) calc(l - 0.45) c h) 14%, transparent), color-mix(in oklch, oklch(from var(--kmwc-main-bg) calc(l + 0.45) c h) 28%, transparent)));
+        --kmwc-border-color: var(--base-border-color, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.096) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.192) c h)));
+        --kmwc-border-color-strong: var(--base-input-border-color, light-dark(color-mix(in srgb, var(--kmwc-text-color-1) 45%, var(--kmwc-main-bg)), color-mix(in srgb, var(--kmwc-text-color-1) 35%, var(--kmwc-main-bg))));  /* control outline */
+        --kmwc-shadow-color: var(--base-shadow-color, light-dark(rgba(0, 0, 0, 0.15), rgba(0, 0, 0, 0.4)));
+
+        /* ======================================================================
+           COLORS — INPUTS & CODE
+           ====================================================================== */
+        --kmwc-input-bg: var(--base-input-bg, var(--kmwc-main-bg));
+        --kmwc-input-color: var(--base-input-text-color, var(--kmwc-text-color-1));
+        --kmwc-input-border: var(--base-input-border, 1px solid var(--kmwc-border-color-strong));
+        --kmwc-code-bg: light-dark(#2d3748, #0d1117);
+        --kmwc-code-text-color: #e2e8f0;
+        --kmwc-code-comment-color: #8b949e;
+        --kmwc-code-keyword-color: #c678dd;
+        --kmwc-code-string-color: #98c379;
+        --kmwc-code-function-color: #61afef;
+        --kmwc-code-property-color: #d19a66;
+        --kmwc-console-bg: light-dark(#0f172a, #05070d);
+        --kmwc-console-text-color: #e2e8f0;
+        --kmwc-console-muted-color: #94a3b8;
+        --kmwc-console-highlight-color: #68d391;
+        --kmwc-inline-code-bg: light-dark(#edf2f7, #2b2b2b);
+
+        /* ======================================================================
+           COLORS — SEMANTIC
+           ====================================================================== */
+        /* -color = the role as text on a surface (notes, feedback); the danger
+           button fills with --kmwc-danger-fill-color. */
+        --kmwc-success-color: var(--base-success-text-color, light-dark(#155724, #34d399));
+        --kmwc-warning-color: var(--base-warning-text-color, light-dark(#856404, #fbbf24));
+        --kmwc-danger-color: var(--base-danger-text-color, light-dark(#721c24, #f87171));
+        --kmwc-info-color: var(--base-info-text-color, light-dark(#0c5460, #22d3ee));
+        --kmwc-danger-fill-color: var(--base-danger-color, #dc2626);
+        --kmwc-danger-fill-color-hover: var(--base-danger-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-danger-fill-color)), color-mix(in srgb, white 15%, var(--kmwc-danger-fill-color))));
+        --kmwc-text-color-on-danger: var(--base-on-danger-text-color, color(from color(from var(--kmwc-danger-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
+        --kmwc-neutral-color: light-dark(#6b7280, #9ca3af);
+        --kmwc-badge-new-bg: light-dark(#e53e3e, #f56565);
+        /* Text on the neutral / badge fills: the contract's on-colour formula on
+           their own background, not on the accent (a light primary would turn it black). */
+        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
+        --kmwc-text-color-on-badge-new: color(from color(from var(--kmwc-badge-new-bg) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
+
+        /* ======================================================================
+           TYPOGRAPHY & SHAPE
+           ====================================================================== */
+        --kmwc-font-family: var(--base-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+        --kmwc-mono-font-family: var(--base-font-family-mono, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);
+        --kmwc-radius-lg: 12px;
+        --kmwc-radius-md: 8px;
+        --kmwc-radius-sm: 6px;
+        --kmwc-max-width: 1400px;
+    }
+}

package/src/examples/css/widgets.css

@@ -0,0 +1,133 @@
+/* ==============================================================================
+   EXAMPLES KIT — WIDGETS
+   ==============================================================================
+   Opt-in helpers more than one component's examples use. Add here (not to a
+   repo-local stylesheet) once a second component needs a pattern. */
+@layer kmwc {
+    /* ==========================================================================
+       LOG PANELS
+       ==========================================================================
+       `.log-panel` — monospace, scrollable box for streaming output; light by
+       default, `.log-panel--dark` for the console look; height cap via
+       `--log-max-height`. `.event-log` is the legacy dark console with
+       `.event-*` entries — prefer `.log-panel` for new pages. */
+    .log-panel {
+        font-family: var(--kmwc-mono-font-family);
+        font-size: 0.85rem;
+        line-height: 1.5;
+        padding: 1rem 1.25rem;
+        border-radius: var(--kmwc-radius-md);
+        max-height: var(--log-max-height, 220px);
+        overflow: auto;
+        background: var(--kmwc-page-bg);
+        color: var(--kmwc-text-color-1);
+        border: 1px solid var(--kmwc-border-color);
+    }
+
+    .log-panel--dark {
+        background: var(--kmwc-console-bg);
+        color: var(--kmwc-console-text-color);
+        border-color: transparent;
+    }
+
+    .event-log {
+        background: var(--kmwc-console-bg);
+        color: var(--kmwc-console-muted-color);
+        padding: 1rem;
+        border-radius: var(--kmwc-radius-md);
+        font-family: var(--kmwc-mono-font-family);
+        font-size: 0.8rem;
+        max-height: 200px;
+        overflow-y: auto;
+        line-height: 1.5;
+    }
+
+    .event-log .event-entry {
+        padding: 0.15rem 0;
+        border-bottom: 1px solid color-mix(in srgb, var(--kmwc-console-text-color) 6%, transparent);
+    }
+
+    .event-log .event-time { color: var(--kmwc-console-muted-color); }
+    .event-log .event-name { color: var(--kmwc-console-highlight-color); font-weight: 600; }
+
+    /* ==========================================================================
+       CSS-VARIABLE DEMO HELPERS
+       ==========================================================================
+       `.display-sliders` — (name, range, value) rows for live CSS-var demos;
+       `.css-readout` — chips showing measured values (`.is-gap` accents a
+       derived figure). */
+    .display-sliders {
+        display: grid;
+        grid-template-columns: auto 1fr auto;
+        align-items: center;
+        gap: 0.4rem 0.75rem;
+        margin: 0.25rem 0 0.75rem;
+        max-width: 460px;
+    }
+
+    .display-sliders label {
+        font-family: var(--kmwc-mono-font-family);
+        font-size: 0.78rem;
+        color: var(--kmwc-text-color-2);
+    }
+
+    .display-sliders input[type="range"] {
+        width: 100%;
+        accent-color: var(--kmwc-accent-color);
+    }
+
+    .display-sliders output {
+        font-family: var(--kmwc-mono-font-family);
+        font-size: 0.78rem;
+        font-weight: 700;
+        color: var(--kmwc-info-color);
+        min-width: 3.2em;
+        text-align: right;
+    }
+
+    .css-readout {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.4rem;
+        margin: 0.25rem 0 1rem;
+    }
+
+    .css-readout code { font-size: 0.78rem; }
+    .css-readout code b { color: var(--kmwc-info-color); font-weight: 700; }
+    .css-readout code.is-gap b { color: var(--kmwc-warning-color); }
+
+    /* ==========================================================================
+       STATUS DOTS & PILLS
+       ========================================================================== */
+    .status-dot {
+        --kmwc-status-color: var(--kmwc-neutral-color);
+        display: inline-block;
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: var(--kmwc-status-color);
+        margin-right: 0.4rem;
+        vertical-align: middle;
+    }
+
+    .status-dot--ok { --kmwc-status-color: var(--kmwc-success-color); }
+    .status-dot--warn { --kmwc-status-color: var(--kmwc-warning-color); }
+    .status-dot--err { --kmwc-status-color: var(--kmwc-danger-color); }
+
+    .pill {
+        --kmwc-status-color: var(--kmwc-neutral-color);
+        display: inline-flex;
+        align-items: center;
+        padding: 0.15rem 0.55rem;
+        border-radius: 999px;
+        font-size: 0.75rem;
+        font-weight: 600;
+        font-family: var(--kmwc-mono-font-family);
+        background: color-mix(in srgb, var(--kmwc-status-color) 16%, transparent);
+        color: var(--kmwc-status-color);
+    }
+
+    .pill--ok { --kmwc-status-color: var(--kmwc-success-color); }
+    .pill--warn { --kmwc-status-color: var(--kmwc-warning-color); }
+    .pill--err { --kmwc-status-color: var(--kmwc-danger-color); }
+}

package/src/examples/demo-code.js

@@ -0,0 +1,30 @@
+/**
+ * Copy buttons for the code blocks <kmwc-demo> generates. The code itself is
+ * rendered at build time (page-composer.js) from the demo's live markup, so it
+ * can't drift; this only adds the "Copy" affordance. Styles: css/demo.css.
+ */
+import { copyText } from './copy-link.js';
+import { COPY_FEEDBACK_DURATION_MS, DEMO_CLASSES } from './constants.js';
+
+export function attachDemoCopyButtons(root = document) {
+  for (const codeBlock of root.querySelectorAll(`.${DEMO_CLASSES.code}`)) {
+    if (codeBlock.querySelector(`.${DEMO_CLASSES.copyButton}`)) continue;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = DEMO_CLASSES.copyButton;
+    button.textContent = 'Copy';
+    let revertTimer = null;
+    button.addEventListener('click', () => {
+      copyText(codeBlock.querySelector('code')?.textContent ?? '').then((isCopied) => {
+        button.textContent = isCopied ? 'Copied!' : 'Ctrl/Cmd+C';
+        button.classList.toggle(DEMO_CLASSES.copyButtonCopied, isCopied);
+        clearTimeout(revertTimer);
+        revertTimer = setTimeout(() => {
+          button.textContent = 'Copy';
+          button.classList.remove(DEMO_CLASSES.copyButtonCopied);
+        }, COPY_FEEDBACK_DURATION_MS);
+      });
+    });
+    codeBlock.appendChild(button);
+  }
+}

package/src/examples/index-page.js

@@ -0,0 +1,78 @@
+/**
+ * The examples landing page, rendered from a page registry. A component's
+ * index.html shrinks to:
+ *
+ *     <body>
+ *       <script type="module">
+ *         import { renderExamplesIndex } from '@keenmate/web-components-devkit/examples';
+ *         renderExamplesIndex({
+ *           pages: [
+ *             { href: 'examples-basic.html', icon: '🧩', title: 'Basic Usage', description: '…' },
+ *           ],
+ *         });
+ *       </script>
+ *     </body>
+ *
+ * Title, tagline, version and the GitHub link come from package.json#kmwc via
+ * the injected page config. The registry also feeds the cross-page chapter nav.
+ */
+import { getPageConfig } from './page-config.js';
+import { getVersionLabel } from './version-badge.js';
+import { INDEX_PAGE_CLASSES } from './constants.js';
+
+const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const mapToEscapedHtml = (text) => String(text ?? '').replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+
+/**
+ * @param {import('./index.js').ExamplesIndexConfig} indexConfig
+ * @returns {HTMLElement} the rendered page wrapper
+ */
+export function renderExamplesIndex(indexConfig) {
+  const pageConfig = getPageConfig();
+  const pages = indexConfig.pages || [];
+  const title = indexConfig.title ?? pageConfig.title;
+  const tagline = indexConfig.tagline ?? pageConfig.tagline;
+  const footerLinks = [
+    ...(pageConfig.repository ? [{ label: 'GitHub', href: pageConfig.repository }] : []),
+    ...(indexConfig.links || []),
+  ];
+  const classes = INDEX_PAGE_CLASSES;
+
+  document.body.classList.add(classes.body);
+  if (!document.title) document.title = `${title} — Examples`;
+
+  const containerEl = indexConfig.containerEl || document.body;
+  const pageElement = document.createElement('div');
+  pageElement.className = classes.page;
+  pageElement.innerHTML = `
+    <header class="${classes.header}">
+      <h1>${mapToEscapedHtml(title)}</h1>
+      ${tagline ? `<p class="${classes.tagline}">${mapToEscapedHtml(tagline)}</p>` : ''}
+      <span class="${classes.version}" data-kmwc-version>${mapToEscapedHtml(getVersionLabel(pageConfig))}</span>
+    </header>
+    <div class="${classes.cards}">
+      ${pages
+        .map(
+          (page) => `
+        <a href="${mapToEscapedHtml(page.href)}" class="${classes.card}">
+          ${page.icon ? `<div class="${classes.icon}">${mapToEscapedHtml(page.icon)}</div>` : ''}
+          <h2 class="${classes.cardTitle}">${mapToEscapedHtml(page.title)}${page.badge ? ` <span class="${classes.badge}">${mapToEscapedHtml(page.badge)}</span>` : ''}</h2>
+          ${page.description ? `<p class="${classes.cardDescription}">${mapToEscapedHtml(page.description)}</p>` : ''}
+        </a>`
+        )
+        .join('')}
+    </div>
+    <footer class="${classes.footer}">
+      <p>Created by <a href="https://github.com/keenmate" target="_blank" rel="noopener">Keenmate s.r.o.</a>${footerLinks
+        .map((link) => ` | <a href="${mapToEscapedHtml(link.href)}" target="_blank" rel="noopener">${mapToEscapedHtml(link.label)}</a>`)
+        .join('')}${
+        pageConfig.devkitVersion
+          ? ` | <a class="${classes.devkit}" href="${mapToEscapedHtml(pageConfig.devkitHomepage)}" target="_blank" rel="noopener">web-components-devkit v${mapToEscapedHtml(pageConfig.devkitVersion)}</a>`
+          : ''
+      }</p>
+    </footer>`;
+  containerEl.prepend(pageElement);
+
+  window.CHAPTER_NAV_ITEMS = pages.map((page) => ({ label: page.title, href: page.href }));
+  return pageElement;
+}

package/src/examples/index.d.ts

@@ -0,0 +1,107 @@
+export interface KmwcPageConfig {
+  id: string;
+  title: string;
+  tagline: string;
+  version: string;
+  packageName: string;
+  buildTimestamp: string | null;
+  mode: 'dev' | 'build';
+  canonicalOrigin: string;
+  storagePrefix: string;
+  repository: string;
+  homepage: string;
+  /** The @keenmate/web-components-devkit version that built the page (shown in the index footer). */
+  devkitVersion: string;
+  devkitHomepage: string;
+}
+
+/** One card on the examples index (plain data model). */
+export interface ExamplePage {
+  href: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  badge?: string;
+}
+
+export interface ExamplesIndexConfig {
+  pages: ExamplePage[];
+  title?: string;
+  tagline?: string;
+  links?: Array<{ label: string; href: string }>;
+  /** Where the page is rendered; defaults to <body>. */
+  containerEl?: Element;
+}
+
+export interface ChapterNavConfig {
+  /** Cross-page jump list (the index passes its registry). */
+  items?: Array<{ label: string; href: string }>;
+  /** "Back to Examples" target; '' hides it. */
+  indexHref?: string;
+}
+
+export interface Section {
+  heading: HTMLElement;
+  section: HTMLElement;
+  id: string;
+  label: string;
+}
+
+export type Theme = 'light' | 'dark' | 'auto';
+
+export function attachControlsPersistence(pageId: string, root?: ParentNode): { clear(): void };
+export function getControlsStorageKey(pageId: string, storagePrefix?: string): string;
+
+export function renderExamplesIndex(indexConfig: ExamplesIndexConfig): HTMLElement;
+
+/** Re-mount copy-links + chapter nav + version badges + theme switch after rendering sections late. */
+export function mountExamplesKit(): void;
+export function mountChapterNav(navConfig?: ChapterNavConfig): { unmount(): void } | null;
+
+export function attachCopyLinks(): void;
+export function copyText(text: string): Promise<boolean>;
+export function getSectionUrl(sectionId: string, canonicalOrigin?: string): string;
+
+export function renderVersionBadges(root?: ParentNode): void;
+export function attachDemoCopyButtons(root?: ParentNode): void;
+export function getVersionLabel(pageConfig?: KmwcPageConfig): string;
+
+export function mountThemeSwitch(): { unmount(): void };
+export function applyTheme(theme: Theme): void;
+export function getSavedTheme(): Theme;
+
+export function ensureSectionAnchors(root?: Document): Section[];
+export function generateSlug(text: string): string;
+export function getHeadingLabel(heading: Element, fallbackLabel: string): string;
+
+export function getPageConfig(): KmwcPageConfig;
+export function attachDomReadyHandler(handler: () => void): void;
+
+export const CHAPTER_NAV_CLASSES: Record<string, string>;
+export const COPY_LINK_CLASSES: Record<string, string>;
+export const INDEX_PAGE_CLASSES: Record<string, string>;
+export const THEME_SWITCH_CLASSES: Record<string, string>;
+export const DEMO_CLASSES: Record<string, string>;
+export const THEMES: Theme[];
+export const DEFAULT_THEME: Theme;
+/** id of the chapter-nav panel (the toggle's `aria-controls`). */
+export const CHAPTER_NAV_PANEL_ID: string;
+/** Where sections live, and what counts as one (one `<h2>` each = one chapter). */
+export const SECTION_CONTAINER_SELECTOR: string;
+export const SECTION_SELECTOR: string;
+/** Heading children left out of a chapter label (badges, the copy-link button). */
+export const HEADING_CHIP_SELECTOR: string;
+export const VERSION_BADGE_SELECTOR: string;
+export const DEFAULT_INDEX_HREF: string;
+/** `data-<THEME_ATTRIBUTE>` on `<html>`, and the localStorage key of the saved choice. */
+export const THEME_ATTRIBUTE: string;
+export const THEME_STORAGE_KEY: string;
+export const ACTIVE_CHAPTER_OFFSET_PX: number;
+export const COPY_FEEDBACK_DURATION_MS: number;
+
+declare global {
+  interface Window {
+    __KMWC__?: Partial<KmwcPageConfig>;
+    CHAPTER_NAV_ITEMS?: Array<{ label: string; href: string }>;
+  }
+}

package/src/examples/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@keenmate/web-components-devkit/examples` — named exports for example pages.
+ * The page-level helpers (styles, chapter nav, copy-links, version badge,
+ * theme switch) are mounted automatically by the Vite plugin; import from here
+ * only for the opt-in bits (controls persistence, index page) or to drive a
+ * helper manually.
+ */
+export { attachControlsPersistence, getControlsStorageKey } from './controls-persistence.js';
+export { renderExamplesIndex } from './index-page.js';
+export { mountExamplesKit } from './kit.js';
+export { mountChapterNav } from './chapter-nav.js';
+export { attachCopyLinks, copyText, getSectionUrl } from './copy-link.js';
+export { renderVersionBadges, getVersionLabel } from './version-badge.js';
+export { attachDemoCopyButtons } from './demo-code.js';
+export { mountThemeSwitch, applyTheme, getSavedTheme } from './theme-switch.js';
+export { ensureSectionAnchors, generateSlug, getHeadingLabel } from './sections.js';
+export { getPageConfig, attachDomReadyHandler } from './page-config.js';
+export * from './constants.js';

package/src/examples/kit.js

@@ -0,0 +1,22 @@
+import { mountChapterNav } from './chapter-nav.js';
+import { attachCopyLinks } from './copy-link.js';
+import { renderVersionBadges } from './version-badge.js';
+import { mountThemeSwitch } from './theme-switch.js';
+import { attachDemoCopyButtons } from './demo-code.js';
+import { INDEX_PAGE_CLASSES } from './constants.js';
+
+/**
+ * (Re)mount the page-level helpers on the current DOM. Runs automatically once
+ * per page; call it again after rendering sections asynchronously. Idempotent:
+ * copy-link / demo copy buttons skip elements that already have one, the nav
+ * and the theme switch are remounted.
+ */
+export function mountExamplesKit() {
+  // Copy-links before the nav: the nav strips the buttons back out when
+  // reading labels, and this order avoids a relayout after the nav is built.
+  if (!document.body.classList.contains(INDEX_PAGE_CLASSES.body)) attachCopyLinks();
+  mountChapterNav();
+  renderVersionBadges();
+  attachDemoCopyButtons();
+  mountThemeSwitch();
+}

package/src/examples/page-config.js

@@ -0,0 +1,30 @@
+/**
+ * Page-level config. The Vite plugin injects `window.__KMWC__` into every
+ * example page's <head> (id, title, version, build timestamp, canonical
+ * origin, …). Reading it through here gives sane defaults when a page is
+ * opened outside the plugin (e.g. a fixture page or a plain static copy).
+ */
+export function getPageConfig() {
+  const injectedConfig = (typeof window !== 'undefined' && window.__KMWC__) || {};
+  return {
+    id: injectedConfig.id || 'component',
+    title: injectedConfig.title || document.title || '',
+    tagline: injectedConfig.tagline || '',
+    version: injectedConfig.version || '',
+    packageName: injectedConfig.packageName || '',
+    buildTimestamp: injectedConfig.buildTimestamp || null,
+    mode: injectedConfig.mode || 'dev',
+    canonicalOrigin: injectedConfig.canonicalOrigin || '',
+    storagePrefix: injectedConfig.storagePrefix || injectedConfig.id || 'component',
+    repository: injectedConfig.repository || '',
+    homepage: injectedConfig.homepage || '',
+    devkitVersion: injectedConfig.devkitVersion || '',
+    devkitHomepage: injectedConfig.devkitHomepage || '',
+  };
+}
+
+/** Run `handler` once the DOM is parsed (immediately if it already is). */
+export function attachDomReadyHandler(handler) {
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', handler, { once: true });
+  else handler();
+}