Introduce State collection and rename validationState prop to state (#723)

.claude/rules/frontend.md

@@ -71,7 +71,7 @@ Components are `.tsx` files. They:
    element.
 6. Declare `Props` in `<ComponentName>.types.ts` (extending the matching
    `*HTMLAttributes` type) and export it from `index.ts`. Reuse shared unions
-   from `src/types` (`Color`, `Priority`, `Size`, `Layout`, `ValidationState`,
+   from `src/types` (`Color`, `Priority`, `Size`, `Layout`, `State`,
    …); component-specific unions stay in the component directory. Every
    type lives in a `.types.ts` file next to its implementation — including
    context values (`<ComponentName>ContextValue`), provider props and helper

src/components/CheckboxField/CheckboxField.module.scss

@@ -35,16 +35,20 @@
     }
 
     // States
+    .isRootStateChanged {
+        @include variants.state(changed);
+    }
+
     .isRootStateInvalid {
-        @include variants.validation(invalid);
+        @include variants.state(invalid);
     }
 
     .isRootStateValid {
-        @include variants.validation(valid);
+        @include variants.state(valid);
     }
 
     .isRootStateWarning {
-        @include variants.validation(warning);
+        @include variants.state(warning);
     }
 
     // Invisible label

src/components/CheckboxField/CheckboxField.tsx

@@ -2,7 +2,7 @@ import React, { useContext } from 'react';
 import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../helpers/classNames/classNames';
 import { transferProps } from '../../helpers/transferProps';
-import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
+import { getRootStateClassName } from '../_helpers/getRootStateClassName';
 import { FormLayoutContext } from '../FormLayout/FormLayoutContext';
 import styles from './CheckboxField.module.scss';
 import type { CheckboxFieldProps } from './CheckboxField.types';
@@ -16,7 +16,7 @@ export const CheckboxField = React.forwardRef<HTMLInputElement, CheckboxFieldPro
   labelPosition = 'after',
   renderAsRequired = false,
   required = false,
-  validationState,
+  state,
   validationText,
   ...restProps
 }, ref) => {
@@ -31,7 +31,7 @@ export const CheckboxField = React.forwardRef<HTMLInputElement, CheckboxFieldPro
         labelPosition === 'before' && styles.hasRootLabelBefore,
         disabled && styles.isRootDisabled,
         (renderAsRequired || required) && styles.isRootRequired,
-        getRootValidationStateClassName(styles, validationState),
+        getRootStateClassName(styles, state),
       )}
       htmlFor={id}
       id={id && `${id}__label`}

src/components/CheckboxField/CheckboxField.types.ts

@@ -4,7 +4,7 @@ import type {
 } from 'react';
 import type {
   LabelPosition,
-  ValidationState,
+  State,
 } from '../../types';
 
 export type CheckboxFieldLabelPosition = LabelPosition;
@@ -53,9 +53,10 @@ export type CheckboxFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'ty
    */
   required?: boolean;
   /**
-   * Alter the field to provide feedback based on validation result.
+   * Alter the field to reflect the state of its data, e.g. a validation result or a change
+   * against the saved value.
    */
-  validationState?: ValidationState;
+  state?: State;
   /**
    * Validation message to be displayed.
    */

src/components/CheckboxField/README.md

@@ -146,7 +146,7 @@ React.createElement(() => {
           </>
         )}
         onChange={() => setAgree(!agree)}
-        validationState="valid"
+        state="valid"
       />
       <CheckboxField
         checked={agree}
@@ -158,7 +158,7 @@ React.createElement(() => {
           </>
         )}
         onChange={() => setAgree(!agree)}
-        validationState="warning"
+        state="warning"
         validationText={(
           <>
             Please wait 10 minutes until we verify your data.
@@ -178,14 +178,36 @@ React.createElement(() => {
         )}
         onChange={() => setAgree(!agree)}
         required
-        validationState="invalid"
+        state="invalid"
         validationText="You must agree to be able to proceed."
       />
     </>
   );
 });
 ```
 
+### Changed State
+
+Changed state highlights fields whose value differs from the saved one, so users
+can review their edits before saving.
+
+A field shows one state at a time. When a changed value is also invalid, it's
+up to you to pick the state that matters more to the user.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [newsletter, setNewsletter] = React.useState(true);
+  return (
+    <CheckboxField
+      checked={newsletter}
+      label="Subscribe to newsletter"
+      onChange={() => setNewsletter(!newsletter)}
+      state="changed"
+    />
+  );
+});
+```
+
 ### Required State
 
 The required state indicates that the input is mandatory. Required fields

src/components/CheckboxField/__tests__/CheckboxField.spec.tsx

@@ -18,17 +18,17 @@ test.describe('CheckboxField', () => {
         ...mixPropTests([
           propTests.disabledPropTest,
           propTests.checkedPropTest,
-          propTests.validationStatePropTest,
+          propTests.statePropTest,
         ]),
         ...mixPropTests([
           propTests.checkedPropTest,
           propTests.requiredPropTest,
-          propTests.validationStatePropTest,
+          propTests.statePropTest,
         ]),
         ...mixPropTests([
           propTests.checkedPropTest,
           propTests.renderAsRequiredPropTest,
-          propTests.validationStatePropTest,
+          propTests.statePropTest,
         ]),
         ...mixPropTests([
           propTests.checkedPropTest,

src/components/FileInputField/FileInputField.module.scss

@@ -100,16 +100,20 @@
         cursor: inherit;
     }
 
+    .isRootStateChanged {
+        @include variants.state(changed);
+    }
+
     .isRootStateInvalid {
-        @include variants.validation(invalid);
+        @include variants.state(invalid);
     }
 
     .isRootStateValid {
-        @include variants.validation(valid);
+        @include variants.state(valid);
     }
 
     .isRootStateWarning {
-        @include variants.validation(warning);
+        @include variants.state(warning);
     }
 
     // Invisible label

src/components/FileInputField/FileInputField.tsx

@@ -15,7 +15,7 @@ import { classNames } from '../../helpers/classNames';
 import { transferProps } from '../../helpers/transferProps';
 import { TranslationsContext } from '../../providers/translations';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
-import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
+import { getRootStateClassName } from '../_helpers/getRootStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
 import { InputGroupContext } from '../InputGroup/InputGroupContext';
 import { Text } from '../Text';
@@ -42,7 +42,7 @@ export const FileInputField = React.forwardRef<FileInputFieldRef, FileInputField
   onFilesChanged,
   required = false,
   size = 'medium',
-  validationState,
+  state,
   validationText,
   ...restProps
 }, ref) => {
@@ -170,7 +170,7 @@ export const FileInputField = React.forwardRef<FileInputFieldRef, FileInputField
           styles,
           resolveContextOrProp(inputGroupContext && inputGroupContext.size, size),
         ),
-        getRootValidationStateClassName(styles, validationState),
+        getRootStateClassName(styles, state),
       )}
       id={`${id}__root`}
       onDragLeave={!disabled ? handleDragLeave : undefined}

src/components/FileInputField/FileInputField.types.ts

