@twick/2d 0.11.0

package/src/lib/code/CodeFragment.ts

@@ -0,0 +1,97 @@
+import type {CodeMetrics} from './CodeMetrics';
+import {isCodeMetrics, measureString} from './CodeMetrics';
+
+export interface CodeFragment {
+  before: CodeMetrics;
+  after: CodeMetrics;
+}
+export interface RawCodeFragment {
+  before: string;
+  after: string;
+}
+
+export type PossibleCodeFragment =
+  | CodeFragment
+  | CodeMetrics
+  | RawCodeFragment
+  | string;
+
+export function metricsToFragment(value: CodeMetrics): CodeFragment {
+  return {
+    before: value,
+    after: value,
+  };
+}
+
+export function parseCodeFragment(
+  value: PossibleCodeFragment,
+  context: CanvasRenderingContext2D,
+  monoWidth: number,
+): CodeFragment {
+  let fragment: CodeFragment;
+  if (typeof value === 'string') {
+    fragment = metricsToFragment(measureString(context, monoWidth, value));
+  } else if (isCodeMetrics(value)) {
+    fragment = metricsToFragment(value);
+  } else {
+    fragment = {
+      before:
+        typeof value.before === 'string'
+          ? measureString(context, monoWidth, value.before)
+          : value.before,
+      after:
+        typeof value.after === 'string'
+          ? measureString(context, monoWidth, value.after)
+          : value.after,
+    };
+  }
+
+  return fragment;
+}
+
+/**
+ * Create a code fragment that represents an insertion of code.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param code - The code to insert.
+ */
+export function insert(code: string): RawCodeFragment {
+  return {
+    before: '',
+    after: code,
+  };
+}
+
+/**
+ * Create a code fragment that represents a change from one piece of code to
+ * another.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param before - The code to change from.
+ * @param after - The code to change to.
+ */
+export function replace(before: string, after: string): RawCodeFragment {
+  return {
+    before,
+    after,
+  };
+}
+
+/**
+ * Create a code fragment that represents a removal of code.
+ *
+ * @remarks
+ * Can be used in conjunction with {@link code.CodeSignalHelpers.edit}.
+ *
+ * @param code - The code to remove.
+ */
+export function remove(code: string): RawCodeFragment {
+  return {
+    before: code,
+    after: '',
+  };
+}

package/src/lib/code/CodeHighlighter.ts

@@ -0,0 +1,75 @@
+/**
+ * Describes the result of a highlight operation.
+ */
+export interface HighlightResult {
+  /**
+   * The color of the code at the given index.
+   */
+  color: string | null;
+
+  /**
+   * The number of characters to skip ahead.
+   *
+   * @remarks
+   * This should be used to skip to the end of the currently highlighted token.
+   * The returned style will be used for the skipped characters, and they will
+   * be drawn as one continuous string keeping emojis and ligatures intact.
+   *
+   * The returned value is the number of characters to skip ahead, not the
+   * index of the end of the token.
+   */
+  skipAhead: number;
+}
+
+/**
+ * Describes custom highlighters used by the Code node.
+ *
+ * @typeParam T - The type of the cache used by the highlighter.
+ */
+export interface CodeHighlighter<T = unknown> {
+  /**
+   * Initializes the highlighter.
+   *
+   * @remarks
+   * This method is called when collecting async resources for the node.
+   * It can be called multiple times so caching the initialization is
+   * recommended.
+   *
+   * If initialization is asynchronous, a promise should be registered using
+   * {@link DependencyContext.collectPromise} and the value of `false` should
+   * be returned. The hook will be called again when the promise resolves.
+   * This process can be repeated until the value of `true` is returned which
+   * will mark the highlighter as ready.
+   */
+  initialize(): boolean;
+
+  /**
+   * Prepares the code for highlighting.
+   *
+   * @remarks
+   * This method is called each time the code changes. It can be used to do
+   * any preprocessing of the code before highlighting. The result of this
+   * method is cached and passed to {@link highlight} when the code is
+   * highlighted.
+   *
+   * @param code - The code to prepare.
+   * @param dialect - The language in which the code is written.
+   */
+  prepare(code: string): T;
+
+  /**
+   * Highlights the code at the given index.
+   *
+   * @param index - The index of the code to highlight.
+   * @param cache - The result of {@link prepare}.
+   */
+  highlight(index: number, cache: T): HighlightResult;
+
+  /**
+   * Tokenize the code.
+   *
+   * @param code - The code to tokenize.
+   * @param dialect - The language in which the code is written.
+   */
+  tokenize(code: string): string[];
+}

