tekivex-ui 2.2.0 → 2.3.0

package/src/components/TkxTour.tsx

@@ -0,0 +1,239 @@
+import { useState, useEffect, useCallback, useRef, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface TourStep {
+  target: string;
+  title: string;
+  description: string;
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+export interface TkxTourProps {
+  steps: TourStep[];
+  isOpen?: boolean;
+  onClose?: () => void;
+  current?: number;
+  onChange?: (step: number) => void;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getRect(selector: string): DOMRect | null {
+  const el = document.querySelector(selector);
+  return el ? el.getBoundingClientRect() : null;
+}
+
+interface PopoverPos {
+  top: number;
+  left: number;
+}
+
+function computePosition(
+  rect: DOMRect,
+  placement: string,
+  tipW: number,
+  tipH: number,
+): PopoverPos {
+  const gap = 12;
+  switch (placement) {
+    case 'top':
+      return { top: rect.top - tipH - gap + window.scrollY, left: rect.left + rect.width / 2 - tipW / 2 + window.scrollX };
+    case 'bottom':
+      return { top: rect.bottom + gap + window.scrollY, left: rect.left + rect.width / 2 - tipW / 2 + window.scrollX };
+    case 'left':
+      return { top: rect.top + rect.height / 2 - tipH / 2 + window.scrollY, left: rect.left - tipW - gap + window.scrollX };
+    case 'right':
+      return { top: rect.top + rect.height / 2 - tipH / 2 + window.scrollY, left: rect.right + gap + window.scrollX };
+    default:
+      return { top: rect.bottom + gap + window.scrollY, left: rect.left + window.scrollX };
+  }
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxTour({
+  steps,
+  isOpen = false,
+  onClose,
+  current: controlledCurrent,
+  onChange,
+}: TkxTourProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const [internal, setInternal] = useState(0);
+  const current = controlledCurrent ?? internal;
+  const tipRef = useRef<HTMLDivElement>(null);
+  const [pos, setPos] = useState<PopoverPos>({ top: 0, left: 0 });
+  const [targetRect, setTargetRect] = useState<DOMRect | null>(null);
+
+  const step = steps[current];
+
+  const updatePosition = useCallback(() => {
+    if (!step) return;
+    const rect = getRect(step.target);
+    setTargetRect(rect);
+    if (rect && tipRef.current) {
+      const tipW = tipRef.current.offsetWidth;
+      const tipH = tipRef.current.offsetHeight;
+      setPos(computePosition(rect, step.placement ?? 'bottom', tipW, tipH));
+    }
+  }, [step]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    updatePosition();
+    window.addEventListener('resize', updatePosition);
+    window.addEventListener('scroll', updatePosition, true);
+    return () => {
+      window.removeEventListener('resize', updatePosition);
+      window.removeEventListener('scroll', updatePosition, true);
+    };
+  }, [isOpen, current, updatePosition]);
+
+  // Focus trap: refocus popover on step change
+  useEffect(() => {
+    if (isOpen) tipRef.current?.focus();
+  }, [isOpen, current]);
+
+  const goTo = useCallback(
+    (idx: number) => {
+      setInternal(idx);
+      onChange?.(idx);
+    },
+    [onChange],
+  );
+
+  const handleNext = useCallback(() => {
+    if (current < steps.length - 1) goTo(current + 1);
+    else onClose?.();
+  }, [current, steps.length, goTo, onClose]);
+
+  const handlePrev = useCallback(() => {
+    if (current > 0) goTo(current - 1);
+  }, [current, goTo]);
+
+  if (!isOpen || !step) return null;
+
+  const pad = 6;
+  const safeTitle = sanitizeString(step.title);
+  const safeDesc = sanitizeString(step.description);
+  const TIP_W = 300;
+
+  const overlay = (
+    <div aria-hidden="true">
+      {/* Dimming overlay with spotlight cutout via CSS clip-path */}
+      <div
+        style={{
+          position: 'fixed',
+          inset: 0,
+          zIndex: 9998,
+          backgroundColor: 'rgba(0,0,0,0.55)',
+          clipPath: targetRect
+            ? `polygon(0% 0%, 0% 100%, ${targetRect.left - pad}px 100%, ${targetRect.left - pad}px ${targetRect.top - pad}px, ${targetRect.right + pad}px ${targetRect.top - pad}px, ${targetRect.right + pad}px ${targetRect.bottom + pad}px, ${targetRect.left - pad}px ${targetRect.bottom + pad}px, ${targetRect.left - pad}px 100%, 100% 100%, 100% 0%)`
+            : undefined,
+          transition: reducedMotion ? 'none' : 'clip-path 0.25s ease',
+        }}
+        onClick={onClose}
+      />
+
+      {/* Popover */}
+      <div
+        ref={tipRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={`Tour step ${current + 1} of ${steps.length}`}
+        tabIndex={-1}
+        style={{
+          position: 'absolute',
+          zIndex: 9999,
+          top: pos.top,
+          left: pos.left,
+          width: TIP_W,
+          backgroundColor: theme.surface,
+          border: `1px solid ${theme.border}`,
+          borderRadius: 10,
+          padding: 20,
+          boxShadow: `0 8px 24px ${theme.bg}80`,
+          animation: reducedMotion ? 'none' : 'tkxFadeIn 0.2s ease',
+          fontFamily: 'inherit',
+        }}
+        onKeyDown={(e) => {
+          if (e.key === 'Escape') onClose?.();
+        }}
+      >
+        <h3
+          className={tkx('m-0 mb-2 text-base font-semibold')}
+          style={{ color: theme.text }}
+        >
+          {safeTitle}
+        </h3>
+        <p
+          className={tkx('m-0 mb-4 text-sm leading-relaxed')}
+          style={{ color: theme.textMuted }}
+        >
+          {safeDesc}
+        </p>
+
+        {/* Step dots */}
+        <div className={tkx('flex items-center gap-1 mb-4')} aria-label="Tour progress">
+          {steps.map((_, i) => (
+            <span
+              key={i}
+              aria-hidden="true"
+              style={{
+                width: 8,
+                height: 8,
+                borderRadius: '50%',
+                backgroundColor: i === current ? theme.primary : theme.border,
+                transition: reducedMotion ? 'none' : 'background-color 0.2s',
+              }}
+            />
+          ))}
+        </div>
+
+        {/* Navigation */}
+        <div className={tkx('flex items-center justify-between gap-2')}>
+          <button
+            type="button"
+            aria-label="Skip tour"
+            onClick={onClose}
+            className={tkx('border-0 bg-transparent cursor-pointer text-sm px-2 py-1')}
+            style={{ color: theme.textMuted }}
+          >
+            Skip
+          </button>
+          <div className={tkx('flex gap-2')}>
+            {current > 0 && (
+              <button
+                type="button"
+                aria-label="Previous step"
+                onClick={handlePrev}
+                className={tkx('rounded-md border px-3 py-1 text-sm cursor-pointer bg-transparent')}
+                style={{ borderColor: theme.border, color: theme.text }}
+              >
+                Prev
+              </button>
+            )}
+            <button
+              type="button"
+              aria-label={current === steps.length - 1 ? 'Finish tour' : 'Next step'}
+              onClick={handleNext}
+              className={tkx('rounded-md border-0 px-4 py-1 text-sm cursor-pointer font-medium')}
+              style={{ backgroundColor: theme.primary, color: '#fff' }}
+            >
+              {current === steps.length - 1 ? 'Finish' : 'Next'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+
+  return createPortal(overlay, document.body);
+}

package/src/components/TkxWatermark.tsx

@@ -0,0 +1,143 @@
+import { type ReactNode, useRef, useEffect, useMemo, useState, useCallback } from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface TkxWatermarkProps {
+  text: string | string[];
+  children: ReactNode;
+  rotate?: number;
+  gap?: [number, number];
+  fontSize?: number;
+  color?: string;
+  zIndex?: number;
+}
+
+// ── Canvas Renderer ──────────────────────────────────────────────────────────
+
+function renderWatermarkPattern(
+  lines: string[],
+  rotate: number,
+  gap: [number, number],
+  fontSize: number,
+  fillColor: string,
+): string {
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return '';
+
+  const lineHeight = fontSize * 1.5;
+  const totalTextHeight = lines.length * lineHeight;
+
+  // Calculate canvas dimensions based on text length and gap
+  const maxTextWidth = Math.max(...lines.map((l) => l.length)) * fontSize * 0.6;
+  const canvasW = gap[0] + maxTextWidth;
+  const canvasH = gap[1] + totalTextHeight;
+
+  // High-DPI rendering
+  const dpr = 2;
+  canvas.width = canvasW * dpr;
+  canvas.height = canvasH * dpr;
+  ctx.scale(dpr, dpr);
+
+  // Move origin to center for rotation
+  ctx.translate(canvasW / 2, canvasH / 2);
+  ctx.rotate((rotate * Math.PI) / 180);
+
+  // Text styling
+  ctx.font = `${fontSize}px sans-serif`;
+  ctx.fillStyle = fillColor;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+
+  // Draw each line centered
+  lines.forEach((line, i) => {
+    const y = (i - (lines.length - 1) / 2) * lineHeight;
+    ctx.fillText(line, 0, y);
+  });
+
+  return canvas.toDataURL();
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxWatermark({
+  text,
+  children,
+  rotate = -22,
+  gap = [100, 100],
+  fontSize = 14,
+  color,
+  zIndex = 10,
+}: TkxWatermarkProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [bgImage, setBgImage] = useState('');
+
+  // Sanitize text lines
+  const lines = useMemo(
+    () => (Array.isArray(text) ? text : [text]).map((t) => sanitizeString(t)),
+    [text],
+  );
+
+  const fillColor = color ?? `${theme.textMuted}22`;
+
+  // Memoize the render function
+  const generatePattern = useCallback(() => {
+    return renderWatermarkPattern(lines, rotate, gap, fontSize, fillColor);
+  }, [lines, rotate, gap, fontSize, fillColor]);
+
+  // Generate the watermark canvas pattern
+  useEffect(() => {
+    const dataUrl = generatePattern();
+    if (dataUrl) {
+      setBgImage(`url(${dataUrl})`);
+    }
+  }, [generatePattern]);
+
+  // Prevent tampering via MutationObserver
+  useEffect(() => {
+    const overlay = containerRef.current?.querySelector<HTMLElement>('[data-watermark]');
+    if (!overlay) return;
+
+    const observer = new MutationObserver(() => {
+      // Re-apply watermark if someone modifies it
+      const dataUrl = generatePattern();
+      if (dataUrl) {
+        overlay.style.backgroundImage = `url(${dataUrl})`;
+      }
+    });
+
+    observer.observe(overlay, {
+      attributes: true,
+      attributeFilter: ['style'],
+    });
+
+    return () => observer.disconnect();
+  }, [generatePattern]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={tkx('relative')}
+      style={{ overflow: 'hidden' }}
+    >
+      {children}
+      <div
+        data-watermark
+        aria-hidden="true"
+        className={tkx('absolute inset-0 pointer-events-none')}
+        style={{
+          zIndex,
+          backgroundImage: bgImage,
+          backgroundRepeat: 'repeat',
+          animation: reducedMotion ? 'none' : 'tkxFadeIn 0.3s ease',
+        }}
+      />
+    </div>
+  );
+}

package/src/components/index.ts

@@ -58,3 +58,13 @@ export * from './TkxTypography';
 export * from './TkxSpin';
 export * from './TkxEmpty';
 export * from './TkxStatistic';
+export * from './TkxSegmented';
+export * from './TkxMentions';
+export * from './TkxQRCode';
+export * from './TkxResult';
+export * from './TkxTour';
+export * from './TkxWatermark';
+export * from './TkxAffix';
+export * from './TkxAnchor';
+export * from './TkxCascader';
+export * from './TkxList';

package/src/engine/tkx.ts

@@ -660,6 +660,10 @@ function resolveUtility(u: string): Declarations | null {
   // ── CSS variable passthrough: [--my-var:value] ────────────────────────────
   if ((m = u.match(/^\[(--[a-zA-Z0-9-]+):(.+)]$/))) { return { [m[1]]: m[2] }; }
 
+  // ── Plugin utilities ─────────────────────────────────────────────────────
+  const pluginResult = resolvePluginUtility(u);
+  if (pluginResult) return pluginResult;
+
   return null;
 }
 
@@ -872,3 +876,61 @@ export function resetAtomicCSS(): void {
 export function cx(...classes: (string | false | null | undefined)[]): string {
   return classes.filter(Boolean).join(' ');
 }
+
+// ── Plugin System ────────────────────────────────────────────────────────────
+/**
+ * TKX Plugin API — extend the utility engine with custom utilities.
+ *
+ * @example
+ * ```tsx
+ * import { tkxPlugin, tkx } from '@tekivex/ui';
+ *
+ * // Register custom utilities
+ * tkxPlugin({
+ *   name: 'brand',
+ *   utilities: {
+ *     'brand-gradient': { background: 'linear-gradient(135deg, #667eea, #764ba2)' },
+ *     'brand-text': { color: '#667eea', fontWeight: '700' },
+ *     'card-shadow': { boxShadow: '0 8px 32px rgba(102, 126, 234, 0.15)' },
+ *     'glass': {
+ *       background: 'rgba(255, 255, 255, 0.05)',
+ *       backdropFilter: 'blur(12px)',
+ *       border: '1px solid rgba(255, 255, 255, 0.1)',
+ *     },
+ *   },
+ * });
+ *
+ * // Use them like any built-in utility
+ * const cls = tkx('brand-gradient p-6 rounded-xl card-shadow');
+ * ```
+ */
+
+export interface TkxPluginDef {
+  name: string;
+  utilities: Record<string, Record<string, string>>;
+}
+
+const pluginRegistry = new Map<string, Record<string, Record<string, string>>>();
+
+export function tkxPlugin(plugin: TkxPluginDef): void {
+  pluginRegistry.set(plugin.name, plugin.utilities);
+}
+
+export function tkxRemovePlugin(name: string): void {
+  pluginRegistry.delete(name);
+}
+
+export function tkxListPlugins(): string[] {
+  return Array.from(pluginRegistry.keys());
+}
+
+/**
+ * Resolve a plugin utility to CSS properties.
+ * Called internally by the TKX engine — but also exported for inspection.
+ */
+export function resolvePluginUtility(name: string): Record<string, string> | null {
+  for (const utilities of pluginRegistry.values()) {
+    if (utilities[name]) return utilities[name];
+  }
+  return null;
+}