@zerotal/flow 1.1.0 → 1.4.0

package/CHANGELOG.md

@@ -10,6 +10,95 @@ between minor versions.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-08-10
+
+### Fixed
+
+- **`focusOnError` did nothing on a page that rendered through the runtime.** The
+  JSX runtime rewrites `-` to `.` inside a `flow:` attribute — right for a
+  hand-written `flow:loading-class`, wrong for a name the directive map already
+  spells out. `focusOnError` reached the DOM as `flow:focus.error` while the
+  bridge only ever queries `[flow\:focus-error]`, so focus-on-error worked on a
+  compiled page and silently did not on one the compiler bailed out of (a
+  branching `render()`, say). Mapped names now go out verbatim; the kebab→dot
+  rewrite still applies to attributes written by hand. `sortGroupId` was affected
+  the same way.
+
+- **`flow:navigate` now scrolls, instead of leaving you wherever the last page
+  was.** The SPA swap replaced the page under a stationary viewport and never
+  touched the scroll offset, so following a link from near the bottom of a long
+  list landed you halfway down the next page. Nothing visible changed, which
+  reads as the page having failed to load rather than as a scroll problem.
+
+  A navigation now lands at the top of the new page, or at the fragment when the
+  href names one (`/docs#install`) — which is what the same link does without the
+  SPA swap. Back and Forward restore the position the entry was left at.
+
+  The scroll happens inside the swap, after the root is replaced: the document
+  only has its new height (and its fragment targets) at that point, and inside a
+  View Transition it is also what the "after" snapshot captures, so the animation
+  ends at the right offset rather than sliding to it. It is issued with
+  `behavior: "instant"`, so a page whose CSS sets `scroll-behavior: smooth` does
+  not animate the whole way up on every visit.
+
+### Added
+
+- **`preserveScroll`** — `<Link href="…" preserveScroll>` and
+  `this.navigateCurrent({ query: …, preserveScroll: true })` leave the viewport
+  where it is. For a control partway down a page — a sort header, a filter, a tab
+  strip — going to the top loses the thing the user was just looking at. Compiles
+  to `flow:navigate.preserve` on the anchor.
+
+## [1.3.0] — 2026-08-09
+
+### Fixed
+
+- **An `@expose`d action on a shared page base no longer disappears from the allowlist.** Bun
+  1.3.x does not reliably run a method decorator's `addInitializer` callbacks: when a subclass
+  declared a decorated field, the base class's method initializers never ran at all. So a page
+  base carrying `@expose guard()` lost that action the moment any subclass added one `@expose`
+  field — and since the un-`@expose`d action check is fatal, clicking a perfectly legitimate
+  button was rejected at runtime with a message pointing at the wrong cause. It reproduced with a
+  bare `class Sub extends Base` and no mixin anywhere. `@expose` (methods), `@task`,
+  `@renderless`, `@on` and `@computed` were all affected.
+
+  Method and getter decorators now tag the function in the decorator body — which always runs,
+  with the right name — and the readers scan the prototype chain for tagged members, registering
+  against the **declaring** prototype so inheritance resolves through the existing chain walk.
+  Registration no longer requires an instance to have been constructed, so `getExposedMethods()`
+  is correct on a class that has never been instantiated.
+
+### Changed — BREAKING
+
+- **`ComponentWith(...)` is replaced by the `Component.using(...)` static.** Mixin composition is
+  now a property of the base class rather than a helper shipped alongside it, so there is one
+  idiom to learn and nothing extra to import.
+
+  ```tsx
+  // before
+  import { ComponentWith, Pagination } from "@zerotal/flow";
+  class PostsPage extends ComponentWith(Pagination, FileUploads) {}
+
+  // after
+  import { Component, Pagination } from "@zerotal/flow";
+  class PostsPage extends Component.using(Pagination, FileUploads) {}
+  ```
+
+  Run `bun run scripts/codemod-mixin-composition.ts` to rewrite call sites and imports.
+
+  How mixins are **authored** is unchanged — `<T extends Constructor<Component>>(Base: T) => …`
+  still works exactly as before, and every shipped mixin keeps its signature. The `Constructor`
+  and `Mixin` types are still exported; `Compose` (the type of `Component.using`) joins them.
+
+### Added
+
+- **`using` composes onto any class in the chain, not just `Component`.** An app-level base can
+  now carry mixins without being flattened out of the prototype chain — `AdminPage.using(Pagination)`
+  keeps `AdminPage` in the lineage. `ComponentWith` hardcoded `Component`, so this previously
+  required hand-nesting (`Pagination(AdminPage)`).
+- **Composition chains.** The composed class carries `using` itself, so
+  `Component.using(a, b).using(c, d)` works past the 8-mixin overload set.
+
 ## [1.1.0] — 2026-08-08
 
 ### Fixed

