firstly 0.5.0 → 0.6.0

package/esm/svelte/toast.d.ts

@@ -0,0 +1,59 @@
+import type { LocalizedMessage } from '../core/FF_Validators.js';
+export type ToastKind = 'success' | 'error' | 'info' | 'warning';
+export type ToastOptions = {
+    /**
+     * Bold heading shown above the description. Defaults per `kind`
+     * (e.g. `error` → "Error"). Pass to override.
+     */
+    title?: LocalizedMessage;
+    /** ms before auto-dismiss (passed through to svelte-sonner). */
+    duration?: number;
+    /** An action button. */
+    action?: {
+        label: LocalizedMessage;
+        onClick: () => void;
+    };
+};
+/** @internal Wired by `<FF_ToastManager>` to bridge `<FF_Config>` titles into this module. */
+export declare function _setToastTitleResolver(fn: (kind: ToastKind) => string): void;
+/** A svelte-sonner toast id. */
+type ToastId = string | number;
+/**
+ * firstly's toast - a `LocalizedMessage`-aware wrapper over svelte-sonner. Mount
+ * `<FF_ToastManager>` once (it renders sonner's `<Toaster>`).
+ *
+ * The first argument is the **description** (the body) and **may contain HTML**.
+ * A bold **title** sits above it; it defaults per kind (e.g. `error` → "Error") and
+ * can be overridden via `opts.title`. The per-kind defaults are localizable through
+ * `<FF_Config messages.toast>`. Labels accept a string OR a message function
+ * (paraglide/i18next), resolved at call time.
+ *
+ * ⚠️ **Security:** the description is rendered as **HTML**. Pass only trusted/sanitized
+ * content - never raw user input or network/error text, or you risk XSS. Use `toast.fromError`
+ * for thrown values: it HTML-escapes the extracted message for you. (The title is always plain text.)
+ *
+ * ```ts
+ * toast.error('Could not save the quote')                  // title: "Error"
+ * toast.success('Saved <b>3</b> rows', { title: 'Done 🎉' })
+ * toast.fromError(err)                                      // error toast from any thrown value
+ * ```
+ */
+export declare const toast: {
+    success: (description: LocalizedMessage, opts?: ToastOptions) => ToastId;
+    error: (description: LocalizedMessage, opts?: ToastOptions) => ToastId;
+    info: (description: LocalizedMessage, opts?: ToastOptions) => ToastId;
+    warning: (description: LocalizedMessage, opts?: ToastOptions) => ToastId;
+    /** Dispatch on `kind` (default `'info'`). */
+    show: (description: LocalizedMessage, opts?: ToastOptions & {
+        kind?: ToastKind;
+    }) => ToastId;
+    /**
+     * Pull a message out of any thrown value and show an error toast. The extracted message is
+     * HTML-escaped (error text is often server- or user-controlled), so it renders as plain text -
+     * unlike `toast.error`, which treats its argument as HTML.
+     */
+    fromError: (err: unknown, opts?: ToastOptions) => ToastId;
+    /** Dismiss a toast by id (or all, if omitted). */
+    dismiss: (id?: ToastId) => void;
+};
+export {};

package/esm/svelte/toast.js

