flet-box 0.0.0-stage → 1.0.2

package/src/widgets/Inspector.js

@@ -0,0 +1,254 @@
+// utils/Inspector.js
+import { getWidgetProps } from "../utils/getWidgetProps.js";
+
+/**
+ * Converts a JavaScript value to its source-code string representation.
+ * Handles primitives, arrays, plain objects, and nested widget elements
+ * by recursively calling `Inspector` for any DOM node that carries `_widgetName`.
+ *
+ * @param {*} value - The value to stringify.
+ * @param {number} [indent=0] - Current indentation depth (used for pretty-printing nested structures).
+ * @returns {string} A human-readable code representation of the value.
+ */
+const stringifyValue = (value, indent = 0) => {
+  const spaces = "  ".repeat(indent);
+
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+
+  if (typeof value === "function") {
+    return "() => {}";
+  }
+
+  if (typeof value === "string") {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    return `'${escaped}'`;
+  }
+
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const items = value
+      .map((item) => stringifyValue(item, indent + 1))
+      .join(",\n" + spaces + "  ");
+    return `[\n${spaces}  ${items}\n${spaces}]`;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    // If the object is a widget DOM node, delegate to Inspector for full reconstruction
+    if (value.nodeType === 1 && value._widgetName) {
+      return Inspector(value, indent);
+    }
+
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+
+    const props = entries
+      .map(([k, v]) => {
+        if (typeof v === "number" || typeof v === "boolean") {
+          return `${k}: ${v}`;
+        }
+        if (typeof v === "string") {
+          return `${k}: '${v.replace(/'/g, "\\'")}'`;
+        }
+        if (v && v.nodeType === 1) {
+          return `${k}: ${Inspector(v, indent + 1)}`;
+        }
+        return `${k}: ${stringifyValue(v, indent + 1)}`;
+      })
+      .join(",\n" + spaces + "  ");
+
+    return `{\n${spaces}  ${props}\n${spaces}}`;
+  }
+
+  return String(value);
+};
+
+/**
+ * Resolves the display name of a widget element.
+ *
+ * Names come from the underlying HTML tag (documented behavior): `span` →
+ * `Span()`, `div` → `Div()`, `button` → `Button()`, … `_widgetName` is used
+ * only as a fallback for tags without a mapping so the output reads like real
+ * DOM.
+ *
+ * @param {HTMLElement} widget - The DOM node whose name to resolve.
+ * @returns {string} The widget name (e.g. "Button", "Span", "Div").
+ */
+const TAG_NAMES = {
+  SPAN: "Span",
+  DIV: "Div",
+  BUTTON: "Button",
+  INPUT: "Input",
+  TEXTAREA: "Textarea",
+  IMG: "Image",
+  CANVAS: "Canvas",
+  VIDEO: "Video",
+  AUDIO: "Audio",
+  SELECT: "Select",
+  TABLE: "Table",
+  TH: "Th",
+  TD: "Td",
+  TR: "Tr",
+  UL: "Ul",
+  OL: "Ol",
+  LI: "Li",
+  A: "A",
+  CODE: "Code",
+  PRE: "Pre",
+  HEADER: "Header",
+  FOOTER: "Footer",
+};
+
+const getWidgetName = (widget) => {
+  const tag = (widget.tagName || "").toUpperCase();
+  if (TAG_NAMES[tag]) return TAG_NAMES[tag];
+  if (widget._widgetName) return widget._widgetName;
+  return widget.tagName?.toLowerCase() || "unknown";
+};
+
+/**
+ * Collects all direct child elements of a widget, merging both the real DOM
+ * children and any virtual children stored in `_children` (set by WidgetFactory).
+ * Deduplication prevents the same node from appearing twice.
+ *
+ * @param {HTMLElement} widget - The widget whose children to collect.
+ * @returns {HTMLElement[]} Deduplicated array of child element nodes.
+ */
+const collectChildren = (widget) => {
+  const children = [];
+
+  for (const child of widget.children) {
+    if (child.nodeType === 1) {
+      children.push(child);
+    }
+  }
+
+  // _children may hold widget references that aren't yet in the DOM
+  if (widget._children && Array.isArray(widget._children)) {
+    for (const child of widget._children) {
+      if (child && child.nodeType === 1 && !children.includes(child)) {
+        children.push(child);
+      }
+    }
+  }
+
+  return children;
+};
+
+/**
+ * Converts a widget element back into its equivalent source-code representation,
+ * recursively reconstructing its full prop tree and children.
+ *
+ * This is the core utility for the widget inspector — it lets you paste the output
+ * directly into your code to reproduce the exact widget configuration.
+ *
+ * @param {HTMLElement} widget - The root widget to inspect.
+ * @param {number} [indent=0] - Starting indentation depth for pretty-printing.
+ * @returns {string} Source code string such as `Row({ gap: 8, children: [...] })`.
+ */
+export const Inspector = (widget, indent = 0) => {
+  if (!widget || widget.nodeType !== 1) {
+    return String(widget);
+  }
+
+  const name = getWidgetName(widget);
+  const props = getWidgetProps(widget);
+  const spaces = "  ".repeat(indent);
+  const nextSpaces = "  ".repeat(indent + 1);
+
+  // Separate structural props from the rest so we can render them last
+  const { child, children, ...otherProps } = props;
+
+  const propsList = Object.entries(otherProps)
+    .map(([key, value]) => {
+      const formattedValue = stringifyValue(value, indent + 1);
+      return `${key}: ${formattedValue}`;
+    })
+    .join(",\n" + nextSpaces);
+
+  // Reconstruct a single `child` prop
+  let childStr = "";
+  if (child && child.nodeType === 1) {
+    childStr = `\n${nextSpaces}child: ${Inspector(child, indent + 1)}`;
+  }
+
+  // Reconstruct a `children` array prop
+  let childrenStr = "";
+  if (children && Array.isArray(children) && children.length > 0) {
+    const childrenItems = children
+      .filter((c) => c && c.nodeType === 1)
+      .map((c) => Inspector(c, indent + 1))
+      .join(",\n" + nextSpaces + "  ");
+
+    if (childrenItems) {
+      childrenStr = `\n${nextSpaces}children: [\n${nextSpaces}  ${childrenItems}\n${nextSpaces}]`;
+    }
+  }
+
+  // Fall back to actual DOM children when no explicit child/children props exist
+  const domChildren = collectChildren(widget);
+  let domChildrenStr = "";
+  if (
+    domChildren.length > 0 &&
+    !child &&
+    (!children || children.length === 0)
+  ) {
+    const domChildrenItems = domChildren
+      .map((c) => Inspector(c, indent + 1))
+      .join(",\n" + nextSpaces + "  ");
+
+    if (domChildrenItems) {
+      domChildrenStr = `\n${nextSpaces}children: [\n${nextSpaces}  ${domChildrenItems}\n${nextSpaces}]`;
+    }
+  }
+
+  const allContent = [
+    propsList && `${nextSpaces}${propsList}`,
+    childStr,
+    childrenStr,
+    domChildrenStr,
+  ]
+    .filter(Boolean)
+    .join(",\n");
+
+  if (allContent) {
+    return `${name}({\n${allContent}\n${spaces}})`;
+  }
+  return `${name}()`;
+};
+
+/**
+ * Logs the widget's source-code representation to the console with green
+ * monospace styling — handy for quick visual inspection during development.
+ *
+ * @param {HTMLElement} widget - The widget to print.
+ */
+export const printWidgetCode = (widget) => {
+  console.log(
+    "%c" + Inspector(widget),
+    "color: #4ade80; font-family: monospace;",
+  );
+};
+
+/**
+ * Performs a full diagnostic inspection of a widget, logging its name,
+ * resolved props, reconstructed source code, and child count as a grouped
+ * console entry. Returns the widget unchanged so it can be used inline
+ * (e.g. `inspectWidget(myWidget).style.color = "red"`).
+ *
+ * @param {HTMLElement} widget - The widget to inspect.
+ * @returns {HTMLElement} The same widget, unmodified.
+ */
+export const inspectWidget = (widget) => {
+  console.group(`🔍 ${getWidgetName(widget)}`);
+  console.log("📦 Props:", getWidgetProps(widget));
+  console.log("📝 Code:\n", Inspector(widget));
+  console.log("👪 Children:", collectChildren(widget).length);
+  console.groupEnd();
+  return widget;
+};
+
+export default { Inspector, printWidgetCode, inspectWidget };

