@finos/legend-application 3.0.3 → 4.0.2

package/src/stores/LegendApplicationAssistantService.ts

@@ -0,0 +1,218 @@
+/**
+ * Copyright (c) 2020-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { action, makeObservable, observable, computed } from 'mobx';
+import type {
+  LegendApplicationContextualDocumentationEntry,
+  LegendApplicationDocumentationEntry,
+} from './LegendApplicationDocumentationService.js';
+import type { LegendApplicationConfig } from './LegendApplicationConfig.js';
+import type { ApplicationStore } from './ApplicationStore.js';
+import { Fuse } from './CJS__Fuse.cjs';
+import {
+  type MarkdownText,
+  guaranteeNonEmptyString,
+  uuid,
+  isNonNullable,
+  ActionState,
+} from '@finos/legend-shared';
+
+export enum VIRTUAL_ASSISTANT_TAB {
+  SEARCH = 'SEARCH',
+  CONTEXTUAL_SUPPORT = 'CONTEXTUAL_SUPPORT',
+}
+
+export class VirtualAssistantDocumentationEntry {
+  uuid = uuid();
+  documentationKey: string;
+  title: string;
+  content?: string | MarkdownText | undefined;
+  url?: string | undefined;
+  isOpen = false;
+
+  constructor(docEntry: LegendApplicationDocumentationEntry) {
+    makeObservable(this, {
+      isOpen: observable,
+      setIsOpen: action,
+    });
+
+    this.documentationKey = docEntry._documentationKey;
+    this.title = guaranteeNonEmptyString(docEntry.title);
+    this.content = docEntry.markdownText ?? docEntry.text;
+    this.url = docEntry.url;
+  }
+
+  setIsOpen(val: boolean): void {
+    this.isOpen = val;
+  }
+}
+
+export class VirtualAssistantContextualDocumentationEntry {
+  uuid = uuid();
+  context: string;
+  title?: string | undefined;
+  content?: string | MarkdownText | undefined;
+  url?: string | undefined;
+  related: VirtualAssistantDocumentationEntry[];
+
+  constructor(
+    contextualDocEntry: LegendApplicationContextualDocumentationEntry,
+    related: VirtualAssistantDocumentationEntry[],
+  ) {
+    this.context = contextualDocEntry._context;
+    this.title = contextualDocEntry.title;
+    this.content = contextualDocEntry.markdownText ?? contextualDocEntry.text;
+    this.url = contextualDocEntry.url;
+    this.related = related;
+  }
+}
+
+export class LegendApplicationAssistantService {
+  readonly applicationStore: ApplicationStore<LegendApplicationConfig>;
+  private readonly searchEngine: Fuse<LegendApplicationDocumentationEntry>;
+  isHidden = false;
+  isOpen = false;
+  selectedTab = VIRTUAL_ASSISTANT_TAB.SEARCH;
+
+  searchResults: VirtualAssistantDocumentationEntry[] = [];
+  searchState = ActionState.create().pass();
+  searchText = '';
+
+  constructor(applicationStore: ApplicationStore<LegendApplicationConfig>) {
+    makeObservable(this, {
+      isHidden: observable,
+      isOpen: observable,
+      selectedTab: observable,
+      searchText: observable,
+      searchResults: observable,
+      currentContextualDocumentationEntry: computed,
+      setIsHidden: action,
+      setIsOpen: action,
+      setSelectedTab: action,
+      setSearchText: action,
+      resetSearch: action,
+      search: action,
+    });
+
+    this.applicationStore = applicationStore;
+    this.searchEngine = new Fuse(
+      this.applicationStore.documentationService.getAllDocEntries().filter(
+        (entry) =>
+          // NOTE: since we're searching for user-friendly docs, we will discard anything that
+          // doesn't come with a title, or does not have any content/url
+          entry.title && (entry.url ?? entry.text ?? entry.markdownText),
+      ),
+      {
+        includeScore: true,
+        shouldSort: true,
+        // Ignore location when computing the search score
+        // See https://fusejs.io/concepts/scoring-theory.html
+        ignoreLocation: true,
+        // This specifies the point the search gives up
+        // `0.0` means exact match where `1.0` would match anything
+        // We set a relatively low threshold to filter out irrelevant results
+        threshold: 0.2,
+        keys: [
+          {
+            // NOTE: for now, we would weight title the most
+            name: 'title',
+            weight: 4,
+          },
+          {
+            name: 'text',
+            weight: 1,
+          },
+          {
+            name: 'markdownText.value',
+            weight: 1,
+          },
+        ],
+      },
+    );
+  }
+
+  get currentContextualDocumentationEntry():
+    | VirtualAssistantContextualDocumentationEntry
+    | undefined {
+    const currentContextualDocumentationEntry = this.applicationStore
+      .navigationContextService.currentContext
+      ? this.applicationStore.documentationService.getContextualDocEntry(
+          this.applicationStore.navigationContextService.currentContext.value,
+        )
+      : undefined;
+    return currentContextualDocumentationEntry
+      ? new VirtualAssistantContextualDocumentationEntry(
+          currentContextualDocumentationEntry,
+          currentContextualDocumentationEntry.related
+            .map((entry) =>
+              this.applicationStore.documentationService.getDocEntry(entry),
+            )
+            .filter(isNonNullable)
+            .filter(
+              (entry) =>
+                // NOTE: since we're searching for user-friendly docs, we will discard anything that
+                // doesn't come with a title, or does not have any content/url
+                entry.title && (entry.url ?? entry.text ?? entry.markdownText),
+            )
+            .map((entry) => new VirtualAssistantDocumentationEntry(entry)),
+        )
+      : undefined;
+  }
+
+  setIsHidden(val: boolean): void {
+    this.isHidden = val;
+  }
+
+  hideAssistant(): void {
+    this.setIsHidden(true);
+    this.setIsOpen(false);
+  }
+
+  toggleAssistant(): void {
+    const newVal = !this.isHidden;
+    if (newVal) {
+      this.hideAssistant();
+    } else {
+      this.setIsHidden(false);
+    }
+  }
+
+  setIsOpen(val: boolean): void {
+    this.isOpen = val;
+  }
+
+  setSelectedTab(val: VIRTUAL_ASSISTANT_TAB): void {
+    this.selectedTab = val;
+  }
+
+  setSearchText(val: string): void {
+    this.searchText = val;
+  }
+
+  resetSearch(): void {
+    this.searchText = '';
+    this.searchResults = [];
+    this.searchState.complete();
+  }
+
+  search(): void {
+    this.searchState.inProgress();
+    this.searchResults = Array.from(
+      this.searchEngine.search(this.searchText).values(),
+    ).map((result) => new VirtualAssistantDocumentationEntry(result.item));
+    this.searchState.complete();
+  }
+}

package/src/stores/LegendApplicationConfig.ts

@@ -17,13 +17,15 @@
 import {
   guaranteeNonEmptyString,
   guaranteeNonNullable,
-  type PlainObject,
 } from '@finos/legend-shared';
 import {
   type LegendApplicationKeyedDocumentationEntry,
-  type LegendApplicationDocumentationEntry,
+  type LegendApplicationDocumentationEntryConfig,
+  type LegendApplicationKeyedContextualDocumentationEntry,
+  type LegendApplicationContextualDocumentationEntryConfig,
   collectKeyedDocumnetationEntriesFromConfig,
-} from './LegendApplicationDocumentationRegistry';
+  collectKeyedContextualDocumentationEntriesFromConfig,
+} from './LegendApplicationDocumentationService.js';
 
 export interface LegendApplicationVersionData {
   buildTime: string;
@@ -36,7 +38,11 @@ export interface LegendApplicationConfigurationData {
   env: string;
   documentation?: {
     url: string;
-    entries?: Record<string, PlainObject<LegendApplicationDocumentationEntry>>;
+    entries?: Record<string, LegendApplicationDocumentationEntryConfig>;
+    contextualEntries?: Record<
+      string,
+      LegendApplicationContextualDocumentationEntryConfig
+    >;
   };
   // TODO: when we support vault-like settings
   // See https://github.com/finos/legend-studio/issues/407
@@ -49,10 +55,14 @@ export abstract class LegendApplicationConfig {
   readonly baseUrl: string;
   readonly env: string;
 
+  // documentation
   readonly documentationUrl: string | undefined;
-  readonly documentationKeyedEntries: LegendApplicationKeyedDocumentationEntry[] =
+  readonly keyedDocumentationEntries: LegendApplicationKeyedDocumentationEntry[] =
+    [];
+  readonly keyedContextualDocumentationEntries: LegendApplicationKeyedContextualDocumentationEntry[] =
     [];
 
+  // version
   readonly appVersion: string;
   readonly appVersionBuildTime: string;
   readonly appVersionCommitId: string;
@@ -74,9 +84,13 @@ export abstract class LegendApplicationConfig {
 
     // Documentation
     this.documentationUrl = configData.documentation?.url;
-    this.documentationKeyedEntries = collectKeyedDocumnetationEntriesFromConfig(
+    this.keyedDocumentationEntries = collectKeyedDocumnetationEntriesFromConfig(
       configData.documentation?.entries ?? {},
     );
+    this.keyedContextualDocumentationEntries =
+      collectKeyedContextualDocumentationEntriesFromConfig(
+        configData.documentation?.contextualEntries ?? {},
+      );
 
     // Version
     this.appVersion = guaranteeNonNullable(

package/src/stores/LegendApplicationDocumentationService.ts

@@ -0,0 +1,276 @@
+/**
+ * Copyright (c) 2020-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  type MarkdownText,
+  type PlainObject,
+  type Writable,
+  SerializationFactory,
+  LogEvent,
+  uniq,
+  guaranteeNonNullable,
+} from '@finos/legend-shared';
+import {
+  createModelSchema,
+  custom,
+  list,
+  optional,
+  primitive,
+} from 'serializr';
+import { APPLICATION_EVENT } from './ApplicationEvent.js';
+import type { ApplicationStore } from './ApplicationStore.js';
+import type { LegendApplicationConfig } from './LegendApplicationConfig.js';
+
+export type LegendApplicationDocumentationEntryConfig = {
+  markdownText?: MarkdownText | undefined;
+  title?: string | undefined;
+  text?: string | undefined;
+  url?: string | undefined;
+};
+
+export class LegendApplicationDocumentationEntry {
+  readonly _documentationKey!: string;
+
+  markdownText?: MarkdownText | undefined;
+  title?: string | undefined;
+  text?: string | undefined;
+  url?: string | undefined;
+
+  static readonly serialization = new SerializationFactory(
+    createModelSchema(LegendApplicationDocumentationEntry, {
+      markdownText: custom(
+        (val) => val,
+        (val) => (val.value ? val : undefined),
+      ),
+      title: optional(primitive()),
+      text: optional(primitive()),
+      url: optional(primitive()),
+    }),
+  );
+
+  static create(
+    json: PlainObject<LegendApplicationDocumentationEntry>,
+    documentationKey: string,
+  ): LegendApplicationDocumentationEntry {
+    const entry =
+      LegendApplicationDocumentationEntry.serialization.fromJson(json);
+    (entry as Writable<LegendApplicationDocumentationEntry>)._documentationKey =
+      documentationKey;
+    return entry;
+  }
+}
+
+export type LegendApplicationContextualDocumentationEntryConfig =
+  LegendApplicationDocumentationEntryConfig & {
+    related?: string[];
+  };
+
+export class LegendApplicationContextualDocumentationEntry {
+  readonly _context!: string;
+
+  markdownText?: MarkdownText | undefined;
+  title?: string | undefined;
+  text?: string | undefined;
+  url?: string | undefined;
+  related: string[] = [];
+
+  static readonly serialization = new SerializationFactory(
+    createModelSchema(LegendApplicationContextualDocumentationEntry, {
+      markdownText: custom(
+        (val) => val,
+        (val) => (val.value ? val : undefined),
+      ),
+      title: optional(primitive()),
+      text: optional(primitive()),
+      url: optional(primitive()),
+      related: list(primitive()),
+    }),
+  );
+
+  static create(
+    json: PlainObject<LegendApplicationContextualDocumentationEntry>,
+    context: string,
+  ): LegendApplicationContextualDocumentationEntry {
+    const entry =
+      LegendApplicationContextualDocumentationEntry.serialization.fromJson(
+        json,
+      );
+    (
+      entry as Writable<LegendApplicationContextualDocumentationEntry>
+    )._context = context;
+    return entry;
+  }
+}
+
+export interface LegendApplicationKeyedContextualDocumentationEntry {
+  key: string;
+  content: LegendApplicationContextualDocumentationEntry;
+}
+
+export const collectKeyedContextualDocumentationEntriesFromConfig = (
+  rawEntries: Record<
+    string,
+    LegendApplicationContextualDocumentationEntryConfig
+  >,
+): LegendApplicationKeyedContextualDocumentationEntry[] =>
+  Object.entries(rawEntries).map((entry) => ({
+    key: entry[0],
+    content: LegendApplicationContextualDocumentationEntry.create(
+      entry[1],
+      entry[0],
+    ),
+  }));
+
+export interface LegendApplicationKeyedDocumentationEntry {
+  key: string;
+  content: LegendApplicationDocumentationEntry;
+}
+
+export const collectKeyedDocumnetationEntriesFromConfig = (
+  rawEntries: Record<string, LegendApplicationDocumentationEntryConfig>,
+): LegendApplicationKeyedDocumentationEntry[] =>
+  Object.entries(rawEntries).map((entry) => ({
+    key: entry[0],
+    content: LegendApplicationDocumentationEntry.create(entry[1], entry[0]),
+  }));
+
+export class LegendApplicationDocumentationService {
+  url?: string | undefined;
+
+  private docRegistry = new Map<string, LegendApplicationDocumentationEntry>();
+  private contextualDocRegistry = new Map<
+    string,
+    LegendApplicationContextualDocumentationEntry
+  >();
+
+  constructor(applicationStore: ApplicationStore<LegendApplicationConfig>) {
+    applicationStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap((plugin) => plugin.getExtraKeyedDocumentationEntries?.() ?? [])
+      .forEach((entry) => {
+        // Entries specified natively will not override each other. This is to prevent entries from extensions
+        // overriding entries from core.
+        if (this.hasDocEntry(entry.key)) {
+          applicationStore.log.warn(
+            LogEvent.create(
+              APPLICATION_EVENT.APPLICATION_DOCUMTENTION_LOAD_SKIPPED,
+            ),
+            entry.key,
+          );
+        } else {
+          this.docRegistry.set(entry.key, entry.content);
+        }
+      });
+    // entries from config will override entries specified natively
+    applicationStore.config.keyedDocumentationEntries.forEach((entry) =>
+      this.docRegistry.set(entry.key, entry.content),
+    );
+
+    // Contextual Documentation
+    applicationStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap(
+        (plugin) =>
+          plugin.getExtraKeyedContextualDocumentationEntries?.() ?? [],
+      )
+      .forEach((entry) => {
+        // Entries specified natively will not override each other. This is to prevent entries from extensions
+        // overriding entries from core. However, we will merge the list of related doc entries. This allows
+        // extensions to broaden related doc entries for certain contexts
+        if (this.hasContextualDocEntry(entry.key)) {
+          applicationStore.log.warn(
+            LogEvent.create(
+              APPLICATION_EVENT.APPLICATION_CONTEXTUAL_DOCUMTENTION_LOAD_SKIPPED,
+            ),
+            entry.key,
+          );
+          const existingEntry = guaranteeNonNullable(
+            this.getContextualDocEntry(entry.key),
+          );
+          existingEntry.related = uniq([
+            ...existingEntry.related,
+            ...entry.content.related,
+          ]);
+        } else {
+          this.contextualDocRegistry.set(entry.key, entry.content);
+        }
+      });
+    // entries from config will override entries specified natively
+    // however, we will keep merging related doc entries list
+    applicationStore.config.keyedContextualDocumentationEntries.forEach(
+      (entry) => {
+        const existingEntry = this.getContextualDocEntry(entry.key);
+        if (existingEntry) {
+          entry.content.related = uniq([
+            ...existingEntry.related,
+            ...entry.content.related,
+          ]);
+        }
+        this.contextualDocRegistry.set(entry.key, entry.content);
+      },
+    );
+    this.url = applicationStore.config.documentationUrl;
+  }
+
+  getDocEntry(key: string): LegendApplicationDocumentationEntry | undefined {
+    return this.docRegistry.get(key);
+  }
+
+  hasDocEntry(key: string): boolean {
+    return this.docRegistry.has(key);
+  }
+
+  getContextualDocEntry(
+    key: string,
+  ): LegendApplicationContextualDocumentationEntry | undefined {
+    return this.contextualDocRegistry.get(key);
+  }
+
+  hasContextualDocEntry(key: string): boolean {
+    return this.contextualDocRegistry.has(key);
+  }
+
+  getAllDocEntries(): LegendApplicationDocumentationEntry[] {
+    return Array.from(this.docRegistry.values());
+  }
+
+  publishDocRegistry(): Record<
+    string,
+    LegendApplicationDocumentationEntryConfig
+  > {
+    const result: Record<string, LegendApplicationDocumentationEntryConfig> =
+      {};
+    this.docRegistry.forEach((value, key) => {
+      result[key] =
+        LegendApplicationDocumentationEntry.serialization.toJson(value);
+    });
+    return result;
+  }
+
+  publishContextualDocRegistry(): object {
+    const result: Record<
+      string,
+      LegendApplicationContextualDocumentationEntryConfig
+    > = {};
+    this.contextualDocRegistry.forEach((value, key) => {
+      result[key] =
+        LegendApplicationContextualDocumentationEntry.serialization.toJson(
+          value,
+        );
+    });
+    return result;
+  }
+}

package/src/stores/LegendApplicationEventService.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2020-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  NotificationEventData,
+  EventNotifierPlugin,
+} from '@finos/legend-shared';
+
+export class LegendApplicationEventService {
+  private notifierPlugins: EventNotifierPlugin[] = [];
+
+  registerEventNotifierPlugins(plugins: EventNotifierPlugin[]): void {
+    this.notifierPlugins = plugins;
+  }
+
+  notify(event: string, data: NotificationEventData): void {
+    this.notifierPlugins.forEach((plugin) => plugin.notify(event, data));
+  }
+}