@@ -0,0 +1,92 @@
+import { toast as sonner } from 'svelte-sonner';
+import { resolveMessage } from '../core/FF_Validators.js';
+import FF_ToastHtml from './FF_ToastHtml.svelte';
+/** Per-kind default heading, used when `opts.title` is omitted (and no manager wired one). */
+const DEFAULT_TITLE = {
+    success: 'Success',
+    error: 'Error',
+    info: 'Info',
+    warning: 'Warning',
+};
+/**
+ * Resolves the per-kind default title. `<FF_ToastManager>` overrides this (client-side) to read
+ * your `<FF_Config>` `messages.toast` titles, so defaults become locale-aware. Until then (or with
+ * no manager mounted) the English `DEFAULT_TITLE` above is used.
+ */
+let resolveDefaultTitle = (kind) => DEFAULT_TITLE[kind];
+/** @internal Wired by `<FF_ToastManager>` to bridge `<FF_Config>` titles into this module. */
+export function _setToastTitleResolver(fn) {
+    resolveDefaultTitle = fn;
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    if (err !== null && typeof err === 'object' && 'message' in err)
+        return String(err.message);
+    return String(err);
+}
+/** Entity-encode a string so it renders as literal text through the HTML description renderer. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Build a toast: the bold `title` (from `opts.title`, else the per-kind default)
+ * is svelte-sonner's main message; `description` is the body, rendered as HTML.
+ */
+function build(kind, description, opts) {
+    const title = opts?.title !== undefined ? resolveMessage(opts.title) : resolveDefaultTitle(kind);
+    return sonner[kind](title, {
+        // svelte-sonner renders a component description as `<Description {...componentProps} />`
+        description: FF_ToastHtml,
+        componentProps: { html: resolveMessage(description) },
+        duration: opts?.duration,
+        action: opts?.action
+            ? { label: resolveMessage(opts.action.label), onClick: opts.action.onClick }
+            : undefined,
+    });
+}
+/**
+ * firstly's toast - a `LocalizedMessage`-aware wrapper over svelte-sonner. Mount
+ * `<FF_ToastManager>` once (it renders sonner's `<Toaster>`).
+ *
+ * The first argument is the **description** (the body) and **may contain HTML**.
+ * A bold **title** sits above it; it defaults per kind (e.g. `error` → "Error") and
+ * can be overridden via `opts.title`. The per-kind defaults are localizable through
+ * `<FF_Config messages.toast>`. Labels accept a string OR a message function
+ * (paraglide/i18next), resolved at call time.
+ *
+ * ⚠️ **Security:** the description is rendered as **HTML**. Pass only trusted/sanitized
+ * content - never raw user input or network/error text, or you risk XSS. Use `toast.fromError`
+ * for thrown values: it HTML-escapes the extracted message for you. (The title is always plain text.)
+ *
+ * ```ts
+ * toast.error('Could not save the quote')                  // title: "Error"
+ * toast.success('Saved <b>3</b> rows', { title: 'Done 🎉' })
+ * toast.fromError(err)                                      // error toast from any thrown value
+ * ```
+ */
+export const toast = {
+    success: (description, opts) => build('success', description, opts),
+    error: (description, opts) => build('error', description, opts),
+    info: (description, opts) => build('info', description, opts),
+    warning: (description, opts) => build('warning', description, opts),
+    /** Dispatch on `kind` (default `'info'`). */
+    show: (description, opts) => build(opts?.kind ?? 'info', description, opts),
+    /**
+     * Pull a message out of any thrown value and show an error toast. The extracted message is
+     * HTML-escaped (error text is often server- or user-controlled), so it renders as plain text -
+     * unlike `toast.error`, which treats its argument as HTML.
+     */
+    fromError: (err, opts) => build('error', escapeHtml(errorMessage(err)), opts),
+    /** Dismiss a toast by id (or all, if omitted). */
+    dismiss: (id) => {
+        sonner.dismiss(id);
+    },
+};

package/esm/virtual/StateDemoEnum.js

@@ -29,7 +29,7 @@ let StateDemoEnum = class StateDemoEnum extends BaseEnum {
         caption: 'Delete',
         icon: {
             data: LibIcon_Delete,
-            class: 'text-error',
+            class: 'text-destructive',
         },
     });
     constructor(id, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",
@@ -38,10 +38,11 @@
     "cron": "4.4.0",
     "esm-env": "1.2.2",
     "nodemailer": "8.0.5",
+    "svelte-sonner": "1.1.1",
     "tailwind-merge": "3.5.0",
     "tailwindcss": "4.2.2",
-    "vite-plugin-kit-routes": "1.0.5",
-    "vite-plugin-stripper": "0.10.3"
+    "vite-plugin-kit-routes": "1.0.6",
+    "vite-plugin-stripper": "0.10.4"
   },
   "sideEffects": false,
   "exports": {

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

@@ -1,191 +0,0 @@
-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>;
-};
-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. 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;
-    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;
-    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>;
-    /**
-     * 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.
-     */
-    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;
-    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 {};