@aethervtt/shard-ui 0.0.1

package/dist/length.js

@@ -0,0 +1,92 @@
+import {
+  ShardError
+} from "@aethervtt/shard-core";
+const LengthUnit = { Px: 0, Percent: 1, Auto: 2 };
+const PATTERN = /^\s*(-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)\s*(px|%)?\s*$/i;
+function parseLength(json, out = [0, 0]) {
+  if (typeof json === "number") {
+    if (!Number.isFinite(json)) return void 0;
+    out[0] = json;
+    out[1] = LengthUnit.Px;
+    return out;
+  }
+  if (typeof json !== "string") return void 0;
+  if (json.trim() === "auto") {
+    out[0] = 0;
+    out[1] = LengthUnit.Auto;
+    return out;
+  }
+  const m = PATTERN.exec(json);
+  if (!m) return void 0;
+  out[0] = Number(m[1]);
+  out[1] = m[2] === "%" ? LengthUnit.Percent : LengthUnit.Px;
+  return out;
+}
+function invalid(path, got) {
+  return new ShardError(
+    "ui/invalid-length",
+    `${JSON.stringify(got)} at ${path || "/"} isn't a length`,
+    {
+      path,
+      hint: 'Use pixels (120 or "120"), a percent of the parent ("50%"), or "auto".'
+    }
+  );
+}
+function toValue(value, unit) {
+  if (unit === LengthUnit.Auto) return "auto";
+  const v = Number.isInteger(value) ? value : Number(value.toPrecision(7));
+  return unit === LengthUnit.Percent ? `${v}%` : v;
+}
+const scratch = [0, 0];
+function uiLength(options = {}) {
+  const fallback = options.default ?? "auto";
+  const field = {
+    kind: "length",
+    storage: "f32",
+    stride: 2,
+    options,
+    defaultValue: () => fallback,
+    read: (c, r) => {
+      const col = c;
+      return toValue(col[r * 2], col[r * 2 + 1]);
+    },
+    write: (c, r, v) => {
+      const parsed = parseLength(v, scratch);
+      if (!parsed) throw invalid("", v);
+      const col = c;
+      col[r * 2] = parsed[0];
+      col[r * 2 + 1] = parsed[1];
+    },
+    validate(json, path, errors) {
+      if (!parseLength(json, scratch)) errors.push(invalid(path, json));
+    },
+    toJson: (v) => {
+      const parsed = parseLength(v, scratch);
+      return parsed ? toValue(parsed[0], parsed[1]) : "auto";
+    },
+    fromJson: (json) => {
+      const parsed = parseLength(json, scratch);
+      return parsed ? toValue(parsed[0], parsed[1]) : "auto";
+    },
+    jsonSchema: () => {
+      const schema = {
+        anyOf: [
+          { type: "number" },
+          { type: "string", pattern: "^\\s*-?(\\d+\\.?\\d*|\\.\\d+)\\s*(px|%)?\\s*$" },
+          { const: "auto" }
+        ],
+        default: fallback
+      };
+      if (options.description) schema.description = options.description;
+      if (options.readonly) schema.readOnly = true;
+      schema["x-unit"] = "px or %";
+      return schema;
+    }
+  };
+  return field;
+}
+export {
+  LengthUnit,
+  parseLength,
+  uiLength
+};

package/dist/methods.d.ts

@@ -0,0 +1,52 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { AppMethod } from '@aethervtt/shard-runtime';
+/** An entity's scene path, if it came from a scene. */
+export declare function uiPath(world: World, entity: Entity): string | null;
+/**
+ * A UI node by id or scene path. A path may also be a suffix after "/" ("play" finds
+ * "hud/menu/play") when only one node matches.
+ */
+export declare function resolveUiEntity(world: World, ref: unknown): Entity;
+interface DescribedNode {
+    entity: Entity;
+    path: string | null;
+    rect: [number, number, number, number];
+    visible: boolean;
+    [key: string]: unknown;
+}
+/** Hooks other parts of the plugin add to describe (the renderer's upload counts). */
+export declare const describeExtras: Map<string, (world: World) => unknown>;
+/** Every UI tree as data: rects, text, widget state, focus, anchors, and this frame's work. */
+export declare function describeUi(world: World, root?: Entity): {
+    roots: {
+        entity: number;
+        path: string | null;
+        size: number[];
+        scale: number;
+        viewport: number[];
+        camera: number | null;
+        nodes: number;
+        laidOutAt: number;
+        tree: DescribedNode;
+    }[];
+    focus: string | number | null;
+    hovered: string | number | null;
+    pointer: {
+        x: number;
+        y: number;
+        overUi: boolean;
+    };
+    frame: {
+        layouts: number;
+        nodesLaidOut: number;
+        repositions: number;
+        flexCalls: number;
+    } & Record<string, unknown>;
+    problems: {
+        code: string;
+        entity: number;
+        path: string | null;
+    }[];
+};
+export declare const uiMethods: AppMethod[];
+export {};

