@kind-ui/charts 0.1.1 → 0.2.0

package/dist/chart-background-pattern.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+export type ChartBackgroundPatternRenderProps = {
+    size: number;
+    color: string;
+    /** Scope any custom SVG resources with this prefix; never use global IDs. */
+    idPrefix: string;
+};
+export type ChartBackgroundPatternDefinition = Readonly<{
+    render: (props: ChartBackgroundPatternRenderProps) => ReactNode;
+}>;
+/** Register a reusable, consumer-owned definition without mutating global state. */
+export declare function defineChartBackgroundPattern(render: ChartBackgroundPatternDefinition["render"]): ChartBackgroundPatternDefinition;
+export type ChartBackgroundPatternProps = {
+    pattern: "pinpoints" | "crossings" | "waves" | ChartBackgroundPatternDefinition;
+    /** CSS paint, including variables/system colors. Defaults to the chart grid token. */
+    color?: string;
+    /** Opacity in [0, 1], default 0.15. */
+    opacity?: number;
+    /** Positive tile size in SVG user units, default 16; does not stretch on resize. */
+    size?: number;
+};
+/** Decorative plot chrome, independent of series paint and interactions. */
+export declare function ChartBackgroundPattern({ pattern, color, opacity, size, }: ChartBackgroundPatternProps): import("react").JSX.Element | null;

package/dist/chart-background-pattern.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { DefaultZIndexes, usePlotArea, ZIndexLayer } from "recharts";
+/** Register a reusable, consumer-owned definition without mutating global state. */
+export function defineChartBackgroundPattern(render) {
+    if (typeof render !== "function")
+        throw new Error("defineChartBackgroundPattern requires a render function");
+    return Object.freeze({ render });
+}
+/** Decorative plot chrome, independent of series paint and interactions. */
+export function ChartBackgroundPattern({ pattern, color = "var(--kind-ui-chart-grid, CanvasText)", opacity = 0.15, size = 16, }) {
+    const area = usePlotArea();
+    const identity = useId();
+    const encodedId = Array.from(identity, (char) => char.codePointAt(0)?.toString(16)).join("-");
+    const id = `kind-ui-background-${encodedId}`;
+    if (!Number.isFinite(size) ||
+        size <= 0 ||
+        !Number.isFinite(opacity) ||
+        opacity < 0 ||
+        opacity > 1)
+        throw new Error("ChartBackgroundPattern requires positive finite size and opacity in [0, 1]");
+    if (typeof pattern === "string"
+        ? !["pinpoints", "crossings", "waves"].includes(pattern)
+        : !pattern || typeof pattern.render !== "function")
+        throw new Error("ChartBackgroundPattern requires a preset or a custom definition");
+    if (!area || area.width <= 0 || area.height <= 0)
+        return null;
+    const tile = typeof pattern !== "string" ? (pattern.render({ size, color, idPrefix: `${id}-custom` })) : pattern === "pinpoints" ? (_jsx("circle", { cx: size / 2, cy: size / 2, r: size / 16, fill: color })) : pattern === "crossings" ? (_jsx("path", { d: `M${size / 2} ${size / 4}v${size / 2} M${size / 4} ${size / 2}h${size / 2}`, stroke: color, fill: "none" })) : (_jsx("path", { d: `M0 ${size / 2}Q${size / 4} 0 ${size / 2} ${size / 2}T${size} ${size / 2}`, stroke: color, fill: "none" }));
+    return (_jsx(ZIndexLayer, { zIndex: DefaultZIndexes.grid - 1, children: _jsxs("g", { "data-kind-ui": "chart-background-pattern", "aria-hidden": "true", focusable: "false", pointerEvents: "none", clipPath: `url(#${id}-clip)`, opacity: opacity, children: [_jsxs("defs", { children: [_jsx("clipPath", { id: `${id}-clip`, children: _jsx("rect", { x: area.x, y: area.y, width: area.width, height: area.height }) }), _jsx("pattern", { id: id, x: area.x, y: area.y, width: size, height: size, patternUnits: "userSpaceOnUse", children: tile })] }), _jsx("rect", { x: area.x, y: area.y, width: area.width, height: area.height, fill: `url(#${id})` })] }) }));
+}

package/dist/chart-context.d.ts

