pro-editor-schema 0.2.0 → 0.2.1

package/README.md

@@ -7,41 +7,64 @@ TypeScript library that defines XML/HTML schema rules used by the editor and pro
 - Schema definitions for supported tags and schema codes.
 - Shared schema constants and attribute helpers.
 - Runtime schema lookup utilities.
-- XML validation utilities (`validateXml`, attribute/child validators, footnote and link validators).
+- XML validation utilities (`validateXml` and related validators).
 - Type-safe element factory (`createElement`) based on schema definitions.
 
-## Install and build
+## Install
 
 ```bash
 npm install
-npm run typecheck
-npm run test
-npm run build
 ```
 
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Build in watch mode |
+| `npm run build` | Build CJS, ESM, and type declarations |
+| `npm run typecheck` | Run TypeScript without emitting files |
+| `npm run lint` | Run ESLint on `src/` |
+| `npm run test` | Run tests once with Vitest |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run check` | Run the full verification pipeline (`npm ci`, `typecheck`, `lint`, `test`, `build`) |
+
+For local development, `npm run check` is the fastest way to verify everything before pushing.
+
+## CI
+
+GitHub Actions runs on push and pull requests to `main` / `master`:
+
+- **Typecheck** — `npm run typecheck`
+- **Lint** — `npm run lint`
+- **Test** — `npm test`
+
+Workflow file: `.github/workflows/ci.yml`
+
 ## Project structure
 
-- `src/index.ts`: public exports for schemas, types, shared constants, and validation.
-- `src/schema/schema.types.ts`: core schema and validation-related types.
-- `src/schema/schemas.ts`: central `SCHEMAS` map (`code -> schema`).
-- `src/schema/elementSchemas/elements`: element schema definitions and `ELEMENT_SCHEMAS`.
-- `src/schema/elementSchemas/atoms`: atom schema definitions and `ATOM_SCHEMAS`.
-- `src/schema/elementSchemas/inlineElements`: inline schema definitions and `INLINE_ELEMENT_SCHEMAS`.
-- `src/schema/shared`: shared attribute and ignored-node constants.
-- `src/schema/utils`: schema lookup and element creation helpers.
-- `src/validation`: document validation entrypoint and validation modules.
+- `src/index.ts` — public exports for schemas, types, shared constants, and validation.
+- `src/schema/schema.types.ts` — core schema and validation-related types.
+- `src/schema/schemas.ts` — central `SCHEMAS` map (`code -> schema`).
+- `src/schema/elementSchemas/elements` — element schema definitions and `ELEMENT_SCHEMAS`.
+- `src/schema/elementSchemas/atoms` — atom schema definitions and `ATOM_SCHEMAS`.
+- `src/schema/elementSchemas/inlineElements` — inline schema definitions and `INLINE_ELEMENT_SCHEMAS`.
+- `src/schema/shared` — shared attribute and ignored-node constants.
+- `src/schema/utils` — schema lookup, element creation, and label helpers.
+- `src/validation` — document validation entrypoint and validation modules.
+- `src/**/*.test.ts` — Vitest test files (run with `happy-dom`).
 
 ## Schema model
 
 Each schema defines:
 
-- `code`: internal schema identifier.
-- `kind`: schema category (`element`, `atom`, `inline`).
-- `tag`: uppercase XML tag name used in documents.
-- `requiredAttributes`: required attributes (free or restricted values).
-- `optionalAttributes`: optional attributes (free or restricted values).
-- `defaultChildCode`: preferred child tag (optional, used by some block-like schemas).
-- `allowedChildrenCodes`: allowed child tags and whether each child is required.
+- `code` — internal schema identifier.
+- `kind` — schema category (`element`, `atom`, `inline`).
+- `tag` — uppercase XML tag name used in documents.
+- `requiredAttributes` — required attributes (free or restricted values).
+- `optionalAttributes` — optional attributes (free or restricted values).
+- `defaultChildCode` — preferred child tag (optional, used by some block-like schemas).
+- `allowedChildrenCodes` — allowed child tags and whether each child is required.
+- `matchesElement` — optional predicate to resolve elements that share the same tag (for example `SPAN`, `SECTION1`).
 
 Schemas are combined in `SCHEMAS` from:
 
@@ -49,15 +72,29 @@ Schemas are combined in `SCHEMAS` from:
 - `ATOM_SCHEMAS`
 - `INLINE_ELEMENT_SCHEMAS`
 
+### Resolving schemas from DOM elements
+
+`findSchemaByElement` matches by tag name. When multiple schemas share a tag, the first schema with a matching `matchesElement` predicate wins.
+
+Examples:
+
+- `SPAN` with class `ins` → `insertion`
+- `SPAN` with class `del` → `deletion`
+- `SPAN` with class `cmtQurySection` → `commentQuerySection`
+- `SECTION1` with `role="H1"` → `heading`
+- `SECTION1` with `role="ch"` or a `FOOTNOTE` child → `footnoteSection`
+
+When adding a new schema that reuses an existing tag, define `matchesElement` on every schema that shares that tag.
+
 ## Public API highlights
 
 From `src/index.ts`, consumers can import:
 
-- Types: `Schema`, `SchemaCode`, `ElementSchemaCode`, `AtomSchemaCode`, `InlineSchemaCode`
-- Maps: `SCHEMAS`, `ELEMENT_SCHEMAS`, `ATOM_SCHEMAS`, `INLINE_ELEMENT_SCHEMAS`
-- Utilities: `findSchemaByCode`, `findSchemaByElement`, `createElement`
-- Validators: `validateXml`, `validateFootnotes`, `validateLinkend`, `validateAttributes`, `validateChildren`
-- Shared constants: ignored elements/attributes and global attribute constants
+- **Types:** `Schema`, `SchemaCode`, `ElementSchemaCode`, `AtomSchemaCode`, `InlineSchemaCode`, `ValidationError`
+- **Maps:** `SCHEMAS`, `ELEMENT_SCHEMAS`, `ATOM_SCHEMAS`, `INLINE_ELEMENT_SCHEMAS`
+- **Utilities:** `findSchemaByCode`, `findSchemaByElement`, `createElement`, `ElementLabel`
+- **Validation:** `validateXml`
+- **Shared constants:** ignored elements/attributes, global attribute constants, dependents forbidden elements
 
 ## Usage examples
 
@@ -79,7 +116,6 @@ const para = createElement({
   attributes: {
     store: "body",
     "ele-id": "p-1",
-    role: "body",
   },
 });
 ```
