@punica/form 2.1.0 → 2.2.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.
@@ -0,0 +1,41 @@
1
+ import { FormClassDecorator, FormPropertyDecorator } from './decorator';
2
+ /** A property of a form defined with `defineForm`. */
3
+ export type FormField<T> = {
4
+ /** The value a new form starts with. */
5
+ value: T;
6
+ decorators: FormPropertyDecorator[];
7
+ };
8
+ /** The entity of a form defined with `defineForm`. */
9
+ export type FormValues<S extends Record<string, FormField<unknown>>> = {
10
+ -readonly [K in keyof S]: S[K]['value'];
11
+ };
12
+ /**
13
+ * A property of a form defined with `defineForm`: the value it starts with
14
+ * and the decorators a form class would have on the property.
15
+ *
16
+ * field('', Text({ label: 'Name' }))
17
+ * field<number | undefined>(undefined, NumberField({ label: 'Age' }))
18
+ */
19
+ export declare const field: <T>(value: T, ...decorators: FormPropertyDecorator[]) => FormField<T>;
20
+ /**
21
+ * Defines a form class without decorator syntax, for projects whose build
22
+ * does not compile decorators. The class is what a decorated class would
23
+ * be: give its instances to `FormController.fromEntity`.
24
+ *
25
+ * const UserForm = defineForm(
26
+ * { name: field('', Text({ label: 'Name' })) },
27
+ * Services([GetValues, SetValue])
28
+ * );
29
+ * type User = InstanceType<typeof UserForm>;
30
+ *
31
+ * const controller = await FormController.fromEntity(new UserForm());
32
+ * Decorators are applied like the ones written above a class or a property:
33
+ * the last one first. The value of a field is read once, when the form is
34
+ * defined, and copied for every instance; give values that differ between
35
+ * instances, such as the current date, to the constructor.
36
+ * @param fields - The properties of the form, in the order of its items
37
+ * @param decorators - What a form class would have above it: `Services`, `Readers`, …
38
+ * @returns A class whose constructor takes values that replace the initial
39
+ * ones; a value that is `undefined` leaves the initial one in place
40
+ */
41
+ export declare const defineForm: <S extends Record<string, FormField<unknown>>>(fields: S, ...decorators: FormClassDecorator[]) => new (values?: Partial<FormValues<S>>) => FormValues<S>;
@@ -1,4 +1,6 @@
1
1
  export type { FormClassDecorator, FormPropertyDecorator } from './decorator';
2
+ export type { FormField, FormValues } from './Form';
3
+ export { defineForm, field } from './Form';
2
4
  export { default as defineFormItem } from './FormItem';
3
5
  export { default as defineFormItemProperty } from './FormItemProperty';
4
6
  export { default as defineFormProperty } from './FormProperty';
package/dist/index.js CHANGED
@@ -50,14 +50,17 @@ __export(index_exports, {
50
50
  createInitialReader: () => createInitialReader,
51
51
  deepCopy: () => deepCopy,
52
52
  defaultFormItemRegister: () => defaultFormItemRegister,
53
+ defineForm: () => defineForm,
53
54
  defineFormItem: () => FormItem_default,
54
55
  defineFormItemProperty: () => FormItemProperty_default,
55
56
  defineFormProperty: () => FormProperty_default,
56
57
  disableDevTools: () => disableDevTools,
57
58
  enableDevTools: () => enableDevTools,
59
+ field: () => field,
58
60
  getFormItemProperties: () => getFormItemProperties,
59
61
  getFormProperty: () => getFormProperty,
60
62
  isDevToolsEnabled: () => isDevToolsEnabled,
63
+ isEqual: () => isEqual,
61
64
  readPropertyPath: () => readPropertyPath,
62
65
  writeToPropertyPath: () => writeToPropertyPath
63
66
  });
@@ -112,6 +115,61 @@ var getFormItemProperties = (entity, key) => {
112
115
  }, {});
113
116
  };
114
117
 
118
+ // lib/utils/deepCopy.ts
119
+ var deepCopy = (value, seen = /* @__PURE__ */ new WeakMap()) => {
120
+ if (typeof value !== "object" || value === null) {
121
+ return value;
122
+ }
123
+ if (seen.has(value)) {
124
+ return seen.get(value);
125
+ }
126
+ if (value instanceof Date) {
127
+ return new Date(value.getTime());
128
+ }
129
+ if (value instanceof RegExp) {
130
+ return new RegExp(value.source, value.flags);
131
+ }
132
+ if (value instanceof Map) {
133
+ const copy2 = /* @__PURE__ */ new Map();
134
+ seen.set(value, copy2);
135
+ value.forEach((v, k) => copy2.set(deepCopy(k, seen), deepCopy(v, seen)));
136
+ return copy2;
137
+ }
138
+ if (value instanceof Set) {
139
+ const copy2 = /* @__PURE__ */ new Set();
140
+ seen.set(value, copy2);
141
+ value.forEach((v) => copy2.add(deepCopy(v, seen)));
142
+ return copy2;
143
+ }
144
+ const copy = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
145
+ seen.set(value, copy);
146
+ for (const key of Object.keys(value)) {
147
+ copy[key] = deepCopy(value[key], seen);
148
+ }
149
+ return copy;
150
+ };
151
+
152
+ // lib/define/Form.ts
153
+ var field = (value, ...decorators) => ({ value, decorators });
154
+ var defineForm = (fields, ...decorators) => {
155
+ class DefinedForm {
156
+ constructor(values = {}) {
157
+ for (const [property, { value }] of Object.entries(fields)) {
158
+ this[property] = Object.prototype.hasOwnProperty.call(values, property) && values[property] !== void 0 ? values[property] : deepCopy(value);
159
+ }
160
+ }
161
+ }
162
+ for (const [property, { decorators: decorators2 }] of Object.entries(fields)) {
163
+ for (const decorate of [...decorators2].reverse()) {
164
+ decorate(DefinedForm.prototype, property);
165
+ }
166
+ }
167
+ for (const decorate of [...decorators].reverse()) {
168
+ decorate(DefinedForm);
169
+ }
170
+ return DefinedForm;
171
+ };
172
+
115
173
  // lib/register/index.ts
