From e099f9fe3129f91d300b4ed7107358a2428190e9 Mon Sep 17 00:00:00 2001
From: Nikita Barsukov <nikita.s.barsukov@gmail.com>
Date: Mon, 23 Sep 2024 09:30:51 +0300
Subject: [PATCH] chore(demo): add description how to merge Maskito React ref
 with other 3d-party refs (#1656)

---
 .../react/examples/3-merge-ref/index.tsx      | 21 +++++
 .../frameworks/react/examples/merge-ref.md    | 21 +++++
 .../frameworks/react/react-doc.component.ts   |  5 +-
 .../frameworks/react/react-doc.style.less     | 11 +++
 .../frameworks/react/react-doc.template.html  | 87 +++++++++++--------
 5 files changed, 110 insertions(+), 35 deletions(-)
 create mode 100644 projects/demo/src/pages/frameworks/react/examples/3-merge-ref/index.tsx
 create mode 100644 projects/demo/src/pages/frameworks/react/examples/merge-ref.md
 create mode 100644 projects/demo/src/pages/frameworks/react/react-doc.style.less

diff --git a/projects/demo/src/pages/frameworks/react/examples/3-merge-ref/index.tsx b/projects/demo/src/pages/frameworks/react/examples/3-merge-ref/index.tsx
new file mode 100644
index 000000000..738b1b84d
--- /dev/null
+++ b/projects/demo/src/pages/frameworks/react/examples/3-merge-ref/index.tsx
@@ -0,0 +1,21 @@
+import type {MaskitoOptions} from '@maskito/core';
+import {useMaskito} from '@maskito/react';
+import type {ComponentType} from 'react';
+
+const digitsOnlyMask: MaskitoOptions = {
+    mask: /^\d+$/,
+};
+
+export const App: ComponentType = () => {
+    const maskitoRef = useMaskito({options: digitsOnlyMask});
+
+    return (
+        <input
+            ref={(node) => {
+                maskitoRef(node);
+                externalRef.current = node;
+            }}
+            placeholder="Enter a number"
+        />
+    );
+};
diff --git a/projects/demo/src/pages/frameworks/react/examples/merge-ref.md b/projects/demo/src/pages/frameworks/react/examples/merge-ref.md
new file mode 100644
index 000000000..1ed60c287
--- /dev/null
+++ b/projects/demo/src/pages/frameworks/react/examples/merge-ref.md
@@ -0,0 +1,21 @@
+```tsx
+import {useMaskito} from '@maskito/react';
+
+const options: MaskitoOptions = {
+  mask: /^\d+$/,
+};
+
+function App() {
+  const anyExternalRef = useRef(null);
+  const maskitoRef = useMaskito({options});
+
+  return (
+    <input
+      ref={(node) => {
+        maskitoRef(node);
+        anyExternalRef.current = node;
+      }}
+    />
+  );
+}
+```
diff --git a/projects/demo/src/pages/frameworks/react/react-doc.component.ts b/projects/demo/src/pages/frameworks/react/react-doc.component.ts
index ec29aee9d..3d1677bc7 100644
--- a/projects/demo/src/pages/frameworks/react/react-doc.component.ts
+++ b/projects/demo/src/pages/frameworks/react/react-doc.component.ts
@@ -20,6 +20,7 @@ import {ReactExample2} from './examples/2-element-predicate/example.component';
         TuiNotification,
     ],
     templateUrl: './react-doc.template.html',
