@zerotal/flow 1.0.4 → 1.3.0

package/src/jsx-runtime.ts

@@ -10,7 +10,11 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { escapeHtml } from "@zerotal/core/helpers";
 import { getExposedProps, getLockedProps } from "./decorators.ts";
-import { _setExposedKeyCapture, _consumeExposedKeyCapture } from "./utils.ts";
+import {
+  _setExposedKeyCapture,
+  _consumeExposedKeyCapture,
+  _consumeExposedKeyReads,
+} from "./utils.ts";
 import { URL_ATTRIBUTES, sanitizeUrl } from "./urlSafety.ts";
 
 /** The rendered output of a JSX element: an object carrying its serialized HTML string. */
@@ -557,18 +561,27 @@ export function _resolveBindName(
  * capture AND a value-identity match, so a literal or server value never false-positives),
  * or null when the attribute is just an ordinary server-rendered value.
  * `locked` distinguishes @locked (read-only, reactive) from @expose (two-way).
+ *
+ * @remarks
+ * The getter capture is a single slot and *all* of an element's props are evaluated
+ * before `jsx()` runs, so any later prop that reads an exposed property clobbers it —
+ * `value={this.destination} disabled={this.notSure}` leaves the capture pointing at
+ * `notSure`. The freshness check then fails and the element renders with no
+ * `flow:model` at all: the field accepts typing and nothing ever reaches the server.
+ * When the capture is unusable we therefore fall back to a value-identity scan over
+ * the exposed props, exactly as `_resolveBindName` does — binding correctly whenever
+ * the answer is unambiguous, rather than silently dropping the binding.
  */
 function _resolveValueBind(value: unknown): { name: string; locked: boolean } | null {
   const page = _getRenderCtx()?.page ?? null;
   if (!page) return null;
   const cap = _consumeExposedKeyCapture();
-  if (!cap) return null;
   const exposed = getExposedProps(page); // includes @locked
 
   // Dotted capture (e.g. "form.email") — a Form field. The root must be an exposed
   // prop and the nested value must identity-match (freshness guard). Form fields
   // are always writable (two-way), so locked is false.
-  if (cap.includes(".")) {
+  if (cap && cap.includes(".")) {
     const root = cap.slice(0, cap.indexOf("."));
     if (!exposed.has(root)) return null;
     const nested = cap
@@ -578,11 +591,29 @@ function _resolveValueBind(value: unknown): { name: string; locked: boolean } |
     return { name: cap, locked: false };
   }
 
-  if (!exposed.has(cap)) return null;
-  // Confirm the capture is fresh for THIS value (guards against a stale capture
-  // lingering from a previous element that didn't consume it).
-  if (!Object.is((page as Record<string, unknown>)[cap], value)) return null;
-  return { name: cap, locked: getLockedProps(page).has(cap) };
+  // Capture fast path: trust it only when it is fresh for THIS value (guards against
+  // a stale capture lingering from a previous element that didn't consume it).
+  if (cap && exposed.has(cap) && Object.is((page as Record<string, unknown>)[cap], value)) {
+    _consumeExposedKeyReads(); // this element is resolved; don't leak reads to the next
+    return { name: cap, locked: getLockedProps(page).has(cap) };
+  }
+
+  // The single slot was clobbered by a later prop on the same element (the B2 case:
+  // `value={this.destination} disabled={this.notSure}`). Fall back to the keys actually
+  // read while this element's props were evaluated, most recent first, and take the one
+  // whose current value IS this value.
+  //
+  // Crucially this is NOT a scan of every exposed prop: a key only qualifies if it was
+  // genuinely read through a `this.` getter, so a literal `value="CUSTOM"` that happens
+  // to equal some property's current value still binds nothing.
+  const reads = _consumeExposedKeyReads();
+  for (const key of reads) {
+    if (key === cap) continue; // already rejected above
+    if (!exposed.has(key)) continue;
+    if (!Object.is((page as Record<string, unknown>)[key], value)) continue;
+    return { name: key, locked: getLockedProps(page).has(key) };
+  }
+  return null;
 }
 
 /**
@@ -1061,6 +1092,18 @@ export function jsx(
         attrs.push(`value="${escapeAttr(String(v ?? ""))}"`);
         continue;
       }
+      // A radio's `value` is the option's identifier and its `checked` is a per-option
+      // boolean — neither is a two-way binding target, and inferring one is actively
+      // wrong. In a group rendered from a .map() the inference lands on whichever single
+      // option currently equals the bound property, so that one radio claims the whole
+      // group's model and overwrites the user's pick on every flush. Bind a radio group
+      // explicitly with {...this.bind('prop', 'optionValue')}, which knows the group is
+      // addressed as a unit.
+      if (type === "input" && String(p["type"] ?? "") === "radio") {
+        if (k === "value") attrs.push(`value="${escapeAttr(String(v ?? ""))}"`);
+        else if (v) attrs.push("checked");
+        continue;
+      }
       const bound = _resolveValueBind(v);
       if (bound) {
         if (bound.locked) {

package/src/mixins.ts

@@ -1,17 +1,9 @@
 // ── Component mixins ────────────────────────────────────────────────────────
 //
-// `ComponentWith(...)` composes any number of feature mixins on top of `Component`,
-// so a page can be broken into focused, reusable behaviours (pagination, file uploads,
-// sortable tables, …) that stack left-to-right instead of bloating one class — the
-// Flow counterpart of the ORM's `BaseModelWith(...)`:
-//
-//   // before — one class carrying every feature inline, base repeated per mixin
-//   class UsersPage extends FileUploads(Pagination(Component)) { … }
-//
-//   // after — flat, left-to-right, base baked in
-//   class UsersPage extends ComponentWith(Pagination, FileUploads) {
-//     async render() { … }   // the page only owns its own markup + state
-//   }
+// Mixin composition machinery for Flow. The entry point is `Component.using(...)`
+// (see Component.ts) — this module owns the types it is built from, and the fold
+// itself. Nothing here imports `Component`: the fold seeds from its receiver, so
+// this is a leaf module.
 //
 // A Component mixin is the canonical generic form below — note it extends an ABSTRACT
 // base and returns an `abstract class`, so it doesn't have to implement Component's
@@ -28,21 +20,7 @@
 //     return WithUpload;
 //   }
 //
-// Because each mixin returns `class extends Base`, Component's full surface (`flash()`,
-// `redirect()`, `validate()`, the `this.set`/`refresh`/… client magics, …) and every other
-// mixin's members flow through to the final page — fully type-checked. The shipped
-// `Pagination` mixin (see ./pagination.ts) is written exactly this way and composes here:
-// `ComponentWith(Pagination)`.
-//
-// Mixin `@expose`/`@locked` props register on the mixin's prototype, which sits in the page's
-// prototype chain — so they're discovered at runtime exactly like props declared on the page
-// itself (snapshot, reactivity, client writes, `@url` sync all work). Note: pages composed
-// with `ComponentWith(...)` render via the runtime path rather than the AOT compiler (which
-// only statically sees a page's own `extends Component` + locally-declared members) — the same
-// fallback complex pages already use; behaviour is identical, you just don't get the
-// ahead-of-time compile step for that page.
-
-import { Component } from "./Component.ts";
+// Compose them onto a page with `Component.using(FileUpload, …)`.
 
 /**
  * A class constructor. Abstract-aware (`abstract new …`) so the abstract `Component` base —
@@ -65,135 +43,127 @@ export type Mixin<TIn extends Constructor = Constructor, TOut extends Constructo
   Base: TIn,
 ) => TOut;
 
-type Base = typeof Component;
-
 /**
- * Compose one or more feature {@link Mixin}s onto {@link Component}, folding them left-to-right
- * so a page can be built from focused, reusable behaviours instead of one bloated class.
- *
- * @remarks
- * Each mixin receives the accumulated base and returns an extended class, so `Component`'s full
- * surface (`flash()`, `redirect()`, `validate()`, the client magics, …) and every mixin's
- * `@expose`/`@locked` members flow through to the final page — fully type-checked. Mixin props
- * register on the mixin prototype, which sits in the page's prototype chain, so snapshot,
- * reactivity, and client writes all work. Overloads cover 1–8 mixins; nest another
- * `ComponentWith(...)` call for more. Pages composed this way render via the runtime path rather
- * than the AOT compiler.
- *
- * @param mixins  mixin factories applied left-to-right (each takes the prior result as its base).
- * @returns a class extending `Component` with every mixin's members mixed in.
+ * The call signatures behind `Component.using(...)`.
  *
- * @example
- * ```tsx
- * // app/flow/mixins/pagination.ts
- * import { Component, expose, type Constructor } from "@zerotal/flow";
+ * Each overload threads the accumulated type through every step, so the composed class carries
+ * the base's full surface plus every mixin's members — fully type-checked. The `this: TBase`
+ * parameter is what makes the base polymorphic: `using` composes onto whatever class it is
+ * called on, not onto a hardcoded `Component`.
  *
- * export function Pagination<T extends Constructor<Component>>(Base: T) {
- *   abstract class WithPagination extends Base {
- *     @expose page = 1;
- *     @expose next() { this.page++; }
- *   }
- *   return WithPagination;
- * }
- *
- * // app/flow/UsersPage.tsx
- * class UsersPage extends ComponentWith(Pagination) {
- *   override async render() {
- *     return <div data-flow-root>Page {this.page}</div>;
- *   }
- * }
- * ```
+ * Overloads cover 1–8 mixins. There is no ceiling: the composed class carries `using` too, so
+ * `Base.using(a, b).using(c, d)` chains.
  */
-export function ComponentWith<A extends Constructor>(a: (base: Base) => A): A;
-export function ComponentWith<A extends Constructor, B extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-): B;
-export function ComponentWith<A extends Constructor, B extends Constructor, C extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-): C;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
->(a: (base: Base) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D): D;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-): E;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-): F;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-): G;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-): H;
+export interface Compose {
+  <TBase extends Constructor, A extends Constructor>(this: TBase, a: (base: TBase) => A): A;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+  ): B;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+  ): C;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+  ): D;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+  ): E;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+  ): F;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+  ): G;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+    H extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+    h: (base: G) => H,
+  ): H;
+}
 
