@octanejs/visx 0.1.0

package/src/theme/provider/ThemeScope.tsrx

@@ -0,0 +1,58 @@
+import { Fragment, createElement } from 'octane';
+import type { JSX as ReactJSX, ReactNode } from 'react';
+import createThemeStyle from '../tokens/style';
+import type { CSSVarStyle, VisxThemeDefinition } from '../tokens/types';
+import warn from '../utils/warn';
+
+export type ThemeScopeElement = keyof ReactJSX.IntrinsicElements;
+
+interface BaseThemeScopeProps {
+	className?: string;
+	style?: CSSVarStyle;
+	children: ReactNode;
+}
+
+interface AutoThemeScopeProps extends BaseThemeScopeProps {
+	theme?: 'auto';
+	as?: ThemeScopeElement | false;
+}
+
+interface EmittingThemeScopeProps extends BaseThemeScopeProps {
+	theme: 'light' | 'dark' | VisxThemeDefinition;
+	as?: ThemeScopeElement;
+}
+
+export type ThemeScopeProps = AutoThemeScopeProps | EmittingThemeScopeProps;
+
+function warnInvalidFalseElement() {
+	warn('[@octanejs/visx/theme] ThemeScope requires a wrapper element for non-auto themes.');
+}
+
+export default function ThemeScope({
+	as,
+	children,
+	className,
+	style,
+	theme = 'auto',
+}: ThemeScopeProps) {
+	if (theme === 'auto') {
+		if (as === false) {
+			return createElement(Fragment, null, children);
+		}
+
+		const Element = as ?? 'div';
+
+		return createElement(Element, { className, style }, children);
+	}
+
+	const Element =
+		as === false ? 'div' : as ?? 'div';
+
+	if (as === false) {
+		warnInvalidFalseElement();
+	}
+
+	const generatedStyle = createThemeStyle(theme);
+
+	return createElement(Element, { className, style: { ...generatedStyle, ...style } }, children);
+}

package/src/theme/provider/ThemeScope.tsrx.d.ts

@@ -0,0 +1,23 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { JSX as ReactJSX, ReactNode } from 'react';
+import type { CSSVarStyle, VisxThemeDefinition } from '../tokens/types';
+export type ThemeScopeElement = keyof ReactJSX.IntrinsicElements;
+interface BaseThemeScopeProps {
+    className?: string;
+    style?: CSSVarStyle;
+    children: ReactNode;
+}
+interface AutoThemeScopeProps extends BaseThemeScopeProps {
+    theme?: 'auto';
+    as?: ThemeScopeElement | false;
+}
+interface EmittingThemeScopeProps extends BaseThemeScopeProps {
+    theme: 'light' | 'dark' | VisxThemeDefinition;
+    as?: ThemeScopeElement;
+}
+export type ThemeScopeProps = AutoThemeScopeProps | EmittingThemeScopeProps;
+export default function ThemeScope({ as, children, className, style, theme, }: ThemeScopeProps): import("octane").ElementDescriptor<null> | import("octane").ElementDescriptor<{
+    className: string | undefined;
+    style: CSSVarStyle | undefined;
+}>;
+export {};

package/src/theme/provider/defineTheme.ts

