@beyondwork/docx-react-component 1.0.40 → 1.0.42

package/src/ui-tailwind/chrome/chrome-preset-model.ts

@@ -51,6 +51,24 @@ export function resolveChromePresetOptions(
       showSectionTagAction: false,
       showReviewRail: true,
     },
+    collab: {
+      // Collab preset composes on top of "review" — same review rail,
+      // plus the collab top nav (presence, role + audience chips,
+      // tamper banner, negotiation action bar, send-to-supplier).
+      // Each sub-surface has its own flag so hosts can selectively
+      // disable parts (e.g. single-user demo, or a presenter-only view)
+      // without forking the preset.
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: true,
+      showCollabTopNav: true,
+      showCollabPresenceStrip: true,
+      showCollabRoleChip: true,
+      showCollabAudienceChip: true,
+      showCollabTamperBanner: true,
+      showCollabNegotiationActionBar: true,
+      showCollabSendToSupplier: true,
+    },
   };
 
   return {
@@ -116,6 +134,16 @@ export function resolveChromeVisibilityForPreset(input: {
       statusBar: true,
       reviewRail: options.showReviewRail,
     },
+    collab: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: options.showReviewRail,
+    },
   };
 
   return {

package/src/ui-tailwind/chrome/collab-audience-chip.tsx

@@ -0,0 +1,73 @@
+import * as React from "react";
+
+import type { CommentAudience } from "../../api/comment-presentation-types.ts";
+
+export interface CollabAudienceChipProps {
+  /** `undefined` when there is no active comment. */
+  audience: CommentAudience | undefined;
+  /** `true` when the local user is allowed to change audience. */
+  canEdit: boolean;
+  /** Invoked when the user cycles the chip. Caller dispatches set-audience. */
+  onCycle?: (next: CommentAudience) => void;
+  className?: string;
+}
+
+const CYCLE: readonly CommentAudience[] = ["internal", "external", "shared"];
+
+/**
+ * Audience chip for the active comment in the collab top nav (P9c).
+ *
+ * Renders the current `audience` of the active comment. Clicking
+ * cycles `internal → external → shared → internal` and invokes
+ * `onCycle(next)` — the caller is responsible for dispatching
+ * `set-audience` through `session.dispatchCommentPresentation`.
+ *
+ * Fail-safe rendering:
+ * - Renders a disabled "no comment" placeholder when `audience` is
+ *   undefined (no active comment selected).
+ * - Respects `canEdit`: when false, renders a disabled chip with the
+ *   current audience but no click handler — useful for observer /
+ *   reviewer who cannot change the audience.
+ */
+export function CollabAudienceChip({
+  audience,
+  canEdit,
+  onCycle,
+  className,
+}: CollabAudienceChipProps): React.ReactElement {
+  const empty = audience === undefined;
+  const disabled = empty || !canEdit;
+  const rootClass = [
+    "tw-collab-audience-chip",
+    audience ? `tw-collab-audience-chip--${audience}` : "tw-collab-audience-chip--empty",
+    disabled ? "tw-collab-audience-chip--disabled" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const label = empty ? "no comment" : audience;
+
+  const handleClick = (): void => {
+    if (disabled || !audience) return;
+    const idx = CYCLE.indexOf(audience);
+    const next = CYCLE[(idx + 1) % CYCLE.length]!;
+    onCycle?.(next);
+  };
+
+  return (
+    <button
+      type="button"
+      className={rootClass}
+      data-testid="collab-audience-chip"
+      data-audience={audience ?? "none"}
+      data-can-edit={canEdit ? "true" : "false"}
+      aria-label={empty ? "No active comment" : `Audience: ${audience}`}
+      aria-disabled={disabled ? "true" : undefined}
+      disabled={disabled}
+      onClick={handleClick}
+    >
+      {label}
+    </button>
+  );
+}

package/src/ui-tailwind/chrome/collab-negotiation-action-bar.tsx

@@ -0,0 +1,244 @@
+import * as React from "react";
+
+import type {
+  CommentNegotiationAction,
+  CommentNegotiationEntry,
+  CommentNegotiationState,
+  NegotiationRole,
+} from "../../api/comment-negotiation-types.ts";
+
+export interface CollabNegotiationActionBarProps {
+  /** Currently-selected comment's negotiation entry. `undefined` when no comment is active. */
+  entry: CommentNegotiationEntry | undefined;
+  /** Local user identity — used to stamp actor / author ids on actions. */
+  actorId: string;
+  /** Local user role — drives button visibility. */
+  role: NegotiationRole;
+  /**
+   * Dispatcher. Caller routes to `session.dispatchCommentNegotiation(action, ctx)`.
+   * We hand back the fully-populated action; context (role/now) is the caller's job.
+   */
+  onDispatch: (action: CommentNegotiationAction) => void;
+  /** Blocks the whole bar when true — used by the chrome when the tamper gate is tampered. */
+  disabled?: boolean;
+  /** Fresh timestamp source (injectable for tests). */
+  now?: () => string;
+  className?: string;
+}
+
+/**
+ * Per-state, per-role action bar for the active comment negotiation
+ * (P9e). Mirrors the role-gating matrix in `collab-master-plan §7`:
+ *
+ *   state       author                                   reviewer            observer
+ *   proposed    propose / counter / reject              propose / counter    (none)
+ *   negotiating approve / reject (vote) / counter /      approve / reject    (none)
+ *               reject-thread / accept / lock           (vote) / counter
+ *   accepted    lock                                    —                   (none)
+ *   rejected    lock                                    —                   (none)
+ *   resolved    reopen                                  reopen              (none)
+ *
+ * Accept is author-only (needs quorum validated server-side; the
+ * reducer will block reviewers with `collab_role_restricted`).
+ */
+export function CollabNegotiationActionBar({
+  entry,
+  actorId,
+  role,
+  onDispatch,
+  disabled = false,
+  now = () => new Date().toISOString(),
+  className,
+}: CollabNegotiationActionBarProps): React.ReactElement {
+  const empty = entry === undefined;
+  const blocked = disabled || role === "observer" || empty;
+  const state: CommentNegotiationState | "empty" = entry?.state ?? "empty";
+
+  const rootClass = [
+    "tw-collab-negotiation-action-bar",
+    `tw-collab-negotiation-action-bar--${state}`,
+    blocked ? "tw-collab-negotiation-action-bar--blocked" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const buttons = entry
+    ? buildButtons(entry, role, actorId, now)
+    : [];
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="collab-negotiation-action-bar"
+      data-state={state}
+      data-role={role}
+      data-blocked={blocked ? "true" : "false"}
+      role="toolbar"
+      aria-label="Comment negotiation actions"
+    >
+      {empty ? (
+        <span
+          className="tw-collab-negotiation-action-bar__empty"
+          data-testid="collab-negotiation-action-bar-empty"
+        >
+          No active comment
+        </span>
+      ) : (
+        buttons.map((btn) => (
+          <button
+            key={btn.id}
+            type="button"
+            className={`tw-collab-negotiation-action-bar__button tw-collab-negotiation-action-bar__button--${btn.id}`}
+            data-testid={`collab-negotiation-action-${btn.id}`}
+            data-action-id={btn.id}
+            disabled={blocked || btn.disabled}
+            aria-disabled={blocked || btn.disabled ? "true" : undefined}
+            title={btn.title}
+            onClick={() => {
+              if (blocked || btn.disabled) return;
+              onDispatch(btn.build());
+            }}
+          >
+            {btn.label}
+          </button>
+        ))
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+type ButtonId =
+  | "propose-change"
+  | "counter-propose"
+  | "vote-approve"
+  | "vote-reject"
+  | "accept"
+  | "reject"
+  | "lock"
+  | "reopen";
+
+interface ButtonDef {
+  id: ButtonId;
+  label: string;
+  title?: string;
+  disabled?: boolean;
+  build(): CommentNegotiationAction;
+}
+
+function buildButtons(
+  entry: CommentNegotiationEntry,
+  role: NegotiationRole,
+  actorId: string,
+  now: () => string,
+): ButtonDef[] {
+  const state = entry.state;
+  const isAuthor = role === "author";
+  const isReviewer = role === "reviewer";
+  const id = entry.commentId;
+  const buttons: ButtonDef[] = [];
+
+  if (state === "proposed" && (isAuthor || isReviewer)) {
+    buttons.push({
+      id: "propose-change",
+      label: "Propose change",
+      build: () => ({ type: "propose-change", commentId: id, actorId }),
+    });
+    buttons.push({
+      id: "counter-propose",
+      label: "Counter-propose",
+      build: () => ({
+        type: "counter-propose",
+        commentId: id,
+        authorId: actorId,
+        proposalId: generateProposalId(),
+        body: "",
+        createdAt: now(),
+      }),
+    });
+    buttons.push({
+      id: "reject",
+      label: "Reject",
+      build: () => ({ type: "reject", commentId: id, actorId }),
+    });
+  }
+
+  if (state === "negotiating" && (isAuthor || isReviewer)) {
+    buttons.push({
+      id: "vote-approve",
+      label: "Approve",
+      build: () => ({
+        type: "vote",
+        commentId: id,
+        authorId: actorId,
+        verdict: "approve",
+      }),
+    });
+    buttons.push({
+      id: "vote-reject",
+      label: "Reject (vote)",
+      build: () => ({
+        type: "vote",
+        commentId: id,
+        authorId: actorId,
+        verdict: "reject",
+      }),
+    });
+    buttons.push({
+      id: "counter-propose",
+      label: "Counter-propose",
+      build: () => ({
+        type: "counter-propose",
+        commentId: id,
+        authorId: actorId,
+        proposalId: generateProposalId(),
+        body: "",
+        createdAt: now(),
+      }),
+    });
+    buttons.push({
+      id: "reject",
+      label: "Reject thread",
+      build: () => ({ type: "reject", commentId: id, actorId }),
+    });
+    if (isAuthor) {
+      buttons.push({
+        id: "accept",
+        label: "Accept",
+        title: "Accept requires quorum",
+        build: () => ({
+          type: "accept",
+          commentId: id,
+          actorId,
+        }),
+      });
+    }
+  }
+
+  if ((state === "accepted" || state === "rejected") && isAuthor) {
+    buttons.push({
+      id: "lock",
+      label: "Lock",
+      build: () => ({ type: "lock", commentId: id, actorId }),
+    });
+  }
+
+  if (state === "resolved" && (isAuthor || isReviewer)) {
+    buttons.push({
+      id: "reopen",
+      label: "Reopen",
+      build: () => ({ type: "reopen", commentId: id, actorId }),
+    });
+  }
+
+  return buttons;
+}
+
+function generateProposalId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return `prop-${globalThis.crypto.randomUUID()}`;
+  }
+  return `prop-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/src/ui-tailwind/chrome/collab-presence-strip.tsx

@@ -0,0 +1,150 @@
+import * as React from "react";
+
+import type {
+  AwarenessPeer,
+  PresenceSnapshot,
+  TransportStatus,
+} from "../../api/awareness-identity-types.ts";
+
+export interface CollabPresenceStripProps {
+  presence: PresenceSnapshot;
+  /**
+   * Optional current-user posture for display styling. When `role ===
+   * "observer"` the strip is rendered dimmed to reflect the read-only
+   * session posture.
+   */
+  localRole?: "author" | "reviewer" | "observer";
+  /** Max number of peer tiles to render inline before collapsing the remainder. */
+  maxInline?: number;
+  /** Classname hook for host styling. */
+  className?: string;
+}
+
+/**
+ * Presence strip for the `"collab"` chrome preset (P9b).
+ *
+ * Reads the snapshot passed in by the host (from
+ * `session.getPresenceSnapshot()`). Kept as a pure component so the
+ * preset can mount / remount it freely without the chrome owning a
+ * session subscription.
+ *
+ * Visual contract:
+ * - Per-peer avatar tile with display-name initials.
+ * - `authorKind` shown as a small badge (`agent` / `system`; `human` is
+ *   the default and unlabelled).
+ * - Transport chip at the end of the strip: `connected` / `syncing` /
+ *   `offline (N queued)`.
+ * - When `localRole === "observer"` the whole strip gets the
+ *   `tw-collab-presence-observer` modifier so the host CSS can dim it.
+ * - When there are zero peers the strip still renders the transport
+ *   chip so hosts see the disconnected state unambiguously.
+ */
+export function CollabPresenceStrip({
+  presence,
+  localRole,
+  maxInline = 6,
+  className,
+}: CollabPresenceStripProps): React.ReactElement {
+  const observer = localRole === "observer";
+  const tiles = presence.peers.slice(0, maxInline);
+  const overflow = Math.max(0, presence.peers.length - tiles.length);
+  const rootClass = [
+    "tw-collab-presence-strip",
+    observer ? "tw-collab-presence-observer" : null,
+    className ?? null,
+  ]
+    .filter((value): value is string => value !== null)
+    .join(" ");
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="collab-presence-strip"
+      role="group"
+      aria-label="Collaborators"
+      data-observer={observer ? "true" : "false"}
+    >
+      <ul className="tw-collab-presence-strip__peers" aria-live="polite">
+        {tiles.map((peer) => (
+          <CollabPresencePeerTile key={peer.userId} peer={peer} />
+        ))}
+      </ul>
+      {overflow > 0 ? (
+        <span
+          className="tw-collab-presence-strip__overflow"
+          aria-label={`${overflow} additional peers`}
+          data-testid="collab-presence-overflow"
+        >
+          +{overflow}
+        </span>
+      ) : null}
+      <CollabTransportChip
+        status={presence.transportStatus}
+        queuedLocalEvents={presence.queuedLocalEvents}
+      />
+    </div>
+  );
+}
+
+function CollabPresencePeerTile({ peer }: { peer: AwarenessPeer }) {
+  const initials = computeInitials(peer.displayName);
+  return (
+    <li
+      className="tw-collab-presence-strip__tile"
+      data-testid={`collab-presence-peer-${peer.userId}`}
+      data-author-kind={peer.authorKind}
+      data-active-story={peer.activeStoryId ?? ""}
+      title={peer.displayName}
+    >
+      <span className="tw-collab-presence-strip__avatar" aria-hidden="true">
+        {initials}
+      </span>
+      <span className="tw-collab-presence-strip__name">{peer.displayName}</span>
+      {peer.authorKind !== "human" ? (
+        <span
+          className="tw-collab-presence-strip__badge"
+          data-testid={`collab-presence-peer-${peer.userId}-badge`}
+        >
+          {peer.authorKind}
+        </span>
+      ) : null}
+    </li>
+  );
+}
+
+function CollabTransportChip({
+  status,
+  queuedLocalEvents,
+}: {
+  status: TransportStatus;
+  queuedLocalEvents: number;
+}) {
+  const label =
+    status === "offline" && queuedLocalEvents > 0
+      ? `offline (${queuedLocalEvents} queued)`
+      : status;
+  return (
+    <span
+      className={`tw-collab-presence-strip__transport tw-collab-presence-strip__transport--${status}`}
+      data-testid="collab-presence-transport"
+      data-status={status}
+      data-queued={queuedLocalEvents.toString()}
+      aria-label={`Transport ${label}`}
+    >
+      {label}
+    </span>
+  );
+}
+
+function computeInitials(displayName: string): string {
+  const trimmed = displayName.trim();
+  if (trimmed.length === 0) return "?";
+  const words = trimmed.split(/\s+/);
+  if (words.length === 1) {
+    return words[0]!.slice(0, 2).toUpperCase();
+  }
+  return (
+    (words[0]![0] ?? "").toUpperCase() +
+    (words[words.length - 1]![0] ?? "").toUpperCase()
+  );
+}

package/src/ui-tailwind/chrome/collab-role-chip.tsx

@@ -0,0 +1,62 @@
+import * as React from "react";
+
+import type {
+  CollabPosture,
+  TransportStatus,
+} from "../../api/awareness-identity-types.ts";
+
+export interface CollabRoleChipProps {
+  posture: CollabPosture;
+  /** Optional transport override (chip dims on offline). */
+  transportStatus?: TransportStatus;
+  className?: string;
+}
+
+/**
+ * Role + peer-count chip for the collab top nav (P9c).
+ *
+ * Reads `CollabPosture` (role, transport, peers). Pure presentational —
+ * the host passes in the snapshot from `session.getCollabPosture()`.
+ * Observer role gets a dimmed modifier class so the chrome can visually
+ * flag the read-only session posture alongside the role chip.
+ */
+export function CollabRoleChip({
+  posture,
+  transportStatus,
+  className,
+}: CollabRoleChipProps): React.ReactElement {
+  const offline =
+    transportStatus === "offline" || posture.transport === "none";
+  const rootClass = [
+    "tw-collab-role-chip",
+    `tw-collab-role-chip--${posture.role}`,
+    offline ? "tw-collab-role-chip--offline" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const peerLabel =
+    posture.peers === 0
+      ? "alone"
+      : posture.peers === 1
+        ? "1 peer"
+        : `${posture.peers} peers`;
+
+  return (
+    <span
+      className={rootClass}
+      data-testid="collab-role-chip"
+      data-role={posture.role}
+      data-transport={posture.transport}
+      data-peers={posture.peers.toString()}
+      aria-label={`Role ${posture.role}, ${peerLabel}`}
+      title={`${posture.role} · ${peerLabel}`}
+    >
+      <span className="tw-collab-role-chip__role">{posture.role}</span>
+      <span className="tw-collab-role-chip__peers" aria-hidden="true">
+        {posture.peers}
+      </span>
+    </span>
+  );
+}

package/src/ui-tailwind/chrome/collab-send-to-supplier-button.tsx

@@ -0,0 +1,68 @@
+import * as React from "react";
+
+import type { MetadataIntegrity } from "../../runtime/tamper-gate.ts";
+
+export interface CollabSendToSupplierButtonProps {
+  role: "author" | "reviewer" | "observer";
+  integrity: MetadataIntegrity;
+  /** Counts from the presentation snapshot, per audience. */
+  shareableCount: number; // external + shared
+  internalCount: number;
+  onOpenModal: () => void;
+  className?: string;
+}
+
+/**
+ * Send-to-supplier button (P9f). Author-only; disabled when the
+ * tamper gate reports "tampered" or there are zero shareable comments
+ * (external + shared). Clicking opens the confirmation modal; the
+ * caller owns modal state.
+ */
+export function CollabSendToSupplierButton({
+  role,
+  integrity,
+  shareableCount,
+  internalCount,
+  onOpenModal,
+  className,
+}: CollabSendToSupplierButtonProps): React.ReactElement | null {
+  if (role !== "author") return null;
+
+  const tampered = integrity === "tampered";
+  const emptyShareable = shareableCount === 0;
+  const disabled = tampered || emptyShareable;
+  const rootClass = [
+    "tw-collab-send-to-supplier-button",
+    tampered ? "tw-collab-send-to-supplier-button--tampered" : null,
+    emptyShareable ? "tw-collab-send-to-supplier-button--empty" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const title = tampered
+    ? "Blocked: metadata integrity check failed. Acknowledge first."
+    : emptyShareable
+      ? "No external or shared comments to send."
+      : `Send ${shareableCount} comment${shareableCount === 1 ? "" : "s"} to supplier · ${internalCount} internal kept local`;
+
+  return (
+    <button
+      type="button"
+      className={rootClass}
+      data-testid="collab-send-to-supplier-button"
+      data-shareable={shareableCount.toString()}
+      data-internal={internalCount.toString()}
+      data-tampered={tampered ? "true" : "false"}
+      disabled={disabled}
+      aria-disabled={disabled ? "true" : undefined}
+      title={title}
+      onClick={() => {
+        if (disabled) return;
+        onOpenModal();
+      }}
+    >
+      Send to supplier
+    </button>
+  );
+}