@khanacademy/wonder-blocks-core 8.0.0 → 10.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @khanacademy/wonder-blocks-core
 
+## 10.0.0
+
+### Major Changes
+
+-   b6009b77: Deprecate the ID provider and unique ID utilities
+
+### Minor Changes
+
+-   897686bc: - Add the `Id` component for cases where `useId` cannot be used directly
+
+### Patch Changes
+
+-   56d961f1: - Migrate Wonder Blocks components off old id providers and onto new `Id` component
+
+## 9.0.0
+
+### Major Changes
+
+-   f4abd572: - Remove `RenderState.Root` from exported enum
+    -   Change `useRenderState` to only return `RenderState.Initial` or `RenderState.Standard`
+
 ## 8.0.0
 
 ### Major Changes

package/dist/components/id-provider.d.ts

@@ -22,6 +22,9 @@ type Props = {
     testId?: string;
 };
 /**
+ * @deprecated This component is deprecated and will be removed in an
+ * upcoming release. Migrate existing code to use `useId` or the `Id` component.
+ *
  * This is a wrapper that returns an identifier. If the `id` prop is set, the
  * component will return the same id to be consumed by its children. Otherwise,
  * a unique id will be provided. This is beneficial for accessibility purposes,
@@ -48,7 +51,6 @@ type Props = {
  *  )}
  * </IDProvider>
  * ```
- *
  */
 export default class IDProvider extends React.Component<Props> {
     static defaultId: string;

package/dist/components/id.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+type Props = {
+    /**
+     * An identifier to use.
+     *
+     * If this is omitted, an identifier is generated.
+     */
+    id?: string | undefined;
+    /**
+     * A function that to render children with the given identifier.
+     */
+    children: (id: string) => React.ReactNode;
+};
+/**
+ * `Id` is a component that provides an identifier to its children.
+ *
+ * It is useful for situations where the `useId` hook cannot be easily used,
+ * such as in class-based components.
+ *
+ * If an `id` prop is provided, that is passed through to the children;
+ * otherwise, a unique identifier is generated.
+ */
+export declare const Id: ({ id, children }: Props) => React.JSX.Element;
+export {};

package/dist/components/initial-fallback.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { RenderState } from "./render-state-context";
+import { RenderStateInternal } from "./render-state-context";
 /**
  * We use render functions so that we don't do any work unless we need to.
  * This avoids rendering but not mounting potentially complex component trees.
@@ -56,7 +56,7 @@ export default class InitialFallback extends React.Component<Props, State> {
     componentDidMount(): void;
     _isTheRootComponent: boolean;
     _renderAsRootComponent(): React.ReactNode;
-    _maybeRender(renderState: typeof RenderState[keyof typeof RenderState]): React.ReactNode;
+    _maybeRender(renderState: RenderStateInternal): React.ReactNode;
     render(): React.ReactNode;
 }
 export {};

package/dist/components/render-state-context.d.ts

@@ -1,7 +1,52 @@
 import * as React from "react";
+/**
+ * The possible states of rendering.
+ *
+ * This is used to determine if we are rendering our initial, hydrateable state
+ * or not. Initial renders must be consistent between the server and client so
+ * that hydration will succeed.
+ *
+ * We use a render state like this instead of a simple check for being mounted
+ * or not, or some other way of each component knowing if it is rendering itself
+ * for the first time so that we can avoid cascading initial renders where each
+ * component has to render itself and its children multiple times to reach a
+ * stable state. Instead, we track the initial render from the root of the tree
+ * and switch everything accordingly so that there are fewer additional renders.
+ */
 export declare enum RenderState {
+    /**
+     * The initial render, either on the server or client.
+     */
+    Initial = "initial",
+    /**
+     * Any render after the initial render. Only occurs on the client.
+     */
+    Standard = "standard"
+}
+/**
+ * The internal states of rendering.
+ *
+ * This is different to the `RenderState` enum as this is internal to the
+ * Core package and solely for components that are going to provide new values
+ * to the render state context.
+ */
+export declare enum RenderStateInternal {
+    /**
+     * This is the root state. It indicates that nothing has actually changed
+     * then context value that tracks this. This is used solely by components
+     * that control the rendering state to know that they are in charge of
+     * that process.
+     */
     Root = "root",
+    /**
+     * This indicates something has taken charge of the rendering state and
+     * components should render their initial render state that is hydrateable.
+     */
     Initial = "initial",
+    /**
+     * This indicates that things are now rendering after the initial render
+     * and components can render without worrying about hydration.
+     */
     Standard = "standard"
 }
 /**
@@ -19,5 +64,5 @@ export declare enum RenderState {
  * standard:
  *   means that we're all now doing non-SSR rendering
  */
-declare const RenderStateContext: React.Context<RenderState>;
+declare const RenderStateContext: React.Context<RenderStateInternal>;
 export { RenderStateContext };

package/dist/components/unique-id-provider.d.ts

@@ -34,6 +34,9 @@ type Props = {
     readonly scope?: string;
 };
 /**
+ * @deprecated This component is deprecated and will be removed in an
+ * upcoming release. Migrate existing code to use `useId` or the `Id` component.
+ *
  * The `UniqueIDProvider` component is how Wonder Blocks components obtain
  * unique identifiers. This component ensures that server-side rendering and
  * initial client rendering match while allowing the provision of unique

package/dist/es/index.js

@@ -1,7 +1,7 @@
 import _extends from '@babel/runtime/helpers/extends';
 import _objectWithoutPropertiesLoose from '@babel/runtime/helpers/objectWithoutPropertiesLoose';
 import * as React from 'react';
-import { useContext, useRef, useEffect as useEffect$1 } from 'react';
+import { useId, useContext as useContext$1, useRef, useEffect as useEffect$1 } from 'react';
 import { StyleSheet, css } from 'aphrodite';
 
 function flatten(list) {
@@ -175,12 +175,17 @@ const View = React.forwardRef(function View(props, ref) {
 });
 
 let RenderState = function (RenderState) {
-  RenderState["Root"] = "root";
   RenderState["Initial"] = "initial";
   RenderState["Standard"] = "standard";
   return RenderState;
 }({});
-const RenderStateContext = React.createContext(RenderState.Root);
+let RenderStateInternal = function (RenderStateInternal) {
+  RenderStateInternal["Root"] = "root";
+  RenderStateInternal["Initial"] = "initial";
+  RenderStateInternal["Standard"] = "standard";
+  return RenderStateInternal;
+}({});
+const RenderStateContext = React.createContext(RenderStateInternal.Root);
 RenderStateContext.displayName = "RenderStateContext";
 
 class InitialFallback extends React.Component {
@@ -209,12 +214,12 @@ class InitialFallback extends React.Component {
     this._isTheRootComponent = true;
     if (mounted) {
       return React.createElement(RenderStateContext.Provider, {
-        value: RenderState.Standard
+        value: RenderStateInternal.Standard
       }, children());
     }
     if (fallback) {
       return React.createElement(RenderStateContext.Provider, {
-        value: RenderState.Initial
+        value: RenderStateInternal.Initial
       }, fallback());
     }
     return null;
@@ -225,17 +230,17 @@ class InitialFallback extends React.Component {
       fallback
     } = this.props;
     switch (renderState) {
-      case RenderState.Root:
+      case RenderStateInternal.Root:
         return this._renderAsRootComponent();
-      case RenderState.Initial:
+      case RenderStateInternal.Initial:
         return fallback ? fallback() : null;
-      case RenderState.Standard:
+      case RenderStateInternal.Standard:
         return children();
     }
     {
       var _JSON$stringify;
       console.log(`We got a render state we don't understand: "${(_JSON$stringify = JSON.stringify(renderState)) != null ? _JSON$stringify : ""}"`);
-      return this._maybeRender(RenderState.Root);
+      return this._maybeRender(RenderStateInternal.Root);
     }
   }
   render() {
@@ -340,14 +345,26 @@ var Server = {
   }
 };
 
-const useRenderState = () => useContext(RenderStateContext);
+const Id = ({
+  id,
+  children
+}) => {
+  const generatedId = useId();
+  return React.createElement(React.Fragment, null, children(id != null ? id : generatedId));
+};
+
+const useRenderState = () => {
+  const rawRenderState = useContext$1(RenderStateContext);
+  if (rawRenderState === RenderStateInternal.Standard) {
+    return RenderState.Standard;
+  } else {
+    return RenderState.Initial;
+  }
+};
 
 const useUniqueIdWithMock = scope => {
   const renderState = useRenderState();
   const idFactory = useRef(null);
-  if (renderState === RenderState.Root) {
-    throw new Error("Components using useUniqueIdWithMock() should be descendants of <RenderStateRoot>");
-  }
   if (renderState === RenderState.Initial) {
     return SsrIDFactory$1;
   }
@@ -359,9 +376,6 @@ const useUniqueIdWithMock = scope => {
 const useUniqueIdWithoutMock = scope => {
   const renderState = useRenderState();
   const idFactory = useRef(null);
-  if (renderState === RenderState.Root) {
-    throw new Error("Components using useUniqueIdWithoutMock() should be descendants of <RenderStateRoot>");
-  }
   if (renderState === RenderState.Initial) {
     return null;
   }
@@ -422,27 +436,28 @@ const usePreHydrationEffect = effect => {
 
 const {
   useEffect,
-  useState
+  useState,
+  useContext
 } = React;
 const RenderStateRoot = ({
   children,
   throwIfNested: _throwIfNested = true
 }) => {
   const [firstRender, setFirstRender] = useState(true);
-  const renderState = useRenderState();
+  const renderState = useContext(RenderStateContext);
   useEffect(() => {
     setFirstRender(false);
   }, []);
-  if (renderState !== RenderState.Root) {
+  if (renderState !== RenderStateInternal.Root) {
     if (_throwIfNested) {
       throw new Error("There's already a <RenderStateRoot> above this instance in " + "the render tree.  This instance should be removed.");
     }
     return React.createElement(React.Fragment, null, children);
   }
-  const value = firstRender ? RenderState.Initial : RenderState.Standard;
+  const value = firstRender ? RenderStateInternal.Initial : RenderStateInternal.Standard;
   return React.createElement(RenderStateContext.Provider, {
     value: value
   }, children);
 };
 
-export { IDProvider, InitialFallback, RenderState, RenderStateRoot, Server, Text, UniqueIDProvider, View, addStyle, useForceUpdate, useIsMounted, useLatestRef, useOnMountEffect, useOnline, usePreHydrationEffect, useRenderState, useUniqueIdWithMock, useUniqueIdWithoutMock };
+export { IDProvider, Id, InitialFallback, RenderState, RenderStateRoot, Server, Text, UniqueIDProvider, View, addStyle, useForceUpdate, useIsMounted, useLatestRef, useOnMountEffect, useOnline, usePreHydrationEffect, useRenderState, useUniqueIdWithMock, useUniqueIdWithoutMock };

package/dist/hooks/use-render-state.d.ts

@@ -1,2 +1,2 @@
 import { RenderState } from "../components/render-state-context";
-export declare const useRenderState: () => (typeof RenderState)[keyof typeof RenderState];
+export declare const useRenderState: () => RenderState;

package/dist/hooks/use-unique-id.d.ts

@@ -1,5 +1,8 @@
 import type { IIdentifierFactory } from "../util/types";
 /**
+ * @deprecated Use `useId` for your ID needs. If you are in a class-based
+ * component and cannot use hooks, then use the `Id` component.
+ *
  * Returns a unique identifier factory.  If the parent component hasn't
  * been mounted yet, the global SsrIDFactory will be returned until the
  * component becomes mounted.
@@ -9,6 +12,9 @@ import type { IIdentifierFactory } from "../util/types";
  */
 export declare const useUniqueIdWithMock: (scope?: string) => IIdentifierFactory;
 /**
+ * @deprecated Use `useId` for your ID needs. If you are in a class-based
+ * component and cannot use hooks, then use the `Id` component.
+ *
  * Returns a unique identifier factory.  If the parent component hasn't
  * been mounted yet, null will be returned.
  *

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { default as IDProvider } from "./components/id-provider";
 export { default as UniqueIDProvider } from "./components/unique-id-provider";
 export { default as addStyle } from "./util/add-style";
 export { default as Server } from "./util/server";
+export { Id } from "./components/id";
 export { useUniqueIdWithMock, useUniqueIdWithoutMock, } from "./hooks/use-unique-id";
 export { useForceUpdate } from "./hooks/use-force-update";
 export { useIsMounted } from "./hooks/use-is-mounted";

package/dist/index.js

@@ -202,12 +202,17 @@ const View = React__namespace.forwardRef(function View(props, ref) {
 });
 
 let RenderState = function (RenderState) {
-  RenderState["Root"] = "root";
   RenderState["Initial"] = "initial";
   RenderState["Standard"] = "standard";
   return RenderState;
 }({});
-const RenderStateContext = React__namespace.createContext(RenderState.Root);
+let RenderStateInternal = function (RenderStateInternal) {
+  RenderStateInternal["Root"] = "root";
+  RenderStateInternal["Initial"] = "initial";
+  RenderStateInternal["Standard"] = "standard";
+  return RenderStateInternal;
+}({});
+const RenderStateContext = React__namespace.createContext(RenderStateInternal.Root);
 RenderStateContext.displayName = "RenderStateContext";
 
 class InitialFallback extends React__namespace.Component {
@@ -236,12 +241,12 @@ class InitialFallback extends React__namespace.Component {
     this._isTheRootComponent = true;
     if (mounted) {
       return React__namespace.createElement(RenderStateContext.Provider, {
-        value: RenderState.Standard
+        value: RenderStateInternal.Standard
       }, children());
     }
     if (fallback) {
       return React__namespace.createElement(RenderStateContext.Provider, {
-        value: RenderState.Initial
+        value: RenderStateInternal.Initial
       }, fallback());
     }
     return null;
@@ -252,17 +257,17 @@ class InitialFallback extends React__namespace.Component {
       fallback
     } = this.props;
     switch (renderState) {
-      case RenderState.Root:
+      case RenderStateInternal.Root:
         return this._renderAsRootComponent();
-      case RenderState.Initial:
+      case RenderStateInternal.Initial:
         return fallback ? fallback() : null;
-      case RenderState.Standard:
+      case RenderStateInternal.Standard:
         return children();
     }
     {
       var _JSON$stringify;
       console.log(`We got a render state we don't understand: "${(_JSON$stringify = JSON.stringify(renderState)) != null ? _JSON$stringify : ""}"`);
-      return this._maybeRender(RenderState.Root);
+      return this._maybeRender(RenderStateInternal.Root);
     }
   }
   render() {
@@ -367,14 +372,26 @@ var Server = {
   }
 };
 
-const useRenderState = () => React.useContext(RenderStateContext);
+const Id = ({
+  id,
+  children
+}) => {
+  const generatedId = React.useId();
+  return React__namespace.createElement(React__namespace.Fragment, null, children(id != null ? id : generatedId));
+};
+
+const useRenderState = () => {
+  const rawRenderState = React.useContext(RenderStateContext);
+  if (rawRenderState === RenderStateInternal.Standard) {
+    return RenderState.Standard;
+  } else {
+    return RenderState.Initial;
+  }
+};
 
 const useUniqueIdWithMock = scope => {
   const renderState = useRenderState();
   const idFactory = React.useRef(null);
-  if (renderState === RenderState.Root) {
-    throw new Error("Components using useUniqueIdWithMock() should be descendants of <RenderStateRoot>");
-  }
   if (renderState === RenderState.Initial) {
     return SsrIDFactory$1;
   }
@@ -386,9 +403,6 @@ const useUniqueIdWithMock = scope => {
 const useUniqueIdWithoutMock = scope => {
   const renderState = useRenderState();
   const idFactory = React.useRef(null);
-  if (renderState === RenderState.Root) {
-    throw new Error("Components using useUniqueIdWithoutMock() should be descendants of <RenderStateRoot>");
-  }
   if (renderState === RenderState.Initial) {
     return null;
   }
@@ -449,30 +463,32 @@ const usePreHydrationEffect = effect => {
 
 const {
   useEffect,
-  useState
+  useState,
+  useContext
 } = React__namespace;
 const RenderStateRoot = ({
   children,
   throwIfNested: _throwIfNested = true
 }) => {
   const [firstRender, setFirstRender] = useState(true);
-  const renderState = useRenderState();
+  const renderState = useContext(RenderStateContext);
   useEffect(() => {
     setFirstRender(false);
   }, []);
-  if (renderState !== RenderState.Root) {
+  if (renderState !== RenderStateInternal.Root) {
     if (_throwIfNested) {
       throw new Error("There's already a <RenderStateRoot> above this instance in " + "the render tree.  This instance should be removed.");
     }
     return React__namespace.createElement(React__namespace.Fragment, null, children);
   }
-  const value = firstRender ? RenderState.Initial : RenderState.Standard;
+  const value = firstRender ? RenderStateInternal.Initial : RenderStateInternal.Standard;
   return React__namespace.createElement(RenderStateContext.Provider, {
     value: value
   }, children);
 };
 
 exports.IDProvider = IDProvider;
+exports.Id = Id;
 exports.InitialFallback = InitialFallback;
 exports.RenderState = RenderState;
 exports.RenderStateRoot = RenderStateRoot;

package/dist/util/types.d.ts

@@ -80,6 +80,8 @@ export type TextViewSharedProps = {
 } & AriaProps & EventHandlers;
 /**
  * Interface implemented by types that can provide identifiers.
+ * @deprecated Use `useId` for your ID needs. If you are in a class-based
+ * component and cannot use hooks, then use the `Id` component.
  */
 export interface IIdentifierFactory {
     get(id: string): string;

package/dist/util/unique-id-factory.d.ts

@@ -3,6 +3,9 @@ import type { IIdentifierFactory } from "./types";
  * This is NOT for direct use. Instead, see the UniqueIDProvider component.
  *
  * Implements IIdentifierFactory to provide unique identifiers.
+ *
+ * @deprecated Use `useId` for your ID needs. If you are in a class-based
+ * component and cannot use hooks, then use the `Id` component.
  */
 export default class UniqueIDFactory implements IIdentifierFactory {
     _uniqueFactoryName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-core",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"