@utopia-studio-design/design-system-cli 0.4.0 → 0.5.0

package/data/templates/dashboard-composer/ActivityFeedBlock.tsx

@@ -0,0 +1,255 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import { StatusDot } from '@utopia-studio-design/design-system/DataDisplay'
+import './activity-feed.css'
+
+export type ActivityFeedDensity = 'compact' | 'default' | 'comfortable'
+export type ActivityFeedGrouping = 'none' | 'day' | 'source'
+export type ActivityFeedState = 'loading' | 'empty' | 'error' | 'ready'
+export type ActivityFeedTone = 'neutral' | 'info' | 'positive' | 'warning' | 'critical'
+
+export interface ActivityFeedItem {
+  id: string
+  label: string
+  source?: string
+  timestamp: string
+  tone?: ActivityFeedTone
+}
+
+export interface ActivityFeedLabels {
+  end: string
+  emptyDescription: string
+  emptyTitle: string
+  errorDescription: string
+  errorTitle: string
+  eyebrow: string
+  invalidTime: string
+  loadMore: string
+  loading: string
+  otherSource: string
+  retry: string
+  title: string
+}
+
+export interface ActivityFeedBlockProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  density?: ActivityFeedDensity
+  direction?: 'ltr' | 'rtl'
+  groupBy?: ActivityFeedGrouping
+  items?: ActivityFeedItem[]
+  labels: ActivityFeedLabels
+  locale?: string
+  onRetry?: () => void
+  pageSize?: number
+  showSources?: boolean
+  state?: ActivityFeedState
+  timeZone?: string
+  title?: string
+}
+
+interface ActivityGroup {
+  id: string
+  label?: string
+  items: ActivityFeedItem[]
+}
+
+function safeDate(timestamp: string) {
+  const date = new Date(timestamp)
+  return Number.isNaN(date.valueOf()) ? null : date
+}
+
+function makeFormatter(locale: string, timeZone: string, options: Intl.DateTimeFormatOptions) {
+  try {
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone })
+  } catch {
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' })
+  }
+}
+
+function formatNumber(locale: string, value: number) {
+  try {
+    return new Intl.NumberFormat(locale).format(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function groupItems(
+  items: ActivityFeedItem[],
+  groupBy: ActivityFeedGrouping,
+  locale: string,
+  timeZone: string,
+  otherSource: string,
+): ActivityGroup[] {
+  if (groupBy === 'none') return [{ id: 'all', items }]
+
+  const dayFormatter = makeFormatter(locale, timeZone, {
+    dateStyle: 'full',
+  })
+  const groups = new Map<string, ActivityGroup>()
+  items.forEach((item) => {
+    const date = safeDate(item.timestamp)
+    const label = groupBy === 'source'
+      ? item.source || otherSource
+      : date ? dayFormatter.format(date) : otherSource
+    const id = `${groupBy}:${label}`
+    const group = groups.get(id) ?? { id, label, items: [] }
+    group.items.push(item)
+    groups.set(id, group)
+  })
+  return [...groups.values()]
+}
+
+function ActivityItems({
+  items,
+  labels,
+  locale,
+  showSources,
+  timeZone,
+}: {
+  items: ActivityFeedItem[]
+  labels: ActivityFeedLabels
+  locale: string
+  showSources: boolean
+  timeZone: string
+}) {
+  const dateTimeFormatter = makeFormatter(locale, timeZone, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  })
+  const timeFormatter = makeFormatter(locale, timeZone, {
+    hour: 'numeric',
+    minute: '2-digit',
+  })
+
+  return (
+    <ol className="ceramic-activity-items">
+      {items.map((item) => {
+        const date = safeDate(item.timestamp)
+        const accessibleTime = date ? dateTimeFormatter.format(date) : labels.invalidTime
+        const visibleTime = date ? timeFormatter.format(date) : labels.invalidTime
+        return (
+          <li key={item.id}>
+            <StatusDot
+              aria-hidden="true"
+              className="ceramic-activity-marker"
+              data-tone={item.tone ?? 'neutral'}
+            />
+            <div className="ceramic-activity-copy">
+              <p>{item.label}</p>
+              <div>
+                <time dateTime={date ? date.toISOString() : undefined} title={accessibleTime}>
+                  {visibleTime}
+                </time>
+                {showSources && item.source ? <Badge variant="outline">{item.source}</Badge> : null}
+              </div>
+            </div>
+          </li>
+        )
+      })}
+    </ol>
+  )
+}
+
+export function ActivityFeedBlock({
+  density = 'default',
+  direction,
+  groupBy = 'day',
+  items = [],
+  labels,
+  locale = 'en-US',
+  onRetry,
+  pageSize = 4,
+  showSources = true,
+  state: stateProp,
+  timeZone = 'UTC',
+  title,
+  ...props
+}: ActivityFeedBlockProps) {
+  const titleId = React.useId()
+  const [visibleCount, setVisibleCount] = React.useState(pageSize)
+  const state = stateProp ?? (items.length ? 'ready' : 'empty')
+  const visibleItems = items.slice(0, visibleCount)
+  const groups = groupItems(visibleItems, groupBy, locale, timeZone, labels.otherSource)
+  const hasMore = visibleCount < items.length
+  const visibleCountLabel = formatNumber(locale, visibleItems.length)
+  const totalCountLabel = formatNumber(locale, items.length)
+
+  React.useEffect(() => {
+    setVisibleCount(pageSize)
+  }, [items.length, pageSize])
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-labelledby={titleId}
+      className="ceramic-activity-feed"
+      data-density={density}
+      data-state={state}
+      dir={direction}
+      lang={locale}
+      {...props}
+    >
+      <header>
+        <div>
+          <span>{labels.eyebrow}</span>
+          <h2 id={titleId}>{title ?? labels.title}</h2>
+        </div>
+        {state === 'ready' ? <Badge variant="outline">{visibleCountLabel}/{totalCountLabel}</Badge> : null}
+      </header>
+
+      {state === 'loading' ? (
+        <div className="ceramic-activity-state" role="status">{labels.loading}</div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-activity-state" role="alert">
+          <strong>{labels.errorTitle}</strong>
+          <span>{labels.errorDescription}</span>
+          {onRetry ? <Button size="sm" variant="outline" onClick={onRetry}>{labels.retry}</Button> : null}
+        </div>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-activity-state" role="status">
+          <strong>{labels.emptyTitle}</strong>
+          <span>{labels.emptyDescription}</span>
+        </div>
+      ) : null}
+      {state === 'ready' ? (
+        <div className="ceramic-activity-groups">
+          {groups.map((group, groupIndex) => {
+            const groupTitleId = `${titleId}-group-${groupIndex + 1}`
+            return (
+              <section aria-labelledby={group.label ? groupTitleId : undefined} key={group.id}>
+                {group.label ? <h3 id={groupTitleId}>{group.label}</h3> : null}
+                <ActivityItems
+                  items={group.items}
+                  labels={labels}
+                  locale={locale}
+                  showSources={showSources}
+                  timeZone={timeZone}
+                />
+              </section>
+            )
+          })}
+        </div>
+      ) : null}
+
+      {state === 'ready' ? (
+        <footer>
+          {hasMore ? (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => setVisibleCount((count) => Math.min(items.length, count + pageSize))}
+            >
+              {labels.loadMore}
+            </Button>
+          ) : <span>{labels.end}</span>}
+        </footer>
+      ) : null}
+      <output aria-live="polite" className="uds-visually-hidden">
+        {state === 'ready' ? `${visibleCountLabel} / ${totalCountLabel}` : ''}
+      </output>
+    </section>
+  )
+}

