@vention/machine-ui 3.27.0

package/src/documentation/design-system/palette.mdx

@@ -0,0 +1,159 @@
+import { Meta } from "@storybook/blocks"
+import { Typography } from "@mui/material"
+import { machineUiTheme } from "../../lib/theme/machine-ui-theme"
+
+<Meta title="Guides/Design System/Palette" />
+
+# Palette
+
+Here are the keys used in the Machine UI theme palette
+
+## Text Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.text).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Button Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.button).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Background Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.background).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Border Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.border).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Icon Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.icon).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Button Text Colors
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Code</th>
+      <th>Color</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(machineUiTheme.palette.buttonText).map(([key, value]) => (
+      <tr key={key}>
+        <td>{key}</td>
+        <td>
+          <Typography variant="body2" style={{ marginLeft: "8px" }}>
+            {value}
+          </Typography>
+        </td>
+        <td style={{ minWidth: "-webkit-fill-available", backgroundColor: value, height: "24px" }}></td>
+      </tr>
+    ))}
+  </tbody>
+</table>

package/src/documentation/design-system/spacing.mdx

@@ -0,0 +1,61 @@
+import { Meta } from "@storybook/blocks"
+import { machineUiTheme } from "../../lib/theme/machine-ui-theme"
+
+<Meta title="Guides/Design System/Spacing" />
+
+# Spacing
+
+In Machine-UI, we use a consistent spacing scale to ensure that the spacing between elements is consistent across the application.
+
+The Product Design team uses a `4px` spacing system for grids, margins, and padding. This system is based on the 4px grid system used in Figma.
+
+## Spacing Scale
+
+The spacing scale is as follows:
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Value</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Array.from(Array(15).keys()).map(i => (
+      <tr key={i}>
+        <td>{i}</td>
+        <td>{machineUiTheme.spacing(i)}</td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+## Usage
+
+To use the spacing system in your components, you can use the spacing property from the mui `theme`.
+
+```tsx
+import { tss } from "tss-react/mui"
+
+const useStyles = tss.create(({ theme }) => ({
+  root: {
+    display: "flex",
+    margin: theme.spacing(2),
+    padding: theme.spacing(4),
+    gap: theme.spacing(2),
+  },
+}))
+```
+
+In the example above, the `theme.spacing(2)` function returns the value `8px` from the spacing scale. You can use this value to set the margin, padding, or gap in your components.
+
+You can also use the spacing scale directly in your components.
+
+```tsx
+import { Box } from "@mui/material"
+;<Box m={2} p={4}>
+  This is a box with 8px margin and 16px padding
+</Box>
+```
+
+In the example above, the `m` property sets the margin and the `p` property sets the padding. The value `2` corresponds to `8px` in the spacing scale.

package/src/documentation/design-system/typography.mdx

@@ -0,0 +1,63 @@
+import { Source, Meta } from "@storybook/blocks"
+import { Typography } from "@mui/material"
+import { TYPOGRAPHY } from "../../lib/theme/typography"
+
+<Meta title="Guides/Design System/Typography" />
+
+export const typographyText = {
+  heading36Bold: "Heading 36 Bold",
+  heading24SemiBold: "Heading 24 Semi Bold",
+  heading24Medium: "Heading 24 Medium",
+  heading18SemiBold: "Heading 18 Semi Bold",
+  heading16SemiBold: "Heading 16 Semi Bold",
+  paragraph18Medium: "Paragraph 18 Medium",
+  paragraph18Regular: "Paragraph 18 Regular",
+  paragraph16Medium: "Paragraph 16 Medium",
+  paragraph16Regular: "Paragraph 16 Regular",
+  paragraph14Regular: "Paragraph 14 Regular",
+  code14Reg: "Code 14 Regular",
+  code12Reg: "Code 12 Regular",
+  uiText14SemiBold: "UI Text 14 Semi Bold",
+  uiText14Medium: "UI Text 14 Medium",
+  uiText14Regular: "UI Text 14 Regular",
+  uiText12SemiBold: "UI Text 12 Semi Bold",
+  uiText12Medium: "UI Text 12 Medium",
+  uiText12Regular: "UI Text 12 Regular",
+  uiTableNumbers14Reg: "UI Table Numbers 14 Regular",
+  uiTableNumbers12Reg: "UI Table Numbers 12 Regular",
+}
+
+# Typography
+
+The typography of the website is based on the [Inter](https://rsms.me/inter/) and [Roboto Mono](https://fonts.google.com/specimen/Roboto+Mono) font family. The font is loaded from Google Fonts and is used for all text on this website.
+
+Since Machine UI is built on MUI, you can use the Typography component to style text. The Typography component is a wrapper around the HTML `<p>` tag and can be used to style text in various ways.
+
+<table>
+  <thead>
+    <tr>
+      <th>Type</th>
+      <th>Weight</th>
+      <th>Size</th>
+      <th>Code</th>
+    </tr>
+  </thead>
+  <tbody>
+    {Object.entries(TYPOGRAPHY).map(([key, value]) => (
+      <tr>
+        <td>
+          <Typography variant={key} sx={value}>
+            {typographyText[key]}
+          </Typography>
+        </td>
+        <td>{value?.fontWeight ?? "n/a"}</td>
+        <td>{value?.fontSize ?? "n/a"}</td>
+        <td>
+          <Source code={`<Typography variant="${key}">${typographyText[key]}</Typography>`} />
+        </td>
+      </tr>
+    ))}
+  </tbody>
+</table>
+
+**Note:** Material UI theming isn't fully working with Storybook, so the typography might not look exactly as it does on the website.

package/src/documentation/getting-started.mdx

@@ -0,0 +1,154 @@
+import { Meta } from "@storybook/blocks"
+
+<Meta title="Guides/Getting Started" />
+
+# Getting Started
+
+Interested in contributing to Vention's design system React library? You've come to the right place!
+
+<br />
+
+## 🛠️ How to set up Machine UI
+
+Machine UI lives in the [machine-cloud](https://github.com/VentionCo/machine-cloud) repository. First, clone the repository:
+
+```bash
+git clone git@github.com:VentionCo/machine-cloud.git
+```
+
+Make sure you're using `Node 18` and `npm 7`. If you're using `nvm`, you can run:
+
+```bash
+nvm use 18
+```
+
+Go to the root of the repository and install dependencies:
+
+```bash
+npm ci
+```
+
+This repository uses [Nx](https://nx.dev) to manage its monorepo. You will need to use Nx commands so install the library globally:
+
+```bash
+npm add --global nx@latest
+```
+
+To build the storybook and start the development server, run (in the root directory):
+
+```bash
+nx run machine-ui:storybook
+```
+
+🚀 This will start the storybook server at `http://localhost:4400/`.
+
+Then, navigate to the `machine-ui` directory to start developing:
+
+```bash
+cd projects/libs/machine-ui
+```
+
+And that's it! You're ready to start developing Machine UI.
+
+If you'd like to learn more on how the `machine-cloud` repo is structured please check [their documentation](https://machine-cloud-documentation.vention-aws.net/docs/machine-cloud-introduction).
+
+### 🔥 Hot Reload
+
+This project has hot-reloading enabled, so you can make changes in the `/src` and see them reflected in the browser.
+
+Changes made elsewhere in the project (e.g. `/.storybook` directory) will require a restart of the server.
+
+<br />
+
+## 📚 Tech Stack
+
+These are the tools we use to build Machine UI:
+
+<table>
+  <thead>
+    <tr>
+      <th>Framework</th>
+      <th>Information</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <a href="https://reactjs.org/">React</a>
+      </td>
+      <td>We chose React as our front-end library because all teams on the Vention platform are using or adopting React.</td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://www.typescriptlang.org/">TypeScript</a>
+      </td>
+      <td>We use typescript to ensure accurate typing of component properties and logic.</td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://material-ui.com/">Material-UI</a>
+      </td>
+      <td>
+        We build off a Material-UI base to create our components. This is because there is underlying logic and base styling in MUI that we
+        can leverage.
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://www.tss-react.dev/">TSS</a>
+      </td>
+      <td>
+        TSS is the typescript equivalent of JSS, we use this to override default MUI styling and add custom styles. We use this over the
+        default MUI styles library because there is CSS typing integrated and because the styles library has caused some issues in other
+        repositories.{" "}
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://storybook.js.org/">Storybook</a>
+      </td>
+      <td>
+        We use storybook for documentation (what you're reading right now is made in storybook!). When contributing the Machine UI you'll
+        need some knowledge of the documentation tool, mainly about how <a href="https://storybook.js.org/docs/writing-stories">stories</a>{" "}
+        and <a href="https://storybook.js.org/docs/writing-docs">docs</a> work.{" "}
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://testing-library.com/docs/react-testing-library/intro/">React Testing Library</a>
+      </td>
+      <td>
+        We use RTL for testing our components. Since Machine UI is going to be used accross the platform, we want to ensure every component
+        is made to the highest quality.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## 📝 Contributing
+
+We are building components as we go, please check that the component you are building does not already exist in the library.
+
+If you are making a new component, or a new **variation** of an existing component, please follow the steps below:
+
+1. Create a ticket in our [Jira Project](https://ventionco.atlassian.net/browse/MUI-95). Prefix the ticket title with `[Component] <name of component> - <variation>`
+
+   e.g. `[Component] Button - Secondary`
+
+2. Create a new branch from `master` with the name `<issue number>-<name of component>-<variation>`.
+
+   e.g. `1234-button-secondary`
+
+3. If this is a new component, create a new folder in the `src/lib/components` directory with the name of the component.
+
+   e.g. `src/lib/components/vention-button`
+
+4. Create a new file in the folder with the name of the component. As well as a storybook and testing file.
+
+   e.g. `vention-button.tsx`, `vention-button.stories.tsx`, `vention-button.test.tsx`
+
+5. While developing, please refer to our [code conventions](/docs/guides-code-conventions--docs) and remember to write unit tests and stories for your component.
+
+6. Once you are done, create a pull request to merge your branch into `master`. Please name the PR the same as the ticket. Request **two** reviewers who have previously contributed to Machine UI, one of which **is not a member of your team** (this is to ensure well-rounded reviews).

package/src/documentation/icons.mdx

@@ -0,0 +1,52 @@
+import { Meta, Anchor } from "@storybook/blocks"
+import { GoToIconGallery } from "../../.storybook/helpers/go-to-icon-gallery"
+
+<Meta title="Guides/Icons" />
+
+# Icons
+
+In Machine-UI, all icons are defined as `.svg` files and automatically transformed into reusable React components through the `<VentionIcon>` system. This approach ensures consistency across the UI, enables strong typing, and simplifies usage in code.
+
+The source for these icons is our [Figma design file](https://www.figma.com/design/oXDceBmiSGck2KEbM6DEbf/MachineUI?node-id=14596-10483&m=dev), where you can export the icon you need as an `.svg` file.
+
+## Generating Icons
+
+To add a new icon to the system:
+
+1. Run `nx reset`
+2. Export the `.svg` from Figma
+3. Add the file to the appropriate folder:
+   - For regular icons:  
+     `libs/machine-ui/src/lib/components/vention-icon/svg`
+   - For duotone icons:  
+     `libs/machine-ui/src/lib/components/vention-icon/duotone-svg`
+4. Run the generation script:  
+   `npm run nx -- generate-icons machine-ui`
+
+This script will:
+
+- Optimize the SVG
+- Convert it into a strongly-typed React component
+- Integrate it into the `<VentionIcon>` system
+
+**Note:** The SVG filename must be in kebab-case. This will determine the value of the `type` prop used in the component.
+
+## Usage
+
+```tsx
+import { VentionIcon } from "@/components/ui/vention-icon"
+;<VentionIcon
+  size={24}
+  type="robot-arm" // Derived from the SVG filename: robot-arm.svg
+  color="black"
+  hoverColor="gray"
+/>
+```
+
+## Icon Gallery
+
+To view all available icons and their type values, refer to the Icon gallery:
+
+<div style={{ display: "flex", gap: "1rem", marginTop: "1rem" }}>
+  <GoToIconGallery type="regular" /> <GoToIconGallery type="duotone" />
+</div>

package/src/documentation/installation-and-usage.mdx

@@ -0,0 +1,148 @@
+import { Meta } from "@storybook/blocks"
+
+<Meta title="Guides/Installation and Usage" />
+
+# Development
+
+We really encourage developers to develop new components **within** their actual designs. This further ensures the components are designed with the actual use case in mind.
+
+If you are consuming Machine-UI from outside the `machine-cloud` repository, you will need to import the components from the `@ventionco/machine-ui` package.
+
+The good thing is: you don't need to wait to publish this package to test your components in your project. You can use tools like `yalc`.
+
+## Yalc
+
+`yalc` is similar to `npm link` but it mimics a production `npm install` more closely and addresses some of the shortcomings that `npm link` still has.
+
+### Installation
+
+```bash
+npm install -g yalc
+```
+
+### Usage
+
+1.  First build the machine-ui package:
+
+    ```bash
+    nx run machine-ui:build
+    ```
+
+    This will build the machine-ui package in the repository's `dist` folder
+
+2.  Publish the package to yalc:
+
+    ```bash
+    cd <machine-cloud repo root>/dist/projects/libs/machine-ui
+    yalc publish
+    ```
+
+    This will publish the package to yalc's local registry
+
+3.  In your project, install the package from yalc:
+
+    ```bash
+    yalc add @ventionco/machine-ui
+    ```
+
+    This will add the package to your project's `node_modules` folder and update the `package.json` file with the yalc package.
+
+4.  Import the components in your project:
+
+    ```javascript
+    import { VentionButton } from "@ventionco/machine-ui"
+    ```
+
+5.  After making any changes to machine-ui, you will need to repeat steps 1 and 2. Rebuild the package and publish it again to yalc:
+
+    ```bash
+    cd <machine-cloud repo root>
+    nx run machine-ui:build
+    cd <machine-cloud repo root>/dist/projects/libs/machine-ui
+    yalc publish
+    ```
+
+And you're ready to go! You can now develop and test your components in your project without having to wait for the package to be published.
+
+# Installation and Usage
+
+Want to use Machine UI components in your project? Here's how to do it.
+
+## Pre-requisites
+
+Machine UI uses the latest version of MUI v5 and React 17. If you're using an older version of React, you may need to upgrade.
+
+If you're using MUI v4 please take the following steps to upgrade to MUI v5:
+
+1.  follow the MUI v5 [default installation guide](https://mui.com/getting-started/usage/). This means:
+
+    1️⃣ (optional) remove MUI v4 packages:
+
+    ```bash
+    npm uninstall @material-ui/core @material-ui/icons @material-ui/lab
+    ```
+
+    2️⃣ install the MUI v5 packages (`@mui/styles` is optional, only if you used the `makeStyles` hook, `@mui/lab` is optional):
+
+    ```bash
+    npm install @mui/material @emotion/react @emotion/styled @mui/icons-material @mui/styles @mui/lab
+    ```
+
+2.  replace all imports of `@material-ui/core` and `@material-ui/icons` with `@mui/material` and `@mui/icons-material` respectively.
+3.  replace all imports of `makeStyles` from `@material-ui/core/styles` with `makeStyles` from `@mui/styles`.
+
+    **Note**: `makeStyles` is unfortunately a deprecated API in MUI v5, so you may want to switch these old components to use the `styled` function from `@mui/material/styles` in the future.
+
+4.  if a component cannot use `makeStyles` in v5, switch to the `styled` function from `@mui/material/styles`.
+
+    **Important**: the `styled` function from 'styled-components' package causes problems in **`vention_assembler`** due to hash issues. If you want to use the `styled` function, do not import it from 'styled-components':
+
+    ```javascript
+    import { styled } from "@mui/material/styles"
+    ```
+
+    And you're done!
+
+## Installation
+
+### Package
+
+Machine UI is deployed as an NPM package automatically on every merge to master by the machine-code team. To use it in your project, simply run:
+
+```bash
+npm install @ventionco/machine-ui@x.xxx.x
+```
+
+Please refer to this [link](https://github.com/VentionCo/machine-cloud/pkgs/npm/machine-ui) for the latest version.
+You will have to maintain (e.g. update) the version of the package every time you want to use new components.
+
+### Fonts
+
+Machine UI uses the `Inter` and `Roboto Mono` font by default. To use it in your project, you can add the following lines to your `/public/index.html` file:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=Roboto+Mono&display=swap" rel="stylesheet" />
+```
+
+### Icons
+
+Machine UI uses `Tabler Icons` by default. It is installed as a peer dependency in the package so you'll be able to use it without any additional installation.
+Please see [Design System/Icons](/docs/guides-design-system-icons--documentation) for more information on how to use Tabler Icons.
+
+## Usage
+
+To use Machine UI components in your project, you need to import them from the package. Here's an example of how to use the `VentionButton` component:
+
+```javascript
+import { VentionButton } from "@ventionco/machine-ui"
+
+function App() {
+  return (
+    <VentionButton variant="contained" color="primary">
+      Hello World
+    </VentionButton>
+  )
+}
+```