@julianoczkowski/create-trimble-app 2.0.0

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

@@ -0,0 +1,75 @@
+
+
+import { useEffect, useRef } from "react";
+import { ModusWcBreadcrumbs } from "@trimble-oss/moduswebcomponents-react";
+
+/**
+ * Represents a single item in the breadcrumb trail.
+ */
+export interface BreadcrumbItem {
+  /** The text to display for the breadcrumb item. */
+  label: string;
+  /** The URL to navigate to when the breadcrumb item is clicked. */
+  url?: string;
+}
+
+/**
+ * Props for the ModusBreadcrumbs component.
+ */
+export interface ModusBreadcrumbsProps {
+  /** The items to display in the breadcrumb trail. */
+  items: BreadcrumbItem[];
+  /** The size of the breadcrumbs. */
+  size?: 'sm' | 'md' | 'lg';
+  /** A custom CSS class to apply to the breadcrumbs. */
+  customClass?: string;
+  /** The ARIA label for the breadcrumbs. */
+  'aria-label'?: string;
+  /** A callback function to handle breadcrumb item clicks. */
+  onBreadcrumbClick?: (event: CustomEvent<BreadcrumbItem>) => void;
+}
+
+/**
+ * Renders a Modus breadcrumbs component.
+ * @param {ModusBreadcrumbsProps} props - The component props.
+ * @param {BreadcrumbItem[]} props.items - The items to display in the breadcrumb trail.
+ * @param {'sm' | 'md' | 'lg'} [props.size='md'] - The size of the breadcrumbs.
+ * @param {string} [props.customClass] - A custom CSS class to apply to the breadcrumbs.
+ * @param {string} [props.aria-label] - The ARIA label for the breadcrumbs.
+ * @param {(event: CustomEvent<BreadcrumbItem>) => void} [props.onBreadcrumbClick] - A callback function to handle breadcrumb item clicks.
+ * @returns {JSX.Element} The rendered breadcrumbs component.
+ */
+export default function ModusBreadcrumbs({
+  items,
+  size = 'md',
+  customClass,
+  'aria-label': ariaLabel,
+  onBreadcrumbClick,
+}: ModusBreadcrumbsProps) {
+  const breadcrumbsRef = useRef<HTMLModusWcBreadcrumbsElement>(null);
+
+  useEffect(() => {
+    const breadcrumbs = breadcrumbsRef.current;
+    if (!breadcrumbs || !onBreadcrumbClick) return;
+
+    const handleBreadcrumbClick = (event: Event) => {
+      const customEvent = event as CustomEvent<BreadcrumbItem>;
+      onBreadcrumbClick(customEvent);
+    };
+
+    breadcrumbs.addEventListener("breadcrumbClick", handleBreadcrumbClick);
+    return () => {
+      breadcrumbs.removeEventListener("breadcrumbClick", handleBreadcrumbClick);
+    };
+  }, [onBreadcrumbClick]);
+
+  return (
+    <ModusWcBreadcrumbs
+      ref={breadcrumbsRef}
+      items={items}
+      size={size}
+      customClass={customClass}
+      aria-label={ariaLabel}
+    />
+  );
+}

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