116
174
  var _items;
117
175
  var FormItemRegister = class {
@@ -269,8 +327,18 @@ var sendToDevTools = (formId, type, data, formItemKey) => {
269
327
  };
270
328
 
271
329
  // lib/controller/index.ts
330
+ var DOCS_URL = "https://form.punicalab.com";
272
331
  var formCount = 0;
273
- var _form, _initialItems, _itemsMap, _services, _started, _batching, _dirty, _epoch, _writes, _subscribers, _listeners, _initialEntity, _register, _name, _FormController_instances, mapItems_fn, _getItem, _setItems, notify_fn, _supersede, _emit, _createCommandItem, _createCommandService, sendEntityToDevTools_fn;
332
+ var INITIAL_STATE = {
333
+ dirty: false,
334
+ touched: false,
335
+ valid: true,
336
+ validating: false,
337
+ submitting: false,
338
+ submitCount: 0,
339
+ errors: []
340
+ };
341
+ var _form, _initialItems, _itemsMap, _services, _started, _batching, _pending, _epoch, _writes, _subscribers, _listeners, _initialEntity, _register, _name, _FormController_instances, mapItems_fn, _getItem, _setItems, _setState, deriveState_fn, commit_fn, notify_fn, _supersede, _emit, _createCommandItem, _createCommandService, sendEntityToDevTools_fn;
274
342
  var _FormController = class _FormController {
275
343
  constructor(form, entity, options) {
276
344
  __privateAdd(this, _FormController_instances);
@@ -281,7 +349,7 @@ var _FormController = class _FormController {
281
349
  __privateAdd(this, _services, /* @__PURE__ */ new Map());
282
350
  __privateAdd(this, _started, false);
283
351
  __privateAdd(this, _batching, 0);
284
- __privateAdd(this, _dirty, false);
352
+ __privateAdd(this, _pending, false);
285
353
  __privateAdd(this, _epoch, 0);
286
354
  __privateAdd(this, _writes, /* @__PURE__ */ new Map());
287
355
  __privateAdd(this, _subscribers, /* @__PURE__ */ new Set());
@@ -310,23 +378,24 @@ var _FormController = class _FormController {
310
378
  */
311
379
  this.batch = (change) => {
312
380
  const done = () => {
313
- if (--__privateWrapper(this, _batching)._ === 0 && __privateGet(this, _dirty)) {
314
- __privateSet(this, _dirty, false);
381
+ if (--__privateWrapper(this, _batching)._ === 0 && __privateGet(this, _pending)) {
382
+ __privateSet(this, _pending, false);
315
383
  __privateMethod(this, _FormController_instances, notify_fn).call(this);
316
384
  }
317
385
  };
318
386
  __privateWrapper(this, _batching)._++;
387
+ let result;
319
388
  try {
320
- const result = change();
321
- if (result instanceof Promise) {
322
- return result.finally(done);
323
- }
324
- done();
325
- return result;
389
+ result = change();
326
390
  } catch (error) {
327
391
  done();
328
392
  throw error;
329
393
  }
394
+ if (result instanceof Promise) {
395
+ return result.finally(done);
396
+ }
397
+ done();
398
+ return result;
330
399
  };
331
400
  __privateAdd(this, _getItem, (property) => {
332
401
  const index = __privateGet(this, _itemsMap).get(property);
@@ -339,18 +408,24 @@ var _FormController = class _FormController {
339
408
  for (const item of items) {
340
409
  const index = __privateGet(this, _itemsMap).get(item.property);
341
410
  if (index !== void 0) {
342
- next[index] = item;
411
+ const initial = __privateGet(this, _initialItems)[index];
412
+ const dirty = Boolean(initial) && !isEqual(item.value, initial.value);
413
+ next[index] = dirty === Boolean(item.dirty) ? item : { ...item, dirty };
343
414
  changed = true;
344
415
  }
345
416
  }
346
- if (!changed) {
347
- return;
417
+ if (changed) {
418
+ __privateMethod(this, _FormController_instances, commit_fn).call(this, {
419
+ ...__privateGet(this, _form),
420
+ items: next,
421
+ state: __privateMethod(this, _FormController_instances, deriveState_fn).call(this, next)
422
+ });
348
423
  }
349
- __privateSet(this, _form, { ...__privateGet(this, _form), items: next });
350
- if (__privateGet(this, _batching)) {
351
- __privateSet(this, _dirty, true);
352
- } else {
353
- __privateMethod(this, _FormController_instances, notify_fn).call(this);
424
+ });
425
+ __privateAdd(this, _setState, (patch) => {
426
+ const state = __privateMethod(this, _FormController_instances, deriveState_fn).call(this, __privateGet(this, _form).items, patch);
427
+ if (state !== __privateGet(this, _form).state) {
428
+ __privateMethod(this, _FormController_instances, commit_fn).call(this, { ...__privateGet(this, _form), state });
354
429
  }
355
430
  });
356
431
  __privateAdd(this, _supersede, (property) => {
@@ -397,6 +472,7 @@ var _FormController = class _FormController {
397
472
  getInitialItems: () => __privateGet(this, _initialItems),
398
473
  getItem: __privateGet(this, _getItem),
399
474
  setItems: __privateGet(this, _setItems),
475
+ setState: __privateGet(this, _setState),
400
476
  supersede: __privateGet(this, _supersede),
401
477
  emit: __privateGet(this, _emit),
402
478
  createCommandItem: __privateGet(this, _createCommandItem)
@@ -421,6 +497,11 @@ var _FormController = class _FormController {
421
497
  static async fromEntity(entity, options = {}) {
422
498
  const form = { items: [] };
423
499
  await createInitialReader().read(entity, form);
500
+ if (!form.items.length && !form.readers?.length && !form.starters?.length) {
501
+ console.warn(
502
+ `[punica-form] ${options.name ?? entity.constructor?.name ?? "The form"} has no form items. Its properties need a form item decorator. If they have one, the build of the project does not apply decorators: see ${DOCS_URL}/docs/installation, or define the form with defineForm, which needs no decorator syntax.`
503
+ );
504
+ }
424
505
  return new _FormController(form, entity, options);
425
506
  }
426
507
  /**
@@ -483,6 +564,10 @@ var _FormController = class _FormController {
483
564
  );
484
565
  }
485
566
  __privateSet(this, _initialItems, deepCopy(__privateGet(this, _form).items));
567
+ __privateSet(this, _form, {
568
+ ...__privateGet(this, _form),
569
+ state: __privateMethod(this, _FormController_instances, deriveState_fn).call(this, __privateGet(this, _form).items)
570
+ });
486
571
  __privateSet(this, _started, true);
487
572
  sendToDevTools(__privateGet(this, _name), "@@INIT", __privateGet(this, _form));
488
573
  __privateMethod(this, _FormController_instances, notify_fn).call(this);
@@ -495,7 +580,7 @@ _itemsMap = new WeakMap();
495
580
  _services = new WeakMap();
496
581
  _started = new WeakMap();
497
582
  _batching = new WeakMap();
498
- _dirty = new WeakMap();
583
+ _pending = new WeakMap();
499
584
  _epoch = new WeakMap();
500
585
  _writes = new WeakMap();
501
586
  _subscribers = new WeakMap();
@@ -511,6 +596,36 @@ mapItems_fn = function() {
511
596
  };
512
597
  _getItem = new WeakMap();
513
598
  _setItems = new WeakMap();
599
+ _setState = new WeakMap();
600
+ /**
601
+ * The state of the form for its items. The current state object is
602
+ * returned when nothing changed, so it can be compared by reference.
603
+ */
604
+ deriveState_fn = function(items, patch = {}) {
605
+ const known = Array.isArray(__privateGet(this, _form).state?.errors);
606
+ const current = known ? __privateGet(this, _form).state : INITIAL_STATE;
607
+ const next = {
608
+ ...current,
609
+ ...patch,
610
+ dirty: items.some((item) => item.dirty),
611
+ touched: items.some((item) => item.touched),
612
+ validating: items.some((item) => item.validating),
613
+ // Like the validation, which skips items the user cannot change
614
+ valid: items.every((item) => !item.error || item.hidden || item.disabled)
615
+ };
616
+ const same = Object.keys(next).every(
617
+ (key) => isEqual(next[key], current[key])
618
+ );
619
+ return same && known ? current : next;
620
+ };
621
+ commit_fn = function(form) {
622
+ __privateSet(this, _form, form);
623
+ if (__privateGet(this, _batching)) {
624
+ __privateSet(this, _pending, true);
625
+ } else {
626
+ __privateMethod(this, _FormController_instances, notify_fn).call(this);
627
+ }
628
+ };
514
629
  /** Tells everyone who follows the form that it changed. */
515
630
  notify_fn = function() {
516
631
  __privateGet(this, _subscribers).forEach((listener) => listener());
@@ -533,38 +648,46 @@ sendEntityToDevTools_fn = function() {
533
648
  };
534
649
  var FormController = _FormController;
535
650
 
536
- // lib/utils/deepCopy.ts
537
- var deepCopy = (value, seen = /* @__PURE__ */ new WeakMap()) => {
538
- if (typeof value !== "object" || value === null) {
539
- return value;
651
+ // lib/utils/isEqual.ts
652
+ var isEqual = (a, b, seen = /* @__PURE__ */ new WeakMap()) => {
653
+ if (Object.is(a, b)) {
654
+ return true;
540
655
  }
541
- if (seen.has(value)) {
542
- return seen.get(value);
656
+ if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
657
+ return false;
543
658
  }
544
- if (value instanceof Date) {
545
- return new Date(value.getTime());
659
+ if (seen.get(a)?.has(b)) {
660
+ return true;
546
661
  }
547
- if (value instanceof RegExp) {
548
- return new RegExp(value.source, value.flags);
662
+ seen.set(a, (seen.get(a) ?? /* @__PURE__ */ new WeakSet()).add(b));
663
+ if (a instanceof Date) {
664
+ return a.getTime() === b.getTime();
549
665
  }
550
- if (value instanceof Map) {
551
- const copy2 = /* @__PURE__ */ new Map();
552
- seen.set(value, copy2);
553
- value.forEach((v, k) => copy2.set(deepCopy(k, seen), deepCopy(v, seen)));
554
- return copy2;
666
+ if (a instanceof RegExp) {
667
+ return String(a) === String(b);
555
668
  }
556
- if (value instanceof Set) {
557
- const copy2 = /* @__PURE__ */ new Set();
558
- seen.set(value, copy2);
559
- value.forEach((v) => copy2.add(deepCopy(v, seen)));
560
- return copy2;
669
+ if (a instanceof Set) {
670
+ const other = [...b];
671
+ return a.size === other.length && [...a].every(
672
+ (value) => b.has(value) || other.some((candidate) => isEqual(value, candidate, seen))
673
+ );
561
674
  }
562
- const copy = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
563
- seen.set(value, copy);
564
- for (const key of Object.keys(value)) {
565
- copy[key] = deepCopy(value[key], seen);
675
+ if (a instanceof Map) {
676
+ const other = [...b];
677
+ return a.size === other.length && [...a].every(
678
+ ([key, value]) => other.some(
679
+ ([otherKey, otherValue]) => isEqual(key, otherKey, seen) && isEqual(value, otherValue, seen)
680
+ )
681
+ );
566
682
  }
567
- return copy;
683
+ const keys = Object.keys(a);
684
+ const left = a;
685
+ const right = b;
686
+ const prototype = Object.getPrototypeOf(a);
687
+ if (keys.length === 0 && prototype !== Object.prototype && prototype !== Array.prototype && prototype !== null) {
688
+ return false;
689
+ }
690
+ return keys.length === Object.keys(right).length && keys.every((key) => key in right && isEqual(left[key], right[key], seen));
568
691
  };
569
692
 
570
693
  // lib/utils/path.ts
@@ -608,14 +731,17 @@ var writeToPropertyPath = (entity, path, value) => {
608
731
  createInitialReader,
609
732
  deepCopy,
610
733
  defaultFormItemRegister,
734
+ defineForm,
611
735
  defineFormItem,
612
736
  defineFormItemProperty,
613
737
  defineFormProperty,
614
738
  disableDevTools,
615
739
  enableDevTools,
740
+ field,
616
741
  getFormItemProperties,
617
742
  getFormProperty,
618
743
  isDevToolsEnabled,
744
+ isEqual,
619
745
  readPropertyPath,
620
746
  writeToPropertyPath
621
747
  });
package/dist/index.mjs CHANGED
@@ -64,6 +64,61 @@ var getFormItemProperties = (entity, key) => {
64
64
  }, {});
65
65
  };
66
66
 
67
+ // lib/utils/deepCopy.ts
68
+ var deepCopy = (value, seen = /* @__PURE__ */ new WeakMap()) => {
69
+ if (typeof value !== "object" || value === null) {
70
+ return value;
71
+ }
72
+ if (seen.has(value)) {
73
+ return seen.get(value);
74
+ }
75
+ if (value instanceof Date) {
76
+ return new Date(value.getTime());
77
+ }
78
+ if (value instanceof RegExp) {
79
+ return new RegExp(value.source, value.flags);
80
+ }
81
+ if (value instanceof Map) {
82
+ const copy2 = /* @__PURE__ */ new Map();
83
+ seen.set(value, copy2);
84
+ value.forEach((v, k) => copy2.set(deepCopy(k, seen), deepCopy(v, seen)));
85
+ return copy2;
86
+ }
87
+ if (value instanceof Set) {
88
+ const copy2 = /* @__PURE__ */ new Set();
89
+ seen.set(value, copy2);
90
+ value.forEach((v) => copy2.add(deepCopy(v, seen)));
91
+ return copy2;
92
+ }
93
+ const copy = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
94
+ seen.set(value, copy);
95
+ for (const key of Object.keys(value)) {
96
+ copy[key] = deepCopy(value[key], seen);
97
+ }
98
+ return copy;
99
+ };
100
+
101
+ // lib/define/Form.ts
102
+ var field = (value, ...decorators) => ({ value, decorators });
103
+ var defineForm = (fields, ...decorators) => {
104
+ class DefinedForm {
105
+ constructor(values = {}) {
106
+ for (const [property, { value }] of Object.entries(fields)) {
107
+ this[property] = Object.prototype.hasOwnProperty.call(values, property) && values[property] !== void 0 ? values[property] : deepCopy(value);
108
+ }
109
+ }
110
+ }
111
+ for (const [property, { decorators: decorators2 }] of Object.entries(fields)) {
112
+ for (const decorate of [...decorators2].reverse()) {
113
+ decorate(DefinedForm.prototype, property);
114
+ }
115
+ }
116
+ for (const decorate of [...decorators].reverse()) {
117
+ decorate(DefinedForm);
118
+ }
119
+ return DefinedForm;
120
+ };
121
+
67
122
  // lib/register/index.ts
68
123
  var _items;
69
124
  var FormItemRegister = class {
@@ -221,8 +276,18 @@ var sendToDevTools = (formId, type, data, formItemKey) => {
221
276
  };
222
277
 
223
278
  // lib/controller/index.ts
279
+ var DOCS_URL = "https://form.punicalab.com";
224
280
  var formCount = 0;
225
- var _form, _initialItems, _itemsMap, _services, _started, _batching, _dirty, _epoch, _writes, _subscribers, _listeners, _initialEntity, _register, _name, _FormController_instances, mapItems_fn, _getItem, _setItems, notify_fn, _supersede, _emit, _createCommandItem, _createCommandService, sendEntityToDevTools_fn;
281
+ var INITIAL_STATE = {
282
+ dirty: false,
283
+ touched: false,
284
+ valid: true,
285
+ validating: false,
286
+ submitting: false,
287
+ submitCount: 0,
288
+ errors: []
289
+ };
290
+ var _form, _initialItems, _itemsMap, _services, _started, _batching, _pending, _epoch, _writes, _subscribers, _listeners, _initialEntity, _register, _name, _FormController_instances, mapItems_fn, _getItem, _setItems, _setState, deriveState_fn, commit_fn, notify_fn, _supersede, _emit, _createCommandItem, _createCommandService, sendEntityToDevTools_fn;
226
291
  var _FormController = class _FormController {
227
292
  constructor(form, entity, options) {
228
293
  __privateAdd(this, _FormController_instances);
@@ -233,7 +298,7 @@ var _FormController = class _FormController {
233
298
  __privateAdd(this, _services, /* @__PURE__ */ new Map());
234
299
  __privateAdd(this, _started, false);
235
300
  __privateAdd(this, _batching, 0);
236
- __privateAdd(this, _dirty, false);
301
+ __privateAdd(this, _pending, false);
237
302
  __privateAdd(this, _epoch, 0);
238
303
  __privateAdd(this, _writes, /* @__PURE__ */ new Map());
239
304
  __privateAdd(this, _subscribers, /* @__PURE__ */ new Set());
@@ -262,23 +327,24 @@ var _FormController = class _FormController {
262
327
  */
263
328
  this.batch = (change) => {
264
329
  const done = () => {
265
- if (--__privateWrapper(this, _batching)._ === 0 && __privateGet(this, _dirty)) {
266
- __privateSet(this, _dirty, false);
330
+ if (--__privateWrapper(this, _batching)._ === 0 && __privateGet(this, _pending)) {
331
+ __privateSet(this, _pending, false);
267
332
  __privateMethod(this, _FormController_instances, notify_fn).call(this);
268
333
  }
269
334
  };
270
335
  __privateWrapper(this, _batching)._++;
336
+ let result;
271
337
  try {
272
- const result = change();
273
- if (result instanceof Promise) {
274
- return result.finally(done);
275
- }
276
- done();
277
- return result;
338
+ result = change();
278
339
  } catch (error) {
279
340
  done();
280
341
  throw error;
281
342
  }
343
+ if (result instanceof Promise) {
344
+ return result.finally(done);
345
+ }
346
+ done();
347
+ return result;
282
348
  };
283
349
  __privateAdd(this, _getItem, (property) => {
284
350
  const index = __privateGet(this, _itemsMap).get(property);
@@ -291,18 +357,24 @@ var _FormController = class _FormController {
291
357
  for (const item of items) {
292
358
  const index = __privateGet(this, _itemsMap).get(item.property);
293
359
  if (index !== void 0) {
294
- next[index] = item;
360
+ const initial = __privateGet(this, _initialItems)[index];
361
+ const dirty = Boolean(initial) && !isEqual(item.value, initial.value);
362
+ next[index] = dirty === Boolean(item.dirty) ? item : { ...item, dirty };
295
363
  changed = true;
296
364
  }
297
365
  }
298
- if (!changed) {
299
- return;
366
+ if (changed) {
367
+ __privateMethod(this, _FormController_instances, commit_fn).call(this, {
368
+ ...__privateGet(this, _form),
369
+ items: next,
370
+ state: __privateMethod(this, _FormController_instances, deriveState_fn).call(this, next)
371
+ });
300
372
  }
301
- __privateSet(this, _form, { ...__privateGet(this, _form), items: next });
302
- if (__privateGet(this, _batching)) {
303
- __privateSet(this, _dirty, true);
304
- } else {
305
- __privateMethod(this, _FormController_instances, notify_fn).call(this);
373
+ });
374
+ __privateAdd(this, _setState, (patch) => {
375
+ const state = __privateMethod(this, _FormController_instances, deriveState_fn).call(this, __privateGet(this, _form).items, patch);
376
+ if (state !== __privateGet(this, _form).state) {
377
+ __privateMethod(this, _FormController_instances, commit_fn).call(this, { ...__privateGet(this, _form), state });
306
378
  }
307
379
  });
308
380
  __privateAdd(this, _supersede, (property) => {
@@ -349,6 +421,7 @@ var _FormController = class _FormController {
349
421
  getInitialItems: () => __privateGet(this, _initialItems),
350
422
  getItem: __privateGet(this, _getItem),
351
423
  setItems: __privateGet(this, _setItems),
424
+ setState: __privateGet(this, _setState),
352
425
  supersede: __privateGet(this, _supersede),
353
426
  emit: __privateGet(this, _emit),
354
427
  createCommandItem: __privateGet(this, _createCommandItem)
@@ -373,6 +446,11 @@ var _FormController = class _FormController {
373
446
  static async fromEntity(entity, options = {}) {
374
447
  const form = { items: [] };
375
448
  await createInitialReader().read(entity, form);
449
+ if (!form.items.length && !form.readers?.length && !form.starters?.length) {
450
+ console.warn(
451
+ `[punica-form] ${options.name ?? entity.constructor?.name ?? "The form"} has no form items. Its properties need a form item decorator. If they have one, the build of the project does not apply decorators: see ${DOCS_URL}/docs/installation, or define the form with defineForm, which needs no decorator syntax.`
452
+ );
453
+ }
376
454
  return new _FormController(form, entity, options);
377
455
  }
378
456
  /**
@@ -435,6 +513,10 @@ var _FormController = class _FormController {
435
513
  );
436
514
  }
437
515
  __privateSet(this, _initialItems, deepCopy(__privateGet(this, _form).items));
516
+ __privateSet(this, _form, {
517
+ ...__privateGet(this, _form),
518
+ state: __privateMethod(this, _FormController_instances, deriveState_fn).call(this, __privateGet(this, _form).items)
519
+ });
438
520
  __privateSet(this, _started, true);
439
521
  sendToDevTools(__privateGet(this, _name), "@@INIT", __privateGet(this, _form));
440
522
  __privateMethod(this, _FormController_instances, notify_fn).call(this);
@@ -447,7 +529,7 @@ _itemsMap = new WeakMap();
447
529
  _services = new WeakMap();
448
530
  _started = new WeakMap();
449
531
  _batching = new WeakMap();
450
- _dirty = new WeakMap();
532
+ _pending = new WeakMap();
451
533
  _epoch = new WeakMap();
452
534
  _writes = new WeakMap();
453
535
  _subscribers = new WeakMap();
@@ -463,6 +545,36 @@ mapItems_fn = function() {
463
545
  };
464
546
  _getItem = new WeakMap();
465
547
  _setItems = new WeakMap();
548
+ _setState = new WeakMap();
549
+ /**
550
+ * The state of the form for its items. The current state object is
551
+ * returned when nothing changed, so it can be compared by reference.
552
+ */
553
+ deriveState_fn = function(items, patch = {}) {
554
+ const known = Array.isArray(__privateGet(this, _form).state?.errors);
555
+ const current = known ? __privateGet(this, _form).state : INITIAL_STATE;
556
+ const next = {
557
+ ...current,
558
+ ...patch,
559
+ dirty: items.some((item) => item.dirty),
560
+ touched: items.some((item) => item.touched),
561
+ validating: items.some((item) => item.validating),
562
+ // Like the validation, which skips items the user cannot change
563
+ valid: items.every((item) => !item.error || item.hidden || item.disabled)
564
+ };
565
+ const same = Object.keys(next).every(
566
+ (key) => isEqual(next[key], current[key])
567
+ );
568
+ return same && known ? current : next;
569
+ };
570
+ commit_fn = function(form) {
571
+ __privateSet(this, _form, form);
572
+ if (__privateGet(this, _batching)) {
573
+ __privateSet(this, _pending, true);
574
+ } else {
575
+ __privateMethod(this, _FormController_instances, notify_fn).call(this);
576
+ }
577
+ };
466
578
  /** Tells everyone who follows the form that it changed. */
467
579
  notify_fn = function() {
468
580
  __privateGet(this, _subscribers).forEach((listener) => listener());
@@ -485,38 +597,46 @@ sendEntityToDevTools_fn = function() {
485
597
  };
486
598
  var FormController = _FormController;
487
599
 
488
- // lib/utils/deepCopy.ts
489
- var deepCopy = (value, seen = /* @__PURE__ */ new WeakMap()) => {
490
- if (typeof value !== "object" || value === null) {
491
- return value;
600
+ // lib/utils/isEqual.ts
601
+ var isEqual = (a, b, seen = /* @__PURE__ */ new WeakMap()) => {
602
+ if (Object.is(a, b)) {
603
+ return true;
492
604
  }
493
- if (seen.has(value)) {
494
- return seen.get(value);
605
+ if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
606
+ return false;
495
607
  }
496
- if (value instanceof Date) {
497
- return new Date(value.getTime());
608
+ if (seen.get(a)?.has(b)) {
609
+ return true;
498
610
  }
499
- if (value instanceof RegExp) {
500
- return new RegExp(value.source, value.flags);
611
+ seen.set(a, (seen.get(a) ?? /* @__PURE__ */ new WeakSet()).add(b));
612
+ if (a instanceof Date) {
613
+ return a.getTime() === b.getTime();
501
614
  }
502
- if (value instanceof Map) {
503
- const copy2 = /* @__PURE__ */ new Map();
504
- seen.set(value, copy2);
505
- value.forEach((v, k) => copy2.set(deepCopy(k, seen), deepCopy(v, seen)));
506
- return copy2;
615
+ if (a instanceof RegExp) {
616
+ return String(a) === String(b);
507
617
  }
508
- if (value instanceof Set) {
509
- const copy2 = /* @__PURE__ */ new Set();
510
- seen.set(value, copy2);
511
- value.forEach((v) => copy2.add(deepCopy(v, seen)));
512
- return copy2;
618
+ if (a instanceof Set) {
619
+ const other = [...b];
620
+ return a.size === other.length && [...a].every(
621
+ (value) => b.has(value) || other.some((candidate) => isEqual(value, candidate, seen))
622
+ );
513
623
  }
514
- const copy = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
515
- seen.set(value, copy);
516
- for (const key of Object.keys(value)) {
517
- copy[key] = deepCopy(value[key], seen);
624
+ if (a instanceof Map) {
625
+ const other = [...b];
626
+ return a.size === other.length && [...a].every(
627
+ ([key, value]) => other.some(
628
+ ([otherKey, otherValue]) => isEqual(key, otherKey, seen) && isEqual(value, otherValue, seen)
629
+ )
630
+ );
518
631
  }
519
- return copy;
632
+ const keys = Object.keys(a);
633
+ const left = a;
634
+ const right = b;
635
+ const prototype = Object.getPrototypeOf(a);
636
+ if (keys.length === 0 && prototype !== Object.prototype && prototype !== Array.prototype && prototype !== null) {
637
+ return false;
638
+ }
639
+ return keys.length === Object.keys(right).length && keys.every((key) => key in right && isEqual(left[key], right[key], seen));
520
640
  };
521
641
 
522
642
  // lib/utils/path.ts
@@ -559,14 +679,17 @@ export {
559
679
  createInitialReader,
560
680
  deepCopy,
561
681
  defaultFormItemRegister,
682
+ defineForm,
562
683
  FormItem_default as defineFormItem,
563
684
  FormItemProperty_default as defineFormItemProperty,
564
685
  FormProperty_default as defineFormProperty,
565
686
  disableDevTools,
566
687
  enableDevTools,
688
+ field,
567
689
  getFormItemProperties,
568
690
  getFormProperty,
569
691
  isDevToolsEnabled,
692
+ isEqual,
570
693
  readPropertyPath,
571
694
  writeToPropertyPath
572
695
  };
@@ -1,4 +1,4 @@
1
- import { CommandItem, Form, FormEventMap, FormItem } from '..';
1
+ import { CommandItem, Form, FormEventMap, FormItem, FormStatePatch } from '..';
2
2
  /**
3
3
  * What a service receives when it is initialized: the only way to read and
4
4
  * change the state of the form.
@@ -15,8 +15,14 @@ export type CommandService<E, F extends FormItem<E>> = {
15
15
  /**
16
16
  * Replaces the items with the same properties. The form gets a new
17
17
  * reference and UPDATE_FORM is fired. Unknown properties are ignored.
18
+ * `dirty` of the items is set by comparing their values with the initial ones.
18
19
  */
19
20
  setItems: (items: Array<FormItem<E>>) => void;
21
+ /**
22
+ * Changes the state of the form as a whole. The form gets a new reference
23
+ * and UPDATE_FORM is fired, unless nothing changed.
24
+ */
25
+ setState: (state: FormStatePatch) => void;
20
26
  /**
21
27
  * Marks the pending asynchronous writes of a property, or of the whole
22
28
  * form when no property is given, as superseded by a newer one.
@@ -9,6 +9,10 @@ export type FormEventMap<E, F extends FormItem<E>> = {
9
9
  RESET: Form<E, F>;
10
10
  /** A value was set: the changed item, then the items its control returned. */
11
11
  UPDATE_ITEM: F[];
12
+ /** The form was submitted: the values the submit handler received. */
13
+ SUBMIT: E;
14
+ /** A submit failed: what the validation or the submit handler threw. */
15
+ SUBMIT_ERROR: unknown;
12
16
  /** The registered form item types. Fired at the beginning of start(). */
13
17
  REGISTER_ITEMS: string[];
14
18
  };
@@ -1,10 +1,33 @@
1
1
  import { FormItem, IReader, IService, IStarter } from '../..';
2
+ /**
3
+ * What a form knows about itself as a whole. A started form always has it.
4
+ */
5
+ export type FormState = {
6
+ /** Whether the value of an item differs from the one the form was started with. */
7
+ dirty: boolean;
8
+ /** Whether the user has left a field. */
9
+ touched: boolean;
10
+ /** Whether no item is in error. */
11
+ valid: boolean;
12
+ /** Whether an item is being validated. */
13
+ validating: boolean;
14
+ /** Whether the form is being submitted. */
15
+ submitting: boolean;
16
+ /** How many times a submit was attempted. */
17
+ submitCount: number;
18
+ /** Errors of the form as a whole, such as a rejected submit. */
19
+ errors: string[];
20
+ };
21
+ /** The part of the state services write; the rest follows from the items. */
22
+ export type FormStatePatch = Partial<Pick<FormState, 'submitting' | 'submitCount' | 'errors'>>;
2
23
  /**
3
24
  * The state of a form. Readers and starters may attach their own properties
4
25
  * (a title, a layout, …), which are read back as `unknown`.
5
26
  */
6
27
  export type Form<E, F extends FormItem<E> = FormItem<E>> = {
7
28
  items: F[];
29
+ /** Set when the form is started and kept up to date after every change. */
30
+ state?: FormState;
8
31
  /** Service classes (one instance per form) or instances. */
9
32
  services?: Array<IService | (new () => IService)>;
10
33
  readers?: Array<IReader<E, F>>;
@@ -20,6 +20,18 @@ export type FormItem<E> = {
20
20
  required?: boolean;
21
21
  disabled?: boolean;
22
22
  hidden?: boolean;
23
+ /** Whether the value differs from the one the form was started with. */
24
+ dirty?: boolean;
25
+ /** Whether the user has left the field. Set by the `Touch` service. */
26
+ touched?: boolean;
27
+ /** Whether the item is being validated. */
28
+ validating?: boolean;
29
+ /**
30
+ * Milliseconds the `Trigger` service waits before it validates the item.
31
+ * A validation triggered again meanwhile starts the wait anew, so a
32
+ * validation that asks a server runs once the user stops typing.
33
+ */
34
+ validateDebounce?: number;
23
35
  /** Whether the last validation of the item failed. */
24
36
  error?: boolean;
25
37
  /** The messages of the last failed validation. */
@@ -28,8 +40,12 @@ export type FormItem<E> = {
28
40
  initialize?(command: CommandItem<E, FormItem<E>>): Promise<Array<FormItem<E>>>;
29
41
  /** Runs after the value of the item was set; the returned items are written to the form. */
30
42
  control?(command: CommandItem<E, FormItem<E>>): Promise<Array<FormItem<E>>>;
31
- /** Validates the item. */
32
- validation?(command: CommandItem<E, FormItem<E>>): Promise<ErrorDetail>;
43
+ /**
44
+ * Validates the item. The services pass a context whose signal is aborted
45
+ * when the result is not needed any more; give it to `fetch` to cancel
46
+ * the request: `fetch(url, { signal: context?.signal })`.
47
+ */
48
+ validation?(command: CommandItem<E, FormItem<E>>, context?: ValidationContext): Promise<ErrorDetail>;
33
49
  };
34
50
  /**
35
51
  * A form item whose `value` has the type of its property. Use it as the item
@@ -45,6 +61,16 @@ export type TypedFormItem<E, F extends FormItem<E> = FormItem<E>> = {
45
61
  value?: E[K];
46
62
  };
47
63
  }[keyof E];
64
+ /**
65
+ * What a validation function receives besides its command.
66
+ */
67
+ export type ValidationContext = {
68
+ /**
69
+ * Aborted when the item is validated again, changed or reset while the
70
+ * validation is running.
71
+ */
72
+ signal: AbortSignal;
73
+ };
48
74
  /**
49
75
  * The result of a validation.
50
76
  */
@@ -1,3 +1,4 @@
1
1
  export { DEVTOOLS_MESSAGE_SOURCE, DEVTOOLS_PROTOCOL_VERSION, disableDevTools, enableDevTools, isDevToolsEnabled } from './devtools';
2
2
  export * from './deepCopy';
3
+ export * from './isEqual';
3
4
  export * from './path';
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Whether two values are deeply equal. Objects, arrays, dates, regular
3
+ * expressions, maps and sets are compared by their content, circular
4
+ * references included. Objects without own properties that are not plain,
5
+ * such as a `File`, are only equal to themselves.
6
+ */
7
+ export declare const isEqual: (a: unknown, b: unknown, seen?: WeakMap<object, WeakSet<object>>) => boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@punica/form",
3
- "version": "2.1.0",
3
+ "version": "2.2.0-next.0",
4
4
  "description": "Headless, framework-agnostic form engine",
5
5
  "author": {
6
6
  "name": "Uryan Sezgin TEKE",