@react-x11/components 0.3.0 → 0.4.0

package/src/qml/containers.tsx

@@ -0,0 +1,380 @@
+// Containers: the positioners (bindings the Row installs on its children),
+// Repeater, Loader, and the scroll pair — Flickable over core's
+// `overflow: 'scroll'` box, ListView over Flickable with windowed
+// delegates: only the visible range (plus a buffer) is instantiated, and
+// scrolling moves the window.
+
+import { useEffect } from 'react';
+import type { ReactElement } from 'react';
+import type { ScrollableNode } from 'react-x11';
+
+import {
+  QmlInstance,
+  instantiateComponentDoc,
+  instantiateTemplate,
+  resolveComponentByPath,
+  type QmlTypeDef,
+} from './objects.js';
+import { renderQmlChildren, geometryStyle } from './react.js';
+import {
+  applyMotion,
+  captureNode,
+  hostNode,
+  initItem,
+  num,
+} from './view-utils.js';
+import { delegateExtras, resolveModel } from './models.js';
+import { warn } from './globals.js';
+
+// --- positioners -----------------------------------------------------------
+
+function positionerLayout(inst: QmlInstance): void {
+  const horizontal = inst.typeInfo.name === 'Row';
+  const main = horizontal ? 'x' : 'y';
+  const mainSize = horizontal ? 'width' : 'height';
+  const crossSize = horizontal ? 'height' : 'width';
+  for (const kid of inst.visualChildren()) {
+    kid.slot(main).setBinding(() => {
+      let pos = 0;
+      const spacing = num(inst.slot('spacing').get());
+      for (const prev of inst.visualChildren()) {
+        if (prev === kid) break;
+        if (prev.slot('visible').get() === false) continue;
+        pos += num(prev.slot(mainSize).get()) + spacing;
+      }
+      return pos;
+    });
+  }
+  const extent = (): number => {
+    let sum = 0;
+    let count = 0;
+    const spacing = num(inst.slot('spacing').get());
+    for (const kid of inst.visualChildren()) {
+      if (kid.slot('visible').get() === false) continue;
+      sum += num(kid.slot(mainSize).get());
+      count++;
+    }
+    return sum + spacing * Math.max(0, count - 1);
+  };
+  const crossExtent = (): number => {
+    let max = 0;
+    for (const kid of inst.visualChildren()) {
+      if (kid.slot('visible').get() === false) continue;
+      max = Math.max(max, num(kid.slot(crossSize).get()));
+    }
+    return max;
+  };
+  inst.slot(horizontal ? 'implicitWidth' : 'implicitHeight').setBinding(extent);
+  inst
+    .slot(horizontal ? 'implicitHeight' : 'implicitWidth')
+    .setBinding(crossExtent);
+}
+
+function positionerInit(inst: QmlInstance): void {
+  initItem(inst);
+  positionerLayout(inst);
+}
+
+// --- Repeater --------------------------------------------------------------
+
+interface RepeaterState {
+  items?: QmlInstance[];
+  revOff?: (() => void) | null;
+}
+
+function repeaterRebuild(inst: QmlInstance): void {
+  const parent = inst.parentInst;
+  const tpl = inst.templates.get('delegate');
+  if (!parent || !tpl) return;
+  const state = inst.state as RepeaterState;
+  for (const item of state.items ?? []) {
+    const at = parent.children.indexOf(item);
+    if (at >= 0) parent.children.splice(at, 1);
+    item.destroy();
+  }
+  const { rows } = resolveModel(inst.slot('model').peek());
+  const items = rows.map(
+    (_, index) =>
+      instantiateTemplate(tpl, parent, delegateExtras(rows, index)).inst,
+  );
+  const at = parent.children.indexOf(inst);
+  parent.children.splice(at + 1, 0, ...items);
+  state.items = items;
+  inst.slot('count').assign(items.length);
+  parent._structChanged();
+}
+
+function repeaterModelChanged(inst: QmlInstance): void {
+  const state = inst.state as RepeaterState;
+  state.revOff?.();
+  state.revOff = null;
+  const { revSlot } = resolveModel(inst.slot('model').peek());
+  if (revSlot) state.revOff = revSlot.watch(() => repeaterRebuild(inst));
+  repeaterRebuild(inst);
+}
+
+// --- Flickable -------------------------------------------------------------
+
+function FlickableView({ inst }: { inst: QmlInstance }): ReactElement {
+  const style = geometryStyle(inst);
+  style.overflow = 'scroll';
+  applyMotion(inst, style);
+  const cw = num(inst.slot('contentWidth').peek());
+  const ch = num(inst.slot('contentHeight').peek());
+  const cx = num(inst.slot('contentX').peek());
+  const cy = num(inst.slot('contentY').peek());
+  useEffect(() => {
+    const node = hostNode(inst) as ScrollableNode | null;
+    if (!node || typeof node.scrollTo !== 'function') return;
+    if (node.scrollX !== cx || node.scrollY !== cy)
+      node.scrollTo({ x: cx, y: cy });
+  }, [inst, cx, cy]);
+  return (
+    <box
+      ref={captureNode(inst)}
+      style={style}
+      onScroll={(ev: { scrollX: number; scrollY: number }) => {
+        inst.slot('contentX').assign(ev.scrollX);
+        inst.slot('contentY').assign(ev.scrollY);
+      }}
+    >
+      <box
+        style={{
+          position: 'relative',
+          width: cw || undefined,
+          height: ch || undefined,
+        }}
+      >
+        {renderQmlChildren(inst)}
+      </box>
+    </box>
+  );
+}
+
+// --- ListView --------------------------------------------------------------
+
+interface ListState {
+  items?: Map<number, QmlInstance>;
+  revOff?: (() => void) | null;
+  measuredWatch?: boolean;
+}
+
+function listViewInit(lv: QmlInstance): void {
+  initItem(lv);
+  const state = lv.state as ListState;
+  const items = new Map<number, QmlInstance>();
+  state.items = items;
+
+  const destroyItem = (i: number): void => {
+    const it = items.get(i);
+    if (!it) return;
+    const at = lv.children.indexOf(it);
+    if (at >= 0) lv.children.splice(at, 1);
+    it.destroy();
+    items.delete(i);
+  };
+
+  const update = (): void => {
+    if (lv.destroyed) return;
+    const tpl = lv.templates.get('delegate');
+    if (!tpl) return;
+    const { rows } = resolveModel(lv.slot('model').peek());
+    const spacing = num(lv.slot('spacing').peek());
+    const count = rows.length;
+    for (const i of [...items.keys()]) if (i >= count) destroyItem(i);
+    if (count === 0) {
+      lv.slot('contentHeight').assign(0);
+      lv._structChanged();
+      return;
+    }
+    const ensure = (i: number): QmlInstance => {
+      let it = items.get(i);
+      if (!it) {
+        it = instantiateTemplate(tpl, lv, delegateExtras(rows, i)).inst;
+        items.set(i, it);
+        lv.children.push(it);
+      }
+      return it;
+    };
+    const first = ensure(0);
+    if (!state.measuredWatch) {
+      state.measuredWatch = true;
+      first.slot('height').watch(update); // implicit sizes settle late
+    }
+    const h = num(first.slot('height').peek());
+    if (!h) {
+      // Nothing measurable yet: stack whatever heights the delegates say.
+      let y = 0;
+      for (let i = 0; i < count; i++) {
+        const it = ensure(i);
+        it.slot('y').assign(y);
+        y += num(it.slot('height').peek()) + spacing;
+      }
+      lv.slot('contentHeight').assign(Math.max(0, y - spacing));
+    } else {
+      // Uniform rows (the first row's height): window the range.
+      const stride = h + spacing;
+      const viewH = num(lv.slot('height').peek());
+      const cy = num(lv.slot('contentY').peek());
+      const buffer = Math.max(2, Math.ceil((viewH || stride) / stride));
+      const start = Math.max(0, Math.floor(cy / stride) - buffer);
+      const end = Math.min(
+        count - 1,
+        Math.ceil((cy + (viewH || stride)) / stride) + buffer,
+      );
+      for (const i of [...items.keys()]) {
+        if (i !== 0 && (i < start || i > end)) destroyItem(i);
+      }
+      for (let i = start; i <= end; i++)
+        ensure(i)
+          .slot('y')
+          .assign(i * stride);
+      first.slot('y').assign(0);
+      lv.slot('contentHeight').assign(count * stride - spacing);
+    }
+    lv._structChanged();
+  };
+
+  const fullRebuild = (): void => {
+    for (const i of [...items.keys()]) destroyItem(i);
+    state.measuredWatch = false;
+    update();
+  };
+  const modelChanged = (): void => {
+    state.revOff?.();
+    state.revOff = null;
+    const { revSlot } = resolveModel(lv.slot('model').peek());
+    if (revSlot) state.revOff = revSlot.watch(fullRebuild);
+    fullRebuild();
+  };
+
+  lv.slot('model').watch(modelChanged);
+  lv.slot('contentY').watch(update);
+  lv.slot('height').watch(update);
+  lv.slot('spacing').watch(fullRebuild);
+  modelChanged();
+}
+
+// --- Loader ----------------------------------------------------------------
+
+function loaderInit(ld: QmlInstance): void {
+  initItem(ld);
+  let child: QmlInstance | null = null;
+  const sync = (): void => {
+    if (child) {
+      const at = ld.children.indexOf(child);
+      if (at >= 0) ld.children.splice(at, 1);
+      child.destroy();
+      child = null;
+      ld.slot('item').assign(null);
+      ld.slot('implicitWidth').assign(0);
+      ld.slot('implicitHeight').assign(0);
+    }
+    const tpl = ld.templates.get('sourceComponent');
+    const sourcePath = String(ld.slot('source').peek() ?? '');
+    const active = ld.slot('active').peek() !== false;
+    let loaded: QmlInstance | null = null;
+    if (!ld.destroyed && active && tpl) {
+      loaded = instantiateTemplate(tpl, ld).inst;
+    } else if (!ld.destroyed && active && sourcePath) {
+      // `source: "widgets/Meter.qml"` — a component document through the
+      // resolver seam, relative to the document that names it.
+      const compDoc = resolveComponentByPath(ld.doc, sourcePath);
+      if (compDoc) {
+        loaded = instantiateComponentDoc(compDoc, ld.context, ld).inst;
+      } else {
+        warn(
+          `QML: Loader.source '${sourcePath}' did not resolve — ` +
+            (ld.doc.load
+              ? 'no such .qml file relative to this document.'
+              : 'pass a resolver (createFileResolver) to QmlView.'),
+        );
+      }
+    }
+    if (loaded) {
+      child = loaded;
+      const item = loaded;
+      ld.children.push(item);
+      ld.slot('item').assign(item.facade);
+      ld.slot('implicitWidth').setBinding(() => num(item.slot('width').get()));
+      ld.slot('implicitHeight').setBinding(() =>
+        num(item.slot('height').get()),
+      );
+      ld.emit('loaded');
+    }
+    ld._structChanged();
+  };
+  ld.slot('active').watch(sync);
+  ld.slot('source').watch(sync);
+  sync();
+}
+
+// --- the type definitions --------------------------------------------------
+
+export const containerTypes: Record<string, QmlTypeDef> = {
+  Row: {
+    extends: 'Item',
+    properties: { spacing: { default: 0 } },
+    init: positionerInit,
+    onStructure: positionerLayout,
+  },
+  Column: {
+    extends: 'Item',
+    properties: { spacing: { default: 0 } },
+    init: positionerInit,
+    onStructure: positionerLayout,
+  },
+
+  Repeater: {
+    nonVisual: true,
+    capture: 'delegate',
+    properties: { model: { default: 0 }, count: { default: 0 } },
+    init(inst) {
+      inst.slot('model').watch(() => repeaterModelChanged(inst));
+      repeaterModelChanged(inst);
+    },
+    dispose(inst) {
+      const state = inst.state as RepeaterState;
+      state.revOff?.();
+      for (const item of state.items ?? []) item.destroy();
+    },
+  },
+
+  Flickable: {
+    extends: 'Item',
+    view: FlickableView,
+    properties: {
+      contentWidth: { default: 0 },
+      contentHeight: { default: 0 },
+      contentX: { default: 0 },
+      contentY: { default: 0 },
+    },
+    init: initItem,
+  },
+
+  ListView: {
+    extends: 'Flickable',
+    capture: 'delegate',
+    properties: {
+      model: { default: 0 },
+      spacing: { default: 0 },
+    },
+    init: listViewInit,
+    dispose(lv) {
+      const state = lv.state as ListState;
+      state.revOff?.();
+    },
+  },
+
+  Loader: {
+    extends: 'Item',
+    capture: 'sourceComponent',
+    properties: {
+      active: { default: true },
+      item: { default: null },
+      source: { default: '' },
+    },
+    signals: { loaded: [] },
+    init: loaderInit,
+  },
+};

