@llmnative/react 2.3.0 → 2.4.0

package/dist/types/src/I18n.d.ts

@@ -16,6 +16,8 @@ export interface I18nDict {
         goHome: string;
         /** The button that opens the menu on a small screen (the header of the scaffold). */
         openNavigation: string;
+        /** CR-129 — a read the database refused or lost. */
+        loadError: string;
     };
     auth: {
         signIn: string;

package/dist/types/src/components/widgets/grid-core/GridCore.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
 import { type RecordProps } from "../../../providers/data/DataProvider";
 import { type GridCoreProps } from "./types";
-declare function GridCore<TRecord extends RecordProps>({ records, recordId, sourcePath, columns, actions, form, editDeepLink, header, footer, view, views, sticky, wrapperClassName, cardClassName, bodyClassName, loading, title, before, after, sortable, pagination, selection, onRowClick, reorderable, onReorder, groupBy, searchable, filters, onSave, onDelete, onComplete, audit, onLoad, }: GridCoreProps<TRecord>): React.JSX.Element;
+declare function GridCore<TRecord extends RecordProps>({ records, recordId, sourcePath, columns, actions, form, editDeepLink, header, footer, view, views, sticky, wrapperClassName, cardClassName, bodyClassName, loading, title, before, after, sortable, pagination, selection, onRowClick, reorderable, onReorder, groupBy, searchable, filters, onSave, onDelete, onComplete, audit, onLoad, loadError, }: GridCoreProps<TRecord>): React.JSX.Element;
 export default GridCore;

package/dist/types/src/components/widgets/grid-core/types.d.ts

@@ -411,6 +411,8 @@ export type GridCoreProps<TRecord extends RecordProps> = GridBaseProps<TRecord>
     records: TRecord[];
     recordId: GridRecordKey<TRecord>;
     sourcePath?: string;
+    /** CR-129 — the reading of `path` failed: this message replaces the records (and their empty state). */
+    loadError?: React.ReactNode;
 };
 export type GridArrayProps<TRecord extends RecordProps> = GridBaseProps<TRecord> & {
     records: TRecord[];

package/dist/types/src/components/widgets/grid-core/useGridDBRecords.d.ts

@@ -1,9 +1,13 @@
-import { type DatabaseOptions, type RecordProps } from "../../../providers/data/DataProvider";
+import { type DatabaseOptions, type DataProviderError, type RecordProps } from "../../../providers/data/DataProvider";
 type UseGridDBRecordsArgs = {
     path?: string;
     where?: DatabaseOptions["where"];
     order?: DatabaseOptions["order"];
     fieldMap?: DatabaseOptions["fieldMap"];
 };
-declare function useGridDBRecords<TRecord extends RecordProps>({ path, where, order, fieldMap, }: UseGridDBRecordsArgs): TRecord[];
+/** The records of a `Grid` with `path`, live, and why they did not arrive (CR-129). */
+declare function useGridDBRecords<TRecord extends RecordProps>({ path, where, order, fieldMap, }: UseGridDBRecordsArgs): {
+    records: TRecord[];
+    error: DataProviderError | null;
+};
 export default useGridDBRecords;

package/dist/types/src/index.d.ts

@@ -15,7 +15,11 @@ export type { AppThemeProviderConfig, BuiltInThemeId, CardTheme, ColorScale, Gal
 export { AuthButton, useAccessToken, getAccessToken } from './auth';
 export * from './components/auth';
 export { useGlobalVars, getGlobalVars, setGlobalVars, removeGlobalVars } from './Global';
-export type { DataProviderAdapter, FieldValue, RecordProps, RecordArray, DatabaseOptions, DBConfig, ReadOptions, WhereClause, OrderClause, Condition } from './providers/data/DataProvider';
+export type { DataProviderAdapter, FieldValue, RecordProps, RecordArray, DatabaseOptions, DBConfig, ReadOptions, WhereClause, OrderClause, Condition, DataProviderErrorCode } from './providers/data/DataProvider';
+export { DataProviderError } from './providers/data/DataProvider';
+export { toDataProviderError } from './providers/data/query';
+export { useDataSubscription } from './providers/data/useDataSubscription';
+export type { DataSubscriptionOptions, DataSubscriptionState } from './providers/data/useDataSubscription';
 export type { OrderConfig, OrderDirection } from './libs/order';
 export { Order } from './libs/order';
 export { PromptUtils } from './libs/promptUtils';

package/dist/types/src/providers/data/DataProvider.d.ts

@@ -28,6 +28,10 @@ export type Condition = {
     gte?: RangeValue;
     nin?: ListValue;
     in?: ListValue;
+    /** CR-129 — the field is a list that holds this value (Firestore `array-contains`, Supabase `contains`). */
+    contains?: ScalarValue;
+    /** CR-129 — the field is a list that holds at least one of these values (Firestore `array-contains-any`, Supabase `overlaps`). */
+    containsAny?: ListValue;
 };
 export type WhereClause = {
     [field: string]: Condition | OperatorValue;
@@ -35,9 +39,32 @@ export type WhereClause = {
 export type OrderClause = {
     [field: string]: "asc" | "desc";
 };
+/**
+ * CR-129 — why a read failed, the same on every provider: the rules refused it (`permission-denied`), there
+ * is no session (`unauthenticated`), the query cannot run as written, e.g. a missing index or an operator the
+ * database refuses (`invalid-query`), the database cannot be reached (`unavailable`), or anything else.
+ */
+export type DataProviderErrorCode = 'permission-denied' | 'unauthenticated' | 'invalid-query' | 'unavailable' | 'unknown';
+/** CR-129 — a failed read, normalized from the error of the database (kept in `cause`). */
+export declare class DataProviderError extends Error {
+    readonly code: DataProviderErrorCode;
+    readonly path?: string;
+    readonly cause?: unknown;
+    constructor(code: DataProviderErrorCode, message: string, options?: {
+        path?: string;
+        cause?: unknown;
+    });
+}
 export interface DatabaseOptions {
     where?: WhereClause;
     order?: OrderClause;
+    /** CR-129 — at most this many records, after `where` and `order`. */
+    limit?: number;
+    /**
+     * CR-129 — called when the database refuses or loses the subscription. Without it the provider logs the
+     * error as before; with it the page can say why the data did not arrive.
+     */
+    onError?: (error: DataProviderError) => void;
     fieldMap?: Record<string, string>;
     onLoad?: (data: RecordObject) => RecordObject;
 }
@@ -47,6 +74,8 @@ export interface DBConfig extends DatabaseOptions {
 export interface ReadOptions {
     where?: WhereClause;
     order?: OrderClause;
+    /** CR-129 — at most this many records, after `where` and `order`. */
+    limit?: number;
     toArray?: boolean;
     exception?: boolean;
 }

package/dist/types/src/providers/data/firebase.d.ts

@@ -10,13 +10,13 @@ export declare class FirebaseDataProvider implements DataProviderAdapter {
     getConfigurationState(): ProviderConfigurationState;
     isConfigured(): boolean;
     readShallow: (path: string, exception?: boolean) => Promise<string[]>;
-    read: (path: string, { where, order, toArray, exception }?: ReadOptions) => Promise<any>;
+    read: (path: string, { where, order, limit, toArray, exception }?: ReadOptions) => Promise<any>;
     update: (path: string, data: object, exception?: boolean) => Promise<void>;
     set: (path: string, data: object, exception?: boolean) => Promise<void>;
     setChunks: (path: string, data: object, { chunkSize, purge, onProgress }?: SetChunksOptions) => Promise<void>;
     remove: (path: string, exception?: boolean) => Promise<void>;
     count: (path: string) => Promise<number>;
-    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, { where, order, fieldMap, onLoad }?: DatabaseOptions) => (() => void);
+    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, options?: DatabaseOptions) => (() => void);
 }
 declare const _default: FirebaseDataProvider;
 export default _default;

package/dist/types/src/providers/data/firestore.d.ts

@@ -23,7 +23,7 @@ export declare class FirestoreDataProvider implements DataProviderAdapter {
     dispose: () => Promise<void>;
     getConfigurationState(): ProviderConfigurationState;
     isConfigured(): boolean;
-    read: (path: string, { where, order, toArray, exception }?: ReadOptions) => Promise<any>;
+    read: (path: string, { where, order, limit, toArray, exception }?: ReadOptions) => Promise<any>;
     set: (path: string, data: object, exception?: boolean) => Promise<void>;
     update: (path: string, data: object, exception?: boolean) => Promise<void>;
     remove: (path: string, exception?: boolean) => Promise<void>;
@@ -39,7 +39,7 @@ export declare class FirestoreDataProvider implements DataProviderAdapter {
      * Firestore inequality filters on a field require the first orderBy() to be
      * on that same field. Pass `order` accordingly to avoid SDK errors.
      */
-    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, { where, order, fieldMap, onLoad }?: DatabaseOptions) => (() => void);
+    subscribe: <T extends RecordProps = RecordProps>(path: string | undefined, setRecords: (records: T[]) => void, options?: DatabaseOptions) => (() => void);
     /**
      * Returns the list of document IDs in a collection without loading document
      * data - the Firestore equivalent of RTDB's ?shallow=true REST endpoint.

package/dist/types/src/providers/data/query.d.ts

@@ -0,0 +1,14 @@
+import { DataProviderError, type Condition, type DatabaseOptions, type OperatorValue } from './DataProvider';
+/** A `where` value as a `Condition`: a list is `in`, a scalar is `eq`. */
+export declare function toCondition(raw: Condition | OperatorValue): Condition;
+/** Whether `value` (the field of a record) satisfies a condition of `where`. Unknown operators never match. */
+export declare function matchCondition(value: unknown, raw: Condition | OperatorValue): boolean;
+/** The first `limit` items (all of them without a valid limit). */
+export declare function applyLimit<T>(items: T[], limit?: number): T[];
+/** Any error of a database as a `DataProviderError` (an existing one is returned as it is). */
+export declare function toDataProviderError(error: unknown, path?: string): DataProviderError;
+/**
+ * Tells the page that a subscription failed: `options.onError` when it is given, else the console as the
+ * providers did before CR-129. Returns the normalized error.
+ */
+export declare function reportSubscribeError(options: Pick<DatabaseOptions, 'onError'> | undefined, error: unknown, path?: string): DataProviderError;

package/dist/types/src/providers/data/useDataSubscription.d.ts

@@ -0,0 +1,20 @@
+import type { DataProviderError, DatabaseOptions, RecordArray } from './DataProvider';
+export type DataSubscriptionOptions = Pick<DatabaseOptions, 'where' | 'order' | 'limit' | 'fieldMap'> & {
+    /** Read nothing (a page still waiting for an id): `loading` false, no records. */
+    skip?: boolean;
+    /** The name of a provider registered in `providers` (the default one without it). */
+    provider?: string;
+};
+export type DataSubscriptionState = {
+    records: RecordArray;
+    loading: boolean;
+    /** Why the data did not arrive (rules, session, query, network), the same on every provider. */
+    error: DataProviderError | null;
+};
+/**
+ * CR-129 — the records at `path`, live, from the data provider: `{ records, loading, error }`. `loading` is
+ * true until the first answer; a subscription the database refuses gives `error` instead of a list that never
+ * arrives. `where`, `order` and `limit` are compared by value, so a new object with the same content does not
+ * subscribe again.
+ */
+export declare function useDataSubscription(path: string | null | undefined, options?: DataSubscriptionOptions): DataSubscriptionState;

package/llms-full.txt

@@ -218,9 +218,9 @@ await oauth.getOrganizations(accessToken)   // [{ login, avatarUrl, role: 'admin
 
 ```ts
 // DataProviderAdapter
-read(path, options?) / set(path, data) / update(path, data) / remove(path)
-subscribe(path, callback: (records: RecordArray) => void): () => void
-count?(path, where?): Promise<number>
+read(path, { where?, order?, limit?, toArray?, exception? }) / set(path, data, exception?) / update(path, data, exception?) / remove(path, exception?)
+subscribe(path, callback: (records: RecordArray) => void, { where?, order?, limit?, fieldMap?, onLoad?, onError? }): () => void
+count?(path): Promise<number>
 
 // StorageProviderAdapter
 upload(file, path): Promise<string|undefined>
@@ -317,6 +317,35 @@ const creds = useCredentialsProvider()
 const token = await creds.getToken('https://www.googleapis.com/auth/solar')
 ```
 
+### Letture: filtri, `limit`, errori (CR-129)
+
+Gli stessi operatori e lo stesso contratto su ogni provider (`firestoreDb`, `supabaseDb`, `dbRealtime`, `mock`):
+l'adapter li traduce nei comandi del database, o li applica nel browser dove il database non li ha.
+
+| `where` | Significato | Firestore | Supabase | Realtime DB / Mock |
+|---|---|---|---|---|
+| `{ f: 'x' }` / `{ f: { eq } }` | uguale | `==` | `eq` | server sul campo di `order`, altrimenti browser |
+| `lt` `lte` `gt` `gte` | confronto | `<` … `>=` | `lt` … `gte` | idem |
+| `{ f: ['a','b'] }` / `in`, `nin` | uno dei valori / nessuno | `in` (≤30), `not-in` (≤10) | `in`, `not.in` | browser |
+| `contains: v` | il campo lista contiene `v` | `array-contains` | `contains` | browser |
+| `containsAny: [..]` | contiene almeno uno | `array-contains-any` (≤30) | `overlaps` | browser |
+
+`limit: n` (in `read` e `subscribe`) tiene i primi `n` dopo `where` e `order`: Firestore `limit()`, Supabase
+`.limit()`, Realtime Database `limitToFirst`/`limitToLast` (nel browser se restano filtri da applicare lì).
+
+Un'iscrizione che il database rifiuta (regole, sessione, indice mancante, rete) arriva a `onError` come
+`DataProviderError` con `code`: `permission-denied` | `unauthenticated` | `invalid-query` | `unavailable` |
+`unknown` (l'errore originale in `cause`). Senza `onError` il provider la scrive in console come prima.
+Un percorso di record (`/users/u1`) segue quel record su ogni provider.
+
+```ts
+const { records, loading, error } = useDataSubscription('/registro', { order: { at: 'desc' }, limit: 50 })
+// error?.code === 'permission-denied' → la pagina dice che non può leggere, invece di restare in caricamento
+db.subscribe('/posts', setRecords, { where: { tags: { contains: 'news' } }, limit: 20, onError: (e) => show(e.code) })
+```
+
+`Grid` con `path` mostra `common.loadError` al posto delle righe quando la lettura fallisce.
+
 ### Provider custom
 ```ts
 import { DataProviderAdapter, RecordArray } from '@llmnative/react'
@@ -1473,7 +1502,10 @@ type FieldValue   = string | number | boolean | null | undefined | Record<string
 type RecordArray  = RecordProps[]
 
 type OrderConfig  = { field: string; dir: 'asc' | 'desc' }
-type WhereClause  = { field: string; op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any'; value: unknown }
+type Condition    = { eq?, lt?, lte?, gt?, gte?, in?: list, nin?: list, contains?: scalar, containsAny?: list }
+type WhereClause  = { [field: string]: Condition | scalar | list }   // scalar = eq, list = in
+type OrderClause  = { [field: string]: 'asc' | 'desc' }
+class DataProviderError extends Error { code: 'permission-denied' | 'unauthenticated' | 'invalid-query' | 'unavailable' | 'unknown'; path?: string; cause?: unknown }
 
 interface UIProps {
   before?: React.ReactNode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnative/react",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "LLM-native React framework for deterministic UI generation. Data-driven by default, schema-driven optional. Ultra-low token consumption — built for AI agents, not just humans.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",