@herdingbits/trailhead-core 0.0.14 → 0.0.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/adapters/types.d.ts +31 -25
- package/dist/adapters/types.d.ts.map +1 -1
- package/dist/lib/http.js +1 -1
- package/dist/shell.d.ts +33 -6
- package/dist/shell.d.ts.map +1 -1
- package/dist/shell.js +34 -15
- package/dist/types/shell-api.d.ts +35 -30
- package/dist/types/shell-api.d.ts.map +1 -1
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -34,7 +34,8 @@ import { YourAdapter } from '@herdingbits/trailhead-your-design-system';
|
|
|
34
34
|
|
|
35
35
|
const shell = new Trailhead({
|
|
36
36
|
adapter: new YourAdapter(),
|
|
37
|
-
|
|
37
|
+
appBasePath: '/app', // URL prefix where SPAs are hosted
|
|
38
|
+
shellUrl: '/app', // URL where shell.js and navigation.json are served (defaults to appBasePath)
|
|
38
39
|
apiUrl: 'https://api.example.com'
|
|
39
40
|
});
|
|
40
41
|
```
|
package/dist/adapters/types.d.ts
CHANGED
|
@@ -3,60 +3,66 @@
|
|
|
3
3
|
*
|
|
4
4
|
* These interfaces define the contract between Trailhead core and design system implementations.
|
|
5
5
|
*/
|
|
6
|
+
/** Visual category of a toast notification, mapped to the adapter's colour/icon scheme. */
|
|
6
7
|
export type ToastVariant = "success" | "error" | "warning" | "info";
|
|
8
|
+
/**
|
|
9
|
+
* A button rendered inside a shell dialog.
|
|
10
|
+
*/
|
|
7
11
|
export interface DialogButton<T extends string = string> {
|
|
12
|
+
/** User-visible button text. */
|
|
8
13
|
label: string;
|
|
14
|
+
/** Value the dialog promise resolves to when this button is clicked. */
|
|
9
15
|
value: T;
|
|
16
|
+
/** Design-system-specific style variant (e.g., `"primary"`, `"danger"`). */
|
|
10
17
|
variant?: string;
|
|
11
18
|
}
|
|
19
|
+
/**
|
|
20
|
+
* Configuration passed to the adapter when the shell needs to display a modal dialog.
|
|
21
|
+
*/
|
|
12
22
|
export interface DialogConfig<T extends string = string> {
|
|
23
|
+
/** Body text displayed inside the dialog. */
|
|
13
24
|
message: string;
|
|
25
|
+
/** Dialog heading. */
|
|
14
26
|
title?: string;
|
|
27
|
+
/** Ordered list of buttons to render, left to right. */
|
|
15
28
|
buttons: DialogButton<T>[];
|
|
16
29
|
}
|
|
30
|
+
/**
|
|
31
|
+
* Value returned when a shell dialog closes.
|
|
32
|
+
* `null` when dismissed without clicking a button (e.g., clicking outside).
|
|
33
|
+
*/
|
|
17
34
|
export interface DialogResult<T extends string = string> {
|
|
18
35
|
value: T | null;
|
|
19
36
|
}
|
|
20
37
|
/**
|
|
21
|
-
*
|
|
38
|
+
* Implemented by adapters to supply shell feedback UI — busy overlays, toasts, and dialogs.
|
|
39
|
+
* Each adapter wires these methods to its own design system components.
|
|
22
40
|
*/
|
|
23
41
|
export interface FeedbackAdapter {
|
|
24
|
-
/**
|
|
25
|
-
* Show a busy overlay with a message
|
|
26
|
-
*/
|
|
42
|
+
/** Block the UI with a spinner and message while a long-running operation is in progress. */
|
|
27
43
|
showBusy(message: string): void;
|
|
28
|
-
/**
|
|
29
|
-
* Clear the busy overlay
|
|
30
|
-
*/
|
|
44
|
+
/** Dismiss the busy overlay once the operation completes. */
|
|
31
45
|
clearBusy(): void;
|
|
32
|
-
/**
|
|
33
|
-
* Show a toast notification
|
|
34
|
-
*/
|
|
46
|
+
/** Show a transient status notification that auto-dismisses after `duration` ms. */
|
|
35
47
|
showToast(message: string, variant: ToastVariant, duration?: number): void;
|
|
36
|
-
/**
|
|
37
|
-
* Show a dialog with custom buttons
|
|
38
|
-
*/
|
|
48
|
+
/** Render a modal dialog and resolve with whichever button the user clicked. */
|
|
39
49
|
showDialog<T extends string>(config: DialogConfig<T>): Promise<DialogResult<T>>;
|
|
40
50
|
}
|
|
41
51
|
/**
|
|
42
|
-
*
|
|
52
|
+
* The integration contract between Trailhead core and a specific design system.
|
|
53
|
+
* Implement this interface to support a new component library as the shell's UI layer.
|
|
43
54
|
*/
|
|
44
55
|
export interface DesignSystemAdapter {
|
|
45
|
-
/**
|
|
46
|
-
* Adapter name (e.g., "shoelace", "cloudscape")
|
|
47
|
-
*/
|
|
56
|
+
/** Identifier used in startup logs and diagnostics (e.g., `"shoelace"`, `"cloudscape"`). */
|
|
48
57
|
name: string;
|
|
49
|
-
/**
|
|
50
|
-
* Adapter version
|
|
51
|
-
*/
|
|
58
|
+
/** Adapter package version, logged at shell startup. */
|
|
52
59
|
version: string;
|
|
53
60
|
/**
|
|
54
|
-
*
|
|
55
|
-
|
|
56
|
-
init(basePath: string): Promise<void>;
|
|
57
|
-
/**
|
|
58
|
-
* Feedback adapter for user notifications
|
|
61
|
+
* Called once at shell startup. Register web component base paths,
|
|
62
|
+
* inject global stylesheets, or perform any other design-system-specific setup.
|
|
59
63
|
*/
|
|
64
|
+
init(shellUrl: string): Promise<void>;
|
|
65
|
+
/** Feedback implementation backed by this adapter's design system components. */
|
|
60
66
|
feedback: FeedbackAdapter;
|
|
61
67
|
}
|
|
62
68
|
//# sourceMappingURL=types.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACjB;AAED
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,EAAE,CAAC,CAAC;IACT,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,6DAA6D;IAC7D,SAAS,IAAI,IAAI,CAAC;IAElB,oFAAoF;IACpF,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3E,gFAAgF;IAChF,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CACjF;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC,iFAAiF;IACjF,QAAQ,EAAE,eAAe,CAAC;CAC3B"}
|
package/dist/lib/http.js
CHANGED
package/dist/shell.d.ts
CHANGED
|
@@ -3,22 +3,49 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import type { NavItem } from "./types/shell-api.js";
|
|
5
5
|
import type { DesignSystemAdapter } from "./adapters/types.js";
|
|
6
|
+
/**
|
|
7
|
+
* Configuration passed to the `Trailhead` constructor.
|
|
8
|
+
*/
|
|
6
9
|
export interface ShellConfig {
|
|
10
|
+
/** Design system adapter that backs all shell UI — toasts, dialogs, and busy overlays. */
|
|
7
11
|
adapter: DesignSystemAdapter;
|
|
8
|
-
|
|
12
|
+
/** URL prefix under which SPAs are hosted (e.g., `"/sample/trailhead"`). Used to strip the prefix from routes, construct SPA asset URLs, and build navigation links. */
|
|
13
|
+
appBasePath?: string;
|
|
14
|
+
/** Base URL prepended to all SPA HTTP requests made via `shell.http`. */
|
|
9
15
|
apiUrl?: string;
|
|
10
|
-
|
|
16
|
+
/** URL from which the shell bundle and static assets (e.g., `navigation.json`) are fetched. Defaults to `appBasePath`. */
|
|
17
|
+
shellUrl?: string;
|
|
11
18
|
}
|
|
19
|
+
/**
|
|
20
|
+
* The Trailhead shell. Bootstraps the micro-frontend host by loading navigation config,
|
|
21
|
+
* mounting SPAs on route activation, and exposing `window.shell` to every hosted application.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```typescript
|
|
25
|
+
* import { Trailhead } from '@herdingbits/trailhead-core';
|
|
26
|
+
* import { createAdapter } from '@herdingbits/trailhead-shoelace';
|
|
27
|
+
*
|
|
28
|
+
* new Trailhead({ adapter: createAdapter() });
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
12
31
|
export declare class Trailhead {
|
|
13
32
|
private navigation;
|
|
14
33
|
private routeChangeCallbacks;
|
|
15
|
-
|
|
16
|
-
|
|
34
|
+
/** URL prefix under which SPAs are hosted. Empty string when hosted at the root. */
|
|
35
|
+
readonly appBasePath: string;
|
|
36
|
+
private readonly shellUrl;
|
|
37
|
+
/** The active design system adapter supplying UI components to the shell. */
|
|
17
38
|
readonly adapter: DesignSystemAdapter;
|
|
39
|
+
/**
|
|
40
|
+
* Creates the shell and immediately begins async initialisation (adapter setup,
|
|
41
|
+
* navigation load, initial route handling). Mount errors are logged to the console.
|
|
42
|
+
*
|
|
43
|
+
* @param config - Shell configuration
|
|
44
|
+
*/
|
|
18
45
|
constructor(config: ShellConfig);
|
|
19
46
|
/**
|
|
20
|
-
*
|
|
21
|
-
*
|
|
47
|
+
* Returns the navigation items loaded from `navigation.json`.
|
|
48
|
+
* Adapters call this to render the shell's navigation menu.
|
|
22
49
|
*/
|
|
23
50
|
getNavigation(): NavItem[];
|
|
24
51
|
/**
|
package/dist/shell.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAY,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAI/D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAY,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,OAAO,EAAE,mBAAmB,CAAC;IAE7B,wKAAwK;IACxK,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0HAA0H;IAC1H,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,oBAAoB,CAAqC;IAEjE,oFAAoF;IACpF,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,6EAA6E;IAC7E,SAAgB,OAAO,EAAE,mBAAmB,CAAC;IAE7C;;;;;OAKG;gBACS,MAAM,EAAE,WAAW;IAO/B;;;OAGG;IACI,aAAa,IAAI,OAAO,EAAE;IAIjC;;OAEG;YACW,IAAI;IAwBlB;;OAEG;YACW,WAAW;IAUzB;;OAEG;IACH,OAAO,CAAC,SAAS;IAiFjB;;OAEG;YACW,cAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA6BxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,WAAW;IAsBnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;YACW,UAAU;CAqDzB"}
|
package/dist/shell.js
CHANGED
|
@@ -1,17 +1,35 @@
|
|
|
1
1
|
import * as http from "./lib/http.js";
|
|
2
2
|
import * as requestManager from "./lib/requestManager.js";
|
|
3
|
+
/**
|
|
4
|
+
* The Trailhead shell. Bootstraps the micro-frontend host by loading navigation config,
|
|
5
|
+
* mounting SPAs on route activation, and exposing `window.shell` to every hosted application.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { Trailhead } from '@herdingbits/trailhead-core';
|
|
10
|
+
* import { createAdapter } from '@herdingbits/trailhead-shoelace';
|
|
11
|
+
*
|
|
12
|
+
* new Trailhead({ adapter: createAdapter() });
|
|
13
|
+
* ```
|
|
14
|
+
*/
|
|
3
15
|
export class Trailhead {
|
|
16
|
+
/**
|
|
17
|
+
* Creates the shell and immediately begins async initialisation (adapter setup,
|
|
18
|
+
* navigation load, initial route handling). Mount errors are logged to the console.
|
|
19
|
+
*
|
|
20
|
+
* @param config - Shell configuration
|
|
21
|
+
*/
|
|
4
22
|
constructor(config) {
|
|
5
23
|
this.navigation = [];
|
|
6
24
|
this.routeChangeCallbacks = [];
|
|
7
|
-
this.
|
|
8
|
-
this.
|
|
25
|
+
this.appBasePath = config.appBasePath || "";
|
|
26
|
+
this.shellUrl = config.shellUrl || this.appBasePath;
|
|
9
27
|
this.adapter = config.adapter;
|
|
10
28
|
this.init(config.apiUrl);
|
|
11
29
|
}
|
|
12
30
|
/**
|
|
13
|
-
*
|
|
14
|
-
*
|
|
31
|
+
* Returns the navigation items loaded from `navigation.json`.
|
|
32
|
+
* Adapters call this to render the shell's navigation menu.
|
|
15
33
|
*/
|
|
16
34
|
getNavigation() {
|
|
17
35
|
return this.navigation;
|
|
@@ -41,7 +59,7 @@ export class Trailhead {
|
|
|
41
59
|
*/
|
|
42
60
|
async initAdapter() {
|
|
43
61
|
try {
|
|
44
|
-
await this.adapter.init(this.
|
|
62
|
+
await this.adapter.init(this.shellUrl);
|
|
45
63
|
console.log(`[Trailhead] Initialized ${this.adapter.name} adapter v${this.adapter.version}`);
|
|
46
64
|
}
|
|
47
65
|
catch (error) {
|
|
@@ -131,7 +149,7 @@ export class Trailhead {
|
|
|
131
149
|
*/
|
|
132
150
|
async loadNavigation() {
|
|
133
151
|
try {
|
|
134
|
-
const response = await fetch(`${this.
|
|
152
|
+
const response = await fetch(`${this.shellUrl}/navigation.json`);
|
|
135
153
|
this.navigation = await response.json();
|
|
136
154
|
}
|
|
137
155
|
catch (error) {
|
|
@@ -148,7 +166,7 @@ export class Trailhead {
|
|
|
148
166
|
return;
|
|
149
167
|
nav.innerHTML = this.navigation
|
|
150
168
|
.map((item) => `
|
|
151
|
-
<a href="${this.
|
|
169
|
+
<a href="${this.appBasePath}${item.path}"
|
|
152
170
|
class="shell-nav-item"
|
|
153
171
|
data-path="${item.path}"
|
|
154
172
|
data-app="${item.app}">
|
|
@@ -179,15 +197,15 @@ export class Trailhead {
|
|
|
179
197
|
* Navigate to path
|
|
180
198
|
*/
|
|
181
199
|
navigate(path) {
|
|
182
|
-
window.location.href = this.
|
|
200
|
+
window.location.href = this.appBasePath + path;
|
|
183
201
|
}
|
|
184
202
|
/**
|
|
185
203
|
* Handle route change
|
|
186
204
|
*/
|
|
187
205
|
handleRoute() {
|
|
188
206
|
let path = window.location.pathname;
|
|
189
|
-
if (this.
|
|
190
|
-
path = path.substring(this.
|
|
207
|
+
if (this.appBasePath && path.startsWith(this.appBasePath)) {
|
|
208
|
+
path = path.substring(this.appBasePath.length) || "/";
|
|
191
209
|
}
|
|
192
210
|
const navItem = this.navigation.find((item) => path.startsWith(item.path));
|
|
193
211
|
if (navItem) {
|
|
@@ -226,18 +244,19 @@ export class Trailhead {
|
|
|
226
244
|
return;
|
|
227
245
|
root.innerHTML = `<div class="shell-loading">Loading...</div>`;
|
|
228
246
|
const isDev = window.__SHELL_DEV__ === true;
|
|
247
|
+
const appBasePath = this.appBasePath + appPath;
|
|
229
248
|
try {
|
|
230
249
|
if (isDev) {
|
|
231
250
|
// ✅ DEV PATH — Vite-native, HMR-compatible
|
|
232
251
|
const mod = await import(
|
|
233
252
|
/* @vite-ignore */
|
|
234
|
-
`${this.
|
|
253
|
+
`${this.appBasePath}${appPath}/src/index.ts`);
|
|
235
254
|
root.innerHTML = "";
|
|
236
|
-
mod.AppMount(root);
|
|
255
|
+
mod.AppMount(root, appBasePath);
|
|
237
256
|
return;
|
|
238
257
|
}
|
|
239
|
-
const pluginUrl = `${this.
|
|
240
|
-
const pluginCss = `${this.
|
|
258
|
+
const pluginUrl = `${this.appBasePath}${appPath}/app.js`;
|
|
259
|
+
const pluginCss = `${this.appBasePath}${appPath}/${appName}.css`;
|
|
241
260
|
// Load CSS
|
|
242
261
|
const link = document.createElement("link");
|
|
243
262
|
link.rel = "stylesheet";
|
|
@@ -250,7 +269,7 @@ export class Trailhead {
|
|
|
250
269
|
script.onload = () => {
|
|
251
270
|
root.innerHTML = "";
|
|
252
271
|
if (window.AppMount) {
|
|
253
|
-
window.AppMount(root);
|
|
272
|
+
window.AppMount(root, appBasePath);
|
|
254
273
|
}
|
|
255
274
|
};
|
|
256
275
|
script.onerror = () => {
|
|
@@ -60,16 +60,27 @@ export type ShellPlugin = {
|
|
|
60
60
|
/**
|
|
61
61
|
* Mounts the application into a DOM element provided by the Shell.
|
|
62
62
|
*
|
|
63
|
-
* This function is responsible for rendering the application UI
|
|
64
|
-
* into the given container element.
|
|
65
|
-
*
|
|
66
63
|
* The Shell guarantees that:
|
|
67
64
|
* - `root` is an empty, attached DOM element
|
|
68
65
|
* - The application owns the DOM subtree beneath `root`
|
|
69
66
|
*
|
|
70
67
|
* @param root - Container element into which the application should render.
|
|
68
|
+
* @param basePath - Full URL prefix under which this SPA is mounted (e.g. `"/trailhead/apps/mailmerge"`).
|
|
69
|
+
* Pass this as `basename` to your client-side router so internal links and default redirects
|
|
70
|
+
* resolve correctly when the shell is hosted under a subpath.
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* ```ts
|
|
74
|
+
* export function AppMount(root: HTMLElement, basePath: string) {
|
|
75
|
+
* ReactDOM.createRoot(root).render(
|
|
76
|
+
* <BrowserRouter basename={basePath}>
|
|
77
|
+
* <App />
|
|
78
|
+
* </BrowserRouter>
|
|
79
|
+
* );
|
|
80
|
+
* }
|
|
81
|
+
* ```
|
|
71
82
|
*/
|
|
72
|
-
AppMount(root: HTMLElement): void;
|
|
83
|
+
AppMount(root: HTMLElement, basePath: string): void;
|
|
73
84
|
};
|
|
74
85
|
/**
|
|
75
86
|
* Feedback system API
|
|
@@ -349,56 +360,51 @@ export interface RequestOptions {
|
|
|
349
360
|
headers?: Record<string, string>;
|
|
350
361
|
}
|
|
351
362
|
/**
|
|
352
|
-
* Successful HTTP response
|
|
363
|
+
* Successful HTTP response — narrows `Result<T>` when `success` is `true`.
|
|
353
364
|
*/
|
|
354
365
|
export interface SuccessResult<T> {
|
|
355
|
-
/** Always true for successful responses */
|
|
356
366
|
success: true;
|
|
357
|
-
/**
|
|
367
|
+
/** Parsed JSON response body. */
|
|
358
368
|
data: T;
|
|
359
|
-
/**
|
|
369
|
+
/** Echo of the `requestKey` from `RequestOptions`, if supplied. */
|
|
360
370
|
requestKey?: string;
|
|
361
371
|
}
|
|
362
372
|
/**
|
|
363
|
-
* Failed HTTP response
|
|
373
|
+
* Failed HTTP response — narrows `Result<T>` when `success` is `false`.
|
|
364
374
|
*/
|
|
365
375
|
export interface ErrorResult {
|
|
366
|
-
/** Always false for error responses */
|
|
367
376
|
success: false;
|
|
368
|
-
/** Error details */
|
|
369
377
|
error: HttpError;
|
|
370
|
-
/**
|
|
378
|
+
/** Echo of the `requestKey` from `RequestOptions`, if supplied. */
|
|
371
379
|
requestKey?: string;
|
|
372
380
|
}
|
|
373
381
|
/**
|
|
374
|
-
* Discriminated union
|
|
375
|
-
*
|
|
382
|
+
* Discriminated union returned by all `shell.http` methods.
|
|
383
|
+
* Branch on `result.success` to get type-safe access to `data` or `error`.
|
|
376
384
|
*
|
|
377
385
|
* @example
|
|
378
386
|
* ```typescript
|
|
379
387
|
* const result = await shell.http.get('/api/data');
|
|
380
388
|
*
|
|
381
389
|
* if (result.success) {
|
|
382
|
-
* // TypeScript knows result.data exists
|
|
383
390
|
* console.log(result.data);
|
|
384
391
|
* } else {
|
|
385
|
-
* // TypeScript knows result.error exists
|
|
386
392
|
* console.error(result.error.message);
|
|
387
393
|
* }
|
|
388
394
|
* ```
|
|
389
395
|
*/
|
|
390
396
|
export type Result<T> = SuccessResult<T> | ErrorResult;
|
|
391
397
|
/**
|
|
392
|
-
* HTTP error
|
|
398
|
+
* Details of a failed HTTP request, normalised from the underlying ky error.
|
|
393
399
|
*/
|
|
394
400
|
export interface HttpError {
|
|
395
|
-
/** Error name (e.g., "HTTPError"
|
|
401
|
+
/** Error class name (e.g., `"HTTPError"`, `"TimeoutError"`). */
|
|
396
402
|
name: string;
|
|
397
|
-
/** Human-readable
|
|
403
|
+
/** Human-readable description, extracted from the server response body when available. */
|
|
398
404
|
message: string;
|
|
399
|
-
/** HTTP status code
|
|
405
|
+
/** HTTP status code, present when the server replied (absent for network errors). */
|
|
400
406
|
status?: number;
|
|
401
|
-
/**
|
|
407
|
+
/** Parsed server response body, when the error response was valid JSON. */
|
|
402
408
|
data?: any;
|
|
403
409
|
}
|
|
404
410
|
/**
|
|
@@ -447,19 +453,18 @@ export interface NavigationAPI {
|
|
|
447
453
|
* Defines a navigation menu item in `navigation.json`.
|
|
448
454
|
*/
|
|
449
455
|
export interface NavItem {
|
|
450
|
-
/**
|
|
456
|
+
/** Stable key used to match active nav state and correlate items across reloads. */
|
|
451
457
|
id: string;
|
|
452
|
-
/**
|
|
458
|
+
/** Route path this item activates (e.g., `"/demo"`). Must match the SPA's base route. */
|
|
453
459
|
path: string;
|
|
454
|
-
/** SPA
|
|
460
|
+
/** SPA directory name; the shell resolves `<basePath>/<app>/app.js` when this route is activated. */
|
|
455
461
|
app: string;
|
|
456
|
-
/** Icon
|
|
462
|
+
/** Icon identifier passed to the adapter's icon component. Naming convention is design-system-specific. */
|
|
457
463
|
icon: string;
|
|
458
|
-
/** Display label for the navigation item */
|
|
459
464
|
label: string;
|
|
460
|
-
/**
|
|
465
|
+
/** Lower numbers appear earlier in the menu. */
|
|
461
466
|
order: number;
|
|
462
|
-
/**
|
|
467
|
+
/** Called on each render to get a live count shown as a badge on the nav item (e.g., unread notifications). */
|
|
463
468
|
badge?: () => number;
|
|
464
469
|
}
|
|
465
470
|
/**
|
|
@@ -471,8 +476,8 @@ declare global {
|
|
|
471
476
|
interface Window {
|
|
472
477
|
/** Trailhead shell API available to all SPAs */
|
|
473
478
|
shell: ShellAPI;
|
|
474
|
-
/**
|
|
475
|
-
AppMount?: (
|
|
479
|
+
/** @see {@link ShellPlugin.AppMount} */
|
|
480
|
+
AppMount?: (root: HTMLElement, basePath: string) => void;
|
|
476
481
|
}
|
|
477
482
|
}
|
|
478
483
|
//# sourceMappingURL=shell-api.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"shell-api.d.ts","sourceRoot":"","sources":["../../src/types/shell-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,mEAAmE;IACnE,QAAQ,EAAE,WAAW,CAAC;IAEtB,uEAAuE;IACvE,IAAI,EAAE,OAAO,CAAC;IAEd,uCAAuC;IACvC,UAAU,EAAE,aAAa,CAAC;CAC3B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB
|
|
1
|
+
{"version":3,"file":"shell-api.d.ts","sourceRoot":"","sources":["../../src/types/shell-api.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@herdingbits/trailhead-core",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.16",
|
|
4
4
|
"description": "Simple application shell that orchestrates multiple SPAs. No webpack magic, just the browser's native module system.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -16,17 +16,17 @@
|
|
|
16
16
|
"README.md"
|
|
17
17
|
],
|
|
18
18
|
"scripts": {
|
|
19
|
-
"clean": "rm -rf dist ../types/*.d.ts ../types/adapters",
|
|
19
|
+
"clean": "rm -rf dist ../types/*.d.ts ../types/*.map ../types/adapters",
|
|
20
20
|
"build": "npm run clean && tsc && npm run build:types",
|
|
21
|
-
"build:types": "tsc
|
|
21
|
+
"build:types": "tsc -p tsconfig.types.json && tsc -p tsconfig.adapters.json",
|
|
22
22
|
"test": "vitest"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"ky": "^
|
|
25
|
+
"ky": "^2.0.2"
|
|
26
26
|
},
|
|
27
27
|
"devDependencies": {
|
|
28
|
-
"typescript": "^
|
|
29
|
-
"vitest": "^4.
|
|
28
|
+
"typescript": "^6.0.3",
|
|
29
|
+
"vitest": "^4.1.6"
|
|
30
30
|
},
|
|
31
31
|
"keywords": [
|
|
32
32
|
"micro-frontend",
|