js-draw 0.25.1 → 1.0.1

package/src/util/ReactiveValue.test.ts

@@ -0,0 +1,168 @@
+import { ReactiveValue, MutableReactiveValue } from './ReactiveValue';
+
+describe('ReactiveValue', () => {
+	it('should fire update listeners on update', () => {
+		const value = ReactiveValue.fromInitialValue(3);
+		const listener = jest.fn();
+		const { remove: removeListener } = value.onUpdateAndNow(listener);
+
+		expect(listener).toHaveBeenCalledWith(3);
+		expect(listener).toHaveBeenCalledTimes(1);
+
+		value.set(2);
+
+		expect(listener).toHaveBeenLastCalledWith(2);
+		expect(listener).toHaveBeenCalledTimes(2);
+
+		removeListener();
+
+		value.set(4);
+		expect(listener).toHaveBeenCalledTimes(2);
+
+		// Should be able to call remove multiple times without error.
+		removeListener();
+		value.set(6);
+	});
+
+	it('values from callbacks should derive values from the callback', () => {
+		const sourceValue1 = ReactiveValue.fromInitialValue('test');
+		const sourceValue2 = ReactiveValue.fromInitialValue('test2');
+		const sourceValue3 = ReactiveValue.fromImmutable(3);
+
+		// Create a value that is computed from the three above values.
+		const derivedValue1 = ReactiveValue.fromCallback(() => {
+			return [
+				sourceValue1.get(),
+				sourceValue2.get(),
+				sourceValue3.get(),
+			].join(',');
+		}, [ sourceValue1, sourceValue2, sourceValue3 ]);
+
+		const derivedValue1Listener = jest.fn();
+		derivedValue1.onUpdate(derivedValue1Listener);
+
+		expect(derivedValue1.get()).toBe('test,test2,3');
+		expect(derivedValue1Listener).toHaveBeenCalledTimes(0);
+
+		// Create a value that is computed just from derivedValue1
+		const derivedValue2 = ReactiveValue.fromCallback(() => {
+			return derivedValue1.get() + '!';
+		}, [ derivedValue1 ]);
+
+		const derivedValue2Listener = jest.fn();
+		derivedValue2.onUpdate(derivedValue2Listener);
+
+		expect(derivedValue2.get()).toBe('test,test2,3!');
+		expect(derivedValue1Listener).toHaveBeenCalledTimes(0);
+		expect(derivedValue2Listener).toHaveBeenCalledTimes(0);
+
+		// Changing the source values should update the derived values
+		sourceValue1.set('...');
+
+		// The change should trigger the listeners
+		expect(derivedValue1Listener).toHaveBeenCalledTimes(1);
+		expect(derivedValue1Listener).toHaveBeenCalledWith(derivedValue1.get());
+		expect(derivedValue2Listener).toHaveBeenCalledTimes(1);
+		expect(derivedValue2Listener).toHaveBeenCalledWith(derivedValue2.get());
+
+		// The values should be updated to the expected values.
+		expect(derivedValue1.get()).toBe('...,test2,3');
+		expect(derivedValue2.get()).toBe('...,test2,3!');
+
+		// Something similar should happen when other values are changed
+		sourceValue1.set('1');
+		sourceValue2.set('2');
+
+		expect(derivedValue1.get()).toBe('1,2,3');
+		expect(derivedValue2.get()).toBe('1,2,3!');
+	});
+
+	it('should be able to create values from properties', () => {
+		const sourceValue = ReactiveValue.fromInitialValue({
+			a: 1,
+			b: 2,
+			c: { d: 3 },
+		});
+
+		const destValue1 = MutableReactiveValue.fromProperty(sourceValue, 'c');
+		const destValue2 = MutableReactiveValue.fromProperty(sourceValue, 'b');
+		expect(destValue1.get()).toBe(sourceValue.get().c);
+		expect(destValue2.get()).toBe(2);
+
+		// Updating the source value should update the destination values.
+		sourceValue.set({
+			...sourceValue.get(),
+			c: { d: 4 },
+		});
+
+		expect(destValue1.get()).toBe(sourceValue.get().c);
+		expect(destValue1.get().d).toBe(4);
+		expect(destValue2.get()).toBe(2);
+
+		sourceValue.set({
+			a: 3,
+			b: 4,
+			c: { d: 5 },
+		});
+		expect(destValue1.get().d).toBe(5);
+		expect(destValue2.get()).toBe(4);
+
+		// Updating the destination values should update the source values
+		destValue1.set({ d: 8 });
+		expect(sourceValue.get().c.d).toBe(8);
+
+		destValue2.set(5);
+		expect(sourceValue.get().b).toBe(5);
+	});
+
+	it('mutable map should be bidirectional', () => {
+		const sourceValue = ReactiveValue.fromInitialValue(5);
+		const mappedValue = MutableReactiveValue.map(
+			sourceValue, a => a ** 2, b => Math.sqrt(b),
+		);
+
+		expect(mappedValue.get()).toBeCloseTo(25);
+
+		// Changing the destination should change the source
+		mappedValue.set(26);
+		expect(sourceValue.get()).toBeCloseTo(Math.sqrt(26));
+
+		// Changing the source should change the destination
+		sourceValue.set(10);
+		expect(mappedValue.get()).toBeCloseTo(100);
+	});
+
+	it('single-directional map should apply the given mapping function', () => {
+		const sourceValue = ReactiveValue.fromInitialValue(1);
+		const midValue = ReactiveValue.map(sourceValue, a => a * 2);
+		const destValue = ReactiveValue.map(midValue, _ => 0);
+
+		const sourceUpdateFn = jest.fn();
+		const midUpdateFn = jest.fn();
+		const destUpdateFn = jest.fn();
+
+		sourceValue.onUpdate(sourceUpdateFn);
+		midValue.onUpdate(midUpdateFn);
+		destValue.onUpdate(destUpdateFn);
+
+		// Initial value checking
+		expect(destValue.get()).toBe(0);
+		expect(sourceUpdateFn).toHaveBeenCalledTimes(0);
+		expect(midUpdateFn).toHaveBeenCalledTimes(0);
+		expect(destUpdateFn).toHaveBeenCalledTimes(0);
+
+		// Setting to the same value should trigger no listeners
+		sourceValue.set(1);
+		expect(sourceUpdateFn).toHaveBeenCalledTimes(0);
+		expect(midUpdateFn).toHaveBeenCalledTimes(0);
+		expect(destUpdateFn).toHaveBeenCalledTimes(0);
+
+		// Changing the initial value should only fire listeners that
+		// result in a different value
+		sourceValue.set(2);
+		expect(sourceUpdateFn).toHaveBeenCalledTimes(1);
+		expect(midUpdateFn).toHaveBeenCalledTimes(1);
+		expect(destUpdateFn).toHaveBeenCalledTimes(0);
+		expect(midValue.get()).toBe(4);
+	});
+});

