tekivex-ui 2.1.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/TkxTypography.tsx

@@ -0,0 +1,263 @@
+import {
+  useState,
+  useCallback,
+  type ReactNode,
+  type CSSProperties,
+  createElement,
+} from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+
+// ── Interfaces ──────────────────────────────────────────────────────────────
+
+export type TypographyType = 'default' | 'secondary' | 'success' | 'warning' | 'danger';
+
+export interface TkxTitleProps {
+  level?: 1 | 2 | 3 | 4 | 5;
+  children: ReactNode;
+  copyable?: boolean;
+  type?: TypographyType;
+  style?: CSSProperties;
+}
+
+export interface TkxTextProps {
+  children: ReactNode;
+  type?: TypographyType;
+  strong?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  delete?: boolean;
+  code?: boolean;
+  mark?: boolean;
+  copyable?: boolean;
+  style?: CSSProperties;
+}
+
+export interface TkxParagraphProps {
+  children: ReactNode;
+  type?: 'default' | 'secondary';
+  copyable?: boolean;
+  ellipsis?: boolean | { rows?: number };
+  style?: CSSProperties;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function getTextContent(node: ReactNode): string {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(getTextContent).join('');
+  if (node && typeof node === 'object' && 'props' in node) {
+    return getTextContent((node as { props: { children?: ReactNode } }).props.children);
+  }
+  return '';
+}
+
+// ── CopyButton ──────────────────────────────────────────────────────────────
+
+function CopyButton({ text }: { text: string }) {
+  const theme = useTheme();
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(() => {
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  }, [text]);
+
+  return createElement(
+    'button',
+    {
+      type: 'button' as const,
+      onClick: handleCopy,
+      'aria-label': copied ? 'Copied' : 'Copy to clipboard',
+      style: {
+        display: 'inline-flex',
+        alignItems: 'center',
+        marginLeft: '4px',
+        padding: '2px 6px',
+        border: 'none',
+        background: 'transparent',
+        color: copied ? theme.success : theme.textMuted,
+        cursor: 'pointer',
+        fontSize: '0.8em',
+        borderRadius: '4px',
+        transition: 'color 0.2s',
+      },
+    },
+    copied ? 'Copied!' : '\u2398',
+  );
+}
+
+// ── Color Map ───────────────────────────────────────────────────────────────
+
+function useTypeColor(type: TypographyType = 'default') {
+  const theme = useTheme();
+  const map: Record<TypographyType, string> = {
+    default: theme.text,
+    secondary: theme.textMuted,
+    success: theme.success,
+    warning: theme.warning,
+    danger: theme.danger,
+  };
+  return map[type];
+}
+
+// ── Title Sizes ─────────────────────────────────────────────────────────────
+
+const TITLE_SIZES: Record<number, { fontSize: string; lineHeight: string; fontWeight: number }> = {
+  1: { fontSize: '2.25rem', lineHeight: '1.2', fontWeight: 700 },
+  2: { fontSize: '1.875rem', lineHeight: '1.25', fontWeight: 700 },
+  3: { fontSize: '1.5rem', lineHeight: '1.3', fontWeight: 600 },
+  4: { fontSize: '1.25rem', lineHeight: '1.35', fontWeight: 600 },
+  5: { fontSize: '1rem', lineHeight: '1.4', fontWeight: 600 },
+};
+
+// ── TkxTitle ────────────────────────────────────────────────────────────────
+
+export function TkxTitle({
+  level = 1,
+  children,
+  copyable = false,
+  type = 'default',
+  style,
+}: TkxTitleProps) {
+  const color = useTypeColor(type);
+  const theme = useTheme();
+  const sizeConfig = TITLE_SIZES[level];
+  const tag = `h${level}` as keyof JSX.IntrinsicElements;
+
+  const safeChildren = typeof children === 'string' ? sanitizeString(children) : children;
+  const textContent = getTextContent(children);
+
+  return createElement(
+    tag,
+    {
+      style: {
+        color,
+        fontSize: sizeConfig.fontSize,
+        lineHeight: sizeConfig.lineHeight,
+        fontWeight: sizeConfig.fontWeight,
+        margin: '0 0 0.5em 0',
+        fontFamily: 'inherit',
+        ...style,
+      },
+    },
+    safeChildren,
+    copyable && createElement(CopyButton, { text: textContent }),
+  );
+}
+
+// ── TkxText ─────────────────────────────────────────────────────────────────
+
+export function TkxText({
+  children,
+  type = 'default',
+  strong = false,
+  italic = false,
+  underline = false,
+  delete: strikethrough = false,
+  code = false,
+  mark = false,
+  copyable = false,
+  style,
+}: TkxTextProps) {
+  const color = useTypeColor(type);
+  const theme = useTheme();
+  const textContent = getTextContent(children);
+  const safeChildren = typeof children === 'string' ? sanitizeString(children) : children;
+
+  const decorations: string[] = [];
+  if (underline) decorations.push('underline');
+  if (strikethrough) decorations.push('line-through');
+
+  let content: ReactNode = safeChildren;
+
+  if (code) {
+    content = createElement(
+      'code',
+      {
+        style: {
+          padding: '0.15em 0.4em',
+          fontSize: '0.875em',
+          backgroundColor: theme.surfaceAlt,
+          border: `1px solid ${theme.border}`,
+          borderRadius: '4px',
+          fontFamily: 'monospace',
+        },
+      },
+      content,
+    );
+  }
+
+  if (mark) {
+    content = createElement(
+      'mark',
+      {
+        style: {
+          backgroundColor: `${theme.warning}33`,
+          color,
+          padding: '0 2px',
+          borderRadius: '2px',
+        },
+      },
+      content,
+    );
+  }
+
+  return createElement(
+    'span',
+    {
+      style: {
+        color,
+        fontWeight: strong ? 600 : 'inherit',
+        fontStyle: italic ? 'italic' : 'normal',
+        textDecoration: decorations.length > 0 ? decorations.join(' ') : 'none',
+        ...style,
+      },
+    },
+    content,
+    copyable && createElement(CopyButton, { text: textContent }),
+  );
+}
+
+// ── TkxParagraph ────────────────────────────────────────────────────────────
+
+export function TkxParagraph({
+  children,
+  type = 'default',
+  copyable = false,
+  ellipsis = false,
+  style,
+}: TkxParagraphProps) {
+  const theme = useTheme();
+  const color = type === 'secondary' ? theme.textMuted : theme.text;
+  const textContent = getTextContent(children);
+  const safeChildren = typeof children === 'string' ? sanitizeString(children) : children;
+
+  const ellipsisStyle: CSSProperties = {};
+  if (ellipsis) {
+    const rows = typeof ellipsis === 'object' ? (ellipsis.rows ?? 3) : 3;
+    ellipsisStyle.display = '-webkit-box';
+    ellipsisStyle.WebkitLineClamp = rows;
+    ellipsisStyle.WebkitBoxOrient = 'vertical';
+    ellipsisStyle.overflow = 'hidden';
+  }
+
+  return createElement(
+    'div',
+    {
+      style: {
+        color,
+        fontSize: '1rem',
+        lineHeight: '1.6',
+        margin: '0 0 1em 0',
+        ...ellipsisStyle,
+        ...style,
+      },
+    },
+    safeChildren,
+    copyable && createElement(CopyButton, { text: textContent }),
+  );
+}

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

@@ -51,3 +51,20 @@ export * from './TkxSnackbar';
 export * from './TkxDataGrid';
 export * from './TkxMasonry';
 export * from './TkxRichTextDisplay';
+export * from './TkxForm';
+export * from './TkxLayout';
+export * from './TkxConfigProvider';
+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';