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

package/data/blocks/dashboard-composer/DashboardComposerBlocks.tsx

@@ -0,0 +1,337 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import { Checkbox, TextInput } from '@utopia-studio-design/design-system/Forms'
+import {
+  getCeramicBlockDefinition,
+  validateCeramicAgentMutation,
+  validateCeramicLayout,
+  type CeramicLayoutBlock,
+  type CeramicLayoutDocument,
+} from '@utopia-studio-design/design-system/Composition'
+import './dashboard-composer.css'
+
+export type TodoFilter = 'all' | 'today' | 'upcoming' | 'completed'
+export type TodoPriority = 'low' | 'medium' | 'high'
+
+export interface TodoItem {
+  id: string
+  title: string
+  completed: boolean
+  dueLabel?: string
+  priority?: TodoPriority
+}
+
+export interface TodoListBlockProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange' | 'title'> {
+  canCreate?: boolean
+  canDelete?: boolean
+  defaultItems?: TodoItem[]
+  density?: 'compact' | 'default' | 'comfortable'
+  filter?: TodoFilter
+  items?: TodoItem[]
+  onItemsChange?: (items: TodoItem[]) => void
+  showCompleted?: boolean
+  state?: 'loading' | 'empty' | 'error' | 'ready'
+  title?: string
+}
+
+export function TodoListBlock({
+  canCreate = true,
+  canDelete = true,
+  defaultItems = [],
+  density = 'default',
+  filter = 'all',
+  items: controlledItems,
+  onItemsChange,
+  showCompleted = true,
+  state: stateProp,
+  title = 'Today’s tasks',
+  ...props
+}: TodoListBlockProps) {
+  const [uncontrolledItems, setUncontrolledItems] = React.useState(defaultItems)
+  const [draft, setDraft] = React.useState('')
+  const nextId = React.useRef(defaultItems.length + 1)
+  const titleId = React.useId()
+  const inputId = React.useId()
+  const items = controlledItems ?? uncontrolledItems
+  const state = stateProp ?? (items.length ? 'ready' : 'empty')
+  const update = (next: TodoItem[]) => {
+    if (controlledItems === undefined) setUncontrolledItems(next)
+    onItemsChange?.(next)
+  }
+  const visibleItems = items.filter((item) => {
+    if (!showCompleted && item.completed) return false
+    if (filter === 'completed') return item.completed
+    if (filter === 'today') return item.dueLabel === 'Today'
+    if (filter === 'upcoming') return item.dueLabel !== 'Today'
+    return true
+  })
+  const completedCount = items.filter((item) => item.completed).length
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-labelledby={titleId}
+      className="ceramic-todo-list"
+      data-density={density}
+      data-state={state}
+      {...props}
+    >
+      <header>
+        <div>
+          <span>To-do</span>
+          <h2 id={titleId}>{title}</h2>
+        </div>
+        <Badge variant="outline">{completedCount}/{items.length} done</Badge>
+      </header>
+
+      {state === 'loading' ? (
+        <div className="ceramic-todo-state" role="status">Loading tasks…</div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-todo-state" role="alert">
+          <strong>Tasks unavailable</strong>
+          <span>Reconnect the task source and try again.</span>
+        </div>
+      ) : null}
+      {state === 'empty' || (state === 'ready' && visibleItems.length === 0) ? (
+        <div className="ceramic-todo-state" role="status">
+          <strong>No tasks in this view</strong>
+          <span>{canCreate ? 'Add the next task when you are ready.' : 'Change the task filter.'}</span>
+        </div>
+      ) : null}
+      {state === 'ready' && visibleItems.length ? (
+        <ul className="ceramic-todo-items">
+          {visibleItems.map((item) => (
+            <li data-completed={item.completed || undefined} key={item.id}>
+              <label>
+                <Checkbox
+                  aria-label={`Mark ${item.title} ${item.completed ? 'incomplete' : 'complete'}`}
+                  checked={item.completed}
+                  onCheckedChange={(checked) => update(items.map((candidate) => (
+                    candidate.id === item.id ? { ...candidate, completed: checked === true } : candidate
+                  )))}
+                />
+                <span>{item.title}</span>
+              </label>
+              <div>
+                {item.dueLabel ? <span>{item.dueLabel}</span> : null}
+                {item.priority ? <Badge variant={item.priority === 'high' ? 'destructive' : 'outline'}>{item.priority}</Badge> : null}
+                {canDelete ? (
+                  <Button
+                    aria-label={`Delete ${item.title}`}
+                    isIconOnly
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => update(items.filter((candidate) => candidate.id !== item.id))}
+                  >
+                    ×
+                  </Button>
+                ) : null}
+              </div>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      {canCreate ? (
+        <form
+          className="ceramic-todo-create"
+          onSubmit={(event) => {
+            event.preventDefault()
+            const titleValue = draft.trim()
+            if (!titleValue) return
+            while (items.some((item) => item.id === `todo-${nextId.current}`)) nextId.current += 1
+            update([...items, {
+              id: `todo-${nextId.current++}`,
+              title: titleValue,
+              completed: false,
+              dueLabel: 'Today',
+              priority: 'medium',
+            }])
+            setDraft('')
+          }}
+        >
+          <label className="uds-visually-hidden" htmlFor={inputId}>New task</label>
+          <TextInput
+            id={inputId}
+            placeholder="Add a task"
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+          />
+          <Button size="sm" type="submit">Add</Button>
+        </form>
+      ) : null}
+      <output aria-live="polite" className="uds-visually-hidden">
+        {completedCount} of {items.length} tasks completed.
+      </output>
+    </section>
+  )
+}
+
+export interface CeramicBlockRendererProps {
+  block: CeramicLayoutBlock
+  direction: 'ltr' | 'rtl'
+}
+
+export type CeramicBlockRenderer = React.ComponentType<CeramicBlockRendererProps>
+
+export interface CeramicDashboardRendererProps extends React.HTMLAttributes<HTMLElement> {
+  direction?: 'ltr' | 'rtl'
+  editable?: boolean
+  layout: CeramicLayoutDocument
+  onLayoutChange?: (layout: CeramicLayoutDocument) => void
+  renderers: Record<string, CeramicBlockRenderer>
+}
+
+export function CeramicDashboardRenderer({
+  direction = 'ltr',
+  editable = false,
+  layout,
+  onLayoutChange,
+  renderers,
+  ...props
+}: CeramicDashboardRendererProps) {
+  const [feedback, setFeedback] = React.useState('')
+  const validation = validateCeramicLayout(layout)
+  const ordered = [...layout.blocks].sort((left, right) => left.placement.order - right.placement.order)
+
+  const commit = (next: CeramicLayoutDocument, message: string) => {
+    const result = validateCeramicAgentMutation(layout, next)
+    if (!result.ok) {
+      setFeedback(result.issues[0]?.message ?? 'The registry rejected this layout change.')
+      return
+    }
+    onLayoutChange?.(next)
+    setFeedback(message)
+  }
+
+  const move = (blockId: string, offset: -1 | 1) => {
+    const currentIndex = ordered.findIndex((block) => block.id === blockId)
+    const targetIndex = currentIndex + offset
+    if (currentIndex < 0 || targetIndex < 0 || targetIndex >= ordered.length) return
+    const current = ordered[currentIndex]
+    const target = ordered[targetIndex]
+    const firstColumn = Math.min(current.placement.column, target.placement.column)
+    const firstOrder = Math.min(current.placement.order, target.placement.order)
+    const secondOrder = Math.max(current.placement.order, target.placement.order)
+    const firstBlock = offset < 0 ? current : target
+    const secondBlock = offset < 0 ? target : current
+    const nextBlocks = layout.blocks.map((block) => {
+      if (block.id === firstBlock.id) {
+        return {
+          ...block,
+          placement: {
+            ...block.placement,
+            column: firstColumn,
+            order: firstOrder,
+          },
+        }
+      }
+      if (block.id === secondBlock.id) {
+        return {
+          ...block,
+          placement: {
+            ...block.placement,
+            column: firstColumn + firstBlock.placement.span,
+            order: secondOrder,
+          },
+        }
+      }
+      return block
+    })
+    commit({ ...layout, blocks: nextBlocks }, `${current.id} moved ${offset < 0 ? 'earlier' : 'later'}.`)
+  }
+
+  if (!validation.ok) {
+    return (
+      <section className="ceramic-dashboard-error" role="alert" {...props}>
+        <strong>Dashboard layout is invalid</strong>
+        <span>{validation.issues[0]?.message}</span>
+      </section>
+    )
+  }
+
+  return (
+    <section
+      aria-label="Rendered Ceramic dashboard"
+      className="ceramic-dashboard-renderer"
+      dir={direction}
+      {...props}
+    >
+      {ordered.map((block, index) => {
+        const definition = getCeramicBlockDefinition(block.type)
+        const Renderer = renderers[block.type]
+        return (
+          <article
+            className="ceramic-dashboard-block"
+            data-block-type={block.type}
+            data-locked={block.locked || undefined}
+            key={block.id}
+            style={{
+              '--ceramic-block-column': block.placement.column,
+              '--ceramic-block-order': block.placement.order,
+              '--ceramic-block-span': block.placement.span,
+              '--ceramic-block-compact-span': block.placement.compactSpan ?? layout.columns,
+            } as React.CSSProperties}
+          >
+            {editable ? (
+              <header className="ceramic-dashboard-block-toolbar">
+                <div>
+                  <Badge variant={block.locked ? 'secondary' : 'outline'}>
+                    {block.locked ? 'Locked' : 'Editable'}
+                  </Badge>
+                  <strong>{definition?.title ?? block.type}</strong>
+                </div>
+                <div aria-label={`${definition?.title ?? block.type} layout actions`} role="toolbar">
+                  <Button
+                    aria-label={`Move ${definition?.title ?? block.type} earlier`}
+                    disabled={block.locked || index === 0}
+                    isIconOnly
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => move(block.id, -1)}
+                  >
+                    ↑
+                  </Button>
+                  <Button
+                    aria-label={`Move ${definition?.title ?? block.type} later`}
+                    disabled={block.locked || index === ordered.length - 1}
+                    isIconOnly
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => move(block.id, 1)}
+                  >
+                    ↓
+                  </Button>
+                  <Button
+                    aria-label={`Remove ${definition?.title ?? block.type}`}
+                    disabled={block.locked}
+                    isIconOnly
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => commit(
+                      { ...layout, blocks: layout.blocks.filter((candidate) => candidate.id !== block.id) },
+                      `${block.id} removed.`,
+                    )}
+                  >
+                    ×
+                  </Button>
+                </div>
+              </header>
+            ) : null}
+            {Renderer ? (
+              <Renderer block={block} direction={direction} />
+            ) : (
+              <div className="ceramic-dashboard-missing" role="status">
+                <strong>{definition?.title ?? block.type}</strong>
+                <span>No renderer has been connected for this block.</span>
+              </div>
+            )}
+          </article>
+        )
+      })}
+      <output aria-live="polite" className="uds-visually-hidden">{feedback}</output>
+    </section>
+  )
+}

