esp-js-react 8.0.2-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 (36) hide show
  1. package/.dist/esp-react.js +41 -77
  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 +0 -1
  10. package/.dist/typings/useModelSelector.d.ts +25 -1
  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 +0 -17
  16. package/src/espModelContextProvider.tsx +26 -9
  17. package/src/espRouterContextProvider.tsx +5 -5
  18. package/src/index.ts +0 -4
  19. package/src/useModelSelector.ts +29 -5
  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 +1 -2
  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 +6 -8
  32. package/tests/viewBinderTests.tsx +61 -0
  33. package/.dist/typings/viewBinderConnectable.d.ts +0 -15
  34. package/src/viewBinderConnectable.tsx +0 -54
  35. package/tests/connectableComponentLegacyTests.tsx +0 -405
  36. package/tests/testApi/viewMetadata.tsx +0 -46
@@ -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
@@ -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,
@@ -8,6 +8,10 @@ import {tryGetPolimerImmutableModel} from './polimer/getEspPolimerImmutableModel
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>()
@@ -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`);