Skip to content

feat(linearscale): rating sub type with stars, hearts or thumbs - #3637

Closed
global-prog wants to merge 2 commits into
nextcloud:mainfrom
global-prog:contrib/rating-question
Closed

global-prog wants to merge 2 commits into
nextcloud:mainfrom
global-prog:contrib/rating-question

Conversation

@global-prog

@global-prog global-prog commented Sep 9, 2026 •

Copy link
Copy Markdown

Closes #2608.

A rating question ("how would you rate this?") drawn as stars, hearts or thumbs up, from 1 to N icons (N from 2 to 10, default 5). A linear scale already stores, validates, counts and exports exactly this kind of answer, but draws it as a row of radio buttons with labels, which is wider and not the control people expect for a rating.

Based on the work of @global-prog in the original version of this PR, which added the rating as a question type of its own.

Rating as a sub type of the linear scale

Following the design discussed in this PR, the rating is not a new question type but a sub type of linearscale, fixed when the question is created and stored in extraSettings.questionType, the way grid questions store their cell type:

  • The add-question menu lists Numbers and Rating under Linear scale, like the cell types under Grid. Existing linear scale questions have no sub type and stay as they are.
  • A rating draws icons instead of the radio buttons and labels. The editor offers the highest rating and the icon (extraSettings.ratingIcon: star, heart or thumb).
  • Answers, results, CSV/XLSX export and (once the jump stack lands) jumps go through the existing linear scale paths, so nothing there needed a change, and API clients that ignore the sub type still see a working numeric scale. No new value in FormsQuestionType, no migration.
  • The server rejects any other linear scale sub type, a rating that does not start at 1, and ratingIcon on anything but a rating. newQuestion's subtype parameter is widened to FormsQuestionSubtype (openapi.json regenerated, docs/API_v3.md and docs/DataStructure.md updated).

The promoter score sub type of #3635 follows the same pattern, and a separate PR makes the sub type immutable after creation.

Accessibility

The rating is built from real radio inputs: each option is named "3 of 5", the hit area is a full --default-clickable-area square while the icon stays at 34 px, the focus ring shows for keyboard focus, the hover effect is dropped under prefers-reduced-motion, and the icons wrap on narrow screens. A required rating left empty shows "You must answer this question" and marks its radios invalid.

How to verify

  1. In a form, add Linear scale → Rating. Open the question menu, set the highest rating to 7 and choose hearts.
  2. Open the form: seven hearts, each announced as "n of 7". Answer with the keyboard (Tab, arrow keys, Space) and submit; the answer shows in the results and export like a linear scale answer.
  3. Repeat through a public link and an embedded form.
  4. Add Linear scale → Numbers: the scale works as before.

Checked on a Nextcloud 35 test instance in the editor, the submit view logged in, a public link (360 px wide, reduced motion) and an embedded form (dark): axe-core reports no violations, keyboard answering and submitting works in all three, and the results summary counts the rating per value. PHPUnit (FormsService, ApiController, SubmissionService), ESLint, Stylelint, Prettier and the build pass, vue-tsc reports no new errors, and the full Playwright suite passes (70 tests).

🤖 AI (if applicable)

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

@codecov

codecov Bot commented Sep 9, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@Chartman123

Copy link
Copy Markdown
Collaborator

@global-prog thanks for the PR :) please add the AI section to the description if you used AI to generate this PR 👍🏻

some comments on the code itself: as this uses mostly the same logic as linear scale questions, we should re-use the existing extraSettings (especially maxOption instead of maxRating) and also the validation logic as far as possible. Rest is looking good from a first glance at it.

Perhaps you could also add a screenshot/recording of how it works to the description so that the @nextcloud/designers could have a look at it without having to build it 👍🏻

@global-prog

Copy link
Copy Markdown
Author

Thanks! Done in the latest commit:

  • the rating now stores its top end as optionsHighest instead of maxRating, and gets the linear scale's bounds on it (2 to 10). optionsLowest is refused, since a rating always starts at 1.
  • the linear scale's range check is moved into one helper that both types call, with the same message and defaults, so linear scale behaviour is unchanged.
  • added tests for the rating's settings and its answer validation.

