ptech-shell-dev 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# ptech-shell-dev
+
+Standalone/mock implementations for services defined in `ptech-shell-sdk`.
+
+## Install
+
+```bash
+npm i ptech-shell-dev ptech-shell-sdk
+```
+
+## Usage
+
+```ts
+import { initStandaloneServices } from 'ptech-shell-dev';
+
+initStandaloneServices();
+```

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { Lang, User, I18nService, UserService, ApiClient, NavigationService, ConfigService, PermissionService, SharedStateService, ObservabilityService, NotificationService, AnalyticsService } from 'ptech-shell-sdk';
+
+type StandaloneServices = {
+    i18n: I18nService;
+    userService: UserService;
+    apiClient: ApiClient;
+    navigation: NavigationService;
+    configService: ConfigService;
+    permissionService: PermissionService;
+    sharedState: SharedStateService;
+    observability: ObservabilityService;
+    notification: NotificationService;
+    analytics: AnalyticsService;
+};
+type ServiceRegisterMode = 'if-missing' | 'always';
+type StandaloneInitOptions = {
+    /**
+     * API base URL when running standalone.
+     * Example: http://localhost:4000
+     */
+    apiBase?: string;
+    /**
+     * Default language for standalone.
+     */
+    lang?: Lang;
+    /**
+     * Seed user for standalone. (Optional)
+     */
+    user?: User | null;
+    /**
+     * Optional hook to customize the created services.
+     * This is useful when each remote wants slightly different mock behavior.
+     */
+    customize?: (services: StandaloneServices) => void;
+    /**
+     * Service registration strategy for standalone init.
+     * - if-missing (default): only register when token has no service yet.
+     * - always: replace any existing service for the token.
+     */
+    registerMode?: ServiceRegisterMode;
+};
+
+/**
+ * Initialize "safe defaults" so a remote app can run standalone without the host.
+ *
+ * In host-composed mode, host should register real services first.
+ * But if host doesn't (or remote is standalone), this provides mocks.
+ */
+declare function initStandaloneServices(options?: StandaloneInitOptions): void;
+
+declare function createStandaloneApiClient(apiBase: string): ApiClient;
+
+declare function createStandaloneI18nService(initialLang: Lang): I18nService;
+
+declare function createStandaloneUserService(user: User | null): UserService;
+
+export { type ServiceRegisterMode, type StandaloneInitOptions, type StandaloneServices, createStandaloneApiClient, createStandaloneI18nService, createStandaloneUserService, initStandaloneServices };

package/dist/index.js

