@neatui/css 4.2.1 → 4.2.3

package/package.json

@@ -1,18 +1,70 @@
 {
   "name": "@neatui/css",
-  "version": "4.2.1",
-  "description": "neatui",
+  "version": "4.2.3",
+  "description": "NeatUI constrained atomic design system — SCSS source for production themes, plus preview CSS with default light/dark",
   "main": "./neatui.scss",
+  "sass": "./neatui.scss",
+  "style": "./dist/neatui.preview.min.css",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "author": "xiaojunbo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/neatui/neatui.git",
+    "directory": "@neatui/css"
+  },
+  "homepage": "https://neatui.fekit.cn",
+  "bugs": {
+    "url": "https://gitlab.com/neatui/neatui/issues"
+  },
+  "keywords": [
+    "neatui",
+    "atomic-css",
+    "design-system",
+    "scss",
+    "theme",
+    "css",
+    "preview"
+  ],
+  "files": [
+    "core",
+    "components",
+    "tokens",
+    "dist",
+    "neatui.scss",
+    "preview.scss",
+    "index.scss",
+    "index.js",
+    "GUIDE.md",
+    "MIGRATION-4.0.md",
+    "MIGRATION-4.1.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "sass": "./neatui.scss",
+      "style": "./dist/neatui.preview.min.css",
+      "default": "./neatui.scss"
+    },
+    "./neatui.scss": "./neatui.scss",
+    "./preview.scss": "./preview.scss",
+    "./preview": "./dist/neatui.preview.min.css",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "build": "yarn build:scss && yarn build:optimize && yarn build:minify",
+    "build": "yarn build:scss && yarn build:preview && yarn build:optimize && yarn build:minify",
     "build:scss": "sass neatui.scss dist/neatui.css --no-source-map",
