[FE] Display Subsection Competency Statuses for Learner in Course #739

This is a suggested approach, not the source of truth. The User Story, Description, and Acceptance Criteria define what must be true when the work is done.

Summary

The panel makes two more requests through #734's plugin-owned query client: #738's statuses and the Progress API's per-subsection scores. Both start only once #733 returns criteria. A pure function, buildCompetencyStatuses, joins them with #733's criteria and the course outline into one display status per named row, applying the hidden-score mask. A hook, useCompetencyStatuses(courseId, targetUserId), exposes that result so #740, #743, and #745 read the same masked statuses, and a new StatusOval component renders all four states.

Approach

1. Requests. Add two functions to src/data/api.js:

   • getCompetencyStatuses(courseId, targetUserId) calls [BE] GET Competency Statuses for Learner in Course #738's LMS route and passes targetUserId as [BE] GET Competency Statuses for Learner in Course #738's learner parameter when it is set.
   • getProgressScores(courseId, targetUserId) calls GET {LMS_BASE_URL}/api/course_home/v1/progress/{courseId}, with /{targetUserId} appended on the staff route.

   Both query keys include targetUserId. Masquerade needs no key entry, because changing it reloads the page. Enable both queries only when [FE] Build cards displaying Competency Criteria on the Course Progress page #734's hasCompetencyCriteria is true, and run them in parallel with the outline query. That way a course without criteria still costs one request and never calls the expensive Progress API a second time.

2. Unknown statuses. getCompetencyStatuses logs, once per response, any status other than PartiallyAttempted, AttemptedNotDemonstrated, or Demonstrated. It keeps those entries, because an unknown status must render no oval rather than "Available".

3. Masking. buildCompetencyStatuses(criteriaResponse, outline, statusesResponse, progressResponse) in src/data/buildCompetencyStatuses.js returns { criteria }, where criteria is a Map from criterion id to { status, percentGraded, masked }. [FE] Display Competency Statuses for Learner in Course #740 adds tags beside it, so the hook's shape doesn't change when [FE] Display Competency Statuses for Learner in Course #740 lands. It covers named rows only, so placeholder rows get no oval. A criterion is a named row when its object_id is in the outline index that buildCompetencyCards builds. Export that index from src/data/buildCompetencyCards.js rather than rebuilding it, so the named-row check can't drift from [FE] Build cards displaying Competency Criteria on the Course Progress page #734's rows. Index section_scores[].subsections[] by block_key, then apply these rules to each named row:

   • A subsection whose outline effective_start is in the future is "Available" with masked: false, because an unreleased subsection has no result to hide. The Progress API leaves unreleased subsections out of a learner's section_scores, so check this first.
   • Otherwise, if the subsection is missing from that index, or its show_grades is false, the result is "Available" with masked: true, whatever the stored status.
   • Otherwise the result is the stored status, or "Available" when there is no status row. percentGraded is set only on Demonstrated. A criterion whose status is unknown is left out of the map.

   The function never compares a score with the rule and never recomputes a status.

4. Hook. useCompetencyStatuses(courseId, targetUserId) in src/data/apiHooks.js composes [FE] Build cards displaying Competency Criteria on the Course Progress page #734's criteria and outline hooks with the two new queries, and returns { isPending, statuses }.

   • isPending is true until [BE] GET Competency Criteria for Course #733 answers. When [BE] GET Competency Criteria for Course #733 returned criteria, it stays true until the other three requests settle. Derive it from [BE] GET Competency Criteria for Course #733's result first, because react-query v5 reports a disabled query as pending indefinitely.
   • statuses is null when [BE] GET Competency Statuses for Learner in Course #738 or the Progress API fails; [FE] Build cards displaying Competency Criteria on the Course Progress page #734's query cache has already logged the error. Otherwise statuses is buildCompetencyStatuses's result, memoized on the four responses' data.
   • The hook reads nothing from props or slot context, so [Placeholder - FE] Build a right sidebar (or central) display of top level competencies ("Focus Areas") with their Competency status displayed. #743's sidebar can call it from its own slot and share the cache without new requests.

5. Join guard. The join assumes [BE] GET Competency Criteria for Course #733's object_id string equals the Progress API's block_key for the same subsection. Both are str() of the usage key, but the equality has not been confirmed on a devstack. If the two never match, every oval reads "Available" with no other symptom. So when section_scores lists subsections and no named row matches any block_key, the hook logs one error. Confirm the equality on a devstack before merging.

