{"slug":"progress-indicator","name":"ProgressIndicator","packageName":"@liquidify/react","category":"controls","maturity":"experimental","summary":"A read-only status indicator that conveys either ongoing progress of unknown duration (indeterminate, circular spinner) or a known fraction of completion (determinate, linear bar).","importPath":"@liquidify/react/progress-indicator","sourcePath":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx","specPath":"packages/@liquidify/react/src/components/progress-indicator/spec.md","docsPath":"../liquidify-page/content/component-source/progress-indicator.md","documentationStatus":"draft","storyIds":["controls-progress-indicator--default"],"additionalExports":["LiquidColor","LiquidTintValue","ProgressIndicatorSize","Size"],"anatomy":[],"props":[{"name":"children","type":"ReactNode","required":false,"description":"Optional visible label rendered as a sibling `<span>` to the spinner or bar, styled with the secondary-label token. The SwiftUI `ProgressView(\"Loading\")` / `{ Text(\"…\") }` analogue — the indicator's text content.","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"},{"name":"className","type":"string | undefined","required":false,"description":"Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"labelProps","type":"LabelProps | undefined","required":false,"description":"Per-instance typography override for the visible label, forwarded to the internal {@link Text} (ADR-0028). Token-backed axes only; the HIG default is `variant=\"body\"` with `color=\"secondary\"` (circular) / `\"primary\"` (linear). Applies only when {@link ProgressIndicatorProps.children} is a string/number.","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"},{"name":"ref","type":"Ref<HTMLDivElement> | undefined","required":false,"description":"Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"size","type":"ProgressIndicatorSize | undefined","required":false,"description":"Size of the circular spinner, drawn from the subset `\"small\" | \"regular\" | \"large\"`. The linear bar has a fixed geometry (Apple ships a single bar height) — the `size` prop applies **only to the circular variant**.","defaultValue":"`\"regular\"`","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"},{"name":"tint","type":"LiquidTintValue | undefined","required":false,"description":"System-accent of the determinate fill and the spinner arc — drawn from the restricted {@link LIQUID_COLORS } palette and applied via the `data-tint` attribute selector in CSS (ADR-0024). Per Apple HIG the linear bar fill is system blue by default.","defaultValue":"`\"blue\"`","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"},{"name":"value","type":"number | undefined","required":false,"description":"Fractional progress value in `[0, 1]`. Applies **only when the resolved `variant` is `\"linear\"`** — on `variant=\"circular\"` the value is ignored for ARIA/state purposes and the spinner stays indeterminate. When omitted (`undefined`) the linear indicator is **indeterminate** — the bar shimmers with no fill fraction. When set on a linear indicator, it is **determinate** — the fill encodes the fraction. Out-of-range values are clamped silently. This is a **one-way display prop**: `ProgressIndicator` reads it but never calls back with a new value.","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"},{"name":"variant","type":"\"circular\" | \"linear\" | undefined","required":false,"description":"Display variant — `\"circular\"` renders the spoked spinner; `\"linear\"` renders the horizontal pill track + fill. When omitted, the variant resolves by `value` presence: `undefined` → `\"circular\"`, number → `\"linear\"` (the SwiftUI `.progressViewStyle(.automatic)` analogue). An explicit `variant` overrides which shape renders, but **does not** grant a circular indicator determinacy: `variant=\"circular\"` is always indeterminate, regardless of `value` (audit §7 P2 — a determinate ARIA state over a perpetually-spinning visual disagreed with the eyes). Determinacy is scoped to `variant=\"linear\"` only.","declaredIn":"packages/@liquidify/react/src/components/progress-indicator/progress-indicator.tsx"}],"swiftUIMap":[{"swiftUI":"`ProgressView()` (no value)","react":"`value` omitted / `undefined`","notes":"Indeterminate — mirrors the no-arg overload; renders the circular spinner by default.","relationship":"direct"},{"swiftUI":"`ProgressView(value: Double)`","react":"`value?: number` in `[0, 1]`","notes":"Determinate fractional; `undefined` ⇒ indeterminate. SwiftUI default `total = 1.0`; React fixes range to `0…1`.","relationship":"direct"},{"swiftUI":"`ProgressView(value:total:)`","react":"`value` only — `total`/`max` not exposed","notes":"SwiftUI allows a custom `total`; React fixes to `0…1` fractional. Deferred.","relationship":"direct"},{"swiftUI":"`.progressViewStyle(.circular)`","react":"`variant=\"circular\"`","notes":"The spoked spinner.","relationship":"direct"},{"swiftUI":"`.progressViewStyle(.linear)`","react":"`variant=\"linear\"`","notes":"The horizontal bar.","relationship":"direct"},{"swiftUI":"`.progressViewStyle(.automatic)`","react":"default `variant` resolution","notes":"SwiftUI picks by context; React picks by `value` presence — circular for undefined, linear for a number.","relationship":"direct"},{"swiftUI":"`ProgressView(\"Loading\")` / `{ Text(\"…\") }`","react":"`children?: ReactNode`","notes":"Title or current-value text slot; circular inline + linear trailing collapse to one `children` slot. A string/number renders through the `Text` primitive (`variant=\"body\"`, `color=\"secondary\"` circular / `\"primary\"` linear); a label *element* passes through unwrapped (ADR-0028).","relationship":"renamed"},{"swiftUI":"`.font(_:)` / `.foregroundStyle(_:)` on the label","react":"`labelProps` (`Pick<TextProps, …>`)","notes":"Per-instance typography override forwarded to the internal `Text` (token-backed axes only; ADR-0028). Spread last, so an explicit value wins over the computed default. Applies only to string/number `children`.","relationship":"direct"},{"swiftUI":"`.controlSize(.small/.regular/.large)`","react":"`size?: Extract<Size, \"small\" | \"regular\" | \"large\">`","notes":"Applies to the circular spinner only; demo uses only these three sizes (ADR-0023, ADR-0018).","relationship":"direct"},{"swiftUI":"`.tint(_:)`","react":"`tint?: LiquidColor`","notes":"13 system colours (ADR-0024); colours the determinate fill and the spinner arc.","relationship":"direct"},{"swiftUI":"(no `.disabled`)","react":"—","notes":"Not demonstrated; progress is a status display, not an input.","relationship":"direct"}],"tokens":["--lq-color-accent","--lq-color-label-primary","--lq-color-label-secondary","--lq-color-separator","--lq-color-system-","--lq-color-system-blue-default-dark","--lq-color-system-blue-default-light","--lq-duration-standard","--lq-easing-standard","--lq-glass-","--lq-hit-target-touch","--lq-progress-bar-h","--lq-progress-pad","--lq-progress-spinner-d-small","--lq-progress-spinner-period","--lq-radius-pill","--lq-space-"],"keyboard":[],"variants":["circular","linear"],"variantPages":[]}