uxml-preview 0.1.0

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,55 @@
+# Third-party notices
+
+`uxml-preview` itself is Apache-2.0 (see `LICENSE`). This file covers software
+redistributed **inside build output**, which carries its own obligations.
+
+## Where this applies
+
+| Artifact | Bundles third-party code? | Notice required |
+|---|---|---|
+| npm package (`dist/`) | No — `yoga-layout` is an external dependency the consumer installs | No |
+| Playground site (`dist-site/`) | **Yes** — `yoga-layout`, including its WebAssembly binary, is inlined | **Yes** |
+
+The published playground is a single self-contained bundle, so it redistributes
+`yoga-layout`. MIT requires the copyright notice and permission notice to travel
+with such copies, which is what this file is for; the site build also emits a
+banner pointing here.
+
+## yoga-layout
+
+- Version: 3.2.1
+- Upstream: https://github.com/facebook/yoga
+- Declared license: MIT (`"license": "MIT"` in its `package.json`; every shipped
+  source file carries the Meta copyright header below)
+
+> Note: the published npm package does not include a `LICENSE` file. The
+> permission notice below is the standard MIT text, matching the license the
+> package declares and the header its sources carry.
+
+```
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Build and test tooling
+
+Vite, Vitest, TypeScript, jsdom, pixelmatch and pngjs are development
+dependencies. They are not redistributed in either artifact above, so they carry
+no notice obligation here.

package/dist/controls/registry.d.ts

@@ -0,0 +1,10 @@
+import { ElementNode } from '../model/types';
+export interface ControlSpec {
+    /** Renders the `text` attribute as its content. */
+    hasText: boolean;
+}
+/** The document container. Not a control, but it is the panel's root box. */
+export declare const ROOT_LOCAL_NAME = "UXML";
+export declare function controlFor(node: ElementNode): ControlSpec | null;
+export declare function isRoot(node: ElementNode): boolean;
+export declare function supportedControlNames(): string[];

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { NodeId, UxmlDocument, Warning } from './model/types';
+import { LayoutBox, MeasureText } from './layout/yoga';
+/**
+ * uxml-preview — public API surface.
+ *
+ * Phase 1: the document model is defined (src/model/types.ts). The functions
+ * below are still signatures only; implementations land in Phases 2–4.
+ * See docs/ROADMAP.md.
+ */
+export type { Span, SourceRef, NodeId, ElementName, Attribute, ElementSpans, ElementNode, Combinator, SimpleSelector, SelectorPart, Selector, Declaration, Rule, SheetItem, StyleSheet, WarningKind, Warning, UxmlDocument, StyleOrigin, } from './model/types';
+export { loadLayoutEngine, isLayoutEngineReady, liveNodeCount } from './layout/yoga';
+export type { LayoutBox, MeasureText, TextContext, TextMetrics } from './layout/yoga';
+export { createDefaultMeasureText } from './render/measure';
+export { NODE_ATTRIBUTE } from './render/paint';
+export { supportedControlNames } from './controls/registry';
+export { resolveStyles, explainProperty } from './style/resolve';
+export type { Candidate, ComputedStyle, ComputedValue, ResolveOptions, ResolveResult, } from './style/resolve';
+export type { Specificity } from './style/specificity';
+export { isInherited } from './style/properties';
+/**
+ * Parse UXML and USS text into a document model.
+ *
+ * Never throws on unsupported input: unknown controls, properties and selectors
+ * are kept verbatim so they survive `serialize`. Only malformed text produces a
+ * warning here — whether something can be *rendered* is decided downstream.
+ */
+export interface ParseOptions {
+    /**
+     * Loads the text of an `@import`ed stylesheet. Return `null` when the path
+     * cannot be resolved; the import is then reported as a warning and its rules
+     * simply do not participate.
+     *
+     * USS import paths look like `project://database/Assets/UI/base.uss`, which
+     * only the host application knows how to turn into file contents.
+     */
+    resolveImport?: (url: string) => string | null;
+}
+export declare function parse(uxml: string, uss?: string, options?: ParseOptions): UxmlDocument;
+/**
+ * Serialize a document model back to UXML and USS text.
+ *
+ * Ensures: for a document with no edits, the output is byte-identical to the
+ * input — untouched nodes are re-emitted by slicing `UxmlDocument.source`
+ * rather than being regenerated. After an edit, only the edited region changes.
+ */
+export declare function serialize(doc: UxmlDocument): {
+    uxml: string;
+    uss: string;
+};
+export interface RenderOptions {
+    /**
+     * Resolves Unity asset references to something a browser can load.
+     *
+     * USS background images look like `url("project://database/Assets/foo.png")`
+     * or `resource("foo")`. Browsers cannot load these, so the host application
+     * must map them to real URLs. Return `null` to draw a placeholder instead.
+     */
+    resolveAsset?: (path: string) => string | null;
+    /** Panel size in pixels. Defaults to the container's client size. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Measures a control's text.
+     *
+     * The default uses a canvas, whose metrics move with the platform and the
+     * installed fonts. Anything that needs a reproducible result — golden tests
+     * above all — should supply its own.
+     */
+    measureText?: MeasureText;
+    /** Pseudo-classes to render as active, e.g. `new Set(['hover'])`. */
+    activeStates?: ReadonlySet<string>;
+}
+export interface RenderResult {
+    /**
+     * Everything the renderer could not honour: unsupported controls, properties,
+     * selectors and units, plus unresolved assets. Distinct from
+     * `UxmlDocument.warnings`, which only covers malformed input.
+     */
+    warnings: readonly Warning[];
+    /** Painted element per model node. Lets a host map a click back to the tree. */
+    elements: ReadonlyMap<NodeId, HTMLElement>;
+    /**
+     * What Yoga computed, in panel coordinates, before any of it became CSS.
+     *
+     * Exposed because a layout bug has two possible homes — the Yoga mapping or
+     * the painting — and CLAUDE.md's rule is to read both rather than guess.
+     * Golden tests compare these numbers rather than pixels.
+     */
+    boxes: ReadonlyMap<NodeId, LayoutBox>;
+    /**
+     * Deps/Effects: frees the Yoga node tree (`freeRecursive`) and removes the
+     * generated DOM from the container.
+     *
+     * Requires: must be called before re-rendering into the same container. Yoga
+     * nodes are WASM handles and are not garbage collected.
+     */
+    dispose(): void;
+}
+/**
+ * Purpose:      draw a document into a container element.
+ * Deps/Effects: replaces the container's children and allocates Yoga nodes.
+ *               Call `dispose()` on the result before rendering again.
+ * Requires:     `await loadLayoutEngine()` once, first. Yoga is WebAssembly and
+ *               cannot be loaded synchronously; keeping that await out here is
+ *               what lets this function stay synchronous, which the playground
+ *               and the golden tests both want.
+ */
+export declare function render(doc: UxmlDocument, container: HTMLElement, options?: RenderOptions): RenderResult;