esp-js-react 8.0.1-next.0 → 8.0.3-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 (42) hide show
  1. package/.dist/esp-react.js +68 -104
  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 +24 -7
  8. package/.dist/typings/espRouterContextProvider.d.ts +5 -5
  9. package/.dist/typings/index.d.ts +2 -3
  10. package/.dist/typings/polimer/getEspPolimerImmutableModel.d.ts +21 -0
  11. package/.dist/typings/useModelSelector.d.ts +25 -1
  12. package/.dist/typings/viewBinder.d.ts +8 -1
  13. package/.dist/typings/viewBindingDecorator.d.ts +1 -1
  14. package/package.json +4 -4
  15. package/src/connect.tsx +2 -6
  16. package/src/connectableComponent.tsx +2 -19
  17. package/src/espModelContextProvider.tsx +26 -9
  18. package/src/espRouterContextProvider.tsx +5 -5
  19. package/src/index.ts +5 -9
  20. package/src/polimer/getEspPolimerImmutableModel.ts +50 -0
  21. package/src/useModelSelector.ts +31 -7
  22. package/src/viewBinder.tsx +13 -2
  23. package/src/viewBindingDecorator.ts +2 -2
  24. package/tests/connectableComponentTests.tsx +496 -0
  25. package/tests/espModelContextProviderTests.tsx +142 -0
  26. package/tests/espRouterContextProviderTests.tsx +54 -0
  27. package/tests/indexTests.ts +24 -91
  28. package/tests/testApi/asserts.ts +90 -0
  29. package/tests/testApi/testApi.tsx +100 -0
  30. package/tests/testApi/testModel.ts +44 -0
  31. package/tests/testApi/useStoreReceivedProps.ts +14 -0
  32. package/tests/testApi/viewFactory.tsx +31 -0
  33. package/tests/useModelSelectorTests.tsx +47 -153
  34. package/tests/viewBinderTests.tsx +61 -0
  35. package/.dist/typings/polimer/getEspReactRenderModel.d.ts +0 -21
  36. package/.dist/typings/viewBinderConnectable.d.ts +0 -15
  37. package/src/polimer/getEspReactRenderModel.ts +0 -50
  38. package/src/viewBinderConnectable.tsx +0 -54
  39. package/tests/connectableComponentLegacyTests.tsx +0 -405
  40. /package/.dist/typings/polimer/{polimerExtentsions.d.ts → polimerModelBuilderExtentsions.d.ts} +0 -0
  41. /package/src/polimer/{polimerExtentsions.ts → polimerModelBuilderExtentsions.ts} +0 -0
  42. /package/tests/{routerSpy.ts → testApi/routerSpy.ts} +0 -0
package/src/connect.tsx CHANGED
@@ -1,15 +1,11 @@
1
1
  import * as React from 'react';
2
2
  import {ConnectableComponent, ConnectableComponentProps, CreatePublishEventProps, MapModelToProps} from './connectableComponent';
3
3
 
4
- /**
5
- * @deprecated
6
- */
7
4
  export type ConnectableComponentFactory<TModel, TPublishEventProps, TModelMappedToProps = {}> = (view: React.ComponentType) => (props: ConnectableComponentProps<TModel, TPublishEventProps, TModelMappedToProps>) => React.JSX.Element;
8
5
 
9
6
  /**
10
- * @deprecated
11
- * @param mapModelToProps
12
- * @param createPublishEventProps
7
+ * @param mapModelToProps - maps the model to a different structure, that structure is sent as props to the view.
8
+ * @param createPublishEventProps - creates functions to publish events, the structure is sent as props to the view.
13
9
  */
14
10
  export const connect = function <TModel, TPublishEventProps, TModelMappedToProps = {}>(
15
11
  mapModelToProps?: MapModelToProps<TModel, TModelMappedToProps, TPublishEventProps>,
@@ -4,22 +4,13 @@ import {useMemo} from 'react';
4
4
  import {Router, utils} from 'esp-js';
5
5
  import {EspModelContextProvider, useGetModelId} from './espModelContextProvider';
6
6
  import {createViewForModel} from './viewBindingDecorator';
7
- import {tryGetRenderModel} from './polimer/getEspReactRenderModel';
7
+ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
8
8
  import {modelSelectorOptions, useModelSelector} from './useModelSelector';
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,8 +35,7 @@ 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
- const model = tryGetRenderModel<TModel>(initialModel);
38
+ const model = tryGetPolimerImmutableModel<TModel>(initialModel);
52
39
  let childProps = {
53
40
  modelId,
54
41
  router: router,
@@ -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,
@@ -8,32 +8,40 @@ const _log = Logger.create('EspModelContextProvider');
8
8
  export type GetModelIdDelegate = () => string;
9
9
  export const GetModelIdContext = createContext<GetModelIdDelegate>(null);
10
10
  /**
11
- * Returns a function which will return the ID of the model currently being rendered.
11
+ * Returns a function to get the ID of the model connected at a higher point in the V-DOM.
12
+ *
13
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
12
14
  */
13
15
  export const useGetModelId = () => useContext(GetModelIdContext)();
14
16
 
15
17
  export type GetModelDelegate = <TModel = any, >() => TModel;
16
18
  export const GetModelContext = createContext<GetModelDelegate>(null);
17
19
  /**
18
- * Returns a function which will return the model set at last dispatch.
20
+ * Returns a function which will return the model connected at a higher point in the V-DOM.
21
+ *
22
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
19
23
  */
20
- export const useGetModel = () => useContext(GetModelContext)();
24
+ export const useGetModel = <TModel,>() => useContext(GetModelContext)() as TModel;
21
25
 
22
26
  export type PublishModelEventDelegate = (eventType: string, event: any) => void;
23
27
  export const PublishModelEventContext = createContext<PublishModelEventDelegate>(null);
24
28
  /**
25
- * Returns a function which can be used to publish an event to the current model being rendered.
29
+ * Returns a function which can be used to publish an event to the model connected at a higher point in the V-DOM.
26
30
  *
27
- * Effectively, this is a version of usePublishEvent() which closes over the current modelId.
31
+ * Effectively, this is a version of usePublishEvent() which closes over the relevant modelId.
32
+ *
33
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
28
34
  */
29
35
  export const usePublishModelEvent = () => useContext(PublishModelEventContext);
30
36
 
31
37
  export type PublishModelEventWithEntityKeyDelegate = (entityKey: string, eventType: string, event: any) => void;
32
38
  export const PublishModelEventWithEntityKeyContext = createContext<PublishModelEventWithEntityKeyDelegate>(null);
33
39
  /**
34
- * Returns a function which can be used to publish an event to the current model being rendered, allows an entityKey to be specified.
40
+ * 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.
41
+ *
42
+ * Effectively, this is a version of usePublishEvent() which closes over the modelId.
35
43
  *
36
- * Effectively, this is a version of usePublishEvent() which closes over the current modelId.
44
+ * To use this, please ensure your V-DOM has the EspModelContextProvider at a higher node.
37
45
  */
38
46
  export const usePublishModelEventWithEntityKey = () => useContext(PublishModelEventWithEntityKeyContext);
39
47
 
@@ -42,6 +50,15 @@ export interface EspModelContextProviderProps {
42
50
  model?: unknown;
43
51
  }
44
52
 
53
+ /**
54
+ * Sets up various ESP context so ESP hooks are available below this point in the V-DOM
55
+ *
56
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node.
57
+ * @param modelId
58
+ * @param children
59
+ * @param model
60
+ * @constructor
61
+ */
45
62
  export const EspModelContextProvider = ({modelId, children, model}: PropsWithChildren<EspModelContextProviderProps>) => {
46
63
  const router = useRouter();
47
64
  const getModelId: () => string = useCallback(() => {
@@ -87,8 +104,8 @@ const warnIfModelAccessedOutSideDispatchLoop = (router: Router, modelId: string)
87
104
  stack = (e as Error).stack;
88
105
  }
89
106
  _log.warn(
90
- `EspModelContextProvider useGetModelId has been invoked outside of the models (${modelId}) dispatch loop.` +
91
- `This may have unknown state state issues.` +
107
+ `EspModelContextProvider useGetModelId has been invoked outside of the models (${modelId}) dispatch loop. ` +
108
+ `This may have unknown state issues.` +
92
109
  stack
93
110
  );
94
111
  }
@@ -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
@@ -18,19 +18,15 @@
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
- export {
25
- ViewBinderConnectableProps,
26
- ViewBinderConnectable
27
- } from './viewBinderConnectable';
28
24
  export {viewBinding, DEFAULT_VIEW_KEY} from './viewBindingDecorator';
29
25
  export {
30
- GetEspReactRenderModelMetadata,
31
- GetEspReactRenderModelConsts,
32
- getEspReactRenderModel
33
- } from './polimer/getEspReactRenderModel';
26
+ GetEspPolimerImmutableModelMetadata,
27
+ GetEspPolimerImmutableModelConsts,
28
+ getEspPolimerImmutableModel
29
+ } from './polimer/getEspPolimerImmutableModel';
34
30
  export {createViewForModel} from './viewBindingDecorator';
35
31
  export {
36
32
  connect,
@@ -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
+ };
@@ -3,11 +3,15 @@ import {useSyncExternalStoreWithSelector} from 'use-sync-external-store/with-sel
3
3
  import {Guard, utils} from 'esp-js';
4
4
  import {useRouter} from './espRouterContextProvider';
5
5
  import {useGetModelId} from './espModelContextProvider';
6
- import {tryGetRenderModel} from './polimer/getEspReactRenderModel';
6
+ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel';
7
7
 
8
8
  export type ModelSelectorEqualityFn<T> = (last: T, next: T) => boolean;
9
9
 
10
10
  /**
11
+ * Options affecting the subscription of the model to the Router.
12
+ *
13
+ * Use modelSelectorOptions() 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).
@@ -18,14 +22,32 @@ export type ModelSelectorOptions<TSelected> = {
18
22
  equalityFn: ModelSelectorEqualityFn<TSelected>
19
23
  };
20
24
 
25
+ /**
26
+ * Convenience API to build ModelSelectorOptions<TSelected>, has sensible defaulting.
27
+ */
21
28
  export interface EditableModelSelectorOptions<TSelected> extends ModelSelectorOptions<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
 
48
+ /**
49
+ * Convenience API to create ModelSelectorOptions
50
+ */
29
51
  export const modelSelectorOptions = <TSelected>() => {
30
52
  let modelId = undefined;
31
53
  let equalityFn: ModelSelectorEqualityFn<TSelected> = (a: TSelected, b: TSelected) => a === b;
@@ -55,19 +77,21 @@ export const modelSelectorOptions = <TSelected>() => {
55
77
  } as EditableModelSelectorOptions<TSelected>;
56
78
  };
57
79
 
58
- export type UseModelSelector = <TModel, TSelected>(
59
- selector: (model: TModel) => TSelected,
60
- options?: ModelSelectorOptions<TSelected>
61
- ) => TSelected;
62
-
63
80
  /**
64
81
  * A hook which returns model state from the esp Router.
65
82
  *
66
83
  * This hooks wih observe updates and re-render the component if the model changes.
67
84
  *
85
+ * To use this, please ensure your V-DOM has the EspRouterContextProvider at a higher node, and optionally EspModelContextProvider.
86
+ *
68
87
  * @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
88
  * @param options
70
89
  */
90
+ export type UseModelSelector = <TModel, TSelected>(
91
+ selector: (model: TModel) => TSelected,
92
+ options?: ModelSelectorOptions<TSelected>
93
+ ) => TSelected;
94
+
71
95
  export const useModelSelector: UseModelSelector = <TModel, TSelected>(
72
96
  selector: (model: TModel) => TSelected,
73
97
  options: ModelSelectorOptions<TSelected> = modelSelectorOptions<TSelected>()
@@ -93,7 +117,7 @@ export const useModelSelector: UseModelSelector = <TModel, TSelected>(
93
117
  (m: any) => {
94
118
  // try and get a submodel to render
95
119
  const nextModel = tryPreSelectPolimerImmutableModel
96
- ? tryGetRenderModel(m)
120
+ ? tryGetPolimerImmutableModel(m)
97
121
  : m;
98
122
  // if the above didn't manage to get a submodel,
99
123
  // we need to mutate to force useSyncExternalStoreWithSelector to pick up the change
@@ -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`);