@burdenoff/microfe-movethewheels 2026.1013.2 → 2026.1016.1

package/src/movethewheels/components/pending-pick/PickReviewPanel.tsx

@@ -0,0 +1,326 @@
+import { useRef, useState } from 'react';
+import { PermissionProvider, usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import {
+  ApprovePickReviewDocument,
+  RejectPickReviewDocument,
+  RevokePickReviewDocument,
+  PickReviewHistoryDocument,
+  type PickReviewHistoryQuery,
+  type PendingPickTaskFragment,
+  type RecordMtwPickReviewInput,
+  type MtwPickReviewAction,
+} from '../../../generated/pending-pick-operations';
+import { confirmPickReviewAcknowledgement } from '../../utils/pickReviewAcknowledgement';
+import { useMoveTheWheels } from '../../providers/MoveTheWheelsProvider';
+import { useConditionApi, useConditionQuery } from '../../hooks/useContainerCondition';
+import { ContainerEvidencePicker, type SelectedEvidence } from '../ContainerEvidencePicker';
+import { ReuseField, ReusePager, ReuseState, reuseCard } from '../ReuseControls';
+import { Button } from '../ui';
+export function PickReviewPanel({ task }: { task: PendingPickTaskFragment }) {
+  const { workspaceId, currentUser, apiGatewayUrl } = useMoveTheWheels();
+  return (
+    <PermissionProvider scopeId={workspaceId ?? null} gateway="workspace">
+      <MoveReview
+        key={JSON.stringify([
+          workspaceId,
+          currentUser?.id,
+          apiGatewayUrl,
+          task.id,
+          task.intentHash,
+        ])}
+        task={task}
+      />
+    </PermissionProvider>
+  );
+}
+function MoveReview({ task }: { task: PendingPickTaskFragment }) {
+  const permissions = usePermissions(),
+    { currentUser, workspaceId } = useMoveTheWheels(),
+    request = useConditionApi('SINGLE_ATTEMPT');
+  const storageKey = JSON.stringify([
+    'mtw-review-intent',
+    workspaceId,
+    currentUser?.id,
+    task.id,
+    task.intentHash,
+  ]);
+  const [attemptKey, setAttemptKey] = useState<string | null>(() => {
+    try {
+      const value = sessionStorage.getItem(storageKey);
+      return value === null ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value)
+        ? value
+        : 'UNAVAILABLE';
+    } catch {
+      return 'UNAVAILABLE';
+    }
+  });
+  const uncertain = attemptKey !== null;
+  const [offset, setOffset] = useState(0),
+    [revision, setRevision] = useState(0),
+    [evidence, setEvidence] = useState<SelectedEvidence[]>([]),
+    [busy, setBusy] = useState(false),
+    [message, setMessage] = useState<string | null>(null);
+  const running = useRef(false);
+  const history = useConditionQuery<PickReviewHistoryQuery>(
+    PickReviewHistoryDocument,
+    permissions.hasPermission('mtw-move-review:list')
+      ? { taskId: task.id, limit: 10, offset }
+      : null,
+    revision
+  );
+  const page = history.data?.mtwPickReviewPage,
+    head = page?.latestDecision;
+  const independent =
+    currentUser?.id && currentUser.id !== task.createdBy && currentUser.id !== task.executorActorId;
+  const decision = async (form: HTMLFormElement, kind: 'APPROVE' | 'REJECT' | 'REVOKE') => {
+    if (
+      running.current ||
+      uncertain ||
+      !page ||
+      !independent ||
+      !permissions.hasPermission(`mtw-move-review:${kind.toLowerCase()}`)
+    )
+      return;
+    const data = new FormData(form),
+      field = (name: string) => String(data.get(name) ?? '').trim();
+    let input: RecordMtwPickReviewInput;
+    try {
+      if (
+        kind === 'APPROVE' &&
+        (!/(Z|[+-]\d{2}:\d{2})$/.test(field('validFrom')) ||
+          !/(Z|[+-]\d{2}:\d{2})$/.test(field('validUntil')))
+      )
+        throw new Error('Use explicit ISO timezone offsets for both validity bounds.');
+      const validFrom = kind === 'APPROVE' ? new Date(field('validFrom')).toISOString() : null;
+      const validUntil = kind === 'APPROVE' ? new Date(field('validUntil')).toISOString() : null;
+      const quantity = kind === 'APPROVE' ? Number(field('quantity')) : null;
+      const allowed = [
+        'RESERVE',
+        'STAGE',
+        'RELEASE_UNPICKED',
+        'RELEASE_STAGED_CUSTODY',
+        'SHORT_PICK',
+      ] as const;
+      const actions: MtwPickReviewAction[] =
+        kind === 'APPROVE' ? allowed.filter((action) => data.has(action)) : [];
+      if (
+        !field('note') ||
+        (kind === 'APPROVE' &&
+          (!actions.length ||
+            !Number.isInteger(quantity) ||
+            quantity === null ||
+            quantity < 1 ||
+            quantity > task.requestedQuantity ||
+            !evidence.length ||
+            !field('handlingReference') ||
+            !field('handlingRevision') ||
+            !field('sopReference') ||
+            !field('sopRevision')))
+      )
+        throw new Error('Review all required fields and select exact evidence.');
+      input = {
+        taskId: task.id,
+        intentHash: task.intentHash,
+        subjectActorId: task.executorActorId,
+        expectedPreviousDecisionId: head?.id ?? null,
+        expectedVersion: head?.version ?? 0,
+        actions,
+        quantityCeiling: quantity,
+        validFrom,
+        validUntil,
+        handlingPolicy:
+          kind === 'APPROVE'
+            ? { reference: field('handlingReference'), revision: field('handlingRevision') }
+            : null,
+        sop:
+          kind === 'APPROVE'
+            ? { reference: field('sopReference'), revision: field('sopRevision') }
+            : null,
+        evidence:
+          kind === 'APPROVE'
+            ? evidence.map(({ fileId, versionId }) => ({ fileId, versionId }))
+            : [],
+        note: field('note'),
+        idempotencyKey: crypto.randomUUID(),
+      };
+    } catch (failure) {
+      setMessage(failure instanceof Error ? failure.message : 'Check the review fields.');
+      return;
+    }
+    // Store the nonsecret request key before dispatch; refresh must never authorize resubmission.
+    try {
+      sessionStorage.setItem(storageKey, input.idempotencyKey);
+      setAttemptKey(input.idempotencyKey);
+    } catch {
+      setAttemptKey('UNAVAILABLE');
+      setMessage('The intended request key could not be preserved. No decision was submitted.');
+      return;
+    }
+    running.current = true;
+    setBusy(true);
+    setMessage(null);
+    try {
+      const document =
+        kind === 'APPROVE'
+          ? ApprovePickReviewDocument
+          : kind === 'REJECT'
+            ? RejectPickReviewDocument
+            : RevokePickReviewDocument;
+      const result = await request<unknown>(document, { input });
+      confirmPickReviewAcknowledgement(result, input, kind, currentUser?.id ?? '');
+      sessionStorage.removeItem(storageKey);
+      setAttemptKey(null);
+      setRevision((value) => value + 1);
+      setMessage('Review recorded. Stock is unchanged.');
+    } catch {
+      setMessage(
+        'The outcome is not confirmed. Preserve the intended request key and match it against review history; do not resend this decision.'
+      );
+    } finally {
+      running.current = false;
+      setBusy(false);
+    }
+  };
+  return (
+    <section className={reuseCard} aria-label="Independent move review">
+      <h4 className="font-semibold">Independent move review</h4>
+      <p>
+        Review only. No stock reservation, movement, qualification or physical safety certification.
+        Current stock and permissions must be checked again before any future execution.
+      </p>
+      <p className="break-all">
+        Exact intent SHA-256: {task.intentHash}; fixed executor: {task.executorActorId}
+      </p>
+      {permissions.isLoading && <p role="status">Checking review permissions…</p>}
+      {permissions.error && <p role="alert">Review permissions are unavailable.</p>}
+      {!permissions.isLoading && !permissions.hasPermission('mtw-move-review:list') && (
+        <p>You do not have permission to list move reviews.</p>
+      )}
+      <ReuseState loading={history.loading} error={history.error} />
+      {page && (
+        <>
+          <p>
+            Latest review: {page.reviewState}, evaluated {page.evaluatedAt}. Older approvals never
+            override a later rejection or revocation.
+          </p>
+          {page.items.map((item) => (
+            <article key={item.id} className="min-w-0 break-words rounded border p-3">
+              <p>
+                Version {item.version}: {item.kind} · {item.note}
+              </p>
+              <p className="break-all">
+                Reviewer {item.reviewerActorId}; receipt {item.id}; request key{' '}
+                {item.idempotencyKey}; intent {item.intentHash}
+              </p>
+              <p>
+                {item.actions.join(', ') || 'No actions granted'}; ceiling{' '}
+                {item.quantityCeiling ?? 'none'}; validity {item.validFrom ?? 'none'} to{' '}
+                {item.validUntil ?? 'none'} (exclusive).
+              </p>
+              <p>
+                Handling source{' '}
+                {item.handlingPolicy
+                  ? `${item.handlingPolicy.reference} · revision ${item.handlingPolicy.revision}`
+                  : 'none'}
+                ; SOP {item.sop ? `${item.sop.reference} · revision ${item.sop.revision}` : 'none'}.
+              </p>
+              {item.evidence.map((file) => (
+                <p key={file.versionId} className="break-all">
+                  Evidence {file.fileId}, version {file.versionId}, SHA-256 {file.sha256Hash};
+                  checked {file.checkedAt}.
+                </p>
+              ))}
+            </article>
+          ))}
+          <ReusePager
+            page={page}
+            offset={offset}
+            onChange={setOffset}
+            busy={busy || history.loading}
+          />
+        </>
+      )}
+      {!independent && <p>The creator and fixed executor cannot review this task.</p>}
+      {independent && page && (
+        <form onSubmit={(event) => event.preventDefault()}>
+          <fieldset disabled={busy || uncertain} className="space-y-3">
+            <legend>Record a decision on the exact intent</legend>
+            <ReuseField label="Decision note" name="note" maxLength={1000} />
+            {permissions.hasPermission('mtw-move-review:approve') && (
+              <details>
+                <summary>Approval scope and sourced handling review</summary>
+                <ReuseField
+                  label={`Quantity ceiling (1–${task.requestedQuantity})`}
+                  name="quantity"
+                  type="number"
+                />
+                <ReuseField label="Valid from (ISO with timezone)" name="validFrom" />
+                <ReuseField label="Valid until (exclusive, ISO with timezone)" name="validUntil" />
+                {(
+                  [
+                    'RESERVE',
+                    'STAGE',
+                    'RELEASE_UNPICKED',
+                    'RELEASE_STAGED_CUSTODY',
+                    'SHORT_PICK',
+                  ] as const
+                ).map((action) => (
+                  <label key={action} className="block">
+                    <input type="checkbox" name={action} /> {action}
+                  </label>
+                ))}
+                <ReuseField label="Handling policy reference" name="handlingReference" />
+                <ReuseField label="Handling policy revision" name="handlingRevision" />
+                <ReuseField label="SOP reference" name="sopReference" />
+                <ReuseField label="SOP revision" name="sopRevision" />
+                <ContainerEvidencePicker
+                  value={evidence}
+                  onChange={setEvidence}
+                  description="Select readable exact Files versions supporting this handling/SOP review. References alone do not certify physical facts."
+                />
+              </details>
+            )}
+            <div className="flex flex-wrap gap-2">
+              {(['APPROVE', 'REJECT', 'REVOKE'] as const)
+                .filter((kind) =>
+                  permissions.hasPermission(`mtw-move-review:${kind.toLowerCase()}`)
+                )
+                .map((kind) => (
+                  <Button
+                    type="button"
+                    key={kind}
+                    disabled={busy || uncertain || (kind === 'REVOKE' && !head)}
+                    onClick={(event) => {
+                      const form = event.currentTarget.form;
+                      if (form) void decision(form, kind);
+                    }}
+                  >
+                    {kind.toLowerCase()}
+                  </Button>
+                ))}
+            </div>
+          </fieldset>
+        </form>
+      )}
+      <Button
+        type="button"
+        variant="outline"
+        disabled={busy}
+        onClick={() => setRevision((value) => value + 1)}
+      >
+        Refresh review history
+      </Button>
+      {uncertain && !busy && (
+        <p role="alert">
+          Submission remains stopped. Intended request key: {attemptKey}. This tab preserves it
+          across refresh for this actor, workspace and exact task. Match it to the read-only
+          history; an absent page result does not prove no commit. Do not resend or clear browser
+          storage to retry. If the key is unavailable, obtain read-only reconciliation before any
+          new decision.
+        </p>
+      )}
+      {message && <p role="status">{message}</p>}
+    </section>
+  );
+}

