tekivex-ui 2.2.0 → 2.5.1

package/src/components/TkxSelect.tsx

@@ -44,6 +44,10 @@ export interface TkxSelectProps {
   onChange?: (value: string | string[]) => void;
   renderOption?: (option: SelectOption, isSelected: boolean) => ReactNode;
   maxMenuHeight?: number;
+  /** Enable virtual scrolling for the dropdown. Defaults to auto (enabled when 100+ options). */
+  virtualScroll?: boolean;
+  /** Fixed option height in pixels for virtual scroll calculations. Default: 36 */
+  optionHeight?: number;
   id?: string;
   className?: string;
   style?: CSSProperties;
@@ -139,6 +143,8 @@ export function TkxSelect({
   onChange,
   renderOption,
   maxMenuHeight = 280,
+  virtualScroll,
+  optionHeight = 36,
   id: idProp,
   className,
   style,
@@ -172,6 +178,32 @@ export function TkxSelect({
   const sz = SIZE_MAP[size];
   const hasError = isInvalid || !!errorMessage;
 
+  // ── Virtual scroll for options ─────────────────────────────────────────
+
+  const optionsListRef = useRef<HTMLDivElement>(null);
+  const [optScrollTop, setOptScrollTop] = useState(0);
+  const [optContainerHeight, setOptContainerHeight] = useState(0);
+
+  const handleOptScroll = useCallback(() => {
+    if (!optionsListRef.current) return;
+    setOptScrollTop(optionsListRef.current.scrollTop);
+  }, []);
+
+  useEffect(() => {
+    if (!isOpen) {
+      setOptScrollTop(0);
+      return;
+    }
+    const el = optionsListRef.current;
+    if (!el) return;
+    setOptContainerHeight(el.clientHeight);
+    const ro = new ResizeObserver(() => {
+      setOptContainerHeight(el.clientHeight);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [isOpen]);
+
   // ── Filtered + grouped options ────────────────────────────────────────────
 
   const filteredOptions = searchable && search
@@ -182,6 +214,25 @@ export function TkxSelect({
 
   const flatEnabled = filteredOptions.filter((o) => !o.disabled);
 
+  const hasGroups = filteredOptions.some((o) => !!o.group);
+  const isVirtualSelect =
+    virtualScroll !== undefined
+      ? virtualScroll
+      : filteredOptions.length >= 100;
+  // Only virtualize when we have a flat list (no groups) for simplicity
+  const useVirtual = isVirtualSelect && !hasGroups;
+
+  const OPTION_OVERSCAN = 8;
+  const virtualTotalHeight = filteredOptions.length * optionHeight;
+  const vStartIndex = useVirtual
+    ? Math.max(0, Math.floor(optScrollTop / optionHeight) - OPTION_OVERSCAN)
+    : 0;
+  const vEndIndex = useVirtual
+    ? Math.min(filteredOptions.length, Math.ceil((optScrollTop + optContainerHeight) / optionHeight) + OPTION_OVERSCAN)
+    : filteredOptions.length;
+  const visibleOptions = useVirtual ? filteredOptions.slice(vStartIndex, vEndIndex) : filteredOptions;
+  const vOffsetY = vStartIndex * optionHeight;
+
   const groups = filteredOptions.reduce<Record<string, SelectOption[]>>(
     (acc, opt) => {
       const g = opt.group ?? '';
@@ -285,11 +336,23 @@ export function TkxSelect({
 
   useEffect(() => {
     if (!isOpen || activeIndex < 0) return;
-    const el = listRef.current?.querySelector(
-      `[data-idx="${activeIndex}"]`,
-    ) as HTMLElement | null;
-    el?.scrollIntoView({ block: 'nearest' });
-  }, [activeIndex, isOpen]);
+    if (useVirtual && optionsListRef.current) {
+      // For virtual scroll, compute position directly
+      const itemTop = activeIndex * optionHeight;
+      const itemBottom = itemTop + optionHeight;
+      const el = optionsListRef.current;
+      if (itemTop < el.scrollTop) {
+        el.scrollTop = itemTop;
+      } else if (itemBottom > el.scrollTop + el.clientHeight) {
+        el.scrollTop = itemBottom - el.clientHeight;
+      }
+    } else {
+      const el = listRef.current?.querySelector(
+        `[data-idx="${activeIndex}"]`,
+      ) as HTMLElement | null;
+      el?.scrollIntoView({ block: 'nearest' });
+    }
+  }, [activeIndex, isOpen, useVirtual, optionHeight]);
 
   // ── Keyboard: trigger button ───────────────────────────────────────────────
 
@@ -494,13 +557,151 @@ export function TkxSelect({
 
           {/* Options list */}
           <div
-            ref={listRef}
+            ref={(el) => {
+              (listRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
+              (optionsListRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
+            }}
+            onScroll={useVirtual ? handleOptScroll : undefined}
             style={{
               overflowY: 'auto',
               flexGrow: 1,
               maxHeight: maxMenuHeight - (searchable ? 48 : 0),
             }}
           >
+            {useVirtual ? (
+              /* Virtualized flat list (no groups) */
+              <div style={{ height: virtualTotalHeight, position: 'relative' }}>
+                <div style={{ position: 'absolute', top: vOffsetY, left: 0, right: 0 }}>
+                  {visibleOptions.map((opt) => {
+                    const flatIdx = flatEnabled.indexOf(opt);
+                    const isActive = flatIdx === activeIndex;
+                    const isSelected = selectedValues.includes(opt.value);
+
+                    const optionContent = renderOption ? (
+                      renderOption(opt, isSelected)
+                    ) : (
+                      <span
+                        style={{
+                          display: 'flex',
+                          flexDirection: 'column',
+                          flex: 1,
+                          minWidth: 0,
+                        }}
+                      >
+                        <span
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 8,
+                          }}
+                        >
+                          {opt.icon && (
+                            <span style={{ flexShrink: 0, display: 'flex' }}>
+                              {opt.icon}
+                            </span>
+                          )}
+                          <span
+                            style={{
+                              overflow: 'hidden',
+                              textOverflow: 'ellipsis',
+                              whiteSpace: 'nowrap',
+                            }}
+                          >
+                            {sanitizeString(opt.label)}
+                          </span>
+                        </span>
+                        {opt.description && (
+                          <span
+                            style={{
+                              fontSize: '12px',
+                              color: theme.textMuted,
+                              marginTop: 1,
+                              overflow: 'hidden',
+                              textOverflow: 'ellipsis',
+                              whiteSpace: 'nowrap',
+                            }}
+                          >
+                            {sanitizeString(opt.description)}
+                          </span>
+                        )}
+                      </span>
+                    );
+
+                    return (
+                      <div
+                        key={opt.value}
+                        id={`${id}-opt-${opt.value}`}
+                        data-idx={flatIdx >= 0 ? flatIdx : undefined}
+                        role="option"
+                        aria-selected={isSelected}
+                        aria-disabled={opt.disabled || undefined}
+                        onClick={() => !opt.disabled && commitValue(opt.value)}
+                        onMouseEnter={() =>
+                          !opt.disabled && flatIdx >= 0 && setActiveIndex(flatIdx)
+                        }
+                        style={{
+                          height: optionHeight,
+                          boxSizing: 'border-box',
+                          padding: `0 ${sz.px}`,
+                          fontSize: sz.fontSize,
+                          fontFamily: 'inherit',
+                          color: opt.disabled ? theme.textMuted : theme.text,
+                          backgroundColor: isActive
+                            ? `${theme.primary}22`
+                            : isSelected
+                            ? `${theme.primary}12`
+                            : 'transparent',
+                          cursor: opt.disabled ? 'not-allowed' : 'pointer',
+                          display: 'flex',
+                          alignItems: 'center',
+                          justifyContent: 'space-between',
+                          gap: 8,
+                          transition: 'background-color 80ms',
+                          opacity: opt.disabled ? 0.5 : 1,
+                          userSelect: 'none',
+                          touchAction: 'manipulation',
+                        }}
+                      >
+                        {optionContent}
+                        {isSelected && !renderOption && (
+                          <svg
+                            width="14"
+                            height="14"
+                            viewBox="0 0 24 24"
+                            fill="none"
+                            stroke={theme.primary}
+                            strokeWidth="2.5"
+                            aria-hidden="true"
+                            style={{ flexShrink: 0 }}
+                          >
+                            <path d="M20 6L9 17l-5-5" />
+                          </svg>
+                        )}
+                      </div>
+                    );
+                  })}
+                </div>
+                {filteredOptions.length === 0 && (
+                  <div
+                    style={{
+                      padding: `${sz.py} ${sz.px}`,
+                      fontSize: sz.fontSize,
+                      fontFamily: 'inherit',
+                      color: theme.textMuted,
+                      textAlign: 'center',
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      right: 0,
+                    }}
+                  >
+                    {isLoading ? 'Loading\u2026' : 'No options found'}
+                  </div>
+                )}
+              </div>
+            ) : (
+            /* Non-virtual: grouped rendering */
+            <>
             {Object.entries(groups).map(([group, groupOpts]) => (
               <div key={group}>
                 {group && (
@@ -646,6 +847,8 @@ export function TkxSelect({
                 {isLoading ? 'Loading…' : 'No options found'}
               </div>
             )}
+            </>
+            )}
           </div>
         </div>,
         document.body,

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

@@ -206,12 +206,14 @@ export function TkxText({
     );
   }
 
+  // Use semantic HTML elements when appropriate
+  const tag = strong ? 'strong' : italic ? 'em' : 'span';
+
   return createElement(
-    'span',
+    tag,
     {
       style: {
         color,
-        fontWeight: strong ? 600 : 'inherit',
         fontStyle: italic ? 'italic' : 'normal',
         textDecoration: decorations.length > 0 ? decorations.join(' ') : 'none',
         ...style,

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';