package/src/widgets/InstallButton.js

@@ -0,0 +1,110 @@
+/**
+ * @file InstallButton.js
+ * @description PWA install prompt button; hidden unless install is available.
+ */
+import { Button } from "./Button.js";
+import { colors } from "../utils/themes.js";
+
+export const InstallButton = (props) => {
+  const {
+    text = "📲 Install",
+    variant = "filled",
+    size = "medium",
+    borderRadius = 28,
+    padding = "12px 24px",
+    bottom = 20,
+    backgroundColor,
+    color,
+    onInstalled,
+    onClick,
+    ...rest
+  } = props;
+
+  let deferredPrompt = null;
+  let button = null;
+  let isInstalled = false;
+
+  const handleClick = async () => {
+    if (deferredPrompt) {
+      deferredPrompt.prompt();
+      const { outcome } = await deferredPrompt.userChoice;
+      if (outcome === "accepted") {
+        if (onInstalled) onInstalled();
+        hideButton();
+      }
+      deferredPrompt = null;
+    }
+    if (onClick) onClick();
+  };
+
+  const showButton = () => {
+    if (button && !isInstalled) {
+      button.style.opacity = "1";
+      button.style.visibility = "visible";
+      button.style.display = "flex";
+    }
+  };
+
+  const hideButton = () => {
+    if (button) {
+      button.style.opacity = "0";
+      button.style.visibility = "hidden";
+      button.style.display = "none";
+    }
+  };
+
+  // Createste button using the flet-box Button component
+  button = Button({
+    widgetName: "InstallButton",
+    text: text,
+    variant: variant,
+    size: size,
+    bgColor: backgroundColor,
+    color: color,
+    borderRadius: borderRadius,
+    padding: padding,
+    position: "fixed",
+    bottom: `${bottom}px`,
+    left: "50%",
+    transform: "translateX(-50%)",
+    zIndex: 10000,
+    opacity: "0",
+    visibility: "hidden",
+    display: "none",
+    boxShadow: "0 4px 12px rgba(0,0,0,0.2)",
+    onPress: handleClick,
+    ...rest,
+  });
+
+  // Listen to events
+  const handleBeforeInstallPrompt = (e) => {
+    e.preventDefault();
+    deferredPrompt = e;
+    showButton();
+  };
+
+  const handleAppInstalled = () => {
+    isInstalled = true;
+    hideButton();
+    if (onInstalled) onInstalled();
+  };
+
+  window.addEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
+  window.addEventListener("appinstalled", handleAppInstalled);
+
+  // Cleanup
+  const cleanup = () => {
+    window.removeEventListener(
+      "beforeinstallprompt",
+      handleBeforeInstallPrompt,
+    );
+    window.removeEventListener("appinstalled", handleAppInstalled);
+    if (button && button.remove) button.remove();
+  };
+
+  button.onUnmount(cleanup);
+
+  return button;
+};
+
+export default InstallButton;

