esp-js-react 8.0.0-next.0 → 8.0.2-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/.dist/esp-react.js +132 -90
  2. package/.dist/esp-react.js.map +1 -1
  3. package/.dist/esp-react.min.js +1 -1
  4. package/.dist/esp-react.min.js.map +1 -1
  5. package/.dist/typings/{espModelContext.d.ts → espModelContextProvider.d.ts} +2 -2
  6. package/.dist/typings/{espRouterContext.d.ts → espRouterContextProvider.d.ts} +8 -8
  7. package/.dist/typings/index.d.ts +5 -5
  8. package/.dist/typings/polimer/getEspPolimerImmutableModel.d.ts +21 -0
  9. package/.dist/typings/useModelSelector.d.ts +20 -6
  10. package/package.json +4 -4
  11. package/src/connectableComponent.tsx +10 -9
  12. package/src/{espModelContext.tsx → espModelContextProvider.tsx} +5 -5
  13. package/src/{espRouterContext.tsx → espRouterContextProvider.tsx} +8 -8
  14. package/src/index.ts +19 -13
  15. package/src/polimer/getEspPolimerImmutableModel.ts +50 -0
  16. package/src/useModelSelector.ts +85 -20
  17. package/src/viewBinder.tsx +1 -1
  18. package/src/viewBinderConnectable.tsx +11 -10
  19. package/tests/connectableComponentLegacyTests.tsx +26 -26
  20. package/tests/connectableComponentTests.tsx +419 -0
  21. package/tests/indexTests.ts +25 -91
  22. package/tests/testApi/asserts.ts +75 -0
  23. package/tests/testApi/routerSpy.ts +24 -0
  24. package/tests/testApi/testApi.tsx +84 -0
  25. package/tests/testApi/testModel.ts +37 -0
  26. package/tests/testApi/useStoreReceivedProps.ts +11 -0
  27. package/tests/testApi/viewMetadata.tsx +46 -0
  28. package/tests/useModelSelectorTests.tsx +257 -0
  29. package/.dist/typings/polimer/getEspReactRenderModel.d.ts +0 -21
  30. package/src/polimer/getEspReactRenderModel.ts +0 -50
  31. package/tests/connectWithSelectorTests.tsx +0 -67
  32. /package/.dist/typings/polimer/{polimerExtentsions.d.ts → polimerModelBuilderExtentsions.d.ts} +0 -0
  33. /package/src/polimer/{polimerExtentsions.ts → polimerModelBuilderExtentsions.ts} +0 -0
@@ -19,12 +19,12 @@ export declare const PublishEventContext: React.Context<PublishEventDelegate>;
19
19
  *
20
20
  * To use this, please ensure your V-DOM has the EspRouterContext at a higher node:
21
21
  *
22
- * <EspRouterContext router={router}>
22
+ * <EspRouterContextProvider router={router}>
23
23
  * <YourComponents />
24
- * </EspRouterContext>
24
+ * </EspRouterContextProvider>
25
25
  */
26
26
  export declare const usePublishEvent: () => PublishEventDelegate;