package/src/movethewheels/utils/pickReviewAcknowledgement.ts

@@ -0,0 +1,51 @@
+import type {
+  PickReviewReceiptFragment,
+  RecordMtwPickReviewInput,
+} from '../../generated/pending-pick-operations';
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A truthy GraphQL data object is not an acknowledgment of the intended write. */
+export function confirmPickReviewAcknowledgement(
+  result: unknown,
+  input: RecordMtwPickReviewInput,
+  kind: PickReviewReceiptFragment['kind'],
+  reviewerActorId: string
+): void {
+  const field =
+    kind === 'APPROVE'
+      ? 'approveMtwPickTask'
+      : kind === 'REJECT'
+        ? 'rejectMtwPickTask'
+        : 'revokeMtwPickTaskReview';
+  const receipt = record(result) ? result[field] : null;
+  if (
+    !record(receipt) ||
+    typeof receipt.id !== 'string' ||
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(receipt.id) ||
+    receipt.kind !== kind ||
+    receipt.taskId !== input.taskId ||
+    receipt.intentHash !== input.intentHash ||
+    receipt.subjectActorId !== input.subjectActorId ||
+    receipt.idempotencyKey !== input.idempotencyKey ||
+    !reviewerActorId ||
+    receipt.reviewerActorId !== reviewerActorId ||
+    receipt.version !== input.expectedVersion + 1 ||
+    receipt.previousDecisionId !== (input.expectedPreviousDecisionId ?? null) ||
+    receipt.classification !== 'REVIEW_ONLY_NO_STOCK_EFFECT' ||
+    receipt.note !== input.note ||
+    receipt.quantityCeiling !== (input.quantityCeiling ?? null) ||
+    receipt.validFrom !== (input.validFrom ?? null) ||
+    receipt.validUntil !== (input.validUntil ?? null) ||
+    !Array.isArray(receipt.actions) ||
+    receipt.actions.length !== input.actions.length ||
+    new Set(receipt.actions).size !== receipt.actions.length ||
+    !receipt.actions.every(
+      (action: unknown) =>
+        typeof action === 'string' && input.actions.some((expected) => expected === action)
+    )
+  )
+    throw new Error('The intended move-review receipt is not confirmed.');
+}