package/src/lib/code/CodeMetrics.ts

@@ -0,0 +1,47 @@
+export interface CodeMetrics {
+  content: string;
+  newRows: number;
+  endColumn: number;
+  firstWidth: number;
+  maxWidth: number;
+  lastWidth: number;
+}
+
+export function measureString(
+  context: CanvasRenderingContext2D,
+  monoWidth: number,
+  value: string,
+): CodeMetrics {
+  const lines = value.split('\n');
+  const lastLine = lines[lines.length - 1];
+  const firstWidth = Math.round(
+    context.measureText(lines[0]).width / monoWidth,
+  );
+  let lastWidth = firstWidth;
+  let maxWidth = firstWidth;
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    const width = Math.round(context.measureText(line).width / monoWidth);
+    if (width > maxWidth) {
+      maxWidth = width;
+    }
+  }
+
+  if (lines.length > 0) {
+    lastWidth = Math.round(context.measureText(lastLine).width / monoWidth);
+  }
+
+  return {
+    content: value,
+    newRows: lines.length - 1,
+    endColumn: lastLine.length,
+    firstWidth,
+    maxWidth,
+    lastWidth,
+  };
+}
+
+export function isCodeMetrics(value: any): value is CodeMetrics {
+  return value?.content !== undefined;
+}

package/src/lib/code/CodeRange.test.ts

@@ -0,0 +1,74 @@
+import {describe, expect, test} from 'vitest';
+import {
+  consolidateCodeRanges,
+  inverseCodeRange,
+  isPointInCodeRange,
+  pointToPoint,
+} from './CodeRange';
+
+describe('CodeRange', () => {
+  test('should detect ranges', () => {
+    expect(
+      isPointInCodeRange([50, 50], pointToPoint(0, 0, 100, 100)),
+      'Should work within both ranges',
+    ).toBeTruthy();
+    expect(
+      isPointInCodeRange([50, 1000], pointToPoint(0, 0, 100, 100)),
+      'Should accept any column when within lines',
+    ).toBeTruthy();
+    expect(
+      isPointInCodeRange([50, 50], pointToPoint(0, 0, Infinity, Infinity)),
+      'Should work with infinity',
+    ).toBeTruthy();
+    expect(
+      isPointInCodeRange([100, 100], pointToPoint(0, 0, 100, 100)),
+      'Should reject points on the outer edge',
+    ).toBeFalsy();
+  });
+
+  test('should consolidate ranges that are completely contained', () => {
+    expect(
+      consolidateCodeRanges([
+        pointToPoint(0, 0, 100, 100),
+        pointToPoint(20, 0, 50, 0),
+      ]),
+    ).toEqual([pointToPoint(0, 0, 100, 100)]);
+    expect(
+      consolidateCodeRanges([
+        pointToPoint(20, 0, 50, 0),
+        pointToPoint(0, 0, 100, 100),
+      ]),
+    ).toEqual([pointToPoint(0, 0, 100, 100)]);
+  });
+
+  test('should combine ranges that overlap', () => {
+    expect(
+      consolidateCodeRanges([
+        pointToPoint(0, 5, 0, 10),
+        pointToPoint(0, 7, 0, 13),
+      ]),
+    ).toEqual([pointToPoint(0, 5, 0, 13)]);
+    expect(
+      consolidateCodeRanges([
+        pointToPoint(0, 7, 2, 13),
+        pointToPoint(0, 5, 2, 10),
+      ]),
+    ).toEqual([pointToPoint(0, 5, 2, 13)]);
+  });
+
+  test('should not combine ranges that do not overlap', () => {
+    expect(
+      consolidateCodeRanges([
+        pointToPoint(0, 5, 0, 10),
+        pointToPoint(0, 7, 0, 13),
+        pointToPoint(1, 5, 1, 10),
+      ]),
+    ).toEqual([pointToPoint(0, 5, 0, 13), pointToPoint(1, 5, 1, 10)]);
+  });
+
+  test('should invert empty ranges', () => {
+    expect(inverseCodeRange([])).toEqual([
+      pointToPoint(0, 0, Infinity, Infinity),
+    ]);
+  });
+});

package/src/lib/code/CodeRange.ts