27
- export type EspRouterContextProps = PropsWithChildren<{
27
+ export type EspRouterContextProviderProps = PropsWithChildren<{
28
28
  router: Router;
29
29
  }>;
30
30
  /**
@@ -32,16 +32,16 @@ export type EspRouterContextProps = PropsWithChildren<{
32
32
  *
33
33
  * Also sets up the usePublishEvent() hook so nested components can publish to the router.
34
34
  */
35
- export declare const EspRouterContext: ({ children, router }: EspRouterContextProps) => React.JSX.Element;
35
+ export declare const EspRouterContextProvider: ({ children, router }: EspRouterContextProviderProps) => React.JSX.Element;
36
36
  /**
37
37
  * Used to set the router on the RouterContext making it available to components down the tree (via useRouter()).
38
38
  *
39
- * @deprecated use EspRouterContext
39
+ * @deprecated use EspRouterContextProvider
40
40
  */
41
- export declare const RouterProvider: ({ children, router }: EspRouterContextProps) => React.JSX.Element;
41
+ export declare const RouterProvider: ({ children, router }: EspRouterContextProviderProps) => React.JSX.Element;
42
42
  /**
43
43
  * Props for RouterProvider
44
44
  *
45
- * @deprecated use EspRouterContextProps
45
+ * @deprecated use EspRouterContextProviderProps
46
46
  */
47
- export type RouterProviderProps = EspRouterContextProps;
47
+ export type RouterProviderProps = EspRouterContextProviderProps;
@@ -1,11 +1,11 @@
1
- import './polimer/polimerExtentsions';
1
+ import './polimer/polimerModelBuilderExtentsions';
2
2
  export { ViewBinder } from './viewBinder';
3
3
  export { ViewBinderConnectableProps, ViewBinderConnectable } from './viewBinderConnectable';
4
4
  export { viewBinding, DEFAULT_VIEW_KEY } from './viewBindingDecorator';
5
- export { GetEspReactRenderModelMetadata, GetEspReactRenderModelConsts, getEspReactRenderModel } from './polimer/getEspReactRenderModel';
5
+ export { GetEspPolimerImmutableModelMetadata, GetEspPolimerImmutableModelConsts, getEspPolimerImmutableModel } from './polimer/getEspPolimerImmutableModel';
6
6
  export { createViewForModel } from './viewBindingDecorator';
7
7
  export { connect, ConnectableComponentFactory } from './connect';
8
8
  export { CreatePublishEventProps, MapModelToProps, ConnectableComponentProps, ConnectableComponentChildProps, ConnectableComponent, } from './connectableComponent';
9
- export { useModelSelector, ConnectEqualityFn, defaultConnectEqualityFn } from './useModelSelector';
10
- export { RouterProvider, RouterProviderProps, EspRouterContext, EspRouterContextProps, RouterContext, useRouter, PublishEventDelegate, PublishEventContext, usePublishEvent, } from './espRouterContext';
11
- export { useGetModelId, GetModelIdDelegate, GetModelIdContext, PublishModelEventDelegate, PublishModelEventContext, usePublishModelEvent, PublishModelEventWithEntityKeyDelegate, PublishModelEventWithEntityKeyContext, usePublishModelEventWithEntityKey, EspModelContext, EspModelContextProps, } from './espModelContext';
9
+ export { UseModelSelector, useModelSelector, EditableModelSelectorOptions, modelSelectorOptions, ModelSelectorOptions, ModelSelectorEqualityFn, } from './useModelSelector';
10
+ export { RouterProvider, RouterProviderProps, EspRouterContextProvider, EspRouterContextProviderProps, RouterContext, useRouter, PublishEventDelegate, PublishEventContext, usePublishEvent, } from './espRouterContextProvider';
11
+ export { useGetModelId, GetModelIdDelegate, GetModelIdContext, useGetModel, GetModelDelegate, GetModelContext, PublishModelEventDelegate, PublishModelEventContext, usePublishModelEvent, PublishModelEventWithEntityKeyDelegate, PublishModelEventWithEntityKeyContext, usePublishModelEventWithEntityKey, EspModelContextProvider, EspModelContextProviderProps, } from './espModelContextProvider';
@@ -0,0 +1,21 @@
1
+ export interface GetEspPolimerImmutableModelMetadata {
2
+ functionName: string;
3
+ }
4
+ export declare namespace GetEspPolimerImmutableModelConsts {
5
+ const CustomDataKey = "GetEspReactImmutableModelCustomDataKey";
6
+ /**
7
+ * If there is no @getEspPolimerImmutableModel decorator and a function by this name exists on a model, then it will be invoked to identify the sub model which will replaced the `model` prop passed to the child view of a ConnectableComponent
8
+ */
9
+ const HandlerFunctionName = "getEspPolimerImmutableModel";
10
+ }
11
+ /**
12
+ * A decorator which can be used to identify the render model which will replaced the `model` prop passed to the child view of a ConnectableComponent
13
+ */
14
+ export declare function getEspPolimerImmutableModel(): (target: any, name: any, descriptor: any) => any;
15
+ /**
16
+ * Returns the model which will be used to pluck state/props for the current view.
17
+ *
18
+ * This is basically a hook (not a React 'hook') to call a function on `model` and get a new subgraph to use as state.
19
+ *
20
+ */
21
+ export declare const tryGetPolimerImmutableModel: <TImmutableModel>(model: any) => TImmutableModel;
@@ -1,13 +1,27 @@
1
- export declare const defaultConnectEqualityFn: <TSelected>(a: TSelected, b: TSelected) => boolean;
2
- export type ConnectEqualityFn<T> = (last: T, next: T) => boolean;
1
+ export type ModelSelectorEqualityFn<T> = (last: T, next: T) => boolean;
2
+ /**
3
+ * @param modelId - the modelId of the model to be observed via the esp Router.
4
+ * @param tryPreSelectPolimerImmutableModel - if true, and the esp model is an esp-js-polimer model, the immutable model will be used when calling the selector.
5
+ * @param equalityFn - Equality function which will be applied against TSelected, defaults to instance equality (a === b).
6
+ */
7
+ export type ModelSelectorOptions<TSelected> = {
8
+ modelId?: string;
9
+ tryPreSelectPolimerImmutableModel: boolean;
10
+ equalityFn: ModelSelectorEqualityFn<TSelected>;
11
+ };
12
+ export interface EditableModelSelectorOptions<TSelected> extends ModelSelectorOptions<TSelected> {
13
+ setModelId(modelId: string): this;
14
+ setTryPreSelectPolimerImmutableModel(value: boolean): this;
15
+ setEqualityFn(fn: (a: TSelected, b: TSelected) => boolean): this;
16
+ }
17
+ export declare const modelSelectorOptions: <TSelected>() => EditableModelSelectorOptions<TSelected>;
18
+ export type UseModelSelector = <TModel, TSelected>(selector: (model: TModel) => TSelected, options?: ModelSelectorOptions<TSelected>) => TSelected;
3
19
  /**
4
20
  * A hook which returns model state from the esp Router.
5
21
  *
6
22
  * This hooks wih observe updates and re-render the component if the model changes.
7
23
  *
8
24
  * @param selector - a function to select a selection of the model - the selector does not need to be memoized, this selector will be cached against the modelId.
9
- * @param modelId - the modelId of the model to be observed via the esp Router.
10
- * @param tryPreSelectPolimerImmutableModel - if true, and the esp model is an esp-js-polimer model, the immutable model will be used when calling the selector.
11
- * @param equalityFn - Equality function which will be applied against TSelected, defaults to instance equality (a === b).
25
+ * @param options
12
26
  */
13
- export declare const useModelSelector: <TModel = unknown, TSelected = unknown>(selector: (model: TModel) => TSelected, modelId?: string, tryPreSelectPolimerImmutableModel?: boolean, equalityFn?: ConnectEqualityFn<TSelected>) => any;
27
+ export declare const useModelSelector: UseModelSelector;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "esp-js-react",
3
- "version": "8.0.0-next.0",
3
+ "version": "8.0.2-next.0",
4
4
  "description": "Evented State Processor (ESP) React Components",
5
5
  "keywords": [
6
6
  "esp",
@@ -24,8 +24,8 @@
24
24
  "dev": "nps dev"
25
25
  },
26
26
  "dependencies": {
27
- "esp-js": "^8.0.0-next.0",
28
- "esp-js-polimer": "^8.0.0-next.0",
27
+ "esp-js": "^8.0.2-next.0",
28
+ "esp-js-polimer": "^8.0.2-next.0",
29
29
  "prop-types": "^15.7.2",
30
30
  "react": "^18.3.1",
31
31
  "use-sync-external-store": "^1.2.2"
@@ -43,5 +43,5 @@
43
43
  "prop-types": "^15.0.0",
44
44
  "react": "^18.0.0"
45
45
  },
46
- "gitHead": "323e76ba03a81860fb027d319eb16b26a1c3e6df"
46
+ "gitHead": "b6d4d9e658a90dd5045fc796fd216111b0ae18d5"
47
47
  }
