@react-x11/components 0.2.1 → 0.4.0

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 },
+};

package/src/qml/models.ts

@@ -0,0 +1,101 @@
+// ListModel / ListElement, and the one helper every model consumer shares.
+//
+// A ListModel is rows of plain objects. Inline `ListElement` children seed
+// it; the mutation methods (`append`, `remove`, `set`, …) are facade
+// methods, and every mutation bumps a hidden revision slot the consumers
+// (Repeater, ListView) watch — a coarse rebuild, which is the honest P1
+// answer; incremental delegate reuse is DelegateModel's job, later.
+
+import { QmlInstance, instanceOf, type QmlTypeDef } from './objects.js';
+import { Slot } from './slots.js';
+
+type Row = Record<string, unknown>;
+
+const rowsOf = (m: QmlInstance): Row[] => m.state.rows as Row[];
+
+function mutate(m: QmlInstance, fn: (rows: Row[]) => void): void {
+  fn(rowsOf(m));
+  m.slot('count').assign(rowsOf(m).length);
+  m.slot('__rev').assign((m.slot('__rev').peek() as number) + 1);
+}
+
+export const modelTypes: Record<string, QmlTypeDef> = {
+  ListElement: {
+    nonVisual: true,
+    dynamicProperties: true,
+    properties: {},
+  },
+
+  ListModel: {
+    nonVisual: true,
+    properties: { count: { default: 0 }, __rev: { default: 0 } },
+    init(m) {
+      const rows: Row[] = [];
+      for (const el of m.children) {
+        if (el.typeInfo.name !== 'ListElement') continue;
+        const row: Row = {};
+        for (const [name, slot] of el.slots) row[name] = slot.peek();
+        rows.push(row);
+      }
+      m.state.rows = rows;
+      m.slot('count').assign(rows.length);
+      m.methods.set('get', (i) => rowsOf(m)[Number(i)]);
+      m.methods.set('append', (row) => mutate(m, (r) => r.push(row as Row)));
+      m.methods.set('insert', (i, row) =>
+        mutate(m, (r) => r.splice(Number(i), 0, row as Row)),
+      );
+      m.methods.set('remove', (i, n) =>
+        mutate(m, (r) => r.splice(Number(i), n === undefined ? 1 : Number(n))),
+      );
+      m.methods.set('set', (i, row) =>
+        mutate(m, (r) => {
+          r[Number(i)] = { ...r[Number(i)], ...(row as Row) };
+        }),
+      );
+      m.methods.set('setProperty', (i, name, value) =>
+        mutate(m, (r) => {
+          r[Number(i)] = { ...r[Number(i)], [String(name)]: value };
+        }),
+      );
+      m.methods.set('clear', () => mutate(m, (r) => (r.length = 0)));
+    },
+  },
+};
+
+export interface ResolvedModel {
+  rows: unknown[];
+  /** Present for a ListModel: the revision slot a consumer watches. */
+  revSlot: Slot | null;
+}
+
+/** number | array | ListModel → rows a Repeater/ListView can walk. */
+export function resolveModel(value: unknown): ResolvedModel {
+  const inst = instanceOf(value);
+  if (inst && inst.typeInfo.name === 'ListModel') {
+    return { rows: rowsOf(inst), revSlot: inst.slot('__rev') };
+  }
+  if (typeof value === 'number') {
+    return {
+      rows: Array.from({ length: Math.max(0, Math.floor(value)) }, (_, i) => i),
+      revSlot: null,
+    };
+  }
+  if (Array.isArray(value)) return { rows: value, revSlot: null };
+  return { rows: [], revSlot: null };
+}
+
+/** The context properties a delegate row sees: index, modelData, and — for
+ * object rows — each role by name, the way QML exposes ListModel roles. */
+export function delegateExtras(
+  rows: unknown[],
+  index: number,
+): Record<string, unknown> {
+  const data = rows[index];
+  const extras: Record<string, unknown> = { index, modelData: data };
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    for (const [k, v] of Object.entries(data as Row)) {
+      if (!(k in extras)) extras[k] = v;
+    }
+  }
+  return extras;
+}