@octane-xplat/charts 0.0.0-stage → 0.10.0

package/src/core/svg.ts

@@ -0,0 +1,84 @@
+import type { Mark } from './marks'
+import type { PlotBox } from './scales'
+
+/** Mark[] → one `<svg>` markup string. Emits only the androidsvg ∩ SVGKit
+ *  subset: `<svg>`/`<g>` structure, path/rect/circle/line shapes, solid fills
+ *  and strokes, `translate` transforms, opacity attributes. Never `<text>`,
+ *  filters, masks, patterns, or gradients — labels are real elements in the
+ *  leaf overlay (docs/notes/primitive-notes.md). */
+
+function num(v: number): string {
+	if (!Number.isFinite(v)) {
+		return '0'
+	}
+
+	return Number.isInteger(v) ? String(v) : String(+v.toFixed(2))
+}
+
+function esc(v: string): string {
+	return v
+		.replaceAll('&', '&amp;')
+		.replaceAll('"', '&quot;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+}
+
+function paintAttrs(m: Mark): string {
+	let out = ''
+	if (m.fill !== undefined) {
+		out += ` fill="${esc(m.fill)}"`
+	}
+
+	if (m.fillOpacity !== undefined) {
+		out += ` fill-opacity="${num(m.fillOpacity)}"`
+	}
+
+	if (m.stroke !== undefined) {
+		out += ` stroke="${esc(m.stroke)}"`
+	}
+
+	if (m.strokeOpacity !== undefined) {
+		out += ` stroke-opacity="${num(m.strokeOpacity)}"`
+	}
+
+	if (m.strokeWidth !== undefined) {
+		out += ` stroke-width="${num(m.strokeWidth)}"`
+	}
+
+	if (m.strokeLinecap !== undefined) {
+		out += ` stroke-linecap="${m.strokeLinecap}"`
+	}
+
+	if (m.transform !== undefined) {
+		out += ` transform="${esc(m.transform)}"`
+	}
+
+	return out
+}
+
+function markXml(m: Mark): string {
+	switch (m.kind) {
+		case 'path':
+			return `<path d="${esc(m.d)}"${paintAttrs(m)}/>`
+		case 'rect':
+			return `<rect x="${num(m.x)}" y="${num(m.y)}" width="${num(m.width)}" height="${num(m.height)}"${paintAttrs(m)}/>`
+		case 'circle':
+			return `<circle cx="${num(m.cx)}" cy="${num(m.cy)}" r="${num(m.r)}"${paintAttrs(m)}/>`
+		case 'line':
+			return `<line x1="${num(m.x1)}" y1="${num(m.y1)}" x2="${num(m.x2)}" y2="${num(m.y2)}"${paintAttrs(m)}/>`
+	}
+}
+
+/** Chart marks are plot-space; axis rules are chart-space. Paint order:
+ *  gridlines under the translated marks group, frame (spine + stubs) over. */
+export function svgDocument(
+	marks: Mark[],
+	grid: Mark[],
+	frame: Mark[],
+	plot: PlotBox,
+	width: number,
+	height: number,
+): string {
+	const body = `${grid.map(markXml).join('')}<g transform="translate(${num(plot.x)} ${num(plot.y)})">${marks.map(markXml).join('')}</g>${frame.map(markXml).join('')}`
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${num(width)} ${num(height)}" width="${num(width)}" height="${num(height)}">${body}</svg>`
+}

package/src/index.macos.ts

@@ -0,0 +1,12 @@
+// Platform barrels — explicit .tsrx leaf specifiers (moduleSuffixes don't
+// reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
+export { Chart } from './Chart.macos.tsrx'
+export type {
+	AxisSpec,
+	ChartDatum,
+	ChartHit,
+	ChartMargin,
+	ChartProps,
+	ChartType,
+	SeriesSpec,
+} from './props'

package/src/index.ts

@@ -0,0 +1,12 @@
+// Platform barrels — explicit .tsrx leaf specifiers (moduleSuffixes don't
+// reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
+export { Chart } from './Chart.tsrx'
+export type {
+	AxisSpec,
+	ChartDatum,
+	ChartHit,
+	ChartMargin,
+	ChartProps,
+	ChartType,
+	SeriesSpec,
+} from './props'

package/src/index.web.ts

@@ -0,0 +1,12 @@
+// Platform barrels — explicit .tsrx leaf specifiers (moduleSuffixes don't
+// reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
+export { Chart } from './Chart.web.tsrx'
+export type {
+	AxisSpec,
+	ChartDatum,
+	ChartHit,
+	ChartMargin,
+	ChartProps,
+	ChartType,
+	SeriesSpec,
+} from './props'

package/src/props.ts

@@ -0,0 +1,90 @@
+/** Shared prop/type contract for @octane-xplat/charts — the single source for
+ *  both platform leaves and the published .d.ts. No imports: the shared
+ *  contract stays dependency-free and platform-agnostic. */
+
+export type ChartType = 'line' | 'area' | 'bar' | 'pie' | 'scatter'
+
+export interface ChartDatum {
+	/** Bar/pie: the category label. Line/area/scatter: number or Date. */
+	x: number | string | Date
+	y: number
+	/** Per-datum color override — wins over the series color (pie slices,
+	 *  scatter points, individual bars). */
+	color?: string
+}
+
+export interface SeriesSpec {
+	name: string
+	/** Series color — stroke for line/scatter, fill for area/bar. Falls back
+	 *  to the built-in palette by series index. */
+	color?: string
+	values: ChartDatum[]
+}
+
+export interface ChartMargin {
+	top?: number
+	right?: number
+	bottom?: number
+	left?: number
+}
+
+/** Axis decomposition — gridline, tick stub, and label toggle independently
+ *  (Swift Charts `AxisMarks` shape). Labels render as real positioned
+ *  elements in the overlay, never `<text>` in markup. */
+export interface AxisSpec {
+	/** Tick labels in the margin. Default true. */
+	labels?: boolean
+	/** Tick stubs on the axis spine. Default true. */
+	ticks?: boolean
+	/** Gridlines across the plot area. Default false. */
+	grid?: boolean
+	/** Desired tick count hint — a hint, not a guarantee. */
+	tickCount?: number
+	/** Tick label formatter; receives the domain value. */
+	format?: (value: number | string | Date) => string
+}
+
+/** A resolved datum reference — `x`/`y` are the datum's values, not pixels. */
+export interface ChartHit {
+	series: number
+	index: number
+	x: number | string | Date
+	y: number
+}
+
+export interface ChartProps {
+	type: ChartType
+	data: SeriesSpec[]
+	/** Explicit size in px (web) / dips (native). Without `height`, the leaf
+	 *  fills its parent or derives height from `aspectRatio`. */
+	width?: number
+	height?: number
+	/** width/height ratio used when `height` is unset. */
+	aspectRatio?: number
+	/** Space reserved inside the chart box for axis labels — labels live in
+	 *  the margin band, the plot in the remainder. Defaults reserve room for
+	 *  x labels (bottom) and y labels (left) when those axes show labels. */
+	margin?: ChartMargin
+	/** Bar only: stack series instead of grouping side by side. */
+	stacked?: boolean
+	/** Pie only: 0–<1 inner-radius fraction — any positive value renders a
+	 *  donut. */
+	innerRadiusRatio?: number
+	xAxis?: AxisSpec
+	yAxis?: AxisSpec
+	/** Legend row of series swatches. `true` = 'bottom'. Pie legends list
+	 *  slices, not series. */
+	legend?: boolean | 'top' | 'bottom'
+	/** Show a value callout at the scrub/hover cursor. */
+	tooltip?: boolean
+	/** Show a snap-to-x cursor rule while scrubbing. */
+	crosshair?: boolean
+	/** Tap/click a datum. */
+	onPress?: (hit: ChartHit) => void
+	/** Scrub position changes — `null` when the gesture ends or leaves. */
+	onScrub?: (hit: ChartHit | null) => void
+	accessibilityLabel?: string
+	className?: any
+	style?: any
+	id?: string
+}

package/src/svg-image.macos.ts

@@ -0,0 +1,34 @@
+// Kept local to avoid coupling the charts leaf to private UI helpers.
+// Foundation's public ObjC API is available through the AppKit metadata bridge.
+declare const NSString: {
+	stringWithString(value: string): {
+		dataUsingEncoding(encoding: number): {
+			base64EncodedStringWithOptions(options: number): string
+		} | null
+	}
+}
+
+export function svgDataUri(markup: string): string {
+	const data = NSString.stringWithString(markup).dataUsingEncoding(4) // NSUTF8StringEncoding
+	if (!data) {
+		throw new Error('Unable to encode SVG as UTF-8')
+	}
+
+	return `data:image/svg+xml;base64,${data.base64EncodedStringWithOptions(0)}`
+}
+
+/** Normalize bundled markup and SVG data URIs for AppKit's image host. */
+export function appKitImageSource(src: string): string {
+	if (src.trimStart().startsWith('<svg') || src.trimStart().startsWith('<?xml')) {
+		return svgDataUri(src)
+	}
+
+	if (
+		/^data:image\/svg\+xml[;,]/i.test(src) &&
+		!src.slice(0, src.indexOf(',')).endsWith(';base64')
+	) {
+		return svgDataUri(decodeURIComponent(src.slice(src.indexOf(',') + 1)))
+	}
+
+	return src
+}

package/types/index.d.ts

@@ -0,0 +1,17 @@
+// Boundary types for @octane-xplat/charts — the mechanical wrapper over
+// props.ts (tsrx-tsc can't emit .tsrx declarations; see ui/types/index.d.ts
+// for the same pattern).
+import type { UniversalComponent } from 'octane/universal'
+import type { ChartProps } from './props.js'
+
+export declare const Chart: UniversalComponent<ChartProps>
+
+export type {
+	AxisSpec,
+	ChartDatum,
+	ChartHit,
+	ChartMargin,
+	ChartProps,
+	ChartType,
+	SeriesSpec,
+} from './props.js'

package/types/props.d.ts

@@ -0,0 +1,83 @@
+/** Shared prop/type contract for @octane-xplat/charts — the single source for
+ *  both platform leaves and the published .d.ts. No imports: the shared
+ *  contract stays dependency-free and platform-agnostic. */
+export type ChartType = 'line' | 'area' | 'bar' | 'pie' | 'scatter';
+export interface ChartDatum {
+    /** Bar/pie: the category label. Line/area/scatter: number or Date. */
+    x: number | string | Date;
+    y: number;
+    /** Per-datum color override — wins over the series color (pie slices,
+     *  scatter points, individual bars). */
+    color?: string;
+}
+export interface SeriesSpec {
+    name: string;
+    /** Series color — stroke for line/scatter, fill for area/bar. Falls back
+     *  to the built-in palette by series index. */
+    color?: string;
+    values: ChartDatum[];
+}
+export interface ChartMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Axis decomposition — gridline, tick stub, and label toggle independently
+ *  (Swift Charts `AxisMarks` shape). Labels render as real positioned
+ *  elements in the overlay, never `<text>` in markup. */
+export interface AxisSpec {
+    /** Tick labels in the margin. Default true. */
+    labels?: boolean;
+    /** Tick stubs on the axis spine. Default true. */
+    ticks?: boolean;
+    /** Gridlines across the plot area. Default false. */
+    grid?: boolean;
+    /** Desired tick count hint — a hint, not a guarantee. */
+    tickCount?: number;
+    /** Tick label formatter; receives the domain value. */
+    format?: (value: number | string | Date) => string;
+}
+/** A resolved datum reference — `x`/`y` are the datum's values, not pixels. */
+export interface ChartHit {
+    series: number;
+    index: number;
+    x: number | string | Date;
+    y: number;
+}
+export interface ChartProps {
+    type: ChartType;
+    data: SeriesSpec[];
+    /** Explicit size in px (web) / dips (native). Without `height`, the leaf
+     *  fills its parent or derives height from `aspectRatio`. */
+    width?: number;
+    height?: number;
+    /** width/height ratio used when `height` is unset. */
+    aspectRatio?: number;
+    /** Space reserved inside the chart box for axis labels — labels live in
+     *  the margin band, the plot in the remainder. Defaults reserve room for
+     *  x labels (bottom) and y labels (left) when those axes show labels. */
+    margin?: ChartMargin;
+    /** Bar only: stack series instead of grouping side by side. */
+    stacked?: boolean;
+    /** Pie only: 0–<1 inner-radius fraction — any positive value renders a
+     *  donut. */
+    innerRadiusRatio?: number;
+    xAxis?: AxisSpec;
+    yAxis?: AxisSpec;
+    /** Legend row of series swatches. `true` = 'bottom'. Pie legends list
+     *  slices, not series. */
+    legend?: boolean | 'top' | 'bottom';
+    /** Show a value callout at the scrub/hover cursor. */
+    tooltip?: boolean;
+    /** Show a snap-to-x cursor rule while scrubbing. */
+    crosshair?: boolean;
+    /** Tap/click a datum. */
+    onPress?: (hit: ChartHit) => void;
+    /** Scrub position changes — `null` when the gesture ends or leaves. */
+    onScrub?: (hit: ChartHit | null) => void;
+    accessibilityLabel?: string;
+    className?: any;
+    style?: any;
+    id?: string;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.