@coze-arch/cli 0.0.10 → 0.0.11

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

@@ -0,0 +1,94 @@
+import React, { useMemo, type PropsWithChildren } from 'react';
+
+import { View } from 'react-native';
+import { createContext } from '../../helpers/internal/utils';
+import Skeleton from '../skeleton/skeleton';
+import { DISPLAY_NAME } from './skeleton-group.constants';
+import { skeletonGroupClassNames } from './skeleton-group.styles';
+import type {
+  SkeletonGroupContextValue,
+  SkeletonGroupItemProps,
+  SkeletonGroupRootProps,
+} from './skeleton-group.types';
+
+const [SkeletonGroupProvider, useSkeletonGroupContext] =
+  createContext<SkeletonGroupContextValue>({
+    name: 'SkeletonGroupContext',
+    errorMessage:
+      'useSkeletonGroupContext: must be used within a SkeletonGroup',
+  });
+
+// --------------------------------------------------
+
+const SkeletonGroupRoot: React.FC<PropsWithChildren<SkeletonGroupRootProps>> = (
+  props
+) => {
+  const {
+    children,
+    className,
+    style,
+    isSkeletonOnly = false,
+    ...restProps
+  } = props;
+
+  const rootClassName = skeletonGroupClassNames.root({ className });
+
+  const contextValue = useMemo<SkeletonGroupContextValue>(
+    () => ({
+      ...restProps,
+    }),
+    [restProps]
+  );
+
+  if (isSkeletonOnly && !restProps.isLoading) {
+    return null;
+  }
+
+  return (
+    <SkeletonGroupProvider value={contextValue}>
+      <View className={rootClassName} style={style}>
+        {children}
+      </View>
+    </SkeletonGroupProvider>
+  );
+};
+
+// --------------------------------------------------
+
+const SkeletonGroupItem: React.FC<SkeletonGroupItemProps> = (props) => {
+  const context = useSkeletonGroupContext();
+
+  const itemProps = {
+    ...context,
+    ...props,
+  };
+
+  return <Skeleton {...itemProps} />;
+};
+
+// --------------------------------------------------
+
+SkeletonGroupRoot.displayName = DISPLAY_NAME.SKELETON_GROUP_ROOT;
+SkeletonGroupItem.displayName = DISPLAY_NAME.SKELETON_GROUP_ITEM;
+
+/**
+ * Compound SkeletonGroup component for managing multiple skeleton loading states
+ *
+ * @component SkeletonGroup - Root container that provides centralized control for all skeleton items.
+ * Passes isLoading, variant, and animation to child items via context.
+ *
+ * @component SkeletonGroup.Item - Individual skeleton item that inherits props from the parent group.
+ * Can override group props with its own props for specific customization.
+ *
+ * Props flow from SkeletonGroup to Items via context (isLoading, variant, animation).
+ * Items can override any inherited prop by passing their own values.
+ *
+ * @see Full documentation: https://v3.heroui.com/docs/native/components/skeleton-group
+ */
+const SkeletonGroup = Object.assign(SkeletonGroupRoot, {
+  /** @optional Individual skeleton item that inherits group settings */
+  Item: SkeletonGroupItem,
+});
+
+export default SkeletonGroup;
+export { useSkeletonGroupContext };

package/lib/__templates__/expo/client/heroui/components/skeleton-group/skeleton-group.types.ts

