@okalit/cli 0.1.0

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

@@ -0,0 +1,309 @@
+import { LitElement } from 'lit';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
+import { EventBus } from './EventBus.js';
+
+// Valid custom element tag: lowercase, must contain at least one hyphen
+const VALID_CE_TAG = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+
+// Normalize a URL path: collapse repeated slashes, strip trailing slash
+function sanitizePath(path) {
+  let p = path.replace(/\/+/g, '/');
+  if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  return p;
+}
+
+// Parse query string into a plain object
+function parseQueryString(search) {
+  const params = {};
+  if (!search) return params;
+  const qs = search.startsWith('?') ? search.slice(1) : search;
+  if (!qs) return params;
+  for (const pair of qs.split('&')) {
+    const idx = pair.indexOf('=');
+    if (idx === -1) continue;
+    const key = decodeURIComponent(pair.slice(0, idx));
+    const val = decodeURIComponent(pair.slice(idx + 1));
+    params[key] = val;
+  }
+  return params;
+}
+
+// Try to match a single route pattern (which may contain :param segments)
+// against an actual path. Returns extracted params or null on mismatch.
+function matchSegments(pattern, path) {
+  const patternParts = pattern.split('/').filter(Boolean);
+  const pathParts = path.split('/').filter(Boolean);
+  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;
+}
+
+function matchRoute(path, routes, basePath = '') {
+  for (const route of routes) {
+    let fullPath = basePath;
+    if (route.path && route.path !== '') {
+      if (!fullPath.endsWith('/')) fullPath += '/';
+      fullPath += route.path.replace(/^\//, '');
+    }
+    if (fullPath.length > 1 && fullPath.endsWith('/')) fullPath = fullPath.slice(0, -1);
+
+    // Try exact match first, then pattern match for :param segments
+    const isExact = fullPath === path;
+    const segmentParams = !isExact ? matchSegments(fullPath, path) : {};
+
+    if (isExact || segmentParams) {
+      if (route.children) {
+        const match = matchRoute(path, route.children, fullPath);
+        if (match) {
+          return {
+            route: match.route,
+            parents: [route, ...match.parents],
+            params: { ...segmentParams, ...match.params }
+          };
+        }
+        const defaultChild = route.children.find(c => c.path === '');
+        if (defaultChild) {
+          return { route: defaultChild, parents: [route], params: segmentParams || {} };
+        }
+      }
+      return { route, parents: [], params: segmentParams || {} };
+    }
+    if (route.children) {
+      const match = matchRoute(path, route.children, fullPath);
+      if (match) {
+        return {
+          route: match.route,
+          parents: [route, ...match.parents],
+          params: match.params
+        };
+      }
+    }
+  }
+  return null;
+}
+
+export class OkalitRouter extends LitElement {
+  static properties = {
+    routes: { type: Array },
+    guards: { type: Array },
+    interceptors: { type: Array },
+    currentRoute: { type: Object },
+    params: { type: Object },
+  };
+
+  constructor() {
+    super();
+    this._guards = [];
+    this._interceptors = [];
+    this._routes = [];
+    this.currentRoute = null;
+    this.params = {};
+    this._listenBus();
+    this._boundPopState = () => this._onPopState();
+    window.addEventListener('popstate', this._boundPopState);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    window.removeEventListener('popstate', this._boundPopState);
+    if (this._busUnsubs) {
+      this._busUnsubs.forEach(unsub => unsub());
+      this._busUnsubs = [];
+    }
+  }
+
+  /**
+   * Runs once after the component has rendered and received all initial
+   * properties (routes, guards, etc.)
+   */
+  firstUpdated() {
+    this._navigate(window.location.pathname);
+  }
+
+  set routes(val) {
+    this._routes = val;
+    // Only auto-navigate if the component has already been initially rendered.
+    // On first load, firstUpdated() handles navigation.
+    if (this.hasUpdated) {
+      this._navigate(window.location.pathname);
+    }
+  }
+  get routes() {
+    return this._routes;
+  }
+
+  set guards(val) {
+    this._guards = Array.isArray(val) ? val : [];
+  }
+  get guards() {
+    return this._guards;
+  }
+  
+  set interceptors(val) {
+    this._interceptors = Array.isArray(val) ? val : [];
+  }
+  get interceptors() {
+    return this._interceptors;
+  }
+
+  _listenBus() {
+    this._busUnsubs = [];
+    this._busUnsubs.push(
+      EventBus.listen('okalit-route:navigate', ({ path, args }) => {
+        this.navigate(path, args);
+      })
+    );
+    this._busUnsubs.push(
+      EventBus.listen('okalit-route:back', () => {
+        window.history.back();
+      })
+    );
+  }
+
+  async _runGuards(guardsList, path, args) {
+    const list = guardsList || [];
+    for (const guard of list) {
+      const result = await guard(path, args);
+      
+      // Support { allow: false, redirect: '...' }
+      if (result && typeof result === 'object' && result.allow === false) {
+        return result; 
+      }
+      
+      // Legacy support: return false
+      if (result === false) {
+        return { allow: false };
+      }
+    }
+    return { allow: true };
+  }
+
+  async navigate(path, args) {
+    const safePath = sanitizePath(path);
+    const success = await this._navigate(safePath, args);
+    if (success) {
+      // Preserve query string in the URL if present
+      const qsIdx = path.indexOf('?');
+      const fullUrl = qsIdx !== -1 ? safePath + path.slice(qsIdx) : safePath;
+      window.history.pushState({}, '', fullUrl);
+      EventBus.clearAll({ persist: 'memory' });
+    }
+  }
+
+  async _navigate(path, args) {
+    const safePath = sanitizePath(path);
+
+    // 1. Global guards
+    const globalCheck = await this._runGuards(this._guards, safePath, args);
+    if (!globalCheck.allow) {
+      if (globalCheck.redirect) {
+        this.navigate(globalCheck.redirect);
+      }
+      return false;
+    }
+
+    // 2. Route matching (extracts :param values from path segments)
+    const match = matchRoute(safePath, this.routes);
+    if (!match) {
+      this.currentRoute = null;
+      this.parents = [];
+      this.params = {};
+      this.requestUpdate();
+      return false;
+    }
+
+    const { route, parents, params: routeParams } = match;
+
+    // 3. Merge route params with query string params.
+    //    Route params (:id) take priority over query params (?id=).
+    const queryParams = parseQueryString(window.location.search);
+    this.params = { ...queryParams, ...routeParams };
+
+    // 4. Route-level guards
+    if (route.guard) {
+      const routeCheck = await this._runGuards([route.guard], safePath, args);
+      if (!routeCheck.allow) {
+        if (routeCheck.redirect) {
+          this.navigate(routeCheck.redirect);
+        }
+        return false;
+      }
+    }
+
+    // 5. Dynamic imports (only after guards pass).
+    //    parents is already ordered outermost-first from matchRoute.
+    for (const r of [...parents, route]) {
+      if (r.import) await r.import();
+      if (r.childrens && !r.children) {
+        const mod = await r.childrens();
+        r.children = mod.default || mod.routes || mod;
+      }
+    }
+
+    this.currentRoute = route;
+    this.parents = parents;
+    this.requestUpdate();
+    return true;
+  }
+
+  _onPopState() {
+    this._navigate(window.location.pathname);
+  }
+
+  addGuard(guard) {
+    this._guards.push(guard);
+  }
+  addInterceptor(interceptor) {
+    this._interceptors.push(interceptor);
+  }
+
+  _renderNested(parents, route) {
+    if (!route) return staticHtml``;
+    const tag = route.component;
+
+    // Validate custom element tag to prevent injection via unsafeStatic
+    if (!VALID_CE_TAG.test(tag)) {
+      console.error(`OkalitRouter: invalid component tag "${tag}"`);
+      return staticHtml``;
+    }
+
+    if (parents.length === 0) {
+      return staticHtml`<${unsafeStatic(tag)}></${unsafeStatic(tag)}>`;
+    }
+    const [parent, ...rest] = parents;
+    const parentTag = parent.component;
+
+    if (!VALID_CE_TAG.test(parentTag)) {
+      console.error(`OkalitRouter: invalid component tag "${parentTag}"`);
+      return staticHtml``;
+    }
+
+    return staticHtml`<${unsafeStatic(parentTag)}>
+      ${this._renderNested(rest, route)}
+    </${unsafeStatic(parentTag)}>`;
+  }
+
+  // After each render, find the leaf component and inject route params
+  updated() {
+    if (!this.currentRoute || !this.params) return;
+    const tag = this.currentRoute.component;
+    const leaf = this.renderRoot.querySelector(tag);
+    if (leaf && typeof leaf === 'object') {
+      leaf.routeParams = this.params;
+    }
+  }
+
+  render() {
+    if (!this.currentRoute) return staticHtml``;
+    return this._renderNested(this.parents || [], this.currentRoute);
+  }
+}
+
+customElements.define('okalit-router', OkalitRouter);

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

@@ -0,0 +1,33 @@
+// src/core/service.js
+// Vanilla JS decorator for service registration and DI
+
+const __serviceRegistry = new Map();
+
+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());
+  };
+}
+
+export function getService(name) {
+  return __serviceRegistry.get(name);
+}
+
+// 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,
+      });
+    }
+  });
+}

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

