@pcg/dynamic-components 1.0.0-alpha.0

package/src/dynamic-components/tools.ts

@@ -0,0 +1,195 @@
+import * as Y from 'yjs';
+
+import { isRichText } from '../assertions/rich-text.js';
+import { generateKeyBetween } from './fractional-indexing.js';
+import {
+  DynamicComponent, DynamicComponentWithPosition, Point,
+} from './types.js';
+
+// This alphabet uses `A-Za-z0-9_-` symbols.
+// The order of characters is optimized for better gzip and brotli compression.
+// References to the same file (works both for gzip and brotli):
+// `'use`, `andom`, and `rict'`
+// References to the brotli default dictionary:
+// `-26T`, `1983`, `40px`, `75px`, `bush`, `jack`, `mind`, `very`, and `wolf`
+export const urlAlphabet =
+  'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+
+export const customAlphabet = (alphabet: string, defaultSize = 21) => {
+  return (size = defaultSize) => {
+    let id = '';
+    // A compact alternative for `for (var i = 0; i < step; i++)`.
+    let i = size;
+    while (i--) {
+      // `| 0` is more compact and faster than `Math.floor()`.
+      // eslint-disable-next-line no-bitwise
+      id += alphabet[(Math.random() * alphabet.length) | 0];
+    }
+
+    return id;
+  };
+};
+
+export const uid = customAlphabet('1234567890abcdefg', 5);
+
+/**
+ * Gets the path to a property in a component.
+ * @param {(string | number)[]} componentPath - The path to the component.
+ * @param {string} name - The name of the property.
+ * @returns {(string | number)[]} Returns the path to the property.
+ * @example
+ * getComponentPropertyPath(['components', 0], 'name');  // Returns ['components', 0, 'props', 'name']
+ */
+export const getComponentPropertyPath = (componentPath: (string | number)[], name: string) => [...componentPath, 'props', name];
+
+/**
+ * Creates a copy of a dynamic component.
+ * @param {DynamicComponent} component - The component to copy.
+ * @param {Y.Doc} yDoc - The Yjs document to update with the copied component.
+ * @returns {DynamicComponent} Returns the copied component.
+ */
+export const copyDynamicComponent = (component: DynamicComponent, yDoc?: Y.Doc): DynamicComponent => {
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    id,
+
+    props,
+    coordinates,
+    inputs,
+    outputs,
+    ...extras
+  } = component;
+
+  const componentCopy: DynamicComponent = {
+    ...extras,
+    id: uid(),
+    props: {
+    },
+  };
+
+  if (coordinates) {
+    componentCopy.coordinates = [
+      coordinates[0] + 10,
+      coordinates[1] + 10,
+    ];
+  }
+
+  if (inputs) {
+    componentCopy.inputs = inputs.map((input) => ({
+      ...input,
+      id: uid(),
+    }));
+  }
+
+  if (outputs) {
+    componentCopy.outputs = outputs.map((output) => ({
+      ...output,
+      id: uid(),
+    }));
+  }
+
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'components' && Array.isArray(value)) {
+      componentCopy.props.components = value.map((cmp) => copyDynamicComponent(cmp));
+    } else if (isRichText(value)) {
+      const oldKey = `${value.type}:${value.id}`;
+
+      const newRichText = {
+        ...value,
+        id: uid(),
+      };
+
+      const newKey = `${value.type}:${newRichText.id}`;
+
+      if (yDoc) {
+        const yXmlFragment = yDoc.getXmlFragment(oldKey);
+        const newYXmlFragment = yDoc.getXmlFragment(newKey);
+
+        const clones: (Y.XmlElement | Y.XmlText)[] = [];
+        for (const item of yXmlFragment.toArray()) {
+          if (item instanceof Y.XmlElement || item instanceof Y.XmlText) {
+            clones.push(item.clone());
+          }
+        }
+
+        newYXmlFragment.insert(0, clones);
+      }
+
+      componentCopy.props[key] = newRichText;
+    } else {
+      componentCopy.props[key] = value;
+    }
+  }
+
+  return componentCopy;
+};
+
+/**
+ * Sorts an array of dynamic components and generates a position for each one.
+ * @param {DynamicComponent[]} components - The components to sort.
+ * @returns {DynamicComponentWithPosition[]} Returns the sorted components with positions.
+ */
+export const sortDynamicComponents = (components: DynamicComponent[]): DynamicComponentWithPosition[] => {
+  return components.reduce((acc, component, i) => {
+    const prev = acc[i - 1];
+
+    const {
+      position,
+      props: {
+        components,
+        ...baseProps
+      },
+      ...baseFields
+    } = component;
+
+    const props: DynamicComponentWithPosition['props'] = baseProps;
+
+    if (components) {
+      props.components = sortDynamicComponents(components);
+    }
+
+    acc.push({
+      ...baseFields,
+      position: position ?? generateKeyBetween(prev?.position ?? null, null),
+      props,
+    });
+
+    return acc;
+  }, [] as DynamicComponentWithPosition[]);
+};
+
+/**
+ * Searches for a dynamic component in a tree that matches a condition.
+ * @param {DynamicComponent[]} components - The tree of components to search.
+ * @param {(cmp: DynamicComponent) => boolean} isMatches - The condition to match.
+ * @returns {DynamicComponent | null} Returns the matching component, or null if no match was found.
+ */
+export const searchDynamicComponentInTree = (
+  components: DynamicComponent[],
+  isMatches: (cmp: DynamicComponent) => boolean,
+): DynamicComponent | null => {
+  for (const component of components) {
+    if (isMatches(component)) {
+      return component;
+    }
+
+    if (Array.isArray(component.props.components)) {
+      const result = searchDynamicComponentInTree(component.props.components, isMatches);
+      if (result) {
+        return result;
+      }
+    }
+  }
+
+  return null;
+};
+
+export const getRelativePoint = (point: Point, relative: Point): Point => [point[0] - relative[0], point[1] - relative[1]];
+
+/**
+ * Creates a copy of a dynamic component and set its position (fractional-index) rely on the index of the component.
+ * @param components - The components without positions.
+ */
+export const makeDynamicComponentsWithPosition = (components: DynamicComponent[]): DynamicComponentWithPosition[] => {
+  return sortDynamicComponents(components.slice(0));
+};

