@vention/machine-ui 3.27.0

package/src/documentation/introduction.mdx

@@ -0,0 +1,96 @@
+import { Meta } from "@storybook/blocks"
+
+<Meta title="Guides/Introduction" />
+
+# Machine UI
+
+## 🎨 What is Machine UI?
+
+Machine UI is Vention's design system aiming to unify the design of UI components across the Vention platform.
+
+This storybook contains the documentation for the source code of the Machine UI library, which is a collection of reusable components and styles built in Typescript and React.
+
+This library aims to bridge the gap between development and design by providing a single source of truth for UI components and styles.
+
+## 🏅 Goals of this project
+
+Machine UI aims to achieve the following goals:
+
+- **Consistency**: Ensure a consistent look and feel across the Vention platform.
+- **Efficiency**: Speed up the development process by providing reusable components and styles.
+- **Scalability**: Scale the design system as the Vention platform grows.
+- **Collaboration**: Foster collaboration between designers and developers by providing a shared language and toolset.
+
+This library is a make-what-you-need type of project, all developers in Vention are welcome to contribute (please refer to our [dev setup page](/docs/guides-getting-started--docs) to learn more about how to contribute to this project).
+
+Our product team has made a commitment to build designs using Machine UI, so whenever there are components in a design that are not yet available in the library, feel free to create them and submit a pull request.
+
+There is NO pressure for full-time commitment to building every Machine UI component.
+
+## 📁 Design Resources
+
+All components created in this library are based on the [Machine UI Figma 🖌️](https://www.figma.com/file/oXDceBmiSGck2KEbM6DEbf/%E2%9D%96-Machine-UI---Beta?type=design&node-id=1289-16&mode=design&t=g0UllUPAhLpuE6KU-0)
+
+More information about the colour selection and naming convention can be found here: [Machine UI Colour Palette 🎨](https://www.figma.com/file/fMslqDAxDQP3WhUSsc74Kf/2024-Colour-Palette-Kick-Off?type=design&node-id=283-3878&mode=design&t=pYNWW5cm23q4izpD-0)
+
+## 👬 Contributors
+
+Machine UI is a collaboration between Vention's software engineering and product design team. This joint effort is essential to ensure that the design system meets the needs of both designers and developers.
+
+If you have any questions or suggestions about the design or development of Machine UI, please reach out to the following people.
+
+The leaders of the Machine UI React Component library are:
+
+- [Yann](https://ventionco.slack.com/team/U017LR9TWV9) (Project Lead)
+- [Jonathan](https://ventionco.slack.com/team/U06LZNY8G0N) (Sponsor from Web and Ecommerce)
+
+The design team responsible of creating Machine UI is composed of:
+
+- [Pascal](https://ventionco.slack.com/team/U04HWTUS525) (Product Designer)
+- [Javed](https://ventionco.slack.com/team/U05NC4ER78X) (Senior Product Designer)
+
+## 📋 Versioning and Breaking Changes
+
+Starting with version 1.0.0, Machine UI follows strict semantic versioning practices to ensure predictable updates for consuming teams:
+
+### Version Types
+
+- **🚨 Major versions** (e.g., 1.x.x → 2.x.x): Reserved for breaking changes to component contracts, APIs, or behavior
+- **✨ Minor versions** (e.g., 1.1.x → 1.2.x): New features while maintaining backward compatibility
+- **🐛 Patch versions** (e.g., 1.1.1 → 1.1.2): Bug fixes and internal improvements
+
+### Breaking Change Policy
+
+Any breaking change, regardless of size, will trigger a major version bump. This includes:
+
+#### 🔧 **Component API Changes**
+
+- **Renaming props**: `labelText` → `children` in VentionButton
+- **Removing props**: Removing deprecated `size="xx-large"` option from VentionButton
+- **Changing prop types**: `variant: "filled-brand" | "filled"` → `variant: "primary" | "secondary"` (breaking existing usage)
+- **Changing required props**: Making VentionButton's `onClick` prop required instead of optional
+
+#### ⚡ **Behavioral Changes That Affect Functionality**
+
+- **Event handling**: Button now prevents default browser behavior differently
+
+#### 🎨 **Visual Breaking Changes (Design Token)**
+
+- **Spacing token changes**: `spacing[4]` changing from `16px` to `20px` (affects layout calculations across components)
+- **Typography token changes**: `uiText14Medium.fontSize` changing from `14` to `16` (affects button labels, form inputs, and UI text rendering)
+
+#### 📝 **TypeScript Interface Changes**
+
+- **Exported type modifications**: Removing `VentionButtonProps["labelText"]` from the public interface
+- **Size type changes**: `Sizes` type changing from `"small" | "medium" | "large"` to `"sm" | "md" | "lg"`
+
+#### ✅ **Non-Breaking Changes** (Minor/Patch versions)
+
+- **New optional props or features**
+- **Bug fixes that restore intended behavior**
+- **Performance improvements without API changes**
+- **New design tokens without changing existing ones**
+- **Internal implementation changes that don't affect public API**
+- **Adding CSS classes or data attributes for styling hooks**
+
+This strict policy ensures that teams can safely upgrade patch and minor versions without fear of unexpected breaking changes, while major version upgrades signal the need for careful testing and potential code updates.

package/src/global-styles.css

@@ -0,0 +1,9 @@
+/* Prevent padding and border from affecting element width. (https://github.com/mozdevs/cssremedy/issues/4) */
+
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/*
+ * Normally, we would add a global css baseline style override in the theme (see MuiCssBaseline).
+ * However, this requires to always add the <CssBaseline /> tag under the <ThemeProvider> tag.
+ * We apply the styling thru the index import (regular MachineUI package consumer import).
+ * The global-styles css is also imported globally in the storybook in preview.tsx.
+ */
+import "./global-styles.css"
+
+// Components
+export * from "./lib/components/vention-alert/vention-alert"
+export * from "./lib/components/vention-badge/vention-badge"
+export * from "./lib/components/vention-button/vention-button"
+export * from "./lib/components/vention-button/vention-icon-button/vention-icon-button"
+export * from "./lib/components/vention-button/vention-dropdown-button/vention-dropdown-button"
+export * from "./lib/components/vention-callout/vention-callout"
+export * from "./lib/components/vention-counter/vention-counter"
+export * from "./lib/components/vention-link/vention-link"
+export * from "./lib/components/vention-modal/vention-modal"
+export * from "./lib/components/vention-modal-base/vention-modal-base"
+export * from "./lib/components/vention-progress-bar/vention-progress-bar"
+export * from "./lib/components/vention-spinner/vention-spinner"
+export * from "./lib/components/vention-steps/vention-steps"
+export * from "./lib/components/vention-status-dot/vention-status-dot"
+export * from "./lib/components/vention-text-input/vention-text-input"
+export * from "./lib/components/vention-radio/vention-radio"
+export * from "./lib/components/vention-radio/vention-radio-tile/vention-radio-tile"
+export * from "./lib/components/vention-select/vention-select"
+export * from "./lib/components/vention-stepper/vention-stepper"
+export * from "./lib/components/vention-tabs/vention-tabs"
+export * from "./lib/components/vention-draggable/vention-draggable"
+export * from "./lib/components/vention-slider/vention-slider"
+export * from "./lib/components/vention-switch/vention-switch"
+export * from "./lib/components/vention-popover/vention-popover"
+export * from "./lib/components/vention-menu/vention-menu"
+export * from "./lib/components/vention-tree-item/vention-tree-item"
+export * from "./lib/components/vention-drawer/vention-drawer"
+export * from "./lib/components/vention-status-indicator/vention-status-indicator"
+export * from "./lib/components/vention-modal-banner/vention-modal-banner"
+export * from "./lib/components/vention-banner/vention-banner"
+export * from "./lib/components/vention-sidebar-item/vention-sidebar-item"
+export * from "./lib/components/vention-icon/vention-icon"
+export * from "./lib/components/vention-combobox/vention-combobox"
+export * from "./lib/components/vention-tooltip/vention-tooltip"
+export * from "./lib/components/vention-checkbox/vention-checkbox"
+export * from "./lib/components/vention-uploadfile/vention-uploadfile"
+export * from "./lib/components/vention-dropzone/vention-dropzone"
+
+// Theme
+export * from "./lib/theme/machine-ui-theme"
+export * from "./lib/theme/colors"
+
+// Interfaces
+export { type VentionAlertProps } from "./lib/components/vention-alert/vention-alert-utils"
+export { type VentionButtonProps } from "./lib/components/vention-button/button-utils"

package/src/lib/components/shared/styles/input-styles.ts

@@ -0,0 +1,123 @@
+import { Theme, TypographyOwnProps } from "@mui/material"
+import { AllInputStates } from "../types/input-types"
+import { Sizes } from "../../../theme/machine-ui-theme"
+
+export const getBorderColorFromState = (state: AllInputStates, theme: Theme) => {
+  switch (state) {
+    case "error":
+      return theme.palette.border.subtleDestructive
+    case "warning":
+      return theme.palette.border.subtleWarning
+    case "success":
+      return theme.palette.border.subtleSuccess
+    case "focused":
+      return theme.palette.border.blueSubtle
+    case "hover":
+    case "default":
+    case "disabled":
+    default:
+      return theme.palette.border.main
+  }
+}
+
+export const getBackgroundColorFromState = (state: AllInputStates, theme: Theme) => {
+  switch (state) {
+    case "error":
+      return theme.palette.background.subtleDestructive
+    case "warning":
+      return theme.palette.background.subtleWarning
+    case "success":
+      return theme.palette.background.subtleSuccess
+    case "disabled":
+      return theme.palette.background.inputDisabled
+    case "default":
+    case "focused":
+    case "hover":
+    default:
+      return theme.palette.background.inputOutlined
+  }
+}
+
+export const getInputHeight = (size: Sizes, theme: Theme) => {
+  switch (size) {
+    case "x-small":
+      return theme.spacing(4)
+    case "small":
+      return theme.spacing(5)
+    case "medium":
+      return theme.spacing(7)
+    case "large":
+      return theme.spacing(8)
+    case "x-large":
+      return theme.spacing(9)
+    case "xx-large":
+      return theme.spacing(11)
+  }
+}
+
+export const getInputPaddingStyles = (size: Sizes, theme: Theme) => {
+  switch (size) {
+    case "x-small":
+    case "small":
+      return {
+        paddingLeft: theme.spacing(2),
+        paddingRight: theme.spacing(2),
+      }
+    case "medium":
+      return {
+        paddingLeft: theme.spacing(3),
+        paddingRight: theme.spacing(3),
+      }
+    case "large":
+    case "x-large":
+    case "xx-large":
+      return {
+        paddingLeft: theme.spacing(4),
+        paddingRight: theme.spacing(4),
+      }
+  }
+}
+
+export const typographyNameFromSizeMap: Record<
+  "x-small" | "small" | "medium" | "large" | "x-large" | "xx-large",
+  Record<"label" | "text" | "helperText", TypographyOwnProps["variant"]>
+> = {
+  "x-small": {
+    label: "uiText12SemiBold",
+    text: "uiText12Regular",
+    helperText: "uiText12Regular",
+  },
+  small: {
+    label: "uiText12SemiBold",
+    text: "uiText12Regular",
+    helperText: "uiText12Regular",
+  },
+  medium: {
+    label: "uiText14SemiBold",
+    text: "uiText14Regular",
+    helperText: "uiText12Regular",
+  },
+  large: {
+    label: "uiText14SemiBold",
+    text: "uiText14Regular",
+    helperText: "uiText12Regular",
+  },
+  "x-large": {
+    label: "heading18SemiBold",
+    text: "paragraph18Regular",
+    helperText: "uiText12Regular",
+  },
+  "xx-large": {
+    label: "hmiText20SemiBold",
+    text: "hmiText22Regular",
+    helperText: "paragraph18Regular",
+  },
+}
+
+export const getTypography = (size: Sizes, theme: Theme) => {
+  return {
+    label: theme.typography[typographyNameFromSizeMap[size].label],
+    text: theme.typography[typographyNameFromSizeMap[size].text],
+    helperText: theme.typography[typographyNameFromSizeMap[size].helperText],
+  }
+}

package/src/lib/components/shared/types/input-types.ts

@@ -0,0 +1,9 @@
+/**
+ * All user configurable input states.
+ */
+export type InputStates = "default" | "error" | "warning" | "success" | "disabled"
+
+/**
+ * These are additional possible input states based on user interaction
+ */
+export type AllInputStates = InputStates | "hover" | "focused"

package/src/lib/components/vention-alert/vention-alert-controls.tsx

@@ -0,0 +1,57 @@
+import { Stack } from "@mui/material"
+import { tss } from "tss-react/mui"
+
+import { VentionButton } from "../vention-button/vention-button"
+import { VentionLink } from "../vention-link/vention-link"
+import { getGapSpaceForContent, VentionAlertProps } from "./vention-alert-utils"
+
+export interface VentionAlertControlProps
+  extends Pick<
+    VentionAlertProps,
+    "size" | "primaryButtonText" | "onPrimaryButtonClick" | "secondaryButtonText" | "onSecondaryButtonClick" | "linkText" | "onLinkClick"
+  > {
+  display: boolean
+}
+
+export const VentionAlertControls = (alertControlProps: VentionAlertControlProps) => {
+  const { classes } = useStyles(alertControlProps)
+
+  return alertControlProps.display ? (
+    <Stack className={classes.alertControls}>
+      {alertControlProps.primaryButtonText ? (
+        <VentionButton
+          onClick={alertControlProps.onPrimaryButtonClick}
+          labelText={alertControlProps.primaryButtonText}
+          size={alertControlProps.size}
+          variant="shaded"
+          data-testid="alertPrimaryBtn"
+        />
+      ) : null}
+      {alertControlProps.secondaryButtonText ? (
+        <VentionButton
+          onClick={alertControlProps.onSecondaryButtonClick}
+          labelText={alertControlProps.secondaryButtonText}
+          size={alertControlProps.size}
+          variant="text-only"
+          data-testid="alertSecondaryBtn"
+        />
+      ) : null}
+      {alertControlProps.linkText ? (
+        <VentionLink
+          onClick={alertControlProps.onLinkClick}
+          labelText={alertControlProps.linkText}
+          size={alertControlProps.size === "small" ? "medium" : "large"}
+        />
+      ) : null}
+    </Stack>
+  ) : null
+}
+
+const useStyles = tss.withParams<Pick<VentionAlertProps, "isSingleLine" | "size">>().create(({ isSingleLine, size }) => {
+  return {
+    alertControls: {
+      flexDirection: isSingleLine ? "row-reverse" : "row",
+      gap: getGapSpaceForContent(isSingleLine, size),
+    },
+  }
+})

package/src/lib/components/vention-alert/vention-alert-utils.ts

@@ -0,0 +1,27 @@
+import { ReactElement } from "react"
+import { Sizes, StrictExtract } from "../../theme/machine-ui-theme"
+
+export interface VentionAlertProps {
+  severity: "info" | "warn" | "error" | "success"
+  linkText?: string
+  primaryButtonText?: string
+  secondaryButtonText?: string
+  onLinkClick?: () => void
+  onPrimaryButtonClick?: () => void
+  onSecondaryButtonClick?: () => void
+  onCloseButtonClick?: () => void
+  size?: StrictExtract<Sizes, "small" | "medium" | "large" | "xx-large">
+  descriptionText?: ReactElement | string
+  leftIcon?: ReactElement | undefined
+  rightIcon?: ReactElement | undefined
+  title?: ReactElement | string
+  isCloseable?: boolean
+  isSingleLine?: boolean
+  isFullWidth?: boolean
+}
+
+export function getGapSpaceForContent(isSingleLine: boolean, size: VentionAlertProps["size"]) {
+  if (!isSingleLine) return "0px"
+
+  return size === "small" ? "8px" : "12px"
+}

package/src/lib/components/vention-alert/vention-alert.stories.tsx

@@ -0,0 +1,137 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { IconHelp, IconShieldFilled } from "@tabler/icons-react"
+import React from "react"
+
+import { VentionAlert } from "./vention-alert"
+
+const meta: Meta<typeof VentionAlert> = {
+  component: VentionAlert,
+  title: "Components/VentionAlert",
+  argTypes: {
+    onLinkClick: { action: "onClick executed!" },
+  },
+}
+export default meta
+type Story = StoryObj<typeof VentionAlert>
+
+export const Default: Story = {
+  args: {
+    size: "medium",
+    descriptionText: "Description placeholder",
+    title: "Alert",
+    severity: "info",
+  },
+}
+
+export const LongTextSingleLine: Story = {
+  args: {
+    size: "medium",
+    descriptionText:
+      "In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this. In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this. In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this",
+    title:
+      "This is a very long title that should wrap. This is a very long title that should wrap. This is a very long title that should wrap",
+    severity: "info",
+  },
+}
+
+export const WithPrimaryAndSecondaryAndLinkButtons: Story = {
+  args: {
+    size: "medium",
+    descriptionText: "In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this",
+    title: "Complete",
+    primaryButtonText: "Primary",
+    secondaryButtonText: "Secondary",
+    linkText: "Link Btn",
+    severity: "success",
+    rightIcon: <IconHelp />,
+  },
+}
+
+export const WithCloseButton: Story = {
+  args: {
+    size: "medium",
+    descriptionText: "Description placeholder",
+    title: "Warning",
+    primaryButtonText: "Primary",
+    secondaryButtonText: "Secondary",
+    isCloseable: true,
+    severity: "warn",
+  },
+}
+
+export const OnSingleLine: Story = {
+  decorators: [
+    Story => (
+      <div style={{ minWidth: "800px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    size: "medium",
+    descriptionText: "Description placeholder",
+    title: "Error",
+    primaryButtonText: "Primary",
+    secondaryButtonText: "Secondary",
+    linkText: "Link",
+    severity: "error",
+    isCloseable: true,
+    isSingleLine: true,
+    rightIcon: <IconHelp />,
+  },
+}
+
+export const LongTextOnSingleLine: Story = {
+  decorators: [
+    Story => (
+      <div style={{ width: "800px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    size: "medium",
+    descriptionText:
+      "In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this. In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this. In a perfect world, content stays brief. Yet, when more words are essential, it unfolds like this",
+    title:
+      "This is a very long title that should wrap. This is a very long title that should wrap. This is a very long title that should wrap",
+    severity: "info",
+    isSingleLine: true,
+    isCloseable: true,
+    isFullWidth: true,
+    rightIcon: <IconHelp />,
+  },
+}
+
+export const WithCustomWidth: Story = {
+  decorators: [
+    Story => (
+      <div style={{ minWidth: "480px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    size: "large",
+    descriptionText: "Description placeholder",
+    title: "Warning",
+    severity: "warn",
+    isSingleLine: true,
+    isCloseable: true,
+  },
+}
+
+export const WithCustomIcons: Story = {
+  args: {
+    size: "large",
+    descriptionText: "Description placeholder",
+    title: "Alert",
+    linkText: "Link",
+    isSingleLine: true,
+    primaryButtonText: "Primary",
+    secondaryButtonText: "Secondary",
+    severity: "error",
+    leftIcon: <IconShieldFilled />,
+    rightIcon: <IconHelp />,
+  },
+}