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

package/components.json

@@ -0,0 +1,206 @@
+{
+  "$comment": "Registry of Keenmate web components — source for the README catalogue (`npm run readme`). `port` is the repo's block: dev server = port, preview = port + 1, examples image = port + 10. Each kind has its own range with headroom (components 12100–14900, libraries 15000–15900, showcases/docs 16000–16900, tests 17000–17900), numbered by 100 in registry order; `kmwc doctor` checks package.json#kmwc.ports against it and `kmwc new` takes the next block. `prefix` mirrors the reserved-prefix table in BlissFramework guidelines/web-components/base-variables.md (the authority).",
+  "components": [
+    {
+      "id": "web-multiselect",
+      "kind": "component",
+      "prefix": "ms",
+      "port": 12100,
+      "path": "../web-multiselect",
+      "npm": "@keenmate/web-multiselect",
+      "repo": "https://github.com/keenmate/web-multiselect",
+      "examples": "https://examples.web-multiselect.keenmate.dev",
+      "docs": "https://web-multiselect.keenmate.dev",
+      "showcase": "web-multiselect-showcase"
+    },
+    {
+      "id": "web-daterangepicker",
+      "kind": "component",
+      "prefix": "drp",
+      "port": 12200,
+      "path": "../web-daterangepicker",
+      "npm": "@keenmate/web-daterangepicker",
+      "repo": "https://github.com/keenmate/web-daterangepicker",
+      "docs": "https://web-daterangepicker.keenmate.dev",
+      "showcase": "web-daterangepicker-showcase"
+    },
+    {
+      "id": "web-treeview",
+      "kind": "component",
+      "prefix": "wtv",
+      "port": 12300,
+      "path": "../web-treeview",
+      "npm": "@keenmate/web-treeview",
+      "repo": "https://github.com/keenmate/web-treeview",
+      "showcase": "web-treeview-showcase"
+    },
+    {
+      "id": "web-commandpalette",
+      "kind": "component",
+      "prefix": "cp",
+      "port": 12400,
+      "path": "../web-commandpalette",
+      "npm": "@keenmate/web-commandpalette",
+      "repo": "https://github.com/keenmate/web-commandpalette",
+      "examples": "https://examples.web-commandpalette.keenmate.dev"
+    },
+    {
+      "id": "web-dropzone",
+      "kind": "component",
+      "prefix": "dz",
+      "port": 12500,
+      "path": "../web-dropzone",
+      "npm": "@keenmate/web-dropzone",
+      "repo": "https://github.com/keenmate/web-dropzone",
+      "monorepo": true,
+      "note": "Monorepo: renderer + headless core."
+    },
+    {
+      "id": "web-grid",
+      "kind": "component",
+      "prefix": "wg",
+      "port": 12600,
+      "path": "../web-grid",
+      "npm": "@keenmate/web-grid",
+      "repo": "https://github.com/keenmate/web-grid",
+      "docs": "https://web-grid.keenmate.com",
+      "showcase": "web-grid-showcase",
+      "monorepo": true
+    },
+    {
+      "id": "web-editor",
+      "kind": "component",
+      "prefix": "km",
+      "port": 12700,
+      "path": "../web-editor",
+      "npm": "@keenmate/web-editor",
+      "examples": "https://examples.web-editor.keenmate.dev",
+      "note": "ProseMirror-based WYSIWYG / Markdown editor."
+    },
+    {
+      "id": "web-switch",
+      "kind": "component",
+      "port": 12800,
+      "path": "../web-switch",
+      "npm": "@keenmate/web-switch",
+      "repo": "https://github.com/keenmate/web-switch",
+      "note": "Svelte-based wrapper around @keenmate/svelte-switch."
+    },
+    {
+      "id": "web-timepicker",
+      "kind": "component",
+      "port": 12900,
+      "path": "../web-timepicker",
+      "note": "Vanilla-JS prototypes (spiral / slider time pickers); no package yet."
+    },
+    {
+      "id": "web-wysiwyg",
+      "kind": "component",
+      "port": 13000,
+      "path": "../web-wysiwyg",
+      "note": "ProseMirror exploration; superseded by web-editor."
+    },
+    {
+      "id": "web-components-core",
+      "kind": "library",
+      "port": 15000,
+      "path": "../web-components-core",
+      "npm": "@keenmate/web-components-core",
+      "note": "Runtime foundation: BlissElement, reactive input table, converters, logging, positioning, CEM preset."
+    },
+    {
+      "id": "web-components",
+      "kind": "library",
+      "port": 15100,
+      "path": ".",
+      "npm": "@keenmate/web-components-devkit",
+      "repo": "https://github.com/keenmate/web-components",
+      "note": "This repo — dev/demo/build tooling (Vite preset, examples kit, kmwc CLI)."
+    },
+    {
+      "id": "pure-css",
+      "kind": "library",
+      "port": 15200,
+      "path": "../pure-css",
+      "npm": "@keenmate/pure-css",
+      "note": "CSS framework mirroring the base-css-variables token contract (demo site + e2e on the dev port)."
+    },
+    {
+      "id": "base-css-variables",
+      "kind": "library",
+      "port": 15300,
+      "path": "../base-css-variables",
+      "npm": "@keenmate/base-css-variables",
+      "repo": "https://github.com/keenmate/base-css-variables",
+      "note": "The shared --base-* token contract (base-variables.css) + base-contract-check; examples site + e2e on the dev port."
+    },
+    {
+      "id": "web-multiselect-showcase",
+      "kind": "showcase",
+      "port": 16000,
+      "path": "../web-multiselect-showcase",
+      "for": "web-multiselect"
+    },
+    {
+      "id": "web-daterangepicker-showcase",
+      "kind": "showcase",
+      "port": 16100,
+      "path": "../web-daterangepicker-showcase",
+      "for": "web-daterangepicker"
+    },
+    {
+      "id": "web-treeview-showcase",
+      "kind": "showcase",
+      "port": 16200,
+      "path": "../web-treeview-showcase",
+      "for": "web-treeview"
+    },
+    {
+      "id": "web-grid-showcase",
+      "kind": "showcase",
+      "port": 16300,
+      "path": "../web-grid-showcase",
+      "for": "web-grid",
+      "url": "https://web-grid.keenmate.com"
+    },
+    {
+      "id": "web-multiselect-docs",
+      "kind": "docs",
+      "port": 16400,
+      "path": "../web-multiselect-docs",
+      "for": "web-multiselect",
+      "note": "Content-only docs (keendocs)."
+    },
+    {
+      "id": "web-component-framework-test",
+      "kind": "test",
+      "port": 17000,
+      "path": "../web-component-framework-test",
+      "note": "Smoke + contrast tests inside CSS host frameworks (plain / Bootstrap / …)."
+    },
+    {
+      "id": "web-multiselect-test",
+      "kind": "test",
+      "port": 17100,
+      "path": "../web-multiselect-test",
+      "for": "web-multiselect",
+      "note": "npm-install vs direct-file consumption checks before publishing."
+    },
+    {
+      "id": "web-multiselect-positioning-demo",
+      "kind": "test",
+      "port": 17200,
+      "path": "../web-multiselect-positioning-demo",
+      "for": "web-multiselect",
+      "note": "Single-page positioning repro."
+    },
+    {
+      "id": "web-playground",
+      "kind": "test",
+      "port": 17300,
+      "path": "playground",
+      "for": "web-components",
+      "note": "Devkit e2e test bed — a component scaffolded with `kmwc new`, linked to this repo."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc02",
+  "description": "Shared dev, example-site and build infrastructure for Keenmate web components: Vite preset, examples kit (chapter nav, copy-link, controls store, shared styles), Playwright preset and the `kmwc` CLI (sync, doctor, check-vars, new, readme).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Keenmate s.r.o.",
+  "homepage": "https://github.com/keenmate/web-components",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keenmate/web-components.git"
+  },
+  "bin": {
+    "kmwc": "./src/cli/kmwc.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
+    },
+    "./vite": {
+      "types": "./src/vite/index.d.ts",
+      "import": "./src/vite/index.js"
+    },
+    "./playwright": {
+      "types": "./src/playwright/index.d.ts",
+      "import": "./src/playwright/index.js"
+    },
+    "./examples": {
+      "types": "./src/examples/index.d.ts",
+      "import": "./src/examples/index.js"
+    },
+    "./examples/auto": "./src/examples/auto.js",
+    "./examples/style.css": "./src/examples/css/style.css",
+    "./components.json": "./components.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "templates",
+    "components.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "readme": "node src/cli/kmwc.js readme",
+    "readme:check": "node src/cli/kmwc.js readme --check",
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:e2e": "cd playground && npx playwright test",
+    "check:contract": "base-contract-check src templates playground",
+    "playground": "cd playground && vite",
+    "playground:build": "cd playground && vite build --mode examples",
+    "playground:lib": "cd playground && vite build"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.8.0",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.60.0",
+    "vite": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@keenmate/base-css-variables": "^2.0.0-rc07",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.7"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
+  }
+}

package/src/cli/args.js

@@ -0,0 +1,16 @@
+/** Tiny flag parser: --flag, --key value, --key=value, positionals. */
+export function parseArgs(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--')) {
+      out._.push(a);
+      continue;
+    }
+    const [key, inline] = a.slice(2).split(/=(.*)/s);
+    if (inline !== undefined) out[key] = inline;
+    else if (args[i + 1] && !args[i + 1].startsWith('--')) out[key] = args[++i];
+    else out[key] = true;
+  }
+  return out;
+}

package/src/cli/commands/check-release.js

@@ -0,0 +1,66 @@
+/**
+ * kmwc check-release --tag latest|rc — gate a publish (publish-command.md).
+ *
+ *   - `latest` takes release versions only (no pre-release suffix);
+ *     `rc` takes `-rcN` versions only — a mismatch publishes under the wrong tag.
+ *   - The version must not already be on npm (`npm view` — a re-publish fails
+ *     late, after the build, and leaves the CHANGELOG lying).
+ *   - The topmost CHANGELOG heading should be this version (warning only).
+ *
+ * Exit 1 on a failed gate. `--offline` skips the npm lookup.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getKmwcConfig } from '../../config.js';
+
+const RC_VERSION_PATTERN = /-rc\d+$/;
+const PRE_RELEASE_PATTERN = /-/;
+
+/** Pure version-vs-tag verdict — exported for tests. Returns an error message or null. */
+export function checkVersionForTag(version, distTag) {
+  if (distTag === 'latest' && PRE_RELEASE_PATTERN.test(version)) {
+    return `${version} is a pre-release — publish it with \`make publish-rc\` (dist-tag rc)`;
+  }
+  if (distTag === 'rc' && !RC_VERSION_PATTERN.test(version)) {
+    return `${version} is not an -rcN version — bump to x.y.z-rcN, or publish a release with \`make publish\``;
+  }
+  if (!['latest', 'rc'].includes(distTag)) return `unknown dist-tag "${distTag}" (expected latest or rc)`;
+  return null;
+}
+
+function checkIsPublished(packageName, version) {
+  const result = spawnSync('npm', ['view', `${packageName}@${version}`, 'version'], { encoding: 'utf8', shell: true });
+  return result.status === 0 && result.stdout.trim() === version;
+}
+
+function getTopChangelogVersion(root) {
+  const changelogPath = join(root, 'CHANGELOG.md');
+  if (!existsSync(changelogPath)) return null;
+  return readFileSync(changelogPath, 'utf8').match(/^## \[?([^\]\s]+)\]?/m)?.[1] ?? null;
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const distTag = args.tag || 'latest';
+  const failures = [];
+
+  const versionError = checkVersionForTag(config.version, distTag);
+  if (versionError) failures.push(versionError);
+
+  if (!args.offline && checkIsPublished(config.packageName, config.version)) {
+    failures.push(`${config.packageName}@${config.version} is already published — bump the version first`);
+  }
+
+  const changelogVersion = getTopChangelogVersion(config.root);
+  if (changelogVersion !== config.version) {
+    console.warn(`⚠ CHANGELOG.md's top entry is ${changelogVersion ?? '(none)'}, not ${config.version}`);
+  }
+
+  if (failures.length) {
+    for (const failure of failures) console.error(`✗ ${failure}`);
+    return 1;
+  }
+  console.log(`✓ ${config.packageName}@${config.version} can be published under "${distTag}"`);
+  return 0;
+}

package/src/cli/commands/check-vars.js

@@ -0,0 +1,116 @@
+/**
+ * kmwc check-vars — validate component-variables.manifest.json against the CSS.
+ *
+ * The manifest feeds the IDE-autocomplete outputs (vscode.css-custom-data.json,
+ * web-types.json) and theme-designer, but is hand-maintained — so it drifts
+ * from the CSS. This makes drift a build failure. (Replaces the three diverged
+ * per-repo copies of scripts/check-variable-manifest.mjs.)
+ *
+ * Contract (prefix = kmwc.prefix or manifest.prefix, e.g. `ms`):
+ *   - every `--base-*` read via var() must be in baseVariables, and vice versa
+ *   - checkMode "declared" (default): every `--<prefix>-*` DECLARED (`--x:`)
+ *     must be in componentVariables, and vice versa
+ *   - checkMode "consumed": the same, but against `var(--<prefix>-*)` reads (for
+ *     components whose public knobs are read-with-fallback, never declared)
+ *   - names in kmwc.cssVariables.internalVariables are runtime internals — exempt
+ *
+ * Undocumented component variables are a warning unless --strict; everything else errors.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, extname, resolve } from 'node:path';
+import { getKmwcConfig } from '../../config.js';
+
+const STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.pcss']);
+
+/**
+ * Directories are scanned for stylesheets; a file listed explicitly is read
+ * whatever its type — e.g. a built bundle that inlines the compiled CSS, for
+ * components whose SCSS generates variable names via interpolation.
+ */
+function getStylesheetTexts(sourcePath, stylesheetTexts, isExplicit = true) {
+  if (!existsSync(sourcePath)) throw new Error(`cssVariables source not found: ${sourcePath}`);
+  if (statSync(sourcePath).isDirectory()) {
+    for (const entryName of readdirSync(sourcePath)) getStylesheetTexts(join(sourcePath, entryName), stylesheetTexts, false);
+  } else if (isExplicit || STYLESHEET_EXTENSIONS.has(extname(sourcePath))) {
+    stylesheetTexts.push(readFileSync(sourcePath, 'utf8'));
+  }
+  return stylesheetTexts;
+}
+
+const mapToRegExpSource = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Pure verdict — exported for tests. */
+export function checkManifestVariables({ cssText, manifest, prefix, internalVariables = [], checkMode = 'declared' }) {
+  cssText = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
+  const prefixSource = mapToRegExpSource(prefix);
+  // A declaration is followed by a colon; a var() read by `)` or `,`.
+  const declaredVariables = new Set([...cssText.matchAll(new RegExp(`--(${prefixSource}-[a-z0-9-]+)\\s*:`, 'gi'))].map((match) => match[1]));
+  const consumedVariables = new Set([...cssText.matchAll(new RegExp(`var\\(\\s*--(${prefixSource}-[a-z0-9-]+)`, 'gi'))].map((match) => match[1]));
+  const consumedBaseVariables = new Set([...cssText.matchAll(/var\(\s*--(base-[a-z0-9-]+)/gi)].map((match) => match[1]));
+
+  const componentVariablesInCss = checkMode === 'consumed' ? consumedVariables : declaredVariables;
+  const internalVariableSet = new Set(internalVariables);
+  const manifestComponentVariables = new Set((manifest.componentVariables || []).map((entry) => entry.name));
+  const manifestBaseVariables = new Set((manifest.baseVariables || []).map((entry) => entry.name));
+  const getDifference = (left, right) => [...left].filter((name) => !right.has(name)).sort();
+
+  return {
+    missingBaseVariables: getDifference(consumedBaseVariables, manifestBaseVariables),
+    unusedBaseVariables: getDifference(manifestBaseVariables, consumedBaseVariables),
+    unusedComponentVariables: getDifference(manifestComponentVariables, componentVariablesInCss),
+    undocumentedComponentVariables: getDifference(componentVariablesInCss, manifestComponentVariables).filter(
+      (name) => !internalVariableSet.has(name)
+    ),
+    counts: { base: manifestBaseVariables.size, component: manifestComponentVariables.size },
+  };
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const isStrict = !!args.strict;
+  const manifestPath = resolve(config.root, config.cssVariables.manifest);
+  if (!existsSync(manifestPath)) {
+    console.log(`kmwc check-vars: no ${config.cssVariables.manifest} — nothing to check.`);
+    return 0;
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const prefix = config.prefix || manifest.prefix;
+  if (!prefix) throw new Error('no variable prefix — set kmwc.prefix or "prefix" in the manifest');
+
+  const cssText = config.cssVariables.sources.flatMap((sourcePath) => getStylesheetTexts(resolve(config.root, sourcePath), [])).join('\n');
+  const verdict = checkManifestVariables({
+    cssText,
+    manifest,
+    prefix,
+    internalVariables: config.cssVariables.internalVariables,
+    checkMode: config.cssVariables.checkMode,
+  });
+
+  const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared';
+  const renderSection = (title, names) => `${title} (${names.length}):\n` + names.map((name) => `  --${name}`).join('\n');
+  const errors = [];
+  const warnings = [];
+  if (verdict.missingBaseVariables.length) errors.push(renderSection('--base-* consumed in CSS but MISSING from manifest.baseVariables', verdict.missingBaseVariables));
+  if (verdict.unusedBaseVariables.length) errors.push(renderSection('--base-* in manifest.baseVariables but NOT consumed in CSS (dead)', verdict.unusedBaseVariables));
+  if (verdict.unusedComponentVariables.length) {
+    errors.push(renderSection(`--${prefix}-* in manifest.componentVariables but NOT ${presenceWord} in CSS (dead)`, verdict.unusedComponentVariables));
+  }
+  if (verdict.undocumentedComponentVariables.length) {
+    const section = renderSection(`--${prefix}-* ${presenceWord} in CSS but MISSING from manifest.componentVariables`, verdict.undocumentedComponentVariables);
+    if (isStrict) errors.push(section);
+    else warnings.push(section + '\n  (warning — --strict enforces; list true internals in kmwc.cssVariables.internalVariables)');
+  }
+
+  if (warnings.length) console.warn('\n⚠ variable-manifest warnings:\n\n' + warnings.join('\n\n') + '\n');
+  if (errors.length) {
+    console.error('\n✗ variable manifest out of sync with CSS:\n\n' + errors.join('\n\n'));
+    console.error(`\nEdit ${config.cssVariables.manifest} (source of truth for IDE autocomplete + theme-designer), then rebuild.\n`);
+    return 1;
+  }
+  console.log(
+    `✓ variable manifest in sync — ${verdict.counts.base} base, ${verdict.counts.component} component vars` +
+      (warnings.length ? ` (${verdict.undocumentedComponentVariables.length} undocumented --${prefix}-* — see warning)` : '') +
+      '.'
+  );
+  return 0;
+}