package/src/dynamic-components/types.ts

@@ -0,0 +1,237 @@
+export type Point = [number, number]; // [x, y]
+
+export interface DynamicComponentIO {
+  id: string;
+  name: string;
+}
+
+/**
+ * Represents a link between two dynamic components.
+ */
+export interface DynamicComponentLink {
+  /** The unique identifier of the link. */
+  id: string;
+  /** The input of the link. */
+  input: string;
+  /** The output of the link. */
+  output: string;
+}
+
+/**
+
+/**
+ * ValidationRules interface is used for defining the set of
+ * validation constraints for a field in a form or component.
+ *
+ * @example
+ * let rules: ValidationRules = {
+ *   required: true,
+ *   min: 1,
+ *   max: 100,
+ *   pattern: 'email'
+ * };
+ */
+export interface ValidationRules {
+  /**
+   * Indicates whether the field is required or not.
+   */
+  required?: boolean;
+
+  /**
+   * Specifies the minimum value for the field.
+   */
+  min?: number;
+
+  /**
+   * Specifies the maximum value for the field.
+   */
+  max?: number;
+
+  /**
+   * Specifies a pattern that the field value should match.
+   */
+  pattern?: 'email' | 'url' | 'hh:mm:ss' | 'phone';
+
+  /**
+   *Specifies whether to trim spaces.
+   */
+  trim?: boolean;
+}
+
+export interface ComponentStyles {
+  /**
+   * Specifies the top padding of the component.
+   */
+  paddingTop?: string;
+
+  /**
+   * Specifies the bottom padding of the component.
+   */
+  paddingBottom?: string;
+}
+
+/**
+ * DynamicComponent is a key feature of the component designer.
+ * It is a data structure used to describe dynamic components,
+ * which can be added to the content by the component designer and their properties can be edited on the fly.
+ * The output of the designer is a tree of dynamic components.
+ *
+ * For example, a text input component can be described as follows:
+ * ```typescript
+ * export interface DTextInput extends DynamicComponent {
+ *   component: 'text-input';
+ *   props: {
+ *     name?: string;
+ *     label?: string;
+ *     placeholder?: string;
+ *     maska?: string;
+ *     disabled?: boolean;
+ *     readonly?: boolean;
+ *     rules?: ValidationRules;
+ *     visible?: string;
+ *   };
+ * }
+ * ```
+ */
+export interface DynamicComponent {
+  /**
+   * The unique identifier of the component.
+   */
+  id: string;
+
+  /**
+   * The type of the component.
+   */
+  component: string;
+
+  /**
+   * The variant of the component.
+   * For example, a button component can have variants like 'primary', 'secondary', etc.
+   */
+  variant?: string;
+
+  /**
+   * The position of the component.
+   */
+  position?: string;
+
+  /**
+   * A flag indicating whether the component is enabled or not.
+   */
+  enabled?: boolean;
+
+  /**
+   * The coordinated of the component in the canvas.
+   */
+  coordinates?: Point;
+
+  /**
+   * The inputs of the component.
+   * Input ports are used to connect the component to other components.
+   */
+  inputs?: DynamicComponentIO[];
+
+  /**
+   * The outputs of the component.
+   * Output ports are used to connect the component to other components.
+   */
+  outputs?: DynamicComponentIO[];
+
+  /**
+   * The properties of the component.
+   */
+  props: {
+    /**
+     * The name of the component.
+     */
+    name?: string;
+
+    /**
+     * The visibility of the component.
+     */
+    visible?: string;
+
+    /**
+     * The readonly status of the component.
+     */
+    readonly?: boolean;
+
+    /**
+     * The child components of the component.
+     */
+    components?: DynamicComponent[];
+
+    /**
+     * The validation rules for the component.
+     */
+    rules?: ValidationRules;
+
+    /**
+     * The styles for the component.
+     */
+    styles?: ComponentStyles;
+
+    /**
+     * Any other properties of the component.
+     */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * DynamicComponent is a key feature of the component designer.
+ * It is a data structure used to describe dynamic components ,
+ * which can be added to the content by the component designer and their properties can be edited on the fly.
+ * The output of the designer is a tree of dynamic components.
+ *
+ * DynamicComponentWithPosition is a DynamicComponent with defind fractional-indexed position.
+ *
+ * For example, a text input component can be described as follows:
+ * ```typescript
+ * {
+ *   component: 'text-input';
+ *   props: {
+ *     name: 'email';
+ *     label:: string;
+ *     placeholder?: string;
+ *     maska?: string;
+ *     disabled?: boolean;
+ *     readonly?: boolean;
+ *     rules?: ValidationRules;
+ *     visible?: string;
+ *   };
+ * }
+ * ```
+ */
+export interface DynamicComponentWithPosition extends DynamicComponent {
+  /**
+   * The position of the component. This is required for DynamicComponentWithPosition.
+   */
+  position: string;
+
+  /**
+   * The properties of the component.
+   */
+  props: DynamicComponent['props'] & {
+    /**
+     * The child components of the component.
+     */
+    components?: DynamicComponentWithPosition[];
+  };
+}
+
+/**
+ * Defines a DynamicComponent.
+ * @param {T} component - The component to define.
+ * @returns {T} Returns the defined component.
+ */
+export const defineDynamicComponent = <T extends DynamicComponent>(component: T): T => component;
+
+/**
+ * Defines an array of DynamicComponents.
+ * @param {T[]} components - The components to define.
+ * @returns {T[]} Returns the defined components.
+ */
+export const defineDynamicComponents = <T extends DynamicComponent>(components: T[]): T[] =>
+  components.map((component) => defineDynamicComponent<T>(component));
+

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './assertions/index.js';
+export * from './data-objects/index.js';
+export * from './dynamic-components/index.js';
+export * from './paths/index.js';
+export * from './y-components/index.js';
+export * from './y-tools/index.js';
+

package/src/paths/array-keys.ts

@@ -0,0 +1,164 @@
+import { isObject, isString } from '@/assertions/index.js';
+
+/**
+ * In the system you are using, two types of keys are used to identify elements in an array: ID keys and position keys.
+ * These keys provide a flexible and robust way to refer to specific elements in an array, particularly when dealing with arrays of objects.
+ *
+ * 1. **ID Keys:**
+ * These keys have a prefix of 'id:' and are followed by the unique identifier of an object in the array.
+ * For example, in your array `items: [{ id: 'xxx', name: 'John' }]`, you can refer to the object with `id: 'xxx'` using the ID key 'id:xxx'.
+ * This is particularly useful when you have a unique identifier for each object in your array.
+ * With this, even if objects move around in the array, you can always accurately refer to a specific object using its unique ID.
+ *
+ * 2. **Position Keys:**
+ * These keys have a prefix of 'pos:' and are followed by a position indicator.
+ * Position keys provide a way to refer to an object in an array based on its position rather than its content.
+ * This can be useful when the position of an object in an array is significant and you want to refer to an object based on where it is in the array.
+ *
+ * In your path system, you can use either type of key as part of the path to refer to specific elements in an array.
+ * For example, if you have an object like `{ items: [{ id: 'xxx', name: 'John' }] }`,
+ * you can refer to the name of the first item in the array using either an ID key or a position key in the path:
+ *
+ * - Using an ID key: `['items', 'id:xxx', 'name']`
+ * - Using a position key: `['items', 'pos:0', 'name']`
+ *
+ * This system of using ID and position keys in paths gives you a powerful and flexible way to refer to specific elements in complex, nested objects.
+ */
+
+export const POSITION_ARRAY_KEY_PREFIX = 'pos:';
+
+/**
+ * Checks if the given key is a position array key.
+ * @param {unknown} key - The key to check.
+ * @returns {boolean} Returns true if `key` is a position array key, false otherwise.
+ * @example
+ * isPositionArrayKey('pos:0');  // Returns true
+ * isPositionArrayKey('id:0');  // Returns false
+ */
+export const isPositionArrayKey = (key: unknown): key is string => {
+  return isString(key) && key.startsWith(POSITION_ARRAY_KEY_PREFIX);
+};
+
+/**
+ * Creates a position array key.
+ * @param {string} position - The position to create the key for.
+ * @returns {string} Returns the created position array key.
+ * @example
+ * createPositionArrayKey('0');  // Returns 'pos:0'
+ */
+export const createPositionArrayKey = (position: string) => {
+  return `${POSITION_ARRAY_KEY_PREFIX}${position}`;
+};
+
+/**
+ * Extracts the position from a position array key.
+ * @param {string} key - The position array key to extract the position from.
+ * @returns {string} Returns the extracted position.
+ * @example
+ * extractPositionFromArrayKey('pos:0');  // Returns '0'
+ */
+export const extractPositionFromArrayKey = (key: string): string => {
+  if (!isPositionArrayKey(key)) {
+    throw new Error(`Invalid array key ${key}. Must be "pos:xxxxx"`);
+  }
+
+  return key.split(POSITION_ARRAY_KEY_PREFIX)[1];
+};
+
+/* ID KEY */
+export const ID_PATH_KEY_PREFIX = 'id:';
+
+/**
+ * Checks if the given key is an ID array key.
+ * @param {unknown} key - The key to check.
+ * @returns {boolean} Returns true if `key` is an ID array key, false otherwise.
+ * @example
+ * isIdArrayKey('id:123');  // Returns true
+ * isIdArrayKey('pos:0');  // Returns false
+ */
+export const isIdArrayKey = (key: unknown): key is string => {
+  return isString(key) && key.startsWith(ID_PATH_KEY_PREFIX);
+};
+
+/**
+ * Creates an ID array key.
+ * @param {string} id - The ID to create the key for.
+ * @returns {string} Returns the created ID array key.
+ * @example
+ * createIdArrayKey('123');  // Returns 'id:123'
+ */
+export const createIdArrayKey = (id: string) => {
+  return `${ID_PATH_KEY_PREFIX}${id}`;
+};
+
+/**
+ * Extracts the ID from an ID array key.
+ * @param {string} key - The ID array key to extract the ID from.
+ * @returns {string} Returns the extracted ID.
+ * @example
+ * extractIdFromArrayKey('id:123');  // Returns '123'
+ */
+export const extractIdFromArrayKey = (key: string): string => {
+  if (!isIdArrayKey(key)) {
+    throw new Error(`Invalid array key ${key}. Must be "id:xxxxx"`);
+  }
+
+  return key.split(ID_PATH_KEY_PREFIX)[1];
+};
+
+/* ARRAY KEYS */
+
+/**
+ * Checks if the given key is an array key (either a position array key or an ID array key).
+ * @param {unknown} key - The key to check.
+ * @returns {boolean} Returns true if `key` is an array key, false otherwise.
+ * @example
+ * isArrayKey('id:123');  // Returns true
+ * isArrayKey('pos:0');  // Returns true
+ * isArrayKey('abc');  // Returns false
+ */
+export const isArrayKey = (key: unknown): key is string => isString(key) && (isPositionArrayKey(key) || isIdArrayKey(key));
+
+/**
+ * Extracts the index from an array key in a given array.
+ * @param {unknown} array - The array to extract the index from.
+ * @param {string} key - The array key to extract the index from.
+ * @returns {number} Returns the extracted index.
+ * @example
+ * getIndexByArrayKey(['a', 'b', 'c'], 'pos:1');  // Returns 1
+ */
+export const getIndexByArrayKey = (array: unknown, key: string): number => {
+  if (!Array.isArray(array)) {
+    console.error(`Non-array type`, array);
+
+    throw new Error(`Can't use array key in non array type (${key})`);
+  }
+
+  if (!isArrayKey(key)) {
+    throw new Error(`Unknown array key type (${key})`);
+  }
+
+  if (array.length === 0) {
+    return 0;
+  }
+
+  if (isIdArrayKey(key)) {
+    const id = extractIdFromArrayKey(key);
+    const index = array.findIndex((it) => isObject(it) && it.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 = array.findIndex((it) => it.position === position);
+    if (index === -1) {
+      throw new Error(`Can't find index by position ${position} (${key})`);
+    }
+
+    return index;
+  }
+
+  return 0;
+};