@neuravision/construct 2.0.3 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuravision/construct",
-  "version": "2.0.3",
+  "version": "2.1.2",
   "description": "Construct Design System - Accessible, token-based design system for modern web applications",
   "license": "MIT",
   "repository": {
@@ -17,19 +17,59 @@
     "components"
   ],
   "type": "module",
+  "engines": {
+    "node": "^22.12.0 || >=24.0.0"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "bin": {
+    "construct-theme": "./scripts/construct-theme.mjs"
+  },
   "scripts": {
-    "build": "node scripts/build-tokens.mjs",
-    "check": "node scripts/build-tokens.mjs --check",
+    "build": "npm run build:tokens && npm run build:standalone",
+    "build:tokens": "node scripts/build-tokens.mjs",
+    "build:standalone": "node scripts/build-standalone-components.mjs",
+    "audit": "npm audit --audit-level=high",
+    "tokens:validate": "node scripts/validate-tokens.mjs",
+    "tokens:test": "node scripts/test-token-pipeline.mjs",
+    "themes:validate": "node scripts/construct-theme.mjs --theme themes/walnut.theme.json --validate-only",
+    "check": "npm run check:tokens && npm run check:standalone && npm run check:css && npm run check:exports && npm run check:version",
+    "check:tokens": "node scripts/build-tokens.mjs --check && npm run tokens:validate && npm run tokens:test && npm run themes:validate",
+    "check:standalone": "node scripts/build-standalone-components.mjs --check",
+    "check:css": "node scripts/validate-css-vars.mjs",
+    "check:exports": "node scripts/validate-package-exports.mjs",
+    "check:version": "node scripts/validate-version.mjs",
+    "test": "npm run test:behaviors && npm run test:storybook && npm run test:touch && npm run test:forced-colors",
+    "test:behaviors": "vitest --run --config behaviors/__tests__/vitest.config.js",
+    "test:storybook": "vitest --run",
+    "test:touch": "vitest --run --config vitest.touch.config.js",
+    "test:forced-colors": "vitest --run --config vitest.forced-colors.config.js",
     "storybook": "storybook dev -p 6006",
-    "storybook:build": "storybook build"
+    "storybook:build": "storybook build",
+    "prepack": "npm run build && npm run check"
   },
   "exports": {
     "./foundations.css": "./foundations.css",
+    "./fonts.css": "./fonts.css",
     "./components/components.css": "./components/components.css",
     "./components/index.css": "./components/index.css",
-    "./components/*.css": "./components/*.css",
+    "./components/core.css": "./standalone/core.css",
+    "./components/_keyframes.css": "./components/_keyframes.css",
+    "./components/_shared.css": "./components/_shared.css",
+    "./components/_shell-shared.css": "./components/_shell-shared.css",
+    "./components/*.css": "./standalone/*.css",
+    "./behaviors": {
+      "types": "./behaviors/index.d.ts",
+      "default": "./behaviors/index.js"
+    },
     "./tokens/tokens.css": "./tokens/tokens.css",
     "./tokens/tokens.json": "./tokens/tokens.json",
+    "./tokens/primitives.json": "./tokens/primitives.json",
+    "./tokens/semantic.light.json": "./tokens/semantic.light.json",
+    "./tokens/semantic.dark.json": "./tokens/semantic.dark.json",
+    "./tokens/semantic.high-contrast.json": "./tokens/semantic.high-contrast.json",
+    "./tokens/components.json": "./tokens/components.json",
     "./tokens/tokens": {
       "types": "./tokens/tokens.ts",
       "default": "./tokens/tokens.js"
@@ -37,31 +77,46 @@
     "./tokens": {
       "types": "./tokens/tokens.ts",
       "default": "./tokens/tokens.js"
-    }
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./schemas/examples/*.json": "./schemas/examples/*.json",
+    "./themes/*.json": "./themes/*.json"
   },
   "files": [
     "foundations.css",
-    "tokens/tokens.css",
-    "tokens/tokens.json",
-    "tokens/tokens.js",
-    "tokens/tokens.ts",
+    "fonts.css",
+    "tokens/*.css",
+    "tokens/*.json",
+    "tokens/*.js",
+    "tokens/*.ts",
     "tokens/README.md",
-    "docs/guidelines.md",
+    "schemas/**/*.json",
+    "themes/*.json",
+    "themes/README.md",
     "components/*.css",
     "components/README.md",
+    "standalone/*.css",
+    "behaviors/*.js",
+    "behaviors/*.d.ts",
+    "behaviors/internal/*.js",
+    "scripts/build-tokens.mjs",
+    "scripts/construct-theme.mjs",
+    "scripts/validate-tokens.mjs",
+    "docs/*.md",
+    "examples/react/*",
+    "CHANGELOG.md",
     "README.md"
   ],
   "devDependencies": {
-    "@storybook/addon-a11y": "^10.2.3",
-    "@storybook/addon-docs": "^10.2.3",
-    "@storybook/addon-themes": "^10.2.3",
-    "@storybook/addon-vitest": "^10.2.3",
-    "@storybook/html-vite": "^10.2.3",
-    "@vitest/browser-playwright": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18",
-    "playwright": "^1.58.1",
+    "@storybook/addon-a11y": "^10.5.0",
+    "@storybook/addon-docs": "^10.5.0",
+    "@storybook/addon-themes": "^10.5.0",
+    "@storybook/addon-vitest": "^10.5.0",
+    "@storybook/html-vite": "^10.5.0",
+    "@vitest/browser-playwright": "^4.1.10",
+    "playwright": "^1.61.1",
     "remark-gfm": "^4.0.1",
-    "storybook": "^10.2.3",
-    "vitest": "^4.0.18"
+    "storybook": "^10.5.0",
+    "vitest": "^4.1.10"
   }
 }

package/schemas/components.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://neuravision.dev/construct/schemas/components.schema.json",
+  "title": "Construct component token contract",
+  "type": "object",
+  "required": ["button", "control", "card", "status", "metric", "meter", "datum"],
+  "additionalProperties": false,
+  "properties": {
+    "button": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["background", "backgroundHover", "backgroundActive", "border", "color", "height", "paddingX", "fontSize", "lineHeight", "fontWeight", "radius", "gap", "loadingSpinnerSize"],
+      "properties": {
+        "background": { "$ref": "#/$defs/token" },
+        "backgroundHover": { "$ref": "#/$defs/token" },
+        "backgroundActive": { "$ref": "#/$defs/token" },
+        "border": { "$ref": "#/$defs/token" },
+        "color": { "$ref": "#/$defs/token" },
+        "height": { "$ref": "#/$defs/token" },
+        "paddingX": { "$ref": "#/$defs/token" },
+        "fontSize": { "$ref": "#/$defs/token" },
+        "lineHeight": { "$ref": "#/$defs/token" },
+        "fontWeight": { "$ref": "#/$defs/token" },
+        "radius": { "$ref": "#/$defs/token" },
+        "gap": { "$ref": "#/$defs/token" },
+        "loadingSpinnerSize": { "$ref": "#/$defs/token" }
+      }
+    },
+    "control": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["background", "backgroundHover", "backgroundDisabled", "border", "borderHover", "borderFocus", "text", "placeholder", "radius"],
+      "properties": {
+        "background": { "$ref": "#/$defs/token" },
+        "backgroundHover": { "$ref": "#/$defs/token" },
+        "backgroundDisabled": { "$ref": "#/$defs/token" },
+        "border": { "$ref": "#/$defs/token" },
+        "borderHover": { "$ref": "#/$defs/token" },
+        "borderFocus": { "$ref": "#/$defs/token" },
+        "text": { "$ref": "#/$defs/token" },
+        "placeholder": { "$ref": "#/$defs/token" },
+        "radius": { "$ref": "#/$defs/token" }
+      }
+    },
+    "card": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["background", "border", "radius", "padding", "shadow", "shadowHover"],
+      "properties": {
+        "background": { "$ref": "#/$defs/token" },
+        "border": { "$ref": "#/$defs/token" },
+        "radius": { "$ref": "#/$defs/token" },
+        "padding": { "$ref": "#/$defs/token" },
+        "shadow": { "$ref": "#/$defs/token" },
+        "shadowHover": { "$ref": "#/$defs/token" }
+      }
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gap", "fontSize", "iconSize"],
+      "properties": {
+        "gap": { "$ref": "#/$defs/token" },
+        "fontSize": { "$ref": "#/$defs/token" },
+        "iconSize": { "$ref": "#/$defs/token" }
+      }
+    },
+    "metric": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["background", "border", "radius", "padding", "valueFontSize", "labelFontSize"],
+      "properties": {
+        "background": { "$ref": "#/$defs/token" },
+        "border": { "$ref": "#/$defs/token" },
+        "radius": { "$ref": "#/$defs/token" },
+        "padding": { "$ref": "#/$defs/token" },
+        "valueFontSize": { "$ref": "#/$defs/token" },
+        "labelFontSize": { "$ref": "#/$defs/token" }
+      }
+    },
+    "meter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["height", "radius", "track"],
+      "properties": {
+        "height": { "$ref": "#/$defs/token" },
+        "radius": { "$ref": "#/$defs/token" },
+        "track": { "$ref": "#/$defs/token" }
+      }
+    },
+    "datum": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["edgeWidth", "tickWidth", "tickHeight", "originLength", "markSize", "scaleHeight", "scaleMinorStep", "scaleMajorStep"],
+      "properties": {
+        "edgeWidth": { "$ref": "#/$defs/token" },
+        "tickWidth": { "$ref": "#/$defs/token" },
+        "tickHeight": { "$ref": "#/$defs/token" },
+        "originLength": { "$ref": "#/$defs/token" },
+        "markSize": { "$ref": "#/$defs/token" },
+        "scaleHeight": { "$ref": "#/$defs/token" },
+        "scaleMinorStep": { "$ref": "#/$defs/token" },
+        "scaleMajorStep": { "$ref": "#/$defs/token" }
+      }
+    }
+  },
+  "$defs": {
+    "token": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^\\{[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)+\\}$"
+        },
+        {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!.*(?:/\\*|\\*/|[;{}]|!\\s*important|\\b(?:url|var)\\s*\\())[^\\u0000-\\u001F\\u007F]+$"
+        }
+      ]
+    }
+  }
+}

