@ni/nimble-components 24.0.1 → 24.1.0

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

@@ -0,0 +1,30 @@
+import type { MarkdownParserMentionConfiguration } from './markdown-parser-mention-configuration';
+export interface ParseResult {
+    fragment: HTMLElement | DocumentFragment;
+    mentionedHrefs: string[];
+}
+/**
+ * Provides markdown parser for rich text components
+ */
+export declare class RichTextMarkdownParser {
+    private static readonly mentionedHrefs;
+    private static readonly updatedSchema;
+    private static readonly markdownParser;
+    private static readonly domSerializer;
+    /**
+     * The markdown parser is static (shared across all rich text components) because it is expensive to create.
+     * To configure parse calls with the mention configurations which can be unique per component instance
+     * we store static configuration in this member and access it from Prosemirror callbacks.
+     */
+    private static mentionConfigs?;
+    /**
+     * This function takes a markdown string, parses it using the ProseMirror MarkdownParser, serializes the parsed content into a
+     * DOM structure using a DOMSerializer, and returns the serialized result.
+     * If the markdown parser returns null, it will clear the viewer component by creating an empty document fragment.
+     */
+    static parseMarkdownToDOM(value: string, markdownParserMentionConfig?: MarkdownParserMentionConfiguration[]): ParseResult;
+    private static initializeMarkdownParser;
+    private static getCustomSchemaConfiguration;
+    private static setup;
+    private static cleanup;
+}

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

@@ -0,0 +1,10 @@
+import type { Node } from 'prosemirror-model';
+/**
+ * Provides markdown serializer for rich text components
+ */
+export declare class RichTextMarkdownSerializer {
+    private readonly markdownSerializer;
+    constructor(mentionList: string[]);
+    serializeDOMToMarkdown(doc: Node): string;
+    private initializeMarkdownSerializerForTipTap;
+}

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

@@ -0,0 +1,19 @@
+import type { ViewTemplate } from '@microsoft/fast-element';
+import type { MentionInternals } from '../../rich-text-mention/base/models/mention-internals';
+import type { MappingConfigs, MentionUpdateEmitter } from '../../rich-text-mention/base/types';
+/**
+ * A configuration object for a Mention extension, to be used by the editor for loading mention plugins in tiptap.
+ * This object maintains the necessary internal values for loading mention extension.
+ */
+export declare class MentionExtensionConfiguration {
+    private static instance;
+    readonly iconTemplate: ViewTemplate;
+    readonly viewElement: string;
+    readonly character: string;
+    readonly name: string;
+    readonly key: string;
+    readonly mappingConfigs?: MappingConfigs;
+    readonly buttonLabel: string;
+    readonly mentionUpdateEmitter: MentionUpdateEmitter;
+    constructor(mentionInternals: MentionInternals);
+}

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

@@ -0,0 +1,19 @@
+import { UpdateTracker } from '../../utilities/models/update-tracker';
+import type { RichText } from '../base';
+declare const trackedItems: readonly ["pattern", "mappingConfigs", "buttonLabel"];
+/**
+ * Helper class to track what updates are needed to the rich text components based on configuration
+ * changes.
+ */
+export declare class RichTextUpdateTracker extends UpdateTracker<typeof trackedItems> {
+    private readonly richText;
+    private updateQueued;
+    constructor(richText: RichText);
+    get updatePattern(): boolean;
+    get updateMappingConfigs(): boolean;
+    get updateButtonLabel(): boolean;
+    trackMentionInternalsPropertyChanged(changedMentionInternalsProperty: string): void;
+    trackMentionElementsInstancesChanged(): void;
+    protected queueUpdate(): void;
+}
+export {};

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

@@ -0,0 +1,15 @@
+import type { RichTextMention } from '../../rich-text-mention/base';
+import type { RichTextValidity } from '../base/types';
+/**
+ * Helper class for the nimble rich text components to validate that the configuration
+ * is valid and report which aspects of the configuration are valid or invalid.
+ */
+export declare class RichTextValidator {
+    private invalidMentionConfiguration;
+    private duplicateMentionConfiguration;
+    getValidity(): RichTextValidity;
+    isValid(): boolean;
+    validate(mentions: RichTextMention[]): void;
+    private validateMentionConfigurations;
+    private validateDuplicateMentionConfigurations;
+}

package/dist/esm/src/rich-text/models/testing/markdown-parser-utils.d.ts

