@ni/nimble-components 24.0.0 → 24.1.0

package/dist/esm/src/rich-text/base/index.d.ts

@@ -0,0 +1,49 @@
+import { type Notifier } from '@microsoft/fast-element';
+import { FoundationElement } from '@microsoft/fast-foundation';
+import { RichTextMention } from '../../rich-text-mention/base';
+import { Configuration } from '../models/configuration';
+import { RichTextUpdateTracker } from '../models/rich-text-tracker';
+import { RichTextValidator } from '../models/rich-text-validator';
+import type { RichTextValidity } from './types';
+/**
+ * Base class for rich text components
+ */
+export declare abstract class RichText extends FoundationElement {
+    /**
+     * @internal
+     */
+    mentionInternalsNotifiers: Notifier[];
+    /**
+     * @internal
+     */
+    readonly childItems: Element[];
+    protected configuration?: Configuration;
+    protected mentionElements: RichTextMention[];
+    protected readonly richTextUpdateTracker: RichTextUpdateTracker;
+    protected readonly richTextValidator: RichTextValidator;
+    /**
+     * @public
+     */
+    get validity(): RichTextValidity;
+    /**
+     * @public
+     */
+    checkValidity(): boolean;
+    /**
+     * @internal
+     */
+    abstract getMentionedHrefs(): string[];
+    /**
+     * @internal
+     */
+    handleChange(source: unknown, args: unknown): void;
+    /**
+     * @internal
+     */
+    createConfig(): void;
+    protected validate(): void;
+    private childItemsChanged;
+    private updateMentionElementsFromChildItems;
+    private observeMentionInternals;
+    private removeMentionInternalsObservers;
+}

package/dist/esm/src/rich-text/base/types.d.ts

@@ -0,0 +1,5 @@
+import type { ValidityObject } from '../../utilities/models/validator';
+export interface RichTextValidity extends ValidityObject {
+    readonly invalidMentionConfiguration: boolean;
+    readonly duplicateMentionConfiguration: boolean;
+}

package/dist/esm/src/rich-text/editor/index.d.ts

@@ -0,0 +1,270 @@
+import { ARIAGlobalStatesAndProperties } from '@microsoft/fast-foundation';
+import { Editor } from '@tiptap/core';
+import type { SuggestionProps } from '@tiptap/suggestion';
+import type { ToggleButton } from '../../toggle-button';
+import { MentionDetail } from './types';
+import type { ErrorPattern } from '../../patterns/error/types';
+import { RichTextMarkdownSerializer } from '../models/markdown-serializer';
+import { RichText } from '../base';
+import type { RichTextMentionListbox } from '../mention-listbox';
+import type { MappingConfigs } from '../../rich-text-mention/base/types';
+import type { MentionExtensionConfiguration } from '../models/mention-extension-configuration';
+import { EditorConfiguration } from '../models/editor-configuration';
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-rich-text-editor': RichTextEditor;
+    }
+}
+/**
+ * A nimble styled rich text editor
+ */
+export declare class RichTextEditor extends RichText implements ErrorPattern {
+    /**
+     * @internal
+     */
+    editor: HTMLDivElement;
+    /**
+     * @internal
+     */
+    tiptapEditor: Editor;
+    /**
+     * @internal
+     */
+    readonly xmlSerializer: XMLSerializer;
+    /**
+     * @internal
+     */
+    richTextMarkdownSerializer: RichTextMarkdownSerializer;
+    /**
+     * Whether to disable user from editing and interacting with toolbar buttons
+     *
+     * @public
+     * HTML Attribute: disabled
+     */
+    disabled: boolean;
+    /**
+     * Whether to hide the footer of the rich text editor
+     *
+     * @public
+     * HTML Attribute: footer-hidden
+     */
+    footerHidden: boolean;
+    /**
+     * Whether to display the error state.
+     *
+     * @public
+     * HTML Attribute: error-visible
+     */
+    errorVisible: boolean;
+    /**
+     * A message explaining why the value is invalid.
+     *
+     * @public
+     * HTML Attribute: error-text
+     */
+    errorText?: string;
+    /**
+     * @public
+     * HTML Attribute: placeholder
+     */
+    placeholder?: string;
+    /**
+     * True if the editor is empty or contains only whitespace, false otherwise.
+     *
+     * @public
+     */
+    get empty(): boolean;
+    /**
+     * @internal
+     */
+    mentionListbox?: RichTextMentionListbox;
+    /**
+     * @internal
+     */
+    boldButton: ToggleButton;
+    /**
+     * @internal
+     */
+    italicsButton: ToggleButton;
+    /**
+     * @internal
+     */
+    bulletListButton: ToggleButton;
+    /**
+     * @internal
+     */
+    numberedListButton: ToggleButton;
+    /**
+     * The width of the vertical scrollbar, if displayed.
+     * @internal
+     */
+    scrollbarWidth: number;
+    /**
+     * @internal
+     */
+    activeMentionCharacter: string;
+    /**
+     * @internal
+     */
+    activeMappingConfigs?: MappingConfigs;
+    /**
+     * @internal
+     */
+    activeMentionCommand?: SuggestionProps['command'];
+    /**
+     * @internal
+     */
+    editorContainer: HTMLDivElement;
+    private resizeObserver?;
+    private updateScrollbarWidthQueued;
+    /**
+     * @internal
+     */
+    connectedCallback(): void;
+    /**
+     * @internal
+     */
+    disconnectedCallback(): void;
+    /**
+     * @internal
+     */
+    disabledChanged(): void;
+    /**
+     * Update the placeholder text and view of the editor.
+     * @internal
+     */
+    placeholderChanged(_prev: unknown, _next: unknown): void;
+    /**
+     * @internal
+     */
+    ariaLabelChanged(_prev: unknown, _next: unknown): void;
+    /**
+     * @internal
+     */
+    configurationChanged(prev: EditorConfiguration | undefined, next: EditorConfiguration): void;
+    /**
+     * @internal
+     */
+    activeMentionCharacterChanged(): void;
+    /**
+     * Toggle the bold mark and focus back to the editor
+     * @internal
+     */
+    boldButtonClick(): void;
+    /**
+     * Toggle the bold mark and focus back to the editor
+     * @internal
+     */
+    boldButtonKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Toggle the italics mark and focus back to the editor
+     * @internal
+     */
+    italicsButtonClick(): void;
+    /**
+     * Toggle the italics mark and focus back to the editor
+     * @internal
+     */
+    italicsButtonKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Toggle the unordered list node and focus back to the editor
+     * @internal
+     */
+    bulletListButtonClick(): void;
+    /**
+     * Toggle the unordered list node and focus back to the editor
+     * @internal
+     */
+    bulletListButtonKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Toggle the ordered list node and focus back to the editor
+     * @internal
+     */
+    numberedListButtonClick(): void;
+    /**
+     * Toggle the ordered list node and focus back to the editor
+     * @internal
+     */
+    numberedListButtonKeyDown(event: KeyboardEvent): boolean;
+    /**
+     * Inserts the mention character into the editor and focus back to the editor
+     * @internal
+     */
+    mentionButtonClick(character: string): void;
+    /**
+     * This function load tip tap editor with provided markdown content by parsing into html
+     * @public
+     */
+    setMarkdown(markdown: string): void;
+    /**
+     * This function returns markdown string by serializing tiptap editor document using prosemirror MarkdownSerializer
+     * @public
+     */
+    getMarkdown(): string;
+    /**
+     * @internal
+     */
+    stopEventPropagation(event: Event): boolean;
+    getMentionedHrefs(): string[];
+    /**
+     * @internal
+     */
+    getMentionExtensionConfig(): MentionExtensionConfiguration[];
+    /**
+     * @internal
+     */
+    onMentionSelect(event: CustomEvent<MentionDetail>): void;
+    /**
+     * @internal
+     */
+    focusoutHandler(): void;
+    createConfig(): void;
+    private isMentionExtensionConfigUnchanged;
+    private createEditor;
+    private initializeEditor;
+    /**
+     * This function takes the Fragment from parseMarkdownToDOM function and return the serialized string using XMLSerializer
+     */
+    private getHtmlContent;
+    /**
+     * Binding the "transaction" event to the editor allows continuous monitoring the events and updating the button state in response to
+     * various actions such as mouse events, keyboard events, changes in the editor content etc,.
+     * https://tiptap.dev/api/events#transaction
+     */
+    private bindEditorTransactionEvent;
+    private unbindEditorTransactionEvent;
+    private updateEditorButtonsState;
+    private keyActivatesButton;
+    private unbindEditorUpdateEvent;
+    /**
+     * input event is fired when there is a change in the content of the editor.
+     *
+     * https://tiptap.dev/api/events#update
+     */
+    private bindEditorUpdateEvent;
+    private disableEditor;
+    private disableMentionViewElement;
+    /**
+     * Stopping the native input event propagation emitted by the contenteditable element in the Tiptap
+     * since there is an issue (linked below) in ProseMirror where selecting the text and removing it
+     * does not trigger the native HTMLElement input event. So using the "update" event emitted by the
+     * Tiptap to capture it as an "input" customEvent in the rich text editor.
+     *
+     * Prose Mirror issue: https://discuss.prosemirror.net/t/how-to-handle-select-backspace-delete-cut-type-kind-of-events-handletextinput-or-handledomevents-input-doesnt-help/4844
+     */
+    private stopNativeInputEventPropagation;
+    private unbindNativeInputEvent;
+    private queueUpdateScrollbarWidth;
+    private updateScrollbarWidth;
+    private onResize;
+    private getTipTapExtension;
+    private setEditorTabIndex;
+    private setActiveMappingConfigs;
+    private shouldInsertSpace;
+    private getMentionExtensionConfigFromCharacter;
+    private resetEditorButtonsState;
+    private getButtonsState;
+}
+export interface RichTextEditor extends ARIAGlobalStatesAndProperties {
+}
+export declare const richTextEditorTag = "nimble-rich-text-editor";

