@carrier-dpx/air-react-library 0.4.0 → 0.6.0

package/src/components/Icon/README.md

@@ -0,0 +1,207 @@
+# Icon Component with Figma Code Connect
+
+This directory contains the Icon wrapper component and Figma Code Connect mappings for individual icon components.
+
+## Architecture
+
+### Icon Wrapper + Individual Icon Components
+
+The Icon system uses:
+- **One Icon wrapper component** (`Icon.tsx`) - Material-UI Icon wrapper that handles `fontSize` (xsmall, small, medium, large)
+- **Individual icon components** - Separate components for each icon (SettingsIcon, HomeIcon, etc.) that handle `variant` (outlined, filled)
+- **Individual Figma connections** - One `.figma.tsx` file per icon component
+
+## Component Usage
+
+```tsx
+import { Icon } from '@carrier-dpx/air-react-library';
+import { SettingsIcon, HomeIcon } from '@carrier-io/icons'; // Your icon library
+
+// Basic usage
+<Icon fontSize="medium">
+  <SettingsIcon variant="filled" />
+</Icon>
+
+// Different sizes
+<Icon fontSize="xsmall">
+  <HomeIcon variant="outlined" />
+</Icon>
+
+<Icon fontSize="large">
+  <SettingsIcon variant="filled" />
+</Icon>
+```
+
+## Figma Code Connect Pattern
+
+Each icon has its own `.figma.tsx` file that:
+
+1. **Imports the icon component** (from your icon library)
+2. **Imports the Icon wrapper** (for fontSize)
+3. **Maps to a specific Figma icon component** (via Figma URL)
+4. **Maps variant and optionally fontSize** props
+
+### Example: SettingsIcon.figma.tsx
+
+```tsx
+import figma from "@figma/code-connect";
+import Icon from "./Icon";
+import { SettingsIcon } from '@carrier-io/icons'; // Your icon library
+
+figma.connect(
+  SettingsIcon, // The actual icon component
+  "https://www.figma.com/design/.../SettingsIcon",
+  {
+    props: {
+      // Variant is handled by the icon component
+      variant: figma.enum("variant", {
+        outlined: "outlined",
+        filled: "filled",
+      }),
+      
+      // fontSize is optional - can be mapped from Figma or set manually
+      // fontSize: figma.enum("fontSize", {
+      //   "xsmall-12px": "xsmall",
+      //   "small-16px": "small",
+      //   "medium-24px": "medium",
+      //   "large-32px": "large",
+      // }),
+    },
+    example: ({ variant }) => (
+      <Icon fontSize="medium">
+        <SettingsIcon variant={variant} />
+      </Icon>
+    ),
+  }
+);
+```
+
+**Key Points**:
+- The icon component (SettingsIcon) is what Figma connects to
+- The Icon wrapper handles fontSize
+- Each icon gets its own `.figma.tsx` file so Figma recognizes them separately
+
+## Icon Component Structure
+
+Your icon components should follow this pattern:
+
+```tsx
+// SettingsIcon.tsx (in your icon library)
+export interface SettingsIconProps {
+  variant?: "outlined" | "filled";
+  // ... other props
+}
+
+export const SettingsIcon: FC<SettingsIconProps> = ({ variant = "outlined", ...props }) => {
+  // Render SVG based on variant
+  return <svg>...</svg>;
+};
+```
+
+## Adding New Icons
+
+To add a new icon to the Figma integration:
+
+1. **Ensure the icon component exists** in your icon library (Bitbucket repo)
+
+2. **Create a new `.figma.tsx` file** following the pattern:
+   ```tsx
+   // {IconName}Icon.figma.tsx
+   import figma from "@figma/code-connect";
+   import Icon from "./Icon";
+   import { YourIconName } from '@carrier-io/icons'; // Your icon library
+   
+   figma.connect(
+     YourIconName,
+     "YOUR_FIGMA_ICON_URL_HERE",
+     {
+       props: {
+         variant: figma.enum("variant", {
+           outlined: "outlined",
+           filled: "filled",
+         }),
+       },
+       example: ({ variant }) => (
+         <Icon fontSize="medium">
+           <YourIconName variant={variant} />
+         </Icon>
+       ),
+     }
+   );
+   ```
+
+3. **Get the Figma URL** by:
+   - Opening the icon component in Figma
+   - Right-clicking → "Copy link to selection"
+   - Replacing the URL in the `figma.connect()` call
+
+## Scaling to 700 Icons
+
+### Option 1: Manual Creation
+Create individual `.figma.tsx` files for each icon. This gives you full control.
+
+### Option 2: Code Generation Script
+Create a script that generates `.figma.tsx` files from a list of icons:
+
+```typescript
+// scripts/generateIconConnections.ts
+const icons = [
+  { name: "SettingsIcon", figmaNodeId: "SETTINGS-ICON-NODE-ID" },
+  { name: "HomeIcon", figmaNodeId: "HOME-ICON-NODE-ID" },
+  // ... 698 more icons
+];
+
+icons.forEach(({ name, figmaNodeId }) => {
+  const content = `
+import figma from "@figma/code-connect";
+import Icon from "./Icon";
+import { ${name} } from '@carrier-io/icons';
+
+figma.connect(
+  ${name},
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=${figmaNodeId}",
+  {
+    props: {
+      variant: figma.enum("variant", {
+        outlined: "outlined",
+        filled: "filled",
+      }),
+    },
+    example: ({ variant }) => (
+      <Icon fontSize="medium">
+        <${name} variant={variant} />
+      </Icon>
+    ),
+  }
+);
+  `;
+  // Write to file: ${name}.figma.tsx
+});
+```
+
+## Icon Library Integration
+
+The icon components should be imported from your icon library package (Bitbucket repo). Update the imports in each `.figma.tsx` file to point to your actual icon library:
+
+```tsx
+// Replace placeholder imports with actual icon library imports
+import { SettingsIcon, HomeIcon, UserIcon } from '@carrier-io/icons';
+```
+
+## Testing
+
+The current setup includes sample Figma connections for testing. To test:
+
+1. **Update imports** in `.figma.tsx` files to point to your actual icon library
+2. **Update Figma URLs** with real node IDs from your Figma file
+3. **Run** `npm run figma:connect` to publish connections
+4. **Open Figma** and check Dev Mode
+5. **Select an icon component** → verify it shows the correct React code
+
+## Notes
+
+- Each icon needs its own Figma component with a "variant" property (outlined/filled)
+- The Icon wrapper handles fontSize (xsmall, small, medium, large)
+- Icon components handle variant (outlined, filled)
+- Icon components are imported from your icon library (Bitbucket repo)
+- The Figma URL must point to the specific icon component instance

package/src/components/Icon/SearchIcon.figma.tsx

@@ -0,0 +1,32 @@
+/**
+ * Figma Code Connect Configuration for Search Icon
+ * 
+ * NOTE: Import SearchIcon from your actual icon library package.
+ * Example: import { SearchIcon } from '@carrier-io/icons';
+ */
+
+import figma from "@figma/code-connect";
+import Icon from "./Icon";
+// TODO: Import from your actual icon library
+// import { SearchIcon } from '@carrier-io/icons';
+
+// Placeholder - replace with actual SearchIcon import
+const SearchIcon = ({ variant, ...props }: any) => <span {...props}>SearchIcon</span>;
+
+figma.connect(
+  SearchIcon,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=SEARCH-ICON-NODE-ID",
+  {
+    props: {
+      variant: figma.enum("variant", {
+        outlined: "outlined",
+        filled: "filled",
+      }),
+    },
+    example: ({ variant }) => (
+      <Icon fontSize="medium">
+        <SearchIcon variant={variant} />
+      </Icon>
+    ),
+  }
+);

package/src/components/Icon/SettingsIcon.figma.tsx

@@ -0,0 +1,61 @@
+/**
+ * Figma Code Connect Configuration for Settings Icon
+ * 
+ * This connects Figma's SettingsIcon component to the React SettingsIcon component.
+ * The icon component is wrapped in the Icon wrapper for fontSize control.
+ * 
+ * Figma URL: https://www.figma.com/design/RT43n0bKuuIt7ylllD3DR0/Icon-Library?node-id=1401-6386
+ * 
+ * NOTE: Import SettingsIcon from your actual icon library package.
+ * Example: import { SettingsIcon } from '@carrier-io/icons';
+ */
+
+import figma from "@figma/code-connect";
+import Icon from "./Icon";
+// TODO: Import from your actual icon library
+// import { SettingsIcon } from '@carrier-io/icons';
+
+// Placeholder - replace with actual SettingsIcon import
+const SettingsIcon = ({ variant, ...props }: any) => <span {...props}>SettingsIcon</span>;
+
+figma.connect(
+  SettingsIcon,
+  "https://www.figma.com/design/RT43n0bKuuIt7ylllD3DR0/Icon-Library?node-id=1401-6386",
+  {
+    props: {
+      /**
+       * STYLE MAPPING
+       * Maps Figma's "Style" property to the icon component's "variant" prop
+       * Figma uses "Style" with values "Outlined" and "Filled"
+       * React icon component expects "variant" with values "outlined" and "filled"
+       */
+      variant: figma.enum("Style", {
+        Outlined: "outlined",
+        Filled: "filled",
+      }),
+      
+      /**
+       * FONT SIZE MAPPING (optional)
+       * If your Figma icon component has a fontSize property, map it here
+       * Otherwise, fontSize is set on the Icon wrapper component
+       */
+      // fontSize: figma.enum("fontSize", {
+      //   "xsmall-12px": "xsmall",
+      //   "small-16px": "small",
+      //   "medium-24px": "medium",
+      //   "large-32px": "large",
+      // }),
+    },
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows the icon component wrapped in Icon for fontSize control.
+     * The Icon wrapper handles fontSize (xsmall, small, medium, large).
+     * The icon component handles variant (outlined, filled).
+     */
+    example: ({ variant }) => (
+      <Icon fontSize="medium">
+        <SettingsIcon variant={variant} />
+      </Icon>
+    ),
+  }
+);

package/src/components/Icon/UserIcon.figma.tsx

@@ -0,0 +1,32 @@
+/**
+ * Figma Code Connect Configuration for User Icon
+ * 
+ * NOTE: Import UserIcon from your actual icon library package.
+ * Example: import { UserIcon } from '@carrier-io/icons';
+ */
+
+import figma from "@figma/code-connect";
+import Icon from "./Icon";
+// TODO: Import from your actual icon library
+// import { UserIcon } from '@carrier-io/icons';
+
+// Placeholder - replace with actual UserIcon import
+const UserIcon = ({ variant, ...props }: any) => <span {...props}>UserIcon</span>;
+
+figma.connect(
+  UserIcon,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=USER-ICON-NODE-ID",
+  {
+    props: {
+      variant: figma.enum("variant", {
+        outlined: "outlined",
+        filled: "filled",
+      }),
+    },
+    example: ({ variant }) => (
+      <Icon fontSize="medium">
+        <UserIcon variant={variant} />
+      </Icon>
+    ),
+  }
+);

package/src/components/Icon/index.ts

@@ -0,0 +1,3 @@
+export { default } from "./Icon";
+export * from "./Icon";
+export type { IconProps } from "./Icon";

package/src/components/Link/Link.figma.tsx

@@ -0,0 +1,70 @@
+/**
+ * Figma Code Connect Configuration for Link Component
+ */
+
+import figma from "@figma/code-connect";
+import Link from "./Link";
+
+figma.connect(
+  Link,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=6574-50682",
+  {
+    props: {
+      /**
+       * VARIANT MAPPING
+       * Same variants as Typography component
+       */
+      variant: figma.enum("variant", {
+        body1: "body1",
+        "body1 semibold": "body1Semibold",
+        "body1 bold": "body1Bold",
+        body2: "body2",
+        "body2 semibold": "body2Semibold",
+        "body2 bold": "body2Bold",
+        body3: "body3",
+        "body3 semibold": "body3Semibold",
+        "body3 bold": "body3Bold",
+        h1: "h1",
+        h2: "h2",
+        h3: "h3",
+        h4: "h4",
+        h5: "h5",
+        h6: "h6",
+        caps1: "caps1",
+        "caps1 bold": "caps1Bold",
+        caps2: "caps2",
+        "caps2 bold": "caps2Bold",
+        caps3: "caps3",
+        "caps3 bold": "caps3Bold",
+        caps4: "caps4",
+        "caps4 bold": "caps4Bold",
+      }),
+
+      /**
+       * UNDERLINE MAPPING
+       * Maps Figma underline style to React underline prop
+       */
+      underline: figma.enum("underline", {
+        always: "always",
+        hover: "hover",
+        none: "none",
+      }),
+
+      /**
+       * TEXT CONTENT
+       * Maps the link text from "Label" layer
+       */
+      children: figma.children("Label"),
+    },
+
+    /**
+     * CODE EXAMPLE TEMPLATE
+     * Note: href is a runtime prop, not configured in static Figma component
+     */
+    example: ({ variant, underline, children }) => (
+      <Link variant={variant} underline={underline} href="#">
+        {children}
+      </Link>
+    ),
+  }
+);

