From 6500441ad1fb66116b9cb5f6afffaf16ec5866ff Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sun, 19 Nov 2023 14:36:30 +0800
Subject: [PATCH] docs: update textarea

---
 .../pages/components/textarea.page.mdx        | 199 ------------------
 .../components/textarea/attribute-disabled.js |  11 +
 .../components/textarea/attribute-readonly.js |  11 +
 .../components/textarea/attribute-required.js |   8 +
 .../pages/components/textarea/basic.js        |  12 ++
 .../pages/components/textarea/index.page.mdx  |  78 +++++++
 .../pages/components/textarea/sizing.js       |  38 ++++
 .../pages/components/textarea/validation.js   |  68 ++++++
 .../components/textarea/variant-filled.js     |   8 +
 .../components/textarea/variant-outline.js    |   8 +
 .../components/textarea/variant-unstyled.js   |   8 +
 11 files changed, 250 insertions(+), 199 deletions(-)
 delete mode 100644 packages/react-docs/pages/components/textarea.page.mdx
 create mode 100644 packages/react-docs/pages/components/textarea/attribute-disabled.js
 create mode 100644 packages/react-docs/pages/components/textarea/attribute-readonly.js
 create mode 100644 packages/react-docs/pages/components/textarea/attribute-required.js
 create mode 100644 packages/react-docs/pages/components/textarea/basic.js
 create mode 100644 packages/react-docs/pages/components/textarea/index.page.mdx
 create mode 100644 packages/react-docs/pages/components/textarea/sizing.js
 create mode 100644 packages/react-docs/pages/components/textarea/validation.js
 create mode 100644 packages/react-docs/pages/components/textarea/variant-filled.js
 create mode 100644 packages/react-docs/pages/components/textarea/variant-outline.js
 create mode 100644 packages/react-docs/pages/components/textarea/variant-unstyled.js