package/dist/esm/src/rich-text/editor/models/create-tiptap-editor.d.ts

@@ -0,0 +1,5 @@
+import { Editor } from '@tiptap/core';
+import { ActiveMentionCommandEmitter, ActiveMentionCharacterEmitter } from '../types';
+import type { MentionExtensionConfiguration } from '../../models/mention-extension-configuration';
+import type { RichTextMentionListbox } from '../../mention-listbox';
+export declare function createTiptapEditor(activeMentionCharacterEmitter: ActiveMentionCharacterEmitter, activeMentionCommandEmitter: ActiveMentionCommandEmitter, editor: HTMLDivElement, mentionExtensionConfig: MentionExtensionConfiguration[], mentionListbox?: RichTextMentionListbox, placeholder?: string): Editor;

package/dist/esm/src/rich-text/editor/styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("@microsoft/fast-element").ElementStyles;

package/dist/esm/src/rich-text/editor/template.d.ts

@@ -0,0 +1,2 @@
+import type { RichTextEditor } from '.';
+export declare const template: import("@microsoft/fast-element").ViewTemplate<RichTextEditor, any>;

package/dist/esm/src/rich-text/editor/testing/rich-text-editor-utils.d.ts

@@ -0,0 +1,6 @@
+import type { RichTextEditor } from '..';
+import { type RichTextMentionUsers } from '../../../rich-text-mention/users';
+import type { MappingConfiguration, UserMentionElements, TestMentionElements } from './types';
+export declare function appendUserMentionConfiguration(element: RichTextEditor, mappings?: MappingConfiguration[]): Promise<UserMentionElements>;
+export declare function appendTestMentionConfiguration(element: RichTextEditor, mappings?: MappingConfiguration[]): Promise<TestMentionElements>;
+export declare function replaceUserMappingElements(element: RichTextMentionUsers, mappings: MappingConfiguration[]): Promise<void>;

package/dist/esm/src/rich-text/editor/testing/rich-text-editor.pageobject.d.ts

