flet-box 0.0.0-stage → 1.0.2

package/src/widgets/Badge.js

@@ -0,0 +1,189 @@
+/**
+ * @file Badge.js
+ * @description An overlay badge that renders a small indicator on top of a
+ * child element. Commonly used for notification counts, status dots, or
+ * "new item" markers on icons and avatars.
+ *
+ * Returns the child element directly when the badge should not be displayed
+ * (value is zero and `showZero` is false, or value is absent). Otherwise
+ * wraps the child in a Stack container with the badge positioned absolutely.
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Stack } from "./Stack.js";
+import { Text } from "./Text.js";
+import { colors, subscribeTheme } from "../utils/themes.js";
+
+/**
+ * Creates a Badge widget that overlays a small count or status indicator on
+ * top of any child element.
+ *
+ * When `value` is falsy (and `showZero` is false), the child is returned
+ * unwrapped — no DOM overhead is added for hidden badges.
+ *
+ * @param {Object} props - Configuration for the badge.
+ * @param {number|string} props.value - The value to display. Numbers are formatted; strings are shown verbatim.
+ * @param {HTMLElement} props.child - The element the badge is anchored to.
+ * @param {string} [props.bgColor=colors.secondary] - Badge background color.
+ * @param {string} [props.color=colors.text] - Badge text/icon color.
+ * @param {number} [props.size=20] - Badge diameter in pixels; also controls font size proportionally.
+ * @param {'top-right'|'top-left'|'bottom-right'|'bottom-left'} [props.position='top-right'] - Where to anchor the badge relative to the child.
+ * @param {number} [props.borderWidth=2] - Width of the contrasting border around the badge in pixels.
+ * @param {string} [props.borderColor=colors.surface] - Color of the border around the badge (typically matches the parent background).
+ * @param {boolean} [props.showZero=false] - When true, the badge is visible even when `value` is 0.
+ * @param {number} [props.max=99] - When `value` exceeds this, the badge shows `"{max}+"` instead of the raw number.
+ * @param {number} [props.offset=0] - Additional pixel offset applied to the badge position for fine-tuning.
+ * @returns {HTMLElement} The wrapped Stack element, or the child element directly if the badge is hidden.
+ */
+export const Badge = (props) => {
+  const {
+    value,
+    child,
+    bgColor = colors.secondary,
+    color = colors.text,
+    size = 20,
+    position = "top-right",
+    borderWidth = 2,
+    borderColor = colors.surface,
+    showZero = false,
+    max = 99,
+    offset = 0,
+    ...rest
+  } = props;
+
+  // Use the supplied bgColor; fall back to danger red if neither bgColor nor color is set
+  const finalBgColor = bgColor || color || colors.danger;
+
+  let unsubscribeTheme = null;
+
+  // Decide whether to show the badge at all
+  const hasValue = value !== undefined && value !== null && value !== "";
+  const showBadge =
+    hasValue &&
+    (showZero || (typeof value === "number" ? value > 0 : value !== ""));
+
+  // Return the child unwrapped to avoid unnecessary DOM nesting
+  if (!showBadge) {
+    return child || null;
+  }
+
+  // Truncate numbers that exceed the `max` cap
+  let displayValue = value;
+  if (typeof value === "number" && max && value > max) {
+    displayValue = `${max}+`;
+  }
+
+  // Pixel offsets for each anchor position — the transform handles the corner alignment
+  const positions = {
+    "top-right": {
+      top: -offset,
+      right: -offset,
+      transform: "translate(25%, -25%)",
+    },
+    "top-left": {
+      top: -offset,
+      left: -offset,
+      transform: "translate(-25%, -25%)",
+    },
+    "bottom-right": {
+      bottom: -offset,
+      right: -offset,
+      transform: "translate(25%, 25%)",
+    },
+    "bottom-left": {
+      bottom: -offset,
+      left: -offset,
+      transform: "translate(-25%, 25%)",
+    },
+  };
+
+  const pos = positions[position] || positions["top-right"];
+
+  // The badge pill element itself
+  const badgeElement = WidgetFactory({
+    widgetName: "Badge",
+    position: "absolute",
+    top: pos.top,
+    right: pos.right,
+    bottom: pos.bottom,
+    left: pos.left,
+    transform: pos.transform,
+    backgroundColor: finalBgColor,
+    borderRadius: size,
+    minWidth: size,
+    height: size,
+    // Extra horizontal padding for two-digit numbers so they don't clip
+    padding: size > 20 ? `0 ${size / 3}px` : 0,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    borderWidth: borderWidth,
+    borderColor: borderColor,
+    zIndex: 1,
+    boxSizing: "border-box",
+    boxShadow: "0 1px 3px rgba(0,0,0,0.2)",
+    child: Text({
+      text: String(displayValue),
+      size: size * 0.55,
+      color: color,
+      weight: "bold",
+      align: "center",
+      lineHeight: 1,
+    }),
+  });
+
+  // Subscribe to theme changes to keep the badge color in sync when no explicit
+  // bgColor/color was provided by the caller
+  if (!bgColor && !color) {
+    unsubscribeTheme = subscribeTheme(() => {
+      badgeElement.style.backgroundColor = colors.danger;
+    });
+  }
+
+  const validChild = child instanceof HTMLElement ? child : null;
+
+  if (!validChild) {
+    console.warn("Badge: child must be an HTMLElement");
+    if (unsubscribeTheme) unsubscribeTheme();
+    return badgeElement;
+  }
+
+  // Wrap the child and the badge in a Stack so the badge is positioned relative to the child
+  const badgeStack = Stack({
+    position: "relative",
+    display: "inline-block",
+    children: [validChild, badgeElement],
+    ...rest,
+  });
+
+  // Unsubscribe from theme updates when the component is removed from the DOM
+  badgeStack.onUnmount(() => {
+    if (unsubscribeTheme) unsubscribeTheme();
+  });
+
+  /**
+   * Updates the displayed badge value without re-rendering the component.
+   * Hides the badge automatically when the new value is zero (unless `showZero` is true).
+   *
+   * @param {number|string} newValue - The new badge value.
+   */
+  badgeStack.updateValue = (newValue) => {
+    let newDisplayValue = newValue;
+    if (typeof newValue === "number" && max && newValue > max) {
+      newDisplayValue = `${max}+`;
+    }
+    const textElement = badgeElement.querySelector("span:not(.material-icons)");
+    if (textElement) {
+      textElement.textContent = String(newDisplayValue);
+    }
+    const shouldShow =
+      newValue &&
+      (showZero ||
+        (typeof newValue === "number" ? newValue > 0 : newValue !== ""));
+    badgeElement.style.display = shouldShow ? "flex" : "none";
+  };
+
+  return badgeStack;
+};
+
+export default Badge;

