@pacem/pacem-scaffolding 1.0.0-bessel → 1.0.0-dirac

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 (55) hide show
  1. package/dist/browser/pacem-scaffolding.js +420 -38
  2. package/dist/browser/pacem-scaffolding.js.map +1 -1
  3. package/dist/browser/pacem-scaffolding.min.js +2 -2
  4. package/dist/bundle/pacem-scaffolding.min.mjs +91 -91
  5. package/dist/bundle/pacem-scaffolding.mjs +329 -200
  6. package/dist/bundle/pacem-scaffolding.mjs.map +3 -3
  7. package/dist/docs/pacem-scaffolding.json +34788 -0
  8. package/dist/esm/calendar-picker.js +6 -1
  9. package/dist/esm/char-counter.js +3 -1
  10. package/dist/esm/checkbox-list.js +2 -1
  11. package/dist/esm/checkbox.js +3 -1
  12. package/dist/esm/childform.js +1 -1
  13. package/dist/esm/contenteditable.js +4 -1
  14. package/dist/esm/datetime-picker.js +8 -1
  15. package/dist/esm/form.js +65 -1
  16. package/dist/esm/formfield.js +9 -1
  17. package/dist/esm/geolocate.js +2 -1
  18. package/dist/esm/hierarchy.js +6 -1
  19. package/dist/esm/index-components-scaffolding.js +1 -1
  20. package/dist/esm/index-components.js +1 -1
  21. package/dist/esm/index-iife.js +1 -1
  22. package/dist/esm/index-root.js +1 -1
  23. package/dist/esm/index-scaffolding.js +1 -1
  24. package/dist/esm/index.js +1 -1
  25. package/dist/esm/input-chars.js +4 -1
  26. package/dist/esm/input-color.js +3 -2
  27. package/dist/esm/input-email.js +13 -7
  28. package/dist/esm/input-file.js +20 -3
  29. package/dist/esm/input-hidden.js +7 -4
  30. package/dist/esm/input-image.js +13 -1
  31. package/dist/esm/input-number.js +5 -2
  32. package/dist/esm/input-password.js +6 -2
  33. package/dist/esm/input-search.js +7 -4
  34. package/dist/esm/input-tel.js +13 -7
  35. package/dist/esm/input-text.js +6 -3
  36. package/dist/esm/input-url.js +13 -7
  37. package/dist/esm/input.js +26 -1
  38. package/dist/esm/l10n.js +2 -1
  39. package/dist/esm/latlng.js +4 -1
  40. package/dist/esm/namevalue-list.js +3 -1
  41. package/dist/esm/property-picker.js +2 -1
  42. package/dist/esm/radio-list.js +2 -1
  43. package/dist/esm/radio.js +2 -1
  44. package/dist/esm/select.js +6 -2
  45. package/dist/esm/slider.js +2 -1
  46. package/dist/esm/snapshot.js +5 -1
  47. package/dist/esm/suggest.js +2 -1
  48. package/dist/esm/tags.js +3 -1
  49. package/dist/esm/textarea-markdown.js +15 -9
  50. package/dist/esm/textarea.js +13 -5
  51. package/dist/esm/types-components.js +53 -2
  52. package/dist/esm/types.js +3 -1
  53. package/dist/esm/validators.js +25 -1
  54. package/package.json +2 -1
  55. package/typings/index.d.ts +626 -14
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * @pacem/pacem-scaffolding v1.0.0-bessel (https://js.pacem.it)
2
+ * @pacem/pacem-scaffolding v1.0.0-dirac (https://js.pacem.it)
3
3
  * Pacem (https://pacem.it)
4
4
  * Licensed under Apache-2.0
5
5
  */
@@ -9,20 +9,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
9
9
  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
10
10
  return c > 3 && r && Object.defineProperty(target, key, r), r;
11
11
  };
12
- import { P, PCSS, CustomElement, Watch, Defaults, ViewChild, PropertyConverters, preventDefaultHandler } from '@pacem/pacem-core';
12
+ import { P, PCSS, CustomElement, Watch, Defaults, ViewChild, PropertyConverters, preventDefaultHandler, Utils } from '@pacem/pacem-core';
13
13
  import { Components } from '@pacem/pacem-ui';
14
14
  import { PacemTextualInputElement } from './input';
15
15
  import { CHAR_COUNTER_CHILD } from './char-counter';
16
16
  //namespace Pacem.Components.Scaffolding {
17
+ /** A `<p-textarea-markdown>` field: a {@link PacemTextualInputElement} backed by a native `<textarea>` for editing Markdown text, whose readonly view renders the value as HTML via {@link Components.UI.MarkdownService}. */
17
18
  let PacemMarkdownTextAreaElement = class PacemMarkdownTextAreaElement extends PacemTextualInputElement {
18
19
  constructor(_md = new Components.UI.MarkdownService()) {
19
20
  super();
20
21
  this._md = _md;
22
+ /** Gets or sets the native `<textarea>`'s `rows` attribute. Defaults to `5`. */
21
23
  this.rows = 5;
24
+ /** Gets or sets the native `<textarea>`'s `cols` attribute. Defaults to `50`. */
22
25
  this.cols = 50;
23
26
  this._keydownHandler = (evt) => {
24
27
  if (evt.keyCode === 9 /* tab */) {
25
- const input = this.input, value = input.value;
28
+ const input = this._input, value = input.value;
26
29
  var ndx = input.selectionStart;
27
30
  input.value = value.substr(0, ndx) + ' ' + value.substr(ndx);
28
31
  preventDefaultHandler(evt);
@@ -30,14 +33,17 @@ let PacemMarkdownTextAreaElement = class PacemMarkdownTextAreaElement extends Pa
30
33
  };
31
34
  }
32
35
  toggleReadonlyView(readonly) {
33
- this.input.hidden = readonly;
36
+ if (!Utils.isNull(this._input))
37
+ this._input.hidden = readonly;
34
38
  }
35
39
  /** @override */
36
40
  get preventKeyboardSubmit() {
37
41
  return true;
38
42
  }
39
43
  get inputFields() {
40
- return [this.input];
44
+ return Utils.isNull(this._input)
45
+ ? []
46
+ : [this._input];
41
47
  }
42
48
  getViewValue(val) {
43
49
  return this._md.toHtml(val);
@@ -54,11 +60,11 @@ let PacemMarkdownTextAreaElement = class PacemMarkdownTextAreaElement extends Pa
54
60
  }
55
61
  viewActivatedCallback() {
56
62
  super.viewActivatedCallback();
57
- this.input.addEventListener("keydown", this._keydownHandler, false);
63
+ this._input.addEventListener("keydown", this._keydownHandler, false);
58
64
  }
59
65
  disconnectedCallback() {
60
- this.input &&
61
- this.input.removeEventListener("keydown", this._keydownHandler, false);
66
+ this._input &&
67
+ this._input.removeEventListener("keydown", this._keydownHandler, false);
62
68
  super.disconnectedCallback();
63
69
  }
64
70
  };
@@ -70,7 +76,7 @@ __decorate([
70
76
  ], PacemMarkdownTextAreaElement.prototype, "cols", void 0);
71
77
  __decorate([
72
78
  ViewChild('textarea')
73
- ], PacemMarkdownTextAreaElement.prototype, "input", void 0);
79
+ ], PacemMarkdownTextAreaElement.prototype, "_input", void 0);
74
80
  __decorate([
75
81
  ViewChild(`div.${PCSS}-readonly`)
76
82
  ], PacemMarkdownTextAreaElement.prototype, "_markdown", void 0);
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * @pacem/pacem-scaffolding v1.0.0-bessel (https://js.pacem.it)
2
+ * @pacem/pacem-scaffolding v1.0.0-dirac (https://js.pacem.it)
3
3
  * Pacem (https://pacem.it)
4
4
  * Licensed under Apache-2.0
5
5
  */
@@ -9,14 +9,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
9
9
  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
10
10
  return c > 3 && r && Object.defineProperty(target, key, r), r;
11
11
  };
12
- import { P, PCSS, CustomElement, Watch, Defaults, ViewChild, PropertyConverters } from '@pacem/pacem-core';
12
+ import { P, PCSS, CustomElement, Watch, Defaults, ViewChild, PropertyConverters, Utils } from '@pacem/pacem-core';
13
13
  import { PacemTextualInputElement } from './input';
14
14
  import { CHAR_COUNTER_CHILD } from './char-counter';
15
15
  //namespace Pacem.Components.Scaffolding {
16
+ /** A `<p-textarea>` field: a {@link PacemTextualInputElement} backed by a native `<textarea>`, with an optional character counter. */
16
17
  let PacemTextAreaElement = class PacemTextAreaElement extends PacemTextualInputElement {
17
18
  constructor() {
18
19
  super(...arguments);
20
+ /** Gets or sets the native `<textarea>`'s `rows` attribute. Defaults to `5`. */
19
21
  this.rows = 5;
22
+ /** Gets or sets the native `<textarea>`'s `cols` attribute. Defaults to `50`. */
20
23
  this.cols = 50;
21
24
  }
22
25
  /** @override */
@@ -24,11 +27,16 @@ let PacemTextAreaElement = class PacemTextAreaElement extends PacemTextualInputE
24
27
  return true;
25
28
  }
26
29
  toggleReadonlyView(readonly) {
27
- this._span.hidden = !readonly;
28
- this._input.hidden = readonly;
30
+ const input = this._input, span = this._span;
31
+ if (!Utils.isNull(input))
32
+ input.hidden = readonly;
33
+ if (!Utils.isNull(span))
34
+ span.hidden = !readonly;
29
35
  }
30
36
  get inputFields() {
31
- return [this._input];
37
+ return Utils.isNull(this._input)
38
+ ? []
39
+ : [this._input];
32
40
  }
33
41
  propertyChangedCallback(name, old, val, first) {
34
42
  super.propertyChangedCallback(name, old, val, first);
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * @pacem/pacem-scaffolding v1.0.0-bessel (https://js.pacem.it)
2
+ * @pacem/pacem-scaffolding v1.0.0-dirac (https://js.pacem.it)
3
3
  * Pacem (https://pacem.it)
4
4
  * Licensed under Apache-2.0
5
5
  */
@@ -12,7 +12,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
12
12
  import { P, PCSS, CustomElementUtils, Utils, Components, PropertyConverters, CustomElement, Watch, stopPropagationHandler, DefaultComparer, PropertyChangeEventName, Debounce } from '@pacem/pacem-core';
13
13
  import { FieldChangeEvent } from './types';
14
14
  import { PacemFormRelevantElement } from './form';
15
+ /** Attached-property key used to stash a field's pristine value on the element itself (see {@link PacemModelElement.originalValue}). */
15
16
  const ORIGINAL_VALUE_FIELD = 'pacem:model:original-value';
17
+ /**
18
+ * Base class for any element that behaves as a bindable, form-aware model value: it registers itself by
19
+ * `name` with the ancestor {@link PacemFormElement} (found via {@link PacemFormRelevantElement}), tracks
20
+ * `dirty`/`valid` state (reflected as `pacem-dirty`/`pacem-invalid` CSS classes), and remembers the value it
21
+ * had when activated/set-pristine so {@link reset} can restore it.
22
+ *
23
+ * Concrete input/selection fields don't extend this directly - see {@link PacemBaseElement}, the abstract
24
+ * subclass that adds readonly/required/focus/keyboard handling on top of it.
25
+ */
16
26
  export class PacemModelElement extends PacemFormRelevantElement {
17
27
  viewActivatedCallback() {
18
28
  super.viewActivatedCallback();
@@ -78,22 +88,26 @@ export class PacemModelElement extends PacemFormRelevantElement {
78
88
  form.unregisterField(name);
79
89
  super.disconnectedCallback();
80
90
  }
91
+ /** @readonly The `value` this element had the last time it was activated or explicitly marked pristine (via {@link setPristine}); what {@link reset} restores. */
81
92
  get originalValue() {
82
93
  return CustomElementUtils.getAttachedPropertyValue(this, ORIGINAL_VALUE_FIELD);
83
94
  }
84
95
  _setAsOriginalValue(v) {
85
96
  CustomElementUtils.setAttachedPropertyValue(this, ORIGINAL_VALUE_FIELD, v);
86
97
  }
98
+ /** Restores {@link value} to {@link originalValue} and clears {@link dirty}. */
87
99
  reset() {
88
100
  this.value = this.originalValue;
89
101
  // then
90
102
  this.dirty = false;
91
103
  }
104
+ /** Marks the current `value` as the new baseline for {@link reset}/{@link originalValue} and clears {@link dirty}. */
92
105
  setPristine() {
93
106
  this._setAsOriginalValue(this.value);
94
107
  //
95
108
  this.dirty = false;
96
109
  }
110
+ /** Marks this field as `dirty`. */
97
111
  setDirty() {
98
112
  this.dirty = true;
99
113
  }
@@ -123,6 +137,16 @@ __decorate([
123
137
  __decorate([
124
138
  Watch({ converter: PropertyConverters.String })
125
139
  ], PacemModelElement.prototype, "name", void 0);
140
+ /**
141
+ * Base class for editable form fields: it adds `required`/`autofocus`/`readonly`/`placeholder` state, focus
142
+ * and keyboard handling (Esc to revert, Enter submit prevention), and the plumbing that wires the
143
+ * `focus`/`blur`/`change`/`keydown`/`keyup` handlers onto whichever native {@link inputFields} a derived
144
+ * class exposes.
145
+ *
146
+ * Not extended directly by concrete fields either - see {@link PacemBaseInputElement} (in `input.ts`) for
147
+ * `<input>`/`<textarea>`-backed fields, and {@link PacemDataSourceElement} for datasource-driven ones
148
+ * (lists, selects, radio groups, ...).
149
+ */
126
150
  export class PacemBaseElement extends PacemModelElement {
127
151
  constructor() {
128
152
  super(...arguments);
@@ -193,6 +217,7 @@ export class PacemBaseElement extends PacemModelElement {
193
217
  compareValuePropertyValues(old, val) {
194
218
  return DefaultComparer(old, val);
195
219
  }
220
+ /** @overridable Whether pressing Enter within this field should be prevented from submitting an ancestor form. Defaults to `false`. */
196
221
  get preventKeyboardSubmit() {
197
222
  return false;
198
223
  }
@@ -327,12 +352,18 @@ __decorate([
327
352
  __decorate([
328
353
  Watch({ converter: PropertyConverters.String })
329
354
  ], PacemBaseElement.prototype, "placeholder", void 0);
355
+ /**
356
+ * Scaffolding-specific counterpart of `@pacem/pacem-ui`'s `PacemItemElement`: a base class for elements that
357
+ * register themselves against an ancestor {@link PacemItemsContainerBaseElement} (found via
358
+ * {@link findContainer}) on activation, and unregister on disconnect. Extended by {@link PacemDataItemElement}.
359
+ */
330
360
  export class PacemItemElement extends Components.PacemElement {
331
361
  #container;
332
- /** @overridable */
362
+ /** @overridable Locates the ancestor items-container this item registers against. Defaults to the nearest {@link PacemItemsContainerBaseElement}. */
333
363
  findContainer() {
334
364
  return CustomElementUtils.findAncestor(this, n => n instanceof PacemItemsContainerBaseElement);
335
365
  }
366
+ /** @readonly Gets the items-container this item is currently registered with, if any. */
336
367
  get container() {
337
368
  return this.#container;
338
369
  }
@@ -350,6 +381,12 @@ export class PacemItemElement extends Components.PacemElement {
350
381
  super.disconnectedCallback();
351
382
  }
352
383
  }
384
+ /**
385
+ * Base class for form fields that also act as a registry of {@link PacemItemElement} children (e.g. a
386
+ * datasource-backed selection field whose options are declared, not just databound). Combines
387
+ * {@link PacemBaseElement}'s field behavior with `ItemsContainer<TItem>`'s registration API.
388
+ * See {@link PacemDataSourceElement} for the concrete specialization holding {@link PacemDataItemElement}s.
389
+ */
353
390
  export class PacemItemsContainerBaseElement extends PacemBaseElement {
354
391
  /**
355
392
  * Registers a new item among the items.
@@ -384,6 +421,7 @@ export class PacemItemsContainerBaseElement extends PacemBaseElement {
384
421
  __decorate([
385
422
  Watch( /* can only be databound or assigned at runtime */)
386
423
  ], PacemItemsContainerBaseElement.prototype, "items", void 0);
424
+ /** A single, declaratively-authored option (`<p-data-item>`) of a {@link PacemDataSourceElement}, as an alternative to a databound `datasource` array. */
387
425
  let PacemDataItemElement = class PacemDataItemElement extends PacemItemElement {
388
426
  };
389
427
  __decorate([
@@ -419,6 +457,13 @@ PacemDataItemElement = __decorate([
419
457
  CustomElement({ tagName: P + '-data-item' })
420
458
  ], PacemDataItemElement);
421
459
  export { PacemDataItemElement };
460
+ /**
461
+ * Base class for datasource-driven selection fields (lists, dropdowns, radio/checkbox groups, autocomplete,
462
+ * ...): adapts a raw `datasource` (an array of arbitrary entities, or declared {@link PacemDataItemElement}
463
+ * children registered via {@link PacemItemsContainerBaseElement}) into a normalized {@link DataSource}, and
464
+ * provides the value/view-value mapping and selection-matching logic (single or, when `multipleChoice` is
465
+ * `true`, multi-select) that concrete subclasses build their UI on top of.
466
+ */
422
467
  export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
423
468
  constructor(multipleChoice = false) {
424
469
  super();
@@ -449,9 +494,11 @@ export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
449
494
  }
450
495
  return flag;
451
496
  }
497
+ /** @overridable Maps a raw `datasource` array into its {@link DataSource} representation via {@link mapEntityToItem}. */
452
498
  buildAdaptedDatasource(ds = this.datasource) {
453
499
  return ds && ds.map(i => this.mapEntityToItem(i));
454
500
  }
501
+ /** Recomputes {@link adaptedDatasource} and, if the current `value` no longer matches any item, calls {@link handleDatasourceMismatch}. Debounced. */
455
502
  databind(datasource = this.buildAdaptedDatasource(this.datasource)) {
456
503
  if (Utils.isNull(datasource) && Utils.isNull(this.adaptedDatasource))
457
504
  return;
@@ -461,6 +508,7 @@ export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
461
508
  if (Utils.isNullOrEmpty(ds.filter(i => this.isDataSourceItemSelected(i))))
462
509
  this.handleDatasourceMismatch(ds);
463
510
  }
511
+ /** @overridable Called by {@link databind} when the current `value` matches none of the adapted `datasource` items. Defaults to clearing `value`. */
464
512
  handleDatasourceMismatch(datasource) {
465
513
  this.value = undefined;
466
514
  }
@@ -510,6 +558,7 @@ export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
510
558
  return false;
511
559
  }
512
560
  }
561
+ /** @overridable Extracts the selectable `value` out of a raw datasource entity (via {@link valueProperty}, or `entity.value` for a {@link PacemDataItemElement}). */
513
562
  mapEntityToValue(entity) {
514
563
  if (entity == null) {
515
564
  throw 'entity cannot be null';
@@ -525,6 +574,7 @@ export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
525
574
  }
526
575
  return value;
527
576
  }
577
+ /** @overridable Extracts the display text out of a raw datasource entity (via {@link textProperty}, or `entity.label`/`entity.value` for a {@link PacemDataItemElement}). */
528
578
  mapEntityToViewValue(entity) {
529
579
  if (entity == null)
530
580
  throw 'entity cannot be null';
@@ -539,6 +589,7 @@ export class PacemDataSourceElement extends PacemItemsContainerBaseElement {
539
589
  }
540
590
  return viewValue;
541
591
  }
592
+ /** @overridable Adapts a raw datasource entity into its normalized {@link DataSourceItem} shape, using {@link mapEntityToValue}, {@link mapEntityToViewValue} and {@link disabledProperty}. */
542
593
  mapEntityToItem(entity) {
543
594
  if (entity == null) {
544
595
  throw 'entity cannot be null';
package/dist/esm/types.js CHANGED
@@ -1,10 +1,12 @@
1
1
  /*!
2
- * @pacem/pacem-scaffolding v1.0.0-bessel (https://js.pacem.it)
2
+ * @pacem/pacem-scaffolding v1.0.0-dirac (https://js.pacem.it)
3
3
  * Pacem (https://pacem.it)
4
4
  * Licensed under Apache-2.0
5
5
  */
6
6
  import { CustomTypedEvent } from '@pacem/pacem-core';
7
+ /** Event type name (`'change'`) dispatched as a {@link FieldChangeEvent}. */
7
8
  export const FieldChangeEventName = 'change';
9
+ /** Dispatched by a scaffolding field (see `PacemBaseElement.changeHandler` in `types-components.ts`) whenever its `value` actually changes as a result of user interaction; bubbles so an ancestor {@link PacemFormElement}/`PacemFormFieldElement` can react to it. */
8
10
  export class FieldChangeEvent extends CustomTypedEvent {
9
11
  constructor(args) {
10
12
  super(FieldChangeEventName, args, { bubbles: true, cancelable: false });
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * @pacem/pacem-scaffolding v1.0.0-bessel (https://js.pacem.it)
2
+ * @pacem/pacem-scaffolding v1.0.0-dirac (https://js.pacem.it)
3
3
  * Pacem (https://pacem.it)
4
4
  * Licensed under Apache-2.0
5
5
  */
@@ -12,6 +12,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
12
12
  import { Watch, P, PCSS, CustomElement, ViewChild, Utils, PropertyConverters, Defaults, DeferPromise } from '@pacem/pacem-core';
13
13
  import { PacemFormRelevantElement } from './form';
14
14
  // TODO: add warning state
15
+ /**
16
+ * Base class for all `p-*-validator` elements: registers/unregisters itself against the ancestor
17
+ * {@link PacemFormElement} field named by `watch`, and turns the abstract {@link evaluate} logic into the
18
+ * `Validator` contract's `validate` (short-circuiting to valid when `disabled`). Concrete validators only
19
+ * need to implement {@link evaluate}; the field's own error UI reads `invalid`/`errorMessage` off the
20
+ * element (see {@link BASIC_VALIDATOR_TEMPLATE}).
21
+ */
15
22
  export class PacemBaseValidatorElement extends PacemFormRelevantElement {
16
23
  constructor() {
17
24
  super();
@@ -45,6 +52,7 @@ export class PacemBaseValidatorElement extends PacemFormRelevantElement {
45
52
  }
46
53
  }
47
54
  #easer;
55
+ /** Asks the owning {@link PacemFormElement} to re-validate the watched field on the next animation frame; call after a configuration property (e.g. `min`/`max`/`pattern`) changes so the field re-evaluates against the new rule. */
48
56
  triggerFormFieldValidation() {
49
57
  const form = this.form, watch = this.watch;
50
58
  if (!Utils.isNull(form) && !Utils.isNullOrEmpty(watch)) {
@@ -54,6 +62,7 @@ export class PacemBaseValidatorElement extends PacemFormRelevantElement {
54
62
  });
55
63
  }
56
64
  }
65
+ /** Validates `val` against this validator's rule; always resolves `true` (skips {@link evaluate}) when the validator is `disabled`. */
57
66
  validate(val) {
58
67
  if (this.disabled) {
59
68
  return Utils.fromResult(true);
@@ -70,11 +79,13 @@ __decorate([
70
79
  __decorate([
71
80
  Watch({ emit: false, reflectBack: true, converter: PropertyConverters.String })
72
81
  ], PacemBaseValidatorElement.prototype, "watch", void 0);
82
+ /** Default shadow-DOM template shared by every built-in `p-*-validator`: a `<p-span>` (exposed as the `error-message` part) shown only while `invalid`, displaying `errorMessage`. */
73
83
  export const BASIC_VALIDATOR_TEMPLATE = `<${P}-span part="error-message" hide="{{ !:host.invalid }}" text="{{ :host.errorMessage }}"></${P}-span>`;
74
84
  // #region TEXTUAL
75
85
  function isValueEmpty(val) {
76
86
  return Utils.isNullOrEmpty(val);
77
87
  }
88
+ /** Validates that a field's value is not empty (`p-required-validator`). */
78
89
  let PacemRequiredValidatorElement = class PacemRequiredValidatorElement extends PacemBaseValidatorElement {
79
90
  evaluate(val) {
80
91
  let retval = !isValueEmpty(val);
@@ -85,6 +96,7 @@ PacemRequiredValidatorElement = __decorate([
85
96
  CustomElement({ tagName: P + '-required-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: Defaults.USE_SHADOW_ROOT })
86
97
  ], PacemRequiredValidatorElement);
87
98
  export { PacemRequiredValidatorElement };
99
+ /** Validates that a field's (non-empty) value matches a regular expression (`p-regex-validator`). */
88
100
  let PacemRegexValidatorElement = class PacemRegexValidatorElement extends PacemBaseValidatorElement {
89
101
  propertyChangedCallback(name, old, val, first) {
90
102
  super.propertyChangedCallback(name, old, val, first);
@@ -107,6 +119,7 @@ PacemRegexValidatorElement = __decorate([
107
119
  CustomElement({ tagName: P + '-regex-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: Defaults.USE_SHADOW_ROOT })
108
120
  ], PacemRegexValidatorElement);
109
121
  export { PacemRegexValidatorElement };
122
+ /** Validates that a field's (non-empty) value's string length falls within `[min, max]` (`p-length-validator`). */
110
123
  let PacemLengthValidatorElement = class PacemLengthValidatorElement extends PacemBaseValidatorElement {
111
124
  propertyChangedCallback(name, old, val, first) {
112
125
  super.propertyChangedCallback(name, old, val, first);
@@ -138,6 +151,7 @@ PacemLengthValidatorElement = __decorate([
138
151
  export { PacemLengthValidatorElement };
139
152
  // #endregion
140
153
  // #region NUMERIC/ORDINAL
154
+ /** Validates that a field's (non-empty) numeric or date value falls within `[min, max]` (`p-range-validator`); dates (parsed via `Utils.parseDate`) are compared by their timestamp. */
141
155
  let PacemRangeValidatorElement = class PacemRangeValidatorElement extends PacemBaseValidatorElement {
142
156
  propertyChangedCallback(name, old, val, first) {
143
157
  super.propertyChangedCallback(name, old, val, first);
@@ -178,6 +192,7 @@ PacemRangeValidatorElement = __decorate([
178
192
  export { PacemRangeValidatorElement };
179
193
  // #endregion
180
194
  // #region COMPLEX
195
+ /** Validates a field's (non-empty) value against another (non-empty) value `to`, using the given comparison `operator` (`p-compare-validator`); dates are compared by their timestamp. */
181
196
  let PacemCompareValidatorElement = class PacemCompareValidatorElement extends PacemBaseValidatorElement {
182
197
  propertyChangedCallback(name, old, val, first) {
183
198
  super.propertyChangedCallback(name, old, val, first);
@@ -233,6 +248,7 @@ PacemCompareValidatorElement = __decorate([
233
248
  ], PacemCompareValidatorElement);
234
249
  export { PacemCompareValidatorElement };
235
250
  // #endregion
251
+ /** Validates a {@link BinaryValue}/file-name (non-empty) upload against an optional filename `pattern` and/or `maxSize` in bytes (`p-binary-validator`). */
236
252
  let PacemBinaryValidatorElement = class PacemBinaryValidatorElement extends PacemBaseValidatorElement {
237
253
  propertyChangedCallback(name, old, val, first) {
238
254
  super.propertyChangedCallback(name, old, val, first);
@@ -267,6 +283,13 @@ PacemBinaryValidatorElement = __decorate([
267
283
  CustomElement({ tagName: P + '-binary-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: Defaults.USE_SHADOW_ROOT })
268
284
  ], PacemBinaryValidatorElement);
269
285
  export { PacemBinaryValidatorElement };
286
+ /**
287
+ * Validates a field's (non-empty) value by calling a remote `url` (`p-async-validator`), sending it - along
288
+ * with any extra `parameters` - as a request parameter named after {@link PacemBaseValidatorElement#watch}.
289
+ * The response is considered valid when it is the literal text `'true'`, or a fetched JSON payload whose API
290
+ * result (see `Utils.getApiResult`) is truthy; anything else (including a failed fetch) is invalid.
291
+ * Debounces requests by 1 second and memoizes the last request/result to avoid redundant round-trips.
292
+ */
270
293
  let PacemAsyncValidatorElement = class PacemAsyncValidatorElement extends PacemBaseValidatorElement {
271
294
  constructor() {
272
295
  super(...arguments);
@@ -389,6 +412,7 @@ PacemAsyncValidatorElement = __decorate([
389
412
  })
390
413
  ], PacemAsyncValidatorElement);
391
414
  export { PacemAsyncValidatorElement };
415
+ /** Validates a field's (non-empty) value by deferring entirely to the externally-controlled {@link isValid} flag (`p-custom-validator`), for validation logic that doesn't fit the other built-in validators. */
392
416
  let PacemCustomValidatorElement = class PacemCustomValidatorElement extends PacemBaseValidatorElement {
393
417
  propertyChangedCallback(name, old, val, first) {
394
418
  super.propertyChangedCallback(name, old, val, first);
package/package.json CHANGED
@@ -4,6 +4,7 @@
4
4
  "dist/browser/*.*",
5
5
  "dist/bundle/*.*",
6
6
  "dist/esm/*.*",
7
+ "dist/docs/*.*",
7
8
  "typings/*.*",
8
9
  "README.md",
9
10
  "LICENSE",
@@ -24,7 +25,7 @@
24
25
  "types": "./typings/index.d.ts"
25
26
  }
26
27
  },
27
- "version": "1.0.0-bessel",
28
+ "version": "1.0.0-dirac",
28
29
  "author": {
29
30
  "name": "Pacem",
30
31
  "url": "https://pacem.it"