@fluidframework/react 0.41.3 → 2.62.0

package/lib/useTree.js

@@ -0,0 +1,105 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Tree } from "@fluidframework/tree";
+import { TreeAlpha } from "@fluidframework/tree/internal";
+import * as React from "react";
+import { unwrapPropTreeNode, unwrapPropTreeRecord, } from "./propNode.js";
+import { useObservation } from "./useObservation.js";
+/**
+ * Custom hook which invalidates a React Component when there is a change in the subtree defined by `subtreeRoot`.
+ * This includes changes to the tree's content, but not changes to its parentage.
+ * See {@link @fluidframework/tree#TreeChangeEvents.treeChanged} for details.
+ * @remarks
+ * Consider using {@link useTreeObservations} instead which tracks what was observed and only invalidates if it changes.
+ * @alpha
+ */
+export function useTree(subtreeRoot) {
+    // Use a React effect hook to invalidate this component when the subtreeRoot changes.
+    // We do this by incrementing a counter, which is passed as a dependency to the effect hook.
+    const [invalidations, setInvalidations] = React.useState(0);
+    // React effect hook that increments the 'invalidation' counter whenever subtreeRoot or any of its children change.
+    React.useEffect(() => {
+        // Returns the cleanup function to be invoked when the component unmounts.
+        return Tree.on(subtreeRoot, "treeChanged", () => {
+            setInvalidations((i) => i + 1);
+        });
+    }, [invalidations, subtreeRoot]);
+    return invalidations;
+}
+/**
+ * Higher order component which wraps a component to use {@link useTreeObservations}.
+ *
+ * @remarks
+ * When passing TreeNodes in props, care must be taken to not observe their content outside of a context which does observation tracking (or manual invalidation).
+ * This wraps a component in such tracking.
+ *
+ * It is recommended that sub-components which take in TreeNodes, if not defined using this higher order components, take the nodes in as {@link PropTreeNode}s.
+ * Components defined using this higher order component can take in either raw TreeNodes or {@link PropTreeNode}s: the latter will be automatically unwrapped.
+ * @privateRemarks
+ * `React.FC` does not seem to be covariant over its input type, so to make use of this more ergonomic,
+ * the return type intersects the various ways this could be used (with or without PropTreeNode wrapping).
+ * @alpha
+ */
+export function withTreeObservations(component, options) {
+    return (props) => useTreeObservations(() => component(props), options);
+}
+/**
+ * {@link withTreeObservations} wrapped with React.memo.
+ * @remarks
+ * There is no special logic here, just a convenience wrapper.
+ * @alpha
+ */
+export function withMemoizedTreeObservations(component, options) {
+    return React.memo(withTreeObservations(component, options), options?.propsAreEqual);
+}
+/**
+ * Custom hook which invalidates a React Component when there is a change in tree content observed during `trackDuring`.
+ *
+ * @param trackDuring - Called synchronously, and will have its tree observations tracked.
+ *
+ * @remarks
+ * This includes changes to the tree's content.
+ * Currently this will throw if observing a node's parentage to be undefined,
+ * and node status changes will not cause invalidation.
+ *
+ * For additional type safety to help avoid observing TreeNode content outside of this hook, see {@link PropTreeNode}.
+ * @alpha
+ */
+export function useTreeObservations(trackDuring, options) {
+    return useObservation((invalidate) => TreeAlpha.trackObservationsOnce(invalidate, trackDuring), options);
+}
+/**
+ * Custom hook for using a prop tree node.
+ *
+ * @param propNode - Input, automatically unwrapped TreeNode from a {@link PropTreeNode} if needed.
+ * @param trackDuring - Callback which reads from the node and returns a result.
+ * If the result is a TreeNode or {@link NodeRecord} it will be wrapped as a {@link PropTreeNode} or {@link PropTreeNodeRecord}, see {@link WrapNodes}.
+ *
+ * It is recommended that when returning data containing TreeNodes,
+ * use a format supported by {@link WrapNodes} or wrap the nodes manually using {@link toPropTreeNode}.
+ * This improves the type safety, reducing the risk of invalidation bugs due to untracked access of tree content contained in the return value.
+ *
+ * Note that is is fine to observe any node inside the callback, not just the provided node: all accesses will be tracked.
+ * The input node is just provided as a way to automatically unwrap the {@link PropTreeNode}
+ *
+ * @remarks
+ * Reads content using {@link useTreeObservations} to track dependencies.
+ * @alpha
+ */
+export function usePropTreeNode(propNode, trackDuring) {
+    const node = unwrapPropTreeNode(propNode);
+    const result = useTreeObservations(() => trackDuring(node));
+    return result;
+}
+/**
+ * {@link usePropTreeNode} but takes in a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export function usePropTreeRecord(props, f) {
+    const record = unwrapPropTreeRecord(props);
+    const result = useTreeObservations(() => f(record));
+    return result;
+}
+//# sourceMappingURL=useTree.js.map

package/lib/useTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTree.js","sourceRoot":"","sources":["../src/useTree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAKpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAA2B,MAAM,qBAAqB,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,WAAqB;IAC5C,qFAAqF;IACrF,4FAA4F;IAC5F,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE5D,mHAAmH;IACnH,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACpB,0EAA0E;QAC1E,OAAO,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,aAAa,EAAE,GAAG,EAAE;YAC/C,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;IAEjC,OAAO,aAAa,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CACnC,SAAwB,EACxB,OAA4B;IAE5B,OAAO,CAAC,KAA2B,EAAmB,EAAE,CACvD,mBAAmB,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,KAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC3C,SAAwB,EACxB,OAEC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAClC,WAA0B,EAC1B,OAA4B;IAE5B,OAAO,cAAc,CACpB,CAAC,UAAU,EAAE,EAAE,CAAC,SAAS,CAAC,qBAAqB,CAAC,UAAU,EAAE,WAAW,CAAC,EACxE,OAAO,CACP,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC9B,QAA8B,EAC9B,WAAiC;IAEjC,MAAM,IAAI,GAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAE7C,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5D,OAAO,MAA4B,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAChC,KAAQ,EACR,CAAiD;IAEjD,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAE3C,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEpD,OAAO,MAA4B,CAAC;AACrC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeLeafValue, TreeNode } from \"@fluidframework/tree\";\nimport { Tree } from \"@fluidframework/tree\";\nimport { TreeAlpha } from \"@fluidframework/tree/internal\";\nimport * as React from \"react\";\n\nimport {\n\tunwrapPropTreeNode,\n\tunwrapPropTreeRecord,\n\ttype PropTreeNodeRecord,\n\ttype PropTreeValue,\n\ttype UnwrapPropTreeNodeRecord,\n\ttype WrapNodes,\n} from \"./propNode.js\";\nimport { useObservation, type ObservationOptions } from \"./useObservation.js\";\n\n/**\n * Custom hook which invalidates a React Component when there is a change in the subtree defined by `subtreeRoot`.\n * This includes changes to the tree's content, but not changes to its parentage.\n * See {@link @fluidframework/tree#TreeChangeEvents.treeChanged} for details.\n * @remarks\n * Consider using {@link useTreeObservations} instead which tracks what was observed and only invalidates if it changes.\n * @alpha\n */\nexport function useTree(subtreeRoot: TreeNode): number {\n\t// Use a React effect hook to invalidate this component when the subtreeRoot changes.\n\t// We do this by incrementing a counter, which is passed as a dependency to the effect hook.\n\tconst [invalidations, setInvalidations] = React.useState(0);\n\n\t// React effect hook that increments the 'invalidation' counter whenever subtreeRoot or any of its children change.\n\tReact.useEffect(() => {\n\t\t// Returns the cleanup function to be invoked when the component unmounts.\n\t\treturn Tree.on(subtreeRoot, \"treeChanged\", () => {\n\t\t\tsetInvalidations((i) => i + 1);\n\t\t});\n\t}, [invalidations, subtreeRoot]);\n\n\treturn invalidations;\n}\n\n/**\n * Higher order component which wraps a component to use {@link useTreeObservations}.\n *\n * @remarks\n * When passing TreeNodes in props, care must be taken to not observe their content outside of a context which does observation tracking (or manual invalidation).\n * This wraps a component in such tracking.\n *\n * It is recommended that sub-components which take in TreeNodes, if not defined using this higher order components, take the nodes in as {@link PropTreeNode}s.\n * Components defined using this higher order component can take in either raw TreeNodes or {@link PropTreeNode}s: the latter will be automatically unwrapped.\n * @privateRemarks\n * `React.FC` does not seem to be covariant over its input type, so to make use of this more ergonomic,\n * the return type intersects the various ways this could be used (with or without PropTreeNode wrapping).\n * @alpha\n */\nexport function withTreeObservations<TIn>(\n\tcomponent: React.FC<TIn>,\n\toptions?: ObservationOptions,\n): React.FC<TIn> & React.FC<WrapNodes<TIn>> & React.FC<TIn | WrapNodes<TIn>> {\n\treturn (props: TIn | WrapNodes<TIn>): React.ReactNode =>\n\t\tuseTreeObservations(() => component(props as TIn), options);\n}\n\n/**\n * {@link withTreeObservations} wrapped with React.memo.\n * @remarks\n * There is no special logic here, just a convenience wrapper.\n * @alpha\n */\nexport function withMemoizedTreeObservations<TIn>(\n\tcomponent: React.FC<TIn>,\n\toptions?: ObservationOptions & {\n\t\treadonly propsAreEqual?: Parameters<typeof React.memo>[1];\n\t},\n): React.MemoExoticComponent<ReturnType<typeof withTreeObservations<TIn>>> {\n\treturn React.memo(withTreeObservations(component, options), options?.propsAreEqual);\n}\n\n/**\n * Custom hook which invalidates a React Component when there is a change in tree content observed during `trackDuring`.\n *\n * @param trackDuring - Called synchronously, and will have its tree observations tracked.\n *\n * @remarks\n * This includes changes to the tree's content.\n * Currently this will throw if observing a node's parentage to be undefined,\n * and node status changes will not cause invalidation.\n *\n * For additional type safety to help avoid observing TreeNode content outside of this hook, see {@link PropTreeNode}.\n * @alpha\n */\nexport function useTreeObservations<TResult>(\n\ttrackDuring: () => TResult,\n\toptions?: ObservationOptions,\n): TResult {\n\treturn useObservation(\n\t\t(invalidate) => TreeAlpha.trackObservationsOnce(invalidate, trackDuring),\n\t\toptions,\n\t);\n}\n\n/**\n * Custom hook for using a prop tree node.\n *\n * @param propNode - Input, automatically unwrapped TreeNode from a {@link PropTreeNode} if needed.\n * @param trackDuring - Callback which reads from the node and returns a result.\n * If the result is a TreeNode or {@link NodeRecord} it will be wrapped as a {@link PropTreeNode} or {@link PropTreeNodeRecord}, see {@link WrapNodes}.\n *\n * It is recommended that when returning data containing TreeNodes,\n * use a format supported by {@link WrapNodes} or wrap the nodes manually using {@link toPropTreeNode}.\n * This improves the type safety, reducing the risk of invalidation bugs due to untracked access of tree content contained in the return value.\n *\n * Note that is is fine to observe any node inside the callback, not just the provided node: all accesses will be tracked.\n * The input node is just provided as a way to automatically unwrap the {@link PropTreeNode}\n *\n * @remarks\n * Reads content using {@link useTreeObservations} to track dependencies.\n * @alpha\n */\nexport function usePropTreeNode<T extends TreeNode | TreeLeafValue, TResult>(\n\tpropNode: PropTreeValue<T> | T,\n\ttrackDuring: (node: T) => TResult,\n): WrapNodes<TResult> {\n\tconst node: T = unwrapPropTreeNode(propNode);\n\n\tconst result = useTreeObservations(() => trackDuring(node));\n\n\treturn result as WrapNodes<TResult>;\n}\n\n/**\n * {@link usePropTreeNode} but takes in a {@link PropTreeNodeRecord}.\n * @alpha\n */\nexport function usePropTreeRecord<const T extends PropTreeNodeRecord, TResult>(\n\tprops: T,\n\tf: (node: UnwrapPropTreeNodeRecord<T>) => TResult,\n): WrapNodes<TResult> {\n\tconst record = unwrapPropTreeRecord(props);\n\n\tconst result = useTreeObservations(() => f(record));\n\n\treturn result as WrapNodes<TResult>;\n}\n"]}

package/package.json

@@ -1,63 +1,162 @@
 {
   "name": "@fluidframework/react",
-  "version": "0.41.3",
-  "description": "Base views and hooks for building Fluid React views",
+  "version": "2.62.0",
+  "description": "Utilities for integrating content powered by the Fluid Framework into React applications",
   "homepage": "https://fluidframework.com",
-  "repository": "https://github.com/microsoft/FluidFramework",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/framework/react"
+  },
   "license": "MIT",
   "author": "Microsoft and contributors",
   "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/public.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/public.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./alpha": {
+      "import": {
+        "types": "./lib/alpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/alpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./beta": {
+      "import": {
+        "types": "./lib/beta.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/beta.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
   "main": "dist/index.js",
-  "module": "lib/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "concurrently npm:build:compile npm:lint && npm run build:docs",
-    "build:compile": "concurrently npm:tsc npm:build:esnext",
-    "build:docs": "api-extractor run --local && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
-    "build:esnext": "tsc --project ./tsconfig.esnext.json",
-    "build:full": "npm run build",
-    "build:full:compile": "npm run build:compile",
-    "ci:build:docs": "api-extractor run && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
-    "clean": "rimraf dist lib *.tsbuildinfo *.build.log",
-    "eslint": "eslint --format stylish src",
-    "eslint:fix": "eslint --format stylish src --fix",
-    "lint": "npm run eslint",
-    "lint:fix": "npm run eslint:fix",
-    "tsc": "tsc",
-    "tsfmt": "tsfmt --verify",
-    "tsfmt:fix": "tsfmt --replace"
+  "types": "./dist/public.d.ts",
+  "c8": {
+    "all": true,
+    "cache-dir": "nyc/.cache",
+    "exclude": [
+      "src/test/**/*.*ts",
+      "dist/test/**/*.*js",
+      "lib/test/**/*.*js"
+    ],
+    "exclude-after-remap": false,
+    "include": [
+      "src/**/*.*ts",
+      "dist/**/*.*js",
+      "lib/**/*.*js"
+    ],
+    "report-dir": "nyc/report",
+    "reporter": [
+      "cobertura",
+      "html",
+      "text"
+    ],
+    "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluidframework/aqueduct": "^0.41.3",
-    "@fluidframework/common-definitions": "^0.20.1",
-    "@fluidframework/core-interfaces": "^0.39.0",
-    "@fluidframework/counter": "^0.41.3",
-    "@fluidframework/datastore-definitions": "^0.41.3",
-    "@fluidframework/map": "^0.41.3",
-    "@fluidframework/sequence": "^0.41.3",
-    "@fluidframework/shared-object-base": "^0.41.3",
-    "@fluidframework/view-interfaces": "^0.41.3",
-    "react": "^16.10.2"
+    "@fluidframework/aqueduct": "~2.62.0",
+    "@fluidframework/core-interfaces": "~2.62.0",
+    "@fluidframework/datastore-definitions": "~2.62.0",
+    "@fluidframework/fluid-static": "~2.62.0",
+    "@fluidframework/runtime-definitions": "~2.62.0",
+    "@fluidframework/shared-object-base": "~2.62.0",
+    "@fluidframework/tree": "~2.62.0",
+    "react": "^18.3.1"
   },
   "devDependencies": {
-    "@fluidframework/build-common": "^0.22.0",
-    "@fluidframework/eslint-config-fluid": "^0.23.0",
-    "@microsoft/api-extractor": "^7.13.1",
-    "@types/node": "^12.19.0",
-    "@types/react": "^16.9.15",
-    "@typescript-eslint/eslint-plugin": "~4.14.0",
-    "@typescript-eslint/parser": "~4.14.0",
-    "concurrently": "^5.2.0",
-    "copyfiles": "^2.1.0",
-    "eslint": "~7.18.0",
-    "eslint-plugin-eslint-comments": "~3.2.0",
-    "eslint-plugin-import": "~2.22.1",
-    "eslint-plugin-no-null": "~1.0.2",
-    "eslint-plugin-prefer-arrow": "~1.2.2",
-    "eslint-plugin-react": "~7.22.0",
-    "eslint-plugin-unicorn": "~26.0.1",
-    "rimraf": "^2.6.2",
-    "typescript": "~4.1.3",
-    "typescript-formatter": "7.1.0"
+    "@arethetypeswrong/cli": "^0.17.1",
+    "@biomejs/biome": "~1.9.3",
+    "@fluid-internal/mocha-test-setup": "~2.62.0",
+    "@fluid-tools/build-cli": "^0.58.3",
+    "@fluidframework/build-common": "^2.0.3",
+    "@fluidframework/build-tools": "^0.58.3",
+    "@fluidframework/eslint-config-fluid": "^6.0.0",
+    "@fluidframework/tinylicious-client": "~2.62.0",
+    "@microsoft/api-extractor": "7.52.11",
+    "@testing-library/react": "^16.3.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^18.19.0",
+    "@types/react": "^18.3.11",
+    "c8": "^10.1.3",
+    "concurrently": "^8.2.1",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^7.0.3",
+    "eslint": "~8.55.0",
+    "eslint-config-prettier": "~9.0.0",
+    "global-jsdom": "^26.0.0",
+    "mocha": "^10.8.2",
+    "mocha-multi-reporters": "^1.5.1",
+    "rimraf": "^4.4.0",
+    "typescript": "~5.4.5"
+  },
+  "typeValidation": {
+    "disabled": true,
+    "broken": {},
+    "entrypoint": "internal"
+  },
+  "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "flub generate entrypoints --outDir ./dist",
+    "api-extractor:esnext": "flub generate entrypoints --outDir ./lib",
+    "build": "fluid-build . --task build",
+    "build:commonjs": "fluid-build . --task commonjs",
+    "build:compile": "fluid-build . --task compile",
+    "build:docs": "api-extractor run --local",
+    "build:esnext": "tsc --project ./tsconfig.json && copyfiles -f ../../../common/build/build-common/src/esm/package.json ./lib",
+    "build:test": "npm run build:test:esm && npm run build:test:cjs",
+    "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
+    "build:test:esm": "tsc --project ./src/test/tsconfig.json",
+    "check:are-the-types-wrong": "attw --pack . --entrypoints .",
+    "check:biome": "biome check .",
+    "check:exports": "concurrently \"npm:check:exports:*\"",
+    "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
+    "check:exports:cjs:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.cjs.json",
+    "check:exports:cjs:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.cjs.json",
+    "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
+    "check:exports:esm:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.esm.json",
+    "check:exports:esm:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.esm.json",
+    "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
+    "check:format": "npm run check:biome",
+    "ci:build:docs": "api-extractor run",
+    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "eslint": "eslint --format stylish src",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
+    "format": "npm run format:biome",
+    "format:biome": "biome check . --write",
+    "lint": "fluid-build . --task lint",
+    "lint:fix": "fluid-build . --task eslint:fix --task format",
+    "pack:tests": "tar -cf ./react.test-files.tar ./src/test ./dist/test ./lib/test",
+    "test": "npm run test:mocha",
+    "test:coverage": "c8 npm test",
+    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
+    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
+    "test:mocha:esm": "mocha",
+    "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist"
   }
-}
+}

package/src/index.ts

@@ -3,10 +3,45 @@
  * Licensed under the MIT License.
  */
 
-export * from "./reactView";
-export * from "./useStateFluid";
-export * from "./useReducerFluid";
-export * from "./createContextFluid";
-export * from "./interface";
-export * from "./syncedDataObject";
-export * from "./syncedObjects";
+/**
+ * Utilities for using SharedTree with React.
+ * @packageDocumentation
+ */
+
+export type {
+	IReactTreeDataObject,
+	TreeViewProps,
+	SchemaIncompatibleProps,
+} from "./reactSharedTreeView.js";
+export {
+	treeDataObject,
+	treeDataObjectInternal,
+	TreeViewComponent,
+} from "./reactSharedTreeView.js";
+export type { ObservationOptions } from "./useObservation.js";
+export type {
+	NodeRecord,
+	PropTreeNode,
+	PropTreeNodeRecord,
+	PropTreeValue,
+	UnwrapPropTreeNode,
+	UnwrapPropTreeNodeRecord,
+	WrapPropTreeNodeRecord,
+	WrapNodes,
+	IsMappableObjectType,
+} from "./propNode.js";
+export {
+	toPropTreeNode,
+	toPropTreeRecord,
+	unwrapPropTreeNode,
+	unwrapPropTreeRecord,
+} from "./propNode.js";
+export {
+	useTree,
+	usePropTreeNode,
+	usePropTreeRecord,
+	useTreeObservations,
+	withTreeObservations,
+	withMemoizedTreeObservations,
+} from "./useTree.js";
+export { objectIdNumber } from "./simpleIdentifier.js";

package/src/propNode.ts

@@ -0,0 +1,164 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ErasedType } from "@fluidframework/core-interfaces";
+import type { TreeNode, TreeLeafValue } from "@fluidframework/tree";
+
+/**
+ * A type erased TreeNode for use in react props.
+ * @remarks
+ * Read content from the node using {@link usePropTreeNode} or {@link usePropTreeRecord}.
+ *
+ * In events where tracking dependencies is not required, the node can be unwrapped using {@link unwrapPropTreeNode}.
+ *
+ * To convert a TreeNode to this type use {@link toPropTreeNode} or {@link toPropTreeRecord}.
+ * @alpha
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface PropTreeNode<T extends TreeNode> extends ErasedType<[T, "PropTreeNode"]> {}
+
+/**
+ * Type TreeNodes in T as {@link PropTreeNode}s.
+ * @remarks
+ * This only handles a few cases (TreeNode, structurally typed objects fields and arrays) and leaves other types as is.
+ * Users which provide other types (e.g. maps) which contain TreeNodes will need to handle wrapping those themselves if the wrapping is desired.
+ *
+ * Users of this should not rely on a given use of TreeNode not being wrapped:
+ * future changes to this API may add more cases which are wrapped, and this will be considered a non-breaking change.
+ * @privateRemarks
+ * Covering all cases is impossible, and trying to cover more with recursive mapped types can break some of the types by losing methods, private members, etc.
+ * To mitigate this IsMappableObjectType is used for objects, and only mappable types, where the mapping actually impacted the type are modified.
+ *
+ * This is intended to cover the common cases, and users can handle other cases manually.
+ * See the tests for this for more details.
+ * @alpha
+ */
+export type WrapNodes<T> = T extends TreeNode
+	? PropTreeNode<T>
+	: T extends readonly (infer U)[]
+		? readonly WrapNodes<U>[]
+		: // `T extends (infer U)` distributes over unions, allowing WrapNodes<A|B> to be WrapNodes<A> | WrapNodes<B>.
+			T extends infer U
+			? IsMappableObjectType<
+					U,
+					{
+						[P in keyof U]: WrapNodes<U[P]>;
+					} extends U
+						? // Returning U in this case (when assignable to the mapped type) avoids flatting named interfaces when they are unchanged.
+							U
+						: {
+								[P in keyof U]: WrapNodes<U[P]>;
+							},
+					T
+				>
+			: T;
+
+/**
+ * Detect if a type is a simple structural object.
+ * @remarks
+ * This returns the true case if the type is entirely defined by its set of public properties.
+ * More concretely, this indicates if creating a mapped type based on `T`
+ * will be lossy due to details mapped types cannot access.
+ *
+ * This is shallow, and distributes over unions.
+ *
+ * This also returns the true case for primitive types since mapping over them leaves them unchanged if doing so in a generic context:
+ * Mapping over a primitive does not leave them unchanged if done directly (not to a generic type parameter), but this can not detect that behavior.
+ * This is fine as the use for this is to detect when making a mapped type from a generic type parameter would be lossy.
+ * @system @alpha
+ */
+export type IsMappableObjectType<
+	T,
+	True = true,
+	False = false,
+	Mapped = {
+		[P in keyof T]: T[P];
+	},
+> = [Mapped] extends [T] ? ([T] extends [Mapped] ? True : False) : False;
+
+/**
+ * Casts a node from a {@link PropTreeNode} back to a TreeNode.
+ * @remarks
+ * This should only be done in scenarios where tracking observations is not required (such as event handlers),
+ * or when taking care to handle invalidation manually.
+ * @alpha
+ */
+export function unwrapPropTreeNode<T extends TreeNode | TreeLeafValue>(
+	propNode: PropTreeValue<T> | T,
+): T {
+	return propNode as T;
+}
+
+/**
+ * {@link unwrapPropTreeNode} but for a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export function unwrapPropTreeRecord<T extends PropTreeNodeRecord>(
+	props: T,
+): UnwrapPropTreeNodeRecord<T> {
+	return props as UnwrapPropTreeNodeRecord<T>;
+}
+
+/**
+ * {@inheritdoc unwrapPropTreeNode}
+ * @alpha
+ */
+export type UnwrapPropTreeNode<T extends TreeLeafValue | PropTreeNode<TreeNode> | undefined> =
+	T extends PropTreeNode<infer Node> ? Node : T;
+
+/**
+ * Record that can contain TreeNodes.
+ * @alpha
+ */
+export type NodeRecord = Record<string, TreeNode | TreeLeafValue>;
+
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type WrapPropTreeNodeRecord<T extends NodeRecord> = {
+	readonly [P in keyof T]: PropTreeValue<T[P]>;
+};
+
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type UnwrapPropTreeNodeRecord<T extends PropTreeNodeRecord> = {
+	readonly [P in keyof T]: UnwrapPropTreeNode<T[P]>;
+};
+
+/**
+ * Type erase `TreeNode`s from a {@link NodeRecord} as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type PropTreeNodeRecord = Record<
+	string,
+	TreeLeafValue | PropTreeNode<TreeNode> | undefined
+>;
+
+/**
+ * Type erase a `TreeNode` from a `TreeNode | TreeLeafValue` as a {@link PropTreeNode}.
+ * @alpha
+ */
+export type PropTreeValue<T extends TreeNode | TreeLeafValue | undefined> = T extends TreeNode
+	? PropTreeNode<T>
+	: T;
+
+/**
+ * Type erase a TreeNode as a {@link PropTreeNode}.
+ * @alpha
+ */
+export function toPropTreeNode<T extends TreeNode | TreeLeafValue>(node: T): PropTreeValue<T> {
+	return node as unknown as PropTreeValue<T>;
+}
+
+/**
+ * Type erase a {@link NodeRecord} as a {@link PropTreeNodeRecord}.
+ * @alpha
+ */
+export function toPropTreeRecord<T extends NodeRecord>(node: T): WrapPropTreeNodeRecord<T> {
+	return node as unknown as WrapPropTreeNodeRecord<T>;
+}