package/README.md

@@ -122,7 +122,7 @@ Action helpers available inside any exposed method include `this.flash()`, `this
 
 **Headless (unstyled, accessible) primitives:** `Switch`, `Checkbox`, `Select`, `RadioGroup`, `Listbox`, `Combobox`, `Disclosure`, `Accordion`, `Popover`, `Field`, `Label`, `Description`, `Fieldset`, `Legend`.
 
-**Mixins & helpers:** compose features with `ComponentWith(Pagination, FileUploads)` — the `Pagination` mixin (`page` state + `nextPage`/`gotoPage`/…, paired with `Model.paginate()` and rendered by `<Pager>`) and the `FileUploads` mixin (`removeUpload`, paired with `<FileUpload>` + `TemporaryUploadedFile`). Also `Form` + `registerForm`, the `paginate` helper + `Paginator` type, and `Layout` for shared page shells.
+**Mixins & helpers:** compose features with `Component.using(Pagination, FileUploads)` — the `Pagination` mixin (`page` state + `nextPage`/`gotoPage`/…, paired with `Model.paginate()` and rendered by `<Pager>`) and the `FileUploads` mixin (`removeUpload`, paired with `<FileUpload>` + `TemporaryUploadedFile`). Also `Form` + `registerForm`, the `paginate` helper + `Paginator` type, and `Layout` for shared page shells.
 
 **Slots:** a child component's plain children are its default slot; a `slots={{ header, footer }}` prop supplies named slots. The child places them with `this.slot(name)` / `this.slot()` and branches on `this.hasSlot(name)` — ideal for reusable shells (cards, modals, panels). Slot markup renders in the parent's scope and is carried, signed, in the child's snapshot.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "license": "MIT",
   "maturity": "experimental",
   "private": false,
@@ -45,14 +45,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.1.0",
-    "@zerotal/orm": "1.1.0",
-    "@zerotal/validator": "1.1.0",
+    "@zerotal/core": "1.4.0",
+    "@zerotal/orm": "1.4.0",
+    "@zerotal/validator": "1.4.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.1.0",
+    "@zerotal/broadcasting": "1.4.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -23,6 +23,8 @@ import { ValidationError } from "./validation.ts";
 import type { ValidationRules } from "./validation.ts";
 import { resolveUploadValue } from "./uploads/TemporaryUploadedFile.ts";
 import { toScriptJson } from "./utils.ts";
+import { _compose } from "./mixins.ts";
+import type { Compose } from "./mixins.ts";
 import { _validateEventPayload } from "./events.ts";
 import type { FlowEvents, EventName, EventArgs } from "./events.ts";
 import { route, request, safeRedirectPath, HttpContext } from "@zerotal/core";
@@ -343,6 +345,54 @@ export abstract class Component {
    */
   static readonly __isFlowPage = true as const;
 
+  /**
+   * Compose one or more feature mixins onto this class, 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, client writes, and `@url` sync all work exactly as for props declared on the page.
+   *
+   * `using` composes onto whatever class it is called on, so it also works on an intermediate base
+   * (`AdminPage.using(Pagination)` keeps `AdminPage` in the chain), and the composed class carries
+   * `using` itself, so `Component.using(a, b).using(c)` chains past the 8-mixin overload set.
+   *
+   * Pages composed this way render via the runtime path rather than the AOT compiler (which only
+   * statically sees a page's own `extends Component` plus 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.
+   *
+   * @param mixins - Mixin factories applied left-to-right (each takes the prior result as its base).
+   * @returns A class extending this one with every mixin's members mixed in.
+   *
+   * @example
+   * ```tsx
+   * // app/flow/mixins/pagination.ts
+   * import { Component, expose, type Constructor } from "@zerotal/flow";
+   *
+   * 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 Component.using(Pagination) {
+   *   override async render() {
+   *     return <div data-flow-root>Page {this.page}</div>;
+   *   }
+   * }
+   * ```
+   *
+   * @category Composition
+   */
+  static using: Compose = _compose;
+
   // ── @internal: framework bookkeeping, not part of the developer API ──────────
 
   /** Set to true by hydrate() so the framework skips calling onMount(). @internal */

package/src/client/bridge.ts

@@ -865,7 +865,11 @@ function _syncUrlParams(comp: FlowComponent): void {
 
   if (newUrl !== location.pathname + location.search + location.hash) {
     if (pushed) {
-      history.pushState({ flowNavigate: true }, "", newUrl);
+      // Bank the scroll offset first: this entry is about to become a Back
+      // target, and the viewport has not moved, so where the user is now is
+      // where Back should return them.
+      _rememberScroll();
+      _pushHistoryEntry(newUrl);
     } else {
       history.replaceState(history.state, "", newUrl);
     }
@@ -2357,7 +2361,127 @@ function _takePrefetched(href: string): string | null {
   return Date.now() - cached.at < PREFETCH_TTL_MS ? cached.html : null;
 }
 
-async function _navigateTo(href: string, pushState = true): Promise<void> {
+// ── Scroll position across SPA navigations ────────────────────────────────────
+//
+// A real navigation puts you at the top of the new page, and Back puts you back
+// where you were. Swapping the DOM under a stationary viewport does neither: you
+// click a link near the bottom of a long list and land halfway down the next
+// page, which reads as the page having failed to load.
+//
+// Positions live in a map keyed by history entry rather than inside
+// `history.state`, because the entry you are *leaving* on a Back cannot be
+// stamped — by the time `popstate` fires, `history.state` is already the
+// destination's. A key per entry lets both directions be recorded.
+
+let _nextHistoryKey = 1;
+let _currentHistoryKey = 0;
+const _scrollByHistoryKey = new Map<number, [number, number]>();
+
+/**
+ * The live scroll offset, tracked passively.
+ *
+ * Read from here rather than from `window.scrollY` at navigation time: on a
+ * `popstate` the browser may already have applied its own scroll restoration
+ * before our handler runs, and by then the outgoing page's real position is gone.
+ */
+let _liveScroll: [number, number] = [0, 0];
+
+function _trackScroll(): void {
+  const update = (): void => {
+    _liveScroll = [window.scrollX, window.scrollY];
+  };
+  update();
+  window.addEventListener("scroll", update, { passive: true });
+}
+
+/** Record where the current history entry was left, so Back can return to it. */
+function _rememberScroll(): void {
+  _scrollByHistoryKey.set(_currentHistoryKey, _liveScroll);
+}
+
+/** Start a new history entry, keyed so its scroll position can be found again. */
+function _pushHistoryEntry(url: string): void {
+  _currentHistoryKey = _nextHistoryKey++;
+  history.pushState({ flowNavigate: true, flowKey: _currentHistoryKey }, "", url);
+}
+
+/** Where a navigation should leave the viewport. */
+export type ScrollIntent = "top" | "preserve" | readonly [number, number];
+
+/** The fragment of an href, without the `#`. Empty when it has none. */
+export function _hashOf(href: string): string {
+  const at = href.indexOf("#");
+  return at === -1 ? "" : href.slice(at + 1);
+}
+
+/**
+ * Resolve what a navigation should do to the viewport.
+ *
+ * A recorded position wins outright: on Back/Forward the whole point is to land
+ * where the user was, and `preserveScroll` is passed alongside it only as the
+ * fallback for an entry with nothing recorded.
+ */
+export function _scrollIntent(options: {
+  preserveScroll?: boolean;
+  restoreScroll?: readonly [number, number] | undefined;
+}): ScrollIntent {
+  return options.restoreScroll ?? (options.preserveScroll ? "preserve" : "top");
+}
+
+/** What {@link _applyScroll} will do, separated out so the decision is testable. */
+export type ScrollAction =
+  | { kind: "none" }
+  | { kind: "offset"; left: number; top: number }
+  | { kind: "fragment"; id: string };
+
+export function _scrollAction(intent: ScrollIntent, hash: string): ScrollAction {
+  if (intent === "preserve") return { kind: "none" };
+  if (intent !== "top") return { kind: "offset", left: intent[0], top: intent[1] };
+
+  // A fragment in the URL beats the top of the page — that is what the browser
+  // would have done for the same link without the SPA swap.
+  let id = hash;
+  if (id) {
+    try {
+      id = decodeURIComponent(id);
+    } catch {
+      /* malformed %-escape — take the fragment literally, as browsers do */
+    }
+  }
+  return id ? { kind: "fragment", id } : { kind: "offset", left: 0, top: 0 };
+}
+
+function _applyScroll(intent: ScrollIntent, hash: string): void {
+  const action = _scrollAction(intent, hash);
+  if (action.kind === "none") return;
+
+  // `behavior: "instant"` on purpose: a page with `scroll-behavior: smooth` in
+  // its CSS would otherwise animate the whole way up on every navigation, which
+  // on a long page is a visible scroll-back the user did not ask for.
+  if (action.kind === "offset") {
+    window.scrollTo({ left: action.left, top: action.top, behavior: "instant" });
+    return;
+  }
+
+  const target = document.getElementById(action.id);
+  // A fragment naming nothing on the page lands at the top, same as a real load.
+  if (target) target.scrollIntoView({ behavior: "instant", block: "start" });
+  else window.scrollTo({ left: 0, top: 0, behavior: "instant" });
+}
+
+/** Options for {@link _navigateTo}. */
+interface NavigateOptions {
+  /** Add a history entry. False on Back/Forward, where the entry already exists. */
+  push?: boolean;
+  /** Leave the viewport where it is instead of going to the top of the new page. */
+  preserveScroll?: boolean;
+  /** Offsets to restore, for Back/Forward. Takes precedence over `preserveScroll`. */
+  restoreScroll?: readonly [number, number] | undefined;
+}
+
+async function _navigateTo(href: string, options: NavigateOptions = {}): Promise<void> {
+  const { push = true } = options;
+  const scrollIntent = _scrollIntent(options);
   let html: string;
   const prefetched = _takePrefetched(href);
   if (prefetched !== null) {
@@ -2391,8 +2515,9 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     // document.write() here would re-inject the classic runtime <script> into the
     // *current* realm and redeclare its top-level bindings (e.g. `class
     // FlowComponent` → "already declared"). A hard navigation also re-bootstraps
-    // the client cleanly for the new layout.
-    if (pushState) window.location.assign(href);
+    // the client cleanly for the new layout — including the scroll position,
+    // which the browser owns on a real document load.
+    if (push) window.location.assign(href);
     else window.location.reload();
     return;
   }
@@ -2417,6 +2542,12 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   const incomingClone = incomingRoot.cloneNode(true) as HTMLElement;
   _carryPersisted(currentRoot, incomingClone);
 
+  // Where this page is sitting, banked before the swap. Replacing the root
+  // changes the document height, and the browser clamps the scroll offset
+  // against it — read afterwards, a position near the bottom of a long page
+  // comes back as somewhere near the bottom of the short one.
+  if (push) _rememberScroll();
+
   // Swap state script + component root. Wrapped in a View Transition when the
   // browser supports it, for a smooth cross-page animation; falls back to an
   // instant swap otherwise.
@@ -2427,6 +2558,11 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
     _cleanupDisconnected();
     _scanComponents();
     _processHead(doc); // re-apply head from the incoming page (shell stylesheet + page meta)
+    // Inside the swap, not after it: the document only has its new height (and
+    // its fragment targets) once the root is in place. Inside the View
+    // Transition callback this is also what the "after" snapshot captures, so
+    // the animation ends at the right offset instead of sliding there.
+    _applyScroll(scrollIntent, _hashOf(href));
   };
   const _startVT = (document as unknown as { startViewTransition?: (cb: () => void) => unknown })
     .startViewTransition;
