@punica/form 1.2.0 → 2.1.0-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 (73) hide show
  1. package/dist/controller/index.d.ts +46 -51
  2. package/dist/decorator/Readers.d.ts +2 -2
  3. package/dist/decorator/Services.d.ts +2 -2
  4. package/dist/decorator/Starters.d.ts +2 -2
  5. package/dist/define/FormItem.d.ts +12 -6
  6. package/dist/define/FormItemProperty.d.ts +5 -5
  7. package/dist/define/FormProperty.d.ts +5 -4
  8. package/dist/define/decorator.d.ts +16 -0
  9. package/dist/define/index.d.ts +1 -0
  10. package/dist/index.d.ts +1 -0
  11. package/dist/index.js +620 -22
  12. package/dist/index.mjs +572 -0
  13. package/dist/metadata/index.d.ts +16 -0
  14. package/dist/model/command/item.d.ts +11 -5
  15. package/dist/model/command/service.d.ts +25 -10
  16. package/dist/model/constants/index.d.ts +13 -2
  17. package/dist/model/form/index.d.ts +9 -4
  18. package/dist/model/index.d.ts +0 -1
  19. package/dist/model/item/index.d.ts +41 -12
  20. package/dist/model/reader/index.d.ts +5 -1
  21. package/dist/model/service/index.d.ts +28 -10
  22. package/dist/reader/index.d.ts +10 -17
  23. package/dist/register/index.d.ts +26 -39
  24. package/dist/shared.d.ts +20 -0
  25. package/dist/utils/deepCopy.d.ts +1 -1
  26. package/dist/utils/devtools.d.ts +11 -70
  27. package/dist/utils/index.d.ts +2 -1
  28. package/dist/utils/path.d.ts +10 -0
  29. package/package.json +21 -11
  30. package/dist/controller/index.js +0 -238
  31. package/dist/decorator/Readers.js +0 -15
  32. package/dist/decorator/Services.js +0 -15
  33. package/dist/decorator/Starters.js +0 -15
  34. package/dist/decorator/index.js +0 -19
  35. package/dist/define/FormItem.js +0 -26
  36. package/dist/define/FormItemProperty.js +0 -21
  37. package/dist/define/FormProperty.js +0 -15
  38. package/dist/define/index.js +0 -12
  39. package/dist/model/command/index.js +0 -18
  40. package/dist/model/command/item.js +0 -2
  41. package/dist/model/command/service.js +0 -2
  42. package/dist/model/constants/index.js +0 -2
  43. package/dist/model/form/index.js +0 -2
  44. package/dist/model/index.js +0 -24
  45. package/dist/model/item/index.js +0 -2
  46. package/dist/model/reader/index.js +0 -2
  47. package/dist/model/service/index.js +0 -2
  48. package/dist/model/starter/index.js +0 -2
  49. package/dist/model/util/GetItem.d.ts +0 -9
  50. package/dist/model/util/GetItem.js +0 -2
  51. package/dist/model/util/WriteItems.d.ts +0 -8
  52. package/dist/model/util/WriteItems.js +0 -2
  53. package/dist/model/util/index.d.ts +0 -2
  54. package/dist/model/util/index.js +0 -18
  55. package/dist/reader/decorators/base/index.d.ts +0 -35
  56. package/dist/reader/decorators/base/index.js +0 -82
  57. package/dist/reader/decorators/readers/FormItemsReader.d.ts +0 -17
  58. package/dist/reader/decorators/readers/FormItemsReader.js +0 -42
  59. package/dist/reader/decorators/readers/ItemDataReader.d.ts +0 -24
  60. package/dist/reader/decorators/readers/ItemDataReader.js +0 -42
  61. package/dist/reader/decorators/readers/ItemInitializerReader.d.ts +0 -16
  62. package/dist/reader/decorators/readers/ItemInitializerReader.js +0 -34
  63. package/dist/reader/decorators/readers/index.d.ts +0 -3
  64. package/dist/reader/decorators/readers/index.js +0 -12
  65. package/dist/reader/index.js +0 -30
  66. package/dist/reader/reader/Reader.d.ts +0 -13
  67. package/dist/reader/reader/Reader.js +0 -19
  68. package/dist/reader/reader/index.d.ts +0 -1
  69. package/dist/reader/reader/index.js +0 -8
  70. package/dist/register/index.js +0 -72
  71. package/dist/utils/deepCopy.js +0 -45
  72. package/dist/utils/devtools.js +0 -136
  73. package/dist/utils/index.js +0 -18