@@ -1,11 +1,11 @@
1
1
  import * as React from 'react';
2
- import {useRouter} from './espRouterContext';
2
+ import {useRouter} from './espRouterContextProvider';
3
3
  import {useMemo} from 'react';
4
4
  import {Router, utils} from 'esp-js';
5
- import {EspModelContext, useGetModelId} from './espModelContext';
5
+ import {EspModelContextProvider, useGetModelId} from './espModelContextProvider';
6
6
  import {createViewForModel} from './viewBindingDecorator';
7
- import {tryGetRenderModel} from './polimer/getEspReactRenderModel';
8
- import {useModelSelector} from './useModelSelector';
7
+ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
8
+ import {modelSelectorOptions, useModelSelector} from './useModelSelector';
9
9
 
10
10
  /**
11
11
  * @deprecated
@@ -48,7 +48,7 @@ const getChildProps = <TModel, TModelMappedToProps, TPublishEventProps>(
48
48
  publishEventProps: TPublishEventProps
49
49
  ): ConnectableComponentChildProps<TModel> => {
50
50
  // consume what this component owns, and let the rest end up in `...rest`
51
- const model = tryGetRenderModel<TModel>(initialModel);
51
+ const model = tryGetPolimerImmutableModel<TModel>(initialModel);
52
52
  let childProps = {
53
53
  modelId,
54
54
  router: router,
@@ -98,8 +98,9 @@ export const ConnectableComponent = <TModel = {}, TPublishEventProps = {}, TMode
98
98
  );
99
99
  const model = useModelSelector<TModel, TModel>(
100
100
  m => m,
101
- modelId,
102
- false
101
+ modelSelectorOptions()
102
+ .setModelId(modelId)
103
+ .setTryPreSelectPolimerImmutableModel(false)
103
104
  );
104
105
  if (model == null) {
105
106
  return null;
@@ -107,8 +108,8 @@ export const ConnectableComponent = <TModel = {}, TPublishEventProps = {}, TMode
107
108
  let childProps = getChildProps(router, modelId, rest, model, mapModelToProps, publishEventProps);
108
109
  let viewElement = createViewForModel(model, childProps, viewContext, view);
109
110
  return (
110
- <EspModelContext modelId={modelId} model={model} router={router} {...childProps}>
111
+ <EspModelContextProvider modelId={modelId} model={model} router={router} {...childProps}>
111
112
  {viewElement}
112
- </EspModelContext>
113
+ </EspModelContextProvider>
113
114
  );
114
115
  };
@@ -1,9 +1,9 @@
1
1
  import * as React from 'react';
2
2
  import {DefaultModelAddress, Router, Status, Logger, utils} from 'esp-js';
3
3
  import {useContext, useCallback, createContext, PropsWithChildren} from 'react';
4
- import {useRouter} from './espRouterContext';
4
+ import {useRouter} from './espRouterContextProvider';
5
5
 
6
- const _log = Logger.create('EspModelContext');
6
+ const _log = Logger.create('EspModelContextProvider');
7
7
 
8
8
  export type GetModelIdDelegate = () => string;
9
9
  export const GetModelIdContext = createContext<GetModelIdDelegate>(null);
@@ -37,12 +37,12 @@ export const PublishModelEventWithEntityKeyContext = createContext<PublishModelE
37
37
  */
