@pcg/dynamic-components 1.0.0-alpha.0

package/src/y-tools/tools.ts

@@ -0,0 +1,122 @@
+import * as Y from 'yjs';
+
+import { isObject } from '@/assertions/index.js';
+import { sortByPosition } from '@/paths/index.js';
+
+/**
+ * Returns the index of the first item in a Y.Array that matches a condition.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * yArray.push(['item1', 'item2', 'item3']);
+ * const index = findIndexInYArray(yArray, (item) => item === 'item2');
+ * // index is now: 1
+ */
+export const findIndexInYArray = <T = unknown>(yArray: Y.Array<T>, isMatches: (item: T) => boolean): number => {
+  return yArray.toArray().findIndex(isMatches);
+};
+
+/**
+ * Returns the first item in a Y.Array that matches a condition.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * yArray.push(['item1', 'item2', 'item3']);
+ * const item = findInYArray(yArray, (item) => item === 'item2');
+ * // item is now: 'item2'
+ */
+export const findInYArray = <T = unknown>(yArray: Y.Array<T>, isMatches: (item: T) => boolean): T | null => {
+  const index = findIndexInYArray(yArray, isMatches);
+  if (index === -1) {
+    return null;
+  }
+
+  return yArray.get(index);
+};
+
+/**
+ * Converts an object to a Y.Map.
+ *
+ * @example
+ * const object = { key: 'value' };
+ * const yMap = objectToYMap(object);
+ * // yMap now looks like: { key: 'value' }
+ */
+export const objectToYMap = (values: object) => {
+  const entries: [string, unknown][] = Object.entries(values).map(([key, value]) => {
+    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);
+};
+
+/**
+ * Converts an array to a Y.Array.
+ *
+ * @example
+ * const array = ['item1', 'item2', 'item3'];
+ * const yArray = arrayToYArray(array);
+ * // yArray now looks like: ['item1', 'item2', 'item3']
+ */
+export const arrayToYArray = (array: unknown[], yArray: Y.Array<unknown> = new Y.Array()) => {
+  const items = array.map((it) => isObject(it) ? objectToYMap(it) : it);
+  yArray.insert(0, items);
+
+  return yArray;
+};
+
+/**
+ * Returns a sorted Y.Array based on the position of each Y.Map in it.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * let yMap1 = new Y.Map();
+ * let yMap2 = new Y.Map();
+ * yMap1.set('position', 'a0');
+ * yMap2.set('position', 'b0');
+ * yArray.push([yMap2, yMap1]);
+ * const sortedYArray = getSortedYArray(yArray);
+ * // sortedYArray now looks like: [ yMap1, yMap2 ]
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const getSortedYArray = <T extends Y.Map<any>>(yArray: Y.Array<T>) => yArray
+  .toArray()
+  .sort((a, b) => sortByPosition((a.get('position') as string), (b.get('position') as string)));
+
+/**
+ * Returns references to a Y.Map and its neighbors in a Y.Array based on its position.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * let yMap1 = new Y.Map();
+ * let yMap2 = new Y.Map();
+ * yMap1.set('position', 'a0');
+ * yMap2.set('position', 'b0');
+ * yArray.push([yMap2, yMap1]);
+ * const refs = getYArrayRefsByPosition(yArray, 'a0');
+ * // refs now looks like: { index: 0, ref: yMap1, right: yMap2, left: undefined, sortedArray: [yMap1, yMap2] }
+ */
+export const getYArrayRefsByPosition = <T extends Y.Map<unknown>>(yArray: Y.Array<T>, position: string) => {
+  const sortedArray = getSortedYArray(yArray);
+  // const currentYArrayIndex = sortedArray.findIndex((it) => it === yComponent);
+  const index = sortedArray.findIndex((it) => it.get('position') === position);
+  if (index === -1) {
+    console.error('sortedArray', sortedArray);
+    throw new Error(`Relative item with position ${position} not found`);
+  }
+
+  return {
+    index,
+    ref: sortedArray[index],
+    right: sortedArray[index + 1],
+    left: sortedArray[index - 1],
+    sortedArray,
+  };
+};
+

package/src/y-tools/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents changes in Y.js awareness state. Contains arrays of added, removed, and updated items.
+ */
+export interface AwarenessStateChange {
+  added: number[];
+  removed: number[];
+  updated: number[];
+}
+
+/**
+ * Represents the awareness state. This includes a cursor, user information (id, name, avatarUrl), and a color.
+ *
+ * @example
+ * const awarenessState: AwarenessState = {
+ *   cursor: ['xxx', 'yyy'], // rpath
+ *   user: {
+ *     id: 'abc123',
+ *     name: 'John Doe',
+ *     avatarUrl: 'https://example.com/avatar.jpg'
+ *   },
+ *   color: '#ff0000'
+ * };
+ */
+export interface AwarenessState {
+  cursor: string[];
+  user: {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+  };
+  color: string;
+}

package/src/y-tools/y-array-keys.ts

@@ -0,0 +1,47 @@
+import * as Y from 'yjs';
+
+import { isYArray, isYMap } from '@/assertions/index.js';
+import {
+  extractIdFromArrayKey, extractPositionFromArrayKey, isIdArrayKey, isPositionArrayKey,
+} from '@/paths/index.js';
+
+/**
+ * Returns the index of an item in a Y.Array based on its key.
+ * The key can represent either the id or the position of the item in the array.
+ *
+ * @example
+ * let yArray = new Y.Array();
+ * let yMap = new Y.Map();
+ * yMap.set('id', '123');
+ * yMap.set('position', 'a0');
+ * yArray.push([yMap]);
+ * const index = getYArrayIndexByArrayKey(yArray, 'id:123');
+ * const index = getYArrayIndexByArrayKey(yArray, 'pos:a0');
+ * // index is now: 0
+ */
+export const getYArrayIndexByArrayKey = (yArray: unknown, key: string): number => {
+  if (!isYArray<Y.Map<unknown>>(yArray)) {
+    console.error(`Non-YArray type`, yArray);
+    throw new Error(`Can't use array key in non YArray type (${key})`);
+  }
+
+  if (isIdArrayKey(key)) {
+    const id = extractIdFromArrayKey(key);
+    const index = yArray.toArray().findIndex((it) => isYMap(it) && it.get('id') === id);
+    if (index === -1) {
+      throw new Error(`Can't find index by id ${id} (${key})`);
+    }
+
+    return index;
+  } else if (isPositionArrayKey(key)) {
+    const position = extractPositionFromArrayKey(key);
+    const index = yArray.toArray().findIndex((it) => isYMap(it) && it.get('position') === position);
+    if (index === -1) {
+      throw new Error(`Can't find index by position ${position} (${key})`);
+    }
+
+    return index;
+  }
+
+  throw new Error(`Unknown array key type (${key})`);
+};

package/tests/assertions/basic-types.test.ts

@@ -0,0 +1,78 @@
+import {
+  describe, expect, test,
+} from 'vitest';
+import {
+  isCallable,
+  isIndex,
+  isNullOrUndefined,
+  isNumber,
+  isString,
+} from '../../src/assertions/index.js';
+
+const object = {
+  a: 2,
+};
+
+describe('isCallable', () => {
+  test('must return false on non-callable', () => {
+    expect(isCallable('123')).toBe(false);
+  });
+
+  test('must return true on callable', () => {
+    expect(isCallable(() => 0)).toBe(true);
+  });
+});
+
+describe('isIndex', () => {
+  test.each(['string', -1, '-1', [], object, null, undefined, () => 0])('must return false on non-index value: %p', (value) => {
+    expect(isIndex(value)).toBe(false);
+  });
+
+  test.each([
+    0,
+    1,
+    '1',
+  ])('must return true on index value: %p', (value) => {
+    expect(isIndex(value)).toBe(true);
+  });
+});
+
+describe('isString', () => {
+  test.each([1, [], object, null, undefined, () => 0])('must return false on non-string value: %p', (value) => {
+    expect(isString(value)).toBe(false);
+  });
+
+  test.each([
+    '',
+    'text',
+  ])('must return true on string value: %p', (value) => {
+    expect(isString(value)).toBe(true);
+  });
+});
+
+describe('isNumber', () => {
+  test.each(['text', [], object, null, undefined, () => 0])('must return false on non-number value: %p', (value) => {
+    expect(isNumber(value)).toBe(false);
+  });
+
+  test.each([
+    0,
+    -1,
+    100,
+  ])('must return true on number value: %p', (value) => {
+    expect(isNumber(value)).toBe(true);
+  });
+});
+
+describe('isNullOrUndefined', () => {
+  test.each(['', [], object, false, 0, () => 0])('must return false on non-null and non-undefined value: %p', (value) => {
+    expect(isNullOrUndefined(value)).toBe(false);
+  });
+
+  test.each([
+    null,
+    [].find((it) => it === 2),
+  ])('must return true on null or undefined value: %p', (value) => {
+    expect(isNullOrUndefined(value)).toBe(true);
+  });
+});

package/tests/assertions/containers.test.ts

@@ -0,0 +1,72 @@
+import {
+  describe, expect, test,
+} from 'vitest';
+import {
+  isContainerValue,
+  isEmptyArray,
+  isEmptyContainer,
+  isObject,
+} from '../../src/assertions/index.js';
+
+describe('isObject', () => {
+  test.each(['string', 4, [1, 2, 3], null, undefined, () => 0])('must return false on non object types: %p', (value) => {
+    expect(isObject(value)).toBe(false);
+  });
+
+  test.each([
+    {
+    },
+    {
+      a: 1,
+    },
+  ])('must return true on object types', (value) => {
+    expect(isObject(value)).toBe(true);
+  });
+});
+
+describe('isEmptyArray', () => {
+  test('must return false on non-empty array', () => {
+    expect(isEmptyArray([1, 2, 3])).toBe(false);
+  });
+
+  test('must return true on empty array', () => {
+    expect(isEmptyArray([])).toBe(true);
+  });
+});
+
+describe('isContainerValue', () => {
+  test.each(['string', 4, null, undefined, () => 0])('must return false on non-container value: %p', (value) => {
+    expect(isContainerValue(value)).toBe(false);
+  });
+
+  test.each([
+    {
+    },
+    [],
+    [1, 2, 3],
+    {
+      a: 2,
+    },
+  ])('must return true on container value: %p', (value) => {
+    expect(isContainerValue(value)).toBe(true);
+  });
+});
+
+describe('isEmptyContainer', () => {
+  test.each([
+    [1],
+    {
+      n: 1,
+    },
+  ])('must return false on non-empty container value: %p', (value) => {
+    expect(isEmptyContainer(value)).toBe(false);
+  });
+
+  test.each([
+    [],
+    {
+    },
+  ])('must return true on empty container value: %p', (value) => {
+    expect(isEmptyContainer(value)).toBe(true);
+  });
+});

package/tests/assertions/paths.test.ts

@@ -0,0 +1,23 @@
+import {
+  describe, expect, test,
+} from 'vitest';
+import { isEqualPath } from '../../src/assertions/index.js';
+
+describe('isEqualPath', () => {
+  test.each([
+    [[0], []],
+    [[0], [1]],
+    [[0, 'props', 'items'], [0, 'props', 'components']],
+  ])('must return false on non-equal pathes: %p === %p', (path1, path2) => {
+    expect(isEqualPath(path1, path2)).toBe(false);
+  });
+
+  test.each([
+    [[], []],
+    [[1], [1]],
+    [['components'], ['components']],
+    [[0, 'props', 'components'], [0, 'props', 'components']],
+  ])('must return true on equal pathes: %p === %p', (path1, path2) => {
+    expect(isEqualPath(path1, path2)).toBe(true);
+  });
+});

package/tests/assertions/yjs.test.ts

@@ -0,0 +1,33 @@
+import {
+  describe, expect, test,
+} from 'vitest';
+import {
+  isYArray,
+  isYMap,
+} from '../../src/assertions/index.js';
+
+import * as Y from 'yjs';
+
+const object = {
+  a: 2,
+};
+
+describe('isYMap', () => {
+  test.each(['string', 4, object, null, new Y.Array()])('must return false on non YMap types: %p', (value) => {
+    expect(isYMap(value)).toBe(false);
+  });
+
+  test('must return true on YMap types', () => {
+    expect(isYMap(new Y.Map())).toBe(true);
+  });
+});
+
+describe('isYArray', () => {
+  test.each(['[]', object, [], null, new Y.Map()])('must return false on non YArray types: %p', (value) => {
+    expect(isYArray(value)).toBe(false);
+  });
+
+  test('must return true on YArray types', () => {
+    expect(isYArray(new Y.Array())).toBe(true);
+  });
+});

package/tests/dynamic-components/paths.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'vitest';
+import { getComponentsSubtreeByPath, getComponentsSubtreeByRPath } from '../../src/dynamic-components/index.js';
+
+describe('getComponentsSubtreeByRPath', () => {
+  test('must extract subtree from collection', () => {
+    const components = [
+      {
+        id: 'xxx',
+        component: 'collection',
+        props: {
+          components: [
+            {
+              id: 'yyy',
+              component: 'text-input',
+              props: {
+                label: 'Title',
+              },
+            },
+          ],
+        },
+      },
+    ];
+
+    const { pathWithComponents, complete } = getComponentsSubtreeByRPath(components, ['xxx', 'yyy']);
+    expect(complete).toBeTruthy();
+
+    expect(pathWithComponents).toMatchObject([
+      {
+        id: 'xxx',
+        component: 'collection',
+      },
+      {
+        id: 'yyy',
+        component: 'text-input',
+      },
+    ]);
+  });
+
+  test('must extract subtree from repeatable collection', () => {
+    const components = [
+      {
+        id: 'xxx',
+        component: 'repeatable-collection',
+        props: {
+          name: 'fields',
+          components: [
+            {
+              id: 'yyy',
+              component: 'text-input',
+              props: {
+                name: 'title',
+                label: 'Title',
+              },
+            },
+          ],
+        },
+      },
+    ];
+
+    const { pathWithComponents, complete } = getComponentsSubtreeByRPath(components, ['xxx', 'yyy']);
+    expect(complete).toBeTruthy();
+
+    expect(pathWithComponents).toMatchObject([
+      {
+        id: 'xxx',
+        component: 'repeatable-collection',
+      },
+      {
+        id: 'yyy',
+        component: 'text-input',
+      },
+    ]);
+  });
+});
+
+describe('deepGetComponentsSubtreeByPath', () => {
+  test('must extract subtree from collection', () => {
+    const components = [
+      {
+        id: 'xxx',
+        component: 'collection',
+        props: {
+          name: 'seo',
+          components: [
+            {
+              id: 'yyy',
+              component: 'text-input',
+              props: {
+                name: 'title',
+                label: 'Title',
+              },
+            },
+          ],
+        },
+      },
+    ];
+
+    const { pathWithComponents, complete } = getComponentsSubtreeByPath(components, ['seo', 'title']);
+    expect(complete).toBeTruthy();
+
+    expect(pathWithComponents).toMatchObject([
+      {
+        id: 'xxx',
+        component: 'collection',
+      },
+      {
+        id: 'yyy',
+        component: 'text-input',
+      },
+    ]);
+  });
+
+  test('must extract subtree from repeatable collection', () => {
+    const components = [
+      {
+        id: 'xxx',
+        component: 'repeatable-collection',
+        props: {
+          name: 'fields',
+          components: [
+            {
+              id: 'yyy',
+              component: 'text-input',
+              props: {
+                name: 'title',
+                label: 'Title',
+              },
+            },
+          ],
+        },
+      },
+    ];
+
+    const { pathWithComponents, complete } = getComponentsSubtreeByPath(components, ['fields', 'id:xxx', 'title']);
+    expect(complete).toBeTruthy();
+
+    expect(pathWithComponents).toMatchObject([
+      {
+        id: 'xxx',
+        component: 'repeatable-collection',
+      },
+      {
+        id: 'yyy',
+        component: 'text-input',
+      },
+    ]);
+  });
+
+  test('must extract subtree by id', () => {
+    const components = [
+      {
+        id: 'e97ea',
+        component: 'text-input',
+        props: {
+          name: 'title',
+          label: 'Title',
+        },
+      },
+    ];
+
+    const { pathWithComponents, complete } = getComponentsSubtreeByPath(components, ['e97ea']);
+    expect(complete).toBeTruthy();
+
+    expect(pathWithComponents).toMatchObject([
+      {
+        id: 'e97ea',
+        component: 'text-input',
+      },
+    ]);
+  });
+});

package/tests/dynamic-components/tools.test.ts

@@ -0,0 +1,121 @@
+import { getDataObjectKey } from '@/data-objects/index.js';
+import { JSONContent, getSchema } from '@tiptap/core';
+import { default as StarterKit } from '@tiptap/starter-kit';
+import { describe, expect, test } from 'vitest';
+import { prosemirrorJSONToYXmlFragment } from 'y-prosemirror';
+import * as Y from 'yjs';
+import {
+  DRichText, DTextInput, DynamicComponent, DynamicComponentWithPosition, copyDynamicComponent, makeDynamicComponentsWithPosition,
+} from '../../src/dynamic-components/index.js';
+
+describe('copyDynamicComponent', () => {
+  test('must copy component', () => {
+    const component: DTextInput = {
+      id: 'xxx',
+      component: 'text-input',
+      props: {
+        name: 'email',
+        label: 'Email',
+      },
+    };
+
+    const componentCopy = copyDynamicComponent(component);
+
+    expect(componentCopy).toEqual({
+      ...component,
+      id: expect.any(String),
+    });
+  });
+
+  test('must copy component with rich text', () => {
+    const jsonContent: JSONContent = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'Hello World!',
+            },
+          ],
+        },
+      ],
+    };
+
+    const component: DRichText = {
+      id: 'xxx',
+      component: 'rich-text',
+      props: {
+        content: {
+          id: 'yyy',
+          type: 'RichText',
+        },
+      },
+    };
+
+    const schema = getSchema([
+      StarterKit,
+    ]);
+
+    const key = getDataObjectKey(component.props.content);
+
+    const yDoc = new Y.Doc();
+    prosemirrorJSONToYXmlFragment(
+      schema,
+      jsonContent,
+      yDoc.getXmlFragment(key),
+    );
+
+    const componentCopy = copyDynamicComponent(component, yDoc) as DRichText;
+
+    const newKey = getDataObjectKey(componentCopy.props.content);
+
+    expect(yDoc.getXmlFragment(newKey).toJSON())
+      .toEqual(yDoc.getXmlFragment(key).toJSON());
+
+    expect(componentCopy).toEqual({
+      ...component,
+      props: {
+        ...component.props,
+        content: {
+          ...component.props.content,
+          id: expect.any(String),
+        },
+      },
+      id: expect.any(String),
+    });
+  });
+});
+
+describe('makeDynamicComponentsWithPosition', () => {
+  test('should return dynamic components with position', () => {
+    const components: DynamicComponent[] = [1, 2, 3].map((n) => ({
+      id: `${n}`,
+      component: `component${n}`,
+      props: {
+      },
+    }));
+
+    const expected: DynamicComponentWithPosition[] = [1, 2, 3].map((n) => ({
+      id: `${n}`,
+      component: `component${n}`,
+      position: `a${n - 1}`, // a0, a1, a2
+      props: {
+      },
+    }));
+
+    const result = makeDynamicComponentsWithPosition(components);
+
+    expect(result).toEqual(expected);
+  });
+
+  test('should return empty array if no components provided', () => {
+    const components: DynamicComponent[] = [];
+    const expected: DynamicComponentWithPosition[] = [];
+
+    const result = makeDynamicComponentsWithPosition(components);
+
+    expect(result).toEqual(expected);
+  });
+});