I've added the AI declaration to the description, and I'll add a screenshot of the editor and the filled-in form there as well.

@Chartman123 Chartman123 left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've had a closer look on the code now and added a few more suggestions and comments. Could you please also rebase your branch on current main? Thanks :)

Comment thread lib/Constants.php Resolved
Comment thread lib/Service/SubmissionService.php Resolved
Comment thread lib/Constants.php Resolved
@github-actions

Copy link
Copy Markdown
Contributor

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

@Chartman123

Copy link
Copy Markdown
Collaborator

@global-prog are you still working on this (and the other PRs) ?

@Chartman123 Chartman123 added the stale On hold label Oct 30, 2026
@Chartman123
Chartman123 force-pushed the contrib/rating-question branch from 29ea986 to 4286aff Compare November 16, 2026 11:56
@AndyScherzinger

Copy link
Copy Markdown
Member

@Chartman123 I rebased this onto current main and added two fixes on top of your review commit:

  • b759398 fix(rating): check rating answers against the scale, not ranking answers: ANSWER_TYPES_SCALE listed ANSWER_TYPE_RANKING instead of ANSWER_TYPE_RATING. Ranking answers are option ids, so rankings with option ids above 5 were rejected, while rating answers were not checked at all.
  • ac8fdb6 fix(rating): reject booleans and lists as answers on a scale: moving the linear scale check into validateScaleQuestion had dropped the !is_scalar($answer) || is_bool($answer) guard from 433302b, so true was accepted as 1 again.

SubmissionServiceTest and FormsServiceTest pass again (they had 8 failures and 2 errors before).

I also checked the icon colours in the light, dark and both high contrast themes: stars use --color-element-warning, hearts --color-element-error and thumbs --color-element-info, and the filled icons have a contrast of at least 3.5:1 against the background in every theme, so no change was needed there.

@Chartman123

Copy link
Copy Markdown
Collaborator
  • fix(rating): check rating answers against the scale, not ranking answers: ANSWER_TYPES_SCALE listed ANSWER_TYPE_RANKING instead of ANSWER_TYPE_RATING. Ranking answers are option ids, so rankings with option ids above 5 were rejected, while rating answers were not checked at all.

oh, my bad... I confused the two there 🙈

@AndyScherzinger AndyScherzinger self-assigned this Nov 19, 2026
@AndyScherzinger
AndyScherzinger force-pushed the contrib/rating-question branch 3 times, most recently from 86c7ff1 to 018092d Compare November 20, 2026 10:09
@AndyScherzinger AndyScherzinger removed the stale On hold label Nov 20, 2026
@AndyScherzinger
AndyScherzinger changed the base branch from main to feat/conditional-questions-5-scale-color November 20, 2026 23:32

@AndyScherzinger AndyScherzinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review with a focus on performance, accessibility, security, clean code and architecture, plus an accessibility check of the rating on a Nextcloud 36 instance built from this branch: editor, submit view logged in, public link, embedded form, dark mode, forced colors, 320 px reflow and the results summary. axe-core 4.10 reports no violations for the rating, and keyboard use, the focus ring, the 34 px targets and the contrast of the icons (3.5:1 to 11.9:1 against the background) pass. The only axe hits are role="false" attributes inside the question menus, which come from @nextcloud/vue and show up in every question menu. No performance or security problems turned up: the rating settings are checked against a whitelist on update, and nothing a user enters reaches its CSS or HTML.

The findings are inline. Fixes for problems this PR introduced are fixups of the commits that introduced them; problems that already exist on main are fixed in separate commits at the end of the branch. The updated branch follows this review.

Assisted by Claude Code:claude-opus-5-5

Comment thread src/views/Submit.vue Resolved
Comment thread src/views/Submit.vue Resolved
Comment thread lib/Db/Question.php Resolved
Comment thread lib/ResponseDefinitions.php Resolved
Comment thread src/views/Submit.vue Resolved
Comment thread lib/Service/SubmissionService.php Resolved
Comment thread src/types/Entities.d.ts Resolved

