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

package/data/blocks/activity-feed/activity-feed.css

@@ -0,0 +1,154 @@
+.ceramic-activity-feed {
+  display: grid;
+  align-content: start;
+  gap: var(--space-3);
+  min-inline-size: 0;
+  block-size: 100%;
+  padding: var(--space-4);
+  background: var(--surface);
+  color: var(--foreground);
+  text-align: start;
+}
+
+.ceramic-activity-feed > header,
+.ceramic-activity-feed > header > div,
+.ceramic-activity-items > li,
+.ceramic-activity-copy > div,
+.ceramic-activity-feed > footer {
+  display: flex;
+  align-items: center;
+}
+
+.ceramic-activity-feed > header {
+  justify-content: space-between;
+  gap: var(--space-3);
+  padding-block-end: var(--space-3);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.ceramic-activity-feed > header > div {
+  align-items: start;
+  flex-direction: column;
+  gap: var(--space-1);
+  min-inline-size: 0;
+}
+
+.ceramic-activity-feed :is(h2, h3, p) {
+  margin: 0;
+}
+
+.ceramic-activity-feed > header span {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-eyebrow);
+  font-weight: var(--font-weight-semibold);
+  letter-spacing: var(--tracking-eyebrow);
+  text-transform: uppercase;
+}
+
+.ceramic-activity-groups {
+  display: grid;
+  gap: var(--space-4);
+}
+
+.ceramic-activity-groups > section {
+  display: grid;
+  gap: var(--space-2);
+  min-inline-size: 0;
+}
+
+.ceramic-activity-groups h3 {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+  font-weight: var(--font-weight-semibold);
+}
+
+.ceramic-activity-items {
+  display: grid;
+  gap: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ceramic-activity-items > li {
+  position: relative;
+  align-items: start;
+  gap: var(--space-3);
+  min-inline-size: 0;
+  padding-block: var(--space-2);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.ceramic-activity-feed[data-density='compact'] .ceramic-activity-items > li {
+  padding-block: var(--space-1);
+}
+
+.ceramic-activity-feed[data-density='comfortable'] .ceramic-activity-items > li {
+  padding-block: var(--space-3);
+}
+
+.ceramic-activity-marker {
+  flex: 0 0 auto;
+  margin-block-start: var(--space-1);
+  background: var(--muted-foreground);
+}
+
+.ceramic-activity-marker[data-tone='info'] {
+  background: var(--primary);
+}
+
+.ceramic-activity-marker[data-tone='positive'] {
+  background: var(--success);
+}
+
+.ceramic-activity-marker[data-tone='warning'] {
+  background: var(--warning);
+}
+
+.ceramic-activity-marker[data-tone='critical'] {
+  background: var(--destructive);
+}
+
+.ceramic-activity-copy {
+  display: grid;
+  gap: var(--space-1);
+  min-inline-size: 0;
+}
+
+.ceramic-activity-copy p {
+  overflow-wrap: anywhere;
+  line-height: var(--line-height-body);
+}
+
+.ceramic-activity-copy > div {
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+.ceramic-activity-state {
+  display: grid;
+  align-content: center;
+  justify-items: start;
+  gap: var(--space-2);
+  min-block-size: 10rem;
+  color: var(--muted-foreground);
+}
+
+.ceramic-activity-state strong {
+  color: var(--foreground);
+}
+
+.ceramic-activity-feed > footer {
+  justify-content: center;
+  min-block-size: var(--control-size-sm);
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+@media (max-width: 28rem) {
+  .ceramic-activity-feed {
+    padding: var(--space-3);
+  }
+}

package/data/blocks/agent-status/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/blocks/agent-status/README.md

@@ -0,0 +1,15 @@
+# Agent Status
+
+`AgentStatusBlock` is a product-data surface for observing agent execution,
+progress, risk, approval, failure, and completion without putting operational
+records into Ceramic Layout JSON.
+
+The registry controls only semantic presentation props. Products own execution
+records, sanitized summaries, timestamps, retry behavior, and approval/rejection
+callbacks. Never pass raw stack traces, prompts, credentials, or command output
+as an item summary.
+
+Use `resolveAgentStatusConfiguration` in every runtime/editor adapter so locale,
+direction, filter, density, item limit, approval visibility, and timezone remain
+consistent. Arabic fixtures demonstrate scoped RTL and mixed-direction agent
+names.

package/data/blocks/agent-status/agent-status-contract.ts

@@ -0,0 +1,133 @@
+import { getLocaleTextDirection } from '@utopia-studio-design/design-system/Utilities'
+import type {
+  AgentStatusBlockProps,
+  AgentStatusFilter,
+  AgentStatusLabels,
+} from './AgentStatusBlock'
+
+export const agentStatusLocaleOptions = ['en-US', 'ar-SA', 'ar-EG', 'ar-AE'] as const
+
+export type AgentStatusLocale = typeof agentStatusLocaleOptions[number]
+export type AgentStatusDirection = 'inherit' | 'auto' | 'ltr' | 'rtl'
+
+export interface AgentStatusConfiguration {
+  density: NonNullable<AgentStatusBlockProps['density']>
+  direction?: 'ltr' | 'rtl'
+  filter: AgentStatusFilter
+  labels: AgentStatusLabels
+  locale: AgentStatusLocale
+  maxItems: number
+  showApprovals: boolean
+  timeZone: string
+}
+
+export interface AgentStatusContext {
+  direction: 'ltr' | 'rtl'
+}
+
+const directions: AgentStatusDirection[] = ['inherit', 'auto', 'ltr', 'rtl']
+const densities: AgentStatusConfiguration['density'][] = ['compact', 'default', 'comfortable']
+const filters: AgentStatusFilter[] = ['all', 'active', 'attention', 'completed']
+
+const englishLabels: AgentStatusLabels = {
+  approve: 'Approve',
+  approvalRequested: 'Approval requested',
+  count: (visible, total) => `${visible} of ${total}`,
+  emptyDescription: 'Agent executions will appear here when work begins.',
+  emptyTitle: 'No agent executions',
+  errorDescription: 'Reconnect the execution source and try again.',
+  errorTitle: 'Agent status unavailable',
+  eyebrow: 'Agent operations',
+  loading: 'Loading agent status…',
+  noMatchingDescription: 'Change the semantic filter to review other executions.',
+  noMatchingTitle: 'No executions match this view',
+  progress: 'Progress',
+  reject: 'Reject',
+  retry: 'Try again',
+  risk: {
+    high: 'High risk',
+    low: 'Low risk',
+    medium: 'Medium risk',
+  },
+  state: {
+    blocked: 'Blocked',
+    completed: 'Completed',
+    failed: 'Failed',
+    queued: 'Queued',
+    running: 'Running',
+    'waiting-approval': 'Waiting for approval',
+  },
+  timeUnavailable: 'Update time unavailable',
+  title: 'Agent status',
+  updated: 'Updated',
+}
+
+const arabicLabels: AgentStatusLabels = {
+  approve: 'موافقة',
+  approvalRequested: 'طلب موافقة',
+  count: (visible, total) => `${visible} من ${total}`,
+  emptyDescription: 'ستظهر عمليات الوكلاء هنا عند بدء العمل.',
+  emptyTitle: 'لا توجد عمليات للوكلاء',
+  errorDescription: 'أعد الاتصال بمصدر التنفيذ ثم حاول مرة أخرى.',
+  errorTitle: 'حالة الوكلاء غير متاحة',
+  eyebrow: 'عمليات الوكلاء',
+  loading: 'جارٍ تحميل حالة الوكلاء…',
+  noMatchingDescription: 'غيّر عامل التصفية الدلالي لمراجعة العمليات الأخرى.',
+  noMatchingTitle: 'لا توجد عمليات مطابقة لهذا العرض',
+  progress: 'التقدم',
+  reject: 'رفض',
+  retry: 'حاول مرة أخرى',
+  risk: {
+    high: 'مخاطر عالية',
+    low: 'مخاطر منخفضة',
+    medium: 'مخاطر متوسطة',
+  },
+  state: {
+    blocked: 'متوقف',
+    completed: 'مكتمل',
+    failed: 'فشل',
+    queued: 'في قائمة الانتظار',
+    running: 'قيد التشغيل',
+    'waiting-approval': 'بانتظار الموافقة',
+  },
+  timeUnavailable: 'وقت التحديث غير متاح',
+  title: 'حالة الوكلاء',
+  updated: 'آخر تحديث',
+}
+
+export function getAgentStatusLabels(locale: string): AgentStatusLabels {
+  return getLocaleTextDirection(locale) === 'rtl' ? arabicLabels : englishLabels
+}
+
+export function resolveAgentStatusConfiguration(
+  props: Record<string, unknown>,
+  context: AgentStatusContext,
+): AgentStatusConfiguration {
+  const locale = agentStatusLocaleOptions.includes(props.locale as AgentStatusLocale)
+    ? props.locale as AgentStatusLocale
+    : 'en-US'
+  const directionMode = directions.includes(props.direction as AgentStatusDirection)
+    ? props.direction as AgentStatusDirection
+    : 'inherit'
+  const direction = directionMode === 'inherit'
+    ? context.direction
+    : directionMode === 'auto' ? getLocaleTextDirection(locale) : directionMode
+  const maxItems = Number.isInteger(props.maxItems)
+    ? Math.min(12, Math.max(1, Number(props.maxItems)))
+    : 6
+
+  return {
+    density: densities.includes(props.density as AgentStatusConfiguration['density'])
+      ? props.density as AgentStatusConfiguration['density']
+      : 'default',
+    direction,
+    filter: filters.includes(props.filter as AgentStatusFilter)
+      ? props.filter as AgentStatusFilter
+      : 'all',
+    labels: getAgentStatusLabels(locale),
+    locale,
+    maxItems,
+    showApprovals: props.showApprovals !== false,
+    timeZone: typeof props.timeZone === 'string' && props.timeZone ? props.timeZone : 'UTC',
+  }
+}

package/data/blocks/agent-status/agent-status-fixture.ts

@@ -0,0 +1,79 @@
+import type { AgentStatusItem } from './AgentStatusBlock'
+
+const englishItems: AgentStatusItem[] = [
+  {
+    id: 'mina-qa',
+    name: 'Mina UX-QA',
+    progress: 68,
+    risk: 'low',
+    state: 'running',
+    summary: 'Checking responsive, Arabic, and interaction contracts.',
+    taskLabel: 'Dashboard composition QA',
+    updatedAt: '2026-07-30T08:42:00.000Z',
+  },
+  {
+    approval: {
+      id: 'publish-approval',
+      description: 'Publishes the validated patch release to the configured npm registry.',
+      label: 'Publish Ceramic patch release',
+    },
+    id: 'release-agent',
+    name: 'Release Agent',
+    risk: 'medium',
+    state: 'waiting-approval',
+    summary: 'All local release gates passed. External publishing requires a human decision.',
+    taskLabel: 'Prepare npm release',
+    updatedAt: '2026-07-30T08:39:00.000Z',
+  },
+  {
+    id: 'registry-agent',
+    name: 'Registry Agent',
+    risk: 'high',
+    state: 'blocked',
+    summary: 'A required product data adapter has not been connected.',
+    taskLabel: 'Sync production activity source',
+    updatedAt: '2026-07-30T08:31:00.000Z',
+  },
+  {
+    id: 'build-agent',
+    name: 'Build Agent',
+    progress: 100,
+    risk: 'none',
+    state: 'completed',
+    summary: 'Standalone Calendar and Dashboard templates built successfully.',
+    taskLabel: 'Verify generated templates',
+    updatedAt: '2026-07-30T08:20:00.000Z',
+  },
+]
+
+const arabicItems: AgentStatusItem[] = [
+  {
+    ...englishItems[0],
+    summary: 'جارٍ فحص عقود الاستجابة والعربية والتفاعل.',
+    taskLabel: 'فحص جودة تكوين لوحة المعلومات',
+  },
+  {
+    ...englishItems[1],
+    approval: {
+      id: 'publish-approval',
+      description: 'سيتم نشر إصدار التصحيح المعتمد في سجل npm المحدد.',
+      label: 'نشر إصدار تصحيح Ceramic',
+    },
+    summary: 'نجحت جميع فحوصات الإصدار المحلية. يتطلب النشر الخارجي قراراً بشرياً.',
+    taskLabel: 'إعداد إصدار npm',
+  },
+  {
+    ...englishItems[2],
+    summary: 'لم يتم ربط محول بيانات المنتج المطلوب.',
+    taskLabel: 'مزامنة مصدر النشاط في الإنتاج',
+  },
+  {
+    ...englishItems[3],
+    summary: 'تم بناء قوالب التقويم ولوحة المعلومات المستقلة بنجاح.',
+    taskLabel: 'التحقق من القوالب المولدة',
+  },
+]
+
+export function getAgentStatusFixture(locale: string): AgentStatusItem[] {
+  return locale.startsWith('ar') ? arabicItems : englishItems
+}