@hamak/ui-shell-api 0.1.0

package/dist/types/layout-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Layout Types
+ * Type definitions for layout and responsive design
+ */
+export type LayoutArea = 'header' | 'sidebar' | 'main' | 'footer' | 'overlay';
+export interface LayoutSlot {
+    /** Slot identifier */
+    id: string;
+    /** Slot position/area */
+    area: LayoutArea;
+    /** Slot priority for ordering */
+    priority?: number;
+    /** Optional metadata */
+    meta?: Record<string, any>;
+}
+export interface ViewportInfo {
+    width: number;
+    height: number;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+}
+export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export interface Breakpoint {
+    name: BreakpointName;
+    minWidth: number;
+    maxWidth?: number;
+}
+//# sourceMappingURL=layout-types.d.ts.map

package/dist/types/layout-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-types.d.ts","sourceRoot":"","sources":["../../src/types/layout-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/layout-types.js

@@ -0,0 +1,5 @@
+/**
+ * Layout Types
+ * Type definitions for layout and responsive design
+ */
+export {};

package/dist/types/route-types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Route Types
+ * Type definitions for routing
+ */
+export interface RouteConfig {
+    path: string;
+    /** Lazy-loaded component factory */
+    component: () => Promise<any>;
+    /** Route metadata */
+    meta?: Record<string, any>;
+    /** Child routes */
+    children?: RouteConfig[];
+    /** Route guards */
+    beforeEnter?: (to: RouteConfig, from: RouteConfig) => boolean | Promise<boolean>;
+}
+export type RouterMode = 'history' | 'hash' | 'memory';
+export interface RouterOptions {
+    routes: RouteConfig[];
+    mode?: RouterMode;
+    base?: string;
+}
+//# sourceMappingURL=route-types.d.ts.map

package/dist/types/route-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-types.d.ts","sourceRoot":"","sources":["../../src/types/route-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,mBAAmB;IACnB,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClF;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/types/route-types.js

@@ -0,0 +1,5 @@
+/**
+ * Route Types
+ * Type definitions for routing
+ */
+export {};

package/dist/types/shell-context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shell Context Types
+ * Type definitions for shell context
+ */
+import type { ThemeMode, ThemeConfig } from './theme-types';
+import type { FeatureFlags } from './feature-types';
+import type { ViewportInfo } from './layout-types';
+export interface ShellConfig {
+    /** Theme configuration */
+    theme?: ThemeConfig;
+    /** Feature flags and experimental configurations */
+    features?: FeatureFlags;
+    /** Enable server-side rendering */
+    ssr?: boolean;
+    /** Enable streaming rendering */
+    streaming?: boolean;
+    /** Custom shell metadata */
+    metadata?: Record<string, any>;
+}
+export interface ShellContext {
+    /** Current theme mode */
+    theme: ThemeMode;
+    /** Set theme mode */
+    setTheme: (mode: ThemeMode) => void;
+    /** Feature flags */
+    features: FeatureFlags;
+    /** Check if a feature is enabled */
+    isFeatureEnabled: (key: string) => boolean;
+    /** Get feature value */
+    getFeature: <T = any>(key: string, defaultValue?: T) => T;
+    /** Current viewport size */
+    viewport: ViewportInfo;
+}
+//# sourceMappingURL=shell-context.d.ts.map

package/dist/types/shell-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-context.d.ts","sourceRoot":"","sources":["../../src/types/shell-context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mCAAmC;IACnC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iCAAiC;IACjC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,qBAAqB;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACpC,oBAAoB;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,oCAAoC;IACpC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,wBAAwB;IACxB,UAAU,EAAE,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAC1D,4BAA4B;IAC5B,QAAQ,EAAE,YAAY,CAAC;CACxB"}

package/dist/types/shell-context.js

@@ -0,0 +1,5 @@
+/**
+ * Shell Context Types
+ * Type definitions for shell context
+ */
+export {};

package/dist/types/theme-types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Theme Types
+ * Type definitions for theme management
+ */
+export type ThemeMode = 'light' | 'dark' | 'system';
+export interface ThemeConfig {
+    mode: ThemeMode;
+    /** Primary color scheme */
+    primaryColor?: string;
+    /** Custom CSS variables */
+    cssVariables?: Record<string, string>;
+}
+//# sourceMappingURL=theme-types.d.ts.map

