firstly 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # firstly
 
+## 0.5.0
+
+### Minor Changes
+
+- [#274](https://github.com/jycouet/firstly/pull/274) [`6114148`](https://github.com/jycouet/firstly/commit/61141482a06f0a006ae148f0645146c073a2fb3c) Thanks [@jycouet](https://github.com/jycouet)! - **BREAKING (svelte): `FF_Repo` class -> `ffRepo()` factory.** The reactive repo wrapper now takes a reactive options getter and a mode (`load` / `listen` / `paginate` / `one`), with built-in mutations (no-arg `save()`/`delete()` target the loaded `item`), client-side list reconcilers (`addItem`/`updateItem`/`removeItem`, with `addItem` positioning), `firstOnce`/`draft`, and permissions via `r.meta`. The old `new FF_Repo(E, { findOptions })` class is removed.
+
+  One rule: anything not under `.repo` is reactive; every imperative read/write lives on `.repo` (the plain remult repo). The builder no longer hoists `findFirst`/`findId`/`insert`/... - use `ffRepo(E).repo.*`.
+
+  Also new: `infiniteScroll` (svelte attachment, pairs with `paginate`), `stackHttpClient`/`withHeader` (core), `FF_Filter.containsWords` (multi-field search filter), `splitTrim` (formats), and exported types including the umbrella `FF_Repo` handle plus `FF_RepoBuilder`/`FF_RepoLoad`/`FF_RepoLive`/`FF_RepoPaginate`/`FF_RepoOne`/`QueryOptionsHelper`/`AggregateOptions`.
+
+  Migration (see `/docs/svelte/ff-repo`):
+  - `new FF_Repo(E, { findOptions: { where } })` -> `ffRepo(E).load(() => ({ where }))`
+  - `new FF_Repo(E, { queryOptions })` + `.query()/.queryMore()/.queryRefresh()` -> `ffRepo(E).paginate(() => ({ ... }))` + `.more()/.refresh()`
+  - `r.globalError` -> `r.error`
+  - `r.fields` -> `r.meta.fields`; `r.metadata.apiInsertAllowed()` -> `r.meta.apiInsertAllowed()`
+  - `repo(r.ent).update(...)` / `.insert(...)` -> `r.update(...)` / `r.insert(...)`
+  - `r.aggregates.$count` unchanged; `skipAutoFetch` -> `enabled: false`
+
+## 0.4.5
+
+### Patch Changes
+
+- [#270](https://github.com/jycouet/firstly/pull/270) [`ba5eec6`](https://github.com/jycouet/firstly/commit/ba5eec6b0099127c9b5424dd3fb44184b4c70b28) Thanks [@jycouet](https://github.com/jycouet)! - fix(core): add explicit return type to `FF_Entity` so its `.d.ts` is emitted.
+
+  The inferred return type referenced a non-portable remult internal, so svelte-package silently skipped generating `FF_Entity.d.ts`. Consumers using the published package got `FF_Entity` typed as `any`, which made every entity option callback (`saving`, `displayValue`, ...) implicitly `any`.
+
 ## 0.4.4
 
 ### Patch Changes

package/esm/core/FF_Entity.d.ts

@@ -0,0 +1,2 @@
+import { Entity, type EntityOptions } from 'remult';
+export declare function FF_Entity<entityType>(key: string, options?: EntityOptions<entityType extends new (...args: any) => any ? InstanceType<entityType> : entityType>): ReturnType<typeof Entity<entityType>>;

package/esm/core/FF_Filter.d.ts

@@ -1,7 +1,9 @@
 /**
- * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ * Filter helpers that build a remult `EntityFilter`.
  *
- * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ * `owner` / `ownerOr` are prefilters (for `apiPrefilter`, `backendPrefilter`) -
+ * pair with `FF_Allow` (the equivalent for `allowApi*` row checks). `containsWords`
+ * is a search-box helper (pairs with `ffRepo(...).load/paginate`).
  *
  * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
  * autocompletion and type-safety on the column name. Without a generic the
@@ -52,4 +54,17 @@ export declare const FF_Filter: {
         col?: keyof T & string;
         roles: string[];
     }) => any;
+    /**
+     * Build a search filter where every word must match (AND) and each word may
+     * match any of the given fields (OR), case-insensitive `$contains`. Word order
+     * and which field holds which word don't matter - handy for "NOM Prénom" search.
+     *
+     * @example
+     * ```ts
+     * const r = ffRepo(User).load(() => ({
+     *   where: FF_Filter.containsWords([repo(User).fields.name, repo(User).fields.sesa], q),
+     * }))
+     * ```
+     */
+    containsWords: <Entity>(fields: import("remult").FieldMetadata<unknown, Entity>[], search: string) => import("remult").EntityFilter<Entity>;
 };

package/esm/core/FF_Filter.js

@@ -1,8 +1,11 @@
 import { remult } from 'remult';
+import { containsWords } from './containsWords.js';
 /**
- * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ * Filter helpers that build a remult `EntityFilter`.
  *
- * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ * `owner` / `ownerOr` are prefilters (for `apiPrefilter`, `backendPrefilter`) -
+ * pair with `FF_Allow` (the equivalent for `allowApi*` row checks). `containsWords`
+ * is a search-box helper (pairs with `ffRepo(...).load/paginate`).
  *
  * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
  * autocompletion and type-safety on the column name. Without a generic the
@@ -54,4 +57,17 @@ export const FF_Filter = {
             return {};
         return { [col]: [remult.user?.id] };
     },
+    /**
+     * Build a search filter where every word must match (AND) and each word may
+     * match any of the given fields (OR), case-insensitive `$contains`. Word order
+     * and which field holds which word don't matter - handy for "NOM Prénom" search.
+     *
+     * @example
+     * ```ts
+     * const r = ffRepo(User).load(() => ({
+     *   where: FF_Filter.containsWords([repo(User).fields.name, repo(User).fields.sesa], q),
+     * }))
+     * ```
+     */
+    containsWords,
 };

