# LabeledContent

**Maturity:** experimental

Show a label/value pair on one line — "Version … 2.6.0", "Wi-Fi … Liquid-5G" — without inventing a bespoke flex-row per screen.

## Import

```tsx
import { LabeledContent } from "@liquidify/react/labeled-content"
```

## Props

- `align`: `LabeledContentAlign | undefined`; default ``"baseline"``. Cross-axis alignment of the label against the trailing slot. Leave `"baseline"` (the default) for a text "key: value" row; pass `"center"` to seat a control (Toggle/Slider/Picker) — taller than one text line — against its label, the settings-row posture absorbed from the removed `Form.Body.Row`.
- `children`: `ReactNode`. The trailing value, as rich/formatted content (SwiftUI `@ViewBuilder content:`) — a styled `Text`, a formatted date, or any other node. A bare `string | number` child is wrapped `color="secondary"` (overridable via {@link LabeledContentProps.valueProps}) via `TextLabel`, same as {@link LabeledContentProps.value}; any other `ReactNode` passes through unchanged and ignores `valueProps`. Mutually exclusive with `value` (see `value` for the both-supplied dev-warning contract). children role: `content` (charter §8) — the free-form value slot.
- `className`: `string | undefined`. 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.
- `label`: `ReactNode` (required). The leading descriptor (SwiftUI `titleKey:` / `label:`) — the accessible name source. A `string | number` renders through the `TextLabel` guard into an internal `Text` (default `color="primary"`, overridable via {@link LabeledContentProps.labelProps}); any other `ReactNode` (e.g. an icon+text composite) passes through unwrapped — `labelProps` is ignored — so the caller keeps ownership of its own typography and icon.
- `labelProps`: `LabelProps | undefined`. Per-instance typography override for the leading label — the web-only seam for SwiftUI's `.font(_:)` / `.foregroundStyle(_:)` on the label (ADR-0028). Spread **last** into the label `TextLabel`, so an explicit value here wins over the component's `color="primary"` default. Applies only when {@link LabeledContentProps.label} is a `string | number`; a composite `ReactNode` label ignores this prop entirely.
- `ref`: `Ref<HTMLDivElement> | undefined`. 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`.
- `value`: `string | undefined`. The trailing value, as a plain string (SwiftUI `init(_:value:)`). Routed through `TextLabel` (default `color="secondary"`, overridable via {@link LabeledContentProps.valueProps}). Mutually exclusive with {@link LabeledContentProps.children} — supply exactly one per instance; when both are supplied, `value` wins (the `value !== undefined` gate is retained, so a legitimate empty-string `value` still wins), and a dev build additionally fires a `console.error` (charter §8; audit §7 P2).
- `valueProps`: `LabelProps | undefined`. Per-instance typography override for the trailing value — the web-only seam for SwiftUI's `.font(_:)` / `.foregroundStyle(_:)` on the value content (ADR-0028). Spread **last** into the value `TextLabel`, so an explicit value here wins over the component's `color="secondary"` default. Applies only to a `string | number` {@link LabeledContentProps.value} or a bare `string | number` {@link LabeledContentProps.children}; a `ReactNode` child ignores this prop entirely.

## SwiftUI mapping

- ``init(_ titleKey: LocalizedStringKey/String, value: V)` (`V: Text`)` → `✅` (direct): `<LabeledContent label="Version" value="2.6.0" />` — string `label` + string `value`
- ``init(_ titleKey:, @ViewBuilder content:)`` → `✅` (direct): `<LabeledContent label="Storage">128 GB</LabeledContent>` — `children` = the value slot
- ``init(@ViewBuilder content:, @ViewBuilder label:)`` → `✅` (direct): `label` accepts an arbitrary `ReactNode` (icon+text composite) + `children` = the value slot
- ``init(_ titleKey:, value: V, format: FormatStyle)`` → `~ (via `Text(Date(), format:)` inside a `content:` closure)` (direct): Folds into the `children` path — React's value slot accepts any formatted/rich node, not only plain strings; no dedicated `format` prop.
- ``init(_ configuration: LabeledContentStyleConfiguration)`` → `✗` (direct): Style-plumbing internal; not a public React prop.
- ``.labeledContentStyle(_:)`` → `✗ (no custom style used in the demo)` (direct): Not surfaced; only the default/automatic layout ships in v1 (see Out of scope).
- ``Label(_:, systemImage:)` in the `label` slot` → `✅` (direct): `label` is a plain `ReactNode` — the caller composes its own icon+text node (e.g. `<><Icon name="wifi" />Bluetooth</>`); no dedicated `icon` prop in v1 (see Out of scope).
- ``.foregroundStyle(.secondary)` on value content` → `✅ (explicit on "Storage", matching the automatic default)` (direct): `value`/`children` default to `color="secondary"` via the internal `TextLabel` routing — overridable via `valueProps` below, never opted out entirely.
- ``.font(_:)` / `.foregroundStyle(_:)` on the label` → `~ (web-only seam, ADR-0028)` (direct): `labelProps?: LabelProps` — the shared `Pick<TextProps, …>` from `shared/text-label`, spread last into the label `TextLabel`. Applies only to a `string | number` label; a composite `ReactNode` label bypasses it.
- ``.font(_:)` / `.foregroundStyle(_:)` on value content` → `~ (web-only seam, ADR-0028)` (direct): `valueProps?: LabelProps` — same shared `Pick`, spread last into the value `TextLabel`. Applies only to a `string | number` `value` or bare `string | number` `children`; a `ReactNode` child bypasses it.
- ``.glassEffect(in: .rect(cornerRadius: 20))` on a row container` → `✅` (direct): Not a LabeledContent prop — glass belongs to the surrounding container, an external composition (see Out of scope).
- ``Divider()` between stacked rows` → `✅` (direct): Not a LabeledContent primitive — external composition (see Out of scope).