@keenmate/web-components-devkit 1.0.0-rc01 → 1.0.0-rc03

package/src/vite/page-composer.js

@@ -18,7 +18,8 @@
  *        kmwc:layout      page (default) | bare (no header / container — e.g. the index)
  *        kmwc:entry       component entry script; default /<library.entry>, "none" to skip
  *        kmwc:body-class  classes for <body> (e.g. dark-output)
- *      <link> and <style> elements anywhere in a fragment move into <head>.
+ *      <link> and <style> elements anywhere in a fragment move into <head>
+ *      (not those inside a <script> — there they are strings, e.g. shadow-DOM styles).
  *   Full documents (<html …>) are left as they are — pages migrate one at a time.
  *
  * Pure string work on purpose: unit-testable, no HTML parser dependency. The
@@ -42,6 +43,9 @@ const HEAD_ELEMENT_PATTERN = /<link\b[^>]*>\s*|<style\b[^>]*>[\s\S]*?<\/style>\s
 const ATTRIBUTE_PATTERN = /([a-zA-Z][\w-]*)(?:\s*=\s*"([^"]*)")?/g;
 
 const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+// Comments plus whole <script> elements: a <style> / <link> inside a script is a string
+// (shadow-DOM styles, an SVG's own <style>), never a page element to move into <head>.
+const COMMENT_OR_SCRIPT_PATTERN = /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script>/gi;
 // A full document STARTS with a doctype or <html> (after a BOM, whitespace, comments). Matching
 // `<html>` anywhere would misread a fragment whose script or code sample mentions it.
 const DOCUMENT_START_PATTERN = /^?(?:\s|<!--[\s\S]*?-->)*<(?:!doctype\b|html[\s>])/i;
