rn-native-ios-charts 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-05-11
+
+Production-grade upgrades: trading-chart props, multi-series support,
+axis value formatters, richer tooltip + selection payloads, and an
+axis-config bug fix that surfaced once people actually customized
+their axes.
+
+### Added
+
+- **`tightX`** prop on `<Chart />` / `<LineChart />` / `<BarChart />`
+  — zeros out SwiftUI Charts' default plot-dimension X padding so
+  the first and last data points sit flush against the chart's left
+  and right edges. The "Robinhood / Apple Stocks" look. Pair with
+  `xAxis={{ hidden: true }}` for a clean trading-chart aesthetic.
+- **`scrollableX`** + **`visibleXCount`** — enables SwiftUI's
+  native `chartScrollableAxes(.horizontal)` plus
+  `chartXVisibleDomain(length:)`. Use this instead of wrapping the
+  chart in an RN `<ScrollView horizontal>` — native scrolling
+  keeps tooltip coordinates correct and avoids gesture conflicts
+  with the selection scrubber.
+- **`categoryColors`** chart-level prop — maps `category` →
+  `ColorValue`. Translates to SwiftUI's
+  `chartForegroundStyleScale`. Define a palette once at the chart
+  level instead of repeating `color` on every datum.
+- **Axis value formatters.** `AxisConfig` now honors `valueFormat`
+  (`"raw" | "currency" | "percent" | "abbreviated" | "decimal"`),
+  `currencyCode`, `valueDecimals`, `valuePrefix`, and `valueSuffix`.
+  Common patterns:
+  ```tsx
+  yAxis={{ valueFormat: "currency", currencyCode: "USD" }}
+  yAxis={{ valuePrefix: "$", valueDecimals: 0 }}     // symbol-only
+  yAxis={{ valueFormat: "abbreviated" }}             // 1K / 1.2M
+  yAxis={{ valueFormat: "percent" }}                 // 0.5 → "50%"
+  ```
+- **Multi-series tooltip.** `tooltip.multiSeries` renders one row
+  per cartesian mark at the selected X (color dot + series name +
+  formatted value). Drops to a single-row callout automatically
+  when only one mark is present. Useful for OHLC stock charts and
+  side-by-side comparisons.
+- **`markIndex` + `pointIndex` in the `onSelect` payload.** Lets
+  consumers locate the datum in their `marks` array
+  deterministically — value-only matching is fragile when two
+  slices share the same y. Existing single-key consumers continue
+  to work; the indices are additive.
+- **Multi-line `<LineChart>` via the new `series` prop.** Pass an
+  array of `{ name, color, data, ...overrides }` to draw multiple
+  lines on the same plot. Each series' `name` becomes the
+  `category` key, the legend label, and the row label in the
+  multi-series tooltip. The existing `data` prop still works for
+  single-series charts.
+- **Bar chart enhancements.** Two new fields on `bar` marks (and
+  the matching `<BarChart>` props):
+    - `position: "auto" | "stacked" | "grouped"` — multi-series
+      positioning. `"stacked"` applies SwiftUI's
+      `positionAdjustment(.stacking)`; `"grouped"` applies
+      `position(by: .value("Series", category))` so bars sit
+      side-by-side.
+    - `horizontal: boolean` — swaps the X and Y axes for `bar`
+      marks. Use for Top-N lists and ranked leaderboards.
+
+### Fixed
+
+- **Axis customization fields now actually apply.** `xAxis` /
+  `yAxis` config has supported `labelColor`, `labelFontSize`,
+  `gridColor`, `gridLines`, and `tickLabels` since v0.1.0, but the
+  Swift side only toggled `.hidden` vs `.automatic` and silently
+  ignored the rest. Replaced the boolean toggle with a full
+  `AxisMarks` builder so every field is honored.
+
+  **Migration note:** if you were passing these fields and worked
+  around the lack of effect (e.g. extra padding to hide the
+  default label color), your chart will now render with the
+  requested style. Visual diffs are possible.
+
 ## [0.1.0] — 2026-05-11
 
 Initial public release. iOS-only Expo module that bridges every SwiftUI
@@ -57,5 +131,6 @@ primitive plus convenience wrappers.
   `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
+[Unreleased]: https://github.com/abdallaemadeldin/rn-native-ios-charts/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/abdallaemadeldin/rn-native-ios-charts/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/abdallaemadeldin/rn-native-ios-charts/releases/tag/v0.1.0

package/README.md

@@ -136,6 +136,227 @@ import { LineChart } from "rn-native-ios-charts";
 />
 ```
 
