@redis-ui/components 42.8.0 → 43.2.1

package/skills/redis-ui-components/references/PasswordInput.md

@@ -0,0 +1,262 @@
+# PasswordInput
+
+A password input component with exposure toggle, validation states, reset affordance, and compose support for custom layouts.
+
+## Import
+
+```tsx
+import { PasswordInput } from '@redislabsdev/redis-ui-components';
+```
+
+> Some examples also use icons from `@redislabsdev/redis-ui-icons`:
+> ```tsx
+> import { SendIcon } from '@redislabsdev/redis-ui-icons';
+> ```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Shared id for the compose wrapper and the inner input. |
+| variant | `'outline' \| 'underline'` | `'outline'` | Visual style for the input wrapper. |
+| error | `ReactElement \| string` | - | Error content. Enables error state and tooltip content. |
+| valid | `boolean` | - | Enables the success state. |
+| readOnly | `boolean` | - | Switches the input into read-only mode. |
+| value | `string` | - | Controlled input value. |
+| defaultValue | `string` | - | Uncontrolled initial value. |
+| onChange | `(value: string) => void` | - | Called when the parsed value changes. |
+| showExposureToggle | `'always' \| 'never' \| 'has-value'` | `'always'` | Controls when the show/hide password button is visible. |
+| exposed | `boolean` | - | Controlled exposure state. |
+| defaultExposed | `boolean` | - | Uncontrolled initial exposure state. |
+| onExposedChange | `(exposed: boolean) => void` | - | Called when the exposure state changes. |
+| allowReset | `boolean` | `false` | Shows the reset button when a value is present. |
+
+The component also forwards standard `input` attributes through the underlying password field, excluding `children`, `defaultValue`, `value`, `onChange`, and `readOnly`.
+
+## Sub-components
+
+- `PasswordInput.Compose` - Compose wrapper that manages value state, validation state, read-only rendering, and exposure state. It uses the shared compose API props for id, variant, value, defaultValue, onChange, showExposureToggle, exposed, defaultExposed, onExposedChange, plus `readonlyRender` and `readonlyProps`.
+- `PasswordInput.Tag` - The underlying password input element. It accepts native `input` props except `type` and `readOnly`, and switches between `password` and `text` based on exposure state.
+- `PasswordInput.StatusIndicator` - Success/error indicator with tooltip support for error content. It uses the shared indicator props plus `className` and `style`.
+- `PasswordInput.PasswordButton` - Show/hide password toggle button. It inherits `IconButton` props except `onClick`, `icon`, and `disabled`.
+- `PasswordInput.ResetButton` - Reset action button used when a value is present. It accepts `allowReset` plus partial `IconButton` props.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<PasswordInput placeholder="PasswordInput" type="text" id="custom-id" disabled={false} />
+```
+
+### Status
+
+> Adding `valid` prop enables valid status.
+>
+> Adding some text to the `error` prop of `PasswordInput` enables error status. Hover the error indicator to see the specified text in a tooltip.
+>
+> `error` status overrides `valid` status.
+
+```tsx
+<>
+  Valid status
+  <PasswordInput placeholder="Password Input" valid />
+  Error status
+  <PasswordInput placeholder="Password Input" error="Error message" />
+</>
+```
+
+### ResetButton
+
+> `PasswordInput` allows the user to clear the value. Set `allowReset` to show the reset button.
+
+```tsx
+<PasswordInput placeholder="Password Input" defaultValue="orange" allowReset />
+```
+
+### ExposureButtonControl
+
+> Visibility of the exposure (show password) button and exposure state can be controlled.
+>
+> The button can be always visible, always hidden, or visible only when the input has a value.
+> Set `showExposureToggle` to `always`, `never`, or `has-value`.
+
+```tsx
+import { useState } from 'react';
+import { FormField, PasswordInput, Typography } from '@redislabsdev/redis-ui-components';
+
+function Render() {
+  const [exposed, setExposed] = useState(false);
+
+  return (
+    <>
+      <Typography.Heading size="M">Controlled exposure state, various "Exposure" button visibility</Typography.Heading>
+      <FormField label="Button is always visible (default)">
+        <PasswordInput defaultValue="password" exposed={exposed} onExposedChange={setExposed} />
+      </FormField>
+      <FormField label="Button is always hidden">
+        <PasswordInput
+          showExposureToggle="never"
+          defaultValue="password"
+          exposed={exposed}
+          onExposedChange={setExposed}
+        />
+      </FormField>
+      <FormField label="Button is visible if input has value">
+        <PasswordInput
+          allowReset
+          showExposureToggle="has-value"
+          defaultValue="password"
+          exposed={exposed}
+          onExposedChange={setExposed}
+        />
+      </FormField>
+      <Typography.Heading size="M">Uncontrolled exposure state</Typography.Heading>
+      <FormField label="Initially covert (default)">
+        <PasswordInput defaultValue="password" />
+      </FormField>
+      <FormField label="Initially exposed">
+        <PasswordInput defaultValue="password" defaultExposed />
+      </FormField>
+    </>
+  );
+}
+```
+
+### DisabledAndReadonly
+
+> Adding `disabled` or `readOnly` switches the component to the corresponding state.
+>
+> In read-only mode only the value is visible. Other indicators are ignored.
+>
+> `readOnly` overrides `disabled`.
+
+```tsx
+<>
+  Disabled
+  <PasswordInput disabled />
+  Disabled with value
+  <PasswordInput disabled defaultValue="orange" />
+  Disabled with indicators
+  <PasswordInput disabled defaultValue="banana" error="Error message" allowReset />
+  Read only
+  <PasswordInput value="read-only input value" readOnly />
+</>
+```
+
+### WithLabel
+
+> `PasswordInput` does not have its own label or other external decoration elements.
+>
+> Use `FormField` for those cases. If a custom id is specified, `FormField` inherits it;
+> otherwise the label is connected automatically via a generated id.
+>
+> Custom ids must start with a letter to work correctly.
+>
+> `FormField` also inherits status and some states from the input.
+
+```tsx
+<>
+  <FormField label="FormField Label with custom id">
+    <PasswordInput placeholder="Password Input" id="custom-id" />
+  </FormField>
+  <FormField
+    label="FormField Label with auto-generated id"
+    additionalText="FormField additional text"
+  >
+    <PasswordInput placeholder="Password Input" />
+  </FormField>
+  <FormField
+    label="FormField Label with read-only mode"
+    additionalText="FormField additional text"
+  >
+    <PasswordInput value="read-only input value" readOnly />
+  </FormField>
+</>
+```
+
+### Variants
+
+```tsx
+<>
+  <FormField label="Outline (default)" additionalText="outline">
+    <PasswordInput placeholder="Password Input" />
+  </FormField>
+  <FormField label="Underline" additionalText="underline">
+    <PasswordInput placeholder="Password Input" variant="underline" />
+  </FormField>
+</>
+```
+
+### ComposeTokenInput
+
+```tsx
+import { useState } from 'react';
+import {
+  ActionIconButton,
+  FormField,
+  PasswordInput,
+  Tooltip,
+  Typography
+} from '@redislabsdev/redis-ui-components';
+import { SendIcon } from '@redislabsdev/redis-ui-icons';
+
+function Render() {
+  const [token, setToken] = useState('');
+  const [error, setError] = useState('');
+
+  const sendToken = () => {
+    if (!token.match(/^[a-z0-9]{10}$/)) {
+      setError('token must contain letters (a-z) or digits and be 10 symbols long');
+    } else {
+      // eslint-disable-next-line no-alert
+      alert('Token has been sent');
+    }
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (token && e.key.toLowerCase() === 'enter') {
+      sendToken();
+    }
+  };
+
+  return (
+    <FormField
+      required
+      label="Token"
+      additionalText="Enter symbols and press Enter or click Send button"
+    >
+      <PasswordInput.Compose
+        id="token_input"
+        value={token}
+        onChange={(newValue) => {
+          setToken(newValue.replace(/\s/g, ''));
+          setError('');
+        }}
+        error={error}
+      >
+        <PasswordInput.Tag onKeyDown={onKeyDown} placeholder="Enter Token" autoComplete="off" />
+        <PasswordInput.StatusIndicator />
+        <Tooltip disabled={!!token} content="Token is mandatory">
+          <ActionIconButton
+            size="M"
+            disabled={!token || !!error}
+            icon={SendIcon}
+            variant="secondary"
+            onClick={sendToken}
+          />
+        </Tooltip>
+      </PasswordInput.Compose>
+    </FormField>
+  );
+}
+```
+
+## Notes
+
+- `error` status overrides `valid`.
+- `showExposureToggle` accepts `always`, `never`, and `has-value`.
+- `allowReset` shows the reset button when a value is present.
+- `readOnly` overrides `disabled`, and read-only mode hides the extra indicators.
+- Custom ids used with `FormField` must start with a letter.
+- Exposure state controls whether the field renders as `password` or `text`.