Apakah semua state yang mungkin terjadi sudah punya representasi UI?
Apakah state yang berbahaya sudah dicegah?
Apakah loading/error/empty/permission/optimistic state punya desain yang konsisten?
Apakah bug bisa direproduksi tanpa menjalankan seluruh aplikasi?
Apakah reviewer bisa melihat behavior, bukan hanya membaca kode?

Given environment X,
when component starts in state Y,
and user performs interaction Z,
then observable UI should become W.

Component.stories.tsx
  ├─ Default
  ├─ Controlled
  ├─ Uncontrolled
  ├─ Loading
  ├─ Empty
  ├─ Error
  ├─ Disabled
  ├─ PermissionDenied
  ├─ Optimistic
  ├─ WithLongContent
  ├─ WithKeyboardNavigation
  ├─ InDarkTheme
  └─ Regression_<bug-id>

import type { Meta, StoryObj } from '@storybook/react';
import { StatusBadge } from './StatusBadge';

const meta = {
  title: 'Components/StatusBadge',
  component: StatusBadge,
  args: {
    status: 'pending',
  },
} satisfies Meta<typeof StatusBadge>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Pending: Story = {
  args: { status: 'pending' },
};

export const Approved: Story = {
  args: { status: 'approved' },
};

export const Rejected: Story = {
  args: { status: 'rejected' },
};

export const Complex: Story = {
  args: {
    entireReduxState: hugeState,
    queryCache: hugeCache,
    routerState: hugeRouterState,
  },
};

export const PermissionDenied: Story = {
  args: {
    decision: {
      allowed: false,
      reason: 'Only case supervisor can approve this escalation.',
    },
  },
};

import type { Decorator } from '@storybook/react';
import { ThemeProvider } from '../theme/ThemeProvider';
import { PermissionProvider } from '../permissions/PermissionProvider';

export const withAppProviders: Decorator = (Story, context) => {
  const role = context.parameters.role ?? 'case-worker';

  return (
    <ThemeProvider mode="light">
      <PermissionProvider role={role}>
        <Story />
      </PermissionProvider>
    </ThemeProvider>
  );
};

export const SupervisorCanApprove: Story = {
  parameters: {
    role: 'supervisor',
  },
};

export const WorkerCannotApprove: Story = {
  parameters: {
    role: 'case-worker',
  },
};

Args menjelaskan input komponen.
Parameters menjelaskan environment story.
Decorators membangun environment itu.
Play function menjalankan interaksi.

1 baseline happy path
1 permission denied
1 loading skeleton
1 server error with retry
1 workflow submitting
1 workflow failed with recovery
1 closed entity where action unavailable
1 invalid form state
1 regression story for known bug

export function buildCase(overrides: Partial<CaseViewModel> = {}): CaseViewModel {
  return {
    id: 'CASE-1001',
    title: 'Delayed reporting threshold breach',
    status: 'open',
    priority: 'medium',
    assignee: { id: 'u1', name: 'Rina' },
    permissions: {
      canApprove: true,
      canEscalate: true,
      canClose: false,
    },
    ...overrides,
  };
}

export const ClosedCase: Story = {
  args: {
    case: buildCase({
      status: 'closed',
      permissions: {
        canApprove: false,
        canEscalate: false,
        canClose: false,
      },
    }),
  },
};

export const Controlled: Story = {
  render: function ControlledStory(args) {
    const [value, setValue] = React.useState('overview');

    return (
      <Tabs
        {...args}
        value={value}
        onValueChange={setValue}
      />
    );
  },
};

export const Uncontrolled: Story = {
  args: {
    defaultValue: 'overview',
  },
};

controlled: user click calls onChange and parent updates value
controlled-readonly: user click calls onChange but value stays if parent refuses
uncontrolled: user click updates internal state
reset: changing key resets uncontrolled state

function PermissionStoryHarness({
  role,
  children,
}: {
  role: Role;
  children: React.ReactNode;
}) {
  const permissions = createPermissionDecisionMap(role);

  return (
    <PermissionProvider value={permissions}>
      {children}
    </PermissionProvider>
  );
}

export const AsSupervisor: Story = {
  decorators: [
    (Story) => (
      <PermissionStoryHarness role="supervisor">
        <Story />
      </PermissionStoryHarness>
    ),
  ],
};

