@react-x11/components 0.3.0 → 0.5.0

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';

package/src/qml/interaction.tsx

@@ -0,0 +1,317 @@
+// Pointer and keyboard: MouseArea, the `Keys` attached handlers, `focus`/
+// `activeFocus`, and the two text editors over core's `<textinput>` /
+// `<textarea>`.
+
+import { useEffect } from 'react';
+import type { ReactElement } from 'react';
+import type { Style } from 'react-x11/style';
+import {
+  XK_BACKSPACE,
+  XK_DELETE,
+  XK_DOWN,
+  XK_ESCAPE,
+  XK_KP_ENTER,
+  XK_LEFT,
+  XK_RETURN,
+  XK_RIGHT,
+  XK_SPACE,
+  XK_TAB,
+  XK_UP,
+} from 'react-x11/keysyms';
+
+import { QmlInstance, type QmlTypeDef } from './objects.js';
+import { renderQmlChildren, geometryStyle } from './react.js';
+import {
+  applyMotion,
+  captureNode,
+  hostNode,
+  num,
+  qmlColor,
+  str,
+} from './view-utils.js';
+
+// --- Keys + focus ----------------------------------------------------------
+
+interface KeyEventLike {
+  keysym?: number;
+  key?: string;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  metaKey?: boolean;
+  stopPropagation?(): void;
+}
+
+interface PointerEventLike {
+  x: number;
+  y: number;
+  button?: number;
+  detail?: number;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  stopPropagation?(): void;
+}
+
+interface WheelEventLike extends PointerEventLike {
+  deltaX?: number;
+  deltaY?: number;
+}
+
+// Qt's modifier flags, so `mouse.modifiers & Qt.ShiftModifier` reads as
+// ported code expects.
+const SHIFT = 0x02000000;
+const CTRL = 0x04000000;
+const ALT = 0x08000000;
+const META = 0x10000000;
+
+const modifiersOf = (e: {
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  metaKey?: boolean;
+}): number =>
+  (e.shiftKey ? SHIFT : 0) |
+  (e.ctrlKey ? CTRL : 0) |
+  (e.altKey ? ALT : 0) |
+  (e.metaKey ? META : 0);
+
+const NAMED_KEYS: Record<number, string> = {
+  [XK_RETURN]: 'Return',
+  [XK_KP_ENTER]: 'Enter',
+  [XK_ESCAPE]: 'Escape',
+  [XK_UP]: 'Up',
+  [XK_DOWN]: 'Down',
+  [XK_LEFT]: 'Left',
+  [XK_RIGHT]: 'Right',
+  [XK_TAB]: 'Tab',
+  [XK_SPACE]: 'Space',
+  [XK_DELETE]: 'Delete',
+  [XK_BACKSPACE]: 'Back',
+};
+
+function dispatchKeys(inst: QmlInstance, e: KeyEventLike): void {
+  const ev = {
+    key: e.keysym ?? 0,
+    text: e.key ?? '',
+    modifiers: modifiersOf(e),
+    accepted: false,
+  };
+  const named = NAMED_KEYS[ev.key];
+  if (named) inst.attachedHandlers.get(`Keys.on${named}Pressed`)?.(ev);
+  if (!ev.accepted) inst.attachedHandlers.get('Keys.onPressed')?.(ev);
+  if (ev.accepted) e.stopPropagation?.();
+}
+
+/**
+ * The focus/keyboard props an Item earns from `focus: true`, `Keys.*`
+ * handlers, or being told to be focusable. `activeFocus` follows the real
+ * focus events.
+ */
+export function keyFocusProps(inst: QmlInstance): Record<string, unknown> {
+  const wantsFocus = inst.slots.get('focus')?.peek() === true;
+  let hasKeys = false;
+  for (const k of inst.attachedHandlers.keys()) {
+    if (k.startsWith('Keys.')) {
+      hasKeys = true;
+      break;
+    }
+  }
+  if (!wantsFocus && !hasKeys) return {};
+  const props: Record<string, unknown> = {
+    focusable: true,
+    onFocus: () => inst.slots.get('activeFocus')?.assign(true),
+    onBlur: () => inst.slots.get('activeFocus')?.assign(false),
+  };
+  if (wantsFocus) props.autoFocus = true;
+  if (hasKeys) props.onKeyDown = (e: KeyEventLike) => dispatchKeys(inst, e);
+  return props;
+}
+
+// --- MouseArea -------------------------------------------------------------
+
+function MouseAreaView({ inst }: { inst: QmlInstance }): ReactElement {
+  const enabled = inst.slot('enabled').peek() !== false;
+  const hoverEnabled = inst.slot('hoverEnabled').peek() === true;
+  const style = geometryStyle(inst);
+  applyMotion(inst, style);
+
+  const mouse = (e: PointerEventLike) => {
+    const abs = hostNode(inst)?.abs;
+    return {
+      x: e.x - (abs?.x ?? 0),
+      y: e.y - (abs?.y ?? 0),
+      button: e.button,
+      modifiers: modifiersOf(e),
+      accepted: true,
+    };
+  };
+
+  const handlers: Record<string, unknown> = {};
+  if (enabled) {
+    handlers.onClick = (e: PointerEventLike) => {
+      e.stopPropagation?.();
+      inst.emit('clicked', mouse(e));
+      if (e.detail === 2) inst.emit('doubleClicked', mouse(e));
+    };
+    handlers.onMouseDown = (e: PointerEventLike) => {
+      e.stopPropagation?.();
+      inst.slot('pressed').assign(true);
+      inst.emit('pressed', mouse(e));
+    };
+    handlers.onMouseUp = (e: PointerEventLike) => {
+      e.stopPropagation?.();
+      inst.slot('pressed').assign(false);
+      inst.emit('released', mouse(e));
+    };
+    handlers.onMouseMove = (e: PointerEventLike) => {
+      inst.emit('positionChanged', mouse(e));
+    };
+    handlers.onWheel = (e: WheelEventLike) => {
+      inst.emit('wheel', {
+        ...mouse(e),
+        angleDelta: { x: e.deltaX ?? 0, y: e.deltaY ?? 0 },
+      });
+    };
+    if (hoverEnabled) {
+      handlers.onMouseEnter = () => {
+        inst.slot('containsMouse').assign(true);
+        inst.emit('entered');
+      };
+      handlers.onMouseLeave = () => {
+        inst.slot('containsMouse').assign(false);
+        inst.emit('exited');
+      };
+    }
+  }
+
+  return (
+    <box
+      ref={captureNode(inst)}
+      style={style}
+      {...handlers}
+      {...keyFocusProps(inst)}
+    >
+      {renderQmlChildren(inst)}
+    </box>
+  );
+}
+
+// --- TextInput / TextEdit --------------------------------------------------
+
+/** The font/colour subset Text and the editors share. */
+export function applyFontStyle(inst: QmlInstance, style: Style): void {
+  const color = inst.slots.get('color')?.peek();
+  if (color !== undefined) style.color = qmlColor(color);
+  const px = num(inst.slots.get('font.pixelSize')?.peek());
+  const pt = num(inst.slots.get('font.pointSize')?.peek());
+  if (px) style.fontSize = px;
+  else if (pt) style.fontSize = Math.round((pt * 96) / 72); // CSS's 1pt
+  const family = inst.slots.get('font.family')?.peek();
+  if (family) style.fontFamily = String(family);
+  if (inst.slots.get('font.bold')?.peek()) style.fontWeight = 700;
+  else {
+    const weight = num(inst.slots.get('font.weight')?.peek());
+    if (weight) style.fontWeight = weight;
+  }
+  if (inst.slots.get('font.italic')?.peek()) style.fontStyle = 'italic';
+}
+
+function useImplicitLineHeight(inst: QmlInstance, text: string): void {
+  useEffect(() => {
+    const node = hostNode(inst) as {
+      app?: { fonts?: { layout(t: string, s: unknown): { height: number } } };
+      resolvedTextStyle?(): unknown;
+    } | null;
+    if (!node?.app?.fonts || !node.resolvedTextStyle) return;
+    try {
+      const probe = node.app.fonts.layout(
+        text || 'Mg',
+        node.resolvedTextStyle(),
+      );
+      inst.slots.get('implicitHeight')?.assign(Math.ceil(probe.height) + 8);
+    } catch {
+      // No fonts loaded (headless without the fonts option): leave 0.
+    }
+  });
+}
+
+function editorView(tag: 'textinput' | 'textarea') {
+  return function EditorView({ inst }: { inst: QmlInstance }): ReactElement {
+    const style = geometryStyle(inst);
+    applyFontStyle(inst, style);
+    applyMotion(inst, style);
+    const text = str(inst.slot('text').peek());
+    useImplicitLineHeight(inst, text);
+    const maxLen = num(inst.slots.get('maximumLength')?.peek());
+    const props: Record<string, unknown> = {
+      ref: captureNode(inst),
+      style,
+      value: text,
+      onChange: (ev: { value: string }) => inst.slot('text').set(ev.value),
+      ...keyFocusProps(inst),
+    };
+    if (tag === 'textinput') {
+      props.onSubmit = () => inst.emit('accepted');
+      if (maxLen > 0 && maxLen < 32767) props.maxLength = maxLen;
+      return <textinput {...props} />;
+    }
+    return <textarea {...props} />;
+  };
+}
+
+// --- the type definitions --------------------------------------------------
+
+export const interactionTypes: Record<string, QmlTypeDef> = {
+  MouseArea: {
+    extends: 'Item',
+    view: MouseAreaView,
+    properties: {
+      pressed: { default: false },
+      containsMouse: { default: false },
+      hoverEnabled: { default: false },
+    },
+    signals: {
+      clicked: ['mouse'],
+      doubleClicked: ['mouse'],
+      pressed: ['mouse'],
+      released: ['mouse'],
+      positionChanged: ['mouse'],
+      entered: [],
+      exited: [],
+      wheel: ['wheel'],
+    },
+  },
+
+  TextInput: {
+    extends: 'Item',
+    view: editorView('textinput'),
+    properties: {
+      text: { default: '' },
+      color: { default: undefined },
+      maximumLength: { default: 32767 },
+      'font.pixelSize': { default: 0 },
+      'font.pointSize': { default: 0 },
+      'font.family': { default: '' },
+      'font.bold': { default: false },
+      'font.italic': { default: false },
+      'font.weight': { default: 0 },
+    },
+    signals: { accepted: [], editingFinished: [] },
+  },
+
+  TextEdit: {
+    extends: 'Item',
+    view: editorView('textarea'),
+    properties: {
+      text: { default: '' },
+      color: { default: undefined },
+      'font.pixelSize': { default: 0 },
+      'font.pointSize': { default: 0 },
+      'font.family': { default: '' },
+      'font.bold': { default: false },
+      'font.italic': { default: false },
+      'font.weight': { default: 0 },
+    },
+  },
+};

