@twick/2d 0.11.0

package/src/lib/decorators/filtersSignal.ts

@@ -0,0 +1,136 @@
+import type {
+  Signal,
+  SignalValue,
+  SimpleSignal,
+  ThreadGenerator,
+  TimingFunction,
+} from '@twick/core';
+import {
+  SignalContext,
+  all,
+  deepLerp,
+  easeInOutCubic,
+  unwrap,
+} from '@twick/core';
+import type {FilterName} from '../partials';
+import {FILTERS, Filter} from '../partials';
+import {addInitializer} from './initializers';
+import {getPropertyMetaOrCreate} from './signal';
+
+export type FiltersSignal<TOwner> = Signal<
+  Filter[],
+  Filter[],
+  TOwner,
+  FiltersSignalContext<TOwner>
+> & {
+  [K in FilterName]: SimpleSignal<number, TOwner>;
+};
+
+export class FiltersSignalContext<TOwner> extends SignalContext<
+  Filter[],
+  Filter[],
+  TOwner
+> {
+  public constructor(initial: Filter[], owner: TOwner) {
+    super(initial, deepLerp, owner);
+
+    for (const filter in FILTERS) {
+      const props = FILTERS[filter];
+      Object.defineProperty(this.invokable, filter, {
+        value: (
+          newValue?: SignalValue<number>,
+          duration?: number,
+          timingFunction: TimingFunction = easeInOutCubic,
+        ) => {
+          if (newValue === undefined) {
+            return (
+              this.get()
+                ?.find(filter => filter.name === props.name)
+                ?.value() ??
+              props.default ??
+              0
+            );
+          }
+
+          let instance = this.get()?.find(filter => filter.name === props.name);
+          if (!instance) {
+            instance = new Filter(props);
+            this.set([...this.get(), instance]);
+          }
+
+          if (duration === undefined) {
+            instance.value(newValue);
+            return this.owner;
+          }
+
+          return instance.value(newValue, duration, timingFunction);
+        },
+      });
+    }
+  }
+
+  public override *tweener(
+    value: SignalValue<Filter[]>,
+    duration: number,
+    timingFunction: TimingFunction,
+  ): ThreadGenerator {
+    const from = this.get();
+    const to = unwrap(value);
+
+    if (areFiltersCompatible(from, to)) {
+      yield* all(
+        ...from.map((filter, i) =>
+          filter.value(to[i].value(), duration, timingFunction),
+        ),
+      );
+      this.set(to);
+      return;
+    }
+
+    for (const filter of to) {
+      filter.value(filter.default);
+    }
+
+    const toValues = to.map(filter => filter.value.context.raw());
+    const partialDuration =
+      from.length > 0 && to.length > 0 ? duration / 2 : duration;
+    if (from.length > 0) {
+      yield* all(
+        ...from.map(filter =>
+          filter.value(filter.default, partialDuration, timingFunction),
+        ),
+      );
+    }
+    this.set(to);
+    if (to.length > 0) {
+      yield* all(
+        ...to.map((filter, index) =>
+          filter.value(toValues[index]!, partialDuration, timingFunction),
+        ),
+      );
+    }
+  }
+}
+
+export function filtersSignal(): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMetaOrCreate<Filter[]>(target, key);
+    addInitializer(target, (instance: any) => {
+      instance[key] = new FiltersSignalContext(
+        meta.default ?? [],
+        instance,
+      ).toSignal();
+    });
+  };
+}
+
+function areFiltersCompatible(a: Filter[], b: Filter[]) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].name !== b[i].name) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/lib/decorators/index.ts

@@ -0,0 +1,10 @@
+export * from './canvasStyleSignal';
+export * from './colorSignal';
+export * from './compound';
+export * from './computed';
+export * from './defaultStyle';
+export * from './filtersSignal';
+export * from './initializers';
+export * from './nodeName';
+export * from './signal';
+export * from './vector2Signal';

package/src/lib/decorators/initializers.ts

@@ -0,0 +1,32 @@
+const INITIALIZERS = Symbol.for('@twick/2d/decorators/initializers');
+
+export type Initializer<T> = (instance: T, context?: any) => void;
+
+export function addInitializer<T>(target: any, initializer: Initializer<T>) {
+  if (!target[INITIALIZERS]) {
+    target[INITIALIZERS] = [];
+  } else if (
+    // if one of the prototypes has initializers
+    target[INITIALIZERS] &&
+    // and it's not the target object itself
+    !Object.prototype.hasOwnProperty.call(target, INITIALIZERS)
+  ) {
+    const base = Object.getPrototypeOf(target);
+    target[INITIALIZERS] = [...base[INITIALIZERS]];
+  }
+
+  target[INITIALIZERS].push(initializer);
+}
+
+export function initialize(target: any, context?: any) {
+  if (target[INITIALIZERS]) {
+    try {
+      target[INITIALIZERS].forEach((initializer: Initializer<any>) =>
+        initializer(target, context),
+      );
+    } catch (e: any) {
+      e.inspect ??= target.key;
+      throw e;
+    }
+  }
+}