@@ -0,0 +1,14 @@
+// src/core/trigger.js
+import { EventBus } from './EventBus.js';
+
+export function trigger(event) {
+  return (target, context) => {
+    context.addInitializer(function () {
+      // Subscribe the decorated method to the global trigger
+      this._okalit_trigger_unsubs = this._okalit_trigger_unsubs || [];
+      const unsub = EventBus.listen(event, this[context.name].bind(this));
+      this._okalit_trigger_unsubs.push(unsub);
+    });
+    // Cleanup is handled centrally in Okalit.disconnectedCallback
+  };
+}

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

@@ -0,0 +1,69 @@
+// src/core/viewport.js
+import { html } from 'lit';
+
+export function viewport({ template = () => html`<p>Loading...</p>`, dynamicLoader = [] } = {}) {
+  return (target, context) => {
+    context.addInitializer(function () {
+      const methodName = context.name;
+      const loaders = Array.isArray(dynamicLoader) ? dynamicLoader : [dynamicLoader];
+      this[`__${methodName}_loaded`] = false;
+      this[`__${methodName}_loading`] = false;
+      this[`__${methodName}_observer`] = null;
+
+      // 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(`viewport("${methodName}"): loader failed`, err);
+          });
+        }
+        return template();
+      };
+
+      // Set up IntersectionObserver to trigger loading on visibility
+      const setupObserver = () => {
+        if (this[`__${methodName}_observer`]) return;
+        this[`__${methodName}_observer`] = new IntersectionObserver(entries => {
+          if (entries[0].isIntersecting) {
+            this[`__${methodName}_observer`].disconnect();
+            this[`__${methodName}_observer`] = null;
+            this[methodName](); // Trigger load
+          }
+        });
+        // Wait for the component to be in the DOM
+        requestAnimationFrame(() => {
+          const el = this.renderRoot?.querySelector(`[data-viewport="${methodName}"]`);
+          if (el) {
+            this[`__${methodName}_observer`].observe(el);
+          }
+        });
+      };
+
+      // Attach observer on first render
+      const origFirstUpdated = this.firstUpdated;
+      this.firstUpdated = function (...args) {
+        setupObserver.call(this);
+        origFirstUpdated && origFirstUpdated.apply(this, args);
+      };
+
+      // Clean up observer on disconnect to prevent memory leaks
+      const origDisconnected = this.disconnectedCallback;
+      this.disconnectedCallback = function (...args) {
+        if (this[`__${methodName}_observer`]) {
+          this[`__${methodName}_observer`].disconnect();
+          this[`__${methodName}_observer`] = null;
+        }
+        origDisconnected && origDisconnected.apply(this, args);
+      };
+    });
+  };
+}

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

