Page is a composition root, not a dumping ground.

Apa screen ini?
Data apa yang dibutuhkan?
State mana yang hidup di URL?
Command apa yang tersedia?
Permission apa yang membatasi action?
Boundary loading/error apa yang tepat?
View mana yang menerima read model?

const status = searchParams.get('status') || 'open';
const page = Number(searchParams.get('page') || 1);
const q = searchParams.get('q') || '';

// logic parsing ini lalu disalin ke banyak component

export type CaseSearchPageInput = {
  query: string;
  status: CaseStatusFilter;
  page: number;
  pageSize: number;
};

export function parseCaseSearchPageInput(searchParams: URLSearchParams): CaseSearchPageInput {
  return {
    query: searchParams.get('q')?.trim() ?? '',
    status: parseStatusFilter(searchParams.get('status')),
    page: clampPositiveInteger(searchParams.get('page'), 1),
    pageSize: clampPageSize(searchParams.get('pageSize'), 25),
  };
}

export function serializeCaseSearchPageInput(input: CaseSearchPageInput): URLSearchParams {
  const params = new URLSearchParams();

  if (input.query) params.set('q', input.query);
  if (input.status !== 'all') params.set('status', input.status);
  if (input.page !== 1) params.set('page', String(input.page));
  if (input.pageSize !== 25) params.set('pageSize', String(input.pageSize));

  return params;
}

Invalid URL tidak boleh membuat screen crash.
Invalid URL harus di-canonicalize menjadi input valid.
Serialization harus stabil.
Default value jangan menulis noise ke URL.

const query = useQuery({
  queryKey: ['cases', status, q, page, pageSize, user.tenantId],
  queryFn: () => fetch(`/api/cases?...`).then((r) => r.json()),
});

export const caseQueryKeys = {
  all: ['cases'] as const,
  search: (tenantId: string, input: CaseSearchPageInput) =>
    [...caseQueryKeys.all, 'search', tenantId, canonicalizeCaseSearchInput(input)] as const,
  detail: (tenantId: string, caseId: string) =>
    [...caseQueryKeys.all, 'detail', tenantId, caseId] as const,
};

export function caseSearchQueryOptions(tenantId: string, input: CaseSearchPageInput) {
  return {
    queryKey: caseQueryKeys.search(tenantId, input),
    queryFn: () => caseApi.search({ tenantId, ...input }),
    staleTime: 30_000,
  };
}

export function useCaseSearchQuery(tenantId: string, input: CaseSearchPageInput) {
  return useQuery(caseSearchQueryOptions(tenantId, input));
}

const casesQuery = useCaseSearchQuery(tenantId, pageInput);

type CasesPageModel =
  | { kind: 'forbidden' }
  | { kind: 'loading' }
  | { kind: 'error'; error: PageError }
  | {
      kind: 'ready';
      input: CaseSearchPageInput;
      rows: CaseRow[];
      totalCount: number;
      selectedIds: string[];
      capabilities: CasePageCapabilities;
      pending: {
        assign: boolean;
        close: boolean;
      };
      commands: {
        changeInput(next: CaseSearchPageInput): void;
        selectRows(ids: string[]): void;
        openCase(caseId: string): void;
        assignSelected(): Promise<void>;
        closeCase(caseId: string): Promise<void>;
      };
    };