@@ -0,0 +1,216 @@
+export type CodePoint = [number, number];
+
+function isCodePoint(value: unknown): value is CodePoint {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === 'number' &&
+    typeof value[1] === 'number'
+  );
+}
+
+export type CodeRange = [CodePoint, CodePoint];
+
+export function isCodeRange(value: unknown): value is CodeRange {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    isCodePoint(value[0]) &&
+    isCodePoint(value[1])
+  );
+}
+
+/**
+ * Create a code range that spans the given lines.
+ *
+ * @param from - The line from which the range starts.
+ * @param to - The line at which the range ends. If omitted, the range will
+ *             cover only one line.
+ */
+export function lines(from: number, to?: number): CodeRange {
+  return [
+    [from, 0],
+    [to ?? from, Infinity],
+  ];
+}
+
+/**
+ * Create a code range that highlights the given word.
+ *
+ * @param line - The line at which the word appears.
+ * @param from - The column at which the word starts.
+ * @param length - The length of the word. If omitted, the range will cover the
+ *                 rest of the line.
+ */
+export function word(line: number, from: number, length?: number): CodeRange {
+  return [
+    [line, from],
+    [line, from + (length ?? Infinity)],
+  ];
+}
+
+/**
+ * Create a custom selection range.
+ *
+ * @param startLine - The line at which the selection starts.
+ * @param startColumn - The column at which the selection starts.
+ * @param endLine - The line at which the selection ends.
+ * @param endColumn - The column at which the selection ends.
+ */
+export function pointToPoint(
+  startLine: number,
+  startColumn: number,
+  endLine: number,
+  endColumn: number,
+): CodeRange {
+  return [
+    [startLine, startColumn],
+    [endLine, endColumn],
+  ];
+}
+
+export function isPointInCodeRange(point: CodePoint, range: CodeRange) {
+  const [y, x] = point;
+  const [[startLine, startColumn], [endLine, endColumn]] = range;
+  return (
+    ((y === startLine && x >= startColumn) || y > startLine) &&
+    ((y === endLine && x < endColumn) || y < endLine)
+  );
+}
+
+export function consolidateCodeRanges(ranges: CodeRange[]): CodeRange[] {
+  // Sort by start position
+  ranges.sort((a, b) => {
+    const lines = b[0][0] - a[0][0];
+    // Break ties on start column
+    if (lines === 0) {
+      return b[0][1] - a[0][1];
+    }
+    return lines;
+  });
+
+  const staged: CodeRange[] = [...ranges];
+  const results = [];
+  while (staged.length > 0) {
+    let current = staged.pop();
+    if (!current) {
+      continue;
+    }
+    const [[initStartLine, initStartColumn], [initEndLine, initEndColumn]] =
+      current;
+
+    for (const targetRange of staged) {
+      const [
+        [targetStartLine, targetStartColumn],
+        [targetEndLine, targetEndColumn],
+      ] = targetRange;
+      if (
+        isPointInCodeRange(targetRange[0], current) ||
+        isPointInCodeRange(targetRange[1], current)
+      ) {
+        staged.pop();
+
+        let startColumn;
+        if (initStartLine === targetStartLine) {
+          startColumn = Math.min(initStartColumn, targetStartColumn);
+        } else if (initStartLine < targetStartLine) {
+          startColumn = initStartColumn;
+        } else {
+          startColumn = targetStartColumn;
+        }
+
+        let endColumn;
+        if (initEndLine === targetEndLine) {
+          endColumn = Math.max(initEndColumn, targetEndColumn);
+        } else if (initEndLine > targetEndLine) {
+          endColumn = initEndColumn;
+        } else {
+          endColumn = targetEndColumn;
+        }
+        // Update the current to the consolidated one and get rid of the
+        // remaining instance of the unconsolidated target
+        current = [
+          [Math.min(initStartLine, targetStartLine), startColumn],
+          [Math.max(initEndLine, targetEndLine), endColumn],
+        ];
+      }
+    }
+    results.push(current);
+  }
+  return results;
+}
+
+export function inverseCodeRange(ranges: CodeRange[]): CodeRange[] {
+  if (ranges.length === 0) {
+    return [
+      [
+        [0, 0],
+        [Infinity, Infinity],
+      ],
+    ];
+  }
+  const firstRange = ranges[0];
+  const result: CodeRange[] = [];
+  for (let first = 0; first < ranges.length - 1; first++) {
+    const range1 = ranges[first];
+    const range2 = ranges[first + 1];
+    result.push([range1[1], range2[0]]);
+  }
+  const lastRange = ranges.slice(-1)[0];
+  return [
+    [[0, 0], firstRange[0]],
+    ...result,
+    [lastRange[1], [Infinity, Infinity]],
+  ];
+}
+
+/**
+ * Find all code ranges that match the given pattern.
+ *
+ * @param code - The code to search in.
+ * @param pattern - Either a string or a regular expression to search for.
+ * @param limit - An optional limit on the number of ranges to find.
+ */
+export function findAllCodeRanges(
+  code: string,
+  pattern: string | RegExp,
+  limit = Infinity,
+): CodeRange[] {
+  if (typeof pattern === 'string') {
+    pattern = new RegExp(pattern, 'g');
+  }
+
+  const matches = code.matchAll(pattern);
+  const ranges: CodeRange[] = [];
+  let index = 0;
+  let line = 0;
+  let column = 0;
+
+  for (const match of matches) {
+    if (match.index === undefined || ranges.length >= limit) {
+      continue;
+    }
+
+    let from: CodePoint = [line, column];
+    while (index <= code.length) {
+      if (index === match.index) {
+        from = [line, column];
+      }
+
+      if (index === match.index + match[0].length) {
+        ranges.push([from, [line, column]]);
+        break;
+      }
+
+      if (code[index] === '\n') {
+        line++;
+        column = 0;
+      } else {
+        column++;
+      }
+      index++;
+    }
+  }
+
+  return ranges;
+}