@@ -0,0 +1,75 @@
+import type { RichTextEditor } from '..';
+import { ArrowKeyButton, MappingConfiguration, ToolbarButton } from './types';
+/**
+ * Page object for the `nimble-rich-text-editor` component.
+ */
+export declare class RichTextEditorPageObject {
+    private readonly richTextEditorElement;
+    constructor(richTextEditorElement: RichTextEditor);
+    editorSectionHasChildNodes(): boolean;
+    getEditorSectionFirstElementChildClassName(): string;
+    clickEditorShortcutKeys(shortcutKey: string, isShiftKey: boolean): Promise<void>;
+    pressEnterKeyInEditor(): Promise<void>;
+    pressEscapeKeyInEditor(): Promise<void>;
+    pressArrowKeyInEditor(arrowButton: ArrowKeyButton): Promise<void>;
+    pressShiftEnterKeysInEditor(): Promise<void>;
+    pressTabKeyInEditor(): Promise<void>;
+    pressShiftTabKeysInEditor(): Promise<void>;
+    /**
+     * In testing environment, when clicking on the footer button, it may not persist in the same state if any editor transaction occurs in between.
+     * This behavior is likely due to dynamic modifications of formatting button states based on cursor positions during editor transactions.
+     * Setting the "force" parameter to true activates the formatting button state; when set to false, it deactivates the state.
+     * If unset, the state toggles by interacting with it once.
+     */
+    toggleFooterButton(button: ToolbarButton, force?: boolean): Promise<void>;
+    clickUserMentionButton(): Promise<void>;
+    getMentionButtonIcon(buttonIndex: number): string | undefined;
+    getMentionButtonTitle(buttonIndex: number): string;
+    getMentionButtonLabel(buttonIndex: number): string;
+    getButtonCheckedState(button: ToolbarButton): boolean;
+    getButtonTabIndex(button: ToolbarButton): number;
+    spaceKeyActivatesButton(button: ToolbarButton): void;
+    enterKeyActivatesButton(button: ToolbarButton): void;
+    pasteToEditor(text: string): void;
+    pasteHTMLToEditor(htmlString: string): void;
+    setEditorTextContent(value: string): Promise<void>;
+    setCursorPosition(position: number): Promise<void>;
+    replaceEditorContent(value: string): Promise<void>;
+    sliceEditorContent(from: number, to: number): Promise<void>;
+    getEditorLastChildAttribute(attribute: string): string;
+    isMentionListboxOpened(): boolean;
+    getEditorMentionViewAttributeValues(attribute: string): string[];
+    getEditorFirstChildTagName(): string;
+    getEditorFirstChildTextContent(): string;
+    getEditorTextContents(): string[];
+    getEditorTagNames(): string[];
+    getMarkdownRenderedTagNames(): string[];
+    getEditorLeafContents(): string[];
+    getEditorTagNamesWithClosingTags(): string[];
+    getFormattingButtonTextContent(toolbarButton: ToolbarButton): string;
+    getFormattingButtonTitle(toolbarButton: ToolbarButton): string;
+    isRichTextEditorActiveElement(): boolean;
+    getEditorTabIndex(): string;
+    setFooterHidden(footerHidden: boolean): Promise<void>;
+    isFooterHidden(): boolean;
+    setDisabled(disabled: boolean): Promise<void>;
+    isButtonDisabled(button: ToolbarButton): boolean;
+    getPlaceholderValue(): string;
+    getParsedHtmlFromMarkdown(markdown: string, mappings?: MappingConfiguration[]): string;
+    focusOutEditor(): Promise<void>;
+    getMentionListboxItemsName(): string[];
+    getSelectedOption(): string;
+    clickMentionListboxOption(index: number): Promise<void>;
+    moveCursorToStart(): void;
+    getCursorPosition(): number;
+    private getEditorSection;
+    private getFooter;
+    private getTiptapEditor;
+    private getFormattingButton;
+    private getUserMentionButton;
+    private getMentionButtons;
+    private getMentionListbox;
+    private getAllListItemsInMentionBox;
+    private getEditorLastChildElement;
+    private getParserMentionConfigForUser;
+}

package/dist/esm/src/rich-text/editor/testing/types.d.ts