package/src/components/Link/Link.tsx

@@ -0,0 +1,69 @@
+import { forwardRef } from "react";
+
+import MuiLink, { LinkProps as MuiLinkProps } from "@mui/material/Link";
+import { AllSystemCSSProperties, ResponsiveStyleValue } from "@mui/system";
+import { useTheme } from "@mui/material";
+import { TypographyProps } from "@mui/material/Typography";
+
+// List of variants we want to exclude
+type ExcludedVariants =
+  | "overline"
+  | "avatarLetter"
+  | "buttonLarge"
+  | "buttonMedium"
+  | "buttonSmall"
+  | "caption"
+  | "inputLabel"
+  | "inputText1"
+  | "inputText2"
+  | "helperText"
+  | "alertTitle"
+  | "tableHeader1"
+  | "tableHeader2"
+  | "badge"
+  | "chip"
+  | "tooltip";
+
+// Get all valid variant options from MUI's Typography component
+type MUIValidVariants = Exclude<TypographyProps["variant"], ExcludedVariants>;
+
+export interface LinkProps extends Omit<MuiLinkProps, "variant"> {
+  /**
+   * Specifies how to capitalize an element's text
+   */
+  textTransform?: ResponsiveStyleValue<AllSystemCSSProperties["textTransform"]>;
+  /**
+   * The target attribute specifies where to open the linked document:
+   */
+  target?: string;
+  /**
+   * Applies the theme typography styles.
+   */
+  variant?: MUIValidVariants;
+}
+
+/** The Link component allows you to easily customize anchor elements with your theme colors and typography styles.
+ *
+ * `import Link from '@carrier-io/air-react/Link'`
+ */
+
+const Link = forwardRef<HTMLAnchorElement, LinkProps>(
+  ({ color, variant = "body2", ...rest }, ref) => {
+    const theme = useTheme();
+    const resolvedColor = color ?? theme.palette.primary.main;
+
+    return (
+      <MuiLink
+        {...rest}
+        color={resolvedColor}
+        ref={ref}
+        variant={variant}
+        sx={{ cursor: "pointer", textUnderlineOffset: "4px" }}
+      />
+    );
+  }
+);
+
+Link.displayName = "Link";
+
+export default Link;

package/src/components/Link/index.ts