+    styleUrls: ['./react-doc.style.less'],
     changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export default class ReactDocPageComponent {
@@ -28,6 +29,9 @@ export default class ReactDocPageComponent {
         './examples/1-use-maskito-basic-usage/use-maskito-basic-usage.tsx?raw'
     );
 
+    protected readonly controlledInputDemo = import('./examples/controlled-input.md?raw');
+    protected readonly mergeRefDemo = import('./examples/merge-ref.md?raw');
+
     protected readonly elementPredicateExample: Record<string, TuiRawLoaderContent> = {
         'index.tsx': import('./examples/2-element-predicate/index.tsx?raw'),
         'awesome-input.tsx': import(
@@ -35,6 +39,5 @@ export default class ReactDocPageComponent {
         ),
     };
 
-    protected readonly controlledInputDemo = import('./examples/controlled-input.md?raw');
     protected readonly bestBadPractice = import('./examples/best-bad-practice.md?raw');
 }
diff --git a/projects/demo/src/pages/frameworks/react/react-doc.style.less b/projects/demo/src/pages/frameworks/react/react-doc.style.less
new file mode 100644
index 000000000..677d96d2b
--- /dev/null
+++ b/projects/demo/src/pages/frameworks/react/react-doc.style.less
@@ -0,0 +1,11 @@
+.no-tabs {
+    padding-top: 0;
+
+    ::ng-deep .t-example {
+        margin-top: 0;
+    }
+}
+
+section {
+    margin-top: 3.5rem;
+}
diff --git a/projects/demo/src/pages/frameworks/react/react-doc.template.html b/projects/demo/src/pages/frameworks/react/react-doc.template.html
index 28133426f..92999e00e 100644
--- a/projects/demo/src/pages/frameworks/react/react-doc.template.html
+++ b/projects/demo/src/pages/frameworks/react/react-doc.template.html
@@ -12,7 +12,6 @@
     <tui-notification
         appearance="warning"
         size="m"
-        class="tui-space_top-6"
     >
         <div>
             <strong>Prerequisites</strong>
@@ -29,7 +28,7 @@
         </div>
     </tui-notification>
 
-    <section class="tui-space_top-12">
+    <section id="getting-started">
         <h2>Getting Started</h2>
 
         <p>Install libraries</p>
@@ -45,25 +44,69 @@ <h2>Getting Started</h2>
 
         <p>See the result of above code example in action:</p>
 
-        <tui-doc-example [style.padding-top.px]="0">
+        <tui-doc-example class="no-tabs">
             <react-example-1 />
         </tui-doc-example>
     </section>
 
-    <section class="tui-space_top-12">
+    <section id="controlled-input">
+        <h2>Controlled masked input</h2>
+
+        <p>
+            <strong>Maskito</strong>
+            core is developed as framework-agnostic library. It does not depend on any JS-framework's peculiarities. It
+            uses only native browser API. That is why you should use native
+            <code>onInput</code>
+            instead of React-specific
+            <code>onChange</code>
+            event. Do not worry, both events works similarly! Read more about it in the
+            <a
+                href="https://react.dev/reference/react-dom/components/input#props"
+                rel="noreferrer"
+                target="_blank"
+                tuiLink
+            >
+                official React documentation.
+            </a>
+        </p>
+
+        <tui-doc-code [code]="controlledInputDemo" />
+    </section>
+
+    <section id="merge-refs">
+        <h2>Merge Maskito ref with the third-party ref</h2>
+
+        <p>Do you need to use multiple hooks that return refs which both should be attached to the masked textfield?</p>
+
+        <p>
+            <strong>
+                Use
+                <a
+                    href="https://react.dev/reference/react-dom/components/common#ref-callback"
+                    rel="noreferrer"
+                    target="_blank"
+                    tuiLink
+                >
+                    ref callback
+                </a>
+                !
+            </strong>
+        </p>
+
+        <tui-doc-code [code]="mergeRefDemo" />
+    </section>
+
+    <section id="element-predicate">
         <h2>Query nested input element</h2>
 
         <p>
             Pass a predicate to
             <code>elementPredicate</code>
             to find input element for you, if you do not have a direct access to it. For example, you use component from
-            some UI Kit library.
+            some UI Kit library.
         </p>
 
-        <tui-notification
-            size="m"
-            class="tui-space_bottom-4"
-        >
+        <tui-notification size="m">
             <div>
                 By default
                 <strong>Maskito</strong>
@@ -81,31 +124,7 @@ <h2>Query nested input element</h2>
         </tui-doc-example>
     </section>
 
-    <section class="tui-space_top-12">
-        <h2>Controlled masked input</h2>
-
-        <p>
-            <strong>Maskito</strong>
-            core is developed as framework-agnostic library. It does not depend on any JS-framework's peculiarities. It
-            uses only native browser API. That is why you should use native
-            <code>onInput</code>
-            instead of React-specific
-            <code>onChange</code>
-            event. Do not worry, both events works similarly! Read more about it in the
-            <a
-                href="https://react.dev/reference/react-dom/components/input#props"
-                rel="noreferrer"
-                target="_blank"
-                tuiLink
-            >
-                official React documentation.
-            </a>
-        </p>
-
-        <tui-doc-code [code]="controlledInputDemo" />
-    </section>
-
-    <section class="tui-space_top-12">
+    <section>
         <h2>Best practices & Anti-Patterns</h2>
 
         <p>