@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/image/content.md

@@ -0,0 +1,104 @@
+# Image (https://design.candescent.com/docs/components/image)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=9091-16186), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-image--default)
+
+A thin wrapper around React Native's `Image` that accepts a URI string as `source` and adds web-oriented image attributes without imposing loading or error UI.
+
+```tsx
+import { Image } from '@cdx-ui/components';
+```
+
+## Basic
+
+Pass a URI string directly to `source`. It is normalized to React Native's `{ uri }` format.
+
+```tsx
+import { Image } from '@cdx-ui/components';
+
+export default function ImageBasicDemo() {
+  // Interim: Image has no radius or shape prop yet, so the corner radius is a class.
+  return (
+    <Image
+      source="/candescent/intelligent-banking.jpg"
+      alt="A person using digital banking on a mobile phone"
+      className="h-48 w-72 rounded-xl"
+      resizeMode="cover"
+    />
+  );
+}
+```
+
+## Resize modes
+
+Use `resizeMode` to control how an image fits its dimensions.
+
+```tsx
+import { HStack, Image, Text, VStack } from '@cdx-ui/components';
+
+const resizeModes = ['cover', 'contain', 'stretch', 'center'] as const;
+
+export default function ImageResizeModesDemo() {
+  return (
+    <HStack space="lg" className="flex-wrap justify-center">
+      {resizeModes.map((resizeMode) => (
+        <VStack key={resizeMode} space="xs" className="items-center">
+          <Image
+            source="/candescent/intelligent-banking.jpg"
+            alt=""
+            resizeMode={resizeMode}
+            className="h-24 w-36 rounded-lg bg-surface-secondary"
+          />
+          <Text size="sm" color="secondary">
+            {resizeMode}
+          </Text>
+        </VStack>
+      ))}
+    </HStack>
+  );
+}
+```
+
+## Web attributes
+
+On web, use `loading`, `decoding`, `draggable`, and responsive image attributes such as `sizes` and `srcSet`. Native platforms ignore these web-only hints.
+
+```tsx
+import { Image } from '@cdx-ui/components';
+
+export default function ImageWebAttributesDemo() {
+  // Interim: Image has no radius or shape prop yet, so the corner radius is a class.
+  return (
+    <Image
+      source="/candescent/intelligent-banking.jpg"
+      alt="A person using digital banking on a mobile phone"
+      srcSet="/candescent/intelligent-banking.jpg 1x"
+      sizes="(max-width: 640px) 100vw, 288px"
+      loading="lazy"
+      decoding="async"
+      draggable={false}
+      className="h-48 w-72 rounded-xl"
+      resizeMode="cover"
+    />
+  );
+}
+```
+
+For avatars with initials or icon fallbacks, use the [Avatar](https://design.candescent.com/docs/components/avatar/content.md) component.
+
+## API
+
+### Image
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `source` | `string \| ImageSourcePropType` | — | URI string (normalized to `{ uri }`) or standard `ImageSourcePropType`. |
+| `sizes?` | `string` | — | DOM `sizes` for responsive selection with `srcSet` — web only. |
+| `loading?` | `'lazy' \| 'eager'` | — | DOM lazy-loading hint — web only. |
+| `decoding?` | `'async' \| 'auto' \| 'sync'` | — | DOM decode hint — web only. |
+| `draggable?` | `boolean` | — | DOM drag behavior — web only. |
+| `tabIndex?` | `number` | — | DOM focus order — web only. |
+
+Inherits all [`ImageProps`](https://reactnative.dev/docs/image#props). `source` accepts either a URI string or a standard React Native `ImageSourcePropType`, including bundled assets.
+
+Web-only props are forwarded to the underlying DOM image where supported by React Native Web and have no effect on iOS or Android.

package/docs/components/input/content.md

@@ -0,0 +1,346 @@
+# Input Field (https://design.candescent.com/docs/components/input)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-CDS-V2--React-Native?node-id=159-22), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-input--default)
+
+A compound component with sub-components for the editable field, slots, and icons.
+
+```tsx
+import { Input } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Input } from '@cdx-ui/components';
+
+export default function InputBasicDemo() {
+  return (
+    <Input>
+      <Input.Field accessibilityLabel="Name" placeholder="Enter your name" />
+    </Input>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { Box, Input, Text, type InputProps } from '@cdx-ui/components';
+
+const sizes = ['default', 'small'] as const satisfies readonly NonNullable<InputProps['size']>[];
+
+export default function InputSizesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {sizes.map((size) => (
+        <Box key={size} className="gap-2">
+          <Text size="sm" color="secondary">
+            {size}
+          </Text>
+          <Input size={size}>
+            <Input.Field accessibilityLabel={`${size} input`} placeholder={`${size} input`} />
+          </Input>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With icons
+
+Use `Input.Slot` and `Input.Icon` to add leading or trailing adornments.
+
+```tsx
+import { Input } from '@cdx-ui/components';
+import { Search } from '@cdx-ui/icons';
+
+export default function InputWithIconsDemo() {
+  return (
+    <Input>
+      <Input.Slot>
+        <Input.Icon as={Search} />
+      </Input.Slot>
+      <Input.Field accessibilityLabel="Search transactions" placeholder="Search transactions" />
+    </Input>
+  );
+}
+```
+
+## Password
+
+Place an interactive visibility toggle inside `Input.Slot`.
+
+```tsx
+import { useState } from 'react';
+import { IconButton, Input } from '@cdx-ui/components';
+import { Visibility, VisibilityOff } from '@cdx-ui/icons';
+
+export default function InputPasswordDemo() {
+  const [isVisible, setIsVisible] = useState(false);
+
+  return (
+    <Input>
+      <Input.Field
+        accessibilityLabel="Password"
+        placeholder="Enter your password"
+        type={isVisible ? 'text' : 'password'}
+        secureTextEntry={!isVisible}
+      />
+      <Input.Slot>
+        <IconButton
+          as={isVisible ? VisibilityOff : Visibility}
+          variant="ghost"
+          size="small"
+          accessibilityLabel={isVisible ? 'Hide password' : 'Show password'}
+          onPress={() => setIsVisible((visible) => !visible)}
+        />
+      </Input.Slot>
+    </Input>
+  );
+}
+```
+
+## Character count
+
+Derive the count from the field value and render it as adornment text in a trailing `Input.Slot` — a raw count, or the count alongside a limit.
+
+```tsx
+import { useState } from 'react';
+import { Box, Input, Text } from '@cdx-ui/components';
+
+const MEMO_LIMIT = 40;
+
+export default function InputCharacterCountDemo() {
+  const [nickname, setNickname] = useState('Checking');
+  const [memo, setMemo] = useState('Rent for October');
+  const nicknameCount = String(nickname.length);
+  const memoLength = String(memo.length);
+  const memoLimit = String(MEMO_LIMIT);
+  const memoCount = `${memoLength}/${memoLimit}`;
+
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Count
+        </Text>
+        <Input>
+          <Input.Field
+            accessibilityLabel="Account nickname"
+            value={nickname}
+            onChangeText={setNickname}
+          />
+          <Input.Slot>
+            <Text
+              size="sm"
+              color="tertiary"
+              className="tabular-nums"
+              accessibilityLabel={`${nicknameCount} characters`}
+            >
+              {nicknameCount}
+            </Text>
+          </Input.Slot>
+        </Input>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Count and limit
+        </Text>
+        <Input>
+          <Input.Field accessibilityLabel="Transfer memo" value={memo} onChangeText={setMemo} />
+          <Input.Slot>
+            <Text
+              size="sm"
+              color="tertiary"
+              className="tabular-nums"
+              accessibilityLabel={`${memoLength} of ${memoLimit} characters`}
+            >
+              {memoCount}
+            </Text>
+          </Input.Slot>
+        </Input>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## States
+
+The root controls disabled, read-only, required, and invalid state for the field.
+
+```tsx
+import { Box, Input, Text } from '@cdx-ui/components';
+
+export default function InputStatesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Input isDisabled>
+          <Input.Field accessibilityLabel="Disabled input" defaultValue="Account number" />
+        </Input>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <Input isReadOnly>
+          <Input.Field accessibilityLabel="Read-only input" defaultValue="jane.doe@example.com" />
+        </Input>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <Input isInvalid>
+          <Input.Field accessibilityLabel="Invalid input" defaultValue="not-an-email" />
+        </Input>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With field
+
+Compose with `Field` to provide a visible label, helper text, and validation messaging.
+
+```tsx
+import { Field, Input } from '@cdx-ui/components';
+
+export default function InputWithFieldDemo() {
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Email address</Field.Label>
+      <Input isRequired>
+        <Input.Field
+          autoCapitalize="none"
+          autoComplete="email"
+          keyboardType="email-address"
+          placeholder="you@example.com"
+        />
+      </Input>
+      <Field.Helper>We will only use this for account notifications.</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## With field and validation
+
+Set the invalid state on both `Field` and `Input` so the error message and input styling stay in sync.
+
+```tsx
+import { Field, Input } from '@cdx-ui/components';
+
+export default function InputWithFieldInvalidDemo() {
+  return (
+    <Field className="w-full" isRequired isInvalid>
+      <Field.Label>Email address</Field.Label>
+      <Input isRequired isInvalid>
+        <Input.Field
+          autoCapitalize="none"
+          autoComplete="email"
+          defaultValue="not-an-email"
+          keyboardType="email-address"
+        />
+      </Input>
+      <Field.Error>Enter a valid email address.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### Input
+
+The root shell that lays out the field alongside optional slots and icons, and provides variant/size context to its sub-components.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the shell's own styles. |
+| `children?` | `ReactNode` | — | Shell content — typically `Input.Field` plus optional `Input.Slot`/`Input.Icon`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `View` host. |
+| `variant?` | `'outline'` | `'outline'` | Visual style variant. |
+| `size?` | `'default' \| 'small'` | `'default'` | Height, padding, and field font size. |
+| `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. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### Input.Field
+
+The editable text entry. A discriminated union on `type` — `'text'`/`'password'` render the standard field, while `'file'` switches to the web file-picker branch and enables the file-only props.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `type?` | `'text' \| 'password' \| 'file'` | — | — |
+| `disabled?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `isInvalid?` | `boolean` | — | — |
+| `isReadOnly?` | `boolean` | — | — |
+| `isRequired?` | `boolean` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `placeholderTextColorClassName?` | `string` | — | — |
+| `accept?` | `string` | — | — |
+| `multiple?` | `boolean` | — | — |
+| `capture?` | `'user' \| 'environment'` | — | — |
+| `onFiles?` | `((files: File[]) => void)` | — | — |
+
+Inherits all [`TextInputProps`](https://reactnative.dev/docs/textinput#props). `Input.Field` is a
+discriminated union on `type`; the file-only props (`accept`/`multiple`/`capture`/`onFiles`) apply
+when `type="file"`. `type="file"` is web-only. On native the field stays a text input, so use a
+platform file-picker library there.
+
+On web viewports below 600px, field text renders at 16px (`text-base`) for both sizes so iOS Safari
+does not auto-zoom the page when the input is focused. At 600px and above, web matches native sizes
+(14px default, 12px small).
+
+### Input.Slot
+
+A layout slot for adornments (icons, buttons, adornment text) rendered inside the shell before or after the field. The slot does not handle presses — wrap an interactive control in a `Pressable`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the slot's own styles. |
+| `children?` | `ReactNode` | — | Adornment content (icons, buttons, or adornment text). |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `View` host. |
+| `isDisabled?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Input.Icon
+
+Renders a Forge icon sized to the input. Inherits size from the parent Input context.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as?` | `ForgeIcon` | — | Forge icon component to render. Required unless `asChild` is set, in which case the consumer's substituted element is rendered instead. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default icon host. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+## Accessibility
+
+| Item                   | Behavior                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| Accessible name        | Compose with `Field.Label` (recommended) or pass `accessibilityLabel` on `Input.Field`.            |
+| Validation             | Pair `isInvalid` with `Field.Error` so the error is not communicated by color alone.               |
+| Required               | `isRequired` sets `aria-required` on web.                                                          |
+| Disabled and read-only | `isDisabled` and `isReadOnly` prevent editing and expose `aria-disabled` / `aria-readonly` on web. |