@@ -0,0 +1,244 @@
+import { ModusWcButton } from "@trimble-oss/moduswebcomponents-react";
+import type { ReactNode } from "react";
+
+/**
+ * Props for the ModusButton component.
+ */
+interface ModusButtonProps {
+  /** The color of the button. */
+  color?: "primary" | "secondary" | "tertiary" | "warning" | "danger";
+  /** The variant of the button. */
+  variant?: "filled" | "outlined" | "borderless";
+  /** The size of the button. */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** The shape of the button. */
+  shape?: "rectangle" | "square" | "circle";
+
+  /** Whether the button is disabled. */
+  disabled?: boolean;
+  /** Whether the button should take up the full width of its container. */
+  fullWidth?: boolean;
+  /** Whether the button is pressed. */
+  pressed?: boolean;
+  /** The type of the button. */
+  type?: "button" | "submit" | "reset";
+
+  /** The content to display inside the button. */
+  children?: ReactNode;
+  /** An icon to display in the button. */
+  icon?: string;
+  /** The position of the icon relative to the button text. */
+  iconPosition?: "left" | "right" | "only";
+  /** The size of the icon (Tailwind text class). */
+  iconSize?: string;
+
+  /** The ARIA label for the button. */
+  ariaLabel?: string;
+
+  /** A callback function to handle button clicks. */
+  onButtonClick?: () => void;
+
+  /** A custom CSS class to apply to the button. */
+  className?: string;
+}
+
+/**
+ * Renders a Modus button component with full customization support.
+ *
+ * @example
+ * // Basic button
+ * <ModusButton>Click me</ModusButton>
+ *
+ * @example
+ * // Icon button with custom styling
+ * <ModusButton
+ *   icon="add"
+ *   iconPosition="left"
+ *   color="primary"
+ *   size="lg"
+ * >
+ *   Add Item
+ * </ModusButton>
+ *
+ * @example
+ * // Icon-only button with accessibility
+ * <ModusButton
+ *   icon="settings"
+ *   iconPosition="only"
+ *   ariaLabel="Open settings"
+ * />
+ *
+ * @param {ModusButtonProps} props - The component props.
+ * @returns {JSX.Element} The rendered button component.
+ * @see {@link https://modus.trimble.com/components/button} - Modus Button documentation
+ */
+export default function ModusButton({
+  color,
+  variant,
+  size = "md",
+  shape = "rectangle",
+  disabled = false,
+  fullWidth = false,
+  pressed = false,
+  type = "button",
+  children,
+  icon,
+  iconPosition = "left",
+  iconSize,
+  ariaLabel,
+  onButtonClick,
+  className,
+}: ModusButtonProps) {
+  /**
+   * Determines the appropriate icon size class based on button size, icon position, and explicit iconSize prop.
+   *
+   * @returns {string} The Tailwind text class for the icon size
+   * @private
+   */
+  const getIconSizeClass = (): string => {
+    // If iconSize is explicitly provided, use it
+    if (iconSize) {
+      return iconSize;
+    }
+
+    // Automatic sizing based on button size and icon position
+    if (iconPosition === "only") {
+      // Icon-only buttons get larger icons
+      switch (size) {
+        case "xs":
+          return "text-sm";
+        case "sm":
+          return "text-base";
+        case "md":
+          return "text-xl";
+        case "lg":
+          return "text-2xl";
+        default:
+          return "text-xl";
+      }
+    } else {
+      // Icons with text scale with button size
+      switch (size) {
+        case "xs":
+          return "text-xs";
+        case "sm":
+          return "text-sm";
+        case "md":
+          return "text-lg";
+        case "lg":
+          return "text-xl";
+        default:
+          return "text-lg";
+      }
+    }
+  };
+
+  /**
+   * Renders an icon with proper positioning and styling based on its position.
+   *
+   * This helper function creates an icon element with appropriate margin spacing
+   * based on the icon's position relative to the button text. Icons positioned
+   * on the left get right margin, icons on the right get left margin, and
+   * icon-only buttons have no margin.
+   *
+   * @param {string} iconName - The name of the Modus icon to render
+   * @param {"left" | "right" | "only"} position - The position of the icon relative to text
+   * @returns {JSX.Element} The rendered icon element with appropriate styling
+   * @private
+   */
+  const renderIcon = (
+    iconName: string,
+    position: "left" | "right" | "only",
+  ) => {
+    const iconStyle =
+      position === "left"
+        ? { marginRight: "8px" }
+        : position === "right"
+          ? { marginLeft: "8px" }
+          : {};
+
+    const iconSizeClass = getIconSizeClass();
+
+    return (
+      <i className={`modus-icons ${iconSizeClass}`} style={iconStyle}>
+        {iconName}
+      </i>
+    );
+  };
+
+  /**
+   * Determines and renders the button content based on icon position.
+   *
+   * This function handles the complex logic of combining icons and text content
+   * based on the iconPosition prop. It supports three modes:
+   * - "left": Icon appears before text
+   * - "right": Icon appears after text
+   * - "only": Only the icon is displayed (text is hidden)
+   *
+   * @returns {ReactNode} The rendered content with proper icon and text arrangement
+   * @private
+   */
+  const renderContent = () => {
+    if (!icon) {
+      return children;
+    }
+
+    switch (iconPosition) {
+      case "left":
+        return (
+          <>
+            {renderIcon(icon, "left")}
+            {children}
+          </>
+        );
+      case "right":
+        return (
+          <>
+            {children}
+            {renderIcon(icon, "right")}
+          </>
+        );
+      case "only":
+        return renderIcon(icon, "only");
+      default:
+        return children;
+    }
+  };
+
+  /**
+   * Generates appropriate ARIA label for accessibility.
+   *
+   * This function ensures proper accessibility by generating ARIA labels
+   * for icon-only buttons. If no explicit ariaLabel is provided and the
+   * button is icon-only, it uses the text content as the aria-label.
+   * This ensures screen readers can properly announce the button's purpose.
+   *
+   * @returns {string | undefined} The appropriate ARIA label or undefined
+   * @private
+   */
+  const getAriaLabel = () => {
+    if (ariaLabel) return ariaLabel;
+    if (iconPosition === "only" && typeof children === "string") {
+      return children; // Use text content as aria-label for icon-only buttons
+    }
+    return undefined;
+  };
+
+  return (
+    <ModusWcButton
+      {...(color && { color })}
+      {...(variant && { variant })}
+      size={size}
+      shape={shape}
+      disabled={disabled}
+      fullWidth={fullWidth}
+      pressed={pressed}
+      type={type}
+      aria-label={getAriaLabel()}
+      onButtonClick={onButtonClick}
+      custom-class={className}
+    >
+      {renderContent()}
+    </ModusWcButton>
+  );
+}

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

