@herdingbits/trailhead-types 0.0.1

package/README.md

@@ -0,0 +1,36 @@
+# @herdingbits/trailhead-types
+
+TypeScript type definitions for the Trailhead micro-frontend framework.
+
+**Note:** This package is auto-generated from `@herdingbits/trailhead-core` during build. Do not edit these files directly.
+
+## Installation
+
+```bash
+npm install --save-dev @herdingbits/trailhead-types
+```
+
+## Usage
+
+```typescript
+import type { ShellAPI } from '@herdingbits/trailhead-types';
+import type { DesignSystemAdapter } from '@herdingbits/trailhead-types/adapters';
+
+// Use in your SPA apps
+export function init(shell: ShellAPI) {
+  shell.feedback.success('App loaded!');
+}
+
+// Use when creating custom adapters
+export class MyAdapter implements DesignSystemAdapter {
+  // ...
+}
+```
+
+## Documentation
+
+See the [main Trailhead documentation](https://github.com/herdingbits/trailhead) for more information.
+
+## License
+
+MIT

package/adapters/public-api.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Public Adapter API - For creating custom design system adapters
+ */
+export type { DesignSystemAdapter, FeedbackAdapter, ToastVariant, DialogButton, DialogConfig, DialogResult, } from './types.js';

package/adapters/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Design System Adapter Interfaces
+ *
+ * These interfaces define the contract between Trailhead core and design system implementations.
+ */
+export type ToastVariant = "success" | "error" | "warning" | "info";
+export interface DialogButton<T extends string = string> {
+    label: string;
+    value: T;
+    variant?: string;
+}
+export interface DialogConfig<T extends string = string> {
+    message: string;
+    title?: string;
+    buttons: DialogButton<T>[];
+}
+export interface DialogResult<T extends string = string> {
+    value: T | null;
+}
+/**
+ * Feedback Adapter - Handles user feedback (toasts, dialogs, busy states)
+ */
+export interface FeedbackAdapter {
+    /**
+     * Show a busy overlay with a message
+     */
+    showBusy(message: string): void;
+    /**
+     * Clear the busy overlay
+     */
+    clearBusy(): void;
+    /**
+     * Show a toast notification
+     */
+    showToast(message: string, variant: ToastVariant, duration?: number): void;
+    /**
+     * Show a dialog with custom buttons
+     */
+    showDialog<T extends string>(config: DialogConfig<T>): Promise<DialogResult<T>>;
+}
+/**
+ * Design System Adapter - Main adapter interface
+ */
+export interface DesignSystemAdapter {
+    /**
+     * Adapter name (e.g., "shoelace", "cloudscape")
+     */
+    name: string;
+    /**
+     * Adapter version
+     */
+    version: string;
+    /**
+     * Initialize the design system (load assets, set base paths, etc.)
+     */
+    init(basePath: string): Promise<void>;
+    /**
+     * Feedback adapter for user notifications
+     */
+    feedback: FeedbackAdapter;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@herdingbits/trailhead-types",
+  "version": "0.0.1",
+  "description": "TypeScript type definitions for Trailhead micro-frontend framework",
+  "type": "module",
+  "types": "./public-api.d.ts",
+  "exports": {
+    ".": {
+      "types": "./public-api.d.ts"
+    },
+    "./adapters": {
+      "types": "./adapters/public-api.d.ts"
+    }
+  },
+  "files": [
+    "*.d.ts",
+    "adapters/*.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "micro-frontend",
+    "types",
+    "typescript",
+    "trailhead"
+  ],
+  "author": "HerdingBits",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/herdingbits/trailhead.git",
+    "directory": "packages/types"
+  }
+}

package/public-api.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Public Shell API - Only these types are exposed to plugin applications
+ * This file explicitly defines what's public vs internal
+ */
+export type { ShellAPI, FeedbackAPI, AlertVariant, HttpAPI, RequestOptions, Result, SuccessResult, ErrorResult, HttpError, NavigationAPI, NavItem, } from './shell-api.js';

package/shell-api.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Shell API Interface
+ * Exposed to plugin applications via window.shell
+ */
+export interface ShellAPI {
+    version: string;
+    feedback: FeedbackAPI;
+    http: HttpAPI;
+    navigation: NavigationAPI;
+}
+/**
+ * Feedback system API
+ */
+export interface FeedbackAPI {
+    busy(message: string): void;
+    clear(): void;
+    success(message: string, duration?: number): void;
+    error(message: string, duration?: number): void;
+    warning(message: string, duration?: number): void;
+    info(message: string, duration?: number): void;
+    alert(message: string, variant?: AlertVariant, duration?: number): void;
+    confirm(message: string, title?: string): Promise<boolean>;
+    ok(message: string, title?: string): Promise<void>;
+    yesNo(message: string, title?: string): Promise<boolean>;
+    yesNoCancel(message: string, title?: string): Promise<"yes" | "no" | "cancel">;
+    custom<T extends string>(message: string, title: string, buttons: Array<{
+        label: string;
+        value: T;
+        variant?: string;
+    }>): Promise<T | null>;
+}
+export type AlertVariant = "success" | "error" | "warning" | "info";
+/**
+ * HTTP client API with automatic feedback orchestration
+ */
+export interface HttpAPI {
+    get<T = any>(url: string, options?: RequestOptions): Promise<Result<T>>;
+    post<T = any>(url: string, data?: any, options?: RequestOptions): Promise<Result<T>>;
+    put<T = any>(url: string, data?: any, options?: RequestOptions): Promise<Result<T>>;
+    patch<T = any>(url: string, data?: any, options?: RequestOptions): Promise<Result<T>>;
+    delete<T = any>(url: string, options?: RequestOptions): Promise<Result<T>>;
+}
+export interface RequestOptions {
+    requestKey?: string;
+    busyMessage?: string;
+    successMessage?: string;
+    showSuccess?: boolean;
+    noFeedback?: boolean;
+    headers?: Record<string, string>;
+}
+export interface SuccessResult<T> {
+    success: true;
+    data: T;
+    requestKey?: string;
+}
+export interface ErrorResult {
+    success: false;
+    error: HttpError;
+    requestKey?: string;
+}
+export type Result<T> = SuccessResult<T> | ErrorResult;
+export interface HttpError {
+    name: string;
+    message: string;
+    status?: number;
+    data?: any;
+}
+/**
+ * Navigation API
+ */
+export interface NavigationAPI {
+    navigate(path: string): void;
+    getCurrentPath(): string;
+    onRouteChange(callback: (path: string) => void): () => void;
+}
+/**
+ * Navigation configuration
+ */
+export interface NavItem {
+    id: string;
+    path: string;
+    app: string;
+    icon: string;
+    label: string;
+    order: number;
+    badge?: () => number;
+}
+/**
+ * Global window extension
+ */
+declare global {
+    interface Window {
+        shell: ShellAPI;
+        AppMount?: (container: HTMLElement) => void;
+    }
+}