package/src/util/ReactiveValue.ts

@@ -0,0 +1,241 @@
+
+type ListenerResult = { remove(): void; };
+type UpdateCallback<T> = (value: T)=>void;
+
+const noOpUpdateListenerResult = {
+	remove() { }
+};
+
+/**
+ * An update listener that does nothing. Useful for reactive values
+ * that will never change.
+ */
+const noOpSetUpdateListener = () => {
+	return noOpUpdateListenerResult;
+};
+
+/**
+ * A `ReactiveValue` is a value that
+ * - updates periodically,
+ * - can fire listeners when it updates,
+ * - and can be chanined together with other `ReactiveValue`s.
+ *
+ * A `ReactiveValue` is a read-only view. See {@link MutableReactiveValue} for a
+ * read-write view.
+ *
+ * Static methods in the `ReactiveValue` and `MutableReactiveValue` classes are
+ * constructors (e.g. `fromImmutable`).
+ */
+export abstract class ReactiveValue<T> {
+	/**
+	 * Returns a reference to the current value of this `ReactiveValue`.
+	 *
+	 * The result of this **should not be modified** (use `setValue` instead).
+	 */
+	public abstract get(): T;
+
+	/**
+	 * Registers a listener that is notified when the value of this changes.
+	 */
+	public abstract onUpdate(listener: UpdateCallback<T>): ListenerResult;
+
+	/**
+	 * Calls `callback` immediately, then registers `callback` as an onUpdateListener.
+	 *
+	 * @see {@link onUpdate}.
+	 */
+	public abstract onUpdateAndNow(callback: UpdateCallback<T>): ListenerResult;
+
+	/** Creates a `ReactiveValue` with an initial value, `initialValue`. */
+	public static fromInitialValue<T> (
+		initialValue: T
+	): MutableReactiveValue<T>{
+		return new ReactiveValueImpl(initialValue);
+	}
+
+	/** Returns a `ReactiveValue` that is **known** will never change. */
+	public static fromImmutable<T> (
+		value: T
+	): ReactiveValue<T>{
+		return {
+			get: () => value,
+			onUpdate: noOpSetUpdateListener,
+			onUpdateAndNow: callback => {
+				callback(value);
+				return noOpUpdateListenerResult;
+			},
+		};
+	}
+
+	/**
+	 * Creates a `ReactiveValue` whose values come from `callback`.
+	 *
+	 * `callback` is called whenever any of `sourceValues` are updated and initially to
+	 * set the initial value of the result.
+	 */
+	public static fromCallback<T> (
+		callback: ()=>T, sourceValues: ReactiveValue<any>[]
+	): ReactiveValue<T>{
+		const result = new ReactiveValueImpl(callback());
+		const resultRef = window.WeakRef ? new WeakRef(result) : { deref: () => result };
+
+		for (const value of sourceValues) {
+			const listener = value.onUpdate(() => {
+				// Use resultRef to allow `result` to be garbage collected
+				// despite this listener.
+				const value = resultRef.deref();
+				if (value) {
+					value.set(callback());
+				} else {
+					listener.remove();
+				}
+			});
+		}
+
+		return result;
+	}
+
+	/**
+	 * Returns a reactive value derived from a single `source`.
+	 *
+	 * If `inverseMap` is `undefined`, the result is a read-only view.
+	 */
+	public static map<A, B> (
+		source: ReactiveValue<A>,
+		map: (a: A)=>B,
+		inverseMap?: undefined,
+	): ReactiveValue<B>;
+
+
+	/**
+	 * Returns a reactive value derived from a single `source`.
+	 */
+	public static map<A, B> (
+		source: ReactiveValue<A>,
+		map: (a: A)=>B,
+		inverseMap: (b: B)=>A,
+	): MutableReactiveValue<B>;
+
+
+	public static map<A, B> (
+		source: MutableReactiveValue<A>,
+		map: (a: A)=>B,
+		inverseMap: ((b: B)=>A)|undefined,
+	): ReactiveValue<B>|MutableReactiveValue<B>{
+		const result = ReactiveValue.fromInitialValue(map(source.get()));
+
+		let expectedResultValue = result.get();
+		source.onUpdate(newValue => {
+			expectedResultValue = map(newValue);
+			result.set(expectedResultValue);
+		});
+
+		if (inverseMap) {
+			result.onUpdate(newValue => {
+				// Prevent infinite loops if inverseMap is not a true
+				// inverse.
+				if (newValue !== expectedResultValue) {
+					source.set(inverseMap(newValue));
+				}
+			});
+		}
+
+		return result;
+	}
+}
+
+export abstract class MutableReactiveValue<T> extends ReactiveValue<T> {
+	/**
+	 * Changes the value of this and fires all update listeners.
+	 *
+	 * @see {@link onUpdate}
+	 */
+	public abstract set(newValue: T): void;
+
+	public static fromProperty<SourceType extends object, Name extends keyof SourceType> (
+		sourceValue: MutableReactiveValue<SourceType>,
+		propertyName: Name,
+	): MutableReactiveValue<SourceType[Name]>{
+		const child = ReactiveValue.fromInitialValue(
+			sourceValue.get()[propertyName]
+		);
+		const childRef = new WeakRef(child);
+
+		// When the source is updated...
+		const sourceListener = sourceValue.onUpdate(newValue => {
+			const childValue = childRef.deref();
+
+			if (childValue) {
+				childValue.set(newValue[propertyName]);
+			} else {
+				// TODO: What if `sourceValue` would be dropped before
+				// the child value?
+				sourceListener.remove();
+			}
+		});
+
+		// When the child is updated, also apply the update to the
+		// parent.
+		child.onUpdate(newValue => {
+			sourceValue.set({
+				...sourceValue.get(),
+				[propertyName]: newValue,
+			});
+		});
+
+		return child;
+	}
+}
+
+// @internal
+class ReactiveValueImpl<T> extends MutableReactiveValue<T> {
+	#value: T;
+	#onUpdateListeners: Array<(value: T)=>void>;
+
+	public constructor(initialValue: T) {
+		super();
+
+		this.#value = initialValue;
+		this.#onUpdateListeners = [];
+	}
+
+	public set(newValue: T) {
+		if (this.#value === newValue) {
+			return;
+		}
+
+		this.#value = newValue;
+
+		for (const listener of this.#onUpdateListeners) {
+			listener(newValue);
+		}
+	}
+
+	public get() {
+		return this.#value;
+	}
+
+	public onUpdate(listener: (value: T)=>void) {
+		// **Note**: If memory is a concern, listeners should avoid referencing this
+		// reactive value directly. Doing so allows the value to be garbage collected when
+		// no longer referenced.
+
+		this.#onUpdateListeners.push(listener);
+
+		return {
+			remove: () => {
+				this.#onUpdateListeners = this.#onUpdateListeners.filter(otherListener => {
+					return otherListener !== listener;
+				});
+			},
+		};
+	}
+
+	public onUpdateAndNow(callback: (value: T)=>void) {
+		callback(this.get());
+		return this.onUpdate(callback);
+	}
+}
+
+
+export default ReactiveValue;

