@keenmate/web-components-devkit 1.0.0-rc02 → 1.0.0-rc04

package/src/vite/chapter-index.js

@@ -0,0 +1,107 @@
+/**
+ * The site-wide chapter index behind the spotlight: every <h2> of every
+ * example page, read at build time (and on demand in dev) from the COMPOSED
+ * page — includes resolved, so a heading from a partial counts too.
+ *
+ * Served as the virtual module `virtual:kmwc-chapters` (see index.js), which
+ * the spotlight imports lazily on first open.
+ *
+ * Each entry links by section code when the heading has one (`#th07` — the
+ * kit resolves it on arrival, see chapter-links.js), else by the slug of its
+ * heading text, the same slug the chapter nav assigns. Pure string work, like
+ * page-composer.js.
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { composePage } from './page-composer.js';
+import { generateSlug, getChapterCode } from '../examples/sections.js';
+import { CHAPTER_CODE_PATTERN } from '../examples/constants.js';
+
+/** Pages that are not part of the chapter index (the landing page has cards, not chapters). */
+export const UNINDEXED_PAGE_NAMES = ['index'];
+
+const COMMENT_SCRIPT_OR_STYLE_PATTERN = /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script>|<style\b[^>]*>[\s\S]*?<\/style>/gi;
+const HEADING_PATTERN = /<h2\b[^>]*>([\s\S]*?)<\/h2>/gi;
+const PAGE_HEADING_PATTERN = /<h1\b[^>]*>([\s\S]*?)<\/h1>/i;
+const DOCUMENT_TITLE_PATTERN = /<title\b[^>]*>([\s\S]*?)<\/title>/i;
+// The chips sections.js strips from a label (HEADING_CHIP_SELECTOR: `.badge`).
+const BADGE_PATTERN = /<span\b[^>]*\bclass="[^"]*\bbadge\b[^"]*"[^>]*>[\s\S]*?<\/span>/gi;
+const TAG_PATTERN = /<[^>]+>/g;
+
+const NAMED_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', middot: '·', mdash: '—', ndash: '–', hellip: '…', rarr: '→', larr: '←' };
+
+export function mapToDecodedText(html) {
+  return html.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, name) => {
+    if (name[0] === '#') {
+      const codePoint = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : entity;
+    }
+    return NAMED_ENTITIES[name.toLowerCase()] ?? entity;
+  });
+}
+
+/** Heading HTML → the label the kit shows (badges dropped, tags stripped, entities decoded). */
+export function getHeadingText(headingHtml) {
+  const text = mapToDecodedText(headingHtml.replace(BADGE_PATTERN, '').replace(TAG_PATTERN, ''));
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Chapters of one composed page.
+ * @param {string} html the composed page
+ * @param {{ pageHref: string }} pageInfo
+ */
+export function getPageChapters(html, { pageHref }) {
+  const visibleHtml = html.replace(COMMENT_SCRIPT_OR_STYLE_PATTERN, '');
+  // The <h1> (the layout's page title); <title> carries the site name after " — ".
+  const headingTitleMatch = visibleHtml.match(PAGE_HEADING_PATTERN);
+  const documentTitleMatch = visibleHtml.match(DOCUMENT_TITLE_PATTERN);
+  const pageTitle =
+    (headingTitleMatch && getHeadingText(headingTitleMatch[1])) ||
+    (documentTitleMatch && getHeadingText(documentTitleMatch[1]).split(' — ')[0]) ||
+    pageHref;
+
+  const usedAnchors = new Set();
+  const chapters = [];
+  for (const headingMatch of visibleHtml.matchAll(HEADING_PATTERN)) {
+    const label = getHeadingText(headingMatch[1]);
+    if (!label) continue;
+    const code = getChapterCode(label);
+    let anchor = code ? code.toLowerCase() : generateSlug(label) || `section-${chapters.length + 1}`;
+    if (usedAnchors.has(anchor)) {
+      let suffix = 2;
+      while (usedAnchors.has(`${anchor}-${suffix}`)) suffix++;
+      anchor = `${anchor}-${suffix}`;
+    }
+    usedAnchors.add(anchor);
+    chapters.push({
+      code,
+      title: code ? label.replace(CHAPTER_CODE_PATTERN, '') : label,
+      label,
+      pageHref,
+      pageTitle,
+      href: `${pageHref}#${anchor}`,
+    });
+  }
+  return chapters;
+}
+
+/**
+ * Chapters of every example page, in page order (alphabetical, as Vite builds them).
+ * @param {import('../config.d.ts').KmwcConfig} config
+ * @param {Record<string, string>} pages page name → absolute path (getExamplePages)
+ */
+export function generateChapterIndex(config, pages, readFile = (path) => readFileSync(path, 'utf8')) {
+  return Object.entries(pages)
+    .filter(([pageName]) => !UNINDEXED_PAGE_NAMES.includes(pageName))
+    .sort(([firstName], [secondName]) => firstName.localeCompare(secondName))
+    .flatMap(([, pagePath]) => {
+      const pageHref = basename(pagePath);
+      try {
+        const composedHtml = composePage(readFile(pagePath), { config, pagePath: `/${pageHref}` });
+        return getPageChapters(composedHtml, { pageHref });
+      } catch {
+        return []; // a broken page reports its own error when served — never break the index
+      }
+    });
+}

package/src/vite/index.js

@@ -21,9 +21,13 @@ 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';
+import { generateChapterIndex } from './chapter-index.js';
 
 const AUTO_ENTRY_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'auto.js');
 const VIRTUAL_AUTO_ID = 'virtual:kmwc-examples';
