esp-js-react 8.0.2-next.0 → 8.0.4-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 (37) hide show
  1. package/.dist/esp-react.js +68 -112
  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/connect.d.ts +2 -6
  6. package/.dist/typings/connectableComponent.d.ts +0 -16
  7. package/.dist/typings/espModelContextProvider.d.ts +27 -12
  8. package/.dist/typings/espRouterContextProvider.d.ts +5 -5
  9. package/.dist/typings/index.d.ts +2 -3
  10. package/.dist/typings/useSyncModelWithSelector.d.ts +50 -0
  11. package/.dist/typings/viewBinder.d.ts +8 -1
  12. package/.dist/typings/viewBindingDecorator.d.ts +1 -1
  13. package/package.json +4 -4
  14. package/src/connect.tsx +2 -6
  15. package/src/connectableComponent.tsx +3 -20
  16. package/src/espModelContextProvider.tsx +30 -46
  17. package/src/espRouterContextProvider.tsx +5 -5
  18. package/src/index.ts +6 -13
  19. package/src/{useModelSelector.ts → useSyncModelWithSelector.ts} +47 -16
  20. package/src/viewBinder.tsx +13 -2
  21. package/src/viewBindingDecorator.ts +2 -2
  22. package/tests/connectableComponentTests.tsx +323 -246
  23. package/tests/espModelContextProviderTests.tsx +142 -0
  24. package/tests/espRouterContextProviderTests.tsx +54 -0
  25. package/tests/indexTests.ts +3 -4
  26. package/tests/testApi/asserts.ts +17 -2
  27. package/tests/testApi/testApi.tsx +37 -21
  28. package/tests/testApi/testModel.ts +15 -8
  29. package/tests/testApi/useStoreReceivedProps.ts +3 -0
  30. package/tests/testApi/viewFactory.tsx +31 -0
  31. package/tests/{useModelSelectorTests.tsx → useSyncModelWithSelectorTests.tsx} +52 -22
  32. package/tests/viewBinderTests.tsx +61 -0
  33. package/.dist/typings/useModelSelector.d.ts +0 -27
  34. package/.dist/typings/viewBinderConnectable.d.ts +0 -15
  35. package/src/viewBinderConnectable.tsx +0 -54
  36. package/tests/connectableComponentLegacyTests.tsx +0 -405
  37. package/tests/testApi/viewMetadata.tsx +0 -46
@@ -5,21 +5,12 @@ import {Router, utils} from 'esp-js';
5
5
  import {EspModelContextProvider, useGetModelId} from './espModelContextProvider';
6
6
  import {createViewForModel} from './viewBindingDecorator';
7
7
  import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
8
- import {modelSelectorOptions, useModelSelector} from './useModelSelector';
8
+ import {syncModelWithSelectorOptions, useSyncModelWithSelector} from './useSyncModelWithSelector';
9
9
 
10
- /**
11
- * @deprecated
12
- */
13
10
  export type CreatePublishEventProps<TPublishEventProps> = (publishModelEvent: (eventType: string, event: any) => void) => TPublishEventProps;
14
11
 
15
- /**
16
- * @deprecated
17
- */
18
12
  export type MapModelToProps<TModel, TModelMappedToProps, TPublishEventProps = {}> = (model: TModel, publishEventProps: TPublishEventProps) => TModelMappedToProps;
19
13
 
20
- /**
21
- * @deprecated
22
- */
23
14
  export interface ConnectableComponentProps<TModel = {}, TPublishEventProps = {}, TModelMappedToProps = {}> {
24
15
  modelId?: string;
25
16
  viewContext?: string;
@@ -29,9 +20,6 @@ export interface ConnectableComponentProps<TModel = {}, TPublishEventProps = {},
29
20
  [key: string]: any; // ...rest props, including the result of mapPublish and mapPublish if 'connect' was used
30
21
  }
31
22
 
