Skip to content

feat(results): average, median, range and a promoter score sub type for scale questions - #3984

Open
AndyScherzinger wants to merge 13 commits into
feat/linearscale-ratingfrom
feat/linearscale-promoter-figures
Open

AndyScherzinger wants to merge 13 commits into
feat/linearscale-ratingfrom
feat/linearscale-promoter-figures

Conversation

@AndyScherzinger

@AndyScherzinger AndyScherzinger commented Nov 22, 2026 •

Copy link
Copy Markdown
Member

Stack

Part 2 of 2 of the linear scale stack. Merge in this order:

  1. feat(linearscale): rating sub type with stars, hearts or thumbs #3978 feat(linearscale): rating sub type with stars, hearts or thumbs
  2. This PR promoter score sub type and scale figures

Replaces #3635, moved from the fork to a branch on nextcloud/forms so CI runs without approval; the commits are unchanged. This PR targets feat/linearscale-rating. After #3978 is merged, change its base to main before that branch is deleted. CI runs Playwright only for PRs into main, so the full suite was run locally on the top of the stack: 84 of 84 passed on the final top of the stack (f710384).

Screenshots

👀 🌞 🌚
Editor forms-pr3984-editor-light forms-pr3984-editor-dark
Results forms-pr3984-results-light forms-pr3984-results-dark
Public link forms-pr3984-public-link-light forms-pr3984-public-link-dark
Embedded form forms-pr3984-embedded-form-light forms-pr3984-embedded-form-dark

Summary

Scale questions currently show a bar per value, which makes it hard to compare two questions, or two runs of the same form, at a glance.

This adds a small set of figures, shown as cards above the existing bars, for linearscale questions:

  • number of answers, average, median, minimum, maximum, formatted for the user's locale
  • for a promoter score question, a new sub type of the linear scale with a fixed 0–10 range, the promoter score (promoters − detractors, the usual 9–10 / 7–8 / 0–6 split) as a signed value, e.g. "+11", with a bar split into detractors, passives and promoters and their shares

The median sits next to the average deliberately — at the response counts most forms see, one extreme answer moves an average a long way, and showing both makes that visible.

The promoter score is labelled by its calculation rather than with the name of the method, which is a registered trademark of Bain & Company, NICE Systems and Fred Reichheld.