package/dist/types/theme-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-types.d.ts","sourceRoot":"","sources":["../../src/types/theme-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC"}

package/dist/types/theme-types.js

@@ -0,0 +1,5 @@
+/**
+ * Theme Types
+ * Type definitions for theme management
+ */
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hamak/ui-shell-api",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "UI Shell API - Core UI shell interfaces",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/ui-shell/ui-shell-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "~5.4.0"
+  }
+}

package/src/api/IFeatureManager.ts

@@ -0,0 +1,68 @@
+/**
+ * Feature Manager Interface
+ * Public API contract for feature flag management
+ */
+
+import type { FeatureFlags } from '../types';
+
+export interface IFeatureManager {
+  /**
+   * Check if a feature is enabled (boolean features)
+   */
+  isEnabled(key: string): boolean;
+
+  /**
+   * Get a feature value with optional default
+   */
+  get<T = any>(key: string, defaultValue?: T): T;
+
+  /**
+   * Set a feature value
+   */
+  set(key: string, value: any): void;
+
+  /**
+   * Enable a feature (set to true)
+   */
+  enable(key: string): void;
+
+  /**
+   * Disable a feature (set to false)
+   */
+  disable(key: string): void;
+
+  /**
+   * Toggle a boolean feature
+   */
+  toggle(key: string): void;
+
+  /**
+   * Update multiple features at once
+   */
+  update(updates: FeatureFlags): void;
+
+  /**
+   * Get all features
+   */
+  getAll(): Readonly<FeatureFlags>;
+
+  /**
+   * Check if a feature exists
+   */
+  has(key: string): boolean;
+
+  /**
+   * Subscribe to feature changes
+   */
+  subscribe(key: string, listener: (value: any) => void): () => void;
+
+  /**
+   * Subscribe to all feature changes
+   */
+  subscribeAll(listener: (key: string, value: any) => void): () => void;
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void;
+}

package/src/api/ILayoutManager.ts

@@ -0,0 +1,48 @@
+/**
+ * Layout Manager Interface
+ * Public API contract for layout management
+ */
+
+import type { LayoutSlot, LayoutArea } from '../types';
+
+export interface ILayoutManager {
+  /**
+   * Register a layout slot
+   */
+  registerSlot(slot: LayoutSlot): () => void;
+
+  /**
+   * Unregister a layout slot
+   */
+  unregisterSlot(slot: LayoutSlot): void;
+
+  /**
+   * Get all slots for an area
+   */
+  getSlots(area: LayoutArea): LayoutSlot[];
+
+  /**
+   * Get all registered areas
+   */
+  getAreas(): LayoutArea[];
+
+  /**
+   * Check if an area has any slots
+   */
+  hasSlots(area: LayoutArea): boolean;
+
+  /**
+   * Subscribe to layout changes
+   */
+  subscribe(listener: () => void): () => void;
+
+  /**
+   * Clear all slots
+   */
+  clear(): void;
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void;
+}

package/src/api/IRouter.ts

@@ -0,0 +1,48 @@
+/**
+ * Router Interface
+ * Public API contract for routing
+ */
+
+import type { RouteConfig } from '../types';
+
+export interface IRouter {
+  /**
+   * Navigate to a path
+   */
+  push(path: string): Promise<boolean>;
+
+  /**
+   * Replace current route
+   */
+  replace(path: string): Promise<boolean>;
+
+  /**
+   * Go back in history
+   */
+  back(): void;
+
+  /**
+   * Go forward in history
+   */
+  forward(): void;
+
+  /**
+   * Get current route
+   */
+  getCurrentRoute(): RouteConfig | null;
+
+  /**
+   * Subscribe to route changes
+   */
+  subscribe(listener: (route: RouteConfig) => void): () => void;
+
+  /**
+   * Load a route component (lazy loading)
+   */
+  loadRouteComponent(route: RouteConfig): Promise<any>;
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void;
+}

package/src/api/IShell.ts

