tekivex-ui 2.2.0 → 2.5.1

package/src/charts/TkxScatterChart.tsx

@@ -0,0 +1,102 @@
+import {
+  ResponsiveContainer,
+  ScatterChart,
+  Scatter,
+  XAxis,
+  YAxis,
+  ZAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+} from 'recharts';
+import { useTheme } from '../themes';
+import { getDefaultColors, tooltipStyle, DEFAULT_MARGIN, type ChartMargin } from './shared';
+
+export interface TkxScatterSeries {
+  data: { x: number; y: number; z?: number; label?: string }[];
+  name?: string;
+  color?: string;
+}
+
+export interface TkxScatterChartProps {
+  series: TkxScatterSeries[];
+  height?: number;
+  margin?: ChartMargin;
+  showGrid?: boolean;
+  showLegend?: boolean;
+  showTooltip?: boolean;
+  xLabel?: string;
+  yLabel?: string;
+  xTickFormatter?: (value: any) => string;
+  yTickFormatter?: (value: any) => string;
+  /** Z-axis range (bubble size). Default: [20, 400] */
+  zRange?: [number, number];
+  ariaLabel?: string;
+}
+
+export function TkxScatterChart({
+  series,
+  height = 300,
+  margin = DEFAULT_MARGIN,
+  showGrid = true,
+  showLegend = true,
+  showTooltip = true,
+  xTickFormatter,
+  yTickFormatter,
+  zRange = [20, 400],
+  ariaLabel = 'Scatter chart',
+}: TkxScatterChartProps) {
+  const theme = useTheme();
+  const colors = getDefaultColors(theme);
+  const tt = tooltipStyle(theme);
+  const tickStyle = { fill: theme.textMuted, fontSize: 12 };
+
+  return (
+    <div role="img" aria-label={ariaLabel} style={{ width: '100%', height }}>
+      <ResponsiveContainer width="100%" height="100%">
+        <ScatterChart margin={margin}>
+          {showGrid && (
+            <CartesianGrid strokeDasharray="3 3" stroke={theme.border} />
+          )}
+          <XAxis
+            type="number"
+            dataKey="x"
+            tick={tickStyle}
+            axisLine={{ stroke: theme.border }}
+            tickLine={false}
+            tickFormatter={xTickFormatter}
+          />
+          <YAxis
+            type="number"
+            dataKey="y"
+            tick={tickStyle}
+            axisLine={false}
+            tickLine={false}
+            tickFormatter={yTickFormatter}
+          />
+          <ZAxis type="number" dataKey="z" range={zRange} />
+          {showTooltip && (
+            <Tooltip
+              contentStyle={tt.contentStyle}
+              labelStyle={tt.labelStyle}
+              itemStyle={tt.itemStyle}
+              cursor={{ strokeDasharray: '3 3' }}
+            />
+          )}
+          {showLegend && (
+            <Legend wrapperStyle={{ fontSize: 13, color: theme.textMuted, paddingTop: 8 }} />
+          )}
+          {series.map((s, i) => (
+            <Scatter
+              key={s.name ?? i}
+              name={s.name}
+              data={s.data}
+              fill={s.color ?? colors[i % colors.length]}
+              fillOpacity={0.8}
+            />
+          ))}
+        </ScatterChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}

package/src/charts/index.ts

@@ -0,0 +1,20 @@
+// ── @tekivex/ui/charts ───────────────────────────────────────────────────────
+// Theme-aware chart components built on Recharts.
+// Import from '@tekivex/ui/charts' — zero impact on the main bundle.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { TkxAreaChart } from './TkxAreaChart';
+export { TkxBarChart } from './TkxBarChart';
+export { TkxLineChart } from './TkxLineChart';
+export { TkxPieChart } from './TkxPieChart';
+export { TkxDonutChart } from './TkxDonutChart';
+export { TkxScatterChart } from './TkxScatterChart';
+export { TkxRadarChart } from './TkxRadarChart';
+
+export type { TkxAreaChartProps } from './TkxAreaChart';
+export type { TkxBarChartProps } from './TkxBarChart';
+export type { TkxLineChartProps } from './TkxLineChart';
+export type { TkxPieChartProps } from './TkxPieChart';
+export type { TkxDonutChartProps } from './TkxDonutChart';
+export type { TkxScatterChartProps } from './TkxScatterChart';
+export type { TkxRadarChartProps } from './TkxRadarChart';

package/src/charts/shared.ts

@@ -0,0 +1,45 @@
+// ── Shared chart utilities ───────────────────────────────────────────────────
+
+import type { ThemeTokens } from '../themes';
+
+/** Default palette: uses theme tokens then falls back to categorical colors */
+export function getDefaultColors(theme: ThemeTokens): string[] {
+  return [
+    theme.primary,
+    theme.secondary,
+    theme.info,
+    theme.success,
+    theme.warning,
+    theme.danger,
+    '#a855f7',
+    '#f97316',
+    '#14b8a6',
+    '#e879f9',
+  ];
+}
+
+export interface ChartMargin {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+export const DEFAULT_MARGIN: ChartMargin = { top: 10, right: 30, bottom: 10, left: 0 };
+
+/** Common recharts tooltip style that matches TekiVex theme */
+export function tooltipStyle(theme: ThemeTokens) {
+  return {
+    contentStyle: {
+      backgroundColor: theme.surface,
+      border: `1px solid ${theme.border}`,
+      borderRadius: 8,
+      boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
+      color: theme.text,
+      fontSize: 13,
+    },
+    labelStyle: { color: theme.textMuted, fontWeight: 600, marginBottom: 4 },
+    itemStyle: { color: theme.text },
+    cursor: { fill: `${theme.primary}15` },
+  };
+}

package/src/components/TkxAffix.tsx

@@ -0,0 +1,138 @@
+import { type ReactNode, useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface TkxAffixProps {
+  children: ReactNode;
+  offsetTop?: number;
+  offsetBottom?: number;
+  onChange?: (affixed: boolean) => void;
+  target?: () => HTMLElement | Window;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getScrollTarget(target?: () => HTMLElement | Window): HTMLElement | Window {
+  if (target) {
+    try {
+      return target();
+    } catch {
+      return window;
+    }
+  }
+  return window;
+}
+
+function getTargetRect(el: HTMLElement | Window): { top: number; bottom: number } {
+  if (el instanceof Window) {
+    return { top: 0, bottom: el.innerHeight };
+  }
+  const rect = el.getBoundingClientRect();
+  return { top: rect.top, bottom: rect.bottom };
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxAffix({
+  children,
+  offsetTop,
+  offsetBottom,
+  onChange,
+  target,
+}: TkxAffixProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const placeholderRef = useRef<HTMLDivElement>(null);
+  const fixedRef = useRef<HTMLDivElement>(null);
+  const [affixed, setAffixed] = useState(false);
+  const [placeholderSize, setPlaceholderSize] = useState({ width: 0, height: 0 });
+  const prevAffixed = useRef(false);
+
+  // Sanitize any debug info strings for security
+  const _labelSafe = useMemo(() => sanitizeString('Sticky content'), []);
+
+  const checkPosition = useCallback(() => {
+    const el = placeholderRef.current;
+    if (!el) return;
+
+    const rect = el.getBoundingClientRect();
+    const targetRect = getTargetRect(getScrollTarget(target));
+    let shouldAffix = false;
+
+    if (offsetTop !== undefined) {
+      // Affix when element scrolls past the top offset
+      shouldAffix = rect.top - targetRect.top <= offsetTop;
+    } else if (offsetBottom !== undefined) {
+      // Affix when element scrolls past the bottom offset
+      shouldAffix = targetRect.bottom - rect.bottom <= offsetBottom;
+    }
+
+    if (shouldAffix !== prevAffixed.current) {
+      prevAffixed.current = shouldAffix;
+      setAffixed(shouldAffix);
+      setPlaceholderSize({
+        width: rect.width,
+        height: rect.height,
+      });
+      onChange?.(shouldAffix);
+    }
+  }, [offsetTop, offsetBottom, onChange, target]);
+
+  // Attach scroll and resize listeners
+  useEffect(() => {
+    const scrollTarget = getScrollTarget(target);
+
+    checkPosition();
+    scrollTarget.addEventListener('scroll', checkPosition, { passive: true });
+    window.addEventListener('resize', checkPosition);
+
+    return () => {
+      scrollTarget.removeEventListener('scroll', checkPosition);
+      window.removeEventListener('resize', checkPosition);
+    };
+  }, [checkPosition, target]);
+
+  // Build the fixed positioning styles
+  const fixedStyle: React.CSSProperties = affixed
+    ? {
+        position: 'fixed',
+        zIndex: 100,
+        ...(offsetTop !== undefined ? { top: offsetTop } : {}),
+        ...(offsetBottom !== undefined ? { bottom: offsetBottom } : {}),
+        width: placeholderSize.width || undefined,
+        transition: reducedMotion ? 'none' : 'box-shadow 0.2s ease',
+        boxShadow: `0 2px 8px ${theme.border}`,
+      }
+    : {};
+
+  // Placeholder keeps the document flow intact when element is fixed
+  const placeholderStyle: React.CSSProperties = affixed
+    ? {
+        height: placeholderSize.height,
+        width: placeholderSize.width,
+      }
+    : {};
+
+  return (
+    <>
+      <div
+        ref={placeholderRef}
+        aria-hidden={affixed}
+        style={placeholderStyle}
+      />
+      <div
+        ref={fixedRef}
+        role="region"
+        aria-label={_labelSafe}
+        className={tkx(affixed ? 'tkx-affixed' : '')}
+        style={fixedStyle}
+      >
+        {children}
+      </div>
+    </>
+  );
+}

package/src/components/TkxAnchor.tsx

@@ -0,0 +1,193 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface AnchorLink {
+  key: string;
+  href: string;
+  title: string;
+  children?: AnchorLink[];
+}
+
+export interface TkxAnchorProps {
+  items: AnchorLink[];
+  offsetTop?: number;
+  getCurrentAnchor?: (activeLink: string) => string;
+  onChange?: (currentLink: string) => void;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function flattenLinks(items: AnchorLink[]): AnchorLink[] {
+  const result: AnchorLink[] = [];
+  for (const item of items) {
+    result.push(item);
+    if (item.children) result.push(...flattenLinks(item.children));
+  }
+  return result;
+}
+
+function getAnchorId(href: string): string {
+  return href.startsWith('#') ? href.slice(1) : href;
+}
+
+// ── Link Item ────────────────────────────────────────────────────────────────
+
+function AnchorItem({
+  item,
+  activeKey,
+  depth,
+  onClick,
+  theme,
+  reducedMotion,
+}: {
+  item: AnchorLink;
+  activeKey: string;
+  depth: number;
+  onClick: (href: string) => void;
+  theme: ReturnType<typeof useTheme>;
+  reducedMotion: boolean;
+}) {
+  const isActive = item.key === activeKey;
+  const safeTitle = sanitizeString(item.title);
+
+  return (
+    <li role="none" style={{ listStyle: 'none' }}>
+      <a
+        role="treeitem"
+        aria-current={isActive ? 'location' : undefined}
+        href={item.href}
+        onClick={(e) => {
+          e.preventDefault();
+          onClick(item.href);
+        }}
+        className={tkx('block text-sm py-1 no-underline')}
+        style={{
+          paddingLeft: 12 + depth * 16,
+          color: isActive ? theme.primary : theme.textMuted,
+          fontWeight: isActive ? 600 : 400,
+          borderLeft: `2px solid ${isActive ? theme.primary : 'transparent'}`,
+          transition: reducedMotion ? 'none' : 'color 0.15s ease, border-color 0.15s ease',
+        }}
+      >
+        {safeTitle}
+      </a>
+      {item.children && item.children.length > 0 && (
+        <ul role="group" style={{ margin: 0, padding: 0 }}>
+          {item.children.map((child) => (
+            <AnchorItem
+              key={child.key}
+              item={child}
+              activeKey={activeKey}
+              depth={depth + 1}
+              onClick={onClick}
+              theme={theme}
+              reducedMotion={reducedMotion}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxAnchor({
+  items,
+  offsetTop = 0,
+  getCurrentAnchor,
+  onChange,
+}: TkxAnchorProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const [activeKey, setActiveKey] = useState(items[0]?.key ?? '');
+  const isScrolling = useRef(false);
+
+  const flat = flattenLinks(items);
+
+  const updateActive = useCallback(() => {
+    if (isScrolling.current) return;
+
+    let current = flat[0]?.key ?? '';
+    for (const link of flat) {
+      const id = getAnchorId(link.href);
+      const el = document.getElementById(id);
+      if (el) {
+        const top = el.getBoundingClientRect().top;
+        if (top <= offsetTop + 10) {
+          current = link.key;
+        }
+      }
+    }
+
+    if (getCurrentAnchor) {
+      current = getCurrentAnchor(current);
+    }
+
+    if (current !== activeKey) {
+      setActiveKey(current);
+      onChange?.(current);
+    }
+  }, [flat, offsetTop, getCurrentAnchor, activeKey, onChange]);
+
+  useEffect(() => {
+    window.addEventListener('scroll', updateActive, { passive: true });
+    updateActive();
+    return () => window.removeEventListener('scroll', updateActive);
+  }, [updateActive]);
+
+  const handleClick = useCallback(
+    (href: string) => {
+      const id = getAnchorId(href);
+      const el = document.getElementById(id);
+      if (!el) return;
+
+      isScrolling.current = true;
+      const top = el.getBoundingClientRect().top + window.scrollY - offsetTop;
+      window.scrollTo({ top, behavior: reducedMotion ? 'auto' : 'smooth' });
+
+      // Find the link by href and set active
+      const link = flat.find((l) => l.href === href);
+      if (link) {
+        setActiveKey(link.key);
+        onChange?.(link.key);
+      }
+
+      setTimeout(() => {
+        isScrolling.current = false;
+      }, 800);
+    },
+    [flat, offsetTop, reducedMotion, onChange],
+  );
+
+  return (
+    <nav
+      role="tree"
+      aria-label="Anchor navigation"
+      className={tkx('font-sans')}
+      style={{
+        borderLeft: `1px solid ${theme.border}`,
+        padding: '4px 0',
+      }}
+    >
+      <ul role="group" style={{ margin: 0, padding: 0 }}>
+        {items.map((item) => (
+          <AnchorItem
+            key={item.key}
+            item={item}
+            activeKey={activeKey}
+            depth={0}
+            onClick={handleClick}
+            theme={theme}
+            reducedMotion={reducedMotion}
+          />
+        ))}
+      </ul>
+    </nav>
+  );
+}