@difizen/libro-common 0.3.4 → 1.0.0

package/src/app/tree/tree-view-decoration.ts

@@ -0,0 +1,349 @@
+export const TreeViewDecorationStyles = {
+  CAPTION_HIGHLIGHT_CLASS: 'mana-caption-highlight',
+  CAPTION_PREFIX_CLASS: 'mana-caption-prefix',
+  CAPTION_SUFFIX_CLASS: 'mana-caption-suffix',
+  ICON_WRAPPER_CLASS: 'mana-icon-wrapper',
+  DECORATOR_SIZE_CLASS: 'mana-decorator-size',
+  DECORATOR_SIDEBAR_SIZE_CLASS: 'mana-decorator-sidebar-size',
+  TOP_RIGHT_CLASS: 'mana-top-right',
+  BOTTOM_RIGHT_CLASS: 'mana-bottom-right',
+  BOTTOM_RIGHT_SIDEBAR_CLASS: 'mana-bottom-right-sidebar',
+  BOTTOM_LEFT_CLASS: 'mana-bottom-left',
+  TOP_LEFT_CLASS: 'mana-top-left',
+};
+/**
+ * Enumeration for the quadrant to overlay the image on.
+ */
+export enum IconOverlayPosition {
+  /**
+   * Overlays the top right quarter of the original image.
+   */
+  TOP_RIGHT,
+  /**
+   * Overlays the bottom right of the original image.
+   */
+  BOTTOM_RIGHT,
+  /**
+   * Overlays the bottom left segment of the original image.
+   */
+  BOTTOM_LEFT,
+  /**
+   * Occupies the top left quarter of the original icon.
+   */
+  TOP_LEFT,
+}
+
+export namespace IconOverlayPosition {
+  /**
+   * Returns with the CSS class style for the enum.
+   */
+  export function getStyle(position: IconOverlayPosition, inSideBar?: boolean): string {
+    switch (position) {
+      case IconOverlayPosition.TOP_RIGHT:
+        return TreeViewDecorationStyles.TOP_RIGHT_CLASS;
+      case IconOverlayPosition.BOTTOM_RIGHT:
+        return inSideBar
+          ? TreeViewDecorationStyles.BOTTOM_RIGHT_SIDEBAR_CLASS
+          : TreeViewDecorationStyles.BOTTOM_RIGHT_CLASS;
+      case IconOverlayPosition.BOTTOM_LEFT:
+        return TreeViewDecorationStyles.BOTTOM_LEFT_CLASS;
+      case IconOverlayPosition.TOP_LEFT:
+        return TreeViewDecorationStyles.TOP_LEFT_CLASS;
+      default:
+        return '';
+    }
+  }
+}
+
+export namespace CaptionHighlight {
+  /**
+   * A pair of offset and length that has to be highlighted as a range.
+   */
+  export type Range = {
+    /**
+     * Zero based offset of the highlighted region.
+     */
+    readonly offset: number;
+    /**
+     * The length of the highlighted region.
+     */
+    readonly length: number;
+  };
+  export namespace Range {
+    /**
+     * `true` if the `arg` is contained in the range. The ranges are closed ranges, hence the check is inclusive.
+     */
+    export function contains(arg: number, range: Range): boolean {
+      return arg >= range.offset && arg <= range.offset + range.length;
+    }
+  }
+  /**
+   * The result of a caption splitting based on the highlighting information.
+   */
+  export type Fragment = {
+    /**
+     * The text data of the fragment.
+     */
+    readonly data: string;
+    /**
+     * Has to be highlighted if defined.
+     */
+    readonly highlight?: true;
+  };
+  /**
+   * Splits the `caption` argument based on the ranges from the `highlight` argument.
+   */
+  export function split(caption: string, highlight: CaptionHighlight): Fragment[] {
+    const result: Fragment[] = [];
+    const ranges = highlight.ranges.slice();
+    const containerOf = (index: number) =>
+      ranges.findIndex((range) => Range.contains(index, range));
+    let data = '';
+    for (let i = 0; i < caption.length; i += 1) {
+      const containerIndex = containerOf(i);
+      if (containerIndex === -1) {
+        data += caption[i];
+      } else {
+        if (data.length > 0) {
+          result.push({ data });
+        }
+        const { length } = ranges.splice(containerIndex, 1).shift()!;
+        result.push({ data: caption.substr(i, length), highlight: true });
+        data = '';
+        i = i + length - 1;
+      }
+    }
+    if (data.length > 0) {
+      result.push({ data });
+    }
+    if (ranges.length !== 0) {
+      throw new Error(
+        'Error occurred when splitting the caption. There was a mismatch between the caption and the corresponding highlighting ranges.',
+      );
+    }
+    return result;
+  }
+}
+/**
+ * The caption highlighting with the highlighted ranges and an optional background color.
+ */
+export type CaptionHighlight = {
+  /**
+   * The ranges to highlight in the caption.
+   */
+  readonly ranges: CaptionHighlight.Range[];
+  /**
+   * The optional color of the text data that is being highlighted. Falls back to the default `mark` color values defined under a widget segment class.
+   */
+  readonly color?: TreeViewDecoration.Color;
+  /**
+   * The optional background color of the text data that is being highlighted.
+   */
+  readonly backgroundColor?: TreeViewDecoration.Color;
+};
+/**
+ * Namespace for the decoration data and the styling refinements for the decorated widgets.
+ */
+export namespace TreeViewDecoration {
+  /**
+   * For the sake of simplicity, we have merged the `font-style`, `font-weight`, and the `text-decoration` together.
+   */
+  export type FontStyle =
+    | 'normal'
+    | 'bold'
+    | 'italic'
+    | 'oblique'
+    | 'underline'
+    | 'line-through';
+  /**
+   * A string that could be:
+   *
+   *  - one of the browser colors, (E.g.: `blue`, `red`, `magenta`),
+   *  - the case insensitive hexadecimal color code, (for instance, `#ee82ee`, `#20B2AA`, `#f09` ), or
+   *  - either the `rgb()` or the `rgba()` functions.
+   *
+   * For more details, see: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value.
+   *
+   * Note, it is highly recommended to use one of the predefined colors of Mana, so the desired color will
+   * look nice with both the `light` and the `dark` theme too.
+   */
+  export type Color = string;
+  /**
+   * Encapsulates styling information of the font.
+   */
+  export type FontData = {
+    /**
+     * Zero to any font style.
+     */
+    readonly style?: FontStyle | FontStyle[];
+    /**
+     * The color of the font.
+     */
+    readonly color?: Color;
+  };
+  /**
+   * Arbitrary information that has to be shown either before or after the caption as a prefix or a suffix.
+   */
+  export type CaptionAffix = {
+    /**
+     * The text content of the prefix or the suffix.
+     */
+    readonly data: string;
+    /**
+     * Font data for customizing the prefix of the suffix.
+     */
+    readonly fontData?: FontData;
+  };
+  export type BaseTailDecoration = {
+    /**
+     * Optional tooltip for the tail decoration.
+     */
+    readonly tooltip?: string;
+  };
+  /**
+   * Unlike caption suffixes, tail decorations appears right-aligned after the caption and the caption suffixes (is any).
+   */
+  export type TailDecoration = {
+    /**
+     * The text content of the tail decoration.
+     */
+    readonly data: string;
+    /**
+     * Font data for customizing the content.
+     */
+    readonly fontData?: FontData;
+  } & BaseTailDecoration;
+  export type TailDecorationIcon = {
+    /**
+     * This should be the name of the Font Awesome icon with out the `fa fa-` prefix, just the name, for instance `paw`.
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly icon: string;
+    /**
+     * The color of the icon.
+     */
+    readonly color?: Color;
+  } & BaseTailDecoration;
+  export type TailDecorationIconClass = {
+    /**
+     * This should be the entire Font Awesome class array, for instance ['fa', 'fa-paw']
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly iconClass: string[];
+    /**
+     * The color of the icon.
+     */
+    readonly color?: Color;
+  } & BaseTailDecoration;
+
+  /**
+   * A shape that can be optionally rendered behind the overlay icon. Can be used to further refine colors.
+   */
+  export type IconOverlayBackground = {
+    /**
+     * Either `circle` or `square`.
+     */
+    readonly shape: 'circle' | 'square';
+    /**
+     * The color of the background shape.
+     */
+    readonly color?: Color;
+  };
+  /**
+   * Has not effect if the widget being decorated has no associated icon.
+   */
+  export type BaseOverlay = {
+    /**
+     * The position where the decoration will be placed on the top of the original icon.
+     */
+    readonly position: IconOverlayPosition;
+    /**
+     * The color of the overlaying icon. If not specified, then the default icon color will be used.
+     */
+    readonly color?: Color;
+    /**
+     * The optional background color of the overlay icon.
+     */
+    readonly background?: IconOverlayBackground;
+  };
+  export type IconOverlay = {
+    /**
+     * This should be the name of the Font Awesome icon with out the `fa fa-` prefix, just the name, for instance `paw`.
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly icon: string;
+  } & BaseOverlay;
+  export type IconClassOverlay = {
+    /**
+     * This should be the entire Font Awesome class array, for instance ['fa', 'fa-paw']
+     * For the existing icons, see here: https://fontawesome.com/v4.7.0/icons/.
+     */
+    readonly iconClass: string[];
+  } & BaseOverlay;
+}
+/**
+ * Encapsulates styling information that has to be applied on the widget which we decorate.
+ */
+export type TreeViewDecorationData = {
+  /**
+   * The higher number has higher priority. If not specified, treated as `0`.
+   * When multiple decorators are available for the same item, and decoration data cannot be merged together,
+   * then the higher priority item will be applied on the decorated element and the lower priority will be ignored.
+   */
+  readonly priority?: number;
+  /**
+   * The font data for the caption.
+   */
+  readonly fontData?: TreeViewDecoration.FontData;
+  /**
+   * The background color of the entire row.
+   */
+  readonly backgroundColor?: TreeViewDecoration.Color;
+  /**
+   * Optional, leading prefixes right before the caption.
+   */
+  readonly captionPrefixes?: TreeViewDecoration.CaptionAffix[];
+  /**
+   * Suffixes that might come after the caption as an additional information.
+   */
+  readonly captionSuffixes?: TreeViewDecoration.CaptionAffix[];
+  /**
+   * Optional right-aligned decorations that appear after the widget caption and after the caption suffixes (is any).
+   */
+  readonly tailDecorations?: (
+    | TreeViewDecoration.TailDecoration
+    | TreeViewDecoration.TailDecorationIcon
+    | TreeViewDecoration.TailDecorationIconClass
+  )[];
+  /**
+   * Custom tooltip for the decorated item. Tooltip will be appended to the original tooltip, if any.
+   */
+  readonly tooltip?: string;
+  /**
+   * Sets the color of the icon. Ignored if the decorated item has no icon.
+   */
+  readonly iconColor?: TreeViewDecoration.Color;
+  /**
+   * Has not effect if given, but the widget does not have an associated image.
+   */
+  readonly iconOverlay?:
+    | TreeViewDecoration.IconOverlay
+    | TreeViewDecoration.IconClassOverlay;
+  /**
+   * An array of ranges to highlight the caption.
+   */
+  readonly highlight?: CaptionHighlight;
+  /**
+   * A count badge for widgets.
+   */
+  readonly badge?: number;
+};
+export namespace TreeViewDecorationData {
+  /**
+   * Compares the decoration data based on the priority. Lowest priorities come first.
+   */
+  export const comparePriority = (
+    left: TreeViewDecorationData,
+    right: TreeViewDecorationData,
+  ): number => (left.priority || 0) - (right.priority || 0);
+}

