@galfus/engine 0.0.0-stage → 0.31.0-alpha

package/src/text/input.ts

@@ -0,0 +1,160 @@
+import type { KeyboardEvent } from '@galfus/transport-types';
+import type { Focusable } from '../interaction/focus';
+import type { Realm2D } from '../realm2d/realm';
+import { TextEditor, type TextSelection } from './editor';
+import { applyTextKeyboardEvent } from './keyboard';
+
+export interface TextInputOptions {
+  readonly svgId: number;
+  readonly elementId: string;
+  /** SVG element used for hit testing; defaults to elementId. */
+  readonly hitAreaId?: string;
+  readonly value?: string;
+  readonly tabIndex?: number;
+}
+
+export type TextInputEventType = 'focus' | 'blur' | 'change' | 'selection' | 'composition';
+export interface TextInputEvent {
+  readonly type: TextInputEventType;
+  readonly windowId?: number;
+  readonly value: string;
+  readonly selection: TextSelection;
+}
+export type TextInputCallback = (event: TextInputEvent) => void;
+
+/** Editable Unicode state bound to one SVG text element and one focus target. */
+export class TextInput {
+  private readonly editor: TextEditor;
+  private readonly callbacks = new Map<TextInputEventType, Set<TextInputCallback>>();
+  private disposed = false;
+  private disposing = false;
+
+  constructor(
+    private readonly realm: Realm2D,
+    private readonly options: TextInputOptions,
+    readonly focusable: Focusable,
+    private readonly setIme: (windowId: number, enabled: boolean) => void,
+    private readonly remove: (input: TextInput) => void
+  ) {
+    this.editor = new TextEditor(options.value ?? '');
+    this.render();
+    focusable.on('focus', ({ windowId }) => {
+      this.setIme(windowId, true);
+      this.emit('focus', windowId);
+    });
+    focusable.on('blur', ({ windowId }) => {
+      if (this.editor.composition) {
+        this.editor.cancelComposition();
+        if (!this.realm.isDisposed && !this.focusable.listener.isDisposed) this.render();
+      }
+      this.setIme(windowId, false);
+      this.emit('blur', windowId);
+    });
+  }
+
+  get value(): string {
+    return this.editor.value;
+  }
+  get svgId(): number {
+    return this.options.svgId;
+  }
+  get elementId(): string {
+    return this.options.elementId;
+  }
+  get displayValue(): string {
+    return this.editor.displayValue;
+  }
+  get selection(): TextSelection {
+    return this.editor.selection;
+  }
+  get selectedText(): string {
+    return this.editor.selectedText;
+  }
+  get composition() {
+    return this.editor.composition;
+  }
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  requestFocus(windowId?: number): boolean {
+    this.assertLive();
+    return this.focusable.requestFocus(windowId);
+  }
+  blur(windowId?: number): void {
+    this.assertLive();
+    this.focusable.blur(windowId);
+  }
+  setValue(value: string): void {
+    this.mutate(() => this.editor.setValue(value));
+  }
+  setSelection(anchor: number, focus = anchor): void {
+    this.mutate(() => this.editor.setSelection(anchor, focus));
+  }
+  selectAll(): void {
+    this.mutate(() => this.editor.selectAll());
+  }
+
+  on(type: TextInputEventType, callback: TextInputCallback): () => void {
+    this.assertLive();
+    let callbacks = this.callbacks.get(type);
+    if (!callbacks) this.callbacks.set(type, (callbacks = new Set()));
+    callbacks.add(callback);
+    return () => callbacks.delete(callback);
+  }
+  off(type: TextInputEventType, callback: TextInputCallback): void {
+    this.callbacks.get(type)?.delete(callback);
+  }
+
+  /** @internal */
+  handleKeyboard(event: KeyboardEvent): void {
+    if (!this.disposed)
+      this.mutate(() => applyTextKeyboardEvent(this.editor, event), event.windowId);
+  }
+
+  dispose(): void {
+    if (this.disposed || this.disposing) return;
+    this.disposing = true;
+    this.focusable.dispose();
+    this.disposed = true;
+    this.callbacks.clear();
+    this.remove(this);
+  }
+
+  private mutate(action: () => void, windowId?: number): void {
+    this.assertLive();
+    const value = this.editor.value;
+    const display = this.editor.displayValue;
+    const { anchor, focus } = this.editor.selection;
+    const composition = this.editor.composition;
+    action();
+    if (display !== this.editor.displayValue) this.render();
+    if (value !== this.editor.value) this.emit('change', windowId);
+    if (this.disposed) return;
+    const selection = this.editor.selection;
+    if (anchor !== selection.anchor || focus !== selection.focus) this.emit('selection', windowId);
+    if (!this.disposed && composition !== this.editor.composition)
+      this.emit('composition', windowId);
+  }
+
+  private render(): void {
+    this.realm.setSvgText(
+      { svgId: this.options.svgId },
+      this.options.elementId,
+      this.editor.displayValue
+    );
+  }
+
+  private emit(type: TextInputEventType, windowId?: number): void {
+    const callbacks = this.callbacks.get(type);
+    if (!callbacks) return;
+    const event = { type, windowId, value: this.value, selection: this.selection };
+    for (const callback of callbacks) {
+      callback(event);
+      if (this.disposed) break;
+    }
+  }
+  private assertLive(): void {
+    if (this.disposed) throw new Error('Text input is disposed.');
+  }
+}

