ladrillosjs 2.0.0-beta.3.7 → 2.0.0-beta.4

package/README.md

@@ -31,6 +31,7 @@ A lightweight, zero-dependency web component framework for building modular web
   - [Shadow DOM](#shadow-dom)
   - [Styling Components](#styling-components)
   - [Performance & Caching](#performance--caching)
+- [Creating Component Libraries](#creating-component-libraries)
 - [Common Patterns](#common-patterns)
   - [Keyboard Events](#keyboard-events)
   - [Form Validation](#form-validation)
@@ -1594,6 +1595,117 @@ LadrillosJS includes built-in performance optimizations:
 - Event listeners are automatically cleaned up
 - Conditional rendering skips hidden elements
 
+## Creating Component Libraries
+
+LadrillosJS makes it easy to create and publish reusable component libraries. Developers can use your components in their projects with full TypeScript support.
+
+### Quick Example
+
+**Create a library:**
+
+```typescript
+// src/types/index.ts - Define interfaces
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary';
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export interface AwesomeButton extends HTMLElement {
+  variant?: ButtonProps['variant'];
+  size?: ButtonProps['size'];
+  setLoading(state: boolean): void;
+}
+
+// src/components/Button/button.html
+<button class="btn-{variant}" onclick="handleClick()">
+  <slot>{label}</slot>
+</button>
+
+<script>
+  let variant = this.getAttribute('variant') || 'primary';
+  let label = this.getAttribute('label') || 'Click';
+
+  export const handleClick = () => {
+    $emit('button:click', { timestamp: Date.now() });
+  };
+</script>
+
+// src/index.ts - Export registry
+export * from './types';
+export * from './components/Button';
+
+export const AWESOME_COMPONENTS = [
+  { name: 'awesome-button', path: './components/Button/button.html' }
+];
+
+export const registerAwesomeComponents = async () => {
+  const { registerComponents } = await import('ladrillosjs');
+  return registerComponents(AWESOME_COMPONENTS);
+};
+```
+
+**Consumers use it:**
+
+```typescript
+import {
+  registerAwesomeComponents,
+  createButton,
+  type AwesomeButton,
+} from "@awesome/ui";
+
+// Register all components
+await registerAwesomeComponents();
+
+// Use in HTML
+<awesome-button variant="primary" label="Click Me"></awesome-button>;
+
+// Or programmatically with types
+const btn = createButton() as AwesomeButton;
+btn.setAttribute("variant", "secondary");
+btn.setLoading(true);
+
+// Type-safe events
+btn.addEventListener("button:click", (e) => {
+  console.log("Clicked:", e.detail.timestamp);
+});
+```
+
+### Key Features for Libraries
+
+✅ **TypeScript Interfaces** - Full type definitions for all props, events, and methods  
+✅ **Component Registry** - Easy batch registration  
+✅ **Helper Functions** - `createButton()`, `configureCard()`, etc.  
+✅ **Metadata Export** - Component documentation and metadata  
+✅ **Multiple Formats** - ESM, CJS, UMD outputs  
+✅ **Tree-Shakeable** - Only import what you use
+
+### Creating Your Library
+
+1. **Define TypeScript interfaces** for props, events, and typed element references
+2. **Create single-file `.html` components** with template, styles, and scripts
+3. **Export helper functions** for programmatic component creation
+4. **Create component registry** for batch registration
+5. **Configure package.json** with exports field for subpath imports
+6. **Build and publish** to NPM
+
+### Example Projects
+
+- **[Full Example Library](samples/component-library/)** - Complete Button, Card, Modal components with TypeScript
+- **[Library Demo App](samples/apps/component-library-demo/)** - Shows all usage patterns and integrations
+
+### Complete Guide
+
+For detailed instructions on creating, building, and publishing component libraries, see the **[Library Authoring Guide](docs/LIBRARY_AUTHORING.md)**.
+
+Topics covered:
+
+- Project structure and best practices
+- Component creation with HTML + TypeScript
+- Building with Vite
+- Publishing to NPM
+- Consumer usage examples
+- React/Vue integration patterns
+
 ## Common Patterns
 
 ### Keyboard Events

package/dist/{index-DZqKSX8_.mjs → index-BcPgsuUl.mjs}

@@ -1,21 +1,21 @@
-var I = Object.defineProperty, B = Object.defineProperties;
-var D = Object.getOwnPropertyDescriptors;
+var D = Object.defineProperty, B = Object.defineProperties;
+var W = Object.getOwnPropertyDescriptors;
 var P = Object.getOwnPropertySymbols;
-var W = Object.prototype.hasOwnProperty, O = Object.prototype.propertyIsEnumerable;
+var O = Object.prototype.hasOwnProperty, J = Object.prototype.propertyIsEnumerable;
 var k = (t) => {
   throw TypeError(t);
 };
-var _ = (t, e, r) => e in t ? I(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r, h = (t, e) => {
+var _ = (t, e, r) => e in t ? D(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r, h = (t, e) => {
   for (var r in e || (e = {}))
-    W.call(e, r) && _(t, r, e[r]);
+    O.call(e, r) && _(t, r, e[r]);
   if (P)
     for (var r of P(e))
-      O.call(e, r) && _(t, r, e[r]);
+      J.call(e, r) && _(t, r, e[r]);
   return t;
-}, w = (t, e) => B(t, D(e));
-var J = (t, e, r) => e.has(t) || k("Cannot " + r);
+}, w = (t, e) => B(t, W(e));
+var K = (t, e, r) => e.has(t) || k("Cannot " + r);
 var L = (t, e, r) => e.has(t) ? k("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(t) : e.set(t, r);
-var E = (t, e, r) => (J(t, e, "access private method"), r);
+var v = (t, e, r) => (K(t, e, "access private method"), r);
 var p = (t, e, r) => new Promise((s, o) => {
   var i = (c) => {
     try {
@@ -32,7 +32,7 @@ var p = (t, e, r) => new Promise((s, o) => {
   }, l = (c) => c.done ? s(c.value) : Promise.resolve(c.value).then(i, a);
   l((r = r.apply(t, e)).next());
 });
-const j = () => {
+const z = () => {
   try {
     return !1;
   } catch (t) {
@@ -45,7 +45,7 @@ const j = () => {
    * @param args - Additional arguments to log
    */
   log(t, ...e) {
-    j() && console.log(t, ...e);
+    z() && console.log(t, ...e);
   },
   /**
    * Log an error (always logs in both dev and production)
@@ -61,9 +61,9 @@ const j = () => {
    * @param args - Additional arguments to log
    */
   warn(t, ...e) {
-    j() && console.warn(t, ...e);
+    z() && console.warn(t, ...e);
   }
-}, f = (t, e) => {
+}, g = (t, e) => {
   const r = [t];
   return e && (e.componentName && r.push(`
   Component: <${e.componentName}>`), e.componentPath && r.push(`
@@ -74,7 +74,7 @@ const j = () => {
   Element: <${e.elementTag}>`), e.lineHint && r.push(`
   Location: ${e.lineHint}`)), r.join("");
 }, me = (t, e, r) => {
-  const s = f(
+  const s = g(
     "⚠️ Binding Error: Failed to evaluate expression",
     w(h({}, r), {
       expression: t,
@@ -82,8 +82,8 @@ const j = () => {
     })
   );
   n.error(s), n.error(`  Error details: ${e.message}`), e.stack && console.debug("  Stack trace:", e.stack);
-}, ge = (t, e, r, s) => {
-  const o = f(
+}, fe = (t, e, r, s) => {
+  const o = g(
     "⚠️ Event Handler Error: Failed to execute handler",
     w(h({}, s), {
       eventType: t,
@@ -92,8 +92,8 @@ const j = () => {
     })
   );
   n.error(o), n.error(`  Error details: ${r.message}`), r.stack && console.debug("  Stack trace:", r.stack);
-}, fe = (t, e, r) => {
-  const s = f(
+}, ge = (t, e, r) => {
+  const s = g(
     "⚠️ Conditional Error: Failed to evaluate condition",
     w(h({}, r), {
       expression: t,
@@ -102,7 +102,7 @@ const j = () => {
   );
   n.error(s), n.error(`  Error details: ${e.message}`), e.stack && console.debug("  Stack trace:", e.stack);
 }, he = (t, e, r) => {
-  const s = f(
+  const s = g(
     "⚠️ Loop Error: Failed to process loop",
     w(h({}, r), {
       expression: t,
@@ -110,8 +110,8 @@ const j = () => {
     })
   );
   n.error(s), n.error(`  Error details: ${e.message}`), e.stack && console.debug("  Stack trace:", e.stack);
-}, z = (t, e, r) => {
-  const s = f(
+}, j = (t, e, r) => {
+  const s = g(
     "⚠️ Registration Error: Failed to register component",
     {
       componentName: t,
@@ -120,7 +120,7 @@ const j = () => {
   );
   n.error(s), n.error(`  Error details: ${r.message}`), r.stack && console.debug("  Stack trace:", r.stack);
 }, N = (t, e, r) => {
-  const s = f(
+  const s = g(
     "⚠️ Fetch Error: Failed to load resource",
     w(h({}, r), {
       componentPath: t
@@ -128,19 +128,19 @@ const j = () => {
   );
   n.error(s), n.error(`  Error details: ${e.message}`);
 }, x = (t, e) => {
-  const r = f(
+  const r = g(
     `⚠️ Parse Error: ${t}`,
     e
   );
   n.error(r);
 }, we = (t, e) => {
-  const r = f(
+  const r = g(
     "⚠️ Script Error: Failed to execute component script",
     e
   );
   n.error(r), n.error(`  Error details: ${t.message}`), t.stack && console.debug("  Stack trace:", t.stack);
 }, ye = (t, e, r) => {
-  const s = f(
+  const s = g(
     "⚠️ Two-Way Binding Error: Failed to setup binding",
     w(h({}, r), {
       expression: t,
@@ -154,21 +154,21 @@ const j = () => {
     componentName: (t == null ? void 0 : t.tagName) || ((r = t == null ? void 0 : t.constructor) == null ? void 0 : r.name),
     componentPath: (t == null ? void 0 : t.sourcePath) || (t == null ? void 0 : t._sourcePath)
   }, e);
-}, g = /* @__PURE__ */ new Map(), K = 25, U = (t) => {
-  const e = g.get(t);
-  return e && (g.delete(t), g.set(t, e)), e;
-}, G = (t, e) => {
-  if (g.has(t))
-    g.delete(t);
-  else if (g.size >= K) {
-    const r = g.keys().next().value;
-    r && g.delete(r);
+}, f = /* @__PURE__ */ new Map(), U = 25, G = (t) => {
+  const e = f.get(t);
+  return e && (f.delete(t), f.set(t, e)), e;
+}, Q = (t, e) => {
+  if (f.has(t))
+    f.delete(t);
+  else if (f.size >= U) {
+    const r = f.keys().next().value;
+    r && f.delete(r);
   }
-  g.set(t, e);
-}, F = (t) => p(null, null, function* () {
+  f.set(t, e);
+}, M = (t) => p(null, null, function* () {
   if (!t)
     throw new Error("Path cannot be null or empty");
-  const e = U(t);
+  const e = G(t);
   if (e) return e;
   try {
     const r = yield fetch(t);
@@ -177,11 +177,11 @@ const j = () => {
         `Failed to fetch component from ${t}: ${r.statusText}`
       );
     const s = yield r.text();
-    return G(t, s), s;
+    return Q(t, s), s;
   } catch (r) {
     N(t, r, { componentPath: t });
   }
-}), Q = (t) => p(null, null, function* () {
+}), V = (t) => p(null, null, function* () {
   try {
     const e = yield fetch(t);
     if (!e.ok) throw new Error(`HTTP ${e.status}`);
@@ -196,8 +196,8 @@ const j = () => {
     css: /\/\*[\s\S]*?\*\//g,
     html: /<!--[\s\S]*?-->/g
   }
-}, V = new DOMParser(), M = (t, e) => p(null, null, function* () {
-  const r = X(t), { scripts: s, externalScripts: o } = Z(r), i = yield te(r), a = r.body.innerHTML.trim();
+}, X = new DOMParser(), F = (t, e) => p(null, null, function* () {
+  const r = Y(t), { scripts: s, externalScripts: o } = ee(r), i = yield re(r), a = r.body.innerHTML.trim();
   return {
     tagName: e,
     template: a,
@@ -205,10 +205,10 @@ const j = () => {
     externalScripts: o,
     styles: i
   };
-}), X = (t) => V.parseFromString(
+}), Y = (t) => X.parseFromString(
   t.replace(b.comments.html, ""),
   "text/html"
-), Y = (t) => [
+), Z = (t) => [
   "/@vite/",
   // Vite dev client
   "/__vite",
@@ -223,12 +223,12 @@ const j = () => {
   // Browser Sync
   "/livereload.js"
   // LiveReload
-].some((r) => t.includes(r)), Z = (t) => {
+].some((r) => t.includes(r)), ee = (t) => {
   var s, o;
   const e = [], r = [];
   for (const i of t.querySelectorAll("script")) {
     if (i.src) {
-      if (Y(i.src)) {
+      if (Z(i.src)) {
         i.remove();
         continue;
       }
@@ -249,7 +249,7 @@ const j = () => {
     i.remove();
   }
   return { scripts: e, externalScripts: r };
-}, ee = (t) => {
+}, te = (t) => {
   const e = t.match(/const __vite__css = "((?:[^"\\]|\\.)*)"/);
   if (e && e[1])
     return e[1].replace(/\\r\\n/g, `
@@ -261,12 +261,12 @@ const j = () => {
 `).replace(/\\t/g, "	").replace(/\\"/g, '"').replace(/\\\\/g, "\\") : t.includes("import") || t.includes("export") ? (n.warn(
     "CSS file returned JavaScript module format. CSS may not load correctly."
   ), "") : t;
-}, te = (t) => p(null, null, function* () {
+}, re = (t) => p(null, null, function* () {
   let e = "";
   const r = t.querySelectorAll("style, link[rel='stylesheet']");
   for (const s of r) {
     if (s.tagName === "LINK") {
-      const i = yield Q(s.href), a = ee(i);
+      const i = yield V(s.href), a = te(i);
       a && (e += `
 ` + a);
     } else if (s.tagName === "STYLE") {
@@ -282,7 +282,7 @@ const j = () => {
   return e.trim();
 });
 var C, T, H;
-class re {
+class se {
   constructor() {
     L(this, C);
     this.components = {}, this.lazyComponents = /* @__PURE__ */ new Set(), this.intersectionObserver = null, this.lazyLoadingInProgress = /* @__PURE__ */ new Map(), this.lazyComponentsLoaded = /* @__PURE__ */ new Set();
@@ -294,11 +294,11 @@ class re {
         return;
       }
       if (o) {
-        this.lazyComponents.add(e), E(this, C, T).call(this, e, r, s), n.log(`Component ${e} registered as lazy-loaded`);
+        this.lazyComponents.add(e), v(this, C, T).call(this, e, r, s), n.log(`Component ${e} registered as lazy-loaded`);
         return;
       }
       try {
-        const i = yield F(r), a = yield M(i, e);
+        const i = yield M(r), a = yield F(i, e);
         this.components[e] = {
           tagName: e,
           template: a.template,
@@ -307,9 +307,9 @@ class re {
           styles: a.styles,
           sourcePath: r,
           lazy: !1
-        }, n.log(`Component ${e} registered successfully`), yield E(this, C, H).call(this, e, s);
+        }, n.log(`Component ${e} registered successfully`), yield v(this, C, H).call(this, e, s);
       } catch (i) {
-        z(e, r, i);
+        j(e, r, i);
         return;
       }
     });
@@ -369,7 +369,7 @@ T = function(e, r, s) {
           const l = this.performLoad();
           o.lazyLoadingInProgress.set(e, l), yield l, o.lazyLoadingInProgress.delete(e), o.lazyComponentsLoaded.add(e), o.lazyComponents.delete(e), n.log(`Component ${e} lazy-loaded successfully`);
         } catch (l) {
-          o.lazyLoadingInProgress.delete(e), z(e, r, l);
+          o.lazyLoadingInProgress.delete(e), j(e, r, l);
         }
       });
     }
@@ -384,7 +384,7 @@ T = function(e, r, s) {
           });
           return;
         }
-        const c = yield F(r), d = yield M(c, e);
+        const c = yield M(r), d = yield F(c, e);
         n.log(`Component ${e} parsed successfully`), o.components[e] = {
           tagName: e,
           template: d.template,
@@ -398,7 +398,7 @@ T = function(e, r, s) {
         n.log(`Defining real component with temp name: ${m}`);
         const y = o.components[e].tagName;
         o.components[e].tagName = m;
-        const { defineWebComponent: S } = yield import("./webcomponent-DyrhK3aa.mjs");
+        const { defineWebComponent: S } = yield import("./webcomponent-Dt-f2pQx.mjs");
         S(o.components[e], s), n.log(`Real component ${m} defined`), o.components[e].tagName = y, this.upgradePlaceholder();
       });
     }
@@ -422,12 +422,12 @@ T = function(e, r, s) {
   customElements.get(e) || customElements.define(e, i);
 }, H = function(e, r) {
   return p(this, null, function* () {
-    const { defineWebComponent: s } = yield import("./webcomponent-DyrhK3aa.mjs");
+    const { defineWebComponent: s } = yield import("./webcomponent-Dt-f2pQx.mjs");
     this.components[e] && s(this.components[e], r);
   });
 };
-const A = new re();
-class se {
+const A = new se();
+class oe {
   constructor() {
     this.listeners = /* @__PURE__ */ new Map();
   }
@@ -497,14 +497,14 @@ class se {
     return (s = (r = this.listeners.get(e)) == null ? void 0 : r.size) != null ? s : 0;
   }
 }
-const R = new se(), u = {};
-function q(t) {
+const R = new oe(), u = {};
+function I(t) {
   return p(this, null, function* () {
     const e = yield u.readdir(t, { withFileTypes: !0 });
     for (const r of e) {
       const s = u.resolve(t, r.name);
       if (r.isDirectory())
-        yield q(s);
+        yield I(s);
       else if (r.name.endsWith(".html")) {
         let o = yield u.readFile(s, "utf-8");
         o = o.replace(
@@ -595,7 +595,7 @@ function Se(t = {}) {
         try {
           u.existsSync(d) && u.rmSync(d, { recursive: !0, force: !0 }), u.cpSync(c, d, { recursive: !0 }), console.log(
             `[ladrillosjs:copy-components] Copied components from ${c} to ${d}`
-          ), o && (yield q(d), console.log(
+          ), o && (yield I(d), console.log(
             `[ladrillosjs:copy-components] Processed component scripts in ${d}`
           ));
         } catch (m) {
@@ -608,7 +608,7 @@ function Se(t = {}) {
     }
   };
 }
-const oe = (t, e, r, s) => A.registerComponent(t, e, r, s), ne = (t) => p(null, null, function* () {
+const ne = (t, e, r, s) => A.registerComponent(t, e, r, s), q = (t) => p(null, null, function* () {
   yield Promise.all(
     t.map(
       ({ name: e, path: r, useShadowDOM: s, lazy: o }) => A.registerComponent(e, r, s, o)
@@ -631,11 +631,11 @@ const oe = (t, e, r, s) => A.registerComponent(t, e, r, s), ne = (t) => p(null,
 }, ae = () => {
   const t = $();
   return t && t.element ? t.element.state || {} : {};
-}, v = (t) => {
+}, E = (t) => {
   const e = $();
   e && e.setState && e.setState(t);
-}, ce = (t, e) => (v({ [t]: e }), (r) => {
-  v({ [t]: r });
+}, ce = (t, e) => (E({ [t]: e }), (r) => {
+  E({ [t]: r });
 }), de = (t, e) => {
   if (e)
     return e.querySelector(t);
@@ -662,9 +662,27 @@ const oe = (t, e, r, s) => A.registerComponent(t, e, r, s), ne = (t) => p(null,
   return document.querySelectorAll(t);
 };
 typeof window != "undefined" && (window.ladrillosjs = {
-  registerComponent: oe,
-  registerComponents: ne
-}, window.$listen = ie, window.$emit = le, window.$querySelector = de, window.$querySelectorAll = pe, window.$reactive = ce, window.$setState = v, window.$getState = ae);
+  registerComponent: ne,
+  registerComponents: q
+}, window.$listen = ie, window.$emit = le, window.$querySelector = de, window.$querySelectorAll = pe, window.$reactive = ce, window.$setState = E, window.$getState = ae);
+const ve = (t) => t, Ee = (t) => {
+  var e, r;
+  return {
+    registration: {
+      name: t.name,
+      path: t.path,
+      useShadowDOM: (e = t.useShadowDOM) != null ? e : !0,
+      lazy: (r = t.lazy) != null ? r : !1
+    },
+    interface: t.interface,
+    version: t.version,
+    library: t.library
+  };
+}, be = (t, e) => t ? (e && t.tagName.toLowerCase() !== e.toLowerCase() && console.warn(
+  `Expected element with tag "${e}", got "${t.tagName.toLowerCase()}"`
+), t) : null, Pe = (t, e) => p(null, null, function* () {
+  return q(t);
+});
 export {
   ie as $,
   b as R,
@@ -672,21 +690,25 @@ export {
   me as a,
   he as b,
   Ce as c,
-  fe as d,
-  ge as e,
+  ge as d,
+  fe as e,
   R as f,
   we as g,
   n as h,
   ye as i,
-  ne as j,
+  q as j,
   le as k,
   x as l,
   ae as m,
-  v as n,
+  E as n,
   ce as o,
   de as p,
   pe as q,
-  oe as r,
-  Se as s
+  ne as r,
+  ve as s,
+  Ee as t,
+  be as u,
+  Pe as v,
+  Se as w
 };
-//# sourceMappingURL=index-DZqKSX8_.mjs.map
+//# sourceMappingURL=index-BcPgsuUl.mjs.map