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

package/data/templates/database-workspace/main.tsx

@@ -0,0 +1,247 @@
+import { StrictMode, useMemo, useRef, useState } from 'react'
+import { createRoot } from 'react-dom/client'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import type {
+  DatabaseMutationAdapter,
+  DatabaseQuery,
+  DatabaseRecord,
+  DatabaseSchema,
+  DatabaseState,
+  DatabaseView,
+} from '@utopia-studio-design/design-system/Database'
+import {
+  DatabaseTableBlock,
+  DatabaseToolbar,
+  RecordDetailDrawer,
+  SavedViewsBar,
+} from './DatabaseWorkspaceBlocks'
+import '@utopia-studio-design/design-system/core.css'
+import '@utopia-studio-design/design-system/themes/utopia-default.css'
+import './database-workspace.css'
+import './styles.css'
+
+const schema: DatabaseSchema = {
+  id: 'product-work',
+  title: 'Product work',
+  primaryPropertyId: 'title',
+  properties: [
+    { id: 'title', label: 'Work item', type: 'text', required: true, width: 260 },
+    {
+      id: 'status',
+      label: 'Status',
+      type: 'select',
+      width: 150,
+      options: [
+        { id: 'backlog', label: 'Backlog' },
+        { id: 'progress', label: 'In progress', tone: 'warning' },
+        { id: 'review', label: 'In review' },
+        { id: 'done', label: 'Done', tone: 'positive' },
+      ],
+    },
+    {
+      id: 'tags',
+      label: 'Tags',
+      type: 'multi-select',
+      width: 190,
+      options: [
+        { id: 'design', label: 'Design' },
+        { id: 'research', label: 'Research' },
+        { id: 'platform', label: 'Platform' },
+      ],
+    },
+    { id: 'due', label: 'Due date', type: 'date', width: 160 },
+    { id: 'owner', label: 'Owner', type: 'person', width: 150 },
+    { id: 'estimate', label: 'Estimate', type: 'number', min: 0, max: 100, width: 120 },
+    { id: 'approved', label: 'Approved', type: 'checkbox', width: 120 },
+    { id: 'reference', label: 'Reference', type: 'url', width: 240 },
+  ],
+}
+
+const titles = [
+  'Audit dashboard navigation',
+  'Define analytics empty states',
+  'Review record detail behavior',
+  'Test Arabic mixed-script labels',
+  'Document optimistic recovery',
+  'Validate mobile record cards',
+  'Measure virtual scroll latency',
+  'Prepare accessibility review',
+]
+const owners = ['Aiden', 'Mina', 'Haajar', 'Sora']
+const statuses = ['backlog', 'progress', 'review', 'done']
+
+const initialRecords: DatabaseRecord[] = Array.from({ length: 1000 }, (_, index) => ({
+  id: `record-${index + 1}`,
+  values: {
+    title: `${titles[index % titles.length]} ${index + 1}`,
+    status: statuses[index % statuses.length],
+    tags: index % 3 === 0 ? ['design', 'research'] : index % 3 === 1 ? ['platform'] : ['design'],
+    due: `2026-${String(((index + 7) % 12) + 1).padStart(2, '0')}-${String((index % 24) + 1).padStart(2, '0')}`,
+    owner: owners[index % owners.length],
+    estimate: (index % 13) + 1,
+    approved: index % 4 === 0,
+    reference: `https://example.com/work/${index + 1}`,
+  },
+}))
+
+const views: DatabaseView[] = [
+  { id: 'all', label: 'All work', query: {} },
+  {
+    id: 'active',
+    label: 'Active',
+    query: { filters: [{ id: 'active-status', propertyId: 'status', operator: 'not-equals', value: 'done' }] },
+  },
+  {
+    id: 'review',
+    label: 'In review',
+    query: { filters: [{ id: 'review-status', propertyId: 'status', operator: 'equals', value: 'review' }] },
+  },
+  {
+    id: 'compact',
+    label: 'Compact delivery',
+    query: { sorts: [{ propertyId: 'due', direction: 'ascending' }] },
+    hiddenPropertyIds: ['tags', 'reference'],
+  },
+  {
+    id: 'by-status',
+    label: 'By status',
+    query: { groupBy: 'status', sorts: [{ propertyId: 'due', direction: 'ascending' }] },
+  },
+]
+
+function App() {
+  const [records, setRecords] = useState(initialRecords)
+  const [activeViewId, setActiveViewId] = useState('all')
+  const [search, setSearch] = useState('')
+  const [direction, setDirection] = useState<'ltr' | 'rtl'>('ltr')
+  const [dark, setDark] = useState(false)
+  const [state, setState] = useState<DatabaseState>('ready')
+  const [canEdit, setCanEdit] = useState(true)
+  const [openRecord, setOpenRecord] = useState<DatabaseRecord | null>(null)
+  const [clipboardStatus, setClipboardStatus] = useState('Clipboard boundary idle')
+  const failNext = useRef(false)
+  const activeView = views.find((view) => view.id === activeViewId) ?? views[0]
+  const query = useMemo<DatabaseQuery>(() => ({
+    ...activeView.query,
+    filters: [
+      ...(activeView.query.filters ?? []),
+      ...(search
+        ? [{ id: 'search', propertyId: 'title', operator: 'contains' as const, value: search }]
+        : []),
+    ],
+  }), [activeView, search])
+  const adapter = useMemo<DatabaseMutationAdapter>(() => ({
+    async commit() {
+      const shouldFail = failNext.current
+      failNext.current = false
+      await new Promise((resolve) => window.setTimeout(resolve, 60))
+      if (shouldFail) throw new Error('Fixture mutation rejected')
+    },
+  }), [])
+
+  return (
+    <main
+      className="database-template"
+      data-color-mode={dark ? 'dark' : 'light'}
+      data-theme="utopia-default"
+      dir="ltr"
+      id="main-content"
+    >
+      <header className="database-template-header">
+        <div>
+          <span>Database workspace</span>
+          <h1>Plan product work as structured records</h1>
+          <p>1,000 records · schema-driven properties · controlled persistence</p>
+        </div>
+        <div>
+          <Button variant="outline" onClick={() => setDirection((value) => value === 'ltr' ? 'rtl' : 'ltr')}>
+            {direction === 'ltr' ? 'Switch grid to RTL' : 'Switch grid to LTR'}
+          </Button>
+          <Button variant="outline" onClick={() => setDark((value) => !value)}>
+            {dark ? 'Switch to light' : 'Switch to dark'}
+          </Button>
+        </div>
+      </header>
+
+      <section aria-label="Database fixture controls" className="database-fixture-controls">
+        <div>
+          <span>Data state</span>
+          <div>
+            {(['ready', 'loading', 'empty', 'error'] as DatabaseState[]).map((item) => (
+              <Button
+                aria-pressed={state === item}
+                key={item}
+                size="sm"
+                variant={state === item ? 'default' : 'outline'}
+                onClick={() => setState(item)}
+              >
+                {item}
+              </Button>
+            ))}
+          </div>
+        </div>
+        <Button aria-pressed={!canEdit} size="sm" variant="outline" onClick={() => setCanEdit((value) => !value)}>
+          {canEdit ? 'Test read-only permissions' : 'Enable editing'}
+        </Button>
+        <Button size="sm" variant="outline" onClick={() => { failNext.current = true }}>
+          Fail next save
+        </Button>
+      </section>
+
+      <section aria-labelledby="workspace-title" className="database-workspace">
+        <header>
+          <span>Workspace</span>
+          <h2 id="workspace-title">Product delivery database</h2>
+          <p>Double-click or press Enter on a cell to edit. Arrow keys move by logical grid direction.</p>
+        </header>
+        <SavedViewsBar activeViewId={activeViewId} views={views} onViewChange={setActiveViewId} />
+        <DatabaseToolbar
+          activeFilterCount={query.filters?.length}
+          activeSortCount={query.sorts?.length}
+          groupLabel={query.groupBy ? schema.properties.find((property) => property.id === query.groupBy)?.label : undefined}
+          searchValue={search}
+          onCreate={() => setRecords((current) => [{
+            id: `record-${current.length + 1}`,
+            values: { title: 'Untitled work item', status: 'backlog', tags: [], due: null, owner: null, estimate: null, approved: false, reference: null },
+          }, ...current])}
+          onSearchChange={setSearch}
+        />
+        <output aria-live="polite" className="database-clipboard-status">{clipboardStatus}</output>
+        <DatabaseTableBlock
+          adapter={adapter}
+          direction={direction}
+          permissions={{
+            edit: canEdit,
+            bulkActions: canEdit,
+            reorderColumns: canEdit,
+            reorderRows: canEdit,
+            resizeColumns: canEdit,
+          }}
+          query={query}
+          records={records}
+          schema={{ ...schema, properties: schema.properties.map((property) => ({
+            ...property,
+            hidden: activeView.hiddenPropertyIds?.includes(property.id),
+          })) }}
+          state={state}
+          onCopyCell={(text, _recordId, propertyId) => setClipboardStatus(`Copied ${propertyId}: ${text}`)}
+          onPasteCell={(_recordId, propertyId) => setClipboardStatus(`Paste requested for ${propertyId}`)}
+          onRecordOpen={setOpenRecord}
+          onRecordsChange={setRecords}
+        />
+      </section>
+      <RecordDetailDrawer
+        open={Boolean(openRecord)}
+        record={openRecord}
+        schema={schema}
+        onClose={() => setOpenRecord(null)}
+      />
+    </main>
+  )
+}
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/data/templates/database-workspace/styles.css