package/src/text/keyboard.ts

@@ -0,0 +1,50 @@
+import type { KeyboardEvent } from '@galfus/transport-types';
+import { TextEditor } from './editor';
+
+/** Maps platform keyboard and composition events to a single editor. */
+export function applyTextKeyboardEvent(editor: TextEditor, event: KeyboardEvent): void {
+  switch (event.type) {
+    case 'imePreedit':
+      if (event.text) editor.updateComposition(event.text, event.selection);
+      else editor.cancelComposition();
+      return;
+    case 'imeCommit':
+    case 'imeDisabled':
+      editor.cancelComposition();
+      return;
+    case 'textInput':
+      editor.insert(event.text);
+      return;
+    case 'input':
+      break;
+    default:
+      return;
+  }
+  if (event.state !== 'pressed' || editor.composition) return;
+  const { shift, ctrl, alt, superKey } = event.modifiers;
+  const isControl = (ctrl || superKey) && !alt;
+  if (isControl && event.logicalKey.toLowerCase() === 'a') {
+    editor.selectAll();
+    return;
+  }
+  switch (event.logicalKey) {
+    case 'ArrowLeft':
+      editor.move('left', shift, isControl);
+      return;
+    case 'ArrowRight':
+      editor.move('right', shift, isControl);
+      return;
+    case 'Home':
+      if (!isControl) editor.moveToBoundary('start', shift);
+      return;
+    case 'End':
+      if (!isControl) editor.moveToBoundary('end', shift);
+      return;
+    case 'Backspace':
+      editor.backspace(isControl);
+      return;
+    case 'Delete':
+      editor.deleteForward(isControl);
+      return;
+  }
+}

package/src/text/svg-decorations.ts