package/src/widgets/ListTile.js

@@ -0,0 +1,224 @@
+/**
+ * @file ListTile.js
+ * @description List row with leading/trailing content and optional divider.
+ */
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Row } from "./Row.js";
+import { Column } from "./Column.js";
+import { Text } from "./Text.js";
+import { colors, subscribeTheme } from "../utils/themes.js";
+
+/**
+ * @typedef {Object} ListTileProps
+ * @property {HTMLElement} [leftItem] - Widget rendered on the leading edge (e.g. an avatar or icon).
+ * @property {HTMLElement} [rightItem] - Widget rendered on the trailing edge (e.g. a chevron or switch).
+ * @property {string} [title] - Primary text line.
+ * @property {string} [subtitle] - Secondary text line rendered below the title at reduced size.
+ * @property {string} [description] - Tertiary text line rendered below the subtitle, typically muted.
+ * @property {Function} [onPress] - Click handler. When provided the tile becomes interactive.
+ * @property {boolean} [selected=false] - Highlights the tile with `selectedBgColor` and bolds the title.
+ * @property {boolean} [disabled=false] - Reduces opacity and removes interactivity.
+ * @property {boolean} [divider=false] - When true, appends a thin horizontal rule below the tile.
+ * @property {number} [paddingHorizontal=16] - Horizontal padding in pixels.
+ * @property {number} [paddingVertical=12] - Vertical padding in pixels.
+ * @property {number} [gap=12] - Gap between the left item, text column, and right item.
+ * @property {number} [elevation=0] - Drop-shadow depth. 0 means no shadow.
+ * @property {number} [borderRadius=0] - Corner radius of the tile in pixels.
+ * @property {string} [bgColor] - Default background color.
+ * @property {string} [selectedBgColor] - Background color when `selected` is true.
+ * @property {string} [hoverColor] - Background color on mouse hover (only when interactive).
+ * @property {Object} [titleProps={}] - Extra props forwarded to the `Text` widget for the title.
+ * @property {Object} [subtitleProps={}] - Extra props forwarded to the `Text` widget for the subtitle.
+ * @property {Object} [descriptionProps={}] - Extra props forwarded to the `Text` widget for the description.
+ */
+
+/**
+ * A single-row list item that follows the Material Design ListTile pattern.
+ *
+ * Composes a leading widget, a text column (title / subtitle / description),
+ * and a trailing widget into a horizontally-aligned row. Supports selection
+ * highlighting, hover effects, elevation shadows, and an optional divider.
+ * Automatically unsubscribes from the theme system when the tile is unmounted.
+ *
+ * @param {ListTileProps} props
+ * @returns {HTMLElement} The tile element (or a wrapper `<div>` when `divider` is true).
+ */
+export const ListTile = (props) => {
+  const {
+    leftItem,
+    rightItem,
+    title,
+    subtitle,
+    description,
+    onPress,
+    selected = false,
+    disabled = false,
+    divider = false,
+    paddingHorizontal = 16,
+    paddingVertical = 12,
+    gap = 12,
+    elevation = 0,
+    borderRadius = 0,
+    bgColor = colors.surface,
+    selectedBgColor = `${colors.primary}20`,
+    hoverColor = colors.border,
+    titleProps = {},
+    subtitleProps = {},
+    descriptionProps = {},
+    ...rest
+  } = props;
+
+  // Only add pointer cursor and hover/click behavior when an onPress handler exists
+  // and the tile is not disabled.
+  const isInteractive = onPress && !disabled;
+
+  // Build text column — only include lines that were actually provided
+  const textChildren = [];
+
+  if (title) {
+    textChildren.push(
+      Text({
+        text: title,
+        size: 16,
+        weight: selected ? "600" : "500",
+        color: selected ? colors.primary : colors.text,
+        ...titleProps,
+      }),
+    );
+  }
+
+  if (subtitle) {
+    textChildren.push(
+      Text({
+        text: subtitle,
+        size: 13,
+        color: colors.textSecondary,
+        marginTop: 2,
+        ...subtitleProps,
+      }),
+    );
+  }
+
+  if (description) {
+    textChildren.push(
+      Text({
+        text: description,
+        size: 12,
+        color: colors.textDisabled,
+        marginTop: 2,
+        ...descriptionProps,
+      }),
+    );
+  }
+
+  // Wrap text lines in a Column only when at least one line was provided
+  const centerColumn =
+    textChildren.length > 0
+      ? Column({
+          gap: 2,
+          alignItems: "flex-start",
+          flex: 1,
+          minWidth: 0, // allows the column to shrink below its content size in a flex row
+          children: textChildren,
+        })
+      : null;
+
+  // Assemble the main content row: [leftItem] [textColumn] [rightItem]
+  const rowChildren = [];
+  if (leftItem) rowChildren.push(leftItem);
+  if (centerColumn) rowChildren.push(centerColumn);
+  if (rightItem) rowChildren.push(rightItem);
+
+  const contentRow = Row({
+    alignItems: "center",
+    gap: gap,
+    padding: `${paddingVertical}px ${paddingHorizontal}px`,
+    width: "100%",
+    boxSizing: "border-box",
+    children: rowChildren,
+  });
+
+  // Main tile element
+  const tile = WidgetFactory({
+    tag: "div",
+    widgetName: "ListTile",
+    backgroundColor: selected ? selectedBgColor : bgColor,
+    borderRadius: borderRadius,
+    cursor: isInteractive ? "pointer" : "default",
+    opacity: disabled ? 0.6 : 1,
+    boxShadow:
+      elevation > 0
+        ? `0 ${elevation}px ${elevation * 2}px rgba(0,0,0,0.1)`
+        : "none",
+    transition: "all 0.2s ease",
+    width: "100%",
+    child: contentRow,
+    onclick: isInteractive ? onPress : null,
+    ...rest,
+  });
+
+  // Hover effects — only when the tile can be interacted with
+  if (isInteractive) {
+    tile.addEventListener("mouseenter", () => {
+      if (!selected) tile.style.backgroundColor = hoverColor;
+      if (elevation > 0) {
+        tile.style.transform = "translateY(-2px)";
+        tile.style.boxShadow = `0 ${elevation + 2}px ${(elevation + 2) * 2}px rgba(0,0,0,0.15)`;
+      }
+    });
+    tile.addEventListener("mouseleave", () => {
+      if (!selected) tile.style.backgroundColor = bgColor;
+      if (elevation > 0) {
+        tile.style.transform = "translateY(0)";
+        tile.style.boxShadow = `0 ${elevation}px ${elevation * 2}px rgba(0,0,0,0.1)`;
+      }
+    });
+  }
+
+  // Theme subscription — keep the background in sync with the active theme.
+  // Only subscribe when the caller has not overridden bgColor/selectedBgColor,
+  // to avoid fighting with explicit colors.
+  let unsubscribeTheme = null;
+  if (!props.bgColor && !props.selectedBgColor) {
+    unsubscribeTheme = subscribeTheme(() => {
+      if (!selected) {
+        tile.style.backgroundColor = colors.surface;
+      } else {
+        tile.style.backgroundColor = `${colors.primary}20`;
+      }
+    });
+  }
+
+  // Cleanup — unsubscribe from the theme system when the tile is unmounted
+  tile.onUnmount(() => {
+    if (unsubscribeTheme) unsubscribeTheme();
+  });
+
+  // When a divider is requested, wrap the tile in a column and append a separator line
+  if (divider) {
+    const dividerLine = WidgetFactory({
+      height: 1,
+      backgroundColor: colors.border,
+      marginLeft: `${paddingHorizontal}px`,
+      width: `calc(100% - ${paddingHorizontal}px)`,
+    });
+
+    const container = WidgetFactory({
+      width: "100%",
+      display: "flex",
+      flexDirection: "column",
+      children: [tile, dividerLine],
+    });
+
+    // Propagate cleanup to the outer container as well
+    container.onUnmount(() => {
+      if (unsubscribeTheme) unsubscribeTheme();
+    });
+
+    return container;
+  }
+
+  return tile;
+};
+
+export default ListTile;