@ichicraft/widgets-widget-base 1.18.0 → 1.20.0

package/lib/dev/createWidgetDevServerConfig.d.ts

@@ -0,0 +1,31 @@
+import type { Configuration as DevServerConfiguration } from 'webpack-dev-server';
+import type { WidgetDebugServeConfig } from '../types';
+/** Port the first widget dev server claims. Later ones move up from here. */
+export declare const DEFAULT_WIDGET_DEBUG_PORT = 8080;
+export interface CreateWidgetDevServerConfigOptions {
+    /** Root folder of the widget project, normally `__dirname` from webpack.dev.ts. */
+    projectPath: string;
+    /** The widget's `config/serve.config.ts` export. */
+    serveConfig: WidgetDebugServeConfig;
+}
+export interface WidgetDevServerConfigResult {
+    /** The port the dev server will listen on. */
+    port: number;
+    devServer: DevServerConfiguration;
+    /**
+     * Value for the css-loader `localIdentName` option. Keyed by port so two widgets served at
+     * the same time -- and the CDN build of the same widget -- never share a class name.
+     */
+    cssModuleLocalIdentName: string;
+    /** Where the board fetches this widget's manifest from. */
+    manifestUrl: string;
+    /** The board url that gets opened, or null when no debug page is configured. */
+    debugPageUrl: string | null;
+}
+/**
+ * Builds the dev server configuration for debugging a widget against a live widget board.
+ *
+ * The port is resolved at config time rather than hardcoded, so the manifest url handed to the
+ * board always matches the port the server actually binds to.
+ */
+export declare function createWidgetDevServerConfig(options: CreateWidgetDevServerConfigOptions): Promise<WidgetDevServerConfigResult>;

package/lib/dev/createWidgetDevServerConfig.js

@@ -0,0 +1,92 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWidgetDevServerConfig = exports.DEFAULT_WIDGET_DEBUG_PORT = void 0;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+const findAvailablePort_1 = require("./findAvailablePort");
+/** Port the first widget dev server claims. Later ones move up from here. */
+exports.DEFAULT_WIDGET_DEBUG_PORT = 8080;
+/**
+ * Builds the dev server configuration for debugging a widget against a live widget board.
+ *
+ * The port is resolved at config time rather than hardcoded, so the manifest url handed to the
+ * board always matches the port the server actually binds to.
+ */
+function createWidgetDevServerConfig(options) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const { projectPath, serveConfig } = options;
+        const port = (_a = serveConfig.debugPort) !== null && _a !== void 0 ? _a : (yield (0, findAvailablePort_1.findAvailablePort)(exports.DEFAULT_WIDGET_DEBUG_PORT));
+        const manifestUrl = `https://localhost:${port}/manifest.json`;
+        let debugPageUrl = null;
+        if (serveConfig.widgetsDebugPageUrl && serveConfig.openBrowser !== false) {
+            const serveUrl = new url_1.URL(serveConfig.widgetsDebugPageUrl);
+            serveUrl.searchParams.append('debugWidgetManifest', manifestUrl);
+            debugPageUrl = serveUrl.href;
+        }
+        return {
+            port,
+            manifestUrl,
+            debugPageUrl,
+            cssModuleLocalIdentName: `[local]_${port}`,
+            devServer: {
+                static: path_1.default.join(projectPath, './dist'),
+                port,
+                host: 'localhost',
+                allowedHosts: 'all',
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                },
+                client: {
+                    overlay: false,
+                },
+                server: {
+                    type: 'https',
+                    options: resolveDevCertificate(),
+                },
+                open: debugPageUrl
+                    ? {
+                        target: [debugPageUrl],
+                        app: {
+                            name: 'google-chrome',
+                            arguments: ['--incognito', '--new-window'],
+                        },
+                    }
+                    : false,
+                devMiddleware: {
+                    writeToDisk: true,
+                },
+            },
+        };
+    });
+}
+exports.createWidgetDevServerConfig = createWidgetDevServerConfig;
+/**
+ * Uses the SPFx localhost certificate that was trusted with `gulp trust-dev-cert`,
+ * falling back to the rushstack certificate on newer toolchains.
+ */
+function resolveDevCertificate() {
+    const gcbCert = path_1.default.join(os_1.default.homedir(), '.gcb-serve-data', 'gcb-serve.cer');
+    const gcbKey = path_1.default.join(os_1.default.homedir(), '.gcb-serve-data', 'gcb-serve.key');
+    if (fs_1.default.existsSync(gcbCert) && fs_1.default.existsSync(gcbKey)) {
+        return { cert: fs_1.default.readFileSync(gcbCert), key: fs_1.default.readFileSync(gcbKey) };
+    }
+    return {
+        cert: fs_1.default.readFileSync(path_1.default.join(os_1.default.homedir(), '.rushstack', 'rushstack-serve.pem')),
+        key: fs_1.default.readFileSync(path_1.default.join(os_1.default.homedir(), '.rushstack', 'rushstack-serve.key')),
+    };
+}

