@carrier-dpx/air-react-library 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# Air React Library
+
+Air web React component library for Figma Make integration.
+
+## Installation
+
+```bash
+npm install @carrier-dpx/air-react-library
+```
+
+## Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```bash
+npm install react react-dom @mui/material @emotion/react @emotion/styled
+```
+
+## Usage
+
+### Button Component
+
+```tsx
+import { Button } from '@carrier-dpx/air-react-library';
+
+function App() {
+  return (
+    <Button
+      variant="contained"
+      color="primary"
+      size="large"
+      onClick={() => console.log('clicked')}
+    >
+      Get Started
+    </Button>
+  );
+}
+```
+
+### Available Props
+
+#### Button
+
+- `variant`: `"contained"` | `"outlined"` | `"text"` (default: `"contained"`)
+- `color`: `"base"` | `"primary"` | `"secondary"` | `"error"` | `"warning"` | `"success"` | `"info"` (default: `"primary"`)
+- `size`: `"xlarge"` | `"large"` | `"medium"` | `"small"` | `"xsmall"`
+- `shape`: `"rounded"` | `"circular"` (default: `"rounded"`)
+- `disabled`: `boolean`
+- `startIcon`: `ReactNode` - Icon to display before the button text
+- `endIcon`: `ReactNode` - Icon to display after the button text
+- `onClick`: `() => void` - Click handler
+- All standard Material-UI Button props
+
+## Figma Integration
+
+This library is integrated with Figma Code Connect. When using Figma Make, components from this library will be automatically suggested and used in generated code.
+
+## Components
+
+Currently available components:
+
+- **Button** - Material-UI based button component with Carrier DPX design system styling
+
+More components coming soon!
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/Carrier-DPX/air-react-library](https://github.com/Carrier-DPX/air-react-library)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@carrier-dpx/air-react-library",
+  "version": "0.1.0",
+  "description": "Air web React component library for Figma Make",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Carrier-DPX/air-react-library.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "figma:connect": "figma connect",
+    "figma:publish": "figma connect publish"
+  },
+  "keywords": [
+    "react",
+    "components",
+    "figma",
+    "code-connect",
+    "carrier",
+    "design-system",
+    "ui",
+    "material-ui"
+  ],
+  "author": "Carrier DPX",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@mui/material": "^5.0.0",
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0"
+  },
+  "devDependencies": {
+    "@figma/code-connect": "^1.0.0",
+    "@mui/material": "^5.15.0",
+    "@emotion/react": "^11.11.0",
+    "@emotion/styled": "^11.11.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/components/Button/Button.figma.tsx

@@ -0,0 +1,142 @@
+/**
+ * Figma Code Connect Configuration for Button Component
+ * 
+ * This file creates the bridge between your Figma Button component
+ * and your React Button component. It tells Figma Make:
+ * 1. Which React component corresponds to which Figma component
+ * 2. How Figma properties/variants map to React props
+ * 3. How to generate code examples
+ */
+
+import figma from "@figma/code-connect";
+import Button from "./Button";
+
+/**
+ * figma.connect() creates the connection between Figma and React
+ * 
+ * Parameters:
+ * 1. Button - Your React component
+ * 2. Figma URL - Points to your specific component in Figma
+ * 3. Configuration object - Defines the prop mappings
+ */
+figma.connect(
+  Button,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=20456-152342",
+  {
+    /**
+     * PROPS MAPPING
+     * 
+     * This section maps Figma properties to React props.
+     * 
+     * Format options:
+     * - figma.enum("PropertyName", { ... }) - for variant/dropdown properties
+     * - figma.boolean("PropertyName") - for boolean properties
+     * - figma.string("PropertyName") - for text properties
+     * - figma.children("LayerName") - for nested content/children
+     * - figma.instance("LayerName") - for nested component instances
+     */
+    props: {
+      /**
+       * VARIANT MAPPING
+       * Maps Figma's "variant" property to React's "variant" prop
+       * 
+       * Figma: filled, outlined, text
+       * React: contained, outlined, text
+       * 
+       * Note: "filled" in Figma maps to "contained" in Material-UI
+       */
+      variant: figma.enum("variant", {
+        filled: "contained",
+        outlined: "outlined",
+        text: "text",
+      }),
+
+      /**
+       * SIZE MAPPING
+       * Maps Figma's "size" property to React's "size" prop
+       * 
+       * Figma size names include pixel values (e.g., "xlarge-56px")
+       * React expects just the size name (e.g., "xlarge")
+       */
+      size: figma.enum("size", {
+        "xlarge-56px": "xlarge",
+        "large-48px": "large",
+        "medium-40px": "medium",
+        "small-32px": "small",
+        "xsmall-24px": "xsmall",
+      }),
+
+      /**
+       * COLOR MAPPING
+       * Maps Figma's "color" property to React's "color" prop
+       * 
+       * Note: "base" is a custom color in the Carrier DPX theme palette
+       * It's an extension of the standard Material-UI colors and provides
+       * the foundation colors for the design system
+       */
+      color: figma.enum("color", {
+        base: "base",
+        primary: "primary",
+        secondary: "secondary",
+        error: "error",
+        warning: "warning",
+        success: "success",
+        info: "info",
+      }),
+
+      /**
+       * DISABLED STATE
+       * Maps Figma's "disabled" boolean property to React's "disabled" prop
+       */
+      disabled: figma.boolean("disabled"),
+
+      /**
+       * BUTTON TEXT/CHILDREN
+       * Maps the text content from the "Button Label" layer
+       * Uses figma.children() to capture nested text content
+       */
+      children: figma.children("Button Label"),
+
+      /**
+       * START ICON
+       * Maps Figma's "startIcon" layer (when visible) to React's startIcon prop
+       * 
+       * figma.instance() connects to nested component instances in Figma
+       * The "startIcon" boolean property controls visibility in Figma
+       */
+      startIcon: figma.instance("startIcon"),
+
+      /**
+       * END ICON
+       * Maps Figma's "endIcon" layer (when visible) to React's endIcon prop
+       */
+      endIcon: figma.instance("endIcon"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * 
+     * This defines how the component should appear in generated code.
+     * The template uses the props mapped above.
+     * 
+     * When Figma Make generates code, it will substitute the actual
+     * values based on the component instance properties.
+     * 
+     * Note: We're ignoring the "state" and "label" properties because:
+     * - "state" (enabled/hover/focus) is a visual state in Figma, not a prop
+     * - "label" is just a boolean to show/hide the text layer
+     */
+    example: ({ variant, color, size, disabled, startIcon, endIcon, children }) => (
+      <Button
+        variant={variant}
+        color={color}
+        size={size}
+        disabled={disabled}
+        startIcon={startIcon}
+        endIcon={endIcon}
+      >
+        {children}
+      </Button>
+    ),
+  }
+);

package/src/components/Button/Button.tsx

@@ -0,0 +1,104 @@
+import { ElementType, forwardRef, Ref } from "react";
+
+import MuiButton, { ButtonProps as MuiButtonProps } from "@mui/material/Button";
+import { TouchRippleActions } from "@mui/material/ButtonBase/TouchRipple";
+import { CSSObject, Theme } from "@mui/material/styles";
+
+import { getSxStyles } from "../utils/styles";
+import { styleTokens } from "../theme/constants/styleTokens";
+
+declare module "@mui/material/Button" {
+  interface ButtonPropsSizeOverrides {
+    xlarge: true;
+    xsmall: true;
+  }
+}
+
+export interface ButtonProps extends MuiButtonProps {
+  /**
+   * A ref that points to the TouchRipple element.
+   */
+  touchRippleRef?: Ref<TouchRippleActions>;
+  /**
+   * The component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: ElementType;
+  /**
+   * The border radius of the button.
+   * @default "rounded"
+   */
+  shape?: "rounded" | "circular";
+}
+
+const getHoverOverrides = (theme: Theme): CSSObject => ({
+  "&.MuiButton-containedPrimary:hover": {
+    backgroundColor: theme.palette.primary?.containedHoverBackground,
+  },
+  "&.MuiButton-containedSecondary:hover": {
+    backgroundColor: theme.palette.secondary?.containedHoverBackground,
+  },
+  "&.MuiButton-containedError:hover": {
+    backgroundColor: theme.palette.error?.containedHoverBackground,
+  },
+  "&.MuiButton-containedWarning:hover": {
+    backgroundColor: theme.palette.warning?.containedHoverBackground,
+  },
+  "&.MuiButton-containedSuccess:hover": {
+    backgroundColor: theme.palette.success?.containedHoverBackground,
+  },
+  "&.MuiButton-containedInfo:hover": {
+    backgroundColor: theme.palette.info?.containedHoverBackground,
+  },
+});
+
+/** The Button component allows users to take action which is communicated through a text label and optional icons.
+ *
+ * // Default import
+ * import Button from '@carrier-io/air-react/Button'
+ *
+ * // Named import
+ * import { Button } from '@carrier-io/air-react'
+ */
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      color = "primary",
+      size,
+      variant = "contained",
+      disableElevation = true,
+      shape = "rounded",
+      sx,
+      ...rest
+    },
+    ref
+  ) => {
+    return (
+      <MuiButton
+        ref={ref}
+        color={color}
+        size={size}
+        variant={variant}
+        disableElevation={disableElevation}
+        sx={(theme) =>
+          ({
+            borderRadius:
+              shape === "rounded"
+                ? styleTokens.borderRadius.large
+                : styleTokens.borderRadius.circular,
+            ...getHoverOverrides(theme),
+            ...getSxStyles(theme, sx),
+          } as CSSObject)
+        }
+        style={{
+          textTransform: "unset",
+          border: variant === "text" ? "none" : "",
+        }}
+        {...rest}
+      />
+    );
+  }
+);
+
+Button.displayName = "Button";
+
+export default Button;

package/src/components/Button/index.ts

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

package/src/components/theme/constants/styleTokens.ts

@@ -0,0 +1,6 @@
+export const styleTokens = {
+  borderRadius: {
+    large: "8px",
+    circular: "50%",
+  },
+};

package/src/components/utils/styles.ts

@@ -0,0 +1,8 @@
+import { SxProps, Theme } from "@mui/material/styles";
+
+export const getSxStyles = (theme: Theme, sx?: SxProps<Theme>) => {
+  if (typeof sx === "function") {
+    return sx(theme);
+  }
+  return sx || {};
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default as Button } from "./components/Button";
+export type { ButtonProps } from "./components/Button";