@okalit/cli 0.1.0

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

@@ -0,0 +1,152 @@
+// Prevents crashes from tampered or corrupted storage values
+function safeJsonParse(str, fallback = undefined) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback;
+  }
+}
+
+class EventBusImpl {
+  constructor() {
+    this.listeners = Object.create(null);
+    this.triggers = Object.create(null);
+    this.persistTypes = {
+      memory: null,
+      session: window.sessionStorage,
+      local: window.localStorage
+    };
+    this.memoryStore = Object.create(null);
+  }
+
+  _readPersistedValue(event, persist = 'memory') {
+    if (persist === 'memory') {
+      const found = event in this.memoryStore;
+      return {
+        found,
+        value: found ? this.memoryStore[event] : undefined,
+      };
+    }
+
+    const storage = this.persistTypes[persist];
+    if (!storage) {
+      return {
+        found: false,
+        value: undefined,
+      };
+    }
+
+    const stored = storage.getItem(`okalit:bus:${event}`);
+    return {
+      found: stored !== null,
+      value: stored !== null ? safeJsonParse(stored) : undefined,
+    };
+  }
+
+  // Validate event name to prevent accidental misuse
+  _validateEvent(event) {
+    if (typeof event !== 'string' || event.trim() === '') {
+      throw new Error(`EventBus: invalid event name "${event}"`);
+    }
+  }
+
+  // Remove a specific channel from memory, session or local storage
+  remove(event, { persist = 'memory' } = {}) {
+    this._validateEvent(event);
+    if (persist === 'memory') {
+      delete this.memoryStore[event];
+    } else {
+      const storage = this.persistTypes[persist];
+      if (storage) {
+        storage.removeItem(`okalit:bus:${event}`);
+      }
+    }
+  }
+
+  // Clear all channels of a given persistence type
+  clearAll({ persist = 'memory' } = {}) {
+    if (persist === 'memory') {
+      this.memoryStore = Object.create(null);
+    } else {
+      const storage = this.persistTypes[persist];
+      if (storage) {
+        // Collect keys first to avoid mutating storage during iteration
+        const keys = [];
+        for (let i = 0; i < storage.length; i++) {
+          const k = storage.key(i);
+          if (k && k.startsWith('okalit:bus:')) keys.push(k);
+        }
+        keys.forEach(k => storage.removeItem(k));
+      }
+    }
+  }
+
+  // Emit a stateful event (persists value and notifies subscribers)
+  emit(event, data, { persist = 'memory' } = {}) {
+    this._validateEvent(event);
+    if (persist !== 'memory') {
+      const storage = this.persistTypes[persist];
+      if (storage) {
+        storage.setItem(`okalit:bus:${event}`, JSON.stringify(data));
+      }
+    } else {
+      this.memoryStore[event] = data;
+    }
+    // Notify all subscribers
+    const cbs = this.listeners[event];
+    if (cbs) {
+      for (let i = 0; i < cbs.length; i++) cbs[i](data);
+    }
+  }
+
+  get(event, { persist = 'memory', fallback } = {}) {
+    this._validateEvent(event);
+    const { found, value } = this._readPersistedValue(event, persist);
+
+    if (!found || value === undefined) {
+      return fallback;
+    }
+
+    return value;
+  }
+
+  // Trigger a stateless (ephemeral) event — no persistence
+  trigger(event, data) {
+    this._validateEvent(event);
+    const cbs = this.triggers[event];
+    if (cbs) {
+      for (let i = 0; i < cbs.length; i++) cbs[i](data);
+    }
+  }
+
+  // Subscribe to a stateful channel; delivers persisted value immediately if available
+  on(event, cb, { persist = 'memory', immediate = true } = {}) {
+    this._validateEvent(event);
+    if (!this.listeners[event]) this.listeners[event] = [];
+    this.listeners[event].push(cb);
+
+    // Deliver persisted value immediately on subscribe
+    if (immediate) {
+      const { found, value } = this._readPersistedValue(event, persist);
+      if (found && value !== undefined) cb(value);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners[event] = (this.listeners[event] || []).filter(fn => fn !== cb);
+    };
+  }
+
+  // Subscribe to ephemeral (stateless) events
+  listen(event, cb) {
+    this._validateEvent(event);
+    if (!this.triggers[event]) this.triggers[event] = [];
+    this.triggers[event].push(cb);
+    // Return unsubscribe function
+    return () => {
+      this.triggers[event] = (this.triggers[event] || []).filter(fn => fn !== cb);
+    };
+  }
+}
+
+export const EventBus = new EventBusImpl();

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

