@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
  */
@@ -32,6 +32,7 @@ function buildMonthGrid() {
32
32
  }
33
33
  return header;
34
34
  }
35
+ /** Utility 12-month grid picker, used internally by {@link PacemCalendarPickerElement} to pick a month within {@link viewYear}. */
35
36
  let PacemCalendarMonthPickerElement = class PacemCalendarMonthPickerElement extends Components.PacemElement {
36
37
  propertyChangedCallback(name, old, val, first) {
37
38
  super.propertyChangedCallback(name, old, val, first);
@@ -81,6 +82,7 @@ PacemCalendarMonthPickerElement = __decorate([
81
82
  })
82
83
  ], PacemCalendarMonthPickerElement);
83
84
  export { PacemCalendarMonthPickerElement };
85
+ /** Dispatched by {@link PacemCalendarPickerElement} when its clear button is used to unselect the current date. */
84
86
  export class CalendarDateUnselectEvent extends ComponentsUI.UI.DateSelectEvent {
85
87
  constructor() {
86
88
  super(void 0);
@@ -100,6 +102,7 @@ function rangeFirstYear(y) {
100
102
  const mod = y % 10;
101
103
  return y - mod;
102
104
  }
105
+ /** Utility grid picker of {@link YEARS_IN_RANGE} years, used internally by {@link PacemCalendarPickerElement} to pick a year within the range containing {@link viewYear}. */
103
106
  let PacemCalendarYearPickerElement = class PacemCalendarYearPickerElement extends Components.PacemElement {
104
107
  propertyChangedCallback(name, old, val, first) {
105
108
  super.propertyChangedCallback(name, old, val, first);
@@ -157,9 +160,11 @@ function buildCalendarHeader() {
157
160
  }
158
161
  return `<${P}-panel hide="{{ :host.viewmode !== 'calendar' }}" class="calendar-header">${header}</${P}-panel>`;
159
162
  }
163
+ /** {@link PacemBaseInputElement}-alike field that pops up a `pacem-calendar` (with month/year zoom levels) to pick a `Date` value. */
160
164
  let PacemCalendarPickerElement = class PacemCalendarPickerElement extends PacemBaseElement {
161
165
  constructor() {
162
166
  super(...arguments);
167
+ /** Gets or sets which picker is currently shown in the dropdown: the day calendar, the month grid, or the year grid. */
163
168
  this.viewmode = 'calendar';
164
169
  this.#locked = false;
165
170
  this._swipeHandler = (e) => {
@@ -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
  */
@@ -11,7 +11,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
11
11
  };
12
12
  import { Components, CustomElement, Defaults, P, PCSS, PropertyConverters, Watch } from '@pacem/pacem-core';
13
13
  //namespace Pacem.Components.Scaffolding {
14
+ /** Markup fragment for a `pacem-char-count` companion element, meant to be spliced into a `@CustomElement` template so a text field can display its own character counter. */
14
15
  export const CHAR_COUNTER_CHILD = `<${P}-char-count hide="{{ :host.readonly || !(:host.minlength > 0 || :host.maxlength > 0) }}" minlength="{{ :host.minlength }}" maxlength="{{ :host.maxlength }}" string="{{ :host.value }}"></${P}-char-count>`;
16
+ /** Displays how many characters {@link string} contains, relative to {@link minlength}/{@link maxlength}, flagging validity via CSS class. */
15
17
  let PacemCharCountElement = class PacemCharCountElement extends Components.PacemElement {
16
18
  _isValid(v) {
17
19
  const l = this._length(v);
@@ -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,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
12
12
  import { CustomElement, Defaults, P, PCSS, PropertyChangeEventName, Utils, ViewChild } from '@pacem/pacem-core';
13
13
  import { PacemDataSourceElement } from './types-components';
14
14
  //namespace Pacem.Components.Scaffolding {
15
+ /** Renders {@link PacemDataSourceElement#datasource} as a list of `pacem-checkbox` items, producing an array `value` of the checked items' mapped values. */
15
16
  let PacemCheckboxListElement = class PacemCheckboxListElement extends PacemDataSourceElement {
16
17
  acceptValue(val) {
17
18
  // no need to implement
@@ -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
  */
@@ -16,9 +16,11 @@ const StringOrBooleanPropertyConverter = {
16
16
  convert: (attr) => attr === 'true' ? true : (attr === 'false' ? false : attr),
17
17
  convertBack: (prop) => prop.toString()
18
18
  };
19
+ /** {@link PacemBaseElement}-based single checkbox field, mapping its checked state to {@link trueValue}/{@link falseValue}. */
19
20
  let PacemCheckboxElement = class PacemCheckboxElement extends PacemBaseElement {
20
21
  constructor() {
21
22
  super('checkbox');
23
+ /** Gets or sets the label displayed next to the checkbox (and used as the read-only view value when checked). */
22
24
  this.caption = '';
23
25
  this._key = '_' + Utils.uniqueCode();
24
26
  }
@@ -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
  */
@@ -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
  */
@@ -21,6 +21,7 @@ class ContenteditableChangeEvent extends CustomTypedEvent {
21
21
  super('contenteditablechange', { html: html });
22
22
  }
23
23
  }
24
+ /** Base class for {@link PacemContenteditableElement} toolbar/command items, registered as {@link PacemItemElement} children of the editor. */
24
25
  export class PacemContenteditableCommandElement extends PacemItemElement {
25
26
  constructor() {
26
27
  super(...arguments);
@@ -77,6 +78,7 @@ function isFileCommand(obj) {
77
78
  function isElement(node) {
78
79
  return node?.nodeType == Node.ELEMENT_NODE;
79
80
  }
81
+ /** Rich-text (`contenteditable`) field, hosting {@link PacemContenteditableCommandElement} toolbar commands and tracking an undo/redo {@link history}. */
80
82
  let PacemContenteditableElement = class PacemContenteditableElement extends PacemItemsContainerBaseElement {
81
83
  constructor() {
82
84
  super('rich text editor');
@@ -157,6 +159,7 @@ let PacemContenteditableElement = class PacemContenteditableElement extends Pace
157
159
  //this._workspace = document.createElement('div');
158
160
  }
159
161
  #history;
162
+ /** @readonly Gets the undo/redo history service tracking this editor's HTML content. */
160
163
  get history() {
161
164
  return this.#history;
162
165
  }
@@ -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
  */
@@ -29,17 +29,24 @@ const JsonOrStringConverter = {
29
29
  // super('datetimechange', { date: date });
30
30
  // }
31
31
  //}
32
+ /** {@link PacemBaseElement}-based field composing a set of `pacem-select` dropdowns (year/month/day and, depending on {@link precision}, time) into a single `Date` value. */
32
33
  let PacemDatetimePickerElement = class PacemDatetimePickerElement extends PacemBaseElement {
33
34
  constructor() {
34
35
  super();
36
+ /** Gets or sets the granularity of the picker: date only, or including hours/minutes ('minute') or hours/minutes/seconds ('second'). */
35
37
  this.precision = 'day';
36
38
  this._months = [];
39
+ /** Internal: datasource of selectable days for the current {@link year}/{@link month}. */
37
40
  this._dates = [];
38
41
  this._a24 = [];
39
42
  this._a60 = [];
43
+ /** Internal: datasource of selectable years, computed from {@link min}/{@link max}. */
40
44
  this._years = [];
45
+ /** Internal: the hours select's current value. */
41
46
  this.hours = '00';
47
+ /** Internal: the minutes select's current value. */
42
48
  this.minutes = '00';
49
+ /** Internal: the seconds select's current value. */
43
50
  this.seconds = '00';
44
51
  }
45
52
  get inputFields() {
package/dist/esm/form.js CHANGED
@@ -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,20 +12,37 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
12
12
  import { P, PCSS, CustomElement, Watch, Utils, PropertyConverters, CustomTypedEvent, CommandEventName, Components, Net, Debounce, avoidHandler, PropertyChangeEvent, PropertyChangeEventName, DeferPromise, Logging, CustomElementUtils } from '@pacem/pacem-core';
13
13
  import { PacemModelElement } from './types-components';
14
14
  import { FieldChangeEventName } from './types';
15
+ /** Event type name (`'submit'`) dispatched as a {@link FormSubmitEvent}. */
15
16
  export const FormSubmitEventName = 'submit';
17
+ /** Event type name (`'reset'`) dispatched as a {@link FormResetEvent}. */
16
18
  export const FormResetEventName = 'reset';
19
+ /**
20
+ * Dispatched by {@link PacemFormElement} right before a submission is actually sent to the server, once all
21
+ * fields have validated successfully. Cancelable: calling `preventDefault()` (or handling the event and
22
+ * returning `false`) aborts the submission before any request is made - useful to inject/transform
23
+ * {@link FormSubmitEventArgs#parameters} or veto the submit outright.
24
+ */
17
25
  export class FormSubmitEvent extends CustomTypedEvent {
18
26
  constructor(args) {
19
27
  super(FormSubmitEventName, args, { bubbles: true, cancelable: true });
20
28
  }
21
29
  }
30
+ /** Dispatched by {@link PacemFormElement} when the form is about to be reset (programmatically or via its generated reset button). Cancelable: calling `preventDefault()` aborts the reset, leaving fields as they were. */
22
31
  export class FormResetEvent extends Event {
23
32
  constructor() {
24
33
  super(FormResetEventName, { bubbles: true, cancelable: true });
25
34
  }
26
35
  }
36
+ /** Event types re-dispatched/handled on behalf of a {@link PacemFormElement} by its {@link FormEventEmitter}: upload `download` events, field {@link FieldChangeEventName} changes, and item `command` events (see {@link Components.CommandEvent}). */
27
37
  const EMITTABLE_EVENT_TYPES = ['download' /* < dedicated, for the upload custom element */, FieldChangeEventName /* expose */, CommandEventName];
38
+ /** Sentinel value used to reject a submission's promise when it was canceled via {@link FormSubmitEvent#preventDefault}, as opposed to a genuine fetch failure. */
28
39
  const SUBMIT_CANCELLATION_TOKEN = false;
40
+ /**
41
+ * Listens on a {@link PacemEventTarget} (typically a {@link PacemFormElement}) for the events listed in
42
+ * {@link EMITTABLE_EVENT_TYPES} and pipes each through the target's `handle` method, additionally
43
+ * re-dispatching `command` events as a synthesized `'item' + commandName`-named `CustomEvent` (e.g.
44
+ * `itemdelete`, `itemselect`) so listeners can subscribe to the specific command they care about.
45
+ */
29
46
  export class FormEventEmitter {
30
47
  constructor(_element) {
31
48
  this._element = _element;
@@ -39,13 +56,16 @@ export class FormEventEmitter {
39
56
  }
40
57
  };
41
58
  }
59
+ /** Starts listening for {@link EMITTABLE_EVENT_TYPES} on the target element. */
42
60
  start() {
43
61
  EMITTABLE_EVENT_TYPES.forEach(t => this._element.addEventListener(t, this._itemEmitHandler, false));
44
62
  }
63
+ /** Stops listening for {@link EMITTABLE_EVENT_TYPES} on the target element. */
45
64
  stop() {
46
65
  EMITTABLE_EVENT_TYPES.forEach(t => this._element.removeEventListener(t, this._itemEmitHandler, false));
47
66
  }
48
67
  }
68
+ /** Base class for elements that need a reference to their closest ancestor {@link PacemFormElement} (form fields, validators): resolves and exposes it as {@link form} on activation. */
49
69
  export class PacemFormRelevantElement extends Components.PacemElement {
50
70
  viewActivatedCallback() {
51
71
  super.viewActivatedCallback();
@@ -55,9 +75,18 @@ export class PacemFormRelevantElement extends Components.PacemElement {
55
75
  __decorate([
56
76
  Watch({ converter: PropertyConverters.Element })
57
77
  ], PacemFormRelevantElement.prototype, "form", void 0);
78
+ /**
79
+ * `<p-form>`: the scaffolding package's central form element. Aggregates the validity/dirty state of its
80
+ * registered fields ({@link registerField}) and validators ({@link registerValidator}), of any nested
81
+ * sub-forms ({@link registerSubForm} - e.g. from a {@link Pacem.Components.Scaffolding.PacemChildFormElement}
82
+ * in `childform.ts`), drives submission ({@link submit}) and reset ({@link reset}), and - when `autogenerate`
83
+ * is `true` and `metadata` is provided - builds its own field markup from a {@link TypeMetadata}/
84
+ * {@link PropertyMetadata} description instead of requiring hand-authored markup.
85
+ */
58
86
  let PacemFormElement = class PacemFormElement extends PacemFormRelevantElement {
59
87
  constructor() {
60
88
  super('form');
89
+ /** Gets or sets the HTTP method used by the auto-generated fetcher. Defaults to `POST`. */
61
90
  this.method = Net.HttpMethod.Post;
62
91
  this._emitter = null;
63
92
  this._buttons = { submit: undefined, reset: undefined };
@@ -223,6 +252,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
223
252
  return this._buttons;
224
253
  }
225
254
  #fetching;
255
+ /** @readonly Gets whether a submission is currently in flight; also reflected as the `pacem-fetching` CSS class. */
226
256
  get fetching() {
227
257
  return this.#fetching;
228
258
  }
@@ -404,6 +434,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
404
434
  }
405
435
  return Promise.resolve(false);
406
436
  }
437
+ /**
438
+ * Validates a single named field, or - when `name` is omitted - every field of this form and its
439
+ * sub-forms, running each field's registered validators and updating their `valid`/`invalid` state.
440
+ * @param name Optional name of a single field to validate; validates the whole form (recursively) when omitted.
441
+ */
407
442
  // @Concurrent()
408
443
  validate(name) {
409
444
  if (!Utils.isNullOrEmpty(name)) {
@@ -502,6 +537,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
502
537
  this.valid = valid;
503
538
  }
504
539
  ;
540
+ /**
541
+ * Registers a nested {@link PacemFormElement} (e.g. rendered by a `PacemChildFormElement`, see
542
+ * `childform.ts`) so its fields' validity/dirtyness roll up into this form's own {@link valid}/{@link dirty}.
543
+ * @param form Sub-form to enroll
544
+ */
505
545
  registerSubForm(form) {
506
546
  let arr = this._subForms;
507
547
  if (arr.indexOf(form) == -1) {
@@ -511,6 +551,10 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
511
551
  this._checkDirtyness();
512
552
  }
513
553
  }
554
+ /**
555
+ * Removes a previously-registered nested form; its fields no longer influence this form's {@link valid}/{@link dirty}.
556
+ * @param form Sub-form to remove
557
+ */
514
558
  unregisterSubForm(form) {
515
559
  let arr = this._subForms, ndx = arr.indexOf(form);
516
560
  if (ndx >= 0) {
@@ -520,6 +564,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
520
564
  this._checkDirtyness();
521
565
  }
522
566
  }
567
+ /**
568
+ * Registers a field's {@link PacemModel} under `name`, so it is included in submission ({@link FormSubmitEventArgs#fields}), validation, dirty/valid roll-up and reset. Typically called by the field itself (see `PacemModelElement._registerFieldConditionally` in `types-components.ts`) rather than directly.
569
+ * @param name Field name to register under
570
+ * @param model Field implementing {@link PacemModel}
571
+ */
523
572
  registerField(name, model) {
524
573
  var container = this._fields;
525
574
  if (container[name] != model) {
@@ -533,6 +582,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
533
582
  this._checkDirtyness();
534
583
  }
535
584
  }
585
+ /**
586
+ * Removes a previously-registered field.
587
+ * @param name Field name to remove
588
+ * @param check Whether to re-check the form's overall validity/dirtyness afterwards (default `true`)
589
+ */
536
590
  unregisterField(name, check = true) {
537
591
  var container = this._fields, current = container[name];
538
592
  if (current instanceof HTMLElement) {
@@ -544,6 +598,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
544
598
  this._checkDirtyness();
545
599
  }
546
600
  }
601
+ /**
602
+ * Registers a {@link Validator} (typically a {@link PacemBaseValidatorElement}) against the named field, so it participates in that field's validation. Typically called by the validator itself rather than directly.
603
+ * @param name Name of the field being validated
604
+ * @param validator Validator to enroll
605
+ */
547
606
  registerValidator(name, validator) {
548
607
  var container = this._validators[name] = this._validators[name] || [], index = container.indexOf(validator);
549
608
  if (index == -1) {
@@ -556,6 +615,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
556
615
  this._checkFieldValidity(name);
557
616
  }
558
617
  }
618
+ /**
619
+ * Removes a previously-registered validator from the named field.
620
+ * @param name Name of the field the validator was registered against
621
+ * @param validator Validator to remove
622
+ */
559
623
  unregisterValidator(name, validator) {
560
624
  this._unregisterValidator(name, validator, true);
561
625
  }
@@ -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
  */
@@ -27,6 +27,11 @@ function isKnownValidator(v) {
27
27
  function isValidatorFactory(v) {
28
28
  return 'attributes' in v && typeof v.attributes === 'function';
29
29
  }
30
+ /**
31
+ * Renders a single editing field (label, input, validators, tooltip) for {@link entity}'s property described by {@link metadata},
32
+ * dynamically choosing and building up the concrete input element (e.g. `pacem-input-text`, `pacem-select`, `pacem-checkbox`, ...)
33
+ * based on the metadata's `dataType`/`ui` hints. Used internally by `pacem-form` for autogenerated forms.
34
+ */
30
35
  let PacemFormFieldElement = class PacemFormFieldElement extends PacemFormRelevantElement {
31
36
  constructor(_md = new ComponentsUI.UI.MarkdownService()) {
32
37
  super();
@@ -40,12 +45,15 @@ let PacemFormFieldElement = class PacemFormFieldElement extends PacemFormRelevan
40
45
  };
41
46
  this._key = '_' + Utils.uniqueCode();
42
47
  }
48
+ /** @readonly Gets this field's unique key, used to derive DOM ids for the label/input/fetcher. */
43
49
  get key() {
44
50
  return this._key;
45
51
  }
52
+ /** @readonly Gets the inner `pacem-fetch` element used to retrieve remotely-sourced datasources for this field. */
46
53
  get fetcher() {
47
54
  return this._fetcher;
48
55
  }
56
+ /** @readonly Gets the concrete input element built for this field (e.g. `pacem-input-text`, `pacem-select`, ...). */
49
57
  get field() {
50
58
  return this._field;
51
59
  }
@@ -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
  */
@@ -14,6 +14,7 @@ import { Components as ComponentsMaps, Maps } from '@pacem/pacem-maps';
14
14
  import { PacemBaseElement } from './types-components';
15
15
  import { FieldChangeEventName } from './types';
16
16
  const MIN_LENGTH = 3;
17
+ /** {@link PacemBaseElement}-based field pairing an address `pacem-suggest` (forward geocoding) with a draggable map marker (reverse geocoding) to pick an {@link Address}. */
17
18
  let PacemGeolocateElement = class PacemGeolocateElement extends PacemBaseElement {
18
19
  constructor() {
19
20
  super(...arguments);
@@ -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
  */
@@ -29,6 +29,10 @@ const HIERARCHYITEM_LINK_ICON = 'link';
29
29
  const HIERARCHYITEM_MOVE_CSSCLASS = 'item-move';
30
30
  const HIERARCHYITEM_MOVE_ICON = 'drag_indicator';
31
31
  const DEFAULT_PARENTSPROPERTY = 'parents';
32
+ /**
33
+ * {@link PacemBaseElement}-based field for editing a DAG-like parent/child hierarchy over {@link datasource}: items are
34
+ * arranged level-by-level and linked/unlinked via drag-drop, producing an array `value` of `{ [valueProperty]: any, parents: any[] }`.
35
+ */
32
36
  let PacemHierarchyElement = class PacemHierarchyElement extends PacemBaseElement {
33
37
  getViewValue(value) {
34
38
  return '';
@@ -40,6 +44,7 @@ let PacemHierarchyElement = class PacemHierarchyElement extends PacemBaseElement
40
44
  super();
41
45
  this.#bindings = new Map();
42
46
  this.#dropTargets = new Map();
47
+ /** Gets or sets the caption of the balloon button used to unlink a parent/child relation. */
43
48
  this.unlinkCaption = 'Delete';
44
49
  this._binderClickHandler = (evt) => {
45
50
  const origType = evt.originalEvent.type;
@@ -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
  */
@@ -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
  */
@@ -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
  */
@@ -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
  */
@@ -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
  */
package/dist/esm/index.js CHANGED
@@ -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
  */
@@ -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
  */
@@ -13,10 +13,13 @@ import { Arrays } from '@pacem/pacem-foundation';
13
13
  import { Components, PropertyConverters, Utils, P, PCSS, CustomElement, Watch, Defaults, ViewChild } from '@pacem/pacem-core';
14
14
  import { PacemBaseInputElement } from './input';
15
15
  //namespace Pacem.Components.Scaffolding {
16
+ /** {@link PacemBaseInputElement} rendering one single-character `<input>` per position (e.g. OTP/verification codes), joining them into a single string `value`. */
16
17
  let PacemCharsInputElement = class PacemCharsInputElement extends PacemBaseInputElement {
17
18
  constructor() {
18
19
  super();
20
+ /** Gets or sets how many single-character inputs to render. */
19
21
  this.charCount = 6;
22
+ /** Gets or sets how the entered characters are transformed/displayed: as-is, forced to a case, or masked like a password. */
20
23
  this.inputTransform = 'none';
21
24
  this._itemCreateHandler = (e) => {
22
25
  const { dom, index } = e.detail;
@@ -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
  */
@@ -13,6 +13,7 @@ import { Colors } from '@pacem/pacem-foundation';
13
13
  import { Utils, P, PCSS, CustomElement, Defaults, ViewChild } from '@pacem/pacem-core';
14
14
  import { PacemBaseElement } from './types-components';
15
15
  //namespace Pacem.Components.Scaffolding {
16
+ /** {@link PacemBaseElement}-based field pairing a native color picker with an alpha (0-100) slider, producing a hex/rgba color string `value`. */
16
17
  let PacemColorInputElement = class PacemColorInputElement extends PacemBaseElement {
17
18
  acceptValue(val) {
18
19
  const parsed = this._parseValue(val);
@@ -57,7 +58,7 @@ let PacemColorInputElement = class PacemColorInputElement extends PacemBaseEleme
57
58
  return value;
58
59
  }
59
60
  get inputFields() {
60
- return [this._tint, this._alpha];
61
+ return [this._tint, this._alpha].filter(e => !Utils.isNull(e));
61
62
  }
62
63
  };
63
64
  __decorate([
@@ -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,25 +9,31 @@ 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, Defaults, ViewChild } from '@pacem/pacem-core';
12
+ import { P, PCSS, CustomElement, Utils, Defaults, ViewChild } 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
+ /** {@link PacemTextualInputElement} for an `<input type="email">`, whose read-only view renders as a `mailto:` link. */
16
17
  let PacemEmailInputElement = class PacemEmailInputElement extends PacemTextualInputElement {
17
18
  toggleReadonlyView(readonly) {
18
- this.input.hidden = readonly;
19
- this.anchor.hidden = !readonly;
19
+ const input = this._input, anchor = this._anchor;
20
+ if (!Utils.isNull(input))
21
+ input.hidden = readonly;
22
+ if (!Utils.isNull(anchor))
23
+ anchor.hidden = !readonly;
20
24
  }
21
25
  get inputFields() {
22
- return [this.input];
26
+ return Utils.isNull(this._input)
27
+ ? []
28
+ : [this._input];
23
29
  }
24
30
  };
25
31
  __decorate([
26
32
  ViewChild('input[type=email]')
27
- ], PacemEmailInputElement.prototype, "input", void 0);
33
+ ], PacemEmailInputElement.prototype, "_input", void 0);
28
34
  __decorate([
29
35
  ViewChild(P + '-a')
30
- ], PacemEmailInputElement.prototype, "anchor", void 0);
36
+ ], PacemEmailInputElement.prototype, "_anchor", void 0);
31
37
  PacemEmailInputElement = __decorate([
32
38
  CustomElement({
33
39
  tagName: P + '-input-email',
@@ -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
  */
@@ -11,18 +11,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
11
11
  };
12
12
  import { P, PCSS, CustomElement, Watch, Defaults, ViewChild, CustomTypedEvent, CustomEventUtils, PropertyConverters, Animations, Utils, stopPropagationHandler, avoidHandler } from '@pacem/pacem-core';
13
13
  import { PacemBaseElement } from './types-components';
14
+ /** Name of the {@link FileUploadEvent} dispatched by {@link PacemUploadElement} while/after a chunked upload progresses. */
14
15
  export const FileUploadEventName = 'fileupload';
16
+ /** Name of the {@link FileChangeEvent} dispatched by {@link PacemUploadElement} whenever the selected file(s)/directory change. */
15
17
  export const FileChangeEventName = 'filechange';
16
18
  class StoragePickEvent extends CustomTypedEvent {
17
19
  constructor(file) {
18
20
  super('pick', file);
19
21
  }
20
22
  }
23
+ /** Dispatched by {@link PacemUploadElement} to report chunked-upload progress/completion. */
21
24
  export class FileUploadEvent extends CustomTypedEvent {
22
25
  constructor(file) {
23
26
  super(FileUploadEventName, file);
24
27
  }
25
28
  }
29
+ /** Dispatched by {@link PacemUploadElement} whenever the user picks (or clears) file(s)/a directory. */
26
30
  export class FileChangeEvent extends CustomTypedEvent {
27
31
  constructor(file) {
28
32
  super(FileChangeEventName, file);
@@ -53,20 +57,30 @@ async function computeFileStats(files) {
53
57
  return stats;
54
58
  }
55
59
  /**
56
- * PacemUploader Component
60
+ * PacemUploader Component: {@link PacemBaseElement}-based field to pick and (optionally chunk-)upload file(s)/a directory to {@link url},
61
+ * or defer to the File System Access API pickers depending on {@link selectMode}.
57
62
  */
58
63
  let PacemUploadElement = class PacemUploadElement extends PacemBaseElement {
59
64
  constructor(_tweener = new Animations.TweenService()) {
60
65
  super();
61
66
  this._tweener = _tweener;
67
+ /** Gets or sets the caption of the "undo" button, shown while an upload with {@link url} set is in progress. */
62
68
  this.undoCaption = 'undo';
69
+ /** Gets or sets the caption of the "retry" button, shown after a {@link failed} upload. */
63
70
  this.retryCaption = 'retry';
71
+ /** Gets or sets the caption of the "clear" button. */
64
72
  this.clearCaption = 'clear';
73
+ /** @readonly Gets whether an upload is currently in progress. */
65
74
  this.uploading = false;
75
+ /** @readonly Gets the total size (in bytes) of the file(s) currently being uploaded. */
66
76
  this.size = 0;
77
+ /** @readonly Gets the current upload progress, from 0 to 100. */
67
78
  this.percentage = .0;
79
+ /** @readonly Gets whether the current upload has completed. */
68
80
  this.complete = false;
81
+ /** @readonly Gets whether the current upload chunk request failed (enabling the retry button). */
69
82
  this.failed = false;
83
+ /** @readonly Gets whether the selected file failed {@link pattern}/{@link maxSize} validation. */
70
84
  this.invalidFile = false;
71
85
  this._fields = {
72
86
  'parallelism': 3,
@@ -126,11 +140,14 @@ let PacemUploadElement = class PacemUploadElement extends PacemBaseElement {
126
140
  }
127
141
  return 'filter_none';
128
142
  }
143
+ /** @readonly Gets the raw blob currently being (or last) uploaded. */
129
144
  get blob() {
130
145
  return this._fields.blob;
131
146
  }
132
147
  get inputFields() {
133
- return [this._fileupload];
148
+ return Utils.isNull(this._fileupload)
149
+ ? []
150
+ : [this._fileupload];
134
151
  }
135
152
  getViewValue(val) {
136
153
  const value = this._localValue || val;