@react-ui-org/react-ui 0.60.0 → 0.61.0

package/jest.config-ts.js

@@ -0,0 +1,34 @@
+
+ module.exports = {
+  extensionsToTreatAsEsm: [
+    '.ts',
+    '.tsx',
+  ],
+  moduleFileExtensions: [
+    'js',
+    'jsx',
+    'ts',
+    'tsx',
+  ],
+  moduleNameMapper: {
+    '\\.scss$': 'identity-obj-proxy',
+    '\\.svg$': '<rootDir>/tests/jest/mocks/svgrMock.jsx',
+  },
+  preset: 'ts-jest',
+  setupFiles: [
+    '<rootDir>/tests/jest/setupJest.js',
+  ],
+  setupFilesAfterEnv: [
+  ],
+  testEnvironment: '@happy-dom/jest-environment',
+  testMatch: [
+    '**/*.test.{ts,tsx}',
+  ],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      { useESM: true },
+    ],
+  },
+  verbose: true,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@react-ui-org/react-ui",
   "description": "React UI is a themeable UI library for React apps.",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "keywords": [
     "react",
     "ui",
@@ -47,17 +47,24 @@
     "copy": "npm run copy:css && npm run copy:js",
     "copy:css": "cp src/docs/_assets/generated/react-ui.css dist && cp src/docs/_assets/generated/react-ui.development.css dist",
     "copy:js": "cp src/docs/_assets/generated/react-ui.js dist && cp src/docs/_assets/generated/react-ui.development.js dist",
-    "eslint": "eslint --ext js,jsx src",
-    "jest": "jest src --coverage",
+    "eslint": "npm run eslint:ts && npm run eslint:js",
+    "eslint:js": "eslint --ext js,jsx src",
+    "eslint:ts": "eslint --ext ts,tsx -c .eslintrc-ts src tests",
     "lint": "npm run eslint && npm run markdownlint && npm run stylelint",
-    "markdownlint": "markdownlint-cli2 \"CONTRIBUTING.md\" \"README.md\" \"RELEASING.md\" \"src/**/*.md\"",
+    "markdownlint": "markdownlint-cli2 \"README.md\" \"src/**/*.md\"",
     "postbuild": "npm run copy",
-    "postinstall": "cp -n .env.dist .env || true",
+    "postinstall": "cp -n .env.dist .env && cp -n .env.playwright.dist .env.playwright || true",
     "precopy": "rm -rf dist && mkdir dist",
     "prepublishOnly": "npm run build",
     "start": "webpack --watch --mode=development",
     "stylelint": "stylelint \"src/**/*.{css,scss}\" \"!src/docs/_assets/generated/**\" --config stylelint.config.js",
-    "test": "npm run jest"
+    "test": "npm run test:jest",
+    "test:jest": "npm run test:jest:ts && npm run test:jest:js",
+    "test:jest:js": "jest --coverage",
+    "test:jest:ts": "jest -c jest.config-ts.js --coverage",
+    "test:playwright-ct:all": "playwright test -c playwright-ct.config.ts",
+    "test:playwright-ct:all-with-update": "playwright test -c playwright-ct.config.ts --update-snapshots",
+    "test:playwright-ct:show-report": "playwright show-report --host=0.0.0.0 --port=9323"
   },
   "dependencies": {
     "normalize.css": "^8.0.1"
@@ -77,11 +84,18 @@
     "@babel/preset-react": "^7.24.7",
     "@babel/register": "^7.24.6",
     "@happy-dom/jest-environment": "^16.6.0",
+    "@playwright/experimental-ct-react": "^1.50.1",
     "@stylistic/stylelint-config": "^1.0.1",
     "@svgr/webpack": "^8.1.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.5",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
     "@visionappscz/eslint-config-visionapps": "^1.7.0",
     "@visionappscz/stylelint-config": "^4.0.0",
     "autoprefixer": "^10.4.19",
@@ -89,13 +103,17 @@
     "babel-loader": "^9.1.3",
     "core-js": "^3.37.1",
     "css-loader": "^7.1.2",
+    "dotenv": "^16.4.7",
     "eslint": "^8.57.0",
     "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "eslint-plugin-deprecation": "^3.0.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-jsx-a11y": "^6.9.0",
     "eslint-plugin-markdown": "^3.0.1",
     "eslint-plugin-react": "^7.34.3",
     "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-typescript-sort-keys": "^3.3.0",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
     "markdownlint-cli2": "^0.13.0",
@@ -110,6 +128,7 @@
     "stylelint": "^16.7.0",
     "stylelint-webpack-plugin": "^5.0.1",
     "terser-webpack-plugin": "^5.3.10",
+    "ts-jest": "^29.2.6",
     "webpack": "^5.92.1",
     "webpack-cli": "^5.1.4",
     "webpack-visualizer-plugin2": "^1.1.0"

package/playwright-ct.config.ts

@@ -0,0 +1,68 @@
+import {
+  defineConfig,
+  devices,
+} from '@playwright/experimental-ct-react';
+import { parseEnvironment } from './tests/playwright/env/parseEnvironment';
+
+const environment = parseEnvironment();
+
+const isCI = !!process.env.CI;
+
+/**
+ * @see https://playwright.dev/docs/test-configuration
+ */
+module.exports = defineConfig({
+  // Fail the build on CI if you accidentally left test.only in the source code
+  forbidOnly: isCI,
+  // Run tests in files in parallel
+  fullyParallel: true,
+  // Directory where the output generated by Playwright is stored
+  outputDir: './tests/playwright/.temp/playwright-ct-output/',
+  // Run tests for following projects
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  // Retry failed tests once to eliminate flakiness
+  retries: 1,
+  // Directory where the snapshots are located
+  // (must be same as testDir to save snapshots in place where tests are located)
+  snapshotDir: './src/',
+  // Directory where the tests are located
+  testDir: './src/',
+  // Pattern to search for test files
+  testMatch: '*/*.spec.{ts,tsx}',
+  // Timeout for each test
+  timeout: 10 * 1000,
+  // Do not update snapshots automatically
+  updateSnapshots: 'none',
+  // Configuration for Playwright component testing
+  use: {
+    // Directory where the cache is stored
+    ctCacheDir: './tests/playwright/.temp/playwright-ct-cache',
+    // Port to use for Playwright component endpoint
+    ctPort: environment.CT_PORT,
+    // Directory where the templates are stored
+    ctTemplateDir: './tests/playwright/templates',
+    // Launch options for Playwright
+    launchOptions: {
+      args: [
+        '--use-gl=egl',
+        // # Must be set to `new` to enable new version of Chromium Headless to obtain correct snapshots
+        '--headless=new',
+      ],
+      ignoreDefaultArgs: [
+        // # Must be ignored to enable new version of Chromium Headless to obtain correct snapshots
+        '--headless',
+      ],
+    },
+    // Collect trace on all retries
+    trace: 'on-all-retries',
+  },
+  // Number of workers to use
+  workers: environment.WORKERS,
+});

package/src/components/Alert/Alert.jsx

@@ -57,9 +57,9 @@ export const Alert = ({
 
 Alert.defaultProps = {
   color: 'note',
-  icon: null,
+  icon: undefined,
   id: undefined,
-  onClose: null,
+  onClose: undefined,
 };
 
 Alert.propTypes = {

package/src/components/Button/Button.jsx

@@ -101,18 +101,18 @@ export const Button = React.forwardRef((props, ref) => {
 });
 
 Button.defaultProps = {
-  afterLabel: null,
-  beforeLabel: null,
+  afterLabel: undefined,
+  beforeLabel: undefined,
   block: false,
   color: 'primary',
   disabled: false,
-  endCorner: null,
-  feedbackIcon: null,
+  endCorner: undefined,
+  feedbackIcon: undefined,
   id: undefined,
   labelVisibility: 'xs',
   priority: 'filled',
   size: 'medium',
-  startCorner: null,
+  startCorner: undefined,
   type: 'button',
 };
 

package/src/components/Button/README.md

@@ -28,7 +28,7 @@ See [API](#api) for all available options.
 - **Don't overwhelm your UI** with too many high-emphasis actions. There should
     always be one but chances are that having more of them is not necessary.
 
-- Ensure the **button action is well recognazible** across your target audience.
+- Ensure the **button action is well recognizable** across your target audience.
     This is especially important when using the button [with an icon only](#icon-buttons).
 
 ## Priorities

package/src/components/ButtonGroup/ButtonGroup.jsx

@@ -48,7 +48,7 @@ export const ButtonGroup = ({
 
 ButtonGroup.defaultProps = {
   block: false,
-  children: null,
+  children: undefined,
   disabled: false,
   priority: 'filled',
   size: 'medium',

package/src/components/Card/CardFooter.jsx

@@ -24,7 +24,7 @@ export const CardFooter = ({
 };
 
 CardFooter.defaultProps = {
-  children: null,
+  children: undefined,
 };
 
 CardFooter.propTypes = {

package/src/components/CheckboxField/CheckboxField.jsx

@@ -79,14 +79,14 @@ export const CheckboxField = React.forwardRef((props, ref) => {
 
 CheckboxField.defaultProps = {
   disabled: false,
-  helpText: null,
+  helpText: undefined,
   id: undefined,
   isLabelVisible: true,
   labelPosition: 'after',
   renderAsRequired: false,
   required: false,
-  validationState: null,
-  validationText: null,
+  validationState: undefined,
+  validationText: undefined,
 };
 
 CheckboxField.propTypes = {

package/src/components/FileInputField/FileInputField.jsx

@@ -78,6 +78,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
   const handleFileChange = (files, event) => {
     if (files.length === 0) {
       setSelectedFileNames([]);
+      onFilesChanged([], event);
       return;
     }
 
@@ -85,6 +86,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
     // does not accept multiple files, no files are processed.
     if (files.length > 1 && !multiple) {
       setSelectedFileNames([]);
+      onFilesChanged([], event);
       return;
     }
 
@@ -221,7 +223,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
             </Text>
           </button>
         </div>
-        {helpText && (
+        {(helpText && !inputGroupContext) && (
           <div
             className={styles.helpText}
             id={`${id}__helpText`}
@@ -229,7 +231,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
             {helpText}
           </div>
         )}
-        {validationText && (
+        {(validationText && !inputGroupContext) && (
           <div
             className={styles.validationText}
             id={`${id}__validationText`}
@@ -245,14 +247,14 @@ export const FileInputField = React.forwardRef((props, ref) => {
 FileInputField.defaultProps = {
   disabled: false,
   fullWidth: false,
-  helpText: null,
+  helpText: undefined,
   isLabelVisible: true,
   layout: 'vertical',
   multiple: false,
   required: false,
   size: 'medium',
-  validationState: null,
-  validationText: null,
+  validationState: undefined,
+  validationText: undefined,
 };
 
 FileInputField.propTypes = {
@@ -266,6 +268,9 @@ FileInputField.propTypes = {
   fullWidth: PropTypes.bool,
   /**
    * Optional help text.
+   *
+   * Help text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   helpText: PropTypes.node,
   /**
@@ -319,6 +324,9 @@ FileInputField.propTypes = {
   validationState: PropTypes.oneOf(['invalid', 'valid', 'warning']),
   /**
    * Validation message to be displayed.
+   *
+   * Validation text is never rendered when the component is placed into `InputGroup`.
+   * If a validation text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
 };

package/src/components/FormLayout/FormLayout.jsx

@@ -68,7 +68,7 @@ export const FormLayout = ({
 
 FormLayout.defaultProps = {
   autoWidth: false,
-  children: null,
+  children: undefined,
   fieldLayout: 'vertical',
   labelWidth: 'default',
 };

package/src/components/FormLayout/FormLayoutCustomField.jsx

@@ -80,15 +80,15 @@ export const FormLayoutCustomField = ({
 };
 
 FormLayoutCustomField.defaultProps = {
-  children: null,
+  children: undefined,
   disabled: false,
   fullWidth: false,
   id: undefined,
-  innerFieldSize: null,
-  label: null,
+  innerFieldSize: undefined,
+  label: undefined,
   labelForId: undefined,
   required: false,
-  validationState: null,
+  validationState: undefined,
 };
 
 FormLayoutCustomField.propTypes = {

package/src/components/Grid/Grid.jsx

@@ -54,7 +54,7 @@ Grid.defaultProps = {
   alignContent: undefined,
   alignItems: undefined,
   autoFlow: undefined,
-  children: null,
+  children: undefined,
   columnGap: 4,
   columns: '1fr',
   justifyContent: undefined,

package/src/components/Grid/GridSpan.jsx

@@ -35,7 +35,7 @@ export const GridSpan = ({
 /* eslint-disable sort-keys */
 
 GridSpan.defaultProps = {
-  children: null,
+  children: undefined,
   columns: 1,
   rows: 1,
   tag: 'div',

package/src/components/InputGroup/InputGroup.jsx

@@ -18,6 +18,7 @@ import styles from './InputGroup.module.scss';
 export const InputGroup = ({
   children,
   disabled,
+  helpTexts,
   id,
   isLabelVisible,
   label,
@@ -89,7 +90,21 @@ export const InputGroup = ({
             {children}
           </InputGroupContext.Provider>
         </div>
-        {validationTexts && (
+        {helpTexts && helpTexts.length > 0 && (
+          <ul
+            className={styles.helpText}
+            id={id && `${id}__helpTexts`}
+          >
+            {helpTexts.map((helpText) => (
+              <li key={helpText}>
+                <Text blockLevel>
+                  {helpText}
+                </Text>
+              </li>
+            ))}
+          </ul>
+        )}
+        {validationTexts && validationTexts.length > 0 && (
           <ul
             className={styles.validationText}
             id={id && `${id}__validationTexts`}
@@ -109,14 +124,15 @@ export const InputGroup = ({
 };
 
 InputGroup.defaultProps = {
-  children: null,
+  children: undefined,
   disabled: false,
+  helpTexts: undefined,
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
   required: false,
   size: 'medium',
-  validationTexts: null,
+  validationTexts: undefined,
 };
 
 InputGroup.propTypes = {
@@ -133,6 +149,10 @@ InputGroup.propTypes = {
    * If `true`, the whole input group with all nested inputs and buttons will be disabled.
    */
   disabled: PropTypes.bool,
+  /**
+   * An array of help texts to be displayed.
+   */
+  helpTexts: PropTypes.arrayOf(PropTypes.node),
   /**
    * ID of the root HTML element.
    *
@@ -171,7 +191,7 @@ InputGroup.propTypes = {
   /**
    * An array of validation messages to be displayed.
    */
-  validationTexts: PropTypes.node,
+  validationTexts: PropTypes.arrayOf(PropTypes.node),
 };
 
 export const InputGroupWithGlobalProps = withGlobalProps(InputGroup, 'InputGroup');

package/src/components/InputGroup/InputGroup.module.scss

@@ -1,4 +1,4 @@
-// 1. The class name is intentionally singular because it's targeted by other mixins too.
+// 1. The class names are intentionally singular because they are also targeted by other mixins.
 // 2. Use a block-level display mode to prevent extra white space below grouped inputs in Safari.
 // 3. Let wide input groups honor the minimum input width and overflow horizontally without wrapping and distorting
 //    the inputs.
@@ -39,6 +39,7 @@
     }
 
     // 1.
+    .helpText,
     .validationText {
         @include reset.list();
         @include foundation.help-text();

package/src/components/InputGroup/README.md

@@ -60,13 +60,14 @@ See [API](#api) for all available options.
   Make sure your inputs fit their container, especially on small screens.
 
 - In the background, InputGroup uses the [`fieldset`][fieldset] element. Not
-  only it improves the [accessibility] of the group, it also allows you to make
-  use of its built-in features like disabling all nested inputs or pairing the
-  group with a form outside. Consult [the MDN docs][fieldset] to learn more.
+  only does it improve the [accessibility] of the group, it also allows you to
+  make use of its built-in features like disabling all nested inputs or pairing
+  the group with a form outside. Consult [the MDN docs][fieldset] to learn more.
 
 - InputGroup currently **supports grouping of**
   [TextField](/components/TextField), [SelectField](/components/SelectField),
-  and [Button](/components/Button) components.
+  [FileInputField](/components/FileInputField), and [Button](/components/Button)
+  components.
 
 - To group [Buttons](/components/Button) only, use the
   [ButtonGroup](/components/ButtonGroup) component which is designed
@@ -104,7 +105,7 @@ You can set the `size` property directly on InputGroup to be shared for all
 fields and buttons inside the group. This property is then passed over to
 individual elements. At the same time, it **cannot be overridden** on the
 fields' or buttons' level. While technically possible, from the design point of
-view it's undesirable to group elements of totally different types or sizes.
+view, it's undesirable to group elements of totally different types or sizes.
 
 ## Invisible Label
 
@@ -136,9 +137,9 @@ the input.
 
 ## Horizontal layout
 
-The default vertical layout is very easy to use and work with. However, there
-are situations where horizontal layout suits better — and that's why React UI
-supports this kind of layout as well.
+The default vertical layout is straightforward to use and work with. However,
+there are situations where horizontal layout suits better — and that's why
+React UI supports this kind of layout as well.
 
 ```docoff-react-preview
 <InputGroup
@@ -150,6 +151,57 @@ supports this kind of layout as well.
 </InputGroup>
 ```
 
+## Help Text
+
+You may provide one or more additional help texts to clarify how the input group
+should be filled.
+
+These messages are not semantically tied to the `children` elements, the
+connection should be expressed in textual form in the actual message.
+
+⚠️ Help texts passed to input elements' `helpText` prop are ignored within
+InputGroup.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Pear',
+      value: 'pear',
+    },
+    {
+      label: 'Cherry',
+      value: 'cherry',
+    },
+  ];
+  return (
+    <InputGroup
+      label="Your favourite fruit"
+      helpTexts={[
+        "Choose one or more kinds of fruit to feel happy.",
+      ]}
+    >
+      <SelectField
+        label="Your favourite fruit"
+        onChange={(e) => setFruit(e.target.value)}
+        options={options}
+        value={fruit}
+      />
+      <TextField
+        label="Variety"
+        placeholder="Eg. Golden delicious"
+      />
+      <Button label="Submit" />
+    </InputGroup>
+  );
+})
+```
+
 ## States
 
 ### Disabled State
@@ -169,12 +221,15 @@ Validation states visually present the result of validation of the grouped
 inputs. Input group's validation state is taken from its child inputs. You
 should always **provide validation messages for states other than valid**
 directly through `validationTexts` prop so users know what happened and what
-action they should take or what options they have. These messages are not
-semantically tied to the `children` elements, the connection should be expressed
-in textual form in the actual message. The individual `children` elements must
-not show any `validationText`, they only show their respective `validationState`.
-Validation messages passed to input elements' `validationText` prop will be
-ignored.
+action they should take or what options they have.
+
+These messages are not semantically tied to the `children` elements, the
+connection should be expressed in textual form in the actual message. The
+individual `children` elements must not show any `validationText`, they only
+show their respective `validationState`.
+
+⚠️ Validation messages passed to input elements' `validationText` prop are
+ignored within InputGroup.
 
 👉 While there is a `required` property to visually denote the whole input group
 is required, there is no functional effect as there is no such HTML attribute

package/src/components/Modal/Modal.jsx

@@ -76,7 +76,12 @@ export const Modal = ({
   useModalScrollPrevention(preventScrollUnderneath);
 
   const onCancel = useCallback(
-    (e) => dialogOnCancelHandler(e, closeButtonRef, restProps.onCancel),
+    (e) => {
+      if (e.target !== internalDialogRef.current) {
+        return;
+      }
+      dialogOnCancelHandler(e, closeButtonRef, restProps.onCancel);
+    },
     [closeButtonRef, restProps.onCancel],
   );
   const onClick = useCallback(
@@ -121,7 +126,7 @@ export const Modal = ({
     onMouseDown,
   };
 
-  if (portalId === null) {
+  if (portalId === undefined) {
     return preRender(
       children,
       color,
@@ -152,14 +157,14 @@ Modal.defaultProps = {
   allowCloseOnEscapeKey: true,
   allowPrimaryActionOnEnterKey: true,
   autoFocus: true,
-  children: null,
-  closeButtonRef: null,
+  children: undefined,
+  closeButtonRef: undefined,
   color: undefined,
-  dialogRef: null,
-  portalId: null,
+  dialogRef: undefined,
+  portalId: undefined,
   position: 'center',
   preventScrollUnderneath: window.document.body,
-  primaryButtonRef: null,
+  primaryButtonRef: undefined,
   size: 'medium',
 };
 

package/src/components/Modal/ModalBody.jsx

@@ -30,7 +30,7 @@ export const ModalBody = ({
 };
 
 ModalBody.defaultProps = {
-  children: null,
+  children: undefined,
   scrolling: 'auto',
 };
 

package/src/components/Modal/ModalContent.jsx

@@ -24,7 +24,7 @@ export const ModalContent = ({
 };
 
 ModalContent.defaultProps = {
-  children: null,
+  children: undefined,
 };
 
 ModalContent.propTypes = {