@xmesh/system-design 0.0.3 → 0.0.5

package/dist/react/react-utils.js

@@ -0,0 +1,67 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+export function mergeRefs(target, forwardedRef) {
+  if (!forwardedRef) {
+    return;
+  }
+
+  if (typeof forwardedRef === "function") {
+    forwardedRef(target);
+  } else {
+    forwardedRef.current = target;
+  }
+}
+
+export function createForwardedRefHandler(localRef, forwardedRef) {
+  return (node) => {
+    localRef.current = node;
+    mergeRefs(node, forwardedRef);
+  };
+}
+
+export function useProperties(targetElement, propName, value) {
+  useEffect(() => {
+    const el = targetElement?.current;
+    if (!el || value === undefined || el[propName] === value) {
+      return;
+    }
+
+    try {
+      el[propName] = value;
+    } catch (e) {
+      console.warn(e);
+    }
+  }, [targetElement, propName, value]);
+}
+
+export function useEventListener(targetElement, eventName, eventHandler) {
+  // keep a ref to the latest handler so we don't need to re-register the event listener
+  // whenever the handler changes (avoids duplicate listeners on re-renders)
+  const handlerRef = useRef(eventHandler);
+  handlerRef.current = eventHandler;
+
+  useLayoutEffect(() => {
+    const el = targetElement?.current;
+    if (!el || eventName === undefined) {
+      return;
+    }
+
+    // capture the handler at the time the listener is attached so we can call cancel on it
+    const eventListener = (event) => {
+      const handler = handlerRef.current;
+      if (handler) {
+        handler(event);
+      }
+    };
+
+    el.addEventListener(eventName, eventListener);
+
+    return () => {
+      const handler = handlerRef.current;
+      if (handler?.cancel) {
+        handler.cancel();
+      }
+      el.removeEventListener(eventName, eventListener);
+    };
+  }, [eventName, targetElement?.current]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmesh/system-design",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -35,6 +35,11 @@
       "import": "./dist/lit/components/*/index.js"
     },
     "./styles": "./styles/index.css",
+    "./base": "./styles/base.css",
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
     "./styles/*": "./styles/*",
     "./assets/*": "./assets/*"
   },
@@ -42,7 +47,10 @@
     "dist",
     "styles",
     "assets",
-    "colors_and_type.css"
+    "colors_and_type.css",
+    "custom-elements.json",
+    "vscode.html-custom-data.json",
+    "vscode.css-custom-data.json"
   ],
   "sideEffects": [
     "**/*.css",
@@ -52,12 +60,14 @@
   "scripts": {
     "serve": "npm-run-all --parallel watch:lit serve:static",
     "serve:static": "npx --yes http-server . -p 8080 -c-1 -o /lit/preview/",
-    "build:lit": "tsc -p lit/tsconfig.json",
+    "build:lit": "tsc -p lit/tsconfig.json && node scripts/gen-styles.mjs --out lit/build",
     "watch:lit": "tsc -p lit/tsconfig.json --watch --preserveWatchOutput",
     "build:dist": "node scripts/build-dist.mjs",
     "gen:barrel": "node scripts/gen-barrel.mjs",
+    "gen:cem": "node scripts/gen-cem.mjs",
     "screenshot": "node scripts/screenshot.mjs",
     "shoot-all": "node scripts/screenshot.mjs --all",
+    "smoke": "npm run build:lit && node scripts/smoke-render.mjs",
     "shoot:storybook": "node scripts/shoot-storybook.mjs",
     "shoot:storybook:build": "node scripts/shoot-storybook.mjs --build --theme=both",
     "check": "bash scripts/check.sh",
@@ -65,27 +75,36 @@
     "check:structure": "bash scripts/check-structure.sh",
     "check:previews": "bash scripts/check-previews.sh",
     "check:bem": "bash scripts/check-bem.sh",
+    "check:public-elements": "bash scripts/check-public-elements.sh",
+    "check:element-typings": "bash scripts/check-element-typings.sh",
+    "check:annotation-coverage": "bash scripts/check-annotation-coverage.sh",
+    "check:theme-parity": "bash scripts/check-theme-parity.sh",
+    "check:css-delivery": "bash scripts/check-css-delivery.sh",
     "check:contrast": "node scripts/check-contrast.mjs",
     "audit:contrast": "node scripts/check-contrast.mjs --audit",
     "check:spacing": "node scripts/check-spacing.mjs",
-    "prepublishOnly": "npm run build:dist",
+    "prepublishOnly": "npm run gen:cem && npm run build:dist",
     "release": "npm publish",
     "sb:prep": "npm run build:lit && node scripts/gen-storybook-register.mjs",
     "storybook": "npm run sb:prep && storybook dev -p 6006 --no-open",
     "storybook:dev": "storybook dev -p 6006 --no-open",
     "storybook:watch": "npm run sb:prep && npm-run-all --parallel watch:lit storybook:dev",
-    "storybook:react": "storybook dev -p 6007 -c .storybook-react --no-open",
-    "build-storybook": "npm run sb:prep && storybook build -o storybook-static",
-    "build-storybook:react": "storybook build -c .storybook-react -o storybook-static-react"
+    "build-storybook": "npm run sb:prep && storybook build -o storybook-static"
   },
   "peerDependencies": {
-    "lit": "^3.2.0"
+    "lit": "^3.2.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
   },
   "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
     "@storybook/addon-a11y": "^9.0.0",
     "@storybook/addon-docs": "^9.0.0",
-    "@storybook/react-vite": "^9.0.0",
     "@storybook/web-components-vite": "^9.0.0",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "@wc-toolkit/react-wrappers": "^1.2.6",
+    "custom-element-vs-code-integration": "^1.5.0",
     "http-server": "^14.1.1",
     "lit": "^3.2.0",
     "npm-run-all": "^4.1.5",
@@ -95,5 +114,14 @@
     "storybook": "^9.0.0",
     "typescript": "^5.6.3",
     "vite": "^6.0.0"
+  },
+  "customElements": "custom-elements.json",
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   }
 }