-    "build:optimize": "postcss dist/neatui.css -o dist/neatui.css --no-map",
-    "build:minify": "cleancss -o dist/neatui.min.css dist/neatui.css"
+    "build:preview": "sass preview.scss dist/neatui.preview.css --no-source-map",
+    "build:optimize": "postcss dist/neatui.css -o dist/neatui.css --no-map && postcss dist/neatui.preview.css -o dist/neatui.preview.css --no-map",
+    "build:minify": "cleancss -o dist/neatui.min.css dist/neatui.css && cleancss -o dist/neatui.preview.min.css dist/neatui.preview.css",
+    "tokens:generate": "node scripts/generate-vscode-snapshot.mjs && node scripts/generate-docs-index.mjs",
+    "tokens:check": "node scripts/generate-vscode-snapshot.mjs --check",
+    "tokens:docs": "node scripts/generate-docs-index.mjs",
+    "validate": "node scripts/validate-grammar.mjs",
+    "prepublishOnly": "yarn build"
   },
   "peerDependencies": {},
   "devDependencies": {

package/preview.scss

@@ -0,0 +1,10 @@
+// Preview bundle for trial / CDN demos.
+// Includes official default light + dark themes.
+// Production projects should use SCSS:
+//   $theme: (...);
+//   @use '@neatui/css' as *;
+//   @include theme($theme);
+
+@use './neatui.scss' as *;
+
+@include theme();

package/tokens/grammar.cjs

@@ -0,0 +1,310 @@
+'use strict';
+
+/**
+ * Shared NeatUI grammar validator (Node / CommonJS).
+ * Pure: pass tokens or a prebuilt grammar spec — no filesystem I/O.
+ */
+
+function resolveValueGroup(tokens, groupRef) {
+  const [root, key] = groupRef.split('.');
+  const group = tokens[root]?.[key];
+  if (!Array.isArray(group)) {
+    throw new Error(`Unknown value group: ${groupRef}`);
+  }
+  return group;
+}
+
+function collectManagedValues(tokens, attrDef) {
+  if (Array.isArray(attrDef.values)) {
+    return attrDef.values.map((item) => item.value);
+  }
+  const values = [];
+  for (const ref of attrDef.valueGroups || []) {
+    for (const item of resolveValueGroup(tokens, ref)) {
+      values.push(item.value);
+    }
+  }
+  return values;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function buildGrammarSpec(tokens) {
+  const attributes = {};
+  for (const [name, def] of Object.entries(tokens.attributes || {})) {
+    if (!def.managed) continue;
+    attributes[name] = {
+      openEnded: Boolean(def.openEnded),
+      expandResponsive: Boolean(def.expandResponsivePrefixes),
+      values: collectManagedValues(tokens, def),
+      intent: def.intent || '',
+    };
+  }
+
+  return {
+    schemaVersion: tokens.schemaVersion,
+    cssVersion: tokens.cssVersion,
+    grades: (tokens.grades || []).map((item) => item.value),
+    semanticColors: (tokens.semanticColors || []).map((item) => item.value),
+    responsivePrefixes: tokens.breakpoints?.attributeResponsivePrefixes || ['mob', 'pad'],
+    classPatterns: (tokens.classPatterns || []).map((item) => ({
+      id: item.id,
+      intent: item.intent,
+      example: item.example,
+      pattern: item.pattern,
+    })),
+    attributes,
+  };
+}
+
+function compileClassPatterns(spec) {
+  const grades = (spec.grades || []).map(escapeRegExp).join('|');
+  const colors = (spec.semanticColors || []).map(escapeRegExp).join('|');
+
+  return (spec.classPatterns || []).map((item) => {
+    const source = String(item.pattern)
+      .split('({grade})')
+      .join(`(${grades})`)
+      .split('({semanticColor})')
+      .join(`(${colors})`);
+    return {
+      id: item.id,
+      intent: item.intent,
+      example: item.example,
+      regex: new RegExp(source),
+    };
+  });
+}
+
+function createValidatorFromSpec(spec) {
+  const classPatterns = compileClassPatterns(spec);
+  const responsivePrefixes = new Set(spec.responsivePrefixes || ['mob', 'pad']);
+
+  const attributes = {};
+  for (const [name, def] of Object.entries(spec.attributes || {})) {
+    attributes[name] = {
+      openEnded: Boolean(def.openEnded),
+      expandResponsive: Boolean(def.expandResponsive),
+      values: new Set(def.values || []),
+      intent: def.intent || '',
+    };
+  }
+
+  function stripResponsivePrefix(token) {
+    const match = /^([a-z]+):(.+)$/i.exec(token);
+    if (!match) return { prefix: null, base: token };
+    const [, prefix, base] = match;
+    if (!responsivePrefixes.has(prefix)) {
+      return { prefix: null, base: token, unknownPrefix: prefix };
+    }
+    return { prefix, base };
+  }
+
+  function validateClassToken(raw) {
+    const token = String(raw || '').trim();
+    if (!token) return null;
+
+    const { prefix, base, unknownPrefix } = stripResponsivePrefix(token);
+    if (unknownPrefix) {
+      return {
+        kind: 'class',
+        token,
+        ok: false,
+        reason: `未知响应前缀 \`${unknownPrefix}:\`（允许: ${[...responsivePrefixes].join(', ')}）`,
+      };
+    }
+
+    for (const pattern of classPatterns) {
+      if (pattern.regex.test(base)) {
+        return {
+          kind: 'class',
+          token,
+          ok: true,
+          patternId: pattern.id,
+          prefix,
+          base,
+        };
+      }
+    }
+
+    return {
+      kind: 'class',
+      token,
+      ok: false,
+      reason: `无法匹配 token schema 中的 classPatterns（示例: ${classPatterns
+        .slice(0, 3)
+        .map((item) => item.example)
+        .join(', ')}…）`,
+      base,
+      prefix,
+    };
+  }
+
+  function validateAttributeToken(attrName, raw) {
+    const token = String(raw || '').trim();
+    if (!token) return null;
+
+    const def = attributes[attrName];
+    if (!def) {
+      return {
+        kind: 'attr',
+        attr: attrName,
+        token,
+        ok: false,
+        reason: `属性 \`${attrName}\` 不在 token schema 的 managed attributes 中`,
+      };
+    }
+
+    const { prefix, base, unknownPrefix } = stripResponsivePrefix(token);
+    if (unknownPrefix) {
+      return {
+        kind: 'attr',
+        attr: attrName,
+        token,
+        ok: false,
+        reason: `未知响应前缀 \`${unknownPrefix}:\``,
+      };
+    }
+
+    if (prefix && !def.expandResponsive) {
+      return {
+        kind: 'attr',
+        attr: attrName,
+        token,
+        ok: false,
+        reason: `属性 \`${attrName}\` 不支持响应前缀`,
+      };
+    }
+
+    if (def.values.has(base) || def.openEnded) {
+      return {
+        kind: 'attr',
+        attr: attrName,
+        token,
+        ok: true,
+        prefix,
+        base,
+        openEnded: def.openEnded && !def.values.has(base),
+      };
+    }
+
+    const sample = [...def.values].slice(0, 8).join(', ');
+    return {
+      kind: 'attr',
+      attr: attrName,
+      token,
+      ok: false,
+      reason: `\`${base}\` 不是 \`${attrName}\` 的合法值（例如: ${sample}${def.values.size > 8 ? '…' : ''}）`,
+      base,
+      prefix,
+    };
+  }
+
+  function validateClassString(classString) {
+    return String(classString || '')
+      .split(/\s+/)
+      .map(validateClassToken)
+      .filter(Boolean);
+  }
+
+  function validateAttributeString(attrName, valueString) {
+    return String(valueString || '')
+      .split(/\s+/)
+      .map((token) => validateAttributeToken(attrName, token))
+      .filter(Boolean);
+  }
+
+  function extractFromMarkup(source) {
+    const classes = [];
+    const attrs = [];
+
+    for (const match of String(source).matchAll(
+      /\bclass(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi,
+    )) {
+      classes.push(match[1] ?? match[2] ?? match[3] ?? '');
+    }
+
+    for (const name of Object.keys(attributes)) {
+      const re = new RegExp(
+        `\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`,
+        'gi',
+      );
+      for (const match of String(source).matchAll(re)) {
+        attrs.push({ name, value: match[1] ?? match[2] ?? match[3] ?? '' });
+      }
+    }
+
+    return { classes, attrs };
+  }
+
+  function validateMarkup(source) {
+    const extracted = extractFromMarkup(source);
+    const results = [];
+    for (const classString of extracted.classes) {
+      results.push(...validateClassString(classString));
+    }
+    for (const attr of extracted.attrs) {
+      results.push(...validateAttributeString(attr.name, attr.value));
+    }
+    return results;
+  }
+
+  /**
+   * Flag only tokens that look like NeatUI / common drift — not arbitrary custom classes.
+   */
+  function looksLikeNeatuiClass(token) {
+    const base = String(token || '').replace(/^(?:mob|pad):/, '');
+    if (!base) return false;
+    if (/^(?:co|bg|fs|lh|r|o|z)-/.test(base)) return true;
+    if (/^-?(?:n|nx|ny|nt|nr|nb|nl|m|mx|my|mt|mr|mb|ml)-/.test(base)) return true;
+    if (/^(?:w|min-w|max-w|h|min-h|max-h)-/.test(base)) return true;
+    // Common utility drift that should fail loudly
+    if (/^(?:p|px|py|pt|pr|pb|pl|gap|space-[xy])-\d/.test(base)) return true;
+    if (/^(?:text|bg|border)-(?:red|blue|green|gray|slate|zinc)-\d{2,3}$/.test(base)) return true;
+    if (/^(?:justify|items|content)-/.test(base)) return true;
+    return false;
+  }
+
+  function validateClassStringSelective(classString) {
+    return validateClassString(classString).filter((item) => looksLikeNeatuiClass(item.token));
+  }
+
+  function validateMarkupSelective(source) {
+    const extracted = extractFromMarkup(source);
+    const results = [];
+    for (const classString of extracted.classes) {
+      results.push(...validateClassStringSelective(classString));
+    }
+    for (const attr of extracted.attrs) {
+      results.push(...validateAttributeString(attr.name, attr.value));
+    }
+    return results;
+  }
+
+  return {
+    spec,
+    attributes,
+    classPatterns,
+    validateClassToken,
+    validateAttributeToken,
+    validateClassString,
+    validateAttributeString,
+    validateClassStringSelective,
+    extractFromMarkup,
+    validateMarkup,
+    validateMarkupSelective,
+    looksLikeNeatuiClass,
+  };
+}
+
+function createValidator(tokens) {
+  return createValidatorFromSpec(buildGrammarSpec(tokens));
+}
+
+module.exports = {
+  buildGrammarSpec,
+  createValidator,
+  createValidatorFromSpec,
+};