@@ -1,10 +1,14 @@
-import type { SeriesConfig } from "./types.js";
+import type { ColorStops } from "./series-color.js";
+import type { ResolvedSeriesConfig } from "./series-label.js";
 type Visibility = {
     visibleSeries?: readonly string[];
     onVisibleSeriesChange?: (next: string[]) => void;
 };
 export type ChartContextValue = Visibility & {
-    config: SeriesConfig;
+    config: ResolvedSeriesConfig;
+    colorId: string;
+    colorStops: Readonly<Record<string, ColorStops>>;
+    paints: Readonly<Record<string, string>>;
 };
 export declare const ChartContext: import("react").Context<ChartContextValue | null>;
 export declare function useChart(): ChartContextValue;

package/dist/chart-interaction.d.ts

@@ -0,0 +1,94 @@
+import { type ReactNode, type SyntheticEvent } from "react";
+import type { SeriesConfig } from "./types.js";
+export type ChartIdentity = {
+    kind: "series" | "category" | "node";
+    key: string;
+};
+export type ChartInteractionEvent = SyntheticEvent<Element> | null;
+export type ChartInteractionRequest = {
+    identity: ChartIdentity | null;
+    source: "legend" | "mark" | "reset";
+    mode: "visibility" | "focus";
+    event: ChartInteractionEvent;
+};
+export type ChartInteractionConfig = {
+    /** Explicit binding between this Root's legend and participating chart identities. */
+    markActivation?: "none" | "matching-legend";
+    /** Settled data identities, including hidden items and zero values. */
+    eligibleKeys: readonly string[];
+    onBeforeInteraction?: (request: ChartInteractionRequest) => boolean | void;
+} & ({
+    kind: "series" | "category";
+    mode?: "visibility";
+    selected?: never;
+    defaultSelected?: never;
+    onSelectionChange?: never;
+} | ({
+    kind: "series" | "category" | "node";
+    mode: "focus";
+} & ({
+    selected?: undefined;
+    defaultSelected?: string | null;
+    onSelectionChange?: (next: string | null) => void;
+} | {
+    selected: string | null;
+    defaultSelected?: never;
+    onSelectionChange: (next: string | null) => void;
+})));
+export type ChartVisibilityProps = {
+    visibleSeries?: undefined;
+    defaultVisibleSeries?: undefined;
+    onVisibleSeriesChange?: never;
+} | {
+    visibleSeries?: undefined;
+    defaultVisibleSeries: readonly string[];
+    onVisibleSeriesChange?: (next: string[]) => void;
+} | {
+    visibleSeries: readonly string[];
+    defaultVisibleSeries?: never;
+    onVisibleSeriesChange?: (next: string[]) => void;
+};
+type Interaction = {
+    configured: boolean;
+    mode: "visibility" | "focus";
+    kind: ChartIdentity["kind"];
+    markActivation: boolean;
+    interactive: boolean;
+    selected: string | null;
+    eligible: readonly string[];
+    visible: readonly string[] | undefined;
+    activate: (identity: ChartIdentity, source: "legend" | "mark", event?: ChartInteractionEvent) => boolean;
+    reset: (event?: ChartInteractionEvent) => boolean;
+    announcement: {
+        text: string;
+        sequence: number;
+    };
+    registerUnavailable: (owner: string, key: string | undefined, unavailable: boolean) => () => void;
+    register: (owner: string, keys: readonly string[]) => () => void;
+};
+export declare function useOptionalChartInteraction(): Interaction | null;
+export declare function useChartInteraction(): {
+    reset: (event?: ChartInteractionEvent) => boolean;
+    configured: boolean;
+    mode: "visibility" | "focus";
+    kind: ChartIdentity["kind"];
+    markActivation: boolean;
+    interactive: boolean;
+    selected: string | null;
+    eligible: readonly string[];
+    visible: readonly string[] | undefined;
+    activate: (identity: ChartIdentity, source: "legend" | "mark", event?: ChartInteractionEvent) => boolean;
+};
+export declare function ChartInteractionProvider({ config, children, ...props }: {
+    interaction?: ChartInteractionConfig;
+} & ChartVisibilityProps & {
+    config: SeriesConfig;
+    children: (visible: readonly string[] | undefined, change: ((next: string[]) => void) | undefined) => ReactNode;
+}): import("react").JSX.Element;
+export declare function ChartInteractionStatus(): import("react").JSX.Element;
+/** Native series registration preserves hidden eligibility; callers may supply a stricter snapshot. */
+export declare function useInteractionRegistration(keys: readonly string[]): void;
+export declare function useInteractionAvailability(key: string | undefined, unavailable: boolean): void;
+/** Retain the focused data identity when native layout replaces a sector node. */
+export declare function useInteractionFocus(key: string | undefined, enabled: boolean): (node: SVGGElement | null) => void;
+export {};

