[docs] Add ui schema evaluation rules paragraph

Author: x0k

.changeset/three-donuts-move.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+Add ui schema evaluation rules paragraph

apps/docs/src/content/docs/api-reference/_ui-schema-example.ts

@@ -0,0 +1,29 @@
+import type { Schema, UiSchemaRoot } from "@sjsf/form";
+
+const schema: Schema = {
+  oneOf: [
+    {
+      properties: {
+        foo: {
+          type: "string",
+        },
+      },
+    },
+    {
+      properties: {
+        bar: {
+          type: "number",
+        },
+      },
+    },
+  ],
+};
+
+const uiSchema: UiSchemaRoot = {
+  foo: {
+    // ui schema for `foo` field
+  },
+  bar: {
+    // ui schema for `bar` field
+  },
+};

apps/docs/src/content/docs/api-reference/ui-schema.mdx

@@ -4,6 +4,10 @@ sidebar:
   order: 2
 ---
 
+import { Code } from '@astrojs/starlight/components'
+
+import uiSchemaExampleCode from './_ui-schema-example.ts?raw'
+
 UI schema allows you to customize the appearance of the form and influence its behavior.
 
 The UI schema object follows the tree structure of the form field hierarchy, and defines how each property should be rendered.
@@ -130,3 +134,49 @@ interface UiOptions {
   emptyValue?: SchemaValue;
 }
 ```
+
+## UI schema evaluation rules
+
+Usually ui schema corresponds to the data structure described by json schema.
+
+For example, with this json schema, the following ui schema would be correct:
+
+<Code code={uiSchemaExampleCode} lang="typescript" />
+
+Special cases:
+
+### Array
+
+Instead of defining indices in the ui schema, the `items` keyword should be used
+to specify the ui schema for the elements of the array.
+
+For a fixed array `items` also can be an array.
+If you have additional items you should use `additionalItems` keyword
+to specify the ui schema for them.
+
+```
+{
+  items: [<uiSchema>, ...],
+  additionalItems: <uiSchema>
+}
+```
+
+### Object
+
+You should use `additionalProperties` keyword to specify the ui schema for
+additional properties.
+
+You can use `additionalPropertyKeyInput` keyword to define an ui schema for
+the additional property key input field.
+
+### oneOf/anyOf
+
+You can define separate ui schemas for each `oneOf/anyOf` branch
+using the corresponding keyword in the ui schema.
+Otherwise the ui schema of the current field will be used.
+
+```
+{
+  oneOf: [<uiSchema>, ...]
+}
+```