@@ -0,0 +1,40 @@
+// src/core/when.js
+import { html } from 'lit';
+
+export function when({ template = () => html`<p>Loading...</p>`, dynamicLoader = [], condition = () => false } = {}) {
+  return (target, 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 condition is false, reset state and show the placeholder
+        if (!condition.call(this)) {
+          this[`__${methodName}_loaded`] = false;
+          this[`__${methodName}_loading`] = false;
+          return template();
+        }
+        // Already loaded — render original content
+        if (this[`__${methodName}_loaded`]) {
+          return originalMethod.apply(this, args);
+        }
+        // Start loading
+        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(`when("${methodName}"): loader failed`, err);
+          });
+        }
+        return template();
+      };
+    });
+  };
+}

package/templates/app/babel.config.json

@@ -0,0 +1,5 @@
+{
+  "plugins": [
+    ["@babel/plugin-proposal-decorators", { "version": "2023-05", "decoratorsBeforeExport": true }]
+  ]
+}

package/templates/app/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<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>
+    <link rel="stylesheet" href="./src/styles/index.css" />
+    <script type="module" src="/src/main-app.js"></script>
+  </head>
+  <body>
+    <main-app></main-app>
+  </body>
+</html>

package/templates/app/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "okalit-app",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@lit-labs/signals": "^0.2.0",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-proposal-decorators": "^7.29.0",
+    "@babel/preset-env": "^7.29.0",
+    "sass": "^1.97.3",
+    "vite": "^7.3.1",
+    "vite-plugin-babel": "^1.5.1"
+  }
+}

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

@@ -0,0 +1,3 @@
+{
+    "WELCOME": "Welcome to Okalit Template"
+}

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

@@ -0,0 +1,3 @@
+{
+    "WELCOME": "Bienvenido a la plantilla de Okalit"
+}