+## Trading-chart preset — `tightX` + hidden axes
+
+For the Robinhood / Apple Stocks aesthetic — line flush against
+both screen edges, no axes, no grid, deep gradient fill. The `tightX`
+prop zeros out SwiftUI Charts' default plot-dimension padding so the
+first and last points sit at the chart's left and right edges.
+
+```tsx
+import { LineChart } from "rn-native-ios-charts";
+
+<LineChart
+  style={{ width: "100%", height: 260 }}
+  data={dailyPrice}
+  color="#1FA92E"
+  lineWidth={3}
+  interpolation="catmullRom"
+  area={{ startOpacity: 0.55, endOpacity: 0 }}
+  tightX
+  xAxis={{ hidden: true }}
+  yAxis={{ hidden: true }}
+  tooltip={{ enabled: true, valuePrefix: "$" }}
+/>
+```
+
+## Multi-line charts — `<LineChart series={…} />`
+
+Render multiple lines on the same plot by passing a `series` array
+instead of a single `data` array. Each series has its own color and
+its own line config (width, dash, interpolation, points, symbol,
+area) — chart-level props act as fallbacks.
+
+```tsx
+import { LineChart } from "rn-native-ios-charts";
+
+<LineChart
+  // Chart-level defaults
+  lineWidth={2}
+  interpolation="catmullRom"
+  series={[
+    {
+      name: "Revenue",
+      color: "#1FA92E",
+      data: revenueByMonth,
+      area: { startOpacity: 0.4, endOpacity: 0 },  // shaded under this one
+    },
+    {
+      name: "Expenses",
+      color: "#F59E0B",
+      data: expensesByMonth,
+      lineWidth: 3,
+      dashArray: [6, 4],     // dashed
+    },
+    {
+      name: "Forecast",
+      color: "#3B82F6",
+      data: forecastByMonth,
+      interpolation: "linear",
+      showPoints: true,
+      symbol: "diamond",
+    },
+  ]}
+  tooltip={{ enabled: true, multiSeries: true, valuePrefix: "$" }}
+/>
+```
+
+Each series' `name` becomes:
+
+- the `category` key on every point (so SwiftUI groups them into one
+  continuous line),
+- the legend label, and
+- the row label in the multi-series tooltip (see below).
+
+The single-series `data` prop still works for one-line charts — pass
+either `data` **or** `series`, not both. If both, `series` wins.
+
+## Multi-series tooltip
+
+Pair multi-line charts with `tooltip.multiSeries` to get a stacked-row
+callout: one row per cartesian mark at the selected X, each with the
+series' color dot, name, and formatted value.
+
+```tsx
+<LineChart
+  series={[ /* multiple series as above */ ]}
+  tooltip={{
+    enabled: true,
+    multiSeries: true,         // <-- enables the stacked-row callout
+    valuePrefix: "$",
+    backgroundColor: "#161618",
+    textColor: "#FFFFFF",
+    borderColor: "#2A2A2D",
+  }}
+/>
+```
+
+When the chart has only one cartesian mark, `multiSeries` silently
+falls back to the regular single-row tooltip — safe to leave on.
+
+## Axis value formatters
+
+Format the tick labels on either axis without writing custom Swift.
+Supports four common formats plus optional prefix/suffix; works on
+numeric axes (in practice: the Y axis, since X is `String`).
+
+```tsx
+<LineChart
+  data={annualRevenue}
+  yAxis={{ valueFormat: "currency", currencyCode: "USD" }}
+/>
+
+<LineChart
+  data={percentReturns}
+  yAxis={{ valueFormat: "percent" }}    // 0.5 → "50%"
+/>
+
+<LineChart
+  data={networthOverTime}
+  yAxis={{ valueFormat: "abbreviated" }} // 1K, 1.2M, 3.4B
+/>
+
+<LineChart
+  data={returns}
+  yAxis={{ valuePrefix: "$", valueDecimals: 0 }}  // symbol-only "$50,000"
+/>
+```
+
+| `valueFormat` | Output (en-US)            | Notes                                  |
+| ------------- | ------------------------- | -------------------------------------- |
+| `"raw"` (default) | `50000`               | Plain number with `valueDecimals`.     |
+| `"currency"`  | `$50,000.00`              | Locale-aware. Uses `currencyCode`.     |
+| `"percent"`   | `50%`                     | SwiftUI multiplies by 100 — pass `0.5` to render `"50%"`. For pre-scaled (0–100) values, use `valueSuffix: "%"` instead. |
+| `"abbreviated"` | `50K`, `1.2M`, `3.4B`   | Compact notation.                      |
+| `"decimal"`   | `50,000.00`               | Plain decimal with thousands separators. |
+
+`valuePrefix` / `valueSuffix` are applied after the format style, so
+`valueFormat: "decimal" + valuePrefix: "$"` gives you symbol-only
+currency without locale code lookups.
+
+## Category color palettes — `categoryColors`
+
+When your data has `category` values, set a chart-level palette
+instead of repeating `color` on every datum. Translates to SwiftUI's
+`chartForegroundStyleScale`.
+
+```tsx
+<LineChart
+  series={[
+    { name: "Cash", data: cashData },
+    { name: "Stocks", data: stocksData },
+    { name: "Bonds", data: bondsData },
+  ]}
+  categoryColors={{
+    Cash:   "#1FA92E",
+    Stocks: "#3B82F6",
+    Bonds:  "#F59E0B",
+  }}
+/>
+```
+
+Per-series `color` (or per-point `color`) always overrides
+`categoryColors` when both are set.
+
+## Bar charts — stacking & horizontal
+
+`<BarChart>` (and `bar` marks on the generic `<Chart>`) accept two
+extra fields for multi-series layouts:
+
+```tsx
+// Stacked bars
+<BarChart
+  data={[
+    { x: "Q1", y: 24, category: "Revenue" },
+    { x: "Q1", y: 18, category: "Expenses" },
+    { x: "Q2", y: 31, category: "Revenue" },
+    { x: "Q2", y: 22, category: "Expenses" },
+  ]}
+  position="stacked"
+  categoryColors={{ Revenue: "#1FA92E", Expenses: "#F59E0B" }}
+/>
+
+// Grouped (side-by-side)
+<BarChart
+  data={/* same data */}
+  position="grouped"
+  categoryColors={{ Revenue: "#1FA92E", Expenses: "#F59E0B" }}
+/>
+
+// Horizontal bars — Top-N / ranked leaderboards
+<BarChart
+  data={topAssetsByValue}      // [{ x: "AAPL", y: 38000 }, ...]
+  horizontal
+  cornerRadius={4}
+/>
+```
+
+| Prop         | Effect                                                                 |
+| ------------ | ---------------------------------------------------------------------- |
+| `position: "auto"`    | SwiftUI's default.                                            |
+| `position: "stacked"` | Applies `.positionAdjustment(.stacking)`.                     |
+| `position: "grouped"` | Applies `.position(by: .value("Series", category))`.          |
+| `horizontal: true`    | Swaps X and Y on `BarMark` — labels on the Y axis.            |
+
+## Horizontal scrolling for long time series
+
+When you have more data points than fit on screen, use SwiftUI's
+native `chartScrollableAxes(.horizontal)` instead of wrapping the
+chart in an RN `<ScrollView horizontal>` — that wrapper would steal
+the scrubber's pan gesture and shift the tooltip's touch coordinates.
+
+```tsx
+<LineChart
+  data={twoYearsOfDailyData}      // ~730 points
+  scrollableX                     // enables native horizontal scroll
+  visibleXCount={30}              // show ~30 days per "page"
+  tooltip={{ enabled: true }}     // scrubber + tooltip still work
+/>
+```
+
+`visibleXCount` is optional — omit it (or pass 0) to let SwiftUI
+auto-decide.
+
 ## Interactivity — native tooltips & selection
 
 All cartesian charts (line, area, bar, point, rectangle) support
