lecodes-sdk 2.2.0 → 2.2.1

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.0",
+  "version": "2.2.1",
   "files": [
     "src",
     "dist",

package/prompts/ui.md

@@ -191,6 +191,7 @@ UIInput() / UITextArea()
 //   type: "text"|"password"|"search"|"phone"|"email"|"number"|"decimal"|"url"|"date"|"time"
 //   enterKey: "done"|"go"|"next"|"search"|"send" (UIInput only) — return-key label
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
+//   autofocus: boolean — takes the focus as its screen opens (a composer, a chat, a search; once, one per screen)
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
 //   $focused: { borderColor, ..., duration? } — style while focused (reserved class)

package/src/ui/UIInput.ts

@@ -1,5 +1,6 @@
 import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
 import { TREE_FLAG_BLUR, TREE_FLAG_CHANGE, TREE_FLAG_FOCUS, TREE_FLAG_SUBMIT, tree } from "./tree"
+import { registerAutofocus } from "./autofocus"
 
 type InputStyle = {
   placeholder?: string,
@@ -32,6 +33,13 @@ type InputStyle = {
    * still work in both modes. Scrolling never dismisses the keyboard on any setting.
    */
   keyboardDismiss?: boolean,
+  /**
+   * Takes the focus when its screen opens — the keyboard is up from the first moment. For a
+   * screen made for typing: a composer, a chat, a search, a one-field form; not the first field
+   * of a long form. Once per input (a screen shown again does not take the keyboard back); one
+   * per screen. The SDK's own behaviour over `focus()`: a design tool shows the screen as it opens.
+   */
+  autofocus?: boolean,
   /** Hard cap on the text length — enforced by the host while typing/pasting. */
   maxLength?: number,
   /** Auto-capitalization hint; omitted = platform default. */
@@ -110,9 +118,11 @@ class InputElement<T extends "input" | "textarea"> extends Element<T> {
   }
 
   // `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.
+  // the wire format, so the rename never reaches them. `autofocus` is the SDK's too (./autofocus.ts):
+  // it never reaches a host.
   _mapStyle(style: any): void {
     if (style.type === "phone") style.type = "tel"
+    if ("autofocus" in style) { registerAutofocus(this, !!style.autofocus); delete style.autofocus }
   }
 
   onChange (callback: (value: string) => void): this {

package/src/ui/UINode.ts

@@ -395,6 +395,7 @@ const handler: ProxyHandler<any> = {
     if (el._mapStyle !== undefined) {
       const mapped = { [key]: value }
       el._mapStyle(mapped)
+      if (!(key in mapped)) return true   // the SDK's own key (an input's autofocus): nothing for the host
       value = mapped[key]
     }
     const wire = wireValue(key, value)

package/src/ui/UIScreen.ts

@@ -3,6 +3,7 @@ import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOp
 import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { ContainerElement, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
 import { TREE_DEST_SCREEN, TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_KEEP_ALIVE, pin, tree } from "./tree"
+import { autofocusIn } from "./autofocus"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
@@ -92,7 +93,7 @@ export class ScreenElement extends ContainerElement<"screen"> {
     return this
   }
   /** @internal presentation lifecycle from the runtime (also a pager's page open / close). */
-  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  _emitOpen(): void { autofocusIn(this._h.id); for (const cb of this.ol.slice()) cb() }
   /** @internal */
   _emitClose(): void { for (const cb of this.cl.slice()) cb() }
 

package/src/ui/autofocus.ts

@@ -0,0 +1,54 @@
+// Autofocus: an input that takes the focus when its screen opens (`autofocus: true` in its style)
+// — a composer, a chat, a search, a one-field form open with the keyboard. The behaviour is the
+// SDK's over the hosts' `focus()`: no host knows the key. An input registers here when the key is
+// set; a screen's open (UIScreen._emitOpen, a pager's page too) asks for the one inside it. Once
+// per input: a screen shown again (uncovered, its tab chosen again) does not take the keyboard
+// back. Two on one screen is a mistake the console says; the first keeps it. The registry holds
+// the inputs weakly: a screen that was dropped goes with its input.
+import { tree } from "./tree"
+
+interface WeakRefLike<T extends object> { deref(): T | undefined }
+const WeakRefImpl: new <T extends object>(target: T) => WeakRefLike<T> =
+  typeof WeakRef !== "undefined" ? WeakRef : class StrongRef<T extends object> {
+    private _t: T
+    constructor(target: T) { this._t = target }
+    deref(): T | undefined { return this._t }
+  }
+
+type Focusable = { readonly _h: { readonly id: number }, focus(): void, _autofocusDone?: boolean }
+
+const registry = new Set<WeakRefLike<Focusable>>()
+const refOf = (el: Focusable): WeakRefLike<Focusable> | undefined => { for (const ref of registry) if (ref.deref() === el) return ref; return undefined }
+
+/** @internal The input asks for (or gives up) the focus at its screen's open. */
+export const registerAutofocus = (el: Focusable, on: boolean): void => {
+  const ref = refOf(el)
+  if (on) { if (!ref) registry.add(new WeakRefImpl(el)) }
+  else if (ref) registry.delete(ref)
+}
+
+const within = (id: number, rootId: number): boolean => {
+  const t = tree()
+  let p = t.parent(id)
+  for (let guard = 0; p !== 0 && guard < 10_000; guard++) {
+    if (p === rootId) return true
+    p = t.parent(p)
+  }
+  return false
+}
+
+/** @internal A screen (or page) opened: the autofocus input inside it takes the focus, once. */
+export const autofocusIn = (rootId: number): void => {
+  if (registry.size === 0) return
+  let taken: Focusable | null = null
+  for (const ref of [...registry]) {
+    const el = ref.deref()
+    if (!el || el._h.id === 0) { registry.delete(ref); continue }
+    if (el._autofocusDone || !within(el._h.id, rootId)) continue
+    if (taken) { console.warn("autofocus: two inputs on one screen ask for it — the first keeps it"); continue }
+    taken = el
+  }
+  if (!taken) return
+  taken._autofocusDone = true
+  taken.focus()
+}

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.2.0"
+export const SDK_VERSION = "2.2.1"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {