@carrier-dpx/air-react-library 0.7.35 → 0.7.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrier-dpx/air-react-library",
-  "version": "0.7.35",
+  "version": "0.7.37",
   "description": "Air web React component library for Figma Make",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/components/Breadcrumbs/BreadcrumbLink.figma.tsx

@@ -0,0 +1,137 @@
+/**
+ * Figma Code Connect Configuration for Breadcrumb Link Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20464-143034
+ * 
+ * Figma Properties:
+ * - color (primary, main)
+ * - active (true, false)
+ * - state (enabled, hover) - visual state, not a prop
+ * - disabled (true, false)
+ * - Icon (true, false) - boolean hide/show
+ * - separator (true, false) - boolean hide/show
+ * 
+ * Structure:
+ * - Icon: Nested Icon component instance (when Icon=true)
+ * - Link: Nested Link component instance with text content
+ */
+
+import figma from "@figma/code-connect";
+import BreadcrumbLink from "./BreadcrumbLink";
+import Link from "../Link";
+import Icon from "../Icon";
+
+figma.connect(
+  BreadcrumbLink,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20464-143034",
+  {
+    props: {
+      /**
+       * COLOR MAPPING
+       * Maps Figma's "color" property to React's "color" prop
+       * Figma: primary, main → React: primary, base
+       */
+      color: figma.enum("color", {
+        primary: "primary",
+        main: "base",
+      }),
+
+      /**
+       * ACTIVE STATE
+       * Maps Figma's "active" boolean to React's "active" prop
+       */
+      active: figma.boolean("active"),
+
+      /**
+       * DISABLED STATE
+       * Maps Figma's "disabled" boolean to React's "disabled" prop
+       */
+      disabled: figma.boolean("disabled"),
+
+      /**
+       * ICON VISIBILITY
+       * Maps Figma's "Icon" boolean - controls visibility of nested Icon component
+       */
+      showIcon: figma.boolean("Icon"),
+
+      /**
+       * SEPARATOR VISIBILITY
+       * Maps Figma's "separator" boolean - controls visibility of separator
+       * Note: Separator is typically handled by parent Breadcrumbs component
+       */
+      showSeparator: figma.boolean("separator"),
+
+      /**
+       * ICON NESTED PROPERTIES
+       * Access Icon's fontSize and SVG through nested properties
+       * The Icon component is nested within BreadcrumbLink when Icon is visible
+       */
+      icon: figma.nestedProps("Icon", {
+        fontSize: figma.enum("fontSize", {
+          large: "large",
+          medium: "medium",
+          small: "small",
+          xsmall: "xsmall",
+        }),
+        children: figma.instance("SVG"),
+      }),
+
+      /**
+       * LINK COMPONENT INSTANCE
+       * Maps nested Link component instance
+       * The Link component is nested within BreadcrumbLink
+       * Using figma.instance() to get the Link component instance
+       */
+      link: figma.instance("Link"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how BreadcrumbLink should be used with optional icon and link
+     */
+    example: ({ color, active, disabled, showIcon, icon, link }) => {
+      // Handle case with icon
+      if (showIcon && icon && icon.fontSize && icon.children && link) {
+        return (
+          <BreadcrumbLink
+            color={color}
+            active={active}
+            disabled={disabled}
+            icon={
+              <Icon fontSize={icon.fontSize}>
+                {icon.children}
+              </Icon>
+            }
+            href="#"
+          >
+            {link}
+          </BreadcrumbLink>
+        );
+      }
+
+      // Handle case without icon
+      if (link) {
+        return (
+          <BreadcrumbLink
+            color={color}
+            active={active}
+            disabled={disabled}
+            href="#"
+          >
+            {link}
+          </BreadcrumbLink>
+        );
+      }
+
+      // Fallback
+      return (
+        <BreadcrumbLink
+          color={color}
+          active={active}
+          disabled={disabled}
+          href="#"
+        />
+      );
+    },
+  }
+);

package/src/components/Breadcrumbs/BreadcrumbLink.tsx

@@ -0,0 +1,82 @@
+import { forwardRef } from "react";
+import Link from "../Link";
+import Icon from "../Icon";
+import { styled } from "@mui/material/styles";
+import { Theme } from "@mui/material";
+
+export interface BreadcrumbLinkProps {
+  /**
+   * The color of the breadcrumb link
+   */
+  color?: "primary" | "base";
+  /**
+   * Whether the breadcrumb link is active
+   */
+  active?: boolean;
+  /**
+   * Whether the breadcrumb link is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Icon element to display before the link text
+   */
+  icon?: React.ReactElement;
+  /**
+   * Link content (text)
+   */
+  children?: React.ReactNode;
+  /**
+   * href for the link
+   */
+  href?: string;
+  /**
+   * onClick handler
+   */
+  onClick?: () => void;
+}
+
+const StyledLink = styled(Link)<{ active?: boolean; disabled?: boolean }>(
+  ({ theme, active, disabled }: { theme: Theme; active?: boolean; disabled?: boolean }) => ({
+    ...(active && {
+      color: theme.palette.base?.text.primary,
+      fontWeight: 600,
+    }),
+    ...(disabled && {
+      color: theme.palette.base?.text.disabled,
+      cursor: "not-allowed",
+      pointerEvents: "none",
+    }),
+  })
+);
+
+/** BreadcrumbLink component used within Breadcrumbs
+ *
+ * `import BreadcrumbLink from '@carrier-io/air-react/Breadcrumbs/BreadcrumbLink'`
+ */
+
+const BreadcrumbLink = forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
+  ({ color, active, disabled, icon, children, href, onClick, ...rest }, ref) => {
+    // If children is a Link component instance, extract its content
+    const linkContent = children;
+    
+    return (
+      <StyledLink
+        ref={ref}
+        href={href}
+        onClick={onClick}
+        active={active}
+        disabled={disabled}
+        color={color === "base" ? undefined : color}
+        {...rest}
+      >
+        {icon}
+        {linkContent}
+      </StyledLink>
+    );
+  }
+);
+
+BreadcrumbLink.displayName = "BreadcrumbLink";
+
+export default BreadcrumbLink;
+export type { BreadcrumbLinkProps };

package/src/components/Breadcrumbs/Breadcrumbs.figma.tsx

@@ -0,0 +1,117 @@
+/**
+ * Figma Code Connect Configuration for Breadcrumbs Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20464-143181
+ * 
+ * Figma Properties:
+ * - color (primary, main)
+ * - icon (true, false)
+ * - separator (slash, icon)
+ * - collapsed (true, false)
+ * - mobile (true, false)
+ * 
+ * Structure:
+ * - Breadcrumb 01-06: Multiple Breadcrumb Link instances with numbered layer names
+ */
+
+import figma from "@figma/code-connect";
+import Breadcrumbs from "./Breadcrumbs";
+
+figma.connect(
+  Breadcrumbs,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20464-143181",
+  {
+    props: {
+      /**
+       * COLOR MAPPING
+       * Maps Figma's "color" property to React's "color" prop
+       * Figma: primary, main → React: primary, base
+       */
+      color: figma.enum("color", {
+        primary: "primary",
+        main: "base",
+      }),
+
+      /**
+       * ICON VISIBILITY
+       * Maps Figma's "icon" boolean property
+       * Controls visibility of icons in breadcrumbs
+       */
+      icon: figma.boolean("icon"),
+
+      /**
+       * SEPARATOR TYPE
+       * Maps Figma's "separator" property to React separator prop
+       * Figma: slash, icon → React: "/", icon component
+       */
+      separator: figma.enum("separator", {
+        slash: "/",
+        icon: "icon",
+      }),
+
+      /**
+       * COLLAPSED STATE
+       * Maps Figma's "collapsed" boolean property
+       * Controls collapsed state of breadcrumbs
+       */
+      collapsed: figma.boolean("collapsed"),
+
+      /**
+       * MOBILE STATE
+       * Maps Figma's "mobile" boolean property
+       * Controls mobile-specific behavior
+       */
+      mobile: figma.boolean("mobile"),
+
+      /**
+       * BREADCRUMB LINK CHILDREN
+       * Maps nested Breadcrumb Link instances from Figma
+       * Each "Breadcrumb XX" is an instance of the Breadcrumb Link component
+       * We map each one individually using the exact layer names
+       */
+      breadcrumb01: figma.children("Breadcrumb 01"),
+      breadcrumb02: figma.children("Breadcrumb 02"),
+      breadcrumb03: figma.children("Breadcrumb 03"),
+      breadcrumb04: figma.children("Breadcrumb 04"),
+      breadcrumb05: figma.children("Breadcrumb 05"),
+      breadcrumb06: figma.children("Breadcrumb 06"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how Breadcrumbs should be used with Breadcrumb Link children
+     * Note: separator prop handling may need adjustment based on actual implementation
+     */
+    example: ({ color, separator, breadcrumb01, breadcrumb02, breadcrumb03, breadcrumb04, breadcrumb05, breadcrumb06 }) => {
+      // Handle separator - if icon, use undefined (separator handled by parent), otherwise use the separator string
+      if (separator === "icon") {
+        return (
+          <Breadcrumbs
+            color={color}
+          >
+            {breadcrumb01}
+            {breadcrumb02}
+            {breadcrumb03}
+            {breadcrumb04}
+            {breadcrumb05}
+            {breadcrumb06}
+          </Breadcrumbs>
+        );
+      }
+      
+      return (
+        <Breadcrumbs
+          color={color}
+          separator={separator}
+        >
+          {breadcrumb01}
+          {breadcrumb02}
+          {breadcrumb03}
+          {breadcrumb04}
+          {breadcrumb05}
+          {breadcrumb06}
+        </Breadcrumbs>
+      );
+    },
+  }
+);

package/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,53 @@
+import { forwardRef } from "react";
+
+import MuiBreadcrumbs, {
+  BreadcrumbsProps as MuiBreadcrumbsProps,
+} from "@mui/material/Breadcrumbs";
+import { CSSObject, Theme } from "@mui/material/styles";
+
+import { baseBreadcrumbsSx } from "./styles";
+import { getSxStyles } from "../utils/styles";
+import useMediaQuery from "../useMediaQuery/useMediaQuery";
+
+export interface BreadcrumbsProps extends MuiBreadcrumbsProps {
+  color?: "primary" | "base";
+}
+
+/** The Breadcrumbs component is a set of links that help users navigate
+ *  and visualize the current location within a hierarchical structure.
+ *
+ * // Default import
+ * import Breadcrumbs from '@carrier-io/air-react/Breadcrumbs'
+ *
+ * // Named import
+ * import { Breadcrumbs } from '@carrier-io/air-react'
+ */
+
+const Breadcrumbs = forwardRef<HTMLElement, BreadcrumbsProps>(
+  ({ sx, color, ...rest }, ref) => {
+    const isMobile = useMediaQuery(`(max-width:599px)`);
+
+    const breadcrumbSX = (theme: Theme) => {
+      const baseStyles = getSxStyles(theme, sx);
+
+      return {
+        ...baseStyles,
+        ...baseBreadcrumbsSx(theme, color),
+      } as CSSObject;
+    };
+
+    return (
+      <MuiBreadcrumbs
+        {...rest}
+        sx={breadcrumbSX}
+        ref={ref}
+        separator={isMobile ? "" : "/"}
+      />
+    );
+  }
+);
+
+Breadcrumbs.displayName = "Breadcrumbs";
+
+export default Breadcrumbs;
+export type { BreadcrumbsProps };

package/src/components/Breadcrumbs/index.ts

@@ -0,0 +1,5 @@
+export { default } from "./Breadcrumbs";
+export { default as Breadcrumbs } from "./Breadcrumbs";
+export * from "./Breadcrumbs";
+export { default as BreadcrumbLink } from "./BreadcrumbLink";
+export * from "./BreadcrumbLink";

package/src/components/Breadcrumbs/styles.ts

@@ -0,0 +1,20 @@
+import { CSSObject, Theme } from "@mui/material";
+import { styleTokens } from "../theme/constants/styleTokens";
+
+export const baseBreadcrumbsSx = (
+  theme: Theme,
+  color: "primary" | "base" | undefined
+): CSSObject => ({
+  "& .MuiBreadcrumbs-separator": {
+    color: theme.palette.base?.filledInput.outlinedBorder,
+    marginRight: styleTokens.margin.medium,
+    marginLeft: styleTokens.margin.medium,
+  },
+  "& .MuiBreadcrumbs-li:last-child": {
+    color: theme.palette.base?.text.primary,
+  },
+  color:
+    color == "primary"
+      ? theme.palette.primary.main
+      : theme.palette.base?.state.active,
+});

package/src/components/Tag/Tag.figma.tsx

@@ -0,0 +1,130 @@
+/**
+ * Figma Code Connect Configuration for Tag Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20692-169354
+ * 
+ * Figma Properties:
+ * - size (xsmall-24px, micro-small-20px)
+ * - color (purple, primary, info, cyan, success, warning, orange, error, pink)
+ * - uppercase (true, false)
+ * - disabled (true, false)
+ * - startIcon (true, false) - boolean hide/show
+ * - ✏️ Text - text property with layer name "Label"
+ */
+
+import figma from "@figma/code-connect";
+import Tag from "./Tag";
+import Icon from "../Icon";
+
+figma.connect(
+  Tag,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20692-169354",
+  {
+    props: {
+      /**
+       * SIZE MAPPING
+       * Maps Figma's "size" property to React's "size" prop
+       * Figma: xsmall-24px, micro-small-20px
+       */
+      size: figma.enum("size", {
+        "xsmall-24px": "xsmall",
+        "micro-small-20px": "micro",
+        xsmall: "xsmall",
+        micro: "micro",
+      }),
+
+      /**
+       * COLOR MAPPING
+       * Maps Figma's "color" property to React's "color" prop
+       * Note: Some Figma colors may map to similar React colors
+       * purple -> primary, cyan -> info, orange -> warning, pink -> error
+       */
+      color: figma.enum("color", {
+        base: "base",
+        purple: "primary",
+        primary: "primary",
+        info: "info",
+        cyan: "info",
+        success: "success",
+        warning: "warning",
+        orange: "warning",
+        error: "error",
+        pink: "error",
+      }),
+
+      /**
+       * UPPERCASE MAPPING
+       * Maps Figma's "uppercase" boolean to React's "uppercase" prop
+       */
+      uppercase: figma.boolean("uppercase"),
+
+      /**
+       * DISABLED STATE
+       * Maps Figma's "disabled" boolean to React's "disabled" prop
+       */
+      disabled: figma.boolean("disabled"),
+
+      /**
+       * START ICON VISIBILITY
+       * Maps Figma's "startIcon" boolean - controls visibility of icon
+       */
+      showStartIcon: figma.boolean("startIcon"),
+
+      /**
+       * START ICON NESTED PROPERTIES
+       * Access Icon's fontSize and SVG through nested properties
+       * The Icon component is nested within Tag when startIcon is visible
+       */
+      startIcon: figma.nestedProps("startIcon", {
+        fontSize: figma.enum("fontSize", {
+          large: "large",
+          medium: "medium",
+          small: "small",
+          xsmall: "xsmall",
+        }),
+        children: figma.instance("SVG"),
+      }),
+
+      /**
+       * TEXT CONTENT
+       * Maps text property "✏️ Text" from layer "Label"
+       */
+      label: figma.string("✏️ Text"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how Tag should be used with optional startIcon
+     */
+    example: ({ size, color, uppercase, disabled, showStartIcon, startIcon, label }) => {
+      // Handle case with startIcon
+      if (showStartIcon && startIcon && startIcon.fontSize && startIcon.children) {
+        return (
+          <Tag
+            size={size}
+            color={color}
+            uppercase={uppercase}
+            disabled={disabled}
+            startIcon={
+              <Icon fontSize={startIcon.fontSize}>
+                {startIcon.children}
+              </Icon>
+            }
+            label={label}
+          />
+        );
+      }
+
+      // Handle case without startIcon
+      return (
+        <Tag
+          size={size}
+          color={color}
+          uppercase={uppercase}
+          disabled={disabled}
+          label={label}
+        />
+      );
+    },
+  }
+);

package/src/components/Tag/Tag.tsx

@@ -0,0 +1,40 @@
+import { Chip, Typography, styled } from "@mui/material";
+import { StyledTagProps, TagProps } from "./types";
+import styles from "./styles";
+
+const StyledMuiChip = styled(Chip)<StyledTagProps>(styles);
+
+const Tag = ({
+  label,
+  size = "xsmall",
+  color = "success",
+  uppercase,
+  startIcon,
+  disabled = false,
+  ...rest
+}: TagProps) => {
+  const formattedLabel =
+    typeof label === "string" && uppercase ? label.toUpperCase() : label;
+
+  return (
+    <StyledMuiChip
+      data-testid="tag"
+      label={
+        <Typography variant="body4Semibold" sx={{ padding: "0px 4px" }}>
+          {formattedLabel}
+        </Typography>
+      }
+      size={size}
+      style={{ borderRadius: "999px" }}
+      color={color}
+      icon={startIcon ?? undefined}
+      disabled={disabled}
+      {...rest}
+    />
+  );
+};
+
+Tag.displayName = "Tag";
+
+export default Tag;
+export type { TagProps };

package/src/components/Tag/index.ts

@@ -0,0 +1,4 @@
+export { default } from "./Tag";
+export * from "./Tag";
+
+export * from "./types";

package/src/components/Tag/styles.ts

@@ -0,0 +1,93 @@
+import { chipClasses } from "@mui/material/Chip";
+import { Theme } from "@mui/material/styles";
+import { StyledTagProps, TagProps } from "./types";
+import { StyledComponentDefaultProps } from "../types/common";
+import { ChipHeightMap } from "../utils/HeightUtils";
+
+const getBackgroundColor = (
+  theme: Theme,
+  color: TagProps["color"] = "success"
+) => {
+  if (color === "base") {
+    return theme.palette.base?.state.selected;
+  }
+  return (
+    theme.palette[color]?.selectedHover ?? theme.palette.success.selectedHover
+  );
+};
+
+const getContentColor = (
+  theme: Theme,
+  color: TagProps["color"] = "success"
+) => {
+  if (color === "base") {
+    return theme.palette.base?.text.secondary;
+  }
+  if (color === "primary") {
+    return theme.palette.primary.main;
+  }
+  if (color === "warning") {
+    return theme.palette.warning.dark;
+  }
+
+  return (
+    theme.palette[color]?.containedHoverBackground ??
+    theme.palette.success.containedHoverBackground
+  );
+};
+const styles = ({
+  theme,
+  color = "success",
+  disabled,
+  size,
+}: StyledTagProps & StyledComponentDefaultProps) => {
+  const commonLabelStyles = {
+    fontSize: "0.75rem",
+    itemSpacing: "4px",
+    padding: "4px",
+  };
+
+  const commonIconStyles = {
+    marginLeft: "4px",
+    marginRight: "-4px",
+    width: "16px",
+    height: "16px",
+    itemSpacing: "4px",
+  };
+
+  const sizeStyles = (size === "xsmall" || size === "micro") && {
+    height: ChipHeightMap[size],
+    [`.${chipClasses.label}`]: commonLabelStyles,
+  };
+
+  const disabledStyles = disabled && {
+    backgroundColor: `${theme.palette.base?.state.disabledBackground}!important`,
+    opacity: "1 !important",
+    [`& .${chipClasses.label}`]: {
+      color: theme.palette.base?.text.disabled,
+    },
+    [`& .${chipClasses.icon}`]: {
+      ...commonIconStyles,
+      color: theme.palette.base?.text.disabled,
+    },
+  };
+
+  const enabledStyles = !disabled && {
+    backgroundColor: getBackgroundColor(theme, color),
+    [`& .${chipClasses.label}`]: {
+      color: getContentColor(theme, color),
+    },
+    [`& .${chipClasses.icon}`]: {
+      ...commonIconStyles,
+      color: getContentColor(theme, color),
+    },
+  };
+
+  return {
+    ...sizeStyles,
+    ...disabledStyles,
+    ...enabledStyles,
+  };
+};
+
+export default styles;

package/src/components/Tag/types.ts

@@ -0,0 +1,39 @@
+import { ChipProps as MuiChipProps } from "@mui/material";
+import fleetPalette from "../theme/constants/colors";
+
+declare module "@mui/material/Chip" {
+  export interface ChipPropsColorOverrides {
+    base: true;
+    default: typeof fleetPalette;
+  }
+}
+export interface TagProps extends Omit<MuiChipProps, "color" | "size"> {
+  /**
+   *  Represents the desired size of the component
+   * @default xsmall
+   */
+  size?: "micro" | "xsmall";
+  /**
+   * The color of the component. It supports those theme colors that make sense for this component.
+   * @default success
+   */
+  color?:
+    | "base"
+    | "primary"
+    | "secondary"
+    | "warning"
+    | "success"
+    | "info"
+    | "error";
+  /**
+   *  It capitalizes the label and adds custom styling.
+   * @default false
+   */
+  uppercase?: boolean;
+  /**
+   *  If defined, then the startIcon is added to the front of the label
+   */
+  startIcon?: React.ReactElement;
+}
+
+export type StyledTagProps = TagProps;

package/src/components/useMediaQuery/index.ts

@@ -0,0 +1,3 @@
+export { default } from "./useMediaQuery";
+export { default as useMediaQuery } from "./useMediaQuery";
+export * from "./useMediaQuery";

package/src/components/useMediaQuery/useMediaQuery.ts

@@ -0,0 +1,35 @@
+import muiUseMediaQuery from "@mui/material/useMediaQuery";
+
+export interface Options {
+  /**
+   * As `window.matchMedia()` is unavailable on the server,
+   * `useMediaQuery` returns `false` during server-side rendering by default.
+   * To change this behavior, set `noSsr` to `true`.
+   */
+  noSsr?: boolean;
+  /**
+   * You can provide a custom `matchMedia` implementation. This can be used for handling an `iframe` content window.
+   */
+  matchMedia?: (query: string) => MediaQueryList;
+  /**
+   * The default value to return when the hook is called on the server.
+   */
+  defaultMatches?: boolean;
+}
+
+export type QueryInput = string | ((theme: unknown) => string);
+
+/** useMediaQuery
+ *
+ *  This is a CSS media query hook for React. It listens for matches to a CSS media query.
+ *  It allows the rendering of components based on whether the query matches or not.
+ *
+ * `import useMediaQuery from '@carrier-io/air-react/useMediaQuery'`
+ */
+
+export default function useMediaQuery(
+  queryInput: QueryInput,
+  options?: Options
+): boolean {
+  return muiUseMediaQuery(queryInput, options);
+}

package/src/index.ts

@@ -59,6 +59,10 @@ export { default as AccentIndicator } from "./components/AccentIndicator";
 export type { AccentIndicatorProps } from "./components/AccentIndicator";
 export { default as Menu } from "./components/Menu";
 export type { MenuProps } from "./components/Menu";
+export { default as Tag } from "./components/Tag";
+export type { TagProps } from "./components/Tag";
+export { default as Breadcrumbs, BreadcrumbLink } from "./components/Breadcrumbs";
+export type { BreadcrumbsProps, BreadcrumbLinkProps } from "./components/Breadcrumbs";
 export * from "./components/theme";
 
 // Demo Icons - exported from main index to avoid deep-path imports