docs: add information about @storybook/preview-api useArgs hook

docs/snippets/react/page-story-args-within-story.js.mdx

@@ -0,0 +1,32 @@
+```js
+// my-component/component.stories.js|jsx
+
+import { useArgs } from '@storybook/preview-api';
+import { Switch } from '.';
+
+export default {
+  title: 'Inputs/Switch',
+  component: Switch,
+};
+
+export const Example = {
+  args: {
+    isChecked: false,
+    label: 'Switch Me!',
+  },
+  /**
+   * 👇 React believes the Storybook function "useArgs" is a hook, but it's really not.
+   * Using a named capital-letter function prevents an ESLint warning related to this.
+   * Don't lint? You can use an arrow function instead.
+   */
+  render: function Render(args) {
+    const [{ isChecked }, updateArgs] = useArgs();
+
+    function onChange() {
+      updateArgs({ isChecked: !isChecked });
+    }
+
+    return <Switch {...args} onChange={onChange} isChecked={isChecked} />;
+  },
+};
+```

docs/snippets/react/page-story-args-within-story.ts.mdx

@@ -0,0 +1,36 @@
+```ts
+// my-component/component.stories.ts|tsx
+
+import { StoryObj, Meta } from '@storybook/react';
+import { useArgs } from '@storybook/preview-api';
+import { Switch } from '.';
+
+const meta: Meta<typeof Switch> = {
+  title: 'Inputs/Switch',
+  component: Switch,
+};
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+export const Example = {
+  args: {
+    isChecked: false,
+    label: 'Switch Me!',
+  },
+  /**
+   * 👇 React believes the Storybook function "useArgs" is a hook, but it's really not.
+   * Using a named capital-letter function prevents an ESLint warning related to this.
+   * Don't lint? You can use an arrow function instead.
+   */
+  render: function Render(args) {
+    const [{ isChecked }, updateArgs] = useArgs();
+
+    function onChange() {
+      updateArgs({ isChecked: !isChecked });
+    }
+
+    return <Switch {...args} onChange={onChange} isChecked={isChecked} />;
+  },
+};
+```

docs/writing-stories/args.md

@@ -207,6 +207,21 @@ Similarly, special formats are available for dates and colors. Date objects will
 
 Args specified through the URL will extend and override any default values of args set on the story.
 
+## Setting args from within a story
+
+Components with interactivity often need their containing component, or page, to respond to events, modify their state, then pass a changed arg back to the rendered component to reflect the change. For example, you would want a Switch component to be checked by a user and the arg shown in Storybook to reflect the change. This can be accomplished by using the `useArgs` hook exported by `@storybook/preview-api`:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'react/this-pr-example-snippet.js.mdx',
+    'react/page-story-args-within-story.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
 ## Mapping to complex arg values
 
 Complex values such as JSX elements cannot be serialized to the manager (e.g., the Controls addon) or synced with the URL. Arg values can be "mapped" from a simple string to a complex type using the `mapping` property in `argTypes` to work around this limitation. It works in any arg but makes the most sense when used with the `select` control type.