@@ -7,7 +7,7 @@ import type {
 import type {
   Layout,
   Size,
-  ValidationState,
+  State,
 } from '../../types';
 
 export type FileInputFieldFilesChangedEvent = ChangeEvent<HTMLInputElement> | DragEvent<HTMLDivElement> | Event | null;
@@ -87,9 +87,10 @@ export type FileInputFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'i
    */
   size?: Size;
   /**
-   * Alter the field to provide feedback based on validation result.
+   * Alter the field to reflect the state of its data, e.g. a validation result or a change
+   * against the saved value.
    */
-  validationState?: ValidationState;
+  state?: State;
   /**
    * Validation message to be displayed.
    *

src/components/FileInputField/README.md

@@ -166,28 +166,45 @@ have.
   id="my-file-valid"
   label="Attachment"
   onFilesChanged={() => {}}
-  validationState="valid"
+  state="valid"
   validationText="Looks good!"
 />
 <FileInputField
   id="my-file-invalid"
   label="Attachment"
   onFilesChanged={() => {}}
-  validationState="invalid"
+  state="invalid"
   validationText="Your file is too big. Please select something smaller."
 />
 <FileInputField
   id="my-file-warning"
   label="Attachment"
   onFilesChanged={() => {}}
-  validationState="warning"
+  state="warning"
   validationText={`
     You selected more than 10 files.
     It may take some time before we process them.
   `}
 />
 ```
 
+### Changed State
+
+Changed state highlights fields whose value differs from the saved one, so users
+can review their edits before saving.
+
+A field shows one state at a time. When a changed value is also invalid, it's
+up to you to pick the state that matters more to the user.
+
+```docoff-react-preview
+<FileInputField
+  id="my-file-changed"
+  label="Attachment"
+  onFilesChanged={() => {}}
+  state="changed"
+/>
+```
+
 ### Disabled State
 
 It's possible to disable the whole input.

src/components/FileInputField/__tests__/FileInputField.spec.tsx

@@ -13,7 +13,7 @@ test.describe('FileInputField', () => {
         ...propTests.defaultComponentPropTest,
         ...mixPropTests([
           propTests.disabledPropTest,
-          propTests.validationStatePropTest,
+          propTests.statePropTest,
         ]),
         ...fileSelectedPropTest,
         ...mixPropTests([

src/components/FileInputField/__tests__/_propTests/fileSelectedPropTest.ts

@@ -22,7 +22,7 @@ export const fileSelectedPropTest: PropTests = [
     onBeforeSnapshot,
     props,
   })),
-  ...propTests.validationStatePropTest.map(({
+  ...propTests.statePropTest.map(({
     name,
     props,
   }) => ({

src/components/FormLayout/FormLayoutCustomField.module.scss

@@ -19,16 +19,20 @@
     }
 
     // States
+    .isRootStateChanged {
+        @include variants.state(changed);
+    }
+
     .isRootStateInvalid {
-        @include variants.validation(invalid);
+        @include variants.state(invalid);
     }
 
     .isRootStateValid {
-        @include variants.validation(valid);
+        @include variants.state(valid);
     }
 
     .isRootStateWarning {
-        @include variants.validation(warning);
+        @include variants.state(warning);
     }
 
     // Layouts

src/components/FormLayout/FormLayoutCustomField.tsx

@@ -3,7 +3,7 @@ import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../helpers/classNames/classNames';
 import { transferProps } from '../../helpers/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
-import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
+import { getRootStateClassName } from '../_helpers/getRootStateClassName';
 import { isChildrenEmpty } from '../../helpers/isChildrenEmpty/isChildrenEmpty';
 import { FormLayoutContext } from './FormLayoutContext';
 import { FormLayoutCustomFieldContext } from './FormLayoutCustomFieldContext';
@@ -46,7 +46,7 @@ export const FormLayoutCustomField: React.FunctionComponent<FormLayoutCustomFiel
   label,
   labelForId,
   required = false,
-  validationState,
+  state,
   ...restProps
 }: FormLayoutCustomFieldProps) => {
   const context = useContext(FormLayoutContext);
@@ -65,7 +65,7 @@ export const FormLayoutCustomField: React.FunctionComponent<FormLayoutCustomFiel
         disabled && styles.isRootDisabled,
         required && styles.isRootRequired,
         getRootSizeClassName(styles, innerFieldSize),
-        getRootValidationStateClassName(styles, validationState),
+        getRootStateClassName(styles, state),
       )}
       id={id}
     >

src/components/FormLayout/FormLayoutCustomField.types.ts

@@ -4,7 +4,7 @@ import type {
 } from 'react';
 import type {
   Size,
-  ValidationState,
+  State,
 } from '../../types';
 
 /**
@@ -48,9 +48,10 @@ export type FormLayoutCustomFieldProps = HTMLAttributes<HTMLDivElement> & {
    */
   required?: boolean;
   /**
-   * Alter the field to provide feedback based on validation result.
+   * Alter the field to reflect the state of its data, e.g. a validation result or a change
+   * against the saved value.
    */
-  validationState?: ValidationState;
+  state?: State;
 };
 
 /**

src/components/FormLayout/README.md

@@ -119,7 +119,7 @@ React.createElement(() => {
           <TextField
             inputSize={6}
             label="ZIP"
-            validationState="invalid"
+            state="invalid"
             validationText="ZIP should be 5 to 6 digits long code."
           />
           <FormLayoutCustomField label="Country">
@@ -383,7 +383,7 @@ provide labels with optional feedback style.
 <FormLayout fieldLayout="horizontal" labelWidth="auto">
   <FormLayoutCustomField
     label="Custom field label in valid state"
-    validationState="valid"
+    state="valid"
   >
     <docoff-placeholder bordered>Custom field content</docoff-placeholder>
   </FormLayoutCustomField>