package/src/lib/decorators/nodeName.ts

@@ -0,0 +1,13 @@
+/**
+ * @internal
+ */
+export const NODE_NAME = Symbol.for('@twick/2d/nodeName');
+
+/**
+ * @internal
+ */
+export function nodeName(name: string) {
+  return function (target: any) {
+    target.prototype[NODE_NAME] = name;
+  };
+}

package/src/lib/decorators/signal.test.ts

@@ -0,0 +1,90 @@
+import type {SimpleSignal} from '@twick/core';
+import {DEFAULT} from '@twick/core';
+import {beforeEach, describe, expect, test, vi} from 'vitest';
+import {initial, initializeSignals, parser, signal} from './signal';
+
+interface OwnerProps {
+  integer?: number;
+  custom?: number;
+}
+
+class Owner {
+  @initial(2.2)
+  @parser((value: number) => Math.round(value))
+  @signal()
+  public declare readonly integer: SimpleSignal<number>;
+
+  @initial(0)
+  @signal()
+  public declare readonly custom: SimpleSignal<number>;
+  public getCustom() {
+    return 4;
+  }
+  public setCustom() {
+    // do nothing
+  }
+
+  public constructor(props: OwnerProps = {}) {
+    initializeSignals(this, props);
+  }
+}
+
+const GetterMock = vi.spyOn(Owner.prototype, 'getCustom');
+const SetterMock = vi.spyOn(Owner.prototype, 'setCustom');
+
+describe('signal', () => {
+  beforeEach(() => {
+    GetterMock.mockClear();
+    SetterMock.mockClear();
+  });
+
+  test('Has initial value', () => {
+    const instance = new Owner();
+
+    expect(instance.integer()).toBe(2);
+    expect(instance.integer.isInitial()).toBe(true);
+  });
+
+  test('Overrides the value', () => {
+    const instance = new Owner({integer: 4});
+
+    expect(instance.integer()).toBe(4);
+    expect(instance.integer.isInitial()).toBe(false);
+  });
+
+  test('Resets the value to default', () => {
+    const instance = new Owner({integer: 4});
+    instance.integer(DEFAULT);
+
+    expect(instance.integer()).toBe(2);
+    expect(instance.integer.isInitial()).toBe(true);
+  });
+
+  test('Parses the value', () => {
+    const instance = new Owner();
+    instance.integer(2.7);
+
+    expect(instance.integer()).toBe(3);
+  });
+
+  test('Uses the custom getter', () => {
+    const instance = new Owner();
+    const value = instance.custom();
+
+    expect(value).toBe(4);
+    expect(GetterMock).toBeCalledTimes(1);
+  });
+
+  test('Calls the setter with the initial value', () => {
+    new Owner();
+
+    expect(SetterMock).toBeCalledWith(0);
+  });
+
+  test('Uses the setter', () => {
+    const instance = new Owner({custom: 1});
+    instance.custom(2);
+
+    expect(SetterMock).toBeCalledTimes(3);
+  });
+});

package/src/lib/decorators/signal.ts

@@ -0,0 +1,345 @@
+import type {
+  InterpolationFunction,
+  SignalValue,
+  TimingFunction,
+} from '@twick/core';
+import {capitalize, deepLerp, SignalContext, useLogger} from '@twick/core';
+import {makeSignalExtensions} from '../utils/makeSignalExtensions';
+import {addInitializer, initialize} from './initializers';
+
+export interface PropertyMetadata<T> {
+  default?: T;
+  interpolationFunction?: InterpolationFunction<T>;
+  parser?: (value: any) => T;
+  getter?: () => T;
+  setter?: (value: any) => void;
+  tweener?: (
+    value: T,
+    duration: number,
+    timingFunction: TimingFunction,
+    interpolationFunction: InterpolationFunction<T>,
+  ) => void;
+  cloneable?: boolean;
+  inspectable?: boolean;
+  compoundParent?: string;
+  compound?: boolean;
+  compoundEntries: [string, string][];
+}
+
+const PROPERTIES = Symbol.for('@twick/2d/decorators/properties');
+
+export function getPropertyMeta<T>(
+  object: any,
+  key: string | symbol,
+): PropertyMetadata<T> | null {
+  return object[PROPERTIES]?.[key] ?? null;
+}
+
+export function getPropertyMetaOrCreate<T>(
+  object: any,
+  key: string | symbol,
+): PropertyMetadata<T> {
+  let lookup: Record<string | symbol, PropertyMetadata<T>>;
+  if (!object[PROPERTIES]) {
+    object[PROPERTIES] = lookup = {};
+  } else if (
+    object[PROPERTIES] &&
+    !Object.prototype.hasOwnProperty.call(object, PROPERTIES)
+  ) {
+    object[PROPERTIES] = lookup = Object.fromEntries<PropertyMetadata<T>>(
+      Object.entries(
+        <Record<string | symbol, PropertyMetadata<T>>>object[PROPERTIES],
+      ).map(([key, meta]) => [key, {...meta}]),
+    );
+  } else {
+    lookup = object[PROPERTIES];
+  }
+
+  lookup[key] ??= {
+    cloneable: true,
+    inspectable: true,
+    compoundEntries: [],
+  };
+  return lookup[key];
+}
+
+export function getPropertiesOf(
+  value: any,
+): Record<string, PropertyMetadata<any>> {
+  if (value && typeof value === 'object') {
+    return value[PROPERTIES] ?? {};
+  }
+
+  return {};
+}
+
+export function initializeSignals(instance: any, props: Record<string, any>) {
+  initialize(instance);
+  for (const [key, meta] of Object.entries(getPropertiesOf(instance))) {
+    const signal = instance[key];
+    signal.reset();
+    if (props[key] !== undefined) {
+      signal(props[key]);
+    }
+    if (meta.compoundEntries !== undefined) {
+      for (const [key, property] of meta.compoundEntries) {
+        if (property in props) {
+          signal[key](props[property]);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Create a signal decorator.
+ *
+ * @remarks
+ * This decorator turns the given property into a signal.
+ *
+ * The class using this decorator can implement the following methods:
+ * - `get[PropertyName]` - A property getter.
+ * - `get[PropertyName]` - A property setter.
+ * - `tween[PropertyName]` - A tween provider.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@property()
+ *   public declare length: Signal<number, this>;
+ * }
+ * ```
+ */
+export function signal<T>(): PropertyDecorator {
+  return (target: any, key) => {
+    // FIXME property metadata is not inherited
+    // Consider retrieving it inside the initializer using the instance and not
+    // the class.
+    const meta = getPropertyMetaOrCreate<T>(target, key);
+    addInitializer(target, (instance: any) => {
+      let initial: SignalValue<T> = meta.default!;
+      const defaultMethod = instance[`getDefault${capitalize(key as string)}`];
+      if (defaultMethod) {
+        initial = () => defaultMethod.call(instance, meta.default);
+      }
+
+      const signal = new SignalContext<T, T, any>(
+        initial,
+        meta.interpolationFunction ?? deepLerp,
+        instance,
+        meta.parser?.bind(instance),
+        makeSignalExtensions(meta, instance, <string>key),
+      );
+      instance[key] = signal.toSignal();
+    });
+  };
+}
+
+/**
+ * Create an initial signal value decorator.
+ *
+ * @remarks
+ * This decorator specifies the initial value of a property.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@initial(1)
+ *   \@property()
+ *   public declare length: Signal<number, this>;
+ * }
+ * ```
+ *
+ * @param value - The initial value of the property.
+ */
+export function initial<T>(value: T): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.default = value;
+  };
+}
+
+/**
+ * Create a signal interpolation function decorator.
+ *
+ * @remarks
+ * This decorator specifies the interpolation function of a property.
+ * The interpolation function is used when tweening between different values.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@interpolation(textLerp)
+ *   \@property()
+ *   public declare text: Signal<string, this>;
+ * }
+ * ```
+ *
+ * @param value - The interpolation function for the property.
+ */
+export function interpolation<T>(
+  value: InterpolationFunction<T>,
+): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.interpolationFunction = value;
+  };
+}
+
+/**
+ * Create a signal parser decorator.
+ *
+ * @remarks
+ * This decorator specifies the parser of a property.
+ * Instead of returning the raw value, its passed as the first parameter to the
+ * parser and the resulting value is returned.
+ *
+ * If the wrapper class has a method called `lerp` it will be set as the
+ * default interpolation function for the property.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@wrapper(Vector2)
+ *   \@property()
+ *   public declare offset: Signal<Vector2, this>;
+ * }
+ * ```
+ *
+ * @param value - The wrapper class for the property.
+ */
+export function parser<T>(value: (value: any) => T): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.parser = value;
+  };
+}
+
+/**
+ * Create a signal wrapper decorator.
+ *
+ * @remarks
+ * This is a shortcut decorator for setting both the {@link parser} and
+ * {@link interpolation}.
+ *
+ * The interpolation function will be set only if the wrapper class has a method
+ * called `lerp`, which will be used as said function.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@wrapper(Vector2)
+ *   \@property()
+ *   public declare offset: Signal<Vector2, this>;
+ *
+ *   // same as:
+ *   \@parser(value => new Vector2(value))
+ *   \@interpolation(Vector2.lerp)
+ *   \@property()
+ *   public declare offset: Signal<Vector2, this>;
+ * }
+ * ```
+ *
+ * @param value - The wrapper class for the property.
+ */
+export function wrapper<T>(
+  value: (new (value: any) => T) & {lerp?: InterpolationFunction<T>},
+): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.parser = raw => new value(raw);
+    if ('lerp' in value) {
+      meta.interpolationFunction ??= value.lerp;
+    }
+  };
+}
+
+/**
+ * Create a cloneable property decorator.
+ *
+ * @remarks
+ * This decorator specifies whether the property should be copied over when
+ * cloning the node.
+ *
+ * By default, any property is cloneable.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@clone(false)
+ *   \@property()
+ *   public declare length: Signal<number, this>;
+ * }
+ * ```
+ *
+ * @param value - Whether the property should be cloneable.
+ */
+export function cloneable<T>(value = true): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.cloneable = value;
+  };
+}
+
+/**
+ * Create an inspectable property decorator.
+ *
+ * @remarks
+ * This decorator specifies whether the property should be visible in the
+ * inspector.
+ *
+ * By default, any property is inspectable.
+ *
+ * Must be specified before the {@link signal} decorator.
+ *
+ * @example
+ * ```ts
+ * class Example {
+ *   \@inspectable(false)
+ *   \@property()
+ *   public declare hiddenLength: Signal<number, this>;
+ * }
+ * ```
+ *
+ * @param value - Whether the property should be inspectable.
+ */
+export function inspectable<T>(value = true): PropertyDecorator {
+  return (target: any, key) => {
+    const meta = getPropertyMeta<T>(target, key);
+    if (!meta) {
+      useLogger().error(`Missing property decorator for "${key.toString()}"`);
+      return;
+    }
+    meta.inspectable = value;
+  };
+}

package/src/lib/decorators/spacingSignal.ts

@@ -0,0 +1,15 @@
+import {Spacing} from '@twick/core';
+import {compound} from './compound';
+import {wrapper} from './signal';
+
+export function spacingSignal(prefix?: string): PropertyDecorator {
+  return (target, key) => {
+    compound({
+      top: prefix ? `${prefix}Top` : 'top',
+      right: prefix ? `${prefix}Right` : 'right',
+      bottom: prefix ? `${prefix}Bottom` : 'bottom',
+      left: prefix ? `${prefix}Left` : 'left',
+    })(target, key);
+    wrapper(Spacing)(target, key);
+  };
+}

package/src/lib/decorators/vector2Signal.ts

@@ -0,0 +1,30 @@
+import type {PossibleVector2, Signal} from '@twick/core';
+import {Vector2} from '@twick/core';
+import type {Length} from '../partials';
+import {compound} from './compound';
+import {wrapper} from './signal';
+
+export type Vector2LengthSignal<TOwner> = Signal<
+  PossibleVector2<Length>,
+  Vector2,
+  TOwner
+> & {
+  x: Signal<Length, number, TOwner>;
+  y: Signal<Length, number, TOwner>;
+};
+
+export function vector2Signal(
+  prefix?: string | Record<string, string>,
+): PropertyDecorator {
+  return (target, key) => {
+    compound(
+      typeof prefix === 'object'
+        ? prefix
+        : {
+            x: prefix ? `${prefix}X` : 'x',
+            y: prefix ? `${prefix}Y` : 'y',
+          },
+    )(target, key);
+    wrapper(Vector2)(target, key);
+  };
+}

package/src/lib/globals.d.ts

@@ -0,0 +1,2 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/// <reference types="@twick/core/project" />

package/src/lib/index.ts

@@ -0,0 +1,8 @@
+export * from './code';
+export * from './components';
+export * from './curves';
+export * from './decorators';
+export * from './jsx-runtime';
+export * from './partials';
+export * from './scenes';
+export * from './utils';

package/src/lib/jsx-dev-runtime.ts

@@ -0,0 +1,2 @@
+import {Fragment, jsx} from './jsx-runtime';
+export {Fragment, jsx as jsxDEV};