package/src/operations/pending-pick/pick-review.graphql

@@ -0,0 +1,14 @@
+fragment PickReviewReceipt on MtwPickReview {
+ id taskId version previousDecisionId intentHash subjectActorId kind actions quantityCeiling validFrom validUntil
+ handlingPolicy { reference revision } sop { reference revision }
+ evidence { fileId versionId sha256Hash checkedAt } note idempotencyKey reviewerActorId recordedAt classification
+}
+query PickReviewHistory($taskId: ID!, $limit: Int!, $offset: Int!) {
+ mtwPickReviewPage(taskId:$taskId,limit:$limit,offset:$offset) {
+ items { ...PickReviewReceipt } total limit offset hasMore nextOffset
+ latestDecision { ...PickReviewReceipt } reviewState evaluatedAt
+ }
+}
+mutation ApprovePickReview($input:RecordMtwPickReviewInput!) { approveMtwPickTask(input:$input) { ...PickReviewReceipt } }
+mutation RejectPickReview($input:RecordMtwPickReviewInput!) { rejectMtwPickTask(input:$input) { ...PickReviewReceipt } }
+mutation RevokePickReview($input:RecordMtwPickReviewInput!) { revokeMtwPickTaskReview(input:$input) { ...PickReviewReceipt } }

package/src/stories/EntityCombobox.stories.tsx