package/schemas/examples/theme.example.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../theme.schema.json",
+  "name": "example-theme",
+  "extends": "light",
+  "semantic": {
+    "color": {
+      "brand": {
+        "primary": "{color.ocean.700}",
+        "primaryHover": "{color.ocean.800}",
+        "primaryActive": "{color.ocean.900}"
+      }
+    }
+  },
+  "components": {
+    "button": {
+      "radius": "{radius.pill}"
+    }
+  },
+  "contrast": [
+    {
+      "name": "button label",
+      "foreground": "components.button.color",
+      "background": "components.button.background",
+      "minRatio": 4.5
+    }
+  ]
+}

package/schemas/primitives.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://neuravision.dev/construct/schemas/primitives.schema.json",
+  "title": "Construct primitive tokens",
+  "type": "object",
+  "required": [
+    "color",
+    "font",
+    "space",
+    "radius",
+    "border",
+    "opacity",
+    "size",
+    "layout",
+    "shadow",
+    "motion",
+    "zIndex",
+    "breakpoint"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "color": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "minProperties": 1,
+        "patternProperties": {
+          "^(0|[1-9][0-9]*)$": { "$ref": "#/$defs/color" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "font": {
+      "type": "object",
+      "required": ["family", "weight", "size", "lineHeight", "letterSpacing"],
+      "additionalProperties": false,
+      "properties": {
+        "family": {
+          "type": "object",
+          "required": ["brand", "text", "mono"],
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
+        "weight": { "$ref": "#/$defs/numberScale" },
+        "size": { "$ref": "#/$defs/nonNegativeScale" },
+        "lineHeight": { "$ref": "#/$defs/nonNegativeScale" },
+        "letterSpacing": { "$ref": "#/$defs/numberScale" }
+      }
+    },
+    "space": { "$ref": "#/$defs/nonNegativeScale" },
+    "radius": { "$ref": "#/$defs/nonNegativeScale" },
+    "border": {
+      "type": "object",
+      "required": ["width"],
+      "additionalProperties": false,
+      "properties": {
+        "width": { "$ref": "#/$defs/nonNegativeScale" }
+      }
+    },
+    "opacity": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      }
+    },
+    "size": {
+      "type": "object",
+      "required": ["controlHeight", "icon"],
+      "additionalProperties": false,
+      "properties": {
+        "controlHeight": { "$ref": "#/$defs/nonNegativeScale" },
+        "icon": { "$ref": "#/$defs/nonNegativeScale" }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "required": ["container", "gutter", "gridGap", "navbar"],
+      "additionalProperties": false,
+      "properties": {
+        "container": { "$ref": "#/$defs/nonNegativeScale" },
+        "gutter": { "$ref": "#/$defs/nonNegativeScale" },
+        "gridGap": { "$ref": "#/$defs/nonNegativeScale" },
+        "navbar": { "$ref": "#/$defs/nonNegativeScale" }
+      }
+    },
+    "shadow": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "motion": {
+      "type": "object",
+      "required": ["duration", "easing"],
+      "additionalProperties": false,
+      "properties": {
+        "duration": { "$ref": "#/$defs/nonNegativeScale" },
+        "easing": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "zIndex": { "$ref": "#/$defs/numberScale" },
+    "breakpoint": { "$ref": "#/$defs/nonNegativeScale" }
+  },
+  "$defs": {
+    "color": {
+      "type": "string",
+      "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
+    },
+    "numberScale": {
+      "type": "object",
+      "minProperties": 1,
+      "patternProperties": {
+        "^[A-Za-z0-9][A-Za-z0-9_-]*$": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "nonNegativeScale": {
+      "type": "object",
+      "minProperties": 1,
+      "patternProperties": {
+        "^[A-Za-z0-9][A-Za-z0-9_-]*$": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/semantic.schema.json

@@ -0,0 +1,224 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://neuravision.dev/construct/schemas/semantic.schema.json",
+  "title": "Construct semantic token contract",
+  "type": "object",
+  "required": ["color", "theme", "font", "typography", "radius", "shadow"],
+  "additionalProperties": false,
+  "properties": {
+    "color": {
+      "type": "object",
+      "required": [
+        "brand",
+        "text",
+        "background",
+        "border",
+        "state",
+        "stateSurface",
+        "stateBorder",
+        "stateText",
+        "overlay",
+        "focus",
+        "avatarSeed",
+        "chartSeries"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "brand": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primary", "primaryHover", "primaryActive", "accent", "accentHover", "accentActive", "accentStrong", "onAccent"],
+          "properties": {
+            "primary": { "$ref": "#/$defs/token" },
+            "primaryHover": { "$ref": "#/$defs/token" },
+            "primaryActive": { "$ref": "#/$defs/token" },
+            "accent": { "$ref": "#/$defs/token" },
+            "accentHover": { "$ref": "#/$defs/token" },
+            "accentActive": { "$ref": "#/$defs/token" },
+            "accentStrong": { "$ref": "#/$defs/token" },
+            "onAccent": { "$ref": "#/$defs/token" }
+          }
+        },
+        "text": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primary", "secondary", "muted", "inverse", "onPrimary"],
+          "properties": {
+            "primary": { "$ref": "#/$defs/token" },
+            "secondary": { "$ref": "#/$defs/token" },
+            "muted": { "$ref": "#/$defs/token" },
+            "inverse": { "$ref": "#/$defs/token" },
+            "onPrimary": { "$ref": "#/$defs/token" }
+          }
+        },
+        "background": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["canvas", "surface", "elevated", "muted", "subtle"],
+          "properties": {
+            "canvas": { "$ref": "#/$defs/token" },
+            "surface": { "$ref": "#/$defs/token" },
+            "elevated": { "$ref": "#/$defs/token" },
+            "muted": { "$ref": "#/$defs/token" },
+            "subtle": { "$ref": "#/$defs/token" }
+          }
+        },
+        "border": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["subtle", "default", "strong", "muted"],
+          "properties": {
+            "subtle": { "$ref": "#/$defs/token" },
+            "default": { "$ref": "#/$defs/token" },
+            "strong": { "$ref": "#/$defs/token" },
+            "muted": { "$ref": "#/$defs/token" }
+          }
+        },
+        "state": { "$ref": "#/$defs/stateGroupWithSolid" },
+        "stateSurface": { "$ref": "#/$defs/stateGroup" },
+        "stateBorder": { "$ref": "#/$defs/stateGroup" },
+        "stateText": { "$ref": "#/$defs/stateGroup" },
+        "overlay": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["scrim"],
+          "properties": { "scrim": { "$ref": "#/$defs/token" } }
+        },
+        "focus": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ring"],
+          "properties": { "ring": { "$ref": "#/$defs/token" } }
+        },
+        "avatarSeed": {
+          "type": "object",
+          "minProperties": 16,
+          "patternProperties": {
+            "^[1-8](Bg|Fg)$": { "$ref": "#/$defs/token" }
+          },
+          "additionalProperties": false
+        },
+        "chartSeries": {
+          "type": "object",
+          "minProperties": 8,
+          "patternProperties": {
+            "^[1-8]$": { "$ref": "#/$defs/token" }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "required": ["colorScheme"],
+      "additionalProperties": false,
+      "properties": {
+        "colorScheme": { "enum": ["light", "dark", "light dark", "dark light"] }
+      }
+    },
+    "font": {
+      "type": "object",
+      "required": ["family"],
+      "additionalProperties": false,
+      "properties": {
+        "family": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["heading", "body", "code"],
+          "properties": {
+            "heading": { "$ref": "#/$defs/token" },
+            "body": { "$ref": "#/$defs/token" },
+            "code": { "$ref": "#/$defs/token" }
+          }
+        }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "required": ["display", "h1", "h2", "h3", "h4", "body", "bodySm", "label", "caption"],
+      "additionalProperties": false,
+      "properties": {
+        "display": { "$ref": "#/$defs/typeStyle" },
+        "h1": { "$ref": "#/$defs/typeStyle" },
+        "h2": { "$ref": "#/$defs/typeStyle" },
+        "h3": { "$ref": "#/$defs/typeStyle" },
+        "h4": { "$ref": "#/$defs/typeStyle" },
+        "body": { "$ref": "#/$defs/typeStyle" },
+        "bodySm": { "$ref": "#/$defs/typeStyle" },
+        "label": { "$ref": "#/$defs/typeStyle" },
+        "caption": { "$ref": "#/$defs/typeStyle" }
+      }
+    },
+    "radius": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["control", "card", "modal", "pill"],
+      "properties": {
+        "control": { "$ref": "#/$defs/token" },
+        "card": { "$ref": "#/$defs/token" },
+        "modal": { "$ref": "#/$defs/token" },
+        "pill": { "$ref": "#/$defs/token" }
+      }
+    },
+    "shadow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["card", "dropdown", "modal"],
+      "properties": {
+        "card": { "$ref": "#/$defs/token" },
+        "dropdown": { "$ref": "#/$defs/token" },
+        "modal": { "$ref": "#/$defs/token" }
+      }
+    }
+  },
+  "$defs": {
+    "token": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^\\{[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)+\\}$"
+        },
+        {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!.*(?:/\\*|\\*/|[;{}]|!\\s*important|\\b(?:url|var)\\s*\\())[^\\u0000-\\u001F\\u007F]+$"
+        }
+      ]
+    },
+    "stateGroup": {
+      "type": "object",
+      "required": ["info", "success", "warning", "danger"],
+      "additionalProperties": false,
+      "properties": {
+        "info": { "$ref": "#/$defs/token" },
+        "success": { "$ref": "#/$defs/token" },
+        "warning": { "$ref": "#/$defs/token" },
+        "danger": { "$ref": "#/$defs/token" }
+      }
+    },
+    "stateGroupWithSolid": {
+      "type": "object",
+      "required": ["info", "success", "warning", "danger", "onSolid"],
+      "additionalProperties": false,
+      "properties": {
+        "info": { "$ref": "#/$defs/token" },
+        "success": { "$ref": "#/$defs/token" },
+        "warning": { "$ref": "#/$defs/token" },
+        "danger": { "$ref": "#/$defs/token" },
+        "onSolid": { "$ref": "#/$defs/token" }
+      }
+    },
+    "typeStyle": {
+      "type": "object",
+      "required": ["fontFamily", "fontSize", "lineHeight", "fontWeight", "letterSpacing"],
+      "additionalProperties": false,
+      "properties": {
+        "fontFamily": { "$ref": "#/$defs/token" },
+        "fontSize": { "$ref": "#/$defs/token" },
+        "lineHeight": { "$ref": "#/$defs/token" },
+        "fontWeight": { "$ref": "#/$defs/token" },
+        "letterSpacing": { "$ref": "#/$defs/token" }
+      }
+    }
+  }
+}