Addon-Docs: Improve object control JSON editor accessibility

AGENTS.md

@@ -9,7 +9,7 @@ This file is the canonical instruction source for coding agents. Files like `CLA
 Storybook is a large TypeScript monorepo. The git root is the repo root, the main code lives in `code/`, and build tooling lives in `scripts/`. The default branch is `next`.
 
 - **Base branch**: `next` (all PRs should target `next`, not `main`)
-- **Node.js**: `22.21.1` (see `.nvmrc`)
+- **Node.js**: `22.22.1` (see `.nvmrc`)
 - **Package Manager**: Yarn Berry
 - **Task orchestration**: NX plus the custom `yarn task` runner
 - **CI environment**: Linux and Windows

code/addons/docs/src/blocks/components/ArgsTable/ArgsTable.stories.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { action } from 'storybook/actions';
+import { expect, fireEvent } from 'storybook/test';
 import { styled } from 'storybook/theming';
 
 import * as ArgRow from './ArgRow.stories';
@@ -123,6 +124,46 @@ export const AllControls = {
   },
 };
 
+export const AllControlsObjectSet: Story = {
+  args: AllControls.args,
+  play: async ({ canvas, canvasElement, step }) => {
+    await step('Switch the object control from empty to filled', async () => {
+      const setObjectButton = canvasElement.querySelector('#set-someObject') as HTMLButtonElement;
+
+      await fireEvent.click(setObjectButton);
+
+      const rawInput = canvas.getByRole('textbox', { name: 'Edit someObject as JSON' });
+      await expect(rawInput).toBeVisible();
+      await expect(rawInput).toHaveValue('{}');
+    });
+  },
+};
+
+export const AllControlsFilled: Story = {
+  args: {
+    ...AllControls.args,
+    args: {
+      someArray: [1, 2, 3],
+      someBoolean: true,
+      someColor: '#ff4785',
+      someDate: new Date('2020-10-20T09:30:02'),
+      someObject: {
+        name: 'Storybook',
+        nested: { enabled: true, count: 2 },
+      },
+      someString: 'Filled string control',
+      number: 42,
+      range: 24,
+      radio: 'b',
+      inlineRadio: 'c',
+      check: ['a'],
+      inlineCheck: ['b', 'c'],
+      select: 'b',
+      multiSelect: ['a', 'c'],
+    },
+  },
+};
+
 const AddonPanelLayout = styled.div(({ theme }) => ({
   fontSize: theme.typography.size.s2 - 1,
   background: theme.background.content,

code/addons/docs/src/blocks/controls/Object.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { destroyAnnouncer } from '@react-aria/live-announcer';
 
-import { fn } from 'storybook/test';
+import { expect, fireEvent, fn, waitFor, within } from 'storybook/test';
 
 import { ObjectControl } from './Object';
 
@@ -12,6 +13,9 @@ const meta = {
     name: 'object',
     onChange: fn(),
   },
+  beforeEach: async () => {
+    destroyAnnouncer();
+  },
 } satisfies Meta<typeof ObjectControl>;
 
 export default meta;
@@ -140,3 +144,96 @@ export const ArraySmallViewport: Story = {
     chromatic: { viewports: [320] },
   },
 };
+
+export const JsonEditorValidation: Story = {
+  args: {
+    value: { label: 'value' },
+    onChange: fn(),
+  },
+  play: async ({ args, canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Open the raw JSON editor and verify it is described', async () => {
+      const editAsJsonButton = canvas.getByRole('switch', { name: 'Edit object as JSON' });
+
+      await expect(editAsJsonButton).toHaveAttribute('aria-describedby');
+      await fireEvent.click(editAsJsonButton);
+      await expect(
+        canvas.getByRole('textbox', { name: 'Edit object as JSON' })
+      ).toBeInTheDocument();
+    });
+
+    await step('Show a parse error for invalid JSON', async () => {
+      const rawInput = canvas.getByRole('textbox', { name: 'Edit object as JSON' });
+
+      rawInput.focus();
+      await fireEvent.change(rawInput, { target: { value: '{"label":' } });
+      rawInput.blur();
+
+      await waitFor(() => {
+        expect(document.body).toHaveLiveRegion({
+          text: 'Invalid JSON: Unexpected end of JSON input',
+        });
+      });
+      await expect(rawInput).toHaveAttribute('aria-invalid', 'true');
+
+      const error = await canvas.findByText('Invalid JSON: Unexpected end of JSON input');
+      await expect(rawInput).toHaveAttribute('aria-describedby', error.getAttribute('id') ?? '');
+
+      await expect(args.onChange).not.toHaveBeenCalled();
+    });
+
+    await step('Clear the parse error after entering valid JSON', async () => {
+      const rawInput = canvas.getByRole('textbox', { name: 'Edit object as JSON' });
+
+      rawInput.focus();
+      await fireEvent.change(rawInput, { target: { value: '{"label":"updated"}' } });
+      rawInput.blur();
+
+      await waitFor(async () => {
+        await expect(document.body).not.toHaveLiveRegion();
+      });
+      await expect(rawInput).toHaveAttribute('aria-invalid', 'false');
+      await expect(rawInput).not.toHaveAttribute('aria-describedby');
+      await expect(args.onChange).toHaveBeenCalledWith({ label: 'updated' });
+    });
+  },
+};
+
+export const JsonEditorErrorReset: Story = {
+  args: {
+    value: { label: 'value' },
+    onChange: fn(),
+  },
+  play: async ({ canvas, step }) => {
+    await step('Create a parse error in the raw JSON editor', async () => {
+      const editAsJsonButton = canvas.getByRole('switch', { name: 'Edit object as JSON' });
+      await fireEvent.click(editAsJsonButton);
+
+      const rawInput = canvas.getByRole('textbox', { name: 'Edit object as JSON' });
+      rawInput.focus();
+      await fireEvent.change(rawInput, { target: { value: '{"label":' } });
+      rawInput.blur();
+
+      await waitFor(() => {
+        expect(document.body).toHaveLiveRegion({
+          text: 'Invalid JSON: Unexpected end of JSON input',
+        });
+      });
+      await expect(rawInput).toHaveAttribute('aria-invalid', 'true');
+    });
+
+    await step('Clear stale parse errors after closing and reopening the editor', async () => {
+      const editAsJsonButton = canvas.getByRole('switch', { name: 'Edit object as JSON' });
+      await fireEvent.click(editAsJsonButton);
+      await fireEvent.click(canvas.getByRole('switch', { name: 'Edit object as JSON' }));
+
+      const rawInput = canvas.getByRole('textbox', { name: 'Edit object as JSON' });
+      await waitFor(async () => {
+        await expect(document.body).not.toHaveLiveRegion();
+      });
+      await expect(rawInput).toHaveAttribute('aria-invalid', 'false');
+      await expect(rawInput).not.toHaveAttribute('aria-describedby');
+    });
+  },
+};

code/addons/docs/src/blocks/controls/Object.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment happy-dom
+import React from 'react';
+
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ThemeProvider, convert, themes } from 'storybook/theming';
+
+import { ObjectControl } from './Object';
+
+describe('Object control', () => {
+  it('renders function values without crashing', () => {
+    const onChange = vi.fn();
+
+    render(
+      <ThemeProvider theme={convert(themes.light)}>
+        <ObjectControl
+          name="object"
+          storyId="story--function"
+          value={vi.fn()}
+          onChange={onChange}
+        />
+      </ThemeProvider>
+    );
+
+    const rawInput = screen.getByRole('textbox', { name: 'Edit object as JSON' });
+
+    expect((rawInput as HTMLTextAreaElement).value).toBe('');
+  });
+});