@AndyScherzinger AndyScherzinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two more findings from a final pass over the tests of this PR.

Assisted by Claude Code:claude-opus-5-5

Comment thread playwright/e2e/jumps.spec.ts Resolved
Comment thread playwright/e2e/rating-question.spec.ts Resolved

@AndyScherzinger AndyScherzinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second review round, again with a focus on performance, accessibility, security, clean code and architecture, plus an accessibility check on a Nextcloud 36 instance built from this branch: editor, submit view logged in, public link and embedded form, dark mode, forced colors, and widths of 320 and 360 px. axe-core 4.10 reports no violations for the rating; the only hits are the known role="false" attributes that @nextcloud/vue puts into the question menu. The names and description of the rating, its focus ring, forced colors, and moving on with Enter from ratings, radios, short answers and the answer "Other" work in all three submit contexts. Psalm, php-cs-fixer, ESLint and Stylelint pass, composer openapi reproduces openapi.json, and the unit tests pass except three UploadedFilesShareServiceTest cases that fail on Nextcloud 36 for a mock type this PR does not touch. No performance or security problems turned up.

The findings are inline. The fixes are fixups of the commits that introduced them, covered by the rating and jump e2e tests; the updated branch follows this review.

Assisted by Claude Code:claude-opus-5-5

Comment thread src/views/Submit.vue Resolved
Comment thread playwright/e2e/jumps.spec.ts Resolved
@AndyScherzinger
AndyScherzinger force-pushed the contrib/rating-question branch 2 times, most recently from ef71165 to b1926e3 Compare November 21, 2026 07:55

@AndyScherzinger AndyScherzinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Third and final review round, again with a focus on performance, accessibility, security, clean code and architecture, plus a check on a Nextcloud 36 instance built from this branch: the editor with the question menu and the jump targets, the submit view logged in, through a public link and embedded, and the results summary. axe-core 4.14 reports no violations for the rating in any of them; the only hits are inside the question menu (role="false", aria-checked on its labels, and <li> items in a list with role="dialog"), which come from @nextcloud/vue and appear in every question menu. Keyboard use works in all three submit contexts: Enter moves from a short answer into the rating and on to the next question, arrow keys and Space choose a value, Ctrl+Enter submits or focuses the required rating with its error, and Enter keeps its own meaning in the date picker and the dropdown. Neither Ctrl+Enter pressed twice nor a held Enter sends a response twice, as the form unmounts while it is sent. The server rejects "0", "8", "05", "5.0", " 5" and true as rating answers, and unknown icons and bounds in the settings.

The findings are inline. The fixes are fixups of the commits that introduced them, covered by two new rating e2e tests, and the updated branch is pushed. ESLint, Stylelint and the build pass, Prettier flags no file the base branch does not flag already, npm run typecheck reports the same errors with and without the fixes (it already fails for every question component, and CI does not run it), the PHP unit tests pass apart from the three UploadedFilesShareServiceTest cases that fail on Nextcloud 36, and the Playwright suite passes.

Assisted by Claude Code:claude-opus-5-5

@AndyScherzinger

Copy link
Copy Markdown
Member

Rating, promoter score and linear scale: one question type with sub types

I compared this PR, #3637 (rating) / #3635 (promoter score) and the linear scale on main. All three answer with one whole number in a range of at most 0 to 10: a rating is 1 to N (N = 2 to 10), a promoter score is fixed 0 to 10. They differ only in how the scale is drawn (icons instead of radio buttons) and in one extra results figure (the score). So I'd make them one linearscale type with sub types, fixed when the question is created, instead of separate question types or an on/off setting.