@@ -0,0 +1,7 @@
+import { html } from "lit";
+
+export const ModuleMixin = (Base) => class extends Base {
+    render() {
+      return html`<slot></slot>`;
+    }
+}

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

@@ -0,0 +1,129 @@
+
+import { LitElement } from 'lit';
+import { EventBus } from './EventBus.js';
+import { OkalitI18n } from './i18n.js';
+import {signal, SignalWatcher} from '@lit-labs/signals';
+
+export class Okalit extends SignalWatcher(LitElement) {
+  constructor() {
+    super();
+
+    this._okalit_channel_unsubs = [];
+    this._okalit_listen_unsubs = [];
+
+    const props = this.constructor.properties || {};
+    for (const [key, opts] of Object.entries(props)) {
+      if ('value' in opts && this[key] === undefined) {
+        this[key] = opts.value;
+      }
+    }
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    if (typeof this.okalitConnections === 'function') {
+      this.okalitConnections();
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+
+    if (this._okalit_channel_unsubs.length > 0) {
+      this._okalit_channel_unsubs.forEach(unsub => unsub());
+      this._okalit_channel_unsubs = [];
+    }
+
+    if (this._okalit_listen_unsubs.length > 0) {
+      this._okalit_listen_unsubs.forEach(unsub => unsub());
+      this._okalit_listen_unsubs = [];
+    }
+
+    // Clean up @trigger decorator subscriptions
+    if (this._okalit_trigger_unsubs && this._okalit_trigger_unsubs.length > 0) {
+      this._okalit_trigger_unsubs.forEach(unsub => unsub());
+      this._okalit_trigger_unsubs = [];
+    }
+  }
+
+  output(eventName, detail) {
+    this.dispatchEvent(new CustomEvent(eventName, {
+      detail,
+      bubbles: true,
+      composed: true
+    }));
+  }
+
+  emit(event, data, options) {
+    EventBus.emit(event, data, options);
+  }
+
+  trigger(event, data) {
+    EventBus.trigger(event, data);
+  }
+
+  navigate(path, args) {
+    EventBus.trigger('okalit-route:navigate', { path, args });
+  }
+
+  // Called by the router to inject route + query params.
+  // Coerces values to the types declared in defineElement({ params }).
+  set routeParams(obj) {
+    if (!obj || typeof obj !== 'object') return;
+    const schema = this.constructor.__okalitParams;
+    for (const [key, raw] of Object.entries(obj)) {
+      if (schema && schema[key]) {
+        const typeCtor = schema[key].type;
+        if (typeCtor === Number)       this[key] = Number(raw);
+        else if (typeCtor === Boolean) this[key] = raw === 'true' || raw === '1' || raw === true;
+        else                           this[key] = String(raw);
+      } else {
+        // No schema — assign as-is (string from URL)
+        this[key] = raw;
+      }
+    }
+  }
+
+  listen(event, callback) {
+    const unsub = EventBus.listen(event, callback.bind(this));
+    this._okalit_listen_unsubs.push(unsub);
+  }
+
+  t(key, params) {
+    return OkalitI18n.t(key, params);
+  }
+
+  channel(event, { persist = 'memory', initialValue, onValue } = {}) {
+    const currentValue = EventBus.get(event, { persist, fallback: initialValue });
+    const s = signal(currentValue);
+
+    const handleValue = (val) => {
+      s.set(val);
+      if (typeof onValue === 'function') {
+        onValue.call(this, val);
+      }
+      this.requestUpdate();
+    };
+
+    // Subscribe to channel changes
+    const unsub = EventBus.on(event, handleValue, {
+      persist,
+      immediate: false,
+    });
+
+    this._okalit_channel_unsubs.push(unsub);
+
+    if (typeof onValue === 'function') {
+      onValue.call(this, currentValue);
+    }
+
+    return {
+      get: () => s.get(),
+      set: (v) => {
+        s.set(v);
+        EventBus.emit(event, v, { persist });
+      }
+    };
+  }
+}

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

@@ -0,0 +1,145 @@
+import { EventBus } from './EventBus.js';
+
+export class OkalitService {
+  constructor() {
+    this.baseUrl = '';
+    this.headers = {};
+    this.__cache = new Map();
+    this.__debounceTimers = new Map();
+    this.__activeRequests = new Map();
+  }
+
+  _makeCacheKey(path, params) {
+    let key = path;
+    if (params && typeof params === 'object') {
+      key += '?' + Object.entries(params).sort().map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&');
+    }
+    return key;
+  }
+
+  _debounce(cacheKey, delay, fn) {
+    if (this.__debounceTimers.has(cacheKey)) {
+      clearTimeout(this.__debounceTimers.get(cacheKey));
+    }
+    return new Promise((resolve, reject) => {
+      this.__debounceTimers.set(cacheKey, setTimeout(async () => {
+        this.__debounceTimers.delete(cacheKey);
+        try { resolve(await fn()); }
+        catch (err) { reject(err); }
+      }, delay));
+    });
+  }
+
+  async _parseJson(res, path) {
+    try {
+      return await res.json();
+    } catch {
+      const err = new Error(`Failed to parse JSON response from ${path} (HTTP ${res.status})`);
+      err.status = res.status;
+      throw err;
+    }
+  }
+
+  _buildUrl(path, params) {
+    let url = this.baseUrl + path;
+    if (params && typeof params === 'object') {
+      const qs = Object.entries(params)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join('&');
+      if (qs) url += (url.includes('?') ? '&' : '?') + qs;
+    }
+    return url;
+  }
+
+  // Abort any in-flight request for the same cache key
+  abort(cacheKey) {
+    const controller = this.__activeRequests.get(cacheKey);
+    if (controller) {
+      controller.abort();
+      this.__activeRequests.delete(cacheKey);
+    }
+  }
+
+  // Unified request method — eliminates duplication across get/post/put/delete
+  async _request(method, path, opts = {}, body = undefined) {
+    const {
+      onSuccess, onError, cache = false, force = false, params = undefined,
+      debounce = 0, transform = undefined, headers = undefined, timeout = 30000,
+    } = opts;
+    const cacheKey = `${method}:${this._makeCacheKey(path, params)}`;
+
+    if (debounce > 0) {
+      return this._debounce(cacheKey, debounce, () =>
+        this._request(method, path, { ...opts, debounce: 0 }, body)
+      );
+    }
+
+    if (cache && !force && this.__cache.has(cacheKey)) {
+      const cached = this.__cache.get(cacheKey);
+      if (onSuccess) setTimeout(() => EventBus.trigger(onSuccess, cached), 0);
+      return cached;
+    }
+
+    const url = this._buildUrl(path, params);
+    const controller = new AbortController();
+    this.abort(cacheKey);
+    this.__activeRequests.set(cacheKey, controller);
+
+    const timeoutId = timeout > 0
+      ? setTimeout(() => controller.abort(), timeout)
+      : null;
+
+    const fetchOpts = {
+      method,
+      headers: {
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...this.headers,
+        ...headers,
+      },
+      signal: controller.signal,
+    };
+    if (body !== undefined) fetchOpts.body = JSON.stringify(body);
+
+    try {
+      const res = await fetch(url, fetchOpts);
+
+      // Validate HTTP status before parsing
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} ${res.statusText} on ${method} ${path}`);
+        err.status = res.status;
+        err.response = res;
+        throw err;
+      }
+
+      let data = await this._parseJson(res, path);
+      if (transform && typeof transform === 'function') {
+        data = transform(data);
+      }
+      if (cache) this.__cache.set(cacheKey, data);
+      if (onSuccess) EventBus.trigger(onSuccess, data);
+      return data;
+    } catch (err) {
+      if (onError) EventBus.trigger(onError, err);
+      throw err;
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+      this.__activeRequests.delete(cacheKey);
+    }
+  }
+
+  get(path, opts = {}) {
+    return this._request('GET', path, opts);
+  }
+
+  post(path, body, opts = {}) {
+    return this._request('POST', path, opts, body);
+  }
+
+  put(path, body, opts = {}) {
+    return this._request('PUT', path, opts, body);
+  }
+
+  delete(path, opts = {}) {
+    return this._request('DELETE', path, opts);
+  }
+}

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

@@ -0,0 +1,65 @@
+// src/core/defineElement.js
+import { css, unsafeCSS } from 'lit';
+import { injectServices } from './service.js';
+
+// Convert PascalCase or camelCase to kebab-case
+function toKebabCase(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/([A-Z])([A-Z][a-z])/g, '$1-$2').toLowerCase();
+}
+
+// Custom element tags must contain a hyphen and only valid characters
+const VALID_CE_TAG = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+
+export function defineElement({ styles, tag, props, params, inject, template } = {}) {
+  return function (target) {
+    if (styles) {
+      const arr = Array.isArray(styles) ? styles : [styles];
+      target.styles = arr.map(s => {
+        if (typeof s === 'string') return css`${unsafeCSS(s)}`;
+        return s;
+      });
+    }
+
+    if (props)
+      target.properties = Object.assign({}, target.properties, props);
+
+    // Route params: register as Lit properties so they get default values
+    // and participate in the reactive update cycle.
+    if (params && typeof params === 'object') {
+      // Store the params schema so the routeParams setter can coerce types
+      target.__okalitParams = params;
+      target.properties = Object.assign({}, target.properties, params);
+    }
+
+    // Service injection support
+    if (inject && Array.isArray(inject)) {
+      const orig = target.prototype.connectedCallback;
+      target.prototype.connectedCallback = function () {
+        injectServices(this, inject);
+        if (orig) orig.call(this);
+      };
+    }
+
+    // Decoupled template: overrides the prototype's render method.
+    // When Lit calls this.render(), the context is the component instance.
+    if (template && typeof template === 'function') {
+      target.prototype.render = template;
+    }
+    // If no template is provided, Lit uses the render() defined in the class.
+
+    let finalTag = tag;
+    if (!finalTag)
+      finalTag = toKebabCase(target.name);
+
+    // Validate tag name to prevent malformed or dangerous custom element names
+    if (finalTag && !VALID_CE_TAG.test(finalTag)) {
+      console.error(`defineElement: invalid custom element tag "${finalTag}"`);
+      return target;
+    }
+
+    // Skip if already defined (prevents DOMException during Vite HMR)
+    if (finalTag && !window.customElements.get(finalTag)) {
+      window.customElements.define(finalTag, target);
+    }
+  };
+}

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

@@ -0,0 +1,89 @@
+import { EventBus } from './EventBus.js';
+import { signal } from '@lit-labs/signals';
+
+class OkalitI18nImpl {
+  constructor() {
+    this._translations = Object.create(null);
+    this._locale = signal('');
+    this._config = null;
+    this._ready = false;
+  }
+
+  async init(config) {
+    this._config = {
+      default: config.default || 'es',
+      locales: config.locales || [],
+      path: config.path || '/i18n',
+    };
+
+    const persisted = localStorage.getItem('okalit:i18n:locale');
+    const initialLocale = (persisted && this._config.locales.includes(persisted))
+      ? persisted
+      : this._config.default;
+
+    await this._loadLocale(initialLocale);
+    this._locale.set(initialLocale);
+    this._ready = true;
+
+    EventBus.emit('i18n:ready', { locale: initialLocale });
+
+    // Allow locale switching via EventBus
+    EventBus.listen('i18n:set-locale', ({ locale }) => this.setLocale(locale));
+  }
+
+  async _loadLocale(locale) {
+    if (this._translations[locale]) return;
+
+    const path = `${this._config.path}/${locale}.json`;
+    try {
+      const res = await fetch(path);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      this._translations[locale] = await res.json();
+    } catch (e) {
+      console.error(`[OkalitI18n] Failed to load locale "${locale}" from ${path}:`, e);
+      this._translations[locale] = {};
+    }
+  }
+
+  async setLocale(locale) {
+    if (!this._config?.locales.includes(locale)) {
+      console.warn(`[OkalitI18n] Locale "${locale}" is not configured. Available: ${this._config?.locales}`);
+      return;
+    }
+
+    await this._loadLocale(locale);
+    this._locale.set(locale);
+    localStorage.setItem('okalit:i18n:locale', locale);
+    EventBus.emit('i18n:locale-changed', { locale });
+  }
+
+  get locale() {
+    return this._locale.get();
+  }
+
+  get locales() {
+    return this._config?.locales || [];
+  }
+
+  t(key, params) {
+    // Reading the signal value triggers SignalWatcher tracking
+    const locale = this._locale.get();
+    const dict = this._translations[locale] || {};
+
+    // Nested key support: "home.welcome.title" → dict.home.welcome.title
+    let value = key.split('.').reduce((obj, k) => obj?.[k], dict);
+
+    if (value === undefined) {
+      return key;
+    }
+
+    // Interpolation: "Hola {name}" + { name: "Alex" } → "Hola Alex"
+    if (params && typeof value === 'string') {
+      value = value.replace(/\{(\w+)\}/g, (_, k) => (k in params) ? params[k] : `{${k}}`);
+    }
+
+    return value;
+  }
+}
+
+export const OkalitI18n = new OkalitI18nImpl();

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

@@ -0,0 +1,40 @@
+// src/core/idle.js
+import { html } from 'lit';
+
+export function idle({ template = () => html`<p>Loading...</p>`, dynamicLoader = [] } = {}) {
+  return (_, context) => {
+    context.addInitializer(function () {
+      const methodName = context.name;
+      const loaders = Array.isArray(dynamicLoader) ? dynamicLoader : [dynamicLoader];
+      this[`__${methodName}_loaded`] = false;
+      this[`__${methodName}_loading`] = false;
+
+      // Override the original method
+      const originalMethod = this[methodName];
+      this[methodName] = (...args) => {
+        if (this[`__${methodName}_loaded`]) {
+          return originalMethod.apply(this, args);
+        }
+        if (!this[`__${methodName}_loading`]) {
+          this[`__${methodName}_loading`] = true;
+          const load = () => {
+            Promise.all(loaders.map(fn => fn())).then(() => {
+              this[`__${methodName}_loaded`] = true;
+              this.requestUpdate && this.requestUpdate();
+            }).catch(err => {
+              this[`__${methodName}_loading`] = false;
+              console.error(`idle("${methodName}"): loader failed`, err);
+            });
+          };
+          if ('requestIdleCallback' in window) {
+            window.requestIdleCallback(load);
+          } else {
+            // Fallback when requestIdleCallback is not available
+            setTimeout(load, 200);
+          }
+        }
+        return template();
+      };
+    });
+  };
+}

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

@@ -0,0 +1,10 @@
+export { Okalit } from  './Okalit.js';
+export { defineElement } from './defineElement.js';
+export { AppMixin } from './AppMixin.js';
+export { ModuleMixin } from './ModuleMixin.js';
+export { OkalitService } from './OkalitService.js';
+export { idle } from './idle.js';
+export { lazy} from './lazy.js';
+export { when } from './when.js';
+export { service, getService, injectServices } from './service.js';
+export { OkalitI18n } from './i18n.js';

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

@@ -0,0 +1,32 @@
+// src/core/lazy.js
+import { html } from 'lit';
+
+export function lazy({ template = () => html`<p>Loading...</p>`, dynamicLoader = [] } = {}) {
+  return (_, context) => {
+    context.addInitializer(function () {
+      const methodName = context.name;
+      const loaders = Array.isArray(dynamicLoader) ? dynamicLoader : [dynamicLoader];
+      this[`__${methodName}_loaded`] = false;
+      this[`__${methodName}_loading`] = false;
+
+      // Override the original method
+      const originalMethod = this[methodName];
+      this[methodName] = (...args) => {
+        if (this[`__${methodName}_loaded`]) {
+          return originalMethod.apply(this, args);
+        }
+        if (!this[`__${methodName}_loading`]) {
+          this[`__${methodName}_loading`] = true;
+          Promise.all(loaders.map(fn => fn())).then(() => {
+            this[`__${methodName}_loaded`] = true;
+            this.requestUpdate && this.requestUpdate();
+          }).catch(err => {
+            this[`__${methodName}_loading`] = false;
+            console.error(`lazy("${methodName}"): loader failed`, err);
+          });
+        }
+        return template();
+      };
+    });
+  };
+}