@@ -0,0 +1,121 @@
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  min-block-size: 100%;
+  margin: 0;
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}
+
+.skip-link {
+  position: fixed;
+  inset-block-start: var(--space-2);
+  inset-inline-start: var(--space-2);
+  z-index: var(--z-modal);
+  translate: 0 -200%;
+}
+
+.skip-link:focus {
+  translate: 0;
+}
+
+.database-template {
+  min-block-size: 100vh;
+  padding: var(--page-gutter);
+  background: var(--background);
+  color: var(--foreground);
+}
+
+.database-template > * {
+  max-inline-size: var(--container-wide);
+  margin-inline: auto;
+}
+
+.database-template-header {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: var(--space-6);
+  padding-block: var(--space-6);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.database-template-header > div:first-child,
+.database-workspace,
+.database-workspace > header {
+  display: grid;
+  gap: var(--space-2);
+}
+
+.database-template-header > div:last-child,
+.database-fixture-controls,
+.database-fixture-controls > div > div {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+
+.database-template :is(h1, h2, p) {
+  margin: 0;
+}
+
+.database-template-header span,
+.database-fixture-controls > div > span,
+.database-workspace > 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;
+}
+
+.database-template-header p,
+.database-workspace > header p {
+  color: var(--muted-foreground);
+}
+
+.database-fixture-controls {
+  align-items: end;
+  justify-content: space-between;
+  padding-block: var(--space-4);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.database-fixture-controls > div {
+  display: grid;
+  gap: var(--space-2);
+}
+
+.database-workspace {
+  min-inline-size: 0;
+  padding-block: var(--space-6);
+}
+
+.database-clipboard-status {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-sm);
+}
+
+@media (max-width: 44rem) {
+  .database-template-header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .database-template-header > div:last-child {
+    display: grid;
+  }
+
+  .database-fixture-controls {
+    align-items: stretch;
+    flex-direction: column;
+  }
+}

package/data/templates/database-workspace/template.manifest.json

@@ -0,0 +1,19 @@
+{
+  "id": "database-workspace",
+  "title": "Database Workspace",
+  "status": "available",
+  "route": "/templates/database-workspace/",
+  "entry": "templates/database-workspace/main.tsx",
+  "blocks": [
+    "database-toolbar",
+    "database-table-block",
+    "saved-views-bar",
+    "record-detail-drawer",
+    "bulk-action-bar"
+  ],
+  "states": ["loading", "empty", "error", "ready"],
+  "themes": ["utopia-default"],
+  "directions": ["ltr", "rtl"],
+  "responsiveMinimum": "320px",
+  "largeFixtureRecords": 1000
+}

package/data/templates/interaction-lab/InteractionWorkbench.tsx

@@ -0,0 +1,271 @@
+import * as React from 'react'
+import {
+  createCommandHistory,
+  findTypeaheadMatch,
+  getGridNavigationTarget,
+  getVirtualRange,
+  reorderItems,
+  updateSelection,
+  type InteractionCommand,
+  type SelectionState,
+} from '@utopia-studio-design/design-system/Interaction'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import './interaction-workbench.css'
+
+type WorkItem = { id: string; label: string }
+
+const initialItems: WorkItem[] = [
+  { id: 'intake', label: 'Intake' },
+  { id: 'review', label: 'Review' },
+  { id: 'decision', label: 'Decision' },
+  { id: 'delivery', label: 'Delivery' },
+  { id: 'follow-up', label: 'Follow up' },
+  { id: 'archive', label: 'Archive' },
+]
+
+const compactStageQuery = '(max-width: 44rem)'
+
+function useStageColumnCount() {
+  const [columnCount, setColumnCount] = React.useState(2)
+
+  React.useEffect(() => {
+    const media = window.matchMedia(compactStageQuery)
+    const update = () => setColumnCount(media.matches ? 1 : 2)
+    update()
+    media.addEventListener('change', update)
+    return () => media.removeEventListener('change', update)
+  }, [])
+
+  return columnCount
+}
+
+function reorderCommand(items: WorkItem[], fromIndex: number, toIndex: number): InteractionCommand<WorkItem[]> {
+  const next = reorderItems(items, fromIndex, toIndex).items
+  return {
+    label: `Move ${items[fromIndex]?.label ?? 'item'}`,
+    execute: () => next,
+    undo: () => items,
+  }
+}
+
+export function InteractionWorkbench({ direction = 'ltr' }: { direction?: 'ltr' | 'rtl' }) {
+  const [items, setItems] = React.useState(initialItems)
+  const history = React.useRef(createCommandHistory(initialItems, setItems))
+  const [selection, setSelection] = React.useState<SelectionState<string>>({
+    selectedKeys: new Set(),
+    anchorKey: null,
+  })
+  const [activeIndex, setActiveIndex] = React.useState(0)
+  const [width, setWidth] = React.useState(320)
+  const [scrollOffset, setScrollOffset] = React.useState(0)
+  const [announcement, setAnnouncement] = React.useState('Interaction workbench ready')
+  const [typeahead, setTypeahead] = React.useState('')
+  const itemRefs = React.useRef<Array<HTMLButtonElement | null>>([])
+  const dragIndex = React.useRef<number | null>(null)
+  const columnCount = useStageColumnCount()
+  const virtual = getVirtualRange({
+    itemCount: 1000,
+    itemSize: 36,
+    viewportSize: 180,
+    scrollOffset,
+    overscan: 3,
+  })
+
+  const focusIndex = (index: number) => {
+    setActiveIndex(index)
+    requestAnimationFrame(() => itemRefs.current[index]?.focus())
+  }
+
+  const move = (fromIndex: number, toIndex: number) => {
+    if (toIndex < 0 || toIndex >= items.length || fromIndex === toIndex) return
+    const moved = items[fromIndex]
+    history.current.execute(reorderCommand(items, fromIndex, toIndex))
+    setAnnouncement(`${moved.label} moved to position ${toIndex + 1} of ${items.length}`)
+    focusIndex(toIndex)
+  }
+
+  const onItemKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>, index: number) => {
+    if (columnCount === 1 && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) return
+    const navigationTarget = getGridNavigationTarget({
+      currentIndex: index,
+      itemCount: items.length,
+      columnCount,
+      key: event.key,
+      direction,
+    })
+    if (navigationTarget !== index) {
+      event.preventDefault()
+      focusIndex(navigationTarget)
+      return
+    }
+    if (event.key === ' ' || event.key === 'Enter') {
+      event.preventDefault()
+      setSelection((current) => updateSelection({
+        state: current,
+        orderedKeys: items.map((item) => item.id),
+        key: items[index].id,
+        behavior: event.shiftKey ? 'range' : event.metaKey || event.ctrlKey ? 'toggle' : 'replace',
+      }))
+      return
+    }
+    if (event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {
+      const query = `${typeahead}${event.key}`
+      const match = findTypeaheadMatch(items.map((item) => item.label), query, index)
+      setTypeahead(query)
+      window.setTimeout(() => setTypeahead(''), 500)
+      if (match >= 0) focusIndex(match)
+    }
+  }
+
+  return (
+    <section className="interaction-workbench" dir={direction} aria-labelledby="interaction-workbench-title">
+      <header>
+        <div>
+          <p className="interaction-eyebrow">Hands-on review</p>
+          <h2 id="interaction-workbench-title">Try the shared interactions</h2>
+          <p className="interaction-supporting">The same behavior will be reused by charts, tables, and calendars.</p>
+        </div>
+        <div className="interaction-history" aria-label="History controls">
+          <Button size="sm" variant="outline" disabled={!history.current.canUndo()} onClick={() => {
+            history.current.undo()
+            setAnnouncement('Last move undone')
+          }}>Undo</Button>
+          <Button size="sm" variant="outline" disabled={!history.current.canRedo()} onClick={() => {
+            history.current.redo()
+            setAnnouncement('Move redone')
+          }}>Redo</Button>
+        </div>
+      </header>
+
+      <div className="interaction-layout">
+        <div className="interaction-panel">
+          <div className="interaction-panel-heading">
+            <div>
+              <p className="interaction-step">Task 1</p>
+              <h3>Select and move workflow stages</h3>
+            </div>
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={() => setSelection((current) => updateSelection({
+                state: current,
+                orderedKeys: items.map((item) => item.id),
+                behavior: 'all',
+              }))}
+            >
+              Select all
+            </Button>
+          </div>
+          <p className="interaction-instruction">
+            Try clicking a stage, pressing Space, dragging it, or using the − / + move buttons. Undo should restore the previous order.
+          </p>
+          <div className="interaction-current-actions" aria-label="Move focused stage">
+            <span>Focused stage: <strong>{items[activeIndex]?.label}</strong></span>
+            <div>
+              <Button
+                aria-label={`Move ${items[activeIndex]?.label} earlier`}
+                disabled={activeIndex === 0}
+                onClick={() => move(activeIndex, activeIndex - 1)}
+                size="sm"
+                variant="outline"
+              >
+                − Move earlier
+              </Button>
+              <Button
+                aria-label={`Move ${items[activeIndex]?.label} later`}
+                disabled={activeIndex === items.length - 1}
+                onClick={() => move(activeIndex, activeIndex + 1)}
+                size="sm"
+                variant="outline"
+              >
+                + Move later
+              </Button>
+            </div>
+          </div>
+          <ul
+            aria-label="Workflow stages"
+            className="interaction-grid"
+            data-column-count={columnCount}
+          >
+            {items.map((item, index) => (
+              <li className="interaction-item-shell" key={item.id}>
+                <button
+                  aria-pressed={selection.selectedKeys.has(item.id)}
+                  className="interaction-item"
+                  data-workflow-stage
+                  draggable
+                  onDragStart={() => { dragIndex.current = index }}
+                  onDragOver={(event) => event.preventDefault()}
+                  onDrop={() => {
+                    if (dragIndex.current !== null) move(dragIndex.current, index)
+                    dragIndex.current = null
+                  }}
+                  onKeyDown={(event) => onItemKeyDown(event, index)}
+                  onClick={() => {
+                    setActiveIndex(index)
+                    setSelection((current) => updateSelection({
+                      state: current,
+                      orderedKeys: items.map((entry) => entry.id),
+                      key: item.id,
+                      behavior: 'replace',
+                    }))
+                  }}
+                  onFocus={() => setActiveIndex(index)}
+                  ref={(node) => { itemRefs.current[index] = node }}
+                  tabIndex={activeIndex === index ? 0 : -1}
+                  type="button"
+                >
+                  <span>{item.label}</span>
+                  <small>{index + 1}</small>
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
+
+        <div className="interaction-panel">
+          <div>
+            <p className="interaction-step">Task 2</p>
+            <h3>Resize and scroll a large list</h3>
+          </div>
+          <p className="interaction-instruction">
+            Change the panel width, then scroll toward record 1,000. Only the visible rows should render and the page itself should never scroll sideways.
+          </p>
+          <label className="interaction-resize">
+            <span>Panel inline size</span>
+            <output>{width}px</output>
+            <input min="240" max="480" step="8" type="range" value={width} onChange={(event) => setWidth(event.currentTarget.valueAsNumber)} />
+          </label>
+          <div className="interaction-virtual-shell" style={{ inlineSize: `min(100%, ${width}px)` }}>
+            <div
+              className="interaction-virtual-scroll"
+              onScroll={(event) => setScrollOffset(event.currentTarget.scrollTop)}
+              tabIndex={0}
+              aria-label="One thousand virtualized records"
+              role="list"
+            >
+              <div style={{ blockSize: virtual.totalSize, position: 'relative' }}>
+                {Array.from({ length: virtual.endIndex - virtual.startIndex + 1 }, (_, offset) => {
+                  const index = virtual.startIndex + offset
+                  return (
+                    <div
+                      aria-posinset={index + 1}
+                      aria-setsize={1000}
+                      className="interaction-virtual-row"
+                      key={index}
+                      role="listitem"
+                      style={{ insetBlockStart: index * 36 }}
+                    >
+                      Record {String(index + 1).padStart(4, '0')}
+                    </div>
+                  )
+                })}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <p aria-live="polite" className="interaction-announcement"><strong>Result:</strong> {announcement}</p>
+    </section>
+  )
+}

package/data/templates/interaction-lab/README.md

@@ -0,0 +1,7 @@
+# Ceramic Interaction Lab
+
+Use this runnable template while building Charts, Database, Calendar, or
+Scheduler surfaces. It exercises the shared interaction foundation with
+deterministic local data and no product-specific workflow.
+
+Run at 320px and desktop widths, in LTR and RTL, with reduced motion enabled.

package/data/templates/interaction-lab/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" dir="ltr" data-theme="utopia-default" data-color-mode="light">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Ceramic shared interaction contract lab." />
+    <title>Ceramic Interaction Lab</title>
+  </head>
+  <body>
+    <a class="skip-link" href="#main-content">Skip to interaction lab</a>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>