export function useCasesPageModel(): CasesPageModel {
  const navigate = useNavigate();
  const [searchParams, setSearchParams] = useSearchParams();

  const tenant = useTenantContext();
  const currentUser = useCurrentUser();

  const input = parseCaseSearchPageInput(searchParams);
  const capabilities = useCasePageCapabilities({ user: currentUser, tenantId: tenant.id });

  const [selectedIds, setSelectedIds] = useState<string[]>([]);

  const casesQuery = useCaseSearchQuery(tenant.id, input);
  const assignCommand = useAssignCasesCommand({ tenantId: tenant.id });
  const closeCommand = useCloseCaseCommand({ tenantId: tenant.id });
  const assignDialog = useAssignCasesDialog();
  const closeDialog = useCloseCaseDialog();

  usePageAnalytics('cases.search', {
    tenantId: tenant.id,
    status: input.status,
  });

  if (!capabilities.canView) {
    return { kind: 'forbidden' };
  }

  if (casesQuery.isPending) {
    return { kind: 'loading' };
  }

  if (casesQuery.isError) {
    return { kind: 'error', error: toPageError(casesQuery.error) };
  }

  return {
    kind: 'ready',
    input,
    rows: toCaseRows(casesQuery.data.items),
    totalCount: casesQuery.data.totalCount,
    selectedIds,
    capabilities,
    pending: {
      assign: assignCommand.isPending,
      close: closeCommand.isPending,
    },
    commands: {
      changeInput(next) {
        setSearchParams(serializeCaseSearchPageInput({ ...next, page: 1 }));
        setSelectedIds([]);
      },
      selectRows(ids) {
        setSelectedIds(ids);
      },
      openCase(caseId) {
        navigate(`/cases/${caseId}`);
      },
      async assignSelected() {
        if (selectedIds.length === 0) return;
        if (!capabilities.canAssign) return;

        const result = await assignDialog.open({ caseIds: selectedIds });
        if (result.kind !== 'confirmed') return;

        await assignCommand.assignCases({
          caseIds: selectedIds,
          assigneeId: result.assigneeId,
        });

        setSelectedIds([]);
      },
      async closeCase(caseId) {
        if (!capabilities.canClose) return;

        const result = await closeDialog.open({ caseId });
        if (result.kind !== 'confirmed') return;

        await closeCommand.closeCase({
          caseId,
          reason: result.reason,
        });
      },
    },
  };
}

Page model boleh mengorkestrasi banyak boundary.
Tetapi setiap boundary tetap punya modul internal sendiri.

export function CasesPageRoute() {
  const model = useCasesPageModel();

  if (model.kind === 'forbidden') return <ForbiddenPage />;
  if (model.kind === 'loading') return <CasesPageSkeleton />;
  if (model.kind === 'error') return <CasesPageError error={model.error} />;

  return <CasesPageView model={model} />;
}

function CasesPageView({ model }: { model: Extract<CasesPageModel, { kind: 'ready' }> }) {
  return (
    <PageShell title="Cases">
      <CasesFilters value={model.input} onChange={model.commands.changeInput} />

      <CasesToolbar
        selectedCount={model.selectedIds.length}
        canAssign={model.capabilities.canAssign}
        isAssigning={model.pending.assign}
        onAssignSelected={model.commands.assignSelected}
      />

      <CasesTable
        rows={model.rows}
        selectedIds={model.selectedIds}
        totalCount={model.totalCount}
        onSelectionChange={model.commands.selectRows}
        onOpenCase={model.commands.openCase}
        onCloseCase={model.commands.closeCase}
      />
    </PageShell>
  );
}

Route component = memilih state branch.
Page view = menampilkan ready state.
Child component = render + emit intent.

// route loader prefetches critical query
export async function loader({ request, context }: LoaderArgs) {
  const url = new URL(request.url);
  const input = parseCaseSearchPageInput(url.searchParams);
  const tenantId = await requireTenantId(context);

  await context.queryClient.ensureQueryData(
    caseSearchQueryOptions(tenantId, input)
  );

  return { tenantId, input };
}

export function CasesRoute() {
  const loaderData = useLoaderData<typeof loader>();
  return <CasesPage tenantId={loaderData.tenantId} initialInput={loaderData.input} />;
}

function CasesPage() {
  const query = useQuery(...);

  if (query.isLoading) return <Spinner />;
  if (query.isError) return <div>Error</div>;

  return <BigPage />;
}

export function CasesRouteBoundary() {
  return (
    <ErrorBoundary fallback={<CasesPageCrashFallback />}>
      <Suspense fallback={<CasesPageSkeleton />}>
        <CasesPage />
      </Suspense>
    </ErrorBoundary>
  );
}

<PageShell title="Cases">
  <CasesFilters />

  <ErrorBoundary fallback={<CasesTableError />}>
    <Suspense fallback={<CasesTableSkeleton />}>
      <CasesTableRegion />
    </Suspense>
  </ErrorBoundary>

  <Suspense fallback={<CaseStatsSkeleton />}>
    <CaseStatsRegion />
  </Suspense>
</PageShell>

Boundary harus mengikuti UX recovery unit.
Jika user bisa memulihkan table tanpa merusak seluruh page, table punya boundary sendiri.
Jika seluruh page invalid, page punya boundary sendiri.