@@ -189,9 +410,24 @@ the leftmost / rightmost / topmost data points.
 Fires every time the selection changes (including when it clears):
 
 ```ts
-onSelect?: (point: { x: string; y: number } | null) => void;
+type SelectedPoint = {
+  x: string;
+  y: number;
+  /** Index of the mark this point belongs to (0-based). */
+  markIndex: number;
+  /** Index of the point within that mark's data (0-based). */
+  pointIndex: number;
+} | null;
+
+onSelect?: (point: SelectedPoint) => void;
 ```
 
+The `markIndex` + `pointIndex` pair locates the datum in the caller's
+`marks` array deterministically — value-only matching is fragile
+when two slices or points share the same y. Pies emit the slice
+index on tap; cartesian charts emit the first cartesian mark's
+index for the selected X.
+
 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`:
@@ -257,8 +493,25 @@ const [center, setCenter] = useState({ value: "$148K", label: "Total" });
   [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`.
+- `tightX`: zero out plot-dimension X padding so the line / area
+  bleeds to both edges. See [Trading-chart preset](#trading-chart-preset--tightx--hidden-axes).
+- `scrollableX` + `visibleXCount`: enable SwiftUI's native horizontal
+  scrolling. See [Horizontal scrolling](#horizontal-scrolling-for-long-time-series).
+- `categoryColors`: map `category` strings → colors. See
+  [Category color palettes](#category-color-palettes--categorycolors).
 - `animate`: toggle SwiftUI's native ease-in-out on data changes.
 
+`xAxis` / `yAxis` honor every field — `labelColor`, `labelFontSize`,
+`gridColor`, `gridLines`, `tickLabels`, plus optional `[domainMin,
+domainMax]` and `valueFormat` / `currencyCode` / `valueDecimals` /
+`valuePrefix` / `valueSuffix` for tick label formatting. See
+[Axis value formatters](#axis-value-formatters). (Fully wired from
+v0.2.0 onward — v0.1.0 silently ignored everything except `hidden`.)
+
+Bar marks additionally accept `position: "auto" | "stacked" |
+"grouped"` and `horizontal: boolean` — see
+[Bar charts — stacking & horizontal](#bar-charts--stacking--horizontal).
+
 Top-level utility:
 
 - `isChartSupported()`: runtime feature-detection helper — `true` on

package/ios/ChartConfig.swift

@@ -14,6 +14,23 @@ internal struct ChartAxisConfig: Record {
   /// Explicit numeric domain. Both must be set to take effect.
   @Field var domainMin: Double?
   @Field var domainMax: Double?
+  /// Value-label format. Only meaningful for axes whose values are
+  /// Double (in practice: the Y axis — our X axis is `String`):
+  ///   - "" / "raw"      — no formatting, pass through
+  ///   - "currency"      — locale-aware currency (`currencyCode`)
+  ///   - "percent"       — multiplied by 100 with "%"
+  ///   - "abbreviated"   — compact "1K", "1.2M", "3.4B"
+  ///   - "decimal"       — plain number with `decimals` fraction digits
+  @Field var valueFormat: String = ""
+  /// Used when `valueFormat == "currency"`. Default "USD".
+  @Field var currencyCode: String = "USD"
+  /// Fraction digits for numeric formatters that respect it. Default 0.
+  @Field var valueDecimals: Int = 0
+  /// Prepended to the formatted value, e.g. "$" when not using the
+  /// currency format. Useful for custom prefixes/suffixes.
+  @Field var valuePrefix: String = ""
+  /// Appended to the formatted value, e.g. "%" or " years".
+  @Field var valueSuffix: String = ""
 
   init() {}
 }
@@ -56,6 +73,11 @@ internal struct ChartTooltipConfig: Record {
   @Field var showDot: Bool = true
   /// Show the x label above the y value in the callout.
   @Field var showTitle: Bool = true
+  /// Render one row per mark at the selected X (color dot + series
+  /// name + value). Falls back to single-row mode when the chart has
+  /// only one cartesian mark anyway. Useful for OHLC stock charts
+  /// and side-by-side series comparisons.
+  @Field var multiSeries: Bool = false
   @Field var backgroundColor: UIColor?
   @Field var textColor: UIColor?
   @Field var borderColor: UIColor?

package/ios/ChartMark.swift

@@ -43,6 +43,14 @@ internal struct ChartMark: Record {
   @Field var cornerRadius: Double = 0
   /// Bar width (pt). 0 = auto.
   @Field var barWidth: Double = 0
+  /// Bar positioning when multiple BarMarks share an X:
+  ///   - "auto"    (default) — SwiftUI's default behavior
+  ///   - "stacked" — explicit `.positionAdjustment(.stacking)`
+  ///   - "grouped" — side-by-side via `.position(by: category)`
+  @Field var position: String = "auto"
+  /// Horizontal bars — swap the X and Y axes for `bar` marks. Use
+  /// for Top-N lists, ranked leaderboards, etc.
+  @Field var horizontal: Bool = false
 
   // ─── Sector (pie / donut) ───
   /// Inner radius as a ratio of outer, 0–1. 0 = full pie, 0.62 = thin donut.