@@ -0,0 +1,3 @@
+export { default } from "./Link";
+export * from "./Link";
+export type { LinkProps } from "./Link";

package/src/components/theme/FleetThemeProvider.tsx

@@ -1,50 +1,50 @@
-import React, { ReactNode, useEffect } from "react";
-import { Theme, ThemeProvider, createTheme } from "@mui/material/styles";
-import { airDarkThemeOptions, fleetThemeOptions } from "./fleetThemeOptions";
-
-// Define theme instances
-const ahpTheme: Theme = createTheme({ ...fleetThemeOptions });
-
-const airLightTheme: Theme = createTheme(fleetThemeOptions);
-
-const airDarkTheme: Theme = createTheme(airDarkThemeOptions);
-
-// Mapping from theme names to actual Theme instances
-export const ThemeMap = {
-  AHP: ahpTheme,
-  AirLight: airLightTheme,
-  AirDark: airDarkTheme,
-} as const;
-
-// Define props for FleetThemeProvider
-export type ThemeProviderProps = {
-  /** Content to render with the specified theme */
-  children?: ReactNode;
-
-  /** Custom Theme instance or predefined theme key */
-  theme?: Theme | keyof typeof ThemeMap;
-};
-
-// FleetThemeProvider component
-const FleetThemeProvider: React.FC<ThemeProviderProps> = ({
-  children,
-  theme = airLightTheme, // Default to airLightTheme
-}) => {
-  const resolvedTheme = typeof theme === "string" ? ThemeMap[theme] : theme;
-
-  // Load Nunito Sans font
-  useEffect(() => {
-    // Check if font is already loaded
-    if (!document.querySelector('link[href*="Nunito+Sans"]')) {
-      const link = document.createElement('link');
-      link.href = 'https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@200;300;400;600;700;800;900&display=swap';
-      link.rel = 'stylesheet';
-      document.head.appendChild(link);
-    }
-  }, []);
-
-  return <ThemeProvider theme={resolvedTheme}>{children}</ThemeProvider>;
-};
-
-export default FleetThemeProvider;
-export { FleetThemeProvider };
+import React, { ReactNode, useEffect } from "react";
+import { Theme, ThemeProvider, createTheme } from "@mui/material/styles";
+import { airDarkThemeOptions, fleetThemeOptions } from "./fleetThemeOptions";
+
+// Define theme instances
+const ahpTheme: Theme = createTheme({ ...fleetThemeOptions });
+
+const airLightTheme: Theme = createTheme(fleetThemeOptions);
+
+const airDarkTheme: Theme = createTheme(airDarkThemeOptions);
+
+// Mapping from theme names to actual Theme instances
+export const ThemeMap = {
+  AHP: ahpTheme,
+  AirLight: airLightTheme,
+  AirDark: airDarkTheme,
+} as const;
+
+// Define props for FleetThemeProvider
+export type ThemeProviderProps = {
+  /** Content to render with the specified theme */
+  children?: ReactNode;
+
+  /** Custom Theme instance or predefined theme key */
+  theme?: Theme | keyof typeof ThemeMap;
+};
+
+// FleetThemeProvider component
+const FleetThemeProvider: React.FC<ThemeProviderProps> = ({
+  children,
+  theme = airLightTheme, // Default to airLightTheme
+}) => {
+  const resolvedTheme = typeof theme === "string" ? ThemeMap[theme] : theme;
+
+  // Load Nunito Sans font
+  useEffect(() => {
+    // Check if font is already loaded
+    if (!document.querySelector('link[href*="Nunito+Sans"]')) {
+      const link = document.createElement('link');
+      link.href = 'https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@200;300;400;600;700;800;900&display=swap';
+      link.rel = 'stylesheet';
+      document.head.appendChild(link);
+    }
+  }, []);
+
+  return <ThemeProvider theme={resolvedTheme}>{children}</ThemeProvider>;
+};
+
+export default FleetThemeProvider;
+export { FleetThemeProvider };