@@ -0,0 +1,5 @@
+export declare const getTagsFromElement: (doc: DocumentFragment | HTMLElement) => string[];
+export declare const getLeafContentsFromElement: (doc: DocumentFragment | HTMLElement) => string[];
+export declare const getLastChildElementAttribute: (attribute: string, doc: DocumentFragment | HTMLElement) => string;
+export declare const lastChildElementHasAttribute: (attribute: string, doc: DocumentFragment | HTMLElement) => boolean;
+export declare function getLastChildElement(doc: DocumentFragment | HTMLElement): Element | null | undefined;

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

@@ -0,0 +1,37 @@
+import { RichText } from '../base';
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-rich-text-viewer': RichTextViewer;
+    }
+}
+/**
+ * A nimble styled rich text viewer
+ */
+export declare class RichTextViewer extends RichText {
+    /**
+     *
+     * @public
+     * Markdown string to render its corresponding rich text content in the component.
+     */
+    markdown: string;
+    /**
+     * @internal
+     */
+    viewer: HTMLDivElement;
+    private mentionedHrefs;
+    /**
+     * @internal
+     */
+    connectedCallback(): void;
+    /**
+     * @internal
+     */
+    markdownChanged(): void;
+    /**
+     * @internal
+     */
+    configurationChanged(): void;
+    getMentionedHrefs(): string[];
+    private updateView;
+}
+export declare const richTextViewerTag = "nimble-rich-text-viewer";

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

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

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

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

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

@@ -0,0 +1,27 @@
+import type { RichTextViewer } from '..';
+/**
+ * Page object for the `nimble-rich-text-viewer` component.
+ */
+export declare class RichTextViewerPageObject {
+    private readonly richTextViewerElement;
+    constructor(richTextViewerElement: RichTextViewer);
+    getRenderedMarkdownLastChildContents(): string;
+    getRenderedMarkdownLastChildAttribute(attribute: string): string;
+    /**
+     * Retrieves tag names for the rendered markdown content in document order
+     * @returns An array of tag names in document order
+     */
+    getRenderedMarkdownTagNames(): string[];
+    /**
+     * @returns An array of tag names with the closing tags (eg: '/P') in a document order
+     */
+    getRenderedMarkdownTagNamesWithClosingTags(): string[];
+    /**
+     * Retrieves text contents for the rendered markdown content in document order
+     * @returns An array of text contents of last elements in a tree
+     */
+    getRenderedMarkdownLeafContents(): string[];
+    getRenderedMarkdownAttributeValues(attribute: string): string[];
+    private getMarkdownRenderedElement;
+    private getLastChildMarkdownRenderedElement;
+}

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

@@ -0,0 +1,56 @@
+import { Notifier, Subscriber } from '@microsoft/fast-element';
+import { FoundationElement } from '@microsoft/fast-foundation';
+import type { MappingConfig } from './models/mapping-config';
+import type { RichTextMentionValidator, RichTextMentionValidity } from './models/mention-validator';
+import { MentionInternals, MentionInternalsOptions } from './models/mention-internals';
+import { Mapping } from '../../mapping/base';
+/**
+ * The base class for Mention configuration
+ */
+export declare abstract class RichTextMention<TValidator extends RichTextMentionValidator = RichTextMentionValidator> extends FoundationElement implements Subscriber {
+    /**
+     * @internal
+     */
+    readonly mentionInternals: MentionInternals;
+    /** @internal */
+    readonly validator: TValidator;
+    /**
+     * A regex used to extract user ID from user key (url) while parsing and serializing a markdown.
+     */
+    pattern?: string;
+    /**
+     * @public
+     */
+    buttonLabel?: string;
+    /** @internal */
+    mappingNotifiers: Notifier[];
+    /** @internal */
+    mappingElements: Mapping<unknown>[];
+    /**
+     * @public
+     */
+    checkValidity(): boolean;
+    /**
+     * @public
+     */
+    get validity(): RichTextMentionValidity;
+    /**
+     * @internal
+     */
+    emitMentionUpdate(filter: string): void;
+    /**
+     * @internal
+     */
+    handleChange(source: unknown, args: unknown): void;
+    protected abstract createValidator(): TValidator;
+    protected abstract getObservedMappingProperty(): string[];
+    protected abstract getMentionInternalsOptions(): MentionInternalsOptions;
+    protected abstract createMappingConfig(mapping: Mapping<unknown>): MappingConfig;
+    private getMappingConfigs;
+    private updateMappingConfigs;
+    private mappingElementsChanged;
+    private patternChanged;
+    private buttonLabelChanged;
+    private removeMappingElementObservers;
+    private observeMappingElements;
+}