package/src/qml/controls.tsx

@@ -0,0 +1,47 @@
+// `import QtQuick.Controls` — the beginnings of the Controls story:
+// widgets react-x11 already ships, registered as QML types. The widgets
+// are passed in rather than imported here, so the family costs nothing
+// when Controls are unused and the app decides which widget set answers
+// (core's `Button`, or its own).
+
+import type { ComponentType } from 'react';
+import { registerQmlModule } from './objects.js';
+import { geometryStyle } from './react.js';
+import { str } from './view-utils.js';
+
+export interface ControlsWidgets {
+  /** A pressable taking `primary`, `disabled`, `onPress` and children —
+   * core's `Button` as it stands. Deliberately `ComponentType<any>`:
+   * React's `propTypes`/`defaultProps` members make component types
+   * near-invariant in their props, so a props-typed seam rejects any
+   * richer button; `any` is the honest edge (eslint does not see
+   * TypeScript here — AGENTS.md, "Linting").  */
+  Button: ComponentType<any>;
+}
+
+export function registerControls({ Button }: ControlsWidgets): void {
+  registerQmlModule('QtQuick.Controls', {
+    version: '2.0',
+    types: {
+      Button: {
+        extends: 'Item',
+        properties: {
+          text: { default: '' },
+          primary: { default: false },
+        },
+        signals: { clicked: [] },
+        view: ({ inst }) => (
+          <box style={geometryStyle(inst)}>
+            <Button
+              primary={inst.slot('primary').peek() === true}
+              disabled={inst.slot('enabled').peek() === false}
+              onPress={() => inst.emit('clicked')}
+            >
+              {str(inst.slot('text').peek())}
+            </Button>
+          </box>
+        ),
+      },
+    },
+  });
+}