package/dist/methods.js

@@ -0,0 +1,187 @@
+import {
+  defineSchema,
+  findComponent,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { Localized } from "@aethervtt/shard-text";
+import {
+  UI_ANCHOR_STATES,
+  UI_STATES,
+  UiInteraction,
+  UiNode,
+  UiSlider,
+  UiText,
+  UiTextInput,
+  UiToggle
+} from "./components.js";
+import { clickUi, focusUi, UiPointer } from "./interaction.js";
+import { ResolvedStyle, resolveStyle } from "./style.js";
+import { Kind, textColumns, UiState } from "./tree.js";
+const round = (x) => Math.round(x * 100) / 100;
+const KINDS = ["", "button", "toggle", "slider", "text-input"];
+function uiPath(world, entity) {
+  const member = findComponent("scene/SceneMember");
+  if (!member || !world.isAlive(entity)) return null;
+  return world.tryGet(entity, member)?.path || null;
+}
+function resolveUiEntity(world, ref) {
+  const store = world.resource(UiState);
+  if (typeof ref === "number" && world.isAlive(ref) && store.rootOf.has(ref)) return ref;
+  if (typeof ref === "string" && ref !== "") {
+    let exact;
+    const suffix = [];
+    for (const e of store.rootOf.keys()) {
+      const path = uiPath(world, e);
+      if (!path) continue;
+      if (path === ref || path.endsWith(`:${ref}`)) exact = e;
+      else if (path.endsWith(`/${ref}`)) suffix.push(e);
+    }
+    if (exact !== void 0) return exact;
+    if (suffix.length === 1) return suffix[0];
+    if (suffix.length > 1) {
+      throw new ShardError("ui/ambiguous-path", `"${ref}" matches ${suffix.length} UI nodes`, {
+        hint: `Use the full path: ${suffix.map((e) => uiPath(world, e)).join(", ")}.`
+      });
+    }
+  }
+  throw new ShardError("ui/unknown-node", `No UI node ${JSON.stringify(ref)}`, {
+    hint: "Pass an entity id or a scene path of a node under a UiRoot (ui.describe lists them)."
+  });
+}
+const describeStyle = new ResolvedStyle();
+function describeNode(world, r, i, focused) {
+  const e = r.entities[i];
+  const table = world.entityTable(e);
+  const row = world.entityRow(e);
+  const out = {
+    entity: e,
+    path: uiPath(world, e),
+    rect: [round(r.x[i]), round(r.y[i]), round(r.w[i]), round(r.h[i])],
+    visible: r.visible[i] !== 0
+  };
+  const style = table.column(UiNode, "style")[row] ?? "";
+  if (style) {
+    out.style = style;
+    if (r.theme && !r.theme.styles.has(style))
+      out.problem = `ui/unknown-style: "${style}" isn't in the theme`;
+  }
+  const text = r.texts[i];
+  if (text) {
+    out.text = table.has(UiTextInput) ? table.column(UiTextInput, "value")[row] : table.has(Localized) ? table.column(Localized, "value")[row] : table.column(UiText, "text")[row];
+    const key = table.column(UiText, "key")[row];
+    if (key) {
+      out.key = key;
+      if (!table.has(Localized)) out.problem = `locale/missing-key: no string for "${key}"`;
+    }
+    resolveStyle(describeStyle, textColumns(table), row, r.theme, style, 0);
+    out.textSize = round(describeStyle.size);
+    if (!text.font) out.problem = "no font: set UiText.font, a theme font, or UiDefaults.font";
+    else if (text.layout.missing > 0) out.missingGlyphs = text.layout.missing;
+  }
+  const kind = r.kind[i];
+  if (kind !== Kind.None) {
+    out.widget = KINDS[kind];
+    const s = table.has(UiInteraction) ? table.column(UiInteraction, "state")[row] : 0;
+    out.state = UI_STATES[s];
+    if (focused === e) out.focused = true;
+    if (r.disabled[i]) out.disabled = true;
+    if (kind === Kind.Toggle) out.on = table.column(UiToggle, "on")[row] !== 0;
+    if (kind === Kind.Slider) out.value = round(table.column(UiSlider, "value")[row]);
+  }
+  if (r.anchorKind[i] === 1) {
+    out.anchor = UI_ANCHOR_STATES[r.anchorState[i]];
+    out.distance = round(r.distance[i]);
+    if (r.anchorScale[i] !== 1) out.scale = round(r.anchorScale[i]);
+  }
+  if (r.anchorKind[i] === 2) out.arrowAngle = round(r.angle[i]);
+  if (r.overflow[i] === 2) {
+    out.scroll = [round(r.scrollX[i]), round(r.scrollY[i])];
+    out.content = [round(r.contentW[i]), round(r.contentH[i])];
+  }
+  const children = [];
+  for (let c = i + 1; c < r.end[i]; c = r.end[c])
+    children.push(describeNode(world, r, c, focused));
+  if (children.length > 0) out.children = children;
+  return out;
+}
+const describeExtras = /* @__PURE__ */ new Map();
+function describeUi(world, root) {
+  const store = world.resource(UiState);
+  const pointer = world.resource(UiPointer);
+  const roots = store.roots.filter((r) => root === void 0 || r.entity === root).map((r) => ({
+    entity: r.entity,
+    path: uiPath(world, r.entity),
+    size: [round(r.width), round(r.height)],
+    scale: round(r.factor),
+    viewport: [r.viewportW, r.viewportH],
+    camera: r.camera,
+    nodes: r.count,
+    laidOutAt: r.laidOutAt,
+    tree: describeNode(world, r, 0, pointer.focused)
+  }));
+  const extras = {};
+  for (const [name, fn] of describeExtras) extras[name] = fn(world);
+  return {
+    roots,
+    focus: pointer.focused === null ? null : uiPath(world, pointer.focused) ?? pointer.focused,
+    hovered: pointer.hovered === null ? null : uiPath(world, pointer.hovered) ?? pointer.hovered,
+    pointer: { x: round(pointer.x), y: round(pointer.y), overUi: pointer.overUi },
+    frame: {
+      layouts: store.layouts,
+      nodesLaidOut: store.nodesLaidOut,
+      repositions: store.repositions,
+      flexCalls: store.flexCalls,
+      ...extras
+    },
+    problems: [...store.orphans].map((e) => ({
+      code: "ui/no-root",
+      entity: e,
+      path: uiPath(world, e)
+    }))
+  };
+}
+const uiMethods = [
+  {
+    name: "ui.describe",
+    description: "Every UI tree (or one root) as data: each node's path, rect [x, y, width, height] in the root's pixels, visibility, text and size, style, widget kind and state (hovered, pressed, disabled, focused, on, value), anchor state (on-screen, clamped, hidden) and distance, scroll; the focused and hovered nodes; and this frame's layout and upload counts (0 on a frame where nothing changed).",
+    params: defineSchema("ui/DescribeParams", {
+      root: t.json({ description: "A UiRoot entity id or path (default: all)." })
+    }),
+    handler: ({ world }, p) => describeUi(
+      world,
+      p.root === void 0 || p.root === null ? void 0 : resolveUiEntity(world, p.root)
+    )
+  },
+  {
+    name: "ui.click",
+    description: 'Clicks a UiButton or UiToggle by entity id or path (a unique suffix like "play" works): sends ui/UiClick and flips a toggle, as a real click does, with no pixel coordinates. Takes effect now; step a frame for systems to react.',
+    params: defineSchema("ui/ClickParams", {
+      entity: t.json({ description: "Entity id or scene path of the button." })
+    }),
+    handler: ({ world }, p) => {
+      const e = resolveUiEntity(world, p.entity);
+      clickUi(world, e);
+      return { clicked: e, path: uiPath(world, e) };
+    }
+  },
+  {
+    name: "ui.focus",
+    description: "Gives keyboard and gamepad focus to a widget by id or path (null clears it). While a node has focus, action maps in the game context are paused.",
+    params: defineSchema("ui/FocusParams", {
+      entity: t.json({ description: "Entity id or scene path, or null." })
+    }),
+    handler: ({ world }, p) => {
+      const e = p.entity === null || p.entity === void 0 ? null : resolveUiEntity(world, p.entity);
+      focusUi(world, e);
+      return { focused: e, path: e === null ? null : uiPath(world, e) };
+    }
+  }
+];
+export {
+  describeExtras,
+  describeUi,
+  resolveUiEntity,
+  uiMethods,
+  uiPath
+};

package/dist/plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Retained UI: UiNode trees under UiRoots laid out by flexbox after transforms, drawn over the
+ * finished image, and driven by the pointer, keyboard, and gamepad. Without a renderer (headless)
+ * everything but drawing runs, so layout and clicks are testable.
+ */
+export declare const uiPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,40 @@
+import { First, PostUpdate } from "@aethervtt/shard-core";
+import { updateActions, updateInput } from "@aethervtt/shard-input";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { Fonts, installLocalization, localizeComponent, localizeText } from "@aethervtt/shard-text";
+import { TransformSystems } from "@aethervtt/shard-transform";
+import * as componentsModule from "./components.js";
+import { UiDefaults, UiText } from "./components.js";
+import * as interactionModule from "./interaction.js";
+import { interactUi, UiPointer } from "./interaction.js";
+import { uiMethods } from "./methods.js";
+import * as renderModule from "./render.js";
+import { installUiRenderer } from "./render.js";
+import * as themeModule from "./theme.js";
+import { UiThemes } from "./theme.js";
+import * as treeModule from "./tree.js";
+import { layoutUi, observeUiStructure, UiState } from "./tree.js";
+const uiPlugin = definePlugin({
+  name: "ui",
+  provides: [componentsModule, interactionModule, renderModule, themeModule, treeModule],
+  dependencies: ["core/transform"],
+  build(app) {
+    const w = app.world;
+    w.initResource(UiState);
+    w.initResource(UiPointer);
+    w.initResource(UiThemes);
+    w.initResource(UiDefaults);
+    w.initResource(Fonts);
+    observeUiStructure(w);
+    installLocalization(app);
+    localizeComponent(w, UiText);
+    app.addSystems(First, interactUi.after(updateInput).before(updateActions)).addSystems(PostUpdate, layoutUi.after(TransformSystems, localizeText));
+    app.addMethod(...uiMethods);
+  },
+  ready(app) {
+    installUiRenderer(app);
+  }
+});
+export {
+  uiPlugin
+};

package/dist/render.d.ts

@@ -0,0 +1,76 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type NodeDescriptor } from '@aethervtt/shard-render';
+import type { App } from '@aethervtt/shard-runtime';
+import type { FontPage } from '@aethervtt/shard-text';
+import { type Texture } from '@aethervtt/shard-texture';
+import { type UiRootState } from './tree.js';
+/** Floats per quad record: rect, uv, color, border color, radius, clip, border, kind, range, angle. */
+export declare const QUAD_FLOATS = 28;
+/** Consecutive quads drawn with one texture (boxes join any run). */
+interface UiDraw {
+    camera: Entity | null;
+    first: number;
+    count: number;
+    /** A texture or a font page; null while only boxes are in the run. */
+    source: Texture | FontPage | null;
+    page: boolean;
+    /** Sample the sRGB view (color images) or the linear one (glyphs, data). */
+    srgb: boolean;
+}
+/**
+ * Every UI root's quads in one storage buffer, in draw order (roots by order, nodes in paint
+ * order). Rebuilt only on frames where a root's layout or look changed; otherwise nothing uploads.
+ */
+export declare class UiRenderStore {
+    records: Float32Array<ArrayBuffer>;
+    recordU32: Uint32Array<ArrayBuffer>;
+    count: number;
+    draws: UiDraw[];
+    drawCount: number;
+    readonly buffer: GpuBuffer;
+    /** Root visual versions the records were built from. */
+    private built;
+    overlay: boolean;
+    /** This frame's rebuilds and bytes uploaded, and the frame total. */
+    rebuilds: number;
+    uploadedBytes: number;
+    totalUploads: number;
+    constructor(gpu: GpuContext);
+    /** Whether any root changed since the records were built. */
+    stale(roots: readonly UiRootState[], overlay: boolean): boolean;
+    markBuilt(roots: readonly UiRootState[], overlay: boolean): void;
+    push(): number;
+}
+export declare const UiRenderer: import("@aethervtt/shard-core").ResourceDef<UiRenderStore>;
+export declare const uiLayoutOverlay: import("@aethervtt/shard-render").OverlayDef;
+/** Rebuilds the quad records when any root changed, and uploads them. */
+export declare const prepareUi: import("@aethervtt/shard-core").SystemDef<undefined>;
+interface UiCaches {
+    generation: number;
+    layouts?: {
+        view: GPUBindGroupLayout;
+        texture: GPUBindGroupLayout;
+    };
+    pipelines: Map<string, GPURenderPipeline>;
+    groups: Map<string, {
+        key: string;
+        group: GPUBindGroup;
+    }>;
+    views: Map<string, GpuBuffer>;
+    sampler?: GPUSampler;
+    white?: GPUTextureView;
+}
+export declare const UiCachesResource: import("@aethervtt/shard-core").ResourceDef<UiCaches>;
+/** UI: over the finished image, after screen sprites and screen text. */
+export declare function uiNode(world: World): NodeDescriptor;
+/** The ui section of `render.describe`, and the upload counts ui.describe reports. */
+export declare function describeUiRender(world: World): {
+    quads: number;
+    drawCalls: number;
+    rebuilds: number;
+    uploadedBytes: number;
+} | undefined;
+/** Adds drawing when a renderer is present: the pass, the prepare system, and the pick blocker. */
+export declare function installUiRenderer(app: App): void;
+export {};