@sesionario/blocks 1.26.1 → 1.28.0

package/dist/charts.d.ts

@@ -0,0 +1,247 @@
+import * as React from 'react';
+import { ReactNode, RefObject } from 'react';
+import { Transition } from 'motion/react';
+
+/** Subset of `Intl.NumberFormatOptions` supported by NumberFlow */
+interface ChartStatFlowFormat {
+    notation?: "standard" | "compact";
+    compactDisplay?: "short" | "long";
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    minimumIntegerDigits?: number;
+    minimumSignificantDigits?: number;
+    maximumSignificantDigits?: number;
+    style?: "decimal" | "percent" | "currency";
+    currency?: string;
+    currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
+    unit?: string;
+    unitDisplay?: "short" | "long" | "narrow";
+}
+declare const defaultChartStatFlowFormat: ChartStatFlowFormat;
+interface ChartStatFlowProps {
+    value: number;
+    label: string;
+    formatOptions?: ChartStatFlowFormat;
+    prefix?: string;
+    suffix?: string;
+    valueClassName?: string;
+    labelClassName?: string;
+    icon?: ReactNode;
+}
+/**
+ * Shared value + label stack using NumberFlow (same layout as pie / ring centers).
+ * Parent should provide flex alignment and sizing when needed.
+ */
+declare function ChartStatFlow({ value, label, formatOptions, prefix, suffix, valueClassName, labelClassName, icon, }: ChartStatFlowProps): React.JSX.Element;
+declare namespace ChartStatFlow {
+    var displayName: string;
+}
+
+type GaugeLabelPlacement = "top" | "bottom" | "left" | "right";
+type GaugeLabelAlign = "start" | "center" | "end";
+
+type GaugeOrientation = "arc" | "linear";
+interface GaugeProps {
+    /** Arc (default) or horizontal linear notch track */
+    orientation?: GaugeOrientation;
+    /** Fill level 0–100 */
+    value: number;
+    /** Number of notches */
+    totalNotches?: number;
+    /** Percentage of the track reserved for gaps between notches */
+    spacing?: number;
+    notchCornerRadius?: number;
+    /** `true` = rectangular notches; `false` = tapered toward center / midline */
+    uniformWidth?: boolean;
+    startAngle?: number;
+    endAngle?: number;
+    useGradient?: boolean;
+    activeGradient?: readonly [string, string];
+    inactiveGradient?: readonly [string, string];
+    /** Center statistic — omit to hide the label block */
+    centerValue?: number;
+    defaultLabel?: string;
+    prefix?: string;
+    suffix?: string;
+    formatOptions?: ChartStatFlowFormat;
+    /** Label position for `orientation="linear"`. Arc gauges always overlay center. */
+    labelPlacement?: GaugeLabelPlacement;
+    /** Cross-axis alignment (start / center / end), same model as chart legend */
+    labelAlign?: GaugeLabelAlign;
+    inactiveFill?: string;
+    activeFill?: string;
+    inactiveFillOpacity?: number;
+    activeFillOpacity?: number;
+    children?: ReactNode;
+    className?: string;
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    notchLengthPercent?: number;
+    /** Linear only — notch width as % of each slot (default 80) */
+    notchWidthPercent?: number;
+    /** Linear only — bar thickness in px when responsive (default 24) */
+    linearHeight?: number;
+    enterTransition?: Transition;
+    enterStaggerScale?: number;
+    /** Studio-only: static paths while scrubbing geometry controls */
+    geometryScrubbing?: boolean;
+}
+declare function Gauge({ width: widthProp, height: heightProp, className, minWidth, orientation, linearHeight, ...props }: GaugeProps): React.JSX.Element;
+declare namespace Gauge {
+    var displayName: string;
+}
+
+declare const ringCssVars: {
+    background: string;
+    foreground: string;
+    foregroundMuted: string;
+    label: string;
+    ringBackground: string;
+    ring1: string;
+    ring2: string;
+    ring3: string;
+    ring4: string;
+    ring5: string;
+};
+declare const defaultRingColors: string[];
+interface RingData {
+    /** Display label for the ring */
+    label: string;
+    /** Current value */
+    value: number;
+    /** Maximum value (determines progress percentage) */
+    maxValue: number;
+    /** Optional color override - falls back to palette */
+    color?: string;
+}
+interface RingHoverContextValue {
+    hoveredIndex: number | null;
+    setHoveredIndex: (index: number | null) => void;
+}
+interface RingStableContextValue {
+    data: RingData[];
+    size: number;
+    center: number;
+    strokeWidth: number;
+    ringGap: number;
+    baseInnerRadius: number;
+    animationKey: number;
+    isLoaded: boolean;
+    enterTransition?: Transition;
+    enterStaggerScale: number;
+    containerRef: RefObject<HTMLDivElement | null>;
+    totalValue: number;
+    getColor: (index: number) => string;
+    getRingRadii: (index: number) => {
+        innerRadius: number;
+        outerRadius: number;
+    };
+    startAngle: number;
+    endAngle: number;
+    /**
+     * Studio geometry scrub — skip Motion path morphing and use plain SVG paths.
+     * @default false
+     */
+    geometryScrubbing: boolean;
+}
+type RingContextValue = RingStableContextValue & RingHoverContextValue;
+declare function RingProvider({ children, value, }: {
+    children: ReactNode;
+    value: RingContextValue;
+}): React.JSX.Element;
+declare function useRingStable(): RingStableContextValue;
+declare function useRingHover(): RingHoverContextValue;
+declare function useRing(): RingContextValue;
+
+interface RingChartProps {
+    /** Data array - each item represents a ring */
+    data: RingData[];
+    /** Chart size in pixels. If not provided, uses parent container size */
+    size?: number;
+    /** Stroke width of each ring. Default: 12 */
+    strokeWidth?: number;
+    /** Gap between rings. Default: 6 */
+    ringGap?: number;
+    /** Inner radius of the innermost ring. Default: 60 */
+    baseInnerRadius?: number;
+    /** Animation duration in milliseconds. Default: 1100 */
+    animationDuration?: number;
+    /** Additional class name for the container */
+    className?: string;
+    /** Controlled hover state - index of hovered ring */
+    hoveredIndex?: number | null;
+    /** Callback when hover state changes */
+    onHoverChange?: (index: number | null) => void;
+    /** Start angle in radians. Default: -PI/2 (top) */
+    startAngle?: number;
+    /** End angle in radians. Default: 3*PI/2 (full circle) */
+    endAngle?: number;
+    /** Framer Motion transition for ring enter animation */
+    enterTransition?: Transition;
+    /** Scales ring stagger delays (1 = default). */
+    enterStaggerScale?: number;
+    /**
+     * High-frequency geometry updates (e.g. studio NumberField scrub).
+     * Uses plain SVG paths instead of Motion `d` morphing.
+     */
+    geometryScrubbing?: boolean;
+    /** Child components (Ring, RingCenter, etc.) */
+    children: ReactNode;
+}
+declare function RingChart({ data, size: fixedSize, strokeWidth, ringGap, baseInnerRadius, className, hoveredIndex, onHoverChange, startAngle, endAngle, enterTransition, enterStaggerScale, geometryScrubbing, children, }: RingChartProps): React.JSX.Element;
+
+type RingLineCap = "round" | "butt";
+interface RingProps {
+    index: number;
+    color?: string;
+    animate?: boolean;
+    showGlow?: boolean;
+    lineCap?: RingLineCap;
+}
+declare const Ring: React.NamedExoticComponent<RingProps>;
+
+interface RingCenterProps {
+    /** Label shown below the value. Default: "Total" when not hovering */
+    defaultLabel?: string;
+    /** Format options for NumberFlow. Default: standard notation */
+    formatOptions?: ChartStatFlowFormat;
+    /** Custom render function for complete control over center content */
+    children?: (props: {
+        value: number;
+        label: string;
+        isHovered: boolean;
+        data: {
+            label: string;
+            value: number;
+            maxValue: number;
+            color?: string;
+        };
+    }) => ReactNode;
+    /** Additional class name for the container */
+    className?: string;
+    /** Class name for the value text. Scales with center size via container queries. */
+    valueClassName?: string;
+    /** Class name for the label text. Scales with center size via container queries. */
+    labelClassName?: string;
+    /** Prefix to show before the number (e.g., "$") */
+    prefix?: string;
+    /** Suffix to show after the number (e.g., "%") */
+    suffix?: string;
+}
+/**
+ * RingCenter displays content in the center of the ring chart.
+ *
+ * This component renders as pure HTML (not inside SVG foreignObject) to avoid
+ * Safari's WebKit bug #23113 where HTML content with CSS transforms/opacity
+ * inside foreignObject renders at incorrect positions.
+ *
+ * The parent RingChart uses CSS Grid stacking to overlay this HTML content
+ * on top of the SVG rings.
+ */
+declare function RingCenter({ defaultLabel, formatOptions, children, className, valueClassName, labelClassName, prefix, suffix, }: RingCenterProps): React.JSX.Element;
+declare namespace RingCenter {
+    var displayName: string;
+}
+
+export { ChartStatFlow, type ChartStatFlowFormat, type ChartStatFlowProps, Gauge, type GaugeLabelAlign, type GaugeLabelPlacement, type GaugeOrientation, type GaugeProps, Ring, RingCenter, type RingCenterProps, RingChart, type RingChartProps, type RingContextValue, type RingData, type RingHoverContextValue, type RingLineCap, type RingProps, RingProvider, type RingStableContextValue, defaultChartStatFlowFormat, defaultRingColors, ringCssVars, useRing, useRingHover, useRingStable };