@neatui/css 4.2.2 → 4.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neatui/css",
-  "version": "4.2.2",
+  "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",
@@ -63,6 +63,7 @@
     "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": {},

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,
+};

package/tokens/neatui.tokens.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "cssVersion": "4.2.1",
+  "cssVersion": "4.2.2",
   "name": "neatui-tokens",
   "description": "NeatUI constrained design tokens — single source for grades, semantic colors, flex coordinates, breakpoints, and core attribute values. Does not enumerate project theme color names.",
   "grades": [