32
- /**
33
- * @deprecated
34
- */
35
23
  export interface ConnectableComponentChildProps<TModel = object> {
36
24
  modelId: string;
37
25
  model: TModel;
@@ -47,7 +35,6 @@ const getChildProps = <TModel, TModelMappedToProps, TPublishEventProps>(
47
35
  mapModelToProps: MapModelToProps<TModel, TModelMappedToProps, TPublishEventProps>,
48
36
  publishEventProps: TPublishEventProps
49
37
  ): ConnectableComponentChildProps<TModel> => {
50
- // consume what this component owns, and let the rest end up in `...rest`
51
38
  const model = tryGetPolimerImmutableModel<TModel>(initialModel);
52
39
  let childProps = {
53
40
  modelId,
@@ -65,10 +52,6 @@ const getChildProps = <TModel, TModelMappedToProps, TPublishEventProps>(
65
52
  return childProps;
66
53
  };
67
54
 
68
- /**
69
- * @deprecated - use ViewBinderConnectable and ESP hooks if you need to dynamically bind a view to a model
70
- * or useModelSelector with other ESP hooks for direct model subscription.
71
- */
72
55
  export const ConnectableComponent = <TModel = {}, TPublishEventProps = {}, TModelMappedToProps = {}>(
73
56
  {
74
57
  modelId,
@@ -96,9 +79,9 @@ export const ConnectableComponent = <TModel = {}, TPublishEventProps = {}, TMode
96
79
  },
97
80
  [router, modelId]
98
81
  );
99
- const model = useModelSelector<TModel, TModel>(
82
+ const model = useSyncModelWithSelector<TModel, TModel>(
100
83
  m => m,
101
- modelSelectorOptions()
84
+ syncModelWithSelectorOptions()
102
85
  .setModelId(modelId)
103
86
  .setTryPreSelectPolimerImmutableModel(false)
104
87
  );
@@ -5,52 +5,60 @@ import {useRouter} from './espRouterContextProvider';
5
5
 
6
6
  const _log = Logger.create('EspModelContextProvider');
7
7
 
8
- export type GetModelIdDelegate = () => string;
9
- export const GetModelIdContext = createContext<GetModelIdDelegate>(null);
8
+ export const GetModelIdContext = createContext<string>(null);
10
9
  /**
11
- * Returns a function which will return the ID of the model currently being rendered.
10
+ * Returns a function to get the ID of the model connected at a higher point in the V-DOM.
11
+ *
12
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
12
13
  */
13
- export const useGetModelId = () => useContext(GetModelIdContext)();
14
+ export const useGetModelId = () => useContext(GetModelIdContext);
14
15
 
15
- export type GetModelDelegate = <TModel = any, >() => TModel;
16
- export const GetModelContext = createContext<GetModelDelegate>(null);
16
+ export const GetModelContext = createContext<object>(null);
17
17
  /**
18
- * Returns a function which will return the model set at last dispatch.
18
+ * Returns a function which will return the model connected at a higher point in the V-DOM.
19
+ *
20
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
19
21
  */
20
- export const useGetModel = () => useContext(GetModelContext)();
22
+ export const useGetModel = <TModel,>() => useContext(GetModelContext) as TModel;
21
23
 
22
24
  export type PublishModelEventDelegate = (eventType: string, event: any) => void;
23
25
  export const PublishModelEventContext = createContext<PublishModelEventDelegate>(null);
24
26
  /**
25
- * Returns a function which can be used to publish an event to the current model being rendered.
27
+ * Returns a function which can be used to publish an event to the model connected at a higher point in the V-DOM.
28
+ *
29
+ * Effectively, this is a version of usePublishEvent() which closes over the relevant modelId.
26
30
  *
27
- * Effectively, this is a version of usePublishEvent() which closes over the current modelId.
31
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
28
32
  */
29
33
  export const usePublishModelEvent = () => useContext(PublishModelEventContext);
30
34
 
31
35
  export type PublishModelEventWithEntityKeyDelegate = (entityKey: string, eventType: string, event: any) => void;
32
36
  export const PublishModelEventWithEntityKeyContext = createContext<PublishModelEventWithEntityKeyDelegate>(null);
33
37
  /**
34
- * Returns a function which can be used to publish an event to the current model being rendered, allows an entityKey to be specified.
38
+ * Returns a function which can be used to publish an event to the model connected at a higher point in the V-DOM, allows an entityKey to be specified.
35
39
  *
36
- * Effectively, this is a version of usePublishEvent() which closes over the current modelId.
40
+ * Effectively, this is a version of usePublishEvent() which closes over the modelId.
41
+ *
42
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
37
43
  */
38
44
  export const usePublishModelEventWithEntityKey = () => useContext(PublishModelEventWithEntityKeyContext);
39
45
 
40
46
  export interface EspModelContextProviderProps {
41
47
  modelId: string;
42
- model?: unknown;
48
+ model?: any;
43
49
  }
44
50
 
51
+ /**
52
+ * Sets up various ESP context so ESP hooks are available below this point in the V-DOM
53
+ *
54
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node.
55
+ * @param modelId
56
+ * @param children
57
+ * @param model
58
+ * @constructor
59
+ */
45
60
  export const EspModelContextProvider = ({modelId, children, model}: PropsWithChildren<EspModelContextProviderProps>) => {
46
61
  const router = useRouter();
47
- const getModelId: () => string = useCallback(() => {
48
- return modelId;
49
- }, [router, modelId]);
50
- const getModel: () => any = useCallback(() => {
51
- warnIfModelAccessedOutSideDispatchLoop(router, modelId);
52
- return model;
53
- }, [model, router, modelId]);
54
62
  const publishModelEvent: PublishModelEventDelegate = useCallback((eventType: string, event: any) => {
55
63
  router.publishEvent(modelId, eventType, event);
56
64
  }, [router, modelId]);
@@ -58,38 +66,14 @@ export const EspModelContextProvider = ({modelId, children, model}: PropsWithChi
58
66
  router.publishEvent(new DefaultModelAddress(modelId, entityKey), eventType, event);
59
67
  }, [router, modelId]);
60
68
  return (
61
- <GetModelIdContext.Provider value={getModelId}>
69
+ <GetModelIdContext.Provider value={modelId}>
62
70
  <PublishModelEventContext.Provider value={publishModelEvent}>
63
71
  <PublishModelEventWithEntityKeyContext.Provider value={publishModelEventWithEntityKey}>
64
- <GetModelContext.Provider value={getModel}>
72
+ <GetModelContext.Provider value={model}>
65
73
  {children}
66
74
  </GetModelContext.Provider>
67
75
  </PublishModelEventWithEntityKeyContext.Provider>
68
76
  </PublishModelEventContext.Provider>
69
77
  </GetModelIdContext.Provider>
70
78
  );
71
- };
72
-
73
- const warnIfModelAccessedOutSideDispatchLoop = (router: Router, modelId: string) => {
74
- if (process.env.NODE_ENV === 'production') {
75
- return;
76
- }
77
- if (utils.stringIsEmpty(modelId)) {
78
- return;
79
- }
80
- let isDispatchModelUpdateStatus = router.isModelDispatchStatus(modelId, Status.DispatchModelUpdates);
81
- if (!isDispatchModelUpdateStatus) {
82
- let stack: string | undefined = undefined;
83
- try {
84
- // noinspection ExceptionCaughtLocallyJS
85
- throw new Error();
86
- } catch (e) {
87
- stack = (e as Error).stack;
88
- }
89
- _log.warn(
90
- `EspModelContextProvider useGetModelId has been invoked outside of the models (${modelId}) dispatch loop.` +
91
- `This may have unknown state state issues.` +
92
- stack
93
- );
94
- }
95
79
  };
@@ -23,13 +23,13 @@ import {PropsWithChildren, createContext, useContext, useCallback} from 'react';
23
23
  export const RouterContext = createContext<Router>(null);
24
24
 
25
25
  /**
26
- * Get the esp Router from the RouterContext
26
+ * Get the esp Router from context.
27
27
  *
28
- * To use this, please ensure your V-DOM has the EspRouterContext at a higher node:
28
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node:
29
29
  *
30
- * <EspRouterContext router={router}>
30
+ * <EspRouterContextProvider router={router}>
31
31
  * <YourComponents />
32
- * </EspRouterContext>
32
+ * </EspRouterContextProvider>
33
33
  */
34
34
  export const useRouter = () => {
35
35
  const context: Router = useContext(RouterContext);
@@ -45,7 +45,7 @@ export const PublishEventContext = createContext<PublishEventDelegate>(null);
45
45
  /**
46
46
  * Returns a function which can be used to publish an event.
47
47
  *
48
- * To use this, please ensure your V-DOM has the EspRouterContext at a higher node:
48
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node:
49
49
  *
50
50
  * <EspRouterContextProvider router={router}>
51
51
  * <YourComponents />
package/src/index.ts CHANGED
@@ -21,10 +21,6 @@
21
21
  import './polimer/polimerModelBuilderExtentsions';
22
22
 
23
23
  export {ViewBinder} from './viewBinder';
24
- export {
25
- ViewBinderConnectableProps,
26
- ViewBinderConnectable
27
- } from './viewBinderConnectable';
28
24
  export {viewBinding, DEFAULT_VIEW_KEY} from './viewBindingDecorator';
29
25
  export {
30
26
  GetEspPolimerImmutableModelMetadata,
@@ -44,13 +40,12 @@ export {
44
40
  ConnectableComponent,
45
41
  } from './connectableComponent';
46
42
  export {
47
- UseModelSelector,
48
- useModelSelector,
49
- EditableModelSelectorOptions,
50
- modelSelectorOptions,
51
- ModelSelectorOptions,
52
- ModelSelectorEqualityFn,
53
- } from './useModelSelector';
43
+ useSyncModelWithSelector,
44
+ SyncModelWithSelectorOptionsBuilder,
45
+ syncModelWithSelectorOptions,
46
+ SyncModelWithSelectorOptions,
47
+ SyncModelWithSelectorEqualityFn,
48
+ } from './useSyncModelWithSelector';
54
49
  export {
55
50
  RouterProvider,
56
51
  RouterProviderProps,
@@ -64,10 +59,8 @@ export {
64
59
  } from './espRouterContextProvider';
65
60
  export {
66
61
  useGetModelId,
67
- GetModelIdDelegate,
68
62
  GetModelIdContext,
69
63
  useGetModel,
70
- GetModelDelegate,
71
64
  GetModelContext,
72
65
  PublishModelEventDelegate,
73
66
  PublishModelEventContext,
@@ -5,30 +5,52 @@ import {useRouter} from './espRouterContextProvider';
5
5
  import {useGetModelId} from './espModelContextProvider';
6
6
  import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
7
7
 
8
- export type ModelSelectorEqualityFn<T> = (last: T, next: T) => boolean;
8
+ export type SyncModelWithSelectorEqualityFn<T> = (last: T, next: T) => boolean;
9
9
 
10
10
  /**
11
+ * Options affecting the subscription of the model to the Router.
12
+ *
13
+ * Use syncModelWithSelectorOptions() to create an instance of this type with sensible defaults.
14
+ *
11
15
  * @param modelId - the modelId of the model to be observed via the esp Router.
12
16
  * @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
17
  * @param equalityFn - Equality function which will be applied against TSelected, defaults to instance equality (a === b).
14
18
  */
15
- export type ModelSelectorOptions<TSelected> = {
19
+ export type SyncModelWithSelectorOptions<TSelected> = {
16
20
  modelId?: string,
17
21
  tryPreSelectPolimerImmutableModel: boolean,
18
- equalityFn: ModelSelectorEqualityFn<TSelected>
22
+ equalityFn: SyncModelWithSelectorEqualityFn<TSelected>
19
23
  };
20
24
 
21
- export interface EditableModelSelectorOptions<TSelected> extends ModelSelectorOptions<TSelected> {
25
+ /**
26
+ * Convenience API to build SyncModelWithSelectorOptions<TSelected>, has sensible defaulting.
27
+ */
28
+ export interface SyncModelWithSelectorOptionsBuilder<TSelected> extends SyncModelWithSelectorOptions<TSelected> {
29
+ /**
30
+ * Sets the model ID
31
+ * @param modelId - default if unset: undefined
32
+ */
22
33
  setModelId(modelId: string): this;
23
34
 
35
+ /**
36
+ * If the model is a PolimerModel and this set true, PolimerModel.getImmutableModel() will be selected by default.
37
+ * @param value - default if unset: true
38
+ */
24
39
  setTryPreSelectPolimerImmutableModel(value: boolean): this;
25
40
 
41
+ /**
42
+ * Equality function used when comparing the last TSelected with the next.
43
+ * @param fn - default if unset: obj instance equality (e.g. a===b)
44
+ */
26
45
  setEqualityFn(fn: (a: TSelected, b: TSelected) => boolean): this;
27
46
  }
28
47
 
29
- export const modelSelectorOptions = <TSelected>() => {
48
+ /**
49
+ * Convenience API to create SyncModelWithSelectorOptions
50
+ */
51
+ export const syncModelWithSelectorOptions = <TSelected>() => {
30
52
  let modelId = undefined;
31
- let equalityFn: ModelSelectorEqualityFn<TSelected> = (a: TSelected, b: TSelected) => a === b;
53
+ let equalityFn: SyncModelWithSelectorEqualityFn<TSelected> = (a: TSelected, b: TSelected) => a === b;
32
54
  let tryPreSelectPolimerImmutableModel = true;
33
55
  return {
34
56
  get modelId() {
@@ -41,7 +63,7 @@ export const modelSelectorOptions = <TSelected>() => {
41
63
  get equalityFn() {
42
64
  return equalityFn;
43
65
  },
44
- setEqualityFn(value: ModelSelectorEqualityFn<TSelected>) {
66
+ setEqualityFn(value: SyncModelWithSelectorEqualityFn<TSelected>) {
45
67
  equalityFn = value;
46
68
  return this;
47
69
  },
@@ -52,27 +74,36 @@ export const modelSelectorOptions = <TSelected>() => {
52
74
  tryPreSelectPolimerImmutableModel = value;
53
75
  return this;
54
76
  }
55
- } as EditableModelSelectorOptions<TSelected>;
77
+ } as SyncModelWithSelectorOptionsBuilder<TSelected>;
56
78
  };
57
79
 
58
- export type UseModelSelector = <TModel, TSelected>(
59
- selector: (model: TModel) => TSelected,
60
- options?: ModelSelectorOptions<TSelected>
61
- ) => TSelected;
80
+ const checkArguments = (selector: (model: any) => any, options: SyncModelWithSelectorOptions<any> ) => {
81
+ if (!utils.isFunction(selector)) {
82
+ throw new Error('You must pass a selector function to useSyncModelWithSelector');
83
+ }
84
+ if (!utils.isObject(options)) {
85
+ throw new Error('You must provide options when using useSyncModelWithSelector');
86
+ }
87
+ if (!utils.isFunction(options.equalityFn)) {
88
+ throw new Error('You must provide an equalityFn when using useSyncModelWithSelector');
89
+ }
90
+ };
62
91
 
63
92
  /**
64
93
  * A hook which returns model state from the esp Router.
65
94
  *
66
95
  * This hooks wih observe updates and re-render the component if the model changes.
67
96
  *
97
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node, and optionally EspModelContextProvider.
98
+ *
68
99
  * @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.
69
100
  * @param options
70
101
  */
71
- export const useModelSelector: UseModelSelector = <TModel, TSelected>(
102
+ export const useSyncModelWithSelector = <TModel, TSelected>(
72
103
  selector: (model: TModel) => TSelected,
73
- options: ModelSelectorOptions<TSelected> = modelSelectorOptions<TSelected>()
74
- ) => {
75
- Guard.isFunction(selector, 'You must pass a selector function to connectSelector');
104
+ options: SyncModelWithSelectorOptions<TSelected> = syncModelWithSelectorOptions<TSelected>()
105
+ ): TSelected => {
106
+ checkArguments(selector, options);
76
107
  const router = useRouter();
77
108
  const modelId = options?.modelId || useGetModelId();
78
109
  const tryPreSelectPolimerImmutableModel = options?.tryPreSelectPolimerImmutableModel;
@@ -22,13 +22,24 @@ import {useRouter} from './espRouterContextProvider';
22
22
 
23
23
  export interface ViewBinderProps {
24
24
  model: any;
25
- viewContext: string;
25
+ viewContext?: string;
26
+ /**
27
+ * ...rest props, these will be passed to the child
28
+ */
29
+ [key: string]: any;
26
30
  }
27
31
 
32
+ /**
33
+ * Takes a model with a @viewBinding decorator and dynamically crates the view specified by the decorator
34
+ */
28
35
  export const ViewBinder: React.FC<ViewBinderProps> = ({model, viewContext, ...rest}) => {
29
36
  if (model) {
30
37
  const router = useRouter();
31
- const newProps = Object.assign({}, {model, router}, rest);
38
+ const newProps = {
39
+ model,
40
+ router,
41
+ ...rest
42
+ };
32
43
  return createViewForModel(
33
44
  model,
34
45
  newProps,
@@ -40,7 +40,7 @@ function getMetadata(target) {
40
40
  * @param displayContext
41
41
  * @param view
42
42
  */
43
- export function createViewForModel(model: any, props, displayContext: string, view: React.ComponentType) {
43
+ export function createViewForModel(model: any, props: object, displayContext: string, view: React.ComponentType) {
44
44
  let finalView: React.ComponentType = view; // default to that passed in, if any.
45
45
 
46
46
  // displayContext = displayContext || DEFAULT_VIEW_KEY;
@@ -77,7 +77,7 @@ export function createViewForModel(model: any, props, displayContext: string, vi
77
77
  export function viewBinding(view: any, displayContext: string = DEFAULT_VIEW_KEY) {
78
78
  Guard.isDefined(view, 'view must be defined');
79
79
  Guard.isString(displayContext, 'displayContext must be a string');
80
- return function (target) {
80
+ return function (target: any) {
81
81
  let viewMetadata = getMetadata(target);
82
82
  if (viewMetadata.hasRegisteredViewContext(displayContext)) {
83
83
  throw new Error(`Context ${displayContext} already registered for view`);