Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 82 insertions, 0 deletions

diff --git a/browser/components/newtab/docs/v2-system-addon/sections.md b/browser/components/newtab/docs/v2-system-addon/sections.md
new file mode 100644
index 0000000000..332cf5b26d
--- /dev/null
+++ b/browser/components/newtab/docs/v2-system-addon/sections.md
@@ -0,0 +1,82 @@
+# Sections
+
+Each section in Activity Stream displays data from a corresponding section feed
+in a standardised `Section` UI component. Each section feed is responsible for
+listening to events and updating the section options such as the title, icon,
+and rows (the cards for the section to display).
+
+The `Section` UI component displays the rows provided by the section feed. If no
+rows are available it displays an empty state consisting of an icon and a
+message. Optionally, the section may have a info option menu that is displayed
+when users hover over the info icon.
+
+On load, `SectionsManager` and `SectionsFeed` in `SectionsManager.sys.mjs` add the
+sections configured in the `BUILT_IN_SECTIONS` map to the state. These sections
+are initially disabled, so aren't visible. The section's feed may use the
+methods provided by the `SectionsManager` to enable its section and update its
+properties.
+
+The section configuration in `BUILT_IN_SECTIONS` consists of a generator
+function keyed by the pref name for the section feed. The generator function
+takes an `options` argument as the only parameter, which is passed the object
+stored as serialised JSON in the pref `{feed_pref_name}.options`, or the empty
+object if this doesn't exist. The generator returns a section configuration
+object which may have the following properties:
+
+```{eval-rst}
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| Property           | Type                | Description                                                                                                       |
++====================+=====================+===================================================================================================================+
+| id                 | String              | Non-optional unique id.                                                                                           |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| title              | Localisation object | Has property `id`, the string localisation id, and optionally a `values` object to fill in placeholders.          |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| icon               | String              | Icon id. New icons should be added in icons.scss.                                                                 |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| maxRows            | Integer             | Maximum number of rows of cards to display. Should be >= 1.                                                       |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| contextMenuOptions | Array of strings    | The menu options to provide in the card context menus.                                                            |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| shouldHidePref     | Boolean             | If true, will the section preference in the preferences pane will not be shown.                                   |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| pref               | Object              | Configures the section preference to show in the preferences pane. Has properties `titleString` and `descString`. |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+| emptyState         | Object              | Configures the empty state of the section. Has properties `message` and `icon`.                                   |
++--------------------+---------------------+-------------------------------------------------------------------------------------------------------------------+
+```
+
+## Section feeds
+
+Each section feed should be controlled by the pref `feeds.section.{section_id}`.
+
+### Enabling the section
+
+The section feed must listen for the events `INIT` (dispatched when Activity
+Stream is initialised) and `FEED_INIT` (dispatched when a feed is re-enabled
+having been turned off, with the feed id as the `data`). On these events it must
+call `SectionsManager.enableSection(id)`. Care should be taken that this happens
+only once `SectionsManager` has also initialised; the feed can use the method
+`SectionsManager.onceInitialized()`.
+
+### Disabling the section
+
+The section feed must have an `uninit` method. This is called when the section
+feed is disabled by turning the section's pref off. In `uninit` the feed must
+call `SectionsManager.disableSection(id)`. This will remove the section's UI
+component from every existing Activity Stream page.
+
+### Updating the section rows
+
+The section feed can call `SectionsManager.updateSection(id, options)` to update
+section options. The `rows` array property of `options` stores the cards of
+sites to display. Each card object may have the following properties:
+
+```js
+{
+  type, // One of the types in Card/types.js, e.g. "Trending"
+  title, // Title string
+  description, // Description string
+  image, // Image url
+  url // Site url
+}
+```