diff --git a/packages/react-docs/pages/components/textarea.page.mdx b/packages/react-docs/pages/components/textarea.page.mdx
deleted file mode 100644
index 90a92350f5..0000000000
--- a/packages/react-docs/pages/components/textarea.page.mdx
+++ /dev/null
@@ -1,199 +0,0 @@
-# Textarea
-
-The `Textarea` component allows you to create a multi-line text input.
-
-## Import
-
-```js
-import { Textarea } from '@tonic-ui/react';
-```
-
-## Usage
-
-```jsx
-<>
-  <TextLabel mb="1x">Label:</TextLabel>
-  <Textarea placeholder="Basic example" />
-  <Text size="xs" mt="1x">Help text for the text input</Text>
-</>
-```
-
-### Sizing
-
-* The `rows` and `cols` properties allow you to specify an exact size for the `<Textarea>` to take. Setting these is a good idea for consistency, as browser defaults can differ.
-* The `maxLength` property specifies a maximum number of characters that the `Textarea` is allowed to contain.
-* The `minLength` property specifies a minimum length that is considered valid. `Textarea` will not submit (and is invalid) if it is empty, using the `required` attribute.
-* The `resize` property to set whether the `Textarea` is resizable, and if so, in which directions. You can set the value to `none`, `both`, `horizontal`, or `vertical`.
-
-```jsx
-
-function Example() {
-  const [resize, setResize] = React.useState('both');
-
-  return (
-    <>
-      <Flex alignItems="center" mb="5x">
-        <TextLabel>resize =</TextLabel>
-        <Space width="2x" />
-        <Stack direction="row" spacing="2x">
-          {['none', 'both', 'horizontal', 'vertical'].map(value => (
-            <Button
-              key={value}
-              variant={resize === value ? 'primary' : 'secondary'}
-              onClick={() => setResize(value)}
-            >
-              {value}
-            </Button>
-          ))}
-        </Stack>
-      </Flex>
-      <Textarea
-        defaultValue="Placeholder text"
-        width="auto"
-        resize={resize}
-        rows="3"
-        cols="12"
-        minLength={4}
-        maxLength={16}
-        transition="none"
-      />
-    </>
-  );
-}
-```
-
-### Variants
-
-The `Textarea` component comes in 3 variants: `outline`, `filled`, and `unstyled`. Pass the `variant` prop and set it to either of these values.
-
-#### `outline`
-
-```jsx
-<Textarea variant="outline" placeholder="John Doe" />
-```
-
-#### `filled`
-
-```jsx
-<Textarea variant="filled" placeholder="John Doe" />
-```
-
-#### `unstyled`
-
-```jsx
-<Textarea variant="unstyled" placeholder="John Doe" />
-```
-
-### Attributes
-
-General form input attributes are supported, such as `disabled`, `readOnly`, `required`, etc.
-
-#### `disabled`
-
-```jsx
-<Stack directin="column" spacing="4x">
-  <Textarea disabled placeholder="Placeholder text" />
-  <Textarea disabled placeholder="Placeholder text" defaultValue="Disabled" />
-</Stack>
-```
-
-#### `readOnly`
-
-```jsx
-<Stack directin="column" spacing="4x">
-  <Textarea readOnly placeholder="Placeholder text" />
-  <Textarea readOnly placeholder="Placeholder text" defaultValue="Read-only" />
-</Stack>
-```
-
-#### `required`
-
-```jsx
-<Textarea required placeholder="Placeholder text" />
-```
-
-### Validation
-
-The `Textarea` component provides a built-in validation mechanism that can be used to indicate when a field is not valid. When the `error` prop is set to true, a red border is displayed around the input field, allowing you to provide user-friendly form validation feedback.
-
-In addition to the built-in validation mechanism, you can use the native `setCustomValidity()` method to set a custom validation message for the textarea. This method is available on the textarea element and allows you to set a custom error message that will be displayed when the field is invalid.
-
-```jsx noInline
-const InlineError = (props) => (
-  <Text fontSize="sm" lineHeight="sm" color="red:50" {...props} />
-);
-
-const MultilineTextField = React.forwardRef((
-  {
-    value,
-    onChange,
-    ...rest
-  },
-  ref,
-) => {
-  const nodeRef = React.useRef();
-  const combinedRef = useMergeRefs(nodeRef, ref);
-  const error = (value === '') ? 'Please fill out this field' : null;
-
-  // Optional
-  React.useEffect(() => {
-    const el = nodeRef.current;
-    const errorMessage = !!error ? error : '';
-    el.setCustomValidity(errorMessage);
-  }, [error]);
-
-  return (
-    <>
-      <Flex position="relative" alignItems="center" mb="1x">
-        <Textarea
-          ref={combinedRef}
-          resize="none"
-          rows="3"
-          placeholder="Placeholder text"
-          value={value}
-          onChange={onChange}
-          error={error}
-          pr={error ? '10x' : undefined}
-        />
-        {error && (
-          <Box position="absolute" right="3x" top="2x">
-            <Icon icon="warning-circle" color="red:50" />
-          </Box>
-        )}
-      </Flex>
-      <Box>
-        {error && (
-          <InlineError>{error}</InlineError>
-        )}
-      </Box>
-    </>
-  );
-});
-
-render(() => {
-  const [value, setValue] = React.useState('');
-  const onChange = (e) => {
-    setValue(e.target.value);
-  };
-
-  return (
-    <MultilineTextField value={value} onChange={onChange} />
-  );
-});
-```
-
-## Props
-
-### Textarea
-
-| Name | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| rows | number | | Specifies the number of visible lines in a textarea. |
-| cols | number | | Specifies the visible width of a textarea. |
-| maxLength | number | | Specifies the maximum number of characters allowed in the textarea. |
-| minLength | number | | Specifies the minimum number of characters required for the textarea to be considered valid. |
-| resize | string | | The resize behavior of the textarea. One of: 'none', 'both', 'horizontal', 'vertical' |
-| variant | string | 'outline' | The variant of the textarea style to use. One of: 'outline', 'filled', 'unstyled' |
-| disabled | boolean | | If `true`, the textarea is disabled and the user cannot interact with it. |
-| error | boolean | | If `true`, the textarea displays a red border to indicate an error. |
-| readOnly | boolean | | If `true`, the value of the textarea cannot be edited. |
diff --git a/packages/react-docs/pages/components/textarea/attribute-disabled.js b/packages/react-docs/pages/components/textarea/attribute-disabled.js
new file mode 100644
index 0000000000..853dbc777d
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/attribute-disabled.js
@@ -0,0 +1,11 @@
+import { Stack, Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Stack directin="column" spacing="4x">
+    <Textarea disabled placeholder="Placeholder text" />
+    <Textarea disabled placeholder="Placeholder text" defaultValue="Disabled" />
+  </Stack>
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/attribute-readonly.js b/packages/react-docs/pages/components/textarea/attribute-readonly.js
new file mode 100644
index 0000000000..f32279e96b
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/attribute-readonly.js
@@ -0,0 +1,11 @@
+import { Stack, Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Stack directin="column" spacing="4x">
+    <Textarea readOnly placeholder="Placeholder text" />
+    <Textarea readOnly placeholder="Placeholder text" defaultValue="Read-only" />
+  </Stack>
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/attribute-required.js b/packages/react-docs/pages/components/textarea/attribute-required.js
new file mode 100644
index 0000000000..c985685108
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/attribute-required.js
@@ -0,0 +1,8 @@
+import { Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Textarea required placeholder="Placeholder text" />
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/basic.js b/packages/react-docs/pages/components/textarea/basic.js
new file mode 100644
index 0000000000..6ef5786414
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/basic.js
@@ -0,0 +1,12 @@
+import { Text, Textarea, TextLabel } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <>
+    <TextLabel mb="1x">Label:</TextLabel>
+    <Textarea placeholder="Basic example" />
+    <Text size="xs" mt="1x">Help text for the text input</Text>
+  </>
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/index.page.mdx b/packages/react-docs/pages/components/textarea/index.page.mdx
new file mode 100644
index 0000000000..f326869c69
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/index.page.mdx
@@ -0,0 +1,78 @@
+# Textarea
+
+The `Textarea` component allows you to create a multi-line text input.
+
+## Import
+
+```js
+import { Textarea } from '@tonic-ui/react';
+```
+
+## Usage
+
+{render('./basic')}
+
+### Sizing
+
+* The `rows` and `cols` properties allow you to specify an exact size for the `<Textarea>` to take. Setting these is a good idea for consistency, as browser defaults can differ.
+* The `maxLength` property specifies a maximum number of characters that the `Textarea` is allowed to contain.
+* The `minLength` property specifies a minimum length that is considered valid. `Textarea` will not submit (and is invalid) if it is empty, using the `required` attribute.
+* The `resize` property to set whether the `Textarea` is resizable, and if so, in which directions. You can set the value to `none`, `both`, `horizontal`, or `vertical`.
+
+{render('./sizing')}
+
+### Variants
+
+The `Textarea` component comes in 3 variants: `outline`, `filled`, and `unstyled`. Pass the `variant` prop and set it to either of these values.
+
+#### `outline`
+
+{render('./variant-outline')}
+
+#### `filled`
+
+{render('./variant-filled')}
+
+#### `unstyled`
+
+{render('./variant-unstyled')}
+
+### Attributes
+
+General form input attributes are supported, such as `disabled`, `readOnly`, `required`, etc.
+
+#### `disabled`
+
+{render('./attribute-disabled')}
+
+#### `readOnly`
+
+{render('./attribute-readonly')}
+
+#### `required`
+
+{render('./attribute-required')}
+
+### Validation
+
+The `Textarea` component provides a built-in validation mechanism that can be used to indicate when a field is not valid. When the `error` prop is set to true, a red border is displayed around the input field, allowing you to provide user-friendly form validation feedback.
+
+In addition to the built-in validation mechanism, you can use the native `setCustomValidity()` method to set a custom validation message for the textarea. This method is available on the textarea element and allows you to set a custom error message that will be displayed when the field is invalid.
+
+{render('./validation')}
+
+## Props
+
+### Textarea
+
+| Name | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| rows | number | | Specifies the number of visible lines in a textarea. |
+| cols | number | | Specifies the visible width of a textarea. |
+| maxLength | number | | Specifies the maximum number of characters allowed in the textarea. |
+| minLength | number | | Specifies the minimum number of characters required for the textarea to be considered valid. |
+| resize | string | | The resize behavior of the textarea. One of: 'none', 'both', 'horizontal', 'vertical' |
+| variant | string | 'outline' | The variant of the textarea style to use. One of: 'outline', 'filled', 'unstyled' |
+| disabled | boolean | | If `true`, the textarea is disabled and the user cannot interact with it. |
+| error | boolean | | If `true`, the textarea displays a red border to indicate an error. |
+| readOnly | boolean | | If `true`, the value of the textarea cannot be edited. |
diff --git a/packages/react-docs/pages/components/textarea/sizing.js b/packages/react-docs/pages/components/textarea/sizing.js
new file mode 100644
index 0000000000..991aaaf107
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/sizing.js
@@ -0,0 +1,38 @@
+import { Button, Flex, Space, Stack, Textarea, TextLabel } from '@tonic-ui/react';
+import React, { useState } from 'react';
+
+const App = () => {
+  const [resize, setResize] = useState('both');
+
+  return (
+    <>
+      <Flex alignItems="center" mb="5x">
+        <TextLabel>resize =</TextLabel>
+        <Space width="2x" />
+        <Stack direction="row" spacing="2x">
+          {['none', 'both', 'horizontal', 'vertical'].map(value => (
+            <Button
+              key={value}
+              variant={resize === value ? 'primary' : 'secondary'}
+              onClick={() => setResize(value)}
+            >
+              {value}
+            </Button>
+          ))}
+        </Stack>
+      </Flex>
+      <Textarea
+        defaultValue="Placeholder text"
+        width="auto"
+        resize={resize}
+        rows="3"
+        cols="12"
+        minLength={4}
+        maxLength={16}
+        transition="none"
+      />
+    </>
+  );
+};
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/validation.js b/packages/react-docs/pages/components/textarea/validation.js
new file mode 100644
index 0000000000..b225550880
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/validation.js
@@ -0,0 +1,68 @@
+import { Box, Flex, Icon, Text, Textarea } from '@tonic-ui/react';
+import { useMergeRefs } from '@tonic-ui/react-hooks';
+import React, { forwardRef, useEffect, useRef, useState } from 'react';
+
+const InlineError = (props) => (
+  <Text fontSize="sm" lineHeight="sm" color="red:50" {...props} />
+);
+
+const MultilineTextField = forwardRef((
+  {
+    value,
+    onChange,
+    ...rest
+  },
+  ref,
+) => {
+  const nodeRef = useRef();
+  const combinedRef = useMergeRefs(nodeRef, ref);
+  const error = (value === '') ? 'Please fill out this field' : null;
+
+  // Optional
+  useEffect(() => {
+    const el = nodeRef.current;
+    const errorMessage = error || '';
+    el.setCustomValidity(errorMessage);
+  }, [error]);
+
+  return (
+    <>
+      <Flex position="relative" alignItems="center" mb="1x">
+        <Textarea
+          ref={combinedRef}
+          resize="none"
+          rows="3"
+          placeholder="Placeholder text"
+          value={value}
+          onChange={onChange}
+          error={error}
+          pr={error ? '10x' : undefined}
+        />
+        {error && (
+          <Box position="absolute" right="3x" top="2x">
+            <Icon icon="warning-circle" color="red:50" />
+          </Box>
+        )}
+      </Flex>
+      <Box>
+        {error && (
+          <InlineError>{error}</InlineError>
+        )}
+      </Box>
+    </>
+  );
+});
+MultilineTextField.displayName = 'MultilineTextField';
+
+const App = () => {
+  const [value, setValue] = useState('');
+  const onChange = (e) => {
+    setValue(e.target.value);
+  };
+
+  return (
+    <MultilineTextField value={value} onChange={onChange} />
+  );
+};
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/variant-filled.js b/packages/react-docs/pages/components/textarea/variant-filled.js
new file mode 100644
index 0000000000..ffda7317c7
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/variant-filled.js
@@ -0,0 +1,8 @@
+import { Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Textarea variant="filled" placeholder="John Doe" />
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/variant-outline.js b/packages/react-docs/pages/components/textarea/variant-outline.js
new file mode 100644
index 0000000000..93391d05d2
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/variant-outline.js
@@ -0,0 +1,8 @@
+import { Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Textarea variant="outline" placeholder="John Doe" />
+);
+
+export default App;
diff --git a/packages/react-docs/pages/components/textarea/variant-unstyled.js b/packages/react-docs/pages/components/textarea/variant-unstyled.js
new file mode 100644
index 0000000000..cb2b6f56f0
--- /dev/null
+++ b/packages/react-docs/pages/components/textarea/variant-unstyled.js
@@ -0,0 +1,8 @@
+import { Textarea } from '@tonic-ui/react';
+import React from 'react';
+
+const App = () => (
+  <Textarea variant="unstyled" placeholder="John Doe" />
+);
+
+export default App;