@@ -0,0 +1,67 @@
+import lightTheme from '../tokens/light';
+import normalizeCategoricalColors from '../tokens/categorical';
+import type { CategoricalColorScale, VisxThemeDefinition } from '../tokens/types';
+
+type DeepPartialObject<T> = {
+	[K in keyof T]?: T[K] extends readonly string[]
+		? readonly string[]
+		: T[K] extends object
+			? DeepPartialObject<T[K]>
+			: T[K];
+};
+
+export type ThemeOverrides = DeepPartialObject<VisxThemeDefinition>;
+
+function normalizeCategoricalOverride(
+	override: readonly string[] | undefined,
+	base: CategoricalColorScale,
+): CategoricalColorScale {
+	const normalize = (colors: readonly string[]) =>
+		normalizeCategoricalColors(colors) as unknown as CategoricalColorScale;
+
+	if (override == null) {
+		return normalize(base);
+	}
+
+	const colorCount = Math.max(override.length, base.length);
+	const merged = Array.from({ length: colorCount }, (_, index) => override[index] ?? base[index]);
+
+	return normalize(merged);
+}
+
+export default function defineTheme(
+	overrides: ThemeOverrides,
+	base: VisxThemeDefinition = lightTheme,
+): VisxThemeDefinition {
+	return {
+		name: overrides.name ?? base.name,
+		colors: {
+			...base.colors,
+			...overrides.colors,
+			categorical: normalizeCategoricalOverride(
+				overrides.colors?.categorical,
+				base.colors.categorical,
+			),
+		},
+		typography: {
+			...base.typography,
+			...overrides.typography,
+		},
+		axis: {
+			...base.axis,
+			...overrides.axis,
+		},
+		grid: {
+			...base.grid,
+			...overrides.grid,
+		},
+		spacing: {
+			...base.spacing,
+			...overrides.spacing,
+			margin: {
+				...base.spacing.margin,
+				...overrides.spacing?.margin,
+			},
+		},
+	};
+}

package/src/theme/react/ThemeContext.tsrx

@@ -0,0 +1,7 @@
+import { createContext } from 'octane';
+import createRuntimeTheme from '../runtime/createRuntimeTheme';
+import type { VisxThemeRuntime } from '../tokens/types';
+
+const ThemeContext = createContext<VisxThemeRuntime>(createRuntimeTheme('auto'));
+
+export default ThemeContext

package/src/theme/react/ThemeContext.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { VisxThemeRuntime } from '../tokens/types';
+declare const ThemeContext: import("octane").Context<VisxThemeRuntime>;
+export default ThemeContext;

package/src/theme/react/ThemeProvider.tsrx

@@ -0,0 +1,14 @@
+import ThemeScope from '../provider/ThemeScope.tsrx';
+import type { ThemeScopeProps } from '../provider/ThemeScope.tsrx';
+import createRuntimeTheme from '../runtime/createRuntimeTheme';
+import ThemeContext from './ThemeContext.tsrx';
+
+export type ThemeProviderProps = ThemeScopeProps;
+
+export default function ThemeProvider(props: ThemeProviderProps) {
+	const runtimeTheme = createRuntimeTheme(props.theme ?? 'auto');
+
+	return <ThemeContext.Provider value={runtimeTheme}>
+		<ThemeScope {...props} />
+	</ThemeContext.Provider>;
+}

package/src/theme/react/ThemeProvider.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ThemeScopeProps } from '../provider/ThemeScope.tsrx';
+export type ThemeProviderProps = ThemeScopeProps;
+export default function ThemeProvider(props: ThemeProviderProps): import("react").JSX.Element;

package/src/theme/react/categoricalColor.ts

@@ -0,0 +1,32 @@
+import warn from './warn';
+
+function wrapIndex(index: number, length: number) {
+	return ((index % length) + length) % length;
+}
+
+export function normalizeCategoricalIndex(index: number, source: string) {
+	if (!Number.isFinite(index)) {
+		warn(
+			`[@octanejs/visx/theme] ${source} received a non-finite categorical color index; using index 0.`,
+		);
+		return 0;
+	}
+
+	const integerIndex = Math.trunc(index);
+
+	if (integerIndex !== index) {
+		warn(
+			`[@octanejs/visx/theme] ${source} received a fractional categorical color index; truncating to ${integerIndex}.`,
+		);
+	}
+
+	return integerIndex;
+}
+
+export function getCategoricalColor(colors: readonly string[], index: number) {
+	if (colors.length === 0) {
+		return '';
+	}
+
+	return colors[wrapIndex(index, colors.length)];
+}

