@yuktishaalaa/yuktai 5.1.0 → 5.3.0

package/README.md

@@ -1,14 +1,15 @@
 # @yuktishaalaa/yuktai
 
-> Universal Next.js plugin for accessibility, AI, and data. One install brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, and an accessible data grid with Agentic AI + WebMCP. Zero API keys, zero cost, works offline.
+> Universal accessibility, AI and data toolkit for Next.js, React **and plain HTML**. One install (or one script tag) brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, an accessible data grid with Agentic AI + WebMCP, and an agentic toolkit that audits, explains and fixes pages and answers questions about your data. Zero API keys, zero cost, works offline.
 
 [![npm](https://img.shields.io/npm/v/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
 [![downloads](https://img.shields.io/npm/dm/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
-[![license](https://img.shields.io/badge/license-ISC-brightgreen)](./LICENSE)
+[![license](https://img.shields.io/badge/license-GPL--3.0-blue)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D18-blue)](https://nodejs.org)
 [![Next.js](https://img.shields.io/badge/Next.js-13%2B-black)](https://nextjs.org)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/sandeepmiriyala03/badge.svg)](https://hub.xerj.org/contributors/sandeepmiriyala03)
 
-**7,000+ developers** have already installed yuktai. Built entirely in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03).
+Built in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03).
 
 **Live demos:**
 - Staff directory: https://aksharatantra.miriyala.in/staffdirectory
@@ -28,7 +29,7 @@ So I built yuktai, one weekend and one late night at a time.
 
 ## What's inside
 
-Five modules ship in a single npm package:
+Six modules ship in a single npm package, for React/Next.js and, since v5.3, for plain HTML pages with one script tag:
 
 | Module | Features | What it does |
 |---|---|---|
@@ -37,6 +38,180 @@ Five modules ship in a single npm package:
 | **3. In-Tab RAG** | 11 | Ask questions about any page, offline, no API |
 | **4. Autonomous AI Agent** | 13 | Natural-language browser guidance |
 | **5. Vibe Coder** | 19 | Generate full Next.js projects from plain English |
+| **6. Agentic AI Toolkit** | 10 | Accessibility copilot, QA reports, form and design review, smart grid queries, BI answers, multi-step tasks, voice settings |
+| **Vanilla JS build** 🆕 | All | Every module above for plain HTML, CSS and JavaScript: no React, no build step |
+
+---
+
+## What's new in v5.3: Vanilla JS (plain HTML)
+
+All of yuktai now works on any HTML page, without React or a build step. The vanilla build is bundled from the same source as the npm package, so a question gets the same answer in React and in plain HTML.
+
+```html
+<script>
+  window.YUKTAI_CONFIG = { position: "right", showPageTools: true }  // optional
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@yuktishaalaa/yuktai@5.3.0/vanilla/index.min.js"></script>
+
+<div id="staff"></div>
+<script>
+  const grid = yuktai.renderGrid("#staff", {
+    data: rows,
+    rowKey: "id",
+    columns: [
+      { key: "name", label: "Name" },
+      { key: "salary", label: "Salary", type: "number" },
+      { key: "joined", label: "Joined", type: "date" },
+    ],
+    agentic: true,          // question bar: "salary over 1 lakh", "average salary by department"
+    ai: true,               // assistant: custom rules, phrases, grid tools, voice input
+    locale: "en-IN",        // or "te-IN" for Telugu UI and messages
+    webmcp: true,
+  })
+
+  await grid.ask("salary over 1 lakh in Hyderabad")
+  yuktai.mountAgenticPanel("#tools", { defaultTab: "qa" })   // Copilot, QA, Forms, Design, Ask, Voice
+</script>
+```
+
+| React / Next.js | Vanilla JS |
+|---|---|
+| `<YuktaiGrid>` | `yuktai.renderGrid(container, options)` |
+| `useAgenticGrid` + `<AgenticGridBar>` | `yuktai.createAgenticGrid()` + `yuktai.mountAgenticGridBar()`, or `agentic: true` |
+| `useYuktaiGridAgent` | `yuktai.createGridAgent()` |
+| `<YuktaiGridWebMCP>` | `yuktai.registerWebMCP()`, or `webmcp: true` |
+| `<AgenticPanel>` | `yuktai.mountAgenticPanel()` |
+| `<YuktAIWrapper>` | Automatic floating ♿ button (and 🛠 page tools with `showPageTools: true`) |
+| Every function (`runQaAudit`, `askInsight`, `parseAmount`, …) | Same names on `window.yuktai` |
+
+**Grid features in the vanilla build:**
+- search, sort, page-size switching, row selection and CSV export (Excel-safe)
+- table, card or auto view; 5 WCAG themes; Telugu UI
+- loading and empty states; row highlighting that scrolls to the row
+- ARIA grid keyboard navigation: arrow keys, Home/End, Page Up/Down, Space to select, Enter to open
+
+**Tested** in Chromium: 37 end-to-end checks pass, with axe-core reporting 0 violations and no console errors. Open `vanilla/index.html` in the repo for a demo of every feature, including a Telugu grid. Full API: [`vanilla/README.md`](./vanilla/README.md).
+
+### Accessibility engine fixes in v5.3 (React and vanilla)
+
+- Auto-fix no longer adds an `aria-label` to form fields that already have a `<label>`. Before this, it replaced the name that screen readers announce.
+- Buttons and links hidden at scan time are no longer labelled "button" or "link".
+- `<header>` and `<footer>` inside sections and dialogs no longer become page-level banner and contentinfo landmarks.
+- The fix count only includes fixes that were actually applied.
+- Visual alert colours now meet a 4.5:1 contrast ratio.
+
+---
+
+## What's new in v5.2: Agentic AI Toolkit
+
+Ten agentic features, all running in the browser. No API keys, and no page or grid data leaves the device unless you plug in your own model through a `generate` or `summarize` hook.
+
+| # | Feature | What it does | Main export |
+|---|---|---|---|
+| 1 | Accessibility Copilot | Watches the page live, explains each issue in plain English, applies safe fixes and undoes them | `createA11yCopilot` |
+| 2 | Page Understanding | Answers "What does this page do?" and "Which form fields are missing labels?" | `analyzePage`, `askAboutPage` |
+| 3 | Smart Data Grid | Turns "overdue and over ₹10,000" into real filters, finds unusual rows, summarises data | `runGridQuery`, `detectAnomalies`, `summarizeRows` |
+| 4 | Voice Accessibility | "Turn on high contrast", "bigger text", "next row", plus Telugu phrases like "పెద్ద అక్షరాలు" | `createVoiceA11yController` |
+| 5 | QA Tester | 15 checks with WCAG references, a score, pass/fail, and a Markdown or JSON report | `runQaAudit`, `auditToMarkdown` |
+| 6 | Forms Agent | Reviews labels, autocomplete, error messages and senior-friendliness | `reviewForms` |
+| 7 | Page + Data RAG | Answers from page text and grid rows, Telugu-aware, offline | `createContextIndex` |
+| 8 | Multi-Step Tasks | "Show overdue, highlight the errors, then summarise what changed" | `runTasks` |
+| 9 | BI Copilot | "Which region had the highest drop in conversion this week?" | `askInsight`, `comparePeriods` |
+| 10 | Design Review | Hierarchy, readability, focus states, clutter, consistency | `reviewDesign` |
+
+### Page tools in one panel
+
+```tsx
+"use client";
+import { AgenticPanel } from "@yuktishaalaa/yuktai";
+
+export default function A11yTools() {
+  return <AgenticPanel defaultTab="copilot" voiceLang="en-IN" />;
+}
+```
+
+Tabs: **Copilot**, **QA report**, **Forms**, **Design**, **Ask page**, **Voice**. The panel marks itself with `data-yuktai-panel`, so it never audits its own UI.
+
+### Ask your grid
+
+```tsx
+"use client";
+import { YuktaiGrid, useAgenticGrid, AgenticGridBar } from "@yuktishaalaa/yuktai";
+
+const columns = [
+  { key: "name", label: "Customer" },
+  { key: "status", label: "Status" },
+  { key: "region", label: "Region" },
+  { key: "balance", label: "Balance", type: "number" as const },
+  { key: "dueDate", label: "Due date", type: "date" as const },
+];
+
+export default function Customers({ rows }: { rows: Customer[] }) {
+  const grid = useAgenticGrid({ data: rows, columns, rowKey: "id" });
+
+  return (
+    <>
+      <AgenticGridBar
+        grid={grid}
+        examples={[
+          "overdue and over ₹10,000",
+          "anything unusual?",
+          "total balance by region",
+          "show overdue, then sort by balance desc, then summarize what changed",
+        ]}
+      />
+      <YuktaiGrid
+        data={grid.gridData}
+        columns={columns}
+        rowKey="id"
+        highlightIds={grid.highlightIds}
+        autoScrollToHighlight
+      />
+    </>
+  );
+}
+```
+
+`grid.ask(text)` picks the right tool for the question:
+
+| Question type | Example | Handled by |
+|---|---|---|
+| Filters and lookups | "customer starting with A and balance between 1k and 9k" | Smart grid query |
+| Unusual data | "anything unusual?" | Outliers and duplicate rows |
+| Group and period questions | "which region had the highest drop in conversion this week?" | BI copilot |
+| Several steps | "show overdue, then highlight errors, then summarise" | Task runner, with a before/after report |
+
+Amounts like `₹10,000`, `10k`, `1.5 lakh` and `2 crore` are understood.
+
+### Use the functions directly
+
+```ts
+import { runQaAudit, auditToMarkdown, askInsight, runGridQuery } from "@yuktishaalaa/yuktai";
+
+// In the browser: accessibility QA report
+const report = runQaAudit();
+console.log(report.score, report.passed);
+const md = auditToMarkdown(report); // attach to a ticket or PR
+
+// Anywhere: data questions
+askInsight("which region had the highest drop in conversion this week", rows, columns).answer;
+runGridQuery("overdue and over 10k", { data: rows, columns }).ids;
+```
+
+### Plug in your own model (optional)
+
+Everything works offline with rules and keyword search. To get model-written answers, pass a `generate` hook, for example Gemini Nano or your own API:
+
+```tsx
+<AgenticPanel generate={async (question, context) => myModel(question, context)} />
+```
+
+### Honest limits
+
+- Questions are understood with rules, not a language model, so unusual phrasing may need rewording. The parser returns `notes` explaining any assumption it made.
+- The QA and design checks are automatic heuristics. They catch common problems but don't replace testing with real users and assistive technology.
+- Smart grid queries, page answers and BI answers are in English today. Telugu and Hindi data questions are not parsed yet; use `customRules` with your own phrases for them.
+- Voice accessibility commands understand English and Telugu, not yet Hindi or other languages.
 
 ---
 
@@ -59,7 +234,7 @@ Five modules ship in a single npm package:
 
 | Device | Browser | Core features | AI engine |
 |---|---|---|---|
-| 🖥 Desktop | Chrome 147+ | ✅ All | Gemini Nano |
+| 🖥 Desktop | Chrome 147+ (needed only for Gemini Nano) | ✅ All | Gemini Nano |
 | 🖥 Desktop | Firefox / Edge / Safari | ✅ All | Transformers.js |
 | 📱 Android | Chrome Mobile | ✅ All | Transformers.js |
 | 📱 iOS | Safari Mobile | ✅ All | Transformers.js |
@@ -90,7 +265,13 @@ yarn add @yuktishaalaa/yuktai
 pnpm add @yuktishaalaa/yuktai
 ```
 
-Requirements: Node.js 18+, npm 8+, Next.js 13+.
+**Plain HTML (no install)**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@yuktishaalaa/yuktai@5.3.0/vanilla/index.min.js"></script>
+```
+
+Requirements: Node.js 18+, npm 8+, Next.js 13+ (React builds only; the vanilla build needs only a browser).
 
 ---
 
@@ -160,6 +341,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 That's it. Floating buttons appear on every page: ♿ opens the accessibility panel, 💬 opens "Ask this page", and the agent button opens the AI agent.
 
+To add the v5.2 agentic tools, place `<AgenticPanel />` or `useAgenticGrid` in any client component (see [What's new in v5.2](#whats-new-in-v52-agentic-ai-toolkit)).
+
 ### Wrapper props
 
 | Prop | Type | Default | Description |
@@ -278,6 +461,7 @@ export default function EmployeesPage() {
 - Keyboard navigation, ARIA grid semantics, 44×44 targets
 - English and Telugu UI
 - Embedded Grid AI Assistant with voice and chat
+- **New in v5.2:** compound natural-language questions, anomaly detection and BI answers through `useAgenticGrid`
 
 ### Grid AI Assistant
 
@@ -290,7 +474,7 @@ Runs embedded in the grid or as a standalone component. Intent parsing runs loca
   onSearch={handleSearch}
   onSort={handleSort}
   language="te-IN" // AI UI and responses: en-US | te-IN
-  inputLanguage="te-IN" // voice input: en-US | te-IN
+  inputLanguage="te-IN" // voice input: en-IN, en-US or any of the 22 Indian languages
   embedded
 />
 ```
@@ -485,6 +669,8 @@ Retrieval-Augmented Generation running entirely in the browser. It extracts text
 
 **What I learned:** Transformers.js kept crashing on iOS Safari with out-of-memory errors. Quantization (same model, 75% smaller) fixed it. DistilBERT gave short, useless spans; `flan-t5-small` gives real sentences.
 
+**New in v5.2:** `createContextIndex` also searches grid rows (including rows on other pages of the grid) and your own documents, with keyword search that handles Telugu and Hindi script correctly.
+
 ---
 
 ## Module 4: Autonomous AI Agent
@@ -514,6 +700,19 @@ No AI writes the code. It's pure template engineering.
 
 ---
 
+## Module 6: Agentic AI Toolkit 🆕
+
+The ten v5.2 features, described in detail in [What's new in v5.2](#whats-new-in-v52-agentic-ai-toolkit).
+
+- **Copilot and QA:** 15 WCAG checks, plain-English explanations, safe fixes with undo, downloadable reports
+- **Forms and design review:** labels, autocomplete, error messages, focus states, hierarchy, clutter, senior-friendly tips
+- **Data:** compound grid questions, outliers and duplicates, group-by, period comparison, trends
+- **Automation:** multi-step instructions with a before/after summary
+- **Voice:** accessibility settings and grid row navigation by voice, in English and Telugu
+- **React:** `AgenticPanel`, `AgenticGridBar`, `useAgenticGrid`
+
+---
+
 ## Gemini Nano setup (desktop Chrome, one time)
 
 Needed only for Gemini Nano features on desktop Chrome. Mobile and other browsers use Transformers.js automatically.
@@ -556,9 +755,10 @@ Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (def
 
 - **Zero API keys, zero cost, zero telemetry.** Everything runs in the browser.
 - **Zero injected ids.** Injected nodes are tracked by JavaScript references, so they never collide with your app's ids.
-- **Zero framework lock-in.** `core/renderer.ts` has no framework imports.
+- **Zero framework lock-in.** `core/renderer.ts` has no framework imports, and the vanilla build runs on any HTML page.
 - **Never reads its own UI.** Panels are marked with `data-yuktai-panel`.
 - **SSR safe.** No `window` errors on the server.
+- **Every automatic fix can be undone.** The v5.2 copilot records each change it makes.
 - **Honest limits.** Client-side pagination is for a few thousand rows; use server-side beyond that.
 
 ---
@@ -568,6 +768,7 @@ Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (def
 | | Supported |
 |---|---|
 | Next.js | 13, 14, 15, 16 |
+| Plain HTML | Any page, one script tag (vanilla build) |
 | React | 17, 18, 19 (19 needs `--legacy-peer-deps`) |
 | Node.js | 18+ |
 | Browsers | Chrome 90+, Firefox 90+, Safari 15+, Edge 90+, Samsung Internet 14+ |
@@ -576,8 +777,10 @@ Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (def
 
 ## Roadmap
 
+- **Shipped (v5.3):** Vanilla JS build of every module for plain HTML pages, plus accessibility engine fixes
+- **Shipped (v5.2):** Agentic AI Toolkit: accessibility copilot, QA reports, form and design review, smart grid queries, BI answers, multi-step tasks, page + data RAG, voice accessibility commands
 - **Shipped (v4.6.4):** YuktaiGrid Agentic AI + WebMCP, embedded Grid AI Assistant, English/Telugu UI, page-size switching, icon polish
-- **Next:** more Grid Agent tools and WebMCP capabilities, multilingual RAG (Telugu, Hindi, Tamil, Bengali)
+- **Next:** expose the v5.2 agentic tools through WebMCP, more Grid Agent tools, multilingual RAG (Telugu, Hindi, Tamil, Bengali)
 - **Later:** RTL support, richer browser-native AI, multimodal grid experiences
 
 ---
@@ -594,13 +797,14 @@ Issues and pull requests are welcome at [github.com/sandeepmiriyala03/yuktai](ht
 - GitHub: [sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai)
 - Demo: [aksharatantra.miriyala.in/staffdirectory](https://aksharatantra.miriyala.in/staffdirectory)
 - Showcase: [ratnalabala.vercel.app](https://ratnalabala.vercel.app/poems?view=grid)
+- Vanilla JS (CDN): [cdn.jsdelivr.net/npm/@yuktishaalaa/yuktai/vanilla/index.min.js](https://cdn.jsdelivr.net/npm/@yuktishaalaa/yuktai/vanilla/index.min.js)
 
 ---
 
 ## License
 
-ISC © Sandeep Miriyala, [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
+GPL-3.0 © Sandeep Miriyala, [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
 
-Built in free time, with help from Claude, GPT, and Gemini for learning. Every line written, every bug fixed, and every decision made by me.
+Built in free time. AI coding assistants (Claude, GPT and Gemini) helped me learn, and helped write and test parts of the code. Every design decision, review and release is mine.
 
-**Free forever. Open source. Built for every user.** 🏺
+**Free forever. Open source. Built for every user.**