type CasePageCapabilities = {
  canView: boolean;
  canCreate: boolean;
  canAssign: boolean;
  canClose: boolean;
  readOnlyReason?: string;
};

export function useCasePageCapabilities(input: {
  user: CurrentUser;
  tenantId: string;
}): CasePageCapabilities {
  return {
    canView: hasCapability(input.user, 'case:view', input.tenantId),
    canCreate: hasCapability(input.user, 'case:create', input.tenantId),
    canAssign: hasCapability(input.user, 'case:assign', input.tenantId),
    canClose: hasCapability(input.user, 'case:close', input.tenantId),
  };
}

user intent
→ precondition
→ confirmation/modal
→ mutation
→ cache invalidation/direct cache update
→ UI local state cleanup
→ feedback
→ navigation/close

async function closeCase(caseId: string) {
  if (!capabilities.canClose) {
    toast.error('You do not have permission to close this case.');
    return;
  }

  const confirmation = await closeDialog.open({ caseId });
  if (confirmation.kind !== 'confirmed') return;

  try {
    await closeCommand.closeCase({
      caseId,
      reason: confirmation.reason,
    });

    toast.success('Case closed.');
  } catch (error) {
    const pageError = toPageError(error);
    toast.error(pageError.message);
  }
}

export function useCloseCaseWorkflow(input: {
  tenantId: string;
  capabilities: CasePageCapabilities;
}) {
  const dialog = useCloseCaseDialog();
  const command = useCloseCaseCommand({ tenantId: input.tenantId });
  const toast = useToast();

  return {
    isPending: command.isPending,
    async closeCase(caseId: string) {
      if (!input.capabilities.canClose) return;

      const confirmation = await dialog.open({ caseId });
      if (confirmation.kind !== 'confirmed') return;

      await command.closeCase({ caseId, reason: confirmation.reason });
      toast.success('Case closed.');
    },
  };
}

// selectedRows disimpan di URL padahal tidak shareable
?selected=c1,c2,c3,c4,c5

// server data disalin ke local state tanpa alasan
const [cases, setCases] = useState(query.data?.items ?? []);

const rows = query.data ? toCaseRows(query.data.items) : [];

async function createCase(input: CreateCaseFormInput) {
  const result = await createCaseCommand.createCase(input);
  navigate(`/cases/${result.caseId}`, { replace: true });
}

Apakah navigation terjadi sebelum atau sesudah cache invalidation?
Apakah destination page membutuhkan prefetch?
Apakah replace atau push history?
Apakah back button harus kembali ke search result?
Apakah draft harus dibersihkan setelah navigation?

export function useCasesPageAnalytics(input: {
  tenantId: string;
  filters: CaseSearchPageInput;
}) {
  useEffect(() => {
    analytics.track('cases_page_viewed', {
      tenantId: input.tenantId,
      status: input.filters.status,
    });
  }, [input.tenantId, input.filters.status]);
}

const analyticsKey = `${tenantId}:${input.status}`;

useEffect(() => {
  analytics.track('cases_page_viewed', { tenantId, status: input.status });
}, [analyticsKey]);

useEffect(() => {
  analytics.track('cases_page_viewed', { tenantId, status: input.status });
}, [tenantId, input.status]);

it('parses invalid page as page 1', () => {
  const input = parseCaseSearchPageInput(new URLSearchParams('page=-10'));
  expect(input.page).toBe(1);
});

it('includes tenant and canonical input in query key', () => {
  const options = caseSearchQueryOptions('tenant-1', {
    query: 'abc',
    status: 'open',
    page: 1,
    pageSize: 25,
  });

  expect(options.queryKey).toEqual([
    'cases',
    'search',
    'tenant-1',
    { query: 'abc', status: 'open', page: 1, pageSize: 25 },
  ]);
});

it('renders assign button disabled when user cannot assign', () => {
  render(
    <CasesPageView
      model={readyCasesModel({
        capabilities: { canView: true, canAssign: false, canClose: false, canCreate: false },
        selectedIds: ['c1'],
      })}
    />
  );

  expect(screen.getByRole('button', { name: /assign/i })).toBeDisabled();
});