package/esm/core/containsWords.d.ts

@@ -0,0 +1,13 @@
+import type { EntityFilter, FieldMetadata } from 'remult';
+/**
+ * Builds a filter where every word in `search` must match (AND), and each word
+ * may match any of the given fields (OR), using case-insensitive `$contains`.
+ *
+ * E.g. "dupont marie" over [name, sesa] =>
+ *   (name~dupont OR sesa~dupont) AND (name~marie OR sesa~marie)
+ *
+ * So word order and which field holds which word don't matter - handy for
+ * "NOM Prénom" style search across several columns. Pairs with `ffRepo`:
+ * `ffRepo(User).load(() => ({ where: containsWords([f.name, f.sesa], q) }))`.
+ */
+export declare const containsWords: <Entity>(fields: FieldMetadata<unknown, Entity>[], search: string) => EntityFilter<Entity>;

package/esm/core/containsWords.js

@@ -0,0 +1,27 @@
+/**
+ * Builds a filter where every word in `search` must match (AND), and each word
+ * may match any of the given fields (OR), using case-insensitive `$contains`.
+ *
+ * E.g. "dupont marie" over [name, sesa] =>
+ *   (name~dupont OR sesa~dupont) AND (name~marie OR sesa~marie)
+ *
+ * So word order and which field holds which word don't matter - handy for
+ * "NOM Prénom" style search across several columns. Pairs with `ffRepo`:
+ * `ffRepo(User).load(() => ({ where: containsWords([f.name, f.sesa], q) }))`.
+ */
+export const containsWords = (fields, search) => {
+    const words = (search ?? '').split(' ').filter((s) => s.length > 0);
+    if (words.length === 0 || fields.length === 0) {
+        return {};
+    }
+    if (fields.length === 1) {
+        return {
+            $and: words.map((s) => ({ [fields[0].key]: { $contains: s } })),
+        };
+    }
+    return {
+        $and: words.map((s) => ({
+            $or: fields.map((f) => ({ [f.key]: { $contains: s } })),
+        })),
+    };
+};

package/esm/core/httpClientStack.d.ts

@@ -0,0 +1,18 @@
+export type HttpClientFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type HttpClientMiddleware = (next: HttpClientFetch) => HttpClientFetch;
+/**
+ * Compose `fetch` middlewares into a single `fetch`-shaped function. Middlewares
+ * run outermost-first (the first argument wraps the rest). Useful to inject auth
+ * headers, correlation ids, retries, logging, ... around a base `fetch`.
+ *
+ * ```ts
+ * const client = stackHttpClient(
+ *   withHeader('x-correlation-id', () => crypto.randomUUID()),
+ *   withHeader('authorization', () => `Bearer ${token}`),
+ * )
+ * await client('/api/...')
+ * ```
+ */
+export declare function stackHttpClient(...middlewares: HttpClientMiddleware[]): HttpClientFetch;
+/** Middleware that sets a request header from `getValue()` when it returns a value. */
+export declare function withHeader(name: string, getValue: () => string | undefined | null): HttpClientMiddleware;

package/esm/core/httpClientStack.js

@@ -0,0 +1,26 @@
+/**
+ * Compose `fetch` middlewares into a single `fetch`-shaped function. Middlewares
+ * run outermost-first (the first argument wraps the rest). Useful to inject auth
+ * headers, correlation ids, retries, logging, ... around a base `fetch`.
+ *
+ * ```ts
+ * const client = stackHttpClient(
+ *   withHeader('x-correlation-id', () => crypto.randomUUID()),
+ *   withHeader('authorization', () => `Bearer ${token}`),
+ * )
+ * await client('/api/...')
+ * ```
+ */
+export function stackHttpClient(...middlewares) {
+    return middlewares.reduceRight((next, mw) => mw(next), (input, init) => fetch(input, init));
+}
+/** Middleware that sets a request header from `getValue()` when it returns a value. */
+export function withHeader(name, getValue) {
+    return (next) => async (input, init) => {
+        const headers = new Headers(init?.headers);
+        const value = getValue();
+        if (value)
+            headers.set(name, value);
+        return next(input, { ...init, headers });
+    };
+}

package/esm/formats/index.d.ts

@@ -1,4 +1,4 @@
 export { displayCurrency, displayCurrencyK, displayPercent, displayCurrencyWOSuffix, } from './numbers.js';
-export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, } from './strings.js';
+export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, splitTrim, } from './strings.js';
 export { offsetedToPlainDate, plainDateCompare, isBetween, dateISOToPlainDate } from './dates.js';
 export type { KitPlainDateRange } from './dates.js';

package/esm/formats/index.js

@@ -1,3 +1,3 @@
 export { displayCurrency, displayCurrencyK, displayPercent, displayCurrencyWOSuffix, } from './numbers.js';
-export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, } from './strings.js';
+export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, splitTrim, } from './strings.js';
 export { offsetedToPlainDate, plainDateCompare, isBetween, dateISOToPlainDate } from './dates.js';

