@julianoczkowski/create-trimble-app 2.0.0

package/templates/react/src/components/ModusToast.tsx

@@ -0,0 +1,207 @@
+
+
+import { useEffect, useRef, useCallback } from "react";
+import { ModusWcToast, ModusWcButton } from "@trimble-oss/moduswebcomponents-react";
+import ModusAlert from "./ModusAlert";
+
+export type ToastPosition =
+  | "top-start"
+  | "top-center"
+  | "top-end"
+  | "middle-start"
+  | "middle-center"
+  | "middle-end"
+  | "bottom-start"
+  | "bottom-center"
+  | "bottom-end";
+
+export type ToastVariant = "info" | "success" | "warning" | "error";
+
+/**
+ * Represents an action button for a toast.
+ */
+export interface ModusToastAction {
+  /** The label for the action button. */
+  label: string;
+  /** The color of the action button. */
+  color?: 'primary' | 'secondary' | 'tertiary' | 'warning' | 'danger';
+  /** The variant of the action button. */
+  variant?: 'filled' | 'outlined' | 'borderless';
+  /** The size of the action button. */
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  /** Whether to dismiss the toast when the action is clicked. */
+  dismissOnAction?: boolean;
+  /** A callback function to handle action clicks. */
+  onClick?: (toastId: string) => void;
+}
+
+/**
+ * Represents a single toast item.
+ */
+export interface ModusToastItem {
+  /** A unique identifier for the toast. */
+  id: string;
+  /** The title of the toast. */
+  title: string;
+  /** The description of the toast. */
+  description?: string;
+  /** The variant of the toast. */
+  variant?: ToastVariant;
+  /** Whether the toast can be dismissed. */
+  dismissible?: boolean;
+  /** The delay in milliseconds before the toast is automatically dismissed. */
+  delay?: number | null;
+  /** The position of the toast. */
+  position?: ToastPosition;
+  /** A custom CSS class to apply to the toast. */
+  customClass?: string;
+  /** An action button to display in the toast. */
+  action?: ModusToastAction;
+}
+
+/**
+ * Props for the ModusToast component.
+ */
+interface ModusToastProps {
+  /** The toasts to display. */
+  toasts: ModusToastItem[];
+  /** The default position for toasts. */
+  defaultPosition?: ToastPosition;
+  /** The default delay in milliseconds before toasts are automatically dismissed. */
+  defaultDelay?: number | null;
+  /** A custom CSS class to apply to the toast container. */
+  customClass?: string;
+  /** A CSS class to apply to the toast container. */
+  className?: string;
+  /** A callback function to handle toast dismissals. */
+  onDismiss?: (toastId: string) => void;
+  /** A callback function to handle toast actions. */
+  onAction?: (toastId: string) => void;
+}
+
+/**
+ * Renders a Modus toast component.
+ * @param {ModusToastProps} props - The component props.
+ * @returns {JSX.Element} The rendered toast component.
+ */
+export default function ModusToast({
+  toasts,
+  defaultPosition = 'top-end',
+  defaultDelay,
+  customClass,
+  className = 'relative w-full pointer-events-none',
+  onDismiss,
+  onAction,
+}: ModusToastProps) {
+  const timers = useRef<Map<string, number>>(new Map());
+
+  const handleDismiss = useCallback(
+    (toastId: string) => {
+      const timeoutId = timers.current.get(toastId);
+      if (timeoutId) {
+        window.clearTimeout(timeoutId);
+        timers.current.delete(toastId);
+      }
+      onDismiss?.(toastId);
+    },
+    [onDismiss]
+  );
+
+  const handleActionClick = useCallback(
+    (toast: ModusToastItem) => {
+      toast.action?.onClick?.(toast.id);
+      onAction?.(toast.id);
+
+      if (toast.action?.dismissOnAction !== false) {
+        handleDismiss(toast.id);
+      }
+    },
+    [handleDismiss, onAction]
+  );
+
+  const resolveDelay = useCallback(
+    (toast: ModusToastItem) => {
+      if (toast.delay === null) {
+        return undefined;
+      }
+      if (typeof toast.delay === "number") {
+        return toast.delay;
+      }
+      if (typeof defaultDelay === "number") {
+        return defaultDelay;
+      }
+      return 4000;
+    },
+    [defaultDelay]
+  );
+
+  useEffect(() => {
+    const activeToastIds = new Set(toasts.map((toast) => toast.id));
+
+    timers.current.forEach((timeoutId, storedId) => {
+      if (!activeToastIds.has(storedId)) {
+        window.clearTimeout(timeoutId);
+        timers.current.delete(storedId);
+      }
+    });
+
+    toasts.forEach((toast) => {
+      const delayMs = resolveDelay(toast);
+      if (typeof delayMs === "number" && delayMs > 0 && !timers.current.has(toast.id)) {
+        const timeoutId = window.setTimeout(() => {
+          handleDismiss(toast.id);
+        }, delayMs);
+        timers.current.set(toast.id, timeoutId);
+      }
+    });
+  }, [toasts, resolveDelay, handleDismiss]);
+
+  useEffect(() => {
+    const timersMap = timers.current;
+    return () => {
+      timersMap.forEach((timeoutId) => window.clearTimeout(timeoutId));
+      timersMap.clear();
+    };
+  }, []);
+
+  return (
+    <div className={className}>
+      {toasts.map((toast) => {
+        const resolvedDelay = resolveDelay(toast);
+        const toastDelay =
+          typeof resolvedDelay === "number" && resolvedDelay > 0 ? resolvedDelay : undefined;
+        const toastPosition = toast.position ?? defaultPosition;
+
+        return (
+          <div key={toast.id} className="pointer-events-auto">
+            <ModusWcToast
+              position={toastPosition}
+              delay={toastDelay}
+              custom-class={toast.customClass ?? customClass}
+            >
+              <ModusAlert
+                alertTitle={toast.title}
+                alertDescription={toast.description}
+                variant={toast.variant ?? "info"}
+                dismissible={toast.dismissible}
+                onDismissClick={() => handleDismiss(toast.id)}
+              >
+                {toast.action && (
+                  <ModusWcButton
+                    slot="button"
+                    color={toast.action.color ?? "primary"}
+                    variant={toast.action.variant ?? "filled"}
+                    size={toast.action.size ?? "sm"}
+                    onButtonClick={() => handleActionClick(toast)}
+                  >
+                    {toast.action.label}
+                  </ModusWcButton>
+                )}
+              </ModusAlert>
+            </ModusWcToast>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/react/src/components/ModusToolbar.tsx

@@ -0,0 +1,70 @@
+
+
+import type { ReactNode } from "react";
+import { forwardRef } from "react";
+import { ModusWcToolbar } from "@trimble-oss/moduswebcomponents-react";
+
+/**
+ * Props for the ModusToolbar component.
+ */
+export interface ModusToolbarProps {
+  /** The content to display at the start of the toolbar. */
+  startContent?: ReactNode;
+  /** The content to display in the center of the toolbar. */
+  centerContent?: ReactNode;
+  /** The content to display at the end of the toolbar. */
+  endContent?: ReactNode;
+  /** The main content of the toolbar. */
+  children?: ReactNode;
+  /** The ARIA label for the toolbar. */
+  ariaLabel?: string;
+  /** A custom CSS class to apply to the toolbar. */
+  customClass?: string;
+  /** A CSS class to apply to the toolbar. */
+  className?: string;
+  /** The ARIA role of the toolbar. */
+  role?: string;
+}
+
+/**
+ * Renders a Modus toolbar component.
+ * @param {ModusToolbarProps} props - The component props.
+ * @param {React.Ref<HTMLModusWcToolbarElement>} ref - The ref object for the toolbar.
+ * @returns {JSX.Element} The rendered toolbar component.
+ */
+const ModusToolbar = forwardRef<HTMLModusWcToolbarElement, ModusToolbarProps>(
+  (
+    {
+      startContent,
+      centerContent,
+      endContent,
+      children,
+      ariaLabel,
+      customClass,
+      className,
+      role,
+    },
+    ref
+  ) => {
+    const combinedClass =
+      [customClass, className].filter(Boolean).join(" ") || undefined;
+
+    return (
+      <ModusWcToolbar
+        ref={ref}
+        aria-label={ariaLabel}
+        role={role}
+        custom-class={combinedClass}
+      >
+        {startContent && <div slot="start">{startContent}</div>}
+        {centerContent && <div slot="center">{centerContent}</div>}
+        {endContent && <div slot="end">{endContent}</div>}
+        {children}
+      </ModusWcToolbar>
+    );
+  }
+);
+
+ModusToolbar.displayName = "ModusToolbar";
+
+export default ModusToolbar;

package/templates/react/src/components/ModusTooltip.tsx

@@ -0,0 +1,97 @@
+import { Children, forwardRef, useMemo } from "react";
+import type { ReactNode } from "react";
+import { ModusWcTooltip } from "@trimble-oss/moduswebcomponents-react";
+
+export type TooltipPosition = "auto" | "top" | "bottom" | "left" | "right";
+
+/**
+ * Props for the ModusTooltip component.
+ */
+export interface ModusTooltipProps {
+  /** The text to display in the tooltip. */
+  content: string;
+  /** The position of the tooltip. */
+  position?: TooltipPosition;
+  /** Whether the tooltip is disabled. */
+  disabled?: boolean;
+  /** Whether to force the tooltip to be open. */
+  forceOpen?: boolean;
+  /** A unique identifier for the tooltip. */
+  tooltipId?: string;
+  /** A custom CSS class to apply to the tooltip. */
+  customClass?: string;
+  /** A CSS class to apply to the tooltip. */
+  className?: string;
+  /** The content to display as the tooltip's target. */
+  children?: ReactNode;
+}
+
+/**
+ * Renders a Modus tooltip component.
+ * @param {ModusTooltipProps} props - The component props.
+ * @param {React.Ref<HTMLModusWcTooltipElement>} ref - The ref object for the tooltip.
+ * @returns {JSX.Element} The rendered tooltip component.
+ */
+const ModusTooltip = forwardRef<HTMLModusWcTooltipElement, ModusTooltipProps>(
+  (
+    {
+      content,
+      position = "auto",
+      disabled = false,
+      forceOpen = false,
+      tooltipId,
+      customClass,
+      className,
+      children,
+    },
+    ref
+  ) => {
+    /**
+     * Normalizes children to ensure proper tooltip behavior.
+     *
+     * This memoized function handles different child scenarios:
+     * - No children: Returns null
+     * - Single child: Returns the child as-is
+     * - Multiple children: Wraps them in a span with proper styling
+     *
+     * The normalization ensures that the tooltip can properly attach to
+     * the child element(s) and handle hover events correctly.
+     *
+     * @returns {ReactNode | null} The normalized child element(s)
+     * @private
+     */
+    const normalizedChild = useMemo(() => {
+      const childArray = Children.toArray(children);
+      if (childArray.length === 0) {
+        return null;
+      }
+      if (childArray.length === 1) {
+        return childArray[0];
+      }
+      return (
+        <span className="inline-flex items-center gap-1">{childArray}</span>
+      );
+    }, [children]);
+
+    const combinedClass =
+      [customClass, className].filter(Boolean).join(" ") || undefined;
+
+    return (
+      <ModusWcTooltip
+        ref={ref}
+        content={content}
+        position={position}
+        disabled={disabled}
+        force-open={forceOpen}
+        tooltip-id={tooltipId}
+        custom-class={combinedClass}
+      >
+        {normalizedChild}
+      </ModusWcTooltip>
+    );
+  }
+);
+
+ModusTooltip.displayName = "ModusTooltip";
+
+export default ModusTooltip;

package/templates/react/src/components/ModusUtilityPanel.tsx

@@ -0,0 +1,198 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { CSSProperties } from "react";
+import { ModusWcUtilityPanel } from "@trimble-oss/moduswebcomponents-react";
+
+type UtilityPanelPosition = "left" | "right";
+
+/**
+ * Props for the ModusUtilityPanel component.
+ */
+export interface ModusUtilityPanelProps {
+  /** Whether the utility panel is expanded. */
+  expanded?: boolean;
+  /** The position of the utility panel. */
+  position?: UtilityPanelPosition;
+  /** Whether the utility panel should push the content. */
+  pushContent?: boolean;
+  /** The width of the utility panel. */
+  panelWidth?: string;
+  /** A CSS class to apply to the utility panel. */
+  className?: string;
+  /** The main content of the utility panel. */
+  children?: React.ReactNode;
+  /** The content to display in the header slot. */
+  headerSlot?: React.ReactNode;
+  /** The text to display in the header. */
+  headerText?: string;
+  /** The content to display in the footer slot. */
+  footerSlot?: React.ReactNode;
+  /** The ARIA label for the utility panel. */
+  ariaLabel?: string;
+  /** The ARIA expanded state of the utility panel. */
+  ariaExpanded?: boolean;
+  /** A callback function to handle the panel opened event. */
+  onPanelOpened?: () => void;
+  /** A callback function to handle the panel closed event. */
+  onPanelClosed?: () => void;
+  /** A callback function to handle the toggle event. */
+  onToggle?: (collapsed: boolean) => void;
+  /** A CSS selector for the target element to push. */
+  targetSelector?: string;
+  /** The target element to push. */
+  targetElement?: HTMLElement | null;
+}
+
+/**
+ * Renders a Modus utility panel component.
+ * @param {ModusUtilityPanelProps} props - The component props.
+ * @returns {JSX.Element} The rendered utility panel component.
+ */
+export default function ModusUtilityPanel({
+  expanded = false,
+  position = "right",
+  pushContent = false,
+  panelWidth = "312px",
+  className,
+  children,
+  headerSlot,
+  headerText,
+  footerSlot,
+  ariaLabel,
+  ariaExpanded,
+  onPanelOpened,
+  onPanelClosed,
+  onToggle,
+  targetSelector,
+  targetElement,
+}: ModusUtilityPanelProps) {
+  const panelRef = useRef<HTMLModusWcUtilityPanelElement>(null);
+
+  /**
+   * Resolves the target element for content pushing functionality.
+   *
+   * This memoized function determines which element should be pushed when
+   * the utility panel is expanded. It checks for targetElement first,
+   * then falls back to querying the DOM using targetSelector.
+   *
+   * @returns {HTMLElement | undefined} The resolved target element or undefined
+   * @private
+   */
+  const resolvedTarget = useMemo(() => {
+    if (targetElement) return targetElement;
+    if (typeof document === "undefined") return undefined;
+    if (targetSelector) {
+      return document.querySelector<HTMLElement>(targetSelector) ?? undefined;
+    }
+    return undefined;
+  }, [targetElement, targetSelector]);
+
+  useEffect(() => {
+    return () => {
+      if (resolvedTarget) {
+        resolvedTarget.classList.remove(
+          "modus-wc-utility-panel-push-target-left"
+        );
+      }
+    };
+  }, [resolvedTarget]);
+  useEffect(() => {
+    const panel = panelRef.current;
+    if (!panel) return;
+
+    panel.expanded = expanded;
+    panel.pushContent = pushContent;
+    panel.targetElement = resolvedTarget;
+
+    if (resolvedTarget) {
+      if (position === "left" && pushContent) {
+        resolvedTarget.classList.add("modus-wc-utility-panel-push-target-left");
+      } else {
+        resolvedTarget.classList.remove(
+          "modus-wc-utility-panel-push-target-left"
+        );
+      }
+    }
+  }, [expanded, pushContent, resolvedTarget, position]);
+
+  /**
+   * Handles the panel opened event and updates state accordingly.
+   *
+   * This callback is triggered when the utility panel opens and calls
+   * the appropriate event handlers while updating the toggle state.
+   *
+   * @private
+   */
+  const handlePanelOpened = useCallback(() => {
+    onPanelOpened?.();
+    onToggle?.(false);
+  }, [onPanelOpened, onToggle]);
+
+  /**
+   * Handles the panel closed event and updates state accordingly.
+   *
+   * This callback is triggered when the utility panel closes and calls
+   * the appropriate event handlers while updating the toggle state.
+   *
+   * @private
+   */
+  const handlePanelClosed = useCallback(() => {
+    onPanelClosed?.();
+    onToggle?.(true);
+  }, [onPanelClosed, onToggle]);
+
+  useEffect(() => {
+    const panel = panelRef.current;
+    if (!panel) return;
+
+    panel.addEventListener("panelOpened", handlePanelOpened);
+    panel.addEventListener("panelClosed", handlePanelClosed);
+
+    return () => {
+      panel.removeEventListener("panelOpened", handlePanelOpened);
+      panel.removeEventListener("panelClosed", handlePanelClosed);
+    };
+  }, [handlePanelClosed, handlePanelOpened]);
+
+  const positionClass =
+    position === "left" ? "modus-utility-panel--left" : undefined;
+
+  const combinedClass =
+    [className, positionClass].filter(Boolean).join(" ") || undefined;
+
+  const style = useMemo<CSSProperties | undefined>(() => {
+    if (!panelWidth) return undefined;
+    return {
+      "--modus-wc-utility-panel-width": panelWidth,
+    } as CSSProperties;
+  }, [panelWidth]);
+
+  const renderedHeader =
+    headerSlot ??
+    (headerText ? (
+      <div className="text-xl font-bold text-foreground">{headerText}</div>
+    ) : null);
+
+  return (
+    <ModusWcUtilityPanel
+      ref={panelRef}
+      expanded={expanded}
+      pushContent={pushContent}
+      className={combinedClass}
+      aria-label={ariaLabel}
+      aria-expanded={ariaExpanded}
+      style={style}
+    >
+      {renderedHeader && (
+        <div slot="header" className="w-full min-w-full max-w-full block">
+          {renderedHeader}
+        </div>
+      )}
+      <div slot="body">{children}</div>
+      {footerSlot && (
+        <div slot="footer" className="w-full min-w-full max-w-full block">
+          {footerSlot}
+        </div>
+      )}
+    </ModusWcUtilityPanel>
+  );
+}

package/templates/react/src/components/ThemeSwitcherDropdown.tsx

@@ -0,0 +1,117 @@
+import { useTheme } from "../hooks/useTheme";
+import { type Theme } from "../contexts/ThemeContextData";
+import { useState, useEffect } from "react";
+import ModusDropdownMenu from "./ModusDropdownMenu";
+import type { MenuItem } from "./ModusMenu";
+
+/**
+ * Props for the ThemeSwitcherDropdown component.
+ */
+interface ThemeSwitcherDropdownProps {
+  /** A custom CSS class to apply to the component. */
+  className?: string;
+}
+
+/**
+ * Renders the content of the theme switcher dropdown.
+ * @param {ThemeSwitcherDropdownProps} props - The component props.
+ * @returns {JSX.Element} The rendered dropdown content.
+ */
+function ThemeSwitcherDropdownContent({
+  className = '',
+}: ThemeSwitcherDropdownProps) {
+  const { theme, setTheme } = useTheme();
+
+  const handleItemSelect = (event: CustomEvent<{ value: string }>) => {
+    const selectedValue = event.detail.value as Theme;
+    if (selectedValue && selectedValue !== theme) {
+      setTheme(selectedValue);
+    }
+  };
+
+  const themes: { value: Theme; label: string; description: string }[] = [
+    {
+      value: "modus-classic-light",
+      label: "Classic Light",
+      description: "Traditional light theme",
+    },
+    {
+      value: "modus-classic-dark",
+      label: "Classic Dark",
+      description: "Traditional dark theme",
+    },
+    {
+      value: "modus-modern-light",
+      label: "Modern Light",
+      description: "Contemporary light theme",
+    },
+    {
+      value: "modus-modern-dark",
+      label: "Modern Dark",
+      description: "Contemporary dark theme",
+    },
+    {
+      value: "connect-light",
+      label: "Connect Light",
+      description: "Connect light theme",
+    },
+    {
+      value: "connect-dark",
+      label: "Connect Dark",
+      description: "Connect dark theme",
+    },
+  ];
+
+  const getCurrentThemeLabel = () => {
+    const currentTheme = themes.find((t) => t.value === theme);
+    return currentTheme ? currentTheme.label : "Theme";
+  };
+
+  const menuItems: MenuItem[] = themes.map((themeOption) => ({
+    label: themeOption.label,
+    value: themeOption.value,
+    selected: theme === themeOption.value,
+  }));
+
+  return (
+    <div className={className}>
+      <ModusDropdownMenu
+        buttonVariant="filled"
+        menuPlacement="bottom-end"
+        menuItems={menuItems}
+        onItemSelect={handleItemSelect}
+        buttonContent={
+          <div className="flex items-center justify-between w-full min-w-[140px] px-3 py-2 gap-2">
+            <div className="flex-1 text-left text-md font-medium">
+              {getCurrentThemeLabel()}
+            </div>
+            <i className="modus-icons text-base flex-shrink-0">expand_more</i>
+          </div>
+        }
+      />
+    </div>
+  );
+}
+
+export default function ThemeSwitcherDropdown(
+  props: ThemeSwitcherDropdownProps
+) {
+  const [mounted, setMounted] = useState(false);
+
+  // Prevent hydration mismatch
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return (
+      <div className={props.className || ""}>
+        <div className="animate-pulse">
+          <div className="h-8 w-32 rounded bg-muted" />
+        </div>
+      </div>
+    );
+  }
+
+  return <ThemeSwitcherDropdownContent {...props} />;
+}