@moku-labs/game 0.0.2 → 0.0.3

package/dist/{types-yg_ywtT-.d.mts → types-C0SLQsx0.d.mts}

@@ -1,11 +1,10 @@
-import { D as Hint, L as Json, T as Descriptor, k as Api, lt as Require, t as Api$1 } from "./types-JNc_UQBo.mjs";
-import { E as ViewHandle, M as ComponentValue, N as Entity, O as AnyComponentType, S as ProjectionMotion, b as MotionHandle, c as Point$1, j as ComponentType, l as ViewportSize, m as ChangeHook, t as Api$3, u as Api$2, y as Motion } from "./types-BxkNNYul.mjs";
+import { At as Json, D as ProjectionMotion, I as ComponentType, L as ComponentValue, N as AnyComponentType, P as AnyComponentValue, R as Entity, St as Api, T as MotionHandle, bt as Hint, h as Api$2, j as ViewHandle, m as ViewportSize, nn as Require, p as Point$1, q as Api$1, t as Api$3, vt as Descriptor, w as Motion, y as ChangeHook } from "./types-Cjf3ywai.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
 //#region src/plugins/input/types.d.ts
 declare namespace types_d_exports$1 {
-  export { Config$1 as Config, Deps, Direction, GesturePhase, InputApi, InputCtx, KernelSlice, KeyInput, KeyListener, Point, RawSample, State$1 as State, TapListener, Target };
+  export { Config$1 as Config, Deps, Direction, GesturePhase, InputApi, InputCtx, KernelSlice, KeyInput, KeyListener, Point, PointerListener, RawSample, State$1 as State, TapListener, Target };
 }
 /**
  * A point in reference units, as `renderer.viewport.toReference` answers it.
@@ -79,6 +78,19 @@ type GesturePhase = "idle" | "pressed" | "longPressed" | "dragging";
  * ```
  */
 type TapListener = (entity: Entity) => void;
+/**
+ * What `onPointer` registers: called with the raw sample inside the DOM listener, for the kinds
+ * `down`, `up` and `cancel`, right after the sample is queued.
+ *
+ * @example
+ * ```ts
+ * const lifts: RawSample[] = [];
+ * const listener: PointerListener = sample => {
+ *   if (sample.kind === "up") lifts.push(sample);
+ * };
+ * ```
+ */
+type PointerListener = (sample: RawSample) => void;
 /**
  * One key press as `onKey` hands it to a listener: the DOM `KeyboardEvent.key` and whether Shift
  * was held.
@@ -165,7 +177,8 @@ type State$1 = {
   offFrame: (() => void) | undefined;
   detach: (() => void) | undefined; /** Registered through `onTap`, called in this order on every tap. */
   tapListeners: TapListener[]; /** Registered through `onKey`, called in this order on every key. */
-  keyListeners: KeyListener[]; /** Takes the one `keydown` listener off `window`; set while a canvas is attached. */
+  keyListeners: KeyListener[]; /** Registered through `onPointer`, called in this order inside the DOM listener. */
+  pointerListeners: PointerListener[]; /** Takes the one `keydown` listener off `window`; set while a canvas is attached. */
   detachKeys: (() => void) | undefined; /** `time.wake`, bound in `onInit`: every pointer sample leaves the idle frame rate. */
   wake: (() => void) | undefined; /** The cursor last written on the attached canvas; `undefined` while nothing was written. */
   cursor: string | undefined; /** Component types other plugins registered through `controls.add`, once per registration. */
