[wb1812.3.migratewb] Update some docs and improve visibility of depre…

…cation notices

__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} />

__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

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";

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.

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.