@ncino/styles 9.2.0-preview.3 → 9.2.0

package/README.md

@@ -0,0 +1,159 @@
+# @ncino/styles
+
+nCino's shared web component styling package implementing the Gator Design System. Provides CSS design tokens, global styles, and a comprehensive Material-UI theme configuration with TypeScript support for custom component props.
+
+## Installation
+
+```bash
+npm install @ncino/styles
+# or
+pnpm add @ncino/styles
+```
+
+## Quick Start
+
+```typescript
+// app/layout.tsx (or _app.tsx)
+import '@ncino/styles/gator';  // Global styles
+import { ThemeProvider } from '@mui/material/styles';
+import { gatorMUITheme } from '@ncino/styles/gator/themes/MUIGatorTheme';
+
+export default function RootLayout({ children }) {
+  return (
+    <ThemeProvider theme={gatorMUITheme}>
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+**That's it!** All MUI components now use the Gator theme, and TypeScript recognizes custom props like `color="ai"` automatically.
+
+## What's Included
+
+- **Design Tokens**: Primitive and semantic CSS custom properties
+- **Global Styles**: CSS utilities, grid system, typography classes
+- **MUI Theme**: Complete Material-UI theme with component overrides
+- **TypeScript Support**: Type augmentations for custom MUI props
+- **Web Fonts**: Self-hosted Open Sans variable font
+
+## Usage
+
+### Using MUI Components
+
+Material-UI components automatically use the Gator theme:
+
+```typescript
+import { Button, TextField, Card, Chip } from '@mui/material';
+
+<Button color="primary">Primary</Button>
+<Button color="ai">AI</Button>           {/* Custom Gator color */}
+<Button color="neutral">Neutral</Button> {/* Custom Gator color */}
+
+<Chip color="ai" label="AI Feature" />   {/* Custom Gator color */}
+```
+
+### Using Design Tokens
+
+Design tokens are available as CSS custom properties:
+
+```css
+.my-component {
+  /* Colors */
+  color: var(--color-text-primary);
+  background-color: var(--color-surface-brand);
+
+  /* Spacing (0-18 scale) */
+  padding: var(--spacing-8);    /* 16px */
+  margin: var(--spacing-10);    /* 24px */
+  gap: var(--spacing-5);        /* 8px */
+
+  /* Typography */
+  font-size: var(--font-size-body-1);
+  font-weight: var(--font-weight-semi-bold);
+
+  /* Other */
+  border-radius: var(--border-radius-medium);
+  box-shadow: var(--shadow-2-card-raised);
+}
+```
+
+### Grid System
+
+```html
+<div class="gator-container">
+  <div class="gator-row">
+    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
+      Column 1
+    </div>
+    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
+      Column 2
+    </div>
+    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
+      Column 3
+    </div>
+  </div>
+</div>
+```
+
+### Individual Token Imports
+
+Import specific token sets if needed:
+
+```typescript
+import '@ncino/styles/gator/tokens/primitive';  // Base colors, font sizes
+import '@ncino/styles/gator/tokens/semantic';   // Contextual tokens
+```
+
+## TypeScript Setup
+
+### How It Works
+
+TypeScript module augmentations are loaded **project-wide** when you import the theme. You only need to import it once (typically in your app root), and all files get the custom prop types automatically.
+
+### Troubleshooting
+
+#### Custom props showing TypeScript errors
+
+**Most Common Cause:** Dependency version mismatch in monorepos.
+
+TypeScript creates separate `@mui/material` instances for different React/@types/react versions. Augmentations only apply when versions match.
+
+**Solution:** Ensure consistent versions:
+
+```json
+{
+  "dependencies": {
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
+  }
+}
+```
+
+After updating:
+1. Run `pnpm install`
+2. Restart TypeScript server (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server")
+3. Clear caches: `rm -rf .next node_modules/.cache`
+
+#### Still not working?
+
+- **Verify theme import:** Make sure you're importing `gatorMUITheme` somewhere in your app
+- **Check installation:** Verify `node_modules/@ncino/styles` exists
+- **IDE restart:** Sometimes a full IDE restart is needed
+
+## Exports
+
+Available import paths:
+
+```typescript
+import '@ncino/styles';                                    // Load augmentations
+import { gatorMUITheme } from '@ncino/styles';            // Theme (default export)
+import '@ncino/styles/gator';                              // Global styles CSS
+import { gatorMUITheme } from '@ncino/styles/gator/themes/MUIGatorTheme';
+import '@ncino/styles/gator/tokens/primitive';            // Primitive tokens CSS
+import '@ncino/styles/gator/tokens/semantic';             // Semantic tokens CSS
+```

package/dist/gator/themes/MUIGatorTheme.js

@@ -0,0 +1,183 @@
+import * as a from "./components/accordion.js";
+import * as r from "./components/alert.js";
+import * as s from "./components/autocomplete.js";
+import * as l from "./components/avatar.js";
+import * as m from "./components/badge.js";
+import * as g from "./components/button.js";
+import * as h from "./components/card.js";
+import * as c from "./components/checkbox.js";
+import * as f from "./components/chip.js";
+import * as d from "./components/dialog.js";
+import * as p from "./components/fab.js";
+import * as y from "./components/form-control.js";
+import * as u from "./components/radio.js";
+import * as _ from "./components/select.js";
+import * as b from "./components/switch.js";
+import * as v from "./components/table.js";
+import * as F from "./components/tabs.js";
+import * as W from "./components/text-field.js";
+import { createTheme as S } from "@mui/material/styles";
+/* empty css                              */
+/* empty css                             */
+import { gatorShadows as z, gatorBorderRadius as O, gatorSpacing as x, gatorTypography as t, gatorColorValues as e } from "./utils/themeConfig.js";
+const H = /* @__PURE__ */ Object.assign({ "./components/accordion.ts": a, "./components/alert.ts": r, "./components/autocomplete.ts": s, "./components/avatar.ts": l, "./components/badge.ts": m, "./components/button.ts": g, "./components/card.ts": h, "./components/checkbox.ts": c, "./components/chip.ts": f, "./components/dialog.ts": d, "./components/fab.ts": p, "./components/form-control.ts": y, "./components/radio.ts": u, "./components/select.ts": _, "./components/switch.ts": b, "./components/table.ts": v, "./components/tabs.ts": F, "./components/text-field.ts": W }), B = Object.values(H).reduce((n, i) => (Object.keys(i).forEach((o) => {
+  o.startsWith("MUIGator") && o.includes("Override") && Object.assign(n, i[o]);
+}), n), {}), k = {
+  palette: {
+    mode: "light",
+    primary: e.brand,
+    secondary: e.secondary,
+    neutral: {
+      main: e.neutral[70],
+      light: e.neutral[40],
+      dark: e.neutral[80],
+      contrastText: "#FFFFFF"
+    },
+    error: e.error,
+    success: e.success,
+    warning: e.warning,
+    info: e.info,
+    ai: e.ai,
+    text: e.text,
+    background: e.background,
+    divider: e.divider,
+    action: {
+      active: e.neutral[70],
+      hover: e.neutral[10],
+      selected: e.neutral[20],
+      disabled: e.neutral[40],
+      disabledBackground: e.neutral[30],
+      focus: e.neutral[20],
+      hoverOpacity: 0.04,
+      selectedOpacity: 0.08,
+      disabledOpacity: 0.38,
+      focusOpacity: 0.12,
+      activatedOpacity: 0.12
+    }
+  },
+  typography: {
+    fontFamily: t.fontFamily.body,
+    fontWeightLight: t.fontWeight.regular,
+    fontWeightRegular: t.fontWeight.regular,
+    fontWeightMedium: t.fontWeight.medium,
+    fontWeightBold: t.fontWeight.semiBold,
+    // Display styles (using CSS variables for dynamic sizing)
+    h1: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-display-1)",
+      lineHeight: "var(--line-height-display-1)",
+      fontWeight: t.fontWeight.bold,
+      letterSpacing: "var(--letter-spacing-narrow)"
+    },
+    h2: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-display-2)",
+      lineHeight: "var(--line-height-display-2)",
+      fontWeight: t.fontWeight.bold,
+      letterSpacing: "var(--letter-spacing-narrow)"
+    },
+    // Heading styles
+    h3: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-heading-1)",
+      lineHeight: "var(--line-height-heading-1)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    h4: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-heading-2)",
+      lineHeight: "var(--line-height-heading-2)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    h5: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-heading-3)",
+      lineHeight: "var(--line-height-heading-3)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    h6: {
+      fontFamily: t.fontFamily.headings,
+      fontSize: "var(--font-size-heading-4)",
+      lineHeight: "var(--line-height-heading-4)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    // Subtitle styles
+    subtitle1: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-subtitle-1)",
+      lineHeight: "var(--line-height-subtitle-1)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    subtitle2: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-subtitle-2)",
+      lineHeight: "var(--line-height-subtitle-2)",
+      fontWeight: t.fontWeight.semiBold,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    // Body styles
+    body1: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-body-1)",
+      lineHeight: "var(--line-height-body-1)",
+      fontWeight: t.fontWeight.regular,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    body2: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-body-2)",
+      lineHeight: "var(--line-height-body-2)",
+      fontWeight: t.fontWeight.regular,
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    // Button text
+    button: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-body-2)",
+      lineHeight: "var(--line-height-body-2)",
+      fontWeight: t.fontWeight.semiBold,
+      textTransform: "none",
+      letterSpacing: "var(--letter-spacing-default)"
+    },
+    // Caption and overline
+    caption: {
+      fontFamily: t.fontFamily.body,
+      fontSize: "var(--font-size-body-3)",
+      lineHeight: "var(--line-height-body-3)",
+      fontWeight: t.fontWeight.regular,
+      letterSpacing: "var(--letter-spacing-default)"
+    }
+  },
+  spacing: x,
+  shape: {
+    borderRadius: O.xsmall
+  },
+  shadows: z,
+  // Component-specific default props
+  components: {
+    // Component overrides
+    ...B,
+    // Additional component overrides not in separate files
+    MuiLink: {
+      styleOverrides: {
+        root: {
+          color: "var(--color-text-brand)",
+          textDecorationColor: "var(--color-underline-brand)",
+          "&:hover": {
+            color: "var(--color-text-brand)",
+            textDecorationColor: "var(--color-underline-brand-secondary)"
+          }
+        }
+      }
+    }
+  }
+}, C = S(k);
+export {
+  C as default,
+  C as gatorMUITheme
+};

package/dist/gator/themes/components/accordion.js

@@ -0,0 +1,68 @@
+const r = {
+  MuiAccordion: {
+    defaultProps: {
+      disableGutters: !0,
+      elevation: 0
+    },
+    styleOverrides: {
+      root: {
+        borderRadius: "var(--border-radius-small)",
+        "&:not(:last-child)": {
+          borderBottom: "1px solid var(--color-border-tertiary)"
+        },
+        "&:before": {
+          display: "none"
+        },
+        "&.Mui-expanded": {
+          "&:before": {
+            opacity: 1
+          }
+        }
+      }
+    }
+  },
+  MuiAccordionSummary: {
+    styleOverrides: {
+      root: {
+        padding: "16px",
+        minHeight: "56px",
+        transition: "background-color 0.2s ease",
+        "&:hover": {
+          backgroundColor: "var(--color-surface-hover)"
+        },
+        "&.Mui-focusVisible": {
+          outline: "2px solid var(--color-border-focus)",
+          outlineOffset: "-1px"
+        },
+        "&.Mui-expanded": {
+          minHeight: "56px"
+        }
+      },
+      content: {
+        margin: "0",
+        "&.Mui-expanded": {
+          margin: "0"
+        }
+      },
+      expandIconWrapper: {
+        color: "var(--color-icon-primary)",
+        "&.Mui-expanded": {
+          transform: "rotate(180deg)"
+        }
+      }
+    }
+  },
+  MuiAccordionDetails: {
+    styleOverrides: {
+      root: {
+        padding: "16px 16px 24px 16px",
+        fontSize: "var(--font-size-body-2)",
+        lineHeight: "var(--line-height-body-2)",
+        color: "var(--color-text-primary)"
+      }
+    }
+  }
+};
+export {
+  r as MUIGatorAccordionOverrides
+};

package/dist/gator/themes/components/alert.js

@@ -0,0 +1,55 @@
+import { gatorTypography as r } from "../utils/themeConfig.js";
+const a = {
+  MuiAlert: {
+    styleOverrides: {
+      root: {
+        borderRadius: "var(--border-radius-x-large)",
+        padding: "1.5rem",
+        fontSize: "var(--font-size-body-1)",
+        border: "1px solid var(--color-border-primary)"
+      },
+      standardSuccess: {
+        backgroundColor: "var(--color-surface-success)",
+        color: "var(--color-text-primary)",
+        borderColor: "var(--color-border-success)",
+        "& .MuiAlert-icon": {
+          color: "var(--color-icon-success)"
+        }
+      },
+      standardError: {
+        backgroundColor: "var(--color-surface-error)",
+        color: "var(--color-text-primary)",
+        borderColor: "var(--color-border-error)",
+        "& .MuiAlert-icon": {
+          color: "var(--color-icon-error)"
+        }
+      },
+      standardWarning: {
+        backgroundColor: "var(--color-surface-warning)",
+        color: "var(--color-text-primary)",
+        borderColor: "var(--color-border-warning)",
+        "& .MuiAlert-icon": {
+          color: "var(--color-icon-warning)"
+        }
+      },
+      standardInfo: {
+        backgroundColor: "var(--color-surface-secondary)",
+        color: "var(--color-text-primary)",
+        borderColor: "var(--color-border-secondary)",
+        "& .MuiAlert-icon": {
+          color: "var(--color-icon-primary)"
+        }
+      }
+    }
+  },
+  MuiAlertTitle: {
+    styleOverrides: {
+      root: {
+        fontWeight: r.fontWeight.bold
+      }
+    }
+  }
+};
+export {
+  a as MUIGatorAlertOverrides
+};

package/dist/gator/themes/components/autocomplete.js

@@ -0,0 +1,139 @@
+import { gatorTypography as o } from "../utils/themeConfig.js";
+import r from "@mui/icons-material/ExpandMore";
+import a from "react";
+const t = {
+  MuiAutocomplete: {
+    defaultProps: {
+      componentsProps: {
+        paper: {
+          elevation: 3
+        }
+      },
+      popupIcon: a.createElement(r)
+    },
+    styleOverrides: {
+      root: {
+        // Override the input field styling
+        "& .MuiInputBase-root": {
+          padding: "var(--spacing-7) var(--spacing-8)",
+          minHeight: "48px",
+          fontFamily: o.fontFamily.body,
+          fontSize: "var(--font-size-body-1)",
+          lineHeight: "var(--line-height-body-1)"
+        },
+        "& .MuiAutocomplete-input": {
+          padding: "0 !important"
+        },
+        "& .MuiAutocomplete-endAdornment": {
+          right: "var(--spacing-8)"
+        },
+        "& .MuiAutocomplete-clearIndicator": {
+          visibility: "visible",
+          marginRight: "var(--spacing-3)",
+          color: "var(--color-icon-primary)",
+          "&:hover": {
+            color: "var(--color-icon-secondary)",
+            backgroundColor: "transparent"
+          }
+        },
+        "& .MuiAutocomplete-popupIndicator": {
+          color: "var(--color-icon-primary)",
+          "&:hover": {
+            backgroundColor: "transparent"
+          }
+        },
+        ".MuiCircularProgress-root": {
+          marginRight: "var(--spacing-8)"
+        }
+      },
+      // Dropdown popup/menu styling
+      paper: {
+        marginTop: "var(--spacing-3)",
+        borderRadius: "var(--border-radius-medium)",
+        boxShadow: "var(--shadow-3-dropdown)",
+        backgroundColor: "var(--color-surface-primary)"
+      },
+      // List container
+      listbox: {
+        padding: "var(--spacing-5) 0",
+        maxHeight: "300px",
+        fontFamily: o.fontFamily.body,
+        fontSize: "var(--font-size-body-1)",
+        lineHeight: "var(--line-height-body-1)",
+        "& .MuiAutocomplete-option": {
+          padding: " var(--spacing-5) var(--spacing-8) var(--spacing-5) var(--spacing-12)",
+          minHeight: "40px",
+          color: "var(--color-text-primary)",
+          "&:hover": {
+            backgroundColor: "var(--color-surface-hover)"
+          },
+          "&.Mui-focused": {
+            backgroundColor: "var(--color-surface-hover)"
+          },
+          '&[aria-selected="true"]': {
+            backgroundColor: "var(--color-surface-brand)",
+            color: "var(--color-text-primary)",
+            fontWeight: o.fontWeight.bold,
+            paddingLeft: "var(--spacing-8)",
+            "::before": {
+              content: '"✓"',
+              display: "inline-block",
+              marginRight: "var(--spacing-6)",
+              color: "var(--color-icon-on-brand)",
+              fontWeight: o.fontWeight.regular
+            },
+            "&:hover": {
+              backgroundColor: "var(--color-surface-brand-secondary)"
+            },
+            "&.Mui-focused": {
+              backgroundColor: "var(--color-surface-brand-secondary)"
+            }
+          },
+          '&[aria-disabled="true"]': {
+            opacity: 1,
+            color: "var(--color-text-disabled)",
+            pointerEvents: "none"
+          }
+        }
+      },
+      // No options message
+      noOptions: {
+        padding: "var(--spacing-5) var(--spacing-8)",
+        color: "var(--color-text-secondary)",
+        fontFamily: o.fontFamily.body,
+        fontSize: "var(--font-size-body-1)",
+        lineHeight: "var(--line-height-body-1)"
+      },
+      // Loading text
+      loading: {
+        padding: "var(--spacing-5) var(--spacing-8)",
+        color: "var(--color-text-secondary)",
+        fontFamily: o.fontFamily.body,
+        fontSize: "var(--font-size-body-1)",
+        lineHeight: "var(--line-height-body-1)"
+      },
+      // Grouping
+      groupLabel: {
+        padding: "var(--spacing-5) var(--spacing-8)",
+        fontFamily: o.fontFamily.body,
+        fontSize: "var(--font-size-body-2)",
+        lineHeight: "var(--line-height-body-2)",
+        fontWeight: o.fontWeight.semiBold,
+        color: "var(--color-text-secondary)",
+        top: 0,
+        zIndex: 1
+      },
+      groupUl: {
+        padding: 0
+      },
+      // Chips for multiselect
+      tag: {
+        margin: "-5px 4px",
+        fontSize: "var(--font-size-body-3)"
+      }
+    }
+  }
+};
+export {
+  t as MUIGatorAutocompleteOverrides
+};

package/dist/gator/themes/components/avatar.js

@@ -0,0 +1,49 @@
+import { gatorTypography as r } from "../utils/themeConfig.js";
+const a = {
+  MuiAvatar: {
+    styleOverrides: {
+      root: {
+        fontFamily: r.fontFamily.body,
+        fontWeight: r.fontWeight.bold,
+        fontSize: "var(--font-size-body-1)"
+      },
+      colorDefault: {
+        backgroundColor: "var(--color-surface-brand-tertiary)",
+        color: "var(--color-text-brand)"
+      }
+    },
+    variants: [
+      {
+        props: { variant: "circular" },
+        style: {
+          borderRadius: "var(--border-radius-circle)"
+        }
+      },
+      {
+        props: { variant: "rounded" },
+        style: {
+          borderRadius: "var(--border-radius-medium)"
+        }
+      },
+      {
+        props: { variant: "square" },
+        style: {
+          borderRadius: "var(--border-radius-no-radius)"
+        }
+      }
+    ]
+  },
+  MuiAvatarGroup: {
+    styleOverrides: {
+      avatar: {
+        border: "2px solid var(--color-background-primary)",
+        fontSize: "var(--font-size-body-1)",
+        width: 40,
+        height: 40
+      }
+    }
+  }
+};
+export {
+  a as MUIGatorAvatarOverrides
+};