@@ -0,0 +1,147 @@
+/** A rectangle in SVG viewport coordinates. */
+export interface TextDecorationRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface SvgTextDecorationOptions {
+  /** An existing SVG rect reserved for the caret. */
+  readonly cursorId: string;
+  /** Existing SVG rects reserved for selection spans. */
+  readonly selectionIds?: readonly string[];
+  /** Alternatively, one existing SVG path can hold any number of selection spans. */
+  readonly selectionPathId?: string;
+  readonly cursorColor?: string;
+  readonly selectionColor?: string;
+}
+
+interface SvgAttributeWriter {
+  setSvgAttribute(svg: { svgId: number }, elementId: string, name: string, value: string): void;
+}
+
+/** Draws host-calculated caret and selection geometry in an existing SVG. */
+export class SvgTextDecorations {
+  private readonly cache = new Map<string, Map<string, string>>();
+  private readonly selectionIds: readonly string[];
+  private readonly cursorId: string;
+  private readonly selectionPathId?: string;
+  private readonly svg: { svgId: number };
+  private cursorColor: string;
+  private selectionColor: string;
+  private disposed = false;
+
+  constructor(
+    private readonly realm: SvgAttributeWriter,
+    svgId: number,
+    options: SvgTextDecorationOptions
+  ) {
+    const selectionIds = options.selectionIds ?? [];
+    if (!options.cursorId || selectionIds.some((id) => !id) || options.selectionPathId === '')
+      throw new Error('Text decoration IDs must not be empty.');
+    if (selectionIds.length && options.selectionPathId)
+      throw new Error('Use selection rectangles or a selection path, not both.');
+    const ids = [
+      options.cursorId,
+      ...selectionIds,
+      ...(options.selectionPathId ? [options.selectionPathId] : [])
+    ];
+    if (new Set(ids).size !== ids.length) throw new Error('Text decoration IDs must be distinct.');
+    this.selectionIds = [...selectionIds];
+    this.selectionPathId = options.selectionPathId;
+    this.cursorId = options.cursorId;
+    this.svg = { svgId };
+    this.cursorColor = SvgTextDecorations.color(options.cursorColor ?? '#ffffff');
+    this.selectionColor = SvgTextDecorations.color(options.selectionColor ?? '#438cff80');
+  }
+
+  setColors(colors: { cursorColor?: string; selectionColor?: string }): void {
+    this.assertLive();
+    const cursorColor =
+      colors.cursorColor === undefined
+        ? this.cursorColor
+        : SvgTextDecorations.color(colors.cursorColor);
+    const selectionColor =
+      colors.selectionColor === undefined
+        ? this.selectionColor
+        : SvgTextDecorations.color(colors.selectionColor);
+    this.cursorColor = cursorColor;
+    this.selectionColor = selectionColor;
+    if (this.cache.get(this.cursorId)?.get('display') === 'inline')
+      this.attribute(this.cursorId, 'fill', cursorColor);
+    for (const id of this.selectionIds)
+      if (this.cache.get(id)?.get('display') === 'inline')
+        this.attribute(id, 'fill', selectionColor);
+    if (this.selectionPathId && this.cache.get(this.selectionPathId)?.get('display') === 'inline')
+      this.attribute(this.selectionPathId, 'fill', selectionColor);
+  }
+
+  /** Updates geometry and colors; absent rectangles are hidden. */
+  update(cursor: TextDecorationRect | undefined, selections: readonly TextDecorationRect[]): void {
+    this.assertLive();
+    if (!this.selectionPathId && selections.length > this.selectionIds.length)
+      throw new RangeError('Not enough SVG selection rectangles for the text layout.');
+    if (cursor) SvgTextDecorations.validateRect(cursor);
+    for (const rect of selections) SvgTextDecorations.validateRect(rect);
+    this.rect(this.cursorId, cursor, this.cursorColor);
+    if (this.selectionPathId) {
+      if (selections.length) {
+        const path = selections
+          .map(({ x, y, width, height }) => `M${x} ${y}h${width}v${height}h${-width}z`)
+          .join('');
+        this.attribute(this.selectionPathId, 'd', path);
+        this.attribute(this.selectionPathId, 'fill', this.selectionColor);
+        this.attribute(this.selectionPathId, 'display', 'inline');
+      } else this.attribute(this.selectionPathId, 'display', 'none');
+    }
+    for (let index = 0; index < this.selectionIds.length; index++)
+      this.rect(this.selectionIds[index]!, selections[index], this.selectionColor);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.update(undefined, []);
+    this.disposed = true;
+    this.cache.clear();
+  }
+
+  private rect(id: string, rect: TextDecorationRect | undefined, color: string): void {
+    if (!rect) {
+      this.attribute(id, 'display', 'none');
+      return;
+    }
+    this.attribute(id, 'x', String(rect.x));
+    this.attribute(id, 'y', String(rect.y));
+    this.attribute(id, 'width', String(rect.width));
+    this.attribute(id, 'height', String(rect.height));
+    this.attribute(id, 'fill', color);
+    this.attribute(id, 'display', 'inline');
+  }
+
+  private attribute(id: string, name: string, value: string): void {
+    let attributes = this.cache.get(id);
+    if (attributes?.get(name) === value) return;
+    this.realm.setSvgAttribute(this.svg, id, name, value);
+    if (!attributes) this.cache.set(id, (attributes = new Map()));
+    attributes.set(name, value);
+  }
+
+  private assertLive(): void {
+    if (this.disposed) throw new Error('SVG text decorations are disposed.');
+  }
+
+  private static color(value: string): string {
+    if (!value.trim()) throw new Error('Text decoration color must not be empty.');
+    return value;
+  }
+
+  private static validateRect(rect: TextDecorationRect): void {
+    if (
+      ![rect.x, rect.y, rect.width, rect.height].every(Number.isFinite) ||
+      rect.width < 0 ||
+      rect.height < 0
+    )
+      throw new RangeError('Text decoration rectangle must be finite and non-negative in size.');
+  }
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Strongly typed nominal (branded) logical IDs for Galfus Engine subsystems.
+ */
+import { assertValidLogicalId } from '@galfus/transport-types';
+
+declare const __brand: unique symbol;
+export type Brand<T, B> = T & { readonly [__brand]: B };
+
+export type WindowId = Brand<number, 'WindowId'>;
+export type TargetId = Brand<number, 'TargetId'>;
+export type RealmId = Brand<number, 'RealmId'>;
+export type InvocationId = Brand<number, 'InvocationId'>;
+export type TextureId = Brand<number, 'TextureId'>;
+export type GeometryId = Brand<number, 'GeometryId'>;
+export type MaterialId = Brand<number, 'MaterialId'>;
+export type SoundId = Brand<number, 'SoundId'>;
+export type VoiceId = Brand<number, 'VoiceId'>;
+export type TransitionId = Brand<number, 'TransitionId'>;
+export type PathId = Brand<number, 'PathId'>;
+
+/**
+ * Sequential ID allocator that strictly enforces core-reserved ID boundaries.
+ */
+export class IdAllocator<T extends number = number> {
+  private _nextId: number;
+  private readonly _used = new Set<number>();
+
+  constructor(initialId = 1) {
+    this._nextId = initialId;
+  }
+
+  allocate(context = 'LogicalId'): T {
+    while (this._used.has(this._nextId)) {
+      this._nextId++;
+    }
+    const id = this._nextId++;
+    assertValidLogicalId(id, context);
+    this._used.add(id);
+    return id as T;
+  }
+
+  markUsed(id: number, context = 'LogicalId'): void {
+    assertValidLogicalId(id, context);
+    this._used.add(id);
+  }
+
+  reset(startId = 1): void {
+    this._nextId = startId;
+    this._used.clear();
+  }
+}
+
+/**
+ * Event map describing all event types emitted across the Galfus Engine runtime.
+ */
+import type {
+  AnimationEvent,
+  FrameTiming,
+  GamepadEvent,
+  KeyboardEvent,
+  PlatformEvent,
+  PointerEvent,
+  WindowEvent
+} from '@galfus/transport-types';
+
+export interface FixedTickTiming {
+  readonly fixedDt: number;
+  readonly time: number;
+  readonly subStep: number;
+  readonly frameId: number;
+}
+
+export interface RuntimeEventMap {
+  tick: FrameTiming;
+  fixedTick: FixedTickTiming;
+  window: WindowEvent;
+  pointer: PointerEvent;
+  keyboard: KeyboardEvent;
+  gamepad: GamepadEvent;
+  animation: AnimationEvent;
+  platform: PlatformEvent;
+}
+
+export type RuntimeEventType = keyof RuntimeEventMap;
+export type RuntimeEventListener<T extends RuntimeEventType> = (event: RuntimeEventMap[T]) => void;