@gram-ai/elements 1.25.2 → 1.26.0

package/src/plugins/generative-ui/index.ts

@@ -7,147 +7,26 @@ import { GenerativeUIRenderer } from './component'
  */
 export const generativeUI: Plugin = {
   language: 'ui',
-  prompt: `WHEN TO USE UI VISUALIZATION:
-Proactively render tool results and structured data as visual UI components whenever it would improve comprehension. Use the 'ui' code block format for:
-- Tool results that return structured data (lists, objects, metrics)
-- Data that benefits from visual hierarchy (dashboards, summaries)
-- Information with multiple related fields (user profiles, order details)
-- Anything with numbers, statuses, or progress that can be visualized
-- Results that would otherwise be displayed as raw JSON or verbose text
-
-Do NOT use UI for: simple text responses, single values, error messages, or when the user explicitly asks for raw data.
-
-To render UI, output a json-render specification in a code block with the language identifier 'ui'.
-
-CRITICAL JSON REQUIREMENTS:
-- The code block MUST contain ONLY valid, parseable JSON
-- NO comments (no // or /* */ anywhere)
-- NO trailing commas
-- Use double quotes for all strings and keys
-- The JSON must start with { and end with }
-
-AVAILABLE COMPONENTS:
-
-Card - Container with optional title
-  props: { title?: string }
-  children: any components
-
-Grid - Multi-column layout
-  props: { columns?: number } (default: 2)
-  children: any components
-
-Stack - Vertical or horizontal flex layout
-  props: { direction?: "vertical" | "horizontal" } (default: "vertical")
-  children: any components
-
-Metric - Displays a label and formatted value
-  props: { label: string, value: number, format?: "currency" | "percent" | "number" }
-
-Table - Data table
-  props: { headers: string[], rows: any[][] }
-
-Text - Text with variants
-  props: { content: string, variant?: "heading" | "body" | "caption" | "code" }
-
-Badge - Status badge
-  props: { content: string, variant?: "default" | "success" | "warning" | "error" }
-
-Progress - Progress bar
-  props: { value: number, max?: number, label?: string }
-
-List - Bullet or numbered list
-  props: { items: string[], ordered?: boolean }
-
-Divider - Horizontal line separator
-
-ActionButton - Interactive button that triggers a tool call
-  props: {
-    label: string,           // Button text
-    action: string,          // Tool name to invoke when clicked
-    args?: object,           // Arguments to pass to the tool
-    variant?: "default" | "secondary" | "outline" | "destructive"
-  }
-  NOTE: Only use ActionButton with tools you know are available
-
-STRUCTURE:
-Every UI spec is a tree with:
-- "type": component name (required)
-- "props": component properties (optional)
-- "children": array of child components (optional)
-
-EXAMPLE - DASHBOARD:
-{
-  "type": "Card",
-  "props": { "title": "Sales Overview" },
-  "children": [
-    {
-      "type": "Grid",
-      "props": { "columns": 3 },
-      "children": [
-        { "type": "Metric", "props": { "label": "Revenue", "value": 125000, "format": "currency" } },
-        { "type": "Metric", "props": { "label": "Growth", "value": 0.15, "format": "percent" } },
-        { "type": "Metric", "props": { "label": "Orders", "value": 1420, "format": "number" } }
-      ]
-    },
-    { "type": "Divider" },
-    { "type": "Progress", "props": { "label": "Q1 Target", "value": 75, "max": 100 } }
-  ]
-}
-
-EXAMPLE - TABLE:
-{
-  "type": "Card",
-  "props": { "title": "Users" },
-  "children": [
-    {
-      "type": "Table",
-      "props": {
-        "headers": ["Name", "Email", "Status"],
-        "rows": [
-          ["Alice", "alice@example.com", "Active"],
-          ["Bob", "bob@example.com", "Pending"]
-        ]
-      }
-    }
-  ]
-}
-
-EXAMPLE - WITH ACTIONS:
-{
-  "type": "Card",
-  "props": { "title": "Pending Request #123" },
-  "children": [
-    { "type": "Text", "props": { "variant": "body" }, "children": [{ "type": "Text", "props": {}, "children": [] }] },
-    {
-      "type": "Stack",
-      "props": { "direction": "horizontal" },
-      "children": [
-        { "type": "ActionButton", "props": { "label": "Approve", "action": "approve_request", "args": { "id": 123 } } },
-        { "type": "ActionButton", "props": { "label": "Reject", "action": "reject_request", "args": { "id": 123 }, "variant": "destructive" } }
-      ]
-    }
-  ]
-}
-
-STYLE GUIDELINES:
-- Prefer spacious, breathable layouts with adequate visual hierarchy
-- Use Grid with 2-3 columns max for metrics; avoid cramming too many items
-- Group related content in Cards with clear titles
-- Use Dividers to separate logical sections
-- Balance information density: show what matters, hide the noise
-- For dashboards, lead with the most important metrics at the top
-
-CONTENT GUIDELINES:
-- Outside the code block, provide context and insights about the data
-- Do not describe technical implementation details
-- Focus on what the data means, not how it's displayed
-
-ACTION RESULT HANDLING:
-When you receive a message starting with "[Action completed]" or "[Action failed]", the user clicked an action button and the tool has already been executed. Provide a brief, friendly acknowledgment of what happened. Keep your response concise - one sentence is usually enough. Do not re-execute the action or ask if they want to do something they just did.
-
-Examples:
-- "[Action completed] approve_request: Request #123 approved" → "Done! Request #123 has been approved."
-- "[Action failed] delete_task: Permission denied" → "I couldn't delete that task - looks like you don't have permission."`,
+  prompt: `Render structured data as visual UI using \`\`\`ui code blocks with valid JSON.
+
+Components:
+- Card{title?} - container with border
+- Grid{columns?} - multi-column layout
+- Stack{direction?} - vertical/horizontal flex
+- Metric{label,value,format?} - formatted number display (currency/percent/number)
+- Table{headers[],rows[][]} - data table
+- Text{content,variant?} - heading/body/caption/code
+- Badge{content,variant?} - default/success/warning/error
+- Progress{value,max?,label?} - progress bar
+- List{items[],ordered?} - bullet/numbered list
+- Divider - horizontal separator
+- ActionButton{label,action,args?} - triggers tool call
+
+Format: {"type":"Name","props":{...},"children":[...]}
+
+Example: {"type":"Card","props":{"title":"Stats"},"children":[{"type":"Metric","props":{"label":"Revenue","value":50000,"format":"currency"}}]}
+
+Use for dashboards, tables, metrics from tool results. Skip for simple text or errors.`,
   Component: GenerativeUIRenderer,
   Header: undefined,
 }