@@ -89,23 +125,41 @@ const para = createElement({
 ```ts
 import { validateXml } from "pro-editor-schema";
 
-const errors = validateXml(rootElement, linkedIds, true);
+const errors = validateXml(
+  rootElement,
+  elementsToLink,
+  linkElements,
+  ["para", "heading"],
+);
 ```
 
-`validateXml` performs:
+`validateXml` parameters:
+
+- `xml` — root element to validate.
+- `elementsToLink` — IDs available as `linkend` targets.
+- `linkElements` — IDs cited by links (used for reference validation).
+- `schemasToValidateAgainst` — schema codes to run attribute/child validation against.
+
+`validateXml` always runs:
+
+- Consecutive footnote number checks
+- Consecutive footnote cue checks
+
+It also runs per-element checks for:
+
+- Link targets (`linkend`) on linkable elements
+- Uncited bibliographic references
+- Unreferenced footnotes
 
-- Footnote sequence checks
-- Footnote cue sequence checks
-- Link target checks (`linkend`)
-- Optional schema-based attribute and child validation when enabled
+Schema-based attribute and child validation only runs for codes listed in `schemasToValidateAgainst`.
 
 ## How validation works
 
 - `validateXml` traverses the XML tree and delegates checks per element.
-- `findSchemaByElement` resolves schema from classes, role, and tag fallback.
-- `validateAttributes` ensures required attributes exist and restricted values are valid.
+- `findSchemaByElement` resolves schema from tag and optional `matchesElement`.
+- `validateAttributes` validates restricted attribute values.
 - `validateChildren` ensures child tags are allowed and required children exist.
-- `validateFootnotes` and `validateLinkend` provide cross-reference integrity checks.
+- `validateFootnotes`, `validateLinkend`, and `validateReferenceCited` provide cross-reference integrity checks.
 
 Validation results use `ValidationError`:
 
@@ -118,23 +172,23 @@ Validation results use `ValidationError`:
 
 ## Adding or updating a schema
 
-1. Create or update schema file in one of:
+1. Create or update a schema file in one of:
    - `src/schema/elementSchemas/elements`
    - `src/schema/elementSchemas/atoms`
    - `src/schema/elementSchemas/inlineElements`
-2. Define schema with `createSchema(...)`.
-3. Add it to the corresponding registry:
+2. Define the schema with `createSchema(...)`.
+3. If the tag is already used by another schema, add a `matchesElement` predicate.
+4. Register it in the corresponding map:
    - `ELEMENT_SCHEMAS`
    - `ATOM_SCHEMAS`
    - `INLINE_ELEMENT_SCHEMAS`
-4. Ensure the schema code exists in the matching union type in `schema.types.ts`.
-5. If needed, export constants/types from folder `index.ts` and `src/index.ts`.
-6. Run:
-   - `npm run typecheck`
-   - `npm run test`
+5. Ensure the schema code exists in the matching union type in `schema.types.ts`.
+6. Add or update tests for any new validation or utility behavior.
+7. Run `npm run check`.
 
 ## Notes
 
 - Tag matching is done in uppercase in schema definitions and validation.
 - Some schema codes represent block/group-like structures while still being typed as `kind: "element"` in the current model.
 - Ignored attributes and ignored UI helper elements are excluded from strict validation by design.
+- Track-changes atoms (`insertion`, `deletion`) are unwrapped when validating required children.

package/dist/index.js

@@ -2371,7 +2371,7 @@ var isIgnoredValidation = (code) => IGNORED_VALIDATION_ELEMENT_SELECTORS.include
 var findSchemaByCode = (code) => SCHEMAS[code];
 var findSchemaByElement = (element) => {
   const schema = Object.values(SCHEMAS).find(
-    (schema2) => schema2.tag == element.tagName && schema2.matchesElement?.(element)
+    (schema2) => schema2.tag == element.tagName && (!schema2.matchesElement || schema2.matchesElement(element))
   );
   return schema;
 };
@@ -2400,7 +2400,7 @@ var createElement = ({
   return element;
 };
 
-// src/schema/utils/labelElements.ts
+// src/schema/shared/labelElements.ts
 var ElementLabel = {
   referenceBibliomixed: "Reference Bibliomixed",
   referenceBibliography: "Reference Bibliography",

package/dist/index.mjs

@@ -2303,7 +2303,7 @@ var isIgnoredValidation = (code) => IGNORED_VALIDATION_ELEMENT_SELECTORS.include
 var findSchemaByCode = (code) => SCHEMAS[code];
 var findSchemaByElement = (element) => {
   const schema = Object.values(SCHEMAS).find(
-    (schema2) => schema2.tag == element.tagName && schema2.matchesElement?.(element)
+    (schema2) => schema2.tag == element.tagName && (!schema2.matchesElement || schema2.matchesElement(element))
   );
   return schema;
 };
@@ -2332,7 +2332,7 @@ var createElement = ({
   return element;
 };
 
-// src/schema/utils/labelElements.ts
+// src/schema/shared/labelElements.ts
 var ElementLabel = {
   referenceBibliomixed: "Reference Bibliomixed",
   referenceBibliography: "Reference Bibliography",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pro-editor-schema",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pro Editor XML schemas",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,13 +19,18 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "check": "npm ci && npm run typecheck && npm run lint && npm run test && npm run build"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
     "happy-dom": "^20.0.10",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
+    "typescript-eslint": "^8.62.1",
     "vitest": "^3.2.4"
   }
 }