@@ -0,0 +1,91 @@
+import { ModusWcButtonGroup } from "@trimble-oss/moduswebcomponents-react";
+import type { ReactNode } from "react";
+
+/**
+ * Props for the ModusButtonGroup component.
+ */
+export interface ModusButtonGroupProps {
+  /** The content to display inside the button group (ModusButton components). */
+  children?: ReactNode;
+  /** Style variant applied to all buttons within the group. */
+  variant?: "borderless" | "filled" | "outlined";
+  /** Color applied to all buttons within the group. */
+  color?: "primary" | "secondary" | "tertiary" | "warning" | "danger";
+  /** Disables all buttons within the button group. */
+  disabled?: boolean;
+  /** Orientation of the button group: horizontal or vertical. */
+  orientation?: "horizontal" | "vertical";
+  /** Selection behavior - default (no selection), single (radio-like), or multiple (checkbox-like). */
+  selectionType?: "default" | "single" | "multiple";
+  /** Callback when any button in the group is clicked. */
+  onButtonGroupClick?: (
+    event: CustomEvent<{ button: HTMLElement; isSelected: boolean }>,
+  ) => void;
+  /** Callback when button selection changes. */
+  onButtonSelectionChange?: (
+    event: CustomEvent<{ selectedButtons: HTMLElement[] }>,
+  ) => void;
+  /** A custom CSS class to apply to the button group. */
+  customClass?: string;
+  /** The ARIA label for the button group. */
+  ariaLabel?: string;
+}
+
+/**
+ * Renders a Modus button group component that groups multiple buttons together.
+ *
+ * @example
+ * // Basic horizontal button group
+ * <ModusButtonGroup variant="outlined" color="primary">
+ *   <ModusButton>Button 1</ModusButton>
+ *   <ModusButton>Button 2</ModusButton>
+ *   <ModusButton>Button 3</ModusButton>
+ * </ModusButtonGroup>
+ *
+ * @example
+ * // Single selection (radio-like behavior)
+ * <ModusButtonGroup selectionType="single" variant="outlined">
+ *   <ModusButton>Option 1</ModusButton>
+ *   <ModusButton pressed>Option 2</ModusButton>
+ *   <ModusButton>Option 3</ModusButton>
+ * </ModusButtonGroup>
+ *
+ * @example
+ * // Multiple selection (checkbox-like behavior)
+ * <ModusButtonGroup selectionType="multiple" variant="outlined">
+ *   <ModusButton pressed>Bold</ModusButton>
+ *   <ModusButton>Italic</ModusButton>
+ *   <ModusButton pressed>Underline</ModusButton>
+ * </ModusButtonGroup>
+ *
+ * @param {ModusButtonGroupProps} props - The component props.
+ * @returns {JSX.Element} The rendered button group component.
+ */
+export default function ModusButtonGroup({
+  children,
+  variant = "outlined",
+  color,
+  disabled = false,
+  orientation = "horizontal",
+  selectionType = "default",
+  onButtonGroupClick,
+  onButtonSelectionChange,
+  customClass,
+  ariaLabel,
+}: ModusButtonGroupProps) {
+  return (
+    <ModusWcButtonGroup
+      variant={variant}
+      color={color}
+      disabled={disabled}
+      orientation={orientation}
+      selection-type={selectionType}
+      onButtonGroupClick={onButtonGroupClick}
+      onButtonSelectionChange={onButtonSelectionChange}
+      custom-class={customClass}
+      aria-label={ariaLabel}
+    >
+      {children}
+    </ModusWcButtonGroup>
+  );
+}

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

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import { ModusWcCard } from "@trimble-oss/moduswebcomponents-react";
+
+/**
+ * Props for the ModusCard component.
+ */
+export interface ModusCardProps {
+  /** The main content of the card. */
+  children?: ReactNode;
+  /** Whether to show a background figure. */
+  backgroundFigure?: boolean;
+  /** Whether the card has a border. */
+  bordered?: boolean;
+  /** The layout of the card. */
+  layout?: 'vertical' | 'horizontal';
+  /** The padding of the card. */
+  padding?: 'compact' | 'comfortable';
+  /** A custom CSS class to apply to the card. */
+  customClass?: string;
+  /** The ARIA label for the card. */
+  'aria-label'?: string;
+  /** The header content of the card. */
+  header?: ReactNode;
+  /** The title content of the card. */
+  title?: ReactNode;
+  /** The subtitle content of the card. */
+  subtitle?: ReactNode;
+  /** The actions content of the card. */
+  actions?: ReactNode;
+  /** The footer content of the card. */
+  footer?: ReactNode;
+}
+
+/**
+ * Renders a Modus card component.
+ * @param {ModusCardProps} props - The component props.
+ * @returns {JSX.Element} The rendered card component.
+ */
+export default function ModusCard({
+  children,
+  backgroundFigure = false,
+  bordered = false,
+  layout = 'vertical',
+  padding = 'comfortable',
+  customClass,
+  'aria-label': ariaLabel,
+  header,
+  title,
+  subtitle,
+  actions,
+  footer,
+}: ModusCardProps) {
+  return (
+    <ModusWcCard
+      backgroundFigure={backgroundFigure}
+      bordered={bordered}
+      layout={layout}
+      padding={padding}
+      customClass={customClass}
+      aria-label={ariaLabel}
+    >
+      {header && <div slot="header">{header}</div>}
+      {title && <div slot="title">{title}</div>}
+      {subtitle && <div slot="subtitle">{subtitle}</div>}
+      {children}
+      {actions && <div slot="actions">{actions}</div>}
+      {footer && <div slot="footer">{footer}</div>}
+    </ModusWcCard>
+  );
+}

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