@@ -0,0 +1,31 @@
+import type { MappingUser } from '../../../mapping/user';
+import type { RichTextMentionTest } from '../../../rich-text-mention/base/tests/rich-text-mention.fixtures';
+import type { RichTextMentionUsers } from '../../../rich-text-mention/users';
+export declare const ToolbarButton: {
+    readonly bold: 0;
+    readonly italics: 1;
+    readonly bulletList: 2;
+    readonly numberedList: 3;
+};
+export type ToolbarButton = (typeof ToolbarButton)[keyof typeof ToolbarButton];
+export declare const ArrowKeyButton: {
+    readonly up: "ArrowUp";
+    readonly down: "ArrowDown";
+    readonly left: "ArrowLeft";
+    readonly right: "ArrowRight";
+};
+export type ArrowKeyButton = (typeof ArrowKeyButton)[keyof typeof ArrowKeyButton];
+export type LabelProvider = 'toggleBold' | 'toggleItalics' | 'toggleBulletedList' | 'toggleNumberedList';
+export type ToolbarButtonKey = keyof typeof ToolbarButton;
+export interface UserMentionElements {
+    userMentionElement: RichTextMentionUsers;
+    mappingElements: MappingUser[];
+}
+export interface TestMentionElements {
+    testMentionElement: RichTextMentionTest;
+    mappingElements: MappingUser[];
+}
+export interface MappingConfiguration {
+    key?: string;
+    displayName?: string;
+}

package/dist/esm/src/rich-text/editor/types.d.ts

@@ -0,0 +1,27 @@
+import type { SuggestionProps } from '@tiptap/suggestion';
+/**
+ * TipTap node types.
+ * @public
+ */
+export declare const TipTapNodeName: {
+    readonly bulletList: "bulletList";
+    readonly numberedList: "orderedList";
+};
+export type TipTapNodeName = (typeof TipTapNodeName)[keyof typeof TipTapNodeName];
+export interface MentionExtensionConfig {
+    name: string;
+    key: string;
+    character: string;
+    viewElement: string;
+}
+export interface FormatButtonsState {
+    bold: boolean;
+    italics: boolean;
+}
+export interface MentionDetail {
+    href: string;
+    displayName: string;
+}
+export declare const mentionPluginPrefix = "mention-plugin-";
+export type ActiveMentionCommandEmitter = (command?: SuggestionProps['command']) => void;
+export type ActiveMentionCharacterEmitter = (character: string) => void;

package/dist/esm/src/rich-text/mention-listbox/index.d.ts

@@ -0,0 +1,116 @@
+import { ListboxElement as FoundationListbox, ListboxOption } from '@microsoft/fast-foundation';
+import type { AnchoredRegion } from '../../anchored-region';
+import type { MentionListboxShowOptions } from './types';
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-rich-text-mention-listbox': RichTextMentionListbox;
+    }
+}
+/**
+ * A rich text mention listbox which acts as a popup for "@mention" support in editor
+ */
+export declare class RichTextMentionListbox extends FoundationListbox {
+    /**
+     * @internal
+     */
+    open?: boolean;
+    /**
+     * @internal
+     */
+    region?: AnchoredRegion;
+    /**
+     * @internal
+     */
+    filter: string;
+    /**
+     * The collection of currently filtered options.
+     * The approach is defined based on the `Combobox.filteredOptions` implementation.
+     *
+     * @internal
+     */
+    filteredOptions: ListboxOption[];
+    private anchorElement?;
+    private regionNotifier?;
+    private readonly anchorElementIntersectionObserver;
+    /**
+     * @public
+     */
+    close(): void;
+    /**
+     * The list of options.
+     *
+     * @public
+     * @remarks
+     * Overrides `Listbox.options`.
+     */
+    get options(): ListboxOption[];
+    set options(value: ListboxOption[]);
+    /**
+     * Triggers when the mention plugin is activated upon pressing the `key`
+     *
+     * @public
+     */
+    show(options: MentionListboxShowOptions): void;
+    /**
+     * Handle keydown actions for listbox navigation and selection.
+     *
+     * @param e - the keyboard event
+     * @public
+     */
+    keydownHandler(event: KeyboardEvent): boolean;
+    /**
+     * Filter available options by filter value.
+     * The method is defined based on the `Combobox.filterOptions` and `Combobox.inputHandler` implementation.
+     *
+     * @internal
+     */
+    filterOptions(): void;
+    /**
+     * Synchronize the form-associated proxy and update the value property of the element.
+     *
+     * @param prev - the previous collection of slotted option elements
+     * @param next - the next collection of slotted option elements
+     *
+     * @internal
+     */
+    slottedOptionsChanged(prev: Element[] | undefined, next: Element[]): void;
+    /**
+     * Triggers the `suggestionProps` command to notify the tiptap editor to select the option.
+     * The method is defined based on the `Listbox.clickHandler` implementation.
+     *
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean;
+    /**
+     * Observes the anchor element using intersection observer.
+     * Once the anchor element intersects, the anchor region will be closed.
+     *
+     * @internal
+     */
+    anchorElementChanged(prev: HTMLElement, next: HTMLElement): void;
+    /**
+     * Observes the anchor region.
+     *
+     * @internal
+     */
+    regionChanged(): void;
+    /**
+     * Handles the events of the anchored region.
+     * Repositions the listbox scroll bar when the `initialLayoutComplete` event is triggered.
+     * Other events will be passed to the base class.
+     *
+     * @internal
+     */
+    handleChange(source: unknown, args: string): void;
+    /**
+     * Focus the control and scroll the first selected option into view.
+     *
+     * @internal
+     * @remarks
+     * Overrides: `Listbox.focusAndScrollOptionIntoView`
+     */
+    protected focusAndScrollOptionIntoView(): void;
+    private emitMentionSelected;
+    private setOpen;
+}
+export declare const richTextMentionListboxTag = "nimble-rich-text-mention-listbox";