package/src/plugins/generative-ui/ui/accordion-wrapper.tsx

@@ -0,0 +1,57 @@
+'use client'
+
+import * as React from 'react'
+import {
+  Accordion as AccordionPrimitive,
+  AccordionItem as AccordionItemPrimitive,
+  AccordionTrigger,
+  AccordionContent,
+} from './accordion'
+
+export interface AccordionWrapperProps {
+  type?: 'single' | 'multiple'
+  children?: React.ReactNode
+}
+
+/**
+ * Accordion wrapper that adapts the compound Accordion to the catalog's props-based API.
+ */
+export function AccordionWrapper({
+  type = 'single',
+  children,
+}: AccordionWrapperProps) {
+  // Type assertion needed because Radix types are complex
+  const AccordionRoot = AccordionPrimitive as React.FC<{
+    type: 'single' | 'multiple'
+    collapsible?: boolean
+    children?: React.ReactNode
+  }>
+
+  return (
+    <AccordionRoot type={type} collapsible={type === 'single'}>
+      {children}
+    </AccordionRoot>
+  )
+}
+
+export interface AccordionItemWrapperProps {
+  value: string
+  title: string
+  children?: React.ReactNode
+}
+
+/**
+ * AccordionItem wrapper that takes title as a prop and renders trigger + content.
+ */
+export function AccordionItemWrapper({
+  value,
+  title,
+  children,
+}: AccordionItemWrapperProps) {
+  return (
+    <AccordionItemPrimitive value={value}>
+      <AccordionTrigger>{title}</AccordionTrigger>
+      <AccordionContent>{children}</AccordionContent>
+    </AccordionItemPrimitive>
+  )
+}

