Merge pull request #121 from x0k/fix-120

[docs] Add a note about the explicit use of `extra` widgets (#120)

Author: x0k

.changeset/curvy-buttons-float.md

@@ -0,0 +1,5 @@
+---
+"docs2": patch
+---
+
+Add a note about the explicit use of `extra` widgets (#120)

apps/docs2/src/content/docs/form/ui-schema.mdx

@@ -57,7 +57,7 @@ export type UiSchemaRoot = UiSchemaDefinition & {
 ```
 ## Evaluation rules
 
-Usually ui schema corresponds to the data structure described by json schema.
+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:
 
@@ -88,12 +88,12 @@ for the value of the `$ref` key, other fields will be ignored.
 
 ### 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.
+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.
+to specify the UI schema for them.
 
 ```
 {
@@ -104,24 +104,46 @@ to specify the ui schema for them.
 
 ### Object
 
-You should use `additionalProperties` keyword to specify the ui schema for
+You should use `additionalProperties` keyword to specify the UI schema for
 additional properties.
 
-You can use `additionalPropertyKeyInput` keyword to define an ui schema for
+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.
+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>, ...]
 }
 ```
 
+## UI components
+
+Using the `ui:components` property, you can replace any
+[form component](../theme/#component-types) with a compatible one
+using the name of the connected component or
+the component itself directly.
+
+Component `A` is compatible with component `B` if the properties and bindings
+of component `B` extend the properties and bindings of component `A`.
+
+```ts
+export type CompatibleComponentType<T extends ComponentType> = {
+  [C in ComponentType]: Expand<ComponentProps[T]> extends Expand<
+    ComponentProps[C]
+  >
+    ? ComponentBindings[T] extends ComponentBindings[C]
+      ? C
+      : never
+    : never;
+}[ComponentType];
+```
+
 ## UI options
 
 The `UiOptions` type is an extensible set of components options. By default it

apps/docs2/src/content/docs/themes/_demo-schema.ts

@@ -3,7 +3,7 @@ import type { ComponentDefinition, Schema, UiSchema } from "@sjsf/form";
 import FilesField from "@sjsf/form/fields/extra-fields/files.svelte";
 import { s } from "testing/demo";
 
-import { THEME_PACKAGES, type Theme } from '@/shared';
+import { THEME_PACKAGES, type Theme } from "@/shared";
 
 const filesAsArrayField = cast(FilesField, {
   value: {
@@ -14,9 +14,23 @@ const filesAsArrayField = cast(FilesField, {
   },
 }) satisfies ComponentDefinition<"arrayField">;
 
+const WIDGET_USED_AS_DEFAULT_IN_FIELDS: Record<string, string[] | undefined> = {
+  checkboxes: ["multiEnumField"],
+  file: ["fileField", "filesField"],
+  tags: ["tagsField"],
+};
+
 export function createExtraImports(theme: Theme, widgets: string[]) {
   return widgets
-    .map((w) => `import "${THEME_PACKAGES[theme]}/extra-widgets/${w}-include"`)
+    .map((w) => {
+      const line = `import "${THEME_PACKAGES[theme]}/extra-widgets/${w}-include"`;
+      const fields = WIDGET_USED_AS_DEFAULT_IN_FIELDS[w];
+      return fields
+        ? `// Used by default in the following fields: ${fields.join(
+            ", "
+          )}\n${line}`
+        : line;
+    })
     .join("\n");
 }
 

apps/docs2/src/content/docs/themes/basic.mdx

@@ -25,6 +25,14 @@ export const schemas = createSchemas(specs)
 
 You can connect extra widgets using the following `include` imports:
 
+:::note
+
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
 <Code lang='ts' code={createExtraImports("basic", extraWidgets)} />
 
 ## UI options

apps/docs2/src/content/docs/themes/daisyui.mdx

@@ -66,6 +66,14 @@ import daisyStyles from "@sjsf/daisyui-theme/styles.css?inline";
 
 You can connect extra widgets using the following `include` imports:
 
+:::note
+
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
 <Code lang='ts' code={createExtraImports("daisyui", extraWidgets)} />
 
 ## UI options

apps/docs2/src/content/docs/themes/daisyui5.mdx

@@ -50,6 +50,14 @@ You can connect extra widgets using the following `include` imports:
 
 :::note
 
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
+:::caution
+
 The following widgets `radio-buttons` and `filter-radio-buttons`,
 `cally-date-picker` and `pikaday-date-picker` replace each other -
 use one or import the replacement widget directly.

apps/docs2/src/content/docs/themes/flowbite.mdx

@@ -70,6 +70,14 @@ import flowbiteStyles from "@sjsf/flowbite-theme/styles.css?inline";
 
 You can connect extra widgets using the following `include` imports:
 
+:::note
+
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
 <Code lang='ts' code={createExtraImports("flowbite", extraWidgets)} />
 
 ## UI options

apps/docs2/src/content/docs/themes/flowbite3.mdx

@@ -52,6 +52,14 @@ Register the theme source path by adding a line like this to the `app.css` file.
 
 You can connect extra widgets using the following `include` imports:
 
+:::note
+
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
 <Code lang='ts' code={createExtraImports("flowbite3", extraWidgets)} />
 
 ## UI options

apps/docs2/src/content/docs/themes/shadcn.mdx

@@ -94,6 +94,14 @@ You can connect extra widgets using the following `include` imports:
 
 :::note
 
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
+:::caution
+
 The following widgets `combobox` and `select` replace each other -
 use one or import the replacement widget directly.
 

apps/docs2/src/content/docs/themes/shadcn4.mdx

@@ -74,6 +74,14 @@ You can connect extra widgets using the following `include` imports:
 
 :::note
 
+For a widget to be applied, it must be explicitly specified in the
+[UI schema](../../form/ui-schema/#ui-components)
+or used in the field as the default widget.
+
+:::
+
+:::caution
+
 The following widgets `combobox` and `select` replace each other -
 use one or import the replacement widget directly.