@difizen/libro-common 0.3.4 → 1.0.0

package/src/core/view/focus-tracker.ts

@@ -0,0 +1,363 @@
+import type { Disposable, Event as EmitterEvent } from '../../common/index.js';
+import { Iterable } from '../../common/index.js';
+import { Emitter } from '../../common/index.js';
+import { singleton } from '../../ioc/index.js';
+
+import type { View } from './view-protocol';
+
+/**
+ * A class which tracks focus among a set of views.
+ *
+ * This class is useful when code needs to keep track of the most
+ * recently focused view(s) among a set of related views.
+ */
+@singleton()
+export class FocusTracker<T extends View> implements Disposable {
+  protected counter = 0;
+  protected _views: T[] = [];
+  protected _activeView: T | null = null;
+  protected _currentView: T | null = null;
+  protected numbers = new Map<T, number>();
+  protected nodes = new Map<HTMLElement, T>();
+  protected activeChangedEmitter = new Emitter<FocusTracker.IChangedArgs<T>>();
+  protected currentChangedEmitter = new Emitter<FocusTracker.IChangedArgs<T>>();
+
+  /**
+   * A signal emitted when the current view has changed.
+   */
+  get currentChanged(): EmitterEvent<FocusTracker.IChangedArgs<T>> {
+    return this.currentChangedEmitter.event;
+  }
+
+  /**
+   * A signal emitted when the active view has changed.
+   */
+  get activeChanged(): EmitterEvent<FocusTracker.IChangedArgs<T>> {
+    return this.activeChangedEmitter.event;
+  }
+
+  /**
+   * A flag indicating whether the tracker is disposed.
+   */
+  get isDisposed(): boolean {
+    return this.counter < 0;
+  }
+
+  /**
+   * The current view in the tracker.
+   *
+   * #### Notes
+   * The current view is the view among the tracked views which
+   * has the *descendant node* which has most recently been focused.
+   *
+   * The current view will not be updated if the node loses focus. It
+   * will only be updated when a different tracked view gains focus.
+   *
+   * If the current view is removed from the tracker, the previous
+   * current view will be restored.
+   *
+   * This behavior is intended to follow a user's conceptual model of
+   * a semantically "current" view, where the "last thing of type X"
+   * to be interacted with is the "current instance of X", regardless
+   * of whether that instance still has focus.
+   */
+  get currentView(): T | null {
+    return this._currentView;
+  }
+
+  /**
+   * The active view in the tracker.
+   *
+   * #### Notes
+   * The active view is the view among the tracked views which
+   * has the *descendant node* which is currently focused.
+   */
+  get activeView(): T | null {
+    return this._activeView;
+  }
+
+  /**
+   * A read only array of the views being tracked.
+   */
+  get views(): readonly T[] {
+    return this._views;
+  }
+
+  /**
+   * Dispose of the resources held by the tracker.
+   */
+  dispose(): void {
+    // Do nothing if the tracker is already disposed.
+    if (this.counter < 0) {
+      return;
+    }
+
+    // Mark the tracker as disposed.
+    this.counter = -1;
+
+    // Clear the listeners for the tracker.
+    this.activeChangedEmitter.dispose();
+    this.currentChangedEmitter.dispose();
+
+    // Remove all event listeners.
+    this._views.forEach((view) => {
+      view.container?.current?.removeEventListener('focus', this, true);
+      view.container?.current?.removeEventListener('blur', this, true);
+    });
+
+    // Clear the internal data structures.
+    this._activeView = null;
+    this._currentView = null;
+    this.nodes.clear();
+    this.numbers.clear();
+    this._views.length = 0;
+  }
+
+  /**
+   * Get the focus number for a particular view in the tracker.
+   *
+   * @param view - The view of interest.
+   *
+   * @returns The focus number for the given view, or `-1` if the
+   *   view has not had focus since being added to the tracker, or
+   *   is not contained by the tracker.
+   *
+   * #### Notes
+   * The focus number indicates the relative order in which the views
+   * have gained focus. A view with a larger number has gained focus
+   * more recently than a view with a smaller number.
+   *
+   * The `currentView` will always have the largest focus number.
+   *
+   * All views start with a focus number of `-1`, which indicates that
+   * the view has not been focused since being added to the tracker.
+   */
+  focusNumber(view: T): number {
+    const n = this.numbers.get(view);
+    return n === undefined ? -1 : n;
+  }
+
+  /**
+   * Test whether the focus tracker contains a given view.
+   *
+   * @param view - The view of interest.
+   *
+   * @returns `true` if the view is tracked, `false` otherwise.
+   */
+  has(view: T): boolean {
+    return this.numbers.has(view);
+  }
+
+  /**
+   * Add a view to the focus tracker.
+   *
+   * @param view - The view of interest.
+   *
+   * #### Notes
+   * A view will be automatically removed from the tracker if it
+   * is disposed after being added.
+   *
+   * If the view is already tracked, this is a no-op.
+   */
+  add(view: T): void {
+    // Do nothing if the view is already tracked.
+    if (this.numbers.has(view)) {
+      return;
+    }
+
+    // Test whether the view has focus.
+    const focused = view.container?.current?.contains(document.activeElement);
+
+    // Set up the initial focus number.
+    const n = focused ? this.counter++ : -1;
+
+    // Add the view to the internal data structures.
+    this._views.push(view);
+    this.numbers.set(view, n);
+    if (view.container?.current) {
+      this.nodes.set(view.container?.current, view);
+    }
+
+    // Set up the event listeners. The capturing phase must be used
+    // since the 'focus' and 'blur' events don't bubble and Firefox
+    // doesn't support the 'focusin' or 'focusout' events.
+    view.container?.current?.addEventListener('focus', this, true);
+    view.container?.current?.addEventListener('blur', this, true);
+
+    // Connect the disposed signal handler.
+    view.onDisposed(() => this.onViewDisposed);
+
+    // Set the current and active views if needed.
+    if (focused) {
+      this.setViews(view, view);
+    }
+  }
+
+  /**
+   * Remove a view from the focus tracker.
+   *
+   * #### Notes
+   * If the view is the `currentView`, the previous current view
+   * will become the new `currentView`.
+   *
+   * A view will be automatically removed from the tracker if it
+   * is disposed after being added.
+   *
+   * If the view is not tracked, this is a no-op.
+   */
+  remove(view: T): void {
+    // Bail early if the view is not tracked.
+    if (!this.numbers.has(view)) {
+      return;
+    }
+
+    // Disconnect the disposed signal handler.
+    // view.disposed.disconnect(this.onViewDisposed, this);
+
+    // Remove the event listeners.
+    view.container?.current?.removeEventListener('focus', this, true);
+    view.container?.current?.removeEventListener('blur', this, true);
+
+    // Remove the view from the internal data structures.
+    this._views.splice(this._views.indexOf(view), 1);
+
+    if (view.container?.current) {
+      this.nodes.delete(view.container?.current);
+    }
+    this.numbers.delete(view);
+
+    // Bail early if the view is not the current view.
+    if (this._currentView !== view) {
+      return;
+    }
+
+    // Filter the views for those which have had focus.
+    const valid = this._views.filter((w) => this.numbers.get(w) !== -1);
+
+    // Get the valid view with the max focus number.
+    const previous =
+      Iterable.max(valid, (first, second) => {
+        const a = this.numbers.get(first)!;
+        const b = this.numbers.get(second)!;
+        return a - b;
+      }) || null;
+
+    // Set the current and active views.
+    this.setViews(previous, null);
+  }
+
+  /**
+   * Handle the DOM events for the focus tracker.
+   *
+   * @param event - The DOM event sent to the panel.
+   *
+   * #### Notes
+   * This method implements the DOM `EventListener` interface and is
+   * called in response to events on the tracked nodes. It should
+   * not be called directly by user code.
+   */
+  handleEvent(event: Event): void {
+    switch (event.type) {
+      case 'focus':
+        this.handleFocusEvent(event as FocusEvent);
+        break;
+      case 'blur':
+        this.handleBlurEvent(event as FocusEvent);
+        break;
+    }
+  }
+
+  /**
+   * Set the current and active views for the tracker.
+   */
+  protected setViews(current: T | null, active: T | null): void {
+    // Swap the current view.
+    const oldCurrent = this._currentView;
+    this._currentView = current;
+
+    // Swap the active view.
+    const oldActive = this._activeView;
+    this._activeView = active;
+
+    // Emit the `currentChanged` signal if needed.
+    if (oldCurrent !== current) {
+      this.currentChangedEmitter.fire({ oldValue: oldCurrent, newValue: current });
+    }
+
+    // Emit the `activeChanged` signal if needed.
+    if (oldActive !== active) {
+      this.activeChangedEmitter.fire({ oldValue: oldActive, newValue: active });
+    }
+  }
+
+  /**
+   * Handle the `'focus'` event for a tracked view.
+   */
+  protected handleFocusEvent(event: FocusEvent): void {
+    // Find the view which gained focus, which is known to exist.
+    const view = this.nodes.get(event.currentTarget as HTMLElement)!;
+
+    // Update the focus number if necessary.
+    if (view !== this._currentView) {
+      this.numbers.set(view, this.counter++);
+    }
+
+    // Set the current and active views.
+    this.setViews(view, view);
+  }
+
+  /**
+   * Handle the `'blur'` event for a tracked view.
+   */
+  protected handleBlurEvent(event: FocusEvent): void {
+    // Find the view which lost focus, which is known to exist.
+    const view = this.nodes.get(event.currentTarget as HTMLElement)!;
+
+    // Get the node which being focused after this blur.
+    const focusTarget = event.relatedTarget as HTMLElement;
+
+    // If no other node is being focused, clear the active view.
+    if (!focusTarget) {
+      this.setViews(this._currentView, null);
+      return;
+    }
+
+    // Bail if the focus view is not changing.
+    if (view.container?.current?.contains(focusTarget)) {
+      return;
+    }
+
+    // If no tracked view is being focused, clear the active view.
+    if (!this._views.find((v) => v.container?.current?.contains(focusTarget))) {
+      this.setViews(this._currentView, null);
+      return;
+    }
+  }
+
+  /**
+   * Handle the `disposed` signal for a tracked view.
+   */
+  protected onViewDisposed(sender: T): void {
+    this.remove(sender);
+  }
+}
+
+/**
+ * The namespace for the `FocusTracker` class statics.
+ */
+export namespace FocusTracker {
+  /**
+   * An arguments object for the changed signals.
+   */
+  export interface IChangedArgs<T extends View> {
+    /**
+     * The old value for the view.
+     */
+    oldValue: T | null;
+
+    /**
+     * The new value for the view.
+     */
+    newValue: T | null;
+  }
+}

