@okalit/cli 0.1.0 → 0.2.0

package/templates/app/@okalit/router.js

@@ -0,0 +1,240 @@
+import { signal } from 'uhtml';
+import { clearChannelsByScope } from './channel.js';
+
+/** @type {Router|null} */
+let instance = null;
+
+export class Router {
+  constructor(routes = []) {
+    if (instance) return instance;
+    instance = this;
+
+    this._routes = routes;
+    this._outlets = new Set();
+    this._interceptors = [];
+
+    // Reactive signals for current route state
+    this.currentPath = signal(window.location.pathname);
+    this.currentRoute = signal(null);
+    this.params = signal({});
+    this.query = signal({});
+
+    this._onPopState = this._onPopState.bind(this);
+    window.addEventListener('popstate', this._onPopState);
+
+    // Store pending resolve — outlets will trigger it when they register
+    this._pendingPath = window.location.pathname + window.location.search;
+  }
+
+  static getInstance() {
+    return instance;
+  }
+
+  // --- Public API ---
+
+  navigate(path, { replace = false } = {}) {
+    if (path === this.currentPath.value) return;
+    if (replace) {
+      window.history.replaceState(null, '', path);
+    } else {
+      window.history.pushState(null, '', path);
+    }
+    this._resolve(path);
+  }
+
+  back() {
+    window.history.back();
+  }
+
+  addInterceptor(fn) {
+    this._interceptors.push(fn);
+    return () => {
+      this._interceptors = this._interceptors.filter(i => i !== fn);
+    };
+  }
+
+  registerOutlet(outlet) {
+    this._outlets.add(outlet);
+    // If there's a pending resolve or an existing route, trigger it
+    if (this._pendingPath) {
+      const path = this._pendingPath;
+      this._pendingPath = null;
+      this._resolve(path);
+    } else if (this.currentRoute.value) {
+      outlet._renderRoute(this.currentRoute.value);
+    }
+  }
+
+  unregisterOutlet(outlet) {
+    this._outlets.delete(outlet);
+  }
+
+  destroy() {
+    window.removeEventListener('popstate', this._onPopState);
+    instance = null;
+  }
+
+  // --- Internal ---
+
+  _onPopState() {
+    this._resolve(window.location.pathname + window.location.search);
+  }
+
+  async _resolve(fullPath) {
+    const [pathname, search] = fullPath.split('?');
+    const path = pathname || '/';
+    const query = Object.fromEntries(new URLSearchParams(search || ''));
+
+    const match = this._matchRoute(this._routes, path);
+    if (!match) {
+      console.warn(`[okalit-router] No route matched: ${path}`);
+      return;
+    }
+
+    // Run guards BEFORE loading anything
+    const guardsPassed = await this._runGuards(match.guards, path, match);
+    if (!guardsPassed) return;
+
+    // Run interceptors
+    for (const interceptor of this._interceptors) {
+      const result = await interceptor(match, path);
+      if (result === false) return;
+    }
+
+    // Update reactive state
+    this.currentPath.value = path;
+    this.params.value = match.params;
+    this.query.value = query;
+
+    // Determine what changed and clear scoped channels
+    const prevRoute = this.currentRoute.value;
+    if (prevRoute) {
+      const prevPage = prevRoute.chain[prevRoute.chain.length - 1]?.component;
+      const newPage = match.chain[match.chain.length - 1]?.component;
+      const prevModule = prevRoute.chain[0]?.component;
+      const newModule = match.chain[0]?.component;
+
+      if (prevPage !== newPage) clearChannelsByScope('page');
+      if (prevModule !== newModule) clearChannelsByScope('module');
+    }
+
+    this.currentRoute.value = match;
+
+    // Notify all outlets
+    for (const outlet of this._outlets) {
+      outlet._renderRoute(match);
+    }
+  }
+
+  async _runGuards(guards, path, match) {
+    if (!guards || !guards.length) return true;
+
+    for (const guard of guards) {
+      const result = await guard({ path, params: match.params, route: match });
+      if (result === false) return false;
+      if (typeof result === 'string') {
+        // Guard returned a redirect path
+        this.navigate(result, { replace: true });
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Match a path against the route tree.
+   * Returns a flat match object with the chain of matched routes.
+   */
+  _matchRoute(routes, path, basePath = '', parentGuards = []) {
+    for (const route of routes) {
+      const fullPattern = normalizePath(basePath + '/' + route.path);
+
+      // For routes with children, use prefix matching
+      // For leaf routes, use exact matching
+      const hasChildren = route.children && route.children.length;
+      const match = hasChildren
+        ? matchPrefix(fullPattern, path)
+        : matchPath(fullPattern, path);
+
+      if (match) {
+        const guards = [...parentGuards, ...(route.guards || [])];
+        const result = {
+          route,
+          params: match.params,
+          guards,
+          chain: [route],
+        };
+
+        // If route has children, try to match deeper
+        if (route.children && route.children.length) {
+          const childMatch = this._matchRoute(route.children, path, fullPattern, guards);
+          if (childMatch) {
+            childMatch.chain = [route, ...childMatch.chain];
+            return childMatch;
+          }
+        }
+
+        // Exact match or this route is a leaf
+        if (match.exact || !route.children) {
+          return result;
+        }
+      }
+    }
+    return null;
+  }
+}
+
+// --- Path utilities ---
+
+function normalizePath(path) {
+  return '/' + path.split('/').filter(Boolean).join('/');
+}
+
+/**
+ * Match a pattern like /users/:id against a path like /users/42
+ * Returns { params, exact } or null
+ */
+function matchPath(pattern, path) {
+  const patternParts = pattern.split('/').filter(Boolean);
+  const pathParts = path.split('/').filter(Boolean);
+
+  // Exact match requires same length
+  if (patternParts.length !== pathParts.length) return null;
+
+  const params = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i].startsWith(':')) {
+      params[patternParts[i].slice(1)] = pathParts[i];
+    } else if (patternParts[i] !== pathParts[i]) {
+      return null;
+    }
+  }
+
+  return { params, exact: true };
+}
+
+/**
+ * Prefix match: pattern must match the beginning of the path
+ */
+function matchPrefix(pattern, path) {
+  const patternParts = pattern.split('/').filter(Boolean);
+  const pathParts = path.split('/').filter(Boolean);
+
+  if (pathParts.length < patternParts.length) return null;
+
+  const params = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i].startsWith(':')) {
+      params[patternParts[i].slice(1)] = pathParts[i];
+    } else if (patternParts[i] !== pathParts[i]) {
+      return null;
+    }
+  }
+
+  return { params, exact: patternParts.length === pathParts.length };
+}
+
+// Navigation helper for use outside components
+export function navigate(path, options) {
+  Router.getInstance()?.navigate(path, options);
+}