+// The spotlight's chapter index (chapter-index.js); spotlight.js imports it by this literal id.
+const VIRTUAL_CHAPTERS_ID = 'virtual:kmwc-chapters';
+const RESOLVED_CHAPTERS_ID = '\0' + VIRTUAL_CHAPTERS_ID;
 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(/^\//, '')}`;
@@ -79,13 +83,26 @@ export function createExamplesPlugin(pluginConfig = {}) {
     },
 
     resolveId(moduleId) {
-      return moduleId === VIRTUAL_AUTO_ID ? AUTO_ENTRY_PATH : null;
+      if (moduleId === VIRTUAL_AUTO_ID) return AUTO_ENTRY_PATH;
+      if (moduleId === VIRTUAL_CHAPTERS_ID) return RESOLVED_CHAPTERS_ID;
+      return null;
+    },
+
+    load(moduleId) {
+      if (moduleId !== RESOLVED_CHAPTERS_ID) return null;
+      const chapters = config.examples.isSpotlightEnabled ? generateChapterIndex(config, getExamplePages(config)) : [];
+      return `export default ${JSON.stringify(chapters)};`;
     },
 
     // 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, '/') + '/', '');
+      // Any page or partial may change a heading — rebuild the chapter index on its next import.
+      if (relativePath.endsWith('.html')) {
+        const chaptersModule = server.moduleGraph.getModuleById(RESOLVED_CHAPTERS_ID);
+        if (chaptersModule) server.moduleGraph.invalidateModule(chaptersModule);
+      }
       if (relativePath.endsWith('.html') && relativePath.includes('/') && !relativePath.startsWith('test/')) {
         server.ws.send({ type: 'full-reload' });
         return [];
@@ -118,6 +135,7 @@ export function createExamplesPlugin(pluginConfig = {}) {
           mode: isBuild ? 'build' : 'dev',
           canonicalOrigin: config.examples.canonicalOrigin,
           storagePrefix: config.examples.storagePrefix,
+          isSpotlightEnabled: config.examples.isSpotlightEnabled,
           repository: config.repository,
           homepage: config.homepage,
           devkitVersion: devkitPackageJson.version,

package/templates/claude-block.md

@@ -21,12 +21,19 @@ locally — every local fork is how they drifted apart.
 - **Example page styles:** shared rules are in `@layer kmwc` and read
   `--base-*` tokens (pages support light / dark / auto via the theme switch), so
   any unlayered rule wins. Put component-only rules in `examples-local.css`.
-  Re-theme with `kmwc.theme.accentColor`, never by copying CSS. If a second
-  component needs a pattern, it belongs in the devkit.
+  Re-theme with `kmwc.theme.accentColor`, never by copying CSS. Native form
+  controls (inputs, selects, checkboxes, radios, `role="switch"`, buttons) and
+  tables are already styled by the kit (`.reference-table`, `.table-striped`,
+  `.table-compact`, …) — don't restyle them per page; `kmwc-native` opts an
+  element out. If a second component needs a pattern, it belongs in the devkit.
 - **Example pages are fragments:** no `<html>`/`<head>`/`<header>` — start with
   `<meta name="kmwc:title" content="…">`, the devkit layout adds the rest. Shared text
   goes in `partials/` via `<kmwc-include>`; show code with `<kmwc-demo>` (the live
   markup IS the snippet) — never hand-copy a demo into a `.code-block`.
+- **Every example has a permanent code:** each `<h2>` starts `TH07 · Title`
+  (page prefix + number; a plain `Summary` is exempt). New examples take the
+  next free number; never renumber or reuse one — the rules are the rulebook's
+  `example-pages.md`.
 - **Controls persistence:**
   `import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples'`.
   **Landing page:** `renderExamplesIndex({ pages })` from the same module.

package/templates/new/src/css/base.css

@@ -36,8 +36,10 @@
     display: none;
 }
 
-*,
-*::before,
-*::after {
+/* Scoped to :host — the whole file also reaches the page through index.ts's
+   CSS import, and a bare `*` would reset box-sizing on the host page too. */
+:host *,
+:host *::before,
+:host *::after {
     box-sizing: inherit;
 }

package/templates/new-minimal/src/css/base.css

@@ -35,9 +35,11 @@
     display: none;
 }
 
-*,
-*::before,
-*::after {
+/* Scoped to :host — the whole file also reaches the page through index.ts's
+   CSS import, and a bare `*` would reset box-sizing on the host page too. */
+:host *,
+:host *::before,
+:host *::after {
     box-sizing: inherit;
 }