flet-box 0.0.0-stage → 1.0.2

package/src/navigations/CollapsibleSideBar.js

@@ -0,0 +1,139 @@
+// navigations/CollapsibleSideBar.js
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Container } from "../widgets/Container.js";
+import { Column } from "../widgets/Column.js";
+import { Icon } from "../widgets/Icon.js";
+import { useState } from "../tools/useState.js";
+import { colors } from "../utils/themes.js";
+
+/**
+ * @typedef {Object} CollapsibleSideBarProps
+ * @property {HTMLElement} [children] - Content widget rendered inside the scrollable area.
+ * @property {boolean} [expanded=true] - Initial expanded state.
+ * @property {string} [id] - Stable identifier used to persist the expanded state across
+ *   page navigations via `useState`. When omitted, all CollapsibleSideBar instances
+ *   share the same state key, so provide an id when using multiple sidebars.
+ * @property {number} [widthExpanded=260] - Width in pixels when fully expanded.
+ * @property {number} [widthCollapsed=60] - Width in pixels when collapsed (icon-only).
+ * @property {number} [iconSize=24] - Size of the collapse/expand toggle icon.
+ * @property {Function} [onToggle] - Callback fired with the new `expanded` boolean after each toggle.
+ * @property {string} [bgColor] - Background color of the sidebar.
+ * @property {string} [borderRight] - CSS border value applied to the right edge.
+ */
+
+/**
+ * CollapsibleSideBar is a vertically scrollable side panel that can be
+ * toggled between an expanded state (showing full content) and a collapsed
+ * state (icon-only, narrow strip).
+ *
+ * The expanded state is persisted via `useState` so it survives page
+ * navigations within a session. Provide a unique `id` when rendering
+ * multiple instances to avoid state collisions.
+ *
+ * The toggle button renders a `chevron_left` icon when expanded and
+ * `chevron_right` when collapsed. The content area fades out when collapsed
+ * and has `pointer-events: none` applied, preventing accidental interaction
+ * with hidden content.
+ *
+ * Width transitions are driven by CSS `transition: width 0.3s ease` for a
+ * smooth animation without JavaScript timers.
+ *
+ * @param {CollapsibleSideBarProps} props
+ * @returns {HTMLElement} The sidebar container element, augmented with:
+ *   - `updateWidth(w: number|string)` — resize the sidebar programmatically.
+ */
+export const CollapsibleSideBar = ({
+  children,
+  expanded = true,
+  id,
+  widthExpanded = 260,
+  widthCollapsed = 60,
+  iconSize = 24,
+  onToggle,
+  bgColor = colors.surface,
+  borderRight = `1px solid ${colors.border}`,
+  ...rest
+}) => {
+  // Persist the expanded state so collapsing/expanding survives navigation.
+  // A namespaced key is used when `id` is provided to allow multiple
+  // independent sidebars on the same page.
+  const [stateValue, setIsExpanded] = useState(
+    id ? `collapsible-sidebar:${id}` : "collapsible-sidebar",
+    expanded,
+  );
+  let expandedState = Boolean(stateValue.valueOf());
+
+  /**
+   * Toggle the sidebar between expanded and collapsed states.
+   * Updates the persisted state and fires the `onToggle` callback.
+   */
+  const toggle = () => {
+    const newState = !expandedState;
+    expandedState = newState;
+    setIsExpanded(newState);
+    if (onToggle) onToggle(newState);
+  };
+
+  const currentWidth = expandedState ? widthExpanded : widthCollapsed;
+
+  // Main sidebar container — fixed width with smooth CSS width transition.
+  const container = WidgetFactory({
+    tag: "div",
+    id,
+    width:
+      typeof currentWidth === "number" ? `${currentWidth}px` : currentWidth,
+    height: "100%",
+    display: "flex",
+    flexDirection: "column",
+    backgroundColor: bgColor,
+    borderRight: borderRight,
+    transition: "width 0.3s ease",
+    overflow: "hidden",
+    flexShrink: 0,
+    ...rest,
+  });
+
+  // Toggle button — always visible so the user can expand/collapse regardless
+  // of the current state. The icon flips direction to reflect the state.
+  const toggleButton = Container({
+    padding: 16,
+    cursor: "pointer",
+    onclick: toggle,
+    child: Icon({
+      name: expandedState ? "chevron_left" : "chevron_right",
+      size: iconSize,
+      color: colors.textSecondary,
+    }),
+  });
+  container.appendChild(toggleButton);
+
+  // Content wrapper — fades and becomes non-interactive when collapsed.
+  // Opacity + pointer-events together ensure collapsed content cannot be
+  // focused or clicked, even though the DOM nodes remain mounted.
+  const contentWrapper = Container({
+    flex: 1,
+    width: "100%",
+    opacity: expandedState ? 1 : 0,
+    transition: "opacity 0.2s ease",
+    pointerEvents: expandedState ? "auto" : "none",
+    overflow: "auto",
+    child: children,
+  });
+  container.appendChild(contentWrapper);
+
+  /**
+   * Resize the sidebar to a new width without triggering a toggle.
+   * Useful when the parent layout needs to adjust sidebar proportions
+   * dynamically (e.g. responsive breakpoint changes).
+   *
+   * @param {number|string} newWidth - New width (number = pixels, string = CSS value).
+   */
+  container.updateWidth = (newWidth) => {
+    container.style.width =
+      typeof newWidth === "number" ? `${newWidth}px` : newWidth;
+  };
+
+  return container;
+};
+
+export default CollapsibleSideBar;

