@mathstack/app-kit 1.1.2 → 2.0.3

package/src/lib/core/utilities/deep-merge.ts

@@ -0,0 +1,21 @@
+export function deepMerge<T>(target: T, source: Partial<T>): T {
+  const output = Object.assign({}, target);
+  if (isObject(target) && isObject(source)) {
+    Object.keys(source).forEach((key) => {
+      if (isObject(source[key])) {
+        if (!(key in (target as object))) {
+          Object.assign(output, { [key]: source[key] });
+        } else {
+          output[key] = deepMerge(target[key], source[key]);
+        }
+      } else {
+        Object.assign(output, { [key]: source[key] });
+      }
+    });
+  }
+  return output;
+}
+
+function isObject(item: unknown): item is object {
+  return item && typeof item === 'object' && !Array.isArray(item);
+}

package/{lib/core/utilities/index.d.ts → src/lib/core/utilities/index.ts}

@@ -1,2 +1,2 @@
-export * from './deep-merge';
-export * from './safe-assign';
+export * from './deep-merge';
+export * from './safe-assign';

package/src/lib/core/utilities/safe-assign.spec.ts

@@ -0,0 +1,41 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { safeAssign } from './safe-assign';
+
+describe('applyDefaultsSafely', () => {
+  it('should apply defaults to the target object', () => {
+    const target = { a: 1, b: 2 };
+    const defaults = { b: 3, c: 4 };
+
+    safeAssign(target, defaults);
+
+    expect(target).toEqual({ a: 1, b: 3, c: 4 } as any);
+  });
+
+  it('should not overwrite existing function properties', () => {
+    const target = { a: () => 'existing', b: 2 };
+    const defaults = { a: () => 'new', b: 3 };
+
+    safeAssign(target, defaults);
+
+    expect(target.a()).toBe('existing');
+    expect(target.b).toBe(3);
+  });
+
+  it('should handle empty defaults', () => {
+    const target = { a: 1, b: 2 };
+    const defaults = {};
+
+    safeAssign(target, defaults);
+
+    expect(target).toEqual({ a: 1, b: 2 });
+  });
+
+  it('should handle empty target', () => {
+    const target = {};
+    const defaults = { a: 1, b: 2 };
+
+    safeAssign(target, defaults);
+
+    expect(target).toEqual({ a: 1, b: 2 });
+  });
+});

package/{lib/core/utilities/safe-assign.d.ts → src/lib/core/utilities/safe-assign.ts}

@@ -1,18 +1,42 @@
-/**
- * Safely assigns properties from a source object to a target object.
- *
- * Copies all own, enumerable properties from `source` to `target`,
- * except when the target already has a property of the same name that is a function.
- *
- * Logs a warning for each skipped property if `logConflicts` is true.
- *
- * @template TTarget The type of the target object.
- * @template TSource The type of the source object.
- * @param target The object to assign properties to.
- * @param source The object providing properties to assign.
- * @param logConflicts If true, logs when a method/property on the target prevents assignment. Default is false.
- *
- * @example
- * safeAssign(this, { log: 'hello' }, true);
- */
-export declare function safeAssign<TTarget extends object, TSource extends object>(target: TTarget, source: TSource, logConflicts?: boolean): void;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Safely assigns properties from a source object to a target object.
+ *
+ * Copies all own, enumerable properties from `source` to `target`,
+ * except when the target already has a property of the same name that is a function.
+ *
+ * Logs a warning for each skipped property if `logConflicts` is true.
+ *
+ * @template TTarget The type of the target object.
+ * @template TSource The type of the source object.
+ * @param target The object to assign properties to.
+ * @param source The object providing properties to assign.
+ * @param logConflicts If true, logs when a method/property on the target prevents assignment. Default is false.
+ *
+ * @example
+ * safeAssign(this, { log: 'hello' }, true);
+ */
+export function safeAssign<TTarget extends object, TSource extends object>(
+  target: TTarget,
+  source: TSource,
+  logConflicts: boolean = false
+): void {
+  if (!source) return;
+
+  for (const key of Object.keys(source)) {
+    const existing = (target as any)[key];
+    const incoming = (source as any)[key];
+
+    if (typeof existing === 'function') {
+      if (logConflicts) {
+        console.warn(
+          `safeAssign: Skipped assignment for key "${key}" because it would overwrite an existing method.`
+        );
+      }
+      continue;
+    }
+
+    (target as any)[key] = incoming;
+  }
+}

package/src/lib/documentation-display/active-heading-tracker.ts