@@ -0,0 +1,168 @@
+import { useEffect, useRef } from "react";
+import { ModusWcCheckbox } from "@trimble-oss/moduswebcomponents-react";
+
+/**
+ * Props for the ModusCheckbox component.
+ */
+export interface ModusCheckboxProps {
+  /** The value of the checkbox. */
+  value?: boolean;
+  /** Whether the checkbox is disabled. */
+  disabled?: boolean;
+  /** Whether the checkbox is in an indeterminate state. */
+  indeterminate?: boolean;
+  /** The label for the checkbox. */
+  label?: string;
+  /** The name of the checkbox. */
+  name?: string;
+  /** Whether the checkbox is required. */
+  required?: boolean;
+  /** The size of the checkbox. */
+  size?: "sm" | "md" | "lg";
+  /** The ID of the input element. */
+  inputId?: string;
+  /** The tab index of the input element. */
+  inputTabIndex?: number;
+  /** A custom CSS class to apply to the checkbox. */
+  customClass?: string;
+  /** The ARIA label for the checkbox. */
+  "aria-label"?: string;
+  /** A callback function to handle input changes. */
+  onInputChange?: (event: CustomEvent<InputEvent>) => void;
+  /** A callback function to handle input focus. */
+  onInputFocus?: (event: CustomEvent<FocusEvent>) => void;
+  /** A callback function to handle input blur. */
+  onInputBlur?: (event: CustomEvent<FocusEvent>) => void;
+  /** A callback function to handle value changes. */
+  onValueChange?: (event: CustomEvent<boolean>) => void;
+}
+
+/**
+ * Renders a Modus checkbox component with critical bug workaround.
+ *
+ * ⚠️ IMPORTANT: This component includes a workaround for a critical value inversion bug
+ * in the underlying ModusWcCheckbox web component. The value property returns the
+ * opposite of the actual checked state, which is automatically corrected.
+ *
+ * @example
+ * // Basic checkbox
+ * <ModusCheckbox label="Accept terms" />
+ *
+ * @example
+ * // Controlled checkbox with value change handler
+ * <ModusCheckbox
+ *   label="Subscribe to newsletter"
+ *   value={isSubscribed}
+ *   onValueChange={(event) => setSubscribed(event.detail)}
+ * />
+ *
+ * @example
+ * // Indeterminate checkbox
+ * <ModusCheckbox
+ *   label="Select all"
+ *   indeterminate={true}
+ *   onValueChange={handleSelectAll}
+ * />
+ *
+ * @param {ModusCheckboxProps} props - The component props.
+ * @returns {JSX.Element} The rendered checkbox component.
+ * @see {@link https://modus.trimble.com/components/checkbox} - Modus Checkbox documentation
+ * @see {@link https://github.com/trimble-oss/modus-web-components/issues} - Known issues
+ */
+export default function ModusCheckbox({
+  value = false,
+  disabled = false,
+  indeterminate = false,
+  label,
+  name = "",
+  required = false,
+  size = "md",
+  inputId,
+  inputTabIndex,
+  customClass,
+  "aria-label": ariaLabel,
+  onInputChange,
+  onInputFocus,
+  onInputBlur,
+  onValueChange,
+}: ModusCheckboxProps) {
+  const checkboxRef = useRef<HTMLModusWcCheckboxElement>(null);
+
+  useEffect(() => {
+    const checkbox = checkboxRef.current;
+    if (!checkbox) return;
+
+    const handleInputChange = (event: Event) => {
+      onInputChange?.(event as CustomEvent<InputEvent>);
+    };
+    const handleInputFocus = (event: Event) => {
+      onInputFocus?.(event as CustomEvent<FocusEvent>);
+    };
+    const handleInputBlur = (event: Event) => {
+      onInputBlur?.(event as CustomEvent<FocusEvent>);
+    };
+    /**
+     * Handles value change events with critical bug fix for value inversion.
+     *
+     * ⚠️ CRITICAL BUG WORKAROUND: The ModusWcCheckbox component has a value
+     * inversion bug where the `value` property returns the opposite of the
+     * actual checked state. This function corrects this by inverting the
+     * raw value before passing it to the parent component.
+     *
+     * @param {Event} event - The input change event from the web component
+     * @private
+     * @see {@link https://github.com/trimble-oss/modus-web-components/issues} - Modus Web Components issue tracker
+     */
+    const handleValueChange = (event: Event) => {
+      const customEvent = event as CustomEvent<InputEvent>;
+      // 🚨 CRITICAL: Handle the value inversion bug
+      // The value inversion bug is in the target.value, not the event detail
+      const rawValue = (customEvent.target as HTMLModusWcCheckboxElement).value;
+      const actualValue = !rawValue; // ✅ CORRECT: Invert the value
+
+      // Create a new event with the corrected value
+      const correctedEvent = new CustomEvent("valueChange", {
+        detail: actualValue,
+        bubbles: true,
+        cancelable: true,
+      });
+
+      onValueChange?.(correctedEvent);
+    };
+
+    if (onInputChange)
+      checkbox.addEventListener("inputChange", handleInputChange);
+    if (onInputFocus) checkbox.addEventListener("inputFocus", handleInputFocus);
+    if (onInputBlur) checkbox.addEventListener("inputBlur", handleInputBlur);
+    if (onValueChange)
+      checkbox.addEventListener("inputChange", handleValueChange);
+
+    return () => {
+      if (onInputChange)
+        checkbox.removeEventListener("inputChange", handleInputChange);
+      if (onInputFocus)
+        checkbox.removeEventListener("inputFocus", handleInputFocus);
+      if (onInputBlur)
+        checkbox.removeEventListener("inputBlur", handleInputBlur);
+      if (onValueChange)
+        checkbox.removeEventListener("inputChange", handleValueChange);
+    };
+  }, [onInputChange, onInputFocus, onInputBlur, onValueChange]);
+
+  return (
+    <ModusWcCheckbox
+      ref={checkboxRef}
+      value={value}
+      disabled={disabled}
+      indeterminate={indeterminate}
+      label={label}
+      name={name}
+      required={required}
+      size={size}
+      inputId={inputId}
+      inputTabIndex={inputTabIndex}
+      customClass={customClass}
+      aria-label={ariaLabel}
+    />
+  );
+}