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

package/src/examples/css/style.css

@@ -20,11 +20,14 @@
 
 @import './tokens.css';
 @import './base.css';
+@import './form-controls.css';
 @import './controls.css';
 @import './content.css';
+@import './tables.css';
 @import './widgets.css';
 @import './demo.css';
 @import './copy-link.css';
 @import './chapter-nav.css';
+@import './spotlight.css';
 @import './theme-switch.css';
 @import './index-page.css';

package/src/examples/css/tables.css

@@ -0,0 +1,141 @@
+/* ==============================================================================
+   EXAMPLES KIT — TABLES
+   ==============================================================================
+   Any <table> on a page gets the base look (header fill, row lines, hover),
+   modelled on pure-admin's .pa-table. `.reference-table` is the full-width,
+   fully bordered API / option table most pages use. Modifiers combine:
+
+     .table-bordered   every cell boxed (what .reference-table has)
+     .table-striped    zebra rows
+     .table-compact    tighter cells; controls inside shrink with them
+     .table-full       full width
+     tr.is-highlight   an accent-tinted row
+     .num              a right-aligned, tabular-figure cell
+
+   The base is zero-specificity (:where()), so a page or component rule wins;
+   `kmwc-native` on the table (or an ancestor) leaves it unstyled. */
+@layer kmwc {
+    /* ==========================================================================
+       BASE — every table
+       ========================================================================== */
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) {
+        border-collapse: collapse;
+        font-size: 0.875rem;
+        margin-bottom: 1rem;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(th, td) {
+        padding: 0.6rem 0.9rem;
+        text-align: start;
+        vertical-align: middle;
+        border-bottom: 1px solid var(--kmwc-border-color);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(th) {
+        background: var(--kmwc-elevated-bg);
+        color: var(--kmwc-text-color-1);
+        font-weight: 600;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(thead th) {
+        border-bottom: 2px solid var(--kmwc-border-color);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(tbody tr:hover) {
+        background: var(--kmwc-hover-bg);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(tfoot td, tfoot th) {
+        border-top: 2px solid var(--kmwc-border-color);
+        border-bottom: none;
+        font-weight: 600;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(caption) {
+        caption-side: top;
+        padding-bottom: 0.5rem;
+        text-align: start;
+        font-size: 0.8rem;
+        color: var(--kmwc-text-color-2);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(code) {
+        padding: 0.125rem 0.375rem;
+        font-size: 0.75rem;
+    }
+
+    /* ==========================================================================
+       MODIFIERS
+       ========================================================================== */
+    .table-full {
+        width: 100%;
+    }
+
+    .table-bordered :is(th, td) {
+        border: 1px solid var(--kmwc-border-color);
+    }
+
+    .table-striped tbody tr:nth-child(even) {
+        background: var(--kmwc-table-stripe-bg);
+    }
+
+    .table-striped tbody tr:nth-child(even):hover {
+        background: var(--kmwc-hover-bg);
+    }
+
+    /* Tighter cells, and the controls in them shrink too: buttons, inputs and
+       selects read --kmwc-control-height (form-controls.css). */
+    .table-compact {
+        --kmwc-control-height: 1.75rem;
+        font-size: 0.8125rem;
+    }
+
+    .table-compact :is(th, td) {
+        padding: 0.3rem 0.55rem;
+    }
+
+    .table-compact :is(button, input, select) {
+        font-size: 0.8125rem;
+    }
+
+    .table-compact button {
+        padding-inline: 0.6rem;
+    }
+
+    tr.is-highlight,
+    tr.is-highlight:hover {
+        background: var(--kmwc-accent-light-bg);
+    }
+
+    :is(th, td).num {
+        text-align: end;
+        font-variant-numeric: tabular-nums;
+        white-space: nowrap;
+    }
+
+    /* ==========================================================================
+       REFERENCE TABLE — the API / option table (full width, every cell boxed)
+       ========================================================================== */
+    .reference-table {
+        width: 100%;
+        margin-bottom: 2rem;
+    }
+
+    .reference-table th,
+    .reference-table td {
+        padding: 0.75rem 1rem;
+        border: 1px solid var(--kmwc-border-color);
+    }
+
+    /* A wide table scrolls inside its card instead of widening the page.
+       Widening matters beyond looks: mobile browsers grow the layout viewport
+       to fit, so a 390 px phone reports ~600 px and the page's own device /
+       breakpoint detection lies. */
+    @media (max-width: 768px) {
+        :where(table):not(:where(.kmwc-native, .kmwc-native *)) {
+            display: block;
+            max-width: 100%;
+            overflow-x: auto;
+        }
+    }
+}

package/src/examples/css/tokens.css

@@ -72,6 +72,17 @@
         --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)));
+        --kmwc-table-stripe-bg: color-mix(in srgb, var(--kmwc-elevated-bg) 55%, transparent);  /* zebra rows */
+        --kmwc-overlay-bg: var(--base-overlay-bg, rgba(30, 41, 59, 0.5));  /* behind a modal (spotlight) */
+
+        /* ======================================================================
+           FOCUSED ITEM — the keyboard cursor in a list (spotlight rows); the
+           shared state every Keenmate list uses (wcp --cp-item-active-*)
+           ====================================================================== */
+        --kmwc-outline-width: var(--base-outline-width, 1px);
+        --kmwc-focused-bg: var(--base-focused-bg, transparent);
+        --kmwc-focused-text-color: var(--base-focused-text-color, currentColor);
+        --kmwc-focused-outline: var(--base-focused-outline, var(--kmwc-outline-width) solid var(--kmwc-accent-color));
 
         /* ======================================================================
            COLORS — INPUTS & CODE
@@ -79,6 +90,18 @@
         --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-input-border-hover: var(--base-input-border-hover, 1px solid var(--kmwc-accent-color));
+        --kmwc-input-border-focus: var(--base-input-border-focus, 1px solid var(--kmwc-accent-color));
+        --kmwc-input-shadow-color-focus: var(--base-input-shadow-color-focus, color-mix(in srgb, var(--kmwc-accent-color) 5%, transparent));
+        --kmwc-input-box-shadow-focus: var(--base-input-box-shadow-focus, 0 0 0 3px var(--kmwc-input-shadow-color-focus));
+        --kmwc-input-placeholder-color: var(--base-input-placeholder-color, var(--kmwc-text-color-3));
+        --kmwc-input-icon-color: var(--base-input-icon-color, var(--kmwc-text-color-3));  /* select caret */
+        --kmwc-input-disabled-bg: var(--base-input-bg-disabled, var(--base-disabled-bg, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.024) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.048) c h))));
+        --kmwc-disabled-opacity: var(--base-disabled-opacity, 0.65);
+        --kmwc-checkbox-border-color: var(--base-checkbox-border-color, var(--kmwc-border-color-strong));
+        --kmwc-icon-check: var(--base-icon-check, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22M20 6 9 17l-5-5%22/%3E%3C/svg%3E"));
+        --kmwc-icon-indeterminate: var(--base-icon-indeterminate, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22M5 12h14%22/%3E%3C/svg%3E"));
+        --kmwc-icon-check-size: var(--base-icon-check-size, 68%);
         --kmwc-code-bg: light-dark(#2d3748, #0d1117);
         --kmwc-code-text-color: #e2e8f0;
         --kmwc-code-comment-color: #8b949e;
@@ -119,6 +142,11 @@
         --kmwc-radius-lg: 12px;
         --kmwc-radius-md: 8px;
         --kmwc-radius-sm: 6px;
+        /* One height for inputs, selects and buttons, so a control row lines up.
+           A kit size, not --base-input-size-md-height: the contract's unitless
+           heights assume a 10px rem, the example pages keep the browser's 16px. */
+        --kmwc-control-height: 2.25rem;
+        --kmwc-checkbox-size: calc(1rem * var(--base-checkbox-scale, 1));
         --kmwc-max-width: 1400px;
     }
 }

package/src/examples/index.d.ts

@@ -8,6 +8,7 @@ export interface KmwcPageConfig {
   mode: 'dev' | 'build';
   canonicalOrigin: string;
   storagePrefix: string;
+  isSpotlightEnabled: boolean;
   repository: string;
   homepage: string;
   /** The @keenmate/web-components-devkit version that built the page (shown in the index footer). */
@@ -40,6 +41,20 @@ export interface ChapterNavConfig {
   indexHref?: string;
 }
 
+/** One entry of the spotlight's chapter index (virtual:kmwc-chapters). */
+export interface Chapter {
+  /** Section code (`TH07`), null for an uncoded heading (`Summary`). */
+  code: string | null;
+  /** Heading text without the code. */
+  title: string;
+  /** Heading text as shown (`TH07 · Title`). */
+  label: string;
+  pageHref: string;
+  pageTitle: string;
+  /** `examples-theming.html#th07` — by code, else by the heading slug. */
+  href: string;
+}
+
 export interface Section {
   heading: HTMLElement;
   section: HTMLElement;
@@ -58,6 +73,18 @@ export function renderExamplesIndex(indexConfig: ExamplesIndexConfig): HTMLEleme
 export function mountExamplesKit(): void;
 export function mountChapterNav(navConfig?: ChapterNavConfig): { unmount(): void } | null;
 
+/** Ctrl/Cmd+K chapter search across every example page (mirrors web-commandpalette); null when `isSpotlightEnabled` is false. */
+export function mountSpotlight(): { open(): void; close(): void; toggle(): void; unmount(): void } | null;
+/** Resolve the URL hash (`#th07`, an anchor id or a heading slug) now and on every hash change. */
+export function attachChapterLinks(): void;
+export function scrollToChapterHash(hash?: string): boolean;
+/** Chapters whose code or title contains the query; exact code (`th7` = TH07) first, then code prefix, then the rest. */
+export function searchChapters<T extends Pick<Chapter, 'code' | 'title'>>(chapters: T[], query: string): T[];
+/** Substring match of `needle` against any field (web-commandpalette matchesAny). */
+export function checkMatchesAny(fields: readonly unknown[], needle: string): boolean;
+/** Escaped `text` with the occurrences of `needle` in <mark> (web-commandpalette highlight). */
+export function renderHighlightedText(text: string, needle: string): string;
+
 export function attachCopyLinks(): void;
 export function copyText(text: string): Promise<boolean>;
 export function getSectionUrl(sectionId: string, canonicalOrigin?: string): string;
@@ -73,11 +100,22 @@ 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 getChapterCode(label: string): string | null;
+export function mapToCodeKey(code: string): string;
+export function findSectionByHash(hash: string, sections: Section[]): Section | null;
 
 export function getPageConfig(): KmwcPageConfig;
 export function attachDomReadyHandler(handler: () => void): void;
 
 export const CHAPTER_NAV_CLASSES: Record<string, string>;
+export const SPOTLIGHT_CLASSES: Record<string, string>;
+export const SPOTLIGHT_RESULTS_ID: string;
+export const SPOTLIGHT_ITEM_ID_PREFIX: string;
+export const SPOTLIGHT_OPEN_KEY: string;
+export const SPOTLIGHT_PAGE_STEP: number;
+export const SPOTLIGHT_FULLSCREEN_MEDIA: string;
+/** `TH07 · Title` → group 1 is the section code. */
+export const CHAPTER_CODE_PATTERN: RegExp;
 export const COPY_LINK_CLASSES: Record<string, string>;
 export const INDEX_PAGE_CLASSES: Record<string, string>;
 export const THEME_SWITCH_CLASSES: Record<string, string>;

package/src/examples/index.js

@@ -1,7 +1,7 @@
 /**
  * `@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
+ * The page-level helpers (styles, chapter nav, spotlight, 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.
  */
@@ -9,10 +9,13 @@ export { attachControlsPersistence, getControlsStorageKey } from './controls-per
 export { renderExamplesIndex } from './index-page.js';
 export { mountExamplesKit } from './kit.js';
 export { mountChapterNav } from './chapter-nav.js';
+export { mountSpotlight } from './spotlight.js';
+export { attachChapterLinks, scrollToChapterHash } from './chapter-links.js';
+export { searchChapters, checkMatchesAny, renderHighlightedText } from './chapter-search.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 { ensureSectionAnchors, generateSlug, getHeadingLabel, getChapterCode, mapToCodeKey, findSectionByHash } from './sections.js';
 export { getPageConfig, attachDomReadyHandler } from './page-config.js';
 export * from './constants.js';

package/src/examples/kit.js

@@ -1,4 +1,6 @@
 import { mountChapterNav } from './chapter-nav.js';
+import { attachChapterLinks } from './chapter-links.js';
+import { mountSpotlight } from './spotlight.js';
 import { attachCopyLinks } from './copy-link.js';
 import { renderVersionBadges } from './version-badge.js';
 import { mountThemeSwitch } from './theme-switch.js';
@@ -6,16 +8,21 @@ 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.
+ * (Re)mount the page-level helpers on the current DOM (copy-links, chapter
+ * nav, short chapter links, spotlight, version badges, demo copy buttons,
+ * theme switch). 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, spotlight and 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();
+  // After the anchors exist: an arriving #th07 can only resolve now.
+  attachChapterLinks();
+  mountSpotlight();
   renderVersionBadges();
   attachDemoCopyButtons();
   mountThemeSwitch();

package/src/examples/page-config.js

@@ -16,6 +16,7 @@ export function getPageConfig() {
     mode: injectedConfig.mode || 'dev',
     canonicalOrigin: injectedConfig.canonicalOrigin || '',
     storagePrefix: injectedConfig.storagePrefix || injectedConfig.id || 'component',
+    isSpotlightEnabled: injectedConfig.isSpotlightEnabled ?? true,
     repository: injectedConfig.repository || '',
     homepage: injectedConfig.homepage || '',
     devkitVersion: injectedConfig.devkitVersion || '',

package/src/examples/sections.js

@@ -8,7 +8,7 @@
  * 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';
+import { CHAPTER_CODE_PATTERN, HEADING_CHIP_SELECTOR, SECTION_CONTAINER_SELECTOR, SECTION_SELECTOR } from './constants.js';
 
 export function generateSlug(text) {
   return String(text)
@@ -51,3 +51,40 @@ export function ensureSectionAnchors(root = document) {
     return { heading, section, id, label };
   });
 }
+
+/** `TH07 · Title` → 'TH07'; an uncoded label (`Summary`) → null. */
+export function getChapterCode(label) {
+  return String(label).match(CHAPTER_CODE_PATTERN)?.[1] ?? null;
+}
+
+/** Comparison key for a code: case and leading zeros don't matter (`TH07`, `th7` → 'th7'). */
+export function mapToCodeKey(code) {
+  return String(code).toLowerCase().replace(/^([a-z]+)0+(?=\d)/, '$1');
+}
+
+/**
+ * The section a URL hash points at: its anchor id, else its section code
+ * (`#th07`, `#th7` — the short link the codes exist for), else the slug of its
+ * heading text (an uncoded chapter whose section carries its own id).
+ * @param {string} hash `#…` or the bare fragment
+ * @param {ReturnType<typeof ensureSectionAnchors>} sections
+ */
+export function findSectionByHash(hash, sections) {
+  let fragment = String(hash).replace(/^#/, '');
+  try {
+    fragment = decodeURIComponent(fragment);
+  } catch {
+    // a malformed escape — match it as written
+  }
+  if (!fragment) return null;
+  const fragmentKey = mapToCodeKey(fragment);
+  return (
+    sections.find((section) => section.id === fragment) ??
+    sections.find((section) => {
+      const code = getChapterCode(section.label);
+      return code !== null && mapToCodeKey(code) === fragmentKey;
+    }) ??
+    sections.find((section) => generateSlug(section.label) === fragment.toLowerCase()) ??
+    null
+  );
+}