@_linked/react 1.2.1 → 1.3.0-next.20260605144237

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.3.0
+
+### Minor Changes
+
+- [#13](https://github.com/linked-cm/react/pull/13) [`f4688d5`](https://github.com/linked-cm/react/commit/f4688d5c04f97070318f58fceae61d0280562b27) Thanks [@flyon](https://github.com/flyon)! - Loader / errorElement resolution chain, `_refresh` on `linkedSetComponent`, factory overloads, `LinkedInfinityLoader` opt-in export.
+
+  **New: factory overloads.** `linkedComponent` and `linkedSetComponent` now accept three forms:
+
+  ```ts
+  linkedComponent(query, fn); // existing
+  linkedComponent(query, fn, { loader, errorElement }); // new — positional options
+  linkedComponent({ query, component, loader, errorElement }); // new — config object
+  ```
+
+  **New: loader resolution.** Resolves in order — per-instance `loader={<X/>}` prop → factory `options.loader` → `LinkedComponentDefaults.loader` → built-in `<svg class="ld-loader"/>`. Apps style `.ld-loader` (default styles ship in `@_linked/css`'s `loader.css`) or replace the element via `LinkedComponentDefaults.loader = <MyLoader />`.
+
+  **New: error handling.** Both wrappers now capture query errors and resolve an `errorElement` in the same chain (per-instance prop → factory option → global default → built-in `<svg class="ld-error"/>`). Pass the sentinel `'rethrow'` (per-instance or as a global default) to let an external `<ErrorBoundary>` handle the error instead.
+
+  **New: `_refresh` on `linkedSetComponent`.** Mirrors the `linkedComponent` API — `_refresh()` re-runs the query, `_refresh(updatedProps)` patches local query-result state for optimistic UI.
+
+  **New: `LinkedInfinityLoader`.** Opt-in branded loader exported from `@_linked/react`. Tree-shake-safe via the package's new `sideEffects` array form.
+
+  **Tree-shaking.** `package.json` now declares `"sideEffects": ["./lib/cjs/package.js", "./lib/esm/package.js"]` so bundlers drop unused named exports (the package-registration module is whitelisted).
+
+  No breaking changes — all existing `linkedComponent(query, fn)` and `linkedSetComponent(query, fn)` call sites work unchanged.
+
 ## 1.2.1
 
 ### Patch Changes

package/README.md

@@ -4,6 +4,8 @@ React bindings for `@_linked/core`.
 
 `@_linked/react` takes a Linked query from `@_linked/core`'s [Schema-Parameterized Query DSL](../core/README.md#schema-parameterized-query-dsl) and maps the top-level query result keys to props for a React component.
 
+> **Query API note.** Queries are built with `Shape.select(...)` which returns a `QueryBuilder`. A `QueryBuilder` is **lazy** — it only fires when you `await` it or pass it through `linkedComponent` / `linkedSetComponent`. The old `Shape.query(...)` builder name is gone; use `.select(...)` everywhere.
+
 This package provides:
 - `linkedComponent(...)`
 - `linkedSetComponent(...)`
@@ -30,11 +32,11 @@ import {
 
 ### `linkedComponent(...)`
 
-`linkedComponent(...)` wraps a React component with a Linked query. You pass a query built with `Shape.query(...)` (which prepares query execution), not `Shape.select(...)` (which executes immediately). At render time, when you pass `of={{id: ...}}`, the wrapper applies the prepared query to that subject and injects the query result keys as props into your component.
+`linkedComponent(...)` wraps a React component with a Linked query. You pass a query built with `Shape.select(...)` — the returned `QueryBuilder` is lazy and the wrapper fires it at render time. When you pass `of={{id: ...}}`, the wrapper applies the prepared query to that subject and injects the query result keys as props into your component.
 
 ```tsx
 const PersonCard = linkedComponent(
-  Person.query((p) => p.name),
+  Person.select((p) => p.name),
   ({name, source, _refresh}) => (
     <article>
       <h3>{name}</h3>
@@ -66,7 +68,7 @@ Example use case: optimistic UI after a mutation.
 
 ```tsx
 const PersonCard = linkedComponent(
-  Person.query((p) => [p.name, p.active]),
+  Person.select((p) => [p.name, p.active]),
   ({id, name, active, _refresh, title}) => (
     <div>
       <h4>{title}</h4>
@@ -95,7 +97,7 @@ Use `linkedSetComponent(...)` when you want to render a list of sources.
 
 ```tsx
 const NameList = linkedSetComponent(
-  Person.query((p) => p.name),
+  Person.select((p) => p.name),
   ({linkedData}) => (
     <ul>
       {(linkedData || []).map((person) => (
@@ -109,7 +111,7 @@ const NameList = linkedSetComponent(
 ### `linkedSetComponent(...)` (named data-prop format)
 
 ```tsx
-const personQuery = Person.query((p) => [p.name, p.hobby]);
+const personQuery = Person.select((p) => [p.name, p.hobby]);
 
 const NameList = linkedSetComponent({persons: personQuery}, ({persons}) => (
   <ul>
@@ -153,7 +155,7 @@ Example:
 import React from 'react';
 
 const PeopleList = linkedSetComponent(
-  Person.query((p) => [p.name]).limit(5),
+  Person.select((p) => [p.name]).limit(5),
   ({linkedData = [], query}) => {
     const [page, setPage] = React.useState(0);
 

package/lib/cjs/index.d.ts

@@ -4,3 +4,4 @@ export * from './utils/LinkedComponentClass.js';
 export * from './utils/Hooks.js';
 export * from './utils/ClassNames.js';
 export * from './utils/useQueryContext.js';
+export { LinkedInfinityLoader } from './loaders/LinkedInfinityLoader.js';

package/lib/cjs/index.js

@@ -14,10 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkedInfinityLoader = void 0;
 __exportStar(require("./package.js"), exports);
 __exportStar(require("./utils/LinkedComponent.js"), exports);
 __exportStar(require("./utils/LinkedComponentClass.js"), exports);
 __exportStar(require("./utils/Hooks.js"), exports);
 __exportStar(require("./utils/ClassNames.js"), exports);
 __exportStar(require("./utils/useQueryContext.js"), exports);
+var LinkedInfinityLoader_js_1 = require("./loaders/LinkedInfinityLoader.js");
+Object.defineProperty(exports, "LinkedInfinityLoader", { enumerable: true, get: function () { return LinkedInfinityLoader_js_1.LinkedInfinityLoader; } });
 //# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,6DAA2C;AAC3C,kEAAgD;AAChD,mDAAiC;AACjC,wDAAsC;AACtC,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,6DAA2C;AAC3C,kEAAgD;AAChD,mDAAiC;AACjC,wDAAsC;AACtC,6DAA2C;AAC3C,6EAAuE;AAA/D,+HAAA,oBAAoB,OAAA"}

package/lib/cjs/loaders/LinkedInfinityLoader.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+/**
+ * Branded infinity-symbol loader. Opt-in: set
+ * `LinkedComponentDefaults.loader = <LinkedInfinityLoader />` to use it as
+ * the app-wide loading element, or pass `<X loader={<LinkedInfinityLoader/>}/>`
+ * per-instance.
+ *
+ * Uses `stroke: currentColor` and an animated `stroke-dashoffset` that
+ * traces along the figure-8 path. Styled by `.ld-loader--infinity` in
+ * `@_linked/css/loader.css`.
+ */
+export declare function LinkedInfinityLoader(): React.ReactElement;

package/lib/cjs/loaders/LinkedInfinityLoader.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkedInfinityLoader = LinkedInfinityLoader;
+const react_1 = __importDefault(require("react"));
+/**
+ * Branded infinity-symbol loader. Opt-in: set
+ * `LinkedComponentDefaults.loader = <LinkedInfinityLoader />` to use it as
+ * the app-wide loading element, or pass `<X loader={<LinkedInfinityLoader/>}/>`
+ * per-instance.
+ *
+ * Uses `stroke: currentColor` and an animated `stroke-dashoffset` that
+ * traces along the figure-8 path. Styled by `.ld-loader--infinity` in
+ * `@_linked/css/loader.css`.
+ */
+function LinkedInfinityLoader() {
+    return (react_1.default.createElement("svg", { className: "ld-loader ld-loader--infinity", "aria-label": "Loading", role: "status", viewBox: "0 0 64 32", xmlns: "http://www.w3.org/2000/svg" },
+        react_1.default.createElement("path", { d: "M16 16 C 16 4, 30 4, 32 16 C 34 28, 48 28, 48 16 C 48 4, 34 4, 32 16 C 30 28, 16 28, 16 16 Z", fill: "none", stroke: "currentColor" })));
+}
+//# sourceMappingURL=LinkedInfinityLoader.js.map

package/lib/cjs/loaders/LinkedInfinityLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkedInfinityLoader.js","sourceRoot":"","sources":["../../../src/loaders/LinkedInfinityLoader.tsx"],"names":[],"mappings":";;;;;AAYA,oDAgBC;AA5BD,kDAA0B;AAE1B;;;;;;;;;GASG;AACH,SAAgB,oBAAoB;IAClC,OAAO,CACL,uCACE,SAAS,EAAC,+BAA+B,gBAC9B,SAAS,EACpB,IAAI,EAAC,QAAQ,EACb,OAAO,EAAC,WAAW,EACnB,KAAK,EAAC,4BAA4B;QAElC,wCACE,CAAC,EAAC,8FAA8F,EAChG,IAAI,EAAC,MAAM,EACX,MAAM,EAAC,cAAc,GACrB,CACE,CACP,CAAC;AACJ,CAAC"}

package/lib/cjs/package.d.ts

@@ -3,8 +3,21 @@ declare const linkedUtil: (constructor: any) => any, linkedOntology: (allFileExp
     <T extends typeof Shape>(constructor: T): void;
     <T extends typeof Shape>(config?: import("@_linked/core/utils/Package").ShapeConfig): (constructor: T) => void;
 }, registerPackageExport: (exportedObject: any) => void, registerPackageModule: (_module: any) => void, packageExports: any, getPackageShape: (name: string) => import("@_linked/core/shapes/Shape").ShapeConstructor | undefined;
-declare const linkedComponent: <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any, infer R, any> ? R : QueryType extends import("@_linked/core/queries/FieldSet.js").FieldSet<infer R_1, any> ? R_1 : QueryType>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").QueryResponseToResultType<Res, ShapeType>, ShapeType>) => import("./utils/LinkedComponent.js").LinkedComponent<CustomProps, ShapeType, Res>;
-declare const linkedSetComponent: <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> | {
-    [key: string]: import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any>;
-} = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = import("@_linked/core/queries/SelectQuery.js").ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableSetComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").GetCustomObjectKeys<QueryType> & import("@_linked/core/queries/SelectQuery.js").QueryControllerProps, ShapeType>) => import("./utils/LinkedComponent.js").LinkedSetComponent<CustomProps, ShapeType, Res>;
+declare const linkedComponent: {
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any, infer R, any> ? R : QueryType extends import("@_linked/core/queries/FieldSet.js").FieldSet<infer R_1, any> ? R_1 : QueryType>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").QueryResponseToResultType<Res, ShapeType>, ShapeType>): import("./utils/LinkedComponent.js").LinkedComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any, infer R, any> ? R : QueryType extends import("@_linked/core/queries/FieldSet.js").FieldSet<infer R_1, any> ? R_1 : QueryType>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").QueryResponseToResultType<Res, ShapeType>, ShapeType>, options: import("./utils/LinkedComponent.js").LinkedComponentOptions): import("./utils/LinkedComponent.js").LinkedComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any, infer R, any> ? R : QueryType extends import("@_linked/core/queries/FieldSet.js").FieldSet<infer R_1, any> ? R_1 : QueryType>(config: import("./utils/LinkedComponent.js").LinkedComponentConfig<QueryType, CustomProps & import("@_linked/core/queries/SelectQuery.js").QueryResponseToResultType<Res, ShapeType>, ShapeType>): import("./utils/LinkedComponent.js").LinkedComponent<CustomProps, ShapeType, Res>;
+};
+declare const linkedSetComponent: {
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> | {
+        [key: string]: import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = import("@_linked/core/queries/SelectQuery.js").ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableSetComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").GetCustomObjectKeys<QueryType> & import("@_linked/core/queries/SelectQuery.js").QueryControllerProps, ShapeType>): import("./utils/LinkedComponent.js").LinkedSetComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> | {
+        [key: string]: import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = import("@_linked/core/queries/SelectQuery.js").ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: import("./utils/LinkedComponent.js").LinkableSetComponent<CustomProps & import("@_linked/core/queries/SelectQuery.js").GetCustomObjectKeys<QueryType> & import("@_linked/core/queries/SelectQuery.js").QueryControllerProps, ShapeType>, options: import("./utils/LinkedComponent.js").LinkedComponentOptions): import("./utils/LinkedComponent.js").LinkedSetComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any> | {
+        [key: string]: import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = QueryType extends import("@_linked/core/queries/QueryBuilder.js").QueryBuilder<infer S extends Shape, any, any> ? S : never, Res = import("@_linked/core/queries/SelectQuery.js").ToQueryResultSet<QueryType>>(config: import("./utils/LinkedComponent.js").LinkedSetComponentConfig<QueryType, CustomProps & import("@_linked/core/queries/SelectQuery.js").GetCustomObjectKeys<QueryType> & import("@_linked/core/queries/SelectQuery.js").QueryControllerProps, ShapeType>): import("./utils/LinkedComponent.js").LinkedSetComponent<CustomProps, ShapeType, Res>;
+};
+export declare const linkedPackage: (packageName: any) => any;
 export { linkedComponent, linkedSetComponent, linkedShape, linkedUtil, linkedOntology, registerPackageExport, registerPackageModule, packageExports, getPackageShape, };

package/lib/cjs/package.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPackageShape = exports.packageExports = exports.registerPackageModule = exports.registerPackageExport = exports.linkedOntology = exports.linkedUtil = exports.linkedShape = exports.linkedSetComponent = exports.linkedComponent = void 0;
+exports.getPackageShape = exports.packageExports = exports.registerPackageModule = exports.registerPackageExport = exports.linkedOntology = exports.linkedUtil = exports.linkedShape = exports.linkedSetComponent = exports.linkedComponent = exports.linkedPackage = void 0;
 const CoreSet_1 = require("@_linked/core/collections/CoreSet");
 const Package_1 = require("@_linked/core/utils/Package");
 const LinkedComponent_js_1 = require("./utils/LinkedComponent.js");
@@ -30,4 +30,9 @@ const linkedComponent = (0, LinkedComponent_js_1.createLinkedComponentFn)(regist
 exports.linkedComponent = linkedComponent;
 const linkedSetComponent = (0, LinkedComponent_js_1.createLinkedSetComponentFn)(registerPackageExport, registerComponent);
 exports.linkedSetComponent = linkedSetComponent;
+const linkedPackage = (packageName) => {
+    return Object.assign({ linkedComponent,
+        linkedSetComponent }, (0, exports.linkedPackage)(packageName));
+};
+exports.linkedPackage = linkedPackage;
 //# sourceMappingURL=package.js.map

package/lib/cjs/package.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":";;;AAAA,+DAA0D;AAC1D,yDAA0D;AAE1D,mEAIoC;AAEpC,IAAI,iBAAiB,GAA0C,IAAI,GAAG,EAAE,CAAC;AAEzE,MAAM,EACJ,UAAU,EACV,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,eAAe,GAChB,GAAG,IAAA,uBAAa,EAAC,gBAAgB,CAAC,CAAC;AAoClC,gCAAU;AACV,wCAAc;AAFd,kCAAW;AAGX,sDAAqB;AACrB,sDAAqB;AACrB,wCAAc;AACd,0CAAe;AAvCjB,SAAS,iBAAiB,CAAC,iBAA4B,EAAE,KAAoB;IAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,EAAE,CAAC;YACtE,OAAO,CAAC,IAAI,CACV,aACG,iBAAyB,CAAC,WAAW,IAAK,iBAAyB,CAAC,IACvE,4BAA4B,CAC7B,CAAC;YACF,OAAO;QACT,CAAC;QACD,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,iBAAiB,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,iBAAO,EAAO,CAAC,CAAC;IACnD,CAAC;IAED,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,eAAe,GAAG,IAAA,4CAAuB,EAC7C,qBAAqB,EACrB,iBAAiB,CAClB,CAAC;AAQA,0CAAe;AANjB,MAAM,kBAAkB,GAAG,IAAA,+CAA0B,EACnD,qBAAqB,EACrB,iBAAiB,CAClB,CAAC;AAIA,gDAAkB"}
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":";;;AAAA,+DAA0D;AAC1D,yDAA+E;AAE/E,mEAIoC;AAEpC,IAAI,iBAAiB,GAA0C,IAAI,GAAG,EAAE,CAAC;AAEzE,MAAM,EACJ,UAAU,EACV,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,eAAe,GAChB,GAAG,IAAA,uBAAiB,EAAC,gBAAgB,CAAC,CAAC;AA2CtC,gCAAU;AACV,wCAAc;AAFd,kCAAW;AAGX,sDAAqB;AACrB,sDAAqB;AACrB,wCAAc;AACd,0CAAe;AA9CjB,SAAS,iBAAiB,CAAC,iBAA4B,EAAE,KAAoB;IAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,EAAE,CAAC;YACtE,OAAO,CAAC,IAAI,CACV,aACG,iBAAyB,CAAC,WAAW,IAAK,iBAAyB,CAAC,IACvE,4BAA4B,CAC7B,CAAC;YACF,OAAO;QACT,CAAC;QACD,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,iBAAiB,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,iBAAO,EAAO,CAAC,CAAC;IACnD,CAAC;IAED,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,eAAe,GAAG,IAAA,4CAAuB,EAC7C,qBAAqB,EACrB,iBAAiB,CAClB,CAAC;AAeA,0CAAe;AAbjB,MAAM,kBAAkB,GAAG,IAAA,+CAA0B,EACnD,qBAAqB,EACrB,iBAAiB,CAClB,CAAC;AAWA,gDAAkB;AAVb,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,EAAE;IAC3C,uBACE,eAAe;QACf,kBAAkB,IACf,IAAA,qBAAa,EAAC,WAAW,CAAC,EAC9B;AACH,CAAC,CAAA;AANY,QAAA,aAAa,iBAMzB"}

package/lib/cjs/utils/LinkedComponent.d.ts

@@ -36,6 +36,39 @@ export interface LinkedSetComponent<P, ShapeType extends Shape = Shape, Res = an
     shape?: typeof Shape;
 }
 export type LinkableComponent<P, ShapeType extends Shape = Shape> = React.FC<P & LinkedComponentProps<ShapeType>>;
+/**
+ * Options accepted by both `linkedComponent` and `linkedSetComponent` at
+ * definition time (3rd positional arg) and inside the config-object form.
+ * `loader` replaces the framework's default loading element; `errorElement`
+ * replaces the default error element. Pass the sentinel `'rethrow'` for
+ * `errorElement` to let the error propagate to an external `<ErrorBoundary>`.
+ */
+export interface LinkedComponentOptions {
+    loader?: React.ReactElement;
+    errorElement?: React.ReactElement | 'rethrow';
+}
+/**
+ * Config-object form of the factory:
+ *   linkedComponent({ query, component, loader, errorElement });
+ */
+export interface LinkedComponentConfig<Q, P, ShapeType extends Shape = Shape> extends LinkedComponentOptions {
+    query: Q;
+    component: LinkableComponent<P, ShapeType>;
+}
+export interface LinkedSetComponentConfig<Q, P, ShapeType extends Shape = Shape> extends LinkedComponentOptions {
+    query: Q;
+    component: LinkableSetComponent<P, ShapeType>;
+}
+/**
+ * App-global override for loader and errorElement. Setting either of these
+ * applies to every `linkedComponent` / `linkedSetComponent` that doesn't
+ * specify its own. Resolution order:
+ *   instance prop > definition options > LinkedComponentDefaults > built-in
+ */
+export declare const LinkedComponentDefaults: {
+    loader: React.ReactElement | undefined;
+    errorElement: React.ReactElement | 'rethrow' | undefined;
+};
 export type LinkableSetComponent<P, ShapeType extends Shape = Shape, DataResultType = any> = React.FC<LinkedSetComponentProps<ShapeType, DataResultType> & P>;
 export interface LinkedSetComponentProps<ShapeType extends Shape, DataResultType = any> extends LinkedComponentBaseProps<DataResultType>, QueryControllerProps {
     sources: ShapeSet<ShapeType>;
@@ -56,14 +89,28 @@ export interface LinkedComponentInputProps<ShapeType extends Shape = Shape> exte
 interface LinkedComponentInputBaseProps extends React.PropsWithChildren {
     className?: string | string[];
     style?: React.CSSProperties;
+    loader?: React.ReactElement;
+    errorElement?: React.ReactElement | 'rethrow';
 }
 export type LinkedSetComponentFactoryFn = <QueryType extends QueryBuilder<any> | {
     [key: string]: QueryBuilder<any>;
 } = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = ToQueryResultSet<QueryType>>(requiredData: QueryType, functionalComponent: LinkableSetComponent<CustomProps & GetCustomObjectKeys<QueryType> & QueryControllerProps, ShapeType, Res>) => LinkedSetComponent<CustomProps, ShapeType, Res>;
 export type LinkedComponentFactoryFn = <QueryType extends QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Response = GetQueryResponseType<QueryType>, ResultType = QueryResponseToResultType<Response, ShapeType>>(query: QueryType, functionalComponent: LinkableComponent<CustomProps & ResultType, ShapeType>) => LinkedComponent<CustomProps, ShapeType, ResultType>;
-export declare function createLinkedComponentFn(registerPackageExport: any, registerComponent: any): <QueryType extends QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = GetQueryResponseType<QueryType>>(query: QueryType, functionalComponent: LinkableComponent<CustomProps & QueryResponseToResultType<Res, ShapeType>, ShapeType>) => LinkedComponent<CustomProps, ShapeType, Res>;
-export declare function createLinkedSetComponentFn(registerPackageExport: any, registerComponent: any): <QueryType extends QueryBuilder<any> | {
-    [key: string]: QueryBuilder<any>;
-} = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: LinkableSetComponent<CustomProps & GetCustomObjectKeys<QueryType> & QueryControllerProps, ShapeType>) => LinkedSetComponent<CustomProps, ShapeType, Res>;
+export declare function createLinkedComponentFn(registerPackageExport: any, registerComponent: any): {
+    <QueryType extends QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = GetQueryResponseType<QueryType>>(query: QueryType, functionalComponent: LinkableComponent<CustomProps & QueryResponseToResultType<Res, ShapeType>, ShapeType>): LinkedComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = GetQueryResponseType<QueryType>>(query: QueryType, functionalComponent: LinkableComponent<CustomProps & QueryResponseToResultType<Res, ShapeType>, ShapeType>, options: LinkedComponentOptions): LinkedComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends QueryBuilder<any> = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = GetQueryResponseType<QueryType>>(config: LinkedComponentConfig<QueryType, CustomProps & QueryResponseToResultType<Res, ShapeType>, ShapeType>): LinkedComponent<CustomProps, ShapeType, Res>;
+};
+export declare function createLinkedSetComponentFn(registerPackageExport: any, registerComponent: any): {
+    <QueryType extends QueryBuilder<any> | {
+        [key: string]: QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: LinkableSetComponent<CustomProps & GetCustomObjectKeys<QueryType> & QueryControllerProps, ShapeType>): LinkedSetComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends QueryBuilder<any> | {
+        [key: string]: QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = ToQueryResultSet<QueryType>>(query: QueryType, functionalComponent: LinkableSetComponent<CustomProps & GetCustomObjectKeys<QueryType> & QueryControllerProps, ShapeType>, options: LinkedComponentOptions): LinkedSetComponent<CustomProps, ShapeType, Res>;
+    <QueryType extends QueryBuilder<any> | {
+        [key: string]: QueryBuilder<any>;
+    } = null, CustomProps = {}, ShapeType extends Shape = GetQueryShapeType<QueryType>, Res = ToQueryResultSet<QueryType>>(config: LinkedSetComponentConfig<QueryType, CustomProps & GetCustomObjectKeys<QueryType> & QueryControllerProps, ShapeType>): LinkedSetComponent<CustomProps, ShapeType, Res>;
+};
 export declare function getSourceFromInputProps(props: any, shapeClass: any): any;
 export {};

package/lib/cjs/utils/LinkedComponent.js

@@ -32,7 +32,19 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkedComponentDefaults = void 0;
 exports.createLinkedComponentFn = createLinkedComponentFn;
 exports.createLinkedSetComponentFn = createLinkedSetComponentFn;
 exports.getSourceFromInputProps = getSourceFromInputProps;
@@ -45,17 +57,39 @@ const Package_1 = require("@_linked/core/utils/Package");
 const ShapeSet_1 = require("@_linked/core/collections/ShapeSet");
 const NodeReference_1 = require("@_linked/core/utils/NodeReference");
 const ShapeClass_1 = require("@_linked/core/utils/ShapeClass");
+/**
+ * App-global override for loader and errorElement. Setting either of these
+ * applies to every `linkedComponent` / `linkedSetComponent` that doesn't
+ * specify its own. Resolution order:
+ *   instance prop > definition options > LinkedComponentDefaults > built-in
+ */
+exports.LinkedComponentDefaults = {
+    loader: undefined,
+    errorElement: undefined,
+};
 function createLinkedComponentFn(registerPackageExport, registerComponent) {
-    return function linkedComponent(query, functionalComponent) {
+    function linkedComponent(arg1, arg2, arg3) {
+        const normalized = normalizeFactoryArgs(arg1, arg2, arg3);
+        const query = normalized.query;
+        const functionalComponent = normalized.component;
+        const options = normalized.options;
         let [shapeClass, actualQuery] = processQuery(query);
         let _wrappedComponent = react_1.default.forwardRef((props, ref) => {
             var _a;
             let [queryResult, setQueryResult] = (0, react_1.useState)(undefined);
             let [loadingData, setLoadingData] = (0, react_1.useState)();
+            let [queryError, setQueryError] = (0, react_1.useState)(undefined);
             let linkedProps = getLinkedComponentProps(props, shapeClass);
             if (ref) {
                 linkedProps.ref = ref;
             }
+            // Strip framework-only input props before forwarding to the
+            // wrapped component — `loader` / `errorElement` aren't part of
+            // the user's render contract.
+            const instanceLoader = linkedProps.loader;
+            const instanceErrorElement = linkedProps.errorElement;
+            delete linkedProps.loader;
+            delete linkedProps.errorElement;
             const loadData = () => {
                 var _a;
                 const sourceId = (_a = linkedProps.source) === null || _a === void 0 ? void 0 : _a.id;
@@ -65,14 +99,18 @@ function createLinkedComponentFn(registerPackageExport, registerComponent) {
                         ? actualQuery.for(linkedProps.source)
                         : actualQuery;
                     setLoadingData(sourceId || requestQuery.toJSON().subject);
-                    (0, queryDispatch_1.getQueryDispatch)().selectQuery(requestQuery.build()).then((result) => {
-                        // Use empty object when result is null/undefined so the component
-                        // renders with default values instead of showing spinner forever.
+                    setQueryError(undefined);
+                    (0, queryDispatch_1.getQueryDispatch)()
+                        .selectQuery(requestQuery.build())
+                        .then((result) => {
+                        // Use empty object when result is null/undefined so the
+                        // component renders with default values instead of
+                        // showing the loader forever.
                         setQueryResult(result !== null && result !== void 0 ? result : {});
                         setLoadingData(null);
-                    }).catch((err) => {
-                        console.error('linkedComponent loadData failed:', err);
-                        setQueryResult({});
+                    })
+                        .catch((err) => {
+                        setQueryError(err instanceof Error ? err : new Error(String(err)));
                         setLoadingData(null);
                     });
                 }
@@ -102,8 +140,8 @@ function createLinkedComponentFn(registerPackageExport, registerComponent) {
             const resolvedSubjectId = actualQuery.toJSON().subject;
             if (!linkedProps.source && !resolvedSubjectId) {
                 if (actualQuery.hasPendingContext()) {
-                    // Subject will resolve after auth — show spinner until then.
-                    return createLoadingSpinner();
+                    // Subject will resolve after auth — show loader until then.
+                    return resolveLoader(instanceLoader, options.loader);
                 }
                 console.warn('This component requires a source to be provided (use the property "of"): ' +
                     functionalComponent.name);
@@ -114,17 +152,27 @@ function createLinkedComponentFn(registerPackageExport, registerComponent) {
                 if (queryResult) {
                     setQueryResult(undefined);
                 }
+                if (queryError) {
+                    setQueryError(undefined);
+                }
                 if (usingStorage && !sourceIsValidQResult) {
                     loadData();
                 }
             }, [(_a = linkedProps.source) === null || _a === void 0 ? void 0 : _a.id, resolvedSubjectId]);
+            if (queryError) {
+                const resolved = resolveErrorElement(instanceErrorElement, options.errorElement);
+                if (resolved === 'rethrow') {
+                    throw queryError;
+                }
+                return resolved;
+            }
             let dataIsLoaded = queryResult || !usingStorage || sourceIsValidQResult;
             // Keep legacy client-side guard to avoid hydration drift.
             if (dataIsLoaded && typeof window !== 'undefined') {
                 return react_1.default.createElement(functionalComponent, linkedProps);
             }
             else {
-                return createLoadingSpinner();
+                return resolveLoader(instanceLoader, options.loader);
             }
         });
         _wrappedComponent.original = functionalComponent;
@@ -138,15 +186,23 @@ function createLinkedComponentFn(registerPackageExport, registerComponent) {
         }
         registerComponent(_wrappedComponent, shapeClass);
         return _wrappedComponent;
-    };
+    }
+    return linkedComponent;
 }
 function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
-    return function linkedSetComponent(query, functionalComponent) {
+    function linkedSetComponent(arg1, arg2, arg3) {
+        const normalized = normalizeFactoryArgs(arg1, arg2, arg3);
+        const query = normalized.query;
+        const functionalComponent = normalized.component;
+        const options = normalized.options;
         let [shapeClass, actualQuery] = processQuery(query, true);
         let usingStorage = LinkedStorage_1.LinkedStorage.isInitialised();
         let _wrappedComponent = react_1.default.forwardRef((props, ref) => {
             var _a;
             let [queryResult, setQueryResult] = (0, react_1.useState)(undefined);
+            let [queryError, setQueryError] = (0, react_1.useState)(undefined);
+            // Bumped by `_refresh()` to force the load-effect to re-run.
+            let [refreshNonce, setRefreshNonce] = (0, react_1.useState)(0);
             let linkedProps = getLinkedSetComponentProps(props, shapeClass, functionalComponent);
             let defaultLimit = actualQuery.toJSON().limit || Package_1.DEFAULT_LIMIT;
             let [limit, setLimit] = (0, react_1.useState)(defaultLimit);
@@ -154,6 +210,10 @@ function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
             if (ref) {
                 linkedProps.ref = ref;
             }
+            const instanceLoader = linkedProps.loader;
+            const instanceErrorElement = linkedProps.errorElement;
+            delete linkedProps.loader;
+            delete linkedProps.errorElement;
             let sourceIsValidQResult = Array.isArray(props.of) &&
                 props.of.length > 0 &&
                 typeof ((_a = props.of[0]) === null || _a === void 0 ? void 0 : _a.id) === 'string' &&
@@ -197,6 +257,17 @@ function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
                     },
                 };
             }
+            linkedProps._refresh = (0, react_1.useCallback)((updatedProps) => {
+                if (updatedProps) {
+                    setQueryResult((current) => current ? Object.assign(Object.assign({}, current), updatedProps) : updatedProps);
+                }
+                else {
+                    // Bump the nonce so the load-effect refires even when
+                    // props.of / limit / offset are unchanged.
+                    setQueryError(undefined);
+                    setRefreshNonce((n) => n + 1);
+                }
+            }, []);
             (0, react_1.useEffect)(() => {
                 if (usingStorage && !sourceIsValidQResult) {
                     // QueryBuilder is immutable — chain calls to set subjects, limit, offset.
@@ -210,11 +281,24 @@ function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
                     if (offset) {
                         requestQuery = requestQuery.offset(offset);
                     }
-                    (0, queryDispatch_1.getQueryDispatch)().selectQuery(requestQuery.build()).then((result) => {
+                    setQueryError(undefined);
+                    (0, queryDispatch_1.getQueryDispatch)()
+                        .selectQuery(requestQuery.build())
+                        .then((result) => {
                         setQueryResult(result);
+                    })
+                        .catch((err) => {
+                        setQueryError(err instanceof Error ? err : new Error(String(err)));
                     });
                 }
-            }, [props.of, limit, offset]);
+            }, [props.of, limit, offset, refreshNonce]);
+            if (queryError) {
+                const resolved = resolveErrorElement(instanceErrorElement, options.errorElement);
+                if (resolved === 'rethrow') {
+                    throw queryError;
+                }
+                return resolved;
+            }
             let dataIsLoaded = queryResult || !usingStorage || sourceIsValidQResult;
             if (typeof queryResult === 'undefined' &&
                 usingStorage &&
@@ -225,7 +309,7 @@ function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
                 return react_1.default.createElement(functionalComponent, linkedProps);
             }
             else {
-                return createLoadingSpinner();
+                return resolveLoader(instanceLoader, options.loader);
             }
         });
         _wrappedComponent.original = functionalComponent;
@@ -239,7 +323,8 @@ function createLinkedSetComponentFn(registerPackageExport, registerComponent) {
         }
         registerComponent(_wrappedComponent, shapeClass);
         return _wrappedComponent;
-    };
+    }
+    return linkedSetComponent;
 }
 function getLinkedComponentProps(props, shapeClass) {
     let newProps = Object.assign(Object.assign({}, props), { source: getSourceFromInputProps(props, shapeClass) });
@@ -341,11 +426,93 @@ function isValidQResult(of, query) {
 function isValidSetQResult(qResults, query) {
     return qResults.every((qResult) => isValidQResult(qResult, query));
 }
-function createLoadingSpinner() {
-    return react_1.default.createElement('div', {
+/**
+ * Built-in loading element used when nothing higher in the resolution chain
+ * sets one. Renders an SVG ring; `stroke: currentColor` lets parent context
+ * tint it. Style via `.ld-loader` in `@_linked/css/loader.css`.
+ */
+function createDefaultLoader() {
+    return react_1.default.createElement('svg', {
         className: 'ld-loader',
         'aria-label': 'Loading',
         role: 'status',
-    });
+        viewBox: '0 0 24 24',
+        xmlns: 'http://www.w3.org/2000/svg',
+    }, react_1.default.createElement('circle', {
+        className: 'ld-loader__track',
+        cx: 12,
+        cy: 12,
+        r: 9,
+        fill: 'none',
+        stroke: 'currentColor',
+    }), react_1.default.createElement('circle', {
+        className: 'ld-loader__arc',
+        cx: 12,
+        cy: 12,
+        r: 9,
+        fill: 'none',
+        stroke: 'currentColor',
+    }));
+}
+/**
+ * Built-in error element used when a query rejects and nothing higher in the
+ * resolution chain handles it. Renders a small cross SVG; styled by
+ * `.ld-error` in `@_linked/css/error.css`.
+ */
+function createDefaultError() {
+    return react_1.default.createElement('svg', {
+        className: 'ld-error',
+        'aria-label': 'Failed to load',
+        role: 'alert',
+        viewBox: '0 0 24 24',
+        xmlns: 'http://www.w3.org/2000/svg',
+    }, react_1.default.createElement('line', {
+        x1: 6,
+        y1: 6,
+        x2: 18,
+        y2: 18,
+        stroke: 'currentColor',
+    }), react_1.default.createElement('line', {
+        x1: 18,
+        y1: 6,
+        x2: 6,
+        y2: 18,
+        stroke: 'currentColor',
+    }));
+}
+function resolveLoader(instanceLoader, definitionLoader) {
+    var _a, _b;
+    return ((_b = (_a = instanceLoader !== null && instanceLoader !== void 0 ? instanceLoader : definitionLoader) !== null && _a !== void 0 ? _a : exports.LinkedComponentDefaults.loader) !== null && _b !== void 0 ? _b : createDefaultLoader());
+}
+/**
+ * Resolves the error element. Returns either a React element to render, or
+ * the literal `'rethrow'` — callers must rethrow the captured error when
+ * they receive the sentinel.
+ */
+function resolveErrorElement(instanceErrorElement, definitionErrorElement) {
+    var _a, _b;
+    return ((_b = (_a = instanceErrorElement !== null && instanceErrorElement !== void 0 ? instanceErrorElement : definitionErrorElement) !== null && _a !== void 0 ? _a : exports.LinkedComponentDefaults.errorElement) !== null && _b !== void 0 ? _b : createDefaultError());
+}
+/**
+ * Normalizes the three factory signatures into a single shape:
+ *   (query, fn)                  -> { query, component: fn, options: {} }
+ *   (query, fn, options)         -> { query, component: fn, options }
+ *   ({ query, component, ... })  -> { query, component, options: { loader, errorElement } }
+ */
+function normalizeFactoryArgs(arg1, arg2, arg3) {
+    if (arg2 === undefined &&
+        arg1 &&
+        typeof arg1 === 'object' &&
+        'component' in arg1 &&
+        'query' in arg1) {
+        const config = arg1;
+        const { query, component } = config, options = __rest(config, ["query", "component"]);
+        return { query, component, options };
+    }
+    return {
+        query: arg1,
+        component: arg2,
+        options: arg3 !== null && arg3 !== void 0 ? arg3 : {},
+    };
 }
 //# sourceMappingURL=LinkedComponent.js.map