@@ -0,0 +1,61 @@
+import { DestroyRef, inject, Injectable, NgZone } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import {
+  BehaviorSubject,
+  debounceTime,
+  distinctUntilChanged,
+  fromEvent,
+} from 'rxjs';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class AdkActiveHeadingTracker {
+  private activeHeadingId = new BehaviorSubject<string | null>(null);
+  activeHeadingId$ = this.activeHeadingId.asObservable();
+
+  private ngZone = inject(NgZone);
+
+  initScrollListener(contentEl: HTMLElement, destroyRef: DestroyRef): void {
+    this.ngZone.runOutsideAngular(() => {
+      fromEvent(window, 'scroll')
+        .pipe(
+          takeUntilDestroyed(destroyRef),
+          debounceTime(50),
+          distinctUntilChanged()
+        )
+        .subscribe(() => {
+          const headings = Array.from(
+            contentEl.querySelectorAll('h1, h2, h3, h4, h5, h6')
+          ) as HTMLHeadingElement[];
+          const activeHeading = this.findActiveHeading(headings);
+          this.ngZone.run(() => {
+            if (activeHeading) {
+              this.activeHeadingId.next(activeHeading.id);
+            }
+          });
+        });
+    });
+  }
+
+  private findActiveHeading(
+    headings: HTMLHeadingElement[]
+  ): HTMLHeadingElement | null {
+    const scrollPosition = window.scrollY;
+    for (let i = headings.length - 1; i >= 0; i--) {
+      const heading = headings[i];
+      if (heading.offsetTop <= scrollPosition + 50) {
+        return heading;
+      }
+    }
+    return headings[0] || null;
+  }
+
+  setActiveHeading(heading: HTMLHeadingElement): void {
+    this.activeHeadingId.next(heading.id);
+  }
+
+  scrollToTop(): void {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  }
+}

package/src/lib/documentation-display/document-index/document-index.component.html

@@ -0,0 +1,34 @@
+<nav class="toc">
+  @if (headings.length > 0) {
+    <p class="index-title">On this page</p>
+    <ul class="links-container">
+      @for (heading of headings; track $index) {
+        <li class="toc-item">
+          <button
+            type="button"
+            class="toc-link"
+            [style.--level]="heading.level"
+            (click)="setActiveHeading($event, heading)"
+            (keydown.enter)="setActiveHeading($event, heading)"
+            [class.active]="
+              heading.id === (activeHeadingTracker.activeHeadingId$ | async)
+            "
+            >{{ heading.text }}</button
+          >
+        </li>
+      }
+    </ul>
+    <button
+      type="button"
+      class="back-to-top"
+      (click)="scrollToTop()"
+      (keydown.enter)="scrollToTop()"
+    >
+      Back to top<span
+        aria-hidden="true"
+        class="material-symbols-outlined arrow"
+        >arrow_upward</span
+      >
+    </button>
+  }
+</nav>

package/src/lib/documentation-display/document-index/document-index.component.scss

@@ -0,0 +1,56 @@
+@use '../../baseline-styles/grid' as *;
+@use '../../core/scss/placeholders' as *;
+@use '../../core/scss/colors';
+
+.links-container {
+  list-style: none;
+  flex-basis: 28%;
+  padding: 0;
+  margin: 0;
+  width: 250px;
+}
+
+.index-title {
+  @include label-2xs-caps;
+  padding-bottom: grid(1);
+}
+
+.toc-link {
+  @include body-xs;
+  cursor: pointer;
+  padding-top: grid(1);
+  padding-bottom: grid(1);
+  padding-left: calc((var(--level) - 1) * grid(4));
+  display: block;
+  border-left: 2px solid colors.$muted-primary-90;
+  color: colors.$muted-primary-50;
+  text-align: left;
+}
+
+.toc-link:hover {
+  color: colors.$muted-primary-25;
+  border-left: 2px solid colors.$muted-primary-70;
+}
+
+.toc-link.active {
+  color: colors.$primary-40;
+  border-left: 2px solid colors.$primary-40;
+}
+
+.back-to-top {
+  @include body-xs;
+  cursor: pointer;
+  padding: grid(2) 0;
+  display: flex;
+  align-items: center;
+  text-align: left;
+  color: colors.$muted-primary-40;
+}
+
+.back-to-top:hover {
+  color: colors.$muted-primary-10;
+}
+
+.arrow {
+  transform: scale(0.7);
+}

package/src/lib/documentation-display/document-index/document-index.component.ts

