From e259cf4543d57105fbf4e1c383cb0131542e52fe Mon Sep 17 00:00:00 2001
From: Jeff Yates <jeff@khanacademy.org>
Date: Wed, 11 Dec 2024 16:30:05 -0600
Subject: [PATCH] [wb1812.3.migratewb] Update some docs and improve visibility
 of deprecation notices

---
 __docs__/wonder-blocks-core/id.mdx            | 39 +++++++++++++++++++
 __docs__/wonder-blocks-core/use-unique-id.mdx |  8 +++-
 .../src/components/id-provider.tsx            |  6 +--
 .../wonder-blocks-core/src/components/id.tsx  |  5 ++-
 .../src/components/unique-id-provider.tsx     |  6 +--
 5 files changed, 56 insertions(+), 8 deletions(-)
 create mode 100644 __docs__/wonder-blocks-core/id.mdx

diff --git a/__docs__/wonder-blocks-core/id.mdx b/__docs__/wonder-blocks-core/id.mdx
new file mode 100644
index 000000000..e81a59ca3
--- /dev/null
+++ b/__docs__/wonder-blocks-core/id.mdx
@@ -0,0 +1,39 @@
+import * as React from "react";
+import {Meta, Story, Canvas} from "@storybook/blocks";
+import * as IdStories from "./id.stories";
+
+<Meta of={IdStories} />
+
+# Id
+
+`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.
+
+## Usage
+
+```tsx
+import {Id} from "@khanacademy/wonder-blocks-core";
+
+<Id id={maybeId}>{(id) => <div id={id}>Hello, world!</div>}</Id>;
+```
+
+## Examples
+
+### 1. Generating an id
+
+An identifier will always be generated if an `id` prop is not provided, or the
+provided `id` property is falsy.
+
+<Canvas withSource="open" of={IdStories.GeneratedIdExample} />
+
+### 2. Passthrough an id
+
+If an `id` prop is provided and it is truthy, that value will be passed through
+to the children.
+
+<Canvas sourceState="shown" of={IdStories.PassedThroughIdExample} />
diff --git a/__docs__/wonder-blocks-core/use-unique-id.mdx b/__docs__/wonder-blocks-core/use-unique-id.mdx
index a65d7fd2d..4891b23e2 100644
--- a/__docs__/wonder-blocks-core/use-unique-id.mdx
+++ b/__docs__/wonder-blocks-core/use-unique-id.mdx
@@ -1,10 +1,13 @@
 import {Meta, Story, Canvas} from "@storybook/blocks";
-import * as UseUniqueIdStories from './use-unique-id.stories';
+import * as UseUniqueIdStories from "./use-unique-id.stories";
 
 <Meta of={UseUniqueIdStories} />
 
 # `useUniqueIdWithoutMock`
 
+DEPRECATED: Will be removed in a future release. Use `useId` from React or
+the `Id` component.
+
 This hook is similar to `<UniqueIDProvider mockOnFirstRender={false}>`.
 It will return `null` on the initial render and then the same identifier
 factory for each subsequent render. The identifier factory is unique to
@@ -19,6 +22,9 @@ render tree.
 
 # `useUniqueIdWithMock`
 
+DEPRECATED: Will be removed in a future release. Use `useId` from React or
+the `Id` component.
+
 This hook is similar to `<UniqueIDProvider mockOnFirstRender={true}>`.
 It will return a mock identifier factory on the initial render that doesn'that
 guarantee identifier uniqueness. Mock mode can help things appear on the screen
diff --git a/packages/wonder-blocks-core/src/components/id-provider.tsx b/packages/wonder-blocks-core/src/components/id-provider.tsx
index 7b87c9e26..c8f7f5d7b 100644
--- a/packages/wonder-blocks-core/src/components/id-provider.tsx
+++ b/packages/wonder-blocks-core/src/components/id-provider.tsx
@@ -28,6 +28,9 @@ type Props = {
 };
 
 /**
+ * @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,
@@ -54,9 +57,6 @@ type Props = {
  *  )}
  * </IDProvider>
  * ```
- *
- * @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 IDProvider extends React.Component<Props> {
     static defaultId = "wb-id";
diff --git a/packages/wonder-blocks-core/src/components/id.tsx b/packages/wonder-blocks-core/src/components/id.tsx
index 7bf054302..a058cff9c 100644
--- a/packages/wonder-blocks-core/src/components/id.tsx
+++ b/packages/wonder-blocks-core/src/components/id.tsx
@@ -16,7 +16,10 @@ type Props = {
 };
 
 /**
- * A component that provides an identifier to its children.
+ * `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.
diff --git a/packages/wonder-blocks-core/src/components/unique-id-provider.tsx b/packages/wonder-blocks-core/src/components/unique-id-provider.tsx
index fb086c4fd..520f2bec1 100644
--- a/packages/wonder-blocks-core/src/components/unique-id-provider.tsx
+++ b/packages/wonder-blocks-core/src/components/unique-id-provider.tsx
@@ -44,6 +44,9 @@ type Props = {
 };
 
 /**
+ * @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
@@ -70,9 +73,6 @@ type Props = {
  *  )}
  * </UniqueIDProvider>
  * ```
- *
- * @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 UniqueIDProvider extends React.Component<Props> {
     // @ts-expect-error [FEI-5019] - TS2564 - Property '_idFactory' has no initializer and is not definitely assigned in the constructor.