tekivex-ui 2.2.0 → 2.5.1

package/src/components/TkxForm.tsx

@@ -43,6 +43,12 @@ export interface TkxFormProps {
   children: ReactNode;
   className?: string;
   style?: CSSProperties;
+  /**
+   * An external FormInstance created via useTkxForm().
+   * When provided, the form exposes its internal instance through this reference,
+   * enabling programmatic control from outside the component tree.
+   */
+  form?: FormInstance;
 }
 
 // ── Form Field Props ────────────────────────────────────────────────────────
@@ -185,24 +191,63 @@ function hasRequiredRule(rules: ValidationRule[]): boolean {
 // ── useTkxForm Hook ─────────────────────────────────────────────────────────
 
 /**
- * Create a FormInstance for programmatic access to form state.
- * Can be used standalone or connected to a <TkxForm> via context.
+ * Returns a FormInstance for programmatic access to form state.
+ *
+ * - Inside a <TkxForm>: returns the form's live instance (reads/writes real field state).
+ * - Outside a <TkxForm>: returns a standalone instance backed by a ref store.
+ *   Pass it to <TkxForm form={instance}> to connect it to a form.
+ *
+ * @example — programmatic access inside a form
+ * ```tsx
+ * function MyInnerButtons() {
+ *   const form = useTkxForm(); // connected to parent TkxForm
+ *   return <button onClick={() => form.resetFields()}>Reset</button>;
+ * }
+ * ```
+ *
+ * @example — external instance (Ant Design pattern)
+ * ```tsx
+ * function Parent() {
+ *   const form = useTkxForm();
+ *   return (
+ *     <TkxForm form={form}>
+ *       <TkxFormField name="email" label="Email"><TkxInput label="Email" /></TkxFormField>
+ *       <button onClick={() => console.log(form.getFieldsValue())}>Log</button>
+ *     </TkxForm>
+ *   );
+ * }
+ * ```
  */
 export function useTkxForm(): FormInstance {
   const ctx = useContext(FormContext);
 
-  // If used inside a TkxForm, return its instance directly
-  if (ctx) {
-    return ctx.instance;
-  }
+  // Always call hooks unconditionally (Rules of Hooks).
+  // These refs back the standalone instance when used outside a TkxForm.
+  const valuesRef = useRef<Record<string, any>>({});
+  const errorsRef = useRef<Record<string, string | null>>({});
+  const touchedRef = useRef<Record<string, boolean>>({});
 
-  // Standalone usage — maintain internal ref so the same object is returned
-  // across renders. Note: without a TkxForm provider, the standalone instance
-  // is inert (no UI binding), but callers can still use it as a value store.
-  throw new Error(
-    'useTkxForm() must be called inside a <TkxForm> provider. ' +
-    'Wrap your component tree with <TkxForm> first.',
-  );
+  const standaloneInstance = useMemo<FormInstance>(() => ({
+    getFieldValue: (name: string) => valuesRef.current[name],
+    setFieldValue: (name: string, value: any) => { valuesRef.current[name] = value; },
+    getFieldsValue: () => ({ ...valuesRef.current }),
+    setFieldsValue: (values: Record<string, any>) => {
+      Object.assign(valuesRef.current, values);
+    },
+    validateFields: () => Promise.resolve({ ...valuesRef.current }),
+    validateField: (_name: string) => Promise.resolve(true),
+    resetFields: () => {
+      valuesRef.current = {};
+      errorsRef.current = {};
+      touchedRef.current = {};
+    },
+    getFieldError: (name: string) => errorsRef.current[name] ?? null,
+    isFieldTouched: (name: string) => touchedRef.current[name] ?? false,
+  }), []);
+
+  // If inside a TkxForm context, return the live connected instance.
+  // Otherwise return the standalone ref-backed instance.
+  return ctx ? ctx.instance : standaloneInstance;
 }
 
 // ── TkxForm Component ───────────────────────────────────────────────────────
@@ -216,6 +261,7 @@ export function TkxForm({
   children,
   className,
   style,
+  form: externalInstance,
 }: TkxFormProps) {
   const theme = useTheme();
 
@@ -362,6 +408,10 @@ export function TkxForm({
     : tkx('flex flex-col gap-5');
 
   // ─── Context Value ─────────────────────────────────────────────────────
+  // When an external form instance is provided via the `form` prop, expose it
+  // through the context so that useTkxForm() inside children returns it.
+  const activeInstance = externalInstance ?? instance;
+
   const contextValue = useMemo<FormContextValue>(() => ({
     state,
     initialValues: initialValuesRef.current,
@@ -374,13 +424,15 @@ export function TkxForm({
     registerField,
     unregisterField,
     validateField,
-    instance,
-  }), [state, layout, disabled, setFieldValue, setFieldError, setFieldTouched, registerField, unregisterField, validateField, instance]);
+    instance: activeInstance,
+  }), [state, layout, disabled, setFieldValue, setFieldError, setFieldTouched, registerField, unregisterField, validateField, activeInstance]);
 
   return (
     <FormContext.Provider value={contextValue}>
       <form
         noValidate
+        role="form"
+        aria-label="Form"
         onSubmit={handleSubmit}
         className={cx(layoutClass, className)}
         style={{

package/src/components/TkxImage.tsx

@@ -70,7 +70,7 @@ export function TkxImage({
   ratio = 'auto',
   radius = 'none',
   caption,
-  lazy = false,
+  lazy = true,
   preview = false,
   className,
   style,

package/src/components/TkxList.tsx

@@ -0,0 +1,242 @@
+import { type ReactNode } from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface ListItem {
+  key: string;
+  title: string;
+  description?: string;
+  avatar?: ReactNode;
+  actions?: ReactNode;
+  extra?: ReactNode;
+}
+
+export interface TkxListProps {
+  items: ListItem[];
+  header?: ReactNode;
+  footer?: ReactNode;
+  bordered?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  loading?: boolean;
+  emptyText?: string;
+  grid?: { column?: number; gutter?: number };
+}
+
+// ── Size Tokens ──────────────────────────────────────────────────────────────
+
+const SIZE_PADDING = {
+  sm: '8px 12px',
+  md: '12px 16px',
+  lg: '16px 20px',
+} as const;
+
+// ── Loading Skeleton ─────────────────────────────────────────────────────────
+
+function Skeleton({ theme, reducedMotion }: { theme: ReturnType<typeof useTheme>; reducedMotion: boolean }) {
+  return (
+    <div className={tkx('flex items-center gap-3 px-4 py-3')} aria-hidden="true">
+      <div
+        style={{
+          width: 40,
+          height: 40,
+          borderRadius: '50%',
+          backgroundColor: theme.surfaceAlt,
+          animation: reducedMotion ? 'none' : 'tkxPulse 1.5s ease infinite',
+        }}
+      />
+      <div className={tkx('flex-1')}>
+        <div
+          style={{
+            width: '60%',
+            height: 14,
+            borderRadius: 4,
+            backgroundColor: theme.surfaceAlt,
+            marginBottom: 8,
+            animation: reducedMotion ? 'none' : 'tkxPulse 1.5s ease infinite',
+          }}
+        />
+        <div
+          style={{
+            width: '40%',
+            height: 12,
+            borderRadius: 4,
+            backgroundColor: theme.surfaceAlt,
+            animation: reducedMotion ? 'none' : 'tkxPulse 1.5s ease infinite',
+          }}
+        />
+      </div>
+    </div>
+  );
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxList({
+  items,
+  header,
+  footer,
+  bordered = true,
+  size = 'md',
+  loading = false,
+  emptyText = 'No data',
+  grid,
+}: TkxListProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const safeEmptyText = sanitizeString(emptyText);
+  const padding = SIZE_PADDING[size];
+
+  const isGrid = !!grid;
+  const columns = grid?.column ?? 1;
+  const gutter = grid?.gutter ?? 16;
+
+  return (
+    <div
+      role="list"
+      aria-label="List"
+      aria-busy={loading}
+      className={tkx('font-sans rounded-lg overflow-hidden')}
+      style={{
+        border: bordered ? `1px solid ${theme.border}` : 'none',
+        backgroundColor: theme.surface,
+      }}
+    >
+      {/* Header */}
+      {header && (
+        <div
+          className={tkx('font-semibold text-sm')}
+          style={{
+            padding,
+            color: theme.text,
+            borderBottom: `1px solid ${theme.border}`,
+            backgroundColor: theme.surfaceAlt,
+          }}
+        >
+          {header}
+        </div>
+      )}
+
+      {/* Loading */}
+      {loading && (
+        <div>
+          {Array.from({ length: 3 }).map((_, i) => (
+            <Skeleton key={i} theme={theme} reducedMotion={reducedMotion} />
+          ))}
+        </div>
+      )}
+
+      {/* Empty State */}
+      {!loading && items.length === 0 && (
+        <div
+          role="status"
+          className={tkx('text-center py-12 text-sm')}
+          style={{ color: theme.textMuted }}
+        >
+          {safeEmptyText}
+        </div>
+      )}
+
+      {/* Items */}
+      {!loading && items.length > 0 && (
+        <div
+          style={
+            isGrid
+              ? {
+                  display: 'grid',
+                  gridTemplateColumns: `repeat(${columns}, 1fr)`,
+                  gap: gutter,
+                  padding: gutter,
+                }
+              : undefined
+          }
+        >
+          {items.map((item, idx) => {
+            const safeTitle = sanitizeString(item.title);
+            const safeDesc = item.description ? sanitizeString(item.description) : undefined;
+
+            return (
+              <div
+                key={item.key}
+                role="listitem"
+                className={tkx('flex items-start gap-3')}
+                style={{
+                  padding: isGrid ? padding : padding,
+                  borderBottom:
+                    !isGrid && idx < items.length - 1
+                      ? `1px solid ${theme.border}`
+                      : 'none',
+                  ...(isGrid
+                    ? {
+                        border: `1px solid ${theme.border}`,
+                        borderRadius: 8,
+                        backgroundColor: theme.surface,
+                      }
+                    : {}),
+                  animation: reducedMotion ? 'none' : `tkxFadeIn 0.2s ease ${idx * 0.03}s both`,
+                }}
+              >
+                {/* Avatar */}
+                {item.avatar && (
+                  <div aria-hidden="true" className={tkx('shrink-0')}>
+                    {item.avatar}
+                  </div>
+                )}
+
+                {/* Content */}
+                <div className={tkx('flex-1 min-w-0')}>
+                  <div
+                    className={tkx('text-sm font-medium')}
+                    style={{ color: theme.text }}
+                  >
+                    {safeTitle}
+                  </div>
+                  {safeDesc && (
+                    <div
+                      className={tkx('text-xs mt-1 leading-relaxed')}
+                      style={{ color: theme.textMuted }}
+                    >
+                      {safeDesc}
+                    </div>
+                  )}
+                </div>
+
+                {/* Extra */}
+                {item.extra && (
+                  <div className={tkx('shrink-0 ml-auto')} style={{ color: theme.textMuted }}>
+                    {item.extra}
+                  </div>
+                )}
+
+                {/* Actions */}
+                {item.actions && (
+                  <div className={tkx('shrink-0 flex items-center gap-2')}>
+                    {item.actions}
+                  </div>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {/* Footer */}
+      {footer && (
+        <div
+          className={tkx('text-sm')}
+          style={{
+            padding,
+            color: theme.textMuted,
+            borderTop: `1px solid ${theme.border}`,
+            backgroundColor: theme.surfaceAlt,
+          }}
+        >
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/TkxMentions.tsx

@@ -0,0 +1,210 @@
+import { type ReactNode, useState, useRef, useCallback, useEffect } from 'react';
+import { useTheme } from '../themes';
+import { sanitizeString } from '../engine/security';
+import { useReducedMotion } from '../hooks';
+import { tkx } from '../engine/tkx';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface MentionOption {
+  value: string;
+  label: string;
+  avatar?: string;
+}
+
+export interface TkxMentionsProps {
+  options: MentionOption[];
+  value?: string;
+  onChange?: (value: string) => void;
+  trigger?: string;
+  placeholder?: string;
+  label?: string;
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function TkxMentions({
+  options,
+  value = '',
+  onChange,
+  trigger = '@',
+  placeholder,
+  label,
+}: TkxMentionsProps) {
+  const theme = useTheme();
+  const reducedMotion = useReducedMotion();
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const dropdownRef = useRef<HTMLUListElement>(null);
+  const [text, setText] = useState(value);
+  const [showDropdown, setShowDropdown] = useState(false);
+  const [query, setQuery] = useState('');
+  const [activeIdx, setActiveIdx] = useState(0);
+  const [triggerPos, setTriggerPos] = useState(-1);
+
+  useEffect(() => {
+    if (value !== undefined) setText(value);
+  }, [value]);
+
+  const filtered = options.filter((o) =>
+    o.label.toLowerCase().includes(query.toLowerCase()),
+  );
+
+  const handleInput = useCallback(
+    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      const val = e.target.value;
+      setText(val);
+      onChange?.(val);
+
+      const cursorPos = e.target.selectionStart ?? val.length;
+      const beforeCursor = val.slice(0, cursorPos);
+      const lastTrigger = beforeCursor.lastIndexOf(trigger);
+
+      if (lastTrigger >= 0) {
+        const afterTrigger = beforeCursor.slice(lastTrigger + trigger.length);
+        if (!/\s/.test(afterTrigger)) {
+          setQuery(afterTrigger);
+          setTriggerPos(lastTrigger);
+          setShowDropdown(true);
+          setActiveIdx(0);
+          return;
+        }
+      }
+      setShowDropdown(false);
+    },
+    [trigger, onChange],
+  );
+
+  const insertMention = useCallback(
+    (opt: MentionOption) => {
+      const before = text.slice(0, triggerPos);
+      const after = text.slice(
+        triggerPos + trigger.length + query.length,
+      );
+      const newText = `${before}${trigger}${opt.value} ${after}`;
+      setText(newText);
+      onChange?.(newText);
+      setShowDropdown(false);
+      inputRef.current?.focus();
+    },
+    [text, triggerPos, trigger, query, onChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (!showDropdown) return;
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setActiveIdx((i) => (i + 1) % filtered.length);
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActiveIdx((i) => (i - 1 + filtered.length) % filtered.length);
+      } else if (e.key === 'Enter' && filtered[activeIdx]) {
+        e.preventDefault();
+        insertMention(filtered[activeIdx]);
+      } else if (e.key === 'Escape') {
+        setShowDropdown(false);
+      }
+    },
+    [showDropdown, filtered, activeIdx, insertMention],
+  );
+
+  // Scroll active option into view
+  useEffect(() => {
+    if (!showDropdown || !dropdownRef.current) return;
+    const active = dropdownRef.current.children[activeIdx] as HTMLElement;
+    active?.scrollIntoView({ block: 'nearest' });
+  }, [activeIdx, showDropdown]);
+
+  const safeLabel = label ? sanitizeString(label) : undefined;
+  const safePlaceholder = placeholder ? sanitizeString(placeholder) : undefined;
+
+  return (
+    <div className={tkx('relative font-sans')} style={{ width: '100%' }}>
+      {safeLabel && (
+        <label
+          className={tkx('block text-sm font-medium mb-1')}
+          style={{ color: theme.text }}
+        >
+          {safeLabel}
+        </label>
+      )}
+
+      <textarea
+        ref={inputRef}
+        role="combobox"
+        aria-expanded={showDropdown}
+        aria-haspopup="listbox"
+        aria-autocomplete="list"
+        aria-label={safeLabel ?? 'Mentions input'}
+        value={text}
+        placeholder={safePlaceholder}
+        onChange={handleInput}
+        onKeyDown={handleKeyDown}
+        onBlur={() => setTimeout(() => setShowDropdown(false), 200)}
+        className={tkx('w-full rounded-lg border px-3 py-2 text-sm resize-y')}
+        style={{
+          backgroundColor: theme.surface,
+          borderColor: theme.border,
+          color: theme.text,
+          minHeight: 80,
+          outline: 'none',
+        }}
+        rows={3}
+      />
+
+      {showDropdown && filtered.length > 0 && (
+        <ul
+          ref={dropdownRef}
+          role="listbox"
+          aria-label="Mention suggestions"
+          className={tkx('absolute left-0 right-0 z-50 rounded-lg border overflow-auto')}
+          style={{
+            backgroundColor: theme.surface,
+            borderColor: theme.border,
+            maxHeight: 200,
+            top: '100%',
+            marginTop: 4,
+            listStyle: 'none',
+            padding: 0,
+            boxShadow: `0 4px 12px ${theme.bg}80`,
+            animation: reducedMotion ? 'none' : 'tkxFadeIn 0.15s ease',
+          }}
+        >
+          {filtered.map((opt, idx) => (
+            <li
+              key={opt.value}
+              role="option"
+              aria-selected={idx === activeIdx}
+              className={tkx('flex items-center gap-3 px-3 py-2 cursor-pointer text-sm')}
+              style={{
+                backgroundColor: idx === activeIdx ? theme.surfaceAlt : 'transparent',
+                color: theme.text,
+              }}
+              onMouseDown={(e) => {
+                e.preventDefault();
+                insertMention(opt);
+              }}
+              onMouseEnter={() => setActiveIdx(idx)}
+            >
+              {opt.avatar && (
+                <img
+                  src={sanitizeString(opt.avatar)}
+                  alt=""
+                  aria-hidden="true"
+                  width={24}
+                  height={24}
+                  className={tkx('rounded-full')}
+                  style={{ objectFit: 'cover' }}
+                />
+              )}
+              <span>{sanitizeString(opt.label)}</span>
+              <span style={{ color: theme.textMuted, marginLeft: 'auto' }}>
+                {trigger}{sanitizeString(opt.value)}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}