rn-native-ios-charts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to **rn-native-ios-charts** are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-11
+
+Initial public release. iOS-only Expo module that bridges every SwiftUI
+`Charts` mark type to React Native with a single composable `<Chart />`
+primitive plus convenience wrappers.
+
+### Added
+
+- **Generic `<Chart />`** — renders any combination of `bar`, `line`,
+  `area`, `point`, `rectangle`, `rule`, and `sector` marks in a single
+  view.
+- **Convenience wrappers** — `<PieChart />`, `<LineChart />`,
+  `<AreaChart />`, `<BarChart />`, `<ScatterChart />`, `<RangeBarChart />`.
+  All delegate to the generic primitive.
+- **Pie / donut `centerLabel`** — value + caption slot rendered inside
+  the chart's plot frame via SwiftUI's `chartBackground` +
+  `ChartProxy.plotFrame`. Tracks the donut centre natively, no JS
+  overlays.
+- **Native gradients** — `LinearGradient` on any mark's
+  `foregroundStyle` with two-stop shorthand (`startOpacity` /
+  `endOpacity`) or full multi-stop `stops`.
+- **Per-point overrides** — every datum can carry its own `color` and
+  `category` (series key for auto-coloring + legend grouping).
+- **Interactive tooltips** — opt-in `tooltip` prop drives SwiftUI's
+  native `chartXSelection` scrubber: vertical rule + highlighted dot +
+  auto-clamped callout. All rendered inside the SwiftUI view hierarchy,
+  no JS frame round-trips. Configurable colors, value prefix/suffix,
+  decimal places.
+- **`onSelect` event** — fires when the user picks a point via the
+  scrubber or taps a pie sector. Pie uses native `chartAngleSelection`.
+- **Line interpolation** — `linear`, `catmullRom`, `monotone`,
+  `stepStart`, `stepEnd`, `stepCenter`.
+- **Symbols** — `circle`, `square`, `triangle`, `diamond`, `pentagon`,
+  `plus`, `cross`, `asterisk`. With `symbolSize` and `showPoints`.
+- **Axis config** — hidden, grid lines, tick labels, label color & font
+  size, custom `[domainMin, domainMax]`.
+- **Legend config** — hidden, placement (`top`, `bottom`, `leading`,
+  `trailing`, `overlay`, `automatic`).
+- **`isChartSupported()`** — runtime feature-detection helper. Use it
+  to mount a fallback chart library on iOS < 17 and on Android / web.
+
+### Platform support
+
+- **iOS 17+** — full rendering (SwiftUI Charts unified API).
+- **iOS 15.1–16.x** — pod installs cleanly so the module can be a
+  dependency of any modern Expo app, but `<Chart />` renders an empty
+  view. The SwiftUI Charts unified API isn't available pre-17.
+- **Android / web** — components render a transparent placeholder
+  `View` so consuming code doesn't need to feature-detect. Pair with
+  `isChartSupported()` to swap in an alternative renderer.
+
+[Unreleased]: https://github.com/abdallaemadeldin/rn-native-ios-charts/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/abdallaemadeldin/rn-native-ios-charts/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdalla Emadeldin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# rn-native-ios-charts
+
+> Native SwiftUI Charts for React Native / Expo. **iOS-only.** No SVG, no
+> Skia, no canvas approximations — every line and slice is drawn by Apple's
+> own `Charts` framework.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/abdallaemadeldin/rn-native-ios-charts/HEAD/docs/demo.gif" alt="rn-native-ios-charts demo" width="360" />
+</p>
+
+> [▶ Watch HD version](https://github.com/abdallaemadeldin/rn-native-ios-charts/raw/HEAD/docs/demo.mp4) — every chart type, native gradients, interactive tooltips, and pie center-label snapping.
+
+Cross-platform RN chart libraries (Victory, Skia, gifted-charts, etc.) all
+hit the same iOS ceilings:
+
+- Pie / donut charts can't put a label inside the hole that actually
+  tracks the chart's plot frame.
+- Line and area charts can't use a real `LinearGradient` for the fill —
+  they either solid-fill or fake it with `<defs><linearGradient>`.
+- Tooltips, when they exist, are JS overlays that flicker and lag
+  behind the gesture — instead of SwiftUI's native `chartXSelection`
+  that snaps to data points with zero JS round-trips.
+- iOS 17+ Charts features (`chartBackground`, `chartXScale`, mixed
+  marks in a single Chart, native interpolation methods, etc.) aren't
+  exposed at all.
+
+This module is a thin Expo wrapper over SwiftUI `Charts` that exposes
+every mark type and every modifier we've needed in production. iOS-only
+by design — Android / web mount a no-op `<View />` so consuming code
+doesn't need to feature-detect.
+
+## Components
+
+### `<Chart />` — the generic, composable view
+
+Render any combination of marks in a single chart. This is what every
+convenience wrapper below delegates to.
+
+```tsx
+import { Chart } from "rn-native-ios-charts";
+
+<Chart
+  style={{ width: "100%", height: 240 }}
+  marks={[
+    {
+      type: "area",
+      data: yearTotals,
+      color: "#1FA92E",
+      gradient: { startOpacity: 0.35, endOpacity: 0.02 },
+      interpolation: "catmullRom",
+    },
+    {
+      type: "line",
+      data: yearTotals,
+      color: "#1FA92E",
+      lineWidth: 2.5,
+      interpolation: "catmullRom",
+      showPoints: true,
+      symbol: "circle",
+    },
+    {
+      type: "rule",
+      data: [],
+      ruleValue: 0,
+      color: "#9BA1A6",
+      dashArray: [4, 4],
+    },
+  ]}
+  xAxis={{ hidden: false, gridLines: true }}
+  yAxis={{ hidden: false, gridLines: true }}
+  legend={{ hidden: true }}
+  animate
+/>
+```
+
+### Convenience wrappers
+
+| Component         | What it renders                                                       |
+| ----------------- | --------------------------------------------------------------------- |
+| `<PieChart />`    | `sector` marks. Donut hole + optional center label slot.              |
+| `<LineChart />`   | `line` mark, optionally with `area` underneath (the `area` prop).     |
+| `<AreaChart />`   | `area` mark with native linear gradient fill.                         |
+| `<BarChart />`    | `bar` marks. Single series or multi-series via `category`.            |
+| `<ScatterChart />`| `point` marks with configurable symbol + size.                        |
+| `<RangeBarChart />`| `rectangle` marks between `yStart` and `yEnd` (candles, ranges, etc).|
+
+### Runtime helper
+
+| Export                | Returns                                                          |
+| --------------------- | ---------------------------------------------------------------- |
+| `isChartSupported()`  | `true` only on iOS 17+. Use to mount a fallback renderer on iOS 15–16 and on Android / web. See [Feature-detecting at runtime](#feature-detecting-at-runtime). |
+
+Example — pie with center label:
+
+```tsx
+import { PieChart } from "rn-native-ios-charts";
+
+<PieChart
+  style={{ width: 240, height: 240 }}
+  data={[
+    { label: "Cash", value: 86, color: "#1FA92E" },
+    { label: "Stocks", value: 50, color: "#3B82F6" },
+  ]}
+  innerRadius={0.62}
+  angularInset={2}
+  centerLabel={{
+    value: "$136",
+    label: "Total",
+    valueColor: "#FFFFFF",
+    labelColor: "#9BA1A6",
+  }}
+/>
+```
+
+The center label is rendered **inside the chart's plot frame** via
+SwiftUI's `chartBackground` + `ChartProxy.plotFrame`, so it tracks the
+donut's actual center and scales with the chart automatically. No JS
+overlays, no `onLayout` tricks.
+
+Example — gradient line:
+
+```tsx
+import { LineChart } from "rn-native-ios-charts";
+
+<LineChart
+  style={{ width: "100%", height: 200 }}
+  data={[
+    { x: "2024", y: 12000 },
+    { x: "2025", y: 38000 },
+    { x: "2026", y: 86000 },
+  ]}
+  color="#1FA92E"
+  area={{ startOpacity: 0.35, endOpacity: 0.02 }}
+  interpolation="catmullRom"
+  showPoints
+/>
+```
+
+## Interactivity — native tooltips & selection
+
+All cartesian charts (line, area, bar, point, rectangle) support
+SwiftUI's native `chartXSelection` scrubber. Long-press + drag and
+the tooltip follows your finger, snapping to the nearest data point.
+No JS frame round-trips — the highlight, scrubber rule and callout
+are all drawn inside the SwiftUI view hierarchy.
+
+```tsx
+import { LineChart } from "rn-native-ios-charts";
+
+<LineChart
+  data={monthlyRevenue}
+  color="#1FA92E"
+  area={{ startOpacity: 0.35, endOpacity: 0.02 }}
+  tooltip={{
+    enabled: true,
+    valuePrefix: "$",
+    valueDecimals: 0,
+    backgroundColor: "#161618",
+    textColor: "#FFFFFF",
+    borderColor: "#2A2A2D",
+  }}
+  onSelect={(point) => {
+    if (point) console.log(`${point.x}: $${point.y}`);
+  }}
+/>
+```
+
+### `tooltip` config
+
+| Field             | Default                | Notes                                                  |
+| ----------------- | ---------------------- | ------------------------------------------------------ |
+| `enabled`         | `false`                | Opt-in — charts stay static unless you set this.       |
+| `showRule`        | `true`                 | Dashed vertical line at the selected X.                |
+| `showDot`         | `true`                 | Filled dot at the active point, ringed in `backgroundColor`. |
+| `showTitle`       | `true`                 | Show the `x` label above the value in the callout.     |
+| `backgroundColor` | system background      | Callout fill.                                          |
+| `textColor`       | system label           | Callout text.                                          |
+| `borderColor`     | system separator       | Callout border + scrubber rule.                        |
+| `valuePrefix`     | `""`                   | Prepended to the y value, e.g. `"$"`.                  |
+| `valueSuffix`     | `""`                   | Appended, e.g. `"%"`.                                  |
+| `valueDecimals`   | `0`                    | Decimal places. Numbers always get thousands separators. |
+
+The callout is positioned above the active point and **auto-clamped
+to the plot frame** — it never overflows the chart's bounds, even at
+the leftmost / rightmost / topmost data points.
+
+### `onSelect` event
+
+Fires every time the selection changes (including when it clears):
+
+```ts
+onSelect?: (point: { x: string; y: number } | null) => void;
+```
+
+For pie / donut charts there's no visual callout — `onSelect` fires
+on slice taps via `chartAngleSelection`, and the natural place to
+display the info is the `centerLabel`:
+
+```tsx
+import { useState } from "react";
+import { PieChart } from "rn-native-ios-charts";
+
+const [center, setCenter] = useState({ value: "$148K", label: "Total" });
+
+<PieChart
+  data={portfolio}
+  innerRadius={0.62}
+  centerLabel={{ ...center, valueColor: "#FFFFFF", labelColor: "#9BA1A6" }}
+  onSelect={(point) => {
+    setCenter(
+      point
+        ? { value: `$${point.y}K`, label: point.x }
+        : { value: "$148K", label: "Total" }
+    );
+  }}
+/>
+```
+
+## Supported marks
+
+| Mark type     | What it draws                              |
+| ------------- | ------------------------------------------ |
+| `bar`         | Vertical bars                              |
+| `line`        | Connected line                             |
+| `area`        | Filled area under a line                   |
+| `point`       | Discrete symbols at each datum             |
+| `rectangle`   | Rectangle between `yStart` and `yEnd`      |
+| `rule`        | Horizontal or vertical reference line      |
+| `sector`      | Pie / donut wedge (iOS 17+)                |
+
+## Supported per-mark config
+
+- **Color:** solid `color` (any RN ColorValue) or `gradient` (linear,
+  multi-stop, custom start/end points).
+- **Line interpolation:** `linear`, `catmullRom`, `monotone`,
+  `stepStart`, `stepEnd`, `stepCenter`.
+- **Line stroke:** `lineWidth`, `dashArray`, `lineCap`.
+- **Symbols:** `circle`, `square`, `triangle`, `diamond`, `pentagon`,
+  `plus`, `cross`, `asterisk`. With `symbolSize` and `showPoints`.
+- **Bar / rectangle:** `cornerRadius`, fixed `barWidth`.
+- **Sector:** `innerRadius`, `outerRadius`, `angularInset`,
+  `cornerRadius`.
+- **Per-point overrides:** every datum can carry its own `color` and
+  `category` (series key for auto-coloring + legend grouping).
+- **Opacity** per mark.
+
+## Supported chart-level config
+
+- `xAxis` / `yAxis`: hidden, grid lines, tick labels, label color &
+  font size, custom `[domainMin, domainMax]`.
+- `legend`: hidden, placement (`top`, `bottom`, `leading`, `trailing`,
+  `overlay`, `automatic`).
+- `centerLabel`: the in-plot value + caption pair, rendered inside
+  the chart's plot frame.
+- `tooltip`: interactive scrubber tooltip with native
+  `chartXSelection` — vertical rule + dot + auto-clamped callout. See
+  [Interactivity](#interactivity--native-tooltips--selection) above.
+- `onSelect(point)`: event fired when the user picks a point via the
+  scrubber or taps a pie sector. Payload is `{ x, y }` or `null`.
+- `animate`: toggle SwiftUI's native ease-in-out on data changes.
+
+Top-level utility:
+
+- `isChartSupported()`: runtime feature-detection helper — `true` on
+  iOS 17+, `false` elsewhere. Pair with a fallback chart library on
+  older iOS or non-iOS platforms. See
+  [Feature-detecting at runtime](#feature-detecting-at-runtime).
+
+## Platform support
+
+- **iOS 17+** — full rendering. SwiftUI Charts unified API,
+  `chartBackground`, `SectorMark`, `chartXSelection`,
+  `chartAngleSelection`.
+- **iOS 15.1–16.x** — the pod installs cleanly so this library can
+  be a dependency of any modern Expo app, but `<Chart />` renders an
+  empty `UIHostingController` on these versions. The SwiftUI Charts
+  unified API isn't available pre-17, so there's nothing to draw.
+- **Other platforms** — the components render a transparent placeholder
+  `View` so consuming code doesn't need to feature-detect.
+
+### Feature-detecting at runtime
+
+Use `isChartSupported()` to swap in an alternative renderer
+(`react-native-gifted-charts`, Victory, your own placeholder, etc.)
+on iOS < 17 and on Android / web:
+
+```tsx
+import { isChartSupported, LineChart } from "rn-native-ios-charts";
+import { LineChart as GiftedLine } from "react-native-gifted-charts";
+
+export function MyChart(props) {
+  return isChartSupported()
+    ? <LineChart {...props} />
+    : <GiftedLine {...mapToGiftedProps(props)} />;
+}
+```
+
+The check is a single integer parse of `Platform.Version` — cheap
+enough to call inline on every render.
+
+## Installation
+
+```bash
+npm install rn-native-ios-charts
+cd ios && pod install
+```
+
+Rebuild the native app (Metro reload alone won't pick this up — it
+ships a native module).
+
+For local / monorepo development, place the package at
+`modules/rn-native-ios-charts/` and reference it via the `link:`
+protocol so edits propagate without reinstalling:
+
+```json
+// package.json
+{
+  "dependencies": {
+    "rn-native-ios-charts": "link:./modules/rn-native-ios-charts"
+  }
+}
+```
+
+Expo autolinking picks up the symlinked module on the next
+`pod install` automatically.

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["ios"],
+  "ios": {
+    "modules": ["NativeIosChartsModule"]
+  }
+}

package/ios/ChartConfig.swift

@@ -0,0 +1,70 @@
+import ExpoModulesCore
+
+/// Per-axis config. Each field is optional; omit to use SwiftUI's
+/// automatic behavior.
+internal struct ChartAxisConfig: Record {
+  @Field var hidden: Bool = false
+  @Field var gridLines: Bool = true
+  @Field var tickLabels: Bool = true
+  /// Hex color string parsed by Expo's UIColor converter. `nil` =
+  /// system default.
+  @Field var labelColor: UIColor?
+  @Field var gridColor: UIColor?
+  @Field var labelFontSize: Double = 11
+  /// Explicit numeric domain. Both must be set to take effect.
+  @Field var domainMin: Double?
+  @Field var domainMax: Double?
+
+  init() {}
+}
+
+/// Legend placement + visibility. SwiftUI handles auto-coloring when
+/// `category` is set on data points.
+internal struct ChartLegendConfig: Record {
+  @Field var hidden: Bool = false
+  /// "automatic" | "top" | "bottom" | "leading" | "trailing" | "overlay".
+  @Field var placement: String = "automatic"
+
+  init() {}
+}
+
+/// Center label drawn inside the chart's plot frame via
+/// `chartBackground`. Most useful with `sector` marks (the donut hole)
+/// but works on any chart.
+internal struct ChartCenterLabel: Record {
+  @Field var value: String?
+  @Field var label: String?
+  @Field var valueColor: UIColor?
+  @Field var labelColor: UIColor?
+  @Field var valueFontSize: Double = 18
+  @Field var labelFontSize: Double = 11
+
+  init() {}
+}
+
+/// Tooltip overlay shown when the user touches/drags on a cartesian
+/// chart. Uses SwiftUI Charts' native `chartXSelection`, so the
+/// scrubber snaps to data points automatically. For `sector` marks
+/// (pie / donut), `chartAngleSelection` fires the `onSelect` event
+/// but no visual callout is drawn — use the event to update a
+/// `centerLabel` or your own JS overlay.
+internal struct ChartTooltipConfig: Record {
+  @Field var enabled: Bool = false
+  /// Draw a vertical rule at the selected X.
+  @Field var showRule: Bool = true
+  /// Highlight the active point with a filled dot.
+  @Field var showDot: Bool = true
+  /// Show the x label above the y value in the callout.
+  @Field var showTitle: Bool = true
+  @Field var backgroundColor: UIColor?
+  @Field var textColor: UIColor?
+  @Field var borderColor: UIColor?
+  /// Decimal places for the y value when formatting. Default 0.
+  @Field var valueDecimals: Int = 0
+  /// Optional prefix (eg "$") prepended to the y value.
+  @Field var valuePrefix: String = ""
+  /// Optional suffix (eg "%") appended to the y value.
+  @Field var valueSuffix: String = ""
+
+  init() {}
+}

package/ios/ChartDataPoint.swift

@@ -0,0 +1,25 @@
+import ExpoModulesCore
+
+/// One datum on any chart. The shape is intentionally permissive so a
+/// single struct serves bar, line, area, point, rectangle, rule and
+/// sector marks.
+///
+/// - `x` / `y`: primary coordinate. `x` is stringly-typed because
+///   SwiftUI Charts categorical axes want strings; if your data is
+///   numeric, stringify it on the JS side (`String(year)`).
+/// - `yEnd`: optional second value — used by range bar / rectangle
+///   marks (a stacked low/high pair).
+/// - `category`: optional grouping key. When present, the chart
+///   colors by `.value("Category", category)` so SwiftUI assigns a
+///   consistent color per series across the legend.
+/// - `color`: per-point override. Wins over the mark-level color
+///   when both are set.
+internal struct ChartDataPoint: Record {
+  @Field var x: String = ""
+  @Field var y: Double = 0
+  @Field var yEnd: Double?
+  @Field var category: String?
+  @Field var color: UIColor?
+
+  init() {}
+}

package/ios/ChartGradient.swift

@@ -0,0 +1,33 @@
+import ExpoModulesCore
+
+/// One stop in a multi-stop gradient.
+internal struct ChartGradientStop: Record {
+  /// Position along the gradient axis, 0–1.
+  @Field var offset: Double = 0
+  @Field var color: UIColor?
+  /// 0 = transparent, 1 = opaque. Multiplied with the stop's color alpha.
+  @Field var opacity: Double = 1.0
+
+  init() {}
+}
+
+/// Gradient fill applied to a mark's `foregroundStyle`. Two-stop
+/// shorthand (`startOpacity` + `endOpacity`) is the common case; for
+/// fancier multi-stop gradients use `stops`.
+internal struct ChartGradient: Record {
+  /// "linear" | "radial". Default linear.
+  @Field var kind: String = "linear"
+  /// Linear gradient start point in unit coords. Defaults to .top.
+  @Field var startX: Double = 0.5
+  @Field var startY: Double = 0
+  /// Linear gradient end point in unit coords. Defaults to .bottom.
+  @Field var endX: Double = 0.5
+  @Field var endY: Double = 1
+  /// Two-stop shorthand — used when `stops` is empty.
+  @Field var startOpacity: Double = 0.35
+  @Field var endOpacity: Double = 0.02
+  /// Explicit stops. Overrides `startOpacity` / `endOpacity` when set.
+  @Field var stops: [ChartGradientStop] = []
+
+  init() {}
+}

package/ios/ChartMark.swift

@@ -0,0 +1,64 @@
+import ExpoModulesCore
+
+/// One mark on the chart. `type` discriminates between bar / line /
+/// area / point / rectangle / rule / sector — Swift switches on it to
+/// render the appropriate SwiftUI Mark.
+///
+/// All optional fields default to sensible no-ops so consumers only
+/// pass what they care about.
+internal struct ChartMark: Record {
+  /// Discriminator. One of: "bar", "line", "area", "point",
+  /// "rectangle", "rule", "sector".
+  @Field var type: String = "line"
+  @Field var data: [ChartDataPoint] = []
+
+  // ─── Color / fill ───
+  @Field var color: UIColor?
+  @Field var opacity: Double = 1.0
+  /// Optional gradient — wins over solid `color` when set. Most
+  /// commonly used on AreaMark for the "fill under the curve" look.
+  @Field var gradient: ChartGradient?
+
+  // ─── Stroke (line, rule) ───
+  @Field var lineWidth: Double = 2.0
+  /// Dash pattern in points. Empty array = solid line.
+  @Field var dashArray: [Double] = []
+  /// "butt" | "round" | "square". Default "round".
+  @Field var lineCap: String = "round"
+
+  // ─── Line / area interpolation ───
+  /// One of: "linear", "catmullRom", "monotone", "stepStart",
+  /// "stepEnd", "stepCenter". Default "linear".
+  @Field var interpolation: String = "linear"
+
+  // ─── Symbols (point marks, line w/ points) ───
+  /// One of: "circle", "square", "triangle", "diamond", "pentagon",
+  /// "plus", "cross", "asterisk".
+  @Field var symbol: String = "circle"
+  @Field var symbolSize: Double = 36
+  /// When true on a `line` mark, draw point symbols at each datum.
+  @Field var showPoints: Bool = false
+
+  // ─── Bar / rectangle ───
+  @Field var cornerRadius: Double = 0
+  /// Bar width (pt). 0 = auto.
+  @Field var barWidth: Double = 0
+
+  // ─── Sector (pie / donut) ───
+  /// Inner radius as a ratio of outer, 0–1. 0 = full pie, 0.62 = thin donut.
+  @Field var innerRadius: Double = 0
+  /// Outer radius as a ratio of available space, 0–1. 0 = auto.
+  @Field var outerRadius: Double = 0
+  /// Gap between adjacent sectors, pt.
+  @Field var angularInset: Double = 0
+
+  // ─── Rule mark orientation ───
+  /// "horizontal" | "vertical". A horizontal rule draws a constant-y
+  /// reference line across the chart's x extent (and vice-versa).
+  @Field var orientation: String = "horizontal"
+  /// Constant value the rule is drawn at (interpretation depends on
+  /// orientation). When set, `data` can be empty.
+  @Field var ruleValue: Double?
+
+  init() {}
+}