@@ -0,0 +1,492 @@
+// src/initStandaloneServices.ts
+import { FEATURE_FLAGS as FEATURE_FLAGS2, getService, registerService, SHARED_STATE_KEYS, TOKENS } from "ptech-shell-sdk";
+
+// src/services/analytics.ts
+var MAX_EVENTS = 200;
+function createStandaloneAnalyticsService() {
+  const listeners = /* @__PURE__ */ new Set();
+  const events = [];
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  return {
+    track: (event) => {
+      events.push({
+        ...event,
+        timestamp: Date.now()
+      });
+      if (events.length > MAX_EVENTS) {
+        events.shift();
+      }
+      emitChange();
+    },
+    getEvents: () => [...events],
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/apiClient.ts
+function createStandaloneApiClient(apiBase) {
+  return {
+    fetch: async (path, init) => {
+      const url = path.startsWith("http") ? path : `${apiBase}${path.startsWith("/") ? "" : "/"}${path}`;
+      const headers = new Headers(init?.headers);
+      if (!headers.has("Authorization")) {
+        headers.set("Authorization", "Bearer dev-token");
+      }
+      return fetch(url, { ...init, headers });
+    }
+  };
+}
+
+// src/services/config.ts
+import { FEATURE_FLAGS } from "ptech-shell-sdk";
+var DEFAULT_FLAGS = {
+  [FEATURE_FLAGS.uiExperimental]: true
+};
+var DEFAULT_CONFIG = {
+  envName: "standalone",
+  apiBase: "http://localhost:4000"
+};
+function createStandaloneConfigService(initialFlags = DEFAULT_FLAGS, initialConfig = DEFAULT_CONFIG) {
+  const listeners = /* @__PURE__ */ new Set();
+  const flags = { ...initialFlags };
+  const runtimeConfig = { ...initialConfig };
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  return {
+    isEnabled: (flag) => Boolean(flags[flag]),
+    getAllFlags: () => ({ ...flags }),
+    setFlag: (flag, enabled) => {
+      if (flags[flag] === enabled) {
+        return;
+      }
+      flags[flag] = enabled;
+      emitChange();
+    },
+    getValue: (key) => runtimeConfig[key],
+    getAllConfig: () => ({ ...runtimeConfig }),
+    setValue: (key, value) => {
+      if (runtimeConfig[key] === value) {
+        return;
+      }
+      runtimeConfig[key] = value;
+      emitChange();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/i18n.ts
+var BASE_NAMESPACE = "shell-dev";
+var DEFAULT_MESSAGES = {
+  vi: {
+    "common.hello": "Xin chao",
+    "common.language": "Ngon ngu",
+    "common.user": "Nguoi dung",
+    "common.guest": "Khach",
+    "common.callApi": "Goi API"
+  },
+  en: {
+    "common.hello": "Hello",
+    "common.language": "Language",
+    "common.user": "User",
+    "common.guest": "Guest",
+    "common.callApi": "Call API"
+  }
+};
+function createStandaloneI18nService(initialLang) {
+  const listeners = /* @__PURE__ */ new Set();
+  let currentLang = initialLang;
+  const messagesByNamespace = /* @__PURE__ */ new Map();
+  messagesByNamespace.set(BASE_NAMESPACE, DEFAULT_MESSAGES);
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function resolveMessage(key) {
+    for (const messages of messagesByNamespace.values()) {
+      const hit = messages[currentLang]?.[key];
+      if (hit !== void 0) {
+        return hit;
+      }
+    }
+    return key;
+  }
+  return {
+    t: (key) => resolveMessage(key),
+    getLang: () => currentLang,
+    setLang: (nextLang) => {
+      if (nextLang === currentLang) {
+        return;
+      }
+      currentLang = nextLang;
+      emitChange();
+    },
+    registerMessages: (namespace, messages) => {
+      messagesByNamespace.set(namespace, messages);
+      emitChange();
+    },
+    unregisterMessages: (namespace) => {
+      if (namespace === BASE_NAMESPACE) {
+        return;
+      }
+      const changed = messagesByNamespace.delete(namespace);
+      if (changed) {
+        emitChange();
+      }
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/navigation.ts
+function createStandaloneNavigationService(initialPath = "/standalone") {
+  const listeners = /* @__PURE__ */ new Set();
+  let currentPath = initialPath;
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  return {
+    getPath: () => currentPath,
+    navigate: (path) => {
+      if (path === currentPath) {
+        return;
+      }
+      currentPath = path;
+      emitChange();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/notification.ts
+function createStandaloneNotificationService() {
+  const listeners = /* @__PURE__ */ new Set();
+  const items = [];
+  const timersById = /* @__PURE__ */ new Map();
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function dismiss(id) {
+    const timer = timersById.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersById.delete(id);
+    }
+    const index = items.findIndex((item) => item.id === id);
+    if (index < 0) {
+      return;
+    }
+    items.splice(index, 1);
+    emitChange();
+  }
+  return {
+    push: (input) => {
+      const id = `notif-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const item = {
+        id,
+        level: input.level,
+        message: input.message,
+        source: input.source,
+        createdAt: Date.now()
+      };
+      items.unshift(item);
+      emitChange();
+      if (input.ttlMs && input.ttlMs > 0) {
+        const timer = setTimeout(() => dismiss(id), input.ttlMs);
+        timersById.set(id, timer);
+      }
+      return id;
+    },
+    dismiss,
+    getSnapshot: () => [...items],
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/observability.ts
+var MAX_ENTRIES = 100;
+var LOG_METHOD = {
+  debug: "log",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+function createStandaloneObservabilityService() {
+  const listeners = /* @__PURE__ */ new Set();
+  const entries = [];
+  let nextId = 1;
+  function emitChange() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  return {
+    log: (entry) => {
+      const nextEntry = {
+        ...entry,
+        id: nextId,
+        timestamp: Date.now()
+      };
+      nextId += 1;
+      entries.push(nextEntry);
+      if (entries.length > MAX_ENTRIES) {
+        entries.shift();
+      }
+      const method = LOG_METHOD[nextEntry.level];
+      console[method](`[${nextEntry.source}] ${nextEntry.message}`, nextEntry.data ?? "");
+      emitChange();
+    },
+    getEntries: () => [...entries],
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/permission.ts
+import {
+  listPermissionsByRole,
+  USER_ROLES
+} from "ptech-shell-sdk";
+var DEFAULT_PERMISSIONS = listPermissionsByRole(USER_ROLES.authenticated);
+function createStandalonePermissionService(initialPermissions = DEFAULT_PERMISSIONS) {
+  const listeners = /* @__PURE__ */ new Set();
+  const permissions = new Set(initialPermissions);
+  return {
+    can: (permission) => permissions.has(permission),
+    list: () => Array.from(permissions.values()),
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/services/sharedState.ts
+function createStandaloneSharedStateService() {
+  const records = /* @__PURE__ */ new Map();
+  const listenersByKey = /* @__PURE__ */ new Map();
+  const requestListenersByKey = /* @__PURE__ */ new Map();
+  function emitKeyChanged(key) {
+    const listeners = listenersByKey.get(key);
+    if (!listeners) {
+      return;
+    }
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function applyOwnerUpdate(key, value, owner) {
+    const current = records.get(key);
+    if (!current) {
+      throw new Error(`sharedState key "${key}" is not registered.`);
+    }
+    if (current.owner !== owner) {
+      throw new Error(`Only owner "${current.owner}" can set key "${key}".`);
+    }
+    records.set(key, {
+      ...current,
+      value,
+      version: current.version + 1
+    });
+    emitKeyChanged(key);
+  }
+  return {
+    ensureKey: (key, owner, initialValue) => {
+      if (records.has(key)) {
+        return;
+      }
+      records.set(key, {
+        key,
+        owner,
+        value: initialValue,
+        version: 1
+      });
+      emitKeyChanged(key);
+    },
+    getSnapshot: (key) => {
+      const record = records.get(key);
+      return record ? { ...record } : void 0;
+    },
+    getAll: () => Array.from(records.values()).map((record) => ({ ...record })),
+    setByOwner: (key, value, owner) => {
+      applyOwnerUpdate(key, value, owner);
+    },
+    requestChange: (request) => {
+      const current = records.get(request.key);
+      if (!current) {
+        throw new Error(`sharedState key "${request.key}" is not registered.`);
+      }
+      if (request.requestedBy === current.owner) {
+        applyOwnerUpdate(request.key, request.nextValue, current.owner);
+        return;
+      }
+      const listeners = requestListenersByKey.get(request.key);
+      if (!listeners || listeners.size === 0) {
+        throw new Error(
+          `No owner request handler for key "${request.key}". Owner is "${current.owner}".`
+        );
+      }
+      let handled = false;
+      for (const sub of listeners) {
+        if (sub.owner === current.owner) {
+          handled = true;
+          sub.listener(request);
+        }
+      }
+      if (!handled) {
+        throw new Error(
+          `Owner "${current.owner}" has no active request handler for key "${request.key}".`
+        );
+      }
+    },
+    subscribeKey: (key, listener) => {
+      let listeners = listenersByKey.get(key);
+      if (!listeners) {
+        listeners = /* @__PURE__ */ new Set();
+        listenersByKey.set(key, listeners);
+      }
+      listeners.add(listener);
+      return () => {
+        const current = listenersByKey.get(key);
+        current?.delete(listener);
+        if (current && current.size === 0) {
+          listenersByKey.delete(key);
+        }
+      };
+    },
+    subscribeRequests: (key, owner, listener) => {
+      let listeners = requestListenersByKey.get(key);
+      if (!listeners) {
+        listeners = /* @__PURE__ */ new Set();
+        requestListenersByKey.set(key, listeners);
+      }
+      const sub = {
+        owner,
+        listener
+      };
+      listeners.add(sub);
+      return () => {
+        const current = requestListenersByKey.get(key);
+        current?.delete(sub);
+        if (current && current.size === 0) {
+          requestListenersByKey.delete(key);
+        }
+      };
+    }
+  };
+}
+
+// src/services/user.ts
+function createStandaloneUserService(user) {
+  const listeners = /* @__PURE__ */ new Set();
+  const currentUser = user;
+  return {
+    getSnapshot: () => currentUser,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/initStandaloneServices.ts
+function initStandaloneServices(options = {}) {
+  const {
+    apiBase = "http://localhost:4000",
+    lang = "vi",
+    user = { id: "dev", name: "Dev User" },
+    customize,
+    registerMode = "if-missing"
+  } = options;
+  const services = {
+    i18n: createStandaloneI18nService(lang),
+    userService: createStandaloneUserService(user ?? null),
+    apiClient: createStandaloneApiClient(apiBase),
+    navigation: createStandaloneNavigationService("/standalone"),
+    configService: createStandaloneConfigService(
+      { [FEATURE_FLAGS2.uiExperimental]: true },
+      { envName: "standalone", apiBase }
+    ),
+    permissionService: createStandalonePermissionService(),
+    sharedState: createStandaloneSharedStateService(),
+    observability: createStandaloneObservabilityService(),
+    notification: createStandaloneNotificationService(),
+    analytics: createStandaloneAnalyticsService()
+  };
+  customize?.(services);
+  services.sharedState.ensureKey(SHARED_STATE_KEYS.x, "host", 0);
+  services.sharedState.subscribeRequests(SHARED_STATE_KEYS.x, "host", (request) => {
+    services.sharedState.setByOwner(SHARED_STATE_KEYS.x, request.nextValue, "host", request.reason);
+    services.observability.log({
+      level: "info",
+      source: "standalone.sharedState",
+      message: `Applied shared.x from request by ${request.requestedBy}`,
+      data: { nextValue: request.nextValue, reason: request.reason ?? "" }
+    });
+  });
+  if (registerMode === "always" || !getService(TOKENS.i18n)) {
+    registerService(TOKENS.i18n, services.i18n);
+  }
+  if (registerMode === "always" || !getService(TOKENS.userService)) {
+    registerService(TOKENS.userService, services.userService);
+  }
+  if (registerMode === "always" || !getService(TOKENS.apiClient)) {
+    registerService(TOKENS.apiClient, services.apiClient);
+  }
+  if (registerMode === "always" || !getService(TOKENS.navigation)) {
+    registerService(TOKENS.navigation, services.navigation);
+  }
+  if (registerMode === "always" || !getService(TOKENS.configService)) {
+    registerService(TOKENS.configService, services.configService);
+  }
+  if (registerMode === "always" || !getService(TOKENS.permissionService)) {
+    registerService(TOKENS.permissionService, services.permissionService);
+  }
+  if (registerMode === "always" || !getService(TOKENS.sharedState)) {
+    registerService(TOKENS.sharedState, services.sharedState);
+  }
+  if (registerMode === "always" || !getService(TOKENS.observability)) {
+    registerService(TOKENS.observability, services.observability);
+  }
+  if (registerMode === "always" || !getService(TOKENS.notification)) {
+    registerService(TOKENS.notification, services.notification);
+  }
+  if (registerMode === "always" || !getService(TOKENS.analytics)) {
+    registerService(TOKENS.analytics, services.analytics);
+  }
+}
+export {
+  createStandaloneApiClient,
+  createStandaloneI18nService,
+  createStandaloneUserService,
+  initStandaloneServices
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ptech-shell-dev",
+  "version": "0.1.0",
+  "description": "Standalone/mock shell service implementations for Module Federation apps.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist --clean",
+    "dev": "tsup src/index.ts --format esm --dts --out-dir dist --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ptech-shell-sdk": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.6.2"
+  },
+  "keywords": [
+    "micro-frontend",
+    "module-federation",
+    "shell",
+    "standalone",
+    "mock"
+  ],
+  "license": "MIT"
+}