package/src/util/guessKeyCodeFromKey.ts

@@ -0,0 +1,36 @@
+
+// See https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values for
+// more
+const keyToKeyCode: Record<string, string> = {
+	'Control': 'ControlLeft',
+	'=': 'Equal',
+	'-': 'Minus',
+	';': 'Semicolon',
+	' ': 'Space',
+};
+
+/**
+ * Attempts to guess the .code value corresponding to the given key.
+ *
+ * Use this to facilitate testing.
+ *
+ * If no matching keycode is found, returns `key`.
+ */
+const guessKeyCodeFromKey = (key: string) => {
+	const upperKey = key.toUpperCase();
+	if ('A' <= upperKey && upperKey <= 'Z') {
+		return `Key${upperKey}`;
+	}
+
+	if ('0' <= key && key <= '9') {
+		return `Digit${key}`;
+	}
+
+	if (key in keyToKeyCode) {
+		return keyToKeyCode[key];
+	}
+
+	return key;
+};
+
+export default guessKeyCodeFromKey;

package/src/util/listPrefixMatch.ts

@@ -0,0 +1,19 @@
+
+/**
+ * Returns true iff all elements in the shorter list equal (===) the elements
+ * in the longer list.
+ */
+const listPrefixMatch = <T> (a: T[], b: T[]) => {
+	const shorter = a.length < b.length ? a : b;
+	const longer = shorter === a ? b : a;
+
+	for (let i = 0; i < shorter.length; i++) {
+		if (shorter[i] !== longer[i]) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+export default listPrefixMatch;

package/src/util/stopPropagationOfScrollingWheelEvents.ts

@@ -0,0 +1,20 @@
+
+const stopPropagationOfScrollingWheelEvents = (scrollingContainer: HTMLElement) => {
+	scrollingContainer.onwheel = (event) => {
+		const hasScroll = scrollingContainer.clientWidth !== scrollingContainer.scrollWidth
+						&& event.deltaX !== 0;
+		const eventScrollsPastLeft =
+			scrollingContainer.scrollLeft + event.deltaX <= 0;
+		const scrollRight = scrollingContainer.scrollLeft + scrollingContainer.clientWidth;
+		const eventScrollsPastRight =
+			scrollRight + event.deltaX > scrollingContainer.scrollWidth;
+
+		// Stop the editor from receiving the event if it will scroll the pen type selector
+		// instead.
+		if (hasScroll && !eventScrollsPastLeft && !eventScrollsPastRight) {
+			event.stopPropagation();
+		}
+	};
+};
+
+export default stopPropagationOfScrollingWheelEvents;

package/src/version.test.ts

@@ -0,0 +1,12 @@
+import version from './version';
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'path';
+
+describe('version', () => {
+	it('version should be correct', async () => {
+		const packageJSONString = await readFile(join(dirname(__dirname), 'package.json'), 'utf-8');
+		const packageJSON = JSON.parse(packageJSONString);
+
+		expect(packageJSON['version']).toBe(version.number);
+	});
+});

package/src/version.ts

@@ -0,0 +1,3 @@
+export default {
+	number: '1.0.1',
+};

package/tsconfig.json

@@ -2,6 +2,6 @@
 	"extends": "../../tsconfig.json",
 
 	"include": [
-		"**/*.ts",
+		"src/**/*.ts",
 	]
 }

package/typedoc.json

@@ -0,0 +1,4 @@
+{
+	"extends": ["../../typedoc.base.json"],
+	"entryPoints": ["./src/lib.ts"]
+}

package/dist/cjs/Color4.d.ts

@@ -1,69 +0,0 @@
-import Vec3 from './math/Vec3';
-export default class Color4 {
-    /** Red component. Should be in the range [0, 1]. */
-    readonly r: number;
-    /** Green component. `g` ∈ [0, 1] */
-    readonly g: number;
-    /** Blue component. `b` ∈ [0, 1] */
-    readonly b: number;
-    /** Alpha/transparent component. `a` ∈ [0, 1]. 0 = transparent */
-    readonly a: number;
-    private constructor();
-    /**
-     * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
-     *
-     * Each component should be in the range [0, 1].
-     */
-    static ofRGB(red: number, green: number, blue: number): Color4;
-    static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4;
-    static fromHex(hexString: string): Color4;
-    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
-    static fromString(text: string): Color4;
-    /** @returns true if `this` and `other` are approximately equal. */
-    eq(other: Color4 | null | undefined): boolean;
-    /**
-     * If `fractionTo` is not in the range [0, 1], it will be clamped to the nearest number
-     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
-     *
-     * @returns a color `fractionTo` of the way from this color to `other`.
-     *
-     * @example
-     * ```ts
-     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
-     * ```
-     */
-    mix(other: Color4, fractionTo: number): Color4;
-    /**
-     * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
-     */
-    static average(colors: Color4[]): Color4;
-    /**
-     * Converts to (hue, saturation, value).
-     * See also https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
-     *
-     * The resultant hue is represented in radians and is thus in [0, 2pi].
-     */
-    asHSV(): Vec3;
-    private hexString;
-    /**
-     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
-     *
-     * @example
-     * ```
-     * Color4.red.toHexString(); // -> #ff0000ff
-     * ```
-     */
-    toHexString(): string;
-    toString(): string;
-    static transparent: Color4;
-    static red: Color4;
-    static green: Color4;
-    static blue: Color4;
-    static purple: Color4;
-    static yellow: Color4;
-    static clay: Color4;
-    static black: Color4;
-    static gray: Color4;
-    static white: Color4;
-}
-export { Color4 };