package/src/qml/ir.ts

@@ -0,0 +1,80 @@
+// The intermediate representation both halves share: the parser produces it,
+// the runtime instantiates it, and the future compiler will serialize it.
+// Everything is plain data — no methods, no cycles — so a document parses
+// once and instantiates many times (a Repeater's delegate is one ObjectIR,
+// however many rows exist).
+
+export interface QmlImport {
+  /** `import QtQuick 2.15` — a registry module name. */
+  module?: string;
+  /** `import "./widgets"` — a path import (resolved by the host app). */
+  path?: string;
+  version?: string;
+  alias?: string;
+}
+
+export interface ObjectIR {
+  type: string;
+  id: string | null;
+  members: MemberIR[];
+  loc: number;
+}
+
+export type ValueIR =
+  /** A JavaScript expression, compiled lazily by the runtime. */
+  | { kind: 'expr'; src: string; loc: number }
+  /** `prop: { …statements }` — a script binding (still reactive). */
+  | { kind: 'block'; src: string; loc: number }
+  /** `delegate: Component { … }`, `background: Rectangle { … }`. */
+  | { kind: 'object'; object: ObjectIR }
+  /** `states: [State { … }, …]` — an array of object templates. */
+  | { kind: 'array'; items: ValueIR[] };
+
+export interface AliasTargetIR {
+  kind: 'alias-target';
+  path: string[];
+}
+
+export type MemberIR =
+  | {
+      kind: 'property';
+      name: string;
+      propType: string;
+      readonly: boolean;
+      default: boolean;
+      required: boolean;
+      value: ValueIR | AliasTargetIR | null;
+      loc: number;
+    }
+  | {
+      kind: 'signal';
+      name: string;
+      params: Array<{ type: string; name: string }>;
+      loc: number;
+    }
+  | {
+      kind: 'function';
+      name: string;
+      params: string[];
+      body: string;
+      loc: number;
+    }
+  | { kind: 'binding'; path: string[]; value: ValueIR; loc: number }
+  | { kind: 'group'; bindings: BindingMemberIR[]; loc: number }
+  | { kind: 'object'; object: ObjectIR; loc: number }
+  | { kind: 'value-source'; object: ObjectIR; on: string[]; loc: number }
+  | { kind: 'id'; id: string; loc: number }
+  | { kind: 'inline-component'; name: string; object: ObjectIR; loc: number };
+
+export type BindingMemberIR = Extract<MemberIR, { kind: 'binding' }>;
+
+export interface QmlDocument {
+  fileName: string;
+  imports: QmlImport[];
+  pragmas: string[];
+  root: ObjectIR;
+  /** How this document was loaded — set by the engine when a resolver is
+   * in play, so the type names it uses can resolve `.qml` files relative
+   * to it (resolver.ts). */
+  load?: import('./resolver.js').DocLoad;
+}