@@ -0,0 +1,58 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { EntityCombobox } from '../movethewheels/components/EntityCombobox';
+
+const choices = [
+  { id: 'fictional-alpha', label: 'Fictional Alpha' },
+  { id: 'fictional-beta', label: 'Fictional Beta' },
+];
+
+function PairedPickers() {
+  const [external, setExternal] = useState('');
+  const [internal, setInternal] = useState('');
+  const [search, setSearch] = useState('');
+  return (
+    <div className="w-80 space-y-6 p-4">
+      <p>Synthetic component examples; selections remain local to this story.</p>
+      <section>
+        <label htmlFor="fictional-external-picker">Fictional external picker</label>
+        <EntityCombobox
+          id="fictional-external-picker"
+          value={external}
+          onChange={setExternal}
+          options={choices}
+          selectedOption={choices.find((item) => item.id === external)}
+          getId={(item) => item.id}
+          getLabel={(item) => item.label}
+          renderOption={(item) => item.label}
+        />
+        <output aria-label="External selection">{external || 'None'}</output>
+      </section>
+      <section>
+        <label htmlFor="fictional-internal-picker">Fictional internal picker</label>
+        <EntityCombobox
+          id="fictional-internal-picker"
+          value={internal}
+          onChange={setInternal}
+          options={choices.filter((item) =>
+            item.label.toLowerCase().includes(search.toLowerCase())
+          )}
+          onSearchChange={setSearch}
+          selectedOption={choices.find((item) => item.id === internal)}
+          getId={(item) => item.id}
+          getLabel={(item) => item.label}
+          renderOption={(item) => item.label}
+        />
+        <output aria-label="Internal selection">{internal || 'None'}</output>
+      </section>
+    </div>
+  );
+}
+
+const meta: Meta<typeof PairedPickers> = {
+  title: 'MoveTheWheels/EntityCombobox',
+  component: PairedPickers,
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const TwoInstances: Story = {};