@vertesia/ui 0.81.1 → 1.0.0-dev.20260203.130115Z

package/llms.txt

@@ -0,0 +1,494 @@
+# @vertesia/ui Component Library for LLMs
+
+> React component library for building Vertesia UI plugins and applications.
+> This file documents component APIs and usage patterns for AI assistants.
+
+## Installation
+
+```bash
+npm install @vertesia/ui
+# or
+pnpm add @vertesia/ui
+```
+
+## Import Paths
+
+```tsx
+// Core components (buttons, cards, inputs, modals, tabs)
+import { Button, Card, Input, VModal, VTabs } from '@vertesia/ui/core';
+
+// Hooks (data fetching, toasts)
+import { useFetch, useToast } from '@vertesia/ui/core';
+
+// Router (navigation, nested routing for plugins)
+import { useNavigate, useParams, NavLink, NestedRouterProvider } from '@vertesia/ui/router';
+
+// Session (authentication, Vertesia client access)
+import { useUserSession } from '@vertesia/ui/session';
+
+// Layout components
+import { FullHeightLayout } from '@vertesia/ui/layout';
+
+// Feature components (headers, navigation)
+import { GenericPageNavHeader } from '@vertesia/ui/features';
+```
+
+---
+
+# Component API Reference
+
+## Input (Simplified API)
+
+**IMPORTANT:** Input passes the value directly to onChange, NOT an event object.
+
+```tsx
+interface InputProps {
+  value?: string;
+  onChange?: (value: string) => void;  // Value directly, not event!
+  placeholder?: string;
+  disabled?: boolean;
+  clearable?: boolean;  // Shows X button to clear (default: true)
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  variant?: 'default' | 'unstyled' | 'noPadding' | 'legacy';
+}
+
+// Usage - pass setState directly
+<Input value={name} onChange={setName} />
+
+// Or with transformation
+<Input value={name} onChange={(value) => setName(value.trim())} />
+
+// WRONG - this will NOT work:
+<Input onChange={(e) => setName(e.target.value)} />  // ❌ Error!
+```
+
+## Textarea (Standard React API)
+
+Textarea uses standard React event handling.
+
+```tsx
+// Standard React event object
+<Textarea
+  value={description}
+  onChange={(e) => setDescription(e.target.value)}
+/>
+```
+
+## Button
+
+```tsx
+interface ButtonProps {
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+  size?: 'default' | 'sm' | 'lg' | 'icon';
+  disabled?: boolean;
+  onClick?: () => void;
+  children: React.ReactNode;
+}
+
+<Button onClick={handleClick}>Click Me</Button>
+<Button variant="outline" size="sm">Secondary</Button>
+<Button variant="destructive">Delete</Button>
+```
+
+## Card Components
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@vertesia/ui/core';
+
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Optional description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Main content here
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+## VModal (Modal Dialog)
+
+```tsx
+import { VModal, VModalTitle, VModalBody, VModalFooter } from '@vertesia/ui/core';
+
+interface VModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+}
+
+<VModal isOpen={open} onClose={() => setOpen(false)} size="md">
+  <VModalTitle description="Optional subtitle">
+    Modal Title
+  </VModalTitle>
+  <VModalBody>
+    <div className="space-y-4">
+      <Input value={name} onChange={setName} />
+    </div>
+  </VModalBody>
+  <VModalFooter>
+    <Button onClick={handleSubmit}>Submit</Button>
+    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+  </VModalFooter>
+</VModal>
+```
+
+**Note:** VModalFooter uses `flex-row-reverse`, so primary button should be first in code but appears on the right.
+
+## VTabs (Tabbed Interface)
+
+```tsx
+import { VTabs, VTabsBar, VTabsPanel } from '@vertesia/ui/core';
+
+<VTabs
+  defaultValue="tab1"
+  tabs={[
+    { name: 'tab1', label: 'First Tab', content: <Tab1Content /> },
+    { name: 'tab2', label: 'Second Tab', content: <Tab2Content /> },
+    { name: 'tab3', label: 'Third Tab', content: <Tab3Content /> },
+  ]}
+>
+  <VTabsBar />
+  <VTabsPanel />
+</VTabs>
+
+// With controlled value
+const [tab, setTab] = useState('tab1');
+<VTabs value={tab} onValueChange={setTab} tabs={[...]}>
+```
+
+## Label
+
+```tsx
+<Label htmlFor="input-id">Field Label</Label>
+<Input id="input-id" value={value} onChange={setValue} />
+```
+
+## Badge
+
+```tsx
+import { Badge } from '@vertesia/ui/core';
+
+<Badge variant="default">Default</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+## Spinner & ErrorBox
+
+```tsx
+import { Spinner, ErrorBox } from '@vertesia/ui/core';
+
+// Loading state
+if (isLoading) return <Spinner />;
+
+// Error state
+if (error) return <ErrorBox>{error.message}</ErrorBox>;
+```
+
+## Table
+
+```tsx
+import { Table, TBody, THead, Th, Tr, Td } from '@vertesia/ui/core';
+
+<Table>
+  <THead>
+    <Tr>
+      <Th>Name</Th>
+      <Th>Value</Th>
+    </Tr>
+  </THead>
+  <TBody>
+    {items.map(item => (
+      <Tr key={item.id}>
+        <Td>{item.name}</Td>
+        <Td>{item.value}</Td>
+      </Tr>
+    ))}
+  </TBody>
+</Table>
+```
+
+---
+
+# Hooks
+
+## useFetch
+
+Data fetching hook with loading, error, and refetch support.
+
+```tsx
+import { useFetch } from '@vertesia/ui/core';
+
+const { data, isLoading, error, refetch } = useFetch(
+  async () => {
+    return await client.store.collections.list();
+  },
+  [dependency1, dependency2]  // Refetch when dependencies change
+);
+
+// With options
+const { data } = useFetch(
+  fetchFn,
+  [deps],
+  {
+    onSuccess: (data) => console.log('Loaded', data),
+    onError: (err) => console.error('Failed', err),
+  }
+);
+```
+
+## useToast
+
+Show toast notifications.
+
+```tsx
+import { useToast } from '@vertesia/ui/core';
+
+const toast = useToast();
+
+// Success toast
+toast({ title: 'Success', description: 'Item created' });
+
+// Error toast
+toast({ title: 'Error', description: error.message, variant: 'destructive' });
+```
+
+## useUserSession
+
+Access authenticated user and Vertesia client.
+
+```tsx
+import { useUserSession } from '@vertesia/ui/session';
+
+const { client, user, project } = useUserSession();
+
+// client is the Vertesia API client
+const collections = await client.store.collections.list();
+```
+
+---
+
+# Router
+
+## NestedRouterProvider
+
+For plugin routing (nested within host app router).
+
+```tsx
+import { NestedRouterProvider } from '@vertesia/ui/router';
+
+const routes = [
+  { path: '/', Component: HomePage },
+  { path: '/items/:id', Component: ItemPage },
+  { path: '*', Component: NotFound },
+];
+
+<NestedRouterProvider routes={routes} index="/" />
+```
+
+## Navigation Hooks
+
+```tsx
+import { useNavigate, useParams, useSearchParams } from '@vertesia/ui/router';
+
+// Navigate programmatically
+const navigate = useNavigate();
+navigate('/items/123');
+navigate(-1);  // Go back
+
+// Get route params
+const { id } = useParams();  // From /items/:id
+
+// Get/set query params
+const [searchParams, setSearchParams] = useSearchParams();
+const query = searchParams.get('q');
+```
+
+## NavLink
+
+Navigation link component.
+
+```tsx
+import { NavLink } from '@vertesia/ui/router';
+
+<NavLink href="/items">Go to Items</NavLink>
+<NavLink href={`/items/${item.id}`}>View Item</NavLink>
+```
+
+---
+
+# Layout & Features
+
+## GenericPageNavHeader
+
+Standard page header with breadcrumbs and actions.
+
+```tsx
+import { GenericPageNavHeader } from '@vertesia/ui/features';
+import { NavLink } from '@vertesia/ui/router';
+
+<GenericPageNavHeader
+  title="Page Title"
+  description="Optional page description"
+  breadcrumbs={[
+    <NavLink href="/" key="home">Home</NavLink>,
+    <NavLink href="/items" key="items">Items</NavLink>,
+    <span key="current">Current Page</span>,
+  ]}
+  actions={
+    <Button onClick={() => setShowCreate(true)}>
+      <Plus className="w-4 h-4 mr-2" />
+      Create New
+    </Button>
+  }
+/>
+```
+
+## FullHeightLayout
+
+Full height container layout.
+
+```tsx
+import { FullHeightLayout } from '@vertesia/ui/layout';
+
+<FullHeightLayout>
+  <div>Content fills available height</div>
+</FullHeightLayout>
+```
+
+---
+
+# Styling
+
+Use Tailwind CSS with semantic color classes:
+
+```tsx
+// Status colors
+<span className="text-success">Success</span>
+<span className="text-attention">Warning</span>
+<span className="text-destructive">Error</span>
+<span className="text-muted-foreground">Muted</span>
+
+// Backgrounds with opacity
+<div className="bg-success/10 text-success">Success message</div>
+<div className="bg-destructive/10 text-destructive">Error message</div>
+
+// Common layout patterns
+<div className="p-4 space-y-4">         {/* Padding + vertical spacing */}
+<div className="flex items-center gap-2"> {/* Horizontal flex */}
+<div className="grid grid-cols-3 gap-4">  {/* Grid layout */}
+```
+
+---
+
+# Common Patterns
+
+## Form with Input and Textarea
+
+```tsx
+function MyForm() {
+  const [name, setName] = useState('');
+  const [description, setDescription] = useState('');
+
+  return (
+    <form className="space-y-4">
+      <div>
+        <Label htmlFor="name">Name</Label>
+        <Input id="name" value={name} onChange={setName} />
+      </div>
+      <div>
+        <Label htmlFor="desc">Description</Label>
+        <Textarea
+          id="desc"
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+        />
+      </div>
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+```
+
+## Data List with Loading/Error States
+
+```tsx
+function ItemList() {
+  const { client } = useUserSession();
+  const { data, isLoading, error, refetch } = useFetch(
+    () => client.store.collections.list(),
+    []
+  );
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorBox>{error.message}</ErrorBox>;
+
+  return (
+    <div className="space-y-2">
+      {data?.map(item => (
+        <Card key={item.id}>
+          <CardHeader>
+            <CardTitle>{item.name}</CardTitle>
+          </CardHeader>
+        </Card>
+      ))}
+    </div>
+  );
+}
+```
+
+## Modal with Form
+
+```tsx
+function CreateModal({ open, onClose, onCreated }) {
+  const [name, setName] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const { client } = useUserSession();
+  const toast = useToast();
+
+  const handleSubmit = async () => {
+    setIsSubmitting(true);
+    try {
+      await client.store.collections.create({ name });
+      toast({ title: 'Created successfully' });
+      onCreated();
+      onClose();
+    } catch (err) {
+      toast({ title: 'Error', description: err.message, variant: 'destructive' });
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <VModal isOpen={open} onClose={onClose} size="md">
+      <VModalTitle>Create Item</VModalTitle>
+      <VModalBody>
+        <Label>Name</Label>
+        <Input value={name} onChange={setName} disabled={isSubmitting} />
+      </VModalBody>
+      <VModalFooter>
+        <Button onClick={handleSubmit} disabled={!name || isSubmitting}>
+          {isSubmitting ? 'Creating...' : 'Create'}
+        </Button>
+        <Button variant="outline" onClick={onClose}>Cancel</Button>
+      </VModalFooter>
+    </VModal>
+  );
+}
+```
+
+---
+
+# Key Differences from Standard React
+
+1. **Input onChange** passes value directly: `onChange={setValue}` not `onChange={(e) => setValue(e.target.value)}`
+2. **Textarea onChange** uses standard React events
+3. **VModalFooter** uses flex-row-reverse (primary button first in code, appears right)
+4. **NestedRouterProvider** for plugin routing (instead of BrowserRouter)
+5. **useUserSession** provides pre-authenticated Vertesia client

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vertesia/ui",
-  "version": "0.81.1",
+  "version": "1.0.0-dev.20260203.130115Z",
   "description": "Vertesia UI components and and hooks",
   "type": "module",
   "main": "./lib/index.js",
   "files": [
     "lib",
     "src",
-    "tsconfig.dist.json"
+    "tsconfig.dist.json",
+    "llms.txt"
   ],
   "license": "Apache-2.0",
   "homepage": "https://docs.vertesiahq.com",
@@ -21,7 +22,7 @@
   "dependencies": {
     "@floating-ui/dom": "^1.7.1",
     "@floating-ui/react": "^0.27.11",
-    "@headlessui/react": "^2.2.2",
+    "@headlessui/react": "^2.2.9",
     "@monaco-editor/react": "^4.7.0",
     "@radix-ui/react-checkbox": "^1.3.1",
     "@radix-ui/react-dialog": "^1.1.13",
@@ -31,11 +32,12 @@
     "@radix-ui/react-slot": "^1.2.2",
     "@radix-ui/react-tabs": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.6",
-    "ajv": "^8.16.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "dayjs": "^1.11.13",
+    "dayjs": "^1.11.19",
     "debounce": "^2.2.0",
     "fast-xml-parser": "^5.2.3",
     "firebase": "^10.12.2",
@@ -43,10 +45,12 @@
     "html-to-image": "^1.11.13",
     "json-schema": "^0.4.0",
     "jwt-decode": "^4.0.0",
-    "lodash-es": "^4.17.21",
+    "lodash-es": "^4.17.23",
     "lucide-react": "^0.562.0",
+    "mermaid": "^11.4.0",
     "monaco-editor": "^0.52.2",
     "motion": "^12.12.1",
+    "papaparse": "^5.5.3",
     "react": "^19.2.3",
     "react-calendar": "^6.0.0",
     "react-date-picker": "^12.0.1",
@@ -55,23 +59,30 @@
     "react-markdown": "^10.1.0",
     "react-pdf": "^10.2.0",
     "react-resizable-panels": "^3.0.6",
+    "react-vega": "^8.0.0",
     "recharts": "^3.5.0",
     "remark-gfm": "^4.0.1",
-    "tailwind-merge": "^3.3.0",
+    "tailwind-merge": "^3.4.0",
     "ts-md5": "^1.3.1",
     "unist-util-visit": "^5.0.0",
-    "@vertesia/common": "0.81.1",
-    "@vertesia/json": "0.81.1",
-    "@vertesia/client": "0.81.1"
+    "vega": "^6.2.0",
+    "vega-embed": "^7.1.0",
+    "vega-lite": "^6.4.1",
+    "@vertesia/common": "1.0.0-dev.20260203.130115Z",
+    "@vertesia/fusion-ux": "1.0.0-dev.20260203.130115Z",
+    "@vertesia/client": "1.0.0-dev.20260203.130115Z",
+    "@vertesia/json": "1.0.0-dev.20260203.130115Z"
   },
   "devDependencies": {
     "@eslint/js": "^9.27.0",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
+    "@types/hast": "^3.0.4",
     "@types/json-schema": "^7.0.15",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^22.15.21",
+    "@types/node": "^22.19.2",
+    "@types/papaparse": "^5.5.2",
     "@types/react": "^19.2.3",
     "@types/react-dom": "^19.2.3",
     "eslint": "^9.27.0",
@@ -79,12 +90,12 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.40.2",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.3",
     "rollup-plugin-terser": "^7.0.2",
-    "typescript": "~5.8.3",
-    "typescript-eslint": "^8.38.0",
-    "vitest": "^3.0.9"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0",
+    "vitest": "^4.0.16"
   },
   "exports": {
     "./router": {

package/src/core/components/InputList.tsx

@@ -1,7 +1,7 @@
 import clsx from 'clsx';
 import React, { useState } from 'react';
 
-import { Badge } from './Badge';
+import { Badge } from './shadcn/badge';
 import { Input } from './shadcn/input';
 import { VTooltip } from '@vertesia/ui/core';
 

package/src/core/components/Overlay.tsx

@@ -2,7 +2,7 @@ import { motion } from "framer-motion"
 import { X } from "lucide-react"
 import { useState, ReactNode } from "react"
 
-import { Button } from "./Button"
+import { Button } from "./shadcn/button"
 
 interface OverlayProps {
     children: ReactNode

package/src/core/components/SidePanel.tsx

@@ -10,8 +10,11 @@ interface SidePanelProps {
     title?: string;
     panelWidth?: number;
     backdrop?: boolean;
+    side?: 'left' | 'right';
+    resizable?: boolean;
+    className?: string;
 }
-export function SidePanel({ isOpen, title, onClose, children, panelWidth = 768, backdrop = false }: SidePanelProps) {
+export function SidePanel({ isOpen, title, onClose, children, panelWidth = 768, backdrop = false, side = 'right', resizable = true, className }: SidePanelProps) {
     const [_panelWidth, setPanelWidth] = useState(panelWidth);
 
     const handleDragStart = (e: React.MouseEvent) => {
@@ -39,6 +42,13 @@ export function SidePanel({ isOpen, title, onClose, children, panelWidth = 768,
         document.addEventListener('mouseup', handleMouseUp);
     };
 
+    const isLeft = side === 'left';
+    const positionClass = isLeft ? 'left-0' : 'right-0';
+    const paddingClass = isLeft ? 'pr-10 sm:pr-16' : 'pl-10 sm:pl-16';
+    const borderClass = isLeft ? 'border-r' : 'border-l';
+    const dragHandleClass = isLeft ? '-right-1' : '-left-1';
+    const initialX = isLeft ? "-100%" : "100%";
+
     return (
         <AnimatePresence>
             {isOpen && (
@@ -54,26 +64,28 @@ export function SidePanel({ isOpen, title, onClose, children, panelWidth = 768,
                         />
                     )}
 
-                    <div className="fixed inset-y-0 right-0 overflow-hidden">
+                    <div className={`fixed inset-y-0 ${positionClass} overflow-hidden`}>
                         <div className="absolute inset-0 overflow-hidden">
-                            <div className="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
+                            <div className={`pointer-events-none fixed inset-y-0 ${positionClass} flex max-w-full ${paddingClass}`}>
                                 <motion.div
-                                    className="pointer-events-auto border-l"
+                                    className={`pointer-events-auto ${borderClass}`}
                                     style={{ width: `${_panelWidth}px` }}
-                                    initial={{ x: "100%" }}
+                                    initial={{ x: initialX }}
                                     animate={{ x: 0 }}
-                                    exit={{ x: "100%" }}
+                                    exit={{ x: initialX }}
                                     transition={{ type: "spring", stiffness: 300, damping: 30 }}
                                 >
                                     <div className="relative flex h-full">
                                         {/* Drag Handle */}
-                                        <div
-                                            className="absolute -left-1 top-0 bottom-0 w-3 cursor-ew-resize hover:bg-indigo-500 transition-colors flex items-center justify-center"
-                                            onMouseDown={handleDragStart}
-                                        >
-                                            <Minus className="rotate-90 font-semibold" strokeWidth={4} />
-                                        </div>
-                                        <div className="flex-1 flex flex-col overflow-y-scroll gap-4 bg-background py-2 shadow-xl">
+                                        {resizable && (
+                                            <div
+                                                className={`absolute ${dragHandleClass} top-0 bottom-0 w-3 cursor-ew-resize hover:bg-indigo-500 transition-colors flex items-center justify-center`}
+                                                onMouseDown={handleDragStart}
+                                            >
+                                                <Minus className="rotate-90 font-semibold" strokeWidth={4} />
+                                            </div>
+                                        )}
+                                        <div className={`flex-1 flex flex-col overflow-y-scroll gap-4 bg-background py-2 shadow-xl ${className}`}>
                                             {title && (
                                                 <div className="px-2 sm:px-4">
                                                     <div className="flex items-start justify-between">