package/dist/esm/src/rich-text-mention/base/models/mapping-config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Common state shared across Mapping Config
+ */
+export declare abstract class MappingConfig {
+    readonly mentionHref: string | undefined;
+    readonly displayName: string | undefined;
+    constructor(mentionHref: string | undefined, displayName: string | undefined);
+}

package/dist/esm/src/rich-text-mention/base/models/mention-internals.d.ts

@@ -0,0 +1,45 @@
+import { ViewTemplate } from '@microsoft/fast-element';
+import type { MappingConfigs, MentionUpdateEmitter } from '../types';
+export interface MentionInternalsOptions {
+    readonly icon: string;
+    readonly character: string;
+    readonly viewElement: string;
+}
+/**
+ * Internal mention state
+ */
+export declare class MentionInternals {
+    /**
+     * Mappings configured for the mention node
+     */
+    mappingConfigs?: MappingConfigs;
+    /**
+     * Whether this mention has a valid configuration.
+     */
+    validConfiguration: boolean;
+    /**
+     * Regex used to extract user ID from user key (url)
+     */
+    pattern?: string;
+    /**
+     * Label to use as accessible name and title of mention button
+     */
+    buttonLabel?: string;
+    /**
+     * Template of the Icon to display on RichTextEditor Toolbar
+     */
+    readonly iconTemplate: ViewTemplate;
+    /**
+     * Character to show respective mention list
+     */
+    readonly character: string;
+    /**
+     * Mention view element to render in rich text components
+     */
+    readonly viewElement: string;
+    /**
+     * Function to invoke to emit a mention-update event
+     */
+    readonly mentionUpdateEmitter: MentionUpdateEmitter;
+    constructor(options: MentionInternalsOptions, mentionUpdateEmitter: MentionUpdateEmitter);
+}

package/dist/esm/src/rich-text-mention/base/models/mention-validator.d.ts

@@ -0,0 +1,33 @@
+import type { Mapping } from '../../../mapping/base';
+import { Validator, ValidityObject } from '../../../utilities/models/validator';
+import type { MentionInternals } from './mention-internals';
+export interface RichTextMentionValidity extends ValidityObject {
+}
+type FlagNames<T> = T extends readonly (infer U)[] ? U : never;
+export declare const baseValidityFlagNames: readonly ["duplicateMappingMentionHref", "missingMentionHrefValue", "mentionHrefNotValidUrl", "mentionHrefDoesNotMatchPattern", "missingPatternAttribute", "unsupportedPatternValue"];
+/**
+ * Validator for RichTextMention
+ */
+export declare class RichTextMentionValidator<ValidityFlagNames extends readonly string[] = typeof baseValidityFlagNames> extends Validator<typeof baseValidityFlagNames | ValidityFlagNames> {
+    private readonly mentionInternals;
+    constructor(mentionInternals: MentionInternals, configValidityKeys: ValidityFlagNames);
+    validate(mappings: Mapping<unknown>[], pattern: string | undefined): void;
+    /**
+     * @returns an object containing flags for various ways the configuation can be invalid
+     */
+    getValidity(): RichTextMentionValidity;
+    /**
+     * Sets a particular validity condition flag's value, e.g. "hasInvalidFooValue" = true
+     */
+    protected setConditionValue(name: FlagNames<typeof baseValidityFlagNames | ValidityFlagNames>, isInvalid: boolean): void;
+    private updateMentionInternalsFlag;
+    private validateMissingPattern;
+    private validatePattern;
+    private validateUniqueMentionHref;
+    private validateNoMissingMentionHref;
+    private validateHrefForUrl;
+    private validateHrefForPattern;
+    private isInvalidUrl;
+    private isInvalidRegex;
+}
+export {};

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

@@ -0,0 +1,2 @@
+import type { RichTextMention } from '.';
+export declare const template: import("@microsoft/fast-element").ViewTemplate<RichTextMention<import("./models/mention-validator").RichTextMentionValidator<readonly ["duplicateMappingMentionHref", "missingMentionHrefValue", "mentionHrefNotValidUrl", "mentionHrefDoesNotMatchPattern", "missingPatternAttribute", "unsupportedPatternValue"]>>, any>;

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

