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

package/src/examples/sections.js

@@ -0,0 +1,53 @@
+/**
+ * Section discovery shared by the chapter nav and the copy-link buttons — ONE
+ * slug algorithm, so the "on this page" jump list and the copied deep links
+ * always agree on every hash.
+ *
+ * Sections = every <h2> inside `.container` (falling back to <body>). The
+ * anchor id lives on the section wrapper (`.card` / `.example-section`),
+ * reusing an existing section/h2 id before slugging the heading text.
+ * Idempotent: a second call returns the same ids.
+ */
+import { HEADING_CHIP_SELECTOR, SECTION_CONTAINER_SELECTOR, SECTION_SELECTOR } from './constants.js';
+
+export function generateSlug(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function getHeadingLabel(heading, fallbackLabel) {
+  const headingClone = heading.cloneNode(true);
+  headingClone.querySelectorAll(HEADING_CHIP_SELECTOR).forEach((chip) => chip.remove());
+  return (headingClone.textContent || '').replace(/\s+/g, ' ').trim() || fallbackLabel;
+}
+
+/**
+ * Make sure every section has an anchor id, and return the sections in order.
+ * @param {Document} [root]
+ * @returns {Array<{ heading: HTMLElement, section: HTMLElement, id: string, label: string }>}
+ */
+export function ensureSectionAnchors(root = document) {
+  const container = root.querySelector(SECTION_CONTAINER_SELECTOR) || root.body || root;
+  const headings = [...container.querySelectorAll('h2')];
+  const usedIds = new Set();
+
+  return headings.map((heading, headingIndex) => {
+    const section = heading.closest(SECTION_SELECTOR) || heading.parentElement || heading;
+    const label = getHeadingLabel(heading, `Section ${headingIndex + 1}`);
+
+    let id = section.id || heading.id;
+    if (!id) {
+      id = generateSlug(label) || `section-${headingIndex + 1}`;
+      if (usedIds.has(id)) {
+        let suffix = 2;
+        while (usedIds.has(`${id}-${suffix}`)) suffix++;
+        id = `${id}-${suffix}`;
+      }
+      section.id = id;
+    }
+    usedIds.add(id);
+    return { heading, section, id, label };
+  });
+}

package/src/examples/theme-switch.js

@@ -0,0 +1,72 @@
+/**
+ * THEME SWITCH — a small fixed button cycling the page theme light → dark →
+ * auto (follow the OS). It sets `data-theme` on <html>: the kit's tokens flip
+ * via `color-scheme`, and components react through their own
+ * `:host-context([data-theme="dark"])` selectors and inherited `color-scheme`
+ * (rulebook color-scheme.md signals #3/#4) — so every example page doubles as
+ * a dark-mode smoke test of the component.
+ *
+ * The plugin also injects a tiny inline script into <head> that applies the
+ * saved theme before first paint (see `renderThemeBootstrapScript`), so a
+ * reload doesn't flash light. Styles: css/theme-switch.css.
+ */
+import { DEFAULT_THEME, THEME_ATTRIBUTE, THEME_STORAGE_KEY, THEMES, THEME_SWITCH_CLASSES } from './constants.js';
+
+const THEME_ICONS = { light: '☀', dark: '☾', auto: '◐' };
+const THEME_LABELS = { light: 'Light theme', dark: 'Dark theme', auto: 'Follow system theme' };
+
+export function getSavedTheme() {
+  try {
+    const savedTheme = localStorage.getItem(THEME_STORAGE_KEY);
+    return THEMES.includes(savedTheme) ? savedTheme : DEFAULT_THEME;
+  } catch {
+    return DEFAULT_THEME;
+  }
+}
+
+export function applyTheme(theme) {
+  document.documentElement.dataset[THEME_ATTRIBUTE] = theme;
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    /* storage unavailable — theme still applies for this page view */
+  }
+}
+
+/** Inline <head> script source that applies the saved theme before first paint. */
+export function renderThemeBootstrapScript() {
+  return `try{var t=localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)});document.documentElement.dataset.${THEME_ATTRIBUTE}=${JSON.stringify(THEMES)}.indexOf(t)>-1?t:${JSON.stringify(DEFAULT_THEME)}}catch(e){document.documentElement.dataset.${THEME_ATTRIBUTE}=${JSON.stringify(DEFAULT_THEME)}}`;
+}
+
+let mountedThemeSwitch = null;
+
+/** @returns {{ unmount(): void }} */
+export function mountThemeSwitch() {
+  mountedThemeSwitch?.unmount();
+  if (!document.documentElement.dataset[THEME_ATTRIBUTE]) applyTheme(getSavedTheme());
+
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = THEME_SWITCH_CLASSES.root;
+  const iconElement = document.createElement('span');
+  iconElement.className = THEME_SWITCH_CLASSES.icon;
+  iconElement.setAttribute('aria-hidden', 'true');
+  button.appendChild(iconElement);
+
+  const renderButton = () => {
+    const theme = document.documentElement.dataset[THEME_ATTRIBUTE];
+    iconElement.textContent = THEME_ICONS[theme] || THEME_ICONS[DEFAULT_THEME];
+    button.title = `${THEME_LABELS[theme]} (click to switch)`;
+    button.setAttribute('aria-label', button.title);
+  };
+  button.addEventListener('click', () => {
+    const currentTheme = document.documentElement.dataset[THEME_ATTRIBUTE];
+    applyTheme(THEMES[(THEMES.indexOf(currentTheme) + 1) % THEMES.length]);
+    renderButton();
+  });
+  renderButton();
+  document.body.appendChild(button);
+
+  mountedThemeSwitch = { unmount: () => button.remove() };
+  return mountedThemeSwitch;
+}

