@plannotator/ui 0.52.0 → 0.52.1

package/HANDOFF.md

@@ -1880,7 +1880,7 @@ Pinned by `components/DiagramBlock.askAI.test.tsx` and
 
 ---
 
-## Ask AI names a text selection's source lines (unreleased; additive, no core change)
+## Ask AI names a text selection's source lines (ui 0.52.0; additive, no core change)
 
 An Ask AI question asked from a markdown text selection now says which
 source lines the selection is on, so a phrase that occurs more than once in
@@ -1920,7 +1920,7 @@ heading for single-block selections) and `utils/aiPrompt.test.ts`.
 
 ---
 
-## `CompletionOverlay` `done` state (unreleased; additive)
+## `CompletionOverlay` `done` state (ui 0.52.0; additive)
 
 `submitted` accepts a new value, `'done'`: the session finished with nothing
 sent (Plannotator uses it for an annotate Done with nothing to send). It
@@ -1937,7 +1937,7 @@ so this is a visible change for `'exited'` only there. Every other value
 renders exactly as before. The overlay root now carries
 `data-completion-state={submitted}`.
 
-## Quick Labels: reorder and editable emoji (unreleased; additive, no core change)
+## Quick Labels: reorder and editable emoji (ui 0.52.0; additive, no core change)
 
 Settings → Labels (#1736) lets a person move a label up or down (per-row
 buttons, `aria-label="Move <text> up|down"`, a polite live region announces
@@ -1970,7 +1970,7 @@ What a host should know:
   emoji grapheme, including ZWJ sequences, flags, keycaps and skin tones, or
   null) and `emojiFromFieldInput`. Nothing was removed or renamed.
 
-## Question decision toggle and status tag (ui 0.52.0, unreleased; additive, no core change)
+## Question decision toggle and status tag (ui 0.52.0; additive, no core change)
 
 What Workspaces asked for: the reviewer can switch a `Decision: when answered`
 question's recording off and on from the card itself, and the host can draw
@@ -2029,8 +2029,92 @@ row hidden when off, recorded and plain questions untouched, read-only cards
 static, `statusTag: 'none'`, the `Viewer` threading, and a card with none of
 the props rendering the same markup.
 