package/templates/app/public/lit.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="25.6" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 320"><path fill="#00E8FF" d="m64 192l25.926-44.727l38.233-19.114l63.974 63.974l10.833 61.754L192 320l-64-64l-38.074-25.615z"></path><path fill="#283198" d="M128 256V128l64-64v128l-64 64ZM0 256l64 64l9.202-60.602L64 192l-37.542 23.71L0 256Z"></path><path fill="#324FFF" d="M64 192V64l64-64v128l-64 64Zm128 128V192l64-64v128l-64 64ZM0 256V128l64 64l-64 64Z"></path><path fill="#0FF" d="M64 320V192l64 64z"></path></svg>

package/templates/app/src/app.routes.ts

@@ -0,0 +1,10 @@
+import ExampleModuleRoutes from "./modules/example/example.routes.js";
+
+export default [
+  {
+    path: "/",
+    component: "example-module",
+    import: () => import("./modules/example/example.module.js"),
+    children: ExampleModuleRoutes,
+  }
+];

package/templates/app/src/main-app.js

@@ -0,0 +1,13 @@
+import { Okalit, defineElement, AppMixin } from '@okalit';
+import routes from './app.routes.ts';
+
+@defineElement({ tag: 'main-app' })
+export class MainApp extends AppMixin(Okalit) {
+  _appConfig = {
+    routes,
+    i18n: {
+      default: 'es',
+      locales: ['es', 'en'],
+    },
+  }
+}

package/templates/app/src/modules/example/example.module.js

@@ -0,0 +1,4 @@
+import { ModuleMixin, Okalit, defineElement } from '@okalit';
+
+@defineElement({ tag: 'example-module' })
+export class ExampleModule extends ModuleMixin(Okalit) {}

package/templates/app/src/modules/example/example.routes.js

@@ -0,0 +1,7 @@
+export default [
+  {
+    path: '',
+    component: 'example-page',
+    import: () => import('./pages/example.page.js')
+  }
+];

package/templates/app/src/modules/example/pages/example.page.js

@@ -0,0 +1,43 @@
+import { html } from "lit";
+import { Okalit, defineElement } from "@okalit";
+
+import styles from "./example.page.scss?inline";
+import global from "@styles/global.scss?inline";
+
+@defineElement({
+  tag: "example-page",
+  styles: [styles, global]
+})
+export class ExamplePage extends Okalit {
+  counter = this.channel('demo:counter', {
+    initialValue: 0
+  });
+
+  increment() {
+    this.emit('demo:counter', this.counter.get() + 1);
+  }
+
+  decrement() {
+    this.emit('demo:counter', this.counter.get() - 1);
+  }
+
+  render() {
+    return html`
+      <div class="counter-card">
+        <h1>${this.t('WELCOME')}</h1>
+        <p>${this.t('DESCRIPTION')}</p>
+        
+        <span class="count-display">${this.counter.get()}</span>
+        
+        <div class="controls">
+          <button class="btn-decrement" @click="${this.decrement}">
+            ${this.t('DECREMENT')}
+          </button>
+          <button class="btn-increment" @click="${this.increment}">
+            ${this.t('INCREMENT')}
+          </button>
+        </div>
+      </div>
+    `;
+  }
+}

package/templates/app/src/modules/example/pages/example.page.scss

@@ -0,0 +1,76 @@
+:host {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 100vh;
+  font-family: "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: #333;
+}
+
+.counter-card {
+  background: white;
+  padding: 3rem;
+  border-radius: 20px;
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
+  text-align: center;
+  transition: transform 0.2s ease;
+}
+
+.counter-card:hover {
+  transform: translateY(-5px);
+}
+
+h1 {
+  margin: 0 0 1rem 0;
+  font-size: 2rem;
+  color: #4a5568;
+}
+
+p {
+  color: #718096;
+  margin-bottom: 2rem;
+}
+
+.count-display {
+  font-size: 4rem;
+  font-weight: bold;
+  color: #5a67d8;
+  margin-bottom: 2rem;
+  display: block;
+}
+
+.controls {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+}
+
+button {
+  padding: 10px 20px;
+  font-size: 1rem;
+  font-weight: 600;
+  border: none;
+  border-radius: 10px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.btn-decrement {
+  background-color: #edf2f7;
+  color: #4a5568;
+}
+
+.btn-decrement:hover {
+  background-color: #e2e8f0;
+}
+
+.btn-increment {
+  background-color: #5a67d8;
+  color: white;
+}
+
+.btn-increment:hover {
+  background-color: #4c51bf;
+  box-shadow: 0 4px 12px rgba(90, 103, 216, 0.3);
+}