@@ -0,0 +1,66 @@
+/**
+ * Shell Interface
+ * Public API contract for the UI Shell
+ */
+
+import type { ShellConfig, ShellContext, ShellEvent, ShellEventListener, ShellEventType } from '../types';
+import type { IThemeManager } from './IThemeManager';
+import type { IFeatureManager } from './IFeatureManager';
+import type { IRouter } from './IRouter';
+
+export interface IShell {
+  /**
+   * Initialize the shell
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get shell context for consumers
+   */
+  getContext(): ShellContext;
+
+  /**
+   * Get theme manager
+   */
+  getThemeManager(): IThemeManager;
+
+  /**
+   * Get feature manager
+   */
+  getFeatureManager(): IFeatureManager;
+
+  /**
+   * Get router instance
+   */
+  getRouter(): IRouter | null;
+
+  /**
+   * Emit a shell event
+   */
+  emit(type: ShellEventType, payload?: any): void;
+
+  /**
+   * Subscribe to shell events
+   */
+  on(type: ShellEventType | '*', listener: ShellEventListener): () => void;
+
+  /**
+   * Unsubscribe from shell events
+   */
+  off(type: ShellEventType | '*', listener: ShellEventListener): void;
+
+  /**
+   * Check if shell is ready
+   */
+  ready(): boolean;
+
+  /**
+   * Get configuration
+   */
+  getConfig(): Readonly<ShellConfig>;
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void;
+}

package/src/api/IThemeManager.ts

@@ -0,0 +1,43 @@
+/**
+ * Theme Manager Interface
+ * Public API contract for theme management
+ */
+
+import type { ThemeMode } from '../types';
+
+export interface IThemeManager {
+  /**
+   * Get the current theme mode
+   */
+  getTheme(): ThemeMode;
+
+  /**
+   * Get the resolved theme (converts 'system' to actual theme)
+   */
+  getResolvedTheme(): 'light' | 'dark';
+
+  /**
+   * Set the theme mode
+   */
+  setTheme(mode: ThemeMode): void;
+
+  /**
+   * Toggle between light and dark themes
+   */
+  toggleTheme(): void;
+
+  /**
+   * Subscribe to theme changes
+   */
+  subscribe(listener: (theme: ThemeMode) => void): () => void;
+
+  /**
+   * Apply custom CSS variables
+   */
+  setCSSVariables(variables: Record<string, string>): void;
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void;
+}

package/src/api/index.ts

@@ -0,0 +1,10 @@
+/**
+ * UI Shell API Interfaces
+ * All public interface definitions
+ */
+
+export * from './IShell';
+export * from './IThemeManager';
+export * from './IFeatureManager';
+export * from './IRouter';
+export * from './ILayoutManager';

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * UI Shell API
+ * Public API surface for the UI Shell framework
+ *
+ * This package contains only type definitions and interfaces.
+ * Import implementations from @amk/ui-shell-impl
+ */
+
+export const version = '0.1.0';
+
+// Export all types
+export * from './types';
+
+// Export all API interfaces
+export * from './api';
+
+// Export service tokens
+export * from './tokens';

package/src/tokens/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Tokens
+ * Export all service tokens
+ */
+
+export * from './service-tokens';

package/src/tokens/service-tokens.ts

@@ -0,0 +1,64 @@
+/**
+ * Service Tokens
+ * Dependency injection tokens for shell services
+ */
+
+/**
+ * Token for Shell service
+ */
+export const SHELL_TOKEN = Symbol('Shell');
+
+/**
+ * Token for ThemeManager service
+ */
+export const THEME_MANAGER_TOKEN = Symbol('ThemeManager');
+
+/**
+ * Token for FeatureManager service
+ */
+export const FEATURE_MANAGER_TOKEN = Symbol('FeatureManager');
+
+/**
+ * Token for Router service
+ */
+export const ROUTER_TOKEN = Symbol('Router');
+
+/**
+ * Token for LayoutManager service
+ */
+export const LAYOUT_MANAGER_TOKEN = Symbol('LayoutManager');
+
+/**
+ * Shell command names
+ */
+export const ShellCommands = {
+  SET_THEME: 'shell.setTheme',
+  TOGGLE_THEME: 'shell.toggleTheme',
+  ENABLE_FEATURE: 'shell.enableFeature',
+  DISABLE_FEATURE: 'shell.disableFeature',
+  TOGGLE_FEATURE: 'shell.toggleFeature',
+  NAVIGATE: 'shell.navigate',
+  NAVIGATE_BACK: 'shell.navigateBack',
+} as const;
+
+/**
+ * Shell event names
+ */
+export const ShellEvents = {
+  READY: 'shell:ready',
+  THEME_CHANGED: 'shell:theme-changed',
+  FEATURE_TOGGLED: 'shell:feature-toggled',
+  ROUTE_CHANGED: 'shell:route-changed',
+  VIEWPORT_RESIZED: 'shell:viewport-resized',
+} as const;
+
+/**
+ * Shell view slot names
+ */
+export const ShellViewSlots = {
+  HEADER: 'shell.header',
+  SIDEBAR: 'shell.sidebar',
+  MAIN: 'shell.main',
+  FOOTER: 'shell.footer',
+  OVERLAY: 'shell.overlay',
+} as const;

