nt: Alignment.Center }) { Progress({ value: this.currentProgress, total: this.maxValue, type: ProgressType.ScaleRing }) .width('100%') .height('100%') .backgroundColor('#1A1A1A') .style({ scaleCount: 24, scaleWidth: 4, color: '#007AFF' })

  Divider()
    .width(0)
    .height('45%')
    .borderWidth(2)
    .borderColor('#FFFFFF')
    .borderRadius(2)
    .rotate({
      centerX: '50%',
      centerY: '100%',
      angle: this.handRotation
    })
    .hitTestBehavior(HitTestMode.None)
}
.width(120)
.height(120)

} }

### Technical Rationale

- **`Stack` Alignment**: `Alignment.Center` guarantees both children occupy identical bounds. This eliminates manual margin calculations and ensures the rotation pivot remains mathematically stable across device densities.
- **`Divider` as Hand**: Using a zero-width divider with a border renders a vector-native line. This avoids asset loading, scales cleanly across DPI buckets, and consumes negligible memory compared to `Image` or `Text` overlays.
- **Pivot Configuration**: `centerX: '50%'` and `centerY: '100%'` anchors the rotation to the bottom-center of the divider. This matches the physical behavior of a clock hand mounted at the center of the dial.
- **Animation Controller Reference**: Storing the `animateTo` return value enables explicit cancellation. ArkUI's scheduler does not automatically garbage-collect infinite loops when components unmount.
- **`@Watch` Synchronization**: External progress updates trigger `syncRotation()` immediately, preventing visual lag between the ring fill and hand position.

## Pitfall Guide

### 1. Misaligned Rotation Pivot
**Explanation**: Using `centerX: '0%'` or `centerY: '0%'` rotates the hand around its top-left corner, causing a visible wobble and breaking the clock illusion.
**Fix**: Always anchor to `centerX: '50%'` and `centerY: '100%'` for bottom-center mounting. Verify pivot placement using DevEco Studio's layout inspector.

### 2. Animation Memory Leaks
**Explanation**: `animateTo` with `iterations: -1` runs indefinitely. If the component unmounts without cancellation, the scheduler continues consuming CPU cycles in the background.
**Fix**: Store the animation controller reference and call `.stop()` in `aboutToDisappear()`. Never rely on implicit garbage collection for infinite loops.

### 3. Progress-to-Angle Ratio Drift
**Explanation**: Hardcoding `this.handRotation = 360` without calculating the ratio causes the hand to overshoot or undershoot when `maxValue` changes dynamically.
**Fix**: Compute `ratio = current / total` and multiply by 360. Apply this calculation in both initial sync and animation callbacks.

### 4. Main Thread Blocking During State Updates
**Explanation**: Performing heavy computations inside the `animateTo` callback or `@Watch` handler stalls the UI thread, causing frame drops and janky rotation.
**Fix**: Keep animation callbacks minimal. Pre-calculate ratios, use primitive types, and avoid synchronous I/O or complex object instantiation during render cycles.

### 5. Touch Event Interception
**Explanation**: The `Divider` overlay captures tap and swipe events by default, blocking interaction with underlying controls or progress ring gestures.
**Fix**: Apply `.hitTestBehavior(HitTestMode.None)` to the hand component. This ensures touch events pass through to the stack's background layer.

### 6. API Version Incompatibility
**Explanation**: `ProgressType.ScaleRing` and `animateTo` require API 19+. Deploying to older HarmonyOS versions causes silent rendering failures or runtime exceptions.
**Fix**: Implement version guards using `@ohos.app.ability.UIAbilityContext` or provide a fallback linear progress indicator for pre-API 19 environments.

### 7. Ignoring Safe Area and Notch Cuts
**Explanation**: Fixed dimensions (`width(120)`) may clip on devices with aggressive screen cutouts or dynamic island layouts.
**Fix**: Use responsive sizing (`width('80%')`) or wrap the component in a `SafeArea` container. Test across foldable and tablet form factors before production release.

## Production Bundle

