From 2539a9a57eca2c621ed39e9a9ee8423972f21f84 Mon Sep 17 00:00:00 2001 From: Shane Osbourne Date: Tue, 29 Oct 2024 21:27:03 +0000 Subject: [PATCH] docs structure --- .../messages/new-tab/examples/widgets.js | 10 +++--- special-pages/pages/new-tab/app/docs.js | 14 +++----- special-pages/pages/new-tab/app/new-tab.md | 23 ++++++++++++ .../app/privacy-stats/privacy-stats.md | 35 +++++++++++++++++++ .../privacy-stats/privacy-stats.service.js | 33 ----------------- .../{rmf.service.md => rmf.md} | 2 +- .../remote-messaging-framework/rmf.service.js | 4 --- ...tion.service.md => update-notification.md} | 0 special-pages/pages/new-tab/app/utils.js | 4 ++- .../new-tab/app/widget-list/widget-config.md | 26 ++++++++++++++ .../app/widget-list/widget-config.service.js | 24 ------------- 11 files changed, 99 insertions(+), 76 deletions(-) create mode 100644 special-pages/pages/new-tab/app/new-tab.md create mode 100644 special-pages/pages/new-tab/app/privacy-stats/privacy-stats.md rename special-pages/pages/new-tab/app/remote-messaging-framework/{rmf.service.md => rmf.md} (98%) rename special-pages/pages/new-tab/app/update-notification/{update-notification.service.md => update-notification.md} (100%) create mode 100644 special-pages/pages/new-tab/app/widget-list/widget-config.md diff --git a/special-pages/messages/new-tab/examples/widgets.js b/special-pages/messages/new-tab/examples/widgets.js index a5523609ba..2ec7a1daa2 100644 --- a/special-pages/messages/new-tab/examples/widgets.js +++ b/special-pages/messages/new-tab/examples/widgets.js @@ -34,12 +34,14 @@ const widgetConfig = { */ const initialSetupResponse = { widgets: [ - { "id": "weatherWidget" }, - { "id": "newsWidget" } + { "id": "updateNotification" }, + { "id": "rmf" }, + { "id": "favorites" }, + { "id": "privacyStats" } ], widgetConfigs: [ - { "id": "weatherWidget", "visibility": "visible" }, - { "id": "newsWidget", "visibility": "visible" } + { "id": "favorites", "visibility": "visible" }, + { "id": "privacyStats", "visibility": "visible" } ], env: 'production', locale: 'en', diff --git a/special-pages/pages/new-tab/app/docs.js b/special-pages/pages/new-tab/app/docs.js index a53255f9f9..3b278c6716 100644 --- a/special-pages/pages/new-tab/app/docs.js +++ b/special-pages/pages/new-tab/app/docs.js @@ -1,13 +1,9 @@ /** - * - * - {@link WidgetConfigService} - * - {@link PrivacyStatsService} - * - {@link RMFService} - * - {@link UpdateNotificationService} + * @document ./new-tab.md + * @document ./widget-list/widget-config.md + * @document ./remote-messaging-framework/rmf.md + * @document ./update-notification/update-notification.md + * @document ./privacy-stats/privacy-stats.md * * @module NewTab Services */ -export * from './privacy-stats/privacy-stats.service.js' -export * from './widget-list/widget-config.service.js' -export * from './remote-messaging-framework/rmf.service.js' -export * from './update-notification/update-notification.service.js' diff --git a/special-pages/pages/new-tab/app/new-tab.md b/special-pages/pages/new-tab/app/new-tab.md new file mode 100644 index 0000000000..b80f97138e --- /dev/null +++ b/special-pages/pages/new-tab/app/new-tab.md @@ -0,0 +1,23 @@ +--- +title: New Tab Page +--- + +## Requests + +- {@link "NewTab Messages".InitialSetupRequest `initialSetup`} + - Returns {@link "NewTab Messages".InitialSetupResponse} + - See the `initialSetupResponse` section of [example of initial data](../../../messages/new-tab/examples/widgets.js) + +## Notifications + +- {@link "NewTab Messages".ContextMenuNotification `contextMenu`} + - Sent when the user right-clicks in the page + - Note: Other widgets might prevent this (and send their own, eg: favorites) + +- {@link "NewTab Messages".ReportInitExceptionNotification `reportInitException`} + - Sent when the application fails to initialize (for example, a JavaScript exception prevented it) + - Sends: `{ message: string }` - see {@link "NewTab Messages".ReportInitExceptionNotify} + +- {@link "NewTab Messages".ReportPageExceptionNotification `reportPageException`} + - Sent when the application failed after initialization (for example, a JavaScript exception prevented it) + - Sends: `{ message: string }` - see {@link "NewTab Messages".ReportPageExceptionNotify} diff --git a/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.md b/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.md new file mode 100644 index 0000000000..fc1093436a --- /dev/null +++ b/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.md @@ -0,0 +1,35 @@ +--- +title: Privacy Stats +--- + +## Requests: +- {@link "NewTab Messages".StatsGetDataRequest `stats_getData`} + - Used to fetch the initial data (during the first render) + - returns {@link "NewTab Messages".PrivacyStatsData} + +- {@link "NewTab Messages".StatsGetDataRequest `stats_getConfig`} + - Used to fetch the initial config data (eg: expanded vs collapsed) + - returns {@link "NewTab Messages".StatsConfig} + +## Subscriptions: +- {@link "NewTab Messages".StatsOnDataUpdateSubscription `stats_onDataUpdate`}. + - The tracker/company data used in the feed. + - returns {@link "NewTab Messages".PrivacyStatsData} +- {@link "NewTab Messages".StatsOnDataUpdateSubscription `stats_onConfigUpdate`}. + - The widget config + - returns {@link "NewTab Messages".StatsConfig} + +## Notifications: +- {@link "NewTab Messages".StatsSetConfigNotification `stats_setConfig`} + - Sent when the user toggles the expansion of the stats + - sends {@link "NewTab Messages".StatsConfig} + - example payload: + ```json + { + "expansion": "collapsed" + } + ``` + +## Examples: +The following examples show the data types in JSON format: +[messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/stats.js) diff --git a/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.service.js b/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.service.js index e9ab6f20ec..cce8ced8c3 100644 --- a/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.service.js +++ b/special-pages/pages/new-tab/app/privacy-stats/privacy-stats.service.js @@ -4,39 +4,6 @@ */ import { Service } from '../service.js' -/** - * ## Requests: - * - {@link "NewTab Messages".StatsGetDataRequest `stats_getData`} - * - Used to fetch the initial data (during the first render) - * - returns {@link "NewTab Messages".PrivacyStatsData} - * - * - {@link "NewTab Messages".StatsGetDataRequest `stats_getConfig`} - * - Used to fetch the initial config data (eg: expanded vs collapsed) - * - returns {@link "NewTab Messages".StatsConfig} - * - * ## Subscriptions: - * - {@link "NewTab Messages".StatsOnDataUpdateSubscription `stats_onDataUpdate`}. - * - The tracker/company data used in the feed. - * - returns {@link "NewTab Messages".PrivacyStatsData} - * - {@link "NewTab Messages".StatsOnDataUpdateSubscription `stats_onConfigUpdate`}. - * - The widget config - * - returns {@link "NewTab Messages".StatsConfig} - * - * ## Notifications: - * - {@link "NewTab Messages".StatsSetConfigNotification `stats_setConfig`} - * - Sent when the user toggles the expansion of the stats - * - sends {@link "NewTab Messages".StatsConfig} - * - example payload: - * ```json - * { - * "expansion": "collapsed" - * } - * ``` - * - * ## Examples: - * The following examples show the data types in JSON format: - * [messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/stats.js) - */ export class PrivacyStatsService { /** * @param {import("../../src/js/index.js").NewTabPage} ntp - The internal data feed, expected to have a `subscribe` method. diff --git a/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.md b/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.md similarity index 98% rename from special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.md rename to special-pages/pages/new-tab/app/remote-messaging-framework/rmf.md index eac5f2951b..7b3176a710 100644 --- a/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.md +++ b/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.md @@ -44,4 +44,4 @@ title: Remote Messaging Framework ## Examples: The following examples show the data types in JSON format: -[messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/rmf.js) \ No newline at end of file +[messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/rmf.js) diff --git a/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.js b/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.js index fd1af55eb7..6fb1f9a349 100644 --- a/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.js +++ b/special-pages/pages/new-tab/app/remote-messaging-framework/rmf.service.js @@ -3,10 +3,6 @@ */ import { Service } from '../service.js' -/** - * @document ./rmf.service.md - */ - export class RMFService { /** * @param {import("../../src/js/index.js").NewTabPage} ntp - The internal data feed, expected to have a `subscribe` method. diff --git a/special-pages/pages/new-tab/app/update-notification/update-notification.service.md b/special-pages/pages/new-tab/app/update-notification/update-notification.md similarity index 100% rename from special-pages/pages/new-tab/app/update-notification/update-notification.service.md rename to special-pages/pages/new-tab/app/update-notification/update-notification.md diff --git a/special-pages/pages/new-tab/app/utils.js b/special-pages/pages/new-tab/app/utils.js index 17383f83ff..36e499ca46 100644 --- a/special-pages/pages/new-tab/app/utils.js +++ b/special-pages/pages/new-tab/app/utils.js @@ -68,7 +68,9 @@ export function noop (named) { export function useContextMenu () { const messaging = useMessaging() useEffect(() => { - function handler () { + function handler (e) { + e.preventDefault(); + e.stopImmediatePropagation(); messaging.contextMenu() } document.body.addEventListener('contextmenu', handler) diff --git a/special-pages/pages/new-tab/app/widget-list/widget-config.md b/special-pages/pages/new-tab/app/widget-list/widget-config.md new file mode 100644 index 0000000000..ed0d19a223 --- /dev/null +++ b/special-pages/pages/new-tab/app/widget-list/widget-config.md @@ -0,0 +1,26 @@ +--- +title: Widget Config +--- + +## InitialSetup: + +- Data for widgets should be provided as part of the {@link "NewTab Messages".InitialSetupResponse `initialSetup`} response. +- The following keys should be added (also see the example below) + - `widgets`: {@link "NewTab Messages".Widgets} + - `widgetConfigs`: {@link "NewTab Messages".WidgetConfigs} + +## Subscriptions: +- {@link "NewTab Messages".WidgetsOnConfigUpdatedSubscription `widgets_onConfigUpdated`} +- returns {@link "NewTab Messages".WidgetConfigs}. + + +## Notifications: +- {@link "NewTab Messages".WidgetsOnConfigUpdatedSubscription `widgets_setConfig`} +- sends {@link "NewTab Messages".WidgetConfigs} + + If the user toggles the visibility of a section in the frontend, then the entire structure is sent to the + native side. + +## Examples: +The following examples show the data types in JSON format: +[messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/widgets.js) diff --git a/special-pages/pages/new-tab/app/widget-list/widget-config.service.js b/special-pages/pages/new-tab/app/widget-list/widget-config.service.js index c52e81b7bd..29f97586da 100644 --- a/special-pages/pages/new-tab/app/widget-list/widget-config.service.js +++ b/special-pages/pages/new-tab/app/widget-list/widget-config.service.js @@ -3,30 +3,6 @@ */ import { Service } from '../service.js' -/** - * ## InitialSetup: - * - * - Data for widgets should be provided as part of the {@link "NewTab Messages".InitialSetupResponse `initialSetup`} response. - * - The following keys should be added (also see the example below) - * - `widgets`: {@link "NewTab Messages".Widgets} - * - `widgetConfigs`: {@link "NewTab Messages".WidgetConfigs} - * - * ## Subscriptions: - * - {@link "NewTab Messages".WidgetsOnConfigUpdatedSubscription `widgets_onConfigUpdated`} - * - returns {@link "NewTab Messages".WidgetConfigs}. - * - * - * ## Notifications: - * - {@link "NewTab Messages".WidgetsOnConfigUpdatedSubscription `widgets_setConfig`} - * - sends {@link "NewTab Messages".WidgetConfigs} - * - * If the user toggles the visibility of a section in the frontend, then the entire structure is sent to the - * native side. - * - * ## Examples: - * The following examples show the data types in JSON format: - * [messages/new-tab/examples/stats.js](../../../../messages/new-tab/examples/widgets.js) - */ export class WidgetConfigService { /** * @param {import("../../src/js/index.js").NewTabPage} ntp - The internal data feed