package/src/examples/version-badge.js

@@ -0,0 +1,23 @@
+/**
+ * Fill version badges from the injected page config. Any `[data-kmwc-version]`
+ * element (and the legacy `#version-badge`) gets `v1.2.3` in dev and
+ * `v1.2.3 (built 2026-10-12T19:49Z)` in a built examples site.
+ */
+import { getPageConfig } from './page-config.js';
+import { VERSION_BADGE_SELECTOR } from './constants.js';
+
+export function getVersionLabel(pageConfig = getPageConfig()) {
+  if (!pageConfig.version) return '';
+  return pageConfig.buildTimestamp ? `v${pageConfig.version} (built ${pageConfig.buildTimestamp})` : `v${pageConfig.version}`;
+}
+
+export function renderVersionBadges(root = document) {
+  const pageConfig = getPageConfig();
+  const versionLabel = getVersionLabel(pageConfig);
+  if (!versionLabel) return;
+  for (const badge of root.querySelectorAll(VERSION_BADGE_SELECTOR)) {
+    if (badge.textContent.trim()) continue; // page put its own text — leave it
+    badge.textContent = versionLabel;
+    if (pageConfig.buildTimestamp) badge.title = `Built ${pageConfig.buildTimestamp}`;
+  }
+}

package/src/playwright/index.d.ts

@@ -0,0 +1,15 @@
+import type { PlaywrightTestConfig, Project } from '@playwright/test';
+
+export interface PlaywrightPresetConfig extends Omit<PlaywrightTestConfig, 'projects' | 'use' | 'webServer'> {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Replaces the default single desktop-chromium project. */
+  projects?: Project[];
+  /** Merged over the default `use` (baseURL is derived from kmwc.ports.dev). */
+  use?: PlaywrightTestConfig['use'];
+  /** Merged over the default webServer (`npm run dev` on kmwc.ports.dev); an array replaces it. */
+  webServer?: Partial<NonNullable<Exclude<PlaywrightTestConfig['webServer'], unknown[]>>> | PlaywrightTestConfig['webServer'];
+}
+
+export function definePlaywrightConfig(presetConfig?: PlaywrightPresetConfig): PlaywrightTestConfig;
+export const devices: typeof import('@playwright/test').devices;

package/src/playwright/index.js

@@ -0,0 +1,66 @@
+/**
+ * `@keenmate/web-components-devkit/playwright` — the shared Playwright preset.
+ *
+ *     import { definePlaywrightConfig } from '@keenmate/web-components-devkit/playwright';
+ *     export default definePlaywrightConfig();
+ *
+ * Specs live in e2e/ and target fixture pages under test/*.html, served by the
+ * component's own dev server on kmwc.ports.dev (read from package.json, so the
+ * port can't drift from vite.config / the Makefile). Pass `projects` to add
+ * e.g. a touch-only mobile project; anything else is shallow-merged on top.
+ */
+import { getKmwcConfig, getPeerModule } from '../config.js';
+
+/** The component's own @playwright/test (see getPeerModule). */
+function getPlaywright(root = process.cwd()) {
+  return getPeerModule(root, '@playwright/test');
+}
+
+/** Playwright's device descriptors, from the component's install. */
+export const devices = new Proxy({}, { get: (_, deviceName) => getPlaywright().devices[deviceName] });
+
+/** @param {import('./index.js').PlaywrightPresetConfig} [presetConfig] */
+export function definePlaywrightConfig(presetConfig = {}) {
+  const { root, projects, use, webServer, ...restConfig } = presetConfig;
+  const config = getKmwcConfig(root);
+  const { defineConfig, devices: playwrightDevices } = getPlaywright(config.root);
+  const baseUrl = `http://localhost:${config.ports.dev}`;
+  const isCi = !!process.env.CI;
+
+  return defineConfig({
+    testDir: './e2e',
+    timeout: 30_000,
+    expect: { timeout: 5_000 },
+    fullyParallel: true,
+    forbidOnly: isCi,
+    retries: isCi ? 2 : 0,
+    workers: isCi ? 1 : undefined,
+    reporter: isCi ? 'github' : 'list',
+    use: {
+      baseURL: baseUrl,
+      trace: 'on-first-retry',
+      screenshot: 'only-on-failure',
+      video: 'retain-on-failure',
+      ...use,
+    },
+    projects: projects || [
+      {
+        name: 'chromium',
+        use: { ...playwrightDevices['Desktop Chrome'], viewport: { width: 1440, height: 1024 } },
+      },
+    ],
+    // An array (e.g. dev server + examples preview) is taken as-is.
+    webServer: Array.isArray(webServer)
+      ? webServer
+      : {
+          command: 'npm run dev',
+          url: baseUrl,
+          reuseExistingServer: !isCi,
+          timeout: 60_000,
+          stdout: 'ignore',
+          stderr: 'pipe',
+          ...webServer,
+        },
+    ...restConfig,
+  });
+}

package/src/template.js

@@ -0,0 +1,11 @@
+/**
+ * Side layer: the one placeholder syntax the devkit uses for its own templates
+ * (generated files, the scaffold, the examples layout) — `{{UPPER_CASE}}`.
+ * An unknown placeholder is an error, never silently empty.
+ */
+export function renderTemplate(templateText, variables) {
+  return templateText.replace(/\{\{([A-Z_]+)\}\}/g, (placeholder, variableName) => {
+    if (!(variableName in variables)) throw new Error(`kmwc: template variable ${variableName} is not defined`);
+    return String(variables[variableName]);
+  });
+}

package/src/vite/index.d.ts

@@ -0,0 +1,28 @@
+import type { ConfigEnv, Plugin, PluginOption, UserConfig, UserConfigFnPromise } from 'vite';
+import type { KmwcConfig, KmwcPackageConfig } from '../config.js';
+
+export interface VitePresetConfig {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Extra plugins, appended after the kmwc examples plugin. */
+  plugins?: PluginOption[];
+  /** Per-config override of `package.json#kmwc.library`. */
+  library?: KmwcPackageConfig['library'];
+  /** Deep-merged last via Vite's `mergeConfig`. */
+  overrides?: UserConfig;
+  /** Env-dependent overrides; its return is deep-merged after `overrides`. */
+  getOverridesCallback?: (env: ConfigEnv, config: KmwcConfig) => UserConfig | Promise<UserConfig>;
+}
+
+export interface ExamplesPluginConfig {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Force the analytics snippet on/off (default: on for `vite build` only). */
+  shouldInjectAnalytics?: boolean;
+}
+
+export function defineComponentConfig(presetConfig?: VitePresetConfig): UserConfigFnPromise;
+
+export function createExamplesPlugin(pluginConfig?: ExamplesPluginConfig): Plugin;
+
+export function getExamplePages(config: KmwcConfig): Record<string, string>;