@@ -0,0 +1,28 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SkeletonProps } from '../skeleton/skeleton.types';
+
+/**
+ * Props for the SkeletonGroup root component
+ */
+export interface SkeletonGroupRootProps extends Omit<SkeletonProps, 'style'> {
+  /**
+   * When true, hides the entire group when isLoading is false.
+   * Use this to prevent layout issues when skeleton contains wrapper elements.
+   * @default false
+   */
+  isSkeletonOnly?: boolean;
+  /**
+   * Style for the skeleton group container
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Context value for SkeletonGroup provider
+ */
+export interface SkeletonGroupContextValue extends SkeletonGroupRootProps {}
+
+/**
+ * Props for the SkeletonGroup.Item component
+ */
+export interface SkeletonGroupItemProps extends SkeletonProps {}

package/lib/__templates__/expo/client/heroui/components/slider/index.ts

@@ -0,0 +1,23 @@
+// Component export
+export { default as Slider, useSlider } from './slider';
+
+// ClassNames export for external reuse
+export { sliderClassNames } from './slider.styles';
+
+// Re-export primitive context and value types for consumer convenience
+export type {
+  SliderContextValue,
+  SliderOrientation,
+  SliderRenderProps,
+  SliderState,
+  SliderValue,
+} from '../../primitives/slider/slider.types';
+
+// Component-level type exports
+export type {
+  SliderFillProps,
+  SliderOutputProps,
+  SliderProps,
+  SliderThumbProps,
+  SliderTrackProps,
+} from './slider.types';

package/lib/__templates__/expo/client/heroui/components/slider/slider.animation.ts

@@ -0,0 +1,87 @@
+import { useAnimatedStyle, withSpring } from 'react-native-reanimated';
+import { useAnimationSettings } from '../../helpers/internal/contexts';
+import { useCombinedAnimationDisabledState } from '../../helpers/internal/hooks';
+import type { AnimationRootDisableAll } from '../../helpers/internal/types';
+import {
+  getAnimationState,
+  getAnimationValueMergedConfig,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+} from '../../helpers/internal/utils';
+import { THUMB_SPRING_CONFIG } from './slider.constants';
+import type { SliderThumbAnimation } from './slider.types';
+
+/**
+ * Animation hook for Slider root component.
+ * Handles root-level animation configuration and provides
+ * cascading disable-all state for child components.
+ */
+export function useSliderRootAnimation(options: {
+  animation: AnimationRootDisableAll | undefined;
+}) {
+  const { animation } = options;
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  return {
+    isAllAnimationsDisabled,
+  };
+}
+
+// --------------------------------------------------
+
+/**
+ * Animation hook for Slider.Thumb knob scale effect.
+ * Animates scale between idle and dragging states using spring physics,
+ * driven by the `isThumbDragging` state from the slider context.
+ */
+export function useSliderThumbAnimation(options: {
+  animation: SliderThumbAnimation | undefined;
+  isDragging: boolean;
+}) {
+  const { animation, isDragging } = options;
+
+  const { isAllAnimationsDisabled } = useAnimationSettings();
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const scaleValue = getAnimationValueProperty({
+    animationValue: animationConfig?.scale,
+    property: 'value',
+    defaultValue: [1, 0.9] as [number, number],
+  });
+
+  const scaleSpringConfig = getAnimationValueMergedConfig({
+    animationValue: animationConfig?.scale,
+    property: 'springConfig',
+    defaultValue: THUMB_SPRING_CONFIG,
+  });
+
+  const rKnobStyle = useAnimatedStyle(() => {
+    if (isAnimationDisabledValue) {
+      return {
+        transform: [{ scale: isDragging ? scaleValue[1] : scaleValue[0] }],
+      };
+    }
+
+    return {
+      transform: [
+        {
+          scale: withSpring(
+            isDragging ? scaleValue[1] : scaleValue[0],
+            scaleSpringConfig
+          ),
+        },
+      ],
+    };
+  });
+
+  return {
+    rKnobStyle,
+  };
+}

package/lib/__templates__/expo/client/heroui/components/slider/slider.constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Display names for Slider components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUI.Slider.Root',
+  OUTPUT: 'HeroUI.Slider.Output',
+  TRACK: 'HeroUI.Slider.Track',
+  FILL: 'HeroUI.Slider.Fill',
+  THUMB: 'HeroUI.Slider.Thumb',
+};
+
+/**
+ * Extra hit-slop around the thumb to improve touch target
+ */
+export const THUMB_HIT_SLOP = 16;
+
+/**
+ * Spring animation configuration for thumb scale feedback
+ */
+export const THUMB_SPRING_CONFIG = {
+  damping: 15,
+  stiffness: 200,
+  mass: 0.5,
+};

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

