@coze-arch/cli 0.0.10 → 0.0.11

package/lib/__templates__/expo/client/heroui/components/list-group/list-group.md

@@ -0,0 +1,387 @@
+# ListGroup
+
+A Surface-based container that groups related list items with consistent layout and spacing.
+
+## Import
+
+```tsx
+import { ListGroup } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>...</ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>...</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>...</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+- **ListGroup**: Surface-based root container that groups related list items. Supports all Surface variants (default, secondary, tertiary, transparent).
+- **ListGroup.Item**: Pressable horizontal flex-row container for a single item, providing consistent spacing and alignment.
+- **ListGroup.ItemPrefix**: Optional leading content slot for icons, avatars, or other visual elements.
+- **ListGroup.ItemContent**: Flex-1 wrapper for title and description, occupying the remaining horizontal space.
+- **ListGroup.ItemTitle**: Primary text label styled with foreground color and medium font weight.
+- **ListGroup.ItemDescription**: Secondary text styled with muted color and smaller font size.
+- **ListGroup.ItemSuffix**: Optional trailing content slot. Renders a chevron-right icon by default; accepts children to override the default icon.
+
+## Usage
+
+### Basic Usage
+
+The ListGroup component uses compound parts to create grouped list items with title and description.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Personal Info</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Name, email, phone number
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Payment Methods</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Visa ending in 4829
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### With Icons
+
+Add leading icons using the `ListGroup.ItemPrefix` slot.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="person-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Profile</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Name, photo, bio
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="lock-closed-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Security</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        Password, 2FA
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Title Only
+
+Omit `ListGroup.ItemDescription` to display title-only items.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="wifi-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemPrefix>
+      <Icon name="bluetooth-outline" size={22} />
+    </ListGroup.ItemPrefix>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Bluetooth</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Surface Variant
+
+Apply a different visual variant to the root container.
+
+```tsx
+<ListGroup variant="transparent">
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Custom Suffix
+
+Override the default chevron icon by passing children to `ListGroup.ItemSuffix`.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Language</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>English</ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Icon name="arrow-forward" size={18} />
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+  <Separator className="mx-4" />
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix>
+      <Chip variant="primary" color="danger">
+        <Chip.Label className="font-bold">7</Chip.Label>
+      </Chip>
+    </ListGroup.ItemSuffix>
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### Custom Suffix Icon Props
+
+Customise the default chevron icon size and color using `iconProps`.
+
+```tsx
+<ListGroup>
+  <ListGroup.Item>
+    <ListGroup.ItemContent>
+      <ListGroup.ItemTitle>Storage</ListGroup.ItemTitle>
+      <ListGroup.ItemDescription>
+        12.4 GB of 50 GB used
+      </ListGroup.ItemDescription>
+    </ListGroup.ItemContent>
+    <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+  </ListGroup.Item>
+</ListGroup>
+```
+
+### With PressableFeedback
+
+Wrap items with `PressableFeedback` to add scale and ripple press feedback animations. When using this pattern, pass `onPress` on `PressableFeedback` instead of `ListGroup.Item` and disable the item with `disabled` prop.
+
+```tsx
+import { ListGroup, PressableFeedback, Separator } from '@/heroui';
+
+<ListGroup>
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Appearance</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            Theme, font size, display
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+  <Separator className="mx-4" />
+  <PressableFeedback animation={false} onPress={() => {}}>
+    <PressableFeedback.Scale>
+      <ListGroup.Item disabled>
+        <ListGroup.ItemContent>
+          <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+          <ListGroup.ItemDescription>
+            Alerts, sounds, badges
+          </ListGroup.ItemDescription>
+        </ListGroup.ItemContent>
+        <ListGroup.ItemSuffix />
+      </ListGroup.Item>
+    </PressableFeedback.Scale>
+    <PressableFeedback.Ripple />
+  </PressableFeedback>
+</ListGroup>
+```
+
+## Example
+
+```tsx
+import { Ionicons } from '@expo/vector-icons';
+import { ListGroup, Separator, useThemeColor } from '@/heroui';
+import { View, Text } from 'react-native';
+import { withUniwind } from 'uniwind';
+
+const StyledIonicons = withUniwind(Ionicons);
+
+export default function ListGroupExample() {
+  const mutedColor = useThemeColor('muted');
+
+  return (
+    <View className="flex-1 justify-center px-5">
+      <Text className="text-sm text-muted mb-2 ml-2">Account</Text>
+      <ListGroup className="mb-6">
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="person-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Personal Info</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Name, email, phone number
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="card-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Payment Methods</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Visa ending in 4829
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+      </ListGroup>
+      <Text className="text-sm text-muted mb-2 ml-2">Preferences</Text>
+      <ListGroup>
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="color-palette-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Appearance</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Theme, font size, display
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix />
+        </ListGroup.Item>
+        <Separator className="mx-4" />
+        <ListGroup.Item>
+          <ListGroup.ItemPrefix>
+            <StyledIonicons
+              name="notifications-outline"
+              size={22}
+              className="text-foreground"
+            />
+          </ListGroup.ItemPrefix>
+          <ListGroup.ItemContent>
+            <ListGroup.ItemTitle>Notifications</ListGroup.ItemTitle>
+            <ListGroup.ItemDescription>
+              Alerts, sounds, badges
+            </ListGroup.ItemDescription>
+          </ListGroup.ItemContent>
+          <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
+        </ListGroup.Item>
+      </ListGroup>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/list-group.tsx).
+
+## API Reference
+
+### ListGroup
+
+| prop           | type                                                       | default     | description                                        |
+| -------------- | ---------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                                          | -           | Children elements to be rendered inside the group  |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | Visual variant of the underlying Surface container |
+| `className`    | `string`                                                   | -           | Additional CSS classes for the root container      |
+| `...ViewProps` | `ViewProps`                                                | -           | All standard React Native View props are supported |
+
+### ListGroup.Item
+
+| prop                | type              | default | description                                             |
+| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
+| `children`          | `React.ReactNode` | -       | Children elements to be rendered inside the item        |
+| `className`         | `string`          | -       | Additional CSS classes for the item                     |
+| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |
+
+### ListGroup.ItemPrefix
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Leading content such as icons or avatars               |
+| `className`    | `string`          | -       | Additional CSS classes for the prefix                  |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported     |
+
+### ListGroup.ItemContent
+
+| prop           | type              | default | description                                            |
+| -------------- | ----------------- | ------- | ------------------------------------------------------ |
+| `children`     | `React.ReactNode` | -       | Content area, typically title and description          |
+| `className`    | `string`          | -       | Additional CSS classes for the content area            |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported     |
+
+### ListGroup.ItemTitle
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Title text or custom content                       |
+| `className`    | `string`          | -       | Additional CSS classes for the title               |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### ListGroup.ItemDescription
+
+| prop           | type              | default | description                                        |
+| -------------- | ----------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode` | -       | Description text or custom content                 |
+| `className`    | `string`          | -       | Additional CSS classes for the description         |
+| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
+
+### ListGroup.ItemSuffix
+
+| prop           | type                 | default | description                                                                        |
+| -------------- | -------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`    | -       | Custom trailing content; overrides the default chevron-right icon when provided    |
+| `className`    | `string`             | -       | Additional CSS classes for the suffix                                              |
+| `iconProps`    | `ListGroupIconProps` | -       | Props to customise the default chevron-right icon. Only applies when no children   |
+| `...ViewProps` | `ViewProps`          | -       | All standard React Native View props are supported                                 |
+
+#### ListGroupIconProps
+
+| prop    | type     | default             | description                        |
+| ------- | -------- | ------------------- | ---------------------------------- |
+| `size`  | `number` | `16`                | Size of the chevron icon in pixels |
+| `color` | `string` | theme `muted` color | Color of the chevron icon          |

package/lib/__templates__/expo/client/heroui/components/list-group/list-group.styles.ts

@@ -0,0 +1,40 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'p-0',
+});
+
+const item = tv({
+  base: 'flex-row items-center p-4 gap-3',
+});
+
+const itemContent = tv({
+  base: 'flex-1',
+});
+
+const itemTitle = tv({
+  base: 'text-base text-foreground font-medium',
+});
+
+const itemDescription = tv({
+  base: 'text-sm text-muted',
+});
+
+const listGroupClassNames = combineStyles({
+  root,
+  item,
+  itemContent,
+  itemTitle,
+  itemDescription,
+});
+
+export const styleSheet = StyleSheet.create({
+  root: {
+    borderCurve: 'continuous',
+  },
+});
+
+export { listGroupClassNames };
+export default listGroupClassNames;

package/lib/__templates__/expo/client/heroui/components/list-group/list-group.tsx

@@ -0,0 +1,206 @@
+import React, { forwardRef } from 'react';
+import { Pressable, View } from 'react-native';
+import { useThemeColor } from '../../helpers/external/hooks';
+import { ChevronRightIcon, HeroText } from '../../helpers/internal/components';
+import type { PressableRef, ViewRef } from '../../helpers/internal/types';
+import Surface from '../surface/surface';
+import { DEFAULT_ICON_SIZE, DISPLAY_NAME } from './list-group.constants';
+import listGroupClassNames, { styleSheet } from './list-group.styles';
+import type {
+  ListGroupIconProps,
+  ListGroupItemContentProps,
+  ListGroupItemDescriptionProps,
+  ListGroupItemPrefixProps,
+  ListGroupItemProps,
+  ListGroupItemSuffixProps,
+  ListGroupItemTitleProps,
+  ListGroupRootProps,
+} from './list-group.types';
+
+// --------------------------------------------------
+
+const ListGroupRoot = forwardRef<ViewRef, ListGroupRootProps>((props, ref) => {
+  const {
+    children,
+    variant = 'default',
+    className,
+    style,
+    ...restProps
+  } = props;
+
+  const rootClassName = listGroupClassNames.root({ className });
+
+  return (
+    <Surface
+      ref={ref}
+      variant={variant}
+      className={rootClassName}
+      style={[styleSheet.root, style]}
+      {...restProps}
+    >
+      {children}
+    </Surface>
+  );
+});
+
+// --------------------------------------------------
+
+const ListGroupItem = forwardRef<PressableRef, ListGroupItemProps>(
+  (props, ref) => {
+    const { children, className, ...restProps } = props;
+
+    const itemClassName = listGroupClassNames.item({ className });
+
+    return (
+      <Pressable ref={ref} className={itemClassName} {...restProps}>
+        {children}
+      </Pressable>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const ListGroupItemPrefix = forwardRef<ViewRef, ListGroupItemPrefixProps>(
+  (props, ref) => {
+    const { children, ...restProps } = props;
+
+    return (
+      <View ref={ref} {...restProps}>
+        {children}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const ListGroupItemContent = forwardRef<ViewRef, ListGroupItemContentProps>(
+  (props, ref) => {
+    const { children, className, style, ...restProps } = props;
+
+    const contentClassName = listGroupClassNames.itemContent({ className });
+
+    return (
+      <View ref={ref} className={contentClassName} style={style} {...restProps}>
+        {children}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+const ListGroupItemTitle = forwardRef<
+  React.ComponentRef<typeof HeroText>,
+  ListGroupItemTitleProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const titleClassName = listGroupClassNames.itemTitle({ className });
+
+  return (
+    <HeroText ref={ref} className={titleClassName} {...restProps}>
+      {children}
+    </HeroText>
+  );
+});
+
+// --------------------------------------------------
+
+const ListGroupItemDescription = forwardRef<
+  React.ComponentRef<typeof HeroText>,
+  ListGroupItemDescriptionProps
+>((props, ref) => {
+  const { children, className, ...restProps } = props;
+
+  const descriptionClassName = listGroupClassNames.itemDescription({
+    className,
+  });
+
+  return (
+    <HeroText ref={ref} className={descriptionClassName} {...restProps}>
+      {children}
+    </HeroText>
+  );
+});
+
+// --------------------------------------------------
+
+const ListGroupItemSuffix = forwardRef<ViewRef, ListGroupItemSuffixProps>(
+  (props, ref) => {
+    const { children, iconProps, ...restProps } = props;
+
+    const themeColorMuted = useThemeColor('muted');
+
+    const resolvedIconProps: ListGroupIconProps = {
+      size: iconProps?.size ?? DEFAULT_ICON_SIZE,
+      color: iconProps?.color ?? themeColorMuted,
+    };
+
+    return (
+      <View ref={ref} {...restProps}>
+        {children ?? (
+          <ChevronRightIcon
+            size={resolvedIconProps.size}
+            color={resolvedIconProps.color}
+          />
+        )}
+      </View>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+ListGroupRoot.displayName = DISPLAY_NAME.ROOT;
+ListGroupItem.displayName = DISPLAY_NAME.ITEM;
+ListGroupItemPrefix.displayName = DISPLAY_NAME.ITEM_PREFIX;
+ListGroupItemContent.displayName = DISPLAY_NAME.ITEM_CONTENT;
+ListGroupItemTitle.displayName = DISPLAY_NAME.ITEM_TITLE;
+ListGroupItemDescription.displayName = DISPLAY_NAME.ITEM_DESCRIPTION;
+ListGroupItemSuffix.displayName = DISPLAY_NAME.ITEM_SUFFIX;
+
+/**
+ * Compound ListGroup component with sub-components
+ *
+ * @component ListGroup - Surface-based container that groups related list items.
+ * Supports all Surface variants (default, secondary, tertiary, transparent).
+ *
+ * @component ListGroup.Item - Horizontal flex-row container for a single item,
+ * providing consistent spacing and alignment.
+ *
+ * @component ListGroup.ItemPrefix - Optional leading content slot for icons,
+ * avatars, or other visual elements.
+ *
+ * @component ListGroup.ItemContent - Flex-1 wrapper for title and description,
+ * occupying the remaining horizontal space.
+ *
+ * @component ListGroup.ItemTitle - Primary text label styled with foreground color
+ * and medium font weight.
+ *
+ * @component ListGroup.ItemDescription - Secondary text styled with muted color
+ * and smaller font size.
+ *
+ * @component ListGroup.ItemSuffix - Optional trailing content slot. Renders a
+ * chevron-right icon by default; accepts children to override the default icon.
+ * Supports iconProps (size, color) for customising the default chevron.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/list-group
+ */
+const CompoundListGroup = Object.assign(ListGroupRoot, {
+  /** @optional Single item row with flex-row layout */
+  Item: ListGroupItem,
+  /** @optional Leading visual element (icon / avatar) */
+  ItemPrefix: ListGroupItemPrefix,
+  /** @optional Flex-1 content wrapper for title and description */
+  ItemContent: ListGroupItemContent,
+  /** @optional Primary text label */
+  ItemTitle: ListGroupItemTitle,
+  /** @optional Secondary descriptive text */
+  ItemDescription: ListGroupItemDescription,
+  /** @optional Trailing element, defaults to chevron-right icon */
+  ItemSuffix: ListGroupItemSuffix,
+});
+
+export default CompoundListGroup;