export const AsReadOnlyAuditor: Story = {
  decorators: [
    (Story) => (
      <PermissionStoryHarness role="auditor">
        <Story />
      </PermissionStoryHarness>
    ),
  ],
};

provider value apa yang dipakai?
role/capability apa yang sedang disimulasikan?
apakah consumer fallback/default value pernah terjadi?
apakah component harus fail fast kalau provider hilang?

export const MissingProvider: Story = {
  render: () => <PermissionAwareButton action="approve" />,
};

function CaseSummaryView({ state }: { state: CaseSummaryState }) {
  if (state.type === 'loading') return <Skeleton />;
  if (state.type === 'error') return <ErrorMessage error={state.error} />;
  if (state.type === 'empty') return <EmptyState />;
  return <CaseSummary data={state.data} />;
}

export const Loading: Story = {
  args: {
    state: { type: 'loading' },
  },
};

export const Error: Story = {
  args: {
    state: {
      type: 'error',
      error: new Error('Network timeout'),
    },
  },
};

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

function createStoryQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
        staleTime: Infinity,
      },
    },
  });
}

export const WithQueryClient: Story = {
  decorators: [
    (Story) => {
      const [client] = React.useState(createStoryQueryClient);

      return (
        <QueryClientProvider client={client}>
          <Story />
        </QueryClientProvider>
      );
    },
  ],
};

import { expect, userEvent, within } from '@storybook/test';

export const ApproveHappyPath: Story = {
  args: {
    case: buildCase({ status: 'open' }),
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.click(canvas.getByRole('button', { name: /approve/i }));
    await userEvent.type(canvas.getByLabelText(/reason/i), 'Evidence verified.');
    await userEvent.click(canvas.getByRole('button', { name: /confirm/i }));

    await expect(canvas.getByText(/approval submitted/i)).toBeVisible();
  },
};

keyboard navigation
open/close modal
form validation
happy-path workflow
error recovery
permission-blocked interaction
optimistic UI transition
regression reproduction

focus visible
keyboard only
screen-reader labels
error messages
aria-invalid
aria-describedby
disabled vs aria-disabled
modal focus trap
escape close policy
loading announcement
empty state landmark

export const InvalidRequired: Story = {
  args: {
    label: 'Escalation reason',
    value: '',
    error: 'Reason is required before escalation.',
    required: true,
  },
};

export const KeyboardNavigation: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.tab();
    await expect(canvas.getByRole('tab', { name: /overview/i })).toHaveFocus();

    await userEvent.keyboard('{ArrowRight}');
    await expect(canvas.getByRole('tab', { name: /history/i })).toHaveFocus();
  },
};

type SubmitWorkflow =
  | { tag: 'idle' }
  | { tag: 'editing'; draft: Draft }
  | { tag: 'confirming'; draft: Draft }
  | { tag: 'submitting'; draft: Draft; requestId: string }
  | { tag: 'failed'; draft: Draft; error: string }
  | { tag: 'submitted'; confirmationId: string };

export const Confirming: Story = {
  args: {
    workflow: {
      tag: 'confirming',
      draft: buildDraft({ reason: 'Evidence verified.' }),
    },
  },
};

export const Failed: Story = {
  args: {
    workflow: {
      tag: 'failed',
      draft: buildDraft({ reason: 'Evidence verified.' }),
      error: 'The case was already closed by another reviewer.',
    },
  },
};

Tidak bisa menampilkan failed state tanpa memanggil API asli.
Tidak bisa menampilkan pending state tanpa timing hack.
Tidak bisa menampilkan permission denied tanpa login sebagai role tertentu.
Tidak bisa menampilkan stale data tanpa memodifikasi backend.

Ketika user membuka modal approve, lalu data case berubah menjadi closed, tombol confirm tetap enabled dan command tetap dikirim.

export const Regression_CaseClosedWhileConfirming: Story = {
  args: {
    case: buildCase({ status: 'closed' }),
    initialWorkflow: {
      tag: 'confirming',
      draft: buildDraft({ reason: 'Evidence verified.' }),
    },
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await expect(
      canvas.getByRole('button', { name: /confirm approval/i })
    ).toBeDisabled();

    await expect(
      canvas.getByText(/case is already closed/i)
    ).toBeVisible();
  },
};