package/src/qml/globals.ts

@@ -0,0 +1,33 @@
+// Host globals, reached structurally through `globalThis`. The build
+// compiles `src/` with `types: []` on purpose — a Node global that wanders
+// in must fail the build rather than become an implicit `@types/node`
+// dependency (AGENTS.md) — so the few platform facilities the QML runtime
+// needs are typed here, the way `charts/timers.ts` and `three/globals.ts`
+// do it.
+
+interface HostGlobals {
+  queueMicrotask?(fn: () => void): void;
+  setTimeout?(fn: () => void, ms: number): unknown;
+  clearTimeout?(id: unknown): void;
+  console?: { warn(...args: unknown[]): void };
+}
+
+const g = globalThis as HostGlobals;
+
+export function microtask(fn: () => void): void {
+  if (g.queueMicrotask) g.queueMicrotask(fn);
+  else void Promise.resolve().then(fn);
+}
+
+/** `Timer { interval: … }` — null when the host has no timer at all. */
+export function schedule(fn: () => void, ms: number): unknown {
+  return g.setTimeout ? g.setTimeout(fn, ms) : null;
+}
+
+export function cancel(id: unknown): void {
+  if (id != null) g.clearTimeout?.(id);
+}
+
+export function warn(...args: unknown[]): void {
+  g.console?.warn(...args);
+}

