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

package/data/templates/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/templates/dashboard-composer/DatabaseWorkspaceBlocks.tsx

@@ -0,0 +1,240 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import {
+  DatabasePropertyCell,
+  DatabaseRoot,
+  type DatabaseMutationAdapter,
+  type DatabasePermissions,
+  type DatabaseQuery,
+  type DatabaseRecord,
+  type DatabaseSchema,
+  type DatabaseState,
+  type DatabaseView,
+} from '@utopia-studio-design/design-system/Database'
+import './database-workspace.css'
+
+export interface DatabaseToolbarProps extends React.HTMLAttributes<HTMLElement> {
+  activeFilterCount?: number
+  activeSortCount?: number
+  groupLabel?: string
+  onCreate?: () => void
+  onFilter?: () => void
+  onSearchChange?: (value: string) => void
+  onSort?: () => void
+  searchValue?: string
+}
+
+export function DatabaseToolbar({
+  activeFilterCount = 0,
+  activeSortCount = 0,
+  groupLabel,
+  onCreate,
+  onFilter,
+  onSearchChange,
+  onSort,
+  searchValue = '',
+  ...props
+}: DatabaseToolbarProps) {
+  return (
+    <header className="ceramic-database-toolbar" {...props}>
+      <label>
+        <span className="uds-visually-hidden">Search records</span>
+        <input
+          placeholder="Search records"
+          type="search"
+          value={searchValue}
+          onChange={(event) => onSearchChange?.(event.target.value)}
+        />
+      </label>
+      <div>
+        <Button size="sm" variant="outline" onClick={onFilter}>
+          Filter {activeFilterCount ? `(${activeFilterCount})` : ''}
+        </Button>
+        <Button size="sm" variant="outline" onClick={onSort}>
+          Sort {activeSortCount ? `(${activeSortCount})` : ''}
+        </Button>
+        {groupLabel ? <Badge variant="outline">Grouped by {groupLabel}</Badge> : null}
+      </div>
+      <Button size="sm" onClick={onCreate}>New record</Button>
+    </header>
+  )
+}
+
+export interface SavedViewsBarProps extends React.HTMLAttributes<HTMLElement> {
+  activeViewId: string
+  onViewChange?: (viewId: string) => void
+  views: DatabaseView[]
+}
+
+export function SavedViewsBar({
+  activeViewId,
+  onViewChange,
+  views,
+  ...props
+}: SavedViewsBarProps) {
+  return (
+    <nav aria-label="Workspace views" className="ceramic-saved-views" {...props}>
+      {views.map((view) => (
+        <Button
+          aria-current={activeViewId === view.id ? 'page' : undefined}
+          key={view.id}
+          size="sm"
+          variant={activeViewId === view.id ? 'secondary' : 'ghost'}
+          onClick={() => onViewChange?.(view.id)}
+        >
+          {view.label}
+        </Button>
+      ))}
+    </nav>
+  )
+}
+
+export interface DatabaseTableBlockProps extends React.HTMLAttributes<HTMLElement> {
+  adapter?: DatabaseMutationAdapter
+  density?: 'compact' | 'default' | 'comfortable'
+  direction?: 'ltr' | 'rtl'
+  locale?: string
+  onRecordOpen?: (record: DatabaseRecord) => void
+  onCopyCell?: (text: string, recordId: string, propertyId: string) => void
+  onPasteCell?: (recordId: string, propertyId: string) => void
+  onRecordsChange?: (records: DatabaseRecord[]) => void
+  permissions?: DatabasePermissions
+  query?: DatabaseQuery
+  records: DatabaseRecord[]
+  schema: DatabaseSchema
+  state?: DatabaseState
+  views?: DatabaseView[]
+}
+
+export function DatabaseTableBlock({
+  adapter,
+  density,
+  direction,
+  locale,
+  onRecordOpen,
+  onCopyCell,
+  onPasteCell,
+  onRecordsChange,
+  permissions,
+  query,
+  records,
+  schema,
+  state,
+  views,
+  ...props
+}: DatabaseTableBlockProps) {
+  return (
+    <DatabaseRoot
+      adapter={adapter}
+      density={density}
+      direction={direction}
+      locale={locale}
+      permissions={permissions}
+      query={query}
+      records={records}
+      schema={schema}
+      state={state}
+      views={views}
+      onRecordOpen={onRecordOpen}
+      onCopyCell={onCopyCell}
+      onPasteCell={onPasteCell}
+      onRecordsChange={onRecordsChange}
+      {...props}
+    />
+  )
+}
+
+export interface RecordDetailDrawerProps extends React.HTMLAttributes<HTMLElement> {
+  onClose?: () => void
+  open: boolean
+  record: DatabaseRecord | null
+  schema: DatabaseSchema
+}
+
+export function RecordDetailDrawer({
+  onClose,
+  open,
+  record,
+  schema,
+  ...props
+}: RecordDetailDrawerProps) {
+  const drawerRef = React.useRef<HTMLElement>(null)
+  const closeRef = React.useRef<HTMLButtonElement>(null)
+  React.useLayoutEffect(() => {
+    if (!open || !record) return
+    const trigger = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    closeRef.current?.focus()
+    return () => trigger?.focus()
+  }, [open, record])
+  if (!open || !record) return null
+  return (
+    <>
+      <div aria-hidden="true" className="ceramic-record-drawer-backdrop" onClick={onClose} />
+      <aside
+        aria-label="Record details"
+        aria-modal="true"
+        className="ceramic-record-drawer"
+        ref={drawerRef}
+        role="dialog"
+        onKeyDown={(event) => {
+          if (event.key === 'Escape') {
+            event.preventDefault()
+            onClose?.()
+            return
+          }
+          if (event.key !== 'Tab') return
+          const focusable = [...(drawerRef.current?.querySelectorAll<HTMLElement>(
+            'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+          ) ?? [])]
+          if (focusable.length === 0) return
+          const first = focusable[0]
+          const last = focusable.at(-1)!
+          if (event.shiftKey && document.activeElement === first) {
+            event.preventDefault()
+            last.focus()
+          } else if (!event.shiftKey && document.activeElement === last) {
+            event.preventDefault()
+            first.focus()
+          }
+        }}
+        {...props}
+      >
+        <header>
+          <div>
+            <span>Record detail</span>
+            <h2>{String(record.values[schema.primaryPropertyId] ?? 'Untitled')}</h2>
+          </div>
+          <Button ref={closeRef} aria-label="Close record details" isIconOnly variant="ghost" onClick={onClose}>×</Button>
+        </header>
+        <dl>
+          {schema.properties.map((property) => (
+            <div key={property.id}>
+              <dt>{property.label}</dt>
+              <dd>
+                <DatabasePropertyCell property={property} value={record.values[property.id]} />
+              </dd>
+            </div>
+          ))}
+        </dl>
+      </aside>
+    </>
+  )
+}
+
+export interface BulkActionBarProps extends React.HTMLAttributes<HTMLElement> {
+  count: number
+  onClear?: () => void
+  onDelete?: () => void
+}
+
+export function BulkActionBar({ count, onClear, onDelete, ...props }: BulkActionBarProps) {
+  if (count === 0) return null
+  return (
+    <div aria-label="Selected record actions" className="ceramic-bulk-action-bar" role="toolbar" {...props}>
+      <strong>{count} selected</strong>
+      <Button size="sm" variant="ghost" onClick={onClear}>Clear</Button>
+      <Button size="sm" variant="destructive" onClick={onDelete}>Delete</Button>
+    </div>
+  )
+}

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

@@ -0,0 +1,53 @@
+# Dashboard Composer
+
+A runnable example of the missing runtime layer between Ceramic Layout JSON and
+real dashboard blocks.
+
+It renders To-do, Calendar, Issue Table, Chart Panel, Activity Feed, Agent
+Status, and Metrics through a product-supplied renderer map, validates every
+layout and agent mutation, preserves locked regions, and exposes
+keyboard/touch-accessible arrange controls.
+
+`/visual-editor/` adds Puck as an optional editing layer. Its component palette,
+editable fields, defaults, and permissions are generated from the Ceramic
+Composition Registry. Puck Data is converted back to Layout JSON and must pass
+`validateCeramicAgentMutation` before publish is accepted. Product tasks,
+events, authorization, and persistence remain outside both documents. The route
+renders a 3 KB Ceramic boot shell first, then lazy-loads registered block
+previews and editing controls, followed by the Puck surface and its CSS. Runtime
+and state-lab routes never download that optional editor payload. The editor
+uses Puck's `no-external.css` entry so it does not request a hosted Inter font;
+its chrome maps Puck's public CSS variables to Ceramic semantic surface, text,
+interaction, focus, radius, typography, and motion tokens in light and dark
+modes.
+
+`/agent-status-lab/` renders loading, empty, recoverable error, filtered-empty,
+and ready/approval states from the same production block. It is the deterministic
+browser fixture for resilience, retry feedback, Arabic/RTL, dark mode, and
+mobile reflow.
+
+The Calendar renderer uses the shared `calendar-panel-contract` resolver.
+Changing locale, direction mode, timezone, week start, secondary calendar, or
+view through Layout JSON therefore produces the same Scheduler configuration
+in the runtime and the visual editor.
+
+The Activity Feed renderer uses `activity-feed-contract` for density, grouping,
+locale, direction, timezone, source visibility, and pagination size. The
+application continues to own localized activity records and backend cursors.
+
+The Agent Status renderer uses `agent-status-contract` for density, semantic
+filtering, locale, direction, timezone, approval visibility, and item limits.
+The application continues to own execution records and approve/reject
+callbacks; summaries must already be sanitized.
+
+The Metrics renderer imports `KPIGrid` from `AnalyticsMetricBlocks.tsx`.
+Metric-only compositions therefore keep the locale-aware KPI API without
+preloading Recharts or the analytics chart explorer.
+
+The Issue Table consumes `view`, `density`, and governed `columns` while issue
+records, permissions, and persistence remain product-owned. The Chart Panel
+consumes `chartType`, `comparison`, and `showTable`; its Recharts-backed
+renderer is lazy-loaded only when a registered chart block is present.
+
+Install `@puckeditor/core@^0.22.4` when copying the optional visual-editor
+route into a consumer application.