@microsoft/fast-element 2.0.0-beta.5 → 2.0.0-beta.6

package/CHANGELOG.json

@@ -1,6 +1,21 @@
 {
   "name": "@microsoft/fast-element",
   "entries": [
+    {
+      "date": "Thu, 01 Sep 2022 21:53:34 GMT",
+      "tag": "@microsoft/fast-element_v2.0.0-beta.6",
+      "version": "2.0.0-beta.6",
+      "comments": {
+        "prerelease": [
+          {
+            "author": "roeisenb@microsoft.com",
+            "package": "@microsoft/fast-element",
+            "commit": "da9ebbe1b7471cd4e6f7b74f2f9bf02fcc54da4f",
+            "comment": "feat: add new state, ownedState, and computedState APIs"
+          }
+        ]
+      }
+    },
     {
       "date": "Thu, 18 Aug 2022 20:46:10 GMT",
       "tag": "@microsoft/fast-element_v2.0.0-beta.5",

package/CHANGELOG.md

@@ -1,9 +1,17 @@
 # Change Log - @microsoft/fast-element
 
-This log was last generated on Thu, 18 Aug 2022 20:46:10 GMT and should not be manually modified.
+This log was last generated on Thu, 01 Sep 2022 21:53:34 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 2.0.0-beta.6
+
+Thu, 01 Sep 2022 21:53:34 GMT
+
+### Changes
+
+- feat: add new state, ownedState, and computedState APIs (roeisenb@microsoft.com)
+
 ## 2.0.0-beta.5
 
 Thu, 18 Aug 2022 20:46:10 GMT

package/dist/dts/interfaces.d.ts

@@ -197,3 +197,7 @@ export declare const isFunction: (object: any) => object is Function;
  * @internal
  */
 export declare const isString: (object: any) => object is string;
+/**
+ * @internal
+ */
+export declare const noop: () => undefined;

package/dist/dts/state/exports.d.ts

@@ -0,0 +1,3 @@
+export { reactive } from "./reactive.js";
+export { watch } from "./watch.js";
+export * from "./state.js";

package/dist/dts/state/reactive.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a plain object to a reactive, observable object.
+ * @param object - The object to make reactive.
+ * @param deep - Indicates whether or not to deeply convert the oject.
+ * @returns The converted object.
+ * @beta
+ */
+export declare function reactive<T>(object: T, deep?: boolean): T;

package/dist/dts/state/state.d.ts

@@ -0,0 +1,141 @@
+import { Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Options for creating state.
+ * @beta
+ */
+export declare type StateOptions = {
+    /**
+     * Indicates whether to deeply make the state value observable.
+     */
+    deep?: boolean;
+    /**
+     * A friendly name for the state.
+     */
+    name?: string;
+};
+/**
+ * A readonly stateful value.
+ * @beta
+ */
+export declare type ReadonlyState<T> = {
+    /**
+     * Gets the current state value.
+     */
+    (): T;
+    /**
+     * Gets the current state value.
+     */
+    readonly current: T;
+};
+/**
+ * A read/write stateful value.
+ * @beta
+ */
+export declare type State<T> = ReadonlyState<T> & {
+    /**
+     * Gets or sets the current state value.
+     */
+    current: T;
+    /**
+     * Sets the current state value.
+     * @param value The new state value.
+     */
+    set(value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyState<T>;
+};
+/**
+ * Creates a reactive state value.
+ * @param value - The initial state value.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns A State instance.
+ * @beta
+ */
+export declare function state<T>(value: T, options?: string | StateOptions): State<T>;
+/**
+ * A readonly stateful value associated with an object owner.
+ * @beta
+ */
+export declare type ReadonlyOwnedState<T> = {
+    /**
+     * Gets the current stateful value for the owner.
+     */
+    (owner: any): T;
+};
+/**
+ * A read/write stateful value associated with an owner.
+ * @beta
+ */
+export declare type OwnedState<T> = ReadonlyOwnedState<T> & {
+    /**
+     * Sets
+     * @param owner - The object to set the state for the owner.
+     * @param value - The new state value.
+     */
+    set(owner: any, value: T): void;
+    /**
+     * Creates a readonly version of the state.
+     */
+    asReadonly(): ReadonlyOwnedState<T>;
+};
+/**
+ * Creates a reactive state that has its value associated with a specific owner.
+ * @param value - The initial value or a factory that provides an initial value for each owner.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns An OwnedState instance.
+ * @beta
+ */
+export declare function ownedState<T>(value: T | (() => T), options?: string | StateOptions): OwnedState<T>;
+/**
+ * State whose value is computed from other dependencies.
+ * @beta
+ */
+export declare type ComputedState<T> = ReadonlyState<T> & Disposable & {
+    /**
+     * Subscribes to notification of changes in the state.
+     * @param subscriber - The object that is subscribing for change notification.
+     */
+    subscribe(subscriber: Subscriber): void;
+    /**
+     * Unsubscribes from notification of changes in the state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     */
+    unsubscribe(subscriber: Subscriber): void;
+};
+/**
+ * A callback that enables computation setup.
+ * @beta
+ */
+export declare type ComputedSetupCallback = () => (() => void) | void;
+/**
+ * Provides computed state capabilities.
+ * @beta
+ */
+export declare type ComputedBuilder = {
+    /**
+     * Callbacks related to computed state.
+     */
+    on: {
+        /**
+         * Provides a setup callback for the computation.
+         * @param callback The callback to run to setup the computation.
+         */
+        setup(callback: ComputedSetupCallback): void;
+    };
+};
+/**
+ * A callback that initializes the computation.
+ * @beta
+ */
+export declare type ComputedInitializer<T> = (builder: ComputedBuilder) => () => T;
+/**
+ * Creates a ComputedState.
+ * @param initialize - The initialization callback.
+ * @param name - A friendly name for this computation.
+ * @returns A ComputedState
+ * @beta
+ */
+export declare function computedState<T>(initialize: ComputedInitializer<T>, name?: string): ComputedState<T>;

package/dist/dts/state/visitor.d.ts

@@ -0,0 +1,6 @@
+export interface ObjectVisitor<TVisitorData> {
+    visitObject(object: any, data: TVisitorData): void;
+    visitArray(array: any[], data: TVisitorData): void;
+    visitProperty(object: any, key: PropertyKey, value: any, data: TVisitorData): void;
+}
+export declare function visitObject<TVisitorData>(object: any, deep: boolean, visitor: ObjectVisitor<TVisitorData>, data: TVisitorData, traversed: WeakSet<any> | Set<any>): void;

package/dist/dts/state/watch.d.ts

@@ -0,0 +1,10 @@
+import { Disposable } from "../interfaces.js";
+import type { Subscriber } from "../observation/notifier.js";
+/**
+ * Deeply subscribes to changes in existing observable objects.
+ * @param object - The observable object to watch.
+ * @param subscriber - The handler to call when changes are made to the object.
+ * @returns A disposable that can be used to unsubscribe from change updates.
+ * @beta
+ */
+export declare function watch(object: any, subscriber: Subscriber | ((subject: any, args: any) => void)): Disposable;

package/dist/dts/utilities.d.ts

@@ -1,21 +1,3 @@
-import { Disposable } from "./interfaces.js";
-import type { Subscriber } from "./observation/notifier.js";
-/**
- * Converts a plain object to an observable object.
- * @param object - The object to make observable.
- * @param deep - Indicates whether or not to deeply convert the oject.
- * @returns The converted object.
- * @beta
- */
-export declare function makeObservable<T>(object: T, deep?: boolean): T;
-/**
- * Deeply subscribes to changes in existing observable objects.
- * @param object - The observable object to watch.
- * @param subscriber - The handler to call when changes are made to the object.
- * @returns A disposable that can be used to unsubscribe from change updates.
- * @beta
- */
-export declare function watch(object: any, subscriber: Subscriber | ((subject: any, args: any) => void)): Disposable;
 /**
  * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
  * When the parent of a node is a shadow-root, it will return the host

package/dist/esm/interfaces.js

@@ -6,3 +6,7 @@ export const isFunction = (object) => typeof object === "function";
  * @internal
  */
 export const isString = (object) => typeof object === "string";
+/**
+ * @internal
+ */
+export const noop = () => void 0;

package/dist/esm/state/exports.js

@@ -0,0 +1,3 @@
+export { reactive } from "./reactive.js";
+export { watch } from "./watch.js";
+export * from "./state.js";

package/dist/esm/state/reactive.js

@@ -0,0 +1,34 @@
+import { noop } from "../interfaces.js";
+import { Observable } from "../observation/observable.js";
+import { visitObject } from "./visitor.js";
+const observed = new WeakSet();
+const makeObserverVisitor = {
+    visitObject: noop,
+    visitArray: noop,
+    visitProperty(object, propertyName, value) {
+        Reflect.defineProperty(object, propertyName, {
+            enumerable: true,
+            get() {
+                Observable.track(object, propertyName);
+                return value;
+            },
+            set(newValue) {
+                if (value !== newValue) {
+                    value = newValue;
+                    Observable.notify(object, propertyName);
+                }
+            },
+        });
+    },
+};
+/**
+ * Converts a plain object to a reactive, observable object.
+ * @param object - The object to make reactive.
+ * @param deep - Indicates whether or not to deeply convert the oject.
+ * @returns The converted object.
+ * @beta
+ */
+export function reactive(object, deep = false) {
+    visitObject(object, deep, makeObserverVisitor, void 0, observed);
+    return object;
+}

package/dist/esm/state/state.js

@@ -0,0 +1,148 @@
+// Inspired by https://www.starbeamjs.com/
+import { isFunction, isString } from "../interfaces.js";
+import { Observable } from "../observation/observable.js";
+import { reactive } from "./reactive.js";
+const defaultStateOptions = {
+    deep: false,
+};
+/**
+ * Creates a reactive state value.
+ * @param value - The initial state value.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns A State instance.
+ * @beta
+ */
+export function state(value, options = defaultStateOptions) {
+    var _a;
+    if (isString(options)) {
+        options = { deep: false, name: options };
+    }
+    const host = reactive({ value }, options.deep);
+    const state = (() => host.value);
+    Object.defineProperty(state, "current", {
+        get: () => host.value,
+        set: (value) => (host.value = value),
+    });
+    Object.defineProperty(state, "name", {
+        value: (_a = options.name) !== null && _a !== void 0 ? _a : "SharedState",
+    });
+    state.set = (value) => (host.value = value);
+    state.asReadonly = () => {
+        const readonlyState = (() => host.value);
+        Object.defineProperty(readonlyState, "current", {
+            get: () => host.value,
+        });
+        Object.defineProperty(readonlyState, "name", {
+            value: `${state.name} (Readonly)`,
+        });
+        return Object.freeze(readonlyState);
+    };
+    return state;
+}
+/**
+ * Creates a reactive state that has its value associated with a specific owner.
+ * @param value - The initial value or a factory that provides an initial value for each owner.
+ * @param options - Options to customize the state or a friendly name.
+ * @returns An OwnedState instance.
+ * @beta
+ */
+export function ownedState(value, options = defaultStateOptions) {
+    var _a;
+    if (isString(options)) {
+        options = { deep: false, name: options };
+    }
+    if (!isFunction(value)) {
+        const v = value;
+        value = () => v;
+    }
+    const storage = new WeakMap();
+    const getHost = (owner) => {
+        let host = storage.get(owner);
+        if (host === void 0) {
+            host = reactive({ value: value() }, options.deep);
+            storage.set(owner, host);
+        }
+        return host;
+    };
+    const state = ((owner) => getHost(owner).value);
+    Object.defineProperty(state, "name", {
+        value: (_a = options.name) !== null && _a !== void 0 ? _a : "OwnedState",
+    });
+    state.set = (owner, value) => (getHost(owner).value = value);
+    state.asReadonly = () => {
+        const readonlyState = ((owner) => getHost(owner).value);
+        Object.defineProperty(readonlyState, "name", {
+            value: `${state.name} (Readonly)`,
+        });
+        return Object.freeze(readonlyState);
+    };
+    return state;
+}
+/**
+ * Creates a ComputedState.
+ * @param initialize - The initialization callback.
+ * @param name - A friendly name for this computation.
+ * @returns A ComputedState
+ * @beta
+ */
+export function computedState(initialize, name = "ComputedState") {
+    let setupCallback = null;
+    const builder = {
+        on: {
+            setup(callback) {
+                setupCallback = callback;
+            },
+        },
+    };
+    const computer = initialize(builder);
+    const host = reactive({ value: null }, false);
+    const output = (() => host.value);
+    Object.defineProperty(output, "current", {
+        get: () => host.value,
+    });
+    Object.defineProperty(output, "name", {
+        value: name,
+    });
+    // eslint-disable-next-line prefer-const
+    let computedNotifier;
+    const computedSubscriber = {
+        handleChange() {
+            host.value = computedNotifier.observe(null);
+        },
+    };
+    computedNotifier = Observable.binding(computer, computedSubscriber);
+    computedNotifier.setMode(false);
+    let cleanup;
+    let setupNotifier;
+    if (setupCallback) {
+        const setupSubscriber = {
+            handleChange() {
+                if (cleanup) {
+                    cleanup();
+                }
+                cleanup = setupNotifier.observe(null);
+                host.value = computer();
+            },
+        };
+        setupNotifier = Observable.binding(setupCallback, setupSubscriber);
+        setupNotifier.setMode(false);
+        cleanup = setupNotifier.observe(null);
+    }
+    host.value = computedNotifier.observe(null);
+    output.dispose = () => {
+        if (cleanup) {
+            cleanup();
+        }
+        if (setupNotifier) {
+            setupNotifier.dispose();
+        }
+        computedNotifier.dispose();
+    };
+    output.subscribe = (subscriber) => {
+        computedNotifier.subscribe(subscriber);
+    };
+    output.unsubscribe = (subscriber) => {
+        computedNotifier.unsubscribe(subscriber);
+    };
+    return output;
+}

package/dist/esm/state/visitor.js

@@ -0,0 +1,28 @@
+function shouldTraverse(value, traversed) {
+    return (value !== null &&
+        value !== void 0 &&
+        typeof value === "object" &&
+        !traversed.has(value));
+}
+export function visitObject(object, deep, visitor, data, traversed) {
+    if (!shouldTraverse(object, traversed)) {
+        return;
+    }
+    traversed.add(object);
+    if (Array.isArray(object)) {
+        visitor.visitArray(object, data);
+        for (const item of object) {
+            visitObject(item, deep, visitor, data, traversed);
+        }
+    }
+    else {
+        visitor.visitObject(object, data);
+        for (const key in object) {
+            const value = object[key];
+            visitor.visitProperty(object, key, value, data);
+            if (deep) {
+                visitObject(value, deep, visitor, data, traversed);
+            }
+        }
+    }
+}

package/dist/esm/state/watch.js

@@ -0,0 +1,36 @@
+import { isFunction, noop } from "../interfaces.js";
+import { ArrayObserver } from "../observation/arrays.js";
+import { Observable } from "../observation/observable.js";
+import { visitObject } from "./visitor.js";
+function watchObject(object, data) {
+    const notifier = Observable.getNotifier(object);
+    notifier.subscribe(data.subscriber);
+    data.notifiers.push(notifier);
+}
+const watchVisitor = {
+    visitProperty: noop,
+    visitObject: watchObject,
+    visitArray: watchObject,
+};
+/**
+ * Deeply subscribes to changes in existing observable objects.
+ * @param object - The observable object to watch.
+ * @param subscriber - The handler to call when changes are made to the object.
+ * @returns A disposable that can be used to unsubscribe from change updates.
+ * @beta
+ */
+export function watch(object, subscriber) {
+    const data = {
+        notifiers: [],
+        subscriber: isFunction(subscriber) ? { handleChange: subscriber } : subscriber,
+    };
+    ArrayObserver.enable();
+    visitObject(object, true, watchVisitor, data, new Set());
+    return {
+        dispose() {
+            for (const n of data.notifiers) {
+                n.unsubscribe(data.subscriber);
+            }
+        },
+    };
+}

package/dist/esm/utilities.js

@@ -1,98 +1,3 @@
-import { ArrayObserver } from "./index.debug.js";
-import { isFunction } from "./interfaces.js";
-import { Observable } from "./observation/observable.js";
-function shouldTraverse(value, traversed) {
-    return (value !== null &&
-        value !== void 0 &&
-        typeof value === "object" &&
-        !traversed.has(value));
-}
-function traverseObject(object, deep, visitor, data, traversed) {
-    if (!shouldTraverse(object, traversed)) {
-        return;
-    }
-    traversed.add(object);
-    if (Array.isArray(object)) {
-        visitor.visitArray(object, data);
-        for (const item of object) {
-            traverseObject(item, deep, visitor, data, traversed);
-        }
-    }
-    else {
-        visitor.visitObject(object, data);
-        for (const key in object) {
-            const value = object[key];
-            visitor.visitProperty(object, key, value, data);
-            if (deep) {
-                traverseObject(value, deep, visitor, data, traversed);
-            }
-        }
-    }
-}
-const noop = () => void 0;
-const observed = new WeakSet();
-const makeObserverVisitor = {
-    visitObject: noop,
-    visitArray: noop,
-    visitProperty(object, propertyName, value) {
-        Reflect.defineProperty(object, propertyName, {
-            enumerable: true,
-            get() {
-                Observable.track(object, propertyName);
-                return value;
-            },
-            set(newValue) {
-                if (value !== newValue) {
-                    value = newValue;
-                    Observable.notify(object, propertyName);
-                }
-            },
-        });
-    },
-};
-function watchObject(object, data) {
-    const notifier = Observable.getNotifier(object);
-    notifier.subscribe(data.subscriber);
-    data.notifiers.push(notifier);
-}
-const watchVisitor = {
-    visitProperty: noop,
-    visitObject: watchObject,
-    visitArray: watchObject,
-};
-/**
- * Converts a plain object to an observable object.
- * @param object - The object to make observable.
- * @param deep - Indicates whether or not to deeply convert the oject.
- * @returns The converted object.
- * @beta
- */
-export function makeObservable(object, deep = false) {
-    traverseObject(object, deep, makeObserverVisitor, void 0, observed);
-    return object;
-}
-/**
- * Deeply subscribes to changes in existing observable objects.
- * @param object - The observable object to watch.
- * @param subscriber - The handler to call when changes are made to the object.
- * @returns A disposable that can be used to unsubscribe from change updates.
- * @beta
- */
-export function watch(object, subscriber) {
-    const data = {
-        notifiers: [],
-        subscriber: isFunction(subscriber) ? { handleChange: subscriber } : subscriber,
-    };
-    ArrayObserver.enable();
-    traverseObject(object, true, watchVisitor, data, new Set());
-    return {
-        dispose() {
-            for (const n of data.notifiers) {
-                n.unsubscribe(data.subscriber);
-            }
-        },
-    };
-}
 /**
  * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
  * When the parent of a node is a shadow-root, it will return the host

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microsoft/fast-element",
   "description": "A library for constructing Web Components",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.6",
   "author": {
     "name": "Microsoft",
     "url": "https://discord.gg/FcSNfg4"
@@ -50,9 +50,9 @@
       "types": "./dist/dts/utilities.d.ts",
       "default": "./dist/esm/utilities.js"
     },
-    "./hooks": {
-      "types": "./dist/dts/hooks.d.ts",
-      "default": "./dist/esm/hooks.js"
+    "./state": {
+      "types": "./dist/dts/state/exports.d.ts",
+      "default": "./dist/esm/state/exports.js"
     },
     "./context": {
       "types": "./dist/dts/context.d.ts",

package/dist/dts/hooks.d.ts

@@ -1,20 +0,0 @@
-import { ExpressionNotifier } from "./observation/observable.js";
-/**
- * Functions used for getting and setting a stateful value.
- * @beta
- */
-export declare type State<T> = [() => T, (newValue: T) => T];
-/**
- * Creates an observable state value.
- * @param value The initial state value.
- * @param deep Whether or not to convert the state value to an observable.
- * @returns The state accessor functions.
- * @beta
- */
-export declare function useState<T>(value: T, deep?: boolean): State<T>;
-/**
- * Executes an action once, and then whenever any of its dependent state changes.
- * @param action An action that is affected by state changes.
- * @returns A BindingObserver which can be used to dispose of the effect.
- */
-export declare function useEffect(action: () => void): ExpressionNotifier;

package/dist/esm/hooks.js

@@ -1,32 +0,0 @@
-import { Observable } from "./observation/observable.js";
-import { makeObservable } from "./utilities.js";
-/**
- * Creates an observable state value.
- * @param value The initial state value.
- * @param deep Whether or not to convert the state value to an observable.
- * @returns The state accessor functions.
- * @beta
- */
-export function useState(value, deep = false) {
-    const host = makeObservable({ value }, deep);
-    return [() => host.value, newValue => (host.value = newValue)];
-}
-const effectModel = Object.freeze({});
-/**
- * Executes an action once, and then whenever any of its dependent state changes.
- * @param action An action that is affected by state changes.
- * @returns A BindingObserver which can be used to dispose of the effect.
- */
-export function useEffect(action) {
-    /* eslint prefer-const: 0 */
-    let observer;
-    const subscriber = {
-        handleChange() {
-            observer.observe(effectModel);
-        },
-    };
-    observer = Observable.binding(action, subscriber);
-    observer.setMode(false);
-    subscriber.handleChange();
-    return observer;
-}