it('updates URL when filters change', async () => {
  const router = createMemoryRouter([
    { path: '/cases', element: <CasesRoute /> },
  ], {
    initialEntries: ['/cases?status=open'],
  });

  render(<RouterProvider router={router} />, {
    wrapper: createAppTestProviders(),
  });

  await user.selectOptions(screen.getByLabelText(/status/i), 'closed');

  expect(router.state.location.search).toContain('status=closed');
});

Extract query options.
Extract command hook.
Extract page model.
Extract view component.
Extract modal workflow.
Extract view model mapper.

function CasesPage() {
  return <CasesTable />;
}

function CasesTable() {
  const searchParams = useSearchParams();
  const query = useQuery(...);
  const navigate = useNavigate();
  const mutation = useMutation(...);
}

const [filters, setFilters] = useState(parse(searchParams));

useEffect(() => {
  setFilters(parse(searchParams));
}, [searchParams]);

const filters = parseCaseSearchPageInput(searchParams);

const [draft, setDraft] = useState(filters);

function applyFilters() {
  setSearchParams(serializeCaseSearchPageInput(draft));
}

draft filter = local state
committed filter = URL state

Setiap variable yang memengaruhi queryFn harus masuk queryKey.
Canonicalize input sebelum menjadi key.
Masukkan tenant/security scope jika data berbeda per scope.

{canAssign && <AssignButton />}

async function assignSelected() {
  if (!capabilities.canAssign) return;
  // continue
}

Boundary placement mengikuti recovery unit.
Page-critical data gagal → page error.
Secondary widget gagal → widget error.
Table refetch pending → table region pending, bukan full page spinner.

const model = usePageLogic();

const model = useCasesPageModel();
model.commands.assignSelected();
model.commands.changeInput(next);

[ ] Route params dan search params diparse di satu tempat.
[ ] URL state punya canonical serializer.
[ ] Query key factory tidak inline di page.
[ ] Page model membedakan forbidden/loading/error/ready.
[ ] Server response di-map menjadi view model.
[ ] Child view menerima read model + intent handlers, bukan QueryClient/router/API.
[ ] Command punya precondition dan permission guard.
[ ] Mutation invalidation ada di command boundary.
[ ] Local page state tidak menduplikasi server state.
[ ] Draft state dibedakan dari committed URL/server state.
[ ] Suspense/error boundary mengikuti recovery unit.
[ ] Navigation setelah command diperlakukan sebagai bagian workflow.
[ ] Analytics effect punya dependency stabil.
[ ] Page integration test ada, tetapi view/mapper/command tetap punya test kecil.

features/cases/
  api/
    caseApi.ts
    caseQueryKeys.ts
    caseQueries.ts
    caseCommands.ts
  model/
    casePageInput.ts
    caseCapabilities.ts
    caseViewModel.ts
    caseErrors.ts
  workflows/
    useAssignCasesWorkflow.ts
    useCloseCaseWorkflow.ts
  ui/
    CasesFilters.tsx
    CasesToolbar.tsx
    CasesTable.tsx
    CasesPageView.tsx
  page/
    CasesRoute.tsx
    useCasesPageModel.ts

page → api/model/workflows/ui
ui → model types only, not api/query/router
api → transport/query only, not ui
model → pure functions/types
workflows → commands/dialog/toast/cache/navigation when needed

- URL state: q, actorId, actionType, dateRange, page
- Server state: audit log search
- Permission: canViewAuditLog, canExportAuditLog
- Command: export CSV
- View: filters, table, pagination, export button
- Error: forbidden, query failed, export failed
- Analytics: page viewed, export clicked

1. auditLogPageInput.ts
2. auditLogQueries.ts
3. auditLogCommands.ts
4. auditLogViewModel.ts
5. useAuditLogPageModel.ts
6. AuditLogPageView.tsx
7. tests for parser, query key, mapper, view behavior, export command

membaca route/URL,
memilih query,
mengecek capability,
menyusun view model,
menyediakan command,
menentukan loading/error boundary,
menyerahkan rendering detail ke view components.

mengandung semua markup,
query key inline,
mutation inline,
permission raw,
modal detail,
cache invalidation,
field validation,
dan table rendering sekaligus.

Page boleh smart sebagai orchestration root.
Tetapi setiap jenis kecerdasan harus punya boundary sendiri.