-// Implementation: fold the mixins over Component, left to right. The base param is `any` so
-// each typed overload above (whose base is the narrower `typeof Component` or a prior mixin's
-// result) stays assignable to this implementation signature.
-export function ComponentWith(
+/**
+ * The fold behind {@link Compose}: apply each mixin left-to-right, seeding from `this` (the
+ * class `using` was called on). Assigned to `Component.using` — not exported publicly.
+ *
+ * @internal
+ */
+export const _compose = function (
+  this: Constructor,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variadic mixin folder
   ...mixins: Array<(base: any) => Constructor>
 ): Constructor {
-  return mixins.reduce<Constructor>(
-    (acc, mixin) => mixin(acc),
-    Component as unknown as Constructor,
-  );
-}
+  return mixins.reduce<Constructor>((acc, mixin) => mixin(acc), this);
+} as Compose;

package/src/pagination.ts

@@ -133,7 +133,7 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 // `previousPage`, `gotoPage`, `resetPage`), WITHOUT putting any of that on
 // the base Component.
 //
-//   class PostsPage extends ComponentWith(Pagination) {
+//   class PostsPage extends Component.using(Pagination) {
 //     @locked posts: Post[] = [];
 //     async onMount() { this.posts = await Post.all(); }
 //     async render() {
@@ -200,7 +200,7 @@ const DEFAULT_PAGE = "page";
  *
  * @example
  * ```tsx
- * class PostsPage extends ComponentWith(Pagination) {
+ * class PostsPage extends Component.using(Pagination) {
  *   @locked posts: Post[] = [];
  *   async onMount() { this.posts = await Post.all(); }
  *   async render() {

package/src/provider/FlowProvider.ts

@@ -274,6 +274,22 @@ async function _handleFlowMessage(ws: FlowBunWs, raw: string, deps: FlowWsDeps):
   await deps.container.runScoped(async (scoped) => {
     const ctx = new HttpContext(request, scoped);
 
+    // A WebSocket action has no Bun `Server` behind it, so `ctx.ip()` — which resolves
+    // through `server.requestIP(request)` — would return null for every action even
+    // though the socket's peer address is known here and was captured at upgrade. Supply
+    // a minimal provider so `request().ip()` answers the same inside an action as it does
+    // during the initial HTTP render, instead of silently degrading to null.
+    const socketIp = ws.data.remoteIp;
+    if (socketIp && socketIp !== "unknown") {
+      ctx._server = {
+        requestIP: () => ({
+          address: socketIp,
+          family: socketIp.includes(":") ? "IPv6" : "IPv4",
+          port: 0, // not carried across the upgrade; nothing reads it
+        }),
+      };
+    }
+
     await RequestContext.run(ctx, async () => {
       let passed = false;
       let redirectUrl: string | undefined;

package/src/testing.ts

@@ -54,6 +54,10 @@ export class FlowTest<T extends Component> {
   private _effects: FlowEffects | null = null;
   private _snapshot: Snapshot | null = null;
   private _name: string;
+  /** Set by {@link tolerateErrors}: capture action errors instead of rethrowing them. */
+  private _tolerateErrors = false;
+  /** The last non-validation error an action threw, when {@link tolerateErrors} is on. */
+  private _lastError: Error | null = null;
 
   private constructor(page: T, name: string) {
     this._page = page;
@@ -97,13 +101,43 @@ export class FlowTest<T extends Component> {
   // ── Actions ────────────────────────────────────────────────────────────────
 
   /**
-   * Set a property value directly (state seeding), then return for chaining.
-   * Does NOT fire the updating/updated hooks — use `update()` to simulate a
-   * client-driven property change.
+   * Set a property value directly (state seeding) and re-render, then return for
+   * chaining. Does NOT fire the updating/updated hooks — use `update()` to
+   * simulate a client-driven property change.
+   *
+   * The re-render is the point: without it `html()` and every assertion that reads
+   * it would still describe the render from *before* the assignment, so a test
+   * would silently assert against stale markup. Use {@link seed} when you are
+   * assigning several properties and only want to pay for one render.
    * @category Actions
    */
   async set(prop: keyof T, value: unknown): Promise<this> {
     (this._page as Record<string, unknown>)[prop as string] = value;
+    await this._render();
+    return this;
+  }
+
+  /**
+   * Assign a property without re-rendering — the batching form of {@link set}.
+   * Nothing reads the new value until the next `set`/`update`/`call` (or an
+   * explicit {@link render}) produces a fresh render.
+   * @category Actions
+   *
+   * @example
+   * ```ts
+   * await t.seed('step', 3);
+   * await t.seed('mode', 'advanced');
+   * await t.render();          // one render for both
+   * ```
+   */
+  async seed(prop: keyof T, value: unknown): Promise<this> {
+    (this._page as Record<string, unknown>)[prop as string] = value;
+    return this;
+  }
+
+  /** Re-render the page without changing state (pairs with {@link seed}). @category Actions */
+  async render(): Promise<this> {
+    await this._render();
     return this;
   }
 
@@ -120,15 +154,71 @@ export class FlowTest<T extends Component> {
     return this;
   }
 
+  /**
+   * Opt out of the rethrow in {@link call}: a throwing action is captured on the
+   * harness instead of failing the test, so the error path itself can be asserted.
+   *
+   * Only for tests *about* error handling. Leaving it off is what makes a broken
+   * action fail its test rather than look like a no-op.
+   * @category Actions
+   *
+   * @example
+   * ```ts
+   * const t = (await FlowTest.mount(CheckoutPage)).tolerateErrors();
+   * await t.call('submit');
+   * t.assertErrored(/payment gateway/);
+   * ```
+   */
+  tolerateErrors(): this {
+    this._tolerateErrors = true;
+    return this;
+  }
+
+  /** The last non-validation error an action threw, or null. @category Actions */
+  lastError(): Error | null {
+    return this._lastError;
+  }
+
+  /**
+   * Assert the last action threw, optionally matching its message.
+   * Requires {@link tolerateErrors} — without it a throwing action fails the test outright.
+   * @category Assertions
+   */
+  assertErrored(match?: string | RegExp): this {
+    if (!this._lastError) {
+      throw new Error(
+        `[FlowTest] Expected the last action on ${this._name} to throw, but it did not.`,
+      );
+    }
+    if (match !== undefined) {
+      const message = this._lastError.message;
+      const ok = typeof match === "string" ? message.includes(match) : match.test(message);
+      if (!ok) {
+        throw new Error(
+          `[FlowTest] Expected the error message to match ${String(match)}, but got: ${message}`,
+        );
+      }
+    }
+    return this;
+  }
+
   /**
    * Call an action method and re-render. Simulates a subsequent (WebSocket) request:
    * runs `onBoot()` + `onHydrate()`, invokes the method, then `onUpdate()` and re-render.
-   * If the action throws ValidationError, the errors are stored and the page re-renders
-   * with the error bag populated; any other thrown error is routed to `onError()`.
+   *
+   * A `ValidationError` is an expected outcome: the errors are stored and the page
+   * re-renders with the error bag populated, exactly as in production.
+   *
+   * Any other error is routed to `onError()` (mirroring production) and then
+   * **rethrown**, so a broken action fails its test instead of silently rendering
+   * an unchanged page. Call {@link tolerateErrors} first when the error path is
+   * what you are testing.
    *
    * @param method - Name of the method to invoke on the page.
    * @param args - Arguments forwarded to the method.
    * @throws If `method` is not a function on the page instance.
+   * @throws Whatever the action threw, unless it was a `ValidationError` or
+   *   {@link tolerateErrors} is on.
    * @category Actions
    */
   async call(method: string, ...args: unknown[]): Promise<this> {
@@ -141,16 +231,25 @@ export class FlowTest<T extends Component> {
     await this._page.onBoot();
     await this._page.onHydrate();
 
+    this._lastError = null;
+    let thrown: Error | null = null;
+
     try {
       await (fn as (...a: unknown[]) => unknown).apply(this._page, args);
     } catch (error) {
       if (error instanceof ValidationError) {
-        // Errors already stored on page._errors
+        // Errors already stored on page._errors — a normal, assertable outcome.
       } else {
+        thrown = error instanceof Error ? error : new Error(String(error));
+        this._lastError = thrown;
+        // Run the production error hook so its side effects (the default flashes
+        // the message) are observable either way. An onError that itself throws
+        // replaces the original — surfacing the deeper bug rather than hiding it.
         try {
-          await this._page.onError(error instanceof Error ? error : new Error(String(error)));
-        } catch {
-          // ignore
+          await this._page.onError(thrown);
+        } catch (hookError) {
+          thrown = hookError instanceof Error ? hookError : new Error(String(hookError));
+          this._lastError = thrown;
         }
       }
     }
@@ -158,6 +257,10 @@ export class FlowTest<T extends Component> {
     await this._page.onUpdate();
     this._effects = this._page._drainEffects();
     await this._render();
+
+    // Rethrow after the re-render, so an opted-in test still sees the rendered
+    // error state and a non-opted-in test gets the real stack.
+    if (thrown && !this._tolerateErrors) throw thrown;
     return this;
   }
 

package/src/uploads/FileUploads.ts

@@ -7,7 +7,7 @@
 // This mixin adds the ergonomic server-side actions for managing those pending uploads —
 // chiefly removing a chosen file before it's stored — without bloating the base class.
 //
-//   class Avatar extends ComponentWith(FileUploads) {
+//   class Avatar extends Component.using(FileUploads) {
 //     @expose photo: TemporaryUploadedFile | null = null;
 //     @expose async save() {
 //       this.path = await this.photo?.store("avatars"); // persist permanently
@@ -48,7 +48,7 @@ type AbstractComponentCtor = abstract new (...args: any[]) => Component;
  *
  * @example
  * ```tsx
- * class Avatar extends ComponentWith(FileUploads) {
+ * class Avatar extends Component.using(FileUploads) {
  *   @expose photo: TemporaryUploadedFile | null = null;
  *   @expose path = "";
  *

package/src/uploads/TemporaryUploadedFile.ts

@@ -98,7 +98,7 @@ async function disk(name?: string): Promise<Disk> {
  *
  * @example
  * ```tsx
- * class Avatar extends ComponentWith(FileUploads) {
+ * class Avatar extends Component.using(FileUploads) {
  *   @expose photo: TemporaryUploadedFile | null = null;
  *   @expose path = "";
  *