@vtex/faststore-plugin-buyer-portal 2.0.8 → 2.0.9

package/docs/superpowers/plans/2026-06-26-contracts-listing-selection-search-pagination.md

@@ -0,0 +1,1070 @@
+# Contracts Listing — Selection, Search & Local Pagination Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the SUMA contracts listing support checkbox multi-selection, local search, and local pagination — without the checkbox accidentally triggering a contract switch.
+
+**Architecture:** All contracts are already loaded client-side. A new pure-helper module (`filterContracts`, `paginate`) plus a thin `useContractListing` hook drive search + pagination. Selection reuses the existing `useContractSelection`. `ContractListItem` splits its click target: the checkbox selects (stops propagation), the row body switches. New presentational components add the search/pagination header, a tri-state "Select all" row, and a floating selection bar.
+
+**Tech Stack:** React + TypeScript, FastStore plugin, `@faststore/ui` (Icon, useUI), SCSS with `data-fs-bp-*` attributes, Vitest (node env).
+
+## Global Constraints
+
+- Plugin boundary: this is a plugin, no `yarn dev`; verify via `make check`.
+- Page size: **25** contracts per page.
+- Search: **local**, case-insensitive substring over `name` and `email`.
+- Select-all scope: **all filtered contracts** (across pages); selection persists across page/search changes.
+- Remove button: **no-op placeholder** (bulk delete is future).
+- Keep the contract-switch flow (`useSwitchContract`) and ⌘/Ctrl+A select-all keyboard shortcut.
+- Tests run in **node env** (no jsdom/renderHook) — test pure functions, not React hooks.
+- Typecheck has ~133 pre-existing env errors from linked `@faststore/core`; bar = **no new errors in touched files**.
+- Icons: next=`ChevronRight` (shared Icon); prev=`ChevronRight` rotated 180° via CSS; Remove leading icon=`MinusCircle` (shared Icon); clear=`@faststore/ui` `Icon name="X"`; indeterminate checkbox = CSS bar.
+
+---
+
+### Task 1: Pure listing helpers (filter + paginate)
+
+**Files:**
+- Create: `src/features/contracts/hooks/contractListingHelpers.ts`
+- Test: `src/features/contracts/hooks/__tests__/contractListingHelpers.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `filterContracts(contracts: ContractData[], term: string): ContractData[]`
+  - `type PageResult = { pageItems: ContractData[]; from: number; to: number; total: number; hasPrev: boolean; hasNext: boolean }`
+  - `paginate(items: ContractData[], page: number, pageSize: number): PageResult`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "vitest";
+
+import { filterContracts, paginate } from "../contractListingHelpers";
+
+import type { ContractData } from "../../types";
+
+const make = (id: string, name: string, email = ""): ContractData =>
+  ({ id, name, email }) as ContractData;
+
+const contracts = [
+  make("1", "Stellar Global", "ops@stellar.com"),
+  make("2", "Aether Energy"),
+  make("3", "Alpha Logistics", "hi@alpha.io"),
+];
+
+describe("filterContracts", () => {
+  it("returns all contracts for an empty or whitespace term", () => {
+    expect(filterContracts(contracts, "")).toHaveLength(3);
+    expect(filterContracts(contracts, "   ")).toHaveLength(3);
+  });
+
+  it("matches name case-insensitively", () => {
+    const result = filterContracts(contracts, "alpha");
+    expect(result.map((c) => c.id)).toEqual(["3"]);
+  });
+
+  it("matches email case-insensitively", () => {
+    const result = filterContracts(contracts, "STELLAR.COM");
+    expect(result.map((c) => c.id)).toEqual(["1"]);
+  });
+
+  it("returns empty when nothing matches", () => {
+    expect(filterContracts(contracts, "zzz")).toEqual([]);
+  });
+});
+
+describe("paginate", () => {
+  const items = Array.from({ length: 50 }, (_, i) => make(String(i + 1), `C${i + 1}`));
+
+  it("returns the first page with correct interval and flags", () => {
+    const r = paginate(items, 1, 25);
+    expect(r.pageItems).toHaveLength(25);
+    expect([r.from, r.to, r.total]).toEqual([1, 25, 50]);
+    expect(r.hasPrev).toBe(false);
+    expect(r.hasNext).toBe(true);
+  });
+
+  it("returns the last page with a partial slice", () => {
+    const r = paginate(items.slice(0, 30), 2, 25);
+    expect(r.pageItems).toHaveLength(5);
+    expect([r.from, r.to, r.total]).toEqual([26, 30, 30]);
+    expect(r.hasPrev).toBe(true);
+    expect(r.hasNext).toBe(false);
+  });
+
+  it("clamps a page past the end to the last valid page", () => {
+    const r = paginate(items.slice(0, 30), 99, 25);
+    expect(r.from).toBe(26);
+    expect(r.to).toBe(30);
+  });
+
+  it("handles an empty list", () => {
+    const r = paginate([], 1, 25);
+    expect(r.pageItems).toEqual([]);
+    expect([r.from, r.to, r.total]).toEqual([0, 0, 0]);
+    expect(r.hasPrev).toBe(false);
+    expect(r.hasNext).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `yarn vitest run src/features/contracts/hooks/__tests__/contractListingHelpers.test.ts`
+Expected: FAIL (module/exports not found)
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ts
+import type { ContractData } from "../types";
+
+export type PageResult = {
+  pageItems: ContractData[];
+  from: number;
+  to: number;
+  total: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+};
+
+export function filterContracts(
+  contracts: ContractData[],
+  term: string
+): ContractData[] {
+  const q = term.trim().toLowerCase();
+  if (!q) return contracts;
+  return contracts.filter((c) => {
+    const name = (c.name ?? "").toLowerCase();
+    const email = (c.email ?? "").toLowerCase();
+    return name.includes(q) || email.includes(q);
+  });
+}
+
+export function paginate(
+  items: ContractData[],
+  page: number,
+  pageSize: number
+): PageResult {
+  const total = items.length;
+  const lastPage = Math.max(1, Math.ceil(total / pageSize));
+  const safePage = Math.min(Math.max(1, page), lastPage);
+  const start = (safePage - 1) * pageSize;
+  const pageItems = items.slice(start, start + pageSize);
+  const from = total === 0 ? 0 : start + 1;
+  const to = total === 0 ? 0 : start + pageItems.length;
+  return {
+    pageItems,
+    from,
+    to,
+    total,
+    hasPrev: safePage > 1,
+    hasNext: safePage < lastPage,
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `yarn vitest run src/features/contracts/hooks/__tests__/contractListingHelpers.test.ts`
+Expected: PASS (all cases)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/features/contracts/hooks/contractListingHelpers.ts src/features/contracts/hooks/__tests__/contractListingHelpers.test.ts
+git commit -m "feat(suma): add contract listing filter + paginate helpers"
+```
+
+---
+
+### Task 2: `useContractListing` hook
+
+**Files:**
+- Create: `src/features/contracts/hooks/useContractListing.ts`
+- Modify: `src/features/contracts/hooks/index.ts`
+
+**Interfaces:**
+- Consumes: `filterContracts`, `paginate`, `PageResult` (Task 1).
+- Produces:
+  ```ts
+  type UseContractListingReturn = {
+    searchTerm: string;
+    setSearch: (term: string) => void;
+    page: number;
+    nextPage: () => void;
+    prevPage: () => void;
+    pageItems: ContractData[];
+    filteredIds: string[];
+    from: number;
+    to: number;
+    total: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+  };
+  function useContractListing(args: { contracts: ContractData[]; pageSize?: number }): UseContractListingReturn;
+  ```
+
+- [ ] **Step 1: Write the hook**
+
+```ts
+import { useMemo, useState } from "react";
+
+import { filterContracts, paginate } from "./contractListingHelpers";
+
+import type { ContractData } from "../types";
+
+const DEFAULT_PAGE_SIZE = 25;
+
+export type UseContractListingReturn = {
+  searchTerm: string;
+  setSearch: (term: string) => void;
+  page: number;
+  nextPage: () => void;
+  prevPage: () => void;
+  pageItems: ContractData[];
+  filteredIds: string[];
+  from: number;
+  to: number;
+  total: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+};
+
+export function useContractListing({
+  contracts,
+  pageSize = DEFAULT_PAGE_SIZE,
+}: {
+  contracts: ContractData[];
+  pageSize?: number;
+}): UseContractListingReturn {
+  const [searchTerm, setSearchTerm] = useState("");
+  const [page, setPage] = useState(1);
+
+  const filtered = useMemo(
+    () => filterContracts(contracts, searchTerm),
+    [contracts, searchTerm]
+  );
+
+  const result = useMemo(
+    () => paginate(filtered, page, pageSize),
+    [filtered, page, pageSize]
+  );
+
+  const setSearch = (term: string) => {
+    setSearchTerm(term);
+    setPage(1);
+  };
+
+  const nextPage = () => result.hasNext && setPage((p) => p + 1);
+  const prevPage = () => result.hasPrev && setPage((p) => Math.max(1, p - 1));
+
+  return {
+    searchTerm,
+    setSearch,
+    page,
+    nextPage,
+    prevPage,
+    pageItems: result.pageItems,
+    filteredIds: filtered.map((c) => c.id),
+    from: result.from,
+    to: result.to,
+    total: result.total,
+    hasPrev: result.hasPrev,
+    hasNext: result.hasNext,
+  };
+}
+```
+
+- [ ] **Step 2: Export from the hooks barrel**
+
+In `src/features/contracts/hooks/index.ts` add:
+
+```ts
+export { useContractListing } from "./useContractListing";
+export type { UseContractListingReturn } from "./useContractListing";
+```
+
+- [ ] **Step 3: Typecheck the new files**
+
+Run: `yarn typecheck 2>&1 | grep -E "useContractListing|contractListingHelpers" || echo "clean"`
+Expected: `clean`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/contracts/hooks/useContractListing.ts src/features/contracts/hooks/index.ts
+git commit -m "feat(suma): add useContractListing hook for local search + pagination"
+```
+
+---
+
+### Task 3: `ContractListItem` — split checkbox (select) from row (switch)
+
+**Files:**
+- Modify: `src/features/contracts/components/ContractListItem/ContractListItem.tsx`
+
+**Interfaces:**
+- Produces (new prop contract):
+  ```ts
+  type ContractListItemProps = {
+    contract: ContractData;
+    isSelected: boolean;
+    orgUnitId: string;
+    onSelect: (id: string, event: React.MouseEvent) => void; // replaces onModifierClick/onShiftClick
+  };
+  ```
+- Consumes: `useSwitchContract` (existing), `useUI` (existing).
+
+- [ ] **Step 1: Replace the props and handlers**
+
+Full new file content:
+
+```tsx
+import { useUI } from "@faststore/ui";
+
+import { LetterHighlight } from "../../../shared/components";
+import Icon from "../../../shared/components/Icon/Icon";
+import { useSwitchContract } from "../../hooks";
+
+import type { ContractData } from "../../types";
+
+export type ContractListItemProps = {
+  contract: ContractData;
+  isSelected: boolean;
+  orgUnitId: string;
+  onSelect: (id: string, event: React.MouseEvent) => void;
+};
+
+export const ContractListItem = ({
+  contract,
+  isSelected,
+  orgUnitId,
+  onSelect,
+}: ContractListItemProps) => {
+  const displayName = contract.name ?? contract.email;
+  const { pushToast } = useUI();
+  const { switchContract, loading } = useSwitchContract();
+
+  const handleCheckboxClick = (event: React.MouseEvent) => {
+    event.stopPropagation();
+    event.preventDefault();
+    onSelect(contract.id, event);
+  };
+
+  const handleRowClick = async () => {
+    if (loading) return;
+    const switched = await switchContract(contract.id, { orgUnitId });
+    if (!switched) {
+      pushToast({
+        message: "Failed to switch contract. Please try again.",
+        status: "ERROR",
+      });
+    }
+  };
+
+  return (
+    <div
+      data-fs-bp-contract-list-item
+      data-fs-bp-contract-list-item-selected={isSelected || undefined}
+      data-fs-bp-contract-list-item-loading={loading || undefined}
+      onClick={handleRowClick}
+      role="row"
+      aria-selected={isSelected}
+      aria-busy={loading || undefined}
+    >
+      <div
+        data-fs-bp-contract-list-item-checkbox
+        role="checkbox"
+        aria-checked={isSelected}
+        aria-label={`Select ${displayName ?? "contract"}`}
+        tabIndex={0}
+        onClick={handleCheckboxClick}
+      >
+        {isSelected && <Icon name="Check" width={12} height={12} />}
+      </div>
+
+      <LetterHighlight size="small" letter={displayName ?? ""} />
+
+      <span data-fs-bp-contract-list-item-name>{displayName}</span>
+
+      {contract.isDefault && (
+        <span
+          data-fs-bp-contract-list-item-default-badge
+          aria-label="Default contract"
+        >
+          <Icon name="Default" width={20} height={20} />
+        </span>
+      )}
+    </div>
+  );
+};
+```
+
+- [ ] **Step 2: Lint + typecheck this file**
+
+Run: `yarn lint 2>&1 | tail -3 && yarn typecheck 2>&1 | grep ContractListItem || echo "clean"`
+Expected: lint `Done`, typecheck `clean`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/features/contracts/components/ContractListItem/ContractListItem.tsx
+git commit -m "feat(suma): split contract row checkbox-select from row-switch"
+```
+
+---
+
+### Task 4: `ContractsListHeader` — search + local pagination
+
+**Files:**
+- Create: `src/features/contracts/components/ContractsListHeader/ContractsListHeader.tsx`
+- Create: `src/features/contracts/components/ContractsListHeader/index.ts`
+
+**Interfaces:**
+- Consumes: `InternalSearch` (`src/features/shared/components`), `Icon` (`@faststore/ui`).
+- Produces:
+  ```ts
+  type ContractsListHeaderProps = {
+    searchTerm: string;
+    onSearch: (term: string) => void;
+    from: number;
+    to: number;
+    total: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    onPrev: () => void;
+    onNext: () => void;
+  };
+  ```
+
+- [ ] **Step 1: Write the component**
+
+`ContractsListHeader.tsx`:
+
+```tsx
+import { Icon } from "@faststore/ui";
+
+import { InternalSearch } from "../../../shared/components";
+
+export type ContractsListHeaderProps = {
+  searchTerm: string;
+  onSearch: (term: string) => void;
+  from: number;
+  to: number;
+  total: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+};
+
+export const ContractsListHeader = ({
+  searchTerm,
+  onSearch,
+  from,
+  to,
+  total,
+  hasPrev,
+  hasNext,
+  onPrev,
+  onNext,
+}: ContractsListHeaderProps) => {
+  return (
+    <div data-fs-bp-contracts-list-header>
+      <div data-fs-bp-contracts-list-header-search>
+        <InternalSearch defaultValue={searchTerm} textSearch={onSearch} />
+      </div>
+
+      <div data-fs-bp-contracts-list-header-pagination>
+        <span data-fs-bp-contracts-list-header-interval>
+          {from} — {to} of {total}
+        </span>
+        <button
+          type="button"
+          data-fs-bp-contracts-list-header-prev
+          onClick={onPrev}
+          disabled={!hasPrev}
+          aria-label="Previous page"
+        >
+          <Icon name="ChevronRight" width={20} height={20} />
+        </button>
+        <button
+          type="button"
+          data-fs-bp-contracts-list-header-next
+          onClick={onNext}
+          disabled={!hasNext}
+          aria-label="Next page"
+        >
+          <Icon name="ChevronRight" width={20} height={20} />
+        </button>
+      </div>
+    </div>
+  );
+};
+```
+
+`index.ts`:
+
+```ts
+export { ContractsListHeader } from "./ContractsListHeader";
+export type { ContractsListHeaderProps } from "./ContractsListHeader";
+```
+
+- [ ] **Step 2: Lint + typecheck**
+
+Run: `yarn lint 2>&1 | tail -3 && yarn typecheck 2>&1 | grep ContractsListHeader || echo "clean"`
+Expected: lint `Done`, typecheck `clean`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/features/contracts/components/ContractsListHeader/
+git commit -m "feat(suma): add contracts list header with search + pagination"
+```
+
+---
+
+### Task 5: `ContractSelectAllRow` — tri-state select all
+
+**Files:**
+- Create: `src/features/contracts/components/ContractSelectAllRow/ContractSelectAllRow.tsx`
+- Create: `src/features/contracts/components/ContractSelectAllRow/index.ts`
+
+**Interfaces:**
+- Produces:
+  ```ts
+  type ContractSelectAllRowProps = {
+    total: number;          // count of filtered contracts (label + all-selected check)
+    selectedCount: number;  // how many of the filtered are selected
+    onToggle: () => void;   // layout decides select-all vs clear
+  };
+  ```
+
+- [ ] **Step 1: Write the component**
+
+`ContractSelectAllRow.tsx`:
+
+```tsx
+import Icon from "../../../shared/components/Icon/Icon";
+
+export type ContractSelectAllRowProps = {
+  total: number;
+  selectedCount: number;
+  onToggle: () => void;
+};
+
+export const ContractSelectAllRow = ({
+  total,
+  selectedCount,
+  onToggle,
+}: ContractSelectAllRowProps) => {
+  const allSelected = total > 0 && selectedCount >= total;
+  const indeterminate = selectedCount > 0 && !allSelected;
+
+  return (
+    <div data-fs-bp-contract-select-all-row onClick={onToggle}>
+      <div
+        data-fs-bp-contract-select-all-checkbox
+        data-fs-bp-contract-select-all-checkbox-checked={allSelected || undefined}
+        data-fs-bp-contract-select-all-checkbox-indeterminate={
+          indeterminate || undefined
+        }
+        role="checkbox"
+        aria-checked={indeterminate ? "mixed" : allSelected}
+        aria-label="Select all contracts"
+        tabIndex={0}
+      >
+        {allSelected && <Icon name="Check" width={12} height={12} />}
+      </div>
+      <span data-fs-bp-contract-select-all-label>Select all ({total})</span>
+    </div>
+  );
+};
+```
+
+(The indeterminate state renders a CSS minus bar via `[data-fs-bp-contract-select-all-checkbox-indeterminate]` — Task 7.)
+
+`index.ts`:
+
+```ts
+export { ContractSelectAllRow } from "./ContractSelectAllRow";
+export type { ContractSelectAllRowProps } from "./ContractSelectAllRow";
+```
+
+- [ ] **Step 2: Lint + typecheck**
+
+Run: `yarn lint 2>&1 | tail -3 && yarn typecheck 2>&1 | grep ContractSelectAllRow || echo "clean"`
+Expected: lint `Done`, typecheck `clean`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/features/contracts/components/ContractSelectAllRow/
+git commit -m "feat(suma): add tri-state select-all row"
+```
+
+---
+
+### Task 6: `ContractSelectionBar` — floating selection pill
+
+**Files:**
+- Create: `src/features/contracts/components/ContractSelectionBar/ContractSelectionBar.tsx`
+- Create: `src/features/contracts/components/ContractSelectionBar/index.ts`
+
+**Interfaces:**
+- Produces:
+  ```ts
+  type ContractSelectionBarProps = {
+    selectedCount: number;
+    onClear: () => void;
+    onRemove: () => void;   // no-op placeholder from the layout for now
+    canRemove?: boolean;    // hide Remove for single-contract orgs (default true)
+  };
+  ```
+
+- [ ] **Step 1: Write the component**
+
+`ContractSelectionBar.tsx`:
+
+```tsx
+import { Icon as UIIcon } from "@faststore/ui";
+
+import Icon from "../../../shared/components/Icon/Icon";
+
+export type ContractSelectionBarProps = {
+  selectedCount: number;
+  onClear: () => void;
+  onRemove: () => void;
+  canRemove?: boolean;
+};
+
+export const ContractSelectionBar = ({
+  selectedCount,
+  onClear,
+  onRemove,
+  canRemove = true,
+}: ContractSelectionBarProps) => {
+  if (selectedCount === 0) return null;
+
+  return (
+    <div data-fs-bp-contract-selection-bar role="toolbar">
+      <button
+        type="button"
+        data-fs-bp-contract-selection-bar-clear
+        onClick={onClear}
+        aria-label="Clear selection"
+      >
+        <UIIcon name="X" width={20} height={20} />
+      </button>
+
+      <span data-fs-bp-contract-selection-bar-count>
+        {selectedCount} selected
+      </span>
+
+      {canRemove && (
+        <button
+          type="button"
+          data-fs-bp-contract-selection-bar-remove
+          onClick={onRemove}
+        >
+          <Icon name="MinusCircle" width={20} height={20} />
+          Remove
+        </button>
+      )}
+    </div>
+  );
+};
+```
+
+`index.ts`:
+
+```ts
+export { ContractSelectionBar } from "./ContractSelectionBar";
+export type { ContractSelectionBarProps } from "./ContractSelectionBar";
+```
+
+- [ ] **Step 2: Lint + typecheck**
+
+Run: `yarn lint 2>&1 | tail -3 && yarn typecheck 2>&1 | grep ContractSelectionBar || echo "clean"`
+Expected: lint `Done`, typecheck `clean`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/features/contracts/components/ContractSelectionBar/
+git commit -m "feat(suma): add floating contract selection bar"
+```
+
+---
+
+### Task 7: Wire it together — `ContractSelectionList` + `ContractListingLayout` + SCSS
+
+**Files:**
+- Modify: `src/features/contracts/components/ContractSelectionList/ContractSelectionList.tsx`
+- Modify: `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx`
+- Modify: `src/features/contracts/layouts/ContractListingLayout/contract-listing-layout.scss`
+
+**Interfaces:**
+- Consumes: `useContractListing` (Task 2), `useContractSelection` (existing),
+  `ContractsListHeader` (4), `ContractSelectAllRow` (5), `ContractSelectionBar` (6),
+  `ContractListItem` (3, `onSelect`).
+
+- [ ] **Step 1: Slim `ContractSelectionList` to render page items + onSelect**
+
+Full new content:
+
+```tsx
+import { ContractListItem } from "../ContractListItem/ContractListItem";
+
+import type { ContractData } from "../../types";
+
+export type ContractSelectionListProps = {
+  contracts: ContractData[];
+  orgUnitId: string;
+  selectedIds: Set<string>;
+  onKeyDown: (event: React.KeyboardEvent) => void;
+  onSelect: (id: string, event: React.MouseEvent) => void;
+};
+
+export const ContractSelectionList = ({
+  contracts,
+  orgUnitId,
+  selectedIds,
+  onKeyDown,
+  onSelect,
+}: ContractSelectionListProps) => {
+  if (contracts.length === 0) {
+    return (
+      <div data-fs-bp-contract-selection-list-empty>
+        <p>No contracts found for this organizational unit.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-fs-bp-contract-selection-list
+      onKeyDown={onKeyDown}
+      tabIndex={0}
+      role="grid"
+      aria-label="Contracts"
+    >
+      <div data-fs-bp-contract-selection-list-rows>
+        {contracts.map((contract) => (
+          <ContractListItem
+            key={contract.id}
+            contract={contract}
+            isSelected={selectedIds.has(contract.id)}
+            orgUnitId={orgUnitId}
+            onSelect={onSelect}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 2: Update `ContractListingLayout` imports**
+
+Add to the contracts component imports and hooks import:
+
+```tsx
+import { ContractSelectionList } from "../../components/ContractSelectionList/ContractSelectionList";
+import { ContractsListHeader } from "../../components/ContractsListHeader";
+import { ContractSelectAllRow } from "../../components/ContractSelectAllRow";
+import { ContractSelectionBar } from "../../components/ContractSelectionBar";
+import {
+  useContractSelection,
+  useContractSwitchChannel,
+  useContractListing,
+} from "../../hooks";
+```
+
+- [ ] **Step 3: Replace selection wiring in `ContractListingLayout`**
+
+Replace the `handleModifierClickWithContext` / `handleShiftClickWithContext` block and the destructure of `useContractSelection` with listing + selection wiring driven by filtered IDs:
+
+```tsx
+  const {
+    selectedIds,
+    handleModifierClick,
+    handleShiftClick,
+    handleSelectAll,
+    clearSelection,
+  } = useContractSelection();
+
+  const {
+    searchTerm,
+    setSearch,
+    pageItems,
+    filteredIds,
+    from,
+    to,
+    total,
+    hasPrev,
+    hasNext,
+    nextPage,
+    prevPage,
+  } = useContractListing({ contracts });
+
+  const selectedInFiltered = filteredIds.filter((id) =>
+    selectedIds.has(id)
+  ).length;
+
+  const handleSelect = (id: string, event: React.MouseEvent) => {
+    if (event.shiftKey) {
+      handleShiftClick(id, filteredIds);
+    } else {
+      handleModifierClick(id);
+    }
+  };
+
+  const handleToggleSelectAll = () => {
+    if (selectedInFiltered > 0) {
+      clearSelection();
+    } else {
+      handleSelectAll(filteredIds);
+    }
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if ((event.metaKey || event.ctrlKey) && event.key === "a") {
+      event.preventDefault();
+      handleSelectAll(filteredIds);
+    }
+  };
+```
+
+(Remove the now-unused `allIds` const and old handlers.)
+
+- [ ] **Step 4: Replace the multi-contract JSX branch**
+
+Replace the `<ContractSelectionList .../>` branch (the `: (` else of `isSingleContract`) with:
+
+```tsx
+            <>
+              <ContractsListHeader
+                searchTerm={searchTerm}
+                onSearch={setSearch}
+                from={from}
+                to={to}
+                total={total}
+                hasPrev={hasPrev}
+                hasNext={hasNext}
+                onPrev={prevPage}
+                onNext={nextPage}
+              />
+              <ContractSelectAllRow
+                total={total}
+                selectedCount={selectedInFiltered}
+                onToggle={handleToggleSelectAll}
+              />
+              <ContractSelectionList
+                contracts={pageItems}
+                orgUnitId={orgUnit.id}
+                selectedIds={selectedIds}
+                onKeyDown={handleKeyDown}
+                onSelect={handleSelect}
+              />
+              <ContractSelectionBar
+                selectedCount={selectedIds.size}
+                onClear={clearSelection}
+                onRemove={() => {
+                  // TODO: bulk contract removal (future feature)
+                }}
+              />
+            </>
+```
+
+- [ ] **Step 5: Add SCSS**
+
+In `contract-listing-layout.scss`, inside `[data-fs-bp-contract-listing-section] { … }`, replace the old `[data-fs-bp-contract-selection-toolbar]` block with the following new blocks (header, select-all row, indeterminate checkbox, floating bar):
+
+```scss
+  [data-fs-bp-contracts-list-header] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--fs-bp-gap-4);
+    padding: var(--fs-bp-padding-4) 0;
+
+    [data-fs-bp-contracts-list-header-search] {
+      flex: 1;
+      max-width: 22rem;
+    }
+
+    [data-fs-bp-contracts-list-header-pagination] {
+      display: flex;
+      align-items: center;
+      gap: var(--fs-bp-gap-2);
+
+      [data-fs-bp-contracts-list-header-interval] {
+        font-size: var(--fs-bp-text-body);
+        color: var(--fs-bp-color-neutral-7);
+        white-space: nowrap;
+      }
+
+      button {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background: none;
+        border: none;
+        padding: var(--fs-bp-padding-1);
+        cursor: pointer;
+        color: var(--fs-bp-color-neutral-8);
+        border-radius: var(--fs-bp-border-radius-full);
+
+        &:hover:not(:disabled) {
+          background-color: var(--fs-bp-color-neutral-1);
+        }
+
+        &:disabled {
+          color: var(--fs-bp-color-neutral-3);
+          cursor: default;
+        }
+      }
+
+      [data-fs-bp-contracts-list-header-prev] [data-fs-icon] {
+        transform: rotate(180deg);
+      }
+    }
+  }
+
+  [data-fs-bp-contract-select-all-row] {
+    display: flex;
+    align-items: center;
+    gap: var(--fs-bp-gap-3);
+    padding: var(--fs-bp-padding-3) var(--fs-bp-padding-2);
+    cursor: pointer;
+    user-select: none;
+
+    [data-fs-bp-contract-select-all-checkbox] {
+      flex-shrink: 0;
+      width: 1.125rem;
+      height: 1.125rem;
+      border: 2px solid #9e9e9e;
+      border-radius: 2px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: var(--fs-bp-color-white);
+
+      &[data-fs-bp-contract-select-all-checkbox-checked],
+      &[data-fs-bp-contract-select-all-checkbox-indeterminate] {
+        background-color: var(--fs-bp-color-brand);
+        border-color: var(--fs-bp-color-brand);
+      }
+
+      &[data-fs-bp-contract-select-all-checkbox-indeterminate]::after {
+        content: "";
+        width: 0.625rem;
+        height: 2px;
+        background-color: var(--fs-bp-color-white);
+        border-radius: 1px;
+      }
+    }
+
+    [data-fs-bp-contract-select-all-label] {
+      font-size: var(--fs-bp-text-body);
+      font-weight: var(--fs-bp-weight-medium);
+      color: var(--fs-bp-color-neutral-7);
+    }
+  }
+
+  [data-fs-bp-contract-list-item-checkbox] {
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: 2px solid var(--fs-bp-color-brand);
+      outline-offset: 2px;
+    }
+  }
+
+  [data-fs-bp-contract-selection-bar] {
+    position: fixed;
+    left: 50%;
+    bottom: var(--fs-bp-spacing-6);
+    transform: translateX(-50%);
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    gap: var(--fs-bp-gap-6);
+    padding: var(--fs-bp-padding-3) var(--fs-bp-padding-6);
+    background-color: var(--fs-bp-color-white);
+    border-radius: var(--fs-bp-border-radius-full);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+
+    [data-fs-bp-contract-selection-bar-clear] {
+      display: inline-flex;
+      background: none;
+      border: none;
+      padding: 0;
+      cursor: pointer;
+      color: var(--fs-bp-color-neutral-7);
+    }
+
+    [data-fs-bp-contract-selection-bar-count] {
+      font-size: var(--fs-bp-text-body);
+      font-weight: var(--fs-bp-weight-medium);
+      color: var(--fs-bp-color-black);
+    }
+
+    [data-fs-bp-contract-selection-bar-remove] {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--fs-bp-gap-2);
+      background: none;
+      border: none;
+      padding: 0;
+      cursor: pointer;
+      font-size: var(--fs-bp-text-body);
+      font-weight: var(--fs-bp-weight-medium);
+      color: #d32f2f;
+
+      &:hover {
+        text-decoration: underline;
+      }
+    }
+  }
+```
+
+- [ ] **Step 6: Full check**
+
+Run: `yarn lint 2>&1 | tail -3 && yarn vitest run 2>&1 | tail -6 && yarn typecheck 2>&1 | grep -E "contracts/(components|layouts|hooks)" | grep -vE "pre-existing" || echo "no new contracts errors"`
+Expected: lint `Done`, all tests pass, no new typecheck errors in touched contracts files.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/features/contracts/
+git commit -m "feat(suma): wire contracts listing search, pagination, selection UI"
+```
+
+---
+
+### Task 8: Final verification + changelog
+
+**Files:**
+- Possibly: changelog entry (per repo convention — check `docs`/CI `changelog.yml`).
+
+- [ ] **Step 1: Run the full gate**
+
+Run: `make check 2>&1 | tail -30`
+Expected: lint + tests pass; typecheck error count equals the pre-existing baseline (133) with **no** entries referencing the new/edited contracts files.
+
+- [ ] **Step 2: Confirm no new typecheck errors in touched files**
+
+Run: `yarn typecheck 2>&1 | grep -E "contractListingHelpers|useContractListing|ContractListItem|ContractsListHeader|ContractSelectAllRow|ContractSelectionBar|ContractSelectionList|ContractListingLayout" || echo "TOUCHED FILES CLEAN"`
+Expected: `TOUCHED FILES CLEAN`
+
+- [ ] **Step 3: Manual verification (when linked to `b2bfaststoredev.store`)**
+
+Walk the 9 checks in the design doc's "Manual verification" section: pagination, search-resets-page, checkbox-selects-without-switch, shift-range, tri-state select-all + clear, selection persistence across page/search, row-body switch still works, Remove inert.
+
+## Self-Review
+
+- **Spec coverage:** click split (Task 3) · search (2,4) · pagination 25/prev-next (1,2,4) · select-all all-filtered + indeterminate (5,7) · floating bar + no-op Remove (6,7) · persistence (selection Set independent of paging, 7) · styling (7) · tests for helpers (1). All spec sections covered.
+- **Placeholder scan:** the only intentional placeholder is the Remove `onClick` no-op, explicitly required by the spec and marked with a TODO comment. No vague steps.
+- **Type consistency:** `onSelect(id, event)` is defined in Task 3 and consumed identically in Tasks 7. `filteredIds: string[]`, `from/to/total/hasPrev/hasNext` from Task 2 match the props passed in Task 7. `selectedCount`/`total`/`onToggle` (Task 5) and `selectedCount`/`onClear`/`onRemove` (Task 6) match the layout wiring in Task 7.