package/src/core/view/hooks.tsx

@@ -0,0 +1,40 @@
+import { useLayoutEffect } from 'react';
+import ResizeObserver from 'resize-observer-polyfill';
+
+import { useLatest } from '../utils/index';
+
+import type { View } from './view-protocol';
+
+export type Size = { width?: number; height?: number };
+
+export function useViewSize(view: View, ref: React.ForwardedRef<HTMLDivElement>): void {
+  const callback = useLatest((size: Size) => {
+    view.onViewResize?.(size);
+  });
+  useLayoutEffect(() => {
+    if (typeof ref !== 'object') {
+      return () => {
+        //
+      };
+    }
+    const el = ref?.current;
+    if (!el || !view.onViewResize) {
+      return () => {
+        //
+      };
+    }
+    const resizeObserver = new ResizeObserver((entries) => {
+      entries.forEach((entry) => {
+        callback.current({
+          width: entry.target.clientWidth,
+          height: entry.target.clientHeight,
+        });
+      });
+    });
+
+    resizeObserver.observe(el as HTMLElement);
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, [callback, ref, view.container, view.onViewResize]);
+}

package/src/core/view/index.less

@@ -0,0 +1,4 @@
+.mana-view-container {
+  position: relative;
+  height: 100%;
+}

package/src/core/view/index.ts

@@ -0,0 +1,22 @@
+export * from './module';
+export * from './view-protocol';
+export * from './view-manager';
+export * from './slot-view-manager';
+export * from './default-slot-view';
+export * from './default-view';
+export * from './slot';
+export * from './decorator';
+export * from './view-decoration';
+export * from './open-handler';
+export * from './view-open-handler';
+export * from './navigatable';
+export * from './navigatable-types';
+export * from './saveable';
+export * from './view-application';
+export * from './view-context';
+export * from './view-render';
+export * from './view-decoration';
+export * from './view-storage';
+export * from './stateful-view';
+export * from './utils';
+export * from './hooks';

package/src/core/view/module.ts

@@ -0,0 +1,41 @@
+import { ManaModule } from '../module';
+
+import { DefaultSlotView } from './default-slot-view';
+import { DefaultOpenerService, OpenHandler } from './open-handler';
+import { RootComponents, RootView } from './root-view';
+import { SlotViewManager } from './slot-view-manager';
+import { ViewApplication } from './view-application';
+import { ViewManager } from './view-manager';
+import { ViewOpenHandler } from './view-open-handler';
+import { ViewInstance, ViewPreferenceContribution } from './view-protocol';
+import { ViewFactory } from './view-protocol';
+import { SlotPreferenceContribution } from './view-protocol';
+import { ViewStorage } from './view-storage';
+
+export const ViewModule = ManaModule.create()
+  .contribution(
+    ViewFactory,
+    ViewPreferenceContribution,
+    SlotPreferenceContribution,
+    OpenHandler,
+  )
+  .register(
+    RootView,
+    DefaultSlotView,
+    ViewStorage,
+    ViewApplication,
+    SlotViewManager,
+    ViewManager,
+    DefaultOpenerService,
+    ViewOpenHandler,
+  )
+  // register top level ViewInstance
+  // TODO: remove this when we have a better way to register top level ViewInstance
+  .register({
+    token: ViewInstance,
+    useValue: {},
+  })
+  .register({
+    token: RootComponents,
+    useValue: {},
+  });

package/src/core/view/navigatable-types.ts

@@ -0,0 +1,49 @@
+import type { URI } from '../../common/index.js';
+
+import { BaseView } from './default-view';
+import type { View } from './view-protocol';
+
+/**
+ * `Navigatable` provides an access to an URI of an underlying instance of `Resource`.
+ */
+export interface Navigatable {
+  /**
+   * Return an underlying resource URI.
+   */
+  getResourceUri: () => URI | undefined;
+  /**
+   * Creates a new URI to which this navigatable should moved based on the given target resource URI.
+   */
+  createMoveToUri: (resourceUri: URI) => URI | undefined;
+}
+
+export namespace Navigatable {
+  export function is(arg: Record<any, any> | undefined): arg is Navigatable {
+    return !!arg && 'getResourceUri' in arg && 'createMoveToUri' in arg;
+  }
+}
+
+export type NavigatableView = BaseView & Navigatable;
+export namespace NavigatableView {
+  export function is(arg: Record<any, any> | undefined): arg is NavigatableView {
+    return arg instanceof BaseView && Navigatable.is(arg);
+  }
+  export function getUri(widget?: View): URI | undefined {
+    if (is(widget)) {
+      return widget.getResourceUri();
+    }
+    return undefined;
+  }
+}
+
+export interface NavigatableViewOptions {
+  kind: 'navigatable';
+  uri: string;
+  counter?: number;
+}
+export namespace NavigatableWidgetOptions {
+  export function is(arg: Record<any, any> | undefined): arg is NavigatableViewOptions {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return !!arg && 'kind' in arg && (arg as any).kind === 'navigatable';
+  }
+}

package/src/core/view/navigatable.ts

@@ -0,0 +1,29 @@
+import { URI } from '../../common/index.js';
+
+import type { NavigatableView, NavigatableViewOptions } from './navigatable-types';
+import type { ViewOpenHandlerOptions } from './view-open-handler';
+import { ViewOpenHandler } from './view-open-handler';
+
+export abstract class NavigatableViewOpenHandler<
+  W extends NavigatableView,
+> extends ViewOpenHandler<W> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  protected createViewOptions(
+    uri: URI,
+    options?: ViewOpenHandlerOptions,
+  ): NavigatableViewOptions {
+    return {
+      kind: 'navigatable',
+      uri: this.serializeUri(uri),
+      ...options?.viewOptions,
+    };
+  }
+
+  protected serializeUri(uri: URI): string {
+    if (uri.scheme === 'file') {
+      return URI.withFragment(uri).normalizePath().toString();
+    } else {
+      return URI.withFragment(uri).toString();
+    }
+  }
+}