@@ -0,0 +1,348 @@
+# Slider
+
+A draggable input for selecting a value or range within a bounded interval.
+
+## Import
+
+```tsx
+import { Slider } from '@/heroui';
+```
+
+## Anatomy
+
+```tsx
+<Slider>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+- **Slider**: Main container that manages slider value state, orientation, and provides context to all sub-components. Supports single value and range modes.
+- **Slider.Output**: Optional display of the current value(s). Supports render functions for custom formatting. Shows a formatted value label by default.
+- **Slider.Track**: Sizing container for Fill and Thumb elements. Reports its layout size for position calculations. Supports tap-to-position and render-function children for dynamic content (e.g. multiple thumbs for range sliders).
+- **Slider.Fill**: Responsive fill bar that stretches the full cross-axis of the Track. Only the main-axis position and size are computed.
+- **Slider.Thumb**: Draggable thumb element using react-native-gesture-handler. Centered on the cross-axis by the Track layout. Animates scale on press via react-native-reanimated. Each thumb gets `role="slider"` with full `accessibilityValue`.
+
+## Usage
+
+### Basic Usage
+
+The Slider component uses compound parts to create a draggable value input.
+
+```tsx
+<Slider defaultValue={30}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### With Label and Output
+
+Display a label alongside the current value output.
+
+```tsx
+<Slider defaultValue={50}>
+  <View className="flex-row items-center justify-between">
+    <Label>Volume</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+### Vertical Orientation
+
+Render the slider vertically by setting `orientation` to `"vertical"`.
+
+```tsx
+<View className="h-48">
+  <Slider defaultValue={50} orientation="vertical">
+    <Slider.Track>
+      <Slider.Fill />
+      <Slider.Thumb />
+    </Slider.Track>
+  </Slider>
+</View>
+```
+
+### Range Slider
+
+Pass an array as the value and use a render function on `Slider.Track` to create multiple thumbs.
+
+```tsx
+<Slider
+  defaultValue={[200, 800]}
+  minValue={0}
+  maxValue={1000}
+  step={10}
+  formatOptions={{ style: 'currency', currency: 'USD' }}
+>
+  <View className="flex-row items-center justify-between">
+    <Label>Price range</Label>
+    <Slider.Output />
+  </View>
+  <Slider.Track>
+    {({ state }) => (
+      <>
+        <Slider.Fill />
+        {state.values.map((_, i) => (
+          <Slider.Thumb key={i} index={i} />
+        ))}
+      </>
+    )}
+  </Slider.Track>
+</Slider>
+```
+
+### Controlled Value
+
+Use `value` and `onChange` for controlled mode. The `onChangeEnd` callback fires when a drag or tap interaction completes.
+
+```tsx
+const [volume, setVolume] = useState(50);
+
+<Slider value={volume} onChange={setVolume} onChangeEnd={(v) => save(v)}>
+  <Slider.Output />
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>;
+```
+
+### Custom Styling
+
+Apply custom styles using `className`, `classNames`, or `styles` on the thumb and other sub-components.
+
+```tsx
+<Slider defaultValue={65}>
+  <Slider.Track className="h-3 rounded-full bg-success/10">
+    <Slider.Fill className="rounded-full bg-success" />
+    <Slider.Thumb
+      classNames={{
+        thumbContainer: 'size-6 rounded-full bg-success',
+        thumbKnob: 'bg-success-foreground rounded-full',
+      }}
+      animation={{
+        scale: { value: [1, 0.7] },
+      }}
+    />
+  </Slider.Track>
+</Slider>
+```
+
+### Disabled
+
+Disable the entire slider to prevent interaction.
+
+```tsx
+<Slider defaultValue={40} isDisabled>
+  <Slider.Track>
+    <Slider.Fill />
+    <Slider.Thumb />
+  </Slider.Track>
+</Slider>
+```
+
+## Example
+
+```tsx
+import { Label, Slider } from '@/heroui';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+
+export default function SliderExample() {
+  const [price, setPrice] = useState<number[]>([200, 800]);
+
+  return (
+    <View className="px-8 gap-8">
+      <Slider defaultValue={30}>
+        <View className="flex-row items-center justify-between">
+          <Label>Volume</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          <Slider.Fill />
+          <Slider.Thumb />
+        </Slider.Track>
+      </Slider>
+
+      <Slider
+        value={price}
+        onChange={setPrice}
+        minValue={0}
+        maxValue={1000}
+        step={10}
+        formatOptions={{ style: 'currency', currency: 'USD' }}
+      >
+        <View className="flex-row items-center justify-between">
+          <Label>Price range</Label>
+          <Slider.Output />
+        </View>
+        <Slider.Track>
+          {({ state }) => (
+            <>
+              <Slider.Fill />
+              {state.values.map((_, i) => (
+                <Slider.Thumb key={i} index={i} />
+              ))}
+            </>
+          )}
+        </Slider.Track>
+      </Slider>
+    </View>
+  );
+}
+```
+
+You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/slider.tsx>).
+
+## API Reference
+
+### Slider
+
+| prop            | type                                  | default        | description                                                     |
+| --------------- | ------------------------------------- | -------------- | --------------------------------------------------------------- |
+| `children`      | `React.ReactNode`                     | -              | Children elements to be rendered inside the slider              |
+| `value`         | `number \| number[]`                  | -              | Current slider value (controlled mode)                          |
+| `defaultValue`  | `number \| number[]`                  | `0`            | Default slider value (uncontrolled mode)                        |
+| `minValue`      | `number`                              | `0`            | Minimum value of the slider                                     |
+| `maxValue`      | `number`                              | `100`          | Maximum value of the slider                                     |
+| `step`          | `number`                              | `1`            | Step increment for the slider                                   |
+| `formatOptions` | `Intl.NumberFormatOptions`            | -              | Number format options for value label formatting                |
+| `orientation`   | `'horizontal' \| 'vertical'`          | `'horizontal'` | Orientation of the slider                                       |
+| `isDisabled`    | `boolean`                             | `false`        | Whether the slider is disabled                                  |
+| `className`     | `string`                              | -              | Additional CSS classes                                          |
+| `animation`     | `AnimationRootDisableAll`             | -              | Animation configuration for the slider                          |
+| `onChange`      | `(value: number \| number[]) => void` | -              | Callback fired when the slider value changes during interaction |
+| `onChangeEnd`   | `(value: number \| number[]) => void` | -              | Callback fired when an interaction completes (drag end or tap)  |
+| `...ViewProps`  | `ViewProps`                           | -              | All standard React Native View props are supported              |
+
+#### AnimationRootDisableAll
+
+Animation configuration for the slider root component. Can be:
+
+- `"disable-all"`: Disable all animations including children
+- `undefined`: Use default animations
+
+### Slider.Output
+
+| prop           | type                                                                 | default | description                                                                                 |
+| -------------- | -------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | Custom content or render function receiving slider state. Defaults to formatted value label |
+| `className`    | `string`                                                             | -       | Additional CSS classes                                                                      |
+| `...ViewProps` | `ViewProps`                                                          | -       | All standard React Native View props are supported                                          |
+
+#### SliderRenderProps
+
+| prop          | type                | description                    |
+| ------------- | ------------------- | ------------------------------ |
+| `state`       | `SliderState`       | Current slider state           |
+| `orientation` | `SliderOrientation` | Orientation of the slider      |
+| `isDisabled`  | `boolean`           | Whether the slider is disabled |
+
+#### SliderState
+
+| prop                 | type                        | description                                    |
+| -------------------- | --------------------------- | ---------------------------------------------- |
+| `values`             | `number[]`                  | Current slider value(s) by thumb index         |
+| `getThumbValueLabel` | `(index: number) => string` | Returns the formatted string label for a thumb |
+
+### Slider.Track
+
+| prop           | type                                                                 | default | description                                                                   |
+| -------------- | -------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode \| ((props: SliderRenderProps) => React.ReactNode)` | -       | Content or render function receiving slider state for dynamic thumb rendering |
+| `className`    | `string`                                                             | -       | Additional CSS classes                                                        |
+| `hitSlop`      | `number`                                                             | `8`     | Extra touch area around the track                                             |
+| `...ViewProps` | `ViewProps`                                                          | -       | All standard React Native View props are supported                            |
+
+### Slider.Fill
+
+| prop           | type        | default | description                                        |
+| -------------- | ----------- | ------- | -------------------------------------------------- |
+| `className`    | `string`    | -       | Additional CSS classes                             |
+| `...ViewProps` | `ViewProps` | -       | All standard React Native View props are supported |
+
+### Slider.Thumb
+
+| prop           | type                                     | default | description                                        |
+| -------------- | ---------------------------------------- | ------- | -------------------------------------------------- |
+| `children`     | `React.ReactNode`                        | -       | Custom thumb content. Defaults to an animated knob |
+| `index`        | `number`                                 | `0`     | Index of this thumb within the slider              |
+| `isDisabled`   | `boolean`                                | -       | Whether this individual thumb is disabled          |
+| `className`    | `string`                                 | -       | Additional CSS classes for the thumb container     |
+| `classNames`   | `ElementSlots<ThumbSlots>`               | -       | Additional CSS classes for thumb slots             |
+| `styles`       | `Partial<Record<ThumbSlots, ViewStyle>>` | -       | Inline styles for thumb slots                      |
+| `hitSlop`      | `number`                                 | `12`    | Extra touch area around the thumb                  |
+| `animation`    | `SliderThumbAnimation`                   | -       | Animation configuration for the thumb knob         |
+| `...ViewProps` | `ViewProps`                              | -       | All standard React Native View props are supported |
+
+#### ElementSlots\<ThumbSlots\>
+
+| prop             | type     | description                                     |
+| ---------------- | -------- | ----------------------------------------------- |
+| `thumbContainer` | `string` | Custom class name for the outer thumb container |
+| `thumbKnob`      | `string` | Custom class name for the inner thumb knob      |
+
+#### styles
+
+| prop             | type        | description                          |
+| ---------------- | ----------- | ------------------------------------ |
+| `thumbContainer` | `ViewStyle` | Styles for the outer thumb container |
+| `thumbKnob`      | `ViewStyle` | Styles for the inner thumb knob      |
+
+#### SliderThumbAnimation
+
+Animation configuration for the thumb knob scale effect. Can be:
+
+- `false` or `"disabled"`: Disable thumb animation
+- `undefined`: Use default animations
+- `object`: Custom scale animation configuration
+
+| prop                 | type               | default                                      | description                                     |
+| -------------------- | ------------------ | -------------------------------------------- | ----------------------------------------------- |
+| `scale.value`        | `[number, number]` | `[1, 0.9]`                                   | Scale values [idle, dragging]                   |
+| `scale.springConfig` | `WithSpringConfig` | `{ damping: 15, stiffness: 200, mass: 0.5 }` | Spring animation configuration for scale effect |
+
+## Hooks
+
+### useSlider
+
+Hook to access the slider context. Must be used within a `Slider` component.
+
+```tsx
+import { useSlider } from '@/heroui';
+
+const { values, orientation, isDisabled, getThumbValueLabel } = useSlider();
+```
+
+#### Returns
+
+| property             | type                                         | description                                                    |
+| -------------------- | -------------------------------------------- | -------------------------------------------------------------- |
+| `values`             | `number[]`                                   | Current slider values (one per thumb)                          |
+| `minValue`           | `number`                                     | Minimum value of the slider                                    |
+| `maxValue`           | `number`                                     | Maximum value of the slider                                    |
+| `step`               | `number`                                     | Step increment                                                 |
+| `orientation`        | `'horizontal' \| 'vertical'`                 | Current orientation                                            |
+| `isDisabled`         | `boolean`                                    | Whether the slider is disabled                                 |
+| `formatOptions`      | `Intl.NumberFormatOptions \| undefined`      | Number format options for labels                               |
+| `getThumbPercent`    | `(index: number) => number`                  | Returns the percentage position (0–1) for a given thumb index  |
+| `getThumbValueLabel` | `(index: number) => string`                  | Returns the formatted label for a given thumb index            |
+| `getThumbMinValue`   | `(index: number) => number`                  | Returns the minimum allowed value for a thumb                  |
+| `getThumbMaxValue`   | `(index: number) => number`                  | Returns the maximum allowed value for a thumb                  |
+| `updateValue`        | `(index: number, newValue: number) => void`  | Updates a thumb value by index                                 |
+| `isThumbDragging`    | `(index: number) => boolean`                 | Returns whether a given thumb is currently being dragged       |
+| `setThumbDragging`   | `(index: number, dragging: boolean) => void` | Sets the dragging state of a thumb                             |
+| `trackSize`          | `number`                                     | Track layout width (horizontal) or height (vertical) in pixels |
+| `thumbSize`          | `number`                                     | Measured thumb size (main-axis dimension) in pixels            |