package/src/vite/index.js

@@ -0,0 +1,243 @@
+/**
+ * `@keenmate/web-components-devkit/vite` — the shared Vite preset.
+ *
+ * A component's whole vite.config.ts becomes:
+ *
+ *     import { defineComponentConfig } from '@keenmate/web-components-devkit/vite';
+ *     export default defineComponentConfig();
+ *
+ * Everything else comes from package.json#kmwc. Three modes:
+ *
+ *   vite                          dev server on kmwc.ports.dev (strict — no port hopping)
+ *   vite build                    library build → dist/<fileName>.js + .umd.js + style.css (+ .d.ts)
+ *   vite build --mode examples    static example site → dist-examples/ (every root *.html is a page)
+ *
+ * The examples plugin injects the shared kit (styles, chapter nav, copy-link,
+ * version badge) into every root-level page, so pages carry only their own
+ * content — no per-repo copies of the helper scripts or the shared stylesheet.
+ */
+import { readdirSync, existsSync, cpSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getKmwcConfig, getDevkitPackageJson, generateBuildDefines, loadPeerModule, DEVKIT_ROOT, NON_PAGE_HTML_FILES } from '../config.js';
+import { renderThemeBootstrapScript } from '../examples/theme-switch.js';
+import { composePage } from './page-composer.js';
+
+const AUTO_ENTRY_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'auto.js');
+const VIRTUAL_AUTO_ID = 'virtual:kmwc-examples';
+const KIT_STYLESHEET_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'css', 'style.css').replace(/\\/g, '/');
+// Vite's dev-server URL for a file outside the project root.
+const KIT_STYLESHEET_DEV_URL = `/@fs/${KIT_STYLESHEET_PATH.replace(/^\//, '')}`;
+const EXAMPLES_MODE = 'examples';
+
+/** Root-level HTML pages to build as the examples site. */
+export function getExamplePages(config) {
+  const skippedPages = new Set([...NON_PAGE_HTML_FILES, ...config.examples.excludedPages]);
+  return Object.fromEntries(
+    readdirSync(config.root)
+      .filter((fileName) => fileName.endsWith('.html') && !skippedPages.has(fileName))
+      .map((fileName) => [fileName.replace(/\.html$/, ''), resolve(config.root, fileName)])
+  );
+}
+
+function getBuildTimestamp() {
+  return new Date().toISOString().slice(0, 16) + 'Z';
+}
+
+const mapToScriptSafeJson = (json) => json.replace(/</g, '\\u003c');
+
+/** Plausible snippet for the given site id (build only). */
+function renderPlausibleSnippet(config) {
+  const scriptUrl = `${config.analytics.plausibleHostUrl.replace(/\/$/, '')}/js/${config.analytics.plausibleSiteId}.js`;
+  return (
+    `<!-- Privacy-friendly analytics by Plausible (injected by kmwc at build time) -->\n` +
+    `<script async src="${scriptUrl}"></script>\n` +
+    `<script>window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()</script>\n`
+  );
+}
+
+/**
+ * The examples plugin. Usually wired by `defineComponentConfig()`; exported for
+ * repos (monorepos, showcases) that assemble their own Vite config.
+ *
+ * @param {import('./index.js').ExamplesPluginConfig} [pluginConfig]
+ */
+export function createExamplesPlugin(pluginConfig = {}) {
+  const config = getKmwcConfig(pluginConfig.root);
+  let command = 'serve';
+  let mode = 'development';
+  let outDir = config.examples.outDir;
+  const buildTimestamp = process.env.BUILD_TIME || getBuildTimestamp();
+  const devkitPackageJson = getDevkitPackageJson();
+
+  return {
+    name: 'kmwc-examples',
+
+    configResolved(resolvedConfig) {
+      command = resolvedConfig.command;
+      mode = resolvedConfig.mode;
+      outDir = resolvedConfig.build.outDir;
+    },
+
+    resolveId(moduleId) {
+      return moduleId === VIRTUAL_AUTO_ID ? AUTO_ENTRY_PATH : null;
+    },
+
+    // A partial isn't a module, so Vite doesn't know which pages use it —
+    // reload the page on any non-root HTML change (partials/…).
+    handleHotUpdate({ file, server }) {
+      const relativePath = file.replace(/\\/g, '/').replace(config.root.replace(/\\/g, '/') + '/', '');
+      if (relativePath.endsWith('.html') && relativePath.includes('/') && !relativePath.startsWith('test/')) {
+        server.ws.send({ type: 'full-reload' });
+        return [];
+      }
+      return undefined;
+    },
+
+    transformIndexHtml: {
+      // `pre`: run before Vite processes the HTML, so the injected module script
+      // is bundled exactly like an authored one (dev and build alike).
+      order: 'pre',
+      handler(html, context) {
+        // Only root-level pages are example pages — test fixtures under test/
+        // (Playwright) stay bare. A page can opt out with <html data-kmwc="off">.
+        if (context.path.split('/').filter(Boolean).length > 1) return html;
+        if (/<html[^>]*\sdata-kmwc=["']?off/i.test(html)) return html;
+
+        // Includes, demos and — for fragment pages — the shared layout
+        // (page-composer.js). Full documents pass through untouched.
+        html = composePage(html, { config, pagePath: context.path });
+
+        const isBuild = command === 'build';
+        const pageConfig = {
+          id: config.id,
+          title: config.title,
+          tagline: config.tagline,
+          version: config.version,
+          packageName: config.packageName,
+          buildTimestamp: isBuild ? buildTimestamp : null,
+          mode: isBuild ? 'build' : 'dev',
+          canonicalOrigin: config.examples.canonicalOrigin,
+          storagePrefix: config.examples.storagePrefix,
+          repository: config.repository,
+          homepage: config.homepage,
+          devkitVersion: devkitPackageJson.version,
+          devkitHomepage: devkitPackageJson.homepage,
+        };
+
+        let headHtml =
+          `<script>${renderThemeBootstrapScript()}</script>\n` +
+          `<script>window.__KMWC__=${mapToScriptSafeJson(JSON.stringify(pageConfig))};</script>\n`;
+        const accentDeclarations = [
+          config.theme.accentColor && `--kmwc-accent-color:${config.theme.accentColor}`,
+          config.theme.accentEndColor && `--kmwc-accent-end-color:${config.theme.accentEndColor}`,
+        ].filter(Boolean);
+        if (accentDeclarations.length) headHtml += `<style>:root{${accentDeclarations.join(';')}}</style>\n`;
+
+        const shouldInjectAnalytics = pluginConfig.shouldInjectAnalytics ?? isBuild;
+        if (shouldInjectAnalytics && config.analytics.plausibleSiteId) headHtml = renderPlausibleSnippet(config) + headHtml;
+
+        // The kit stylesheet must block first paint, or every reload flashes an
+        // unstyled page (FOUC). Dev: a real <link> in <head> — a CSS import in a
+        // module script only applies once the script has run. Build: a CSS
+        // import, which Vite extracts into a hashed <link> in <head>.
+        if (!isBuild) headHtml += `<link rel="stylesheet" href="${KIT_STYLESHEET_DEV_URL}">\n`;
+        const kitImports = isBuild ? `import '${KIT_STYLESHEET_PATH}'; import '${VIRTUAL_AUTO_ID}';` : `import '${VIRTUAL_AUTO_ID}';`;
+        const bodyHtml = `<script type="module">${kitImports}</script>\n`;
+
+        html = /<head[^>]*>/i.test(html)
+          ? html.replace(/<head[^>]*>/i, (headTag) => `${headTag}\n${headHtml}`)
+          : headHtml + html;
+        html = /<\/body>/i.test(html) ? html.replace(/<\/body>/i, `${bodyHtml}</body>`) : html + bodyHtml;
+        return html;
+      },
+    },
+
+    // Runtime-fetched assets (demo JSON, docs) aren't in the module graph —
+    // copy them verbatim next to the built pages.
+    closeBundle() {
+      if (command !== 'build' || mode !== EXAMPLES_MODE) return;
+      for (const staticPath of config.examples.staticPaths) {
+        const sourcePath = resolve(config.root, staticPath);
+        if (!existsSync(sourcePath)) {
+          this.warn?.(`kmwc: examples.staticPaths entry "${staticPath}" does not exist — skipped`);
+          continue;
+        }
+        cpSync(sourcePath, resolve(config.root, outDir, staticPath), { recursive: true });
+      }
+    },
+  };
+}
+
+/**
+ * The full preset. `presetConfig.overrides` is deep-merged last; for values
+ * that depend on the Vite env, use `getOverridesCallback(env, config)`. A repo
+ * keeps its genuinely-specific bits — extra plugins, aliases, optimizeDeps —
+ * without forking the base.
+ *
+ * @param {import('./index.js').VitePresetConfig} [presetConfig]
+ */
+export function defineComponentConfig(presetConfig = {}) {
+  return async (env) => {
+    const config = getKmwcConfig(presetConfig.root);
+    // The component's own vite — the one running this config (see loadPeerModule).
+    const { mergeConfig, searchForWorkspaceRoot } = await loadPeerModule(config.root, 'vite');
+    const library = { ...config.library, ...(presetConfig.library || {}) };
+    const isExamplesMode = env.mode === EXAMPLES_MODE;
+    const isLibraryBuild = env.command === 'build' && !isExamplesMode;
+
+    const plugins = [createExamplesPlugin({ root: config.root }), ...(presetConfig.plugins || [])];
+
+    if (isLibraryBuild && library.shouldEmitTypes) {
+      const { default: createTypesPlugin } = await import('vite-plugin-dts');
+      plugins.push(createTypesPlugin({ rollupTypes: true, ...library.typesPluginConfig }));
+    }
+
+    const baseConfig = {
+      root: config.root,
+      appType: 'mpa',
+      // Relative asset URLs in the examples build, so the site works from any
+      // sub-path (or a plain file preview), not just a domain root.
+      ...(isExamplesMode && env.command === 'build' ? { base: './' } : {}),
+      define: generateBuildDefines(config),
+      plugins,
+      server: {
+        port: config.ports.dev,
+        strictPort: true,
+        fs: {
+          // The devkit may be a sibling checkout (file: link) — let the dev
+          // server read its example-kit files.
+          allow: [searchForWorkspaceRoot(config.root), DEVKIT_ROOT],
+        },
+      },
+      preview: {
+        port: config.ports.preview,
+        strictPort: true,
+      },
+      build: isExamplesMode
+        ? {
+            outDir: config.examples.outDir,
+            emptyOutDir: true,
+            rollupOptions: { input: getExamplePages(config) },
+          }
+        : {
+            sourcemap: library.shouldEmitSourcemap,
+            lib: {
+              entry: resolve(config.root, library.entry),
+              name: library.globalName,
+              formats: library.formats,
+              cssFileName: library.cssFileName,
+              fileName: (format) => `${library.fileName}.${format === 'es' ? 'js' : `${format}.js`}`,
+            },
+            rollupOptions: {
+              external: library.external,
+            },
+          },
+    };
+
+    let mergedConfig = presetConfig.overrides ? mergeConfig(baseConfig, presetConfig.overrides) : baseConfig;
+    if (presetConfig.getOverridesCallback) {
+      mergedConfig = mergeConfig(mergedConfig, await presetConfig.getOverridesCallback(env, config));
+    }
+    return mergedConfig;
+  };
+}