docs: improve useFilesFieldProps

src/Intro.contents.md

@@ -45,6 +45,7 @@
 | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | [useClearInputAction](?path=/docs/hooks-useclearinputaction--docs)     | Hook providing action to clear input value via its ref.                                  |
 | [useCheckboxFieldProps](?path=/docs/hooks-usecheckboxfieldprops--docs) | Adapts fields having `boolean` values to controlled checkbox inputs.                     |
+| [useFilesFieldProps](?path=/docs/hooks-useFilesfieldprops--docs)       | Adapts fields having `File[]` values to controlled `input[type=file]`.                   |
 | [useNumberFieldProps](?path=/docs/hooks-usenumberfieldprops--docs)     | Adapts fields having `number` values to controlled numeric inputs.                       |
 | [useOptions](?path=/docs/hooks-useoptions--docs)                       | A data hook to evaluate which of option(s) is(are) active with respect to a field.       |
 | [useRequiredProps](?path=/docs/hooks-userequiredprops--docs)           | Provides the `required` prop for input based on field optionality.                       |

src/fields/files-field/Docs.mdx

@@ -23,40 +23,12 @@ const profilePic = filesField({
 const attachments = filesField().optional();
 ```
 
+Usable with [useFilesFieldProps()](?path=/docs/hooks-useFilesfieldprops--docs)
+
 ## Initial Config
 
 <Markdown>{Config}</Markdown>
 
 > **NOTE:** the `File` API is not available on the server side, so in practice the schema is defined as `z.array(isServer ? z.never() : z.instanceof(File)`.
 
-## useFilesFieldProps(filesField)
-
-A hook providing props to control a file input.
-
-### Features
-
-- ✅ Clears the file input, when the form is reset.
-
-```tsx
-const FileInput = ({
-  field,
-  label,
-}: {
-  field: FilesFieldAtom;
-  label: ReactNode;
-}) => {
-  const props = useFilesFieldProps(field);
-
-  return (
-    <div style={{ margin: "20px 0" }}>
-      <FieldLabel field={field} label={label} />
-      <input type="file" {...props} />
-      <div>
-        <FieldErrors field={field} />
-      </div>
-    </div>
-  );
-};
-```
-
 <Stories />

src/hooks/use-files-field-props/Docs.mdx

@@ -0,0 +1,38 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="hooks/useFilesFieldProps" />
+
+# `useFilesFieldProps(field: FilesField)`
+
+A hook to control the file inputs e.g. `input[type=file]`.
+
+```ts
+import { useFilesFieldProps } from "@form-atoms/field";
+```
+
+Works with
+
+- [filesField()](?path=/docs/fields-filesField--docs)
+
+### Features
+
+- ✅ **Reads the `event.files` value** from the event handler.
+- ✅ **Clears the file input**, when the form is reset.
+
+### Example Usage
+
+```tsx
+import { FilesField, useFilesFieldProps } from "@form-atoms/field";
+
+const FileInputMock = ({
+  field,
+  label,
+}: {
+  field: FilesField;
+  label: ReactNode;
+}) => {
+  const props = useFilesFieldProps(field);
+
+  return <input type="file" {...props} />;
+};
+```