package/lib/__templates__/expo/client/heroui/components/slider/slider.styles.ts

@@ -0,0 +1,85 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { combineStyles } from '../../helpers/internal/utils';
+
+const root = tv({
+  base: 'gap-2',
+  variants: {
+    orientation: {
+      horizontal: 'w-full',
+      vertical: 'h-full items-center',
+    },
+    isDisabled: {
+      true: 'opacity-disabled',
+    },
+  },
+  defaultVariants: {
+    orientation: 'horizontal',
+    isDisabled: false,
+  },
+});
+
+const output = tv({
+  base: 'text-sm text-muted font-medium',
+});
+
+const track = tv({
+  base: 'rounded-xl bg-default',
+  variants: {
+    orientation: {
+      horizontal: 'w-full h-5 justify-center',
+      vertical: 'h-full w-5 items-center',
+    },
+  },
+  defaultVariants: {
+    orientation: 'horizontal',
+  },
+});
+
+const fill = tv({
+  base: 'absolute rounded-xl bg-accent',
+  variants: {
+    orientation: {
+      horizontal: 'inset-y-0',
+      vertical: 'inset-x-0',
+    },
+  },
+  defaultVariants: {
+    orientation: 'horizontal',
+  },
+});
+
+const thumb = tv({
+  slots: {
+    thumbContainer: 'absolute p-[2px] bg-accent rounded-xl',
+    thumbKnob: 'flex-1 bg-accent-foreground rounded-xl shadow-field',
+  },
+  variants: {
+    orientation: {
+      horizontal: { thumbContainer: 'w-7 h-5' },
+      vertical: { thumbContainer: 'w-5 h-7' },
+    },
+  },
+  defaultVariants: {
+    orientation: 'horizontal',
+  },
+});
+
+const sliderClassNames = combineStyles({
+  root,
+  output,
+  track,
+  fill,
+  thumb,
+});
+
+export const styleSheet = StyleSheet.create({
+  borderCurve: {
+    borderCurve: 'continuous',
+  },
+});
+
+export type ThumbSlots = keyof ReturnType<typeof thumb>;
+
+export { sliderClassNames };
+export default sliderClassNames;