@@ -0,0 +1,39 @@
+import { CommonModule } from '@angular/common';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  EventEmitter,
+  inject,
+  Input,
+  Output,
+} from '@angular/core';
+import { AdkActiveHeadingTracker } from '../active-heading-tracker';
+import { AdkHtmlHeader } from '../documentation-content-service';
+
+@Component({
+  selector: 'hsi-adk-document-index',
+  imports: [CommonModule],
+  templateUrl: './document-index.component.html',
+  styleUrls: ['./document-index.component.scss'],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AdkDocumentIndexComponent {
+  @Input() headings: AdkHtmlHeader[] = [];
+  @Output() activeHeading = new EventEmitter<{
+    heading: AdkHtmlHeader;
+    event: KeyboardEvent | PointerEvent | MouseEvent | Event;
+  }>();
+
+  public activeHeadingTracker = inject(AdkActiveHeadingTracker);
+
+  setActiveHeading(
+    event: KeyboardEvent | PointerEvent | MouseEvent | Event,
+    heading: AdkHtmlHeader
+  ): void {
+    this.activeHeading.emit({ heading, event });
+  }
+
+  scrollToTop(): void {
+    this.activeHeadingTracker.scrollToTop();
+  }
+}

package/src/lib/documentation-display/documentation-config-parser.ts

@@ -0,0 +1,92 @@
+import { Injectable } from '@angular/core';
+
+export interface AdkNestedObject {
+  [key: string]: string | AdkNestedObject;
+}
+
+export interface AdkDocumentationNavigationSiblings {
+  previous: string | undefined;
+  next: string | undefined;
+}
+
+@Injectable()
+export class AdkDocumentationConfigParser {
+  basePath: string;
+
+  /**
+   * This method takes a path from the application and a configuration object, and returns a path to a file that will be fetched.
+   *
+   * This assumes that the pathFromApp matches a path through the keys of the Nested Object.
+   *
+   * If the path is 'viz/content/items/bars', the config object might look like this:
+   * viz: {
+   *   content: {
+   *     items: {
+   *       bars: 'bars.md'
+   *     }
+   *   }
+   * }
+   *
+   * @param pathFromApp a string representing the path from the application, for example 'viz/content/items/bars'
+   * @param config a nested object representing the configuration
+   * @returns a string representing the file path
+   */
+  getPathToFile(
+    pathFromApp: string,
+    config: AdkNestedObject,
+    basePath: string
+  ): string {
+    const pathParts = pathFromApp.split('/');
+    const fileName = this.getFileNameFromPath(pathParts, config);
+    const pathToFile = basePath ? `${basePath}/${fileName}` : fileName;
+    return pathToFile;
+  }
+
+  /**
+   *
+   * @param pathParts a string array of path parts, for example ['viz', 'content', 'items', 'bars]
+   * @param config a nested object representing the configuration
+   * @returns a string representing the file name
+   */
+  private getFileNameFromPath(
+    pathParts: string[],
+    config: string | AdkNestedObject
+  ): string {
+    const fileName = pathParts.reduce((acc, part) => {
+      const level = acc[part];
+      acc = level;
+      return acc;
+    }, config);
+    return fileName as string;
+  }
+
+  findPreviousAndNextByPath(
+    obj: AdkNestedObject,
+    targetPath: string
+  ): AdkDocumentationNavigationSiblings {
+    const flatPaths = this.flattenObjectWithPath(obj);
+    const index = flatPaths.indexOf(targetPath);
+
+    if (index === -1) {
+      return { previous: undefined, next: undefined };
+    }
+
+    return {
+      previous: index > 0 ? flatPaths[index - 1] : undefined,
+      next: index < flatPaths.length - 1 ? flatPaths[index + 1] : undefined,
+    };
+  }
+
+  flattenObjectWithPath(obj: AdkNestedObject, prefix: string = ''): string[] {
+    let result: string[] = [];
+    for (const [key, value] of Object.entries(obj)) {
+      const newPath = prefix ? `${prefix}/${key}` : key;
+      if (typeof value === 'object' && value !== null) {
+        result = result.concat(this.flattenObjectWithPath(value, newPath));
+      } else {
+        result.push(newPath);
+      }
+    }
+    return result;
+  }
+}

package/src/lib/documentation-display/documentation-content-service.ts

@@ -0,0 +1,118 @@
+import { inject, Injectable } from '@angular/core';
+import { map, Observable, switchMap, withLatestFrom } from 'rxjs';
+import { AdkAssetResponse, AdkAssetsService } from '../assets/assets-service';
+import {
+  AdkMarkdownParser,
+  AdkMarkdownParsingOptions,
+  AdkParsedContentSection,
+} from '../content-parsing';
+import {
+  AdkDocumentationConfigParser,
+  AdkDocumentationNavigationSiblings,
+  AdkNestedObject,
+} from './documentation-config-parser';
+
+export interface AdkDocsConfig {
+  title: string;
+  items: AdkFilesConfig;
+}
+
+export interface AdkFilesConfig {
+  [key: string]: AdkFilesItem;
+}
+
+export type AdkFilesItem = string | null | AdkFilesConfig;
+
+export interface AdkParsedMarkdownFile<Content = string> {
+  sections: AdkParsedContentSection<Content>[];
+  headings: AdkHtmlHeader[];
+}
+
+export interface AdkParsedDocumentation<
+  Content = string,
+> extends AdkParsedMarkdownFile<Content> {
+  siblings: AdkDocumentationNavigationSiblings;
+}
+
+export interface AdkHtmlHeader {
+  id: string;
+  level: number; // starts at 1
+  text: string;
+}
+
+export interface AdkDocumentationContentOptions {
+  fileConfig: AdkNestedObject;
+  basePath: string;
+  parsingOptions?: AdkMarkdownParsingOptions;
+}
+
+@Injectable()
+export class AdkDocumentationContentService {
+  private files: {
+    [name: string]: Observable<AdkParsedContentSection[]>;
+  } = {};
+
+  private assetsService = inject(AdkAssetsService);
+  private docsConfigParser = inject(AdkDocumentationConfigParser);
+  private markdownParser = inject(AdkMarkdownParser);
+
+  /**
+   * This service requires the consuming app to provide the AdkDocumentationDisplayService, the AdkAssetsService, and the AdkDocumentationConfigParser at the level at which this service is configured.
+   *
+   * OPTIONAL: If the consuming app wants to use a different assets directory, they can pass it in here.
+   */
+  initialize(assetsDirectory?: string): void {
+    this.assetsService.setAssetsPath(assetsDirectory || 'assets/');
+  }
+
+  /**
+   * Assumes that the content path matches
+   */
+  getContentForCurrentContentPath(
+    contentPath$: Observable<string>,
+    options: AdkDocumentationContentOptions
+  ): Observable<AdkParsedDocumentation> {
+    return contentPath$.pipe(
+      switchMap((contentPath) => {
+        const pathToFile = this.docsConfigParser.getPathToFile(
+          contentPath,
+          options.fileConfig,
+          options.basePath
+        );
+        return this.getParsedMarkdownFile(pathToFile, options.parsingOptions);
+      }),
+      withLatestFrom(contentPath$),
+      map(([markdownSections, configPath]) => {
+        return {
+          sections: markdownSections,
+          headings: markdownSections.reduce((acc, section) => {
+            if (section.headers.length > 0) {
+              acc.push(...section.headers);
+            }
+            return acc;
+          }, [] as AdkHtmlHeader[]),
+          siblings: this.docsConfigParser.findPreviousAndNextByPath(
+            options.fileConfig,
+            configPath
+          ),
+        };
+      })
+    );
+  }
+
+  private getParsedMarkdownFile(
+    filePathFromAssets: string,
+    parsingOptions?: AdkMarkdownParsingOptions
+  ): Observable<AdkParsedContentSection[]> {
+    if (!this.files[filePathFromAssets]) {
+      this.files[filePathFromAssets] = this.assetsService
+        .getAsset(filePathFromAssets, AdkAssetResponse.Text)
+        .pipe(
+          switchMap((text) =>
+            this.markdownParser.parse(text as string, parsingOptions)
+          )
+        );
+    }
+    return this.files[filePathFromAssets];
+  }
+}

package/src/lib/documentation-display/documentation-display.component.html

@@ -0,0 +1,33 @@
+<div class="documentation-container" #file>
+  @if (content$ | async; as content) {
+    <div class="documentation-content">
+      <div class="main-content">
+        @for (section of content.sections; track $index) {
+          @if (section.type === 'markdown') {
+            <div class="injected-html" [innerHTML]="section.html"></div>
+          } @else if (section.type === 'escaped') {
+            @if (escapedContentTemplateRef) {
+              <ng-container
+                [ngTemplateOutlet]="escapedContentTemplateRef"
+                [ngTemplateOutletContext]="{ $implicit: section }"
+              >
+              </ng-container>
+            }
+          }
+        }
+        @if (showPrevNextNavigation) {
+          <hsi-adk-navigation-siblings
+            class="nav-siblings"
+            [siblings]="content.siblings"
+            (nextDoc)="navigateToDoc($event)"
+          ></hsi-adk-navigation-siblings>
+        }
+      </div>
+      <hsi-adk-document-index
+        class="document-index"
+        [headings]="content.headings.slice(1)"
+        (activeHeading)="scrollToHeading($event)"
+      ></hsi-adk-document-index>
+    </div>
+  }
+</div>