+## Decision toggle on any question, and an opener for the host's decision card (ui 0.52.1; additive, no core change)
+
+Two gaps Workspaces found in 0.52.0 against its approved Inbox design
+("the tag is the switch" on every question, off by default; "clicking the
+tag's words opens the decision card"). Plannotator passes none of this, and a
+card without the new props renders byte-identically to 0.52.0 (checked by
+rendering main and the branch through `BlockRenderer` and `Viewer`,
+interactive and read-only, with no props, with a 0.52.0-shaped host, and with
+a 0.52.0 host returning a boolean for every question).
+
+| `Viewer` | `BlockRenderer` | `QuestionBlock` |
+| --- | --- | --- |
+| `questionDecisionScope?: 'when-answered' \| 'any'` | same | `decisionScope?: 'when-answered' \| 'any'` |
+| `onOpenQuestionDecision?: (key, anchor: HTMLElement) => void` | same | `onOpenDecision?: (key, anchor: HTMLElement) => void` |
+
+1. **Any question can record a decision, opt-in.** With
+   `questionDecisionScope="any"` (`decisionScope: 'any'`),
+   `decisionRecording` / `questionDecisionRecording` also reaches a question
+   WITHOUT a decision line: a boolean adds the "◇ Records a decision" tag in
+   that state (and, with `onToggleDecisionRecording`, makes it the toggle),
+   `undefined` leaves the question as it was (no tag). The default,
+   `'when-answered'`, is the 0.52.0 behaviour: only `Decision: when answered`
+   questions carry the tag, and a boolean returned for a plain question is
+   ignored, as 0.52.0 documented. It is an explicit opt-in rather than
+   "a boolean means show it" so that a 0.52.0 host that returns a boolean for
+   every question does not grow tags on its plain questions in a patch
+   release. On shows the same "Answering this records
+   a decision" row a `Decision: when answered` question shows; off hides it.
+   The default for such a question is whatever you return: start it `false`
+   for "off by default". A question with a recorded decision
+   (`Decision: [statement](url)`) is still never affected, and
+   `data-question-decision` still describes the question's own line (absent
+   for a plain question); `data-question-decision-recording="on" | "off"`
+   appears once you supply a state.
+2. **A separate opener (`onOpenDecision` / `onOpenQuestionDecision`).** Given,
+   the tag is drawn as two adjacent targets inside one visual tag
+   (`[data-question-decision-tag]`), siblings, never nested:
+   - the diamond is the switch: `<button aria-pressed aria-label="Record as a
+     decision" data-question-decision-toggle>` calling
+     `onToggleDecisionRecording(key, next)`. Without a toggle handler the
+     diamond is decoration, not a control.
+   - the words "Records a decision" are `<button aria-haspopup="dialog"
+     data-question-decision-open>`, calling `onOpenDecision(key, element)`
+     with the words' own button as the popover anchor. The card keeps no
+     open state; your popover owns focus and returns it to the anchor.
+   The opener is offered whether recording is on or off: what an off
+   question's card does (switch it on as it opens, or open a card that says
+   it is off) is the host's call. Tab order is switch, then words, both with
+   the `ring-2 ring-primary` focus ring the 0.52.0 toggle uses (a ring, not
+   an outline, because the dotted outline draws the off state, which is now
+   on the wrapping tag). The off look is unchanged: muted-foreground text and
+   a dotted outline (#1744's contrast fix). Without `onOpenDecision` the
+   whole tag is the toggle exactly as in 0.52.0.
+3. **Read-only cards are never interactive.** No answer handler (or
+   `Viewer` `readOnly`, which also drops `onOpenQuestionDecision`) draws the
+   tag as a plain tag in its current state.
+
+Measured in headless Chromium with the default theme: switch and words are
+7.37:1 (dark) / 8.98:1 (light) off, 5.84:1 / 5.15:1 on; the focus ring is
+7.53:1 / 6.53:1 against the card. The split tag draws exactly the 0.52.0 tag
+(127.66 × 17.75 px, the same 4 px between diamond and words). Target size
+(WCAG 2.5.8) is met without changing that look: the diamond (18 × 17.75 px
+drawn) carries an invisible `before:` box 6 px past it on every side, so it
+clicks as 24 × 29.75 px; the words, positioned and later in the tree, paint
+over the box's right-hand part, so a click on the words is always the words,
+and the words (110 px wide) meet the spacing exception.
+
+**No stylesheet change**: only utility classes the package already ships
+(the hit box is the `before:absolute before:-inset-1.5 before:content-['']`
+pattern of the annotation panel's icon buttons), so `styles.css` and the
+guides.show viewer manifest are unchanged (`check:manifest` in sync).
+
+Pinned by `components/blocks/QuestionBlock.decisionAnyQuestion.test.tsx`
+(DOM-gated): the tag on a plain question only with the `'any'` scope and a
+supplied state (a boolean without the scope changes nothing), the
+toggle's arguments and the row on/off, the switch and the opener as sibling
+buttons with the anchor element, tab order, the opener without a toggle
+handler, 0.52.0 behavior without `onOpenDecision`, read-only cards, `Viewer`
+threading, and no-prop markup.
+
 ---
 
+## Stale-tab guard: `serverSession` (ui 0.52.0, core 0.25.12; additive)
+
+Plannotator's servers issue one random `serverSession` nonce per process (new `@plannotator/core/server-session`) and refuse a decision that echoes a different one with `409 { code: "session_mismatch" }`, so a tab left open on a reused port cannot decide a new session. The client half is `utils/serverSession` (`adoptServerSession`, `withServerSession`, `withServerSessionQuery`, `noteServerSessionMismatch`, `useServerSessionReplaced`) plus `components/ServerSessionReplacedBanner`. Hosts that post decisions to their own backend need none of it: nothing in the shared components sends the field on its own, and a request without it is always accepted.
+
 ## The law (guardrails for anyone editing `@plannotator/ui`)
 
 These are enforced socially and, where possible, by CI. They exist because a prior from-scratch reimplementation of this UI broke the app and was reverted.

package/README.md

@@ -392,6 +392,13 @@ See HANDOFF.md § "Question host seams (ui 0.49.0, core 0.25.9)".
 
 See HANDOFF.md § "Question decision toggle and status tag (ui 0.52.0, unreleased; …)".
 
+**Decision toggle on any question, and a decision-card opener (ui 0.52.1, unreleased).** Also optional on `Viewer`, also unused by Plannotator:
+
+- `questionDecisionScope?: 'when-answered' | 'any'` (default `'when-answered'`, the 0.52.0 behaviour). With `'any'`, `questionDecisionRecording(question)` also applies to a question with no decision line: a boolean adds the "Records a decision" tag in that state (true also shows the "Answering this records a decision" row); `undefined` leaves it tag-less. Return `false` for "off by default".
+- `onOpenQuestionDecision(key, anchor)`: splits the tag into a diamond switch (`aria-pressed`, "Record as a decision", driven by `onToggleQuestionDecisionRecording`) and the words as a button (`aria-haspopup="dialog"`) that calls this with its own element to anchor your decision card. Offered on and off; not offered under `readOnly`. Without it the whole tag is the toggle, as in 0.52.0.
+
+See HANDOFF.md § "Decision toggle on any question, and an opener for the host's decision card (ui 0.52.1, …)".
+
 ### Diff file tree (`components/DiffFileTree`; next ui release)
 
 A read-only file tree for a list of changed files, to sit beside a host's own per-file diff list. It is Plannotator's code-review tree, not a lookalike: the builder (`utils/diffFileTree`), the folder open/closed hook (`hooks/useDiffFileTreeExpansion`) and the row atoms moved here from `packages/review-editor`, and the review now renders from them.

package/components/BlockRenderer.tsx

@@ -53,11 +53,15 @@ export const BlockRenderer: React.FC<{
   renderQuestionFooter?: QuestionBlockProps['renderFooter'];
   /** Whether answering this question records a decision (see `QuestionBlock`). */
   questionDecisionRecording?: QuestionBlockProps['decisionRecording'];
+  /** `'any'` lets a question without a decision line carry the tag (see `QuestionBlock`). */
+  questionDecisionScope?: QuestionBlockProps['decisionScope'];
   /** Makes the "Records a decision" tag a toggle (see `QuestionBlock`). */
   onToggleQuestionDecisionRecording?: QuestionBlockProps['onToggleDecisionRecording'];
+  /** Opens the host's decision card from the tag's words (see `QuestionBlock`). */
+  onOpenQuestionDecision?: QuestionBlockProps['onOpenDecision'];
   /** `'none'` hides the card's own status tag (see `QuestionBlock`). */
   questionStatusTag?: QuestionBlockProps['statusTag'];
-}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter, questionDecisionRecording, onToggleQuestionDecisionRecording, questionStatusTag }) => {
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter, questionDecisionRecording, questionDecisionScope, onToggleQuestionDecisionRecording, onOpenQuestionDecision, questionStatusTag }) => {
   switch (block.type) {
     case 'heading': {
       const Tag = `h${block.level || 1}` as React.ElementType;
@@ -185,7 +189,9 @@ export const BlockRenderer: React.FC<{
               saveLabel={saveQuestionAnswerLabel}
               renderFooter={renderQuestionFooter}
               decisionRecording={questionDecisionRecording}
+              decisionScope={questionDecisionScope}
               onToggleDecisionRecording={onToggleQuestionDecisionRecording}
+              onOpenDecision={onOpenQuestionDecision}
               statusTag={questionStatusTag}
               onOpenLinkedDoc={onOpenLinkedDoc}
               onOpenCodeFile={onOpenCodeFile}

package/components/Viewer.tsx

@@ -218,17 +218,31 @@ export interface ViewerProps {
    *  decision"), given the indexed question and its saved answer. Rendered in
    *  read-only cards too; return null for none. */
   renderQuestionFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
-  /** Whether answering a `Decision: when answered` question records a
-   *  decision, per question: return false to draw its "Records a decision"
-   *  tag dimmed with a dotted outline and hide the "Answering this records a
-   *  decision" row; true or undefined keeps today's card. Not consulted for a
-   *  question whose decision is already recorded. */
+  /** Whether answering a question records a decision, per question. On a
+   *  `Decision: when answered` question: false draws its "Records a
+   *  decision" tag dimmed with a dotted outline and hides the "Answering this
+   *  records a decision" row; true or undefined keeps today's card. On a
+   *  question with no decision line it is ignored unless
+   *  `questionDecisionScope` is `'any'`; then a boolean adds the tag in that
+   *  state (true also shows the row) and undefined adds nothing. Has no
+   *  effect on a question whose decision is already recorded. */
   questionDecisionRecording?: (question: IndexedQuestion) => boolean | undefined;
-  /** Makes a `Decision: when answered` question's "Records a decision" tag a
-   *  toggle button (`aria-pressed`); a click calls this with the question's
-   *  key and the next state, which the host stores and returns from
+  /** Which questions can carry the "Records a decision" tag (ui 0.52.1).
+   *  `'when-answered'` (default, the 0.52.0 behaviour): only questions with
+   *  `Decision: when answered`. `'any'`: also a question with no decision
+   *  line, when `questionDecisionRecording` returns a boolean for it. */
+  questionDecisionScope?: 'when-answered' | 'any';
+  /** Makes a question's "Records a decision" tag a toggle button
+   *  (`aria-pressed`); a click calls this with the question's key and the
+   *  next state, which the host stores and returns from
    *  `questionDecisionRecording`. Ignored when `readOnly`. */
   onToggleQuestionDecisionRecording?: (key: string, next: boolean) => void;
+  /** Opens the host's decision card (ui 0.52.1): the tag splits into a
+   *  diamond switch (the toggle above) and the words "Records a decision" as
+   *  a button that calls this with the question's key and the words' element
+   *  (anchor your popover to it). Offered on and off. Ignored when
+   *  `readOnly`. */
+  onOpenQuestionDecision?: (key: string, anchor: HTMLElement) => void;
   /** `'none'` hides each question card's own status tag (Open / Answered /
    *  Settled / Skipped) so the host can draw its own; the decision tags stay.
    *  Default `'card'`. */
@@ -606,7 +620,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   saveQuestionAnswerLabel,
   renderQuestionFooter,
   questionDecisionRecording,
+  questionDecisionScope,
   onToggleQuestionDecisionRecording,
+  onOpenQuestionDecision,
   questionStatusTag,
   onAskAI,
   allowImages = true,
@@ -1570,7 +1586,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                   saveQuestionAnswerLabel={saveQuestionAnswerLabel}
                   renderQuestionFooter={renderQuestionFooter}
                   questionDecisionRecording={question ? questionDecisionRecording?.(question) : undefined}
+                  questionDecisionScope={questionDecisionScope}
                   onToggleQuestionDecisionRecording={readOnly ? undefined : onToggleQuestionDecisionRecording}
+                  onOpenQuestionDecision={readOnly ? undefined : onOpenQuestionDecision}
                   questionStatusTag={questionStatusTag}
                 />
               );

package/components/blocks/QuestionBlock.tsx

@@ -37,9 +37,12 @@ import { QuestionContext } from './QuestionContext';
  * A host can add its own actions at the right of the footer
  * (`renderFooter`), and a question carrying `Decision: when answered` or a
  * `Decision: [statement](url)` link shows that beside the prompt. A host can
- * also let the reviewer switch a `Decision: when answered` question's
- * recording off and on (`decisionRecording` + `onToggleDecisionRecording`),
- * and hide the card's own status tag to draw its own (`statusTag: 'none'`).
+ * also let the reviewer switch a question's decision recording off and on
+ * (`decisionRecording` + `onToggleDecisionRecording`; with
+ * `decisionScope: 'any'`, any question without a recorded decision once the
+ * host supplies a state), open its own decision
+ * card from the tag's words (`onOpenDecision`), and hide the card's own
+ * status tag to draw its own (`statusTag: 'none'`).
  */
 
 /** Pointer travel (px) above which a press on a choice row is a drag. */
@@ -127,17 +130,36 @@ export interface QuestionBlockProps {
    *  saved answer (never the unsaved draft). Rendered in read-only cards too;
    *  return null for nothing. */
   renderFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
-  /** Whether answering a `Decision: when answered` question records a
-   *  decision (default true). False draws the "Records a decision" tag dimmed
-   *  with a dotted outline and hides the "Answering this records a decision"
-   *  row. Has no effect on a question whose decision is already recorded
-   *  (`Decision: [statement](url)`) or that carries no decision line. */
+  /** Whether answering this question records a decision. On a question
+   *  carrying `Decision: when answered` it defaults to true; false draws the
+   *  "Records a decision" tag dimmed with a dotted outline and hides the
+   *  "Answering this records a decision" row. On a question WITHOUT a
+   *  decision line it is ignored unless `decisionScope` is `'any'` (ui
+   *  0.52.1); then a defined value adds the tag in that state (false: off;
+   *  true: on, with the row), so a host can let any answer become a
+   *  decision, and undefined leaves the question with no tag. Has no effect
+   *  on a question whose decision is already recorded
+   *  (`Decision: [statement](url)`). */
   decisionRecording?: boolean;
+  /** Which questions can carry the "Records a decision" tag (ui 0.52.1).
+   *  `'when-answered'` (default, the 0.52.0 behaviour): only a question that
+   *  carries `Decision: when answered`. `'any'`: also a question with no
+   *  decision line, once the host passes a `decisionRecording` for it. */
+  decisionScope?: 'when-answered' | 'any';
   /** Makes the "Records a decision" tag a toggle button (`aria-pressed`):
    *  a click calls this with the question's key and the next state. The host
    *  stores it and passes it back as `decisionRecording`. Not offered in a
    *  read-only card (no answer handler), which draws the tag as it stands. */
   onToggleDecisionRecording?: (key: string, next: boolean) => void;
+  /** Opens the host's decision card (ui 0.52.1). Given, the tag splits into
+   *  two targets inside one visual tag: the diamond is the switch
+   *  (`onToggleDecisionRecording`, labelled "Record as a decision") and the
+   *  words "Records a decision" are a button (`aria-haspopup="dialog"`) that
+   *  calls this with the question's key and the words' own element, to
+   *  anchor a popover. Offered whether recording is on or off (the host
+   *  decides what an off question's card does). Not offered in a read-only
+   *  card. */
+  onOpenDecision?: (key: string, anchor: HTMLElement) => void;
   /** `'none'` hides the card's own status tag (Open / Answered / Settled /
    *  Skipped) so the host can draw its own; the decision tags stay. Default
    *  `'card'`. */
@@ -161,7 +183,9 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   saveLabel,
   renderFooter,
   decisionRecording,
+  decisionScope = 'when-answered',
   onToggleDecisionRecording,
+  onOpenDecision,
   statusTag = 'card',
   onOpenLinkedDoc,
   onOpenCodeFile,
@@ -355,11 +379,15 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const other = answer?.other ?? '';
   const otherOn = other.trim() !== '';
 
-  // A `Decision: when answered` question the host may switch off. A recorded
-  // decision (`question.decision`) is never affected.
-  const decisionCapable = !question.decision && !!question.decisionOnAnswer;
+  // A `Decision: when answered` question the host may switch off, or (with
+  // `decisionScope: 'any'`) any other question once the host supplies a
+  // recording state for it. A recorded decision (`question.decision`) is
+  // never affected.
+  const decisionCapable = !question.decision
+    && (!!question.decisionOnAnswer || (decisionScope === 'any' && decisionRecording !== undefined));
   const recordingOn = decisionRecording ?? true;
   const decisionToggleable = decisionCapable && !readOnly && !!onToggleDecisionRecording;
+  const decisionOpenable = decisionCapable && !readOnly && !!onOpenDecision;
   // Present only when the host speaks to recording, so a card without these
   // props carries exactly the attributes it always did.
   const recordingAttr = decisionCapable && (decisionRecording !== undefined || !!onToggleDecisionRecording)
@@ -396,7 +424,41 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
         <span className="text-[10.5px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{eyebrow}</span>
         <span className="ml-auto">
           {question.decision && <><Tag tone="rec"><DiamondGlyph />Decision</Tag>{' '}</>}
-          {decisionCapable && (decisionToggleable ? (
+          {decisionCapable && (decisionOpenable ? (
+            // Two targets in one tag: the diamond switches recording, the
+            // words open the host's decision card. Siblings, never nested.
+            // Target size (WCAG 2.5.8) without changing the drawn tag: the
+            // diamond's invisible `before:` box reaches 6 px past it on every
+            // side (24 px wide, about 30 px tall), and the words, positioned
+            // and later in the tree, paint over its right-hand part, so a
+            // click on the words is always the words. The words (110 px wide)
+            // meet the spacing exception: nothing else to click within 12 px
+            // of their centre line.
+            <><span
+              className="annotation-exclude select-none inline-flex items-stretch whitespace-nowrap rounded align-[1px] text-[10.5px] font-semibold tracking-[0.03em] bg-primary/15 text-primary"
+              style={recordingOn ? undefined : DECISION_OFF_STYLE}
+              data-pinpoint-ignore=""
+              data-question-decision-tag=""
+            >{decisionToggleable ? (
+              <button
+                type="button"
+                aria-pressed={recordingOn}
+                aria-label="Record as a decision"
+                title="Record as a decision"
+                onClick={() => onToggleDecisionRecording!(question.key, !recordingOn)}
+                className="relative inline-flex cursor-pointer items-center rounded pl-1.5 pr-0.5 before:absolute before:-inset-1.5 before:content-[''] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+                data-question-decision-toggle=""
+              ><DiamondGlyph /></button>
+            ) : (
+              <span className="inline-flex items-center pl-1.5 pr-0.5"><DiamondGlyph /></span>
+            )}<button
+              type="button"
+              aria-haspopup="dialog"
+              onClick={(event) => onOpenDecision!(question.key, event.currentTarget)}
+              className="relative cursor-pointer rounded py-px pl-0.5 pr-1.5 hover:underline underline-offset-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+              data-question-decision-open=""
+            >Records a decision</button></span>{' '}</>
+          ) : decisionToggleable ? (
             // Focus shows as a ring, not an outline: the dotted outline is
             // what draws the off state.
             <><button
@@ -427,7 +489,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
       <p id={promptId} className="m-0 text-[15px] font-semibold leading-[1.45] text-foreground" data-question-part="prompt">
         {inline(question.prompt)}
       </p>
-      {(question.decision || (question.decisionOnAnswer && recordingOn)) && (
+      {(question.decision || (decisionCapable && recordingOn)) && (
         <div
           className="annotation-exclude mt-2 mb-0.5 flex items-center gap-2 rounded-lg bg-primary/8 px-[9px] py-1.5 text-[12.5px] leading-[18px] text-foreground [&>svg]:text-primary"
           data-pinpoint-ignore=""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {