@coze-arch/cli 0.0.10-alpha.11b7ea → 0.0.10-alpha.954690

package/lib/__templates__/expo/client/heroui/components/tabs/tabs.md

@@ -1,565 +0,0 @@
-# Tabs
-
-Organize content into tabbed views with animated transitions and indicators.
-
-## Import
-
-```tsx
-import { Tabs } from '@/heroui';
-```
-
-## Anatomy
-
-```tsx
-<Tabs>
-  <Tabs.List>
-    <Tabs.ScrollView>
-      <Tabs.Indicator />
-      <Tabs.Trigger>
-        <Tabs.Label>...</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Separator />
-      <Tabs.Trigger>
-        <Tabs.Label>...</Tabs.Label>
-      </Tabs.Trigger>
-    </Tabs.ScrollView>
-  </Tabs.List>
-  <Tabs.Content>...</Tabs.Content>
-</Tabs>
-```
-
-- **Tabs**: Main container that manages tab state and selection. Controls active tab, handles value changes, and provides context to child components.
-- **Tabs.List**: Container for tab triggers. Groups triggers together with optional styling variants (primary or secondary).
-- **Tabs.ScrollView**: Optional scrollable wrapper for tab triggers. Enables horizontal scrolling when tabs overflow with automatic centering of active tab.
-- **Tabs.Trigger**: Interactive button for each tab. Handles press events to change active tab and measures its position for indicator animation.
-- **Tabs.Label**: Text content for tab triggers. Displays the tab title with appropriate styling.
-- **Tabs.Indicator**: Animated visual indicator for active tab. Smoothly transitions between tabs using spring or timing animations.
-- **Tabs.Separator**: Visual separator between tabs. Shows when the current tab value is not in the `betweenValues` array, with animated opacity transitions.
-- **Tabs.Content**: Container for tab panel content. Shows content when its value matches the active tab.
-
-## Usage
-
-### Basic Usage
-
-The Tabs component uses compound parts to create navigable content sections.
-
-```tsx
-<Tabs value="tab1" onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="tab1">
-      <Tabs.Label>Tab 1</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="tab2">
-      <Tabs.Label>Tab 2</Tabs.Label>
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="tab1">...</Tabs.Content>
-  <Tabs.Content value="tab2">...</Tabs.Content>
-</Tabs>
-```
-
-### Primary Variant
-
-Default rounded primary style for tab triggers.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="settings">
-      <Tabs.Label>Settings</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="profile">
-      <Tabs.Label>Profile</Tabs.Label>
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="settings">...</Tabs.Content>
-  <Tabs.Content value="profile">...</Tabs.Content>
-</Tabs>
-```
-
-### Secondary Variant
-
-Underline style indicator for a more minimal appearance.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab} variant="secondary">
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="overview">
-      <Tabs.Label>Overview</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="analytics">
-      <Tabs.Label>Analytics</Tabs.Label>
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="overview">...</Tabs.Content>
-  <Tabs.Content value="analytics">...</Tabs.Content>
-</Tabs>
-```
-
-### Scrollable Tabs
-
-Handle many tabs with horizontal scrolling.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.ScrollView scrollAlign="center">
-      <Tabs.Indicator />
-      <Tabs.Trigger value="tab1">
-        <Tabs.Label>First Tab</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Trigger value="tab2">
-        <Tabs.Label>Second Tab</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Trigger value="tab3">
-        <Tabs.Label>Third Tab</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Trigger value="tab4">
-        <Tabs.Label>Fourth Tab</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Trigger value="tab5">
-        <Tabs.Label>Fifth Tab</Tabs.Label>
-      </Tabs.Trigger>
-    </Tabs.ScrollView>
-  </Tabs.List>
-  <Tabs.Content value="tab1">...</Tabs.Content>
-  <Tabs.Content value="tab2">...</Tabs.Content>
-  <Tabs.Content value="tab3">...</Tabs.Content>
-  <Tabs.Content value="tab4">...</Tabs.Content>
-  <Tabs.Content value="tab5">...</Tabs.Content>
-</Tabs>
-```
-
-### Disabled Tabs
-
-Disable specific tabs to prevent interaction.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="active">
-      <Tabs.Label>Active</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="disabled" isDisabled>
-      <Tabs.Label>Disabled</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="another">
-      <Tabs.Label>Another</Tabs.Label>
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="active">...</Tabs.Content>
-  <Tabs.Content value="another">...</Tabs.Content>
-</Tabs>
-```
-
-### With Icons
-
-Combine icons with labels for enhanced visual context.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="home">
-      <Icon name="home" size={16} />
-      <Tabs.Label>Home</Tabs.Label>
-    </Tabs.Trigger>
-    <Tabs.Trigger value="search">
-      <Icon name="search" size={16} />
-      <Tabs.Label>Search</Tabs.Label>
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="home">...</Tabs.Content>
-  <Tabs.Content value="search">...</Tabs.Content>
-</Tabs>
-```
-
-### With Render Function
-
-Use a render function on `Tabs.Trigger` to access state and customize content based on selection.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.Indicator />
-    <Tabs.Trigger value="settings">
-      {({ isSelected, value, isDisabled }) => (
-        <Tabs.Label
-          className={isSelected ? 'text-accent font-medium' : 'text-foreground'}
-        >
-          Settings
-        </Tabs.Label>
-      )}
-    </Tabs.Trigger>
-    <Tabs.Trigger value="profile">
-      {({ isSelected }) => (
-        <>
-          <Icon name="user" size={16} />
-          <Tabs.Label className={isSelected ? 'text-accent' : 'text-muted'}>
-            Profile
-          </Tabs.Label>
-        </>
-      )}
-    </Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="settings">...</Tabs.Content>
-  <Tabs.Content value="profile">...</Tabs.Content>
-</Tabs>
-```
-
-### With Separators
-
-Add visual separators between tabs that show when the active tab is not between specified values.
-
-```tsx
-<Tabs value={activeTab} onValueChange={setActiveTab}>
-  <Tabs.List>
-    <Tabs.ScrollView>
-      <Tabs.Indicator />
-      <Tabs.Trigger value="general">
-        <Tabs.Label>General</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Separator betweenValues={['general', 'notifications']} />
-      <Tabs.Trigger value="notifications">
-        <Tabs.Label>Notifications</Tabs.Label>
-      </Tabs.Trigger>
-      <Tabs.Separator betweenValues={['notifications', 'profile']} />
-      <Tabs.Trigger value="profile">
-        <Tabs.Label>Profile</Tabs.Label>
-      </Tabs.Trigger>
-    </Tabs.ScrollView>
-  </Tabs.List>
-  <Tabs.Content value="general">...</Tabs.Content>
-  <Tabs.Content value="notifications">...</Tabs.Content>
-  <Tabs.Content value="profile">...</Tabs.Content>
-</Tabs>
-```
-
-## Example
-
-```tsx
-import {
-  Button,
-  Checkbox,
-  Description,
-  ControlField,
-  Label,
-  Tabs,
-  TextField,
-} from '@/heroui';
-import { useState } from 'react';
-import { View, Text } from 'react-native';
-import Animated, {
-  FadeIn,
-  FadeOut,
-  LinearTransition,
-} from 'react-native-reanimated';
-
-const AnimatedContentContainer = ({
-  children,
-}: {
-  children: React.ReactNode;
-}) => (
-  <Animated.View
-    entering={FadeIn.duration(200)}
-    exiting={FadeOut.duration(200)}
-    className="gap-6"
-  >
-    {children}
-  </Animated.View>
-);
-
-export default function TabsExample() {
-  const [activeTab, setActiveTab] = useState('general');
-
-  const [showSidebar, setShowSidebar] = useState(true);
-  const [accountActivity, setAccountActivity] = useState(true);
-  const [name, setName] = useState('');
-
-  return (
-    <Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
-      <Tabs.List>
-        <Tabs.ScrollView>
-          <Tabs.Indicator />
-          <Tabs.Trigger value="general">
-            <Tabs.Label>General</Tabs.Label>
-          </Tabs.Trigger>
-          <Tabs.Trigger value="notifications">
-            <Tabs.Label>Notifications</Tabs.Label>
-          </Tabs.Trigger>
-          <Tabs.Trigger value="profile">
-            <Tabs.Label>Profile</Tabs.Label>
-          </Tabs.Trigger>
-        </Tabs.ScrollView>
-      </Tabs.List>
-
-      <Animated.View
-        layout={LinearTransition.duration(200)}
-        className="px-4 py-6 border border-border rounded-xl"
-      >
-        <Tabs.Content value="general">
-          <AnimatedContentContainer>
-            <ControlField
-              isSelected={showSidebar}
-              onSelectedChange={setShowSidebar}
-            >
-              <ControlField.Indicator variant="checkbox" />
-              <View className="flex-1">
-                <Label>Show sidebar</Label>
-                <Description>Display the sidebar navigation panel</Description>
-              </View>
-            </ControlField>
-          </AnimatedContentContainer>
-        </Tabs.Content>
-
-        <Tabs.Content value="notifications">
-          <AnimatedContentContainer>
-            <ControlField
-              isSelected={accountActivity}
-              onSelectedChange={setAccountActivity}
-            >
-              <ControlField.Indicator variant="checkbox" />
-              <View className="flex-1">
-                <Label>Account activity</Label>
-                <Description>
-                  Notifications about your account activity
-                </Description>
-              </View>
-            </ControlField>
-          </AnimatedContentContainer>
-        </Tabs.Content>
-
-        <Tabs.Content value="profile">
-          <AnimatedContentContainer>
-            <TextField isRequired>
-              <Label>Name</Label>
-              <Input
-                value={name}
-                onChangeText={setName}
-                placeholder="Enter your full name"
-              />
-            </TextField>
-            <Button size="sm" className="self-start">
-              <Button.Label>Update profile</Button.Label>
-            </Button>
-          </AnimatedContentContainer>
-        </Tabs.Content>
-      </Animated.View>
-    </Tabs>
-  );
-}
-```
-
-You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/tabs.tsx>).
-
-## API Reference
-
-### Tabs
-
-| prop            | type                         | default     | description                                                                               |
-| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
-| `children`      | `React.ReactNode`            | -           | Children elements to be rendered inside tabs                                              |
-| `value`         | `string`                     | -           | Currently active tab value                                                                |
-| `variant`       | `'primary' \| 'secondary'`   | `'primary'` | Visual variant of the tabs                                                                |
-| `className`     | `string`                     | -           | Additional CSS classes for the container                                                  |
-| `animation`     | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
-| `onValueChange` | `(value: string) => void`    | -           | Callback when the active tab changes                                                      |
-| `...ViewProps`  | `ViewProps`                  | -           | All standard React Native View props are supported                                        |
-
-### Tabs.List
-
-| prop           | type              | default | description                                        |
-| -------------- | ----------------- | ------- | -------------------------------------------------- |
-| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the list   |
-| `className`    | `string`          | -       | Additional CSS classes                             |
-| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |
-
-### Tabs.ScrollView
-
-| prop                        | type                                     | default    | description                                              |
-| --------------------------- | ---------------------------------------- | ---------- | -------------------------------------------------------- |
-| `children`                  | `React.ReactNode`                        | -          | Children elements to be rendered inside the scroll view  |
-| `scrollAlign`               | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | Scroll alignment variant for the selected item           |
-| `className`                 | `string`                                 | -          | Additional CSS classes for the scroll view               |
-| `contentContainerClassName` | `string`                                 | -          | Additional CSS classes for the content container         |
-| `...ScrollViewProps`        | `ScrollViewProps`                        | -          | All standard React Native ScrollView props are supported |
-
-### Tabs.Trigger
-
-| prop                | type                                                                      | default | description                                                               |
-| ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
-| `children`          | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the trigger, or a render function |
-| `value`             | `string`                                                                  | -       | The unique value identifying this tab                                     |
-| `isDisabled`        | `boolean`                                                                 | `false` | Whether the trigger is disabled                                           |
-| `className`         | `string`                                                                  | -       | Additional CSS classes                                                    |
-| `...PressableProps` | `PressableProps`                                                          | -       | All standard React Native Pressable props are supported                   |
-
-#### TabsTriggerRenderProps
-
-When using a render function for `children`, the following props are provided:
-
-| property     | type      | description                                |
-| ------------ | --------- | ------------------------------------------ |
-| `isSelected` | `boolean` | Whether this trigger is currently selected |
-| `value`      | `string`  | The value of the trigger                   |
-| `isDisabled` | `boolean` | Whether the trigger is disabled            |
-
-### Tabs.Label
-
-| prop           | type              | default | description                                        |
-| -------------- | ----------------- | ------- | -------------------------------------------------- |
-| `children`     | `React.ReactNode` | -       | Text content to be rendered as label               |
-| `className`    | `string`          | -       | Additional CSS classes                             |
-| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |
-
-### Tabs.Indicator
-
-| prop                    | type                     | default | description                                                  |
-| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
-| `children`              | `React.ReactNode`        | -       | Custom indicator content                                     |
-| `className`             | `string`                 | -       | Additional CSS classes                                       |
-| `animation`             | `TabsIndicatorAnimation` | -       | Animation configuration                                      |
-| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
-| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported             |
-
-#### TabsIndicatorAnimation
-
-Animation configuration for Tabs.Indicator component. Can be:
-
-- `false` or `"disabled"`: Disable all animations
-- `true` or `undefined`: Use default animations
-- `object`: Custom animation configuration
-
-| prop                | type                                   | default                                                                      | description                                     |
-| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- |
-| `state`             | `'disabled' \| boolean`                | -                                                                            | Disable animations while customizing properties |
-| `width.type`        | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
-| `width.config`      | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
-| `height.type`       | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
-| `height.config`     | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
-| `translateX.type`   | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
-| `translateX.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |
-
-### Tabs.Separator
-
-| prop                    | type                     | default | description                                                                                                                            |
-| ----------------------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `betweenValues`         | `string[]`               | -       | Array of tab values between which the separator should be visible. The separator shows when the current tab value is NOT in this array |
-| `isAlwaysVisible`       | `boolean`                | `false` | If true, opacity is always 1 regardless of the current tab value                                                                       |
-| `className`             | `string`                 | -       | Additional CSS classes                                                                                                                 |
-| `animation`             | `TabsSeparatorAnimation` | -       | Animation configuration                                                                                                                |
-| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active                                                                           |
-| `children`              | `React.ReactNode`        | -       | Custom separator content                                                                                                               |
-| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported                                                                                       |
-
-**Note:** The following style properties are occupied by animations and cannot be set via className:
-
-- `opacity` - Animated for separator visibility transitions (0 when current tab is in `betweenValues`, 1 when not)
-
-To customize these properties, use the `animation` prop. To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
-
-#### TabsSeparatorAnimation
-
-Animation configuration for Tabs.Separator component. Can be:
-
-- `false` or `"disabled"`: Disable all animations
-- `true` or `undefined`: Use default animations
-- `object`: Custom animation configuration
-
-| prop                   | type                    | default             | description                                     |
-| ---------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
-| `state`                | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
-| `opacity.value`        | `[number, number]`      | `[0, 1]`            | Opacity values [hidden, visible]                |
-| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200 }` | Animation timing configuration                  |
-
-### Tabs.Content
-
-| prop           | type              | default | description                                         |
-| -------------- | ----------------- | ------- | --------------------------------------------------- |
-| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the content |
-| `value`        | `string`          | -       | The value of the tab this content belongs to        |
-| `className`    | `string`          | -       | Additional CSS classes                              |
-| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported  |
-
-## Hooks
-
-### useTabs
-
-Hook to access tabs root context values within custom components or compound components.
-
-```tsx
-import { useTabs } from '@/heroui';
-
-const CustomComponent = () => {
-  const { value, onValueChange, nativeID } = useTabs();
-  // ... your implementation
-};
-```
-
-**Returns:** `UseTabsReturn`
-
-| property        | type                      | description                                |
-| --------------- | ------------------------- | ------------------------------------------ |
-| `value`         | `string`                  | Currently active tab value                 |
-| `onValueChange` | `(value: string) => void` | Callback function to change the active tab |
-| `nativeID`      | `string`                  | Unique identifier for the tabs instance    |
-
-**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.
-
-### useTabsMeasurements
-
-Hook to access tab measurements context values for managing tab trigger positions and dimensions.
-
-```tsx
-import { useTabsMeasurements } from '@/heroui';
-
-const CustomIndicator = () => {
-  const { measurements, variant } = useTabsMeasurements();
-  // ... your implementation
-};
-```
-
-**Returns:** `UseTabsMeasurementsReturn`
-
-| property          | type                                                    | description                                       |
-| ----------------- | ------------------------------------------------------- | ------------------------------------------------- |
-| `measurements`    | `Record<string, ItemMeasurements>`                      | Record of measurements for each tab trigger       |
-| `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | Function to update measurements for a tab trigger |
-| `variant`         | `'primary' \| 'secondary'`                              | Visual variant of the tabs                        |
-
-#### ItemMeasurements
-
-| property | type     | description                         |
-| -------- | -------- | ----------------------------------- |
-| `width`  | `number` | Width of the tab trigger in pixels  |
-| `height` | `number` | Height of the tab trigger in pixels |
-| `x`      | `number` | X position of the tab trigger       |
-
-**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.
-
-### useTabsTrigger
-
-Hook to access tab trigger context values within custom components or compound components.
-
-```tsx
-import { useTabsTrigger } from '@/heroui';
-
-const CustomLabel = () => {
-  const { value, isSelected, nativeID } = useTabsTrigger();
-  // ... your implementation
-};
-```
-
-**Returns:** `UseTabsTriggerReturn`
-
-| property     | type      | description                                |
-| ------------ | --------- | ------------------------------------------ |
-| `value`      | `string`  | The value of this trigger                  |
-| `nativeID`   | `string`  | Unique identifier for this trigger         |
-| `isSelected` | `boolean` | Whether this trigger is currently selected |
-
-**Note:** This hook must be used within a `Tabs.Trigger` component. It will throw an error if called outside of the trigger context.