@@ -2435,7 +2571,7 @@ async function _navigateTo(href: string, pushState = true): Promise<void> {
   if (typeof _startVT === "function" && !_reduceMotion) _startVT.call(document, _swap);
   else _swap(); // reduced-motion (or unsupported): swap instantly, no cross-page animation
 
-  if (pushState) history.pushState({ flowNavigate: true }, "", href);
+  if (push) _pushHistoryEntry(href);
   const incomingTitle = doc.querySelector("title");
   if (incomingTitle) document.title = incomingTitle.textContent ?? "";
   _updateCurrentLinks();
@@ -2542,14 +2678,22 @@ function _setupPrefetch(): void {
 function _setupNavigationLinks(): void {
   _updateCurrentLinks();
   _setupPrefetch();
+  _trackScroll();
 
   // Stamp the initial history entry as ours. A fresh page load has `history.state === null`,
   // so without this, pressing Back to the first page fires `popstate` with a null state — the
   // handler below ignores it and the URL changes while the page stays put. Replacing (not
-  // pushing) keeps the entry in place; it just gains the flowNavigate marker.
-  if (!(history.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
+  // pushing) keeps the entry in place; it just gains the flowNavigate marker and its scroll key.
+  const initial = history.state as { flowNavigate?: boolean; flowKey?: number } | null;
+  if (typeof initial?.flowKey === "number") {
+    // Restored from bfcache or a reload — keep the key so the entry's recorded
+    // position still matches, and mint above it so a new entry can't collide.
+    _currentHistoryKey = initial.flowKey;
+    _nextHistoryKey = Math.max(_nextHistoryKey, initial.flowKey + 1);
+  } else {
+    _currentHistoryKey = _nextHistoryKey++;
     history.replaceState(
-      { ...(history.state as object | null), flowNavigate: true },
+      { ...(initial as object | null), flowNavigate: true, flowKey: _currentHistoryKey },
       "",
       location.href,
     );
@@ -2566,13 +2710,31 @@ function _setupNavigationLinks(): void {
       return;
     }
     e.preventDefault();
-    void _navigateTo(href);
+    void _navigateTo(href, {
+      preserveScroll: anchor.hasAttribute("flow:navigate.preserve"),
+    });
   });
 
   window.addEventListener("popstate", (e) => {
-    if ((e.state as { flowNavigate?: boolean } | null)?.flowNavigate) {
-      void _navigateTo(window.location.pathname + window.location.search, false);
-    }
+    const state = e.state as { flowNavigate?: boolean; flowKey?: number } | null;
+    if (!state?.flowNavigate) return;
+
+    // Bank the outgoing entry before the key moves on, so Forward lands correctly
+    // too — not just Back. This is the half that cannot be done from
+    // `history.state`, which by now already describes the destination.
+    _rememberScroll();
+    const destination = state.flowKey;
+    const restore = destination === undefined ? undefined : _scrollByHistoryKey.get(destination);
+    if (destination !== undefined) _currentHistoryKey = destination;
+
+    void _navigateTo(location.pathname + location.search + location.hash, {
+      push: false,
+      restoreScroll: restore,
+      // Nothing recorded for this entry — it predates the runtime, or a reload
+      // cleared the map. Leave the viewport alone rather than jumping to the
+      // top, which is not what Back does.
+      preserveScroll: restore === undefined,
+    });
   });
 }
 
@@ -2584,12 +2746,21 @@ function _setupNavigationLinks(): void {
  * Both read the live URL from window.location (kept in sync by flow:navigate).
  * Ideal for instant filters, e.g.:
  *   <select @change="$flow.navigateCurrent({ query: { status: $event.target.value || null } })">
+ *
+ * Like any navigation this lands at the top of the page. For a control sitting
+ * partway down — a filter row the user is looking at while they change it —
+ * pass `preserveScroll: true` to leave the viewport alone:
+ *   $flow.navigateCurrent({ query: { status: … }, preserveScroll: true })
  */
 function _currentUrl(options: CurrentUrlOptions = {}): string {
   return buildUrlWithQuery(window.location.href, options);
 }
-function _navigateCurrent(options: CurrentUrlOptions = {}): Promise<void> {
-  return _navigateTo(buildUrlWithQuery(window.location.href, options));
+function _navigateCurrent(
+  options: CurrentUrlOptions & { preserveScroll?: boolean } = {},
+): Promise<void> {
+  return _navigateTo(buildUrlWithQuery(window.location.href, options), {
+    preserveScroll: options.preserveScroll ?? false,
+  });
 }
 
 const _debouncedModelSend = (() => {

package/src/compiler/directives.ts

@@ -22,6 +22,7 @@ export const BOOLEAN_DIRECTIVES: Record<string, string> = {
   hideOnDirty: "flow:dirty.remove",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  navigatePreserveScroll: "flow:navigate.preserve",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
   cloak: "flow:cloak",

package/src/compiler/transform.ts

@@ -1634,6 +1634,10 @@ function _compileRenderMethod(
           emitStatic(" flow:navigate.hover");
           continue;
         }
+        if (ln === "preserveScroll" && attr.initializer === undefined) {
+          emitStatic(" flow:navigate.preserve");
+          continue;
+        }
         if (ln === "current") {
           const ci = attr.initializer;
           // current={false} → opt out of the auto active class; current={true} → default (skip).

package/src/components.ts

@@ -22,6 +22,7 @@ export interface LinkProps {
   hover?: boolean;
   current?: boolean;
   exact?: boolean;
+  preserveScroll?: boolean;
   [key: string]: unknown;
 }
 
@@ -35,18 +36,26 @@ export interface LinkProps {
  * the automatic active state to an exact path match. Any other props pass through to
  * the `<a>`.
  *
+ * Following a link lands at the top of the new page, as a full navigation would —
+ * or at the fragment, if the href names one. `preserveScroll` leaves the viewport
+ * where it is instead, which is what you want for a control the user is looking at
+ * partway down a page (a filter, a sort header, a tab strip) rather than a link
+ * that takes them somewhere else.
+ *
  * @example
  * ```tsx
  * <Link href="/posts" hover>Posts</Link>
  * <Link href="/dashboard" exact>Dashboard</Link>
+ * <Link href="/posts?sort=title" preserveScroll>Title</Link>
  * ```
  *
  * @category Navigation & data
  */
 export function Link(props: LinkProps & { children?: unknown }): HtmlNode {
-  const { href, hover, current, exact, children, ...rest } = props;
+  const { href, hover, current, exact, preserveScroll, children, ...rest } = props;
   const out: Record<string, unknown> = { ...rest, href, navigate: true, children };
   if (hover) out["navigateHover"] = true;
+  if (preserveScroll) out["navigatePreserveScroll"] = true;
   // `current` overrides the automatic URL-based active state:
   //   false → never active (flow:current.ignore)
   //   true  → always active, and stays active across SPA navigations (flow:current.force).

package/src/decorators.ts

@@ -3,8 +3,20 @@
 // Standard TC39 decorators, keyed by the class prototype; the `get*` readers walk the
 // prototype chain so subclasses inherit.
 //
-// METHOD / GETTER decorators (@computed, @expose on a method, @renderless, @on) register
-// via `addInitializer`, which Bun compiles correctly.
+// METHOD / GETTER decorators (@computed, @expose on a method, @renderless, @task, @on) CANNOT
+// rely on `addInitializer` either. Bun 1.3.x does not reliably run a method decorator's
+// initializers on construction: a class whose SUBCLASS declares a decorated field never runs the
+// base's method initializers at all, so a shared page base's `@expose` action silently vanished
+// from the allowlist the moment a subclass added one `@expose` field — and since the un-@exposed
+// action check is fatal, a legitimate action was then rejected at runtime. It reproduces with no
+// mixin and no framework code (a bare `class Sub extends Base` on Bun 1.3.14).
+//
+// So method/getter decorators TAG the function object itself in the decorator body — which runs
+// synchronously, with the right name, always — and the `get*` readers scan the prototype chain
+// for tagged members on first read (`_scanProto`). Registration lands on the DECLARING prototype,
+// which is what makes inheritance work through `_collect`'s existing chain walk. `addInitializer`
+// is still called as a belt-and-braces fallback: it is harmless when it fires (the registries are
+// Sets keyed by prototype) and it covers members a prototype scan cannot see.
 //
 // FIELD decorators (@expose on a field, @locked, @reactive, @modelable, @transient,
 // @validate, @url, @session) CANNOT defer to a field initializer or to `addInitializer`:
@@ -106,6 +118,72 @@ function _registerOn(map: WeakMap<object, Set<string>>, self: unknown, key: stri
   _register(map, Object.getPrototypeOf(self as object) as object, key);
 }
 
+// ── Method/getter tagging (Bun addInitializer workaround) ─────────────────────
+//
+// See the header note. A method or getter decorator marks the function object it is handed
+// (or, for @computed, the wrapper it returns); `_scanProto` later reads those marks off the
+// prototype and populates the registries. Symbols so a mark can never collide with a user
+// property, and non-enumerable so nothing serializes or copies them.
+
+/** Which registry a tagged member belongs in. `on` also carries its event name. */
+interface MemberTag {
+  exposed?: boolean;
+  renderless?: boolean;
+  task?: boolean;
+  computed?: boolean;
+  on?: string;
+}
+
+// `unique symbol` (not a plain `symbol`) so the computed-key types below resolve.
+const TAG: unique symbol = Symbol.for("zerotal.flow.memberTag");
+const SCANNED: unique symbol = Symbol.for("zerotal.flow.scanned");
+
+/** Attach/merge a tag on a decorated method or getter function. */
+function _tag(fn: unknown, patch: MemberTag): void {
+  if (typeof fn !== "function") return;
+  const target = fn as { [TAG]?: MemberTag };
+  if (!Object.prototype.hasOwnProperty.call(fn, TAG)) {
+    // Own, non-enumerable slot — an inherited tag from an overridden base method must not leak.
+    Object.defineProperty(fn, TAG, { value: {}, writable: true, configurable: true });
+  }
+  Object.assign(target[TAG] as MemberTag, patch);
+}
+
+/**
+ * Populate the method/getter registries for one prototype from the tags its own members carry.
+ * Idempotent and cheap: marked with a non-enumerable flag so it runs once per prototype.
+ */
+function _scanProto(proto: object): void {
+  if (!proto || proto === Object.prototype) return;
+  if (Object.prototype.hasOwnProperty.call(proto, SCANNED)) return;
+  Object.defineProperty(proto, SCANNED, { value: true, configurable: true });
+
+  for (const name of Object.getOwnPropertyNames(proto)) {
+    if (name === "constructor") continue;
+    const desc = Object.getOwnPropertyDescriptor(proto, name);
+    if (!desc) continue;
+    // A method lives on `value`; a @computed getter on `get`.
+    const fn: unknown = desc.value ?? desc.get;
+    if (typeof fn !== "function") continue;
+    if (!Object.prototype.hasOwnProperty.call(fn, TAG)) continue;
+    const tag = (fn as { [TAG]?: MemberTag })[TAG];
+    if (!tag) continue;
+
+    if (tag.exposed) _register(_exposedMethods, proto, name);
+    if (tag.renderless) _register(_renderlessMethods, proto, name);
+    if (tag.task) _register(_taskMethods, proto, name);
+    if (tag.computed) _register(_computedProtos, proto, name);
+    if (tag.on !== undefined) _registerMap(_onListeners, proto, tag.on, name);
+  }
+}
+
+/** Scan `startProto` and every prototype above it, so inherited members register too. */
+function _scanChain(startProto: object | null): void {
+  for (let p = startProto; p && p !== Object.prototype; p = Object.getPrototypeOf(p) as object) {
+    _scanProto(p);
+  }
+}
+
 // ── Field-decorator buffer (Bun standard-decorator workaround) ────────────────
 
 interface PendingField {
@@ -235,7 +313,9 @@ function _assertField(name: string, context: { kind: string }): void {
 }
 
 export function getComputedKeys(instance: object): Set<string> {
-  return _collect(_computedProtos, Object.getPrototypeOf(instance) as object);
+  const proto = Object.getPrototypeOf(instance) as object;
+  _scanChain(proto);
+  return _collect(_computedProtos, proto);
 }
 export function getTransientKeys(instance: object): Set<string> {
   _ensureDrained(instance);
@@ -250,13 +330,16 @@ export function getLockedProps(instance: object): Set<string> {
   return _collect(_lockedProps, Object.getPrototypeOf(instance) as object);
 }
 export function getExposedMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_exposedMethods, PageClass.prototype as object);
 }
 /** `@task` method names — streaming, cancellable long-running actions. */
 export function getTaskMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_taskMethods, PageClass.prototype as object);
 }
 export function getRenderlessMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_renderlessMethods, PageClass.prototype as object);
 }
 export function getValidateRules(instance: object): Map<string, ValidateBuilder> {
@@ -264,6 +347,7 @@ export function getValidateRules(instance: object): Map<string, ValidateBuilder>
   return _collectMap(_validateRules, Object.getPrototypeOf(instance) as object);
 }
 export function getListeners(PageClass: { prototype: object }): Map<string, string> {
+  _scanChain(PageClass.prototype as object);
   return _collectMap(_onListeners, PageClass.prototype as object);
 }
 export function getUrlProps(instance: object): Map<string, UrlOptions> {
@@ -358,7 +442,10 @@ export function computed<This, Return>(
   context.addInitializer(function (this: This) {
     _registerOn(_computedProtos, this, name);
   });
-  return _memoizeGetter(getter, name) as (this: This) => Return;
+  const memoized = _memoizeGetter(getter, name);
+  // Tag the wrapper we return — that is what lands on the prototype, not `getter`.
+  _tag(memoized, { computed: true });
+  return memoized as (this: This) => Return;
 }
 
 // ── @transient ────────────────────────────────────────────────────────────────
@@ -428,7 +515,9 @@ export function expose(_value: unknown, context: ExposeContext): void {
     _enqueueField(name, (proto) => _register(_exposedProps, proto, name));
     return;
   }
-  // Method: addInitializer is available (and reliable) on method contexts.
+  // Method: tag the function so `_scanProto` finds it on the DECLARING prototype (see header);
+  // addInitializer stays as a fallback for anything a prototype scan cannot reach.
+  _tag(_value, { exposed: true });
   context.addInitializer(function (this: unknown) {
     _registerOn(_exposedMethods, this, name);
   });
@@ -664,6 +753,7 @@ export const modelable = _fieldDecorator((proto, name) => {
  * @category Actions
  */
 export function renderless(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  _tag(_fn, { renderless: true });
   context.addInitializer(function (this: unknown) {
     _registerOn(_renderlessMethods, this, String(context.name));
   });
@@ -703,6 +793,8 @@ export function renderless(_fn: unknown, context: ClassMethodDecoratorContext):
  * @category Actions
  */
 export function task(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  // `@task` implies `@expose` — it registers into the same allowlist.
+  _tag(_fn, { exposed: true, task: true });
   context.addInitializer(function (this: unknown) {
     const proto = Object.getPrototypeOf(this as object) as object;
     const name = String(context.name);
@@ -776,6 +868,8 @@ export function on(
   eventName: LooseEventName,
 ): (fn: unknown, context: ClassMethodDecoratorContext) => void {
   return (_fn: unknown, context: ClassMethodDecoratorContext): void => {
+    // `@on` implies `@expose`; the tag carries the event name so the scan can rebuild the map.
+    _tag(_fn, { exposed: true, on: eventName });
     context.addInitializer(function (this: unknown) {
       const proto = Object.getPrototypeOf(this as object) as object;
       const name = String(context.name);

package/src/index.ts

@@ -70,9 +70,9 @@ export type {
   FlashBuilder,
   FlashOptions,
 } from "./Component.ts";
-// Compose focused feature mixins onto Component — `class extends ComponentWith(Pagination, …)`.
-export { ComponentWith } from "./mixins.ts";
-export type { Constructor, Mixin } from "./mixins.ts";
+// Mixin authoring types. Compose them onto a page with the `Component.using(...)` static —
+// `class PostsPage extends Component.using(Pagination, …)`.
+export type { Constructor, Mixin, Compose } from "./mixins.ts";
 export { Layout } from "./Layout.ts";
 export { Form, registerForm } from "./Form.ts";
 // Global client store — app-wide, client-only reactive UI state, read in JSX as
@@ -80,7 +80,7 @@ export { Form, registerForm } from "./Form.ts";
 // `FlowStore` to type it.
 export { defineStore } from "./store.ts";
 export type { FlowStore } from "./store.ts";
-// Pagination state mixin (compose with `ComponentWith(Pagination)`); `paginate`/`Paginator`
+// Pagination state mixin (compose with `Component.using(Pagination)`); `paginate`/`Paginator`
 // are the in-memory paginator.
 export { paginate, Pagination } from "./pagination.ts";
 export type { Paginator } from "./pagination.ts";
@@ -227,7 +227,7 @@ import type { PageClassWithMeta } from "./registry.ts";
 // File uploads
 export { TemporaryUploadedFile } from "./uploads/TemporaryUploadedFile.ts";
 export type { UploadRef } from "./uploads/TemporaryUploadedFile.ts";
-// File-upload management mixin (compose with `ComponentWith(FileUploads)`).
+// File-upload management mixin (compose with `Component.using(FileUploads)`).
 export { FileUploads } from "./uploads/FileUploads.ts";
 
 // Validation

package/src/jsx-runtime.ts

@@ -59,6 +59,7 @@ interface FlowDirectives {
 
   navigate?: boolean;
   navigateHover?: boolean;
+  navigatePreserveScroll?: boolean;
   current?: string;
   currentExact?: boolean;
   currentStrict?: boolean;
@@ -704,6 +705,10 @@ const PULSE_PROP_MAP: Record<string, string> = {
   dirtyTarget: "flow:target",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  // One word on purpose: toFlowHtmlAttr() rewrites every `-` in a flow: attribute
+  // to a `.`, so a hyphenated modifier would reach the DOM under a different name
+  // here than the compiler emits.
+  navigatePreserveScroll: "flow:navigate.preserve",
   current: "flow:current",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
@@ -1154,8 +1159,14 @@ export function jsx(
       continue;
     }
 
-    let htmlKey = PULSE_PROP_MAP[k] || k;
-    htmlKey = toFlowHtmlAttr(htmlKey);
+    // A mapped value is the attribute name the compiler emits and the bridge queries
+    // for, so it goes out verbatim. Running it through toFlowHtmlAttr() rewrote the
+    // hyphen in `flow:focus-error` to a dot, and the runtime path then emitted an
+    // attribute nothing listens for: `focusOnError` worked on a compiled page and did
+    // nothing at all on one that fell back to the runtime, with no error either way.
+    // The kebab→dot rewrite is for hand-written `flow:*` attributes only.
+    const mapped = PULSE_PROP_MAP[k];
+    const htmlKey = mapped ?? toFlowHtmlAttr(k);
 
     // Special object formatting for `confirm={{ message, title?, confirm?, cancel?,
     // variant?, danger?, icon?, prompt? }}`. The bare {message} and {message,prompt}

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/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 = "";
  *