flet-box 0.0.0-stage → 1.0.2

package/src/widgets/AlertDialog.js

@@ -0,0 +1,162 @@
+/**
+ * @file AlertDialog.js
+ * @description A modal alert dialog built on top of the Modal widget.
+ * Supports four semantic variants (normal, danger, warning, success), each
+ * with its own icon and accent color. Exposes open/close methods and fires
+ * optional callbacks on confirm, cancel, and close.
+ */
+
+import { Modal } from "./Modal.js";
+import { Button } from "./Button.js";
+import { Text } from "./Text.js";
+import { Column } from "./Column.js";
+import { Icon } from "./Icon.js";
+import { colors } from "../utils/themes.js";
+
+/**
+ * Creates an AlertDialog — a pre-styled modal with a title, message, icon,
+ * and confirm/cancel buttons whose appearance adapts to the chosen variant.
+ *
+ * Returns a plain object (not an HTMLElement) with `open`, `close`, and
+ * `modal` so the caller can programmatically control visibility while keeping
+ * the underlying Modal instance accessible for advanced use.
+ *
+ * @param {Object} props - Configuration for the dialog.
+ * @param {string} props.title - Heading text shown at the top of the dialog.
+ * @param {string} props.message - Body text providing more detail to the user.
+ * @param {Function} [props.onConfirm] - Called when the user clicks the confirm button, before the dialog closes.
+ * @param {Function} [props.onCancel] - Called when the user clicks the cancel button, before the dialog closes.
+ * @param {Function} [props.onClose] - Called whenever the dialog closes, regardless of how it was dismissed.
+ * @param {'normal'|'danger'|'warning'|'success'} [props.variant='normal'] - Determines the icon and button accent color.
+ * @param {boolean} [props.showCancel=true] - When false, the cancel button is omitted.
+ * @param {string} [props.confirmText='Accept'] - Label for the confirm button.
+ * @param {string} [props.cancelText='Cancel'] - Label for the cancel button.
+ * @returns {{ open: Function, close: Function, modal: HTMLElement }} Controller object for the dialog.
+ */
+export const AlertDialog = (props) => {
+  let {
+    title,
+    message,
+    onConfirm,
+    onCancel,
+    onClose,
+    variant = "normal", // 'normal', 'danger', 'warning', 'success'
+    showCancel = true,
+    confirmText = "Accept",
+    cancelText = "Cancel",
+    ...rest
+  } = props;
+
+  // Map each variant to its icon name, icon color, and confirm-button color
+  const variantColors = {
+    normal: { confirm: colors.primary, icon: "info", iconColor: colors.info },
+    danger: {
+      confirm: colors.danger,
+      icon: "warning",
+      iconColor: colors.danger,
+    },
+    warning: {
+      confirm: colors.warning,
+      icon: "error",
+      iconColor: colors.warning,
+    },
+    success: {
+      confirm: colors.success,
+      icon: "check_circle",
+      iconColor: colors.success,
+    },
+  };
+  const variantStyle = variantColors[variant] || variantColors.normal;
+
+  // Decorative icon at the top of the dialog body
+  const icon = Icon({
+    name: variantStyle.icon,
+    size: 40,
+    color: variantStyle.iconColor,
+    marginBottom: 8,
+  });
+
+  // Centered column: icon → title → message
+  const content = Column({
+    alignItems: "center",
+    textAlign: "center",
+    children: [
+      icon,
+      Text({
+        value: title,
+        size: 24,
+        fontWeight: "bold",
+        color: colors.text,
+        textAlign: "center",
+      }),
+      Text({
+        value: message,
+        size: 18,
+        fontWeight: "bold",
+        color: colors.textSecondary,
+        textAlign: "center",
+        marginTop: 8,
+      }),
+    ],
+  });
+
+  // Build the action-button row — cancel first (if shown), then confirm
+  const actions = [];
+
+  if (showCancel) {
+    actions.push(
+      Button({
+        text: cancelText,
+        borderColor: colors.danger,
+        variant: "filled",
+        color: colors.danger,
+        onPress: () => {
+          if (onCancel) onCancel();
+          closeModal();
+        },
+      }),
+    );
+  }
+
+  actions.push(
+    Button({
+      text: confirmText,
+      variant: "filled",
+      bgColor: variantStyle.confirm,
+      color: colors.text,
+      borderColor: colors.surface,
+      onPress: () => {
+        if (onConfirm) onConfirm();
+        closeModal();
+      },
+    }),
+  );
+
+  let modal = null;
+  // Placeholder until the modal is created below — avoids a temporal dead-zone
+  let closeModal = () => {};
+
+  // Delegate to the base Modal widget, passing our content and actions
+  modal = Modal({
+    content: content,
+    actions: actions,
+    showCloseButton: false,
+    width: 320,
+    borderRadius: 24,
+    onClose: () => {
+      if (onClose) onClose();
+    },
+    ...rest,
+  });
+
+  // Now that modal exists, wire up the real close function
+  closeModal = () => modal.close();
+
+  // Public controller API
+  const open = () => modal.open();
+  const close = () => modal.close();
+
+  return { open, close, modal };
+};
+
+export default AlertDialog;