@@ -0,0 +1,10 @@
+import type { MappingConfig } from './models/mapping-config';
+/**
+ * The type of the detail associated with the `mention-update`
+ * event on the banner.
+ */
+export interface MentionUpdateEventDetail {
+    filter: string;
+}
+export type MappingConfigs = ReadonlyMap<string, MappingConfig>;
+export type MentionUpdateEmitter = (filter: string) => void;

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

@@ -0,0 +1,20 @@
+import { FoundationElement } from '@microsoft/fast-foundation';
+/**
+ * The base class for Mention View Node
+ */
+export declare class RichTextMentionView extends FoundationElement {
+    /**
+     * Stores the unique URL of the mentioned user matching the pattern
+     *
+     * @public
+     * HTML Attribute: mention-href
+     */
+    mentionHref?: string;
+    /**
+     * Stores the value of the rendering label
+     *
+     * @public
+     * HTML Attribute: mention-label
+     */
+    mentionLabel?: string;
+}

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

@@ -0,0 +1,21 @@
+import type { MentionInternalsOptions } from '../base/models/mention-internals';
+import { RichTextMention } from '../base';
+import type { MappingConfig } from '../base/models/mapping-config';
+import type { Mapping } from '../../mapping/base';
+import type { MappingUserKey } from '../../mapping/base/types';
+import { RichTextMentionUsersValidator } from './models/rich-text-mention-users-validator';
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-rich-text-mention-users': RichTextMentionUsers;
+    }
+}
+/**
+ * Rich Text user mention configuration element which will have MappingMentionUser elements as children
+ */
+export declare class RichTextMentionUsers extends RichTextMention<RichTextMentionUsersValidator> {
+    protected createValidator(): RichTextMentionUsersValidator;
+    protected getMentionInternalsOptions(): MentionInternalsOptions;
+    protected getObservedMappingProperty(): string[];
+    protected createMappingConfig(mapping: Mapping<MappingUserKey>): MappingConfig;
+}
+export declare const richTextMentionUsersTag = "nimble-rich-text-mention-users";

package/dist/esm/src/rich-text-mention/users/models/mapping-user-config.d.ts

@@ -0,0 +1,6 @@
+import { MappingConfig } from '../../base/models/mapping-config';
+/**
+ * Mapping configuration corresponding to a user mapping
+ */
+export declare class MappingUserConfig extends MappingConfig {
+}

package/dist/esm/src/rich-text-mention/users/models/rich-text-mention-users-validator.d.ts

@@ -0,0 +1,16 @@
+import type { Mapping } from '../../../mapping/base';
+import type { MappingUserKey } from '../../../mapping/base/types';
+import type { MentionInternals } from '../../base/models/mention-internals';
+import { RichTextMentionValidator } from '../../base/models/mention-validator';
+declare const usersValidityFlagNames: readonly ["duplicateMappingMentionHref", "missingMentionHrefValue", "mentionHrefNotValidUrl", "mentionHrefDoesNotMatchPattern", "missingPatternAttribute", "unsupportedPatternValue", "missingDisplayNameValue", "unsupportedMappingType"];
+/**
+ * Validator for RichTextMentionUsers
+ */
+export declare class RichTextMentionUsersValidator extends RichTextMentionValidator<typeof usersValidityFlagNames> {
+    constructor(columnInternals: MentionInternals);
+    private static isSupportedMappingElement;
+    validate(mappings: Mapping<MappingUserKey>[], pattern: string): void;
+    private validateNoMissingDisplayName;
+    private validateMappingTypes;
+}
+export {};

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

@@ -0,0 +1,12 @@
+import { RichTextMentionView } from '../../base/view';
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-rich-text-mention-users-view': RichTextMentionUsersView;
+    }
+}
+/**
+ * A nimble styled rich text mention users view
+ */
+export declare class RichTextMentionUsersView extends RichTextMentionView {
+}
+export declare const richTextMentionUsersViewTag = "nimble-rich-text-mention-users-view";

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

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

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

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

package/dist/esm/src/rich-text-mention/users/view/testing/rich-text-mention-users-view.pageobject.d.ts

@@ -0,0 +1,9 @@
+import type { RichTextMentionUsersView } from '..';
+/**
+ * Page object for the `nimble-rich-text-mention-users-view` component.
+ */
+export declare class RichTextMentionUsersViewPageObject {
+    private readonly richTextMentionUsersViewElement;
+    constructor(richTextMentionUsersViewElement: RichTextMentionUsersView);
+    getTextContent(): string;
+}