@@ -259,9 +272,34 @@ type InputApi = {
    * ```
    */
   onTap(fn: TapListener): () => void;
+  /**
+   * Registers a listener called synchronously inside the DOM pointer listener, right after the
+   * sample is queued, for `pointerdown`, `pointerup` and `pointercancel`. It is the one place a
+   * browser call that needs the user gesture can run, such as `focus()` on a text field: in the
+   * next frame iOS shows no keyboard. Never called for a move, a leave or a lost capture, and never
+   * by `tap`, `press`, `drag` or `swipe`, which have no DOM moment. The sample is raw: client px,
+   * no hit test. Listeners run in registration order; a listener that throws is logged with the
+   * sample kind, and the listeners after it still run.
+   *
+   * @param fn - What to run with the raw sample.
+   * @returns The remover; call it to stop listening.
+   * @example
+   * ```ts
+   * // ui opens the keyboard the moment the finger lifts on a text field, inside the DOM listener.
+   * const off = ctx.require(inputPlugin).onPointer(sample => {
+   *   if (sample.kind === "up" && fieldAt(sample.clientX, sample.clientY) !== undefined) element.focus({ preventScroll: true });
+   *   if (sample.kind === "down" && fieldAt(sample.clientX, sample.clientY) === undefined) element.blur();
+   * });
+   * // a tap on the Rename field on an iPhone: the keyboard shows; a tap on the parchment next to it: the keyboard hides
+   * off(); // in onStop
+   * ```
+   */
+  onPointer(fn: PointerListener): () => void;
   /**
    * Registers a listener called on every key pressed while the canvas is attached, and on every
-   * `key` call. Listeners run in registration order, all of them, each time. A listener that
+   * `pressKey` call. A key typed into a text field is not handed over, except Enter and Escape,
+   * and an Enter that commits an IME composition is dropped. Listeners run in registration order,
+   * all of them, each time. A listener that
    * returns `true` marks the key handled, and input calls `preventDefault()` on the DOM event. A
    * listener that throws is logged with its key, and the listeners after it still run.
    *
@@ -718,7 +756,8 @@ type SpriteFit = "fill" | "contain" | "cover";
 /**
  * One textured quad. `texture` is an asset key; `defineGame` narrows it to the game's keys.
  * `width` and `height` are the box in reference units; 0 on an axis keeps the texture's own size
- * there. `anchor` is the point of the box that sits on the `Transform`.
+ * there. `anchor` is the point of the box that sits on the `Transform`. `alpha` fades the quad
+ * and the entity's children.
  *
  * @example
  * ```ts
@@ -740,16 +779,23 @@ type SpriteValue = {
 /**
  * A stretchable panel. The slice borders come with the texture, not with the component. `debug`
  * strokes the bounds and the four cut lines over the panel: cyan, red when the corners overlap or
- * the texture is missing.
+ * the texture is missing. `clip` masks the children of the entity to the `width × height` box,
+ * the same rule as `Shape.clip`: the mask is a filled rectangle and is never drawn, and the panel
+ * itself is never masked. `alpha` fades the panel and the entity's children.
  *
  * @example
  * ```ts
  * const value: NineSliceValue = {
- *   texture: "ui.panel", width: 600, height: 320, alpha: 1, tint: 0xffffff, debug: false
+ *   texture: "ui.panel", width: 600, height: 320, alpha: 1, tint: 0xffffff, debug: false,
+ *   clip: false
  * };
  * // The board tray, outlined while its insets are checked.
  * const tray: NineSliceValue = {
- *   texture: "board.board-tray", width: 1000, height: 1040, alpha: 1, tint: 0xffffff, debug: true
+ *   ...value, texture: "board.board-tray", width: 1000, height: 1040, debug: true
+ * };
+ * // A text field: a long value never draws outside the frame.
+ * const field: NineSliceValue = {
+ *   ...value, texture: "ui.field", width: 480, height: 96, clip: true
  * };
  * ```
  */
@@ -760,6 +806,7 @@ type NineSliceValue = {
   alpha: number;
   tint: number;
   debug: boolean;
+  clip: boolean;
 };
 /**
  * The escape hatch: the game owns a Pixi object and `sync` only attaches and detaches it.
@@ -776,10 +823,11 @@ type DisplayValue = {
  * A filled rounded rectangle or a triangle, anchored at the top left of the `Transform`. `kind`
  * picks the outline: `"rect"` (the default) or `"triangle"`, which fills its `w × h` box pointing
  * right (rotate the element for another direction) and ignores `radius`. `fillAlpha` is the alpha
- * of the fill alone: 0 draws only the stroke, a ring. `alpha` fades the whole shape. `dash` is the
+ * of the fill alone: 0 draws only the stroke, a ring. `alpha` fades the whole shape and the
+ * entity's children: a disabled button at 0.6 draws its icon at 0.6 too. `dash` is the
  * dash length of the stroke in reference units, with gaps of half a dash; 0 strokes a solid line.
  * `clip` masks the children of the entity to the shape, always solid, which is how `ui` draws a
- * scroll and an overflow.
+ * scroll and an overflow. The shape itself is never masked, so its stroke is drawn whole.
  *
  * @example
  * ```ts
@@ -838,7 +886,7 @@ declare const Transform: ComponentType<TransformValue>;
 declare const Sprite: ComponentType<SpriteValue>;
 /**
  * A stretchable panel, sized in reference units, with its own alpha and tint. `debug: true` draws
- * the slice outline over it.
+ * the slice outline over it. `clip: true` masks the children of the entity to the panel box.
  */
 declare const NineSlice: ComponentType<{
   texture: string;
@@ -847,6 +895,7 @@ declare const NineSlice: ComponentType<{
   alpha: number;
   tint: number;
   debug: boolean;
+  clip: boolean;
 }>;
 /**
  * The entity this view moves with. `0` means no parent.
@@ -1282,6 +1331,31 @@ type ImageFit = ("contain" | "cover" | "fill") & Brand<"ImageFit">;
 type ScrollAxis = ("x" | "y") & Brand<"ScrollAxis">;
 /** The world projections whose live views a container draws inside itself. */
 type HostedProjections = readonly string[] & Brand<"HostedProjections">;
+/** The local field of the nearest component instance a text field writes on every keystroke. */
+type InputLocal = string & Brand<"InputLocal">;
+/** The intent a text field answers on Enter, with `{ [local]: value }` as the payload. */
+type InputSubmit = string & Brand<"InputSubmit">;
+/** The longest value of a text field, in UTF-16 units. */
+type InputMaxLength = number & Brand<"InputMaxLength">;
+/** What an empty text field shows at half alpha; also the label a screen reader says. */
+type InputPlaceholder = (string | Message) & Brand<"InputPlaceholder">;
+/** The keyboard a text field opens: plain text, a decimal pad or an email keyboard. */
+type TextInputKind = ("text" | "number" | "email") & Brand<"TextInputKind">;
+/** The text style key of a field's value, its placeholder and its caret height. */
+type InputTextStyle = string & Brand<"InputTextStyle">;
+/**
+ * Extra component values an element's entity carries, beside the ones the tag writes itself. Any
+ * component or tag works: a filter of `effects`, or a game's own component. A value whose type the
+ * element owns (`Transform`, `Box`, `Shape`, `Tappable`, ...) is dropped and logged as
+ * `ui:component-owned`; the element keeps its own.
+ *
+ * @example
+ * ```tsx
+ * <button key="claim" intent="claim" components={[Glow({ strength: 2 })]} />;
+ * // the button entity carries Glow({ strength: 2 }) next to Tappable, Shape and Box
+ * ```
+ */
+type ElementComponents = readonly AnyComponentValue[] & Brand<"ElementComponents">;
 /**
  * The props every tag takes, with the key kept out: JSX passes it as the third argument.
  *
@@ -1397,6 +1471,26 @@ type PanelProps = CommonProps;
 type ScrollProps = CommonProps & {
   axis?: ScrollAxis;
 };
+/**
+ * What a text field takes. `local` is required: every keystroke writes that field of the local
+ * state of the nearest component, and Enter answers `submit` with `{ [local]: value }`. `style` is
+ * the layout style of the field box.
+ *
+ * @example
+ * ```tsx
+ * // The name field of a rename popup. The player types "Alex": local.name is "Alex".
+ * <input key="nameField" local="name" maxLength={16} submit="save" placeholder="Your name" />;
+ * // Enter then answers the gate with { intent: "save", payload: { name: "Alex" } }
+ * ```
+ */
+type InputProps = CommonProps & {
+  local: InputLocal;
+  submit?: InputSubmit;
+  maxLength?: InputMaxLength;
+  placeholder?: InputPlaceholder;
+  kind?: TextInputKind;
+  textStyle?: InputTextStyle;
+};
 /**
  * The thirteen tags a screen is written with.
  *
@@ -1418,7 +1512,7 @@ type UiIntrinsicElements = {
   text: TextTagProps;
   button: ButtonTagProps;
   scroll: ScrollProps;
-  input: BoxProps;
+  input: InputProps;
 };
 /**
  * The props of one tag with its `style` narrowed to the asset keys of one game, so a nine-slice
@@ -1436,14 +1530,19 @@ type Restyled<Properties, Asset extends string> = Properties extends unknown ? O
 /**
  * The same tags with the asset keys, text style keys and message keys of one game. `uiFor`
  * carries it, so a game can name the type of its own intrinsics. The asset keys narrow `texture`,
- * `name` and the `nineSlice` of every style.
+ * `name` and the `nineSlice` of every style; the text style keys narrow the `style` of a text
+ * and the `textStyle` of a field; the message keys narrow `content` and `placeholder`.
  *
  * @example
  * ```ts
  * type Tags = IntrinsicElementsFor<"ui.coin", "digits", "hud.coins">;
  * ```
  */
-type IntrinsicElementsFor<Asset extends string, TextStyleKey extends string, StringKey extends string> = { [Tag in Exclude<keyof UiIntrinsicElements, "image" | "icon" | "text">]: Restyled<UiIntrinsicElements[Tag], Asset> } & {
+type IntrinsicElementsFor<Asset extends string, TextStyleKey extends string, StringKey extends string> = { [Tag in Exclude<keyof UiIntrinsicElements, "image" | "icon" | "text" | "input">]: Restyled<UiIntrinsicElements[Tag], Asset> } & {
+  input: Restyled<Omit<InputProps, "textStyle" | "placeholder">, Asset> & {
+    textStyle?: TextStyleKey;
+    placeholder?: string | Message<StringKey>;
+  };
   image: Restyled<CommonProps, Asset> & {
     texture: Asset;
     fit?: "contain" | "cover" | "fill";
@@ -1679,7 +1778,9 @@ type Instance = {
  * `rect` is natural: under a `fit` ancestor it is the rect before that ancestor's scale. `fit`
  * is the element's own fit scale (1 without `fit: "contain"`), and `rest` the rest `Transform`
  * last written for it. `loop` is the motion of the running `loop` hook, kept apart from
- * `handles`: it never ends, so the exit sweep must not wait for it.
+ * `handles`: it never ends, so the exit sweep must not wait for it. `extras` holds the values of
+ * the `components` prop added last time, by component name; `warnedOwned` the names of the
+ * `components` values the element owns that were already logged.
  */
 type Element = {
   entity: Entity;
@@ -1715,6 +1816,8 @@ type Element = {
   live: boolean;
   entered: boolean;
   dropKey: (() => void) | undefined;
+  extras: ReadonlyMap<string, AnyComponentValue>;
+  warnedOwned: Set<string>;
 };
 /**
  * The popup side of a root: the handler that shows it now and the root it was opened over.
@@ -1768,11 +1871,107 @@ type FocusState = {
     ring: Entity;
   } | undefined;
   drawn: DrawnRing | undefined;
-  tapping: boolean;
+  tapping: boolean; /** The focus came from a finger on a text field: the element is focused, no ring is drawn. */
+  ringless: boolean;
+};
+/**
+ * The text of the field being edited, as the frame step last read it from the hidden input, or
+ * as `fill` wrote it. Indexes count UTF-16 units, as the DOM does.
+ *
+ * @example
+ * ```ts
+ * // "Alex" typed, the caret at the end, nothing selected.
+ * const mirror: Mirror = { value: "Alex", selectionStart: 4, selectionEnd: 4, direction: "none" };
+ * ```
+ */
+type Mirror = {
+  value: string;
+  selectionStart: number;
+  selectionEnd: number;
+  direction: "forward" | "backward" | "none";
+};
+/**
+ * The part of the value an IME is composing, between `compositionstart` and `compositionend`.
+ *
+ * @example
+ * ```ts
+ * const composing: Composing = { start: 4, end: 6 };
+ * ```
+ */
+type Composing = {
+  start: number;
+  end: number;
+};
+/** The keyboard a text field opens. */
+type FieldKind = "text" | "number" | "email";
+/** The four ui-owned entities a field is drawn with besides its own, each with `Parent` = field. */
+type FieldParts = {
+  selection: Entity;
+  text: Entity;
+  caret: Entity;
+  composing: Entity;
+};
+/**
+ * One text field: its entity and the props of the `input` tag, filled at enter and dropped at the
+ * despawn. `instance` is the nearest component instance, the one whose `local` the field writes.
+ */
+type Field = {
+  entity: Entity;
+  key: string | undefined;
+  root: Entity;
+  instance: string | undefined;
+  local: string;
+  submit: string | undefined;
+  maxLength: number | undefined;
+  kind: FieldKind;
+  textStyle: string;
+  placeholder: string | Message | undefined;
+  parts: FieldParts | undefined; /** What the parts were last written with, so a field laid out the same way writes nothing. */
+  drawn: string | undefined;
+  /**
+   * A fingerprint of what the field was last laid out from, so a still field is neither measured
+   * nor laid out. `undefined` lays it out again: before its first placement, and after `text`
+   * resolved its text part again, as it does when a font arrives.
+   */
+  inputs: string | undefined;
+};
+/**
+ * Where the keyboard stands, in CSS px: the height it covers at the bottom of the window, the
+ * window height it was read with, and the lift the editing field's root is moved up by.
+ */
+type Keyboard = {
+  inset: number;
+  innerHeight: number;
+  lift: number;
+};
+/**
+ * The root the keyboard lift was last written on: its root element, the lift in reference units,
+ * and the rest pose it was added to, so a new rest is lifted again.
+ */
+type Lifted = {
+  element: Entity;
+  units: number;
+  rest: TransformValue;
+};
+/**
+ * The text input: the one hidden DOM input (none headless), the field being edited, the mirror of
+ * the text, the composing range, the keyboard, the root lifted above it, the listeners of the
+ * element (removed in `onStop`) and the viewport watcher (removed when the editing ends).
+ */
+type TextState = {
+  element: HTMLInputElement | undefined;
+  editing: Entity | undefined;
+  mirror: Mirror;
+  composing: Composing | undefined;
+  keyboard: Keyboard;
+  lifted: Lifted | undefined;
+  placed: string | undefined;
+  watching: (() => void) | undefined;
+  cleanups: Array<() => void>;
 };
 /**
  * jsx module state. `hosts` holds the elements with a `hosts` prop; `hosted` maps a world view to
- * the element that hosts it.
+ * the element that hosts it; `fields` holds the text fields by entity.
  */
 type JsxState = {
   components: Map<string, AnyComponentDefinition>;
@@ -1787,25 +1986,23 @@ type JsxState = {
   hosted: Map<Entity, Entity>;
   reconciles: number;
   focus: FocusState;
+  fields: Map<Entity, Field>;
+  text: TextState;
 };
 /**
  * One node of the snapshot `tree()` answers with. `rect` is natural: under a `fit` ancestor it
  * is the rect before that ancestor's scale. An element with `fit: "contain"` adds `fitScale`,
- * the scale it is drawn at.
+ * the scale it is drawn at. An `input` adds `value`: the text being typed while it is edited,
+ * else the local field it writes.
  *
  * @example
  * ```ts
- * // The board slot of a merge game on an iPhone SE.
- * const node: UiNode = {
- *   key: "boardSlot", type: "stack", rect: { x: 55, y: 223, w: 970, h: 970 },
- *   style: { width: 970, height: 970, fit: "contain" },
- *   state: {
- *     pressed: false, hover: false, focus: false, disabled: false, active: false, selected: false,
- *     covered: false
- *   },
- *   fitScale: 0.8,
- *   children: []
- * };
+ * // A profile screen before the player types: its name field shows the value, not its parts.
+ * const field = app.ui.tree().children[0];
+ * field?.key; // "nickField"
+ * field?.rect; // { x: 0, y: 0, w: 400, h: 80 }
+ * field?.value; // ""
+ * field?.children; // []
  * ```
  */
 type UiNode = {
@@ -1821,6 +2018,7 @@ type UiNode = {
   state: IsFlags;
   local?: Record<string, unknown>;
   fitScale?: number;
+  value?: string;
   children: UiNode[];
 };
 /**
@@ -1853,7 +2051,8 @@ type CommonProps = {
     selected?: boolean;
   }; /** The motion hooks; `undefined` written out stops a running loop, as leaving it out does. */
   motion?: ElementMotion | undefined;
-  children?: JsxChild;
+  children?: JsxChild; /** Extra components the element's entity carries, beside the ones the tag writes itself. */
+  components?: ElementComponents;
 };
 //#endregion
 export { Transform as A, types_d_exports as B, NineSliceValue as C, Sprite as D, ShapeValue as E, Events as F, InputApi as H, I18nApi as I, Message as L, sprite as M, Argument as N, SpriteOptions as O, Config as P, State as R, NineSlice as S, Shape as T, State$1 as U, Config$1 as V, types_d_exports$1 as W, Style as _, JsxChild as a, defineComponent as b, UiNode as c, popup as d, defineTokens as f, ResolvedStyle as g, IsFlags as h, Finding as i, TransformValue as j, SpriteValue as k, Box as l, UiIntrinsicElements as m, ElementChange as n, JsxState as o, IntrinsicElementsFor as p, ElementMotion as r, PopupComponent as s, DescriptionNode as t, LocalWrite as u, StylesState as v, Parent as w, Display as x, WhenFlags as y, TypedTr as z };