pict-microapp 1.0.0

package/source/Pict-MicroApp.js

@@ -0,0 +1,486 @@
+/**
+ * Pict MicroApp — present a large pict application as a small, focused one.
+ *
+ * A "micro app" is not a fork and not a rebuild: it is the SAME application, booted the same way,
+ * with a smaller surface. You keep every view, provider, template, style and fix the host app
+ * already has — and an enhancement to the host lands in every micro app on its next build — but
+ * the routes, the navigation and the landing page are the micro app's own.
+ *
+ * The seam is narrow on purpose. A host pict application registers every route it owns through one
+ * funnel, `PictRouter.addRoute`. This provider wraps that funnel with an allow list taken from a
+ * declarative manifest, swaps the navigation graph, and re-points the landing route. Nothing else
+ * about the host's boot sequence changes, which is what keeps a micro app cheap to build and cheap
+ * to keep working as the host evolves.
+ *
+ * What this module deliberately does NOT do is make the JavaScript bundle smaller — the host's
+ * module graph is still bundled whole. It slims the app the user sees, not the bytes the browser
+ * downloads. See the README for the reasoning and for when that tradeoff stops being the right one.
+ *
+ * @author steven velozo <steven@velozo.com>
+ */
+
+const libPictProvider = require('pict-provider');
+
+const libManifest = require('./Pict-MicroApp-Manifest.js');
+
+const _DEFAULT_PROVIDER_CONFIGURATION =
+{
+	ProviderIdentifier: 'MicroApp',
+
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+
+	// The micro app manifest. See Pict-MicroApp-Manifest.js for the shape and defaults.
+	Manifest: {},
+
+	// Service hash of the host's pict-router provider. Every host that uses pict-router registers
+	// it under this hash.
+	RouterProviderHash: 'PictRouter',
+
+	// Service hash of the host's pict-section-navigation provider, when it has one.
+	NavigationProviderHash: 'Pict-Navigation',
+
+	// Log each route the gate blocks. Noisy but invaluable while authoring a manifest, so it is on.
+	LogBlockedRoutes: true
+};
+
+class PictMicroApp extends libPictProvider
+{
+	/**
+	 * @param {Object} pFable - the fable instance
+	 * @param {Object} [pOptions] - provider options, including the Manifest
+	 * @param {String} [pServiceHash] - the service hash
+	 */
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		const tmpOptions = Object.assign({}, _DEFAULT_PROVIDER_CONFIGURATION, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		/** @type {any} */
+		this.pict;
+
+		/** The normalized manifest — always fully populated, whatever the author wrote. */
+		this.manifest = libManifest.normalizeManifest(this.options.Manifest);
+
+		/** Route patterns the gate refused, in registration order. Read this when a screen is missing. */
+		this.blockedRoutes = [];
+		/** Route patterns the gate admitted with an entity guard. */
+		this.guardedRoutes = [];
+		/** Route patterns that survived untouched. */
+		this.allowedRoutes = [];
+
+		/** The original addRoute, kept so releaseRouter() can put the host back the way it was. */
+		this._originalAddRoute = null;
+		/** The original navigo `on`, for the same reason. */
+		this._originalRouterOn = null;
+		/** The router provider the gate is currently installed on. */
+		this._gatedRouter = null;
+		/** True while the provider-level gate is delegating into the navigo-level one. */
+		this._delegating = false;
+	}
+
+	/**
+	 * The host's pict-router provider, or null before it exists.
+	 *
+	 * @return {Object|null} the router provider
+	 */
+	get pictRouter()
+	{
+		const tmpProviders = (this.pict && this.pict.providers) ? this.pict.providers : {};
+		return tmpProviders[this.options.RouterProviderHash] || null;
+	}
+
+	/**
+	 * The host's navigation provider, or null when the host has none.
+	 *
+	 * @return {Object|null} the navigation provider
+	 */
+	get navigationProvider()
+	{
+		const tmpProviders = (this.pict && this.pict.providers) ? this.pict.providers : {};
+		return tmpProviders[this.options.NavigationProviderHash] || null;
+	}
+
+	/**
+	 * Replace the manifest after construction. Only meaningful before the gate is installed.
+	 *
+	 * @param {Object} pManifest - a micro app manifest
+	 * @return {Object} the normalized manifest
+	 */
+	setManifest(pManifest)
+	{
+		this.manifest = libManifest.normalizeManifest(pManifest);
+		return this.manifest;
+	}
+
+	/**
+	 * What would the gate do with this route? Exposed so an app (or a test) can ask without
+	 * registering anything.
+	 *
+	 * @param {String} pRoute - a route pattern
+	 * @return {{Mode: String, Route: String, Reason: String}} the decision
+	 */
+	routeDecision(pRoute)
+	{
+		return libManifest.decideRoute(this.manifest, pRoute);
+	}
+
+	/**
+	 * Install the route gate on the host's router.
+	 *
+	 * MUST be called after the router provider exists but BEFORE the host registers its routes. In
+	 * a pict application that means after the provider that owns routing has been added (usually in
+	 * onInitializeAsync) and before the login/data-load cycle that registers them.
+	 *
+	 * Wrapping the instance method rather than the prototype keeps the blast radius to this one
+	 * router: a host that shares pict-router with an embedded module is unaffected.
+	 *
+	 * TWO funnels are wrapped, not one. Most code registers through the provider's `addRoute`, but
+	 * some modules reach past it and call the underlying router's `on` directly — pict-section-
+	 * recordset's list, dashboard, associate and bulk-delete views all do, which is every one of its
+	 * highest-traffic screens. Gating only `addRoute` silently leaves those wide open, and because
+	 * they still work you would never notice. The provider-level wrapper sets `_delegating` while it
+	 * calls through, so a route that came in via `addRoute` is decided once, not twice.
+	 *
+	 * @param {Object} [pPictRouter] - the router provider; defaults to the configured one
+	 * @return {Boolean} whether the gate was installed
+	 */
+	gateRouter(pPictRouter)
+	{
+		const tmpRouter = pPictRouter || this.pictRouter;
+		if (!tmpRouter || (typeof tmpRouter.addRoute !== 'function'))
+		{
+			this.pict.log.warn(`MicroApp [${ this.manifest.Name }] could not gate routes: no router provider at '${ this.options.RouterProviderHash }'.`);
+			return false;
+		}
+		if (this._originalAddRoute)
+		{
+			// Already gated. Re-gating would double-wrap every handler.
+			return true;
+		}
+
+		this._gatedRouter = tmpRouter;
+		this._originalAddRoute = tmpRouter.addRoute.bind(tmpRouter);
+
+		tmpRouter.addRoute = (pRoute, pRenderable, pTitle, pHooks) =>
+		{
+			const tmpDecision = this.routeDecision(pRoute);
+			if (tmpDecision.Mode === 'Block')
+			{
+				this._noteBlocked(tmpDecision);
+				return;
+			}
+
+			const tmpGuarded = (tmpDecision.Mode === 'Guard');
+			if (tmpGuarded)
+			{
+				this.guardedRoutes.push(tmpDecision.Route);
+			}
+			else
+			{
+				this.allowedRoutes.push(tmpDecision.Route);
+			}
+
+			this._delegating = true;
+			try
+			{
+				return this._originalAddRoute(tmpDecision.Route,
+					tmpGuarded ? this._guardRenderable(tmpDecision.Route, pRenderable) : pRenderable, pTitle, pHooks);
+			}
+			finally
+			{
+				this._delegating = false;
+			}
+		};
+
+		// The second funnel: direct registrations against the underlying router.
+		if (tmpRouter.router && (typeof tmpRouter.router.on === 'function'))
+		{
+			this._originalRouterOn = tmpRouter.router.on.bind(tmpRouter.router);
+			tmpRouter.router.on = (pRoute, pHandler, pHooks) =>
+			{
+				// Already decided by the provider-level wrapper, or one of the router's other
+				// `on` shapes (a bare handler, or a route map) that carries no path to decide on.
+				if (this._delegating || (typeof pRoute !== 'string'))
+				{
+					return this._originalRouterOn(pRoute, pHandler, pHooks);
+				}
+
+				const tmpDecision = this.routeDecision(pRoute);
+				if (tmpDecision.Mode === 'Block')
+				{
+					this._noteBlocked(tmpDecision);
+					return this._gatedRouter.router;
+				}
+				if (tmpDecision.Mode === 'Guard')
+				{
+					this.guardedRoutes.push(tmpDecision.Route);
+					return this._originalRouterOn(tmpDecision.Route, this._guardRenderable(tmpDecision.Route, pHandler), pHooks);
+				}
+				this.allowedRoutes.push(tmpDecision.Route);
+				return this._originalRouterOn(pRoute, pHandler, pHooks);
+			};
+		}
+
+		return true;
+	}
+
+	/**
+	 * Record (and optionally log) a route the gate refused.
+	 *
+	 * @param {{Route: String, Reason: String}} pDecision - the decision that blocked it
+	 */
+	_noteBlocked(pDecision)
+	{
+		this.blockedRoutes.push(pDecision.Route);
+		if (this.options.LogBlockedRoutes)
+		{
+			this.pict.log.trace(`MicroApp [${ this.manifest.Name }] route not exposed: ${ pDecision.Route } (${ pDecision.Reason })`);
+		}
+	}
+
+	/**
+	 * Put the host's router back the way it was. Primarily for tests.
+	 *
+	 * @return {Boolean} whether a gate was removed
+	 */
+	releaseRouter()
+	{
+		if (!this._gatedRouter || !this._originalAddRoute)
+		{
+			return false;
+		}
+		this._gatedRouter.addRoute = this._originalAddRoute;
+		if (this._originalRouterOn && this._gatedRouter.router)
+		{
+			this._gatedRouter.router.on = this._originalRouterOn;
+		}
+		this._originalAddRoute = null;
+		this._originalRouterOn = null;
+		this._gatedRouter = null;
+		return true;
+	}
+
+	/**
+	 * Wrap an entity-parameterized route's handler so an entity the micro app does not expose
+	 * bounces to the fallback instead of rendering.
+	 *
+	 * Wildcard record-set routes ('/PSRS/:RecordSet/List') are registered once by the host and fan
+	 * out over every entity it knows. They cannot be refused per-entity at registration time, so
+	 * this is where the subsetting has to happen.
+	 *
+	 * @param {String} pRoute - the canonical route pattern
+	 * @param {Function|String} pRenderable - the host's handler
+	 * @return {Function|String} the guarded handler, or the renderable untouched when it is a template
+	 */
+	_guardRenderable(pRoute, pRenderable)
+	{
+		if (typeof pRenderable !== 'function')
+		{
+			return pRenderable;
+		}
+		const tmpEntityParameter = this.manifest.Routes.EntityParameter;
+		return (pRouteData) =>
+		{
+			const tmpEntity = (pRouteData && pRouteData.data) ? pRouteData.data[tmpEntityParameter] : null;
+			if (tmpEntity && !libManifest.entityPermitted(this.manifest, tmpEntity))
+			{
+				this.pict.log.trace(`MicroApp [${ this.manifest.Name }] entity not exposed on ${ pRoute }: ${ tmpEntity } — routing to ${ this.manifest.Routes.Fallback }.`);
+				return this.navigate(this.manifest.Routes.Fallback);
+			}
+			return pRenderable(pRouteData);
+		};
+	}
+
+	/**
+	 * Send the browser to a route. Uses the host router when it is available so hooks and history
+	 * behave the same as any other navigation.
+	 *
+	 * @param {String} pRoute - the route to navigate to
+	 * @return {Boolean} whether a navigation was attempted
+	 */
+	navigate(pRoute)
+	{
+		const tmpRoute = libManifest.normalizeRoute(pRoute);
+		const tmpRouter = this.pictRouter;
+		if (tmpRouter && (typeof tmpRouter.navigate === 'function'))
+		{
+			tmpRouter.navigate(tmpRoute);
+			return true;
+		}
+		if ((typeof window !== 'undefined') && window.location)
+		{
+			window.location.hash = tmpRoute;
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Point a hash that matched no surviving route at the fallback, so a stale bookmark into a
+	 * screen this micro app does not carry lands somewhere real instead of on a blank page.
+	 *
+	 * @param {Object} [pPictRouter] - the router provider; defaults to the configured one
+	 * @return {Boolean} whether the handler was installed
+	 */
+	installNotFound(pPictRouter)
+	{
+		if (!this.manifest.Routes.CatchUnmatched)
+		{
+			return false;
+		}
+		const tmpRouter = pPictRouter || this.pictRouter;
+		// `router` is the underlying navigo instance the pict provider wraps.
+		if (!tmpRouter || !tmpRouter.router || (typeof tmpRouter.router.notFound !== 'function'))
+		{
+			return false;
+		}
+		tmpRouter.router.notFound(() =>
+		{
+			this.pict.log.trace(`MicroApp [${ this.manifest.Name }] unmatched route — routing to ${ this.manifest.Routes.Fallback }.`);
+			this.navigate(this.manifest.Routes.Fallback);
+		});
+		return true;
+	}
+
+	/**
+	 * Swap the host's navigation graph for the micro app's, and PIN it.
+	 *
+	 * Pinning is not paranoia. A host application of any size rebuilds its own navigation after the
+	 * fact — as configuration loads, as permissions resolve, as dynamically registered sections
+	 * appear — and each rebuild calls `setNavigationGraph` with the host's graph, silently undoing
+	 * the swap. The symptom is the worst kind: the micro app's menu is correct at first paint and
+	 * then quietly becomes the host's, usually after login, where nobody is looking.
+	 *
+	 * So rather than racing the host for the last write, the setter itself is wrapped: later calls
+	 * still re-normalize and re-render, they just always land on the micro app's sections.
+	 *
+	 * @param {Object} [pNavigationProvider] - the navigation provider; defaults to the configured one
+	 * @return {Boolean} whether the graph was swapped
+	 */
+	applyNavigationGraph(pNavigationProvider)
+	{
+		const tmpSections = this.manifest.Navigation.Sections;
+		if (!tmpSections || (tmpSections.length < 1))
+		{
+			return false;
+		}
+		const tmpProvider = pNavigationProvider || this.navigationProvider;
+		if (!tmpProvider || (typeof tmpProvider.setNavigationGraph !== 'function'))
+		{
+			this.pict.log.warn(`MicroApp [${ this.manifest.Name }] could not set the navigation graph: no navigation provider at '${ this.options.NavigationProviderHash }'.`);
+			return false;
+		}
+
+		if (this.manifest.Navigation.PinGraph && !tmpProvider._microAppGraphPinned)
+		{
+			const fSetNavigationGraph = tmpProvider.setNavigationGraph.bind(tmpProvider);
+			tmpProvider.setNavigationGraph = () => fSetNavigationGraph(tmpSections);
+			tmpProvider._microAppGraphPinned = true;
+		}
+
+		tmpProvider.setNavigationGraph(tmpSections);
+		return true;
+	}
+
+	/**
+	 * Install the micro app's navigation visibility gate.
+	 *
+	 * A host that serves many audiences usually trims its own (large) graph hard — the Headlight
+	 * platform app, for instance, shows platform super-users only the handful of cross-customer
+	 * destinations. Applied to a micro app graph, which is already the slimmed surface, that trim
+	 * empties the menu completely. So the default here keeps the host's real gates (session,
+	 * module, capability) and drops only the audience short-circuit.
+	 *
+	 * @param {Function} pHostPermitted - (pItem) => Boolean, the host's own per-item capability test
+	 * @param {Object} [pOptions] - { IsPrivileged: () => Boolean } to keep privileged sessions unfiltered
+	 * @return {Boolean} whether the gate was installed
+	 */
+	applyNavigationGate(pHostPermitted, pOptions)
+	{
+		const tmpProvider = this.navigationProvider;
+		if (!tmpProvider || (typeof tmpProvider.setGlobalFilter !== 'function'))
+		{
+			return false;
+		}
+		const tmpOptions = pOptions || {};
+		const tmpIsPrivileged = (typeof tmpOptions.IsPrivileged === 'function') ? tmpOptions.IsPrivileged : (() => false);
+		const tmpHonorHostGates = this.manifest.Navigation.HonorHostGates;
+		const tmpSuperUserSeesEverything = this.manifest.Navigation.SuperUserSeesEverything;
+
+		tmpProvider.setGlobalFilter((pItem, pCategory) =>
+		{
+			if (pItem.Hidden || (pCategory && pCategory.Hidden))
+			{
+				return false;
+			}
+			if (!tmpHonorHostGates)
+			{
+				return true;
+			}
+			// A privileged session holds no entitlements in the customer's own tenancy, so running
+			// it through the capability test would blank the menu a second way. Show it everything.
+			if (tmpSuperUserSeesEverything && tmpIsPrivileged())
+			{
+				return true;
+			}
+			return (typeof pHostPermitted === 'function') ? !!pHostPermitted(pItem, pCategory) : true;
+		});
+		return true;
+	}
+
+	/**
+	 * Point the host's routing provider at the micro app's landing route.
+	 *
+	 * @param {Object} pHostRouterProvider - the provider that owns `defaultRoute` (often a wrapper
+	 *        around pict-router rather than pict-router itself)
+	 * @return {Boolean} whether the landing route was set
+	 */
+	applyDefaultRoute(pHostRouterProvider)
+	{
+		if (!pHostRouterProvider)
+		{
+			return false;
+		}
+		// Hosts spell this without the leading slash (navigo's own convention for a default).
+		pHostRouterProvider.defaultRoute = this.manifest.DefaultRoute.replace(/^\//, '');
+		return true;
+	}
+
+	/**
+	 * Apply the manifest's branding to the document.
+	 *
+	 * @return {Boolean} whether a title was set
+	 */
+	applyBranding()
+	{
+		const tmpTitle = this.manifest.Branding.Title || this.manifest.Name;
+		if (!tmpTitle || (typeof document === 'undefined'))
+		{
+			return false;
+		}
+		document.title = tmpTitle;
+		return true;
+	}
+
+	/**
+	 * A one-line summary of what the gate did, for the console and for tests.
+	 *
+	 * @return {{Name: String, Allowed: Number, Guarded: Number, Blocked: Number}} the tally
+	 */
+	get routeTally()
+	{
+		return (
+			{
+				Name: this.manifest.Name,
+				Allowed: this.allowedRoutes.length,
+				Guarded: this.guardedRoutes.length,
+				Blocked: this.blockedRoutes.length
+			});
+	}
+}
+
+module.exports = PictMicroApp;
+module.exports.default_configuration = _DEFAULT_PROVIDER_CONFIGURATION;
+module.exports.Manifest = libManifest;
+module.exports.composeMicroApp = require('./Pict-MicroApp-Compose.js');

package/types/Pict-MicroApp-Compose.d.ts

@@ -0,0 +1,24 @@
+export = composeMicroApp;
+/**
+ * Build a micro app application class from a host application class and a manifest.
+ *
+ * @param {Function} pHostApplicationClass - the host pict application class to present a subset of
+ * @param {Object} pManifest - the micro app manifest (see Pict-MicroApp-Manifest.js)
+ * @param {Object} [pComposeOptions] - the host binding options above
+ * @return {Function} a class extending the host application class
+ */
+declare function composeMicroApp(pHostApplicationClass: Function, pManifest: any, pComposeOptions?: any): Function;
+declare namespace composeMicroApp {
+    export { _DEFAULT_COMPOSE_OPTIONS as default_compose_options };
+}
+declare namespace _DEFAULT_COMPOSE_OPTIONS {
+    let ProviderHash: string;
+    let RouterProviderHash: string;
+    let NavigationProviderHash: string;
+    let HostRouterProviderHash: string;
+    let AttachOn: string;
+    let NavigationGateMethod: string;
+    let HostPermittedMethod: string;
+    let IsPrivilegedMethod: string;
+}
+//# sourceMappingURL=Pict-MicroApp-Compose.d.ts.map

package/types/Pict-MicroApp-Compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pict-MicroApp-Compose.d.ts","sourceRoot":"","sources":["../source/Pict-MicroApp-Compose.js"],"names":[],"mappings":";AAqDA;;;;;;;GAOG;AACH,mHAoFC"}

package/types/Pict-MicroApp-Manifest.d.ts

@@ -0,0 +1,88 @@
+declare namespace _DEFAULT_MANIFEST {
+    let Name: string;
+    let Hash: string;
+    let DefaultRoute: string;
+    namespace Routes {
+        let Allow: any[];
+        let Deny: any[];
+        let EntityParameter: string;
+        let Entities: any[];
+        let GuardEntityRoutes: boolean;
+        let Fallback: string;
+        let CatchUnmatched: boolean;
+        let AlwaysAllow: string[];
+    }
+    namespace Navigation {
+        let Sections: any[];
+        let PinGraph: boolean;
+        let SuperUserSeesEverything: boolean;
+        let HonorHostGates: boolean;
+    }
+    namespace Branding {
+        let Title: string;
+        let LoginTitle: string;
+    }
+}
+/**
+ * Deep-ish merge of an author manifest over the defaults. Only the three known sub-objects are
+ * merged a level down; everything else is a straight overwrite.
+ *
+ * @param {Object} [pManifest] - the author's manifest
+ * @return {Object} a fully populated manifest
+ */
+export function normalizeManifest(pManifest?: any): any;
+/**
+ * Strip a route to the canonical form used for comparison: no leading '#', exactly one leading '/',
+ * no trailing '/' (except the bare root).
+ *
+ * @param {String} pRoute - a route pattern or hash
+ * @return {String} the canonical route pattern
+ */
+export function normalizeRoute(pRoute: string): string;
+/**
+ * Does a canonical route pattern match one allow/deny entry? An entry ending in '*' is a prefix
+ * glob; anything else is an exact pattern match (so '/Asset/Workspace/:ID' matches only the route
+ * registered with that exact parameter spelling).
+ *
+ * @param {String} pRoute - a canonical route pattern
+ * @param {String} pEntry - a canonical allow/deny entry
+ * @return {Boolean} whether the entry matches
+ */
+export function routeMatchesEntry(pRoute: string, pEntry: string): boolean;
+/**
+ * Does this route pattern fan out over the manifest's entity parameter (for example
+ * '/PSRS/:RecordSet/List' with an EntityParameter of 'RecordSet')?
+ *
+ * @param {String} pRoute - a canonical route pattern
+ * @param {String} pEntityParameter - the parameter name that names an entity
+ * @return {Boolean} whether the route is entity-parameterized
+ */
+export function routeIsEntityParameterized(pRoute: string, pEntityParameter: string): boolean;
+/**
+ * Decide what the gate should do with a route the host is trying to register.
+ *
+ * Returns one of three modes:
+ *   Allow — register it untouched.
+ *   Guard — register it, but wrap the handler so disallowed entities bounce to the fallback.
+ *   Block — do not register it at all.
+ *
+ * @param {Object} pManifest - a normalized manifest
+ * @param {String} pRoute - the route pattern the host passed to addRoute
+ * @return {{Mode: String, Route: String, Reason: String}} the decision
+ */
+export function decideRoute(pManifest: any, pRoute: string): {
+    Mode: string;
+    Route: string;
+    Reason: string;
+};
+/**
+ * Is an entity name exposed by this micro app? An empty Entities list means every entity is
+ * exposed (the manifest author did not want to constrain the record-set surface).
+ *
+ * @param {Object} pManifest - a normalized manifest
+ * @param {String} pEntity - the entity name resolved from the route
+ * @return {Boolean} whether the entity is exposed
+ */
+export function entityPermitted(pManifest: any, pEntity: string): boolean;
+export { _DEFAULT_MANIFEST as default_manifest };
+//# sourceMappingURL=Pict-MicroApp-Manifest.d.ts.map

package/types/Pict-MicroApp-Manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pict-MicroApp-Manifest.d.ts","sourceRoot":"","sources":["../source/Pict-MicroApp-Manifest.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqGA;;;;;;GAMG;AACH,wDAiBC;AAlDD;;;;;;GAMG;AACH,uDAiBC;AA4BD;;;;;;;;GAQG;AACH,2EAWC;AAED;;;;;;;GAOG;AACH,8FAOC;AAED;;;;;;;;;;;GAWG;AACH,6DAFY;IAAC,IAAI,SAAS;IAAC,KAAK,SAAS;IAAC,MAAM,SAAQ;CAAC,CA2CxD;AAED;;;;;;;GAOG;AACH,0EAQC"}