@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/currency-input/content.md

@@ -0,0 +1,205 @@
+# Currency Input (https://design.candescent.com/docs/components/currency-input)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=10803-8259), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-currencyinput--default)
+
+A controlled amount field that accepts a numeric value and reports edits through `onChangeValue`. Digits accumulate as cents and are formatted automatically.
+
+```tsx
+import { CurrencyInput } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput } from '@cdx-ui/components';
+
+export default function CurrencyInputBasicDemo() {
+  const [amount, setAmount] = useState(0);
+
+  return (
+    <CurrencyInput accessibilityLabel="Transfer amount" value={amount} onChangeValue={setAmount} />
+  );
+}
+```
+
+## Sizes
+
+Use `size="small"` when the amount appears alongside other form fields.
+
+```tsx
+import { useState } from 'react';
+import { Box, CurrencyInput, Text, type CurrencyInputProps } from '@cdx-ui/components';
+
+const sizes = ['default', 'small'] as const satisfies readonly NonNullable<
+  CurrencyInputProps['size']
+>[];
+
+function SizeRow({ size }: { size: NonNullable<CurrencyInputProps['size']> }) {
+  const [amount, setAmount] = useState(4890);
+
+  return (
+    <Box className="gap-2">
+      <Text size="sm" color="secondary">
+        {size}
+      </Text>
+      <CurrencyInput
+        accessibilityLabel={`${size} transfer amount`}
+        size={size}
+        value={amount}
+        onChangeValue={setAmount}
+      />
+    </Box>
+  );
+}
+
+export default function CurrencyInputSizesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {sizes.map((size) => (
+        <SizeRow key={size} size={size} />
+      ))}
+    </Box>
+  );
+}
+```
+
+## Custom currency symbol
+
+`currencySymbol` changes the displayed prefix. Number grouping and decimal formatting remain `en-US` with two fraction digits.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput } from '@cdx-ui/components';
+
+export default function CurrencyInputCustomSymbolDemo() {
+  const [amount, setAmount] = useState(1200);
+
+  return (
+    <CurrencyInput
+      accessibilityLabel="Payment amount in euros"
+      currencySymbol="€"
+      value={amount}
+      onChangeValue={setAmount}
+    />
+  );
+}
+```
+
+## States
+
+The root controls disabled, read-only, required, and invalid state for the field.
+
+```tsx
+import { Box, CurrencyInput, Text } from '@cdx-ui/components';
+
+export default function CurrencyInputStatesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <CurrencyInput accessibilityLabel="Disabled transfer amount" isDisabled value={1200} />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <CurrencyInput accessibilityLabel="Read-only transfer amount" isReadOnly value={4890} />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <CurrencyInput accessibilityLabel="Invalid transfer amount" isInvalid value={0} />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With field
+
+Compose with `Field` to provide a visible label, helper text, and required state.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput, Field } from '@cdx-ui/components';
+
+export default function CurrencyInputWithFieldDemo() {
+  const [amount, setAmount] = useState(0);
+
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label className="text-center">Amount</Field.Label>
+      <CurrencyInput isRequired size="small" value={amount} onChangeValue={setAmount} />
+      <Field.Helper className="justify-center">Daily limit remaining: $1,200</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## With field and validation
+
+Set invalid state on both `Field` and `CurrencyInput` so the error message and amount styling stay in sync.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput, Field } from '@cdx-ui/components';
+
+const DAILY_LIMIT = 1200;
+
+export default function CurrencyInputWithFieldInvalidDemo() {
+  const [amount, setAmount] = useState(1500);
+  const isInvalid = amount > DAILY_LIMIT;
+
+  return (
+    <Field className="w-full" isRequired isInvalid={isInvalid}>
+      <Field.Label className="text-center">Amount</Field.Label>
+      <CurrencyInput
+        isInvalid={isInvalid}
+        isRequired
+        size="small"
+        value={amount}
+        onChangeValue={setAmount}
+      />
+      <Field.Error className="justify-center">Amount exceeds your daily limit.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### CurrencyInput
+
+Controlled calculator-style monetary entry. The numeric `value` is expressed in major currency units, while typed digits accumulate from right to left as cents.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `value?` | `number` | — | Current amount in major currency units, not cents. Renders a formatted zero when omitted or null. |
+| `style?` | `StyleProp<ViewStyle>` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `onChangeValue?` | `((value: number) => void)` | — | Called with the parsed amount in major currency units, not cents, when the user edits the field. |
+| `currencySymbol?` | `string` | — | Currency symbol rendered as an inline prefix. Defaults to `"$"`. |
+| `isInvalid?` | `boolean` | — | If true, the input will indicate an error. |
+| `isDisabled?` | `boolean` | — | If true, the input will be disabled. |
+| `isRequired?` | `boolean` | — | Sets `aria-required="true"` on web when passed in form control. |
+| `isReadOnly?` | `boolean` | — | If true, prevents the value of the input from being edited. |
+| `isFullWidth?` | `boolean` | — | If true, the input element will span the full width of its parent. |
+
+Supports `accessibilityLabel`, `accessibilityHint`, `testID`, `onFocus`, `onBlur`, and `returnKeyType` from [`TextInputProps`](https://reactnative.dev/docs/textinput#props). `style` applies to the root container, and the forwarded ref targets the underlying `TextInput`.
+
+### Input behavior
+
+Only digits contribute to the amount. Each new digit appends to the cents value, backspace removes the rightmost digit, and the caret remains at the end. Input is capped at 15 digits to stay within JavaScript's safe integer range. The component uses `keyboardType="decimal-pad"`, defaults `returnKeyType` to `"done"` (overridable), and formats values with the `en-US` locale and two fraction digits.
+
+## Accessibility
+
+| Item            | Behavior                                                                             |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Accessible name | Compose with `Field.Label` or pass `accessibilityLabel` directly.                    |
+| Value           | `accessibilityValue.text` contains the fully formatted amount.                       |
+| Validation      | Pair `isInvalid` with `Field.Error` so the error is not communicated by color alone. |