package/dist/chart-interaction.js

@@ -0,0 +1,224 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { useOptionalEmphasisActions } from "./emphasis.js";
+const Context = createContext(null);
+/** The single state/action owner shared by native adapters and custom controls. */
+function useInteractionOwner() {
+    const value = use(Context);
+    if (!value)
+        throw new Error("useChartInteraction requires Root");
+    return value;
+}
+export function useOptionalChartInteraction() {
+    return use(Context);
+}
+export function useChartInteraction() {
+    const { register: _register, registerUnavailable: _registerUnavailable, announcement: _announcement, ...publicValue } = useInteractionOwner();
+    const emphasis = useOptionalEmphasisActions();
+    return {
+        ...publicValue,
+        reset: (event = null) => {
+            if (!publicValue.reset(event))
+                return false;
+            emphasis?.reset();
+            return true;
+        },
+    };
+}
+export function ChartInteractionProvider({ config, children, ...props }) {
+    const options = props.interaction;
+    const mode = options?.mode ?? "visibility";
+    const kind = options?.kind ?? "series";
+    const controlled = options?.selected;
+    const onChange = options?.onSelectionChange;
+    const initial = options?.defaultSelected;
+    const [internal, setInternal] = useState(initial ?? null);
+    const [internalVisible, setInternalVisible] = useState(props.defaultVisibleSeries);
+    const [unavailable, setUnavailable] = useState(() => new Map());
+    const registerUnavailable = useCallback((owner, key, blocked) => {
+        setUnavailable((old) => {
+            const next = new Map(old);
+            if (key !== undefined)
+                next.set(owner, { key, unavailable: blocked });
+            else
+                next.delete(owner);
+            return JSON.stringify([...old]) === JSON.stringify([...next]) ? old : next;
+        });
+        return () => setUnavailable((old) => {
+            if (!old.has(owner))
+                return old;
+            const next = new Map(old);
+            next.delete(owner);
+            return next;
+        });
+    }, []);
+    const [registrations, setRegistrations] = useState(() => new Map());
+    const [announcement, setAnnouncement] = useState({ text: "", sequence: 0 });
+    const ownership = useRef(mode === "focus" ? controlled !== undefined : undefined);
+    if (mode === "focus" && ownership.current === undefined)
+        ownership.current = controlled !== undefined;
+    if (options?.kind === "node" && mode !== "focus")
+        throw new Error("Node interaction only supports focus");
+    if (mode === "focus" && ownership.current !== (controlled !== undefined))
+        throw new Error("Root selection ownership cannot change during a mount");
+    if (controlled !== undefined && !onChange)
+        throw new Error("Controlled Root selection requires its change callback");
+    if (controlled !== undefined && initial !== undefined)
+        throw new Error("Root selection cannot be both controlled and defaulted");
+    if (props.visibleSeries !== undefined && props.defaultVisibleSeries !== undefined)
+        throw new Error("Root visibility cannot be both controlled and defaulted");
+    if (props.onVisibleSeriesChange &&
+        props.visibleSeries === undefined &&
+        props.defaultVisibleSeries === undefined)
+        throw new Error("Root requires visibleSeries or defaultVisibleSeries with onVisibleSeriesChange");
+    const register = useCallback((owner, keys) => {
+        setRegistrations((old) => {
+            if (JSON.stringify(old.get(owner)) === JSON.stringify(keys))
+                return old;
+            return new Map(old).set(owner, keys);
+        });
+        return () => setRegistrations((old) => {
+            if (!old.has(owner))
+                return old;
+            const next = new Map(old);
+            next.delete(owner);
+            return next;
+        });
+    }, []);
+    const eligible = useMemo(() => [
+        ...new Set(options?.eligibleKeys ??
+            (registrations.size ? [...registrations.values()].flat() : Object.keys(config))),
+    ].filter((key) => Object.hasOwn(config, key) &&
+        ![...unavailable.values()].some((item) => item.key === key &&
+            item.unavailable &&
+            [...unavailable.values()]
+                .filter((peer) => peer.key === key)
+                .every((peer) => peer.unavailable))), [options?.eligibleKeys, registrations, config, unavailable]);
+    const visible = props.visibleSeries ?? internalVisible;
+    const requested = controlled === undefined ? internal : controlled;
+    const selected = mode === "focus" &&
+        requested !== null &&
+        eligible.includes(requested) &&
+        (visible === undefined || visible.includes(requested))
+        ? requested
+        : null;
+    // Registration settles in layout effects; never turn an invalid controlled ID into an owner write.
+    useEffect(() => {
+        if (controlled === undefined && internal !== null && selected === null)
+            setInternal(null);
+    }, [controlled, internal, selected]);
+    const announce = (text) => setAnnouncement((old) => ({ text, sequence: old.sequence + 1 }));
+    const changeVisibility = (next) => {
+        if (props.visibleSeries === undefined)
+            setInternalVisible(next);
+        props.onVisibleSeriesChange?.(next);
+    };
+    const interactive = mode === "focus" ||
+        props.onVisibleSeriesChange !== undefined ||
+        props.defaultVisibleSeries !== undefined;
+    const permitted = (request) => {
+        if (request.event?.defaultPrevented)
+            return false;
+        const allowed = options?.onBeforeInteraction?.(request) !== false;
+        return allowed && !request.event?.defaultPrevented;
+    };
+    const change = (next) => {
+        if (controlled === undefined)
+            setInternal(next);
+        onChange?.(next);
+        announce(next === null ? "Highlight cleared." : `Highlighted ${config[next]?.label ?? next}.`);
+    };
+    const activate = (identity, source, event = null) => {
+        if (!interactive ||
+            identity.kind !== kind ||
+            !eligible.includes(identity.key) ||
+            (source === "mark" && options?.markActivation !== "matching-legend"))
+            return false;
+        if (!permitted({ identity, source, mode, event }))
+            return false;
+        if (mode === "focus") {
+            if (visible !== undefined && !visible.includes(identity.key))
+                return false;
+            change(selected === identity.key ? null : identity.key);
+        }
+        else {
+            const current = visible ?? eligible;
+            const hiding = current.includes(identity.key);
+            if (hiding && !eligible.some((key) => key !== identity.key && current.includes(key))) {
+                announce("At least one item must remain visible.");
+                return false;
+            }
+            changeVisibility(hiding ? current.filter((key) => key !== identity.key) : [...current, identity.key]);
+            announce(`${hiding ? "Hidden" : "Shown"} ${config[identity.key]?.label ?? identity.key}.`);
+        }
+        return true;
+    };
+    const reset = (event = null) => {
+        if (!permitted({ identity: null, source: "reset", mode, event }))
+            return false;
+        if (mode === "focus" && requested !== null)
+            change(null);
+        return true;
+    };
+    return (_jsx(Context, { value: {
+            configured: options !== undefined,
+            mode,
+            kind,
+            selected,
+            eligible,
+            visible,
+            interactive,
+            markActivation: options?.markActivation === "matching-legend",
+            activate,
+            reset,
+            register,
+            registerUnavailable,
+            announcement,
+        }, children: children(visible, interactive ? changeVisibility : undefined) }));
+}
+export function ChartInteractionStatus() {
+    const { announcement } = useInteractionOwner();
+    return (_jsx("span", { "aria-live": "polite", "aria-atomic": "true", "data-kind-ui": "chart-interaction-status", style: {
+            position: "absolute",
+            width: 1,
+            height: 1,
+            padding: 0,
+            margin: -1,
+            overflow: "hidden",
+            clipPath: "inset(50%)",
+            whiteSpace: "nowrap",
+            border: 0,
+        }, children: _jsx("span", { children: announcement.text }, announcement.sequence) }));
+}
+/** Native series registration preserves hidden eligibility; callers may supply a stricter snapshot. */
+export function useInteractionRegistration(keys) {
+    const { register } = useInteractionOwner();
+    const owner = useId();
+    const encoded = JSON.stringify(keys);
+    useLayoutEffect(() => register(owner, JSON.parse(encoded)), [register, owner, encoded]);
+}
+export function useInteractionAvailability(key, unavailable) {
+    const { registerUnavailable } = useInteractionOwner();
+    const owner = useId();
+    useLayoutEffect(() => registerUnavailable(owner, key, unavailable), [registerUnavailable, owner, key, unavailable]);
+}
+/** Retain the focused data identity when native layout replaces a sector node. */
+export function useInteractionFocus(key, enabled) {
+    const current = useRef(null);
+    return useCallback((node) => {
+        const previous = current.current;
+        if (!node && enabled && previous === document.activeElement) {
+            const root = previous?.closest('[data-kind-ui="chart"]');
+            const plot = previous?.closest('[data-kind-ui="line-frame"]') ?? root;
+            queueMicrotask(() => {
+                if (!root?.isConnected || !plot?.isConnected || document.activeElement !== document.body)
+                    return;
+                const replacement = Array.from(plot.querySelectorAll("[data-interaction-focus-key]")).find((item) => item.dataset.interactionFocusKey === key &&
+                    item.closest('[data-kind-ui="chart"]') === root);
+                replacement?.focus({ preventScroll: true });
+            });
+        }
+        current.current = node;
+    }, [key, enabled]);
+}

