uxml-preview 0.6.0 → 0.7.0

package/dist/controls/theme.d.ts

@@ -1,87 +1,63 @@
 /**
  * Unity's control defaults, as far as we have measured them.
  *
- * Unity ships a theme stylesheet that gives controls their own margin, padding
- * and border before any author USS runs. This renderer supplied none of it, so
- * every Button sat 3px left and 1px high of where Unity puts it — invisible on
- * one button and compounding across a row.
- *
- * **Only measured values live here.** Every declaration below was derived from
- * a Unity layout dump in tests/golden/unity/, and adding `Button`'s margin
- * moved all five Button cases from 18 mismatched values to zero. Values read
- * from Unity's source instead would look identical in this file while being
- * wrong in a way no test could see: they would not appear in the unmeasured
- * list, so they would quietly pass for ground truth.
- *
- * Two kinds of measurement feed this file, and the second was a long time
- * coming. Geometry comes from the coordinate dumps. `-unity-text-align` cannot:
- * where a glyph sits inside a box does not move the box, so no dump can ever
- * see it. It came from the Step 6 eye check — Unity centres a Button's label
- * and this renderer had it at the top left, which is visible the moment the two
- * screenshots sit side by side and invisible in 368 compared numbers.
- *
- * `opacity` on `:disabled` came from the same screenshots, but by sampling
- * pixels rather than looking. Unity's disabled Drop button is rgb(41,50,67);
- * the base colour rgb(58,74,104) composited at half over the footer's
- * rgb(24,26,31) is (41, 50, 67.5) — all three channels exact. That arithmetic
- * is the evidence, and it is why the value is 0.5 and not a number that merely
- * looked about right.
- *
- * Getting there took two wrong turns worth recording. First the author's
- * `Button:disabled` rule was blamed for not applying — it genuinely does not,
- * because `#DropButton` outranks it, in both engines. Then Unity was accused of
- * ranking state rules above specificity, and `state-vs-id` and `state-vs-inline`
- * refuted that: Unity answers 40 to both, exactly as this cascade already did.
- * The dimming was never about the cascade at all.
- *
- * What is deliberately absent, and why:
- *
- *   - `Label` — measured, and it has no default margin. `inherit-vs-direct`
- *     puts an explicitly-sized Label at the origin of a sized parent, and Unity
- *     reports x=0 y=0. Nothing to add is a result, not an omission.
- *   - padding, border, font — invisible to the cases we have. Every compared
- *     element is explicitly sized, and USS is border-box, so padding and border
- *     do not move the outer rectangle. They are unmeasured, so they are not here.
- *   - `Label`'s text alignment — the eye check could not separate it from the
- *     box at this size. Unmeasured, so absent.
- *
- * The class names were a separate claim from the values, and are now measured
- * too. `unity-button` came from Unity's documented `Button.ussClassName`, which
- * the margin dumps said nothing about — they proved the spacing, not the
- * selector delivering it. The golden case `theme-class-hook` was written to
- * settle exactly that, and Unity answered on 2026-08-05: a `.unity-button` rule
- * in author USS reaches a bare `<ui:Button>`, sizing it 120×40 in both engines.
- * The selector below is therefore measured, not assumed.
- */
-/** Where every value in this file was measured. Theme values move between versions. */
-export declare const THEME_UNITY_VERSION = "6000.0.40f1";
-/**
- * Parsed once and spliced in ahead of author sheets, so an author rule of equal
- * specificity wins on order — which is how a theme stylesheet behaves in Unity.
- *
- * Class selectors rather than type selectors, also for Unity's reasons: a theme
- * rule at `.unity-button` (0,1,0) beats an author's `Button { }` (0,0,1), and
- * that is a real Unity gotcha worth reproducing rather than smoothing over.
+ * Unity supplies control spacing before author USS runs; omitting it once put
+ * every Button 3px left and 1px high, compounding across a row. Only measured
+ * values live here. Values copied from Unity's source could look just as
+ * authoritative while being wrong without appearing in the unmeasured list.
+ *
+ * There are two measured themes: editor in an EditorWindow on 6000.0.40f1
+ * (tests/layout/unity/6000.0.40f1/probe-editor-070/), runtime on a real runtime
+ * panel on 6000.3.25f1 (tests/layout/unity/6000.3.25f1/probe-panel/), with
+ * identical runtime values on 6000.0.40f1. Geometry comes from coordinate dumps.
+ * `-unity-text-align` came from the Step 6 eye check: a glyph's position inside
+ * its box does not move the box, so 368 matching coordinates could not reveal
+ * that Unity centred Button text while this renderer put it at the top left.
+ *
+ * Opacity 0.5 was established by pixel arithmetic: Unity's disabled Drop button
+ * is rgb(41,50,67); its base rgb(58,74,104) composited at half over the footer's
+ * rgb(24,26,31) gives (41,50,67.5). It is measured, not chosen by appearance.
+ * `nested-disabled` now places it on `.unity-disabled`, which Unity adds only
+ * where enabled="false" was written. This replaces the earlier `:disabled`
+ * rule that applied half opacity at every disabled level and dimmed twice.
+ *
+ * Two wrong turns preceded that result. The author's `Button:disabled` rule
+ * was first blamed for not applying, but `#DropButton` outranks it in both
+ * engines. Then state rules were thought to outrank specificity; `state-vs-id`
+ * and `state-vs-inline` both returned 40 in Unity, refuting that explanation.
+ * The dimming was never a cascade defect.
+ *
+ * Earlier omissions, superseded by c07-existing and c07-states:
+ * - "Label has nothing" described only its measured editor margin; Label and
+ *   Button spacing and flex-shrink are now measured for both themes.
+ * - "Padding, border, font deliberately absent" is superseded by measured
+ *   padding, borders, colours and font size; Label text alignment stays absent.
+ *
+ * Class hooks are a separate claim from values: margin dumps proved spacing,
+ * not the selector delivering it. `unity-button` began with the documented
+ * Button.ussClassName; `theme-class-hook` then confirmed on 2026-08-05 that
+ * author `.unity-button` reaches a bare <ui:Button>, sizing it 120×40 in Unity
+ * and this renderer. The hook is measured, not assumed.
  */
