npm install tekivex-ui

The 14-package ecosystem at a glance

tekivex-ui is the main library, but the ecosystem ships 14 npm packages total. You typically need 1–3 of them, not 14. Map below groups by the question that makes you install each one. Full reference: ui.tekivex.com/ecosystem.

Why so many packages? Independent versioning, smaller bundles, opt-in peer deps. A consumer wanting tekivex-pdf shouldn't have to pull three.js. A consumer wanting tekivex-india-admin shouldn't wait for a tekivex-ui release when LGD data refreshes. Each package versions and ships on its own clock; this README always reflects the current install matrix.

Project status — read before adopting

TekiVex UI is pre-1.0 and currently maintained by a single developer (007krcs) on novaai0401@gmail.com. We ship a public CycloneDX SBOM, a security threat model (15 STRIDE threats with CWE refs), and 1,798 tests at the published version — but none of that substitutes for the human-scale risk of any pre-1.0, single-maintainer library.

When published from CI, releases carry npm provenance attestations. Local releases (currently the norm during pre-1.0) do not — verify provenance status with npm view tekivex-ui --json | jq '.dist.attestations' if it matters to your supply-chain policy.

Honest guidance:

• Pin your version ("tekivex-ui": "3.18.0", not "^3.18.0") until v4.0
• Read TROUBLESHOOTING.md before integrating — covers known Next.js / RSC / SSR / hydration issues
• Audit the SBOM at ui.tekivex.com/security/sbom.json — verifies zero runtime deps
• Verify the package with npm view tekivex-ui before installing if you're concerned about typosquats (the legitimate name is exactly tekivex-ui)
• Check Socket.dev for supply-chain risk score
• For regulated-industry teams: we're open to design-partner collaborations with regulated-industry teams — see docs/design-partners/README.md for the playbook. No reserved slots, no formal program in place yet; reach out if it fits your situation.

Expect breaking changes at v4.0 — see docs/ROADMAP.md. Until then, the API surface marked stable will not break in minor or patch releases.

Recent compatibility fixes (v3.18, published 2026-05-28):

• Build no longer emits Vite's chunk runtime format — works in Next.js / RSC (was broken pre-v3.18)
• ThemeProvider mode="auto" is now SSR-safe + themeInitScript() helper for FOUC-free initialisation
• 'use client' directives on every hook-using component
• isDisabled absorbed as a deprecated alias (no longer pollutes DOM)
• background / backgroundImage shorthand conflict removed

Standalone template repos

The resume + biodata templates have moved into their own repos so apps that only need the templates don't have to pull the entire tekivex-ui install:

Both repos ship the same generator pattern (form → A4 preview → 1-page print), the same locked-by-default policy, and the same image-upload UX as the original TkxTemplateGenerator in this repo (which is staying for backward compatibility).

What's new in v3.6 → v3.15

Coverage notation: lines / statements / functions / branches.

Pair tekivex-ui with tekivex-3d for the spatial UI toolkit (Scene, Panorama360, Hotspot, XRSession, Model3D, Logo3D, ParticleField, OrbitControls, Starfield, Planet, OrbitPath, Portal3D, Avatar3D — 14 primitives at source v0.7).

Why TekiVex UI?

Installation

# npm
npm install tekivex-ui

# pnpm
pnpm add tekivex-ui

# yarn
yarn add tekivex-ui

Peer dependencies (already in most React projects):

npm install react@^18 react-dom@^18

Optional — for chart components:

npm install recharts

Quick Start

import { ThemeProvider, quantumDark, TkxButton, TkxCard } from 'tekivex-ui';
import 'tekivex-ui/styles';

export default function App() {
  return (
    <ThemeProvider theme={quantumDark}>
      <TkxCard variant="elevated">
        <h2>Hello TekiVex</h2>
        <TkxButton colorScheme="primary" size="md">
          Get Started
        </TkxButton>
      </TkxCard>
    </ThemeProvider>
  );
}

Package Exports

TekiVex UI ships tree-shakeable entry points — import only what you need:

// Core components + theme + engine  (~120 kB gzip)
import { TkxButton, ThemeProvider, useTheme } from 'tekivex-ui';

// 7 chart types built on Recharts  (~3 kB gzip on top of recharts)
import { TkxAreaChart, TkxBarChart, TkxLineChart, TkxPieChart } from 'tekivex-ui/charts';

// 10 headless hooks — zero styles, your UI  (~2.6 kB gzip)
import { useDisclosure, useFormState, useListSelection } from 'tekivex-ui/headless';

// Agent runtime — Anthropic/OpenAI/Gemini/Ollama, RAG, MCP, A2A, tools (~16 kB gzip)
import { createAgent, AnthropicProvider, useAgent } from 'tekivex-ui/agent';

📘 Full agent runtime reference → docs/AGENT.md

Components (115)

Charts

Seven production-ready chart types via the tekivex-ui/charts sub-package:

import {
  TkxAreaChart, TkxBarChart, TkxLineChart,
  TkxPieChart, TkxDonutChart,
  TkxScatterChart, TkxRadarChart,
} from 'tekivex-ui/charts';

const data = [
  { month: 'Jan', revenue: 42000, cost: 28000 },
  { month: 'Feb', revenue: 51000, cost: 31000 },
  { month: 'Mar', revenue: 63000, cost: 34000 },
];

<TkxAreaChart
  data={data}
  xKey="month"
  series={[
    { key: 'revenue', label: 'Revenue' },
    { key: 'cost', label: 'Cost' },
  ]}
  height={300}
  showGrid
  showLegend
  smooth
  ariaLabel="Monthly revenue vs cost"
/>

Headless Primitives

Zero-style hooks from tekivex-ui/headless — bring your own UI:

import {
  useDisclosure,     // open/closed state
  useDebounce,       // debounce any value
  useThrottle,       // throttle any value
  useControllable,   // unify controlled/uncontrolled (Radix pattern)
  useListSelection,  // multi-select with selectAll / toggleAll
  useLocalStorage,   // SSR-safe persisted state
  useMediaQuery,     // reactive media query
  useBreakpoint,     // sm/md/lg/xl/xxl/isMobile/isTablet/isDesktop
  useFormState,      // headless form with validation + dirty tracking
  useRovingTabIndex, // WAI-ARIA roving tabIndex keyboard navigation
  useIntersectionObserver, // viewport visibility
} from 'tekivex-ui/headless';

// Example — useDisclosure
const { isOpen, open, close, toggle } = useDisclosure(false);

// Example — useFormState
const { values, errors, touched, isValid, setValue, validate } = useFormState({
  initialValues: { name: '', email: '' },
  validate: (vals) => {
    const errs: Record<string, string> = {};
    if (!vals.name) errs.name = 'Required';
    if (!vals.email.includes('@')) errs.email = 'Invalid email';
    return errs;
  },
});

// Example — useControllable (works controlled or uncontrolled)
const [value, setValue2] = useControllable({
  value: externalValue,      // optional — if omitted, uses internal state
  onChange: onExternalChange, // optional
  defaultValue: 'default',
});

Theming

import { ThemeProvider, createTheme, quantumDark, auroraLight } from 'tekivex-ui';

// Built-in themes
<ThemeProvider theme={quantumDark}>...</ThemeProvider>   // dark
<ThemeProvider theme={auroraLight}>...</ThemeProvider>   // light

// Custom brand theme
const brandTheme = createTheme({
  primary:   '#6366f1',
  secondary: '#8b5cf6',
  bg:        '#0f0f23',
  surface:   '#1a1a3e',
  text:      '#f0f0ff',
});

// Read current theme tokens anywhere
function MyComponent() {
  const theme = useTheme();
  return <div style={{ color: theme.primary }}>Branded</div>;
}

CSS custom properties are injected automatically — no flash of unstyled content (FOUC).

Internationalisation (44 locales)

import { I18nProvider, zhCN, arSA, jaJP, ptBR } from 'tekivex-ui';

<I18nProvider locale="zh-CN">  {/* RTL is detected automatically for ar-SA, he-IL, fa-IR */}
  <App />
</I18nProvider>

Supported locales:

TKX Atomic CSS Engine

A zero-runtime, conflict-resolving CSS engine. No Tailwind, no styled-components, no extra config.

import { tkx, cx, cssVar, tkxPlugin } from 'tekivex-ui';

// Single string, no class conflicts
const cls = tkx('flex items-center p-4 hover:bg-surface');

// Conflict resolution — last value wins
tkx('p-4 p-8');  // → only padding: 32px

// Arbitrary values & CSS variables
tkx('w-[42px] text-[#ff6b6b] [--spacing:16px]');

// Conditional classes
cx('base', isActive && 'active', hasError ? 'ring-danger' : 'ring-border');

// Plugin API — extend the engine (unique to TekiVex)
tkxPlugin('glass', () => ({
  backdropFilter: 'blur(12px)',
  backgroundColor: 'rgba(255,255,255,0.08)',
  border: '1px solid rgba(255,255,255,0.12)',
}));
tkx('glass p-6 rounded-xl'); // uses your plugin

Engine performance: O(1) style injection via the Constructable Stylesheets API (document.adoptedStyleSheets) with automatic SSR fallback.

Security

TekiVex UI is the only React component library with a built-in zero-trust security engine. Every string that passes through the library is automatically sanitised — no configuration required.

import { sanitizeString, sanitizeProps, contrastRatio, meetsAA, meetsAAA } from 'tekivex-ui/headless';

// XSS sanitisation (called automatically inside every component)
sanitizeString('<script>alert("XSS")</script>Hello');
// → 'Hello'

sanitizeString('<img src=x onerror="stealCookies()" />');
// → '' (fully stripped)

