ouds-ios-components-indicators

Files (1)

• SKILL.md

SKILL.md (first lines)

# OUDS Indicators components

> Prerequisite: load `ouds-ios-framework-usage` first for imports, themes and image rules.

## Badge

Statuses: `neutral`, `accent`, `positive`, `info`, `warning`, `negative` — Sizes: `extraSmall`, `small`, `medium`, `large`
Count parameter must be of type `UInt8`.

```swift
OUDSBadgeStandard(accessibilityLabel: "Some label", status: .neutral, size: .medium)
OUDSBadgeCount(3, accessibilityLabel: "Some label", status: .neutral, size: .medium)
OUDSBadgeIcon(status: .neutral(image: OUDSImage(asset: Image("ic"))), accessibilityLabel: "Label", size: .medium)
```

---

## Tag

```swift
OUDSTag(label: "Label")
OUDSTag(label: "Label", status: .neutral(image: OUDSImage(asset: Image("ic"))))
OUDSTag(label: "Label", status: .neutral(image: OUDSImage(asset: Image("ic"), renderingMode: .original))) // raw image (not tinted)
OUDSTag(label: "Label", status: .neutral(image: OUDSImage(asset: Image("ic"), flipped: true))) // flipped for RTL
OUDSTag(label: "Label", status: .accent(image: OUDSImage(asset: Image("ic"))))
OUDSTag(label: "Label", status: .accent(image: OUDSImage(asset: Image("ic"), renderingMode: .original))) // raw image (not tinted)
OUDSTag(label: "Label", status: .neutral(bullet: true))
// Loading tag (progress is optional, indeterminate by default)
OUDSTag(loadingLabel: "Loading", progress: 0.5)
```

---

## Input Tag

```swift
OUDSInputTag(label: "Label") { /* remove action */ }
```

---

## Categorical Tag

Categories: `category1` to `category5` — each maps to a theme-defined background color (for example, emerald, sky, amber, amethyst, and pink in Orange themes). Supported themes are Orange, Orange Compact, and Wireframe; Sosh is not supported.

```swift
OUDSCategoricalTag(label: "Label")
OUDSCategoricalTag(label: "Label", category: .category2)
OUDSCategoricalTag(label: "Label", category: .category3, leading: .bullet)
OUDSCategoricalTag(label: "Label", category: .category4, leading: .icon(OUDSImage(asset: Image(decorative: "ic_heart"))))
OUDSCategoricalTag(label: "Label", category: .category5, shape: .square, size: .small)
```

Notes:
- Always emphasized (no muted appearance unlike OUDSTag)
- Uses `theme.categoricalTag.colorBgCategoryX` for background and `theme.categoricalTag.colorContent` for text/icon color
- Supports bullet and custom icon (same as OUDSTag)
- Shape: `.rounded` (default) or `.square`
- Size: `.default` (default) or `.small`

---

## Circular Progress Indicator

Statuses: `neutral`, `accent`, `positive`, `info`, `warning`, `negative` — Gap sizes: `default`, `small`

```swift
// Determinate — progress is clamped to [0, 1]
// By default the arc animates from 0 to `progress` on first display and on every change,
// using a Material 3 critically-damped spring (~1.5s).
OUDSCircularProgressIndicator(progress: 0.75)
OUDSCircularProgressIndicator(progress: 0.5, status: .accent, track: false)
OUDSCircularProgressIndicator(progress: 0.3, status: .warning, gapSize: .small)

// Determinate without the reveal animation: the arc is shown instantly at its target value.
OUDSCircularProgressIndicator(progress: 0.75, animated: false)

// Indeterminate — Material 3 spinner (global rotation + additional 90° kicks + sweep respiration)
OUDSCircularProgressIndicator()
OUDSCircularProgressIndicator(status: .info, track: true)

// Custom size — stroke width and gap scale proportionally to the effective size
OUDSCircularProgressIndicator(progress: 0.6)
    .frame(width: 96, height: 96)
```

Notes:
- Default size is `48pt` and scales with Dynamic Type.
- Rounded stroke caps follow the theme tuning: `Tuning.hasRoundedProgressIndicators` picks between the default (butt) and the rounded cap, exactly like `hasRoundedButtons` does for buttons. The gap is auto-compensated so the visible spacing between the foreground arc and the track stays constant regardless of the cap.
- On `OUDSColoredSurface`, the indicator switches to a monochrome rendering: `status` is ignored and the surface content color is used.
- Determinate animations (reveal + updates) are disabled when `accessibilityReduceMotion` is on or when Low Power Mode is enabled — the arc is then shown instantly at its target value. The `animated: false` flag has the same effect on demand.
- Indeterminate rotation is paused in the same conditions (Reduce Motion / Low Power Mode) and falls back to a static arc.

---

## Linear Progress Indicator

Statuses: `neutral`, `accent`, `positive`, `info`, `warning`, `negative` — Gap sizes: `default` (4pt), `small` (1pt)

The determinate and indeterminate initializers have **different** signatures — this is not a mistake. `stopIndicator` and `animated` are **determinate-only** parameters. The Material 3 indeterminate variant does not expose a stop indicator (no meaningful end position) and is always animated (motion is only disabled by Reduce Motion / Low Power Mode).

```swift
// ── Determinate ──────────────────────────────────────────────────────────────

// Progress is clamped to [0, 1]. By default the bar animates from 0 to `progress` on first display
// and on every change, using the same Material 3 critically-damped spring as the circular indicator
// (~1.5s).
OUDSLinearProgressIndicator(progress: 0.75)
OUDSLinearProgressIndicator(progress: 0.5, status: .accent, track: false)
OUDSLinearProgressIndicator(progress: 0.3, status: .warning, gapSize: .small)

// With a stop indicator (small square at the end of the track).
// Required for accessibility when the track contrast is below 3:1 with its container.
OUDSLinearProgressIndicator(progress: 0.5, stopIndicator: true)

// With a centered helper text below the bar. 
// The helper text without progress information (percent) is displayed according to alignment.
// it is also exposed as the accessibility label (VoiceOver reads e.g. "Uploading. 75 percent") even if 
// percent is not displayed.

From Orange-OpenSource/ouds-ios, MIT.

More from Orange-OpenSource/ouds-ios