Home widgets

A widget is a home screen item larger than an app tile that shows live content. The web app has two platform widgets, the widgets that modules declare in their metadata, and blank glass panels. This page lists them, their sizes, how they are rendered and saved, and the shared Mine or All scope. The home screen is on home screen, dock, and launcher.

Scope and source¶

• Defined in: webapp/js/home.js (WIDGET_SIZES, BLANK_SIZES, WIDGETS, buildModuleWidgetDefs, openWidgetGallery, tileWidget), webapp/js/custom-widgets.js, webapp/js/widget-ai.js, webapp/js/widget-approvals.js, webapp/js/widget-scope.js
• Count: 2 platform widgets (WIDGETS in webapp/js/home.js:289-320), 4 module widgets (every HomeWidgetMeta( in src/cluster_erp/modules), 6 footprints (WIDGET_SIZES), 4 blank panel sizes (BLANK_SIZES)

Footprints¶

A footprint wider or taller than the device's board is clamped to the board (webapp/js/home.js:98-102). HomeWidgetMeta.size must match the pattern NxM (src/cluster_erp/core/metadata.py:710).

Platform widgets¶

The approvals widget calls POST /auth/approvals/<id>/decide, POST and DELETE /auth/approvals/<id>/defer, and POST /auth/approvals/<id>/cancel (webapp/js/widget-approvals.js:126-268). Its header opens a full-screen queue (webapp/js/home.js:310-317). Approval logic is described on approvals and approval chains.

Module widgets¶

A module declares widgets in ModuleMeta.home_widgets. The platform knows the key, label, icon, size, and target section; the module's gated bundle renders the content (webapp/js/home.js:242-287).

buildModuleWidgetDefs() runs after metadata loads, before the first layout reconcile, so saved widgets are recognised (webapp/js/home.js:458-461). A tile render calls ensureModuleWidgets(module) and then the registered factory with {item, save, open, title} (webapp/js/home.js:255-283). If the module's app is not installed or licensed, the tile shows error.entitlement.module_not_installed (webapp/js/home.js:262-276). See gated app bundles.

tests/test_metadata_driven_rules.py:158 (test_home_widgets_are_module_metadata_rendered_by_module_bundles) checks that the four keys are declared, labelled in English and Turkish, sized NxM, registered in the module's bundle, and not named in home.js.

Gallery, placement, and removal¶

openWidgetGallery() offers the platform widgets, the module widgets of installed modules, and the four blank sizes (webapp/js/home.js:887-930). It opens on a right-click or long-press of empty home space (webapp/js/home.js:4407-4414). Adding a widget places it in the first free slot (webapp/js/home.js:865-877). A right-click on a widget asks to remove it (webapp/js/home.js:858-861, webapp/js/home.js:879-884).

A widget item is saved with the layout as {type: "widget", id, size, widget, cfg, col, row}. cfg holds per-tile settings such as the scope (webapp/js/home.js:660-673). A saved item that names a widget key no longer registered is dropped at reconcile (webapp/js/home.js:661-663).

Mine or All scope¶

widget-scope.js gives module widgets that summarise shared work a Mine and All segment (widgets.scope_mine, widgets.scope_all) (webapp/js/widget-scope.js:1-44).

Bundles receive resolveScope, scopeSegmentHtml, wireScope, and noEmployeeHtml through the platform context (webapp/js/custom-widgets.js:104-110).

Constraints and validation¶

• Platform widgets carry an i18n key as label; module widgets carry a label dictionary resolved by resolveLabel (webapp/js/home.js:286-287).
• The retired clock widget is dropped from saved layouts; time and date live on the status line (webapp/js/home.js:216-218).
• Browser tests: web-client/_e2e_widgets_ai_sched.mjs, web-client/_e2e_approvals_widget.mjs, web-client/_e2e_widget_scope.mjs, web-client/_e2e_widget_projects.mjs, web-client/_e2e_analytics_widget.mjs, web-client/_e2e_widget_swap.mjs.

Terms introduced¶

Related pages¶

• Web app platform
• Home screen, dock, and launcher
• Gated app bundles
• Assistant and chat screens
• Projects board

Verified against commit 92f8051 on 2026-11-13.