package/src/qml/index.ts

@@ -0,0 +1,67 @@
+// `@react-x11/components/qml` — QML as an authoring layer over react-x11.
+//
+// A zero-dependency QML engine: the parser, the reactive slot graph with
+// QML's binding-breaking assignment, the object model with Qt's scoping
+// rules, and a QtQuick subset whose every pixel is an ordinary
+// `<box>`/`<text>`/`<image>` committed through the renderer. The docs page
+// is docs/components/qml.md; the design record is react-x11's QML RFC.
+//
+// Importing this module populates the QtQuick registry — the family's own
+// module-level registry, no core state touched. That is this family's one
+// import-time side effect, the same shape as a component registering its
+// element (AGENTS.md, "Tree-shaking"): it lives here so a bundler that
+// keeps the family runs it, and one that shakes the family drops it.
+
+import { registerQtQuick } from './qtquick.js';
+
+registerQtQuick();
+
+export { parseQml, ParseError } from './parse.js';
+export type {
+  QmlDocument,
+  QmlImport,
+  ObjectIR,
+  MemberIR,
+  ValueIR,
+} from './ir.js';
+export {
+  Qt,
+  QmlInstance,
+  Context,
+  instantiateDocument,
+  instantiateTemplate,
+  migrateUserState,
+  registerQmlModule,
+  instanceOf,
+  lookupType,
+} from './objects.js';
+export type {
+  QmlFacade,
+  QmlTypeDef,
+  QmlTypeInfo,
+  QmlPropertyDef,
+  ValueSourceHookup,
+  InstantiateResult,
+  QtNamespace,
+  TemplateRef,
+} from './objects.js';
+export { Slot, flushBindings } from './slots.js';
+export {
+  QmlView,
+  QmlNode,
+  registerReactComponent,
+  renderQmlChildren,
+  useQmlVersion,
+} from './react.js';
+export type {
+  QmlViewProps,
+  QmlViewHandle,
+  RegisterReactComponentOptions,
+} from './react.js';
+export { qmlColor, registerQtQuick } from './qtquick.js';
+export { createFileResolver } from './resolver.js';
+export type { QmlResolver, DocLoad } from './resolver.js';
+export { geometryStyle, preferredSpan } from './react.js';
+export { captureNode, hostNode } from './view-utils.js';
+export { registerControls } from './controls.js';
+export type { ControlsWidgets } from './controls.js';