@vention/machine-ui 5.30.8 → 5.30.9

package/README.md

@@ -2,11 +2,7 @@
 
 Machine UI is Vention's component library for building applications and Human-Machine Interfaces (HMIs). This is the same library that Vention uses internally to build our own applications, now available for you to build custom applications for your Vention machines.
 
-## 📚 Documentation
-
-Complete documentation, including component examples, design system guidelines, and usage instructions, can be found at:
-
-**[https://assets.vention.com/machine-ui-storybook/](https://assets.vention.com/machine-ui-storybook/index.html?path=/docs/guides-introduction--documentation)**
+Each component's props and their types are in the package's type declarations, which your editor and `tsc` read. Look there for props; this README covers only defaults, behaviour and composition that the types can't show.
 
 ## 🚀 Installation
 
@@ -18,19 +14,169 @@ npm install @vention/machine-ui
 
 For the latest version and release notes, visit the [npm package page](https://www.npmjs.com/package/@vention/machine-ui).
 
-## 📖 Quick Start
+## Setup
+
+Machine UI builds on MUI v5. The app needs the peer dependencies `react` and `react-dom` 17 and `@mui/material` 5, plus `@emotion/react` and `@emotion/styled`, which MUI needs. `@tabler/icons-react`, `tss-react` and `react-draggable` come with the package.
+
+Wrap the app in MUI's `ThemeProvider` with one of the two themes:
+
+- `machineUiTheme`: the desktop theme. It sets the palette, the spacing scale (`theme.spacing(n)` reads `[0, 4, 8, 12, 16, 24, 28, 32, 40, 48, 56, 64, 80, 96, 128]` px) and the typography variants.
+- `machineUiHmiTheme`: the touch HMI theme. It is `machineUiTheme` with thicker icon strokes (1.5px instead of 1.01px). Palette, spacing and typography are the same, so touch sizing comes from each component's `size` prop, not from the theme (see Components).
+
+Both themes add typography variants you can pass to MUI's `Typography`: `heading36Bold`, `heading24SemiBold`, `heading24Medium`, `heading18SemiBold`, `heading16SemiBold`, `paragraph18Medium`, `paragraph18Regular`, `paragraph16Medium`, `paragraph16Regular`, `paragraph14Regular`, `code16Reg`, `code14Reg`, `code12Reg`, `uiText18SemiBold`, `uiText18Medium`, `uiText18Regular`, `uiText14SemiBold`, `uiText14Medium`, `uiText14Regular`, `uiText12SemiBold`, `uiText12Medium`, `uiText12Regular`, `uiTableNumbers14Reg`, `uiTableNumbers12Reg`, and for HMIs `hmiText20Regular`, `hmiText20SemiBold`, `hmiText22Regular`, `hmiText22Medium`, `hmiText22SemiBold`, `hmiText28SemiBold`, `hmiText32SemiBold`.
+
+`COLORS` holds the raw palette: `COLORS.slate`, `COLORS.blue`, `COLORS.cyan`, `COLORS.green`, `COLORS.amber` and `COLORS.red`, each keyed by shade (`50`, `100` to `900`, `950`), for example `COLORS.slate[800]`. Use it where a component takes a color string, such as `VentionStatusDot`'s `color`.
+
+Importing anything from the package applies its global styles (`box-sizing: border-box` on every element), so there is no `CssBaseline` to add. The themes use the `Inter` and `Roboto Mono` fonts, which the app loads itself, for example from Google Fonts in `index.html`:
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=Roboto+Mono&display=swap" rel="stylesheet" />
+```
+
+```tsx
+import { ThemeProvider, Typography } from "@mui/material"
+import { COLORS, VentionButton, VentionStatusIndicator, machineUiHmiTheme } from "@vention/machine-ui"
+
+export function App() {
+  return (
+    <ThemeProvider theme={machineUiHmiTheme}>
+      <div style={{ backgroundColor: COLORS.slate[50], padding: 24 }}>
+        <Typography variant="hmiText28SemiBold">Cell 1</Typography>
+        <VentionStatusIndicator label="Running" dotColor={COLORS.green[500]} size="xx-large" />
+        <VentionButton size="xx-large" variant="filled-brand" onClick={() => console.log("start")}>
+          Start cycle
+        </VentionButton>
+      </div>
+    </ThemeProvider>
+  )
+}
+```
 
-```javascript
-import { VentionButton } from "@vention/machine-ui"
+## Components
+
+Every component is a named export of `@vention/machine-ui`. Most components take a `size` prop; the HMI sizes are `x-large` and `xx-large`.
+
+Buttons, text inputs, selects and comboboxes share one height per size: `x-small` 16px, `small` 24px, `medium` 32px, `large` 40px, `x-large` 56px, `xx-large` 80px. A touch target should be at least 44px, so on a touch HMI use `x-large` or `xx-large`. At `xx-large`, input and select labels switch to `hmiText20*`; the value text and button labels keep their regular typography.
+
+Components built on an MUI component (noted as "built on MUI `X`") accept that component's props too, so standard props such as `onClick`, `value`, `checked` and `onChange` work as they do in MUI.
+
+### Actions
+
+- `VentionButton`: the standard button. `size` defaults to `"small"` (24px), too small for touch, so use `size="x-large"` or `"xx-large"` on touch screens. `variant` defaults to `"filled-brand"`. The label is `children`, else `labelText`, and reads "Button" when both are missing. `type` defaults to `"button"`, so pass `type="submit"` to submit a form. Built on MUI `Button`.
+- `VentionIconButton`: a square button that shows only an icon, passed as `children`. It takes the same `variant` and `size` as `VentionButton`, with the same `"small"` default. Built on MUI `IconButton`.
+- `VentionDropdownButton`: a button that opens a menu of its children. Pass a `VentionMenu` wrapping `VentionMenu.Item` elements as `children`; the button renders children as-is, so bare items get no menu surface.
+- `VentionLink`: an inline text link. `external` defaults to true and shows an external-link icon, so pass `external={false}` for an in-app link. Without `labelText` it reads "Button".
+
+### Inputs
+
+- `VentionTextInput`: a text field built on MUI `TextField`. Use `state` (`"error"`, `"warning"`, `"success"`, `"disabled"`) instead of `disabled` and `error`. `leftItemText` and `rightItemText` show fixed text inside the field, such as a unit, and `maxCharacters` shows a character count.
+- `VentionSuggestionsInput`: a `VentionTextInput` that shows a list of suggestions as the user types. Pass either `value` (controlled) or `defaultValue`, not both.
+- `VentionSelect`: a dropdown select. `onChange` receives the event, so read `event.target.value`. Each entry in `menuItems` is a `VentionSelectMenuItem` or a `VentionSelectDivider` (`{ type: "divider" }`). With `isMultiple`, `value` is an array. Built on MUI `Select`.
+- `VentionSelectSkeleton`: the loading placeholder for `VentionSelect`, also available as `VentionSelect.Skeleton`.
+- `VentionCombobox`: a searchable single-choice dropdown. `groups` are matched to options by each option's `group`.
+- `VentionTagsInput`: a field that collects a list of text tags.
+- `VentionCheckbox`: a checkbox with an optional label, built on MUI `FormControlLabel`, so `checked` and `onChange` work as there. Its size prop is `checkboxSize`.
+- `VentionRadio`: a radio button, used inside MUI's `RadioGroup`. Its size prop is `radioSize`. Built on MUI `Radio`.
+- `VentionRadioTile`: a large selectable tile with a radio button, used inside MUI's `RadioGroup`, good for touch choices. Built on MUI `FormControlLabel`.
+- `VentionSwitch`: an on/off toggle. `checked` is a string (`"on"`, `"off"`, `"mixed"` or `"loading"`), not a boolean, and `onChange` receives `"on"` or `"off"`.
+- `VentionSlider`: a range slider built on MUI `Slider`. `largeThumb` gives it a bigger handle, for touch.
+- `VentionCounter`: a small pill that shows a number, such as a count of pending items.
+- `VentionStepper`: a value with minus and plus buttons on each side. `value` is displayed as is. Put `onClick` and `disabled` for each button in `minusButtonProps` and `plusButtonProps`.
+- `VentionInputGroupLabel`: a label placed beside a group of inputs.
+- `VentionUploadFile`: one row in a list of uploaded files, with its status. Set `state` to `"indeterminate"` while uploading.
+- `VentionDropZone`: an area to drop or pick files. `onFilesSelect(files)` returns an array of error messages, empty when every file is valid.
+
+### Feedback
+
+- `VentionAlert`: an alert box with optional actions. A button or link shows when its text is set, so pair each text with its click handler, such as `primaryButtonText` with `onPrimaryButtonClick`. Use `size="xx-large"` on touch HMIs.
+- `VentionBanner`: a full-width colored strip for a machine or page state.
+- `VentionCallout`: an inline highlighted note with optional actions.
+- `VentionProgressBar`: a horizontal progress bar. `value` runs from 0 to 100.
+- `VentionSpinner`: a circular progress indicator. With `type="progress"` it shows `value`, from 0 to 100.
+- `VentionSkeleton`: a loading placeholder. `variant` (`"text"`, `"rounded"` or `"circular"`) decides which other props it needs.
+- `VentionStatusDot`: a small colored dot. `color` takes any CSS color, such as a `COLORS` value.
+- `VentionStatusIndicator`: a status dot with a text label, such as a machine state. Use `size="xx-large"` on touch HMIs.
+- `VentionBadge`: a small labeled tag. Pair the color with a text label, since color alone is hard to read on a shop floor.
+- `VentionTooltip`: a tooltip on hover or focus, built on MUI `Tooltip`. `placement` defaults to `"top-end"`. Hover does not exist on touch screens, so don't put information an operator needs only in a tooltip.
+
+### Overlays
+
+- `VentionModal`: a dialog with a title, body and up to two buttons. `type` sets the icon. `backDropClickClosable` defaults to true. `width` overrides the width that `modalSize` sets. Set `isTouchDevice` on touch HMIs for larger padding, icons, text and buttons.
+- `VentionModalBase`: the empty modal frame for custom content. Set `isTouchDevice` on touch HMIs.
+- `VentionModalBanner`: a colored banner to place at the top of a modal.
+- `VentionDrawer`: a panel that slides in from a screen edge, built on MUI `Drawer`. When `onDrawerHandleClick` is set, the drawer stays mounted and shows a handle that calls it to toggle.
+- `VentionPopover`: a floating card with an arrow, pointing at an element or a position. Place it with `anchorElement` (an `HTMLElement`) or `pos2D` (`{ top, left }` in px). `buttons` takes up to three `VentionButton` props objects.
+- `VentionMenu`: a menu list that closes when the user clicks outside it. `showMenu` and `closeMenuOnClick` default to true. Fill it with `VentionMenu.Item` (`subMenuItems` makes a nested menu), `VentionMenu.Header` and `VentionMenu.Divider`.
+- `VentionPositionedComponent`: places its `children` at a fixed position that stays inside the viewport. Pass either `anchorRect` (a `DOMRect`, such as from `getBoundingClientRect()`) or `position` (`{ top, left }`), not both.
+
+### Navigation and layout
+
+- `VentionTabs`: a row of tabs. `value` is the index of the selected tab, and `onChange(event, index)` receives the new index.
+- `VentionSteps`: a vertical list of steps for a guided procedure. Use `size="xx-large"` on touch HMIs; `"small"` always shows dots.
+- `VentionSidebarItem`: a profile entry in a sidebar.
+- `VentionTreeItem`: one row of a tree, with nested `VentionTreeItem` children.
+- `VentionDraggable`: a floating panel the user can drag around the screen. `tabLocation` shows a drag handle on that side; without it the whole panel drags.
+
+### Identity
+
+- `VentionAvatar`: a round user picture or initials.
+- `VentionPersonCard`: an avatar with a name and a description line.
+- `VentionPersonCardSkeleton`: the loading placeholder for `VentionPersonCard`, also available as `VentionPersonCard.Skeleton`.
+- `VentionIcon`: an icon from the Vention icon set. `type` is an icon name such as `"player-play"` or `"status-warning-hmi"`. `size` is in px and defaults to 24. Icon strokes follow the theme, so they are thicker under `machineUiHmiTheme`. For other icons, `@tabler/icons-react` is installed with the package.
+
+A small touch panel that uses several of these:
+
+```tsx
+import { useState } from "react"
+import { VentionModal, VentionSelect, VentionSwitch } from "@vention/machine-ui"
+
+export function RecipePanel() {
+  const [recipe, setRecipe] = useState<string>("small-box")
+  const [vacuum, setVacuum] = useState<"on" | "off">("off")
+  const [pendingRecipe, setPendingRecipe] = useState<string | null>(null)
 
-function App() {
   return (
-    <VentionButton variant="filled-brand">Hello World</VentionButton>
+    <>
+      <VentionSelect
+        size="xx-large"
+        variant="outlined"
+        labelText="Recipe"
+        value={recipe}
+        onChange={event => setPendingRecipe(String(event.target.value))}
+        menuItems={[
+          { value: "small-box", displayText: "Small box" },
+          { value: "large-box", displayText: "Large box" },
+          { type: "divider" },
+          { value: "custom", displayText: "Custom", isDisabled: true },
+        ]}
+      />
+      <VentionSwitch size="xx-large" labelText="Vacuum" checked={vacuum} onChange={setVacuum} />
+      <VentionModal
+        isOpen={pendingRecipe !== null}
+        onClose={() => setPendingRecipe(null)}
+        isTouchDevice
+        type="warning"
+        titleText="Change recipe?"
+        body="The current cycle will stop."
+        primaryButton={{
+          text: "Change",
+          onClick: () => {
+            if (pendingRecipe !== null) setRecipe(pendingRecipe)
+            setPendingRecipe(null)
+          },
+        }}
+        secondaryButton={{ text: "Cancel", onClick: () => setPendingRecipe(null) }}
+      />
+    </>
   )
 }
 ```
 
-For detailed installation instructions, including font setup and prerequisites, see the [Installation and Usage guide](https://assets.vention.com/machine-ui-storybook/index.html?path=/docs/guides-installation-and-usage--documentation).
+## Storybook
+
+The Storybook is the visual reference: it renders every component in each of its variants and sizes, with interactive controls, plus design guidelines for color, typography and HMIs.
+
+**[https://assets.vention.com/machine-ui-storybook/](https://assets.vention.com/machine-ui-storybook/index.html?path=/docs/guides-introduction--documentation)**
 
 ## 📋 Versioning Policy
 
@@ -61,5 +207,3 @@ Machine UI components work exceptionally well for industrial HMI applications. F
 ## 📄 License
 
 This library is provided for use with Vention machines and applications.
-
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vention/machine-ui",
-  "version": "5.30.8",
+  "version": "5.30.9",
   "repository": {
     "type": "git",
     "url": "https://github.com/VentionCo/machine-cloud.git"