// WCAG contrast checking
const ratio = contrastRatio('#00f5d4', '#0a0a1a'); // → 8.21
const aa    = meetsAA('#00f5d4', '#0a0a1a');        // → true  (≥ 4.5:1)
const aaa   = meetsAAA('#00f5d4', '#0a0a1a');       // → true  (≥ 7:1)

What's unique:

• 🛡️ String-prop sanitisation by default — sanitizeString runs on string props across components without opt-in
• 📋 Tamper-evident audit trail — SHA-256 hash-chained append-only log for compliance / SIEM
• 🎨 Built-in WCAG checker — contrastRatio(), meetsAA(), meetsAAA() available anywhere

Accessibility

We target WCAG 2.1 AAA — the highest accessibility standard. Self-tested against the criteria below; a third-party audit is on the roadmap and has not been completed. Treat this section as our internal compliance target, not a certification.

• ✅ Contrast ratio ≥ 7:1 for all text (AAA, not just AA's 4.5:1) — verified via internal meetsAAA() helper
• ✅ Full keyboard navigation — Tab, Enter, Space, Arrow keys, Escape
• ✅ Correct ARIA roles, states & properties (WAI-ARIA 1.2)
• ✅ Focus management — focus trap in modals, visible focus rings
• ✅ Reduced-motion — all animations respect prefers-reduced-motion
• ✅ Screen reader tested — live regions, sr-only text, meaningful alt
• ✅ RTL support — layout mirrors automatically for Arabic, Hebrew, Persian

DataGrid

Full-featured data grid — no paid tier required:

import { TkxDataGrid } from 'tekivex-ui';

<TkxDataGrid
  columns={[
    { key: 'name',   header: 'Name',   sortable: true  },
    { key: 'email',  header: 'Email',  sortable: true  },
    { key: 'status', header: 'Status', filterable: true },
  ]}
  rows={data}
  pageSize={10}
  selectable
  showFilters
  showExport
  exportFileName="users"
/>

Templates

Seven full-page templates included in the demo:

Development

git clone https://ui.tekivex.com
cd tekivex-ui
npm install

# Build the library
npm run build

# Run all 1798 tests
npm test

# Run tests with coverage report
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Run the library Vite playground (localhost:5173)
npm run dev

# Run the interactive demo (localhost:5174)
npm run dev:demo

# Accessibility audit
npm run a11y:audit

# Security audit
npm run security:audit

Testing

90 dedicated component test files · 1798 tests · 0 failures · 1 todo
Coverage: 64.84% lines · 51.10% functions · 56.77% branches · 61.41% statements (ratchet enforced in CI)

Coverage includes dedicated unit tests for 88 of 116 production components plus smoke coverage for the rest, 7 chart types, headless hooks (incl. useWebSocket / useSSE / useMediaQuery), the TKX CSS engine, the WCAG engine, the security (Shield) engine, the i18n provider, and Indian KYC validators (Aadhaar Verhoeff, PAN, Voter ID, DL).

Coverage thresholds are enforced as a CI ratchet in vitest.config.ts — the floor never drops between releases. Path to 90/90/85 is documented in docs/test-coverage-roadmap.md.

Roadmap

Full roadmap with version targets, owners, and definition-of-done at docs/ROADMAP.md.

Nearest milestones:

• v3.18 (target 2026-07-15) — "Land the audit + first partner." Sign a third-party WCAG audit SOW (Deque / TPGi / WebAIM), land 1 design-partner logo, lift TkxDataGrid to 50+ tests. No new components.
• v3.19 (target 2026-09-01) — "Coverage + DataGrid completeness." Ratchet coverage 64.84% → 75% lines, ship DataGrid column-pinning and row-grouping, deep-test TkxSelect, TkxDatePicker, TkxMenu, TkxOrgChart, TkxTreeView.
• v3.20 (target 2026-10-15) — "Forms + i18n depth." Zod + Valibot resolvers for TkxForm, RHF adapter, drop hardcoded-string count below 100, ship 9 new locales (35 → 44).
• v3.21 (target 2026-12-01) — "Charts + visualizations." New TkxHeatmap, TkxFunnelChart, TkxTreemap, TkxGauge, TkxSparkline.
• v4.0 (target 2026-12 to 2027-Q1) — "Stable." Third-party AAA VPAT published, 90/90/85 coverage, 70+ locales, 5 published case studies, React 19 required, codemod for the v3 → v4 migration.

Read the full plan, what we WILL NOT do, and how to propose changes → docs/ROADMAP.md

Bug Reports & Issues

Found a bug or have a feature request? Please open an issue on our dedicated issue tracker:

👉 github.com/007krcs/tekivex-ui/issues

When reporting, please include:

• tekivex-ui version (npm list tekivex-ui)
• React version
• Browser / Node version
• A minimal reproduction (CodeSandbox or code snippet)

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a PR.

Maintainers: 007krcs · seemaalmas · novaai0401-ui

License

MIT © 2026 007krcs