Short docs to explain API (#73)

* Shor docs to explain API * fix * fix * react ver * Fixes * Fix * Fix * fix spaces * spaces * spaces * fix * fix * Fix * Fix * Fix * Fix this- these * Add then * Improve * Fix * fix * Fix anchors * Explicit types * HeadingProps * Update * Fix * Simplify text * Fix mask definition * Fix date-format * Add links * Add replace desription * Update text
realadvisor · Jun 3, 2019 · 6f1a916 · 6f1a916
1 parent 53da208
commit 6f1a916
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -7,11 +7,14 @@ into formatted or masked input.
 
 ## Highlights
 
-- Requires React 16.4+
+- Requires React 16.8+
 - Dependency free
 - Tiny (≈ 800b)
 - Supports any [input](https://istarkov.github.io/rifm#material-ui).
-- Can mask input and format
+- Can [mask](https://istarkov.github.io/rifm#date-format) input,
+  [format](https://istarkov.github.io/rifm#number-format) and [more](https://istarkov.github.io/rifm#case-enforcement)
+- Small readable source
+- flow + typescript definitions
 
 ## Example
 
@@ -54,6 +57,57 @@ const numberFormat = (str: string) => {
 yarn add rifm
 ```
 
+## API
+
+### Terminology
+
+Rifm is based on few simple ideas (**\***):
+
+- format operation doesn't change the order of some symbols after edit
+- all that symbols are placed before input cursor position
+
+**\*** _These ideas are not always true, but we solve some edge cases where it's not._
+
+> Imagine you have simple integer number formatter with **\`** as thousands separator
+> and current input state is _123\`4_**|**_67_ _("|" shows current cursor position)_.
+>
+> User press _5_ then formatted input must be equal to _1\`234\`5_**|**_67_.
+>
+> The overall order of elements has changed (was _1->2->3->\`->4->..._ became _1->\`->2->3->4..._)
+> but the order of digits before cursor hasn't changed (was _1->2->3->4_ and hasn't changed).
+
+The same is true for float numbers formatting, dates and more.
+Symbols with preserved order are different and depends on format.
+We call this kind of symbols - **"accepted"** symbols.
+
+Rifm solves only one task -
+find the right place for cursor after formatting.
+
+Knowledge about what symbols are **"accepted"** and cursor position after any user action
+is enough to find the final cursor position.
+
+Most operations which are not covered with above ideas like
+case enforcements, masks guides, floating point _","=>"."_ replacement
+can be done using simple postprocessing step - replace.
+This operation works well if you need to change input value without loosing cursor position.
+
+And finaly masks - masks are usually is nothing more
+than format with replace editing mode + some small cursor visual hacks.
+
+### Props
+
+| Prop         | type                          | default | Description                                                                         |
+| ------------ | :---------------------------- | :------ | :---------------------------------------------------------------------------------- |
+| **accept**   | RegExp (optional)             | /\d/g   | Regular expression to detect **"accepted"** symbols                                 |
+| **format**   | string => string              |         | format function                                                                     |
+| **value**    | string                        |         | input value                                                                         |
+| **onChange** | string => void                |         | event fired on input change                                                         |
+| **children** | ({ value, onChange }) => Node |         | value and onChange handler you need to pass to underlying input element             |
+| **mask**     | boolean (optional)            |         | use replace input mode if true, use cursor visual hacks if prop provided            |
+| **replace**  | string => string (optional)   |         | format postprocessor allows you to fully replace any/all symbol/s preserving cursor |
+
+See the [Demo](https://istarkov.github.io/rifm) there are a lot of examples there.
+
 ## Thanks
 
 [@TrySound](https://github.com/TrySound) for incredible help and support on this
diff --git a/pages/date-format/index.js b/pages/date-format/index.js
@@ -32,7 +32,9 @@ const formatDateOther = string => {
   return res;
 };
 
-const formatDateWithMask = string => {
+// const addMaskedSymbols = string => string + '________';
+
+const addMask = string => {
   const digits = parseDigits(string);
   const days = digits.slice(0, 2).padEnd(2, '_');
   const months = digits.slice(2, 4).padEnd(2, '_');
@@ -77,7 +79,9 @@ const Example = () /*:React.Node*/ => {
         <div>Date format with mask</div>
         <Rifm
           accept={/[\d]/g}
-          format={formatDateWithMask}
+          mask={true}
+          format={formatDate}
+          replace={addMask}
           value={masked}
           onChange={setMasked}
         >

diff --git a/pages/index.js b/pages/index.js
@@ -38,17 +38,22 @@ const GithubIcon = ({ size }) => {
   );
 };
 
-const H1 = ({ children }) => {
+type HeadingProps = {|
+  children: React.Node,
+  id?: string,
+|};
+
+const H1 = ({ children, id }: HeadingProps) => {
   return (
-    <Typography variant="h2" gutterBottom>
+    <Typography variant="h2" gutterBottom id={id}>
       {children}
     </Typography>
   );
 };
 
-const H2 = ({ children }) => {
+const H2 = ({ children, id }: HeadingProps) => {
   return (
-    <Typography variant="h4" gutterBottom>
+    <Typography variant="h4" gutterBottom id={id}>
       {children}
     </Typography>
   );