package/dist/esm/src/rich-text/mention-listbox/styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("@microsoft/fast-element").ElementStyles;

package/dist/esm/src/rich-text/mention-listbox/template.d.ts

@@ -0,0 +1,2 @@
+import type { RichTextMentionListbox } from '.';
+export declare const template: import("@microsoft/fast-element").ViewTemplate<RichTextMentionListbox, any>;

package/dist/esm/src/rich-text/mention-listbox/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Options passed to the `show()` method of the mention listbox
+ */
+export interface MentionListboxShowOptions {
+    anchorNode: HTMLElement;
+    filter: string;
+}

package/dist/esm/src/rich-text/models/configuration.d.ts

@@ -0,0 +1,10 @@
+import type { RichTextMention } from '../../rich-text-mention/base';
+import { MarkdownParserMentionConfiguration } from './markdown-parser-mention-configuration';
+/**
+ * Base class for Configuration, contains mention configuration required for RichTextMarkdownParser
+ */
+export declare class Configuration {
+    parserMentionConfig: MarkdownParserMentionConfiguration[];
+    protected isValid: boolean;
+    constructor(mentionElements: RichTextMention[]);
+}

package/dist/esm/src/rich-text/models/editor-configuration.d.ts

@@ -0,0 +1,10 @@
+import type { RichTextMention } from '../../rich-text-mention/base';
+import { Configuration } from './configuration';
+import { MentionExtensionConfiguration } from './mention-extension-configuration';
+/**
+ * EditorConfiguration which will hold mentionExtensionConfig for configuring editor's mention extension and RichTextMarkdownSerializer
+ */
+export declare class EditorConfiguration extends Configuration {
+    mentionExtensionConfig: MentionExtensionConfiguration[];
+    constructor(mentionElements: RichTextMention[]);
+}

package/dist/esm/src/rich-text/models/markdown-parser-mention-configuration.d.ts

@@ -0,0 +1,14 @@
+import type { MentionInternals } from '../../rich-text-mention/base/models/mention-internals';
+/**
+ * A configuration object for a Markdown parser, to be used by the viewer and editor components.
+ * This object maintains the necessary internal values for handling mentions within the Markdown parser.
+ */
+export declare class MarkdownParserMentionConfiguration {
+    readonly viewElement: string;
+    private readonly regexPattern;
+    private readonly mappingConfigs?;
+    constructor(mentionInternals: MentionInternals);
+    isValidMentionHref(mentionHref: string): boolean;
+    getDisplayName(mentionHref: string): string | undefined;
+    private extractMentionId;
+}