@coze-arch/cli 0.0.1-alpha.3002ee → 0.0.1-alpha.3260db

package/lib/__templates__/expo/client/heroui/components/search-field/search-field.md

@@ -0,0 +1,231 @@
+# SearchField
+
+A compound search input for filtering and querying content.
+
+## Import
+
+```tsx
+import { SearchField } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<SearchField value={value} onChange={onChange}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+- **SearchField**: Root container that accepts `value` and `onChange`, providing them to children via context. Also provides form field state (isDisabled, isInvalid, isRequired) and animation settings.
+- **SearchField.Group**: Flex-row container that positions the search icon, input, and clear button horizontally.
+- **SearchField.SearchIcon**: Magnifying glass icon positioned absolutely on the left side of the input. Supports custom children to replace the default icon.
+- **SearchField.Input**: Wraps the Input component with search-specific defaults. Reads `value` and `onChangeText` from the SearchField context automatically.
+- **SearchField.ClearButton**: Small icon-only button to clear the search input. Automatically hidden when value is empty. Calls `onChange("")` from context on press.
+
+## Usage
+
+### Basic Usage
+
+The SearchField component uses compound parts to create a search input. Pass `value` and `onChange` to the root; the Input and ClearButton consume them via context.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### With Label and Description
+
+Add a Label and Description outside the Group to provide context for the search field.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <Label>Find products</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description>Search by name, category, or SKU</Description>
+</SearchField>
+```
+
+### With Validation
+
+Use `isInvalid` and `isRequired` on the root to control validation state. Pair with FieldError to display error messages.
+
+```tsx
+<SearchField
+  value={searchValue}
+  onChange={setSearchValue}
+  isRequired
+  isInvalid={isInvalid}
+>
+  <Label>Search users</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+  <Description hideOnInvalid>Enter at least 3 characters to search</Description>
+  <FieldError>No results found. Please try a different search term.</FieldError>
+</SearchField>
+```
+
+### Custom Search Icon
+
+Replace the default magnifying glass icon by passing children to `SearchField.SearchIcon`.
+
+```tsx
+<SearchField value={searchValue} onChange={setSearchValue}>
+  <SearchField.Group>
+    <SearchField.SearchIcon>
+      <Text className="text-base">🔍</Text>
+    </SearchField.SearchIcon>
+    <SearchField.Input className="pl-10" />
+    <SearchField.ClearButton />
+  </SearchField.Group>
+</SearchField>
+```
+
+### Disabled
+
+Set `isDisabled` on the root to disable all child components via context.
+
+```tsx
+<SearchField value="Previous query" isDisabled>
+  <Label>Disabled search</Label>
+  <SearchField.Group>
+    <SearchField.SearchIcon />
+    <SearchField.Input />
+  </SearchField.Group>
+  <Description>Search is temporarily unavailable</Description>
+</SearchField>
+```
+
+## Example
+
+```tsx
+import { Description, Label, SearchField } from '@/heroui';
+import { useState } from 'react';
+import { View } from 'react-native';
+
+export default function SearchFieldExample() {
+  const [searchValue, setSearchValue] = useState('');
+
+  return (
+    <View className="px-5">
+      <SearchField value={searchValue} onChange={setSearchValue}>
+        <Label>Find products</Label>
+        <SearchField.Group>
+          <SearchField.SearchIcon />
+          <SearchField.Input />
+          <SearchField.ClearButton />
+        </SearchField.Group>
+        <Description>Search by name, category, or SKU</Description>
+      </SearchField>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/search-field.tsx>).
+
+## API Reference
+
+### SearchField
+
+| prop           | type                      | default | description                                              |
+| -------------- | ------------------------- | ------- | -------------------------------------------------------- |
+| `children`     | `React.ReactNode`         | -       | Children elements to be rendered inside the search field |
+| `value`        | `string`                  | -       | Controlled search text value                             |
+| `onChange`     | `(value: string) => void` | -       | Callback fired when the search text changes              |
+| `isDisabled`   | `boolean`                 | `false` | Whether the search field is disabled                     |
+| `isInvalid`    | `boolean`                 | `false` | Whether the search field is in an invalid state          |
+| `isRequired`   | `boolean`                 | `false` | Whether the search field is required                     |
+| `className`    | `string`                  | -       | Additional CSS classes                                   |
+| `animation`    | `AnimationRootDisableAll` | -       | Animation configuration for the search field             |
+| `...ViewProps` | `ViewProps`               | -       | All standard React Native View props are supported       |
+
+#### AnimationRootDisableAll
+
+Animation configuration for the SearchField root component. Can be:
+
+- `"disable-all"`: Disable all animations including children (cascades down)
+- `undefined`: Use default animations
+
+### SearchField.Group
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the group  |
+| `className`    | `string`          | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### SearchField.SearchIcon
+
+| prop           | type                             | default | description                                                                        |
+| -------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                | -       | Custom content to replace the default search icon                                  |
+| `className`    | `string`                         | -       | Additional CSS classes                                                             |
+| `iconProps`    | `SearchFieldSearchIconIconProps` | -       | Props for customizing the default search icon (ignored when children are provided) |
+| `...ViewProps` | `ViewProps`                      | -       | All standard React Native View props are supported                                 |
+
+#### SearchFieldSearchIconIconProps
+
+| prop    | type     | default             | description       |
+| ------- | -------- | ------------------- | ----------------- |
+| `size`  | `number` | `16`                | Size of the icon  |
+| `color` | `string` | Theme `muted` color | Color of the icon |
+
+### SearchField.Input
+
+Extends [Input](../input/input.md) props with search-specific defaults (`placeholder="Search..."`, `returnKeyType="search"`, `accessibilityRole="search"`). Omits `value` and `onChangeText` because they are provided by the SearchField context.
+
+### SearchField.ClearButton
+
+Automatically hidden when the controlled `value` is an empty string. Calls `onChange("")` from context on press. Additional `onPress` handlers passed via props are called after clearing.
+
+| prop             | type                              | default | description                                      |
+| ---------------- | --------------------------------- | ------- | ------------------------------------------------ |
+| `children`       | `React.ReactNode`                 | -       | Custom content to replace the default close icon |
+| `iconProps`      | `SearchFieldClearButtonIconProps` | -       | Props for customizing the clear button icon      |
+| `className`      | `string`                          | -       | Additional CSS classes                           |
+| `...ButtonProps` | `ButtonRootProps`                 | -       | All Button root props are supported              |
+
+#### SearchFieldClearButtonIconProps
+
+| prop    | type     | default             | description       |
+| ------- | -------- | ------------------- | ----------------- |
+| `size`  | `number` | `14`                | Size of the icon  |
+| `color` | `string` | Theme `muted` color | Color of the icon |
+
+## Hooks
+
+### useSearchField
+
+Hook to access the search field state from context. Must be used within a `SearchField` component.
+
+```tsx
+import { useSearchField } from '@/heroui';
+
+const { value, onChange, isDisabled, isInvalid, isRequired } = useSearchField();
+```
+
+#### Returns
+
+| property     | type                                     | description                                     |
+| ------------ | ---------------------------------------- | ----------------------------------------------- |
+| `value`      | `string \| undefined`                    | Current controlled search text value            |
+| `onChange`   | `((value: string) => void) \| undefined` | Callback to update the search text              |
+| `isDisabled` | `boolean`                                | Whether the search field is disabled            |
+| `isInvalid`  | `boolean`                                | Whether the search field is in an invalid state |
+| `isRequired` | `boolean`                                | Whether the search field is required            |

package/lib/__templates__/expo/client/heroui/components/search-field/search-field.styles.ts

@@ -0,0 +1,35 @@
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'gap-1.5',
+});
+
+const group = tv({
+  base: 'flex-row items-center',
+});
+
+const searchIcon = tv({
+  base: 'absolute left-3 z-10',
+});
+
+/**
+ * @note This only applies SearchField-specific overrides (flex-1, pl-9).
+ * Base input styling (bg, border, focus, variants, etc.) comes from the Input component.
+ * @see {@link ../input/input.styles.ts} for the base Input styles.
+ */
+const input = tv({
+  base: 'flex-1 pl-9 pr-12',
+});
+
+const clearButton = tv({
+  base: 'absolute right-3 size-6',
+});
+
+export const searchFieldClassNames = combineStyles({
+  root,
+  group,
+  searchIcon,
+  input,
+  clearButton,
+});

package/lib/__templates__/expo/client/heroui/components/search-field/search-field.tsx

@@ -0,0 +1,253 @@
+import { forwardRef, useMemo } from 'react';
+import {
+  type GestureResponderEvent,
+  type TextInput as TextInputType,
+  View,
+} from 'react-native';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { CloseIcon } from '../../helpers/internal/components';
+import {
+  AnimationSettingsProvider,
+  FormFieldProvider,
+} from '../../helpers/internal/contexts';
+import type { ViewRef } from '../../helpers/internal/types';
+import { createContext } from '../../helpers/internal/utils';
+import { Button } from '../button';
+import { Input } from '../input';
+import { useSearchFieldRootAnimation } from './search-field.animation';
+import { DISPLAY_NAME } from './search-field.constants';
+import { searchFieldClassNames } from './search-field.styles';
+import type {
+  SearchFieldClearButtonProps,
+  SearchFieldContextType,
+  SearchFieldGroupProps,
+  SearchFieldInputProps,
+  SearchFieldProps,
+  SearchFieldSearchIconProps,
+} from './search-field.types';
+import { SearchIcon } from './search-icon';
+
+const [SearchFieldProvider, useSearchField] =
+  createContext<SearchFieldContextType>({
+    name: 'SearchFieldContext',
+    strict: false,
+  });
+
+// --------------------------------------------------
+
+const SearchFieldRoot = forwardRef<ViewRef, SearchFieldProps>((props, ref) => {
+  const {
+    children,
+    className,
+    value,
+    onChange,
+    isDisabled = false,
+    isInvalid = false,
+    isRequired = false,
+    animation,
+    ...restProps
+  } = props;
+
+  const rootClassName = searchFieldClassNames.root({ className });
+
+  const { isAllAnimationsDisabled } = useSearchFieldRootAnimation({
+    animation,
+  });
+
+  const searchFieldContextValue = useMemo<SearchFieldContextType>(
+    () => ({ value, onChange, isDisabled, isInvalid, isRequired }),
+    [value, onChange, isDisabled, isInvalid, isRequired]
+  );
+
+  const formFieldContextValue = useMemo(
+    () => ({ isDisabled, isInvalid, isRequired, hasFieldPadding: true }),
+    [isDisabled, isInvalid, isRequired]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <SearchFieldProvider value={searchFieldContextValue}>
+      <AnimationSettingsProvider value={animationSettingsContextValue}>
+        <FormFieldProvider value={formFieldContextValue}>
+          <View ref={ref} className={rootClassName} {...restProps}>
+            {children}
+          </View>
+        </FormFieldProvider>
+      </AnimationSettingsProvider>
+    </SearchFieldProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const SearchFieldGroup = forwardRef<ViewRef, SearchFieldGroupProps>(
+  (props, ref) => {
+    const { children, className, ...restProps } = props;
+
+    const groupClassName = searchFieldClassNames.group({ className });
+
+    return (
+      <View ref={ref} className={groupClassName} {...restProps}>
+        {children}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const SearchFieldSearchIcon = forwardRef<View, SearchFieldSearchIconProps>(
+  (props, ref) => {
+    const { children, className, iconProps, ...restProps } = props;
+
+    const searchIconClassName = searchFieldClassNames.searchIcon({ className });
+
+    return (
+      <View
+        ref={ref}
+        className={searchIconClassName}
+        pointerEvents="none"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        {...restProps}
+      >
+        {children ?? (
+          <SearchIcon size={iconProps?.size} color={iconProps?.color} />
+        )}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const SearchFieldInput = forwardRef<TextInputType, SearchFieldInputProps>(
+  (props, ref) => {
+    const {
+      className,
+      placeholder = 'Search...',
+      returnKeyType = 'search',
+      accessibilityRole = 'search',
+      accessibilityLabel = 'Search',
+      ...restProps
+    } = props;
+
+    const searchField = useSearchField();
+
+    const inputClassName = searchFieldClassNames.input({ className });
+
+    return (
+      <Input
+        ref={ref}
+        className={inputClassName}
+        value={searchField?.value}
+        onChangeText={searchField?.onChange}
+        placeholder={placeholder}
+        returnKeyType={returnKeyType}
+        accessibilityRole={accessibilityRole}
+        accessibilityLabel={accessibilityLabel}
+        {...restProps}
+      />
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const SearchFieldClearButton = forwardRef<View, SearchFieldClearButtonProps>(
+  (props, ref) => {
+    const { iconProps, className, children, onPress, ...restProps } = props;
+
+    const searchField = useSearchField();
+    const themeColorMuted = useThemeColor('muted');
+
+    if (searchField?.value !== undefined && searchField.value.length === 0) {
+      return null;
+    }
+
+    const handlePress = (event: GestureResponderEvent) => {
+      searchField?.onChange?.('');
+
+      if (typeof onPress === 'function') {
+        onPress(event);
+      }
+    };
+
+    const clearButtonClassName = searchFieldClassNames.clearButton({
+      className,
+    });
+
+    return (
+      <Button
+        ref={ref}
+        variant="tertiary"
+        size="sm"
+        isIconOnly
+        className={clearButtonClassName}
+        hitSlop={8}
+        accessibilityRole="button"
+        accessibilityLabel="Clear search"
+        onPress={handlePress}
+        {...restProps}
+      >
+        {children ?? (
+          <CloseIcon
+            size={iconProps?.size ?? 14}
+            color={iconProps?.color ?? themeColorMuted}
+          />
+        )}
+      </Button>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+SearchFieldRoot.displayName = DISPLAY_NAME.SEARCH_FIELD;
+SearchFieldGroup.displayName = DISPLAY_NAME.SEARCH_FIELD_GROUP;
+SearchFieldSearchIcon.displayName = DISPLAY_NAME.SEARCH_FIELD_SEARCH_ICON;
+SearchFieldInput.displayName = DISPLAY_NAME.SEARCH_FIELD_INPUT;
+SearchFieldClearButton.displayName = DISPLAY_NAME.SEARCH_FIELD_CLEAR_BUTTON;
+
+/**
+ * Compound SearchField component with sub-components.
+ *
+ * @component SearchField - Root container that accepts `value`, `onChange`,
+ * `isDisabled`, `isInvalid`, and `isRequired`, providing them to children via
+ * SearchFieldContext. Also provides FormFieldProvider and animation settings.
+ *
+ * @component SearchField.Group - Flex-row container for the search icon, input,
+ * and clear button.
+ *
+ * @component SearchField.SearchIcon - Magnifying glass icon positioned
+ * absolutely on the left.
+ *
+ * @component SearchField.Input - Wraps the Input component with search-specific
+ * defaults: "Search..." placeholder, left padding for the search icon, and
+ * search a11y role. Reads `value` / `onChangeText` from SearchFieldContext.
+ *
+ * @component SearchField.ClearButton - Small button that clears the search
+ * input. Automatically hidden when value is empty. Calls `onChange("")` from
+ * context on press.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/search-field
+ */
+const CompoundSearchField = Object.assign(SearchFieldRoot, {
+  /** Flex-row container for search icon, input, and clear button */
+  Group: SearchFieldGroup,
+  /** Magnifying glass search icon */
+  SearchIcon: SearchFieldSearchIcon,
+  /** Text input with search-specific defaults */
+  Input: SearchFieldInput,
+  /** Small clear button to dismiss search text */
+  ClearButton: SearchFieldClearButton,
+});
+
+export { useSearchField };
+export default CompoundSearchField;

package/lib/__templates__/expo/client/heroui/components/search-field/search-field.types.ts

@@ -0,0 +1,160 @@
+import type { ViewProps } from 'react-native';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+import type { ButtonRootProps } from '../button/button.types';
+import type { InputProps } from '../input/input.types';
+
+/**
+ * Context value provided by SearchField root to child components.
+ * Carries the controlled value, onChange callback, and form-field
+ * state so that Input and ClearButton can consume them.
+ */
+export interface SearchFieldContextType {
+  /** Current search text (undefined when uncontrolled) */
+  value: string | undefined;
+  /** Callback invoked when the search text changes */
+  onChange: ((value: string) => void) | undefined;
+  /** Whether the search field is disabled */
+  isDisabled: boolean;
+  /** Whether the search field is in an invalid state */
+  isInvalid: boolean;
+  /** Whether the search field is required */
+  isRequired: boolean;
+}
+
+/**
+ * Props for the SearchField root component
+ */
+export interface SearchFieldProps extends ViewProps {
+  /**
+   * Children elements to be rendered inside the search field
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Controlled search text value
+   */
+  value?: string;
+
+  /**
+   * Callback fired when the search text changes
+   */
+  onChange?: (value: string) => void;
+
+  /**
+   * Whether the search field is disabled
+   * @default false
+   */
+  isDisabled?: boolean;
+
+  /**
+   * Whether the search field is in an invalid state
+   * @default false
+   */
+  isInvalid?: boolean;
+
+  /**
+   * Whether the search field is required
+   * @default false
+   */
+  isRequired?: boolean;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Animation configuration for search field
+   * - `"disable-all"`: Disable all animations including children (cascades down)
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Props for the SearchField.Group component
+ */
+export interface SearchFieldGroupProps extends ViewProps {
+  /**
+   * Children elements to be rendered inside the group
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * Props for customizing the default search icon
+ */
+export interface SearchFieldSearchIconIconProps {
+  /**
+   * Size of the search icon
+   * @default 16
+   */
+  size?: number;
+
+  /**
+   * Color of the search icon
+   * @default Uses theme muted color
+   */
+  color?: string;
+}
+
+/**
+ * Props for the SearchField.SearchIcon component
+ */
+export interface SearchFieldSearchIconProps extends ViewProps {
+  /**
+   * Custom content to replace the default search icon
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Props for customizing the default search icon (ignored when children are provided)
+   */
+  iconProps?: SearchFieldSearchIconIconProps;
+}
+
+/**
+ * Props for the SearchField.Input component.
+ * Extends InputProps with search-specific defaults (placeholder, a11y role).
+ * Omits `value` and `onChangeText` because they are provided by SearchField
+ * root through SearchFieldValueContext.
+ */
+export interface SearchFieldInputProps
+  extends Omit<InputProps, 'value' | 'onChangeText'> {}
+
+/**
+ * Props for customizing the clear button icon
+ */
+export interface SearchFieldClearButtonIconProps {
+  /**
+   * Size of the icon
+   * @default 14
+   */
+  size?: number;
+
+  /**
+   * Color of the icon
+   * @default Uses theme muted color
+   */
+  color?: string;
+}
+
+/**
+ * Props for the SearchField.ClearButton component
+ */
+export type SearchFieldClearButtonProps = ButtonRootProps & {
+  /**
+   * Props for customizing the clear button icon
+   */
+  iconProps?: SearchFieldClearButtonIconProps;
+};