Skip to content

feat(pages): add and configure widgets from their server schema - #3214

Open
rubenvdlinde wants to merge 5 commits into
feat/noid/grid-canvasfrom
feat/noid/grid-widget-editor
Open

rubenvdlinde wants to merge 5 commits into
feat/noid/grid-canvasfrom
feat/noid/grid-widget-editor

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Part of #3099, on top of #3213 (grid canvas). The dialog that adds a widget to a grid or configures one, with a settings form generated from the widget types the server serves. #3215 opens it from the edit mode of a page.

Size: about 800 changed lines over 7 files.

What changes

  • The widget dialog asks for the type, a title, an icon from the named icon set, a description, and for a table or view widget one of the application's own tables and views. The picker names the table a view belongs to, and one helper makes the labels of targets.
  • The settings form is generated from the schema of the type on GET /api/2/widget-types: text, long text, choices, a switch and colours. A new widget type needs a schema on the server and a renderer here, no new dialog. Required settings are marked and keep Add widget disabled until they're filled. The dialog checks what the server checks (maximum lengths, a value of only blanks), and shows a setting's hint.
  • Only types this frontend can show are offered. The server can know a type before the frontend renders it (the tabs type of feat(pages): let widgets sit in the tabs of a tabs widget #3212 until feat(pages): add a tabs widget whose tabs hold their own widgets #3217), and such a type is left out of the list.
  • Configuring a widget keeps its icon, description and settings, and the type can't be changed.
  • IconField picks a named icon for a form, with a button to clear it; feat(pages): show and edit grid pages of an application #3215 uses it for pages too.

How it was tested

  • Cypress component tests: AddWidget.cy.js (only types it can show, the form from the server's schema with a required setting, icon and description kept when configuring, a data widget needs a table or view; the test of the offered types fails without the filter) and gridLayout.cy.js (the tables and views of the application)
  • npm run lint, npm run stylelint and npm run build
  • no PHP changes

🖼️ Screenshots

No screen yet: #3215 opens the dialog from a page, its pull request has the screenshots.

🏁 Checklist

  • ⛑️ Tests (unit and/or integration) are included or not needed
  • 🔙 Backport requests are created or not needed: /backport to stableX.X
  • 📅 Milestone is set
  • 🌸 PR title is meaningful (if it should be in the changelog: is it meaningful to users?)

🤖 AI (if applicable)

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

@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 focused on performance, accessibility, security, clean code and architecture. The dialog has no entry point in this PR, so the UI checks ran on a dev instance (MariaDB) with the frontend built from #3215, where the dialog's files are identical to this PR. They covered axe-core 4.14 on the open dialog (no violations), the form for each offered type, keyboard use of the icon field, a configure dialog for a widget of a type without a renderer, and saving values over the server limits.

Security: nothing found. The settings form only renders interpolated text and hex colours; the server validates every value again.

Description: it still lists "a switch" among the generated controls and gives 587 lines; the second commit removed the switch.

</div>

<div class="row space-T">
<NcTextField v-model="title"

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.

The dialog accepts values the server rejects, and the error only comes when the whole page is saved. A title over 200 characters (or a description over 2000) goes into the draft without complaint; Save then fails with 400 for the entire page, and the message names the widget by its index in the payload, which the UI doesn't show. #3215's ContextPageForm already sets :maxlength 200/2000 on the same fields, and NcTextField/NcTextArea pass it on. The same applies to a required heading of only zero-width spaces: canSubmit (line 148) uses JS trim(), which keeps U+200B, while TextHelper::trim() strips it, so the server rejects what the dialog accepted.

Validated: reproduced on a deployed instance (MariaDB, 2.4 data upgraded through #3133 to #3212, frontend built from #3215 at d64695b0 because #3215 opens this dialog; AddWidget.vue, SchemaForm.vue and IconField.vue there are identical to this PR: a text widget with a 250-character title was added to the draft, the page save returned 400). The zero-width case: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The title and description fields now have the same limits as the server, 200 and 2000 characters. Required settings count as empty by the same rule as TextHelper::trim(), zero width spaces included, through a small isBlank() helper, so the dialog refuses what the server would refuse. Both have tests.

cc @blizzz

<template>
<div class="schema-form">
<div v-for="(property, name) in properties" :key="name" class="schema-form__field" :data-cy="fieldDataCy(name)">
<NcTextField v-if="property.type === 'string'"

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.

property.required from the schema isn't used for the fields, so required settings aren't marked (no required, no aria-required, no visible marker), and neither is the required "Table or view" select in AddWidget. The only signal is an "Add widget" button that stays disabled without saying why, and as a native disabled button it can't even be reached with Tab to find out. With "Header" preselected and its required "Heading" empty, a user who fills in Title and Description is stuck. Passing :required="property.required" (the Nc fields forward it) and marking the label, like CreateContext does for mandatory fields, would fix it.

Validated: reproduced on a deployed instance (MariaDB, 2.4 data upgraded through #3133 to #3212, frontend built from #3215 at d64695b0 because #3215 opens this dialog; AddWidget.vue, SchemaForm.vue and IconField.vue there are identical to this PR: Header form, the "Heading" input has neither required nor aria-required, "Add widget" disabled).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Required settings and the table or view picker are now marked as required, for screen readers and with a star on the label. A line under the form lists what is still missing, so a disabled button is no longer the only hint. There's a component test for both.

cc @blizzz

Comment thread src/modules/grid/SchemaForm.vue Outdated
label="label"
@update:model-value="option => set(name, option?.value ?? property.default)" />
<div v-else-if="property.type === 'color'" class="schema-form__color">
<NcColorPicker :model-value="colorValue(name)"

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.

The colour button's accessible name is only the property title ("Background color"); the chosen value or "Theme color" sits in the span next to it, which isn't referenced, so a screen reader user doesn't hear what is set. An aria-label with both, as IconField does, fixes that. The two colours are also picked independently with a theme fallback each, which is what makes the header unreadable in one theme (see the comment on HeaderWidget.vue in #3213); requiring both or setting the counterpart automatically would belong here.

Validated: reproduced on a deployed instance (MariaDB, 2.4 data upgraded through #3133 to #3212, frontend built from #3215 at d64695b0 because #3215 opens this dialog; AddWidget.vue, SchemaForm.vue and IconField.vue there are identical to this PR: the colour button's name is "Background color" with the hint "Theme color" outside it). The contrast part: see #3213.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The colour button is gone. Following enjeck on #3099, a header picks one theme colour pair from a regular select, so screen readers hear the chosen value and the text colour always matches the background. That is in "refactor(pages): drop the color field from the widget settings form".

cc @blizzz

</div>

<div class="row space-T">
<NcTextArea v-model="description"

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.

The text widget type is called "Description" on the server, so choosing it shows two text areas, "Description" (the caption under the card title) and "Text" (the body). Writing the body into the first is an easy mistake, and the card then shows a grey caption and an empty body. Renaming the type (for example "Text") avoids the clash. Also, line breaks typed into this multi-line field are stored but GridWidget renders the description in a <p> without white-space: pre-wrap, so they collapse to one line.

Validated: reproduced on a deployed instance (MariaDB, 2.4 data upgraded through #3133 to #3212, frontend built from #3215 at d64695b0 because #3215 opens this dialog; AddWidget.vue, SchemaForm.vue and IconField.vue there are identical to this PR: the form for type "Description" lists the text areas "Description" and "Text"). The line breaks: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks. The text widget type is now called Text on the server, in "fix(pages): name the text widget type Text and give widget settings a hint" on #3132, so its form no longer shows two fields that both sound like the body. A widget description keeps its line breaks, in "fix(pages): name each widget menu, keep focus on a step and drop duplicate landmarks" on #3213.

cc @blizzz

Comment thread src/modules/modals/AddWidget.vue Outdated
await this.loadWidgetTypes()
}
if (this.editingWidget) {
this.selectedType = this.typeOptions.find(option => option.id === this.editingWidget.type) ?? null

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.

"Configure widget" is offered for every type the server knows (GridWidget.isKnownType), but selectedType is looked up in typeOptions, which only holds types with a renderer here. For a tabs widget (on the server since #3212, rendered from #3217) the dialog opens with an empty, disabled type select, no settings and a save button that stays disabled, so its title, icon and description can't be edited. The same will happen to any type whose schema ships before its renderer. Looking the type up with findWidgetType(this.widgetTypes, ...), or only offering "Configure widget" when there's a renderer, fixes it.

Validated: reproduced on a deployed instance (MariaDB, 2.4 data upgraded through #3133 to #3212, frontend built from #3215 at d64695b0 because #3215 opens this dialog; AddWidget.vue, SchemaForm.vue and IconField.vue there are identical to this PR: a page with a tabs widget, Edit page → Widget actions → Configure widget, type select empty, "Save widget" disabled after changing the title).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The dialog now looks up the type of the widget being configured among all types the server knows, not only the ones with a renderer here. So a widget whose renderer comes later can still get its title, icon and description edited. A component test covers a type without a renderer.

cc @blizzz

* @param {Array} views views known to the store
* @return {Array<{id: number, label: string}>} one option per node relation, by relation id
*/
export function applicationNodeOptions(nodes, tables, views) {

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.

This resolves nodes to tables and views and builds the emoji + title label a third time, next to widgetTarget() and GridWidget.sourceTitle from #3213, and with slightly different rules: non-table/view node types end up under tables here, while widgetTarget() rejects them, and the label is assembled differently. A nodeTarget(node) taken out of widgetTarget() and one targetTitle(target, tables, views) helper would keep the picker and the card in agreement.

Validated: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed. nodeTarget() is now split out of widgetTarget(), and one targetTitle() helper builds the emoji and title. The picker and the card both use them, so they agree on which nodes count and how they're labelled, and nodes that aren't a table or view are no longer offered.

cc @blizzz

Comment thread src/modules/modals/AddWidget.vue Outdated
<NcTextField v-model="title"
class="add-widget__input"
:label="t('tables', 'Title')"
:helper-text="t('tables', 'Shown above the widget. Leave empty to show no title.')"

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.

"Leave empty to show no title" isn't what happens for a "Table or view" widget, which then shows the title of its table or view. For the other types an empty title also hides the icon, because GridWidget only draws the icon inside the heading, so an icon chosen here never appears. The hint could depend on hasSource and mention the icon, or the icon could render without a title.

Validated: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The hint now matches what happens. For a table or view widget it says an empty title uses the title of the table or view, and for other types it says the icon shows with the title, so an empty title shows neither. A component test checks the hint per type.

cc @blizzz

Comment thread src/modules/grid/SchemaForm.vue Outdated
class="schema-form__input"
:model-value="value(name)"
:label="property.title"
:placeholder="t('tables', 'Leave an empty line between paragraphs')"

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.

The generic form hard-codes the text widget's hint as the placeholder of every text property. #3217's tabs setting ("one per line") is a text property too and would get the contradicting paragraph hint. A placeholder is also only visible while the empty field has focus, so it doesn't work as an instruction. A per-property hint in the server schema, rendered as helper-text, fits both.

Validated: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed, a placeholder is no instruction. A setting in the server schema can now carry a hint, which the form shows as helper text under the field. Only the text setting of the text widget has one, saying to leave an empty line between paragraphs. The server part is in #3132 with a unit test.

cc @blizzz

async reset() {
// Awaited only when the types are missing, so the common case fills the form before it renders
if (this.widgetTypes.length === 0) {
await this.loadWidgetTypes()

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.

When the store has no widget types yet (the first "Add widget" on an empty page, where no GridWidget has loaded them), the dialog is already shown while reset() awaits them, and then sets title, icon, description and type, overwriting what the user typed in the meantime. Rendering the form only after reset() finished, or loading the types before opening, avoids it.

Validated: code check only (depends on request timing).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The dialog now shows a loading state until the widget types are there and only then shows the filled form, so nothing typed early gets overwritten. A component test delays the types request and checks the form only appears after it answers.

cc @blizzz

this.title = this.editingWidget.title ?? ''
this.icon = this.editingWidget.icon ?? null
this.description = this.editingWidget.description ?? ''
this.settings = { ...defaultSettings(this.widgetType), ...JSON.parse(JSON.stringify(this.editingWidget.settings ?? {})) }

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.

Settings are flat maps of strings (sanitizeValue() returns strings, SchemaForm.set() always emits a new object), so { ...defaultSettings(type), ...this.editingWidget.settings } here and { ...this.settings } on line 207 give the same isolation without the JSON round-trips. The String() on line 148 is left over from the switch the second commit removed.

Validated: code check only.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The String() in canSubmit is gone, the check now uses the same blank rule as the server. I kept the copies through JSON on purpose: with the keyed tabs from #3212 the tabs setting is a list of {key, title} objects, so a spread would share that list between the dialog and the widget and an edit in the dialog would change the widget before it is saved.

cc @blizzz

@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.)

@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-widget-editor branch from 681cf71 to d48a24a Compare November 19, 2026 08:28
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-widget-editor branch from d48a24a to 6ef1865 Compare November 19, 2026 13:35
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-widget-editor branch from 6ef1865 to 258eb0a Compare November 20, 2026 10:52
The dialog that adds or configures a widget asks for its type, title,
named icon and description. Its settings form is generated from the
widget types the server serves, so a new type needs a schema on the
server and a renderer here, no new dialog. A data widget picks a table
or view of its application. Only types this frontend can show are
offered.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
The server no longer knows boolean widget settings.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
No setting is a free color any more; the header's color is a choice of the
theme's pairs and uses the enum field.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
…elper for targets and titles

nodeTarget() is split out of widgetTarget() and targetTitle() builds the
emoji and title of a table or view, so the picker and the card agree on
which nodes count and how they are labelled; nodes that are no table or
view are no longer offered. A view is labelled "{title} (view of
{table})", and labels are neither escaped nor sanitized, since the select
renders them as text.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
… say what is missing

The title and description fields have the server's limits of 200 and 2000
characters, and required settings count as empty by the rule of
TextHelper::trim(), zero width spaces included, through new trimText() and
isBlank() helpers that the save uses as well. Required settings and the
table or view picker are marked, visibly and for screen readers, and a line
under the form lists what is still missing. Settings show an optional
per-setting hint from the schema as helper text instead of one fixed
placeholder.

A widget being configured keeps its type also when this frontend has no
renderer for it yet, the title hint says what an empty title does for the
type, the form only shows once the widget types are loaded, and removing
the icon moves focus to the button that picks one.

Assisted-by: ClaudeCode:claude-opus-5-5

Signed-off-by: Ruben van der Linde <ruben@conduction.nl>
@rubenvdlinde
rubenvdlinde force-pushed the feat/noid/grid-widget-editor branch from 258eb0a to 394c24a Compare November 21, 2026 10:53
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