package/styles/_base-typography.css

@@ -0,0 +1,86 @@
+/* ============================================================
+   xmesh DS · _base-typography.css — opt-in raw-HTML typography.
+
+   Styles a consumer's raw `<h1>`…`<p>`/`<a>`/`<ul>`/`<code>` from the
+   type + color token contract, but ONLY under a `[data-xm-base]`
+   ancestor (ADR 0011, spine AD-3/AD-3a) — so importing the baseline
+   never restyles existing consumer markup until they opt a subtree in.
+   Sourced only from `--t-*` type roles + `--md-sys-color-*`; no raw
+   colors, no raw spacing px. Imported into @layer base by
+   styles/base.css.
+   ============================================================ */
+
+[data-xm-base] {
+  background: var(--md-sys-color-surface);
+  color: var(--md-sys-color-on-surface);
+  font: var(--t-body);
+}
+
+[data-xm-base] h1 { font: var(--t-h1); letter-spacing: var(--t-tracking-tight); }
+[data-xm-base] h2 { font: var(--t-h2); letter-spacing: var(--t-tracking-tight); }
+[data-xm-base] h3 { font: var(--t-h3); letter-spacing: var(--t-tracking-snug); }
+[data-xm-base] h4 { font: var(--t-h4); letter-spacing: var(--t-tracking-snug); }
+[data-xm-base] h5 { font: var(--t-body-strong); }
+[data-xm-base] h6 {
+  font: var(--t-eyebrow);
+  text-transform: uppercase;
+  letter-spacing: var(--t-tracking-wide);
+  color: var(--md-sys-color-on-surface-variant);
+}
+
+[data-xm-base] :is(h1, h2, h3, h4, h5, h6) {
+  margin-block: var(--s-6) var(--s-3);
+}
+[data-xm-base] :is(h1, h2, h3, h4, h5, h6):first-child {
+  margin-block-start: 0;
+}
+
+[data-xm-base] p { font: var(--t-body); margin-block: var(--s-3); }
+[data-xm-base] small { font: var(--t-small); color: var(--md-sys-color-on-surface-variant); }
+
+[data-xm-base] strong,
+[data-xm-base] b { font-weight: var(--t-weight-semibold); }
+
+[data-xm-base] a {
+  color: var(--md-sys-color-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+[data-xm-base] a:hover { text-decoration-thickness: 2px; }
+
+[data-xm-base] :is(ul, ol) {
+  margin-block: var(--s-3);
+  padding-inline-start: var(--s-6);
+}
+[data-xm-base] li { margin-block: var(--s-1); }
+
+[data-xm-base] :is(code, kbd, samp) {
+  font: var(--t-mono);
+  background: var(--md-sys-color-surface-container);
+  padding: var(--s-0-5) var(--s-1-5);
+  border-radius: var(--md-sys-shape-corner-extra-small);
+}
+[data-xm-base] pre {
+  font: var(--t-mono);
+  background: var(--md-sys-color-surface-container);
+  padding: var(--s-4);
+  border-radius: var(--md-sys-shape-corner-small);
+  overflow: auto;
+}
+[data-xm-base] pre code {
+  background: none;
+  padding: 0;
+}
+
+[data-xm-base] blockquote {
+  margin-block: var(--s-4);
+  padding-inline-start: var(--s-4);
+  border-inline-start: 2px solid var(--md-sys-color-outline-variant);
+  color: var(--md-sys-color-on-surface-variant);
+}
+
+[data-xm-base] hr {
+  border: none;
+  border-block-start: 1px solid var(--md-sys-color-outline-variant);
+  margin-block: var(--s-6);
+}

package/styles/_primitives.css

@@ -152,3 +152,57 @@
   --x-secondary-strong: oklch(0.32 0.050 125);
   --x-secondary-ink:    #ffffff;
 }
+
+/* OS-preference default (ADR 0013): with no `data-theme` pinned, follow the OS.
+   The declarations below MUST stay identical to the `:root[data-theme="light"]`
+   block above — enforced by scripts/check-theme-parity.mjs. An explicit
+   `data-theme` always wins because this selector only matches when the
+   attribute is absent (`:not([data-theme])`). */
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme]) {
+    --x-canvas-deep: #ffffff;
+    --x-canvas-0: #f8f8f6;
+    --x-canvas-1: oklch(0.96 0.006 90);
+    --x-canvas-2: oklch(0.94 0.010 88);
+    --x-canvas-3: oklch(0.92 0.013 87);
+    --x-canvas-4: oklch(0.89 0.015 86);
+    --x-canvas-5: oklch(0.85 0.017 85);
+    --x-canvas-6: oklch(0.78 0.018 85);
+    --x-canvas-7: oklch(0.70 0.018 85);
+    --x-canvas-8: oklch(0.62 0.018 85);
+    --x-surface-0: #ffffff;
+    --x-surface-1: oklch(0.995 0.002 85);
+    --x-surface-2: oklch(0.985 0.004 85);
+    --x-surface-3: oklch(0.97 0.006 85);
+    --x-surface-4: oklch(0.91 0.010 85);
+    --x-surface-5: oklch(0.86 0.013 85);
+    --x-surface-6: oklch(0.78 0.015 85);
+    --x-surface-7: oklch(0.66 0.018 85);
+    --x-surface-8: oklch(0.58 0.020 85);
+    --x-paper: oklch(0.99 0.005 85);
+    --x-ink-0: oklch(0.20 0.010 60);
+    --x-ink-1: oklch(0.30 0.010 60);
+    --x-ink-2: oklch(0.42 0.010 60);
+    --x-ink-3: oklch(0.55 0.010 60);
+    --x-ink-4: oklch(0.68 0.010 60);
+    --x-ink-canvas-0: oklch(0.18 0.005 80);
+    --x-ink-canvas-1: oklch(0.28 0.005 80);
+    --x-ink-canvas-2: oklch(0.42 0.005 80);
+    --x-ink-canvas-3: oklch(0.55 0.006 80);
+    --x-ink-canvas-4: oklch(0.68 0.006 80);
+    --x-accent-soft:     oklch(0.92 0.045 45);
+    --x-accent:          oklch(0.62 0.110 40);
+    --x-accent-strong:   oklch(0.50 0.115 38);
+    --x-accent-ink:      #ffffff;
+    --x-accent-disabled: oklch(0.88 0.015 60);
+    --x-primary-soft:     oklch(0.92 0.045 45);
+    --x-primary:          oklch(0.62 0.110 40);
+    --x-primary-strong:   oklch(0.50 0.115 38);
+    --x-primary-ink:      #ffffff;
+    --x-primary-disabled: oklch(0.88 0.015 60);
+    --x-secondary-soft:   oklch(0.88 0.045 120);
+    --x-secondary:        oklch(0.42 0.055 125);
+    --x-secondary-strong: oklch(0.32 0.050 125);
+    --x-secondary-ink:    #ffffff;
+  }
+}

package/styles/_reset.css

@@ -0,0 +1,58 @@
+/* ============================================================
+   xmesh DS · _reset.css — modern, minimal reset.
+
+   Always-on within the `./base` entry (ADR 0011, spine AD-3): it
+   normalizes the box model and user-agent defaults but sets NO colors
+   and NO typography, so importing the baseline never restyles a
+   consumer's content beyond the reset itself. Imported into @layer
+   reset by styles/base.css, so a consumer's own rules win without
+   `!important`.
+   ============================================================ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+body {
+  min-height: 100vh;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+input,
+button,
+textarea,
+select {
+  font: inherit;
+  color: inherit;
+}
+
+p,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}

package/styles/base.css

@@ -0,0 +1,23 @@
+/* ============================================================
+   xmesh DS · base.css — the one-import baseline (the `./base` entry).
+
+   Imported once at a consumer's app root, this gives a styled, themed
+   page foundation in a single statement (FR-1/2/3/4/6, ADR 0011):
+     • the declared @layer order — consumer overrides written outside
+       these layers win without `!important`;
+     • an always-on reset (@layer reset);
+     • the full token contract + theming default (@layer tokens, via
+       styles/index.css), so OS / data-theme theming applies (ADR 0013);
+     • opt-in raw-HTML typography behind [data-xm-base] (@layer base).
+
+   The existing `./styles` entry (styles/index.css) is unchanged and
+   stays tokens-only — existing consumers get no surprise reset.
+   `components` / `utilities` are declared (reserved order slots) so
+   component CSS and consumer utilities slot in predictably later.
+   ============================================================ */
+
+@layer reset, base, tokens, components, utilities;
+
+@import url("./_reset.css") layer(reset);
+@import url("./index.css") layer(tokens);
+@import url("./_base-typography.css") layer(base);

package/vscode.css-custom-data.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
+  "version": 1.1,
+  "properties": [],
+  "pseudoElements": []
+}