@ng-doc/app 22.0.0 → 22.2.0

package/types/ng-doc-app-type-controls-list-control.d.ts

@@ -0,0 +1,313 @@
+import * as _angular_core from '@angular/core';
+import { Signal } from '@angular/core';
+import { NgDocResolvedPlaygroundOption } from '@ng-doc/app/helpers';
+import { NgDocTypeControl, NgDocPlaygroundTexts } from '@ng-doc/app/interfaces';
+import { NgDocPlaygroundOption } from '@ng-doc/core/interfaces';
+import { DIControl } from 'di-controls';
+
+/** A value that an item of an array control can be. */
+type NgDocListControlItem = string | number | boolean;
+/** A row of the dropdown of an array control. */
+interface NgDocListControlRow<T> {
+    /** `add` for the row that adds the typed text, `item` for a suggestion or a value of a union. */
+    kind: 'add' | 'item';
+    /** The value that the row adds. */
+    value: T;
+    /** The text of the value. */
+    label: string;
+    /** Whether the array holds the value: a picked value of a union. */
+    selected: boolean;
+}
+/**
+ * The base of the playground controls of array inputs: a chip combobox. The items are chips, in
+ * one field with a text field after them. Enter adds the typed value, Backspace in the empty field
+ * removes the last chip, and the × of a chip removes it. A chip is dragged to another place, or
+ * moved with Alt+Left and Alt+Right while it is focused, and the arrow keys move between chips.
+ * While the reader types, a dropdown lists the matching suggestions; the arrow keys move its
+ * highlight, and Enter or a click picks a row. Escape closes it.
+ *
+ * Subclasses decide what an item is: typed text (`parseItem`) for the arrays of strings and
+ * numbers, which suggest the input's default items and the items removed while the control is
+ * shown, or the values of a union, which the dropdown lists (`NgDocTypeAliasListControlComponent`).
+ *
+ * The control never changes an array it received: every edit reports a new array of plain values,
+ * so the value can be compared with the default and sent to an isolated demo as it is. An
+ * `undefined` or `null` value has no items and shows as such; the first added item makes it an
+ * array, and removing the last item leaves an empty array. Reset returns to the input's default,
+ * which is how an optional input gets back to `undefined`.
+ */
+declare abstract class NgDocListControl<T extends NgDocListControlItem> extends DIControl<T[] | undefined> implements NgDocTypeControl<T[] | undefined> {
+    /** Default value of the input; Reset returns to it. */
+    readonly default: _angular_core.InputSignal<T[] | undefined>;
+    /**
+     * Whether typed text becomes an item (`parseItem`). Without it, the dropdown lists the values the
+     * items can have, and a value is in the array at most once.
+     */
+    protected abstract readonly freeText: boolean;
+    protected readonly texts: NgDocPlaygroundTexts;
+    /** The prefix of the IDs of the parts of the control. */
+    protected readonly id: string;
+    /** The items of the value; none when the value is not an array. */
+    protected readonly items: Signal<readonly T[]>;
+    /** The items as the chips show them: in the order of a drag in progress. */
+    protected readonly shownItems: Signal<readonly T[]>;
+    /**
+     * The text shown instead of the items when the value is not an array (`undefined` or `null`), or
+     * is an empty array (`[]`), so that the two can be told apart. These are code, not words.
+     */
+    protected readonly literal: Signal<string>;
+    /** Whether Reset is shown: the value differs from the default. */
+    protected readonly canReset: Signal<boolean>;
+    /** The text of the text field. */
+    protected readonly text: _angular_core.WritableSignal<string>;
+    /** Whether the reader asked for the dropdown, by typing, clicking or an arrow key. */
+    protected readonly expanded: _angular_core.WritableSignal<boolean>;
+    /** The position of the highlighted row of the dropdown, or `-1`. */
+    protected readonly highlighted: _angular_core.WritableSignal<number>;
+    /** The position of the item edited in place, or `null`. */
+    protected readonly editing: _angular_core.WritableSignal<number | null>;
+    /** The text of the field that edits an item in place. */
+    protected readonly editText: _angular_core.WritableSignal<string>;
+    /** The position of the chip in the tab order; the others are reached with the arrow keys. */
+    protected readonly tabStop: _angular_core.WritableSignal<number>;
+    /** The position of the chip being dragged, or `null`. */
+    protected readonly dragIndex: _angular_core.WritableSignal<number | null>;
+    /** What the live region announces: the new position of a moved item. */
+    protected readonly announcement: _angular_core.WritableSignal<string>;
+    /** The width of the dropdown: the width of the field. */
+    protected readonly panelWidth: _angular_core.WritableSignal<number>;
+    /** Whether the text field holds text that is not an item, such as a word in a `number[]`. */
+    protected readonly invalid: Signal<boolean>;
+    /** Whether the field that edits an item holds text that is not an item. */
+    protected readonly editInvalid: Signal<boolean>;
+    /**
+     * The rows of the dropdown: the values of `candidates()` whose text contains the typed text (the
+     * one equal to it first), and, when the typed text is an item that no row adds, a row that adds
+     * it, first.
+     */
+    protected readonly rows: Signal<Array<NgDocListControlRow<T>>>;
+    /**
+     * Whether the dropdown is open: the reader asked for it and it has rows, or, for a union, says
+     * that no value matches the typed text.
+     */
+    protected readonly panelOpen: Signal<boolean>;
+    /** The items removed while the control is shown, which the arrays of strings and numbers suggest. */
+    private readonly removed;
+    private readonly injector;
+    private readonly dropdown;
+    private readonly fieldBox;
+    /** The items in the order of a drag in progress, or `null`. */
+    private readonly dragOrder;
+    private drag;
+    /** The last array the control reported, which the form writes back. */
+    private reported;
+    protected constructor();
+    /**
+     * Reads typed text as an item.
+     * @param text - The text.
+     * @returns The item, or `undefined` when the text is not one.
+     */
+    protected abstract parseItem(text: string): T | undefined;
+    /**
+     * The values that the dropdown can list, before the typed text filters them: for an array of
+     * strings or numbers, the items of the default and the removed items that the array doesn't
+     * hold. Plain arrays may hold an item twice, so typed text that is an item is added again, but
+     * the suggestions never repeat an item.
+     */
+    protected candidates(): readonly T[];
+    /**
+     * The text of an item.
+     * @param item - The item.
+     */
+    protected labelOf(item: T): string;
+    /**
+     * The text of a chip: the item's text, or `""` for an empty string.
+     * @param item - The item.
+     */
+    protected chipText(item: T): string;
+    /**
+     * Reads the text field as the reader types.
+     * @param text - The text of the field.
+     */
+    protected type(text: string): void;
+    /**
+     * Handles the keys of the text field.
+     * @param event - The key event.
+     * @param field - The text field.
+     */
+    protected fieldKeydown(event: KeyboardEvent, field: HTMLInputElement): void;
+    /**
+     * Opens the dropdown when the reader clicks the field, and focuses the text field when the click
+     * is not on a chip or a button.
+     * @param event - The click.
+     * @param field - The text field.
+     */
+    protected fieldClick(event: MouseEvent, field: HTMLInputElement): void;
+    /**
+     * Picks a row of the dropdown: adds its value, or removes a picked value of a union.
+     * @param row - The row.
+     */
+    protected pick(row: NgDocListControlRow<T>): void;
+    /**
+     * Handles the keys of a focused chip.
+     * @param event - The key event.
+     * @param index - The position of the chip.
+     */
+    protected chipKeydown(event: KeyboardEvent, index: number): void;
+    /**
+     * Removes an item. The focus goes to the chip that takes its place, the previous chip, or the
+     * text field when the field had it, or no chip is left.
+     * @param index - The position of the item.
+     * @param focus - Whether the focus moves; a pick in the dropdown keeps it in the text field.
+     */
+    protected remove(index: number, focus?: boolean): void;
+    /**
+     * Edits an item in place: its chip becomes a text field.
+     * @param index - The position of the item.
+     */
+    protected startEdit(index: number): void;
+    /**
+     * Handles the keys of the field that edits an item: Enter keeps the text, Escape the item.
+     * @param event - The key event.
+     */
+    protected editKeydown(event: KeyboardEvent): void;
+    /** Ends an edit when its field loses the focus: with the text when it is an item. */
+    protected editBlur(): void;
+    /**
+     * Starts to follow a pointer that went down on a chip.
+     * @param event - The pointer event.
+     * @param index - The position of the chip.
+     */
+    protected chipPointerDown(event: PointerEvent, index: number): void;
+    /**
+     * Drags the chip once the pointer has moved far enough, and moves it in front of or behind the
+     * chip under the pointer once the pointer passes that chip's middle.
+     * @param event - The pointer event.
+     */
+    protected chipPointerMove(event: PointerEvent): void;
+    /**
+     * Drops a dragged chip: the items take the order of the drag.
+     * @param event - The pointer event.
+     */
+    protected chipPointerUp(event: PointerEvent): void;
+    /** Stops following the pointer; a drag in progress leaves the items as they were. */
+    protected cancelDrag(): void;
+    /**
+     * Closes the dropdown and marks the control as touched when the focus leaves the control.
+     * @param event - The focus event.
+     */
+    protected leave(event: FocusEvent): void;
+    /** Sets the value back to the default of the input. */
+    protected reset(): void;
+    /**
+     * The ID of a row of the dropdown, which the text field names as its active descendant.
+     * @param index - The position of the row.
+     */
+    protected rowId(index: number): string;
+    /**
+     * Adds an item at the end.
+     * @param value - The item.
+     */
+    private add;
+    /** Adds the highlighted row, or the typed text when it is an item. */
+    private enter;
+    /**
+     * Moves the highlight of the dropdown, and opens it.
+     * @param step - `1` for the next row, `-1` for the previous one.
+     */
+    private moveHighlight;
+    /**
+     * Moves an item one place, with the focus.
+     * @param index - The position of the item.
+     * @param offset - `-1` toward the start, `1` toward the end.
+     */
+    private move;
+    /**
+     * Sets the edited item from the text of its field.
+     * @returns Whether the text is an item.
+     */
+    private commitEdit;
+    /**
+     * The position a dragged chip moves to: the position of the chip under the pointer, once the
+     * pointer has passed its middle in the direction of the move.
+     * @param event - The pointer event.
+     * @param from - The position of the dragged chip.
+     */
+    private dropTarget;
+    /**
+     * Reports a new value.
+     * @param value - The value.
+     */
+    private report;
+    /**
+     * Announces the new position of a moved item.
+     * @param order - The items after the move.
+     * @param index - The new position of the item.
+     */
+    private announceMove;
+    /**
+     * Focuses a chip once the chips have rendered: they are tracked by position, so the focused
+     * element may show another item, or be gone.
+     * @param index - The position of the chip.
+     */
+    private focusChip;
+    /** Focuses the text field once the chips have rendered. */
+    private focusField;
+    private fieldElement;
+    private isFocused;
+    /** Whether the chips flow from right to left, which turns the arrow keys round. */
+    private isRtl;
+    private host;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocListControl<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgDocListControl<any>, never, never, { "default": { "alias": "default"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * The playground control of `string[]` inputs: a chip combobox (`NgDocListControl`). Typed text is
+ * an item as it is, and a double click, Enter or F2 edits a chip in place.
+ */
+declare class NgDocStringListControlComponent extends NgDocListControl<string> {
+    protected readonly freeText = true;
+    constructor();
+    protected parseItem(text: string): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocStringListControlComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocStringListControlComponent, "ng-doc-string-list-control", never, {}, {}, never, never, true, never>;
+}
+/**
+ * The playground control of `number[]` inputs: a chip combobox (`NgDocListControl`) whose items are
+ * numbers. Text that is not a number marks the field as invalid and adds nothing; a chip edited to
+ * such text keeps its number.
+ */
+declare class NgDocNumberListControlComponent extends NgDocListControl<number> {
+    protected readonly freeText = true;
+    constructor();
+    protected parseItem(text: string): number | undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocNumberListControlComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocNumberListControlComponent, "ng-doc-number-list-control", never, {}, {}, never, never, true, never>;
+}
+/**
+ * The playground control of arrays of a union of literals, such as `NgDocSize[]` or
+ * `('a' | 'b')[]`: a chip combobox (`NgDocListControl`) whose dropdown lists every value of the
+ * union, with the same texts as the control of the union (`NgDocTypeAliasControlComponent`).
+ * Picking a value adds it, and picking a value that the array holds, which is marked, removes it.
+ * The typed text filters the values; it is never an item itself.
+ */
+declare class NgDocTypeAliasListControlComponent extends NgDocListControl<NgDocListControlItem> {
+    /**
+     * The values of the items: the members of the union as written in code, plain values when
+     * `isManual` is set, or the names and values of enum members.
+     */
+    readonly options: _angular_core.InputSignal<(string | NgDocPlaygroundOption)[] | undefined>;
+    /** Whether `options` are values the user listed in the playground config. */
+    readonly isManual: _angular_core.InputSignal<boolean | undefined>;
+    protected readonly freeText = false;
+    /** The values of the union that an item can be; `undefined`, `null` and repeats are left out. */
+    protected readonly values: Signal<NgDocResolvedPlaygroundOption[]>;
+    constructor();
+    protected candidates(): readonly NgDocListControlItem[];
+    protected labelOf(item: NgDocListControlItem): string;
+    protected parseItem(): undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocTypeAliasListControlComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocTypeAliasListControlComponent, "ng-doc-type-alias-list-control", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "isManual": { "alias": "isManual"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgDocListControl, NgDocNumberListControlComponent, NgDocStringListControlComponent, NgDocTypeAliasListControlComponent };

package/types/ng-doc-app-type-controls-type-alias-control.d.ts

@@ -1,20 +1,43 @@
 import * as _angular_core from '@angular/core';
-import { NgDocTypeControl } from '@ng-doc/app/interfaces';
+import { Signal } from '@angular/core';
+import { NgDocResolvedPlaygroundOption } from '@ng-doc/app/helpers';
+import { NgDocTypeControl, NgDocPlaygroundTexts } from '@ng-doc/app/interfaces';
+import { NgDocPlaygroundOption } from '@ng-doc/core/interfaces';
 import { DIControl } from 'di-controls';
 
 /**
- * The playground control of union type aliases: a select that shows the value and whether it is
- * the default. The inspector shows the value type under the input's name.
+ * The playground control of union type aliases and enums: a select that shows the value (or the
+ * name of an enum member) and whether it is the default. The inspector shows the value type under
+ * the input's name.
  */
 declare class NgDocTypeAliasControlComponent<T> extends DIControl<T> implements NgDocTypeControl<T> {
+    protected readonly texts: NgDocPlaygroundTexts;
     /** Default value of the input; clearing the selection returns to it. */
     readonly default: _angular_core.InputSignal<T | undefined>;
-    /** Values the input accepts: literal source text, or plain values when `isManual` is set. */
-    readonly options: _angular_core.InputSignal<string[] | undefined>;
+    /**
+     * Values the input accepts: literal source text, plain values when `isManual` is set, or the
+     * names and values of enum members.
+     */
+    readonly options: _angular_core.InputSignal<(string | NgDocPlaygroundOption)[] | undefined>;
     /** Whether `options` are values the user listed in the playground config. */
     readonly isManual: _angular_core.InputSignal<boolean | undefined>;
+    /**
+     * The options of the select. `undefined` and `null` get no option: clearing the selection
+     * returns to the default value instead.
+     */
+    protected readonly items: Signal<NgDocResolvedPlaygroundOption[]>;
     constructor();
     typeOf(value: unknown): string;
+    /**
+     * The text of a value: the name of its option, such as the name of an enum member.
+     * @param value - A value of the input.
+     */
+    labelOf(value: unknown): string;
+    /**
+     * Whether the reset button is shown: a value other than the default is selected.
+     * @param value - The selected value.
+     */
+    protected canReset(value: T | null): boolean;
     changeModel(value: T | null): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocTypeAliasControlComponent<any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocTypeAliasControlComponent<any>, "ng-doc-type-alias-control", never, { "default": { "alias": "default"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "isManual": { "alias": "isManual"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;

package/types/ng-doc-app-type-controls.d.ts

@@ -1,4 +1,6 @@
 export * from '@ng-doc/app/type-controls/boolean-control';
+export * from '@ng-doc/app/type-controls/json-control';
+export * from '@ng-doc/app/type-controls/list-control';
 export * from '@ng-doc/app/type-controls/number-control';
 export * from '@ng-doc/app/type-controls/string-control';
 export * from '@ng-doc/app/type-controls/type-alias-control';