feat(ipa): Add <Workflow> evaluation-steps component#55
Merged
Conversation
Renders a guideline's manual evaluation steps as an interactive review checklist inside a collapsible accordion: per-step checkboxes, a live "N of M verified" progress chip in the header, and a reset control. Progress is page-local only. - <Workflow> / <Workflow.Step> compound component built on ui/Accordion - "Reference only — agent skips" marker when the parent guideline is lintable (steps document what Spectral checks) - Dev-console warning when an unlintable, non-informational <Guideline> lacks a <Workflow> (cross-field check; build-time enforcement lands with the validation plugin) - Fixtures section + tests CLOUDP-399874
Port the variant-4 mockup faithfully: checkbox-in-square title icon, pill-shaped progress chip with dot, gradient progress track, page-local hint line, full-width hairline step separators, custom animated checkboxes, and step number circles echoing the <Guidelines> numbering motif. Also fix <Example>: the header separator only renders while expanded, so collapsed examples no longer stack it on the container border (thicker bottom edge). CLOUDP-399874
…r, fix tick colors - Add breathing room between the progress chip and the chevron - Remove the 'Reference only — agent skips' marker for lintable guidelines (UX feedback; deviates from CLOUDP-399874 AC) - Hardcode brand accent colors like Example.module.css does: the MongoDB palette in src/css/custom.css is not wired into docusaurus.config.ts, so --mongodb-*/--ifm-color-primary overrides resolve to Infima defaults (blue checkboxes, invisible ticks) CLOUDP-399874
Drop the injected index prop — the numbering circle is an empty aria-hidden span whose number comes from a wf-step CSS counter, matching the <Guidelines>/<Guideline> index pattern. DOM order is the number; cloneElement now only wires checklist state (checked/onToggle). CLOUDP-399874
Same idiom as useGuideline(): a WorkflowContext that the step consumes, throwing a clear error when rendered standalone instead of silently producing an orphaned, unwired checkbox row. CLOUDP-399874
Children.toArray + type-filtering + cloneElement silently dropped any <Workflow.Step> wrapped in another element and breaks under composition (memo/HMR/wrappers) — the pattern React docs discourage. Steps now render themselves inside the <ol> and enroll in the checklist through WorkflowContext (register/toggle/checked keyed by useId), mirroring how <Guidelines>/<Guideline> compose. The chip count derives from registrations, so SSR briefly shows 0 of 0 until hydration — acceptable for a decorative progress indicator. CLOUDP-399874
Checked boxes now use a monochrome emphasis fill with a theme-adaptive inverted tick instead of bright brand green; the number circles stay neutral when checked; the progress track is a thin gray fill instead of a green gradient. The chip remains the one place completion turns green. CLOUDP-399874
Drop the visually-hidden-input + painted-box technique: the input now renders natively (sized and aligned only), removing the stepBox span, its SVG tick, and the associated CSS. Native focus ring and platform checkbox styling apply. CLOUDP-399874
The chip restated visible state (the ticked boxes) about page-local
progress nobody else sees, and was the sole consumer of the
registration machinery and its SSR count flash. With it gone, the
context shrinks to {checked, toggle}, Reset derives from checked.size,
and the component matches the simplicity of the rest of the IPA family.
Checkboxes and Reset stay.
CLOUDP-399874
The site never declared react, so the lockfile resolved root react@18.3.1 against react-dom@19.2.7 — a broken pairing that crashes react-dom on import in any fresh install (existing checkouts only work via drifted node_modules). Pinning both to 19.2.7 makes fresh installs consistent with what the site actually runs. CLOUDP-399874
Drop the checkboxes, Reset, and hint — the last interactive remnants. Steps render as a quiet numbered list: a bold flush-left counter leads the reading line (CSS wf-step counter, fixed column so text stays on one axis), inset hairline separators start at the text column, and the step text carries full base color. The accordion shell, Workflow.Step guard, and the unlintable-guideline dev warning are unchanged. Interactivity can be layered back later if reviewers ask for it. CLOUDP-399874
Bring back the numbering-circle treatment for workflow steps (the plain text counters from the text-first pass read too thin) and extract the circle chrome — shape, size, muted fill — into shared/NumberCircle, used by both <Guideline>'s index and <Workflow.Step>. CSS counters cannot be parameterized across modules, so each consumer keeps a small ::before rule drawing its own counter (ipa-guideline / wf-step) into the shared circle; Workflow sizes it down via --number-circle-size. CLOUDP-399874
MDX wraps step content in <p>, whose theme margin-bottom inflated each row; zero the margins at the content edges (same pattern as the Accordion panel) so rows stay snug while multi-paragraph steps keep their internal spacing. CLOUDP-399874
Repo convention gives multi-file components their own directory; NumberCircle ships a CSS module, so it gets one. Import paths are unchanged (folder index resolution). CLOUDP-399874
Folder-per-component everywhere — StateBadge was the last flat component file. Import paths unchanged (folder index resolution). CLOUDP-399874
Move the checkbox-in-square SVG out of <Workflow> into a new ui/icons module (decorative, currentColor, sized by consumer) and color it with the emphasis scale instead of hardcoded brand greens — the header is now fully monochrome and theme-adaptive, and the component carries no hardcoded colors at all. CLOUDP-399874
CLOUDP-399874
…lidation PR Drop the dev-console warning and the reportWorkflow context plumbing — the rule it encoded (what lintable vs unlintable guidelines must provide) belongs to the validateIpaRules build plugin, where those semantics will be defined properly and enforced at build time instead of as console noise. Guideline and useGuideline revert to main's shape (plus the shared NumberCircle); Workflow is now hook-free except the composition guard. CLOUDP-399874
The consumer-supplied ::before rule was a leaky contract — an invisible CSS side channel where misuse rendered a silently empty circle. The shared component now draws a single fixed counter (number-circle) itself; CSS counter scoping gives each resetting list its own instance, so Guidelines and Workflow share the name safely, even nested. Consumers keep only counter-reset/-increment on their lists and size overrides via custom properties; a forgotten increment now shows a visible 0 instead of nothing. CLOUDP-399874
The component no longer distinguishes lintable from unlintable guidelines (marker and cross-field check both deferred to the validation PR), so the duplicate lintable fixture is gone. CLOUDP-399874
- role="list" on the Workflow and Guidelines ordered lists: WebKit drops the implicit list role from list-style:none lists, and the aria-hidden circle numbering depends on list semantics for AT - Remove dead useEffect/GuidelineContext imports left by an earlier refactor (a silent no-op in a scripted edit) - Test the supported wrapping case (a component, not a DOM element — a div inside <ol> is invalid nesting) - Resolve @site in vitest and use it for the ui import, matching Example; tests no longer force relative imports - Drop unneeded !important overrides; derive the separator inset from --number-circle-size instead of duplicating it - Caret the react/react-dom versions like every other dependency CLOUDP-399874
andmatei
requested review from
andreaangiolillo,
drinkbird,
lovisaberggren,
maks-m-mongo-leaf,
matt-condon,
saisundar and
wtrocki
CI installs with npm ci from package-lock.json; the earlier commit only updated pnpm-lock.yaml, so both CI jobs failed at the install step on the lock-file mismatch. CLOUDP-399874
Collaborator
|
Quick question: will this information be exposed to readers since it is metadata for an agent? I’m asking because it appears in the description as a UI component |
Collaborator
Author
@yelizhenden-mdb Yes, the workflow can also be seen by the users - happy to hide it for users if you think users wouldn't benefit from it |
CLOUDP-399874
Collaborator
|
@andmatei I can’t think of a use case where users would benefit from this right now. I suggest we hide it for now and expose the parts we find valuable later |
Collaborator
Author
|
@yelizhenden-mdb Sounds good to me can hide it as part of this PR and we can decide if we should show it later. My thoughts would be that it can also help API Champions to have a workflow when validating unlintable guidelines |
Workflows are primarily agent-executed evaluation steps consumed from the extracted skill files, not the rendered site. <Workflow> now returns null when customFields.showWorkflows is false; the markup stays in the MDX source for the extraction pipeline, and flipping the flag restores rendering site-wide. Default (flag absent) remains visible. CLOUDP-399874
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the
<Workflow>component for IPA guideline metadata.Ticket: (CLOUDP-399874).
What's added
<Workflow>/<Workflow.Step>— structured authoring for a guideline's evaluation steps. Hidden on the site (showWorkflows: falsein the site config); the markup stays in the MDX source for the extraction pipeline to consume. Steps compose like<Guidelines>/<Guideline>(aStepoutside aWorkflowthrows at build time).shared/NumberCircle— the numbering circle extracted from<Guideline>, shared with workflow steps, driven by a single scoped CSS counter.ui/iconswithCheckSquareIcon.Also in this PR
react/react-domdeclared as direct dependencies — fresh installs previously resolved react 18 against react-dom 19 and crashed on import.<Example>: collapsed headers no longer stack a doubled bottom border.role="list"on the numbered lists (WebKit drops the implicit list role underlist-style: none).The "unlintable guidelines require a
<Workflow>" cross-field check is intentionally deferred to the upcoming validation plugin, where those semantics will be defined and enforced at build time.