uxml-preview 0.4.0 → 0.5.0

package/dist/model/types.d.ts

@@ -66,6 +66,8 @@ export interface Attribute {
      */
     value: string;
     span: Span;
+    /** Render-only provenance for a cloned/overridden attribute. */
+    sourceDocument?: string | null;
 }
 /**
  * Three spans rather than one, so that an edit stays local.
@@ -111,6 +113,21 @@ export interface ElementNode {
      * synthesized (copy a sibling's leading whitespace).
      */
     childrenDirty: boolean;
+    /**
+     * A render-only node synthesized while a template instance is expanded.
+     * Parsed nodes leave this absent; serialization never sees the derived tree.
+     */
+    derived?: {
+        kind: 'template-container';
+        /** The source `<ui:Instance>` that caused this container to exist. */
+        instance: NodeId;
+    };
+    /** URL of the UXML document that supplied a render-only clone. */
+    sourceDocument?: string | null;
+    /** URL that sourceDocument was resolved from, when it was relative. */
+    sourceDocumentFrom?: string | null;
+    /** Node id inside sourceDocument for a render-only clone. */
+    sourceNode?: NodeId;
 }
 export type Combinator = 'descendant' | 'child';
 /**
@@ -209,9 +226,15 @@ export interface StyleSheet {
      * passed directly to `parse()`. Used in warning messages only.
      */
     origin: string | null;
+    /** Containing URL used to resolve origin in a derived template document. */
+    sourceDocumentFrom?: string | null;
     items: SheetItem[];
 }
-export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsupported-selector' | 'unsupported-unit' | 'version-dependent' | 'asset-unresolved' | 'import-unresolved' | 'malformed';
+export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsupported-selector' | 'unsupported-unit' | 'version-dependent' | 'asset-unresolved' | 'import-unresolved' | 'malformed' | 'template-src-unresolved' | 'template-not-declared' | 'template-cycle' | 'template-depth-exceeded' | 'override-target-missing' | 'duplicate-name-in-tree' | 'package-path-not-searched' | 'template-slot-unsupported' | 'override-style-ignored';
+/** A mapped type consumers can use for exhaustive warning classification. */
+export type WarningKindMap<T> = {
+    [K in WarningKind]: T;
+};
 /**
  * Never a thrown error. One unsupported property must not take down the render
  * (see CLAUDE.md rule 6).
@@ -222,6 +245,8 @@ export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsu
 export interface Warning {
     kind: WarningKind;
     message: string;
+    /** Document URL for a warning originating outside the entry UXML. */
+    sourceDocument?: string | null;
     /** Text location, when the warning has one. */
     at?: SourceRef;
     /** Element the warning is about, when it has one. Lets the UI highlight it. */
@@ -276,11 +301,17 @@ export type StyleOrigin = {
     kind: 'inline';
     node: NodeId;
     declIndex: number;
+    /** URL of the UXML/USS document that supplied this declaration. */
+    sourceDocument?: string | null;
+    sourceDocumentFrom?: string | null;
 } | {
     kind: 'rule';
     sheet: number;
     item: number;
     declIndex: number;
+    /** URL of the stylesheet containing the declaration, when external. */
+    sourceDocument?: string | null;
+    sourceDocumentFrom?: string | null;
     /**
      * Pseudo-class states the matched selector required, e.g. `['hover']`.
      *

package/dist/template/expand.d.ts

@@ -0,0 +1,26 @@
+import { UxmlDocument, Warning } from '../model/types';
+export type TemplateResolver = (url: string, from: string | null) => string | null;
+type TemplateDocumentParser = (source: string, resolver: TemplateResolver | undefined) => UxmlDocument;
+/** Internal registration avoids making the template loader depend on index.ts. */
+export declare function registerTemplateParser(parser: TemplateDocumentParser): void;
+/** Called by parse() so expansion can reuse the exact resolver the host passed. */
+export declare function rememberTemplateResolver(document: UxmlDocument, resolver: TemplateResolver | undefined): void;
+/**
+ * Purpose:      collect direct template dependencies without a regex pass.
+ * Deps/Effects: parses `source`; no I/O and no model mutation.
+ * Ensures:      returns decoded `<Template src>` values in source order.
+ */
+export declare function collectDependencies(source: string): string[];
+export interface TemplateExpansion {
+    /** Render-only document. The caller must keep the original for serialization. */
+    document: UxmlDocument;
+    warnings: readonly Warning[];
+}
+/**
+ * Expand all instances in a document into a derived tree.
+ *
+ * The entry UXML is represented as a tiny loaded record so the same recursive
+ * path handles top-level and nested declarations. Its URL is null by contract.
+ */
+export declare function expandTemplates(document: UxmlDocument): TemplateExpansion;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uxml-preview",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Preview Unity UI Toolkit UXML/USS in a browser without the Unity Editor. Uses Yoga (WebAssembly), the same layout engine UI Toolkit uses: 660 of 676 element coordinates identical to Unity 6. Parses and writes files back byte-for-byte.",
   "keywords": [
     "unity",
@@ -69,9 +69,11 @@
     "test:roundtrip": "vitest run tests/roundtrip",
     "test:golden": "vitest run tests/golden --passWithNoTests",
     "golden:emit": "node --experimental-strip-types --no-warnings scripts/emit-golden-cases.mjs",
+    "template:emit": "node --experimental-strip-types --no-warnings scripts/emit-template-cases.mjs",
     "golden:update": "node scripts/update-golden.mjs",
+    "check:self-reference": "node scripts/check-self-reference.mjs",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+    "prepublishOnly": "npm run check:self-reference && npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "yoga-layout": "^3.2.1"