package/data/templates/dashboard-composer/AgentStatusBlock.tsx

@@ -0,0 +1,313 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import {
+  ProgressBar,
+  StatusDot,
+} from '@utopia-studio-design/design-system/DataDisplay'
+import './agent-status.css'
+
+export type AgentExecutionState =
+  | 'queued'
+  | 'running'
+  | 'waiting-approval'
+  | 'blocked'
+  | 'failed'
+  | 'completed'
+
+export type AgentRisk = 'none' | 'low' | 'medium' | 'high'
+export type AgentStatusDensity = 'compact' | 'default' | 'comfortable'
+export type AgentStatusFilter = 'all' | 'active' | 'attention' | 'completed'
+export type AgentStatusState = 'loading' | 'empty' | 'error' | 'ready'
+
+export interface AgentApprovalRequest {
+  id: string
+  description?: string
+  label: string
+}
+
+export interface AgentStatusItem {
+  id: string
+  approval?: AgentApprovalRequest
+  name: string
+  progress?: number
+  risk?: AgentRisk
+  state: AgentExecutionState
+  summary?: string
+  taskLabel: string
+  updatedAt?: string
+}
+
+export interface AgentStatusLabels {
+  approve: string
+  approvalRequested: string
+  count: (visible: string, total: string) => string
+  emptyDescription: string
+  emptyTitle: string
+  errorDescription: string
+  errorTitle: string
+  eyebrow: string
+  loading: string
+  noMatchingDescription: string
+  noMatchingTitle: string
+  progress: string
+  reject: string
+  retry: string
+  risk: Record<Exclude<AgentRisk, 'none'>, string>
+  state: Record<AgentExecutionState, string>
+  timeUnavailable: string
+  title: string
+  updated: string
+}
+
+export interface AgentStatusBlockProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  density?: AgentStatusDensity
+  direction?: 'ltr' | 'rtl'
+  filter?: AgentStatusFilter
+  items?: AgentStatusItem[]
+  labels: AgentStatusLabels
+  locale?: string
+  maxItems?: number
+  onApprove?: (item: AgentStatusItem, request: AgentApprovalRequest) => void
+  onReject?: (item: AgentStatusItem, request: AgentApprovalRequest) => void
+  onRetry?: () => void
+  showApprovals?: boolean
+  state?: AgentStatusState
+  timeZone?: string
+  title?: string
+}
+
+const attentionStates = new Set<AgentExecutionState>([
+  'waiting-approval',
+  'blocked',
+  'failed',
+])
+
+function filterItems(items: AgentStatusItem[], filter: AgentStatusFilter) {
+  if (filter === 'active') {
+    return items.filter((item) => item.state === 'queued' || item.state === 'running')
+  }
+  if (filter === 'attention') {
+    return items.filter((item) => attentionStates.has(item.state))
+  }
+  if (filter === 'completed') {
+    return items.filter((item) => item.state === 'completed')
+  }
+  return items
+}
+
+function formatNumber(locale: string, value: number) {
+  try {
+    return new Intl.NumberFormat(locale).format(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function formatPercent(locale: string, value: number) {
+  try {
+    return new Intl.NumberFormat(locale, {
+      maximumFractionDigits: 0,
+      style: 'percent',
+    }).format(value / 100)
+  } catch {
+    return `${Math.round(value)}%`
+  }
+}
+
+function formatUpdatedAt(locale: string, timeZone: string, value?: string) {
+  if (!value) return null
+  const date = new Date(value)
+  if (Number.isNaN(date.valueOf())) return null
+  try {
+    return {
+      date,
+      label: new Intl.DateTimeFormat(locale, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+        timeZone,
+      }).format(date),
+    }
+  } catch {
+    return {
+      date,
+      label: new Intl.DateTimeFormat(locale, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+        timeZone: 'UTC',
+      }).format(date),
+    }
+  }
+}
+
+function statusVariant(state: AgentExecutionState) {
+  if (state === 'failed') return 'destructive' as const
+  if (state === 'completed') return 'secondary' as const
+  return 'outline' as const
+}
+
+function progressStatus(state: AgentExecutionState) {
+  if (state === 'failed') return 'destructive' as const
+  if (state === 'blocked' || state === 'waiting-approval') return 'warning' as const
+  if (state === 'completed') return 'success' as const
+  return 'default' as const
+}
+
+export function AgentStatusBlock({
+  density = 'default',
+  direction,
+  filter = 'all',
+  items = [],
+  labels,
+  locale = 'en-US',
+  maxItems = 6,
+  onApprove,
+  onReject,
+  onRetry,
+  showApprovals = true,
+  state: stateProp,
+  timeZone = 'UTC',
+  title,
+  ...props
+}: AgentStatusBlockProps) {
+  const titleId = React.useId()
+  const filteredItems = filterItems(items, filter)
+  const visibleItems = filteredItems.slice(0, maxItems)
+  const state = stateProp ?? (items.length ? 'ready' : 'empty')
+  const visibleCount = formatNumber(locale, visibleItems.length)
+  const totalCount = formatNumber(locale, filteredItems.length)
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-labelledby={titleId}
+      className="ceramic-agent-status"
+      data-density={density}
+      data-filter={filter}
+      data-state={state}
+      dir={direction}
+      lang={locale}
+      {...props}
+    >
+      <header>
+        <div>
+          <span>{labels.eyebrow}</span>
+          <h2 id={titleId}>{title ?? labels.title}</h2>
+        </div>
+        {state === 'ready' ? (
+          <Badge variant="outline">{labels.count(visibleCount, totalCount)}</Badge>
+        ) : null}
+      </header>
+
+      {state === 'loading' ? (
+        <div className="ceramic-agent-status-state" role="status">{labels.loading}</div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-agent-status-state" role="alert">
+          <strong>{labels.errorTitle}</strong>
+          <span>{labels.errorDescription}</span>
+          {onRetry ? <Button size="sm" variant="outline" onClick={onRetry}>{labels.retry}</Button> : null}
+        </div>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-agent-status-state" role="status">
+          <strong>{labels.emptyTitle}</strong>
+          <span>{labels.emptyDescription}</span>
+        </div>
+      ) : null}
+      {state === 'ready' && visibleItems.length === 0 ? (
+        <div className="ceramic-agent-status-state" role="status">
+          <strong>{labels.noMatchingTitle}</strong>
+          <span>{labels.noMatchingDescription}</span>
+        </div>
+      ) : null}
+      {state === 'ready' && visibleItems.length > 0 ? (
+        <ul className="ceramic-agent-status-list">
+          {visibleItems.map((item) => {
+            const progress = Math.max(0, Math.min(100, item.progress ?? (
+              item.state === 'completed' ? 100 : 0
+            )))
+            const updatedAt = formatUpdatedAt(locale, timeZone, item.updatedAt)
+            const approvalTitleId = `${titleId}-${item.id}-approval`
+            return (
+              <li data-execution-state={item.state} key={item.id}>
+                <div className="ceramic-agent-status-heading">
+                  <StatusDot aria-hidden="true" data-execution-state={item.state} />
+                  <div>
+                    <strong><bdi>{item.name}</bdi></strong>
+                    <span><bdi>{item.taskLabel}</bdi></span>
+                  </div>
+                  <Badge variant={statusVariant(item.state)}>
+                    {labels.state[item.state]}
+                  </Badge>
+                </div>
+
+                {item.summary ? <p><bdi>{item.summary}</bdi></p> : null}
+
+                {(item.state === 'running' || item.state === 'completed') ? (
+                  <ProgressBar
+                    aria-label={`${item.name}: ${labels.progress}`}
+                    label={labels.progress}
+                    showValue
+                    size={density === 'compact' ? 'sm' : 'md'}
+                    status={progressStatus(item.state)}
+                    value={progress}
+                    valueText={formatPercent(locale, progress)}
+                  />
+                ) : null}
+
+                <div className="ceramic-agent-status-meta">
+                  {item.risk && item.risk !== 'none' ? (
+                    <Badge data-risk={item.risk} variant="outline">
+                      {labels.risk[item.risk]}
+                    </Badge>
+                  ) : null}
+                  {updatedAt ? (
+                    <span>
+                      {labels.updated}{' '}
+                      <time dateTime={updatedAt.date.toISOString()}>{updatedAt.label}</time>
+                    </span>
+                  ) : item.updatedAt ? <span>{labels.timeUnavailable}</span> : null}
+                </div>
+
+                {showApprovals && item.state === 'waiting-approval' && item.approval ? (
+                  <section
+                    aria-labelledby={approvalTitleId}
+                    className="ceramic-agent-approval"
+                  >
+                    <div>
+                      <strong id={approvalTitleId}>{labels.approvalRequested}</strong>
+                      <span>{item.approval.label}</span>
+                      {item.approval.description ? <p>{item.approval.description}</p> : null}
+                    </div>
+                    {onApprove || onReject ? (
+                      <div>
+                        {onReject ? (
+                          <Button
+                            size="sm"
+                            variant="outline"
+                            onClick={() => onReject(item, item.approval!)}
+                          >
+                            {labels.reject}
+                          </Button>
+                        ) : null}
+                        {onApprove ? (
+                          <Button
+                            size="sm"
+                            onClick={() => onApprove(item, item.approval!)}
+                          >
+                            {labels.approve}
+                          </Button>
+                        ) : null}
+                      </div>
+                    ) : null}
+                  </section>
+                ) : null}
+              </li>
+            )
+          })}
+        </ul>
+      ) : null}
+    </section>
+  )
+}