Why sub types, not separate types

  • No new value in the public API (FormsQuestionType, openapi.json): answer validation, jumps, the submit filter, result bars and exports keep working unchanged, and clients that ignore the sub type (Analytics data source, API consumers) still get a working numeric scale instead of an unknown type.
  • Forms already has the pattern: grid questions store their sub type in extraSettings.questionType, newQuestion(type, subtype) sets it, and the add-question menu lists sub types. "Linear scale" would offer Numbers, Rating and Promoter score.
  • Separate types mean every "is this a scale?" check has to list three types (validation, jumps, submit filter, results, export, Analytics); feat(linearscale): rating sub type with stars, hearts or thumbs #3637 already shows the drift (rating is predefined in AnswerTypes.ts but not in ANSWER_TYPES_PREDEFINED, and only rating is in ANSWER_TYPES_SCALE).

Why not an on/off setting (the current state of #3635)

  • Switching a 1 to 5 question that already has answers to 0 to 10 rescores the old answers (5, 5, 4 become −100). A sub type fixed at creation rules that out.

What it takes

  • Server: refuse to change extraSettings.questionType after creation (this also closes the same gap for grids), and validate the range per sub type: promoter exactly 0 to 10, rating 1 to N, ratingIcon only for rating.
  • Frontend: the sub types in the add-question menu, icons for the rating sub type, the score in the results only for the promoter sub type.
  • Existing linear scale questions have no sub type and stay plain numeric scales.

The sub type lock comes first as its own small PR. Then #3635 replaces its showPromoterScore setting with the promoter sub type, and #3637 turns rating into a sub type; unrelated changes in #3637 (jumps, IME input, submit handling) move to their own PRs.

I will be working on this myself, in follow-up commits on both PRs; your existing commits stay as they are. @global-prog, thanks for both features, shout if you see a problem with this direction.

Assisted by ClaudeCode:claude-opus-5-5

A rating ("how would you rate this") is answered with one whole number
from 1 to N, which a linear scale already stores, validates, counts in
the results and exports. Drawn as a row of radio buttons with labels,
though, it is not the compact control people expect for it.

The rating is therefore a sub type of the linear scale, fixed when the
question is created and stored in extraSettings.questionType, the way
grid questions store their cell type. The add-question menu lists
"Numbers" and "Rating" under "Linear scale". A rating draws stars,
hearts or thumbs up (extraSettings.ratingIcon) instead of the radio
buttons and labels, still built from real radio inputs: each is named
"3 of 5", has a hit area of --default-clickable-area, the icons wrap,
and the hover effect is dropped under reduced motion. The editor offers
the highest rating (2 to 10, default 5) and the icon.

Answers, results and exports go through the existing linear scale
paths; the results summary names a rating "Linear scale (Rating)"
instead of listing scale labels it never shows.

The server accepts no other sub type of a linear scale, keeps a rating
starting at 1, and accepts ratingIcon only on a rating. Existing linear
scale questions have no sub type and stay as they are.

Closes nextcloud#2608

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Create the question through "Linear scale" > "Rating" and check what
unit tests cannot: the accessible names of the rating and its options,
restoring an answer from a draft and when editing a response, the error
of a required rating, focus and the insert menu of a new rating, and
the highest rating and the icon chosen in the editor.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
@AndyScherzinger AndyScherzinger changed the title feat: rating question type feat(linearscale): rating sub type with stars, hearts or thumbs Nov 21, 2026
@AndyScherzinger
AndyScherzinger changed the base branch from feat/conditional-questions-5-scale-color to main November 21, 2026 15:43
@AndyScherzinger

Copy link
Copy Markdown
Member

I rewrote this branch as the rating sub type of the linear scale, as proposed in #3637 (comment). It is now two commits on main (the old head was b1926e3), and the PR targets main instead of the conditional questions stack.

What moved out of this PR:

Assisted by ClaudeCode:claude-opus-5-5

@AndyScherzinger

Copy link
Copy Markdown
Member

This PR couldn't be reopened after its base was switched to main (GitHub's limit on open pull requests per author), so the rewritten rating sub type continues in #3978, which carries the same commits from a branch in this repository. Thanks again @global-prog for the original work.

Assisted by ClaudeCode:claude-opus-5-5

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.

[QuestionType] Rating

3 participants