@@ -1,73 +1,68 @@
1
- import { BaseListener } from '@punica/common';
2
- import { Form, FormEvents, FormItem, IServiceCommand, IServiceInitialize, IServiceControl } from '..';
1
+ import { Form, FormEventMap, FormItem, FormItemRegister, IService, ServiceRegistry } from '..';
2
+ export type FormControllerOptions = {
3
+ /** Identifies the form in developer tools. Defaults to the name of its class. */
4
+ name?: string;
5
+ /** The register whose form item types the form reports. */
6
+ register?: FormItemRegister;
7
+ };
8
+ /** A class whose instances are services. */
9
+ type ServiceClass<S extends IService> = new (...args: any[]) => S;
10
+ /** The keys of `ServiceRegistry` a service class is registered under. */
11
+ type RegistryKey<S> = {
12
+ [K in keyof ServiceRegistry<any, any>]: ServiceRegistry<any, any>[K] extends S ? S extends ServiceRegistry<any, any>[K] ? K : never : never;
13
+ }[keyof ServiceRegistry<any, any>];
3
14
  /**
4
- * Controller for managing a form and its associated services.
15
+ * A service bound to the entity and the item type of a form, when its class
16
+ * is in `ServiceRegistry`; the service as it is otherwise.
5
17
  */
6
- export declare class FormController<E, F extends FormItem<E>> extends BaseListener<FormEvents> {
18
+ type BoundService<S, E, F extends FormItem<E>> = [RegistryKey<S>] extends [
19
+ never
20
+ ] ? S : ServiceRegistry<E, F>[RegistryKey<S>];
21
+ /**
22
+ * Holds the state of a form and runs its readers, starters and services.
23
+ * The form is immutable: every change produces a new form object.
24
+ */
25
+ export declare class FormController<E extends object, F extends FormItem<E> = FormItem<E>> {
7
26
  #private;
8
- /**
9
- * Private constructor to prevent direct instantiation.
10
- */
11
27
  private constructor();
12
28
  /**
13
- * Static method to initialize the FormController with form data.
14
- * @param form The initial form data
15
- */
16
- static fromForm<E, F extends FormItem<E>>(form: Form<E, F>): Promise<FormController<E, F>>;
17
- /**
18
- * Static method to initialize the FormController with an entity.
19
- * @param entity The entity for the form
20
- */
21
- static fromEntity<E, F extends FormItem<E>>(entity: E): Promise<FormController<E, F>>;
22
- /**
23
- * Trigger a form event.
24
- * @param eventType The type of the event
25
- * @param data Data associated with the event
26
- */
27
- private fireEvent;
28
- /**
29
- * Send entity data to DevTools
30
- */
31
- private sendEntityToDevTools;
32
- /**
33
- * Create a command service for the form.
34
- * @returns A CommandService for the form
35
- */
36
- private createCommandService;
37
- /**
38
- * Registers form items by triggering the REGISTER_ITEMS event.
29
+ * Creates a controller for a form that is described as data.
39
30
  */
40
- private registerFormItems;
31
+ static fromForm<E extends object, F extends FormItem<E> = FormItem<E>>(form: Form<E, F>, options?: FormControllerOptions): Promise<FormController<E, F>>;
41
32
  /**
42
- * Maps form items to their properties.
33
+ * Creates a controller for an instance of a decorated form class.
43
34
  */
44
- private mapFormItems;
35
+ static fromEntity<E extends object, F extends FormItem<E> = FormItem<E>>(entity: E, options?: FormControllerOptions): Promise<FormController<E, F>>;
45
36
  /**
46
- * Initializes the services defined in the form data.
37
+ * The current form. A form object is never changed once it is returned:
38
+ * after `start()` and after every change this returns a new object.
47
39
  */
48
- private initializeServices;
40
+ getForm: () => Form<E, F>;
49
41
  /**
50
- * Executes the readers defined in the form data.
42
+ * Calls the listener after every change of the form.
43
+ * @returns A function that removes the listener
51
44
  */
52
- private runReaders;
45
+ subscribe: (listener: () => void) => (() => void);
53
46
  /**
54
- * Executes the starters defined in the form data.
47
+ * Listens to an event of the form.
48
+ * @returns A function that removes the handler
55
49
  */
56
- private runStarters;
50
+ on<K extends keyof FormEventMap<E, F>>(event: K, handler: (payload: FormEventMap<E, F>[K]) => void): () => void;
57
51
  /**
58
- * Keeps a deep copy of the form items for the initial state.
59
- * Services, readers and starters are shared, not copied.
52
+ * The service of a class listed in `@Services`, or of a subclass of it.
53
+ * @throws When the form is not started yet or has no service of the class
60
54
  */
61
- private deepCopyForm;
55
+ getService<S extends IService>(service: ServiceClass<S>): BoundService<S, E, F>;
62
56
  /**
63
- * Get services by their names.
64
- * Overloads to return a single item or an array based on provided names.
57
+ * Runs changes as one: subscribers and UPDATE_FORM listeners are notified
58
+ * once, after the function returned or the promise it returned settled.
65
59
  */
66
- getServices<T = IServiceInitialize<E, F> & IServiceControl & IServiceCommand>(serviceName: string): T;
67
- getServices<T = IServiceInitialize<E, F> & IServiceControl & IServiceCommand>(serviceName: string, ...additionalServiceNames: string[]): T[];
60
+ batch: <T>(change: () => T) => T;
68
61
  /**
69
- * Starts the form controller by executing all necessary steps to initialize the form.
70
- * @returns A promise that resolves when the form is fully initialized.
62
+ * Starts the form: runs its readers and starters and initializes its
63
+ * services.
64
+ * @returns The form
71
65
  */
72
66
  start(): Promise<Form<E, F>>;
73
67
  }
68
+ export {};
@@ -1,4 +1,4 @@
1
- import { FormItem, IReader } from '..';
1
+ import { FormClassDecorator, FormItem, IReader } from '..';
2
2
  /**
3
3
  * Constant for identifying form readers decorator.
4
4
  */
@@ -6,4 +6,4 @@ export declare const DECORATOR_READERS = "form-readers";
6
6
  /**
7
7
  * Decorator for adding readers to a form class.
8
8
  */
9
- export declare const Readers: <E, F extends FormItem<E>>(data: IReader<E, F>[]) => ClassDecorator;
9
+ export declare const Readers: <E, F extends FormItem<E>>(data: Array<IReader<E, F>>) => FormClassDecorator;
@@ -1,4 +1,4 @@
1
- import { IService } from '..';
1
+ import { FormClassDecorator, IService } from '..';
2
2
  /**
3
3
  * Constant for identifying form services decorator.
4
4
  */
@@ -6,4 +6,4 @@ export declare const DECORATOR_SERVICES = "form-services";
6
6
  /**
7
7
  * Decorator for adding services to a form class.
8
8
  */
9
- export declare const Services: (data: Array<IService>) => ClassDecorator;
9
+ export declare const Services: (data: Array<IService | (new () => IService)>) => FormClassDecorator;
@@ -1,4 +1,4 @@
1
- import { FormItem, IStarter } from '..';
1
+ import { FormClassDecorator, FormItem, IStarter } from '..';
2
2
  /**
3
3
  * Constant for identifying form starters decorator.
4
4
  */
@@ -6,4 +6,4 @@ export declare const DECORATOR_STARTERS = "form-starters";
6
6
  /**
7
7
  * Decorator for adding starters to a form class.
8
8
  */
9
- export declare const Starters: <E, F extends FormItem<E>>(data: IStarter<E, F>[]) => ClassDecorator;
9
+ export declare const Starters: <E, F extends FormItem<E>>(data: Array<IStarter<E, F>>) => FormClassDecorator;
@@ -1,9 +1,15 @@
1
- import { IPropertyDecorator } from '@punica/common';
1
+ import { FormItemRegister, Renderer } from '../register';
2
+ import { FormPropertyDecorator } from './decorator';
3
+ /** The key the form items of a class are stored under. */
4
+ export declare const FORM_ITEMS = "form-items";
2
5
  /**
3
- * Defines a form item with the specified type and renderer.
4
- * @param {string} type - Type of the form item.
5
- * @param {Function} renderer - Renderer function for the form item.
6
- * @returns {IPropertyDecorator<T>} - Decorator function.
6
+ * Defines a form item type: registers its renderer and returns the property
7
+ * decorator that turns a property of a form class into an item of that type.
8
+ * @param type - The form item type
9
+ * @param renderer - What renders items of the type; Punica Form only stores it
10
+ * @param options.register - The register to use instead of the default one
7
11
  */
8
- declare const defineFormItem: <T>(type: string, renderer: (props: T) => any) => IPropertyDecorator<T>;
12
+ declare const defineFormItem: <T extends object>(type: string, renderer: Renderer, options?: {
13
+ register?: FormItemRegister;
14
+ }) => ((data: T) => FormPropertyDecorator);
9
15
  export default defineFormItem;
@@ -1,8 +1,8 @@
1
- import { IPropertyDecorator } from '@punica/common';
1
+ import { FormPropertyDecorator } from './decorator';
2
2
  /**
3
- * Defines a form item with the specified type and renderer.
4
- * @param {string} type - Type of the form item.
5
- * @returns {IPropertyDecorator<T>} - Decorator function.
3
+ * Defines a property decorator that stores data for a property of a form
4
+ * class. Read it back in a reader with `getFormItemProperties(entity, key)`.
5
+ * @param key - Identifies the data
6
6
  */
7
- declare const defineFormItemProperty: <T>(type: string) => IPropertyDecorator<T>;
7
+ declare const defineFormItemProperty: <T>(key: string) => ((data: T) => FormPropertyDecorator);
8
8
  export default defineFormItemProperty;
@@ -1,7 +1,8 @@
1
+ import { FormClassDecorator } from './decorator';
1
2
  /**
2
- * Defines a form property with the specified type.
3
- * @param {string} type - Type of the form property.
4
- * @returns {ClassDecorator<T>} - Decorator function.
3
+ * Defines a class decorator that stores data on a form class. Read it back
4
+ * in a reader with `getFormProperty(entity, key)`.
5
+ * @param key - Identifies the data
5
6
  */
6
- declare const defineFormProperty: <T>(type: string) => (data: T) => ClassDecorator;
7
+ declare const defineFormProperty: <T>(key: string) => ((data: T) => FormClassDecorator);
7
8
  export default defineFormProperty;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Decorators that work with both decorator implementations of TypeScript:
3
+ * the legacy one (`experimentalDecorators`) and the standard one.
4
+ */
5
+ /** A class decorator. Both implementations pass the class first. */
6
+ export type FormClassDecorator = (target: object, context?: ClassDecoratorContext) => void;
7
+ /**
8
+ * A property decorator: `(prototype, propertyKey)` for the legacy
9
+ * implementation, `(undefined, context)` for the standard one.
10
+ */
11
+ export type FormPropertyDecorator = (target: object | undefined, context: string | symbol | ClassFieldDecoratorContext) => void;
12
+ /**
13
+ * Creates a property decorator.
14
+ * @param register - Called with the class and the name of the decorated property
15
+ */
16
+ export declare const propertyDecorator: (register: (target: object, property: string) => void) => FormPropertyDecorator;
@@ -1,3 +1,4 @@
1
+ export type { FormClassDecorator, FormPropertyDecorator } from './decorator';
1
2
  export { default as defineFormItem } from './FormItem';
2
3
  export { default as defineFormItemProperty } from './FormItemProperty';
3
4
  export { default as defineFormProperty } from './FormProperty';
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './model';
2
+ export { getFormItemProperties, getFormProperty } from './metadata';
2
3
  export * from './define';
3
4
  export * from './decorator';
4
5
  export * from './register';