@@ -50,12 +54,12 @@ const DOCUMENT_START_PATTERN = /^?(?:\s|<!--[\s\S]*?-->)*<(?:!doctype\b|html[
  * Apply `mapper` to the text OUTSIDE HTML comments only, so a usage example in
  * a comment (`<!-- <kmwc-include src="…"> -->`) is never expanded.
  */
-export function mapOutsideComments(html, mapper) {
+export function mapOutsideComments(html, mapper, skippedPattern = HTML_COMMENT_PATTERN) {
   let mappedHtml = '';
   let lastIndex = 0;
-  for (const comment of html.matchAll(HTML_COMMENT_PATTERN)) {
-    mappedHtml += mapper(html.slice(lastIndex, comment.index)) + comment[0];
-    lastIndex = comment.index + comment[0].length;
+  for (const skipped of html.matchAll(skippedPattern)) {
+    mappedHtml += mapper(html.slice(lastIndex, skipped.index)) + skipped[0];
+    lastIndex = skipped.index + skipped[0].length;
   }
   return mappedHtml + mapper(html.slice(lastIndex));
 }
@@ -165,11 +169,14 @@ export function renderLayout(fragmentHtml, { config, pagePath }) {
   if (layout === 'page' && !pageMeta.title) throw new Error(`kmwc: ${pagePath}: a fragment page needs <meta name="kmwc:title" content="…">`);
 
   const headElements = [];
-  const bodyContent = mapOutsideComments(htmlWithoutMeta, (text) =>
-    text.replace(HEAD_ELEMENT_PATTERN, (element) => {
-      headElements.push(`    ${element.trim()}`);
-      return '';
-    })
+  const bodyContent = mapOutsideComments(
+    htmlWithoutMeta,
+    (text) =>
+      text.replace(HEAD_ELEMENT_PATTERN, (element) => {
+        headElements.push(`    ${element.trim()}`);
+        return '';
+      }),
+    COMMENT_OR_SCRIPT_PATTERN
   );
 
   const entry = pageMeta.entry ?? `/${config.library.entry.replace(/^\.?\//, '')}`;

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/component-variables.manifest.json

@@ -6,9 +6,9 @@
     { "name": "base-main-bg", "required": false, "usage": "Component surface" },
     { "name": "base-text-color-1", "required": false, "usage": "Label text" },
     { "name": "base-border-color", "required": false, "usage": "Button border" },
-    { "name": "base-accent-color", "required": false, "usage": "Active state fill, focus outline" },
-    { "name": "base-text-color-on-accent", "required": false, "usage": "Label text in the active state" },
-    { "name": "base-hover-bg", "required": false, "usage": "Hover background (falls back to a text/surface color-mix)" },
+    { "name": "base-primary-color", "required": false, "usage": "Active state fill, focus outline" },
+    { "name": "base-on-primary-text-color", "required": false, "usage": "Label text in the active state" },
+    { "name": "base-hover-bg", "required": false, "usage": "Hover background (falls back to the contract formula on --{{PREFIX}}-bg)" },
     { "name": "base-font-family", "required": false, "usage": "Font family" },
     { "name": "base-font-size-base", "required": false, "usage": "Font size (multiplier × --{{PREFIX}}-rem)" },
     { "name": "base-border-radius-md", "required": false, "usage": "Corner radius (multiplier × --{{PREFIX}}-rem)" },

package/templates/new/docs/examples.md

@@ -27,7 +27,7 @@ Combines a `--base-*` override (all components) with a `--{{PREFIX}}-*` one
 
 ```html
 <style>
-  :root { --base-accent-color: #10b981; }
+  :root { --base-primary-color: #10b981; }
 </style>
 <{{TAG}} label="Dark" data-theme="dark" style="--{{PREFIX}}-root-border-radius: 999px"></{{TAG}}>
 ```

package/templates/new/docs/theming.md

@@ -21,7 +21,7 @@ follow the page font size).
 
 ```css
 /* every Keenmate component on the page */
-:root { --base-accent-color: #10b981; }
+:root { --base-primary-color: #10b981; }
 
 /* this component only */
 {{TAG}} { --{{PREFIX}}-accent-color: #8b5cf6; }

package/templates/new/e2e/dark-mode.spec.ts

@@ -9,18 +9,18 @@ test.describe('<{{TAG}}> dark mode', () => {
   test('defaults to light, per-instance data-theme="dark" goes dark', async ({ page }) => {
     await page.goto('/test/dark-mode.html');
     expect(await getHostBackground(page, '#light-default')).toBe('rgb(255, 255, 255)');
-    expect(await getHostBackground(page, '#dark-instance')).toBe('rgb(26, 26, 26)');
+    expect(await getHostBackground(page, '#dark-instance')).toBe('rgb(30, 41, 59)');
   });
 
   test('an ancestor data-theme="dark" reaches the component', async ({ page }) => {
     await page.goto('/test/dark-mode.html');
-    expect(await getHostBackground(page, '#dark-ancestor')).toBe('rgb(26, 26, 26)');
+    expect(await getHostBackground(page, '#dark-ancestor')).toBe('rgb(30, 41, 59)');
   });
 
   test('a page color-scheme of dark is inherited', async ({ page }) => {
     await page.goto('/test/dark-mode.html');
     await page.evaluate(() => (document.documentElement.style.colorScheme = 'dark'));
-    expect(await getHostBackground(page, '#light-default')).toBe('rgb(26, 26, 26)');
+    expect(await getHostBackground(page, '#light-default')).toBe('rgb(30, 41, 59)');
   });
 
   test('--base-* themes the component', async ({ page }) => {

package/templates/new/examples-theming.html

@@ -18,10 +18,10 @@
 
 <div class="card">
     <h2>TH02 · Variable overrides</h2>
-    <p><code>--base-accent-color</code> themes every Keenmate component in a subtree; <code>--{{PREFIX}}-accent-color</code> one instance.</p>
+    <p><code>--base-primary-color</code> themes every Keenmate component in a subtree; <code>--{{PREFIX}}-accent-color</code> one instance.</p>
     <kmwc-demo>
-        <div style="--base-accent-color: #10b981">
-            <{{TAG}} id="th-base" label="--base-accent-color" active></{{TAG}}>
+        <div style="--base-primary-color: #10b981">
+            <{{TAG}} id="th-base" label="--base-primary-color" active></{{TAG}}>
             <{{TAG}} id="th-local" label="--{{PREFIX}}-accent-color" active style="--{{PREFIX}}-accent-color: #8b5cf6"></{{TAG}}>
         </div>
     </kmwc-demo>

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/src/css/variables.css

@@ -2,8 +2,10 @@
    CSS CUSTOM PROPERTIES (:host level)
    ==============================================================================
    Every --{{PREFIX}}-* variable reads through the cross-component --base-* hook
-   with a standalone fallback; colours fall back to light-dark(), so the
-   component follows the page's color-scheme. `color-scheme` is deliberately
+   with a standalone fallback: an input falls back to the contract default, a
+   derived token to the contract formula on this component's own tokens
+   (base-contract-check). Colours use light-dark(), so the component follows
+   the page's color-scheme. `color-scheme` is deliberately
    NOT declared here (it would shadow the page's) — see dark-mode.css.
 
    Override from outside the shadow DOM:
@@ -21,12 +23,12 @@
     /* ==========================================================================
        COLORS
        ========================================================================== */
-    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1a1a1a));
-    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#242424, #f5f5f5));
-    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(#e0e0e0, #3d3d3d));
-    --{{PREFIX}}-accent-color: var(--base-accent-color, light-dark(#0078d4, #3a96dd));
-    --{{PREFIX}}-text-color-on-accent: var(--base-text-color-on-accent, light-dark(#ffffff, #ffffff));
-    --{{PREFIX}}-hover-bg: var(--base-hover-bg, color-mix(in srgb, var(--{{PREFIX}}-text-color-1) 8%, var(--{{PREFIX}}-bg)));
+    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1e293b));
+    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#334155, #f1f5f9));
+    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(oklch(from var(--{{PREFIX}}-bg) calc(l - 0.096) c h), oklch(from var(--{{PREFIX}}-bg) calc(l + 0.192) c h)));
+    --{{PREFIX}}-accent-color: var(--base-primary-color, #3b82f6);
+    --{{PREFIX}}-text-color-on-accent: var(--base-on-primary-text-color, color(from color(from var(--{{PREFIX}}-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)));
+    --{{PREFIX}}-hover-bg: var(--base-hover-bg, light-dark(color-mix(in oklch, oklch(from var(--{{PREFIX}}-bg) calc(l - 0.45) c h) 14%, transparent), color-mix(in oklch, oklch(from var(--{{PREFIX}}-bg) calc(l + 0.45) c h) 28%, transparent)));
 
     /* ==========================================================================
        TYPOGRAPHY & SHAPE

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;
 }
 

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

@@ -2,8 +2,10 @@
    CSS CUSTOM PROPERTIES (:host level)
    ==============================================================================
    Every --{{PREFIX}}-* variable reads through the cross-component --base-* hook
-   with a standalone fallback; colours fall back to light-dark(), so the
-   component follows the page's color-scheme. `color-scheme` is deliberately
+   with a standalone fallback: an input falls back to the contract default, a
+   derived token to the contract formula on this component's own tokens
+   (base-contract-check). Colours use light-dark(), so the component follows
+   the page's color-scheme. `color-scheme` is deliberately
    NOT declared here (it would shadow the page's) — see dark-mode.css.
 
    Override from outside the shadow DOM:
@@ -14,9 +16,9 @@
     /* Unitless --base-* sizes multiply through --{{PREFIX}}-rem. */
     --{{PREFIX}}-rem: 10px;
 
-    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1a1a1a));
-    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#242424, #f5f5f5));
-    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(#e0e0e0, #3d3d3d));
+    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1e293b));
+    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#334155, #f1f5f9));
+    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(oklch(from var(--{{PREFIX}}-bg) calc(l - 0.096) c h), oklch(from var(--{{PREFIX}}-bg) calc(l + 0.192) c h)));
 
     --{{PREFIX}}-font-family: var(--base-font-family, inherit);
     --{{PREFIX}}-font-size-base: calc(var(--base-font-size-base, 1.6) * var(--{{PREFIX}}-rem));