package/src/plugins/generative-ui/ui/accordion.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import * as React from 'react'
+import { ChevronDownIcon } from 'lucide-react'
+import { Accordion as AccordionPrimitive } from 'radix-ui'
+
+import { cn } from '@/lib/utils'
+
+function Accordion({
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn('border-b last:border-b-0', className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          'text-foreground focus-visible:border-ring focus-visible:ring-ring/50 flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down overflow-hidden text-sm"
+      {...props}
+    >
+      <div className={cn('pt-0 pb-4', className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }

package/src/plugins/generative-ui/ui/action-button.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import * as React from 'react'
+import { Button, buttonVariants } from './button'
+import type { VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+import { useToolExecution } from '@/contexts/ToolExecutionContext'
+
+export interface ActionButtonProps
+  extends
+    Omit<React.ComponentProps<'button'>, 'onClick'>,
+    VariantProps<typeof buttonVariants> {
+  label: string
+  /** Tool name to invoke when clicked (matches LLM prompt) */
+  action: string
+  args?: Record<string, unknown>
+}
+
+export function ActionButton({
+  label,
+  action,
+  args,
+  variant = 'default',
+  size = 'default',
+  className,
+  disabled,
+  ...props
+}: ActionButtonProps) {
+  const { executeTool, isToolAvailable } = useToolExecution()
+  const [isLoading, setIsLoading] = React.useState(false)
+
+  const toolAvailable = isToolAvailable(action)
+
+  const [error, setError] = React.useState<string | null>(null)
+
+  const handleClick = React.useCallback(async () => {
+    if (!toolAvailable || isLoading) return
+
+    setIsLoading(true)
+    setError(null)
+    try {
+      const result = await executeTool(action, args ?? {})
+      if (!result.success && result.error) {
+        setError(result.error)
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error')
+    } finally {
+      setIsLoading(false)
+    }
+  }, [action, args, executeTool, isLoading, toolAvailable])
+
+  return (
+    <div className="inline-flex flex-col gap-1">
+      <Button
+        variant={error ? 'destructive' : variant}
+        size={size}
+        className={cn(className)}
+        onClick={handleClick}
+        disabled={disabled || isLoading || !toolAvailable}
+        {...props}
+      >
+        {isLoading ? 'Loading...' : label}
+      </Button>
+      {error && <span className="text-destructive text-xs">{error}</span>}
+    </div>
+  )
+}

package/src/plugins/generative-ui/ui/alert-wrapper.tsx

@@ -0,0 +1,26 @@
+'use client'
+
+import * as React from 'react'
+import { Alert, AlertTitle, AlertDescription } from './alert'
+
+export interface AlertWrapperProps {
+  title: string
+  description?: string
+  variant?: 'default' | 'destructive'
+}
+
+/**
+ * Alert wrapper that takes title and description as props.
+ */
+export function AlertWrapper({
+  title,
+  description,
+  variant = 'default',
+}: AlertWrapperProps) {
+  return (
+    <Alert variant={variant}>
+      <AlertTitle>{title}</AlertTitle>
+      {description && <AlertDescription>{description}</AlertDescription>}
+    </Alert>
+  )
+}

package/src/plugins/generative-ui/ui/alert.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '@/lib/utils'
+
+const alertVariants = cva(
+  'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+  {
+    variants: {
+      variant: {
+        default: 'bg-card text-card-foreground',
+        destructive:
+          'text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+)
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        'col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        'text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Alert, AlertTitle, AlertDescription }

package/src/plugins/generative-ui/ui/avatar-wrapper.tsx

@@ -0,0 +1,22 @@
+'use client'
+
+import * as React from 'react'
+import { Avatar, AvatarImage, AvatarFallback } from './avatar'
+
+export interface AvatarWrapperProps {
+  src?: string
+  alt?: string
+  fallback: string
+}
+
+/**
+ * Avatar wrapper that takes src, alt, and fallback as props.
+ */
+export function AvatarWrapper({ src, alt, fallback }: AvatarWrapperProps) {
+  return (
+    <Avatar>
+      {src && <AvatarImage src={src} alt={alt} />}
+      <AvatarFallback>{fallback}</AvatarFallback>
+    </Avatar>
+  )
+}

package/src/plugins/generative-ui/ui/avatar.tsx

@@ -0,0 +1,109 @@
+'use client'
+
+import * as React from 'react'
+import { Avatar as AvatarPrimitive } from 'radix-ui'
+
+import { cn } from '@/lib/utils'
+
+function Avatar({
+  className,
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+  size?: 'default' | 'sm' | 'lg'
+}) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      data-size={size}
+      className={cn(
+        'group/avatar relative flex size-8 shrink-0 overflow-hidden rounded-full select-none data-[size=lg]:size-10 data-[size=sm]:size-6',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarImage({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn('aspect-square size-full', className)}
+      {...props}
+    />
+  )
+}
+
+function AvatarFallback({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        'bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm group-data-[size=sm]/avatar:text-xs',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        'bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full ring-2 select-none',
+        'group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden',
+        'group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2',
+        'group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        '*:data-[slot=avatar]:ring-background group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroupCount({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        'bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 items-center justify-center rounded-full text-sm ring-2 group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+}

package/src/plugins/generative-ui/ui/badge.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { Slot } from 'radix-ui'
+
+import { cn } from '@/lib/utils'
+
+const badgeVariants = cva(
+  'inline-flex items-center justify-center rounded-full border border-transparent px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+        secondary:
+          'bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+        /** Matches LLM prompt variant */
+        success:
+          'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-100',
+        /** Matches LLM prompt variant */
+        warning:
+          'bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-100',
+        /** Matches LLM prompt variant */
+        error: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-100',
+        destructive:
+          'bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+        outline:
+          'border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+)
+
+interface BadgeProps
+  extends React.ComponentProps<'span'>, VariantProps<typeof badgeVariants> {
+  asChild?: boolean
+  /** Content text (matches LLM prompt) - rendered as children */
+  content?: string
+}
+
+function Badge({
+  className,
+  variant = 'default',
+  asChild = false,
+  content,
+  children,
+  ...props
+}: BadgeProps) {
+  const Comp = asChild ? Slot.Root : 'span'
+
+  return (
+    <Comp
+      data-slot="badge"
+      data-variant={variant}
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    >
+      {content ?? children}
+    </Comp>
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export { Badge, badgeVariants }

package/src/plugins/generative-ui/ui/button-wrapper.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import * as React from 'react'
+import { Button } from './button'
+
+export interface ButtonWrapperProps {
+  label: string
+  variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost'
+  size?: 'default' | 'sm' | 'lg' | 'icon'
+  disabled?: boolean
+  /** Backend action to trigger (future use) */
+  action?: string
+  /** Parameters for the action (future use) */
+  actionParams?: Record<string, unknown>
+}
+
+/**
+ * Button wrapper that takes label as a prop.
+ * The action/actionParams props are for future backend integration.
+ */
+export function ButtonWrapper({
+  label,
+  variant = 'default',
+  size = 'default',
+  disabled = false,
+}: ButtonWrapperProps) {
+  return (
+    <Button variant={variant} size={size} disabled={disabled}>
+      {label}
+    </Button>
+  )
+}