package/data/templates/dashboard-composer/AnalyticsDashboardBlocks.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import {
+  ChartRoot,
+  type ChartAnnotationDefinition,
+  type ChartDatum,
+  type ChartSeriesDefinition,
+  type ChartState,
+  type ChartType,
+} from '@utopia-studio-design/design-system/Charts'
+import './analytics-dashboard.css'
+
+export {
+  KPIGrid,
+  type KPIGridProps,
+  type MetricDefinition,
+} from './AnalyticsMetricBlocks'
+
+export interface AnalyticsChartCardProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  annotations?: ChartAnnotationDefinition[]
+  data: ChartDatum[]
+  description?: React.ReactNode
+  direction?: 'ltr' | 'rtl'
+  series: ChartSeriesDefinition[]
+  showDataTable?: boolean
+  state?: ChartState
+  title: React.ReactNode
+  type?: ChartType
+}
+
+export function AnalyticsChartCard({
+  annotations = [],
+  data,
+  description,
+  direction,
+  series,
+  showDataTable,
+  state,
+  title,
+  type,
+  ...props
+}: AnalyticsChartCardProps) {
+  return (
+    <ChartRoot
+      accessibleSummary={`${String(title)} across ${data.length} periods. Use the chart explorer or data table for exact values.`}
+      annotations={annotations}
+      axis={{ showGrid: true }}
+      data={data}
+      description={description}
+      direction={direction}
+      series={series}
+      showDataTable={showDataTable}
+      state={state}
+      title={title}
+      type={type}
+      {...props}
+    />
+  )
+}
+
+export interface ComparisonChartPanelProps extends AnalyticsChartCardProps {
+  benchmarkLabel?: string
+  benchmarkValue?: number
+}
+
+export function ComparisonChartPanel({
+  benchmarkLabel = 'Target',
+  benchmarkValue,
+  annotations = [],
+  ...props
+}: ComparisonChartPanelProps) {
+  const nextAnnotations = benchmarkValue === undefined
+    ? annotations
+    : [
+        ...annotations,
+        { id: 'benchmark', label: benchmarkLabel, value: benchmarkValue, tone: 'neutral' as const },
+      ]
+  return <AnalyticsChartCard annotations={nextAnnotations} {...props} />
+}
+
+export function ChartWithDataTable(props: AnalyticsChartCardProps) {
+  return <AnalyticsChartCard {...props} showDataTable />
+}
+
+export interface AnalyticsDashboardHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  onRefresh?: () => void
+  periodLabel: string
+  title: string
+}
+
+export function AnalyticsDashboardHeader({
+  onRefresh,
+  periodLabel,
+  title,
+  ...props
+}: AnalyticsDashboardHeaderProps) {
+  return (
+    <header className="ceramic-analytics-header" {...props}>
+      <div>
+        <span>Analytics dashboard</span>
+        <h1>{title}</h1>
+        <p>{periodLabel}</p>
+      </div>
+      <Button variant="outline" onClick={onRefresh}>Refresh data</Button>
+    </header>
+  )
+}