package/templates/app/@okalit/service.js

@@ -1,33 +1,328 @@
-// src/core/service.js
-// Vanilla JS decorator for service registration and DI
+// ── RequestControl ─────────────────────────────────────────────
+// Wraps a Promise (typically from fetch) and exposes a declarative
+// fire() API for loading / success / error / finish callbacks,
+// while still being await-able via then().
 
-const __serviceRegistry = new Map();
+export class RequestControl {
+  #promise;
 
+  constructor(promise) {
+    this.#promise = promise;
+  }
+
+  /**
+   * Declarative async flow handler.
+   *
+   * @param {Object} callbacks
+   * @param {(loading: boolean) => void} [callbacks.onLoading]
+   * @param {(data: any) => void}        [callbacks.onSuccess]
+   * @param {(error: any) => void}       [callbacks.onError]
+   * @param {() => void}                 [callbacks.onFinish]
+   */
+  fire({ onLoading, onSuccess, onError, onFinish } = {}) {
+    onLoading?.(true);
+
+    this.#promise
+      .then((data) => {
+        onSuccess?.(data);
+      })
+      .catch((err) => {
+        onError?.(err);
+      })
+      .finally(() => {
+        onLoading?.(false);
+        onFinish?.();
+      });
+  }
+
+  /** Allow `await service.getX()` without calling fire(). */
+  then(resolve, reject) {
+    return this.#promise.then(resolve, reject);
+  }
+
+  catch(reject) {
+    return this.#promise.catch(reject);
+  }
+
+  finally(cb) {
+    return this.#promise.finally(cb);
+  }
+}
+
+// ── Service registry ───────────────────────────────────────────
+
+const _registry = new Map();
+
+/**
+ * Decorator — registers the class as a singleton service.
+ *
+ * Usage:
+ *   @service('user')
+ *   class UserService extends OkalitService { … }
+ */
 export function service(name) {
-  return function (target) {
-    if (__serviceRegistry.has(name)) {
-      console.warn(`service("${name}"): already registered — skipping duplicate.`);
-      return;
-    }
-    __serviceRegistry.set(name, new target());
+  return function (cls, context) {
+    context.addInitializer(function () {
+      if (!_registry.has(name)) {
+        _registry.set(name, new cls());
+      }
+    });
   };
 }
 
-export function getService(name) {
-  return __serviceRegistry.get(name);
+/**
+ * Retrieve a registered service singleton by name.
+ *
+ * Usage:
+ *   userApi = inject('user');
+ */
+export function inject(name) {
+  const instance = _registry.get(name);
+  if (!instance) {
+    throw new Error(`[inject] Service "${name}" not found. Make sure the file is imported and @service("${name}") is applied.`);
+  }
+  return instance;
 }
 
-// Helper for DI in components
-export function injectServices(target, injectList) {
-  if (!Array.isArray(injectList)) return;
-  injectList.forEach((name) => {
-    const instance = getService(name);
-    if (instance) {
-      Object.defineProperty(target, name, {
-        value: instance,
-        writable: false,
-        configurable: false,
-      });
+// ── OkalitService base class ───────────────────────────────────
+
+export class OkalitService {
+  #baseUrl = '';
+  #headers = { 'Content-Type': 'application/json' };
+  #cache = new Map();
+  #cacheEnabled = false;
+  #cacheTTL = 0; // 0 = no expiry
+
+  /**
+   * Configure the service instance.
+   *
+   * @param {Object} opts
+   * @param {string}  [opts.baseUrl]
+   * @param {Record<string, string>} [opts.headers]
+   * @param {boolean} [opts.cache]    — enable/disable in-memory cache (default: false)
+   * @param {number}  [opts.cacheTTL] — cache lifetime in ms (0 = forever until clearCache)
+   */
+  configure({ baseUrl, headers, cache, cacheTTL } = {}) {
+    if (baseUrl !== undefined) this.#baseUrl = baseUrl.replace(/\/+$/, '');
+    if (headers !== undefined) this.#headers = { ...this.#headers, ...headers };
+    if (cache !== undefined) this.#cacheEnabled = cache;
+    if (cacheTTL !== undefined) this.#cacheTTL = cacheTTL;
+  }
+
+  // ── HTTP helpers ───────────────────────────────────────────
+
+  /**
+   * GET request (cacheable).
+   * @param {string} path
+   * @param {Record<string, string>} [params] — query-string params
+   * @returns {RequestControl}
+   */
+  get(path, params) {
+    let url = `${this.#baseUrl}${path}`;
+    if (params) {
+      const qs = new URLSearchParams(params).toString();
+      if (qs) url += `?${qs}`;
+    }
+    return this.#request(url, { method: 'GET' }, true);
+  }
+
+  /**
+   * POST request.
+   * @param {string} path
+   * @param {any} body
+   * @returns {RequestControl}
+   */
+  post(path, body) {
+    return this.#request(`${this.#baseUrl}${path}`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * PUT request.
+   * @param {string} path
+   * @param {any} body
+   * @returns {RequestControl}
+   */
+  put(path, body) {
+    return this.#request(`${this.#baseUrl}${path}`, {
+      method: 'PUT',
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * DELETE request.
+   * @param {string} path
+   * @returns {RequestControl}
+   */
+  delete(path) {
+    return this.#request(`${this.#baseUrl}${path}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /** Clear the in-memory cache (all entries or a specific path). */
+  clearCache(path) {
+    if (path) {
+      const url = `${this.#baseUrl}${path}`;
+      this.#cache.delete(url);
+    } else {
+      this.#cache.clear();
+    }
+  }
+
+  // ── Internal ───────────────────────────────────────────────
+
+  #request(url, options, cacheable = false) {
+    // Check cache for GET requests
+    if (cacheable && this.#cacheEnabled) {
+      const cached = this.#cache.get(url);
+      if (cached) {
+        const expired = this.#cacheTTL > 0 && (Date.now() - cached.time > this.#cacheTTL);
+        if (!expired) {
+          return new RequestControl(Promise.resolve(structuredClone(cached.data)));
+        }
+        this.#cache.delete(url);
+      }
     }
-  });
+
+    const promise = fetch(url, {
+      ...options,
+      headers: { ...this.#headers },
+    }).then(async (res) => {
+      if (!res.ok) {
+        let errorBody;
+        try {
+          errorBody = await res.json();
+        } catch {
+          errorBody = { message: res.statusText };
+        }
+        throw { status: res.status, statusText: res.statusText, body: errorBody };
+      }
+
+      // Handle 204 No Content
+      const text = await res.text();
+      if (!text) return null;
+
+      let data;
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+
+      // Store in cache
+      if (cacheable && this.#cacheEnabled) {
+        this.#cache.set(url, { data, time: Date.now() });
+      }
+
+      return data;
+    });
+
+    return new RequestControl(promise);
+  }
+}
+
+// ── OkalitGraphqlService ───────────────────────────────────────
+
+export class OkalitGraphqlService {
+  #endpoint = '';
+  #headers = { 'Content-Type': 'application/json' };
+  #cache = new Map();
+  #cacheEnabled = false;
+  #cacheTTL = 0;
+
+  /**
+   * @param {Object} opts
+   * @param {string}  [opts.endpoint] — GraphQL endpoint URL
+   * @param {Record<string, string>} [opts.headers]
+   * @param {boolean} [opts.cache]    — cache query results (default: false)
+   * @param {number}  [opts.cacheTTL] — cache lifetime in ms
+   */
+  configure({ endpoint, headers, cache, cacheTTL } = {}) {
+    if (endpoint !== undefined) this.#endpoint = endpoint.replace(/\/+$/, '');
+    if (headers !== undefined) this.#headers = { ...this.#headers, ...headers };
+    if (cache !== undefined) this.#cacheEnabled = cache;
+    if (cacheTTL !== undefined) this.#cacheTTL = cacheTTL;
+  }
+
+  /**
+   * Execute a GraphQL query.
+   * @param {string} queryString
+   * @param {Record<string, any>} [variables]
+   * @returns {RequestControl}
+   */
+  query(queryString, variables = {}) {
+    return this.#execute(queryString, variables);
+  }
+
+  /**
+   * Alias for query — semantically marks a mutation.
+   * @param {string} mutationString
+   * @param {Record<string, any>} [variables]
+   * @returns {RequestControl}
+   */
+  mutate(mutationString, variables = {}) {
+    return this.#execute(mutationString, variables);
+  }
+
+  /** Clear cached queries. Pass a query string to clear a specific one. */
+  clearCache(queryString) {
+    if (queryString) {
+      this.#cache.delete(queryString);
+    } else {
+      this.#cache.clear();
+    }
+  }
+
+  #execute(queryString, variables) {
+    // Cache check (keyed by query + variables)
+    const cacheKey = queryString + JSON.stringify(variables);
+    if (this.#cacheEnabled) {
+      const cached = this.#cache.get(cacheKey);
+      if (cached) {
+        const expired = this.#cacheTTL > 0 && (Date.now() - cached.time > this.#cacheTTL);
+        if (!expired) {
+          return new RequestControl(Promise.resolve(structuredClone(cached.data)));
+        }
+        this.#cache.delete(cacheKey);
+      }
+    }
+
+    const promise = fetch(this.#endpoint, {
+      method: 'POST',
+      headers: { ...this.#headers },
+      body: JSON.stringify({ query: queryString, variables }),
+    }).then(async (res) => {
+      // Handle HTTP-level errors (network, 500, etc.)
+      if (!res.ok) {
+        let errorBody;
+        try {
+          errorBody = await res.json();
+        } catch {
+          errorBody = { message: res.statusText };
+        }
+        throw { status: res.status, statusText: res.statusText, body: errorBody };
+      }
+
+      const json = await res.json();
+
+      // GraphQL can return 200 OK with errors in body
+      if (json.errors) {
+        throw { graphql: true, errors: json.errors, data: json.data ?? null };
+      }
+
+      const data = json.data;
+
+      if (this.#cacheEnabled) {
+        this.#cache.set(cacheKey, { data, time: Date.now() });
+      }
+
+      return data;
+    });
+
+    return new RequestControl(promise);
+  }
 }

package/templates/app/index.html

@@ -2,7 +2,6 @@
 <html lang="es">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/lit.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="referrer" content="strict-origin-when-cross-origin" />
     <title>Okalit App</title>

package/templates/app/package.json

@@ -9,8 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@lit-labs/signals": "^0.2.0",
-    "lit": "^3.3.1"
+    "uhtml": "^5.0.9"
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",
@@ -20,4 +19,4 @@
     "vite": "^7.3.1",
     "vite-plugin-babel": "^1.5.1"
   }
-}
+}

package/templates/app/public/i18n/en.json

@@ -1,3 +1,49 @@
 {
-    "WELCOME": "Welcome to Okalit Template"
+  "APP": {
+    "TITLE": "Okalit Starter",
+    "SUBTITLE": "A modern web component framework"
+  },
+  "NAV": {
+    "HOME": "Home",
+    "LIFECYCLE": "Lifecycle",
+    "SERVICES": "Services",
+    "PERFORMANCE": "Performance",
+    "DETAIL": "Detail {{ id }}"
+  },
+  "HOME": {
+    "HEADING": "Dashboard",
+    "COUNTER": "Shared Counter",
+    "COUNTER_HINT": "Counter must be > 2 to access the detail page (guard demo).",
+    "RESET": "Reset",
+    "GO_DETAIL": "Go to Detail {{ id }}",
+    "GO_LIFECYCLE": "Lifecycle Demo",
+    "GO_SERVICES": "Services Demo",
+    "GO_PERF": "Performance Demo"
+  },
+  "LIFECYCLE": {
+    "HEADING": "Lifecycle Hooks",
+    "LOG": "Event log",
+    "CLEAR": "Clear",
+    "CHANGE_PROP": "Change name prop"
+  },
+  "SERVICES": {
+    "HEADING": "Services & GraphQL",
+    "REST_TITLE": "REST — JSONPlaceholder Users",
+    "GQL_TITLE": "GraphQL — Rick & Morty Characters",
+    "LOADING": "Loading…",
+    "ERROR": "Error loading data."
+  },
+  "PERF": {
+    "HEADING": "Performance Components",
+    "IDLE_LABEL": "Loaded via <o-idle> (requestIdleCallback)",
+    "WHEN_LABEL": "Loaded via <o-when> (condition)",
+    "VIEWPORT_LABEL": "Loaded via <o-viewport> (scroll down)",
+    "TOGGLE": "Toggle condition",
+    "SCROLL_HINT": "Scroll down to trigger <o-viewport>…"
+  },
+  "DETAIL": {
+    "HEADING": "Detail Page",
+    "VIEWING": "Viewing item",
+    "BACK": "Back to Home"
+  }
 }