package/src/types/event-types.ts

@@ -0,0 +1,22 @@
+/**
+ * Event Types
+ * Type definitions for shell events
+ */
+
+export type ShellEventType =
+  | 'theme:changed'
+  | 'feature:toggled'
+  | 'route:changed'
+  | 'viewport:resized'
+  | 'shell:ready'
+  | 'shell:error';
+
+export interface ShellEvent {
+  type: string;
+  payload?: any;
+  timestamp: number;
+}
+
+export interface ShellEventListener {
+  (event: ShellEvent): void;
+}

package/src/types/feature-types.ts

@@ -0,0 +1,34 @@
+/**
+ * Feature Types
+ * Type definitions for feature flag management
+ */
+
+export interface FeatureFlags {
+  [key: string]: boolean | string | number | object;
+}
+
+/**
+ * Common feature flag definitions
+ */
+export const CommonFeatures = {
+  // UI Features
+  DARK_MODE: 'ui.darkMode',
+  SIDEBAR: 'ui.sidebar',
+  MOBILE_NAV: 'ui.mobileNav',
+  BREADCRUMBS: 'ui.breadcrumbs',
+
+  // Experimental Features
+  SSR: 'experimental.ssr',
+  STREAMING: 'experimental.streaming',
+  LAZY_LOADING: 'experimental.lazyLoading',
+
+  // User Features
+  VOICE_MODE: 'user.voiceMode',
+  ADVANCED_COMPOSER: 'user.advancedComposer',
+  UPGRADE_PILLS: 'user.upgradePills',
+
+  // Performance Features
+  REQUEST_RETRY: 'performance.requestRetry',
+  POLLING: 'performance.polling',
+  CACHE: 'performance.cache',
+} as const;

package/src/types/index.ts

@@ -0,0 +1,11 @@
+/**
+ * UI Shell API Types
+ * All public type definitions
+ */
+
+export * from './theme-types';
+export * from './feature-types';
+export * from './route-types';
+export * from './layout-types';
+export * from './event-types';
+export * from './shell-context';

package/src/types/layout-types.ts

@@ -0,0 +1,33 @@
+/**
+ * Layout Types
+ * Type definitions for layout and responsive design
+ */
+
+export type LayoutArea = 'header' | 'sidebar' | 'main' | 'footer' | 'overlay';
+
+export interface LayoutSlot {
+  /** Slot identifier */
+  id: string;
+  /** Slot position/area */
+  area: LayoutArea;
+  /** Slot priority for ordering */
+  priority?: number;
+  /** Optional metadata */
+  meta?: Record<string, any>;
+}
+
+export interface ViewportInfo {
+  width: number;
+  height: number;
+  isMobile: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+}
+
+export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export interface Breakpoint {
+  name: BreakpointName;
+  minWidth: number;
+  maxWidth?: number;
+}

package/src/types/route-types.ts

@@ -0,0 +1,24 @@
+/**
+ * Route Types
+ * Type definitions for routing
+ */
+
+export interface RouteConfig {
+  path: string;
+  /** Lazy-loaded component factory */
+  component: () => Promise<any>;
+  /** Route metadata */
+  meta?: Record<string, any>;
+  /** Child routes */
+  children?: RouteConfig[];
+  /** Route guards */
+  beforeEnter?: (to: RouteConfig, from: RouteConfig) => boolean | Promise<boolean>;
+}
+
+export type RouterMode = 'history' | 'hash' | 'memory';
+
+export interface RouterOptions {
+  routes: RouteConfig[];
+  mode?: RouterMode;
+  base?: string;
+}