flet-box 0.0.0-stage → 1.0.2

package/src/widget-factory/warnings.js

@@ -0,0 +1,284 @@
+// core/warnings.js
+// FletBox Warning System – Elegant, minimal, helpful.
+
+// 🚀 Gate of entorno: desactiva warnings in producción
+const IS_DEV = typeof FLETBOX_DEV !== 'undefined' ? FLETBOX_DEV : true;
+
+const suggestionCache = new Map();
+let propNames = [];
+
+export function setPropNames(names) {
+  propNames = names;
+  try { if (typeof window !== 'undefined') window.__FLETBOX_PROP_NAMES = names; } catch(e){}
+}
+
+function getSuggestions(name, limit = 3) {
+  const key = `${name}_${limit}`;
+  if (suggestionCache.has(key)) return suggestionCache.get(key);
+
+  const input = name.toLowerCase();
+  const scored = propNames.map((p) => {
+    const lower = p.toLowerCase();
+    let score = 0;
+    if (lower === input) score = 100;
+    else if (lower.startsWith(input)) score = 80;
+    else if (input.startsWith(lower)) score = 70;
+    else if (lower.includes(input)) score = 50;
+    else if (input.includes(lower)) score = 40;
+    else {
+      const parts = input.split(/(?=[A-Z])/);
+      for (const part of parts) {
+        if (lower.includes(part)) score += 10;
+      }
+    }
+    return { prop: p, score };
+  });
+
+  scored.sort((a, b) => b.score - a.score);
+  const result = scored
+    .filter((s) => s.score > 0 && s.prop !== name)
+    .slice(0, limit)
+    .map((s) => s.prop);
+  suggestionCache.set(key, result);
+  return result;
+}
+
+function getCallLocation() {
+  const stack = new Error().stack;
+  const lines = stack.split("\n");
+  const skip = [
+    "warnings.js",
+    "translateProps.js",
+    "processProps.js",
+    "widgetFactory.js",
+    "createWidget.js",
+    "assignProps.js",
+    "addChildren.js",
+    "makeParentable.js",
+    "effects.js",
+    "lifecycle.js",
+    "reactivity.js",
+    "stackPosition.js",
+    "tools.js",
+    "Container.js",
+    "Row.js",
+    "Column.js",
+    "Stack.js",
+    "Text.js",
+    "Icon.js",
+    "Button.js",
+    "Image.js",
+    "Card.js",
+    "ListTile.js",
+    "ListView.js",
+    "GridView.js",
+    "ProgressBar.js",
+    "Rating.js",
+    "Chip.js",
+    "Badge.js",
+    "Divider.js",
+    "Accordion.js",
+    "Input.js",
+    "Radio.js",
+    "Switch.js",
+    "Checkbox.js",
+    "Dropdown.js",
+    "SnackBar.js",
+    "Modal.js",
+    "BottomSheet.js",
+    "AlertDialog.js",
+    "FloatingActionButton.js",
+    "CodeViewer.js",
+    "Inspector.js",
+    "DraggBox.js",
+    "DroppBox.js",
+    "DataTable.js",
+    "Carousel.js",
+    "Tooltip.js",
+    "Pagination.js",
+    "TreeView.js",
+    "Stepper.js",
+    "Skeleton.js",
+    "Chart.js",
+    "QRCode.js",
+    "Slider.js",
+    "InstallButton.js",
+    "Video.js",
+    "Audio.js",
+    "CircularBar.js",
+    "CircularChart.js",
+    "Markdown.js",
+  ];
+
+  for (const line of lines) {
+    let shouldSkip = false;
+    for (const pattern of skip) {
+      if (line.includes(pattern)) {
+        shouldSkip = true;
+        break;
+      }
+    }
+    if (shouldSkip) continue;
+    if (line.includes("<anonymous>") && !line.includes("app.js")) continue;
+    const match = line.match(/at\s+(.*):(\d+):(\d+)/);
+    if (match) {
+      const file = match[1];
+      const fileName = file.split("/").pop() || file.split("\\").pop() || file;
+      if (file.includes("node_modules")) continue;
+      return { file, fileName, line: match[2], column: match[3] };
+    }
+  }
+
+  for (const line of lines) {
+    const match = line.match(/at\s+(.*):(\d+):(\d+)/);
+    if (match) {
+      const file = match[1];
+      const fileName = file.split("/").pop() || file.split("\\").pop() || file;
+      if (!fileName.includes("node_modules") && !fileName.includes("core")) {
+        return { file, fileName, line: match[2], column: match[3] };
+      }
+    }
+  }
+  return { file: null, fileName: "unknown", line: "?", column: "?" };
+}
+
+function printHeader(label) {
+  console.group(
+    `%c⚠️  FLETBOX: ${label}`,
+    "color: #fbbf24; font-weight: 900; font-size: 18px; background: #1e293b; padding: 6px 12px; border-radius: 6px;",
+  );
+}
+
+function printProp(name, status = "") {
+  console.log(
+    `  %c📦 Prop:  %c"${name}"%c  ${status}`,
+    "color: #94a3b8; font-size: 13px;",
+    "color: #f87171; font-weight: 900; font-size: 16px;",
+    "color: #94a3b8; font-size: 13px;",
+  );
+}
+
+function printLocation(location) {
+  if (location.file) {
+    console.log(
+      `  %c📍 Error at: %c${location.fileName}:${location.line}%c  (click to go to code)`,
+      "color: #94a3b8; font-size: 13px;",
+      "color: #f87171; font-weight: 700; font-size: 14px; text-decoration: underline; cursor: pointer;",
+      "color: #94a3b8; font-size: 13px;",
+    );
+    console.log(`  🔗 ${location.file}:${location.line}:${location.column}`);
+  } else {
+    console.log(
+      `  %c📍 Error at: %c${location.fileName}:${location.line}`,
+      "color: #94a3b8; font-size: 13px;",
+      "color: #f87171; font-weight: 700; font-size: 14px;",
+    );
+  }
+}
+
+function printSuggestions(suggestions) {
+  if (suggestions.length) {
+    console.log(
+      `  %c💡 Did you mean?`,
+      "color: #fbbf24; font-weight: 700; font-size: 14px;",
+    );
+    suggestions.forEach((s) =>
+      console.log(
+        `    %c• "${s}"`,
+        "color: #34d399; font-weight: 600; font-size: 14px;",
+      ),
+    );
+  } else {
+    console.log(
+      `  %c💡 No similar props found. Check spelling.`,
+      "color: #94a3b8; font-size: 13px;",
+    );
+  }
+}
+
+function printWidget(name) {
+  if (name) {
+    console.log(
+      `  %c🧩 Widget: %c${name}`,
+      "color: #94a3b8; font-size: 13px;",
+      "color: #c084fc; font-weight: 600; font-size: 14px;",
+    );
+  }
+}
+
+function printDocs(prop) {
+  console.log(
+    `  %c📚 Docs:  %chttps://fletbox.dev/docs/props#${prop.toLowerCase()}`,
+    "color: #94a3b8; font-size: 13px;",
+    "color: #60a5fa; text-decoration: underline; font-weight: 500; font-size: 13px;",
+  );
+}
+
+export function warnUnknownProp(propName, context = {}) {
+  if (!IS_DEV) return;
+
+  const suggestions = getSuggestions(propName);
+  const location = getCallLocation();
+
+  printHeader("UNKNOWN PROP");
+  printProp(propName, "(not in database)");
+  printLocation(location);
+  printSuggestions(suggestions);
+  printWidget(context.widgetName);
+  printDocs(propName);
+  console.groupEnd();
+}
+
+export function warnDeprecatedProp(propName, replacement = null, context = {}) {
+  if (!IS_DEV) return;
+
+  const location = getCallLocation();
+
+  printHeader("DEPRECATED PROP");
+  printProp(propName, "is deprecated");
+  if (replacement) {
+    console.log(
+      `  %c🔄 Use:   %c"${replacement}"%c  instead`,
+      "color: #94a3b8; font-size: 13px;",
+      "color: #34d399; font-weight: 700; font-size: 16px;",
+      "color: #94a3b8; font-size: 13px;",
+    );
+  }
+  printLocation(location);
+  printWidget(context.widgetName);
+  console.groupEnd();
+}
+
+export function warnInvalidPropType(propName, expected, actual, context = {}) {
+  if (!IS_DEV) return;
+
+  const location = getCallLocation();
+
+  printHeader("INVALID PROP TYPE");
+  printProp(propName, "");
+  console.log(
+    `  %c📊 Expected: %c${expected}`,
+    "color: #94a3b8; font-size: 13px;",
+    "color: #34d399; font-weight: 600; font-size: 14px;",
+  );
+  console.log(
+    `  %c📊 Got:     %c${typeof actual}`,
+    "color: #94a3b8; font-size: 13px;",
+    "color: #f87171; font-weight: 600; font-size: 14px;",
+  );
+  printLocation(location);
+  printWidget(context.widgetName);
+  console.groupEnd();
+}
+
+export function clearSuggestionCache() {
+  suggestionCache.clear();
+}
+
+export default {
+  warnUnknownProp,
+  warnDeprecatedProp,
+  warnInvalidPropType,
+  clearSuggestionCache,
+  setPropNames,
+};