package/lib/dev/findAvailablePort.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves the first free TCP port at or above `startPort`, so several widget dev servers
+ * can run side by side without anyone having to hand out port numbers.
+ */
+export declare function findAvailablePort(startPort: number, attempts?: number): Promise<number>;

package/lib/dev/findAvailablePort.js

@@ -0,0 +1,55 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePort = void 0;
+const net_1 = __importDefault(require("net"));
+/** Both loopback stacks are checked: a dev server on one of them still owns the port. */
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * Resolves the first free TCP port at or above `startPort`, so several widget dev servers
+ * can run side by side without anyone having to hand out port numbers.
+ */
+function findAvailablePort(startPort, attempts = 50) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let port = startPort; port < startPort + attempts; port++) {
+            if (yield isPortAvailable(port)) {
+                return port;
+            }
+        }
+        throw new Error(`[widgets-widget-base] No free port found between ${startPort} and ${startPort + attempts - 1}. Stop a running dev server or set "debugPort" in config/serve.config.ts.`);
+    });
+}
+exports.findAvailablePort = findAvailablePort;
+function isPortAvailable(port) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const host of LOOPBACK_HOSTS) {
+            if (!(yield isPortAvailableOnHost(port, host))) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+function isPortAvailableOnHost(port, host) {
+    return new Promise((resolve) => {
+        const server = net_1.default.createServer();
+        server.once('error', (err) => {
+            // Anything other than "taken" means we can't bind this stack at all (no IPv6, for
+            // example), which says nothing about whether the port is free.
+            resolve(err.code !== 'EADDRINUSE');
+        });
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}

package/lib/dev/index.d.ts

@@ -0,0 +1,2 @@
+export { createWidgetDevServerConfig, DEFAULT_WIDGET_DEBUG_PORT, type CreateWidgetDevServerConfigOptions, type WidgetDevServerConfigResult, } from './createWidgetDevServerConfig';
+export { findAvailablePort } from './findAvailablePort';

package/lib/dev/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePort = exports.DEFAULT_WIDGET_DEBUG_PORT = exports.createWidgetDevServerConfig = void 0;
+var createWidgetDevServerConfig_1 = require("./createWidgetDevServerConfig");
+Object.defineProperty(exports, "createWidgetDevServerConfig", { enumerable: true, get: function () { return createWidgetDevServerConfig_1.createWidgetDevServerConfig; } });
+Object.defineProperty(exports, "DEFAULT_WIDGET_DEBUG_PORT", { enumerable: true, get: function () { return createWidgetDevServerConfig_1.DEFAULT_WIDGET_DEBUG_PORT; } });
+var findAvailablePort_1 = require("./findAvailablePort");
+Object.defineProperty(exports, "findAvailablePort", { enumerable: true, get: function () { return findAvailablePort_1.findAvailablePort; } });

package/lib/types/index.d.ts

@@ -226,6 +226,14 @@ export interface WidgetContext {
      * Provide the id (GUID) of the Bloom Group.
      */
     isCurrentUserMemberOfBloomGroup?: (groupId: string) => Promise<boolean>;
+    /**
+     * Provides the tenant's Bloom Group definitions, e.g. so pickers can offer them.
+     * Untyped to avoid a cross-package dependency (like `theme`); items carry the
+     * Bloom Group shape as defined by the host.
+     */
+    bloomGroups?: {
+        fetchGroups(): Promise<any[]>;
+    };
     /**
      * Generates a hash of all combined SP Groups of the current user. This can be used as
      * cache invalidator to detect changes.
@@ -697,17 +705,6 @@ export interface WidgetManifestConfig {
         }[];
     };
 }
-export declare enum DebugComponentType {
-    /**
-     * This is the default component type and just opens the default widget board.
-     */
-    Default = "Default",
-    /**
-     * This automatically opens the widget board administration panel and opens the widget admin config
-     * dialog of the widget you're working on
-     */
-    AdminConfig = "AdminConfig"
-}
 /**
  * The widget debug serve config contains settings for debugging a widget in development
  */
@@ -718,11 +715,16 @@ export interface WidgetDebugServeConfig {
      */
     widgetsDebugPageUrl: string;
     /**
-     * Provide a component type to open the debugging widget board with that specific component.
-     * This speeds up your development cycle: [npm run start] > save changes > builds automatically >
-     * refresh browser > automatically open updated component.
+     * Pin the dev server to a specific port. When omitted, the first free port from 8080 upwards
+     * is used, so several widgets can be debugged side by side without configuration.
+     */
+    debugPort?: number;
+    /**
+     * Open the widget board in a browser when the dev server starts. Defaults to true.
+     * Set this to false for the second and further widgets in a multi-widget debug session:
+     * they only need to serve their bundle and are registered from the board that is already open.
      */
-    debugComponentType?: DebugComponentType;
+    openBrowser?: boolean;
 }
 /**
  * Tells the severity of the command bar item, resulting in

package/lib/types/index.js

@@ -1,18 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = exports.DebugComponentType = void 0;
-var DebugComponentType;
-(function (DebugComponentType) {
-    /**
-     * This is the default component type and just opens the default widget board.
-     */
-    DebugComponentType["Default"] = "Default";
-    /**
-     * This automatically opens the widget board administration panel and opens the widget admin config
-     * dialog of the widget you're working on
-     */
-    DebugComponentType["AdminConfig"] = "AdminConfig";
-})(DebugComponentType || (exports.DebugComponentType = DebugComponentType = {}));
+exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = void 0;
 /**
  * Tells the severity of the command bar item, resulting in
  * distinguishable presentation of the item

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@ichicraft/widgets-widget-base",
-    "version": "1.18.0",
+    "version": "1.20.0",
     "description": "Part of the Widget Development Kit for building widgets for Bloom Intranet",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
     "scripts": {
-        "build": "tsc --build --force --verbose",
-        "build:watch": "tsc  --build --force --verbose --watch",
+        "build": "tsc --build --force --verbose tsconfig.json tsconfig.dev.json",
+        "build:watch": "tsc --build --force --verbose --watch tsconfig.json tsconfig.dev.json",
         "clean": "rimraf lib",
         "pretty": "prettier --write \"./**/*.{js,jsx,mjs,cjs,ts,tsx,json}\"",
         "prepublishOnly": "npm run clean && npm run build"
@@ -19,7 +19,8 @@
     "author": "Ichicraft",
     "license": "UNLICENSED",
     "files": [
-        "lib/**/*"
+        "lib/**/*",
+        "!lib/**/*.tsbuildinfo"
     ],
     "overrides": {
         "requirejs": "2.3.7",
@@ -34,12 +35,27 @@
     },
     "devDependencies": {
         "@ianvs/prettier-plugin-sort-imports": "4.4.1",
+        "@types/node": "^18.19.0",
         "eslint": "8.57.0",
         "eslint-config-prettier": "9.1.0",
         "eslint-plugin-prettier": "5.2.1",
         "eslint-plugin-react": "7.35.2",
         "eslint-plugin-react-hooks": "4.6.2",
         "prettier": "3.3.3",
-        "typescript": "~5.3.3"
+        "typescript": "~5.3.3",
+        "webpack": "^5.109.2",
+        "webpack-dev-server": "^5.2.6"
+    },
+    "peerDependencies": {
+        "webpack": "^5.0.0",
+        "webpack-dev-server": "^5.0.0"
+    },
+    "peerDependenciesMeta": {
+        "webpack": {
+            "optional": true
+        },
+        "webpack-dev-server": {
+            "optional": true
+        }
     }
 }