package/src/navigations/Drawer.js

@@ -0,0 +1,333 @@
+// src/navigations/Drawer.js
+import { Container } from "../widgets/Container.js";
+import { Column } from "../widgets/Column.js";
+import { dimensions } from "../tools/dimensions.js";
+import { colors } from "../utils/themes.js";
+
+/**
+ * Module-level singleton reference to the most recently created Drawer.
+ * The global helpers (openDrawer, closeDrawer, toggleDrawer, destroyDrawer)
+ * operate on this instance, which means only one drawer is reachable via the
+ * global API at a time. Use the returned instance object directly when you
+ * need to manage multiple drawers.
+ *
+ * @type {{open: Function, close: Function, toggle: Function, destroy: Function, element: HTMLElement}|null}
+ */
+let drawerInstance = null;
+
+/**
+ * @typedef {Object} DrawerProps
+ * @property {HTMLElement|null} [header] - Widget rendered at the top of the drawer panel.
+ * @property {HTMLElement[]} [body=[]] - Array of widgets filling the scrollable middle section.
+ * @property {HTMLElement|null} [footer] - Widget rendered at the bottom of the drawer panel.
+ * @property {"left"|"right"} [position="left"] - Which edge the drawer slides in from.
+ * @property {number|string} [width=280] - Width of the drawer panel (number = pixels).
+ * @property {Function} [onClose] - Callback fired after the close animation completes.
+ * @property {Function} [onOpen] - Callback fired immediately when the drawer opens.
+ * @property {boolean} [blur=true] - Whether to apply a backdrop blur behind the overlay.
+ * @property {number} [blurIntensity=4] - Blur radius in pixels (used when blur is true).
+ * @property {string} [bgColor] - Background color of the drawer panel.
+ * @property {number} [elevation=4] - Box-shadow depth for the panel edge.
+ * @property {boolean} [closeOnOverlayClick=true] - Whether a tap on the backdrop closes the drawer.
+ * @property {boolean} [closeOnEsc=true] - Whether the Escape key closes the drawer.
+ * @property {number} [borderRadius=24] - Corner radius applied to the panel's outer corners.
+ * @property {number} [margin=0] - Offset from the screen edge (pushes panel inward).
+ */
+
+/**
+ * @typedef {Object} DrawerInstance
+ * @property {Function} open - Slide the drawer into view.
+ * @property {Function} close - Slide the drawer out of view.
+ * @property {Function} toggle - Toggle between open and closed states.
+ * @property {Function} destroy - Remove the drawer from the DOM and clean up all listeners.
+ * @property {HTMLElement} element - The outer wrapper element appended to document.body.
+ */
+
+/**
+ * Drawer creates a slide-in panel anchored to the left or right edge of the
+ * screen. It is appended directly to `document.body` and uses a full-screen
+ * wrapper so the overlay backdrop can cover the entire viewport.
+ *
+ * Corner radius is applied only to the outer corners of the panel (i.e. the
+ * two corners that face away from the screen edge) to maintain a flush
+ * attachment at the edge side.
+ *
+ * The module keeps a singleton reference so the standalone helper functions
+ * (openDrawer, closeDrawer, etc.) can be called without passing an instance.
+ *
+ * @param {DrawerProps} [props={}]
+ * @returns {DrawerInstance}
+ */
+export const Drawer = (props = {}) => {
+  const {
+    header,
+    body = [],
+    footer,
+    position = "left",
+    width = 280,
+    onClose,
+    onOpen,
+    blur = true,
+    blurIntensity = 4,
+    bgColor = colors?.surface || "#ffffff",
+    elevation = 4,
+    closeOnOverlayClick = true,
+    closeOnEsc = true,
+    borderRadius = 24,
+    margin = 0,
+    ...rest
+  } = props;
+
+  const element = document.createElement("div");
+  let isOpen = false;
+  let closeTimer = null;
+
+  // The outer wrapper covers the full screen so the backdrop sits above all
+  // other content. It starts hidden and becomes visible on open().
+  element.style.position = "fixed";
+  element.style.top = "0";
+  element.style.left = "0";
+  element.style.width = `${dimensions.width}px`;
+  element.style.height = `${dimensions.height}px`;
+  element.style.zIndex = "10000";
+  element.style.display = "none";
+
+  // Overlay backdrop — semi-transparent with optional blur effect.
+  const overlay = document.createElement("div");
+  overlay.style.position = "absolute";
+  overlay.style.top = "0";
+  overlay.style.left = "0";
+  overlay.style.width = "100%";
+  overlay.style.height = "100%";
+  overlay.style.backdropFilter = blur ? `blur(${blurIntensity}px)` : "none";
+  overlay.style.backgroundColor = "rgba(0,0,0,0.3)";
+  overlay.style.transition = "opacity 0.3s ease";
+  overlay.style.opacity = "0";
+
+  // Sliding drawer panel.
+  const drawerPanel = document.createElement("div");
+  drawerPanel.style.position = "absolute";
+  drawerPanel.style.top = `${margin}px`;
+  drawerPanel.style.bottom = `${margin}px`;
+  drawerPanel.style.height = `calc(100% - ${margin * 2}px)`;
+  drawerPanel.style.display = "flex";
+  drawerPanel.style.flexDirection = "column";
+  drawerPanel.style.backgroundColor = bgColor;
+  drawerPanel.style.overflow = "hidden";
+
+  // Apply border radius only to the corners that face away from the screen edge.
+  // A left drawer gets rounded right corners; a right drawer gets rounded left corners.
+  if (position === "left") {
+    drawerPanel.style.left = `${margin}px`;
+    drawerPanel.style.right = "auto";
+    drawerPanel.style.borderTopRightRadius = `${borderRadius}px`;
+    drawerPanel.style.borderBottomRightRadius = `${borderRadius}px`;
+    drawerPanel.style.borderTopLeftRadius = "0";
+    drawerPanel.style.borderBottomLeftRadius = "0";
+  } else {
+    drawerPanel.style.right = `${margin}px`;
+    drawerPanel.style.left = "auto";
+    drawerPanel.style.borderTopLeftRadius = `${borderRadius}px`;
+    drawerPanel.style.borderBottomLeftRadius = `${borderRadius}px`;
+    drawerPanel.style.borderTopRightRadius = "0";
+    drawerPanel.style.borderBottomRightRadius = "0";
+  }
+
+  drawerPanel.style.width = typeof width === "number" ? `${width}px` : width;
+  // Start the panel off-screen so the entrance animation slides it in.
+  drawerPanel.style.transform =
+    position === "left" ? "translateX(-100%)" : "translateX(100%)";
+  drawerPanel.style.transition = "transform 0.3s ease-out";
+
+  // Shadow faces inward, away from the attachment edge.
+  if (elevation > 0) {
+    if (position === "left") {
+      drawerPanel.style.boxShadow = `${elevation}px 0 ${elevation * 2}px rgba(0,0,0,0.15)`;
+    } else {
+      drawerPanel.style.boxShadow = `-${elevation}px 0 ${elevation * 2}px rgba(0,0,0,0.15)`;
+    }
+  }
+
+  // ========== BUILD PANEL CONTENT ==========
+  // The header and footer containers intentionally only round the corners
+  // that align with the panel's outer edge, so content fills flush at the
+  // attachment side.
+  const contentContainer = Column({
+    height: "100%",
+    display: "flex",
+    flexDirection: "column",
+    children: [
+      header &&
+        Container({
+          flexShrink: 0,
+          borderTopLeftRadius: position === "right" ? `${borderRadius}px` : "0",
+          borderTopRightRadius: position === "left" ? `${borderRadius}px` : "0",
+          overflow: "hidden",
+          child: header,
+        }),
+
+      body.length > 0 &&
+        Column({
+          flex: 1,
+          paddingTop: 8,
+          paddingBottom: 8,
+          overflow: "auto",
+          backgroundColor: bgColor,
+          children: body,
+        }),
+
+      footer &&
+        Container({
+          flexShrink: 0,
+          borderBottomLeftRadius:
+            position === "right" ? `${borderRadius}px` : "0",
+          borderBottomRightRadius:
+            position === "left" ? `${borderRadius}px` : "0",
+          overflow: "hidden",
+          child: footer,
+        }),
+    ].filter(Boolean),
+  });
+
+  drawerPanel.appendChild(contentContainer);
+  element.appendChild(overlay);
+  element.appendChild(drawerPanel);
+
+  // ========== KEYBOARD HANDLER ==========
+  const handleKeyDown = (e) => {
+    if (closeOnEsc && e.key === "Escape" && isOpen) {
+      close();
+    }
+  };
+
+  // ========== CLOSE ==========
+  /**
+   * Slide the drawer out of view with a CSS transition.
+   * The outer wrapper is hidden after the transition completes (300ms) to
+   * remove it from the accessibility tree. Re-entrant calls are ignored.
+   */
+  const close = () => {
+    if (!isOpen) return;
+    isOpen = false;
+    // Cancel any pending hide timer from a previous close call.
+    if (closeTimer) {
+      clearTimeout(closeTimer);
+      closeTimer = null;
+    }
+    drawerPanel.style.transform =
+      position === "left" ? "translateX(-100%)" : "translateX(100%)";
+    overlay.style.opacity = "0";
+    closeTimer = setTimeout(() => {
+      element.style.display = "none";
+      closeTimer = null;
+      if (onClose) onClose();
+    }, 300);
+    if (closeOnEsc) document.removeEventListener("keydown", handleKeyDown);
+  };
+
+  // ========== OPEN ==========
+  /**
+   * Slide the drawer into view.
+   * Forces a reflow (offsetHeight read) before applying the transition so
+   * the animation plays even when the element was just made visible.
+   * Re-entrant calls are ignored.
+   */
+  const open = () => {
+    if (isOpen) return;
+    isOpen = true;
+    if (closeTimer) {
+      clearTimeout(closeTimer);
+      closeTimer = null;
+    }
+    element.style.display = "block";
+    // Trigger a reflow so the browser registers the initial transform value
+    // before the transition starts; without this the animation is skipped.
+    void element.offsetHeight;
+    overlay.style.opacity = "1";
+    drawerPanel.style.transform = "translateX(0)";
+    if (onOpen) onOpen();
+    if (closeOnEsc) document.addEventListener("keydown", handleKeyDown);
+  };
+
+  /**
+   * Toggle between open and closed states.
+   */
+  const toggle = () => {
+    if (isOpen) close();
+    else open();
+  };
+
+  /**
+   * Remove the drawer element from the DOM and release all listeners.
+   * After destroy() the instance is no longer usable.
+   */
+  const destroy = () => {
+    if (closeTimer) clearTimeout(closeTimer);
+    if (closeOnEsc) document.removeEventListener("keydown", handleKeyDown);
+    removeResizeListener();
+    if (element.parentNode) element.parentNode.removeChild(element);
+  };
+
+  if (closeOnOverlayClick) {
+    overlay.addEventListener("click", close);
+  }
+
+  // Keep the wrapper dimensions in sync with the viewport when the window
+  // is resized (e.g. orientation change on mobile).
+  const handleResize = () => {
+    element.style.width = `${dimensions.width}px`;
+    element.style.height = `${dimensions.height}px`;
+  };
+  const removeResizeListener = dimensions.addListener(handleResize);
+
+  const instance = { open, close, toggle, destroy, element };
+  // Register as the module-level singleton so global helpers work.
+  drawerInstance = instance;
+  document.body.appendChild(element);
+
+  return instance;
+};
+
+// ========== GLOBAL HELPER FUNCTIONS ==========
+// These operate on the most recently created Drawer instance.
+// Use the instance returned by Drawer() directly when managing multiple drawers.
+
+/**
+ * Open the most recently created Drawer.
+ * Logs a warning if no Drawer has been initialised yet.
+ */
+export const openDrawer = () => {
+  if (drawerInstance) drawerInstance.open();
+  else console.warn("Drawer not initialized");
+};
+
+/**
+ * Close the most recently created Drawer.
+ * Logs a warning if no Drawer has been initialised yet.
+ */
+export const closeDrawer = () => {
+  if (drawerInstance) drawerInstance.close();
+  else console.warn("Drawer not initialized");
+};
+
+/**
+ * Toggle the most recently created Drawer.
+ * Logs a warning if no Drawer has been initialised yet.
+ */
+export const toggleDrawer = () => {
+  if (drawerInstance) drawerInstance.toggle();
+  else console.warn("Drawer not initialized");
+};
+
+/**
+ * Destroy the most recently created Drawer and clear the singleton reference.
+ * Safe to call even when no drawer exists.
+ */
+export const destroyDrawer = () => {
+  if (drawerInstance) {
+    drawerInstance.destroy();
+    drawerInstance = null;
+  }
+};
+
+export default Drawer;