react-scale-break-chart 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angga Fardana
+
+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,94 @@
+# react-scale-break-chart
+
+A zero-dependency React SVG bar chart that automatically compresses extreme value ranges behind a zigzag break indicator so both small and large values remain readable side-by-side.
+
+[![CI](https://github.com/afardana/react-scale-break-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/afardana/react-scale-break-chart/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/react-scale-break-chart)](https://www.npmjs.com/package/react-scale-break-chart)
+
+## Features
+
+- **Automatic scale break** — detects when one series dominates others by an order of magnitude and compresses the upper region behind a styled zigzag indicator
+- **Upper-region zoom** — when dominant values are tightly clustered (< 10% variance), the chart zooms into the top of the Y-axis so small differences are still visible
+- **Non-break zoom** — when all values are clustered (e.g. 8.029M – 8.068M), the Y-axis automatically narrows around the data range rather than starting at 0
+- **Transition zone** — series that cross the break but fall below the zoomed region get proportional height above the break band
+- **Responsive** — auto-sizes to container width via `ResizeObserver`; supports `height="auto"` for container-driven height
+- **Tooltips & hover** — built-in hover effects with a clean tooltip; no external charting library needed
+- **Tree-shakeable** — ships ESM + CJS with TypeScript declarations
+- **Minimal footprint** — ~28 KB min (no D3, no Recharts)
+
+## Install
+
+```bash
+npm install react-scale-break-chart
+```
+
+## Quick Start
+
+```tsx
+import { ScaleBreakBarChart } from 'react-scale-break-chart';
+
+const data = [
+  { name: 'Jan', otc: 158_000, voice: 2_711_000, fbb: 7_286_000 },
+  { name: 'Feb', otc: 146_000, voice: 2_673_000, fbb: 7_297_000 },
+  { name: 'Mar', otc: 152_000, voice: 2_650_000, fbb: 7_310_000 },
+];
+
+const series = [
+  { dataKey: 'otc',   label: 'OTC',             color: '#F5A623' },
+  { dataKey: 'voice', label: 'Voice',            color: '#E74C3C' },
+  { dataKey: 'fbb',   label: 'Fixed Broadband',  color: '#5B9BD5' },
+];
+
+function App() {
+  return (
+    <ScaleBreakBarChart
+      data={data}
+      series={series}
+      height={400}
+      breakThreshold={5}
+      formatValue={(v) => v.toLocaleString('id-ID')}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `ScaleBreakDataPoint[]` | — | Array of data points; one per bar group |
+| `series` | `SeriesConfig[]` | — | Series definitions (dataKey, label, color) |
+| `height` | `number \| 'auto'` | `350` | Fixed px height or `'auto'` for container-driven |
+| `breakThreshold` | `number` | `5` | Ratio above which the dominant series triggers a scale break |
+| `formatValue` | `(n: number) => string` | `String` | Formatter for value labels & tooltip |
+| `className` | `string` | — | Additional className on root wrapper |
+
+## How the Scale Break Works
+
+```
+┌────────────────────────────────────┐
+│          Upper region              │  ← zoomed scale for dominant series
+│  ╱╲╱╲╱╲╱╲╱╲╱╲╱╲  break indicator  │
+│          Lower region              │  ← proportional scale for all series
+│──────────────────────────── 0 ─────│
+└────────────────────────────────────┘
+```
+
+1. **Break detection**: When `max(series₁) / max(series₂) > breakThreshold`, the chart splits the Y-axis
+2. **Lower region** (40%): Shows small values proportionally
+3. **Upper region** (60%): Shows large values in a compressed (or zoomed) scale
+4. **Transition zone**: If the upper region is zoomed, bars between `lowerMax` and `upperMin` get sqrt-scaled height in a reserved 15% transition area
+
+## Development
+
+```bash
+npm install
+npm run build       # tsup → dist/
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+npm run dev         # tsup --watch
+```
+
+## License
+
+[MIT](./LICENSE) © Angga Fardana

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Scale-Break Bar Chart — Type definitions
+ *
+ * A custom SVG chart that compresses dominant values with zigzag break
+ * indicators so small values remain clearly visible alongside large ones.
+ * Supports both stacked and grouped (side-by-side) bar modes.
+ */
+/** A single data point on the x-axis (e.g., one month). */
+interface ScaleBreakDataPoint {
+    /** Display label for the x-axis (e.g. "January"). */
+    name: string;
+    /** Dynamic numeric keys matching `SeriesConfig.dataKey`. */
+    [key: string]: string | number;
+}
+/** Configuration for one segment / series in the bar chart. */
+interface SeriesConfig {
+    /** Property name on the data point to read the value from. */
+    dataKey: string;
+    /** Human-readable label shown in legend & tooltip. */
+    label: string;
+    /** Fill colour (hex or CSS). */
+    color: string;
+}
+/** Props accepted by the `<ScaleBreakBarChart>` component. */
+interface ScaleBreakBarChartProps {
+    /** Array of data points; one per bar group. */
+    data: ScaleBreakDataPoint[];
+    /** Series definitions. */
+    series: SeriesConfig[];
+    /** Chart height in px (default 350). Use `'auto'` to fill container height. */
+    height?: number | 'auto';
+    /** Ratio above which the dominant segment triggers a scale break (default 5). */
+    breakThreshold?: number;
+    /** Minimum pixel height for non-dominant segments so they remain visible (default 32). */
+    minSegmentPx?: number;
+    /** Value formatter for labels & tooltip (default `String`). */
+    formatValue?: (value: number) => string;
+    /** Additional className on the root wrapper. */
+    className?: string;
+}
+
+declare function ScaleBreakBarChart({ data, series, height, breakThreshold, formatValue, className, }: ScaleBreakBarChartProps): react_jsx_runtime.JSX.Element;
+
+export { ScaleBreakBarChart, type ScaleBreakBarChartProps, type ScaleBreakDataPoint, type SeriesConfig };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Scale-Break Bar Chart — Type definitions
+ *
+ * A custom SVG chart that compresses dominant values with zigzag break
+ * indicators so small values remain clearly visible alongside large ones.
+ * Supports both stacked and grouped (side-by-side) bar modes.
+ */
+/** A single data point on the x-axis (e.g., one month). */
+interface ScaleBreakDataPoint {
+    /** Display label for the x-axis (e.g. "January"). */
+    name: string;
+    /** Dynamic numeric keys matching `SeriesConfig.dataKey`. */
+    [key: string]: string | number;
+}
+/** Configuration for one segment / series in the bar chart. */
+interface SeriesConfig {
+    /** Property name on the data point to read the value from. */
+    dataKey: string;
+    /** Human-readable label shown in legend & tooltip. */
+    label: string;
+    /** Fill colour (hex or CSS). */
+    color: string;
+}
+/** Props accepted by the `<ScaleBreakBarChart>` component. */
+interface ScaleBreakBarChartProps {
+    /** Array of data points; one per bar group. */
+    data: ScaleBreakDataPoint[];
+    /** Series definitions. */
+    series: SeriesConfig[];
+    /** Chart height in px (default 350). Use `'auto'` to fill container height. */
+    height?: number | 'auto';
+    /** Ratio above which the dominant segment triggers a scale break (default 5). */
+    breakThreshold?: number;
+    /** Minimum pixel height for non-dominant segments so they remain visible (default 32). */
+    minSegmentPx?: number;
+    /** Value formatter for labels & tooltip (default `String`). */
+    formatValue?: (value: number) => string;
+    /** Additional className on the root wrapper. */
+    className?: string;
+}
+
+declare function ScaleBreakBarChart({ data, series, height, breakThreshold, formatValue, className, }: ScaleBreakBarChartProps): react_jsx_runtime.JSX.Element;
+
+export { ScaleBreakBarChart, type ScaleBreakBarChartProps, type ScaleBreakDataPoint, type SeriesConfig };