package/src/theme/react/index.ts

@@ -0,0 +1,29 @@
+'use client';
+
+export { default as ThemeProvider } from './ThemeProvider.tsrx';
+export { default as useAxisStyle } from './useAxisStyle.tsrx';
+export { default as useCategoricalScale } from './useCategoricalScale.tsrx';
+export { default as useChartConfig } from './useChartConfig.tsrx';
+export { default as useColor } from './useColor.tsrx';
+export { default as useColorScale } from './useColorScale.tsrx';
+export { default as useGridStyle } from './useGridStyle.tsrx';
+export { default as useTheme } from './useTheme.tsrx';
+
+export type {
+	AxisOrientation,
+	AxisStyleProps,
+	AxisTextAnchor,
+	AxisTextStyleProps,
+	AxisVerticalAnchor,
+} from './useAxisStyle.tsrx';
+export type { CategoricalColorAccessor } from './useCategoricalScale.tsrx';
+export type {
+	ResolvedSeries,
+	UseChartConfigOptions,
+	UseChartConfigResult,
+} from './useChartConfig.tsrx';
+export type { ColorTokenName } from './useColor.tsrx';
+export type { ColorScaleAccessor, UseColorScaleOptions } from './useColorScale.tsrx';
+export type { GridStyleProps } from './useGridStyle.tsrx';
+export type { ThemeProviderProps } from './ThemeProvider.tsrx';
+export type { ChartConfig, ChartSeriesConfig } from '../tokens/types';

package/src/theme/react/useAxisStyle.tsrx

@@ -0,0 +1,100 @@
+import useTheme from './useTheme.tsrx';
+
+export type AxisOrientation = 'top' | 'right' | 'bottom' | 'left';
+export type AxisTextAnchor = 'start' | 'middle' | 'end';
+export type AxisVerticalAnchor = 'start' | 'middle' | 'end';
+
+export type AxisTextStyleProps = {
+	dx?: string | number;
+	dy?: string | number;
+	fill: string;
+	fontFamily: string;
+	fontSize: number;
+	textAnchor: AxisTextAnchor;
+	verticalAnchor?: AxisVerticalAnchor;
+};
+
+export type AxisStyleProps = {
+	labelOffset?: number;
+	stroke: string;
+	strokeWidth: number;
+	tickLength: number;
+	tickStroke: string;
+	tickLabelProps: AxisTextStyleProps;
+	labelProps: AxisTextStyleProps;
+};
+
+const tickLabelPositionByOrientation: Record<AxisOrientation, Pick<AxisTextStyleProps, | 'dx'
+| 'dy'
+| 'textAnchor'>> = {
+	bottom: {
+		dy: '0.25em',
+		textAnchor: 'middle',
+	},
+	top: {
+		dy: '-0.75em',
+		textAnchor: 'middle',
+	},
+	left: {
+		dx: '-0.25em',
+		dy: '0.25em',
+		textAnchor: 'end',
+	},
+	right: {
+		dx: '0.25em',
+		dy: '0.25em',
+		textAnchor: 'start',
+	},
+};
+
+const labelPositionByOrientation: Record<AxisOrientation, Pick<AxisTextStyleProps, | 'dx'
+| 'dy'
+| 'textAnchor'>> = {
+	bottom: {
+		dy: '-0.25em',
+		textAnchor: 'middle',
+	},
+	top: {
+		dy: '-0.25em',
+		textAnchor: 'middle',
+	},
+	left: {
+		dx: '-1.25em',
+		textAnchor: 'middle',
+	},
+	right: {
+		dx: '1.25em',
+		textAnchor: 'middle',
+	},
+};
+
+const labelOffsetByOrientation: Record<AxisOrientation, number> = {
+	bottom: 22,
+	top: 22,
+	left: 20,
+	right: 20,
+};
+
+export default function useAxisStyle(orientation: AxisOrientation): AxisStyleProps {
+	const theme = useTheme();
+
+	return {
+		labelOffset: labelOffsetByOrientation[orientation],
+		stroke: theme.colors.axisStroke,
+		strokeWidth: theme.axis.strokeWidth,
+		tickLength: theme.axis.tickLength,
+		tickStroke: theme.colors.axisTickStroke,
+		tickLabelProps: {
+			...tickLabelPositionByOrientation[orientation],
+			fill: theme.colors.textMuted,
+			fontFamily: theme.typography.fontFamily,
+			fontSize: theme.typography.fontSizeTick,
+		},
+		labelProps: {
+			...labelPositionByOrientation[orientation],
+			fill: theme.colors.textPrimary,
+			fontFamily: theme.typography.fontFamily,
+			fontSize: theme.typography.fontSizeLabel,
+		},
+	};
+}

package/src/theme/react/useAxisStyle.tsrx.d.ts

@@ -0,0 +1,23 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export type AxisOrientation = 'top' | 'right' | 'bottom' | 'left';
+export type AxisTextAnchor = 'start' | 'middle' | 'end';
+export type AxisVerticalAnchor = 'start' | 'middle' | 'end';
+export type AxisTextStyleProps = {
+    dx?: string | number;
+    dy?: string | number;
+    fill: string;
+    fontFamily: string;
+    fontSize: number;
+    textAnchor: AxisTextAnchor;
+    verticalAnchor?: AxisVerticalAnchor;
+};
+export type AxisStyleProps = {
+    labelOffset?: number;
+    stroke: string;
+    strokeWidth: number;
+    tickLength: number;
+    tickStroke: string;
+    tickLabelProps: AxisTextStyleProps;
+    labelProps: AxisTextStyleProps;
+};
+export default function useAxisStyle(orientation: AxisOrientation): AxisStyleProps;

package/src/theme/react/useCategoricalScale.tsrx

@@ -0,0 +1,23 @@
+import { getCategoricalColor } from './categoricalColor';
+import useTheme from './useTheme.tsrx';
+import warn from './warn';
+
+export type CategoricalColorAccessor<Domain extends readonly string[]> =
+	(key: Domain[number]) => string;
+
+export default function useCategoricalScale<Domain extends readonly string[]>(domain: Domain): CategoricalColorAccessor<Domain> {
+	const theme = useTheme();
+
+	return (key) => {
+		const index = domain.indexOf(key);
+
+		if (index < 0) {
+			warn(
+				`[@octanejs/visx/theme] useCategoricalScale received "${key}" outside its domain; using index 0.`,
+			);
+			return getCategoricalColor(theme.colors.categorical, 0);
+		}
+
+		return getCategoricalColor(theme.colors.categorical, index);
+	};
+}

package/src/theme/react/useCategoricalScale.tsrx.d.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export type CategoricalColorAccessor<Domain extends readonly string[]> = (key: Domain[number]) => string;
+export default function useCategoricalScale<Domain extends readonly string[]>(domain: Domain): CategoricalColorAccessor<Domain>;

package/src/theme/react/useChartConfig.tsrx

@@ -0,0 +1,108 @@
+import type { ChartConfig, ChartSeriesConfig } from '../tokens/types';
+import { getCategoricalColor } from './categoricalColor';
+import useTheme from './useTheme.tsrx';
+import warn from './warn';
+
+export type ResolvedSeries<K extends string = string> = ChartSeriesConfig & {
+		key: K;
+		color: string;
+	};
+
+export type UseChartConfigOptions<K extends string = string> = {
+	order?: readonly K[];
+};
+
+export type UseChartConfigResult<K extends string = string> = {
+	series: ResolvedSeries<K>[];
+	getColor: (key: K) => string;
+	getLabel: (key: K) => string;
+};
+
+const integerLikeKeyPattern = /^(0|[1-9]\d*)$/;
+
+function hasOwnKey<K extends string>(
+	config: ChartConfig<K>,
+	key: string,
+): key is K {
+	return Object.prototype.hasOwnProperty.call(config, key);
+}
+
+function warnIntegerLikeKeys(keys: readonly string[]) {
+	const integerLikeKeys = keys.filter((key) => integerLikeKeyPattern.test(key));
+
+	if (integerLikeKeys.length > 0) {
+		warn(
+			`[@octanejs/visx/theme] useChartConfig received integer-like config keys (${integerLikeKeys.join(
+				', ',
+			)}) without an explicit order; pass options.order to make series order stable.`,
+		);
+	}
+}
+
+function resolveSeriesOrder<K extends string>(
+	config: ChartConfig<K>,
+	order: readonly K[] | undefined,
+) {
+	const configKeys = Object.keys(config) as K[];
+
+	if (order == null) {
+		warnIntegerLikeKeys(configKeys);
+		return configKeys;
+	}
+
+	const seen = new Set<string>();
+	const resolvedOrder: K[] = [];
+
+	order.forEach((key) => {
+		if (seen.has(key)) {
+			warn(`[@octanejs/visx/theme] useChartConfig ignored duplicate order key "${key}".`);
+			return;
+		}
+
+		seen.add(key);
+
+		if (!hasOwnKey(config, key)) {
+			warn(
+				`[@octanejs/visx/theme] useChartConfig ignored order key "${key}" because it is not present in config.`,
+			);
+			return;
+		}
+
+		resolvedOrder.push(key);
+	});
+
+	configKeys.forEach((key) => {
+		if (!seen.has(key)) {
+			warn(
+				`[@octanejs/visx/theme] useChartConfig omitted config key "${key}" because it is absent from options.order.`,
+			);
+		}
+	});
+
+	return resolvedOrder;
+}
+
+export default function useChartConfig<K extends string>(
+	config: ChartConfig<K>,
+	options: UseChartConfigOptions<K> = {},
+): UseChartConfigResult<K> {
+	const theme = useTheme();
+	const resolvedOrder = resolveSeriesOrder(config, options.order);
+	const series = resolvedOrder.map(
+		(key, index) => ({
+			...config[key],
+			key,
+			color: config[key].color ?? getCategoricalColor(theme.colors.categorical, index),
+		}),
+	);
+	const seriesByKey = new Map<string, ResolvedSeries<K>>(series.map(
+		(resolvedSeries) => [resolvedSeries.key, resolvedSeries],
+	));
+
+	return {
+		series,
+		getColor: (key) => seriesByKey.get(key)?.color ??
+			getCategoricalColor(theme.colors.categorical, 0),
+		getLabel: (key) => seriesByKey.get(key)?.label ?? key,
+	};
+}

package/src/theme/react/useChartConfig.tsrx.d.ts

@@ -0,0 +1,15 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ChartConfig, ChartSeriesConfig } from '../tokens/types';
+export type ResolvedSeries<K extends string = string> = ChartSeriesConfig & {
+    key: K;
+    color: string;
+};
+export type UseChartConfigOptions<K extends string = string> = {
+    order?: readonly K[];
+};
+export type UseChartConfigResult<K extends string = string> = {
+    series: ResolvedSeries<K>[];
+    getColor: (key: K) => string;
+    getLabel: (key: K) => string;
+};
+export default function useChartConfig<K extends string>(config: ChartConfig<K>, options?: UseChartConfigOptions<K>): UseChartConfigResult<K>;

package/src/theme/react/useColor.tsrx

@@ -0,0 +1,18 @@
+import type { VisxThemeRuntime } from '../tokens/types';
+import { getCategoricalColor, normalizeCategoricalIndex } from './categoricalColor';
+import useTheme from './useTheme.tsrx';
+
+export type ColorTokenName = Exclude<keyof VisxThemeRuntime['colors'], 'categorical'>;
+
+export default function useColor(color: ColorTokenName | number): string {
+	const theme = useTheme();
+
+	if (typeof color === 'number') {
+		return getCategoricalColor(
+			theme.colors.categorical,
+			normalizeCategoricalIndex(color, 'useColor'),
+		);
+	}
+
+	return theme.colors[color];
+}

package/src/theme/react/useColor.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { VisxThemeRuntime } from '../tokens/types';
+export type ColorTokenName = Exclude<keyof VisxThemeRuntime['colors'], 'categorical'>;
+export default function useColor(color: ColorTokenName | number): string;

package/src/theme/react/useColorScale.tsrx

@@ -0,0 +1,39 @@
+import { useStructuralMemo } from '@octanejs/visx/kernel';
+import { useMemo } from 'octane';
+import { getCategoricalColor } from './categoricalColor';
+import useTheme from './useTheme.tsrx';
+import warn from './warn';
+
+export type ColorScaleAccessor<Domain extends readonly string[]> = (key: Domain[number]) => string;
+
+export type UseColorScaleOptions = {
+	/** Optional explicit color range. Falls back to the active theme's categorical palette. */
+	range?: readonly string[];
+};
+
+export default function useColorScale<Domain extends readonly string[]>(
+	domain: Domain,
+	{ range }: UseColorScaleOptions = {},
+): ColorScaleAccessor<Domain> {
+	const theme = useTheme();
+	const stableDomain = useStructuralMemo(domain, 1);
+	const stableRange = useStructuralMemo(range, 1);
+	const fallbackColors = theme.colors.categorical;
+	const colors = stableRange ?? fallbackColors;
+
+	return useMemo(
+		() => (key) => {
+			const index = stableDomain.indexOf(key);
+
+			if (index < 0) {
+				warn(
+					`[@octanejs/visx/theme] useColorScale received "${key}" outside its domain; using index 0.`,
+				);
+				return colors[0] ?? getCategoricalColor(fallbackColors, 0);
+			}
+
+			return colors[index % colors.length] ?? getCategoricalColor(fallbackColors, index);
+		},
+		[colors, fallbackColors, stableDomain],
+	);
+}

package/src/theme/react/useColorScale.tsrx.d.ts

@@ -0,0 +1,7 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export type ColorScaleAccessor<Domain extends readonly string[]> = (key: Domain[number]) => string;
+export type UseColorScaleOptions = {
+    /** Optional explicit color range. Falls back to the active theme's categorical palette. */
+    range?: readonly string[];
+};
+export default function useColorScale<Domain extends readonly string[]>(domain: Domain, { range }?: UseColorScaleOptions): ColorScaleAccessor<Domain>;

package/src/theme/react/useGridStyle.tsrx

@@ -0,0 +1,15 @@
+import useTheme from './useTheme.tsrx';
+
+export type GridStyleProps = {
+	stroke: string;
+	strokeWidth: number;
+};
+
+export default function useGridStyle(): GridStyleProps {
+	const theme = useTheme();
+
+	return {
+		stroke: theme.colors.gridStroke,
+		strokeWidth: theme.grid.strokeWidth,
+	};
+}

package/src/theme/react/useGridStyle.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export type GridStyleProps = {
+    stroke: string;
+    strokeWidth: number;
+};
+export default function useGridStyle(): GridStyleProps;

package/src/theme/react/useTheme.tsrx

@@ -0,0 +1,7 @@
+import { useContext } from 'octane';
+import ThemeContext from './ThemeContext.tsrx';
+import type { VisxThemeRuntime } from '../tokens/types';
+
+export default function useTheme() {
+	return useContext(ThemeContext) as VisxThemeRuntime;
+}

package/src/theme/react/useTheme.tsrx.d.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { VisxThemeRuntime } from '../tokens/types';
+export default function useTheme(): VisxThemeRuntime;

package/src/theme/react/warn.ts

@@ -0,0 +1,3 @@
+import warn from '../utils/warn';
+
+export default warn;