package/src/widget-factory/widgetFactory.js

@@ -0,0 +1,200 @@
+// core/widgetFactory.js
+import { createWidget } from "./createWidget.js";
+import { makeParentable } from "./makeParentable.js";
+import { addLifecycle } from "./lifecycle.js";
+import { applyEffects } from "./effects.js";
+import { makeReactive } from "./reactivity.js";
+import { processProps } from "./processProps.js";
+import { assignProps } from "./assignProps.js";
+import { stackPosition } from "./stackPosition.js";
+import { addChildren, removePropChildren } from "./addChildren.js";
+
+/**
+ * Main widget factory. Creates a fully functional DOM widget with reactivity,
+ * lifecycle hooks, prop processing, and child management.
+ *
+ * Accepts either a tag string or a config object (with an optional `tag` key).
+ * When both `child` and `children` are provided, `children` takes precedence.
+ *
+ * @param {string|Object} tag - HTML tag name (e.g. `'div'`) or a config object
+ *   whose `tag` property specifies the element type. Defaults to `'div'` when
+ *   the value is not a string.
+ * @param {Object} [customProps={}] - Additional props merged on top of any
+ *   props already present in a config object passed as `tag`.
+ * @returns {HTMLElement} The constructed widget element, extended with reactive
+ *   accessors, lifecycle hooks, and `update` / `getProps` methods.
+ */
+export function WidgetFactory(tag, customProps = {}) {
+  // ============================================================
+  // 1. NORMALIZE TAG AND PROPS
+  // ============================================================
+  let finalTag = tag;
+  let finalProps = customProps;
+
+  if (typeof tag === "object" && tag !== null) {
+    if (tag.tag) {
+      finalTag = tag.tag;
+      finalProps = { ...tag, ...customProps };
+      delete finalProps.tag;
+    } else {
+      finalTag = "div";
+      finalProps = { ...tag, ...customProps };
+    }
+  }
+
+  if (typeof finalTag !== "string") {
+    finalTag = "div";
+  }
+
+  // ------------------------------------------------------------
+  // Reserved prop: `widgetName`
+  // ------------------------------------------------------------
+  // Labels the widget with its real FletBox name (e.g. "QRCode", "Button")
+  // instead of the capitalized HTML tag. Consumed by Inspector, navigation
+  // helpers and warnings; it never reaches the DOM. When omitted it falls
+  // back to the capitalized tag, so bare factory calls keep working.
+  //
+  // NOTE: the key is `widgetName`, not `name`, because `name` is a legitimate
+  // public prop of Icon/Avatar (Icon({ name: "add" })).
+  let explicitName = null;
+  if (finalProps && typeof finalProps === "object" && "widgetName" in finalProps) {
+    if (typeof finalProps.widgetName === "string" && finalProps.widgetName) {
+      explicitName = finalProps.widgetName;
+    }
+    finalProps = { ...finalProps };
+    delete finalProps.widgetName;
+  }
+  const widgetName =
+    explicitName || finalTag.charAt(0).toUpperCase() + finalTag.slice(1);
+
+  // ============================================================
+  // 2. NORMALIZE child/children IN INITIAL PROPS
+  // ============================================================
+  // When both are present, prefer `children` (expected behavior).
+  if (
+    finalProps.child !== undefined &&
+    finalProps.children !== undefined
+  ) {
+    delete finalProps.child;
+  }
+
+  // ============================================================
+  // 3. CREATE BASE WIDGET
+  // ============================================================
+  const widget = createWidget(finalTag, {});
+  widget._widgetName = widgetName;
+  widget._updating = false;
+  widget._events = [];
+
+  makeParentable(widget);
+  addLifecycle(widget);
+
+  widget._originalProps = { ...finalProps };
+
+  // ============================================================
+  // 4. APPLY INITIAL PROPS
+  // ============================================================
+  const initialProps = processProps(finalProps, finalTag, widgetName);
+  assignProps(widget, initialProps);
+  stackPosition(widget, finalProps);
+
+  if (finalProps.child !== undefined) {
+    addChildren(widget, finalProps.child);
+  }
+  if (finalProps.children !== undefined) {
+    addChildren(widget, finalProps.children);
+  }
+
+  applyEffects(widget);
+
+  if (finalProps.ref && typeof finalProps.ref === "function") {
+    finalProps.ref(widget);
+  }
+
+  // ============================================================
+  // 5. update METHOD WITH NORMALIZATION
+  // ============================================================
+  let updateDepth = 0;
+  const MAX_UPDATE_DEPTH = 10;
+
+  /**
+   * Updates the widget with new props. Merges the new props into the stored
+   * original props and re-applies styles, attributes, children, and effects.
+   *
+   * Prevents infinite loops via a recursion depth guard (`MAX_UPDATE_DEPTH`).
+   * When both `child` and `children` are passed, `children` wins (same rule as
+   * the constructor).
+   *
+   * @param {Object} [newProps={}] - Partial or full prop set to apply.
+   * @returns {HTMLElement} The widget itself (for chaining).
+   */
+  widget.update = (newProps = {}) => {
+    if (updateDepth >= MAX_UPDATE_DEPTH) {
+      console.warn("⚠️ [WidgetFactory] Max update depth reached, skipping");
+      return widget;
+    }
+
+    updateDepth++;
+    try {
+      // Normalize: never allow child AND children simultaneously
+      const normalized = { ...newProps };
+      // Reserved: `widgetName` labels the widget for Inspector and must never
+      // persist in props. It may re-label the widget on update, nothing more.
+      if ("widgetName" in normalized) {
+        const nextName = normalized.widgetName;
+        if (typeof nextName === "string" && nextName) widget._widgetName = nextName;
+        delete normalized.widgetName;
+      }
+      const hasChild = "child" in normalized;
+      const hasChildren = "children" in normalized;
+
+      if (hasChild || hasChildren) {
+        delete widget._originalProps.child;
+        delete widget._originalProps.children;
+        if (hasChildren) delete normalized.child;
+        else if (hasChild) delete normalized.children;
+      }
+
+      const merged = { ...widget._originalProps, ...normalized };
+      widget._originalProps = merged;
+
+      const processed = processProps(merged, finalTag, widgetName);
+      assignProps(widget, processed);
+      stackPosition(widget, merged);
+
+      if (hasChild || hasChildren) {
+        removePropChildren(widget);
+        if (hasChild) addChildren(widget, newProps.child);
+        if (hasChildren) addChildren(widget, newProps.children);
+      }
+
+      applyEffects(widget);
+
+      if (newProps.ref && typeof newProps.ref === "function") {
+        newProps.ref(widget);
+      }
+    } finally {
+      updateDepth--;
+    }
+
+    return widget;
+  };
+
+  /**
+   * Returns a shallow copy of the widget's current stored props.
+   *
+   * @returns {Object} Copy of `_originalProps`.
+   */
+  widget.getProps = () => ({ ...widget._originalProps });
+
+  // ============================================================
+  // 6. REACTIVITY
+  // ============================================================
+  makeReactive(widget, (changedProps) => {
+    widget.update(changedProps);
+  });
+
+  return widget;
+}
+
+export default WidgetFactory;