Scope

  • the figures are shown above the existing per-value bars; questions of other types render as before
  • the cards sit five in a row on wide screens and wrap to three or two columns on narrow ones; the promoter score card spans three columns, or the full row when narrow (checked from 320 px to 3840 px wide)
  • a rating (feat(linearscale): rating sub type with stars, hearts or thumbs #3978) gets none of these figures: it has its own summary with the average as icons and a bar per rating level
  • the promoter score is a sub type of the linear scale, as discussed in feat(results): average, median, range and a promoter score sub type for scale questions #3635 (comment). The shared sub type code (the questionType extra setting, the sub type check on creation, the FormsQuestionSubtype API type and the "Linear scale" sub menu with Numbers) comes from feat(linearscale): rating sub type with stars, hearts or thumbs #3978; this PR adds Promoter score as the third entry, after Rating
  • creating a promoter score question stores the range 0 to 10; the server rejects any other range for it, both on creation and on update. The editor shows no range pickers for it; the label fields stay and default to "Not at all likely" and "Extremely likely"
  • the results show the score only for the promoter score sub type. Existing linear scale questions have no sub type, so they stay plain numeric scales and never show a score
  • POST /api/v3/forms/{formId}/questions accepts subtype: promoter for linearscale; openapi.json, docs/API_v3.md and docs/DataStructure.md are updated. No schema change, no migration

How to verify

  1. In a form, choose "Add a question" → "Linear scale" → "Promoter score": the question shows 0 ("Not at all likely") to 10 ("Extremely likely"), and its actions menu has no "Lowest value" / "Highest value" pickers.
  2. Answer it a few times (logged in, public link or embedded) and open the results: the summary shows answers, average, median, minimum, maximum and the "Promoter score" card with the signed score, the split bar and the shares of detractors, passives and promoters.
  3. Add "Linear scale" → "Numbers" and set it to 0 to 10: its results show the figures but no promoter score.
  4. Add "Linear scale" → "Rating" and answer it: its results show the average as icons and a bar per rating level, and no figures.

Testing

  • every commit passes npm run lint and npm run build; npm run stylelint, Prettier and vue-tsc show no new findings on the top of the stack
  • PHP unit tests for the promoter range validation (FormsServiceTest) and for creating a promoter score question (ApiControllerTest)
  • Playwright: playwright/e2e/results-scale-figures.spec.ts covers the figures and the score, no score on a plain 0–10 scale, no figures on a rating, and both the "Promoter score" and "Numbers" menu entries
  • checked on NC 36: the promoter score and rating results in the logged-in app, axe clean on the results page; text in the cards meets 4.5:1 and the split bar's segments 3:1 against the card in light and dark

History

Based on the work of the original contributor of #3635. The commits that show the scale figures and the promoter score in the results carry their authorship and sign-off; changes made during review are separate commits on top of them. Their original contribution, before the rework: 86a6e87d (average, median, range and promoter score for scale questions).

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-promoter-figures branch 3 times, most recently from 41d4536 to bb1c259 Compare November 22, 2026 16:52
@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-promoter-figures branch from bb1c259 to 6b53b6c Compare November 22, 2026 17:44
@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-promoter-figures branch from 6b53b6c to ec657a1 Compare November 22, 2026 17:47
@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-promoter-figures branch from ec657a1 to e7ce346 Compare November 22, 2026 17:53
AndyScherzinger and others added 11 commits November 22, 2026 18:56
A 0-10 scale is not always a "how likely are you to recommend"
question, and switching a scale that already has answers to 0-10
would score those answers on the wrong scale. The promoter score is
therefore a sub type of the linear scale, fixed when the question is
created and stored in extraSettings.questionType next to "Numbers"
and "Rating" in the add-question menu.

Creating a promoter score question stores the range 0 to 10, the
server rejects any other range for it, and the editor shows no range
pickers for it. Its lowest and highest values are labelled "Not at all
likely" and "Extremely likely" unless the author changes them, as
"Strongly disagree" and "Strongly agree" do not fit a likelihood.
Existing scales have no sub type and keep working as before.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
…m for scale questions

Scale questions only show a bar per value, which makes it hard to
compare two questions or two runs of the same form at a glance. The
summary now lists the number of answers, the average, the median, the
minimum and the maximum above the bars. The median sits next to the
average because, at the response counts most forms see, a single
extreme answer moves an average a long way.

The figures are formatted for the user's locale and are derived from
the per-value counts the bars already compute, so the answers are not
walked a second time. A rating keeps its own "Average rating" line
and gets no figures. No API or schema change; other question types
are unaffected.

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The template comment only restated what the markup next to it shows.
Comments in this code base document behaviour, not layout.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The scale figures created their own Intl.NumberFormat per summary,
although the module already provides formatCount for the user's
locale. As the average is rounded to two decimals before formatting,
the output stays the same.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
…alues

A rating shows no scale figures, yet their values were collected and
sorted first and only then discarded. The sub type is now checked
first, using the sub type constant instead of a string literal.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The average of the scale figures showed up to two decimals, while
every other average in the results, such as the average rating, shows
one. Both now use the same one-decimal formatter.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The figures of a scale (answers, average, median, minimum, maximum)
sat in one line with their labels so close to the values that they
were hard to read and to tell apart. Each figure is now a small card
with the label above a larger value, laid out in a grid that wraps on
narrow screens, with more room before the bars.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A promoter score question splits respondents into promoters (9-10),
passives (7-8) and detractors (0-6). The summary of such a question
now adds the promoter score, the share of promoters minus the share
of detractors, together with both shares. The score is rounded from
the exact difference rather than computed from the rounded shares,
which can be one point off (4 promoters and 2 detractors out of 7
give 29, not 28). Plain scales, including plain 0-10 scales, show no
score.

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The promoter score compared the sub type with a string literal, while
the other sub type checks use the LinearScaleType enum. A typo in the
literal would silently hide the score.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The shares of promoters and detractors put a hard-coded "%" after the
number, while the per-value bars right below format their shares for
the user's locale. In German this showed "50% promoters" above
"1 (13 %)". The shares now use the same percent formatter.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Translators need to know that {promoters} and {detractors} already
contain the percent sign. The translation tool only picks up a
TRANSLATORS comment on the line directly above the t() call, which a
template comment never is, so the text moves into a function with the
note above it.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The promoter score joins the scale figures as one more card, laid out
like a dashboard figure. The label is just "Promoter score", with the
formula "(promoters − detractors)" kept for screen readers only, so it
no longer wraps. The value shows its sign ("+11", "0", "−25"), as the
score ranges from −100 to 100.

Below the value, one bar split into detractors, passives and promoters
shows the three groups at a glance in red, yellow and green. The bar is
decorative; the line below it states the shares of all three groups,
now including the passives, which were not shown before. The card
takes two grid columns.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The figures and the promoter score are computed in the frontend only,
which has no unit tests, so end-to-end tests are their only coverage.
They check the figures above the bars of a scale question, the promoter
score of the promoter sub type, its absence on a plain 0-10 scale, the
absence of the figures on a rating, and the questions the add-question
menu creates for the "Promoter score" and "Numbers" entries, including
the default labels of a promoter score question.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
@AndyScherzinger
AndyScherzinger force-pushed the feat/linearscale-promoter-figures branch from e7ce346 to f710384 Compare November 22, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants