slicejs-web-framework 3.2.0 → 3.2.2

package/Slice/Components/Structural/Controller/Controller.js

@@ -65,6 +65,20 @@ export default class Controller {
       return importPromise;
    }
 
+   buildBundleImportPath(bundleInfo) {
+      if (!bundleInfo || typeof bundleInfo.file !== 'string' || bundleInfo.file.length === 0) {
+         throw new Error('Bundle file is required');
+      }
+
+      const basePath = `/bundles/${bundleInfo.file}`;
+      const bundleHash = typeof bundleInfo.hash === 'string' ? bundleInfo.hash.trim() : '';
+      if (!bundleHash) {
+         return basePath;
+      }
+
+      return `${basePath}?v=${encodeURIComponent(bundleHash)}`;
+   }
+
    /**
     * Validate Bundling V2 module contract.
     * Requires named exports: SLICE_BUNDLE_META and registerAll.
@@ -126,7 +140,7 @@ export default class Controller {
                await this.loadBundleWithDependencies(dependencyName, loadingStack);
             }
 
-            const bundlePath = `/bundles/${bundleInfo.file}`;
+            const bundlePath = this.buildBundleImportPath(bundleInfo);
             const bundleModule = await this.importBundleOnce(bundlePath);
             const { metadata, registerAll } = await this.validateBundleModule(bundleModule, resolvedBundleName);
 

package/Slice/tests/bundle-v2-runtime-contract.test.js

@@ -379,6 +379,66 @@ test('loadBundle registers vendor-shared dependencies from registerAll return wh
    }
 });
 
+test('loadBundle appends bundle hash as query param when importing bundle files', async () => {
+   const tempDir = await mkdtemp(path.join(tmpdir(), 'slice-controller-loader-'));
+   const loaderPath = path.join(tempDir, 'components-alias-loader.mjs');
+   await writeFile(
+      loaderPath,
+      `export async function resolve(specifier, context, nextResolve) {
+   if (specifier === '/Components/components.js') {
+      return {
+         shortCircuit: true,
+         url: 'data:text/javascript,export default {};',
+      };
+   }
+   return nextResolve(specifier, context);
+}
+`,
+      'utf8'
+   );
+   register(pathToFileURL(loaderPath).href);
+
+   const controllerModuleUrl = new URL('../Components/Structural/Controller/Controller.js', import.meta.url).href;
+   const { default: Controller } = await import(controllerModuleUrl);
+   const controller = new Controller();
+   const originalSlice = globalThis.slice;
+
+   controller.bundleConfig = {
+      bundles: {
+         routes: {
+            dashboard: {
+               file: 'slice-bundle.dashboard.js',
+               hash: 'abc123hash',
+            },
+         },
+      },
+   };
+
+   let importedPath = null;
+   controller.importBundleOnce = async (bundlePath) => {
+      importedPath = bundlePath;
+      return {
+         SLICE_BUNDLE_META: {
+            bundleKey: 'dashboard',
+            type: 'route',
+         },
+         registerAll: async () => {},
+      };
+   };
+
+   try {
+      globalThis.slice = {
+         stylesManager: {},
+      };
+
+      await controller.loadBundle('dashboard');
+      assert.equal(importedPath, '/bundles/slice-bundle.dashboard.js?v=abc123hash');
+   } finally {
+      globalThis.slice = originalSlice;
+      await rm(tempDir, { recursive: true, force: true });
+   }
+});
+
 test('loadBundle dedupes concurrent and repeated alias/case requests using canonical bundle key', async () => {
    const tempDir = await mkdtemp(path.join(tmpdir(), 'slice-controller-loader-'));
    const loaderPath = path.join(tempDir, 'components-alias-loader.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "",
   "engines": {
     "node": ">=20"
@@ -21,6 +21,7 @@
   "author": "",
   "license": "ISC",
   "type": "module",
+  "types": "./types/index.d.ts",
   "dependencies": {
     "express": "^4.19.2"
   },

package/types/index.d.ts

@@ -0,0 +1,207 @@
+export type SliceMode = 'development' | 'production' | string;
+
+export interface RouteConfig {
+  path: string;
+  component: string;
+  children?: RouteConfig[];
+  metadata?: Record<string, unknown>;
+  fullPath?: string;
+  parentPath?: string | null;
+  parentRoute?: RouteConfig | null;
+}
+
+export interface RouteInfo {
+  path: string;
+  component: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  metadata: Record<string, unknown>;
+}
+
+export interface RouteMatch {
+  route: RouteConfig | null;
+  params: Record<string, string>;
+  childRoute?: RouteConfig;
+}
+
+export type RouterNext = (arg?: void | false | string | { path: string; replace?: boolean }) => void;
+
+export interface SliceControllerApi {
+  componentCategories: Map<string, string>;
+  templates: Map<string, HTMLTemplateElement>;
+  classes: Map<string, new (...args: any[]) => HTMLElement>;
+  requestedStyles: Set<string>;
+  activeComponents: Map<string, HTMLElement>;
+  getComponent(sliceId: string): HTMLElement | undefined;
+  getComponentCategory(componentSliceId: string): string | undefined;
+  fetchText(
+    componentName: string,
+    resourceType: 'html' | 'css' | 'theme' | 'styles',
+    componentCategory?: string,
+    customPath?: string
+  ): Promise<string>;
+  setComponentProps(component: HTMLElement, props: Record<string, unknown>): void;
+  destroyComponent(components: HTMLElement | string | Array<HTMLElement | string>): number;
+  destroyByContainer(container: HTMLElement): number;
+  destroyByPattern(pattern: string | RegExp): number;
+}
+
+export interface SliceStylesManagerApi {
+  componentStyles: HTMLStyleElement;
+  themeManager?: SliceThemeManagerApi;
+  init(): Promise<void>;
+  appendComponentStyles(cssText: string): void;
+  registerComponentStyles(componentName: string, cssText: string): void;
+}
+
+export interface SliceThemeManagerApi {
+  currentTheme: string | null;
+  applyTheme(themeName: string): Promise<void>;
+}
+
+export interface SliceLoggerApi {
+  logError(componentSliceId: string, message: string, error?: unknown): void;
+  logWarning(componentSliceId: string, message: string): void;
+  logInfo(componentSliceId: string, message: string): void;
+  getLogs(): unknown[];
+  clearLogs(): void;
+}
+
+export interface SliceEventBindingApi {
+  subscribe(eventName: string, callback: (data?: unknown) => void): string | null;
+  subscribeOnce(eventName: string, callback: (data?: unknown) => void): string | null;
+  emit(eventName: string, data?: unknown): void;
+}
+
+export interface SliceEventManagerApi {
+  init(): boolean;
+  subscribe(
+    eventName: string,
+    callback: (data?: unknown) => void,
+    options?: { component?: HTMLElement }
+  ): string | null;
+  subscribeOnce(
+    eventName: string,
+    callback: (data?: unknown) => void,
+    options?: { component?: HTMLElement }
+  ): string | null;
+  unsubscribe(eventName: string, subscriptionId: string): boolean;
+  emit(eventName: string, ...data: unknown[]): void;
+  bind(component: HTMLElement): SliceEventBindingApi | null;
+  cleanupComponent(sliceId: string): number;
+  hasSubscribers(eventName: string): boolean;
+  subscriberCount(eventName: string): number;
+  clear(): void;
+}
+
+export interface SliceContextOptions {
+  persist?: boolean;
+  storageKey?: string;
+}
+
+export interface SliceContextManagerApi {
+  init(): boolean;
+  create(name: string, initialState?: Record<string, unknown>, options?: SliceContextOptions): boolean;
+  getState<T = unknown>(name: string): T | null;
+  setState<T = unknown>(name: string, updater: T | ((prevState: T) => T)): void;
+  watch<TSelected = unknown>(
+    name: string,
+    component: HTMLElement,
+    callback: (value: TSelected) => void,
+    selector?: (state: unknown) => TSelected
+  ): string | null;
+  has(name: string): boolean;
+  destroy(name: string): boolean;
+  list(): string[];
+}
+
+export interface SliceRouterApi {
+  activeRoute: RouteConfig | null;
+  pathToRouteMap: Map<string, RouteConfig>;
+  init(): void;
+  start(): Promise<void>;
+  beforeEach(guard: (to: RouteInfo, from: RouteInfo, next: RouterNext) => void | Promise<void>): void;
+  afterEach(guard: (to: RouteInfo, from: RouteInfo) => void): void;
+  navigate(path: string, redirectChain?: string[], options?: { replace?: boolean }): Promise<void>;
+  matchRoute(path: string): RouteMatch;
+}
+
+export interface SlicePanelDebuggerApi {
+  init(): Promise<void>;
+  toggle(): void;
+  open(): void;
+  close(): void;
+}
+
+export interface SliceDebuggerApi {
+  enableDebugMode(): Promise<boolean>;
+  attachDebugMode(component: HTMLElement): void;
+  hide(): void;
+}
+
+export interface SliceLoadingApi {
+  start?: () => void;
+  stop?: () => void;
+}
+
+export interface SlicePaths {
+  routesFile?: string;
+  themes?: string;
+  styles?: string;
+  structuralComponentFolderPath?: string;
+  components?: Record<string, { path: string; type?: string }>;
+  [key: string]: unknown;
+}
+
+export interface SliceFrameworkClasses {
+  Controller?: new () => SliceControllerApi;
+  StylesManager?: new () => SliceStylesManagerApi;
+  Router?: new (routes: RouteConfig[]) => SliceRouterApi;
+  Logger?: new () => SliceLoggerApi;
+  EventManager?: new () => SliceEventManagerApi;
+  ContextManager?: new () => SliceContextManagerApi;
+  Debugger?: new () => SliceDebuggerApi;
+  EventManagerDebugger?: new () => SlicePanelDebuggerApi;
+  ContextManagerDebugger?: new () => SlicePanelDebuggerApi;
+  ThemeManager?: new () => SliceThemeManagerApi;
+  [key: string]: unknown;
+}
+
+export interface SliceApi {
+  frameworkClasses: SliceFrameworkClasses | null;
+  controller: SliceControllerApi;
+  stylesManager: SliceStylesManagerApi;
+  logger: SliceLoggerApi;
+  router: SliceRouterApi;
+  events: SliceEventManagerApi;
+  context: SliceContextManagerApi;
+  debugger?: SliceDebuggerApi;
+  eventsDebugger?: SlicePanelDebuggerApi;
+  contextDebugger?: SlicePanelDebuggerApi;
+  loading?: SliceLoadingApi;
+  paths: SlicePaths;
+  _mode: SliceMode;
+  getClass<T = unknown>(module: string): Promise<T | undefined>;
+  isProduction(): boolean;
+  getEnv(name: string, fallbackValue?: string): string | undefined;
+  getPublicEnv(): Record<string, string>;
+  getComponent(componentSliceId: string): HTMLElement | undefined;
+  build<T = HTMLElement>(componentName: string, props?: Record<string, unknown>): Promise<T | null>;
+  setTheme(themeName: string): Promise<void>;
+  readonly theme: string | null;
+  attachTemplate(componentInstance: HTMLElement): void;
+}
+
+declare class Slice {
+  constructor(sliceConfig: Record<string, unknown>, frameworkClasses?: SliceFrameworkClasses | null);
+}
+
+export default Slice;
+
+declare global {
+  interface Window {
+    slice: SliceApi;
+  }
+
+  const slice: SliceApi;
+}