Merge pull request #13 from swsnr/globals

Add global shell types

examples/hello-world/src/extension.ts

@@ -2,6 +2,7 @@ import '@girs/gjs'; // For global types like `log()`
 import St from '@girs/st-13';
 import GObject from '@girs/gobject-2.0';
 
+import "@girs/gnome-shell/global"; // For global shell types
 import { Extension, gettext as _ } from '@girs/gnome-shell/extensions/extension';
 import * as panelMenu from '@girs/gnome-shell/ui/panelMenu';
 import { PopupMenuItem } from '@girs/gnome-shell/ui/popupMenu';
@@ -25,7 +26,7 @@ class TIndicator extends PanelMenuButton {
 
         let item = new PopupMenuItem(_('Show Notification'));
         item.connect('activate', () => {
-            Main.notify(_('Hello World! :)'));
+            Main.notify(_('Hello %s! :)').format("World"));
         });
 
         this.menu.addMenuItem(item);

packages/gnome-shell/README.md

@@ -50,6 +50,17 @@ import '@girs/gnome-shell/ui/components/automountManager/ambient';  // For a spe
 
 These Ambient types can be integrated into your project by including them in your `tsconfig.json` or by importing them at the top of your main project file, typically `extension.ts`.
 
+## GNOME Shell globals
+
+GNOME Shell defines some specific globals and monkey-patches some built-in GJS objects.
+To import the corresponding types, use:
+
+```ts
+import '@girs/gnome-shell/extensions/global';
+```
+
+Note that these globals are not available in the environment that runs the preferences code from `prefs.js`.  If You make use of these global types take care in `prefs.js`.
+
 ## ESM vs. CommonJS in GJS
 
 GJS supports two import syntaxes: the modern ESM syntax and the traditional global imports syntax. This package is designed to accommodate both, depending on your project's setup and requirements.

packages/gnome-shell/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
+    "./extensions/global": "./dist/extensions/global.d.ts",
     "./extensions/extension": {
       "import": {
         "types": "./dist/extensions/extension.d.ts",

packages/gnome-shell/scripts/generate-exports.js

@@ -5,7 +5,7 @@ import { loadJsonFile, writeJsonFile } from './utils/json.js';
 import { DIST_DIR, __dirname } from './config.js';
 import { resolve, extname, basename } from 'path';
 
-const IGNORE_FILENAMES = ['sharedInternals.d.ts']
+const IGNORE_FILENAMES = ['sharedInternals.d.ts', 'global.d.ts']
 const IGNORE_DIRS = ['types']
 
 /** */
@@ -44,18 +44,20 @@ const generateExport = (filePath) => {
 
 const start = async () => {
     const pkg = await loadJsonFile(resolve(__dirname, '../package.json'));
-    
+
     const typeFiles = await getAllFiles(DIST_DIR, ['.ts'], IGNORE_DIRS);
 
-    let exports = {};
+    let exports = {
+        "./extensions/global": "./dist/extensions/global.d.ts"
+    };
 
     for (const absolutePath of typeFiles) {
         exports = { ...exports, ...generateExport(absolutePath) }
     }
 
     pkg.exports = exports;
-    
+
     writeJsonFile(resolve(__dirname, '../package.json'), pkg);
 }
 
-await start();
+await start();

packages/gnome-shell/scripts/generate-files.js

@@ -16,7 +16,7 @@ const AMBIENT_TEMPLATE = (path, fileName) => `declare module "${RESOURCE_PATH(pa
 const ESM_TEMPLATE = (path, fileName) => `export * from '${RESOURCE_PATH(path, fileName)}';`;
 const CJS_TEMPLATE = (path, fileName) => `module.exports = imports${path.replaceAll('/', '.')}.${fileName};`;
 
-const IGNORE_FILENAMES = ['index.d.ts', 'index.ts', 'sharedInternals.d.ts'];
+const IGNORE_FILENAMES = ['index.d.ts', 'index.ts', 'sharedInternals.d.ts', 'global.d.ts'];
 
 const IGNORE_DIRS = ['types'];
 

packages/gnome-shell/scripts/generate-index.js

@@ -7,7 +7,7 @@ import { resolve, extname, basename } from 'path';
 import { writeFile } from 'fs/promises';
 
 const IGNORE_DIRS = ['types']
-const IGNORE_FILENAMES = ['index.d.ts', 'index.ts', 'sharedInternals.d.ts']
+const IGNORE_FILENAMES = ['index.d.ts', 'index.ts', 'sharedInternals.d.ts', 'global.d.ts']
 const EXPORT_ESM_TEMPLATE = (exportName, fileName) => `export * as ${exportName} from './${fileName}.js';`;
 const EXPORT_CJS_TEMPLATE = (exportName, fileName) => `module.exports.${exportName} = require('./${fileName}.cjs');`;
 const IMPORT_AMBIENT_TEMPLATE = (fileName) => `import './${fileName}-ambient.d.ts';`;
@@ -35,7 +35,7 @@ const appendFile = async (filePath, data) => {
 }
 
 
-const start = async () => {    
+const start = async () => {
     const dirs = await getAllDirs(DIST_DIR, IGNORE_DIRS, true);
 
     for (const absoluteDir of dirs) {
@@ -61,7 +61,7 @@ const start = async () => {
         await writeFile(resolve(absoluteDir, 'index.js'), data.esm, 'utf-8');
         await writeFile(resolve(absoluteDir, 'index.cjs'), data.cjs, 'utf-8');
         await writeFile(resolve(absoluteDir, 'index-ambient.d.ts'), data.ambient, 'utf-8');
-        
+
     }
 
     const rootDirs = await getAllDirs(DIST_DIR, IGNORE_DIRS, false);
@@ -82,4 +82,4 @@ const start = async () => {
     await writeFile(resolve(DIST_DIR, 'index-ambient.d.ts'), data.ambient, 'utf-8');
 }
 
-await start();
+await start();

packages/gnome-shell/scripts/generate-types.js

@@ -4,7 +4,7 @@ import { getAllFiles } from './utils/files.js';
 import { copyFile, mkdir } from 'fs/promises';
 import { SRC_DIR, DIST_DIR, __dirname } from './config.js';
 
-const start = async () => {    
+const start = async () => {
     const srcFiles = await getAllFiles(SRC_DIR, ['.ts', '.js', '.cjs']);
 
     for (const srcFile of srcFiles) {
@@ -14,4 +14,4 @@ const start = async () => {
     }
 }
 
-await start();
+await start();

packages/gnome-shell/src/extensions/global.d.ts

@@ -0,0 +1,34 @@
+import type Shell from "@girs/shell-13";
+
+declare global {
+  /**
+   * Global shell object created by GNOME Shell on startup.
+   *
+   * @see https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/8a8539ee6766058b39d0a5c0961a08f76799f4da/js/ui/environment.js#L253
+   */
+  const global: Shell.Global;
+}
+
+// Gnome shell monkey-patches format into `String` which is the recommended way to use formatting for translatable strings.
+// See https://gjs.guide/extensions/development/translations.html#marking-strings-for-translation
+interface String {
+  /**
+   * Format this string with the given `args`.
+   *
+   * @see https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/8a8539ee6766058b39d0a5c0961a08f76799f4da/js/ui/environment.js#L355
+   * @param args
+   */
+  format(...args: any[]): string;
+}
+
+interface Math {
+  /**
+   * Returns {@link x} clamped to the inclusive range of {@link min} and {@link max}.
+   *
+   * @see https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/8a8539ee6766058b39d0a5c0961a08f76799f4da/js/ui/environment.js#L357
+   * @param x The value to be clamped.
+   * @param min The lower bound of the result.
+   * @param max The upper bound of the result.
+   */
+  clamp(x: number, min: number, max: number): number;
+}