package/esm/formats/strings.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Split a string into a flat list of trimmed, non-empty tokens. The default
+ * separator handles comma- and newline-separated input.
+ *
+ * `"a, b\n,c"` -> `["a", "b", "c"]`
+ */
+export declare const splitTrim: (input?: string | null, separator?: string | RegExp) => string[];
 export declare const formatNumber: (number: number, digitNumber?: number) => string;
 export declare function displayPhone(_entity: any, value: string | undefined): string;
 export declare const arrToStr: (arr: string | undefined | (string | undefined)[]) => string;

package/esm/formats/strings.js

@@ -1,3 +1,15 @@
+/** Default separator for `splitTrim`: any run of commas and/or newlines. */
+const COMMA_OR_NEWLINE = /[,\n]+/;
+/**
+ * Split a string into a flat list of trimmed, non-empty tokens. The default
+ * separator handles comma- and newline-separated input.
+ *
+ * `"a, b\n,c"` -> `["a", "b", "c"]`
+ */
+export const splitTrim = (input, separator = COMMA_OR_NEWLINE) => (input ?? '')
+    .split(separator)
+    .map((s) => s.trim())
+    .filter(Boolean);
 export const formatNumber = (number, digitNumber = 2) => {
     if (number === undefined || number === null || isNaN(number)) {
         const value = 0;

package/esm/index.d.ts

@@ -15,6 +15,8 @@ export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export type { ResolvedType, UnArray, RecursivePartial } from './core/types.js';
 export { tw } from './core/tailwind.js';
+export { stackHttpClient, withHeader } from './core/httpClientStack.js';
+export type { HttpClientFetch, HttpClientMiddleware } from './core/httpClientStack.js';
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';
 export { UIEntity } from './virtual/UIEntity.js';

package/esm/index.js

@@ -15,6 +15,7 @@ export { FF_Validators, createValidators } from './core/FF_Validators.js';
 export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export { tw } from './core/tailwind.js';
+export { stackHttpClient, withHeader } from './core/httpClientStack.js';
 // Misc primitives still exposed from the root.
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';

package/esm/svelte/FF_Repo.svelte.d.ts

@@ -1,18 +1,83 @@
-import { type ClassType, type FindOptions, type GroupByOptions, type GroupByResult, type MembersOnly, type NumericKeys, type QueryOptions, type Repository } from 'remult';
-type EmptyAggregateResult = {
-    $count: number;
+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';
+/**
+ * `ffRepo` - thin reactive wrapper around a Remult `repo`, exposing its results as
+ * Svelte runes. Pick the mode with a verb:
+ *
+ *   ffRepo(E).load(() => ({ where }))       // load  - one-shot list + refresh()
+ *   ffRepo(E).listen(() => ({ where }))     // live  - liveQuery, auto-updates
+ *   ffRepo(E).paginate(() => ({ where }))   // paginate - more() / hasNextPage / aggregates
+ *   ffRepo(E).one(() => ({ where }))        // one   - reactive single record in `item`
+ *
+ * Two surfaces, one rule: anything NOT under `.repo` is reactive (a verb returns a
+ * runes handle; that handle's writes sync its own state). Anything under `.repo` is
+ * the plain remult repo - imperative, returns Promises, touches no runes state.
+ *
+ * The options getter is reactive: change `where` (e.g. a search box), `orderBy`,
+ * `enabled`, etc. and the query re-runs - `listen` re-subscribes (the old
+ * subscription is torn down), `load`/`paginate`/`one` re-fetch and ignore any
+ * stale in-flight response. `orderBy` defaults to the entity's `defaultOrderBy`.
+ *
+ * Getter hygiene: read SvelteKit load `data` through a `$derived`
+ * (`const did = $derived(data.targetDid)`), never raw inside the getter. A derived
+ * only propagates on value change, so a parent layout load revalidating - e.g. an
+ * SP URL write re-running url-dependent loads on every filter - hands you a new
+ * `data` object but does NOT re-fetch unless the value actually changed; a real
+ * change (route param switch) still does. Reading `data.x` raw re-fetches on every
+ * revalidation (a duplicate request per filter).
+ *
+ * `enabled: false` skips the query entirely (keeps the last result) and runs it
+ * the moment it flips true - use it for search-min-length, tab visibility,
+ * dependent queries, or a manual button trigger.
+ *
+ * Mutations on a handle (`insert`/`update`/`save`/`delete`) flip `loading` and keep
+ * the result in sync - in `live` mode the liveQuery does it; in `load`/`paginate` a
+ * delete is removed locally and an insert/update triggers a keep-count re-fetch; in
+ * `one` any write re-fetches the single record. `save()`/`delete()` with no argument
+ * target the current `item` (pairs with `one`/`create()`). For a raw write that syncs
+ * nothing, use `.repo` (e.g. `ffRepo(E).repo.insert(...)`).
+ *
+ * The factory's return type is mode-specific, so e.g. `.more()` doesn't exist on
+ * a `listen()` handle. Methods also throw if reached via a cast in the wrong mode.
+ *
+ * Reactive vs imperative: the reactive verbs take a *getter* (`() => ({ ... })`) and
+ * return a runes handle; they build an `$effect`, so they must be created during
+ * component init. For a one-off read/write in a click handler / async fn (no runes
+ * context) go through `.repo` (plain remult): `ffRepo(E).repo.findFirst(where)`,
+ * `ffRepo(E).repo.findId(id)`, `ffRepo(E).repo.find(...)`.
+ *
+ * Tip: prefer `.paginate()` whenever you want a total - it returns `aggregates.$count`
+ * for free in the same request. `load`/`listen`/`one` don't count; for a one-off count
+ * use `ffRepo(E).repo.count(where)`.
+ */
+/** 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 `ffRepo` (e.g. a generic table component).
+ */
+export type QueryOptionsHelper<Entity> = QueryOptions<Entity> & {
+    aggregate?: AggregateOptions<Entity>;
 };
-type Loading = {
-    init: boolean;
-    fetching: boolean;
-    more: boolean;
-    saving: boolean;
-    deleting: boolean;
+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 QueryOptionsHelper<entityType> = QueryOptions<entityType> & {
-    aggregate?: Omit<GroupByOptions<entityType, never, NumericKeys<entityType>[], NumericKeys<entityType>[], (keyof MembersOnly<entityType>)[], (keyof MembersOnly<entityType>)[], (keyof MembersOnly<entityType>)[]>, 'group' | 'orderBy' | 'where' | 'limit' | 'page'>;
+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;
 };
-type ExtractAggregateResult<Entity, Options extends QueryOptionsHelper<Entity>> = Options extends {
+/** 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;
@@ -20,57 +85,107 @@ type ExtractAggregateResult<Entity, Options extends QueryOptionsHelper<Entity>>
     avg?: infer V;
 } ? (V extends NumericKeys<Entity>[] ? V : never) : never, A extends {
     min?: infer M;
-} ? (M extends (keyof MembersOnly<Entity>)[] ? M : never) : never, A extends {
+} ? (M extends NumericKeys<Entity>[] ? M : never) : never, A extends {
     max?: infer X;
-} ? (X extends (keyof MembersOnly<Entity>)[] ? X : never) : never, A extends {
+} ? (X extends NumericKeys<Entity>[] ? X : never) : never, A extends {
     distinctCount?: infer D;
 } ? D extends (keyof MembersOnly<Entity>)[] ? D : never : never> : EmptyAggregateResult;
-export declare class FF_Repo<Entity, QueryOptions extends QueryOptionsHelper<Entity> = QueryOptionsHelper<Entity>> {
+export type FF_RepoLoading = {
+    init: boolean;
+    fetching: boolean;
+    more: boolean;
+    saving: boolean;
+    deleting: boolean;
+};
+type Mode = 'live' | 'load' | 'paginate' | 'one';
+/**
+ * The reactive handle implementation. Not exported directly - consumers use a per-mode
+ * alias (`FF_RepoLoad`/`FF_RepoLive`/`FF_RepoPaginate`/`FF_RepoOne`) or the umbrella
+ * union `FF_Repo` (any mode). Each verb returns the Omit'd per-mode view of this.
+ */
+declare class FF_RepoHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> {
     #private;
-    ent: ClassType<Entity>;
-    fields: Repository<Entity>['fields'];
-    metadata: Repository<Entity>['metadata'];
-    loading: Loading;
-    items: Entity[] | undefined;
-    aggregates: ExtractAggregateResult<Entity, QueryOptions> | undefined;
-    hasNextPage: boolean | undefined;
+    items: Entity[];
+    /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
     item: Entity | undefined;
-    globalError: string | undefined;
-    private loadingEnd;
-    constructor(ent: ClassType<Entity>, o?: ({
-        findOptions?: FindOptions<Entity> & {
-            skipAutoFetch?: boolean;
-        };
-        queryOptions?: never;
-    } | {
-        findOptions?: never;
-        queryOptions?: QueryOptions & {
-            skipAutoFetch?: boolean;
-        };
-    }) & {
-        item?: Entity;
-    });
-    find(options: FindOptions<Entity>): Promise<Entity[] | undefined>;
-    query(options: Pick<QueryOptionsHelper<Entity>, 'where' | 'orderBy'>): Promise<{
-        items: Entity[];
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | undefined>;
-    queryMore(): Promise<{
-        items: Entity[] | undefined;
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | 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;
+    first: Entity | null;
+    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>;
     /**
-     * Refresh query keeping current items count (BIG refresh)
-     * Useful after edit/delete to stay at current scroll position
+     * Run `fn` once, the first time a row is known (first non-null `first`).
+     * Never fires while the result is empty - so it's robust to liveQuery emitting
+     * an empty snapshot before the data lands. Nothing to seed from an empty result.
      */
-    queryRefresh(options: Pick<QueryOptionsHelper<Entity>, 'where' | 'orderBy'>): Promise<{
-        items: Entity[];
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | undefined>;
+    firstOnce(fn: (latest: Entity) => void): void;
+    /** Reactive, bindable editor state seeded once from the latest row. */
+    draft<D extends Record<string, unknown>>(seed: (latest: Entity | null) => D): D;
+    /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args: Parameters<Repository<Entity>['create']>): Entity;
-    delete(...args: Parameters<Repository<Entity>['delete']>): Promise<undefined>;
+    insert(...args: Parameters<Repository<Entity>['insert']>): Promise<Entity>;
+    update(...args: Parameters<Repository<Entity>['update']>): Promise<Entity>;
+    /** Save. With no argument, saves the current `item` (e.g. a bound `one`/`create` form). */
+    save(...args: [] | Parameters<Repository<Entity>['save']>): Promise<Entity>;
+    /** Delete. With no argument, deletes the current `item`. */
+    delete(...args: [] | Parameters<Repository<Entity>['delete']>): Promise<void>;
+    deleteMany(...args: Parameters<Repository<Entity>['deleteMany']>): Promise<number>;
+    /** 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;
+    /**
+     * 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. No paging / aggregates. */
+export type FF_RepoLoad<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates'>;
+/** live: reactive subscription, auto-updates. No manual refresh / paging / aggregates / list reconcilers (the liveQuery does it). */
+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'>;
+/** paginate: `more()` / `hasNextPage` / `aggregates`. No `first`/`firstOnce`/`draft` (paged ≠ latest). */
+export type FF_RepoPaginate<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'first' | 'firstOnce' | 'draft'>;
+/** one: a single reactive record in `item` (+ `first`). 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'>;
+/**
+ * Umbrella handle type - any mode. Use for a component prop that accepts a
+ * `load`/`listen`/`paginate`/`one` handle (`r: FF_Repo<T>`). It exposes the surface
+ * common to every mode (`items`/`item`/`loading`/`error`/`meta`/`repo` + the writes);
+ * mode-specific members (`more`/`hasNextPage`/`aggregates`/`refresh`/`first`/`firstOnce`/
+ * `draft`/`addItem`/`updateItem`/`removeItem`) require the matching per-mode type.
+ */
+export type FF_Repo<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = FF_RepoLoad<Entity, O> | FF_RepoLive<Entity, O> | FF_RepoPaginate<Entity, O> | FF_RepoOne<Entity, O>;
+type StrictGetter<Entity, O extends FF_RepoOptions<Entity>> = () => O & Record<Exclude<keyof O, keyof FF_RepoOptions<Entity>>, never>;
+/**
+ * The builder returned by `ffRepo(E)`. Two surfaces only: the reactive verbs
+ * (`load`/`listen`/`paginate`/`one`), and `.repo` - the plain remult repo for every
+ * imperative read/write (`findFirst`, `findId`, `find`, `insert`, `update`, `save`,
+ * `delete`, `count`, `upsert`, ...). `.meta` is a shortcut to `repo.metadata`.
+ */
+export type FF_RepoBuilder<Entity> = {
+    load: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoLoad<Entity, O>;
+    listen: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoLive<Entity, O>;
+    paginate: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoPaginate<Entity, O>;
+    one: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoOne<Entity, O>;
+    /** The entity's remult metadata (permissions, fields, key). Shortcut to `repo.metadata`. */
+    readonly meta: EntityMetadata<Entity>;
+    /** The underlying remult repo - every imperative read/write lives here. */
+    readonly repo: Repository<Entity>;
+};
+export declare function ffRepo<Entity>(entity: ClassType<Entity>): FF_RepoBuilder<Entity>;
 export {};

package/esm/svelte/FF_Repo.svelte.js

@@ -1,193 +1,312 @@
 import { repo as remultRepo, } from 'remult';
-import { Log } from '@kitql/helpers';
-import { tryCatch, tryCatchSync } from '../core/tryCatch.js';
-export class FF_Repo {
-    ent;
+/**
+ * The reactive handle implementation. Not exported directly - consumers use a per-mode
+ * alias (`FF_RepoLoad`/`FF_RepoLive`/`FF_RepoPaginate`/`FF_RepoOne`) or the umbrella
+ * union `FF_Repo` (any mode). Each verb returns the Omit'd per-mode view of this.
+ */
+class FF_RepoHandle {
     #repo;
+    #opts;
+    #mode;
+    #defaultOrderBy;
     #paginator;
-    #findOptions;
-    #queryOptions;
-    fields;
-    metadata;
+    #seq = 0;
+    items = $state([]);
+    /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
+    item = $state(undefined);
     loading = $state({
-        init: false,
+        init: true,
         fetching: false,
         more: false,
         saving: false,
         deleting: false,
     });
-    items = $state(undefined);
+    error = $state(undefined);
+    hasNextPage = $state(false);
+    /** Aggregations for the whole query (paginate mode). `aggregates.$count` is the total row count. */
     aggregates = $state(undefined);
-    hasNextPage = $state(undefined);
-    item = $state(undefined);
-    // errors = $state<ErrorInfo<Entity> | undefined>(undefined)
-    globalError = $state(undefined);
-    loadingEnd = (toRet) => {
-        this.loading = {
-            init: false,
-            fetching: false,
-            more: false,
-            saving: false,
-            deleting: false,
-        };
-        return toRet;
-    };
-    constructor(ent, o) {
-        this.ent = ent;
-        this.#repo = remultRepo(ent);
-        this.fields = this.#repo.fields;
-        this.metadata = this.#repo.metadata;
-        this.#paginator = undefined;
-        this.#findOptions = o?.findOptions;
-        this.#queryOptions = o?.queryOptions;
-        this.item = o?.item;
-        if (o?.findOptions !== undefined && !o.findOptions.skipAutoFetch) {
-            this.loading.init = true;
-            this.find(o.findOptions);
-        }
-        else if (o?.queryOptions !== undefined && !o.queryOptions.skipAutoFetch) {
-            this.loading.init = true;
-            this.query(o.queryOptions);
-        }
-        else {
-            this.loadingEnd();
-        }
+    first = $derived(this.items[0] ?? null);
+    constructor(r, opts, mode) {
+        this.#repo = r;
+        this.#opts = opts;
+        this.#mode = mode;
+        this.#defaultOrderBy = r.metadata.options.defaultOrderBy;
+        $effect(() => {
+            const o = this.#resolve();
+            if (o.enabled === false) {
+                this.loading.init = false;
+                return;
+            }
+            if (mode === 'live') {
+                // Pass orderBy so liveQuery re-sorts incrementally-added rows too;
+                // without it a freshly inserted row is appended and `first` goes stale.
+                const unsub = this.#repo
+                    .liveQuery({ where: o.where, orderBy: o.orderBy, limit: o.limit, include: o.include })
+                    .subscribe({
+                    next: (info) => {
+                        this.items = info.items;
+                        this.loading.init = false;
+                    },
+                    error: (e) => {
+                        this.error = e instanceof Error ? e.message : String(e);
+                        this.loading.init = false;
+                    },
+                });
+                return () => unsub();
+            }
+            // load | paginate | one: (re)fetch; a newer opts() invalidates older responses.
+            void this.#load(o, ++this.#seq);
+        });
     }
-    async find(options) {
+    #resolve() {
+        const o = this.#opts();
+        return { ...o, orderBy: o.orderBy ?? this.#defaultOrderBy };
+    }
+    async #load(o, seq, keepCount) {
         this.loading.fetching = true;
-        const { data, error } = await tryCatch(this.#repo.find({
-            ...this.#findOptions,
-            ...options,
-        }));
-        if (error) {
-            this.globalError = error.message;
-            return this.loadingEnd();
+        this.error = undefined;
+        try {
+            if (this.#mode === 'paginate') {
+                // One request returns the page AND the aggregates ($count always, plus any
+                // requested): on the client REST proxy remult fetches both together. It sets
+                // `hasNextPage` from whether a full page came back (no count probe); `more()`
+                // then fetches the next page via a keyset cursor (orderBy + PK).
+                const p = await this.#repo
+                    .query({
+                    where: o.where,
+                    orderBy: o.orderBy,
+                    pageSize: keepCount ?? o.pageSize ?? 25,
+                    include: o.include,
+                    aggregate: { ...o.aggregate },
+                })
+                    .paginator();
+                if (seq !== this.#seq)
+                    return;
+                this.#paginator = p;
+                this.items = p.items;
+                this.hasNextPage = p.hasNextPage;
+                // `aggregates` is only on the paginator type when the aggregate is non-empty,
+                // but remult returns `$count` for the empty case too - so read it through a cast.
+                this.aggregates = p.aggregates;
+            }
+            else if (this.#mode === 'one') {
+                const found = await this.#repo.findFirst(o.where, {
+                    orderBy: o.orderBy,
+                    include: o.include,
+                });
+                if (seq !== this.#seq)
+                    return;
+                this.item = found ?? undefined;
+                this.items = found ? [found] : [];
+            }
+            else {
+                const items = await this.#repo.find({
+                    where: o.where,
+                    orderBy: o.orderBy,
+                    limit: o.limit,
+                    include: o.include,
+                });
+                if (seq !== this.#seq)
+                    return;
+                this.items = items;
+            }
         }
-        this.items = data;
-        return this.loadingEnd(data);
-    }
-    async query(options) {
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            init: this.items === undefined,
-        };
-        // REMULT P1: add test for dynamic orderBy in remult
-        //            Looks like only the default orderby of the entity is working
-        const { data: queryResult, error: queryResultError } = tryCatchSync(() => this.#repo.query({
-            pageSize: 2,
-            ...this.#queryOptions,
-            ...options,
-            // Yes, we always want to aggregate to get at least the $count!
-            // And empty object is giving us that
-            aggregate: {
-                ...this.#queryOptions?.aggregate,
-            },
-        }));
-        if (queryResultError) {
-            this.globalError = queryResultError.message;
-            return this.loadingEnd();
+        catch (e) {
+            if (seq === this.#seq)
+                this.error = e instanceof Error ? e.message : String(e);
         }
-        const { data: paginator, error: paginatorError } = await tryCatch(queryResult.paginator());
-        if (paginatorError) {
-            this.globalError = paginatorError.message;
-            return this.loadingEnd();
+        finally {
+            if (seq === this.#seq) {
+                this.loading.init = false;
+                this.loading.fetching = false;
+            }
         }
-        this.#paginator = paginator;
-        this.items = this.#paginator.items;
-        // @ts-expect-error - We know the structure will match due to how we define the types
-        this.aggregates = this.#paginator.aggregates;
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
-        });
     }
-    async queryMore() {
-        if (this.#paginator === undefined) {
-            new Log('FF_Repo').error('No paginator found');
-            return undefined;
-        }
-        if (this.loading.more) {
-            // already in progress...
-            return undefined;
+    /** Re-run the current query (load/paginate/one), back to the first page. */
+    async refresh() {
+        if (this.#mode === 'live')
+            throw new Error('FF_Repo: refresh() is not available in live mode');
+        await this.#load(this.#resolve(), ++this.#seq);
+    }
+    /** Load and append the next page (paginate mode). */
+    async more() {
+        if (this.#mode !== 'paginate')
+            throw new Error('FF_Repo: more() requires paginate mode');
+        if (!this.#paginator || this.loading.more || !this.hasNextPage)
+            return;
+        this.loading.more = true;
+        try {
+            const next = await this.#paginator.nextPage();
+            this.#paginator = next;
+            this.items = [...this.items, ...next.items];
+            this.hasNextPage = next.hasNextPage;
         }
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            more: true,
-        };
-        const { data: nextPage, error: nextPageError } = await tryCatch(this.#paginator.nextPage());
-        if (nextPageError) {
-            this.globalError = nextPageError.message;
-            return this.loadingEnd();
+        finally {
+            this.loading.more = false;
         }
-        this.#paginator = nextPage;
-        this.items?.push(...nextPage.items);
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
-        });
     }
     /**
-     * Refresh query keeping current items count (BIG refresh)
-     * Useful after edit/delete to stay at current scroll position
+     * Run `fn` once, the first time a row is known (first non-null `first`).
+     * Never fires while the result is empty - so it's robust to liveQuery emitting
+     * an empty snapshot before the data lands. Nothing to seed from an empty result.
      */
-    async queryRefresh(options) {
-        const currentCount = this.items?.length ?? this.#queryOptions?.pageSize ?? 25;
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            init: this.items === undefined,
-        };
-        const { data: queryResult, error: queryResultError } = tryCatchSync(() => this.#repo.query({
-            ...this.#queryOptions,
-            ...options,
-            pageSize: currentCount,
-            aggregate: {
-                ...this.#queryOptions?.aggregate,
-            },
-        }));
-        if (queryResultError) {
-            this.globalError = queryResultError.message;
-            return this.loadingEnd();
-        }
-        const { data: paginator, error: paginatorError } = await tryCatch(queryResult.paginator());
-        if (paginatorError) {
-            this.globalError = paginatorError.message;
-            return this.loadingEnd();
-        }
-        this.#paginator = paginator;
-        this.items = this.#paginator.items;
-        // @ts-expect-error - We know the structure will match due to how we define the types
-        this.aggregates = this.#paginator.aggregates;
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
+    firstOnce(fn) {
+        let done = false;
+        $effect(() => {
+            if (done)
+                return;
+            const latest = this.first;
+            if (latest == null)
+                return;
+            fn(latest);
+            done = true;
         });
     }
+    /** Reactive, bindable editor state seeded once from the latest row. */
+    draft(seed) {
+        const values = $state(seed(null));
+        this.firstOnce((latest) => Object.assign(values, seed(latest)));
+        return values;
+    }
+    /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args) {
         this.item = this.#repo.create(...args);
         return this.item;
     }
-    async delete(...args) {
-        this.loading.deleting = true;
-        await this.#repo.delete(...args);
-        // REMULT P4: return the deleted item ?
-        if (typeof args[0] === 'string') {
-            this.items = this.items?.filter((i) => this.metadata.idMetadata.getId(i) !== args[0]);
+    // Mutations: run `op`, then the post-write sync on SUCCESS only (a failed write
+    // leaves the result untouched). On failure we fill `error` AND re-throw - the
+    // caller still gets the rejection (not silenced); `error` is for a reactive
+    // UI that wants it. `finally` only flips `loading` (no `await`, which would
+    // mask the original error).
+    async #write(flag, op, after) {
+        this.loading[flag] = true;
+        this.error = undefined;
+        try {
+            const res = await op();
+            await after();
+            return res;
         }
-        else {
-            this.items = this.items?.filter((i) => this.metadata.idMetadata.getId(i) !== this.metadata.idMetadata.getId(args[0]));
+        catch (e) {
+            this.error = e instanceof Error ? e.message : String(e);
+            throw e;
         }
-        if (this.aggregates) {
-            this.aggregates.$count = this.aggregates.$count - 1;
+        finally {
+            this.loading[flag] = false;
         }
-        return this.loadingEnd();
     }
+    insert(...args) {
+        return this.#write('saving', () => this.#repo.insert(...args), () => this.#resync());
+    }
+    update(...args) {
+        return this.#write('saving', () => this.#repo.update(...args), () => this.#resync());
+    }
+    /** Save. With no argument, saves the current `item` (e.g. a bound `one`/`create` form). */
+    save(...args) {
+        return this.#write('saving', () => this.#repo.save(...(args.length ? args : [this.#requireItem()])), () => this.#resync());
+    }
+    /** Delete. With no argument, deletes the current `item`. */
+    delete(...args) {
+        let target;
+        return this.#write('deleting', () => {
+            const a = (args.length ? args : [this.#requireItem()]);
+            target = a[0];
+            return this.#repo.delete(...a);
+        }, () => {
+            // live: liveQuery removes it. one: re-fetch (likely empty now).
+            // load/paginate: drop it locally (no refetch).
+            if (this.#mode === 'live')
+                return;
+            if (this.#mode === 'one')
+                return this.#resync();
+            this.#removeLocal(target);
+        });
+    }
+    /** The current `item` (or throw) - backs the no-arg `save()`/`delete()` forms. */
+    #requireItem() {
+        if (this.item === undefined)
+            throw new Error('FF_Repo: no `item` to save/delete - pass an explicit argument, or load one first (`one` mode or `create()`).');
+        return this.item;
+    }
+    deleteMany(...args) {
+        return this.#write('deleting', () => this.#repo.deleteMany(...args), () => this.#resync());
+    }
+    // Client-side list reconcilers (no server I/O) - reflect a change you made
+    // elsewhere (e.g. via `.repo`) in the reactive `items`. `load`/`paginate` only;
+    // `listen` reconciles itself via the liveQuery. `add`/`remove` also adjust
+    // `aggregates.$count` (not the other aggregates). For authoritative state, call
+    // `refresh()` (it re-pulls and, for paginate, resets to the first page).
+    /** Insert into `items` at `top` (default) / `bottom` / an index (`-1` = last). +1 to `$count`. */
+    addItem(item, options) {
+        const at = options?.at ?? 'top';
+        const list = this.items;
+        const idx = at === 'top'
+            ? 0
+            : at === 'bottom'
+                ? list.length
+                : at < 0
+                    ? Math.max(0, list.length + at + 1)
+                    : Math.min(at, list.length);
+        this.items = [...list.slice(0, idx), item, ...list.slice(idx)];
+        if (this.aggregates)
+            this.aggregates.$count += 1;
+    }
+    /** Replace the row whose id matches `item`'s id (no `$count` change). */
+    updateItem(item) {
+        const id = this.#repo.metadata.idMetadata.getId(item);
+        this.items = this.items.map((x) => (this.#repo.metadata.idMetadata.getId(x) === id ? item : x));
+    }
+    /** Drop the matching row (pass an id or the item). -1 to `$count`. */
+    removeItem(idOrItem) {
+        this.#removeLocal(idOrItem);
+    }
+    #removeLocal(idOrItem) {
+        const id = idOrItem != null && typeof idOrItem === 'object'
+            ? this.#repo.metadata.idMetadata.getId(idOrItem)
+            : idOrItem;
+        this.items = this.items.filter((i) => this.#repo.metadata.idMetadata.getId(i) !== id);
+        if (this.aggregates)
+            this.aggregates.$count = Math.max(0, this.aggregates.$count - 1);
+    }
+    /** After insert/update (or a `one` delete) in a non-live mode, re-fetch keeping the current count. */
+    async #resync() {
+        if (this.#mode === 'live')
+            return;
+        const keepCount = this.#mode === 'paginate' ? this.items.length || undefined : undefined;
+        await this.#load(this.#resolve(), ++this.#seq, keepCount);
+    }
+    /**
+     * 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() {
+        return this.#repo.metadata;
+    }
+    /** Escape hatch to the underlying repo (count, findId, upsert, projections, ...). */
+    get repo() {
+        return this.#repo;
+    }
+}
+export function ffRepo(entity) {
+    const r = remultRepo(entity);
+    const builder = {
+        load(o) {
+            return new FF_RepoHandle(r, o, 'load');
+        },
+        listen(o) {
+            return new FF_RepoHandle(r, o, 'live');
+        },
+        paginate(o) {
+            return new FF_RepoHandle(r, o, 'paginate');
+        },
+        one(o) {
+            return new FF_RepoHandle(r, o, 'one');
+        },
+        get meta() {
+            return r.metadata;
+        },
+        repo: r,
+    };
+    return builder;
 }

package/esm/svelte/index.d.ts

@@ -1,4 +1,7 @@
-export { FF_Repo } from './FF_Repo.svelte.js';
+export { ffRepo } from './FF_Repo.svelte.js';
+export type { FF_Repo, FF_RepoOptions, FF_RepoLoading, FF_RepoLoad, FF_RepoLive, FF_RepoPaginate, FF_RepoOne, FF_RepoBuilder, AggregateOptions, QueryOptionsHelper, } from './FF_Repo.svelte.js';
+export { infiniteScroll } from './infiniteScroll.js';
+export type { InfiniteScrollOptions } from './infiniteScroll.js';
 export { SP } from './class/SP.svelte';
 export type { ParamDefinition } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';

package/esm/svelte/index.js

@@ -1,4 +1,5 @@
-export { FF_Repo } from './FF_Repo.svelte.js';
+export { ffRepo } from './FF_Repo.svelte.js';
+export { infiniteScroll } from './infiniteScroll.js';
 export { SP } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';
 export { default as Icon } from './ui/Icon.svelte';

package/esm/svelte/infiniteScroll.d.ts

@@ -0,0 +1,31 @@
+import type { Attachment } from 'svelte/attachments';
+export type InfiniteScrollOptions = {
+    /** Are there more pages to load? */
+    hasMore: () => boolean;
+    /** Is a load already in flight? */
+    loading: () => boolean;
+    /** Load the next page. */
+    onMore: () => void;
+    /** Preload distance below the scroll viewport, in px (default 1200). */
+    rootMarginPx?: number;
+};
+/**
+ * Infinite-scroll attachment: put it on a bottom sentinel element and it calls
+ * `onMore()` when the sentinel nears the scroll container. The observer is rooted
+ * on the nearest scrollable ancestor, so it works when the app scrolls inside an
+ * inner div (not the window), and a `rootMarginPx` margin streams the next page in
+ * just before the sentinel shows. Guarded by `hasMore()`/`loading()`. Because it
+ * observes geometry it never misfires on mount: a full first page leaves the
+ * sentinel far below the root.
+ *
+ * Pairs with `ffRepo(E).paginate(...)`:
+ *
+ * ```svelte
+ * <div {@attach infiniteScroll({
+ *   hasMore: () => r.hasNextPage,
+ *   loading: () => r.loading.more,
+ *   onMore: () => r.more(),
+ * })}></div>
+ * ```
+ */
+export declare function infiniteScroll(opts: InfiniteScrollOptions): Attachment;

package/esm/svelte/infiniteScroll.js

@@ -0,0 +1,40 @@
+/** Nearest scrollable ancestor, or null (the document/window scrolls). */
+function scrollParent(el) {
+    let p = el.parentElement;
+    while (p && p !== document.body) {
+        const oy = getComputedStyle(p).overflowY;
+        if (oy === 'auto' || oy === 'scroll')
+            return p;
+        p = p.parentElement;
+    }
+    return null;
+}
+/**
+ * Infinite-scroll attachment: put it on a bottom sentinel element and it calls
+ * `onMore()` when the sentinel nears the scroll container. The observer is rooted
+ * on the nearest scrollable ancestor, so it works when the app scrolls inside an
+ * inner div (not the window), and a `rootMarginPx` margin streams the next page in
+ * just before the sentinel shows. Guarded by `hasMore()`/`loading()`. Because it
+ * observes geometry it never misfires on mount: a full first page leaves the
+ * sentinel far below the root.
+ *
+ * Pairs with `ffRepo(E).paginate(...)`:
+ *
+ * ```svelte
+ * <div {@attach infiniteScroll({
+ *   hasMore: () => r.hasNextPage,
+ *   loading: () => r.loading.more,
+ *   onMore: () => r.more(),
+ * })}></div>
+ * ```
+ */
+export function infiniteScroll(opts) {
+    return (node) => {
+        const io = new IntersectionObserver((entries) => {
+            if (entries[0]?.isIntersecting && opts.hasMore() && !opts.loading())
+                opts.onMore();
+        }, { root: scrollParent(node), rootMargin: `${opts.rootMarginPx ?? 1200}px 0px` });
+        io.observe(node);
+        return () => io.disconnect();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",