firefox-main/browser/extensions/newtab/common
Name Description Size Coverage
Actions.mjs globalImportContext - Are we in UI code (i.e. react, a dom) or some kind of background process? Use this in action creators if you need different logic for ui/background processes. 16324 -
Reducers.sys.mjs 37924 -
WidgetsRegistry.mjs WIDGET_REGISTRY — single source of truth for all New Tab widgets. WHY THIS EXISTS Previously, every widget was hardcoded in three places: the render loop in Widgets.jsx, the hideAllWidgets handler, and the toggleMaximize handler. Adding or removing a widget required edits in all three spots and was easy to get out of sync. This registry replaces those hardcoded lists so that Widgets.jsx, WidgetsSidebar.jsx, and any future consumers share one authoritative definition. HOW IT WORKS Each entry describes one widget's static metadata: id — unique string key used in prefs and the order pref telemetryName — the name sent in Glean events (snake_case; may differ from id) order — default render position (0-indexed); used when widgets.order is empty enabledPref — the user-facing pref that toggles this widget on/off sizePref — the pref that stores the user's chosen size (empty string = not set) defaultSize — size to use when sizePref is empty and no trainhop suggestion exists validSizes — the sizes this widget supports (drives size picker options) hasSidebar — when true, the widget renders in the sidebar instead of the widget row when its effective size equals "small". Size alone is not sufficient — this flag must be set explicitly so that future widgets that support "small" but stay in the row are not accidentally moved to the sidebar. systemEnabledPref — system/operator pref that gates this widget independent of the user pref trainhopEnabledKey — key in trainhopConfig.widgets.* for the enabled override trainhopSizeKey — key in trainhopConfig.widgets.* for the size default suggestion (only applies when the user has not explicitly set sizePref) trainhopSidebarKey — key in trainhopConfig.widgets.* for the hasSidebar override; null means the sidebar placement is not overridable via trainhop SIZE PRIORITY sizePref defaults to "" (empty string) in PREFS_CONFIG. An empty value means the user has not explicitly chosen a size; resolveWidgetSize() falls through to a trainhop suggestion and then to widget.defaultSize. Once the user resizes a widget via the UI the pref is written with a real value and trainhop can no longer override it. resolveWidgetSize() applies these in order: 1. User-set pref (sizePref is non-empty) — always wins 2. trainhopConfig suggestion (trainhopSizeKey) — acts as default, not override 3. widget.defaultSize — final fallback Note: widgets.weather.size uses getValue: getWeatherWidgetSize in ActivityStream.sys.mjs rather than value: "" because it has a Nova migration path that infers the correct initial size from the user's previous weather configuration. After migration the stored value is non-empty and the sentinel logic above applies normally. ADDING A NEW WIDGET 1. Add a new entry to WIDGET_REGISTRY below with the next `order` integer. Set telemetryName to the snake_case Glean name for this widget. 2. Export its pref key constants from this file. 3. Register both prefs (enabled + size) in lib/ActivityStream.sys.mjs. 4. Add the component to WIDGET_ROW_COMPONENTS in WidgetsComponentRegistry.jsx. 5. If it has a sidebar variant, set hasSidebar: true and add its component to WIDGET_SIDEBAR_COMPONENTS in WidgetsComponentRegistry.jsx. ADDING A NEW PER-WIDGET DIMENSION (e.g. "scale") 1. Add scalePref and trainhopScaleKey fields to each registry entry. 2. Export a resolveWidgetScale(widget, prefs) helper following the same user-pref-wins pattern as resolveWidgetSize(). 3. Update components to call the helper instead of reading the pref directly. The widgets.order pref (CSV of widget IDs) persists user-defined order. It is only written when the user explicitly reorders widgets — never on enable/disable. Disabled widgets keep their slot so they reappear in the same position when re-enabled. See resolveWidgetOrder() below. 13650 -