ZingGrid HTML Validator

A Node.js CLI tool to validate ZingGrid-generated HTML files against the official Custom Elements Manifest (CEM), Content Model Schema (CMS), and capabilities metadata. It ensures your ZingGrid markup is compliant with component definitions, attribute rules, and parent-child relationships.

Features

• Validates that only valid ZingGrid components are used.
• Checks that attributes exist and have valid values.
• Enforces boolean presence attribute semantics.
• Verifies required parent-child relationships.
• Detects incompatible or dependent attributes.
• Provides structured error reporting with clear error types.

Note: This validator does not work with server-rendered ZingGrid.

Installation

Install dependencies:

npm install

Usage (NPM Script)

npm run validate -- <file.html> [flags]

• <file.html>: Path to the HTML file you want to validate.
• Exit codes:
  • 0 — no errors found
  • 1 — errors detected

Usage (CLI)

npx zinggrid-validate <file.html> [flags]

Usage (Function)

import { validateFile } from './validator.mjs';

// Without flags
let result1 = await validateFile('grid.html');

// With flags
let result2 = await validateFile('grid.html', [
  '--allow-common-attributes',
  '--no-warnings'
]);

The function returns:

{
  success: boolean,
  errors: {type, message, element, attribute}[],
  warnings: {type, message, element, attribute}[],
}

Flags

Skip invalid attribute checking entirely

npm run validate -- file.html --skip-invalid-attributes

Only output errors (no warnings)

npm run validate -- file.html --no-warnings

Allow HTML attributes: id, class, style, title, hidden, role, tabindex

npm run validate -- file.html --allow-common-attributes

Allow specific attributes

npm run validate -- file.html --allow-attributes=data-test,aria-label,foo

Combine flags

npm run validate -- file.html \
  --allow-common-attributes \
  --allow-attributes=data-test \
  --no-warnings

Validator Error Types

| Error Type | Description | Example | |----------------------------------|--------------------------------------------------|--------------------------------------------------------------| | PRESENCE_ATTRIBUTE_ERROR | Boolean presence attribute explicitly set to "true" | <zg-column sort="true"> → should be <zg-column sort> | | INVALID_ATTRIBUTE_ERROR | Attribute does not exist for the component | <zing-grid layout-mode="flex"> when layout-mode is undefined | | INVALID_ATTRIBUTE_VALUE_ERROR | Attribute value does not match type | <zg-column sort="true"> if sort only allows "disabled" | | ATTRIBUTE_DEPENDENCY_ERROR | Attribute requires other attribute(s) | <zing-grid pager-position="top"> requires pager | | INCOMPATIBILITY_ATTRIBUTES_ERROR | Attributes cannot be enabled together | <zing-grid compact row-height="5px"> | | REQUIRED_ELEMENT_PARENT_ERROR | Component missing a required parent | <zg-column> must be a child of <zg-colgroup> | | INVALID_ELEMENT_CHILD_ERROR | Component cannot be a child of this parent | <zg-param> cannot be inside <zing-grid> | | COMPONENT_MISSING_ATTRIBUTE_ERROR | Required attribute missing | <zg-column> missing index | | FILE_NOT_FOUND_ERROR | File to validate not found | N/A | | SERVER_RENDERED_ERROR | Validator does not work on server-rendered grids | <zing-grid server-rendered> | | UNKNOWN_ERROR | Any other unclassified error | N/A |

Validator Warning Types

| Warning Type | Description | Example | |----------------------------------|--------------------------------------------------|--------------------------------------------------------------| | INVALID_ATTRIBUTE_VALUE_WARNING | String value is not a predefined enum value | <zing-grid theme="customTheme" → Theme accepts built-in themes or a custom one, just make sure it is intentional | | NOT_RECOMMENDED_ATTRIBUTE_WARNING | Attribute not recommended to be used | <zing-grid columns='[...]'> not recommended, should set columns with <zg-column> |

Output

• Errors and warnings are printed to stderr.
• Each error includes:
  • type
  • message
  • element
  • attribute (if applicable)
  • value (if applicable)

Example output:

❌ Errors
  - INVALID_ATTRIBUTE_ERROR: <zing-grid>: unknown attribute "layout-mode"
  - PRESENCE_ATTRIBUTE_ERROR: Boolean presence attribute "sort" must not be explicitly set to "true" on <zg-column>

⚠️ Warnings
  - INVALID_ATTRIBUTE_VALUE_WARNING: <zg-column>: "custom-value" is not a predefined value for "align"

If no issues are found:

✅ No CEM issues found