package/src/widgets/BottomSheet.js

@@ -0,0 +1,287 @@
+/**
+ * @file BottomSheet.js
+ * @description Bottom sheet controller returned to callers (`open`/`close`/`toggle`/`destroy`).
+ */
+import { WidgetFactory } from "../widget-factory/index.js";
+import { colors } from "../utils/themes.js";
+import { Row } from "./Row.js";
+import { Column } from "./Column.js";
+import { Text } from "./Text.js";
+import { Icon } from "./Icon.js";
+import { Container } from "./Container.js";
+
+export const BottomSheet = (props) => {
+  const {
+    content,
+    title,
+    actions = [],
+    height = "auto",
+    maxHeight = "80%",
+    showDragHandle = true,
+    closeOnOverlayClick = true,
+    closeOnDragDown = true,
+    showCloseButton = true,
+
+    // Colors
+    backgroundColor = colors.surface,
+    overlayColor = "rgba(0, 0, 0, 0.5)",
+    dragHandleColor = colors.border,
+    headerTextColor = colors.text,
+    headerBorderColor = colors.border,
+    actionBorderColor = colors.border,
+
+    // Borders and shadows
+    borderRadius = 24,
+    shadow = "0 -4px 12px rgba(0,0,0,0.1)",
+
+    // Spacing
+    headerPadding = "0 16px 8px 16px",
+    contentPadding = "0 16px",
+    actionPadding = "12px 16px",
+    dragHandlePadding = "14px 0 8px 0",
+    dragHandleWidth = 40,
+    dragHandleHeight = 4,
+
+    // Animation
+    animationDuration = 300,
+
+    // Z-index
+    zIndex = 9999,
+    overlayZIndex = 9998,
+
+    // Callbacks
+    onOpen,
+    onClose,
+
+    ...rest
+  } = props;
+
+  let isOpen = false;
+  let overlay = null;
+  let sheetContainer = null;
+  let startY = 0;
+  let currentY = 0;
+
+  // ✅ Overlay with onclick
+  overlay = WidgetFactory({
+    position: "fixed",
+    top: 0,
+    left: 0,
+    width: "100%",
+    height: "100%",
+    backgroundColor: overlayColor,
+    zIndex: overlayZIndex,
+    opacity: 0,
+    visibility: "hidden",
+    transition: `opacity ${animationDuration}ms ease, visibility ${animationDuration}ms ease`,
+    // onclick: (e) => {
+    //   // ✅ Only close if the click was directly on the overlay (not on the sheet)
+    //   if (e.target === overlay && closeOnOverlayClick) {
+    //     close();
+    //   }
+    // },
+  });
+
+  // ✅ Drag handle with stopPropagation
+  const dragHandle = showDragHandle
+    ? WidgetFactory({
+        display: "flex",
+        justifyContent: "center",
+        padding: dragHandlePadding,
+        cursor: "grab",
+onclick: (e) => e.stopPropagation(), // ✅ Prevents the click from reaching the overlay
+        child: WidgetFactory({
+          width: dragHandleWidth,
+          height: dragHandleHeight,
+          backgroundColor: dragHandleColor,
+          borderRadius: dragHandleHeight / 2,
+        }),
+      })
+    : null;
+
+  // Header
+  const headerChildren = [];
+  if (title) {
+    headerChildren.push(
+      Text({
+        text: title,
+        size: 18,
+        weight: "bold",
+        color: headerTextColor,
+        flex: 1,
+      }),
+    );
+  }
+  if (showCloseButton) {
+    const closeBtn = Icon({
+      name: "close",
+      size: 22,
+      color: colors.textSecondary,
+      cursor: "pointer",
+    });
+    closeBtn.onclick = () => close();
+    headerChildren.push(closeBtn);
+  }
+
+  const header =
+    title || showCloseButton
+      ? Row({
+          alignItems: "center",
+          justifyContent: "space-between",
+          padding: headerPadding,
+          borderBottom: title ? `1px solid ${headerBorderColor}` : "none",
+          children: headerChildren,
+        })
+      : null;
+
+  // Actions footer
+  const actionsElement =
+    actions.length > 0
+      ? Row({
+          alignItems: "center",
+          justifyContent: "flex-end",
+          gap: 8,
+          padding: actionPadding,
+          borderTop: `1px solid ${actionBorderColor}`,
+          marginTop: "auto",
+          children: actions,
+        })
+      : null;
+
+  // Content wrapper
+  const contentWrapper = Container({
+    flex: 1,
+    overflow: "auto",
+    padding: contentPadding,
+    child: content,
+  });
+
+  // ✅ SheetContainer with stopPropagation
+  sheetContainer = WidgetFactory({
+    position: "fixed",
+    bottom: 0,
+    left: 0,
+    right: 0,
+    paddingBottom: 12,
+    backgroundColor: backgroundColor,
+    borderRadius: `${borderRadius}px ${borderRadius}px 0 0`,
+    boxShadow: shadow,
+    transform: "translateY(100%)",
+    transition: `transform ${animationDuration}ms ease`,
+    maxHeight: maxHeight,
+    height: height === "auto" ? "auto" : height,
+    display: "flex",
+    flexDirection: "column",
+    zIndex: zIndex,
+    overflow: "hidden",
+    // onclick: (e) => e.stopPropagation(), // ✅ Prevents the click from reaching the overlay
+  });
+
+  // Body
+  const sheetBody = Column({
+    height: "100%",
+    gap: 12,
+    children: [dragHandle, header, contentWrapper, actionsElement].filter(
+      Boolean,
+    ),
+  });
+
+  sheetContainer.appendChild(sheetBody);
+  overlay.appendChild(sheetContainer);
+  document.body.appendChild(overlay);
+
+  // Drag handlers
+  const onTouchStart = (e) => {
+    // ✅ Prevent the drag event from propagating to the overlay
+    e.stopPropagation();
+    startY = e.touches ? e.touches[0].clientY : e.clientY;
+    currentY = startY;
+    sheetContainer.style.transition = "none";
+  };
+
+  const onTouchMove = (e) => {
+    if (!closeOnDragDown) return;
+    e.preventDefault();
+    const moveY = e.touches ? e.touches[0].clientY : e.clientY;
+    const delta = moveY - startY;
+    if (delta > 0) {
+      currentY = moveY;
+      sheetContainer.style.transform = `translateY(${delta}px)`;
+      const opacity = 1 - delta / sheetContainer.offsetHeight;
+      overlay.style.opacity = Math.max(0, Math.min(1, opacity));
+    }
+  };
+
+  const onTouchEnd = (e) => {
+    e.stopPropagation();
+    sheetContainer.style.transition = `transform ${animationDuration}ms ease`;
+    const delta = currentY - startY;
+    if (delta > 100) {
+      close();
+    } else {
+      sheetContainer.style.transform = "translateY(0)";
+      overlay.style.opacity = "1";
+    }
+    startY = 0;
+    currentY = 0;
+  };
+
+  const open = () => {
+    if (isOpen) return;
+    isOpen = true;
+    overlay.style.visibility = "visible";
+    overlay.style.opacity = "1";
+    sheetContainer.style.transform = "translateY(0)";
+    if (onOpen) onOpen();
+    document.addEventListener("keydown", handleKeyDown);
+
+    if (closeOnDragDown && dragHandle) {
+      dragHandle.addEventListener("mousedown", onTouchStart);
+      // dragHandle.addEventListener("mousemove", onTouchMove);
+      dragHandle.addEventListener("mouseup", onTouchEnd);
+      dragHandle.addEventListener("touchstart", onTouchStart);
+      dragHandle.addEventListener("touchmove", onTouchMove);
+      dragHandle.addEventListener("touchend", onTouchEnd);
+    }
+  };
+
+  const close = () => {
+    if (!isOpen) return;
+    isOpen = false;
+    sheetContainer.style.transform = "translateY(100%)";
+    overlay.style.opacity = "0";
+    setTimeout(() => {
+      overlay.style.visibility = "hidden";
+    }, animationDuration);
+    if (onClose) onClose();
+    document.removeEventListener("keydown", handleKeyDown);
+
+    if (closeOnDragDown && dragHandle) {
+      dragHandle.removeEventListener("mousedown", onTouchStart);
+      // dragHandle.removeEventListener("mousemove", onTouchMove);
+      dragHandle.removeEventListener("mouseup", onTouchEnd);
+      dragHandle.removeEventListener("touchstart", onTouchStart);
+      dragHandle.removeEventListener("touchmove", onTouchMove);
+      dragHandle.removeEventListener("touchend", onTouchEnd);
+    }
+  };
+
+  const toggle = () => {
+    if (isOpen) close();
+    else open();
+  };
+
+  const destroy = () => {
+    if (overlay && overlay.parentNode) overlay.parentNode.removeChild(overlay);
+    document.removeEventListener("keydown", handleKeyDown);
+  };
+
+  const handleKeyDown = (e) => {
+    if (e.key === "Escape" && isOpen) close();
+  };
+
+  const bottomSheet = { open, close, toggle, destroy };
+  return bottomSheet;
+};
+
+export default BottomSheet;