lecodes-sdk 0.19.0

package/src/ui/UIInput.ts

@@ -0,0 +1,185 @@
+import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
+
+type InputStyle = {
+  placeholder?: string,
+  placeholderColor?: Color,
+  /**
+   * Keyboard hint, NOT a validator — `number` does not block pasted letters; validate in your own
+   * onChange. The phone-pad value is `phone` (LeCodes has no `tel`).
+   *
+   * `date` / `time` are PICKER kinds, not keyboards: the host opens its native picker in the
+   * keyboard slot (iOS wheels / browser calendar) and free typing is disabled. `value` is always
+   * canonical — `YYYY-MM-DD` for `date`, `HH:MM` (24h) for `time` — while the field displays a
+   * localized string; set/compare values in the canonical form only.
+   */
+  type?: "text" | "password" | "search" | "phone" | "email" | "number" | "decimal" | "url"
+    | "date" | "time",
+  /**
+   * What the layout does while the keyboard is up (decided by the FOCUSED input). `true` (default):
+   * the layout viewport shrinks to the area above the keyboard — one relayout. `false`: the keyboard
+   * overlays the UI with NO layout recalculation — for chat composers that manage their own inset
+   * (pair with `app.keyboardHeight` / the app `"keyboard"` event) and full-screen canvases where a
+   * reflow is worse than overlap.
+   */
+  keyboardShrink?: boolean,
+  /**
+   * Whether a tap on a non-interactive area dismisses the keyboard while THIS input is focused
+   * (like `keyboardShrink`, the policy of the focused input). `true` (default): tapping dead
+   * space blurs — but a tap on a button or another input NEVER dismisses; the control acts and
+   * focus stays. `false`: taps never dismiss — the chat-composer policy. `blur()`, the return
+   * key (per `enterKey`), and the platform's own gestures (iOS drag-down over the keyboard)
+   * still work in both modes. Scrolling never dismisses the keyboard on any setting.
+   */
+  keyboardDismiss?: boolean,
+  /** Hard cap on the text length — enforced by the host while typing/pasting. */
+  maxLength?: number,
+  /** Auto-capitalization hint; omitted = platform default. */
+  autocapitalize?: "none" | "words" | "sentences" | "characters",
+  /** Enable/disable the platform autocorrection & suggestions; omitted = platform default. */
+  autocorrect?: boolean,
+}
+export type UIInputStyle = ElementStyle & DrawableStyle & TextStyle & InputStyle
+
+/** UIInput-only (a UITextArea's Enter is a newline, period): the return-key label. */
+type SubmitStyle = {
+  /**
+   * Return-key label. On submit the keyboard dismisses UNLESS `enterKey` is `"next"` — then the
+   * app is expected to call `otherInput.focus()` from `onSubmit`, so the keyboard never blinks.
+   */
+  enterKey?: "done" | "go" | "next" | "search" | "send",
+}
+
+/** A single-line text input. Keyboard/picker kind via the `type` style, return-key behavior via
+ *  `enterKey` + `onSubmit`; keyboard policy on `keyboardShrink`/`keyboardDismiss`. */
+export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+  readonly type: "input",
+
+  /**
+   * The field's text. Writable at any time — set it BEFORE the screen opens to pre-fill a form
+   * (settings, edit-profile); the value is stashed on the node and applied when the host builds
+   * it. Reads return the live text while the screen is open, and the last value you set while it
+   * isn't. The user's typing is not preserved across close/open (use `keepAlive()` for that).
+   */
+  value: string
+
+  /** The text changed — fires on every user edit. */
+  onChange(callback: (value: string) => void): UIInput
+  /** Gained focus (keyboard opens). */
+  onFocus(callback: () => void): UIInput
+  /** Lost focus. */
+  onBlur(callback: () => void): UIInput
+  /** The keyboard's return key was pressed. `value` is the current text. See `enterKey`. */
+  onSubmit(callback: (value: string) => void): UIInput
+
+  /** Focus the input (opens the keyboard). No-op before mount. */
+  focus(): void
+  /** Release focus (dismisses the keyboard when this input held it). */
+  blur(): void
+}
+
+/** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
+export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+  readonly type: "textarea",
+
+  /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */
+  value: string
+
+  /** The text changed — fires on every user edit. */
+  onChange(callback: (value: string) => void): UITextArea
+  /** Gained focus (keyboard opens). */
+  onFocus(callback: () => void): UITextArea
+  /** Lost focus. */
+  onBlur(callback: () => void): UITextArea
+
+  /** Focus the text area (opens the keyboard). No-op before mount. */
+  focus(): void
+  /** Release focus (dismisses the keyboard when this text area held it). */
+  blur(): void
+}
+
+class InputElement<T extends "input" | "textarea"> extends Element<T> {
+
+  readonly cl: Function[] = []
+  readonly fl: Function[] = []
+  readonly bl: Function[] = []
+  readonly sl: Function[] = []
+
+  /** @internal The value as last set by CODE. Hosts read it at node creation (after the initial
+   *  style, so a `date` field's canonical parse and `maxLength` are already in place), which is
+   *  what makes a value assigned before mount — a pre-filled settings form — land on the field.
+   *  Same pre-mount stash as UIImage's `_sourceRect`. Typing does NOT sync back here: while
+   *  mounted the HOST owns the text (IME composition, paste, the maxLength clamp, date/time
+   *  canonicalization) and the getter reads it over the bridge. So on a remount the field comes
+   *  back with the last code-set value, not what the user typed — screens that must keep live
+   *  editing state across close/open use `keepAlive()`, the mechanism built for it. */
+  _value = ""
+
+  get value() {
+    // Mounted: the host is authoritative. Unmounted: what code last set (0 => never mounted).
+    return this._id !== 0 ? _creatorUI.getTextValue(this._id) : this._value
+  }
+  set value(value: string) {
+    this._value = value
+    if (this._id !== 0) {
+      _creatorUI.updateNode(this._id, "value", value)
+    }
+  }
+
+  // `phone` is SDK-surface only — hosts (and the web's verbatim `el.type`) keep HTML's `tel` as
+  // the wire format, so the rename never reaches them.
+  _mapStyle(style: any): void {
+    if (style.type === "phone") style.type = "tel"
+  }
+
+  onChange (callback: (value: string) => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onFocus(callback: () => void): this {
+    this.fl.push(callback)
+    return this
+  }
+  onBlur(callback: () => void): this {
+    this.bl.push(callback)
+    return this
+  }
+  onSubmit(callback: (value: string) => void): this {
+    this.sl.push(callback)
+    return this
+  }
+
+  // Focus rides the existing value channel (updateNode "focus") — no new ABI method.
+  focus(): void {
+    if (this._id !== 0) {
+      _creatorUI.updateNode(this._id, "focus", true)
+    }
+  }
+  blur(): void {
+    if (this._id !== 0) {
+      _creatorUI.updateNode(this._id, "focus", false)
+    }
+  }
+}
+
+/** Create a single-line text input. Read/write the text via `.value`, listen with
+ *  `onChange`/`onSubmit`; style keys `placeholder`, `type`, `enterKey`, … configure it. */
+export function UIInput(): UIInput;
+export function UIInput(style: UIInputStyle): UIInput;
+export function UIInput(style?: UIInputStyle): UIInput {
+  // One text line as the floor — an unstyled input must never collapse to 0 height.
+  return new InputElement("input", { minHeight: "1.2em", ...style })
+}
+
+/**
+ * Multi-line text field. Enter is a newline (submit lives on UIInput / your own button).
+ *
+ * Auto-grow: with no explicit `height` the field measures its own content and grows line by
+ * line — clamp the range with `minHeight` / `maxHeight` (past `maxHeight` the text scrolls
+ * inside). A fixed `height` opts out and scrolls internally from the start. Chat composers are
+ * the canonical use: a bare textarea in a padded pill, `maxHeight` at ~5 lines.
+ */
+export function UITextArea(): UITextArea;
+export function UITextArea(style: UIInputStyle): UITextArea;
+export function UITextArea(style?: UIInputStyle): UITextArea {
+  return new InputElement("textarea", { minHeight: "1.2em", ...style })
+}

package/src/ui/UIModal.ts

@@ -0,0 +1,139 @@
+import { type UIWidget, type UIWidgetStyle, WidgetElement } from "./UIWidget"
+import { buildUI, type BaseStyle, type ChildrenFn, type Color, type DrawableStyle, type UIChildArg, type UINodeChild } from "./UINode"
+
+export type UIModalStyle = UIWidgetStyle
+
+/**
+ * The modal's hidden pose: `show()` animates from it, `hide()` animates to it. `duration` (ms)
+ * applies to both directions.
+ */
+export type UIModalTransition = DrawableStyle & BaseStyle & {
+  overlayColor?: Color | null,
+  duration?: number,
+}
+
+const MODAL_ANIM_MS = 200
+
+/**
+ * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
+ * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()`
+ * (a 200 ms fade by default — swap the pose via `transition()`; the exit plays with
+ * `commit: false`, so the style is intact for the next show), and closes itself on a scrim tap
+ * or the Android back button (disable via `dismissible(false)`). Everything else is a plain
+ * widget — same styling, children, touch and `attachTo()` surface; create it **once** at module
+ * scope and reuse it.
+ */
+export interface UIModal extends UIWidget {
+  /** Mount as an overlay and play the entrance transition. No-op while already open. */
+  show(): void,
+  /** Play the exit transition, then unmount. No-op while closed or already closing. */
+  hide(): void,
+  /** True from `show()` until `hide()` starts (already false during the exit animation). */
+  readonly isOpen: boolean,
+
+  /**
+   * Replace the show/hide animation. `hidden` is the off-screen pose — `show()` animates from
+   * it, `hide()` animates to it. Default `{ opacity: 0, duration: 200 }` (a fade); the pose
+   * replaces it wholesale, so a slide without a fade is just the slide. The scrim keeps its own
+   * fade unless the pose sets `overlayColor` itself.
+   *
+   * ```ts
+   * sheet.transition({ transform: "translateY(480px)", duration: 250 })   // bottom sheet
+   * ```
+   */
+  transition(hidden: UIModalTransition): this,
+
+  /** Called when `show()` mounts the modal. */
+  onOpen(callback: () => void): this,
+  /** Called when the modal starts closing — scrim tap, back button, or a `hide()` call. */
+  onClose(callback: () => void): this,
+  /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
+   *  (forced-choice dialogs). Default `true`. */
+  dismissible(enabled: boolean): this,
+}
+
+export class ModalElement extends WidgetElement {
+  _open = false
+  _dismissible = true
+  _transition: UIModalTransition = { opacity: 0 }
+  _closeTimer?: ReturnType<typeof setTimeout>
+  readonly _openListeners: (() => void)[] = []
+  readonly _closeListeners: (() => void)[] = []
+
+  constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn) {
+    super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", ...style }, children)
+    this.onOverlayTap(() => { if (this._dismissible) this.hide() })
+    this.onBackPressed(() => { if (this._dismissible) this.hide() })
+  }
+
+  // The full animate argument: hidden pose + duration, plus the scrim fade — only when the
+  // modal actually has a scrim (overlayColor: null opts out; animating a null scrim would
+  // create the intercepting layer) and the pose doesn't drive the scrim itself.
+  private _pose(extra?: Record<string, unknown>): Record<string, unknown> {
+    const pose: Record<string, unknown> = { duration: MODAL_ANIM_MS, ...this._transition, ...extra }
+    const overlayColor = (this._style as UIModalStyle).overlayColor
+    if (pose.overlayColor === undefined && overlayColor !== undefined && overlayColor !== null) {
+      pose.overlayColor = "transparent"
+    }
+    return pose
+  }
+
+  private get _duration(): number {
+    return this._transition.duration ?? MODAL_ANIM_MS
+  }
+
+  transition(hidden: UIModalTransition): this {
+    this._transition = hidden
+    return this
+  }
+
+  show(): void {
+    if (this._open) return
+    if (this._closeTimer !== undefined) {   // reopened mid exit: finish that hide now
+      clearTimeout(this._closeTimer)
+      this._closeTimer = undefined
+      super.hide()
+    }
+    this._open = true
+    super.show()
+    this.animateFrom(this._pose())
+    for (const callback of this._openListeners) callback()
+  }
+
+  hide(): void {
+    if (!this._open) return
+    this._open = false
+    this.animateTo(this._pose({ commit: false }))
+    this._closeTimer = setTimeout(() => { this._closeTimer = undefined; super.hide() }, this._duration)
+    for (const callback of this._closeListeners) callback()
+  }
+
+  get isOpen(): boolean {
+    return this._open
+  }
+
+  onOpen(callback: () => void): this {
+    this._openListeners.push(callback)
+    return this
+  }
+  onClose(callback: () => void): this {
+    this._closeListeners.push(callback)
+    return this
+  }
+  dismissible(enabled: boolean): this {
+    this._dismissible = enabled
+    return this
+  }
+}
+
+const makeModal = (style: any, children: any) => new ModalElement(style, children)
+
+/** Create a modal dialog (see {@link UIModal}) — create once at module scope, then
+ *  `show()`/`hide()`. Same argument forms as `UIColumn`. */
+export function UIModal(...children: UIChildArg[]): UIModal;
+export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIModal(style: UIModalStyle, children?: UINodeChild[] | ChildrenFn): UIModal;
+export function UIModal(...args: any[]): UIModal {
+  return buildUI(args, null, makeModal)
+}