-export declare const THEME_USS = ":disabled {\n  opacity: 0.5;\n}\n\n.unity-button {\n  margin: 1px 3px;\n  -unity-text-align: middle-center;\n}\n";
+export type Theme = 'runtime' | 'editor';
+export declare const DEFAULT_THEME: Theme;
+/** Unity version used to measure the editor theme. */
+export declare const THEME_UNITY_VERSION: string;
+/** Unity measurement version for each theme. */
+export declare const THEME_UNITY_VERSIONS: Readonly<Record<Theme, string>>;
+/** Panel defaults inherited by the rendered elements. */
+export declare const PANEL_TEXT_DEFAULTS_SELECTOR = "UXML";
 /**
- * **Unmeasured, and reachable: nested disabled elements.**
- *
- * `enabled="false"` puts a whole subtree into `:disabled` — measured, by
- * `disabled-inherits`. The rule above therefore hands every level its own
- * `opacity: 0.5`, and CSS multiplies them, so a disabled button inside a
- * disabled panel comes out at a quarter. Unity almost certainly dims once.
- *
- * Not guessed at, because the fix has a choice inside it — dim only where
- * `enabled="false"` was written, or suppress the inherited one — and picking
- * without evidence is how the `.unity-button` selector became a hypothesis
- * nobody noticed for a day. Opacity leaves no trace in a coordinate dump, so
- * settling it needs a screenshot of a nested case. Recorded in
- * `docs/backlog.md` and visible in `visual-nested-disabled`.
+ * Editor theme stylesheet; kept as the legacy editor-sheet export.
+ * Parsed once and spliced in ahead of author sheets, so equal specificity lets
+ * author rules win on order, as in Unity. Class selectors also preserve Unity's
+ * specificity: `.unity-button` (0,1,0) beats an author `Button {}` (0,0,1).
  */
+export declare const THEME_USS: string;
+export declare const THEME_SHEETS: Readonly<Record<Theme, string>>;
 /**
  * Purpose:      how much width a vertical scrollbar claims, given whether it shows.
  * Ensures:      0 when the content fits — Unity hides the scroller rather than
  *               shrinking the viewport for a bar nobody can see.
  */
-export declare function verticalScrollbarWidth(overflows: boolean): number;
+export declare function verticalScrollbarWidth(overflows: boolean, theme?: Theme): number;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Theme } from './controls/theme';
 import { NodeId, UxmlDocument, Warning } from './model/types';
 import { ComputedStyle, ResolveResult } from './style/resolve';
 import { LayoutBox, MeasureText } from './layout/yoga';
@@ -10,6 +11,7 @@ import { ResolveFont } from './render/fonts';
  * See docs/ROADMAP.md.
  */
 export type { Span, SourceRef, NodeId, ElementName, Attribute, ElementSpans, ElementNode, Combinator, SimpleSelector, SelectorPart, Selector, Declaration, Rule, SheetItem, StyleSheet, WarningKind, WarningKindMap, WarningReason, WarningSubject, Warning, UxmlDocument, StyleOrigin, } from './model/types';
+export type { Theme } from './controls/theme';
 export { collectDependencies, expandTemplates, TEMPLATE_DEPTH_LIMIT } from './template/expand';
 export type { TemplateExpansion, TemplateResolver } from './template/expand';
 export { loadLayoutEngine, isLayoutEngineReady, liveNodeCount } from './layout/yoga';
@@ -76,6 +78,14 @@ export declare function serialize(doc: UxmlDocument): {
     uss: string;
 };
 export interface RenderOptions {
+    /**
+     * Defaults to 'runtime' since 0.7.0 (Unity's PanelSettings runtime theme).
+     * 'editor' is Unity's dark editor theme, used for the published 662/676 figure.
+     * The core draws no panel background (transparent, as Unity does). Runtime
+     * text is dark (#1b1b1b), so hosts drawing on a dark backdrop must provide
+     * a panel background.
+     */
+    theme?: Theme;
     /** Resolves font assets once per distinct path and form in each render. */
     resolveFont?: ResolveFont;
     /**
@@ -127,6 +137,8 @@ export interface RenderOptions {
 export { classifyVisibility } from './render/visibility';
 export type { Visibility } from './render/visibility';
 export interface RenderResult {
+    /** The theme actually drawn, after option validation. */
+    theme: Theme;
     /** Expanded document used for rendering, separate from the source AST. */
     document?: UxmlDocument;
     /** Computed styles keyed by rendered element id. */