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

package/src/components/List/List.figma.tsx

@@ -0,0 +1,110 @@
+/**
+ * Figma Code Connect Configuration for List Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=19353-120893
+ * 
+ * Figma Properties:
+ * - subheader (true, false) - boolean hide/show
+ * 
+ * Structure:
+ * - Container: Frame wrapping Subheader and ListItem components
+ * - Subheader: Nested component "ListItems/List Subheader" with layer name "Subheader"
+ *   - Contains Typography component with layer name "↪ Subheader"
+ * - List Item 1-10: Multiple ListItem instances with numbered layer names
+ */
+
+import figma from "@figma/code-connect";
+import List from "./List";
+import ListSubheader from "./ListSubheader";
+import ListItem from "./ListItem";
+import Typography from "../Typography";
+
+figma.connect(
+  List,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=19353-120893",
+  {
+    props: {
+      /**
+       * SUBHEADER VISIBILITY
+       * Maps Figma's "subheader" boolean property
+       * When true, shows the nested "Subheader" component
+       */
+      subheader: figma.boolean("subheader"),
+
+      /**
+       * SUBHEADER TEXT CONTENT
+       * Maps text content from nested Typography component with layer name "Subheader/↪ Subheader"
+       * Using full path to avoid nested nestedProps
+       */
+      subheaderText: figma.nestedProps("Subheader/↪ Subheader", {
+        children: figma.children("Subheader/↪ Subheader"),
+      }),
+
+      /**
+       * LIST ITEM CHILDREN
+       * Maps nested ListItem instances from Figma
+       * Each "List Item X" is an instance of the ListItem component
+       * We map each one individually using the exact layer names
+       */
+      listItem1: figma.children("List Item 1"),
+      listItem2: figma.children("List Item 2"),
+      listItem3: figma.children("List Item 3"),
+      listItem4: figma.children("List Item 4"),
+      listItem5: figma.children("List Item 5"),
+      listItem6: figma.children("List Item 6"),
+      listItem7: figma.children("List Item 7"),
+      listItem8: figma.children("List Item 8"),
+      listItem9: figma.children("List Item 9"),
+      listItem10: figma.children("List Item 10"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how List should be used with optional subheader and ListItem children
+     * Note: This example handles up to 10 list items. Adjust based on your design needs.
+     */
+    example: ({ subheader, subheaderText, listItem1, listItem2, listItem3, listItem4, listItem5, listItem6, listItem7, listItem8, listItem9, listItem10 }) => {
+      // Handle case with subheader and multiple list items
+      if (subheader && subheaderText && subheaderText.children) {
+        return (
+          <List
+            subheader={
+              <ListSubheader>
+                <Typography variant="body2Semibold">
+                  {subheaderText.children}
+                </Typography>
+              </ListSubheader>
+            }
+          >
+            {listItem1}
+            {listItem2}
+            {listItem3}
+            {listItem4}
+            {listItem5}
+            {listItem6}
+            {listItem7}
+            {listItem8}
+            {listItem9}
+            {listItem10}
+          </List>
+        );
+      }
+
+      // Handle case without subheader
+      return (
+        <List>
+          {listItem1}
+          {listItem2}
+          {listItem3}
+          {listItem4}
+          {listItem5}
+          {listItem6}
+          {listItem7}
+          {listItem8}
+          {listItem9}
+          {listItem10}
+        </List>
+      );
+    },
+  }
+);

package/src/components/List/List.tsx

@@ -0,0 +1,72 @@
+import { forwardRef } from "react";
+
+import {
+  List as MuiList,
+  ListProps as MuiListProps,
+  CSSObject,
+  Theme,
+} from "@mui/material";
+import { styleTokens } from "../theme/constants/styleTokens";
+import { getSxStyles } from "../utils/styles";
+
+export interface ListProps extends MuiListProps {
+  maxHeight?: string;
+  // this may be updated later if Design needs any props to be removed
+
+  /**
+   * The content of the subheader, normally `ListSubheader`.
+   */
+  subheader?: React.ReactNode;
+
+  /**
+   * Toggles the display of the subheader. Set to `true` to show the subheader.
+   */
+  showSubheader?: boolean;
+
+  /**
+   * Added padding between the list
+   * @default false
+   */
+  padded?: boolean;
+}
+
+/** The List component is useful for organizing related content or actions in a vertical format.
+ *
+ * `import List from '@carrier-io/air-react/List'`
+ */
+
+const List = forwardRef<HTMLUListElement, ListProps>(
+  (
+    { maxHeight, sx, subheader, showSubheader = true, padded = false, ...rest },
+    ref
+  ) => {
+    return (
+      <MuiList
+        ref={ref}
+        {...rest}
+        sx={(theme: Theme) =>
+          ({
+            backgroundColor: theme.palette.base?.background.paper,
+            maxHeight: maxHeight ?? "auto",
+            overflowY: maxHeight ? "auto" : "visible",
+            ...(padded && {
+              ".MuiListItem-root": {
+                padding: styleTokens.paddingItem,
+              },
+              ".MuiListItemButton-root": {
+                padding: styleTokens.paddingItem,
+              },
+            }),
+            ...getSxStyles(theme, sx),
+          } as CSSObject)
+        }
+        subheader={showSubheader && subheader ? subheader : null}
+      />
+    );
+  }
+);
+
+List.displayName = "List";
+
+export default List;
+export type { ListProps };

package/src/components/List/ListItem.figma.tsx

@@ -0,0 +1,298 @@
+/**
+ * Figma Code Connect Configuration for ListItem Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=22974-86899
+ * 
+ * Figma Properties:
+ * - size (large: 48px, medium: 40px, small: 32px)
+ * - padded (true, false)
+ * - selected (true, false)
+ * - disabled (true, false)
+ * - disableGutters (true, false)
+ * - state (enabled, hover, focus) - visual state, not a prop
+ * - divider (true, false) - boolean hide/show
+ * - nesting (true, false) - boolean hide/show
+ * - startAdornment (true, false) - boolean hide/show
+ * - endAdornment (true, false) - boolean hide/show
+ * - statusStart (true, false) - boolean hide/show (uses AccentIndicator - to be added later)
+ * - statusEnd (true, false) - boolean hide/show (uses AccentIndicator - to be added later)
+ * 
+ * Structure:
+ * - Labels (nested component): Contains header, label, and helperText Typography components
+ *   - header (true, false) - Typography component
+ *   - label (true, false) - Typography component
+ *   - helperText (true, false) - Typography component
+ */
+
+import figma from "@figma/code-connect";
+import ListItem from "./ListItem";
+import ListItemText from "./ListItemText";
+import Typography from "../Typography";
+import AccentIndicator from "../AccentIndicator";
+
+figma.connect(
+  ListItem,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=22974-86899",
+  {
+    props: {
+      /**
+       * SIZE MAPPING
+       * Maps Figma's "size" property to React's "size" prop
+       * Figma: large (48px), medium (40px), small (32px)
+       */
+      size: figma.enum("size", {
+        "large: 48px": "large",
+        "medium: 40px": "medium",
+        "small: 32px": "small",
+        large: "large",
+        medium: "medium",
+        small: "small",
+      }),
+
+      /**
+       * PADDED MAPPING
+       * Maps Figma's "padded" boolean to React's "padded" prop
+       */
+      padded: figma.boolean("padded"),
+
+      /**
+       * SELECTED STATE
+       * Maps Figma's "selected" boolean to React's "selected" prop
+       */
+      selected: figma.boolean("selected"),
+
+      /**
+       * DISABLED STATE
+       * Maps Figma's "disabled" boolean to React's "disabled" prop
+       */
+      disabled: figma.boolean("disabled"),
+
+      /**
+       * DISABLE GUTTERS
+       * Maps Figma's "disableGutters" boolean to React's "disableGutters" prop
+       */
+      disableGutters: figma.boolean("disableGutters"),
+
+      /**
+       * DIVIDER VISIBILITY
+       * Maps Figma's "divider" boolean - controls divider visibility
+       */
+      divider: figma.boolean("divider"),
+
+      /**
+       * NESTING VISIBILITY
+       * Maps Figma's "nesting" boolean - controls nesting visibility
+       */
+      nesting: figma.boolean("nesting"),
+
+      /**
+       * START ADORNMENT VISIBILITY
+       * Maps Figma's "startAdornment" boolean - controls start adornment visibility
+       */
+      startAdornment: figma.boolean("startAdornment"),
+
+      /**
+       * END ADORNMENT VISIBILITY
+       * Maps Figma's "endAdornment" boolean - controls end adornment visibility
+       */
+      endAdornment: figma.boolean("endAdornment"),
+
+      /**
+       * STATUS START ACCENT INDICATOR
+       * Maps nested AccentIndicator component instance when statusStart is visible
+       * The AccentIndicator is nested within the statusStart layer
+       * Uses figma.instance() to get the AccentIndicator component instance
+       */
+      statusStart: figma.instance("statusStart"),
+
+      /**
+       * STATUS END ACCENT INDICATOR
+       * Maps nested AccentIndicator component instance when statusEnd is visible
+       * The AccentIndicator is nested within the statusEnd layer
+       * Uses figma.instance() to get the AccentIndicator component instance
+       */
+      statusEnd: figma.instance("statusEnd"),
+
+      /**
+       * LABELS NESTED PROPERTIES
+       * Access properties from nested "Labels" component (layer name "Labels")
+       * Contains header, label, and helperText Typography components
+       */
+      labels: figma.nestedProps("Labels", {
+        /**
+         * HEADER VISIBILITY
+         * Maps Figma's "header" boolean from nested "Labels" component
+         */
+        header: figma.boolean("header"),
+
+        /**
+         * LABEL VISIBILITY
+         * Maps Figma's "label" boolean from nested "Labels" component
+         */
+        label: figma.boolean("label"),
+
+        /**
+         * HELPER TEXT VISIBILITY
+         * Maps Figma's "helperText" boolean from nested "Labels" component
+         */
+        helperText: figma.boolean("helperText"),
+      }),
+
+      /**
+       * HEADER TEXT CONTENT
+       * Maps text content from nested "Labels/header" Typography component
+       * Using full path to avoid nested nestedProps
+       */
+      headerText: figma.nestedProps("Labels/header", {
+        children: figma.children("Labels/header"),
+      }),
+
+      /**
+       * LABEL TEXT CONTENT
+       * Maps text content from nested "Labels/label" Typography component
+       * Using full path to avoid nested nestedProps
+       */
+      labelText: figma.nestedProps("Labels/label", {
+        children: figma.children("Labels/label"),
+      }),
+
+      /**
+       * HELPER TEXT CONTENT
+       * Maps text content from nested "Labels/helperText" Typography component
+       * Using full path to avoid nested nestedProps
+       */
+      helperTextContent: figma.nestedProps("Labels/helperText", {
+        children: figma.children("Labels/helperText"),
+      }),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how ListItem should be used with optional labels, adornments, and AccentIndicators
+     */
+    example: ({ size, padded, selected, disabled, disableGutters, divider, labels, statusStart, statusEnd, headerText, labelText, helperTextContent }) => {
+      // Handle case with header, label, and helperText
+      if (labels && labels.header && headerText && headerText.children && labels.label && labelText && labelText.children && labels.helperText && helperTextContent && helperTextContent.children) {
+        return (
+          <ListItem
+            size={size}
+            padded={padded}
+            selected={selected}
+            disabled={disabled}
+            disableGutters={disableGutters}
+            divider={divider}
+          >
+            {statusStart}
+            <Typography variant="body1Semibold">
+              {headerText.children}
+            </Typography>
+            <ListItemText
+              primary={labelText.children}
+              secondary={helperTextContent.children}
+            />
+            {statusEnd}
+          </ListItem>
+        );
+      }
+
+      // Handle case with header and label (no helperText)
+      if (labels && labels.header && headerText && headerText.children && labels.label && labelText && labelText.children) {
+        return (
+          <ListItem
+            size={size}
+            padded={padded}
+            selected={selected}
+            disabled={disabled}
+            disableGutters={disableGutters}
+            divider={divider}
+          >
+            {statusStart}
+            <Typography variant="body1Semibold">
+              {headerText.children}
+            </Typography>
+            <ListItemText
+              primary={labelText.children}
+            />
+            {statusEnd}
+          </ListItem>
+        );
+      }
+
+      // Handle case with label and helperText (no header)
+      if (labels && labels.label && labelText && labelText.children && labels.helperText && helperTextContent && helperTextContent.children) {
+        return (
+          <ListItem
+            size={size}
+            padded={padded}
+            selected={selected}
+            disabled={disabled}
+            disableGutters={disableGutters}
+            divider={divider}
+          >
+            {statusStart}
+            <ListItemText
+              primary={labelText.children}
+              secondary={helperTextContent.children}
+            />
+            {statusEnd}
+          </ListItem>
+        );
+      }
+
+      // Handle case with only label
+      if (labels && labels.label && labelText && labelText.children) {
+        return (
+          <ListItem
+            size={size}
+            padded={padded}
+            selected={selected}
+            disabled={disabled}
+            disableGutters={disableGutters}
+            divider={divider}
+          >
+            {statusStart}
+            <ListItemText
+              primary={labelText.children}
+            />
+            {statusEnd}
+          </ListItem>
+        );
+      }
+
+      // Handle case with only header
+      if (labels && labels.header && headerText && headerText.children) {
+        return (
+          <ListItem
+            size={size}
+            padded={padded}
+            selected={selected}
+            disabled={disabled}
+            disableGutters={disableGutters}
+            divider={divider}
+          >
+            {statusStart}
+            <Typography variant="body1Semibold">
+              {headerText.children}
+            </Typography>
+            {statusEnd}
+          </ListItem>
+        );
+      }
+
+      // Fallback: ListItem with no labels
+      return (
+        <ListItem
+          size={size}
+          padded={padded}
+          selected={selected}
+          disabled={disabled}
+          disableGutters={disableGutters}
+          divider={divider}
+        >
+          {statusStart}
+          {statusEnd}
+        </ListItem>
+      );
+    },
+  }
+);

package/src/components/List/ListItem.tsx

@@ -0,0 +1,58 @@
+import { forwardRef } from "react";
+import { heightMap } from "../utils/HeightUtils";
+import {
+  ListItem as MuiListItem,
+  ListItemProps as MuiListItemProps,
+} from "@mui/material";
+import { getSxStyles } from "../utils/styles";
+import { CSSObject } from "@emotion/react";
+import { styleTokens } from "../theme/constants/styleTokens";
+
+export interface ListItemProps extends MuiListItemProps {
+  /**
+   * size of the component
+   */
+  size?: keyof typeof heightMap;
+  /**
+   * If `true`, list item has padding on left and right.
+   * @default true
+   */
+  padded?: boolean;
+  /**
+   * If `true`, the left and right padding is removed.
+   * @default false
+   */
+  disableGutters?: boolean;
+}
+
+/** ListItem
+ *
+ * `import ListItem from '@carrier-io/air-react/ListItem'`
+ */
+
+const ListItem = forwardRef<HTMLLIElement, ListItemProps>((props, ref) => {
+  const { size, sx, padded = true, disableGutters = false, ...rest } = props;
+
+  return (
+    <MuiListItem
+      sx={(theme) =>
+        ({
+          height: size ? heightMap[size] : "auto",
+          padding: disableGutters
+            ? "0"
+            : padded
+            ? `${styleTokens.padding.xsmall} ${styleTokens.padding.xlarge}`
+            : styleTokens.padding.xsmall,
+          ...getSxStyles(theme, sx),
+        } as CSSObject)
+      }
+      {...rest}
+      ref={ref}
+    />
+  );
+});
+
+ListItem.displayName = "ListItem";
+
+export default ListItem;
+export type { ListItemProps };

package/src/components/List/ListItemAvatar.tsx

@@ -0,0 +1,26 @@
+import { forwardRef } from "react";
+
+import {
+  ListItemAvatar as MuiListItemAvatar,
+  ListItemAvatarProps as MuiListItemAvatarProps,
+} from "@mui/material";
+
+export interface ListItemAvatarProps extends MuiListItemAvatarProps {
+  // this may be updated later if Design needs any props to be removed
+}
+
+/** ListItemAvatar
+ *
+ * `import ListItemAvatarProps from '@carrier-io/air-react/ListItemAvatar'`
+ */
+
+const ListItemAvatar = forwardRef<HTMLDivElement, ListItemAvatarProps>(
+  (props, ref) => {
+    return <MuiListItemAvatar {...props} ref={ref} />;
+  }
+);
+
+ListItemAvatar.displayName = "ListItemAvatar";
+
+export default ListItemAvatar;
+export type { ListItemAvatarProps };

package/src/components/List/ListItemButton.tsx

@@ -0,0 +1,42 @@
+import { forwardRef } from "react";
+
+import {
+  ListItemButton as MuiListItemButton,
+  ListItemButtonProps as MuiListItemButtonProps,
+} from "@mui/material";
+import { Theme, styled } from "@mui/material/styles";
+
+export interface ListItemButtonProps extends MuiListItemButtonProps {
+  // this may be updated later if Design needs any props to be removed
+}
+
+/** ListItemButton
+ *
+ * `import ListItemButton from '@carrier-io/air-react/ListItemButton'`
+ */
+
+const MuiListItemButtonStyled = styled(MuiListItemButton)(
+  ({ theme }: { theme: Theme }) => ({
+    color: theme.palette.base?.state.active,
+    "&:hover": {
+      backgroundColor: theme.palette.base?.state.hover,
+    },
+    "&.Mui-selected": {
+      backgroundColor: theme.palette.base?.state.selected,
+    },
+    "&.Mui-selected:hover": {
+      backgroundColor: theme.palette.base?.state.selectedHover,
+    },
+  })
+);
+
+const ListItemButton = forwardRef<HTMLDivElement, ListItemButtonProps>(
+  (props, ref) => {
+    return <MuiListItemButtonStyled {...props} ref={ref} />;
+  }
+);
+
+ListItemButton.displayName = "ListItemButton";
+
+export default ListItemButton;
+export type { ListItemButtonProps };

package/src/components/List/ListItemIcon.tsx

@@ -0,0 +1,41 @@
+import { forwardRef } from "react";
+
+import {
+  ListItemIcon as MuiListItemIcon,
+  ListItemIconProps as MuiListItemIconProps,
+  CSSObject,
+  Theme,
+} from "@mui/material";
+
+import { getSxStyles } from "../utils/styles";
+
+export interface ListItemIconProps extends MuiListItemIconProps {
+  // this may be updated later if Design needs any props to be removed
+}
+
+/** ListItemIcon
+ *
+ * `import ListItemIcon from '@carrier-io/air-react/ListItemIcon'`
+ */
+
+const ListItemIcon = forwardRef<HTMLDivElement, ListItemIconProps>(
+  (props, ref) => {
+    return (
+      <MuiListItemIcon
+        {...props}
+        sx={(theme: Theme) =>
+          ({
+            color: theme.palette.base?.state.active,
+            ...getSxStyles(theme, props.sx),
+          } as CSSObject)
+        }
+        ref={ref}
+      />
+    );
+  }
+);
+
+ListItemIcon.displayName = "ListItemIcon";
+
+export default ListItemIcon;
+export type { ListItemIconProps };

package/src/components/List/ListItemSecondaryAction.tsx

@@ -0,0 +1,28 @@
+import { forwardRef } from "react";
+
+import {
+  ListItemSecondaryAction as MuiListItemSecondaryAction,
+  ListItemSecondaryActionProps as MuiListItemSecondaryActionProps,
+} from "@mui/material";
+
+export interface ListItemSecondaryActionProps
+  extends MuiListItemSecondaryActionProps {
+  // this may be updated later if Design needs any props to be removed
+}
+
+/** ListItemSecondaryAction
+ *
+ * `import ListItemSecondaryAction from '@carrier-io/air-react/ListItemSecondaryAction'`
+ */
+
+const ListItemSecondaryAction = forwardRef<
+  HTMLDivElement,
+  ListItemSecondaryActionProps
+>((props, ref) => {
+  return <MuiListItemSecondaryAction {...props} ref={ref} />;
+});
+
+ListItemSecondaryAction.displayName = "ListItemSecondaryAction";
+
+export default ListItemSecondaryAction;
+export type { ListItemSecondaryActionProps };