package/src/lib/code/CodeScope.ts

@@ -0,0 +1,101 @@
+import type {SignalValue} from '@twick/core';
+import {unwrap} from '@twick/core';
+import type {PossibleCodeFragment} from './CodeFragment';
+import {isCodeMetrics} from './CodeMetrics';
+
+export interface CodeScope {
+  progress: SignalValue<number>;
+  fragments: CodeTag[];
+}
+
+export type PossibleCodeScope = CodeScope | CodeTag[] | string;
+
+export type CodeTag = SignalValue<PossibleCodeFragment | CodeScope | CodeTag[]>;
+
+export function CODE(
+  strings: TemplateStringsArray,
+  ...tags: CodeTag[]
+): CodeTag[] {
+  const result: CodeTag[] = [];
+  for (let i = 0; i < strings.length; i++) {
+    result.push(strings[i]);
+    const tag = tags[i];
+    if (tag !== undefined) {
+      if (Array.isArray(tag)) {
+        result.push(...tag);
+      } else {
+        result.push(tag);
+      }
+    }
+  }
+
+  return result;
+}
+
+export function isCodeScope(value: any): value is CodeScope {
+  return value?.fragments !== undefined;
+}
+
+export function parseCodeScope(value: PossibleCodeScope): CodeScope {
+  if (typeof value === 'string') {
+    return {
+      progress: 0,
+      fragments: [value],
+    };
+  }
+
+  if (Array.isArray(value)) {
+    return {
+      progress: 0,
+      fragments: value,
+    };
+  }
+
+  return value;
+}
+
+type IsAfterPredicate = ((scope: CodeScope) => boolean) | boolean;
+
+export function resolveScope(
+  scope: CodeScope,
+  isAfter: IsAfterPredicate,
+): string {
+  let code = '';
+  const after = typeof isAfter === 'boolean' ? isAfter : isAfter(scope);
+  for (const wrapped of scope.fragments) {
+    code += resolveCodeTag(wrapped, after, isAfter);
+  }
+
+  return code;
+}
+
+export function resolveCodeTag(
+  wrapped: CodeTag,
+  after: boolean,
+  isAfter: IsAfterPredicate = after,
+) {
+  const fragment = unwrap(wrapped);
+  if (typeof fragment === 'string') {
+    return fragment;
+  } else if (isCodeScope(fragment)) {
+    return resolveScope(fragment, isAfter);
+  } else if (isCodeMetrics(fragment)) {
+    return fragment.content;
+  } else if (Array.isArray(fragment)) {
+    return resolveScope(
+      {
+        progress: 0,
+        fragments: fragment,
+      },
+      isAfter,
+    );
+  } else {
+    return after
+      ? typeof fragment.after === 'string'
+        ? fragment.after
+        : fragment.after.content
+      : typeof fragment.before === 'string'
+        ? fragment.before
+        : fragment.before.content;
+  }
+}

package/src/lib/code/CodeSelection.ts

@@ -0,0 +1,24 @@
+import type {CodePoint, CodeRange} from './CodeRange';
+import {isCodeRange, isPointInCodeRange} from './CodeRange';
+
+export type CodeSelection = CodeRange[];
+export type PossibleCodeSelection = CodeRange | CodeRange[];
+
+export function parseCodeSelection(
+  value: PossibleCodeSelection,
+): CodeSelection {
+  return isCodeRange(value) ? [value] : value;
+}
+
+export function isPointInCodeSelection(
+  point: CodePoint,
+  selection: CodeSelection,
+) {
+  for (const range of selection) {
+    if (isPointInCodeRange(point, range)) {
+      return true;
+    }
+  }
+
+  return false;
+}