Skip to content

feat(ui,core): in-document question blocks — core + ui (PR 1) - #1637

Merged
backnotprop merged 2 commits into
mainfrom
feat/question-blocks-core-ui
Sep 29, 2026
Merged

backnotprop merged 2 commits into
mainfrom
feat/question-blocks-core-ui

Conversation

@backnotprop

Copy link
Copy Markdown
Owner

PR 1 of the approved question/answer components feature (.product/approved/qa-components/: SPEC §8 PR 1, with the owner's approval.md decisions applied). It covers core and ui. Editor polish, agent prompts, SKILL.md and WebMCP are PR 2/3.

What this adds

@plannotator/core/question-block (new subpath, pure; packages/shared/question-block.ts shim)

  • parseQuestionBlock: the :::question / :::question-multi / :::question-text grammar. It reuses the prototype parser (archive/grillsheet-prototype, fd31a196) with the §3.4 changes:
    • [x] means settled.
    • Recommended: is the primary marker. The arrow forms are aliases.
    • There are no required questions.
    • It is tolerant of tight or spaced markdown, */+/1. markers, plain bullets, continuation lines, **Recommended:**, label — reason, and multi lists.
    • It returns null and never throws.
  • indexQuestionBlocks (numbering, prompt line, de-duplicated keys) and questionKey (q- + hash8).
  • QuestionAnswer, with the fail-closed and capped parseQuestionAnswer.
  • formatQuestionAnswersSection and helpers, buildQuestionAnswerAnnotation.
  • QUESTION_AUTHORING_GUIDE.

@plannotator/ui

  • components/blocks/QuestionBlock.tsx: the approved Card.
    • Eyebrow "Question N of M", with "· pick any" on multi.
    • Status tag: Open / ✓ Answered / Skipped / ✓ Settled.
    • An inline "Recommended" tag on choices, and a "Suggested … Use" line for free text.
    • "Other…" is always shown.
    • The footer is Add note · Skip · right-aligned Accept recommended, shown only while the question is unanswered and has a recommendation.
    • It uses theme tokens, not the mock's hardcoded values.
    • Native radios and checkboxes, with the prototype's drag-vs-pick guard: 4 px mouse, 10 px touch, and no selection. The guard runs in the capture phase so it cancels before label activation.
    • Prompt, context and choice text stay annotatable. Only the chrome is annotation-exclude.
  • BlockRenderer/Viewer wiring. Viewer gains one optional prop, onAnswerQuestion?(blockId, answer | null, key), and draws answers from its existing annotations prop. With no prop, or under readOnly, the cards are read-only. An unparseable block falls back to the existing Callout. Older ui versions show :::question as a callout through the untouched directive path.
  • Annotation.questionAnswer (types). utils/questionAnswers provides upsertQuestionAnswerAnnotation and collectQuestionAnswers for hosts.
  • The highlighter skips questionAnswer rows.
  • The Answers section is in exportAnnotations, exportLinkedDocAnnotations and exportAnnotationEntry. It comes first, and answers are excluded from the feedback count.
  • HANDOFF and README sections for Workspaces, plus the allowlist row.
  • Versions: core 0.25.8 (patch; additive) and ui 0.48.0, which pins core 0.25.8 exactly. Publish core first. Nothing is published here.

Minimal editor hook, used only to show the feature working: packages/editor/hooks/useQuestionAnswers.ts passes onAnswerQuestion to the main Viewer and upserts the annotation. Answers draw, autosave in the draft, restore on reload, and export on Send Feedback. It has no undo history, progress chip, Send answers framing or Questions panel section. Those are PR 2.

Evidence

  • Unit tests (21 core, 11 component, 9 exporter/upsert, 1 highlighter):
    • Parser: tolerant input, [x], Recommended:, the free-text form, malformed blocks.
    • Exporters.
    • Component: select, multi, Other, skip, note, Accept recommended / Use, settled, read-only, and callout fallback.
    • Drag guard: a mutation check confirms the test fails when the guard is removed.
    • Highlighter skip: also mutation-checked.
  • bun test packages/ui packages/core packages/editor: 1539 pass.
  • The CI DOM list: 1337 pass. Both new DOM files are added to test.yml.
  • Typecheck passes, including tsconfig.strict-consumer.json, which now lists the new files.
  • smoke:package passes: @plannotator/ui@0.48.0 with @plannotator/core@0.25.8.
  • Built with bun run --cwd apps/review build && bun run build:hook. I then ran bun run apps/hook/server/index.ts annotate offline-sync.md (5 questions) and drove it in headless Chromium (--use-mock-keychain --password-store=basic):
    • Dragging across "Server-side per user": no radio checked, the annotation toolbar opened, and a comment was created on the option text.
    • After answering, the statuses were answered,answered,answered,skipped,settled.
    • After reload and Restore draft, the same statuses came back, with 0 highlight marks in the prompts.
    • The feedback captured from Send Feedback:
# File Feedback

## Answers to your questions

3 of 4 questions answered. 1 already settled in the document was left as is.

### Q1. Where should losing conflict versions be kept? (line 14)
Answer: Local only, purged after 30 days (your recommendation)
Note: Keep the log reachable from the debug menu so support can use it.

### Q2. Should sync run while the app is in the background? (line 26)
Answer: Yes, best-effort via BGAppRefreshTask

### Q3. Which sync indicators ship in v1? (line 39)
Answer:
- Global offline banner
- Other: A sync-now button in the menu

### Q4. Describe the manual test you'd run before calling offline sync shippable. (line 50)
Skipped

I've reviewed this file and have 1 piece of feedback:

## 1. (lines 13–23) Feedback on: "Server-side per us"
> Per user or per device? Reinstall is the case that matters.

Screenshots

The images are hosted on the assets/qa-components-pr1 branch. Delete that branch after review.

Dark Light
dark empty light empty
dark answered light answered
dark lower light lower

Drag across option text: this selects text and shows the annotation toolbar. It does not pick the option.

drag

Deviations and decisions to review

  • Settled questions in the export. A question the agent settled with [x] and the reviewer left alone is not counted in "N of M" and is not listed under Unanswered. The count line then adds "1 already settled in the document was left as is." The SPEC does not say how to count these.
  • "(your recommendation)" is also added when a multi-choice answer equals the recommended set exactly, and when free text equals the suggestion. The mock adds it for single choice only.
  • A recommendation that names no choice, on a choice question, is shown as the "Suggested" text. Accept recommended then fills "Other…" with it.
  • onAnswerQuestion takes a third argument, key. The SPEC signature is (blockId, answer | null). The key is needed to remove an answer when answer is null. The change is additive.
  • Core helper name. Core's buildQuestionAnswerAnnotation returns a structural record with type: 'COMMENT'. The ui-typed version is questionAnswerToAnnotation in utils/questionAnswers, because a string literal is not assignable to the AnnotationType enum.
  • Accessibility. The fieldset uses aria-labelledby pointing at the visible prompt, not a <legend>, so the prompt stays annotatable document text.
  • Native controls follow the theme mode through color-scheme, so radios and checkboxes are dark in dark mode.
  • guides.show. The viewer JS is unchanged, but the shared stylesheet gained the card's classes, so guide-viewer-manifest.ts pins a new CSS hash. check:manifest passes. Deploy guides.show before a release that ships this.

Left for PR 2 (editor)

  • Undo/redo history for answers, debounced for typing.
  • annotationOwnsHighlight / repaintHighlights / applyEditedDocument should treat ann-question-* like ann-checkbox-*.
  • The header "N/M answered" chip, which jumps to the next open question.
  • The Questions section in the annotations panel. Answers currently list as plain Comment cards, and a panel click on an answer does not scroll to the card.
  • The Unanswered chip for orphaned answers.
  • "Send answers" and the feedbackLoss "answers" copy.
  • In pinpoint input mode, a click on option text both pinpoints it and picks the option.

PR 3 covers the plan.answered prompt (both runtimes), the SKILL.md section written from QUESTION_AUTHORING_GUIDE with a freshness test, the PFM paragraph, the feedback-archive questionAnswer field, and read-only WebMCP questions.

…(PR 1)

Adds @plannotator/core/question-block (parser, stable key, answer
validator, export section, authoring guide) and the approved Card
QuestionBlock in @plannotator/ui, wired through BlockRenderer/Viewer
with one optional Viewer prop (onAnswerQuestion). Answers are stored as
one annotation carrying questionAnswer; the highlighter skips them and
the three exporters print an Answers section before numbered feedback.

Minimal editor hook (useQuestionAnswers) wires the Viewer prop in
Plannotator so the feature works end to end; history, the progress
chip and agent framing are PR 2/3.

core 0.25.8, ui 0.48.0.
…a note

A note-only answer on a settled question replaced the settled selection with
the answer's empty one, so the [x] radio unchecked and the status dropped to
Open. The settled choice now stays drawn until the reviewer picks, fills
Other or skips.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant