@pcg/dynamic-components 1.0.0-alpha.0

package/src/y-components/tools.ts

@@ -0,0 +1,234 @@
+import { JSONContent } from '@tiptap/core';
+import { yXmlFragmentToProsemirrorJSON } from 'y-prosemirror';
+import * as Y from 'yjs';
+
+import {
+  isObject, isString, isYArray, isYMap,
+} from '@/assertions/index.js';
+import { RichText } from '@/data-objects/index.js';
+import {
+  DynamicComponent, DynamicComponentWithPosition,
+  sortDynamicComponents,
+} from '@/dynamic-components/index.js';
+import {
+  arrayToYArray,
+  objectToYMap,
+} from '@/y-tools/index.js';
+
+import { YComponent } from './types.js';
+
+/**
+ * This function converts dynamic component properties to Y.Map representation.
+ */
+export const dynamicComponentPropsToYComponentProps = (props: Record<string, unknown>) => {
+  const entries: [string, unknown][] = Object.entries(props).map(([key, value]) => {
+    if (key === 'content' && isObject(value) && (value.content as JSONContent)?.type === 'doc') {
+      // sae value content as is
+      return [key, value.content];
+    } else if (Array.isArray(value)) {
+      return [key, arrayToYArray(value)];
+    } else if (isObject(value)) {
+      return [key, objectToYMap(value)];
+    } else {
+      return [key, value];
+    }
+  });
+
+  return new Y.Map(entries);
+};
+
+/**
+ * This function converts a dynamic component to Y.Map representation.
+ */
+export const dynamicComponentToYMap = (component: DynamicComponent, yMap = new Y.Map()): YComponent => {
+  const {
+    props: propsWithComponents,
+    ...fields
+  } = component;
+
+  const {
+    components,
+    ...props
+  } = propsWithComponents ?? {
+  };
+
+  for (const [key, value] of Object.entries(fields)) {
+    yMap.set(key, value);
+  }
+
+  const yProps = props ? objectToYMap(props) : new Y.Map();
+
+  if (Array.isArray(components)) {
+    yProps.set('components', dynamicComponentsToYArray(components));
+  }
+
+  yMap.set('props', yProps);
+
+  return yMap;
+};
+
+/**
+ * This function converts an array of dynamic components to Y.Array representation.
+ */
+export const dynamicComponentsToYArray = (components: DynamicComponent[], yArray = new Y.Array()) => {
+  yArray.push(sortDynamicComponents(components).map((cmp) => dynamicComponentToYMap(cmp)));
+
+  return yArray;
+};
+
+/**
+ * This function checks if a given Y.Map object is a YComponent.
+ */
+export const isYComponent = (yComponent: unknown): yComponent is YComponent => {
+  return isYMap(yComponent) && isString(yComponent.get('component')) && isString(yComponent.get('id'));
+};
+
+/**
+ * This function converts a YComponent to a dynamic component.
+ */
+export const yComponentToDynamicComponent = (yComponent: YComponent, extractContent = false): DynamicComponentWithPosition => {
+  const component: Record<string, unknown> = {
+    props: {
+    },
+  };
+
+  for (const [key, value] of yComponent.entries()) {
+    if (key === 'props') {
+      if (!isYMap(value)) {
+        throw new Error('Component props must be YMap');
+      }
+
+      const yComponentProps = value;
+
+      const props: Record<string, unknown> = {
+      };
+
+      for (const [prop, value] of yComponentProps.entries()) {
+        if (prop === 'components') {
+          if (!isYArray<YComponent>(value)) {
+            throw new Error('Component props.components array must be YArray');
+          }
+
+          props.components = value.toArray().map((it) => yComponentToDynamicComponent(it));
+        } else if (
+          extractContent &&
+          yComponent.doc &&
+          isYMap(value) &&
+          value.get('type') === 'RichText' &&
+          typeof value.get('id') === 'string'
+        ) {
+          const id = value.get('id') as string;
+          const rawRichText = value.toJSON() as RichText;
+
+          const richText: RichText = {
+            ...rawRichText,
+            tiptap: yXmlFragmentToProsemirrorJSON(yComponent.doc.getXmlFragment(`RichText:${id}`)),
+          };
+
+          props[prop] = richText;
+        } else if (value instanceof Y.AbstractType) {
+          props[prop] = value.toJSON();
+        } else {
+          props[prop] = value;
+        }
+      }
+
+      component.props = props;
+    } else if (isYArray(value)) {
+      component[key] = value.toArray();
+    } else if (isYMap(value)) {
+      component[key] = value.toJSON();
+    } else {
+      component[key] = value;
+    }
+  }
+
+  return component as unknown as DynamicComponentWithPosition;
+};
+
+/**
+ * This function converts a dynamic component to YComponent.
+ */
+export const dynamicComponentToYComponent = (component: DynamicComponent): YComponent => {
+  // return yComponent.toJSON() as DynamicComponentWithPosition;
+  return dynamicComponentToYMap(component) as YComponent;
+};
+
+/**
+ * This function retrieves the properties of a YComponent.
+ */
+export const getYComponentProps = (yComponent: YComponent): Y.Map<unknown> => {
+  const props = yComponent.get('props');
+  if (!isYMap(props)) {
+    throw new Error(`Component hasn't "props" property. It must have to be defined as Y.Map (component: ${yComponent.get('id')})`);
+  }
+
+  return props;
+};
+
+/**
+ * This function retrieves the array of components of a YComponent.
+ */
+export const getYComponentComponentsArray = (yComponent: YComponent): Y.Array<YComponent> => {
+  const props = getYComponentProps(yComponent);
+
+  const yComponents = props.get('components');
+
+  if (!isYArray<YComponent>(yComponents)) {
+    throw new Error(`Component hasn't "props.components" property. It must be defined as Y.Array (component: ${yComponent.get('id')})`);
+  }
+
+  return yComponents;
+};
+
+/**
+ * This function checks if a YComponent has a components array.
+ * @example
+ * // component
+ * {
+ *   id: "column",
+ *   component: "column",
+ *   props: {
+ *     components: [...] <= has components array
+ *   }
+ * }
+ */
+export const yComponentHasComponentsYArray = (yComponent: YComponent): boolean => {
+  const props = getYComponentProps(yComponent);
+
+  const yComponents = props.get('components');
+
+  return isYArray<YComponent>(yComponents);
+};
+
+/**
+ * This function retrieves the parent component of a YArray of YComponents.
+ * @example
+ * // parent component
+ * {
+ *   id: "column",
+ *   component: "column",
+ *   props: {
+ *     components: [...] <= components array
+ *   }
+ * }
+ */
+export const getYComponentsArrayParentComponent = (yArray: Y.Array<YComponent>): YComponent | null => {
+  // yarray => parent (props) => parent (YIndexedDynamicComponents)
+
+  return yArray.parent?.parent as YComponent ?? null;
+};
+
+/**
+ * This function finds a Y.Component in a Y.Array by its ID.
+ */
+export const findYComponentInArray = (yArray: Y.Array<YComponent>, componentId: string) => {
+  const yComponent = yArray.toArray().find((it) => it.get('id') === componentId);
+
+  if (!yComponent) {
+    throw new Error(`Component with id ${componentId} not found in yArray`);
+  }
+
+  return yComponent;
+};
+

package/src/y-components/types.ts

@@ -0,0 +1,19 @@
+import * as Y from 'yjs';
+
+/**
+ * Represents a dynamic component in Y.js.
+ * Each component is represented as a Y.Map object where each key-value pair corresponds to a property of the component.
+ */
+export type YComponent = Y.Map<unknown>
+
+/**
+ * Represents an array of dynamic components in Y.js.
+ * Each component in the array is represented as a YComponent.
+ */
+export type YComponentsArray = Y.Array<YComponent>
+
+/**
+ * Represents the properties of a dynamic component in Y.js.
+ * Each property is represented as a key-value pair in a Y.Map object.
+ */
+export type YComponentProps = Y.Map<unknown>

package/src/y-tools/array-path-ops.ts

@@ -0,0 +1,240 @@
+import * as Y from 'yjs';
+
+import {
+  isIndex, isYArray, isYMap,
+} from '@/assertions/index.js';
+import { generateKeyBetween } from '@/dynamic-components/index.js';
+
+import { getFromYPath, setInYPath } from './basic-path-ops.js';
+import { getSortedYArray, getYArrayRefsByPosition } from './tools.js';
+import { getYArrayIndexByArrayKey } from './y-array-keys.js';
+
+/**
+ * Pushes a value to the end of the Y.Array at the specified path.
+ *
+ * @example
+ * let yMap = new Y.Map();
+ * yMap.set('names', new Y.Array());
+ * pushInYPath(yMap, ['names'], 'John');
+ * // yMap now looks like: { names: ['John'] }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const pushInYPath = (entry: Y.Array<any> | Y.Map<any>, path: (string | number)[], value: any) => {
+  const yArray = getFromYPath(entry, path);
+  if (!isYArray(yArray)) {
+    setInYPath(entry, path, Y.Array.from([value]));
+  } else {
+    yArray.push([value]);
+  }
+};
+
+const printPosition = (array: unknown[]) => array.map((it) => isYMap(it) ? it.get('position') ?? 'no-position' : 'not-ymap');
+
+/**
+ * Moves an item to a new position relative to another item in the Y.Array or Y.Map at the specified path.
+ *
+ * @example
+ * moveInYPath(yMap, ['components'], 'a0', 'b1', 'after');
+ */
+export const moveInYPath = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  entry: Y.Array<any> | Y.Map<any>,
+  path: (string | number)[],
+  oldPosition: string,
+  relativePosition: string,
+  insert: 'before' | 'after',
+) => {
+  const yArray = getFromYPath(entry, path);
+  if (!isYArray(yArray)) {
+    throw new Error(`Can't move. Target item is not yArray in path ${JSON.stringify(path)}`);
+  }
+
+  const array = yArray.toArray();
+
+  const item = array.find((it) => isYMap(it) && it.get('position') === oldPosition);
+  const relativeItemIndex = array.findIndex((it) => isYMap(it) && it.get('position') === relativePosition);
+
+  if (!isYMap(item)) {
+    throw new Error(`Can't move. Item in position ${oldPosition} not found. ${printPosition(array)}`);
+  }
+
+  if (relativeItemIndex === -1) {
+    throw new Error(`Can't move. Relative item in position ${relativePosition} not found. ${printPosition(array)}`);
+  }
+
+  const relativeItem = array[relativeItemIndex];
+  if (!isYMap(relativeItem)) {
+    throw new Error(`Can't move. Relative item in position ${relativePosition} must be YMap. ${printPosition(array)}`);
+  }
+
+  if (insert === 'before') {
+    const left = array[relativeItemIndex - 1];
+    const leftPosition = isYMap(left) ? left.get('position') as string ?? null : null;
+
+    const newPosition = generateKeyBetween(leftPosition, relativeItem.get('position') as string);
+    item.set('position', newPosition);
+
+    return newPosition;
+  }
+
+  const right = array[relativeItemIndex + 1];
+  const rightPosition = isYMap(right) ? right.get('position') as string ?? null : null;
+
+  const newPosition = generateKeyBetween(relativeItem.get('position') as string, rightPosition);
+  item.set('position', newPosition);
+
+  return newPosition;
+};
+
+/**
+ * Removes an item from the Y.Array or Y.Map at the specified path.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * yArray.push(['item1', 'item2', 'item3']);
+ * pullFromYPath(yArray, [1]);
+ * // yArray now looks like: ['item1', 'item3']
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const pullFromYPath = (entry: Y.Array<any> | Y.Map<any>, path: (string | number)[], key: string | number) => {
+  const yArray = getFromYPath(entry, path) as unknown[];
+  if (isYArray(yArray)) {
+    if (isIndex(key)) {
+      yArray.delete(key);
+
+      return;
+    }
+
+    const index = getYArrayIndexByArrayKey(yArray, key);
+    yArray.delete(index);
+  }
+};
+
+export interface MoveYMapToStartOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+}
+
+/**
+ * Moves a Y.Map to the start of a Y.Array.
+ * */
+export const moveYMapToStart = ({ yArray, yMap }: MoveYMapToEndOptions) => {
+  const sortedArray = getSortedYArray(yArray);
+  const first = sortedArray[0];
+
+  const rightIndex = first ? (first.get('position') as string) : null;
+
+  yMap.set('position', generateKeyBetween(null, rightIndex));
+};
+
+export interface MoveYMapToEndOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+}
+
+/**
+ * Moves a Y.Map to the end of a Y.Array.
+ * */
+export const moveYMapToEnd = ({ yArray, yMap }: MoveYMapToEndOptions) => {
+  const sortedArray = getSortedYArray(yArray);
+  const last = sortedArray[sortedArray.length - 1];
+
+  const leftIndex = last ? (last.get('position') as string) : null;
+
+  yMap.set('position', generateKeyBetween(leftIndex, null));
+};
+
+export interface MoveYMapBeforeOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+  relativePosition: string;
+}
+
+/**
+ * Moves a Y.Map before another Y.Map in a Y.Array.
+ * */
+export const moveYMapBefore = ({
+  yArray,
+  yMap,
+  relativePosition,
+}: MoveYMapBeforeOptions) => {
+  const { ref: relative, left } = getYArrayRefsByPosition(yArray, relativePosition);
+
+  const right = relative; // left - x - relative
+
+  const rightIndex = right ? (right.get('position') as string) : null;
+  const leftIndex = left ? (left.get('position') as string) : null;
+
+  yMap.set('position', generateKeyBetween(leftIndex, rightIndex));
+};
+
+export interface MoveYMapAfterOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+  relativePosition: string;
+}
+
+/**
+ * Moves a Y.Map after another Y.Map in a Y.Array.
+ * */
+export const moveYMapAfter = ({
+  yArray,
+  yMap,
+  relativePosition,
+}: MoveYMapAfterOptions) => {
+  const { ref: relative, right } = getYArrayRefsByPosition(yArray, relativePosition);
+
+  const left = relative; // relative - x - right
+
+  const rightIndex = right ? (right.get('position') as string) : null;
+  const leftIndex = left ? (left.get('position') as string) : null;
+
+  yMap.set('position', generateKeyBetween(leftIndex, rightIndex));
+};
+
+export interface InsertYMapToEndOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+}
+
+/**
+ * Inserts a Y.Map to the end of a Y.Array.
+ * */
+export const insertYMapToEnd = (opts: InsertYMapToEndOptions) => {
+  moveYMapToEnd(opts);
+
+  // always appended, since sort order is not reliant on array order
+  opts.yArray.push([opts.yMap]);
+};
+
+export interface InsertYMapBeforeOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+  relativePosition: string;
+}
+
+/**
+ * Inserts a Y.Map before another Y.Map in a Y.Array.
+ * */
+export const insertYMapBefore = (opts: InsertYMapBeforeOptions) => {
+  moveYMapBefore(opts);
+
+  // always appended, since sort order is not reliant on array order
+  opts.yArray.push([opts.yMap]);
+};
+
+export interface InsertYMapAfterOptions {
+  yArray: Y.Array<Y.Map<unknown>>;
+  yMap: Y.Map<unknown>;
+  relativePosition: string;
+}
+
+/**
+ * Inserts a Y.Map before another Y.Map in a Y.Array.
+ * */
+export const insertYMapAfter = (opts: InsertYMapAfterOptions) => {
+  moveYMapAfter(opts);
+
+  // always appended, since sort order is not reliant on array order
+  opts.yArray.push([opts.yMap]);
+};

package/src/y-tools/basic-path-ops.ts

@@ -0,0 +1,189 @@
+import * as Y from 'yjs';
+
+import {
+  isIndex, isNullOrUndefined, isString, isYArray, isYMap,
+} from '@/assertions/index.js';
+import { isArrayKey } from '@/paths/index.js';
+
+import { getYArrayIndexByArrayKey } from './y-array-keys.js';
+
+/**
+ * Sets a value at a given path within a Y.Map or Y.Array.
+ *
+ * @example
+ * let ymap = new Y.Map();
+ * setInYPath(ymap, ['key'], 'value');
+ * // ymap now looks like: { key: 'value' }
+ */
+export const setInYPath = (ymap: Y.Map<unknown> | Y.Array<unknown>, path: (string | number)[], value: unknown): void => {
+  let acc: Y.Map<unknown> | Y.Array<unknown> = ymap;
+
+  for (const [i, rawKey] of path.entries()) {
+    const key = isArrayKey(rawKey) ? getYArrayIndexByArrayKey(acc, rawKey) : rawKey;
+
+    if (isYArray(acc) && isIndex(key)) {
+      const index = key;
+
+      // Last key, set it
+      if (i === path.length - 1) {
+        acc.delete(index);
+        acc.push([value]);
+
+        return;
+      }
+
+      // Key does not exist, create a container for it
+      if (isNullOrUndefined(acc.get(index))) {
+        // container can be either an object or an array depending on the next key if it exists
+        const nextRawKey = path[i + 1];
+        const nextKey = isArrayKey(nextRawKey) ? getYArrayIndexByArrayKey(acc, nextRawKey) : nextRawKey;
+
+        // if (isArrayKey(nextKey)) {
+        //   throw Error(`Can't create empty array in "${key}" with next position key (path: ${JSON.stringify(path)})`);
+        // }
+
+        acc.delete(index);
+        acc.insert(index, [isIndex(nextKey) ? new Y.Array() : new Y.Map()]);
+      }
+
+      acc = acc.get(index) as Y.Map<unknown> | Y.Array<unknown>;
+    } else if (isYMap(acc) && isString(key)) {
+      // Last key, set it
+      if (i === path.length - 1) {
+        acc.set(key, value);
+
+        return;
+      }
+
+      // Key does not exist, create a container for it
+      if (!acc.has(key) || isNullOrUndefined(acc.get(key))) {
+      // container can be either an object or an array depending on the next key if it exists
+        const nextRawKey = path[i + 1];
+        const nextKey = isArrayKey(nextRawKey) ? getYArrayIndexByArrayKey(acc, nextRawKey) : nextRawKey;
+
+        // if (isArrayKey(nextKey)) {
+        //   throw Error(`Can't create empty array in "${key}" with next position key "${nextKey}" (path: ${JSON.stringify(path)})`);
+        // }
+
+        acc.set(key, isIndex(nextKey) ? new Y.Array() : new Y.Map());
+      }
+
+      acc = acc.get(key) as Y.Map<unknown> | Y.Array<unknown>;
+    }
+  }
+};
+
+const yUnset = (yType: Y.Map<unknown> | Y.Array<unknown>, key: string | number) => {
+  if (yType instanceof Y.Array && isIndex(key)) {
+    yType.delete(Number(key));
+  } else if (yType instanceof Y.Map && isString(key)) {
+    yType.delete(key);
+  }
+};
+
+/**
+ * Removes a nested property from a Y.Map or Y.Array.
+ *
+ * @example
+ * let ymap = new Y.Map();
+ * ymap.set('key', 'value');
+ * unsetYPath(ymap, ['key']);
+ * // ymap now looks like: {}
+ */
+export const unsetYPath = (yType: Y.Map<unknown> | Y.Array<unknown>, path: (string | number)[]): void => {
+  let acc: Y.Map<unknown> | Y.Array<unknown> = yType;
+  for (const [i, rawKey] of path.entries()) {
+    const key = isArrayKey(rawKey) ? getYArrayIndexByArrayKey(acc, rawKey) : rawKey;
+
+    // Last key, unset it
+    if (i === path.length - 1) {
+      yUnset(acc, key);
+      break;
+    }
+
+    if (acc instanceof Y.Array && isIndex(key)) {
+      const index = Number(key);
+
+      // Key does not exist, exit
+      if (isNullOrUndefined(acc.get(index))) {
+        break;
+      }
+
+      acc = acc.get(index) as Y.Map<unknown> | Y.Array<unknown>;
+    } else if (acc instanceof Y.Map && isString(key)) {
+      // Key does not exist, exit
+      if (!acc.has(key) || isNullOrUndefined(acc.get(key))) {
+        break;
+      }
+
+      acc = acc.get(key) as Y.Map<unknown> | Y.Array<unknown>;
+    }
+  }
+
+  // const pathValues: (unknown | Record<string, unknown>)[] = keys.map((_, idx) => {
+  //   return getFromPath(object, keys.slice(0, idx).join('.'));
+  // });
+
+  // for (let i = pathValues.length - 1; i >= 0; i--) {
+  //   if (!isEmptyContainer(pathValues[i])) {
+  //     continue;
+  //   }
+
+  //   if (i === 0) {
+  //     unset(object, keys[0]);
+  //     continue;
+  //   }
+
+  //   unset(pathValues[i - 1] as Record<string, unknown>, keys[i - 1]);
+  // }
+};
+
+/**
+ * Retrieves a nested property value from a Y.Map or Y.Array.
+ *
+ * @example
+ * let ymap = new Y.Map();
+ * ymap.set('key', 'value');
+ * const value = getFromYPath(ymap, ['key']);
+ * // value is now: 'value'
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const getFromYPath = (entry: Y.Array<any> | Y.Map<any>, path: (string | number)[]): unknown | null => {
+  if (!entry) {
+    return;
+  }
+
+  if (path.length === 0) {
+    return entry;
+  }
+
+  let ref = entry as unknown;
+  for (const rawKey of path) {
+    const key = isArrayKey(rawKey) ? getYArrayIndexByArrayKey(ref, rawKey) : rawKey;
+
+    if (isYArray(ref)) {
+      if (!isIndex(key)) {
+        console.warn(`Can't use non index key in YArray ${key}: ${JSON.stringify(path)}`);
+
+        return null;
+      }
+
+      ref = ref.get(key);
+      continue;
+    } else if (isYMap(ref)) {
+      if (!isString(key)) {
+        console.warn(`Can't use non string key in YMap ${key}: ${JSON.stringify(path)}`);
+
+        return null;
+      }
+
+      ref = ref.get(key);
+    } else {
+      console.warn(`Non supported YType on ${key}: ${JSON.stringify(path)}`);
+
+      return null;
+    }
+  }
+
+  return ref;
+};

package/src/y-tools/index.ts

@@ -0,0 +1,6 @@
+export * from './array-path-ops.js';
+export * from './basic-path-ops.js';
+export * from './tools.js';
+export * from './types.js';
+export * from './y-array-keys.js';
+