add chrome.power/keep awake as an api sample (#1060)

* add chrome.power/keep awake as an api sample
* support localized file info for extension samples

Co-authored-by: Oliver Dunk <oliverdunk@google.com>

.repo/sample-list-generator/src/types.ts

@@ -10,11 +10,19 @@ export interface ApiItemWithType extends ApiItem {
 }
 
 export interface ManifestData {
+  [key: string]: string;
   name: string;
   description: string;
   permissions: string[];
 }
 
+export interface LocaleData {
+  [key: string]: {
+    message: string;
+    description: string;
+  };
+}
+
 export type SampleItem = {
   type: FolderTypes;
   name: string;
@@ -37,4 +45,4 @@ export type ApiTypeResult =
   | 'type'
   | 'unknown';
 
-export type ExtensionApiMap = Record<string, Record<string, string[]>>
+export type ExtensionApiMap = Record<string, Record<string, string[]>>

.repo/sample-list-generator/src/utils/manifest.ts

@@ -1,5 +1,19 @@
 import fs from 'fs/promises';
-import { ManifestData } from '../types';
+import { dirname } from 'path';
+import { ManifestData, LocaleData } from '../types';
+const localeRegex = /__MSG_([^_]*)__/
+
+function usesLocaleFiles(obj: object): boolean {
+  // recursively check if any value in a supplied object
+  // is a string that starts with __MSG_. If found, it 
+  // means that the extension uses locale files.
+  return Object.values(obj).some((value) => {
+    if (Object.prototype.toString.call(value) === '[object Object]') {
+      return usesLocaleFiles(value);
+    }
+    return typeof value === 'string' && value.startsWith('__MSG_')
+  });
+}
 
 export const getManifest = async (
   manifestPath: string
@@ -7,5 +21,24 @@ export const getManifest = async (
   const manifest = await fs.readFile(manifestPath, 'utf8');
   const parsedManifest = JSON.parse(manifest);
 
+  if (usesLocaleFiles(parsedManifest)) {
+    const directory = dirname(manifestPath);
+    const localeFile: string = await fs.readFile(`${directory}/_locales/en/messages.json`, 'utf8')
+    const localeData: LocaleData = JSON.parse(localeFile);
+
+    for (const [key, value] of Object.entries(parsedManifest)) {
+      if (typeof value === 'string' && value.startsWith('__MSG_')) {
+        const localeKey: string | undefined = value.match(localeRegex)?.[1];
+
+        if (localeKey) {
+          const localeKeyData = localeData[localeKey]
+          const localeMessage: string = localeKeyData?.message;
+
+          parsedManifest[key] = localeMessage;
+        }
+      }
+    }
+  }
+
   return parsedManifest;
 };

api-samples/power/README.md

@@ -0,0 +1,13 @@
+# chrome.power
+
+This extension demonstrates the `chrome.power` API by allowing users to override their system's power management features.
+
+## Overview
+
+The extension adds a popup that cycles different states when clicked. It will go though a mode that prevents the display from dimming or going to sleep, a mode that keeps the system awake but allows the screen to dim/go to sleep, and a mode that uses the system's default.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. Pin the extension and click the action button.

api-samples/power/_locales/en/messages.json

@@ -0,0 +1,22 @@
+{
+  "extensionName": {
+    "message": "Keep Awake",
+    "description": "Extension name."
+  },
+  "extensionDescription": {
+    "message": "Override system power-saving settings.",
+    "description": "Extension description."
+  },
+  "disabledTitle": {
+    "message": "Default power-saving settings",
+    "description": "Browser action title when disabled."
+  },
+  "displayTitle": {
+    "message": "Screen will be kept on",
+    "description": "Browser action title when preventing screen-off."
+  },
+  "systemTitle": {
+    "message": "System will stay awake",
+    "description": "Browser action title when preventing system sleep."
+  }
+}

api-samples/power/background.js

@@ -0,0 +1,99 @@
+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * States that the extension can be in.
+ */
+let StateEnum = {
+  DISABLED: 'disabled',
+  DISPLAY: 'display',
+  SYSTEM: 'system'
+};
+
+/**
+ * Key used for storing the current state in {localStorage}.
+ */
+let STATE_KEY = 'state';
+
+/**
+ * Loads the locally-saved state asynchronously.
+ * @param {function} callback Callback invoked with the loaded {StateEnum}.
+ */
+function loadSavedState(callback) {
+  chrome.storage.local.get(STATE_KEY, function (items) {
+    let savedState = items[STATE_KEY];
+    for (let key in StateEnum) {
+      if (savedState == StateEnum[key]) {
+        callback(savedState);
+        return;
+      }
+    }
+    callback(StateEnum.DISABLED);
+  });
+}
+
+/**
+ * Switches to a new state.
+ * @param {string} newState New {StateEnum} to use.
+ */
+function setState(newState) {
+  let imagePrefix = 'night';
+  let title = '';
+
+  switch (newState) {
+    case StateEnum.DISABLED:
+      chrome.power.releaseKeepAwake();
+      imagePrefix = 'night';
+      title = chrome.i18n.getMessage('disabledTitle');
+      break;
+    case StateEnum.DISPLAY:
+      chrome.power.requestKeepAwake('display');
+      imagePrefix = 'day';
+      title = chrome.i18n.getMessage('displayTitle');
+      break;
+    case StateEnum.SYSTEM:
+      chrome.power.requestKeepAwake('system');
+      imagePrefix = 'sunset';
+      title = chrome.i18n.getMessage('systemTitle');
+      break;
+    default:
+      throw 'Invalid state "' + newState + '"';
+  }
+
+  let items = {};
+  items[STATE_KEY] = newState;
+  chrome.storage.local.set(items);
+
+  chrome.action.setIcon({
+    path: {
+      19: 'images/' + imagePrefix + '-19.png',
+      38: 'images/' + imagePrefix + '-38.png'
+    }
+  });
+  chrome.action.setTitle({ title: title });
+}
+
+chrome.action.onClicked.addListener(function () {
+  loadSavedState(function (state) {
+    switch (state) {
+      case StateEnum.DISABLED:
+        setState(StateEnum.DISPLAY);
+        break;
+      case StateEnum.DISPLAY:
+        setState(StateEnum.SYSTEM);
+        break;
+      case StateEnum.SYSTEM:
+        setState(StateEnum.DISABLED);
+        break;
+      default:
+        throw 'Invalid state "' + state + '"';
+    }
+  });
+});
+
+chrome.runtime.onStartup.addListener(function () {
+  loadSavedState(function (state) {
+    setState(state);
+  });
+});

api-samples/power/manifest.json

@@ -0,0 +1,26 @@
+{
+  "manifest_version": 3,
+
+  "name": "__MSG_extensionName__",
+  "description": "__MSG_extensionDescription__",
+  "version": "1.9",
+  "icons": {
+    "16": "images/icon-16.png",
+    "48": "images/icon-48.png",
+    "128": "images/icon-128.png"
+  },
+
+  "permissions": ["power", "storage"],
+  "action": {
+    "default_title": "__MSG_disabledTitle__",
+    "default_icon": {
+      "19": "images/night-19.png",
+      "38": "images/night-38.png"
+    }
+  },
+  "background": {
+    "service_worker": "background.js"
+  },
+
+  "default_locale": "en"
+}