package/src/app/tree/tree.ts

@@ -0,0 +1,288 @@
+import type {
+  Event,
+  Disposable,
+  CancellationToken,
+  WaitUntilEvent,
+} from '../../common/index.js';
+
+import type { NodeProps, TreeProps } from './tree-protocol.js';
+
+export const Tree = Symbol('Tree');
+
+/**
+ * The tree - an abstract data type.
+ */
+export type Tree = {
+  /**
+   * A root node of this tree.
+   * Undefined if there is no root node.
+   * Setting a root node refreshes the tree.
+   */
+  root: TreeNode | undefined;
+  /**
+   * Emit when the tree is changed.
+   */
+  readonly onChanged: Event<void>;
+  /**
+   * Return a node for the given identifier or undefined if such does not exist.
+   */
+  getNode: (id: string | undefined) => TreeNode | undefined;
+  /**
+   * Return a valid node in this tree matching to the given; otherwise undefined.
+   */
+  validateNode: (node: TreeNode | undefined) => TreeNode | undefined;
+  /**
+   * Refresh children of the r../../../../examples/application-react/utils.
+   *
+   * Return a valid refreshed composite root or `undefined` if such does not exist.
+   */
+  refresh: (() => Promise<Readonly<CompositeTreeNode> | undefined>) &
+    ((
+      parent: Readonly<CompositeTreeNode>,
+    ) => Promise<Readonly<CompositeTreeNode> | undefined>);
+  /**
+   * Emit when the children of the given node are refreshed.
+   */
+  readonly onNodeRefreshed: Event<Readonly<CompositeTreeNode> & WaitUntilEvent>;
+  /**
+   * Emits when the busy state of the given node is changed.
+   */
+  readonly onDidChangeBusy: Event<TreeNode>;
+  /**
+   * Marks the give node as busy after a specified number of milliseconds.
+   * A token source of the given token should be canceled to unmark.
+   */
+  markAsBusy: (
+    node: Readonly<TreeNode>,
+    ms: number,
+    token: CancellationToken,
+  ) => Promise<void>;
+} & Disposable;
+
+/**
+ * The tree node.
+ */
+export type TreeNode = {
+  /**
+   * An unique id of this node.
+   */
+  readonly id: string;
+  readonly icon?: string;
+  readonly description?: string;
+  /**
+   * Test whether this node should be rendered.
+   * If undefined then node will be rendered.
+   */
+  readonly visible?: boolean;
+  /**
+   * A parent node of this tree node.
+   * Undefined if this node is root.
+   */
+  readonly parent: Readonly<CompositeTreeNode> | undefined;
+  /**
+   * A previous sibling of this tree node.
+   */
+  readonly previousSibling?: TreeNode;
+  /**
+   * A next sibling of this tree node.
+   */
+  readonly nextSibling?: TreeNode;
+  /**
+   * Whether this node is busy. Greater than 0 then busy; otherwise not.
+   */
+  readonly busy?: number;
+
+  readonly name?: string;
+};
+
+export namespace TreeNode {
+  export function is(node: Record<any, any> | undefined): node is TreeNode {
+    return !!node && typeof node === 'object' && 'id' in node && 'parent' in node;
+  }
+
+  export function equals(
+    left: TreeNode | undefined,
+    right: TreeNode | undefined,
+  ): boolean {
+    return left === right || (!!left && !!right && left.id === right.id);
+  }
+
+  export function isVisible(node: TreeNode | undefined): boolean {
+    return !!node && (node.visible === undefined || node.visible);
+  }
+}
+
+/**
+ * The composite tree node.
+ */
+export type CompositeTreeNode = {
+  /**
+   * Child nodes of this tree node.
+   */
+  children: readonly TreeNode[];
+} & TreeNode;
+
+export namespace CompositeTreeNode {
+  export function is(node: Record<any, any> | undefined): node is CompositeTreeNode {
+    return !!node && 'children' in node;
+  }
+
+  export function getFirstChild(parent: CompositeTreeNode): TreeNode | undefined {
+    return parent.children[0];
+  }
+
+  export function getLastChild(parent: CompositeTreeNode): TreeNode | undefined {
+    return parent.children[parent.children.length - 1];
+  }
+
+  export function isAncestor(
+    parent: CompositeTreeNode,
+    child: TreeNode | undefined,
+  ): boolean {
+    if (!child) {
+      return false;
+    }
+    if (TreeNode.equals(parent, child.parent)) {
+      return true;
+    }
+    return isAncestor(parent, child.parent);
+  }
+
+  export function indexOf(
+    parent: CompositeTreeNode,
+    node: TreeNode | undefined,
+  ): number {
+    if (!node) {
+      return -1;
+    }
+    return parent.children.findIndex((child) => TreeNode.equals(node, child));
+  }
+
+  export function addChildren(
+    parent: CompositeTreeNode,
+    children: TreeNode[],
+  ): CompositeTreeNode {
+    for (const child of children) {
+      addChild(parent, child);
+    }
+    return parent;
+  }
+
+  export function addChild(
+    parent: CompositeTreeNode,
+    child: TreeNode,
+  ): CompositeTreeNode {
+    const children = parent.children as TreeNode[];
+    const index = children.findIndex((value) => value.id === child.id);
+    if (index !== -1) {
+      children.splice(index, 1, child);
+      setParent(child, index, parent);
+    } else {
+      children.push(child);
+      setParent(child, parent.children.length - 1, parent);
+    }
+    return parent;
+  }
+
+  export function removeChild(parent: CompositeTreeNode, child: TreeNode): void {
+    const children = parent.children as TreeNode[];
+    const index = children.findIndex((value) => value.id === child.id);
+    if (index === -1) {
+      return;
+    }
+    children.splice(index, 1);
+    const { previousSibling, nextSibling } = child;
+    if (previousSibling) {
+      Object.assign(previousSibling, { nextSibling });
+    }
+    if (nextSibling) {
+      Object.assign(nextSibling, { previousSibling });
+    }
+  }
+
+  export function setParent(
+    child: TreeNode,
+    index: number,
+    parent: CompositeTreeNode,
+  ): void {
+    const previousSibling = parent.children[index - 1];
+    const nextSibling = parent.children[index + 1];
+    Object.assign(child, { parent, previousSibling, nextSibling });
+    if (previousSibling) {
+      Object.assign(previousSibling, { nextSibling: child });
+    }
+    if (nextSibling) {
+      Object.assign(nextSibling, { previousSibling: child });
+    }
+  }
+}
+
+/**
+ * Representation of a tree node row.
+ */
+export type NodeRow = {
+  /**
+   * The node row index.
+   */
+  index: number;
+  /**
+   * The actual node.
+   */
+  node: TreeNode;
+  /**
+   * A root relative number representing the hierarchical depth of the actual node. Root is `0`, its children have `1` and so on.
+   */
+  depth: number;
+};
+
+export interface TreeNodeProps {
+  node: TreeNode;
+  nodeProps: NodeProps;
+}
+
+export interface TreeNodeCaptionAffixesProps extends TreeNodeProps {
+  affixKey: 'captionPrefixes' | 'captionSuffixes';
+}
+
+export interface TreeNodeIconDecoratorProps extends TreeNodeProps {
+  icon: React.ReactNode;
+}
+
+export interface TreeNodeComponents {
+  TreeNodeExpansion: React.FC<TreeNodeProps>;
+  TreeNode: React.FC<TreeNodeProps>;
+  TreeNodeIcon: React.FC<TreeNodeProps>;
+  TreeNodeCaption: React.FC<TreeNodeProps>;
+  TreeNodeCaptionAffixes: React.FC<TreeNodeCaptionAffixesProps>;
+  TreeNodeTailDecorations: React.FC<TreeNodeProps>;
+  TreeNodeIconDecorator: React.FC<TreeNodeIconDecoratorProps>;
+  TreeIdent: React.FC<TreeNodeProps>;
+  TreeSwitchIcon: React.FC<TreeNodeProps>;
+}
+export const TreeNodeComponents = Symbol('TreeNodeComponents');
+
+/**
+ * Bare minimum common interface of the keyboard and the mouse event with respect to the key maskings.
+ */
+export type ModifierAwareEvent = {
+  /**
+   * Determines if the modifier aware event has the `meta` key masking.
+   */
+  readonly metaKey: boolean;
+  /**
+   * Determines if the modifier aware event has the `ctrl` key masking.
+   */
+  readonly ctrlKey: boolean;
+  /**
+   * Determines if the modifier aware event has the `shift` key masking.
+   */
+  readonly shiftKey: boolean;
+};
+
+/**
+ * The default tree properties.
+ */
+export const DefaultTreeProps: TreeProps = {
+  leftPadding: 8,
+  expansionTogglePadding: 18,
+};

package/src/app/tree/view/index.less

@@ -0,0 +1,3 @@
+.mana-tree-node-dropdown {
+  overflow: hidden;
+}

package/src/app/tree/view/index.ts

@@ -0,0 +1,3 @@
+export * from './tree-view';
+export * from './tree-view-decorator';
+export * from './tree-view-module';