@react-ui-org/react-ui 0.52.0 → 0.53.0

package/src/components/Text/README.md

@@ -0,0 +1,220 @@
+# Text
+
+Text is a tiny component to control wrapping of text content.
+
+## Basic Usage
+
+To implement the Text component, you need to import it first:
+
+```js
+import { Text } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<docoff-placeholder>
+  <Text lines={3}>
+    Hello! This text will be clamped to three lines.
+    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
+    ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis
+    dis parturient montes, nascetur ridiculus mus. Donec quam felis,
+    ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa
+    quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget,
+    arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo.
+  </Text>
+</docoff-placeholder>
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- Use Text anytime you need to **control potentially long strings** and
+  prevent them from overflowing or breaking their container.
+
+- **By default, Text doesn't alter rendering of its content.** Use available
+  options to achieve the result you need.
+
+- **Text renders as `<span>` by default,** so it can only contain
+  inline-level HTML elements (like `<strong>` or `<a>`, but not `<div>`, `<p>`,
+  or `<h2>`). If necessary, use the `blockLevel` option to render as `<div>` to
+  keep your HTML valid.
+
+- **Use Text for short pieces of text content.** Including a couple of HTML tags
+  shouldn't cause any harm, but keep in mind Text is not intended to wrap
+  complex HTML structures or even React components.
+
+## Number of Lines
+
+Specify how many `lines` of text should be visible if content doesn't fit its
+container. If the number of lines is exceeded, the content is truncated and
+appended by an ellipsis (`…`).
+
+```docoff-react-preview
+React.createElement(() => {
+  const [lines, setLines] = React.useState(1);
+  return (
+    <div>
+      <Toolbar align="baseline">
+        <ToolbarItem>
+          <TextField
+            label="Number of lines"
+            min={1}
+            max={100}
+            onChange={(e) => setLines(Number(e.target.value))}
+            type="number"
+            value={lines}
+          />
+        </ToolbarItem>
+      </Toolbar>
+      <docoff-placeholder>
+        <Text lines={lines}>
+          Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean
+          commodo ligula eget dolor. Aenean massa. Cum sociis natoque
+          penatibus et magnis dis parturient montes, nascetur ridiculus mus.
+          Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem.
+          Nulla consequat massa quis enim. Donec pede justo, fringilla vel,
+          aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut,
+          imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede
+          mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum
+          semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula,
+          porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem
+          ante, dapibus in, viverra quis, feugiat a, tellus.
+        </Text>
+      </docoff-placeholder>
+    </div>
+  );
+});
+```
+
+## Word Wrapping
+
+There are three possible ways of controlling wrapping of long words if they do
+not fit on a line. Set `wordWrapping` to one of the following values:
+
+- `normal`: Do not force any wrapping (default behavior).
+
+- `long-words`: To prevent overflow, an otherwise unbreakable string of
+  characters — like a long word or URL — may be broken at any point if there are
+  no otherwise-acceptable break points in the line.
+
+- `anywhere`: Create a break at the exact place where text would otherwise
+  overflow its container (even if putting an entire word on its own line would
+  negate the need for a break).
+
+📖 [Read more about wrapping and breaking text at MDN.](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Text/Wrapping_Text)
+
+### Hyphens
+
+The `hyphens` option specifies how words should be hyphenated when text wraps
+across multiple lines. It can prevent hyphenation entirely, hyphenate at
+manually-specified points within the text, or let the browser automatically
+insert hyphens where appropriate.
+
+👉 The `auto` setting's behavior depends on the language being properly tagged
+to select the appropriate hyphenation rules. **You must specify a language**
+using the `lang` HTML attribute (e.g.
+[on `<html>` tag](/docs/getting-started/usage#full-example)) to guarantee that
+automatic hyphenation is applied in that language.
+
+👉 [Manually suggested line break opportunities](https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens#suggesting_line_break_opportunities)
+will override automatic break point selection in `auto` mode when present.
+
+📖 [Read more about `hyphens` CSS property at MDN.](https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens)
+
+```docoff-react-preview
+React.createElement(() => {
+  const [hyphens, setHyphens] = React.useState('none');
+  const [wordWrapping, setWordWrapping] = React.useState('normal');
+  return (
+    <div>
+      <Toolbar>
+        <ToolbarGroup align="baseline">
+          <ToolbarItem>
+            <span id="word-wrapping-options-label">Word wrapping:</span>
+          </ToolbarItem>
+          <ToolbarItem>
+            <ButtonGroup aria-labelledby="word-wrapping-options-label" priority="outline">
+              <Button
+                aria-pressed={wordWrapping === 'normal'}
+                color={wordWrapping === 'normal' ? 'selected' : 'secondary'}
+                label="normal"
+                onClick={() => setWordWrapping('normal')}
+              />
+              <Button
+                aria-pressed={wordWrapping === 'long-words'}
+                color={wordWrapping === 'long-words' ? 'selected' : 'secondary'}
+                label="long-words"
+                onClick={() => setWordWrapping('long-words')}
+              />
+              <Button
+                aria-pressed={wordWrapping === 'anywhere'}
+                color={wordWrapping === 'anywhere' ? 'selected' : 'secondary'}
+                label="anywhere"
+                onClick={() => setWordWrapping('anywhere')}
+              />
+            </ButtonGroup>
+          </ToolbarItem>
+        </ToolbarGroup>
+        <ToolbarGroup align="baseline">
+          <ToolbarItem>
+            <span id="hyphens-options-label">Hyphens:</span>
+          </ToolbarItem>
+          <ToolbarItem>
+            <ButtonGroup aria-labelledby="hyphens-options-label" priority="outline">
+              <Button
+                aria-pressed={hyphens === 'none'}
+                color={hyphens === 'none' ? 'selected' : 'secondary'}
+                label="none"
+                onClick={() => setHyphens('none')}
+              />
+              <Button
+                aria-pressed={hyphens === 'auto'}
+                color={hyphens === 'auto' ? 'selected' : 'secondary'}
+                label="auto"
+                onClick={() => setHyphens('auto')}
+              />
+              <Button
+                aria-pressed={hyphens === 'manual'}
+                color={hyphens === 'manual' ? 'selected' : 'secondary'}
+                label="manual"
+                onClick={() => setHyphens('manual')}
+              />
+            </ButtonGroup>
+          </ToolbarItem>
+        </ToolbarGroup>
+      </Toolbar>
+      <docoff-placeholder width="11em" bordered>
+        <Text hyphens={hyphens} wordWrapping={wordWrapping}>
+          {hyphens === 'manual'
+            ? (<>LongWord&shy;ThatHasManual&shy;Breaking&shy;Possibilities</>)
+            : (<>LongWordThatHasNoBreakingPossibilities</>)}
+          {' '}
+          and a couple of ordinary words that are nice and well behaved.
+        </Text>
+      </docoff-placeholder>
+    </div>
+  );
+});
+```
+
+## Forwarding HTML Attributes
+
+In addition to the options below in the [component's API](#api) section, you
+can specify [React synthetic events] or **any HTML attribute you like.** All
+attributes that don't interfere with the API are forwarded either to the
+`<span>` or to the `<div>` HTML element in case that `blockLevel` is set to
+`true`. This enables making the component interactive and helps to improve its
+accessibility.
+
+👉 Refer to the MDN reference for the full list of supported attributes of the
+[span] and [div] element.
+
+## API
+
+<docoff-react-props src="/components/Text/Text.jsx"></docoff-react-props>
+
+[React synthetic events]: https://reactjs.org/docs/events.html
+[span]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span#attributes
+[div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes

package/src/components/TextArea/README.md

@@ -0,0 +1,359 @@
+# TextArea
+
+TextArea enables users to add longer text to a form.
+
+## Basic Usage
+
+To implement the TextArea component, you need to import it first:
+
+```js
+import { TextArea } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<TextArea label="Your feedback" />
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- Use **short and descriptive labels**, ideally nouns rather than seemingly
+  polite phrases like _Please enter your message_. Short labels will help your
+  users accomplish their task faster.
+
+- Only make the TextArea's label invisible when there is **another visual
+  clue** to guide users through filling the input. Using the first option as
+  label is not recommended either — it disappears once user makes their choice.
+
+- When a short label is not enough, use **help texts to guide users** before
+  they enter anything.
+
+- Optionally you can **pre-fill your text fields with a placeholder** to give
+  users an example of what they're expected to fill in. Just remember the
+  placeholder disappears once a value is entered so don't put anything important
+  there. Usually, en example value starting with “Eg.” works best.
+
+- Use **clear, calm error messages** when there's a problem with what they
+  entered. Be positive and focus on solutions to make the error message helpful.
+
+- Ensure the height of a text area **fits within mobile screen sizes.**
+
+## Design Variants
+
+To satisfy the design requirements of your project, all input fields in React UI
+come in **two design variants** to choose from: outline and filled. Both can be
+further [customized](#theming) with CSS custom properties.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+/>
+```
+
+## Sizes
+
+Aside from the default (medium) size, two additional sizes are available: small
+and large.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  size="small"
+/>
+<TextArea
+  label="Your feedback"
+/>
+<TextArea
+  label="Your feedback"
+  size="large"
+/>
+<TextArea
+  label="Your feedback"
+  size="small"
+  variant="filled"
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+/>
+<TextArea
+  label="Your feedback"
+  size="large"
+  variant="filled"
+/>
+```
+
+Full-width fields span the full width of a parent:
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  fullWidth
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+  fullWidth
+/>
+```
+
+## Input Size
+
+The default width of all inputs is 240 px, and it can be
+[customized](/docs/customize/theming/overview) with a CSS custom property.
+However, you can also **control the size of individual text areas** using
+the `rows` and `cols` properties. Additionally, text areas are vertically
+resizable by users.
+
+👉 Remember that the `cols` and `rows` HTML attributes **do not limit on how
+many characters** the user can enter. Use the
+[`maxlength` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#Min_and_max_length)
+to achieve that effect.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  cols={50}
+  rows={6}
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+  cols={50}
+  rows={6}
+/>
+```
+
+## Invisible Label
+
+In some cases, it may be convenient to visually hide the field label. The label
+remains accessible to assistive technologies.
+
+While it may be acceptable for login screens with just a few fields or other
+simple forms, it's dangerous to hide labels from users in most cases. Keep in
+mind you should **provide another visual clue** so users know what to fill into
+the input.
+
+```docoff-react-preview
+<TextArea
+  label="Feedback"
+  isLabelVisible={false}
+  placeholder="Eg. What I liked the best was…"
+/>
+<TextArea
+  label="Feedback"
+  isLabelVisible={false}
+  variant="filled"
+  placeholder="Eg. What I liked the best was…"
+/>
+```
+
+## Horizontal Layout
+
+The default vertical layout is very easy to use and work with. However, there
+are situations where horizontal layout suits better — and that's why React UI
+supports this kind of layout as well.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  variant="filled"
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  fullWidth
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  variant="filled"
+  fullWidth
+/>
+<TextArea
+  isLabelVisible={false}
+  label="Your feedback"
+  layout="horizontal"
+  placeholder="Your feedback"
+  fullWidth
+/>
+<TextArea
+  isLabelVisible={false}
+  label="Your feedback"
+  layout="horizontal"
+  placeholder="Your feedback"
+  variant="filled"
+  fullWidth
+/>
+```
+
+## Help Text
+
+You may provide an additional help text to clarify how the input should be
+filled.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  helpText="Why would you recommend us?"
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+  helpText="Why would you recommend us?"
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  helpText="Why would you recommend us?"
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  helpText="Why would you recommend us?"
+  variant="filled"
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  helpText="Why would you recommend us?"
+  fullWidth
+/>
+<TextArea
+  label="Your feedback"
+  layout="horizontal"
+  variant="filled"
+  helpText="Why would you recommend us?"
+  fullWidth
+/>
+```
+
+## States
+
+### Validation States
+
+Validation states visually present the result of validation of the input. You
+should always **provide a help text for states other than valid** so users know
+what happened and what action they should take or what options they have.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  onChange={() => {}}
+  validationState="valid"
+  validationText="Looks good!"
+  value="Like that!"
+  required
+/>
+<TextArea
+  label="Your feedback"
+  onChange={() => {}}
+  validationState="warning"
+  validationText="The feedback should be at least 3 characters long."
+  value=".."
+  required
+/>
+<TextArea
+  label="Your feedback"
+  validationState="invalid"
+  validationText="Please share your feedback with us."
+  required
+/>
+<TextArea
+  label="Your feedback"
+  onChange={() => {}}
+  validationState="valid"
+  validationText="Looks good!"
+  variant="filled"
+  value="Like that!"
+  required
+/>
+<TextArea
+  label="Your feedback"
+  onChange={() => {}}
+  validationState="warning"
+  validationText="The feedback should be at least 3 characters long."
+  variant="filled"
+  value=".."
+  required
+/>
+<TextArea
+  label="Your feedback"
+  validationState="invalid"
+  validationText="Please share your feedback with us."
+  variant="filled"
+  required
+/>
+```
+
+### Disabled State
+
+It's possible to disable the whole input.
+
+```docoff-react-preview
+<TextArea
+  label="Your feedback"
+  disabled
+/>
+<TextArea
+  label="Your feedback"
+  variant="filled"
+  disabled
+/>
+```
+
+## Forwarding HTML Attributes
+
+In addition to the options below in the [component's API](#api) section, you
+can specify [React synthetic events] or you can **add whatever HTML attribute
+you like.** All attributes that don't interfere with the API are forwarded to
+the native HTML `<textarea>`. This enables making the component interactive and
+to helps to improve its accessibility.
+
+```docoff-react-preview
+<TextArea
+  label="Address"
+  autoComplete="street-address"
+  minLength={3}
+  maxLength={80}
+/>
+<TextArea
+  label="Address"
+  variant="filled"
+  autoComplete="street-address"
+  minLength={3}
+  maxLength={80}
+/>
+```
+
+👉 Refer to the MDN reference for the full list of supported attributes of the
+[textarea] element.
+
+## Forwarding ref
+
+If you provide [ref], it is forwarded to the native HTML `<textarea>` element.
+
+## API
+
+<docoff-react-props src="/components/TextArea/TextArea.jsx"></docoff-react-props>
+
+## Theming
+
+Head to [Forms Theming](/docs/customize/theming/forms) to see shared form theming
+options.
+
+[React synthetic events]: https://reactjs.org/docs/events.html
+[textarea]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#attributes
+[ref]: https://reactjs.org/docs/refs-and-the-dom.html