Regression_<condition>_<expectedProtection>
Regression_ClosedCase_DisablesApprove
Regression_StaleMutation_ShowsRecovery
Regression_DuplicateSubmit_BlocksSecondCommand

empty table with filters applied
error with retry
long translated label
RTL layout
dark mode
small viewport
readonly permission
validation error under focus
modal with nested scroll
optimistic row pending commit

export const ReviewMatrix: Story = {
  render: () => (
    <div className="grid gap-6">
      <CaseCard case={buildCase({ status: 'open' })} />
      <CaseCard case={buildCase({ status: 'escalated' })} />
      <CaseCard case={buildCase({ status: 'closed' })} />
      <CaseCardSkeleton />
      <CaseCardError message="Cannot load case." />
    </div>
  ),
};

Default is not coverage.

story lambat
scenario tersembunyi
dependency tidak jelas
provider coupling tidak terlihat

await expect(mockDispatch).toHaveBeenCalledWith({ type: 'SET_OPEN', value: true });

await expect(canvas.getByRole('dialog')).toBeVisible();

src/features/case-approval/
  ui/
    CaseApprovalPanel.tsx
    CaseApprovalPanel.stories.tsx
    CaseApprovalPanel.test.tsx
  model/
    approvalWorkflow.ts
    approvalWorkflow.test.ts
  testing/
    builders.ts
    storyHarness.tsx

src/shared/ui/tabs/
  Tabs.tsx
  Tabs.stories.tsx
  Tabs.a11y.stories.tsx
  Tabs.test.tsx
  Tabs.contract.md

[ ] Ada Default story.
[ ] Ada loading, empty, error jika data-driven.
[ ] Ada disabled/readonly/permission-denied jika action-driven.
[ ] Ada controlled dan uncontrolled story jika component controllable.
[ ] Ada keyboard interaction story jika interactive primitive.
[ ] Ada long content / overflow story.
[ ] Ada regression story untuk bug yang pernah terjadi.
[ ] Story tidak memanggil backend production.
[ ] Provider/decorator tidak menyembunyikan dependency penting.
[ ] Story menggunakan accessible queries dalam play function.
[ ] State yang ditampilkan sesuai invariant domain.

Component.tsx
Component.stories.tsx
Component.test.tsx
builders.ts
storyHarness.tsx

export function buildUser(overrides: Partial<UserViewModel> = {}): UserViewModel {
  return {
    id: 'u1',
    name: 'Ayu Pratama',
    role: 'reviewer',
    status: 'active',
    ...overrides,
  };
}

export function StoryHarness({
  children,
  role = 'reviewer',
}: {
  children: React.ReactNode;
  role?: Role;
}) {
  return (
    <ThemeProvider mode="light">
      <PermissionProvider value={createPermissions(role)}>
        {children}
      </PermissionProvider>
    </ThemeProvider>
  );
}

const meta = {
  title: 'Features/User/UserSummaryCard',
  component: UserSummaryCard,
  decorators: [
    (Story) => (
      <StoryHarness>
        <Story />
      </StoryHarness>
    ),
  ],
} satisfies Meta<typeof UserSummaryCard>;

Engineer bisa mereproduksi bug state tanpa menjalankan seluruh aplikasi.
Designer bisa review edge state, bukan hanya happy path.
QA bisa memahami state matrix.
New engineer bisa belajar component contract dari story.
Regression state hidup sebagai artifact.
Provider dan state ownership terlihat.
Interaction tests memvalidasi behavior penting.

Kalau state sulit dibuat story-nya, state model kemungkinan belum cukup eksplisit.

1 Default story
1 Loading story
1 Empty story
1 Error story
1 PermissionDenied story
1 Optimistic/Pending story
1 FailedRecovery story
1 Regression story dari bug nyata
1 Play function untuk happy path
1 Play function untuk error recovery

State mana yang sulit diset?
Provider mana yang terlalu berat?
Dependency mana yang harus dibuat injectable?
Apakah public API komponen sudah benar?
Apakah story membuat invariant lebih jelas?