firstly 0.5.0 → 0.6.0

package/esm/svelte/dialog.svelte.js

@@ -0,0 +1,243 @@
+export { resolveMessage } from '../core/FF_Validators.js';
+let _dialogs = $state([]);
+let _confirms = $state([]);
+let _prompts = $state([]);
+let _nextId = 1;
+async function tryClose(d, result) {
+    if (!result.ok && d.options.allowClose) {
+        const allowed = await d.options.allowClose();
+        if (!allowed)
+            return false;
+    }
+    d.resolve(result);
+    _dialogs = _dialogs.filter((x) => x.id !== d.id);
+    return true;
+}
+function normaliseResult(arg) {
+    if (arg === undefined)
+        return { ok: false };
+    if (typeof arg === 'object' && arg !== null && 'ok' in arg) {
+        return arg;
+    }
+    return { ok: true, data: arg };
+}
+export const dialog = {
+    get list() {
+        return _dialogs;
+    },
+    get confirmList() {
+        return _confirms;
+    },
+    get promptList() {
+        return _prompts;
+    },
+    /** Open a dialog. Resolves when it closes. `body` is a snippet receiving `close(result?)`. */
+    show(body, options = {}) {
+        return new Promise((resolve) => {
+            _dialogs = [
+                ..._dialogs,
+                {
+                    id: _nextId++,
+                    render: { kind: 'snippet', body: body },
+                    options: {
+                        dismissible: options.dismissible ?? true,
+                        width: options.width ?? 'md',
+                        allowClose: options.allowClose,
+                    },
+                    resolve: resolve,
+                },
+            ];
+        });
+    },
+    /**
+     * Open a dialog from a **component + props** (the natural door for reusable dialogs).
+     * `close` is injected as a prop; declare it as `close: DialogClose<T>` and `open` infers
+     * the resolved `data` type from it - no call-site generic, no cast. `props` is a snapshot
+     * at open time; for reactive bodies use `show(snippet)`.
+     */
+    open(component, options = {}) {
+        return new Promise((resolve) => {
+            _dialogs = [
+                ..._dialogs,
+                {
+                    id: _nextId++,
+                    render: {
+                        kind: 'component',
+                        component: component,
+                        props: (options.props ?? {}),
+                    },
+                    options: {
+                        dismissible: options.dismissible ?? true,
+                        width: options.width ?? 'md',
+                        allowClose: options.allowClose,
+                    },
+                    resolve: resolve,
+                },
+            ];
+        });
+    },
+    /**
+     * Yes/no confirmation, rendered via the manager's `confirm` snippet. Resolves a
+     * `DialogResult` - `{ ok: true }` when confirmed, `{ ok: false }` when cancelled/dismissed
+     * (no `data`). Same `{ ok }` shape as `show`/`prompt`, so `if ((await dialog.confirm(...)).ok)`.
+     * Labels accept a `LocalizedMessage` (a string, or a paraglide/i18next message fn).
+     */
+    confirm(message, opts = {}) {
+        return new Promise((resolve) => {
+            _confirms = [
+                ..._confirms,
+                {
+                    id: _nextId++,
+                    message,
+                    title: opts.title,
+                    // Labels left undefined fall back to `<FF_Config>` (then the built-in) at render.
+                    confirmLabel: opts.confirmLabel,
+                    cancelLabel: opts.cancelLabel,
+                    danger: opts.danger ?? false,
+                    resolve,
+                },
+            ];
+        });
+    },
+    /**
+     * Ask for a single text value. Resolves a `DialogResult<string>` - `{ ok: true, data }` with the
+     * (trimmed) value, or `{ ok: false }` if cancelled/dismissed. The `{ ok }` flag disambiguates
+     * "cancelled" from "submitted an empty string" (both would collapse to a falsy value otherwise).
+     * Rendered via the manager's `prompt` snippet, or a built-in default.
+     */
+    prompt(opts = {}) {
+        return new Promise((resolve) => {
+            _prompts = [
+                ..._prompts,
+                {
+                    id: _nextId++,
+                    title: opts.title,
+                    label: opts.label,
+                    placeholder: opts.placeholder,
+                    initial: opts.initial ?? '',
+                    // Labels left undefined fall back to `<FF_Config>` (then the built-in) at render.
+                    confirmLabel: opts.confirmLabel,
+                    cancelLabel: opts.cancelLabel,
+                    hint: opts.hint,
+                    resolve,
+                },
+            ];
+        });
+    },
+    /** Internal (manager): resolve a prompt with a value (or null to cancel). */
+    _resolvePrompt(id, value) {
+        const p = _prompts.find((x) => x.id === id);
+        if (!p)
+            return;
+        p.resolve(value === null ? { ok: false } : { ok: true, data: value });
+        _prompts = _prompts.filter((x) => x.id !== id);
+    },
+    /** Dismiss the topmost prompt (resolves `{ ok: false }`). */
+    dismissTopPrompt() {
+        const p = _prompts.at(-1);
+        if (!p)
+            return;
+        p.resolve({ ok: false });
+        _prompts = _prompts.filter((x) => x.id !== p.id);
+    },
+    /** Internal (manager): resolve a dialog with an explicit result. */
+    async _close(id, result) {
+        const d = _dialogs.find((x) => x.id === id);
+        if (!d)
+            return;
+        await tryClose(d, normaliseResult(result));
+    },
+    /** Internal (manager): dismiss a specific dialog (Esc / backdrop / close button) - honours `dismissible` + `allowClose`. */
+    async requestClose(id) {
+        const d = _dialogs.find((x) => x.id === id);
+        if (!d || !d.options.dismissible)
+            return;
+        await tryClose(d, { ok: false });
+    },
+    /** Internal (manager): resolve a confirm. */
+    _resolveConfirm(id, yes) {
+        const c = _confirms.find((x) => x.id === id);
+        if (!c)
+            return;
+        c.resolve(yes ? { ok: true, data: undefined } : { ok: false });
+        _confirms = _confirms.filter((x) => x.id !== id);
+    },
+    /** Dismiss the topmost dialog (honours `dismissible`). */
+    async dismissTop() {
+        const d = _dialogs.at(-1);
+        if (!d || !d.options.dismissible)
+            return;
+        await tryClose(d, { ok: false });
+    },
+    /** Dismiss the topmost confirm (resolves `{ ok: false }`). */
+    dismissTopConfirm() {
+        const c = _confirms.at(-1);
+        if (!c)
+            return;
+        c.resolve({ ok: false });
+        _confirms = _confirms.filter((x) => x.id !== c.id);
+    },
+    /** Force-close everything (e.g. on full-page navigation). All resolve `{ ok: false }`. */
+    closeAll() {
+        for (const d of _dialogs)
+            d.resolve({ ok: false });
+        for (const c of _confirms)
+            c.resolve({ ok: false });
+        for (const p of _prompts)
+            p.resolve({ ok: false });
+        _dialogs = [];
+        _confirms = [];
+        _prompts = [];
+    },
+};
+/**
+ * `use:ffAutofocus` - focus the first focusable element inside the node (after mount).
+ * Put it on your dialog panel so keyboard users land inside it.
+ */
+export function ffAutofocus(node) {
+    queueMicrotask(() => {
+        node
+            .querySelector('input, textarea, select, button, [tabindex]:not([tabindex="-1"])')
+            ?.focus();
+    });
+}
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/**
+ * `use:ffTrapFocus` - keep Tab / Shift+Tab cycling within `node` (a dialog panel) instead
+ * of escaping into the background. Put it on your panel alongside `ffAutofocus`. SSR-safe
+ * (the listener is only attached in the browser, where actions run).
+ */
+export function ffTrapFocus(node) {
+    function onKeydown(e) {
+        if (e.key !== 'Tab')
+            return;
+        const focusable = Array.from(node.querySelectorAll(FOCUSABLE)).filter((el) => el.offsetParent !== null || el === document.activeElement);
+        if (focusable.length === 0) {
+            // Nothing focusable inside: keep focus on the panel itself.
+            e.preventDefault();
+            node.focus();
+            return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey) {
+            if (active === first || !node.contains(active)) {
+                e.preventDefault();
+                last.focus();
+            }
+        }
+        else {
+            if (active === last || !node.contains(active)) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+    }
+    node.addEventListener('keydown', onKeydown);
+    return {
+        destroy() {
+            node.removeEventListener('keydown', onKeydown);
+        },
+    };
+}

package/esm/svelte/ff.svelte.d.ts

@@ -0,0 +1,294 @@
+import type { Snippet } from 'svelte';
+import { type ClassType, type EntityFilter, type EntityMetadata, type EntityOrderBy, type GroupByOptions, type GroupByResult, type MembersOnly, type MembersToInclude, type NumericKeys, type QueryOptions, type Repository } from 'remult';
+import type { LocalizedMessage } from '../core/FF_Validators.js';
+import { type DialogClose, type DialogOptions, type DialogResult } from './dialog.svelte.js';
+/**
+ * `ff` - the firstly reactive layer over a Remult entity, as Svelte runes. Two shapes:
+ *
+ *   ff(E).many(() => ({ where }), strategy?)  // list + editing draft + writes
+ *   ff(E).one(() => ({ where }))              // a single record bound to `item`
+ *
+ * `many`'s `strategy` is the fetch mode: 'paginate' (page + $count + more(), default), 'listen'
+ * (liveQuery, auto-updates), or 'load' (a static one-shot). The handle
+ * owns the list (`items`) AND the editing `draft`: `edit(id)` / `create()` / `cancel()`,
+ * argless `save()` / `remove()` act on the draft, `save(row)` / `remove(row)` target a row,
+ * and the list reconciles itself (load = sorted upsert, paginate = refresh, listen = liveQuery).
+ *
+ * The options getter is reactive: change `where` / `orderBy` / `enabled` / `pageSize` and the
+ * query re-runs (stale in-flight responses dropped; `listen` re-subscribes). `orderBy` defaults
+ * to the entity's `defaultOrderBy`. `enabled: false` skips the query (keeps the last result)
+ * until it flips true. Read SvelteKit load `data` through a `$derived`, never raw in the getter.
+ *
+ * `.meta` is kept on every handle (captions / permissions / fields). There is NO `.repo`:
+ * everything imperative goes through remult's `repo(E)` directly (`insert` / `findId` / `count` /
+ * `deleteMany` / ...). The reactive shapes build an `$effect`, so create them at component init;
+ * for a click handler / async fn use `repo(E)`. A failed write fills `error` and re-throws.
+ *
+ * Internals (FF_RepoHandle modes load/live/paginate/one, the `.syncs` link, reconcilers) are
+ * private to this module; `ff` exposes only `many` / `one`.
+ */
+/** The aggregate request shape - remult's `GroupByOptions` minus the grouping/paging keys. */
+export type AggregateOptions<Entity> = Omit<GroupByOptions<Entity, never, NumericKeys<Entity>[], NumericKeys<Entity>[], (keyof MembersOnly<Entity>)[], (keyof MembersOnly<Entity>)[], (keyof MembersOnly<Entity>)[]>, 'group' | 'orderBy' | 'where' | 'limit' | 'page'>;
+/**
+ * Remult `QueryOptions` plus the `aggregate` request shape. Exported for callers
+ * that build query options outside `ff` (e.g. a generic table component).
+ */
+export type QueryOptionsHelper<Entity> = QueryOptions<Entity> & {
+    aggregate?: AggregateOptions<Entity>;
+};
+export type FF_RepoOptions<Entity> = {
+    where?: EntityFilter<Entity>;
+    orderBy?: EntityOrderBy<Entity>;
+    /** paginate: rows per page (default 25). */
+    pageSize?: number;
+    /** find/one/live: cap the rows returned. No default - returns every matching row. */
+    limit?: number;
+    include?: MembersToInclude<Entity>;
+    /** When false, the query is skipped (last result kept) until it flips true. */
+    enabled?: boolean;
+    /** Aggregations to compute alongside the page (paginate mode only). `$count` is always returned. */
+    aggregate?: AggregateOptions<Entity>;
+};
+type Getter<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = () => O;
+/** `$count` is always present; richer keys appear only for the requested `aggregate`. */
+type EmptyAggregateResult = {
+    $count: number;
+};
+/** The typed aggregate result for a given options object (paginate mode). */
+type ExtractAggregateResult<Entity, O extends FF_RepoOptions<Entity>> = O extends {
+    aggregate: infer A;
+} ? GroupByResult<Entity, never, A extends {
+    sum?: infer S;
+} ? (S extends NumericKeys<Entity>[] ? S : never) : never, A extends {
+    avg?: infer V;
+} ? (V extends NumericKeys<Entity>[] ? V : never) : never, A extends {
+    min?: infer M;
+} ? (M extends NumericKeys<Entity>[] ? M : never) : never, A extends {
+    max?: infer X;
+} ? (X extends NumericKeys<Entity>[] ? X : never) : never, A extends {
+    distinctCount?: infer D;
+} ? D extends (keyof MembersOnly<Entity>)[] ? D : never : never> : EmptyAggregateResult;
+export type FF_RepoLoading = {
+    init: boolean;
+    fetching: boolean;
+    more: boolean;
+    saving: boolean;
+    deleting: boolean;
+};
+type Mode = 'live' | 'load' | 'paginate' | 'one';
+/**
+ * The reactive handle implementation (internal). `ff().one()` returns an Omit'd view of this
+ * (`FF_One`); `ff().many()` wraps a list handle + a `.syncs`-linked one in `FF_ManyHandle`
+ * (exposed as `FF_Many`). The per-mode aliases below stay internal to this module.
+ */
+declare class FF_RepoHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> {
+    #private;
+    items: Entity[];
+    /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
+    item: Entity | undefined;
+    loading: FF_RepoLoading;
+    error: string | undefined;
+    hasNextPage: boolean;
+    /** Aggregations for the whole query (paginate mode). `aggregates.$count` is the total row count. */
+    aggregates: ExtractAggregateResult<Entity, O> | undefined;
+    /** Any read or write currently in flight (init/fetching/more/saving/deleting). */
+    get isBusy(): boolean;
+    /** A write (insert/update/delete) in flight. */
+    get isWriting(): boolean;
+    constructor(r: Repository<Entity>, opts: Getter<Entity, O>, mode: Mode);
+    /** Re-run the current query (load/paginate/one), back to the first page. */
+    refresh(): Promise<void>;
+    /** Load and append the next page (paginate mode). */
+    more(): Promise<void>;
+    /**
+     * Run `fn` once - the first time a row exists (`items[0]`).
+     *
+     * The point: seed editable UI state from the latest row WITHOUT a live query
+     * clobbering in-progress edits. It fires a single time, on the first non-empty
+     * result, and never again - later ticks (an edit, a delete, a re-sort) are
+     * ignored. Empty snapshots are skipped (a liveQuery often emits one before the
+     * data lands; there is nothing to seed from an empty result).
+     *
+     * For pure derived state prefer `$derived`; reach for `onFirst` only when the
+     * seed must become independently editable (a draft the user then mutates).
+     *
+     * ```svelte
+     * const list = ff(Plan).many(() => ({ where: { ownerDid } }), 'listen')
+     * let draft = $state({ title: '' })
+     * list.onFirst((latest) => (draft.title = latest.title)) // seed once, then edit freely
+     * ```
+     */
+    onFirst(fn: (latest: Entity) => void): void;
+    /** Create a new unsaved entity into the `item` slot (for an edit form). */
+    create(...args: Parameters<Repository<Entity>['create']>): Entity;
+    /** Save the current `item` (from `one` / `create()`). To save a specific row, use remult `repo(E).save(row)`. */
+    save(): Promise<Entity>;
+    /** Delete the current `item`. To delete a specific row/id, use remult `repo(E).delete(idOrRow)`. */
+    delete(): Promise<void>;
+    /**
+     * Save a specific `row` through this list handle's loading/error machinery (mirrors the
+     * argless `save()`), then reconcile the list (sorted upsert / paginate refresh). Used by
+     * `FF_ManyHandle.save(target)` so a targeted write flips `loading.saving` and fills `error`.
+     */
+    saveRow(row: Entity): Promise<NonNullable<Entity>>;
+    /**
+     * Delete a specific `row` through this list handle's loading/error machinery (mirrors the
+     * argless `delete()`), then drop it from the list. Used by `FF_ManyHandle.remove(target)`.
+     */
+    deleteRow(row: Entity): Promise<void>;
+    /**
+     * Link this record handle (`one`) to one or more list handles. On `save()` /
+     * `delete()` the lists are reconciled (sorted upsert / remove) and share the
+     * write-loading flag, so the list area shows "busy" during the write too. A live
+     * list reconcile is a no-op (its liveQuery already syncs). Returns `this`.
+     */
+    syncs(...targets: Array<FF_RepoLoad<Entity> | FF_RepoPaginate<Entity> | FF_RepoLive<Entity>>): this;
+    /** Insert into `items` at `top` (default) / `bottom` / an index (`-1` = last). +1 to `$count`. */
+    addItem(item: Entity, options?: {
+        at?: 'top' | 'bottom' | number;
+    }): void;
+    /** Replace the row whose id matches `item`'s id (no `$count` change). */
+    updateItem(item: Entity): void;
+    /** Drop the matching row (pass an id or the item). -1 to `$count`. */
+    removeItem(idOrItem: Parameters<Repository<Entity>['delete']>[0]): void;
+    /**
+     * Insert-or-update `item` at its SORTED position (load mode), recomputing the index
+     * from this handle's `orderBy` plus the entity id as tiebreak. Paginate re-fetches
+     * (a row may belong to an unloaded page); live is a no-op (the liveQuery syncs).
+     */
+    reconcile(item: Entity): void;
+    /**
+     * The entity's remult metadata - the single escape hatch for everything not on
+     * this handle: permissions (`apiInsertAllowed()`, `apiUpdateAllowed(item)`,
+     * `apiDeleteAllowed(item)`, `apiReadAllowed`), `fields`, `idMetadata`, `options`,
+     * `key`. Reflects the current `remult.user`.
+     */
+    get meta(): EntityMetadata<Entity>;
+    /** Escape hatch to the underlying repo (count, findId, upsert, projections, ...). */
+    get repo(): Repository<Entity>;
+}
+/** load: one-shot list (`refresh()` to re-run) - a read+reconcile view. No paging/aggregates, and no `item`/`save`/`delete`/`create` (edit via `one`, write via remult `repo(E)`). */
+export type FF_RepoLoad<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates' | 'item' | 'save' | 'delete' | 'create' | 'syncs'>;
+/** live: reactive subscription, auto-updates - a read view. No refresh/paging/aggregates/reconcilers (the liveQuery does it), and no `item`/`save`/`delete`/`create`. */
+export type FF_RepoLive<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'refresh' | 'more' | 'hasNextPage' | 'aggregates' | 'addItem' | 'updateItem' | 'removeItem' | 'item' | 'save' | 'delete' | 'create' | 'reconcile' | 'syncs'>;
+/** paginate: `more()` / `hasNextPage` / `aggregates` - a read+reconcile view. No `onFirst` (paged ≠ latest), and no `item`/`save`/`delete`/`create`. */
+export type FF_RepoPaginate<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'onFirst' | 'item' | 'save' | 'delete' | 'create' | 'syncs'>;
+/** one: a single reactive record in `item`. No paging / aggregates / list reconcilers. */
+export type FF_RepoOne<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates' | 'addItem' | 'updateItem' | 'removeItem' | 'reconcile'>;
+/** The list strategy backing `many`. Maps `listen` → live mode internally. */
+export type ManyStrategy = 'load' | 'listen' | 'paginate';
+/**
+ * Style 1 - unified composite. One handle owning a list (load/listen/paginate) AND
+ * the current editing `draft`, pre-wired: the draft handle `.syncs(list)`, so saving
+ * or deleting reconciles the list (sorted upsert / remove) and loading/error are
+ * merged across both. Proves the styles share internals: this is just a list handle
+ * plus a `.syncs()`-linked `one` handle.
+ *
+ *   const t = ff(Task).many(() => ({ where }), 'load')
+ *   t.edit(row) / t.create() / t.save() / t.remove(row) / t.cancel()
+ *   markup reads t.items, t.draft, t.loading, t.isBusy, t.error
+ */
+declare class FF_ManyHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> {
+    #private;
+    constructor(r: Repository<Entity>, opts: Getter<Entity, O>, strategy: ManyStrategy);
+    get items(): Entity[];
+    get draft(): Entity | undefined;
+    set draft(v: Entity | undefined);
+    get error(): string | undefined;
+    get hasNextPage(): boolean;
+    get aggregates(): ExtractAggregateResult<Entity, O> | undefined;
+    /** Merged loading: list reads + draft writes. */
+    get loading(): FF_RepoLoading;
+    get isBusy(): boolean;
+    get isWriting(): boolean;
+    /**
+     * Load `row` into `draft` for editing. Pass the row itself (works with any PK,
+     * single or composite - the id is read off it).
+     *
+     * Default (no fetch): edits an isolated **clone** of `row` - instant, no flicker,
+     * and saving updates the original (the clone keeps remult's existing-row state).
+     * Cancelling just drops the clone, so the list row is untouched until save.
+     *
+     * `{ refetch: true }`: optimistic - put `row`'s structure into `draft` **immediately**
+     * (so a form renders at full size, no open-then-grow flicker), then re-read the row
+     * fresh from the data source and swap it in. The optimistic draft is marked as an
+     * **existing** row (rebuilt via json), so it works whether `row` is a tracked entity,
+     * a plain spread/`$state` object, or an id-only stub - and saving updates, never inserts.
+     * Use it when the list row may be stale or you only hold its id.
+     */
+    edit(row: Entity, opts?: {
+        refetch?: boolean;
+    }): void;
+    /** Start a blank `draft` (insert). */
+    create(...args: Parameters<Repository<Entity>['create']>): Entity;
+    /** Drop the draft / stop editing, and clear any pending error. */
+    cancel(): void;
+    /** Save `target` (any row) or, argless, the current `draft`; reconciles the list. */
+    save(target?: Entity): Promise<Entity>;
+    /** Delete `target` (any row) or, argless, the current `draft`; reconciles the list. */
+    remove(target?: Entity): Promise<void>;
+    /**
+     * Confirm, then remove `row`. Resolves `{ ok: true }` when removed, `{ ok: false }` when the
+     * user cancels OR the delete fails (a failure also fills `error` and, unless `toast: false`,
+     * shows `toast.fromError`). Never re-throws - safe for `onclick={() => list.confirmRemove(row)}`.
+     */
+    confirmRemove(row: Entity, opts?: {
+        message?: LocalizedMessage;
+        title?: LocalizedMessage;
+        confirmLabel?: LocalizedMessage;
+        cancelLabel?: LocalizedMessage;
+        /** Style the confirm as destructive. Default true (it's a delete). */
+        danger?: boolean;
+        /** Auto-show `toast.fromError` when the delete fails. Default true. */
+        toast?: boolean;
+    }): Promise<DialogResult<void>>;
+    /**
+     * Edit `row` in a dialog: seed `draft` (a clone, or `{ refetch: true }` to re-read fresh),
+     * open `body`, and always `cancel()` on close. The `body` snippet binds `draft` and calls
+     * `save()` itself (so a failed/validation save keeps the dialog open via `error`); this method
+     * owns only the seed + cleanup. Resolves the dialog's `DialogResult`.
+     */
+    editInDialog<T = unknown>(row: Entity, body: Snippet<[DialogClose<T>]>, opts?: DialogOptions & {
+        refetch?: boolean;
+    }): Promise<DialogResult<T>>;
+    /**
+     * Create in a dialog: start a blank `draft` (optionally seeded with `defaults`), open `body`,
+     * and always `cancel()` on close. The `body` binds `draft` and calls `save()` itself.
+     */
+    createInDialog<T = unknown>(body: Snippet<[DialogClose<T>]>, opts?: DialogOptions & {
+        defaults?: Parameters<Repository<Entity>['create']>[0];
+    }): Promise<DialogResult<T>>;
+    more(): Promise<void>;
+    refresh(): Promise<void>;
+    /**
+     * Seed editable state once, from the latest row (`items[0]`), the first time one
+     * lands - then never again, so a later live tick can't clobber an in-progress edit.
+     * Use it when the seed must become independently editable (a separate `$state` /
+     * `$bindable` the user then mutates), not the draft; for pure display prefer
+     * `$derived(handle.items[0])`. Delegates to the list handle (see `onFirst` there).
+     */
+    onFirst(fn: (latest: Entity) => void): void;
+    get meta(): EntityMetadata<Entity>;
+    get repo(): Repository<Entity>;
+}
+type StrictGetter<Entity, O extends FF_RepoOptions<Entity>> = () => O & Record<Exclude<keyof O, keyof FF_RepoOptions<Entity>>, never>;
+/** The `ff(E).many(...)` handle. The `paginate` strategy adds `more`/`hasNextPage`/`aggregates`/`$count`. */
+export type FF_Many<Entity, S extends ManyStrategy = 'paginate', O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_ManyHandle<Entity, O>, 'repo' | 'more' | 'hasNextPage' | 'aggregates'> & (S extends 'paginate' ? Pick<FF_ManyHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates'> : Record<never, never>);
+/** The `ff(E).one(...)` handle - a single reactive record in `item` (no list/repo/syncs). */
+export type FF_One<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoOne<Entity, O>, 'repo' | 'syncs'>;
+/** Builder from `ff(E)`: the two reactive shapes + `meta`. No `.repo` (use remult's `repo(E)`). */
+export type FF_Builder<Entity> = {
+    /** A crud composite (list + editing draft + writes). `strategy` picks the fetch (default `paginate`). */
+    many: <O extends FF_RepoOptions<Entity>, S extends ManyStrategy = 'paginate'>(opts: StrictGetter<Entity, O>, strategy?: S) => FF_Many<Entity, S, O>;
+    /** A single reactive record bound to `item`. */
+    one: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_One<Entity, O>;
+    /** The entity's remult metadata (captions, permissions, fields). */
+    readonly meta: EntityMetadata<Entity>;
+};
+/**
+ * `ff(E)` - the firstly reactive layer. `ff(E).many(getter, strategy?)` for a list+edit
+ * composite, `ff(E).one(getter)` for a single record. Everything imperative stays on
+ * remult's `repo(E)`.
+ */
+export declare function ff<Entity>(entity: ClassType<Entity>): FF_Builder<Entity>;
+export {};