### Action Checklist
- [ ] Verify API 19+ compatibility before deploying to production builds
- [ ] Implement explicit animation cancellation in `aboutToDisappear()`
- [ ] Calculate rotation angle using `(progress / total) * 360` ratio
- [ ] Anchor rotation pivot to `centerX: '50%'` and `centerY: '100%'`
- [ ] Apply `HitTestMode.None` to overlay components to prevent touch interception
- [ ] Profile animation performance using DevEco Studio's CPU/Memory monitor
- [ ] Add accessibility labels for screen readers (`accessibilityLabel('Progress indicator')`)
- [ ] Test responsive scaling across multiple DPI buckets and foldable states

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Simple timer/loader UI | Composite Progress + Divider | Zero external dependencies, native scheduler optimization | Low (native API only) |
| Complex data visualization with multiple hands | Canvas/SVG Custom Drawing | Requires independent transform matrices per element | Medium (custom render logic) |
| Rapid prototyping with design system compliance | Third-Party UI Library | Pre-built accessibility, theming, and responsive variants | Medium-High (bundle size + licensing) |
| Legacy HarmonyOS < API 19 | Fallback Linear Progress | `ScaleRing` and `animateTo` unavailable | Low (degraded UX) |

### Configuration Template

```typescript
// DialProgressIndicator.ets
import { animation } from '@kit.ArkUI'

@Component
export struct DialProgressIndicator {
  @Prop progress: number = 0
  @Prop total: number = 100
  @Prop ringColor: string = '#007AFF'
  @Prop handColor: string = '#FFFFFF'
  @Prop size: number = 120

  @State private rotationAngle: number = 0
  private sweepController: animation.AnimationController | null = null

  aboutToAppear(): void {
    this.updateAngle()
    this.beginSweep()
  }

  aboutToDisappear(): void {
    this.terminateSweep()
  }

  @Watch('progress')
  onProgressUpdate(): void {
    this.updateAngle()
  }

  private updateAngle(): void {
    const normalized = Math.min(Math.max(this.progress, 0), this.total)
    this.rotationAngle = (normalized / this.total) * 360
  }

  private beginSweep(): void {
    this.sweepController = animation.animateTo({
      duration: 3500,
      curve: animation.Curve.Linear,
      iterations: -1
    }, () => {
      this.rotationAngle = 360
    })
  }

  private terminateSweep(): void {
    this.sweepController?.stop()
    this.sweepController = null
  }

  build() {
    Stack({ alignContent: Alignment.Center }) {
      Progress({
        value: this.progress,
        total: this.total,
        type: ProgressType.ScaleRing
      })
        .width(this.size)
        .height(this.size)
        .backgroundColor('#111111')
        .style({
          scaleCount: 20,
          scaleWidth: 3,
          color: this.ringColor
        })

      Divider()
        .width(0)
        .height(`${this.size * 0.45}px`)
        .borderWidth(2)
        .borderColor(this.handColor)
        .borderRadius(2)
        .rotate({
          centerX: '50%',
          centerY: '100%',
          angle: this.rotationAngle
        })
        .hitTestBehavior(HitTestMode.None)
    }
    .width(this.size)
    .height(this.size)
  }
}

Quick Start Guide

1. Create the Component: Copy the configuration template into DialProgressIndicator.ets within your entry/src/main/ets/components directory.
2. Import and Instantiate: Add import { DialProgressIndicator } from '../components/DialProgressIndicator' to your target page. Render with <DialProgressIndicator progress={45} total={100} size={140} />.
3. Bind Dynamic Progress: Connect the progress prop to your application state using @State or @Link. The component automatically recalculates rotation and ring fill.
4. Verify Animation Lifecycle: Run the app on a physical device or emulator. Open DevEco Studio's Profiler tab and confirm CPU usage remains below 2% during idle animation. Validate that rotation stops cleanly when navigating away from the page.
5. Deploy: Ensure your module.json5 specifies apiVersion: 19 or higher. Build and distribute. No external dependencies or native modules required.