6. Panel. CompetencyProgressPanel calls the hook with both values from useProgressRouteParams. It renders the cards as soon as [FE] Build cards displaying Competency Criteria on the Course Progress page #734 does, without waiting for the hook, and passes statuses?.criteria down to CriteriaGroupList as a plain prop. While isPending is true or statuses is null, the rows render as [FE] Build cards displaying Competency Criteria on the Course Progress page #734 has them, with no oval, so no row shows a temporary "Available" that later changes.

   • buildCompetencyCards carries each named subsection row's criterion id, alongside the tag ids [FE] Build cards displaying Competency Criteria on the Course Progress page #734 already carries. Each named row looks up its own criterion id, so a subsection under two tags, or in two groups under one tag, shows each criterion's own status. Joining by object_id would give both rows the same status.
   • [FE] Let the operator choose to replace Course Grade Slot with CBE Progress #839's useCompetencyPanelState and its loading rule need no change, because the cards don't wait for [BE] GET Competency Statuses for Learner in Course #738 or the Progress API.

7. Oval. StatusOval({ status, percentGraded }) in src/StatusOval.jsx renders Available, Partially Attempted, Not Demonstrated, and Demonstrated. [FE] Display Competency Statuses for Learner in Course #740 reuses it on card headings.

   • Icons: [UXD Spike] Confirm what the Competency Status values should be, how they will be determined, and what iconography or other accessible means will be used with their display. #768's icons, which Paragon exports as RadioButtonUnchecked, Contrast, RemoveCircle, and CheckCircle.
   • Shape: pass Badge's pill prop, which sets Paragon's pill radius (--pgn-size-badge-border-radius-pill), to match the design's fully rounded ovals. Badge's default radius (0.25rem) is nearly square.
   • Outlined "Available" oval: Paragon's Badge has no outlined variant. If the design's "Available" oval is outlined, override Badge's --pgn-badge-bg and add a border locally, and call out the gap in the PR description.
   • Accessibility: when percentGraded is passed, the Demonstrated oval shows the percentage as visible text, with "Demonstrated" in an sr-only sibling placed before it, so a screen reader reads "Demonstrated, 95%". The icon is aria-hidden.
   • Percentage format: copy the Grade Summary table's getGradePercent verbatim (toFixed(0) when percentGraded * 100 is a whole number, otherwise toFixed(2)), with the same right-to-left mark before "%" in RTL locales, so the oval matches the Progress tab exactly. That includes the host's float quirk: 0.29 shows as "29.00%", because 0.29 * 100 is 28.999999999999996.

8. Test cases beyond the AC:

   • A PartiallyAttempted criterion shows the Partially Attempted oval.
   • An unknown status shows no oval and is logged once.
   • When the Progress API fails while [BE] GET Competency Statuses for Learner in Course #738 succeeds, no ovals appear.
   • When [BE] GET Competency Statuses for Learner in Course #738 or the Progress API fails, the failure is reported to the logging service.
   • While the statuses are pending, named rows show no oval.
   • A masked criterion whose stored status is unknown shows "Available".
   • percentGraded values of 0, 0.29, 0.6667, and 0.825 render as 0%, 29.00%, 66.67%, and 82.50%, the same as the Grade Summary table.

Out of scope:

• Tag statuses and propagating the mask to tags ([FE] Display Competency Statuses for Learner in Course #740).
• The Focus Areas sidebar ([Placeholder - FE] Build a right sidebar (or central) display of top level competencies ("Focus Areas") with their Competency status displayed. #743).

Files to create and modify

Paths are relative to the root of the plugin repository from #810.

Additional context

• Known limitations:
  • A Demonstrated oval can show a current percentage below its own rule line, because [BE] Evaluate learner’s criterion status for grade #699 never lowers a stored status.
  • A subsection set to never show individual assessment results (never_but_include_grade) never shows its status, which matches the Progress page itself.
  • On the staff route, subsections the learner can't see appear by name and read "Available".
  • The masking changes only the display, so [BE] GET Competency Statuses for Learner in Course #738's response still carries a hidden subsection's status.
• In frontend-app-learning, GradeSummaryTable.jsx (getGradePercent) and DetailedGradesTable.jsx under src/course-home/progress-tab/grades/ show the host's percentage format and its show_grades hiding. The course tabs in src/course-tabs/CourseTabLink.tsx are plain links, so every visit to the Progress tab starts with an empty query cache.
• In openedx-platform, lms/djangoapps/course_home_api/progress/views.py computes show_grades with the learner's staff access rather than the viewer's, and leaves never_but_include_grade subsections out of section_scores. lms/djangoapps/course_blocks/transformers/start_date.py (StartDateTransformer) removes unreleased subsections from a learner's grade structure, while the learning_sequences outline keeps them by name.