package/data/blocks/dashboard-composer/README.md

@@ -0,0 +1,16 @@
+# Dashboard Composer Blocks
+
+Copyable blocks for rendering and editing a validated Ceramic Layout JSON
+document.
+
+## Exports
+
+- `TodoListBlock`: a controlled or uncontrolled task list with complete states,
+  density and semantic filters.
+- `CeramicDashboardRenderer`: maps registered layout blocks to product-supplied
+  React renderers and exposes keyboard/touch-accessible move and remove controls
+  in edit mode.
+
+The renderer validates every layout and agent-style mutation through
+`@utopia-studio-design/design-system/Composition`. Product data stays outside
+Layout JSON and is supplied by the application renderer map.

package/data/blocks/dashboard-composer/RegistryDataBlocks.tsx

@@ -0,0 +1,238 @@
+import * as React from 'react'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import type {
+  ChartAnnotationDefinition,
+  ChartDatum,
+  ChartSeriesDefinition,
+  ChartType,
+} from '@utopia-studio-design/design-system/Charts'
+import type {
+  DatabaseQuery,
+  DatabaseRecord,
+  DatabaseSchema,
+} from '@utopia-studio-design/design-system/Database'
+import type { CeramicLayoutBlock } from '@utopia-studio-design/design-system/Composition'
+import { DatabaseTableBlock } from '../database-workspace/DatabaseWorkspaceBlocks'
+
+const LazyAnalyticsChartCard = React.lazy(async () => {
+  const module = await import('../analytics-dashboard/AnalyticsDashboardBlocks')
+  return { default: module.AnalyticsChartCard }
+})
+
+const issueSchema: DatabaseSchema = {
+  id: 'composer-issues',
+  title: 'Delivery issues',
+  primaryPropertyId: 'title',
+  properties: [
+    { id: 'title', label: 'Issue', type: 'text', required: true, width: 260 },
+    {
+      id: 'status',
+      label: 'Status',
+      type: 'select',
+      width: 150,
+      options: [
+        { id: 'active', label: 'Active', tone: 'warning' },
+        { id: 'backlog', label: 'Backlog' },
+        { id: 'blocked', label: 'Blocked', tone: 'negative' },
+        { id: 'completed', label: 'Completed', tone: 'positive' },
+      ],
+    },
+    {
+      id: 'priority',
+      label: 'Priority',
+      type: 'select',
+      width: 130,
+      options: [
+        { id: 'high', label: 'High', tone: 'negative' },
+        { id: 'medium', label: 'Medium', tone: 'warning' },
+        { id: 'low', label: 'Low' },
+      ],
+    },
+    { id: 'owner', label: 'Owner', type: 'person', width: 140 },
+    { id: 'due', label: 'Due', type: 'date', width: 150 },
+  ],
+}
+
+const issueRecords: DatabaseRecord[] = [
+  { id: 'issue-1', values: { title: 'Audit Arabic calendar navigation', status: 'active', priority: 'high', owner: 'Mina', due: '2026-08-01' } },
+  { id: 'issue-2', values: { title: 'Review visual-editor payload', status: 'active', priority: 'medium', owner: 'Aiden', due: '2026-08-03' } },
+  { id: 'issue-3', values: { title: 'Document registry permissions', status: 'backlog', priority: 'medium', owner: 'Haajar', due: '2026-08-05' } },
+  { id: 'issue-4', values: { title: 'Resolve mobile table overflow', status: 'blocked', priority: 'high', owner: 'Sora', due: '2026-07-31' } },
+  { id: 'issue-5', values: { title: 'Verify Button asChild regression', status: 'completed', priority: 'high', owner: 'Mina', due: '2026-07-29' } },
+  { id: 'issue-6', values: { title: 'Publish Calendar QA fixture', status: 'completed', priority: 'low', owner: 'Aiden', due: '2026-07-30' } },
+]
+
+const chartData: ChartDatum[] = [
+  { id: 'mon', label: 'Mon', values: { completed: 18, previous: 14 } },
+  { id: 'tue', label: 'Tue', values: { completed: 23, previous: 17 } },
+  { id: 'wed', label: 'Wed', values: { completed: 20, previous: 19 } },
+  { id: 'thu', label: 'Thu', values: { completed: 28, previous: 21 } },
+  { id: 'fri', label: 'Fri', values: { completed: 31, previous: 25 } },
+]
+
+const currentSeries: ChartSeriesDefinition = {
+  id: 'completed',
+  label: 'Completed work',
+  tone: 'primary',
+}
+const previousSeries: ChartSeriesDefinition = {
+  id: 'previous',
+  label: 'Previous period',
+  pattern: 'dash',
+  tone: 'benchmark',
+}
+
+function issueQuery(view: unknown): DatabaseQuery {
+  if (view === 'active') {
+    return {
+      filters: [{
+        id: 'active-issues',
+        propertyId: 'status',
+        operator: 'not-equals',
+        value: 'completed',
+      }],
+    }
+  }
+  if (view === 'backlog' || view === 'blocked' || view === 'completed') {
+    return {
+      filters: [{
+        id: `${view}-issues`,
+        propertyId: 'status',
+        operator: 'equals',
+        value: view,
+      }],
+    }
+  }
+  return {}
+}
+
+export function IssueTableRegistryBlock({
+  block,
+  direction,
+}: {
+  block: CeramicLayoutBlock
+  direction: 'ltr' | 'rtl'
+}) {
+  const requestedColumns = Array.isArray(block.props.columns)
+    ? block.props.columns.filter((column): column is string => typeof column === 'string')
+    : []
+  const visibleColumnIds = new Set(
+    requestedColumns.length
+      ? ['title', ...requestedColumns]
+      : issueSchema.properties.map((property) => property.id),
+  )
+  const density = (
+    block.props.density === 'compact'
+    || block.props.density === 'comfortable'
+    || block.props.density === 'default'
+  )
+    ? block.props.density
+    : 'default'
+
+  return (
+    <div className="ceramic-issue-table-block">
+      <DatabaseTableBlock
+        density={density}
+        direction={direction}
+        permissions={{
+          bulkActions: false,
+          edit: false,
+          reorderColumns: false,
+          reorderRows: false,
+          resizeColumns: false,
+        }}
+        query={issueQuery(block.props.view)}
+        records={issueRecords}
+        schema={{
+          ...issueSchema,
+          properties: issueSchema.properties.map((property) => ({
+            ...property,
+            hidden: !visibleColumnIds.has(property.id),
+          })),
+        }}
+        state="ready"
+      />
+    </div>
+  )
+}
+
+class ChartLoadBoundary extends React.Component<
+  { children: React.ReactNode },
+  { failed: boolean }
+> {
+  state = { failed: false }
+
+  static getDerivedStateFromError() {
+    return { failed: true }
+  }
+
+  componentDidCatch(error: Error) {
+    console.error('The registered chart renderer failed to load.', error)
+  }
+
+  render() {
+    if (this.state.failed) {
+      return (
+        <div className="ceramic-chart-panel-state" role="alert">
+          <strong>Chart preview could not load.</strong>
+          <span>The layout remains valid. Retry the optional visualization module.</span>
+          <Button size="sm" variant="outline" onClick={() => window.location.reload()}>
+            Retry chart
+          </Button>
+        </div>
+      )
+    }
+    return this.props.children
+  }
+}
+
+export function ChartPanelRegistryBlock({
+  block,
+  direction,
+}: {
+  block: CeramicLayoutBlock
+  direction: 'ltr' | 'rtl'
+}) {
+  const chartType = (
+    ['line', 'bar', 'area', 'stacked', 'scatter', 'donut'] as ChartType[]
+  ).includes(block.props.chartType as ChartType)
+    ? block.props.chartType as ChartType
+    : 'line'
+  const comparison = typeof block.props.comparison === 'string'
+    ? block.props.comparison
+    : 'previous-period'
+  const annotations: ChartAnnotationDefinition[] = comparison === 'benchmark'
+    ? [{ id: 'benchmark', label: 'Team benchmark', value: 24, tone: 'neutral' }]
+    : comparison === 'target'
+      ? [{ id: 'target', label: 'Weekly target', value: 30, tone: 'neutral' }]
+      : []
+  const series = comparison === 'previous-period'
+    ? [currentSeries, previousSeries]
+    : [currentSeries]
+
+  return (
+    <div className="ceramic-chart-panel-block" dir={direction}>
+      <ChartLoadBoundary>
+        <React.Suspense
+          fallback={(
+            <div className="ceramic-chart-panel-state" role="status">
+              Loading chart preview…
+            </div>
+          )}
+        >
+          <LazyAnalyticsChartCard
+            annotations={annotations}
+            data={chartData}
+            description="Completed delivery work by weekday"
+            direction={direction}
+            series={series}
+            showDataTable={block.props.showTable === true}
+            state="ready"
+            title="Delivery throughput"
+            type={chartType}
+          />
+        </React.Suspense>
+      </ChartLoadBoundary>
+    </div>
+  )
+}