package/dist/combo-chart.d.ts

@@ -1,16 +1,19 @@
 import { type ComponentProps } from "react";
 import { ComposedChart as EngineComposedChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
-type Reveal = Pick<LineAnimation, "revealDurationMs" | "revealEasing">;
+import { type BaseAnimation, type LineAnimation } from "./animation.js";
+type Reveal = Pick<BaseAnimation, "revealDurationMs" | "revealEasing">;
+type DirectionalReveal = Reveal & Pick<LineAnimation, "revealDirection">;
 /** Shared hover Motion, with independently configured family entrances. */
 export type ComboAnimation = LineAnimation & {
-    lineReveal?: false | Reveal;
-    areaReveal?: false | Reveal;
+    lineReveal?: false | DirectionalReveal;
+    areaReveal?: false | DirectionalReveal;
     barReveal?: false | Reveal;
 };
 export type ComboChartProps = ComponentProps<typeof EngineComposedChart> & {
     animate?: boolean | ComboAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
 };
 /** Native ComposedChart geometry with the maintained Line, Area and Bar series. */
-export declare function ComboChart({ animate, children, ...props }: ComboChartProps): import("react").JSX.Element;
+export declare function ComboChart({ animate, loading, loadingLabel, children, ...props }: ComboChartProps): import("react").JSX.Element;
 export {};

package/dist/combo-chart.js

@@ -1,11 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { motion } from "motion/react";
 import { useCallback, useId, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { ComposedChart as EngineComposedChart } from "recharts";
 import { MotionContext } from "./animation.js";
 import { BarLifecycle, BarMotion } from "./bar-chart.js";
 import { LineChartFrame, useLineInteraction } from "./line-chart.js";
+import { CartesianLoadingDesign } from "./loading-cartesian-designs.js";
+import { RevealClip } from "./reveal-clip.js";
 const query = "(prefers-reduced-motion: reduce)";
 function subscribe(change) {
     const media = window.matchMedia(query);
@@ -15,12 +16,6 @@ function subscribe(change) {
 const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
-function Entrance({ id, family, options, finish, }) {
-    return (_jsx("defs", { children: _jsx("clipPath", { id: id, clipPathUnits: "userSpaceOnUse", children: _jsx(motion.rect, { "data-combo-reveal": family, x: 0, y: 0, height: "100%", initial: { width: "0%" }, animate: { width: "100%" }, onAnimationComplete: finish, transition: {
-                    duration: Math.max(0, options.revealDurationMs ?? 1000) / 1000,
-                    ease: options.revealEasing ?? [0.25, 0.1, 0.25, 1],
-                } }) }) }));
-}
 // A changed native child can change domains, axes, stacks or custom geometry.
 // Conservatively end entrances rather than retain a clip in the old coordinate space.
 function CompositionLifecycle({ children }) {
@@ -34,15 +29,22 @@ function CompositionLifecycle({ children }) {
     return null;
 }
 /** Native ComposedChart geometry with the maintained Line, Area and Bar series. */
-export function ComboChart({ animate = false, children, ...props }) {
+export function ComboChart({ animate = false, loading, loadingLabel, children, ...props }) {
     const id = useId();
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [finished, setFinished] = useState({ line: false, area: false, bar: false });
-    const interrupt = useCallback(() => setFinished({ line: true, area: true, bar: true }), []);
+    const interrupt = useCallback(() => {
+        if (!loading)
+            setFinished({ line: true, area: true, bar: true });
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading)
+            setFinished({ line: false, area: false, bar: false });
+    }, [loading]);
     const finishLine = useCallback(() => setFinished((value) => ({ ...value, line: true })), []);
     const finishArea = useCallback(() => setFinished((value) => ({ ...value, area: true })), []);
     const finishBar = useCallback(() => setFinished((value) => ({ ...value, bar: true })), []);
-    const enabled = animate !== false && !reduced;
+    const enabled = animate !== false && !reduced && !loading;
     const options = typeof animate === "object" ? animate : {};
     const line = options.lineReveal === false ? false : { ...options, ...options.lineReveal };
     const area = options.areaReveal === false ? false : { ...options, ...options.areaReveal };
@@ -53,12 +55,12 @@ export function ComboChart({ animate = false, children, ...props }) {
                 reveal: enabled && !finished.bar && bar !== false,
                 options: bar || {},
                 finish: finishBar,
-            }, children: _jsxs(LineChartFrame, { engine: EngineComposedChart, chartProps: {
+            }, children: _jsxs(LineChartFrame, { loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "combo", loadingDesign: (seed) => _jsx(CartesianLoadingDesign, { family: "combo", seed: seed }), loadingAnimation: { ...options, ...(props.layout ? { layout: props.layout } : {}) }, engine: EngineComposedChart, chartProps: {
                     ...props,
                     className: ["kind-ui-combo-chart", props.className].filter(Boolean).join(" "),
                     style: {
                         ...props.style,
                         "--kind-ui-combo-area-clip": revealArea ? `url(#${id}-area)` : "none",
                     },
-                }, motionEnabled: enabled, interrupt: interrupt, clip: revealLine ? `url(#${id}-line)` : "none", children: [_jsx(BarLifecycle, { ...props }), _jsx(CompositionLifecycle, { children: children }), revealLine && (_jsx(Entrance, { id: `${id}-line`, family: "line", options: line || {}, finish: finishLine })), revealArea && (_jsx(Entrance, { id: `${id}-area`, family: "area", options: area || {}, finish: finishArea })), children] }) }) }));
+                }, motionEnabled: enabled, interrupt: interrupt, clip: revealLine ? `url(#${id}-line)` : "none", children: [_jsx(BarLifecycle, { ...props }), _jsx(CompositionLifecycle, { children: children }), revealLine && (_jsx(RevealClip, { id: `${id}-line`, family: "line", combo: true, options: line || {}, finish: finishLine })), revealArea && (_jsx(RevealClip, { id: `${id}-area`, family: "area", combo: true, options: area || {}, finish: finishArea })), children] }) }) }));
 }

package/dist/configured-line-chart.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from "react";
 import { type CartesianGridProps, type DataKey, type XAxisProps, type YAxisProps } from "recharts";
 import { type LineChartProps as ComposedLineChartProps, type LineSeriesProps, type TooltipProps } from "./animation.js";
+import { type ChartBackgroundPatternProps } from "./chart-background-pattern.js";
 import { type LegendProps } from "./legend.js";
 import { type RootProps } from "./root.js";
 import type { SeriesConfig } from "./types.js";
@@ -34,6 +35,7 @@ type GeneratedParts<DataPoint> = {
     material?: LineSeriesProps["material"];
     xAxis?: false | XAxisProps<DataPoint>;
     yAxis?: false | YAxisProps<DataPoint>;
+    backgroundPattern?: ChartBackgroundPatternProps;
     grid?: false | CartesianGridProps;
     tooltip?: false | TooltipProps;
     series?: readonly ConfiguredLineSeries<DataPoint>[];
@@ -46,6 +48,7 @@ type ExplicitParts = {
     xDataKey?: never;
     xAxis?: never;
     yAxis?: never;
+    backgroundPattern?: never;
     grid?: never;
     tooltip?: never;
     series?: never;
@@ -55,7 +58,7 @@ export type ConfiguredLineChartProps<DataPoint = DefaultDataPoint> = Omit<Compos
     data: readonly DataPoint[];
     "aria-describedby"?: string;
     legend?: false | LegendProps;
-    rootProps?: Omit<RootProps, "config" | "children" | "visibleSeries" | "onVisibleSeriesChange">;
+    rootProps?: Omit<RootProps, "config" | "children" | "visibleSeries" | "defaultVisibleSeries" | "onVisibleSeriesChange">;
 } & Name & Visibility & (GeneratedParts<DataPoint> | ExplicitParts);
 export type LineChartProps = ComposedLineChartProps;
 type CompositionLineChartProps = LineChartProps & {
@@ -63,6 +66,7 @@ type CompositionLineChartProps = LineChartProps & {
     xDataKey?: never;
     xAxis?: never;
     yAxis?: never;
+    backgroundPattern?: never;
     grid?: never;
     tooltip?: never;
     curve?: never;

package/dist/configured-line-chart.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useContext, useId, useMemo, useRef, useState } from "react";
 import { CartesianGrid, XAxis, YAxis, } from "recharts";
 import { LineChart as ComposedLineChart, LineSeries, Tooltip, } from "./animation.js";
+import { ChartBackgroundPattern, } from "./chart-background-pattern.js";
 import { ChartContext } from "./chart-context.js";
 import { Legend } from "./legend.js";
 import { Root } from "./root.js";
@@ -14,7 +15,7 @@ export function LineChart(props) {
 }
 function ConfiguredLineChart(props) {
     const parent = useContext(ChartContext);
-    const { config, data, children, xDataKey, curve, material, xAxis, yAxis, grid, tooltip, series, legend, rootProps, visibleSeries, defaultVisibleSeries, onVisibleSeriesChange, style, className, width, height, responsive, accessibilityLayer = true, animate = true, ...chartProps } = props;
+    const { config, data, children, xDataKey, curve, material, xAxis, yAxis, grid, backgroundPattern, tooltip, series, legend, rootProps, visibleSeries, defaultVisibleSeries, onVisibleSeriesChange, style, className, width, height, responsive, accessibilityLayer = true, animate = true, loading, loadingLabel, ...chartProps } = props;
     const controlled = visibleSeries !== undefined;
     const initialMode = useRef(controlled);
     // Undefined means all current configured keys, including keys added later.
@@ -32,7 +33,7 @@ function ConfiguredLineChart(props) {
         throw new Error("Configured LineChart requires aria-label or aria-labelledby");
     const generated = children === undefined;
     if (!generated &&
-        [xDataKey, curve, material, xAxis, yAxis, grid, tooltip, series].some((part) => part !== undefined))
+        [xDataKey, curve, material, xAxis, yAxis, grid, tooltip, series, backgroundPattern].some((part) => part !== undefined))
         throw new Error("Explicit LineChart children replace generated parts; remove xDataKey and generated-part options");
     if (generated && xDataKey === undefined)
         throw new Error("Configured LineChart requires xDataKey when children are omitted");
@@ -67,11 +68,13 @@ function ConfiguredLineChart(props) {
     ]
         .filter(Boolean)
         .join(" ");
-    return (_jsxs(Root, { ...rootProps, className: ["kind-ui-configured-line-root", rootProps?.className].filter(Boolean).join(" "), config: activeConfig, visibleSeries: visible, ...(change ? { onVisibleSeriesChange: change } : {}), children: [accessibilityLayer && (_jsx("p", { id: instructionId, "data-kind-ui": "chart-instructions", children: "Focus the chart and use the arrow keys to inspect values. Press Escape to dismiss the tooltip." })), _jsx(ComposedLineChart, { ...chartProps, data: data, accessibilityLayer: accessibilityLayer, animate: animate, ...(describedBy ? { "aria-describedby": describedBy } : {}), responsive: responsive ?? true, ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}), className: ["kind-ui-configured-line-chart", className].filter(Boolean).join(" "), style: {
+    return (_jsxs(Root, { ...rootProps, className: ["kind-ui-configured-line-root", rootProps?.className].filter(Boolean).join(" "), config: activeConfig, visibleSeries: visible, ...(change ? { onVisibleSeriesChange: change } : {}), children: [accessibilityLayer && (_jsx("p", { id: instructionId, "data-kind-ui": "chart-instructions", children: "Focus the chart and use the arrow keys to inspect values. Press Escape to dismiss the tooltip." })), _jsx(ComposedLineChart, { ...chartProps, data: data, accessibilityLayer: accessibilityLayer, animate: animate, loading: loading, loadingLabel: loadingLabel, ...(describedBy ? { "aria-describedby": describedBy } : {}), responsive: responsive ?? true, ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}), className: ["kind-ui-configured-line-chart", className].filter(Boolean).join(" "), style: {
                     ...(width !== undefined ? { width } : {}),
                     ...(height !== undefined ? { height } : {}),
                     ...style,
-                }, children: generated ? (_jsxs(_Fragment, { children: [grid !== false && (_jsx(CartesianGrid, { vertical: false, stroke: "var(--kind-ui-chart-grid, #d1d5db)", strokeDasharray: "3 3", ...grid })), xAxis !== false && (_jsx(XAxis, { ...(xDataKey !== undefined ? { dataKey: xDataKey } : {}), axisLine: false, tickLine: false, tick: { fontSize: 12, fill: "var(--kind-ui-chart-muted-foreground, #6b7280)" }, ...xAxis })), yAxis !== false && (_jsx(YAxis, { axisLine: false, tickLine: false, tick: { fontSize: 12, fill: "var(--kind-ui-chart-muted-foreground, #6b7280)" }, ...yAxis })), series !== undefined
-                            ? series.map((item) => (_jsx(LineSeries, { type: curve ?? "monotone", material: material ?? "plain", dot: { r: 2.5 }, strokeWidth: 2, ...item }, item.seriesKey)))
+                }, children: generated ? (_jsxs(_Fragment, { children: [backgroundPattern && _jsx(ChartBackgroundPattern, { ...backgroundPattern }), grid !== false && (_jsx(CartesianGrid, { vertical: false, stroke: "var(--kind-ui-chart-grid, #d1d5db)", strokeDasharray: "3 3", ...grid })), xAxis !== false && (_jsx(XAxis, { ...(xDataKey !== undefined ? { dataKey: xDataKey } : {}), axisLine: false, tickLine: false, tick: { fontSize: 12, fill: "var(--kind-ui-chart-muted-foreground, #6b7280)" }, ...xAxis })), yAxis !== false && (_jsx(YAxis, { axisLine: false, tickLine: false, tick: { fontSize: 12, fill: "var(--kind-ui-chart-muted-foreground, #6b7280)" }, ...yAxis })), series !== undefined
+                            ? series.map((item) => (_jsx(LineSeries, { type: curve ?? "monotone", material: material ?? "plain", ...(item.pointStyle === undefined || item.pointStyle === "default"
+                                    ? { dot: { r: 2.5 } }
+                                    : {}), strokeWidth: 2, ...item }, item.seriesKey)))
                             : keys.map((key) => (_jsx(LineSeries, { dataKey: key, seriesKey: key, type: curve ?? "monotone", material: material ?? "plain", dot: { r: 2.5 }, strokeWidth: 2 }, key))), tooltip !== false && _jsx(Tooltip, { ...tooltip })] })) : (children) }), legend !== false && (generated || legend !== undefined) && _jsx(Legend, { ...legend })] }));
 }

package/dist/emphasis.d.ts

@@ -24,9 +24,10 @@ export declare function EmphasisProvider({ enabled, children, }: {
     enabled: boolean;
     children: React.ReactNode;
 }): import("react").JSX.Element;
+export declare function useOptionalEmphasisActions(): Omit<EmphasisState, "active"> | null;
 export declare function useEmphasisActions(): Omit<EmphasisState, "active">;
 /** Explicit contract for custom and portaled marks; apply factor to an extra paint wrapper. */
-export declare function useEmphasis(target: EmphasisTarget, enabled?: boolean): {
+export declare function useEmphasis(target: EmphasisTarget, enabled?: boolean, persistent?: boolean): {
     active: EmphasisTarget | null;
     dimmed: boolean;
     factor: number;
@@ -36,9 +37,11 @@ export declare function useEmphasis(target: EmphasisTarget, enabled?: boolean):
 export type EmphasisMarkProps = Omit<ComponentPropsWithRef<"g">, "target"> & {
     target: EmphasisTarget;
     enabled?: boolean | undefined;
+    /** Explicitly bind persistent Root focus paint for custom marks. */
+    persistent?: boolean | undefined;
     /** Adapter input from the engine, used only during native keyboard inspection. */
     keyboardActive?: boolean | undefined;
 };
 /** Multiplicative paint layer; native geometry, consumer opacity and hit testing stay intact. */
-export declare function EmphasisMark({ target, enabled, keyboardActive, children, ...props }: EmphasisMarkProps): import("react").JSX.Element;
+export declare function EmphasisMark({ target, enabled, persistent, keyboardActive, children, ...props }: EmphasisMarkProps): import("react").JSX.Element;
 export {};