From b976705f8e33e83faca542d16a134e19bc2d7aa1 Mon Sep 17 00:00:00 2001
From: Miroslav Petrik <miroslavpetrik@outlook.com>
Date: Tue, 5 Dec 2023 15:29:50 +0100
Subject: [PATCH] docs: improve useNumberFieldProps

---
 src/Intro.contents.md                     |  3 +-
 src/fields/number-field/Docs.mdx          | 26 +------------
 src/hooks/use-number-field-props/Docs.mdx | 45 +++++++++++++++++++++++
 3 files changed, 49 insertions(+), 25 deletions(-)
 create mode 100644 src/hooks/use-number-field-props/Docs.mdx

diff --git a/src/Intro.contents.md b/src/Intro.contents.md
index dd105cd..fc4b393 100644
--- a/src/Intro.contents.md
+++ b/src/Intro.contents.md
@@ -44,7 +44,8 @@
 |                                                                        |                                                                                          |
 | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | [useClearInputAction](?path=/docs/hooks-useclearinputaction--docs)     | Hook providing action to clear input value via its ref.                                  |
-| [useCheckboxFieldProps](?path=/docs/hooks-usecheckboxfieldprops--docs) | Controls fields having `boolean` values                                                  |
+| [useCheckboxFieldProps](?path=/docs/hooks-usecheckboxfieldprops--docs) | Adapts fields having `boolean` values to controlled checkbox inputs.                     |
+| [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.                       |
 | [useSelectFieldProps](?path=/docs/hooks-useselectfieldprops--docs)     | A generic hook to manage a field holding active option from primitive options.           |
diff --git a/src/fields/number-field/Docs.mdx b/src/fields/number-field/Docs.mdx
index d249ec0..645b895 100644
--- a/src/fields/number-field/Docs.mdx
+++ b/src/fields/number-field/Docs.mdx
@@ -18,32 +18,10 @@ const heightCentimeters = numberField({
 const tipAmount = numberField().optional();
 ```
 
+Usable with [useNumberFieldProps()](?path=/docs/hooks-useNumberFieldProps--docs)
+
 ## Initial Config
 
 <Markdown>{Config}</Markdown>
 
-## useNumberFieldProps(numberField)
-
-A hook providing props to control a number input.
-
-```tsx
-const NumberInput = ({
-  field,
-  label,
-}: {
-  field: NumberFieldAtom;
-  label: ReactNode;
-}) => {
-  const props = useNumberFieldProps(field);
-
-  return (
-    <div style={{ margin: "20px 0" }}>
-      <FieldLabel field={field} label={label} />
-      <input type="number" {...props} />
-      <FieldErrors field={field} />
-    </div>
-  );
-};
-```
-
 <Stories />
diff --git a/src/hooks/use-number-field-props/Docs.mdx b/src/hooks/use-number-field-props/Docs.mdx
new file mode 100644
index 0000000..8c000b8
--- /dev/null
+++ b/src/hooks/use-number-field-props/Docs.mdx
@@ -0,0 +1,45 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="hooks/useNumberFieldProps" />
+
+# `useNumberFieldProps(field: NumberField)`
+
+A hook to control the numeric inputs e.g. `input[type=number]`, `input[type=range]`.
+
+```ts
+import { useNumberFieldProps } from "@form-atoms/field";
+```
+
+Works with
+
+- [numberField()](?path=/docs/fields-numberField--docs)
+- [digitField()](?path=/docs/fields-digitfield--docs)
+
+### Features
+
+- ✅ **Reads the `event.valueAsNumber` value** from the event handler.
+- ✅ Normalizes the the empty `NaN` value.
+
+### Example Usage
+
+```tsx
+import { NumberField, useNumberFieldProps } from "@form-atoms/field";
+
+const NumberInput = ({
+  field,
+  label,
+}: {
+  field: NumberField;
+  label: ReactNode;
+}) => {
+  const props = useNumberFieldProps(field);
+
+  return (
+    <div style={{ margin: "20px 0" }}>
+      <FieldLabel field={field} label={label} />
+      <input type="number" {...props} />
+      <FieldErrors field={field} />
+    </div>
+  );
+};
+```