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

package/data/blocks/interaction-workbench/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/blocks/interaction-workbench/README.md

@@ -0,0 +1,9 @@
+# Interaction Workbench
+
+This block is a test fixture and implementation reference for Ceramic's shared
+interaction contract. Keep product data and business rules outside the block.
+
+The example includes responsive logical grid navigation, range/select-all
+behavior, typeahead, pointer drag, a focused-stage move toolbar for keyboard and
+touch, resize, fixed-size virtualization with explicit list semantics, undo, an
+ARIA live region, RTL, reduced motion, and a 320px layout.

package/data/blocks/interaction-workbench/interaction-workbench.css

@@ -0,0 +1,226 @@
+.interaction-workbench {
+  display: grid;
+  gap: var(--interaction-density-comfortable);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  color: var(--foreground);
+}
+
+.interaction-workbench > header,
+.interaction-panel-heading,
+.interaction-resize {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+}
+
+.interaction-workbench h2,
+.interaction-workbench h3,
+.interaction-workbench p {
+  margin: 0;
+}
+
+.interaction-supporting,
+.interaction-instruction {
+  color: var(--muted-foreground);
+}
+
+.interaction-supporting {
+  margin-block-start: var(--space-1);
+}
+
+.interaction-instruction {
+  max-inline-size: 62ch;
+  font-size: var(--font-size-small);
+  line-height: var(--line-height-body);
+}
+
+.interaction-step {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-eyebrow);
+  font-weight: var(--font-weight-semibold);
+  letter-spacing: var(--tracking-eyebrow);
+  text-transform: uppercase;
+}
+
+.interaction-eyebrow {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-eyebrow);
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-eyebrow);
+}
+
+.interaction-history,
+.interaction-current-actions > div {
+  display: flex;
+  gap: var(--space-1);
+}
+
+.interaction-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(16rem, .75fr);
+  gap: var(--space-4);
+  min-inline-size: 0;
+}
+
+.interaction-panel {
+  display: grid;
+  align-content: start;
+  gap: var(--interaction-density-default);
+  min-inline-size: 0;
+  padding: var(--space-3);
+  border: var(--border-width-hairline) solid var(--border);
+  border-radius: var(--radius-surface);
+  background: var(--surface);
+}
+
+.interaction-panel > div:first-child h3 {
+  margin-block-start: var(--space-1);
+}
+
+.interaction-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--interaction-density-compact);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.interaction-item-shell {
+  min-inline-size: 0;
+}
+
+.interaction-item {
+  border: var(--border-width-hairline) solid var(--border);
+  border-radius: var(--radius-control);
+  background: var(--background);
+  color: var(--foreground);
+  font: inherit;
+}
+
+.interaction-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  min-block-size: var(--button-height);
+  min-inline-size: 0;
+  padding-inline: var(--space-3);
+  text-align: start;
+  cursor: grab;
+}
+
+.interaction-item[aria-pressed='true'] {
+  border-color: var(--interaction-selection-border);
+  background: var(--interaction-selection-surface);
+}
+
+.interaction-item[draggable='true']:active {
+  border-color: var(--interaction-drag-border);
+  background: var(--interaction-drag-surface);
+}
+
+.interaction-item:focus-visible,
+.interaction-virtual-scroll:focus-visible,
+.interaction-resize input:focus-visible {
+  outline: var(--focus-ring-width) solid var(--interaction-focus);
+  outline-offset: var(--focus-ring-offset);
+}
+
+.interaction-current-actions {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  min-inline-size: 0;
+}
+
+.interaction-current-actions > span {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+.interaction-current-actions button {
+  min-block-size: var(--interaction-target-min);
+}
+
+.interaction-resize {
+  flex-wrap: wrap;
+}
+
+.interaction-resize input {
+  inline-size: 100%;
+}
+
+.interaction-virtual-shell {
+  max-inline-size: 100%;
+  min-inline-size: 0;
+}
+
+.interaction-virtual-scroll {
+  block-size: 180px;
+  max-inline-size: 100%;
+  overflow: auto;
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--background);
+}
+
+.interaction-virtual-row {
+  position: absolute;
+  inset-inline: 0;
+  display: flex;
+  align-items: center;
+  block-size: 36px;
+  padding-inline: var(--space-3);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.interaction-announcement {
+  min-block-size: var(--button-height);
+  padding: var(--space-3);
+  border-inline-start: var(--border-width-strong) solid var(--interaction-selection-border);
+  background: var(--interaction-selection-surface);
+  color: var(--foreground);
+  font-size: var(--font-size-small);
+}
+
+@media (max-width: 44rem) {
+  .interaction-workbench > header,
+  .interaction-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .interaction-workbench > header {
+    display: grid;
+  }
+
+  .interaction-history {
+    inline-size: 100%;
+  }
+
+  .interaction-current-actions {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .interaction-current-actions > div {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .interaction-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .interaction-workbench *,
+  .interaction-workbench *::before,
+  .interaction-workbench *::after {
+    scroll-behavior: auto;
+    transition-duration: 0ms;
+    animation-duration: 0ms;
+  }
+}

package/data/docs/calendar.md

@@ -0,0 +1,164 @@
+# Ceramic Calendar
+
+Ceramic Calendar is a timezone-aware application scheduler for month, week,
+day, and agenda workflows. It provides interaction, recurrence, conflict,
+permission, and mutation contracts; the consuming product still owns
+persistence, authorization, localization, and domain-specific scheduling rules.
+
+The application layer is composed from Ceramic's Shadcn-derived primitives:
+the sidebar uses the `react-day-picker` Calendar contract, toolbars use
+`Button`, `IconButton`, and `ButtonGroup`, timezone selection uses the themed
+Radix `Select`, and event editing uses Ceramic form controls. The scheduler
+engine remains custom because Shadcn's Calendar is a date-selection primitive,
+not a multi-resource event scheduler.
+
+```tsx
+import {
+  SchedulerRoot,
+  type SchedulerEvent,
+  type SchedulerMutationAdapter,
+} from '@utopia-studio-design/design-system/Calendar'
+```
+
+## Stable contracts
+
+- Events are stored as ISO instants with stable IDs. Changing the display
+  timezone changes labels and placement without rewriting those instants.
+- Calendar cells represent civil dates, not instants. Their `dateTime` values
+  are built from local year/month/day parts; never derive a cell date with
+  `toISOString().slice(0, 10)`, which can shift the day outside UTC.
+- Recurrence supports daily and weekly series, bounded expansion, occurrence
+  identity, and explicit exceptions.
+- `SchedulerMutationAdapter` commits create, update, move, resize, duplicate,
+  and delete mutations. Failed commits restore the previous event collection.
+- `SchedulerPermissions` gates every mutation independently. Hidden or disabled
+  controls never replace server-side authorization.
+- Availability and event overlap checks return explicit conflict reasons rather
+  than silently moving or truncating an event.
+
+## Keyboard and accessibility
+
+- Every event is a named button. Enter opens the event editor.
+- `Alt+ArrowUp/ArrowDown` moves an event by 15 minutes.
+- `Alt+Shift+ArrowUp/ArrowDown` resizes an event by 15 minutes.
+- `Ctrl/Cmd+D` duplicates and Delete removes an event when permitted.
+- Selecting an event also exposes equivalent pointer and touch actions.
+- Month dates use one roving tab stop. Arrow keys move by day or week,
+  Home/End move to the logical week boundary, and RTL reverses horizontal
+  movement to match the visual grid.
+- Month exposes a named ARIA grid with one column-header row, six week rows,
+  seven grid cells per week, and `aria-selected` on the active civil date.
+- Week, day, and month views retain an accessible agenda alternative.
+- The event editor traps focus, closes with Escape, and restores focus to its
+  trigger.
+- The editor keeps incomplete date/time text as a local draft instead of
+  converting it on every keystroke. Required fields and `end > start` are
+  validated in the drawer, associated with their controls, and focus the first
+  invalid field without throwing a runtime error.
+- `EventEditorDrawer.onSave` may be synchronous or return a Promise. While a
+  Promise is pending the form is busy and duplicate submission or dismissal is
+  blocked. A rejected save keeps the edited values, exposes a localized alert,
+  and focuses that alert so the user can retry or cancel.
+- Unsaved drafts should pass `canDelete={false}`. Existing-event deletion
+  remains controlled through `onDelete`; persistence and confirmation policy
+  stay with the consuming product.
+- `SchedulerRoot.onEventEdit` and `onEventCreate` receive the invoking
+  `HTMLElement` as an optional second argument. Store it in a ref and pass that
+  ref to `EventEditorDrawer.returnFocusRef`; relying only on
+  `document.activeElement` does not restore pointer focus reliably in Safari.
+- Logical inline placement mirrors under RTL. Dates, times, and stored instants
+  keep their locale and timezone meaning.
+- View buttons keep `labels.view` as their accessible and wide-layout name.
+  Supply `labels.compactView` when a localized mobile label needs a shorter,
+  semantically equivalent form.
+- Month overflow counts keep `labels.more` as their accessible and wide-layout
+  name. Supply `labels.compactMore` for a localized narrow-cell form such as
+  `+٢`.
+
+## Responsive behavior
+
+When no explicit view is requested, the runnable application starts in day view
+below 44rem and week view at wider sizes. An explicit `?view=week` remains week
+view at every viewport. On narrow screens its seven days stay available inside
+the scheduler's own horizontally scrolling surface; the selected date is
+scrolled into view instead of hiding the other six days. Logical scroll
+containment and proximity snapping keep physical LTR and RTL swipe gestures
+inside the scheduler rather than widening or moving the document.
+
+The date navigator remains one logical row when space permits, the four view
+choices retain their full accessible names, and New Event becomes a touch-sized
+icon action without losing that name. Month uses localized weekday headings,
+a compact narrow label at mobile widths, selectable dates, and small event
+indicators while retaining each event's accessible name. Month and week own
+their overflow, and agenda provides the compact reading and touch alternative.
+The document itself must never gain horizontal overflow.
+
+## Locale, RTL, and calendar systems
+
+Arabic is not one scheduling convention. Pass the actual regional locale and
+let `getSchedulerLocaleWeekInfo(locale)` resolve the first day of the week and
+weekend:
+
+- `ar-SA`: Sunday start, Friday–Saturday weekend.
+- `ar-EG`: Saturday start, Friday–Saturday weekend.
+- `ar-AE`: Monday start, Saturday–Sunday weekend.
+
+`SchedulerRoot` accepts `locale`, `direction`, `weekStartsOn`, `weekendDays`,
+`numberingSystem`, `calendarSystem`, `secondaryCalendar`, and localized
+`labels`. Gregorian dates remain the scheduling and persistence coordinate
+system. A Hijri calendar such as `islamic-umalqura` can be shown as a secondary
+date without changing event placement.
+
+When `direction` is omitted, `SchedulerRoot` derives `ltr` or `rtl` from the
+locale through `Intl.Locale` and a script fallback. Pass `direction` only when
+the surrounding product deliberately overrides the locale direction.
+
+```tsx
+const week = getSchedulerLocaleWeekInfo('ar-SA')
+
+<SchedulerRoot
+  calendarSystem="gregory"
+  labels={arabicLabels}
+  locale="ar-SA"
+  secondaryCalendar="islamic-umalqura"
+  weekendDays={week.weekend}
+  weekStartsOn={week.firstDay}
+/>
+```
+
+Do not infer Hijri usage from Arabic language alone. Products must choose the
+calendar system explicitly. Ceramic wraps mixed-direction event titles in
+`bdi` so Arabic chrome and user-authored content remain readable together.
+
+## Copyable blocks and template
+
+- `scheduler-shell`
+- `calendar-sidebar`
+- `event-editor-drawer`
+- `agenda-panel`
+- `timezone-selector`
+- `template-calendar-application`
+
+```bash
+npx utopia-ds template template-calendar-application --copy ./calendar-application
+```
+
+The template presents a product-first calendar workspace with an embedded mini
+calendar, segmented view controls, themed timezone selection, event agenda, and
+editor drawer. All-day, overlapping, recurring, cross-timezone, and unavailable
+events remain available. Loading, empty, error, rollback, conflict, and
+read-only fixtures live in the collapsed `Test states` lab instead of the
+primary product toolbar.
+
+The template routes editor saves through the same
+`SchedulerMutationAdapter` used by move and resize operations. The `Fail next
+save` fixture therefore exercises both direct manipulation rollback and editor
+draft recovery rather than a disconnected demo state.
+
+## Performance boundary
+
+- Import Calendar from its tree-shakeable package entry, not the root package.
+- The Calendar package entry is capped at 45 KiB before gzip.
+- The runnable calendar application asset is capped at 120 KiB before gzip and
+  35 KiB after gzip.
+- Recurrence expansion is capped at 366 occurrences per source event.