flet-box 0.0.0-stage → 1.0.2

package/src/navigations/AppBar.js

@@ -0,0 +1,331 @@
+// navigations/AppBar.js
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Container } from "../widgets/Container.js";
+import { Row } from "../widgets/Row.js";
+import { Text } from "../widgets/Text.js";
+import { Icon } from "../widgets/Icon.js";
+import { colors } from "../utils/themes.js";
+import { goBack, goTo } from "./Router.js";
+
+/**
+ * @typedef {Object} AppBarProps
+ * @property {string|HTMLElement} [title] - Page title shown in the center or left of the bar.
+ * @property {HTMLElement|null} [leading=null] - Widget placed at the leading (left) edge, e.g. a menu or nav icon.
+ * @property {HTMLElement[]} [actions=[]] - Action widgets placed at the trailing (right) edge.
+ * @property {number} [actionsGap=12] - Gap in pixels between action widgets.
+ * @property {string} [backgroundColor] - Background fill color.
+ * @property {string|null} [gradient=null] - CSS gradient string; overrides backgroundColor when set.
+ * @property {string} [titleColor] - Color of the title text.
+ * @property {string} [iconColor] - Color of icons; defaults to titleColor.
+ * @property {number} [elevation=2] - Shadow depth (0–5).
+ * @property {boolean} [centerTitle=false] - Whether to center the title horizontally.
+ * @property {number} [titleSize=20] - Font size of the title in pixels.
+ * @property {string} [titleWeight="500"] - Font weight of the title.
+ * @property {boolean} [showBackButton=false] - Auto-inject a back-navigation arrow as the leading widget.
+ * @property {string|null} [backButtonRoute=null] - Route to push when the back button is pressed; falls back to goBack().
+ * @property {Function|null} [onBackPress=null] - Custom handler for back-button press; takes priority over backButtonRoute.
+ * @property {number} [margin=0] - Uniform outer margin.
+ * @property {number} [marginTop=0] - Top outer margin (overrides margin).
+ * @property {number} [marginBottom=0] - Bottom outer margin (overrides margin).
+ * @property {number} [marginLeft=0] - Left outer margin (overrides margin).
+ * @property {number} [marginRight=0] - Right outer margin (overrides margin).
+ * @property {number} [padding=0] - Uniform inner padding.
+ * @property {number} [paddingTop=0] - Top inner padding (overrides padding).
+ * @property {number} [paddingBottom=0] - Bottom inner padding (overrides padding).
+ * @property {number} [paddingLeft=4] - Left inner padding (overrides padding).
+ * @property {number} [paddingRight=24] - Right inner padding (overrides padding).
+ * @property {number|string} [borderRadius=0] - Border radius (number = pixels, string = CSS value).
+ * @property {boolean|string} [shadow=true] - Whether to apply a shadow; pass a CSS string to use a custom shadow.
+ * @property {boolean} [sticky=true] - Whether the bar sticks to the top of the viewport on scroll.
+ * @property {boolean} [hideOnScroll=false] - Whether to animate the bar out of view when scrolling down.
+ * @property {number} [scrollThreshold=100] - Scroll distance in pixels before the hide animation triggers.
+ */
+
+/**
+ * AppBar renders a top navigation bar with a leading zone, a title, and
+ * an optional set of action widgets on the right.
+ *
+ * The bar can stick to the top of the viewport (`sticky`), hide when
+ * the user scrolls down (`hideOnScroll`), and auto-inject a back button
+ * (`showBackButton`) wired to the router or a custom handler.
+ *
+ * Non-HTMLElement entries in `actions` are silently filtered out to prevent
+ * "[object Object]" from being rendered.
+ *
+ * @param {AppBarProps} props
+ * @returns {HTMLElement} The `<header>` element representing the app bar,
+ *   augmented with the following methods:
+ *   - `setTitle(newTitle: string)` — update the title text in place.
+ *   - `setBackgroundColor(color: string)` — swap the background color or gradient.
+ *   - `show()` / `hide()` — toggle bar visibility.
+ */
+export const AppBar = (props) => {
+  const {
+    title,
+    leading = null,
+    actions = [],
+    actionsGap = 12,
+
+    backgroundColor = colors.surface,
+    gradient = null,
+    titleColor = colors.text,
+    iconColor = titleColor,
+    elevation = 2,
+    centerTitle = false,
+    titleSize = 20,
+    titleWeight = "500",
+
+    showBackButton = false,
+    backButtonRoute = null,
+    onBackPress = null,
+
+    margin = 0,
+    marginTop = 0,
+    marginBottom = 0,
+    marginLeft = 0,
+    marginRight = 0,
+
+    padding = 0,
+    paddingTop = 0,
+    paddingBottom = 0,
+    paddingLeft = 4,
+    paddingRight = 24,
+    borderRadius = 0,
+    shadow = true,
+
+    sticky = true,
+    hideOnScroll = false,
+    scrollThreshold = 100,
+    ...rest
+  } = props;
+
+  // Guard: only HTMLElement instances are valid action widgets.
+  // Filtering here prevents the common mistake of passing component results
+  // that accidentally resolved to plain objects.
+  const validActions = Array.isArray(actions)
+    ? actions.filter((action) => action instanceof HTMLElement)
+    : [];
+
+  // Resolve shorthand margin/padding props — individual sides win over the
+  // uniform shorthand when both are provided.
+  const finalMarginTop = marginTop || margin;
+  const finalMarginBottom = marginBottom || margin;
+  const finalMarginLeft = marginLeft || margin;
+  const finalMarginRight = marginRight || margin;
+
+  const finalPaddingTop = paddingTop || padding;
+  const finalPaddingBottom = paddingBottom || padding;
+  const finalPaddingLeft = paddingLeft || padding;
+  const finalPaddingRight = paddingRight || padding;
+
+  const finalBorderRadius =
+    typeof borderRadius === "number" ? `${borderRadius}px` : borderRadius;
+
+  // Material Design elevation → box-shadow lookup table.
+  const shadows = {
+    0: "none",
+    1: "0 1px 3px rgba(0,0,0,0.12)",
+    2: "0 3px 6px rgba(0,0,0,0.16)",
+    3: "0 6px 12px rgba(0,0,0,0.2)",
+    4: "0 10px 20px rgba(0,0,0,0.25)",
+    5: "0 15px 30px rgba(0,0,0,0.3)",
+  };
+  const boxShadow = shadow === true ? shadows[elevation] : shadow || "none";
+
+  // ========== LEADING SECTION ==========
+  // Auto-create a back button if requested and no custom leading was supplied.
+  let finalLeading = leading;
+  if (showBackButton && !finalLeading) {
+    const backButton = Icon({
+      name: "arrow_back",
+      size: 24,
+      color: iconColor,
+      cursor: "pointer",
+    });
+    backButton.onclick = () => {
+      if (onBackPress) onBackPress();
+      else if (backButtonRoute) goTo(backButtonRoute);
+      else goBack();
+    };
+    finalLeading = backButton;
+  }
+
+  // ========== BACKGROUND ==========
+  // Gradient takes priority over a solid background color.
+  let backgroundStyle = {};
+  if (gradient) {
+    backgroundStyle = { backgroundImage: gradient };
+  } else if (backgroundColor) {
+    backgroundStyle = { backgroundColor: backgroundColor };
+  }
+
+  // ========== MAIN APP BAR ELEMENT ==========
+  const appBar = WidgetFactory({
+    tag: "header",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    minHeight: 56,
+    borderRadius: finalBorderRadius,
+    marginTop: finalMarginTop,
+    marginBottom: finalMarginBottom,
+    marginLeft: finalMarginLeft,
+    marginRight: finalMarginRight,
+    paddingTop: `calc(${finalPaddingTop}px + env(safe-area-inset-top, 0px))`,
+    paddingBottom: finalPaddingBottom,
+    paddingLeft: finalPaddingLeft,
+    paddingRight: finalPaddingRight,
+    boxShadow: boxShadow,
+    flexShrink: 0,
+    position: sticky ? "sticky" : "relative",
+    top: sticky ? 0 : "auto",
+    zIndex: sticky ? 100 : "auto",
+    transition: "transform 0.3s ease, opacity 0.3s ease",
+    ...backgroundStyle,
+    ...rest,
+  });
+
+  // ========== LEFT SECTION ==========
+  // Fixed minimum width ensures the center title stays visually centered
+  // even when no leading widget is present.
+  const leftSection = Container({
+    display: "flex",
+    alignItems: "center",
+    bgColor: "transparent",
+    justifyContent: "flex-start",
+    minWidth: 48,
+    flexShrink: 0,
+    child: finalLeading instanceof HTMLElement ? finalLeading : null,
+  });
+  appBar.appendChild(leftSection);
+
+  // ========== TITLE ==========
+  let titleElement;
+  if (typeof title === "string") {
+    titleElement = Text({
+      text: title,
+      size: titleSize,
+      weight: titleWeight,
+      color: titleColor,
+      whiteSpace: "nowrap",
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+      letterSpacing: "0.15px",
+    });
+  } else if (title instanceof HTMLElement) {
+    titleElement = title;
+  }
+
+  const centerSection = Container({
+    flex: centerTitle ? 1 : "none",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: centerTitle ? "center" : "flex-start",
+    padding: "0 8px",
+    bgColor: "transparent",
+    overflow: "hidden",
+    minWidth: 0,
+    child: titleElement,
+  });
+  appBar.appendChild(centerSection);
+
+  // ========== RIGHT SECTION (only rendered when there are valid actions) ==========
+  if (validActions.length > 0) {
+    const rightSection = Row({
+      alignItems: "center",
+      justifyContent: "flex-end",
+      paddingRight: paddingRight,
+      gap: actionsGap,
+      minWidth: 48,
+      flexShrink: 0,
+      backgroundColor: "transparent",
+      children: validActions,
+    });
+    appBar.appendChild(rightSection);
+  } else {
+    // Invisible placeholder maintains three-zone layout balance when there
+    // are no actions, keeping the title centered when centerTitle is true.
+    const emptyRight = Container({
+      minWidth: 48,
+      flexShrink: 0,
+      visibility: "hidden",
+    });
+    appBar.appendChild(emptyRight);
+  }
+
+  // ========== HIDE-ON-SCROLL BEHAVIOUR ==========
+  // Attach a scroll listener that slides the bar off-screen when the user
+  // scrolls down past the threshold, and restores it on scroll-up.
+  if (hideOnScroll) {
+    let lastScrollY = 0;
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY;
+      if (currentScrollY > lastScrollY && currentScrollY > scrollThreshold) {
+        appBar.style.transform = "translateY(-100%)";
+        appBar.style.opacity = "0";
+      } else if (currentScrollY < lastScrollY) {
+        appBar.style.transform = "translateY(0)";
+        appBar.style.opacity = "1";
+      }
+      lastScrollY = currentScrollY;
+    };
+    window.addEventListener("scroll", handleScroll);
+    // Store the remover so _cleanup can deregister the listener.
+    appBar._cleanupScroll = () =>
+      window.removeEventListener("scroll", handleScroll);
+  }
+
+  // ========== PUBLIC API ==========
+
+  /**
+   * Update the title text in place without rebuilding the bar.
+   *
+   * @param {string} newTitle
+   */
+  appBar.setTitle = (newTitle) => {
+    if (typeof newTitle === "string") {
+      const titleText = centerSection.querySelector(
+        "span:not(.material-icons)",
+      );
+      if (titleText) titleText.textContent = newTitle;
+    }
+  };
+
+  /**
+   * Swap the background color or gradient at runtime.
+   * Passing a string that contains the word "gradient" sets backgroundImage;
+   * otherwise it sets backgroundColor.
+   *
+   * @param {string} color - CSS color value or gradient string.
+   */
+  appBar.setBackgroundColor = (color) => {
+    if (color && color.includes("gradient")) {
+      appBar.style.backgroundImage = color;
+      appBar.style.backgroundColor = "";
+    } else {
+      appBar.style.backgroundColor = color;
+      appBar.style.backgroundImage = "";
+    }
+  };
+
+  /** Make the app bar visible. */
+  appBar.show = () => {
+    appBar.style.display = "flex";
+  };
+
+  /** Hide the app bar (removes it from the layout flow). */
+  appBar.hide = () => {
+    appBar.style.display = "none";
+  };
+
+  // Cleanup: deregister the scroll listener added by hideOnScroll.
+  const originalCleanup = appBar._cleanup;
+  appBar._cleanup = () => {
+    if (originalCleanup) originalCleanup();
+    if (appBar._cleanupScroll) appBar._cleanupScroll();
+  };
+
+  return appBar;
+};
+
+export default AppBar;