package/src/qml/layouts.tsx

@@ -0,0 +1,141 @@
+// QtQuick.Layouts — RowLayout and ColumnLayout, lowered onto yoga.
+//
+// This is react-x11's home turf: the container renders a flex `<box>` and
+// every child renders as a flex item styled from its `Layout.*` attached
+// properties (react.tsx, `layoutChildStyle`) — `fillWidth` is `flexGrow`,
+// `preferredWidth` is the basis, `alignment` is `alignSelf`, margins are
+// margins. Yoga decides the geometry; the renderer never re-implements it.
+//
+// What QML still needs from that arrangement is *readable geometry*:
+// `item.x` and `item.width` are ordinary properties other bindings consume.
+// After each layout pass the container reads its children's laid-out rects
+// and `reflect()`s them into the x/y/width/height slots — a write that
+// disturbs no binding and no flag, so the implicit-width default keeps
+// meaning "content-sized" and an author `width:` keeps reading as a size
+// hint. Expressions see yoga's answer; yoga sees the hints.
+//
+// GridLayout is not here yet — yoga has no grid, and a half-true one would
+// be worse than the clear unknown-type error; RowLayout, ColumnLayout and
+// the full Layout.* set cover the linked reference page.
+
+import { useEffect } from 'react';
+import type { ReactElement } from 'react';
+
+import { QmlInstance, type QmlTypeDef } from './objects.js';
+import { renderQmlChildren, geometryStyle, preferredSpan } from './react.js';
+import {
+  applyMotion,
+  captureNode,
+  hostNode,
+  initItem,
+  num,
+} from './view-utils.js';
+import {
+  afterLayout,
+  cancelAfterLayout,
+  type LayoutTick,
+} from '../internal/timers.js';
+
+function isRow(inst: QmlInstance): boolean {
+  return inst.typeInfo.name === 'RowLayout';
+}
+
+/** Reflect yoga's answers into the managed children's geometry slots. */
+function feedbackLayout(inst: QmlInstance): void {
+  if (inst.destroyed) return;
+  const containerAbs = hostNode(inst)?.abs;
+  if (!containerAbs) return;
+  for (const child of inst.visualChildren()) {
+    const abs = hostNode(child)?.abs;
+    if (!abs) continue; // a custom view without captureNode: skip quietly
+    child.slots.get('x')?.reflect(abs.x - containerAbs.x);
+    child.slots.get('y')?.reflect(abs.y - containerAbs.y);
+    child.slots.get('width')?.reflect(abs.width);
+    child.slots.get('height')?.reflect(abs.height);
+  }
+}
+
+function LayoutView({ inst }: { inst: QmlInstance }): ReactElement {
+  const horizontal = isRow(inst);
+  const style = geometryStyle(inst);
+  style.display = 'flex';
+  style.flexDirection = horizontal ? 'row' : 'column';
+  style.gap = num(inst.slot('spacing').peek());
+  applyMotion(inst, style);
+
+  // Feed geometry back after the layout flush — and again whenever any
+  // child re-renders (its size hints may have moved yoga). A reflect that
+  // changes nothing notifies nobody, so this settles.
+  useEffect(() => {
+    let tick: LayoutTick = null;
+    const schedule = (): void => {
+      cancelAfterLayout(tick);
+      tick = afterLayout(() => feedbackLayout(inst));
+    };
+    schedule();
+    const offs = inst.visualChildren().map((c) => c.subscribe(schedule));
+    return () => {
+      cancelAfterLayout(tick);
+      offs.forEach((off) => off());
+    };
+  });
+
+  return (
+    <box ref={captureNode(inst)} style={style}>
+      {renderQmlChildren(inst)}
+    </box>
+  );
+}
+
+/** The container's own size hint: sum of children's preferred spans on the
+ * main axis (plus spacing), max on the cross — tracked bindings, so a
+ * child's hint change resizes a content-sized layout. */
+function layoutImplicit(inst: QmlInstance): void {
+  const horizontal = isRow(inst);
+  const tracked = (slot: { get(): unknown }): unknown => slot.get();
+  const mainExtent = (): number => {
+    let sum = 0;
+    let count = 0;
+    const spacing = num(inst.slot('spacing').get());
+    for (const child of inst.visualChildren()) {
+      if (child.slot('visible').get() === false) continue;
+      sum += preferredSpan(child, horizontal, tracked) ?? 0;
+      count++;
+    }
+    return sum + spacing * Math.max(0, count - 1);
+  };
+  const crossExtent = (): number => {
+    let max = 0;
+    for (const child of inst.visualChildren()) {
+      if (child.slot('visible').get() === false) continue;
+      max = Math.max(max, preferredSpan(child, !horizontal, tracked) ?? 0);
+    }
+    return max;
+  };
+  inst
+    .slot(horizontal ? 'implicitWidth' : 'implicitHeight')
+    .setBinding(mainExtent);
+  inst
+    .slot(horizontal ? 'implicitHeight' : 'implicitWidth')
+    .setBinding(crossExtent);
+}
+
+function layoutInit(inst: QmlInstance): void {
+  initItem(inst);
+  layoutImplicit(inst);
+}
+
+const layoutContainer: QmlTypeDef = {
+  extends: 'Item',
+  managesChildLayout: true,
+  view: LayoutView,
+  // Qt's RowLayout/ColumnLayout default spacing.
+  properties: { spacing: { default: 5 } },
+  init: layoutInit,
+  onStructure: layoutImplicit, // a Repeater spliced new children in
+};
+
+export const layoutTypes: Record<string, QmlTypeDef> = {
+  RowLayout: { ...layoutContainer },
+  ColumnLayout: { ...layoutContainer },
+};