package/src/core/view/open-handler.ts

@@ -0,0 +1,122 @@
+import type { MaybePromise, Event, Disposable, URI } from '../../common/index.js';
+import { Priority } from '../../common/index.js';
+import type { Contribution } from '../../ioc/index.js';
+import { singleton, contrib, Syringe } from '../../ioc/index.js';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface OpenerOptions {}
+
+export const OpenHandler = Syringe.defineToken('OpenHandler');
+/**
+ * `OpenHandler` should be implemented to provide a new opener.
+ */
+export interface OpenHandler {
+  /**
+   * A unique id of this handler.
+   */
+  readonly id: string;
+  /**
+   * A human-readable name of this handler.
+   */
+  readonly label?: string;
+  /**
+   * A css icon class of this handler.
+   */
+  readonly iconClass?: string;
+  /**
+   * Test whether this handler can open the given resource for given options.
+   * Return a nonzero number if this handler can open; otherwise it cannot.
+   * Never reject.
+   *
+   * A returned value indicating a priority of this handler.
+   */
+  canHandle: (resource: URI, options?: OpenerOptions) => MaybePromise<number>;
+  /**
+   * Open a widget for the given resource and options.
+   * Resolve to an opened widget or undefined, e.g. if a page is opened.
+   * Never reject if `canHandle` return a positive number; otherwise should reject.
+   */
+  open: (
+    resource: URI,
+    options?: OpenerOptions,
+  ) => MaybePromise<Record<any, any> | undefined>;
+}
+
+export const OpenerService = Symbol('OpenerService');
+/**
+ * `OpenerService` provide an access to existing openers.
+ */
+export interface OpenerService {
+  /**
+   * Return all registered openers.
+   * Never reject.
+   */
+  getOpeners: (() => Promise<OpenHandler[]>) &
+    ((resource: URI, options?: OpenerOptions) => Promise<OpenHandler[]>);
+  /**
+   * Return an opener with the higher priority for the given resource.
+   * Reject if such does not exist.
+   */
+  getOpener: (resource: URI, options?: OpenerOptions) => Promise<OpenHandler>;
+  /**
+   * Add open handler i.e. for custom editors
+   */
+  addHandler?: (openHandler: OpenHandler) => Disposable;
+  /**
+   * Event that fires when a new opener is added or removed.
+   */
+  onDidChangeOpeners?: Event<void>;
+}
+
+export async function open(
+  openerService: OpenerService,
+  resource: URI,
+  options?: OpenerOptions,
+): Promise<Record<string, any> | undefined> {
+  const opener = await openerService.getOpener(resource, options);
+  return opener.open(resource, options);
+}
+
+@singleton({ contrib: OpenerService })
+export class DefaultOpenerService implements OpenerService {
+  protected readonly handlersProvider: Contribution.Provider<OpenHandler>;
+
+  constructor(
+    @contrib(OpenHandler)
+    handlersProvider: Contribution.Provider<OpenHandler>,
+  ) {
+    this.handlersProvider = handlersProvider;
+  }
+
+  async getOpener(resource: URI, options?: OpenerOptions): Promise<OpenHandler> {
+    const handlers = await this.prioritize(resource, options);
+    if (handlers.length >= 1) {
+      return handlers[0];
+    }
+    return Promise.reject(
+      new Error(`There is no opener for resource: ${resource.toString()}.`),
+    );
+  }
+
+  async getOpeners(resource?: URI, options?: OpenerOptions): Promise<OpenHandler[]> {
+    return resource ? this.prioritize(resource, options) : this.getHandlers();
+  }
+
+  protected async prioritize(
+    resource: URI,
+    options?: OpenerOptions,
+  ): Promise<OpenHandler[]> {
+    const prioritized = await Priority.sort(this.getHandlers(), async (handler) => {
+      try {
+        return await handler.canHandle(resource, options);
+      } catch {
+        return 0;
+      }
+    });
+    return prioritized.map((p) => p.value);
+  }
+
+  protected getHandlers(): OpenHandler[] {
+    return [...this.handlersProvider.getContributions()];
+  }
+}