38
38
  export const usePublishModelEventWithEntityKey = () => useContext(PublishModelEventWithEntityKeyContext);
39
39
 
40
- export interface EspModelContextProps {
40
+ export interface EspModelContextProviderProps {
41
41
  modelId: string;
42
42
  model?: unknown;
43
43
  }
44
44
 
45
- export const EspModelContext = ({modelId, children, model}: PropsWithChildren<EspModelContextProps>) => {
45
+ export const EspModelContextProvider = ({modelId, children, model}: PropsWithChildren<EspModelContextProviderProps>) => {
46
46
  const router = useRouter();
47
47
  const getModelId: () => string = useCallback(() => {
48
48
  return modelId;
@@ -87,7 +87,7 @@ const warnIfModelAccessedOutSideDispatchLoop = (router: Router, modelId: string)
87
87
  stack = (e as Error).stack;
88
88
  }
89
89
  _log.warn(
90
- `EspModelContext useGetModelId has been invoked outside of the models (${modelId}) dispatch loop.` +
90
+ `EspModelContextProvider useGetModelId has been invoked outside of the models (${modelId}) dispatch loop.` +
91
91
  `This may have unknown state state issues.` +
92
92
  stack
93
93
  );
@@ -47,20 +47,20 @@ export const PublishEventContext = createContext<PublishEventDelegate>(null);
47
47
  *
48
48
  * To use this, please ensure your V-DOM has the EspRouterContext at a higher node:
49
49
  *
50
- * <EspRouterContext router={router}>
50
+ * <EspRouterContextProvider router={router}>
51
51
  * <YourComponents />
52
- * </EspRouterContext>
52
+ * </EspRouterContextProvider>
53
53
  */
54
54
  export const usePublishEvent = () => useContext(PublishEventContext);
55
55
 
56
- export type EspRouterContextProps = PropsWithChildren<{ router: Router; }>;
56
+ export type EspRouterContextProviderProps = PropsWithChildren<{ router: Router; }>;
57
57
 
58
58
  /**
59
59
  * Used to set the router on the RouterContext making it available to components down the tree via the useRouter() hook.
60
60
  *
61
61
  * Also sets up the usePublishEvent() hook so nested components can publish to the router.
62
62
  */
63
- export const EspRouterContext = ({children, router}: EspRouterContextProps) => {
63
+ export const EspRouterContextProvider = ({children, router}: EspRouterContextProviderProps) => {
64
64
  const publishEvent: PublishEventDelegate = useCallback((modelIdOrModelAddress: string, eventType: string, event: any) => {
65
65
  router.publishEvent(modelIdOrModelAddress, eventType, event);
66
66
  }, [router]);
@@ -76,13 +76,13 @@ export const EspRouterContext = ({children, router}: EspRouterContextProps) => {
76
76
  /**
77
77
  * Used to set the router on the RouterContext making it available to components down the tree (via useRouter()).
78
78
  *
79
- * @deprecated use EspRouterContext
79
+ * @deprecated use EspRouterContextProvider
80
80
  */
81
- export const RouterProvider = EspRouterContext;
81
+ export const RouterProvider = EspRouterContextProvider;
82
82
 
83
83
  /**
84
84
  * Props for RouterProvider
85
85
  *
86
- * @deprecated use EspRouterContextProps
86
+ * @deprecated use EspRouterContextProviderProps
87
87
  */
88
- export type RouterProviderProps = EspRouterContextProps;
88
+ export type RouterProviderProps = EspRouterContextProviderProps;
package/src/index.ts CHANGED
@@ -18,7 +18,7 @@
18
18
  //
19
19
 
20
20
  // import for side effects
21
- import './polimer/polimerExtentsions';
21
+ import './polimer/polimerModelBuilderExtentsions';
22
22
 
23
23
  export {ViewBinder} from './viewBinder';
24
24
  export {
@@ -27,10 +27,10 @@ export {
27
27
  } from './viewBinderConnectable';
28
28
  export {viewBinding, DEFAULT_VIEW_KEY} from './viewBindingDecorator';
29
29
  export {
30
- GetEspReactRenderModelMetadata,
31
- GetEspReactRenderModelConsts,
32
- getEspReactRenderModel
33
- } from './polimer/getEspReactRenderModel';
30
+ GetEspPolimerImmutableModelMetadata,
31
+ GetEspPolimerImmutableModelConsts,
32
+ getEspPolimerImmutableModel
33
+ } from './polimer/getEspPolimerImmutableModel';
34
34
  export {createViewForModel} from './viewBindingDecorator';
35
35
  export {
36
36
  connect,
@@ -44,31 +44,37 @@ export {
44
44
  ConnectableComponent,
45
45
  } from './connectableComponent';
46
46
  export {
47
+ UseModelSelector,
47
48
  useModelSelector,
48
- ConnectEqualityFn,
49
- defaultConnectEqualityFn
49
+ EditableModelSelectorOptions,
50
+ modelSelectorOptions,
51
+ ModelSelectorOptions,
52
+ ModelSelectorEqualityFn,
50
53
  } from './useModelSelector';
51
54
  export {
52
55
  RouterProvider,
53
56
  RouterProviderProps,
54
- EspRouterContext,
55
- EspRouterContextProps,
57
+ EspRouterContextProvider,
58
+ EspRouterContextProviderProps,
56
59
  RouterContext,
57
60
  useRouter,
58
61
  PublishEventDelegate,
59
62
  PublishEventContext,
60
63
  usePublishEvent,
61
- } from './espRouterContext';
64
+ } from './espRouterContextProvider';
62
65
  export {
63
66
  useGetModelId,
64
67
  GetModelIdDelegate,
65
68
  GetModelIdContext,
69
+ useGetModel,
70
+ GetModelDelegate,
71
+ GetModelContext,
66
72
  PublishModelEventDelegate,
67
73
  PublishModelEventContext,
68
74
  usePublishModelEvent,
69
75
  PublishModelEventWithEntityKeyDelegate,
70
76
  PublishModelEventWithEntityKeyContext,
71
77
  usePublishModelEventWithEntityKey,
72
- EspModelContext,
73
- EspModelContextProps,
74
- } from './espModelContext';
78
+ EspModelContextProvider,
79
+ EspModelContextProviderProps,
80
+ } from './espModelContextProvider';
@@ -0,0 +1,50 @@
1
+ import {EspMetadata, EspDecoratorUtil, utils} from 'esp-js';
2
+
3
+ export interface GetEspPolimerImmutableModelMetadata {
4
+ functionName: string;
5
+ }
6
+
7
+ export namespace GetEspPolimerImmutableModelConsts {
8
+ export const CustomDataKey = 'GetEspReactImmutableModelCustomDataKey';
9
+ /**
10
+ * If there is no @getEspPolimerImmutableModel decorator and a function by this name exists on a model, then it will be invoked to identify the sub model which will replaced the `model` prop passed to the child view of a ConnectableComponent
11
+ */
12
+ export const HandlerFunctionName = 'getEspPolimerImmutableModel';
13
+ }
14
+
15
+ /**
16
+ * A decorator which can be used to identify the render model which will replaced the `model` prop passed to the child view of a ConnectableComponent
17
+ */
18
+ export function getEspPolimerImmutableModel() {
19
+ return function (target, name, descriptor) {
20
+ let metadata: EspMetadata = EspDecoratorUtil.getOrCreateMetaData(target.constructor);
21
+ metadata.addCustomData(
22
+ GetEspPolimerImmutableModelConsts.CustomDataKey,
23
+ <GetEspPolimerImmutableModelMetadata>{ functionName: name }
24
+ );
25
+ return descriptor;
26
+ };
27
+ }
28
+
29
+ /**
30
+ * Returns the model which will be used to pluck state/props for the current view.
31
+ *
32
+ * This is basically a hook (not a React 'hook') to call a function on `model` and get a new subgraph to use as state.
33
+ *
34
+ */
35
+ export const tryGetPolimerImmutableModel = <TImmutableModel>(model: any): TImmutableModel => {
36
+ // does the given model have a decorated function we can invoke to get a different model to render?
37
+ if (EspDecoratorUtil.hasMetadata(model)) {
38
+ let metadata: GetEspPolimerImmutableModelMetadata = EspDecoratorUtil.getCustomData(model, GetEspPolimerImmutableModelConsts.CustomDataKey);
39
+ if (metadata) {
40
+ return model[metadata.functionName]();
41
+ }
42
+ }
43
+ // else see if there is a function with name GetEspPolimerImmutableModelConsts.HandlerFunctionName we can invoke to get a different model to render?
44
+ let immutableModel = model[GetEspPolimerImmutableModelConsts.HandlerFunctionName];
45
+ if (immutableModel && utils.isFunction(immutableModel)) {
46
+ return immutableModel.call(model);
47
+ }
48
+ // else return the initial model passed in
49
+ return model;
50
+ };
@@ -1,13 +1,64 @@
1
1
  import {useMemo} from 'react';
2
- import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector';
3
- import {Guard} from 'esp-js';
4
- import {useRouter} from './espRouterContext';
5
- import {useGetModelId} from './espModelContext';
6
- import {tryGetRenderModel} from './polimer/getEspReactRenderModel';
2
+ import {useSyncExternalStoreWithSelector} from 'use-sync-external-store/with-selector';
3
+ import {Guard, utils} from 'esp-js';
4
+ import {useRouter} from './espRouterContextProvider';
5
+ import {useGetModelId} from './espModelContextProvider';
6
+ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
7
7
 
8
- export const defaultConnectEqualityFn = <TSelected>(a: TSelected, b: TSelected) => a === b; // reference equality
8
+ export type ModelSelectorEqualityFn<T> = (last: T, next: T) => boolean;
9
9
 
10
- export type ConnectEqualityFn<T> = (last: T, next: T) => boolean;
10
+ /**
11
+ * @param modelId - the modelId of the model to be observed via the esp Router.
12
+ * @param tryPreSelectPolimerImmutableModel - if true, and the esp model is an esp-js-polimer model, the immutable model will be used when calling the selector.
13
+ * @param equalityFn - Equality function which will be applied against TSelected, defaults to instance equality (a === b).
14
+ */
15
+ export type ModelSelectorOptions<TSelected> = {
16
+ modelId?: string,
17
+ tryPreSelectPolimerImmutableModel: boolean,
18
+ equalityFn: ModelSelectorEqualityFn<TSelected>
19
+ };
20
+
21
+ export interface EditableModelSelectorOptions<TSelected> extends ModelSelectorOptions<TSelected> {
22
+ setModelId(modelId: string): this;
23
+
24
+ setTryPreSelectPolimerImmutableModel(value: boolean): this;
25
+
26
+ setEqualityFn(fn: (a: TSelected, b: TSelected) => boolean): this;
27
+ }
28
+
29
+ export const modelSelectorOptions = <TSelected>() => {
30
+ let modelId = undefined;
31
+ let equalityFn: ModelSelectorEqualityFn<TSelected> = (a: TSelected, b: TSelected) => a === b;
32
+ let tryPreSelectPolimerImmutableModel = true;
33
+ return {
34
+ get modelId() {
35
+ return modelId;
36
+ },
37
+ setModelId(value: string) {
38
+ modelId = value;
39
+ return this;
40
+ },
41
+ get equalityFn() {
42
+ return equalityFn;
43
+ },
44
+ setEqualityFn(value: ModelSelectorEqualityFn<TSelected>) {
45
+ equalityFn = value;
46
+ return this;
47
+ },
48
+ get tryPreSelectPolimerImmutableModel() {
49
+ return tryPreSelectPolimerImmutableModel;
50
+ },
51
+ setTryPreSelectPolimerImmutableModel(value: boolean) {
52
+ tryPreSelectPolimerImmutableModel = value;
53
+ return this;
54
+ }
55
+ } as EditableModelSelectorOptions<TSelected>;
56
+ };
57
+
58
+ export type UseModelSelector = <TModel, TSelected>(
59
+ selector: (model: TModel) => TSelected,
60
+ options?: ModelSelectorOptions<TSelected>
61
+ ) => TSelected;
11
62
 
12
63
  /**
13
64
  * A hook which returns model state from the esp Router.
@@ -15,19 +66,17 @@ export type ConnectEqualityFn<T> = (last: T, next: T) => boolean;
15
66
  * This hooks wih observe updates and re-render the component if the model changes.
16
67
  *
17
68
  * @param selector - a function to select a selection of the model - the selector does not need to be memoized, this selector will be cached against the modelId.
18
- * @param modelId - the modelId of the model to be observed via the esp Router.
19
- * @param tryPreSelectPolimerImmutableModel - if true, and the esp model is an esp-js-polimer model, the immutable model will be used when calling the selector.
20
- * @param equalityFn - Equality function which will be applied against TSelected, defaults to instance equality (a === b).
69
+ * @param options
21
70
  */
22
- export const useModelSelector = <TModel = unknown, TSelected = unknown>(
71
+ export const useModelSelector: UseModelSelector = <TModel, TSelected>(
23
72
  selector: (model: TModel) => TSelected,
24
- modelId?: string,
25
- tryPreSelectPolimerImmutableModel: boolean = true,
26
- equalityFn: ConnectEqualityFn<TSelected> = defaultConnectEqualityFn
73
+ options: ModelSelectorOptions<TSelected> = modelSelectorOptions<TSelected>()
27
74
  ) => {
28
75
  Guard.isFunction(selector, 'You must pass a selector function to connectSelector');
29
76
  const router = useRouter();
30
- modelId = modelId || useGetModelId();
77
+ const modelId = options?.modelId || useGetModelId();
78
+ const tryPreSelectPolimerImmutableModel = options?.tryPreSelectPolimerImmutableModel;
79
+ const equalityFn = options?.equalityFn;
31
80
  const dependencies = useMemo(
32
81
  () => {
33
82
  // Because of how useSyncExternalStore works, there is an implicit dependency between the subscribe and getSnapshot functions.
@@ -44,7 +93,7 @@ export const useModelSelector = <TModel = unknown, TSelected = unknown>(
44
93
  (m: any) => {
45
94
  // try and get a submodel to render
46
95
  const nextModel = tryPreSelectPolimerImmutableModel
47
- ? tryGetRenderModel(m)
96
+ ? tryGetPolimerImmutableModel(m)
48
97
  : m;
49
98
  // if the above didn't manage to get a submodel,
50
99
  // we need to mutate to force useSyncExternalStoreWithSelector to pick up the change
@@ -64,10 +113,7 @@ export const useModelSelector = <TModel = unknown, TSelected = unknown>(
64
113
  return model;
65
114
  },
66
115
  // While getSnapshot needs to model to be immutable,
67
-
68
- // TODO confirm this comment with a test:
69
-
70
- // useSyncExternalStoreWithSelector builds on top of this so the TSelected can defer to an equality check to determine if the change is propagated.
116
+ // useSyncExternalStoreWithSelector builds on top of this, so the TSelected can defer to an equality check to determine if the change is propagated.
71
117
  // The selector here just maps the TSelected, useSyncExternalStoreWithSelector internally does the equality check.
72
118
  wrappedSelector: (snapshot: TModel) => {
73
119
  // The first time this renders, react calls getSnapshot and the selector before the router has pushed a change.
@@ -81,6 +127,19 @@ export const useModelSelector = <TModel = unknown, TSelected = unknown>(
81
127
  // Don't cache check against 'selector' argument as that will likely change unless the caller memoizes it.
82
128
  [router, modelId]
83
129
  );
130
+
131
+ // If we don't have a modelId, we still need to return a hook so React doesn't complain.
132
+ // Additionally, we need to let the above expiration (dependencies) run to unsubscribe from any previous subscription.
133
+ if (utils.stringIsEmpty(modelId)) {
134
+ return useSyncExternalStoreWithSelector(
135
+ noopSubscription.subscribe,
136
+ noopSubscription.getSnapshot,
137
+ undefined,
138
+ noopSubscription.wrappedSelector,
139
+ equalityFn
140
+ );
141
+ }
142
+
84
143
  // Docs on useSyncExternalStore https://github.com/reactwg/react-18/discussions/86
85
144
  // Redux's usage of this: https://github.com/reduxjs/react-redux/blob/master/src/hooks/useSelector.ts
86
145
  // Code: https://github.com/facebook/react/blob/main/packages/use-sync-external-store/src/useSyncExternalStoreWithSelector.js
@@ -91,4 +150,10 @@ export const useModelSelector = <TModel = unknown, TSelected = unknown>(
91
150
  dependencies.wrappedSelector,
92
151
  equalityFn,
93
152
  );
153
+ };
154
+
155
+ const noopSubscription = {
156
+ subscribe: () => { },
157
+ getSnapshot: () => null,
158
+ wrappedSelector: () => true
94
159
  };
@@ -18,7 +18,7 @@
18
18
 
19
19
  import * as React from 'react';
20
20
  import {createViewForModel} from './viewBindingDecorator';
21
- import {useRouter} from './espRouterContext';
21
+ import {useRouter} from './espRouterContextProvider';
22
22
 
23
23
  export interface ViewBinderProps {
24
24
  model: any;
@@ -1,10 +1,10 @@
1
- import {useRouter} from './espRouterContext';
2
- import {EspModelContext} from './espModelContext';
1
+ import {useRouter} from './espRouterContextProvider';
2
+ import {EspModelContextProvider} from './espModelContextProvider';
3
3
  import {Logger, Router} from 'esp-js';
4
4
  import * as React from 'react';
5
- import {useModelSelector} from './useModelSelector';
5
+ import {modelSelectorOptions, useModelSelector} from './useModelSelector';
6
6
  import {createViewForModel} from './viewBindingDecorator';
7
- import {tryGetRenderModel} from './polimer/getEspReactRenderModel';
7
+ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
8
8
 
9
9
  const _log = Logger.create('ViewBinderConnectable');
10
10
 
@@ -32,22 +32,23 @@ export const ViewBinderConnectable = ({modelId, viewContext, view}: ViewBinderCo
32
32
  const router = useRouter();
33
33
  const model = useModelSelector<object, object>(
34
34
  m => m,
35
- modelId,
36
- false
35
+ modelSelectorOptions()
36
+ .setModelId(modelId)
37
+ .setTryPreSelectPolimerImmutableModel(false)
37
38
  );
38
39
  if (!model) {
39
40
  return null;
40
41
  }
41
- let renderModel = tryGetRenderModel<object>(model);
42
+ let immutableModel = tryGetPolimerImmutableModel<object>(model);
42
43
  const childProps: ViewBinderConnectableChildProps = {
43
44
  modelId,
44
45
  router: router,
45
- model: renderModel
46
+ model: immutableModel
46
47
  };
47
48
  let viewElement = createViewForModel(model, childProps, viewContext, view);
48
49
  return (
49
- <EspModelContext modelId={modelId} router={router} model={renderModel} {...childProps}>
50
+ <EspModelContextProvider modelId={modelId} router={router} model={immutableModel} {...childProps}>
50
51
  {viewElement}
51
- </EspModelContext>
52
+ </EspModelContextProvider>
52
53
  );
53
54
  };