@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/transformers/ui-call-resolver.d.ts

@@ -0,0 +1,149 @@
+import ts from "typescript";
+import { Diagnostic, type SourceSpan } from "../../types.js";
+import { StatementIR } from "../../api/index.js";
+import { BindingSpec } from "./ui-reactive.js";
+/** Register an element's node index for .value access. Called during
+ *  build-ir.ts's import processing (alongside registerUIModuleImport).
+ *
+ *  Element ids here come from a tree walk over the SAME styled tree that
+ *  resolveNodeIndex walks, so not-found is structurally unreachable in
+ *  practice. We use resolveNodeIndexOrZero (which falls back to 0 on -1)
+ *  rather than threading diagnostics through build-ir's tree-walk path. */
+export declare function registerElementValue(treeName: string, elemId: string, htmlPath: string): void;
+/** Resolve "screen.led" → node index, or undefined if not registered. */
+export declare function resolveElementValue(treeName: string, elemId: string): number | undefined;
+/** Recorded press/release bindings: node index + pin + edge + handler name. */
+export interface PressBinding {
+    nodeIndex: number;
+    pin: string;
+    edge: "press" | "release";
+    handlerName: string;
+}
+export declare function recordPressBinding(binding: PressBinding): void;
+export declare function uiPressBindings(): PressBinding[];
+export interface ClickHandlerSpec {
+    nodeIndex: number;
+    /** Handler kind: click (short tap), hold (long press ≥600ms), release (finger up),
+     *  change (input text committed via keyboard). */
+    kind: "click" | "hold" | "release" | "change" | "rangechange";
+    /** Function name of the generated handler. */
+    fnName: string;
+    /** C++ body of the callback (legacy/auto-wire string bake). Prefer bodyStatements. */
+    callbackBody: string;
+    /** Statement IR for the callback body (main pipeline). */
+    bodyStatements?: StatementIR[];
+    /** Source span of the original callback arrow/function, when known. */
+    sourceSpan?: SourceSpan;
+    /** True when fnName references an existing author-declared C++ function (from
+     *  an on:* attribute like on:click="saveSettings"). When true, the emitter
+     *  must NOT synthesize a wrapper void fnName() {...} — the function exists. */
+    isNamedRef?: boolean;
+}
+export declare function recordClickHandler(spec: ClickHandlerSpec): void;
+export declare function clickHandlers(): ClickHandlerSpec[];
+/** Max node index that has a click handler (for sizing the handler array). */
+export declare function maxClickNodeIndex(): number;
+export interface WatchPinSpec {
+    pin: string;
+    /** Function name of the generated async watcher task. */
+    fnName: string;
+    /** C++ body of the callback (legacy string bake). Prefer bodyStatements. */
+    callbackBody: string;
+    /** Statement IR for the callback body (main pipeline). */
+    bodyStatements?: StatementIR[];
+    /** Source span of the original callback arrow/function, when known. */
+    sourceSpan?: SourceSpan;
+}
+export declare function recordWatchPin(spec: WatchPinSpec): void;
+export declare function watchPinSpecs(): WatchPinSpec[];
+export declare function registerUIModuleImport(name: string, htmlPath: string): void;
+export declare function resolveUIModuleImport(name: string): string | undefined;
+export declare function recordSignal(name: string, cppType: string, initialValue: number | string | boolean): void;
+/** Mark a signal as already emitted via its own var_decl (const X = ui.signal).
+ *  Prevents uiSignalDecls() from double-declaring it at file scope. */
+export declare function markSignalEmitted(name: string): void;
+export declare function uiSignalNames(): string[];
+/** Is `name` a recorded UI signal? Used to lower `temp()` reads → `temp`. */
+export declare function isSignalName(name: string): boolean;
+/** The recorded C++ type of a signal, or undefined if not a signal.
+ *  Used by the text-binding lowerer to pick %d vs %g (spec §5.3). */
+export declare function signalCppType(name: string): string | undefined;
+export declare function uiSignalDecls(): string[];
+export declare function recordBinding(spec: BindingSpec): void;
+export declare function uiBindings(): BindingSpec[];
+export declare function markRunNode(nodeIndex: number): void;
+export declare function isRunNode(nodeIndex: number): boolean;
+export interface CallResolverDiagnostic {
+    severity: "warning" | "error";
+    message: string;
+    code: string;
+}
+export declare function getDiagnostics(): CallResolverDiagnostic[];
+export declare function resetUICallState(): void;
+/** Is this call expression a `ui.<method>(...)` call? */
+export declare function isUICall(call: ts.CallExpression): call is ts.CallExpression & {
+    expression: ts.PropertyAccessExpression;
+};
+export interface UICallOptions {
+    /** When the call is `const X = ui.signal(...)`, the declaration name X. */
+    constName?: string;
+}
+/**
+ * Resolve a ui.* call to IR. Returns null if the call is not a ui.* call
+ * (so the caller falls through to other handling).
+ *
+ * Reads the active PlatformGraphicsStrategy from the compilation context to
+ * validate the driver and resolve colors/storage.
+ */
+/** Push a `ui-unknown-element` error diagnostic. Used by every author-facing
+ *  binding/method call site when resolveNodeIndex returns -1, so a typo'd
+ *  element id fails the build instead of silently re-targeting node 0.
+ *  Exported so call-statement.ts and canvas-lowering.ts can share the exact
+ *  same diagnostic shape across all element-binding entry points. */
+export declare function pushUnknownElementDiagnostic(diagnostics: Diagnostic[], callLabel: string, id: string, treeName: string): void;
+export declare function tryResolveUICall(call: ts.CallExpression, fileName: string, sourceText: string, diagnostics: Diagnostic[], options?: UICallOptions): StatementIR | null;
+/** Result of lowering a text-binding arrow body. */
+export interface LoweredTextBody {
+    /** Imperative C++ statement(s) writing into `buf` (the textFn param). */
+    cppBody: string;
+}
+/**
+ * Lower a text-binding arrow body to an imperative C++ statement that writes
+ * into `buf` (the textFn's first parameter, size `size`). Recognizes three
+ * shapes (spec §5.2): String(<numeric>), a bare string literal, and a template
+ * literal with numeric interpolations. Anything else produces a safe no-op
+ * (`buf[0] = 0;`) plus a `ui-bind-text-unlowered` warning so the author sees it.
+ *
+ * Pure function of the AST + the recorded signal table; no side effects beyond
+ * pushing diagnostics.
+ */
+export declare function lowerTextBindingBody(body: ts.Expression, _fileName: string, sourceText: string, diagnostics: Diagnostic[]): LoweredTextBody;
+/**
+ * Lower a `{expr}` interpolation text string to an imperative snprintf body
+ * that writes into `buf`/`size`. Mirrors `lowerTextBindingBody` Shape 3 but
+ * operates on a raw string (from HTML markup) rather than a TS AST node.
+ *
+ * Each `{...}` span becomes a `%d` argument (v1: numeric default — the dominant
+ * use case is counters/progress; string-signal interpolation should use the
+ * `ui.bind` path which has TS type information). Literal `%` in surrounding text
+ * is escaped to `%%` so snprintf doesn't misread it.
+ *
+ *   "taps: {count}"          → 'snprintf(buf, size, "taps: %d", count);'
+ *   "a:{x} b:{y}"            → 'snprintf(buf, size, "a:%d b:%d", x, y);'
+ *   "{n}% done"              → 'snprintf(buf, size, "%d%% done", n);'
+ *
+ * Empty braces `{}` are treated as literal text (not interpolation). Returns
+ * null if no interpolation is present (caller keeps the static text).
+ */
+export declare function lowerInterpolationText(raw: string): string | null;
+/** Look up a node's index in its tree by element id (pre-order DFS order).
+ *  Returns the node index, or `-1` if the id is not found (or the module
+ *  isn't loaded). Callers must check for `-1` and emit a `ui-unknown-element`
+ *  diagnostic — silently treating `-1` as a valid index would target node 0
+ *  (the screen root), which is the silent-miscompilation failure mode this
+ *  guard exists to prevent. */
+export declare function resolveNodeIndex(htmlPath: string, id: string, screenId?: string): number;
+/** Look up a node's HTML tag by element id (pre-order DFS order).
+ *  Used to route generic callbacks (e.g. onChange) to the right lowering path
+ *  based on element kind (range vs input). Returns "" if not found. */
+export declare function resolveNodeTag(htmlPath: string, id: string, screenId?: string): string;