package/src/widgets/Audio.js

@@ -0,0 +1,311 @@
+/**
+ * @file Audio.js
+ * @description A thin wrapper around the native `<audio>` element that adds
+ * reliable duration detection (with an AudioContext fallback for formats where
+ * the browser cannot report duration from metadata alone), progress callbacks,
+ * and a clean imperative API for controlling playback.
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+
+/**
+ * Creates an Audio widget — an `<audio>` element enriched with helper methods
+ * and reliable duration detection.
+ *
+ * Duration detection works in three stages:
+ * 1. Read directly from `audio.duration` on `loadedmetadata` / `canplay`.
+ * 2. Poll every 200 ms for up to two seconds if the element still reports NaN or Infinity.
+ * 3. Fetch the file as an ArrayBuffer and decode it with AudioContext as a last resort.
+ *
+ * @param {Object} props - Configuration for the audio widget.
+ * @param {string} props.src - URL of the audio file to load.
+ * @param {boolean} [props.autoplay=false] - Whether playback starts automatically on load.
+ * @param {boolean} [props.controls=false] - Whether to render the browser's native playback controls.
+ * @param {boolean} [props.loop=false] - Whether playback restarts automatically when the track ends.
+ * @param {boolean} [props.muted=false] - Whether the audio starts muted.
+ * @param {number} [props.volume=1] - Initial volume level (0.0–1.0).
+ * @param {Function} [props.onPlay] - Fired when playback begins.
+ * @param {Function} [props.onPause] - Fired when playback is paused.
+ * @param {Function} [props.onEnd] - Fired when the track finishes.
+ * @param {Function} [props.onTimeUpdate] - Fired on each timeupdate event. Receives `(currentTime, duration, percentPlayed)`.
+ * @param {Function} [props.onProgress] - Fired on each timeupdate event with only the percent value.
+ * @param {Function} [props.onLoad] - Fired once when the duration is successfully resolved. Receives `(duration)`.
+ * @param {Function} [props.ref] - Callback that receives the `<audio>` element after creation.
+ * @returns {HTMLAudioElement} The audio element, extended with playback control methods.
+ */
+export const Audio = (props) => {
+  const {
+    src,
+    autoplay = false,
+    controls = false,
+    loop = false,
+    muted = false,
+    volume = 1,
+    onPlay,
+    onPause,
+    onEnd,
+    onTimeUpdate,
+    onProgress,
+    onLoad,
+    ref,
+    ...rest
+  } = props;
+
+  const audio = WidgetFactory({
+    tag: "audio",
+    widgetName: "Audio",
+    src: src,
+    ...rest,
+  });
+
+  // Audio attributes are element properties, not CSS attributes — set them directly
+  audio.controls = Boolean(controls);
+  audio.loop = Boolean(loop);
+  audio.muted = Boolean(muted);
+  audio.autoplay = Boolean(autoplay);
+  audio.preload = "metadata";
+  audio.volume = typeof volume === "number" ? volume : 1;
+
+  // Keep native play/pause bound before we might override them
+  const nativePlay = audio.play.bind(audio);
+  const nativePause = audio.pause.bind(audio);
+
+  let currentTime = 0;
+  let duration = 0;
+  let durationPoll = null;
+  let audioContextFallbackAttempted = false;
+
+  /**
+   * Recalculates the current playback position and fires the progress callbacks.
+   * Called on every `timeupdate` event from the element.
+   */
+  const updateTime = () => {
+    currentTime = audio.currentTime || 0;
+    const percent = duration ? (currentTime / duration) * 100 : 0;
+    if (onTimeUpdate) onTimeUpdate(currentTime, duration, percent);
+    if (onProgress) onProgress(percent);
+  };
+
+  /**
+   * Stores the resolved duration and fires `onLoad` exactly once.
+   * Clears any active polling interval once the duration is known.
+   *
+   * @param {number} dur - The resolved audio duration in seconds.
+   */
+  const setDuration = (dur) => {
+    if (dur > 0 && duration === 0) {
+      duration = dur;
+      if (onLoad) onLoad(duration);
+      if (durationPoll) clearInterval(durationPoll);
+      durationPoll = null;
+    }
+  };
+
+  /**
+   * Attempts to read the duration directly from the audio element.
+   *
+   * @returns {boolean} `true` if a valid finite duration was obtained.
+   */
+  const tryGetDurationFromAudio = () => {
+    const d = audio.duration;
+    if (d && d !== Infinity && d > 0) {
+      setDuration(d);
+      return true;
+    }
+    return false;
+  };
+
+  /**
+   * Starts a polling interval that retries duration detection every 200 ms.
+   * Useful for formats (e.g. MP3 with VBR) where the browser reports duration
+   * later than `loadedmetadata`.
+   */
+  const pollDuration = () => {
+    if (durationPoll) return;
+    durationPoll = setInterval(() => {
+      if (tryGetDurationFromAudio()) {
+        clearInterval(durationPoll);
+        durationPoll = null;
+      }
+    }, 200);
+  };
+
+  /**
+   * Last-resort fallback: fetches the audio file as a binary buffer, decodes
+   * it with the Web Audio API, and extracts the duration from the resulting
+   * AudioBuffer. Only attempted once per instance.
+   *
+   * This is necessary for some file formats where the browser's media pipeline
+   * cannot determine duration without fully downloading the file.
+   */
+  const fallbackGetDuration = async () => {
+    if (audioContextFallbackAttempted) return;
+    audioContextFallbackAttempted = true;
+
+    try {
+      const response = await fetch(src);
+      const arrayBuffer = await response.arrayBuffer();
+      const audioContext = new (
+        window.AudioContext || window.webkitAudioContext
+      )();
+      const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+      const durationSeconds = audioBuffer.duration;
+      setDuration(durationSeconds);
+      audioContext.close();
+    } catch (err) {
+      console.warn("[Audio] Fallback duration fetch failed:", err);
+    }
+  };
+
+  // Wire up native audio element events
+  audio.addEventListener("loadedmetadata", () => {
+    if (!tryGetDurationFromAudio()) pollDuration();
+  });
+  audio.addEventListener("durationchange", () => tryGetDurationFromAudio());
+  audio.addEventListener("canplay", () => {
+    if (!tryGetDurationFromAudio()) pollDuration();
+  });
+  audio.addEventListener("timeupdate", updateTime);
+  audio.addEventListener("play", () => {
+    if (onPlay) onPlay();
+  });
+  audio.addEventListener("pause", () => {
+    if (onPause) onPause();
+  });
+  audio.addEventListener("ended", () => {
+    if (onEnd) onEnd();
+  });
+  audio.addEventListener("error", (e) => console.warn("[Audio] Error:", e));
+
+  // Kick off duration detection immediately; if unavailable after 2 s, use fetch fallback
+  if (!tryGetDurationFromAudio()) {
+    pollDuration();
+    setTimeout(() => {
+      if (!duration) fallbackGetDuration();
+    }, 2000);
+  }
+
+  // Cancel the duration polling interval when the widget unmounts
+  audio.onUnmount(() => {
+    if (durationPoll) clearInterval(durationPoll);
+  });
+
+  // ========== PUBLIC PLAYBACK API ==========
+
+  /**
+   * Starts playback. Silently swallows the NotAllowedError thrown by browsers
+   * that require a user gesture before audio can play.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.playAudio = () => {
+    nativePlay().catch((e) => console.warn(e));
+    return audio;
+  };
+
+  /**
+   * Pauses playback.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.pauseAudio = () => {
+    nativePause();
+    return audio;
+  };
+
+  /**
+   * Stops playback and resets the playhead to the beginning.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.stop = () => {
+    nativePause();
+    audio.currentTime = 0;
+    updateTime();
+    return audio;
+  };
+
+  /**
+   * Seeks to an absolute position in seconds.
+   * Silently ignores out-of-range values.
+   *
+   * @param {number} seconds - Target time in seconds.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.seekTo = (seconds) => {
+    if (seconds >= 0 && seconds <= (duration || audio.duration)) {
+      audio.currentTime = seconds;
+      updateTime();
+    }
+    return audio;
+  };
+
+  /**
+   * Seeks to a percentage of the total duration (0–100).
+   *
+   * @param {number} percent - Target position as a percentage.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.seekToPercent = (percent) => {
+    const total = duration || audio.duration;
+    if (total) audio.seekTo((percent / 100) * total);
+    return audio;
+  };
+
+  /** @returns {number} The current playback position in seconds. */
+  audio.getCurrentTime = () => currentTime;
+
+  /** @returns {number} The total track duration in seconds, or 0 if not yet known. */
+  audio.getDuration = () => duration || audio.duration || 0;
+
+  /** @returns {number} The current playback position as a percentage (0–100). */
+  audio.getProgressPercent = () => {
+    const total = duration || audio.duration;
+    return total ? (currentTime / total) * 100 : 0;
+  };
+
+  /**
+   * Increases volume by `step` (clamped to 1.0).
+   * @param {number} [step=0.1] - Volume increment.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.volumeUp = (step = 0.1) => {
+    audio.volume = Math.min(1, audio.volume + step);
+    return audio;
+  };
+
+  /**
+   * Decreases volume by `step` (clamped to 0.0).
+   * @param {number} [step=0.1] - Volume decrement.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.volumeDown = (step = 0.1) => {
+    audio.volume = Math.max(0, audio.volume - step);
+    return audio;
+  };
+
+  /**
+   * Mutes the audio element without changing the volume setting.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.muteAudio = () => {
+    audio.muted = true;
+    return audio;
+  };
+
+  /**
+   * Unmutes the audio element.
+   * @returns {HTMLAudioElement} The audio element (for chaining).
+   */
+  audio.unmuteAudio = () => {
+    audio.muted = false;
+    return audio;
+  };
+
+  /** @returns {boolean} `true` if the audio is currently playing. */
+  audio.isPlaying = () => !audio.paused;
+
+  // Expose the element via ref callback if provided
+  if (ref && typeof ref === "function") ref(audio);
+
+  return audio;
+};
+
+export default Audio;

package/src/widgets/Avatar.js

@@ -0,0 +1,210 @@
+/**
+ * @file Avatar.js
+ * @description A user avatar widget that renders an image, an icon, or
+ * initials derived from a name, depending on what props are provided.
+ * Falls back gracefully: image → icon → initials → generic person icon.
+ * Supports circular, rounded-square, and square shapes, and exposes a method
+ * to update its content without rebuilding the DOM.
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+import { colors } from "../utils/themes.js";
+import { Image } from "./Image.js";
+import { Icon } from "./Icon.js";
+import { Text } from "./Text.js";
+
+/**
+ * Creates an Avatar widget.
+ *
+ * Content priority (first match wins):
+ * 1. `src` — renders an `<img>` filling the avatar circle.
+ * 2. `icon` — renders a Material icon centered in the avatar.
+ * 3. `name` — extracts up to two initials and renders them as text.
+ * 4. Fallback — renders a generic "person" icon.
+ *
+ * @param {Object} props - Configuration for the avatar.
+ * @param {string} [props.src] - URL of a profile image.
+ * @param {string} [props.name] - Full name from which initials are derived (e.g. "Jane Doe" → "JD").
+ * @param {number} [props.size=40] - Diameter of the avatar in pixels.
+ * @param {number} [props.fontSize=16] - Font size of initials text in pixels (overridden by the auto-computed size when `size` changes).
+ * @param {'circle'|'rounded'|'square'} [props.shape='circle'] - Shape of the avatar container.
+ * @param {string} [props.bgColor=colors.primary] - Background color shown behind icons or initials.
+ * @param {string} [props.textColor=colors.text] - Color of icon or initials.
+ * @param {string} [props.icon] - Material icon name to display instead of an image or initials.
+ * @param {Function} [props.onPress] - Click handler. When provided, a hover scale effect is also applied.
+ * @returns {HTMLElement} The avatar container element, augmented with an `updateContent` method.
+ */
+export const Avatar = (props) => {
+  let {
+    src,
+    name,
+    size = 40,
+    fontSize = 16,
+    shape = "circle",
+    bgColor = colors.primary,
+    textColor = colors.text,
+    icon,
+    onPress,
+    ...rest
+  } = props;
+
+  // Map shape to a CSS border-radius value
+  let borderRadius = "50%";
+  if (shape === "rounded") borderRadius = `${size * 0.2}px`;
+  if (shape === "square") borderRadius = "0";
+
+  /**
+   * Extracts up to two initials from a full name.
+   * Single-word names return just the first letter; multi-word names use
+   * the first letter of the first and last words.
+   *
+   * @param {string} fullName - The user's full name.
+   * @returns {string} 1–2 uppercase initials, or "?" if the name is empty.
+   */
+  const getInitials = (fullName) => {
+    if (!fullName) return "?";
+    const parts = fullName.trim().split(/\s+/);
+    if (parts.length === 1) return parts[0].charAt(0).toUpperCase();
+    return (
+      parts[0].charAt(0) + parts[parts.length - 1].charAt(0)
+    ).toUpperCase();
+  };
+
+  // Choose the appropriate child element based on prop priority
+  let content = null;
+  if (src) {
+    content = Image({
+      src: src,
+      width: "100%",
+      height: "100%",
+      fit: "cover",
+    });
+  } else if (icon) {
+    content = Icon({
+      name: icon,
+      size: size * 0.5,
+      color: textColor,
+    });
+  } else if (name) {
+    const initials = getInitials(name);
+    content = Text({
+      text: initials,
+      color: textColor,
+      size: size * 0.4,
+      weight: "bold",
+    });
+  } else {
+    // Generic fallback when no content is supplied
+    content = Icon({
+      name: "person",
+      size: size * 0.5,
+      color: textColor,
+    });
+  }
+
+  const avatar = WidgetFactory({
+    widgetName: "Avatar",
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: size,
+    height: size,
+    borderRadius: borderRadius,
+    backgroundColor: bgColor,
+    color: textColor,
+    overflow: "hidden",
+    fontSize: fontSize,
+    fontWeight: "500",
+    userSelect: "none",
+    cursor: onPress ? "pointer" : "default",
+    transition: "transform 0.2s ease",
+    child: content,
+    onclick: onPress,
+    ...rest,
+  });
+
+  // Add a subtle scale-up on hover when the avatar is interactive
+  if (onPress) {
+    avatar.addEventListener("mouseenter", () => {
+      avatar.style.transform = "scale(1.05)";
+    });
+    avatar.addEventListener("mouseleave", () => {
+      avatar.style.transform = "scale(1)";
+    });
+  }
+
+  /**
+   * Updates the avatar's content and/or dimensions without recreating the element.
+   * Only the properties present in `newProps` are applied; others are left as-is.
+   *
+   * @param {Object} newProps - Partial props to apply.
+   * @param {string} [newProps.src] - New image URL.
+   * @param {string} [newProps.name] - New name (re-derives initials).
+   * @param {string} [newProps.icon] - New icon name.
+   * @param {string} [newProps.bgColor] - New background color.
+   * @param {number|string} [newProps.size] - New avatar diameter.
+   */
+  avatar.updateContent = (newProps) => {
+    // Sync the mutable local variables with any supplied overrides
+    if (newProps.src !== undefined) src = newProps.src;
+    if (newProps.name !== undefined) name = newProps.name;
+    if (newProps.icon !== undefined) icon = newProps.icon;
+    if (newProps.bgColor !== undefined)
+      avatar.style.backgroundColor = newProps.bgColor;
+    if (newProps.size !== undefined) {
+      const newSize = newProps.size;
+      avatar.style.width =
+        typeof newSize === "number" ? `${newSize}px` : newSize;
+      avatar.style.height =
+        typeof newSize === "number" ? `${newSize}px` : newSize;
+      avatar.style.fontSize =
+        typeof newSize === "number" ? `${newSize * 0.4}px` : "16px";
+    }
+
+    // Rebuild the inner content using the updated props
+    let newContent = null;
+    if (newProps.src !== undefined || src !== undefined) {
+      const finalSrc = newProps.src !== undefined ? newProps.src : src;
+      newContent = Image({
+        src: finalSrc,
+        width: "100%",
+        height: "100%",
+        fit: "cover",
+      });
+    } else if (newProps.icon !== undefined || icon !== undefined) {
+      const finalIcon = newProps.icon !== undefined ? newProps.icon : icon;
+      const finalSize = newProps.size || size;
+      newContent = Icon({
+        name: finalIcon,
+        size: finalSize * 0.5,
+        color: textColor,
+      });
+    } else if (newProps.name !== undefined || name !== undefined) {
+      const finalName = newProps.name !== undefined ? newProps.name : name;
+      const initials = getInitials(finalName);
+      const finalSize = newProps.size || size;
+      newContent = Text({
+        text: initials,
+        color: textColor,
+        size: finalSize * 0.4,
+        weight: "bold",
+      });
+    } else {
+      const finalSize = newProps.size || size;
+      newContent = Icon({
+        name: "person",
+        size: finalSize * 0.5,
+        color: textColor,
+      });
+    }
+
+    // Replace the existing child with the new content
+    while (avatar.firstChild) avatar.removeChild(avatar.firstChild);
+    avatar.appendChild(newContent);
+    avatar._child = newContent;
+  };
+
+  return avatar;
+};
+
+export default Avatar;