package/src/navigations/BottomNavigation.js

@@ -0,0 +1,298 @@
+// navigations/BottomNavigation.js
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Container } from "../widgets/Container.js";
+import { Text } from "../widgets/Text.js";
+import { Icon } from "../widgets/Icon.js";
+import { colors } from "../utils/themes.js";
+import { getCurrentPath, subscribe, goTo } from "./Router.js";
+
+/**
+ * @typedef {Object} BottomNavigationItem
+ * @property {string} icon - Material Icon name.
+ * @property {string} [label] - Display label shown below the icon.
+ * @property {string} [route] - Router path this tab navigates to.
+ *   Defaults to `/<label.toLowerCase()>` when omitted.
+ * @property {Function} [onPress] - Additional callback fired when the tab is tapped.
+ */
+
+/**
+ * @typedef {Object} BottomNavigationProps
+ * @property {BottomNavigationItem[]} [items=[]] - Tab definitions.
+ * @property {number} [currentIndex=0] - Initially active tab index (non-router mode).
+ * @property {Function} [onTabChange] - Callback fired with the new index whenever the active tab changes.
+ * @property {string} [backgroundColor] - Background fill color of the bar.
+ * @property {string} [selectedColor] - Icon and label color for the active tab.
+ * @property {string} [unselectedColor] - Icon and label color for inactive tabs.
+ * @property {boolean} [showLabels=true] - Whether to render text labels below icons.
+ * @property {number} [iconSize=24] - Icon size in pixels.
+ * @property {number} [height=65] - Bar height in pixels.
+ * @property {number} [margin=0] - Uniform outer margin.
+ * @property {number} [marginTop=0] - Top margin (overrides margin).
+ * @property {number} [marginBottom=0] - Bottom margin (overrides margin).
+ * @property {number} [marginLeft=0] - Left margin (overrides margin).
+ * @property {number} [marginRight=0] - Right margin (overrides margin).
+ * @property {number|string} [borderRadius=0] - Corner radius.
+ * @property {number|string} [padding=0] - Inner padding.
+ * @property {boolean|string} [shadow=true] - Whether to render a shadow; pass a CSS string for a custom shadow.
+ * @property {number} [elevation=2] - Shadow depth (0–5), used when shadow is true.
+ * @property {boolean} [useRouter=true] - Sync the active tab with the router instead of tracking an internal index.
+ */
+
+/**
+ * BottomNavigation renders a bottom tab bar with icon and optional label tabs.
+ *
+ * By default (`useRouter=true`) it integrates with the Router module: tapping
+ * a tab calls `goTo(route)` and the active highlighting is driven entirely by
+ * the current route, keeping the bar in sync with back/forward navigation and
+ * programmatic route changes. Set `useRouter=false` to operate in standalone
+ * mode where the bar manages its own active index.
+ *
+ * @param {BottomNavigationProps} props
+ * @returns {HTMLElement} The `<nav>` element, augmented with:
+ *   - `setActiveIndex(index: number)` — programmatically activate a tab.
+ *   - `getActiveIndex(): number` — returns the currently active tab index.
+ *   - `getCurrentRoute(): string|null` — returns the current router path (router mode only).
+ */
+export const BottomNavigation = (props) => {
+  const {
+    items = [],
+    currentIndex = 0,
+    onTabChange,
+    backgroundColor = colors.surface,
+    selectedColor = colors.primary,
+    unselectedColor = colors.textSecondary,
+    showLabels = true,
+    iconSize = 24,
+    height = 65,
+    margin = 0,
+    marginTop = 0,
+    marginBottom = 0,
+    marginLeft = 0,
+    marginRight = 0,
+    borderRadius = 0,
+    padding = 0,
+    shadow = true,
+    elevation = 2,
+    useRouter = true,
+    ...rest
+  } = props;
+
+  let activeIndex = currentIndex;
+  const buttons = [];
+  let unsubscribe = null;
+  // Tracks whether the initial router sync has been performed so we don't
+  // override `activeIndex` from the router on subsequent renders.
+  let isRouterSynced = false;
+
+  // Resolve shorthand margin/padding/radius props.
+  const finalMarginTop = marginTop || margin;
+  const finalMarginBottom = marginBottom || margin;
+  const finalMarginLeft = marginLeft || margin;
+  const finalMarginRight = marginRight || margin;
+  const finalBorderRadius =
+    typeof borderRadius === "number" ? `${borderRadius}px` : borderRadius;
+  const finalPadding = typeof padding === "number" ? `${padding}px` : padding;
+
+  // Material Design elevation → box-shadow lookup table.
+  const shadows = {
+    0: "none",
+    1: "0 1px 3px rgba(0,0,0,0.12)",
+    2: "0 3px 6px rgba(0,0,0,0.16)",
+    3: "0 6px 12px rgba(0,0,0,0.2)",
+    4: "0 10px 20px rgba(0,0,0,0.25)",
+    5: "0 15px 30px rgba(0,0,0,0.3)",
+  };
+  const boxShadow = shadow === true ? shadows[elevation] : shadow || "none";
+
+  const container = WidgetFactory({
+    tag: "nav",
+    display: "flex",
+    width: `calc(100% - ${finalMarginLeft}px - ${finalMarginRight}px)`,
+    height: height,
+    backgroundColor: backgroundColor,
+    borderRadius: finalBorderRadius,
+    marginTop: finalMarginTop,
+    marginBottom: finalMarginBottom,
+    marginLeft: finalMarginLeft,
+    marginRight: finalMarginRight,
+    padding: finalPadding,
+    boxShadow: boxShadow,
+    flexShrink: 0,
+    ...rest,
+  });
+
+  /**
+   * Update icon and label colors for the given active tab index.
+   * Used exclusively in non-router mode where the bar manages its own state.
+   *
+   * @param {number} index - The index of the newly active tab.
+   */
+  const updateActive = (index) => {
+    buttons.forEach((btnData, i) => {
+      const isActive = i === index;
+      const icon = btnData.btn.querySelector(".material-icons");
+      const label = btnData.btn.querySelector(".bottom-nav-label");
+      if (icon) icon.style.color = isActive ? selectedColor : unselectedColor;
+      if (label) {
+        label.style.color = isActive ? selectedColor : unselectedColor;
+        label.style.fontWeight = isActive ? "500" : "400";
+      }
+    });
+    if (onTabChange) onTabChange(index);
+  };
+
+  /**
+   * Re-read the current router path and update icon/label colors to match.
+   * Called on every route change event in router mode.
+   */
+  const updateColorsFromRouter = () => {
+    if (!useRouter) return;
+
+    const currentPath = getCurrentPath();
+
+    buttons.forEach((btnData, idx) => {
+      const isSelected = btnData.route === currentPath;
+      const color = isSelected ? selectedColor : unselectedColor;
+
+      if (btnData.icon) btnData.icon.style.color = color;
+      if (btnData.labelWidget) {
+        btnData.labelWidget.style.color = color;
+        btnData.labelWidget.style.fontWeight = isSelected ? "500" : "400";
+      }
+
+      if (isSelected) activeIndex = idx;
+    });
+
+    if (onTabChange) onTabChange(activeIndex);
+  };
+
+  // ========== BUILD TAB BUTTONS ==========
+  items.forEach((item, idx) => {
+    const itemRoute = item.route || `/${item.label?.toLowerCase()}`;
+
+    // Determine initial active state — derive from the router path on first
+    // render so the correct tab is highlighted when the page loads on a
+    // non-root route.
+    let isActive = activeIndex === idx;
+    if (useRouter && !isRouterSynced) {
+      const currentPath = getCurrentPath();
+      isActive = itemRoute === currentPath;
+      if (isActive) activeIndex = idx;
+    }
+
+    const btn = Container({
+      flex: 1,
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 4,
+      cursor: "pointer",
+      padding: "8px 0",
+      backgroundColor: "transparent",
+      onclick: () => {
+        if (useRouter) {
+          goTo(itemRoute);
+          if (item.onPress) item.onPress();
+        } else {
+          // In standalone mode, only update state when a different tab is tapped.
+          if (activeIndex !== idx) {
+            activeIndex = idx;
+            updateActive(idx);
+            if (item.onPress) item.onPress();
+          }
+        }
+      },
+    });
+
+    const icon = Icon({
+      name: item.icon,
+      size: iconSize,
+      color: isActive ? selectedColor : unselectedColor,
+    });
+    btn.appendChild(icon);
+
+    let labelWidget = null;
+    if (showLabels && item.label) {
+      labelWidget = Text({
+        value: item.label,
+        size: 11,
+        color: isActive ? selectedColor : unselectedColor,
+        fontWeight: isActive ? "500" : "400",
+        className: "bottom-nav-label",
+      });
+      btn.appendChild(labelWidget);
+    }
+
+    buttons.push({
+      btn,
+      route: itemRoute,
+      icon,
+      // Store the label widget reference so updateColorsFromRouter can update
+      // it without querying the DOM.
+      labelWidget,
+    });
+    container.appendChild(btn);
+  });
+
+  // Subscribe to router changes once all buttons are built.
+  if (useRouter) {
+    unsubscribe = subscribe(() => {
+      updateColorsFromRouter();
+    });
+    // Apply initial highlighting based on the current route.
+    updateColorsFromRouter();
+    isRouterSynced = true;
+  }
+
+  // ========== PUBLIC API ==========
+
+  /**
+   * Programmatically activate a tab by index.
+   * In router mode, navigates to the tab's route. In standalone mode, updates
+   * the active index and calls `onPress` if provided.
+   *
+   * @param {number} index - Zero-based tab index.
+   */
+  container.setActiveIndex = (index) => {
+    if (!useRouter) {
+      if (index >= 0 && index < items.length && activeIndex !== index) {
+        activeIndex = index;
+        updateActive(index);
+        if (items[index].onPress) items[index].onPress();
+      }
+    } else {
+      const route =
+        items[index]?.route || `/${items[index]?.label?.toLowerCase()}`;
+      if (route) goTo(route);
+    }
+  };
+
+  /**
+   * Returns the currently active tab index.
+   *
+   * @returns {number}
+   */
+  container.getActiveIndex = () => activeIndex;
+
+  /**
+   * Returns the current router path (router mode only).
+   *
+   * @returns {string|null}
+   */
+  container.getCurrentRoute = () => {
+    if (!useRouter) return null;
+    return getCurrentPath();
+  };
+
+  // Cleanup: unsubscribe from the router when the bar is removed from the DOM.
+  const originalCleanup = container._cleanup;
+  container._cleanup = () => {
+    if (unsubscribe) unsubscribe();
+    if (originalCleanup) originalCleanup();
+  };
+
+  return container;
+};
+
+export default BottomNavigation;