fix: Fixed 3478 and 3520 by updating documentation

Fixes rjsf-team#3478 and rjsf-team#3520 by updating documentation
- Updated the root `package.json` to change `npm start` to documentation about the new process
- Updated the `package.json` files to remove the `npm start` script in all packages that had them except for `playground` and `docs`
  - Added `lint-staged`, `cs-check` and `cs-format` in the `docs` directory to format files
  - Fixed up the `lint-staged`, `cs-check` and `cs-format` rules in the `playground` to simplify the globs for the real content
- Added documentation for `getTestValidator()` in `utils`, `validator-ajv6` and `validator-ajv8` to better describe how validator tests work
  - Same for `schema.test.ts`
- Updated the `internals` documentation to switch to using a React ref
- Updated the `contributing` documentation to cover the new development process with `Vite` as well as trying to improve the understanding of validator testing
- Updated the `CHANGELOG.md` accordingly

CHANGELOG.md

@@ -22,6 +22,24 @@ should change the heading of the (upcoming) version to include a major version b
 
 - Updated `AltDateWidget` to remove an infinite loop caused by two conflicting effects by merging them with additional checking of original `value` against the current value, fixing [#3516](https://github.com/rjsf-team/react-jsonschema-form/issues/3516)
 
+## @rjsf/utils
+
+- Updated the documentation of `getTestValidator()` and the `schema.test.ts` file to help developers
+
+## @rjsf/validator-ajv6
+
+- Updated the documentation of `getTestValidator()` and the `schema.test.ts` file to help developers
+
+## @rjsf/validator-ajv8
+
+- Updated the documentation of `getTestValidator()` and the `schema.test.ts` file to help developers
+
+## Dev / docs / playground
+
+- Updated the `internals` documentation to use a React ref in the example, fixing [#3520](https://github.com/rjsf-team/react-jsonschema-form/issues/3520)
+- Updated the `contributing` documentation to describe the new development process needed for a `Vite` playground, fixing [#3478](https://github.com/rjsf-team/react-jsonschema-form/issues/3478)
+  - Also fixed the `package.json` files to remove `npm start` in the subdirectories and change the root one to describe the new process
+
 # 5.3.0
 
 ## @rjsf/antd

package.json

@@ -16,7 +16,7 @@
     "cs-format": "lerna run cs-format",
     "build": "lerna run --stream build",
     "build-serial": "lerna run --concurrency 1 --stream build",
-    "start": "lerna run start --stream --parallel",
+    "start": "echo 'use \"npm run build\" from main directory and then \"npm start\" in the playground package'",
     "pre-commit:husky": "lerna run --concurrency 1 --stream precommit",
     "prepare": "husky install",
     "format": "prettier --write .",

packages/antd/package.json

@@ -6,7 +6,6 @@
   "module": "dist/antd.esm.js",
   "typings": "dist/index.d.ts",
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/bootstrap-4/package.json

@@ -13,7 +13,6 @@
     "url": ""
   },
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/chakra-ui/package.json

@@ -9,7 +9,6 @@
     "dist"
   ],
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/core/package.json

@@ -9,7 +9,6 @@
     "lint": "eslint src test",
     "precommit": "lint-staged",
     "publish-to-npm": "npm run build && npm publish",
-    "start": "dts watch",
     "test": "dts test",
     "test:debug": "node --inspect-brk node_modules/.bin/dts test",
     "test:watch": "dts test --watch",

packages/docs/docs/advanced-customization/internals.md

@@ -79,7 +79,9 @@ You can use the reference to get your `Form` component and call the `submit` met
 This method will dispatch the `submit` event of the form, and the function, that is passed to `onSubmit` props, will be called.
 
 ```tsx
+import { createRef } from 'react';
 import { RJSFSchema, UiSchema } from '@rjsf/utils';
+import { Form } from '@rjsf/core';
 import validator from '@rjsf/validator-ajv8';
 
 const onSubmit = ({ formData }) => console.log('Data submitted: ', formData);
@@ -89,17 +91,17 @@ const schema: RJSFSchema = {
   type: 'string',
 };
 
+const formRef = createRef<Form>();
+
 render(
   <Form
     schema={schema}
     validator={validator}
     onSubmit={onSubmit}
-    ref={(form) => {
-      yourForm = form;
-    }}
+    ref={formRef}
   />,
   document.getElementById('app')
 );
 
-yourForm.submit();
+formRef.current.submit();
 ```

packages/docs/docs/contributing.md

@@ -2,15 +2,21 @@
 
 ## Development server
 
-When developing, run the following from the root-level directory:
+We are using `Vite` to power our `playground`, which caches all the built `@rjsf/*` distributions.
+In order to test the `playground` locally after a new clone or fresh pull from `main`, run the following from the root directory of the monorepo:
 
 ```bash
 npm install
 npm run build
+cd packages/playground
 npm start
 ```
 
-All packages will be live-built, and a live development server showcasing components with hot reload enabled will then run at [localhost:8080](http://localhost:8080).
+This will start the live development server showcasing components at [localhost:8080](http://localhost:8080).
+
+Whenever you make changes to source code, stop the running playground and return to the root directory and rerun `npm run build`.
+Thanks to `nx` caching, this should only rebuild what is necessary.
+After the build is complete, return to the root of the `playground` and restart the server via `npm start`.
 
 ### First time step
 
@@ -32,6 +38,8 @@ When building in environments with limited memory, such as Netlify, it's recomme
 All the JavaScript/Typescript code in this project conforms to the [prettier](https://github.com/prettier/prettier) coding style.
 Code is automatically prettified upon commit using precommit hooks, assuming you followed the `First time step` above.
 
+You can also run `npm cs-format` within any package directory you are changing.
+
 ## Documentation
 
 We use [Docusaurus](https://docusaurus.io/) to build our documentation. To run documentation locally, run:
@@ -45,8 +53,10 @@ Documentation will be served on [localhost:3000](http://localhost:3000).
 
 ## Tests
 
+You can run all tests from the root directory OR from `packages` subdirectory using the following command:
+
 ```bash
-npm test
+npm run test
 ```
 
 ### Code coverage
@@ -60,6 +70,8 @@ The full report can be seen by opening `./coverage/lcov-report/index.html`.
 100% code coverage is required by the `@rjsf/utils` and `@rjsf/validator-ajv6` and `@rjsf/validator-ajv8` tests.
 If you make changes to those libraries, you will have to maintain that coverage, otherwise the tests will fail.
 
+> NOTE: All three of these directories share the same tests for verifying `validator` based APIs. See the documentation in the `getTestValidator()` functions for more information. 
+
 ## Releasing
 
 To release, go to the main branch and then create a new branch with the version number (with an `rc` prefix instead of `v`):

packages/docs/package.json

@@ -12,7 +12,17 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "cs-check": "prettier -l \"{src, docs}/**/*.(ts?(x)|md|css)\"",
+    "cs-format": "prettier \"{src, docs}/**/*.(ts?(x)|md|css)\" --write"
+  },
+  "lint-staged": {
+    "src/**/*.(ts?(x)|css)": [
+      "prettier --write"
+    ],
+    "docs/**/*.md": [
+      "prettier --write"
+    ]
   },
   "dependencies": {
     "@docusaurus/core": "^2.3.1",

packages/fluent-ui/package.json

@@ -9,7 +9,6 @@
     "dist"
   ],
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/material-ui/package.json

@@ -9,7 +9,6 @@
     "dist"
   ],
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/mui/package.json

@@ -9,7 +9,6 @@
     "dist"
   ],
   "scripts": {
-    "start": "dts watch",
     "build": "rimraf dist && dts build --rollupTypes --format cjs,esm,umd",
     "cs-check": "prettier -l \"{src,test}/**/*.ts?(x)\"",
     "cs-format": "prettier \"{src,test}/**/*.ts?(x)\" --write",

packages/utils/test/schema.test.ts

@@ -16,6 +16,7 @@ import {
 
 const testValidator = getTestValidator({});
 
+// NOTE: to restrict which tests to run, you can temporarily comment out any tests you aren't needing
 getDefaultFormStateTest(testValidator);
 getDisplayLabelTest(testValidator);
 getClosestMatchingOptionTest(testValidator);

packages/utils/test/testUtils/getTestValidator.ts

@@ -1,9 +1,19 @@
 import { RJSFValidationError, ValidationData } from '../../src';
 import { TestValidatorParams, TestValidatorType } from '../schema/types';
 
+/** A test validator implements the `ValidatorType` interface needed by all the `schema` based tests. Inside the `utils`
+ * directory, there is no actual validator implementation, so it can be necessary to mock the expected return values
+ * of the `validateFormData()`, `isValid()` and `errorList()` APIs to imitate what is expected from the real validator
+ * implementations. The `setReturnValue()` function is used to set up this mocked data. It may take a some investigation
+ * of the actual `validator` implementations to understand how to set the mocks when writing or updating tests. Feel
+ * free to run the validator tests first if you aren't sure whether your mocks are correct.
+ *
+ * All tests that use the `TestValidator` are contained within the `@rjsf/utils/test/schema` directory and are run via
+ * the `schema.test.ts` file.
+ */
 export default function getTestValidator<T = any>({
-  isValid = [],
   data = [],
+  isValid = [],
   errorList = [],
 }: TestValidatorParams): TestValidatorType {
   const testValidator: {

packages/validator-ajv6/test/utilsTests/getTestValidator.ts

@@ -10,6 +10,12 @@ import {
 import { TestValidatorType } from '@rjsf/utils/test/schema';
 import { customizeValidator, CustomValidatorOptionsType } from '../../src';
 
+/** In this environment, a test validator merely creates an internal `AJV6` validator with the custom `options` and
+ * then forwards all calls into it. It is provided to mirror the test validator in the `utils` directory, except that
+ * the `setReturnValues()` function does nothing.
+ *
+ * @param options
+ */
 export default function getTestValidator<T = any>(options: CustomValidatorOptionsType): TestValidatorType {
   const validator = customizeValidator<T>(options);
   return {

packages/validator-ajv6/test/utilsTests/schema.test.ts

@@ -17,6 +17,7 @@ import getTestValidator from './getTestValidator';
 
 const testValidator = getTestValidator({});
 
+// NOTE: to restrict which tests to run, you can temporarily comment out any tests you aren't needing
 getDefaultFormStateTest(testValidator);
 getDisplayLabelTest(testValidator);
 getClosestMatchingOptionTest(testValidator);

packages/validator-ajv8/test/utilsTests/getTestValidator.ts

@@ -10,6 +10,12 @@ import {
 import { TestValidatorType } from '@rjsf/utils/test/schema';
 import { customizeValidator, CustomValidatorOptionsType } from '../../src';
 
+/** In this environment, a test validator merely creates an internal `AJV8` validator with the custom `options` and
+ * then forwards all calls into it. It is provided to mirror the test validator in the `utils` directory, except that
+ * the `setReturnValues()` function does nothing.
+ *
+ * @param options
+ */
 export default function getTestValidator<T = any>(options: CustomValidatorOptionsType): TestValidatorType {
   const validator = customizeValidator<T>(options);
   return {

packages/validator-ajv8/test/utilsTests/schema.test.ts

@@ -19,6 +19,7 @@ import getTestValidator from './getTestValidator';
 
 const testValidator = getTestValidator({});
 
+// NOTE: to restrict which tests to run, you can temporarily comment out any tests you aren't needing
 getDefaultFormStateTest(testValidator);
 getDisplayLabelTest(testValidator);
 getClosestMatchingOptionTest(testValidator);
@@ -34,6 +35,7 @@ toPathSchemaTest(testValidator);
 
 const testValidator2019 = getTestValidator({ AjvClass: Ajv2019 });
 
+// NOTE: to restrict which tests to run, you can temporarily comment out any tests you aren't needing
 getDefaultFormStateTest(testValidator2019);
 getDisplayLabelTest(testValidator2019);
 getClosestMatchingOptionTest(testValidator2019);
@@ -49,6 +51,7 @@ toPathSchemaTest(testValidator2019);
 
 const testValidator2020 = getTestValidator({ AjvClass: Ajv2020 });
 
+// NOTE: to restrict which tests to run, you can temporarily comment out any tests you aren't needing
 getDefaultFormStateTest(testValidator2020);
 getDisplayLabelTest(testValidator2020);
 getClosestMatchingOptionTest(testValidator2020);