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

package/data/blocks/calendar-application/CalendarApplicationBlocks.tsx

@@ -0,0 +1,519 @@
+import * as React from 'react'
+import { X } from '@phosphor-icons/react'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import { Calendar } from '@utopia-studio-design/design-system/DataDisplay'
+import {
+  Checkbox,
+  Field,
+  FieldError,
+  FieldLabel,
+  NativeSelect,
+  NativeSelectOption,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  TextInput,
+} from '@utopia-studio-design/design-system/Forms'
+import { PhosphorIcon } from '@utopia-studio-design/design-system/PhosphorIcon'
+import {
+  AgendaView,
+  SchedulerRoot,
+  addSchedulerDays,
+  expandRecurringEvents,
+  startOfSchedulerWeek,
+  type SchedulerEvent,
+  type SchedulerEventEditHandler,
+  type SchedulerLabelOverrides,
+  type SchedulerResource,
+  type SchedulerRootProps,
+  type SchedulerWeekDay,
+} from '@utopia-studio-design/design-system/Calendar'
+import './calendar-application.css'
+
+export type SchedulerShellProps = SchedulerRootProps
+
+export function SchedulerShell(props: SchedulerShellProps) {
+  return <SchedulerRoot {...props} />
+}
+
+export interface CalendarSidebarProps extends React.HTMLAttributes<HTMLElement> {
+  date: Date
+  labels?: {
+    ariaLabel?: string
+    jumpToDate?: string
+    schedule?: string
+    calendars?: string
+  }
+  locale?: string
+  onDateChange?: (date: Date) => void
+  resources?: SchedulerResource[]
+  selectedResourceIds?: string[]
+  onResourceToggle?: (resourceId: string) => void
+  weekStartsOn?: SchedulerWeekDay
+}
+
+export function CalendarSidebar({
+  date,
+  labels = {},
+  locale = 'en-US',
+  onDateChange,
+  onResourceToggle,
+  resources = [],
+  selectedResourceIds = resources.map((resource) => resource.id),
+  weekStartsOn = 1,
+  ...props
+}: CalendarSidebarProps) {
+  return (
+    <aside aria-label={labels.ariaLabel ?? 'Calendar sidebar'} className="ceramic-calendar-sidebar" {...props}>
+      <div className="ceramic-calendar-sidebar-heading">
+        <span>{labels.schedule ?? 'Schedule'}</span>
+        <strong>{new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(date)}</strong>
+      </div>
+      <Calendar
+        aria-label={labels.jumpToDate ?? 'Jump to date'}
+        captionLayout="label"
+        className="ceramic-calendar-mini"
+        locale={locale}
+        month={date}
+        selectedDate={date}
+        weekStartsOn={weekStartsOn}
+        onMonthChange={onDateChange}
+        onSelect={onDateChange}
+      />
+      <fieldset>
+        <legend>{labels.calendars ?? 'My calendars'}</legend>
+        {resources.map((resource) => (
+          <label key={resource.id}>
+            <Checkbox
+              aria-label={resource.label}
+              checked={selectedResourceIds.includes(resource.id)}
+              onCheckedChange={() => onResourceToggle?.(resource.id)}
+            />
+            <span>
+              <i aria-hidden="true" data-resource={resource.id} />
+              {resource.label}
+            </span>
+          </label>
+        ))}
+      </fieldset>
+    </aside>
+  )
+}
+
+export interface TimezoneSelectorProps {
+  className?: string
+  label?: string
+  onValueChange?: (value: string) => void
+  timezones: string[]
+  value: string
+}
+
+export function TimezoneSelector({
+  className,
+  label = 'Display timezone',
+  onValueChange,
+  timezones,
+  value,
+}: TimezoneSelectorProps) {
+  const labelId = React.useId()
+  return (
+    <Field className={`ceramic-timezone-selector ${className ?? ''}`.trim()}>
+      <FieldLabel id={labelId}>{label}</FieldLabel>
+      <Select value={value} onValueChange={onValueChange}>
+        <SelectTrigger aria-labelledby={labelId}>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {timezones.map((timezone) => <SelectItem key={timezone} value={timezone}>{timezone}</SelectItem>)}
+        </SelectContent>
+      </Select>
+    </Field>
+  )
+}
+
+export interface AgendaPanelProps extends React.HTMLAttributes<HTMLElement> {
+  calendarSystem?: string
+  date: Date
+  events: SchedulerEvent[]
+  labels?: SchedulerLabelOverrides
+  locale?: string
+  numberingSystem?: string
+  onEventEdit?: SchedulerEventEditHandler
+  timezone: string
+  weekendDays?: SchedulerWeekDay[]
+  weekStartsOn?: SchedulerWeekDay
+}
+
+export function AgendaPanel({
+  calendarSystem,
+  date,
+  events,
+  labels,
+  locale,
+  numberingSystem,
+  onEventEdit,
+  timezone,
+  weekendDays,
+  weekStartsOn,
+  ...props
+}: AgendaPanelProps) {
+  const rangeStart = startOfSchedulerWeek(date, weekStartsOn)
+  const expandedEvents = expandRecurringEvents(events, rangeStart, addSchedulerDays(rangeStart, 7))
+  return (
+    <aside className="ceramic-agenda-panel" {...props}>
+      <AgendaView
+        calendarSystem={calendarSystem}
+        date={date}
+        events={expandedEvents}
+        labels={labels}
+        locale={locale}
+        numberingSystem={numberingSystem}
+        timezone={timezone}
+        weekendDays={weekendDays}
+        weekStartsOn={weekStartsOn}
+        visible
+        onEventEdit={onEventEdit}
+      />
+    </aside>
+  )
+}
+
+export interface EventEditorDrawerProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onSave'> {
+  canDelete?: boolean
+  event: SchedulerEvent | null
+  labels?: Partial<EventEditorLabels>
+  onClose?: () => void
+  onDelete?: (event: SchedulerEvent) => void
+  onSave?: (event: SchedulerEvent, scope: 'occurrence' | 'series') => void | Promise<void>
+  open: boolean
+  returnFocusRef?: React.RefObject<HTMLElement | null>
+}
+
+export interface EventEditorLabels {
+  ariaLabel: string
+  eyebrow: string
+  newEvent: string
+  close: string
+  title: string
+  starts: string
+  ends: string
+  allDay: string
+  applyTo: string
+  occurrence: string
+  series: string
+  save: string
+  saving: string
+  cancel: string
+  delete: string
+  validationSummary: string
+  titleRequired: string
+  startRequired: string
+  endRequired: string
+  invalidDateTime: string
+  endAfterStart: string
+  saveError: string
+}
+
+const defaultEditorLabels: EventEditorLabels = {
+  ariaLabel: 'Event editor',
+  eyebrow: 'Calendar event',
+  newEvent: 'New event',
+  close: 'Close event editor',
+  title: 'Title',
+  starts: 'Starts',
+  ends: 'Ends',
+  allDay: 'All-day event',
+  applyTo: 'Apply change to',
+  occurrence: 'This occurrence',
+  series: 'Entire series',
+  save: 'Save event',
+  saving: 'Saving event…',
+  cancel: 'Cancel',
+  delete: 'Delete event',
+  validationSummary: 'Check the highlighted fields.',
+  titleRequired: 'Enter an event title.',
+  startRequired: 'Enter a start date and time.',
+  endRequired: 'Enter an end date and time.',
+  invalidDateTime: 'Enter a valid date and time.',
+  endAfterStart: 'End must be after start.',
+  saveError: "The event couldn't be saved. Your changes are still here.",
+}
+
+function toLocalInput(value: string) {
+  const date = new Date(value)
+  if (Number.isNaN(date.valueOf())) return ''
+  const offset = date.getTimezoneOffset() * 60_000
+  return new Date(date.valueOf() - offset).toISOString().slice(0, 16)
+}
+
+function parseLocalInput(value: string) {
+  if (!value) return null
+  const date = new Date(value)
+  return Number.isNaN(date.valueOf()) ? null : date
+}
+
+type EventEditorErrors = Partial<Record<'title' | 'start' | 'end', string>>
+
+export function EventEditorDrawer({
+  canDelete = true,
+  event,
+  labels: labelOverrides,
+  onClose,
+  onDelete,
+  onSave,
+  open,
+  returnFocusRef,
+  ...props
+}: EventEditorDrawerProps) {
+  const labels = { ...defaultEditorLabels, ...labelOverrides }
+  const drawerRef = React.useRef<HTMLElement>(null)
+  const closeRef = React.useRef<HTMLButtonElement>(null)
+  const titleRef = React.useRef<HTMLInputElement>(null)
+  const startRef = React.useRef<HTMLInputElement>(null)
+  const endRef = React.useRef<HTMLInputElement>(null)
+  const saveErrorRef = React.useRef<HTMLDivElement>(null)
+  const triggerRef = React.useRef<HTMLElement | null>(null)
+  const openRef = React.useRef(open)
+  openRef.current = open
+  const titleId = React.useId()
+  const startId = React.useId()
+  const endId = React.useId()
+  const scopeId = React.useId()
+  const [draft, setDraft] = React.useState(event)
+  const [titleInput, setTitleInput] = React.useState(event?.title ?? '')
+  const [startInput, setStartInput] = React.useState(event ? toLocalInput(event.start) : '')
+  const [endInput, setEndInput] = React.useState(event ? toLocalInput(event.end) : '')
+  const [scope, setScope] = React.useState<'occurrence' | 'series'>('occurrence')
+  const [errors, setErrors] = React.useState<EventEditorErrors>({})
+  const [saveError, setSaveError] = React.useState(false)
+  const [isSaving, setIsSaving] = React.useState(false)
+  React.useEffect(() => {
+    setDraft(event)
+    setTitleInput(event?.title ?? '')
+    setStartInput(event ? toLocalInput(event.start) : '')
+    setEndInput(event ? toLocalInput(event.end) : '')
+    setScope('occurrence')
+    setErrors({})
+    setSaveError(false)
+    setIsSaving(false)
+  }, [event])
+  React.useLayoutEffect(() => {
+    if (!open) return
+    const activeElement = returnFocusRef?.current
+      ?? (document.activeElement instanceof HTMLElement ? document.activeElement : null)
+    if (activeElement && !drawerRef.current?.contains(activeElement)) triggerRef.current = activeElement
+    const scrollX = window.scrollX
+    const scrollY = window.scrollY
+    const bodyStyles = {
+      inlineSize: document.body.style.inlineSize,
+      inset: document.body.style.inset,
+      overflow: document.body.style.overflow,
+      position: document.body.style.position,
+    }
+    document.body.style.position = 'fixed'
+    document.body.style.inset = '0'
+    document.body.style.inlineSize = '100%'
+    document.body.style.overflow = 'hidden'
+    return () => {
+      document.body.style.position = bodyStyles.position
+      document.body.style.inset = bodyStyles.inset
+      document.body.style.inlineSize = bodyStyles.inlineSize
+      document.body.style.overflow = bodyStyles.overflow
+      window.scrollTo(scrollX, scrollY)
+      const trigger = triggerRef.current
+      window.requestAnimationFrame(() => {
+        if (!openRef.current && trigger?.isConnected && !document.querySelector('.ceramic-event-editor[role="dialog"]')) {
+          trigger.focus()
+          if (triggerRef.current === trigger) triggerRef.current = null
+        }
+      })
+    }
+  }, [open, returnFocusRef])
+  React.useLayoutEffect(() => {
+    if (open && draft) closeRef.current?.focus()
+  }, [draft?.id, open])
+  React.useLayoutEffect(() => {
+    if (saveError) saveErrorRef.current?.focus()
+  }, [saveError])
+  if (!open || !draft) return null
+  const focusableSelector = 'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+  const closeEditor = () => {
+    if (!isSaving) onClose?.()
+  }
+  const clearError = (field: keyof EventEditorErrors) => {
+    setErrors((current) => {
+      if (!current[field]) return current
+      const next = { ...current }
+      delete next[field]
+      return next
+    })
+    setSaveError(false)
+  }
+  const handleSubmit = async (submitEvent: React.FormEvent<HTMLFormElement>) => {
+    submitEvent.preventDefault()
+    if (isSaving) return
+
+    const nextErrors: EventEditorErrors = {}
+    const title = titleInput.trim()
+    const start = parseLocalInput(startInput)
+    const end = parseLocalInput(endInput)
+    if (!title) nextErrors.title = labels.titleRequired
+    if (!startInput) nextErrors.start = labels.startRequired
+    else if (!start) nextErrors.start = labels.invalidDateTime
+    if (!endInput) nextErrors.end = labels.endRequired
+    else if (!end) nextErrors.end = labels.invalidDateTime
+    else if (start && end <= start) nextErrors.end = labels.endAfterStart
+
+    setErrors(nextErrors)
+    setSaveError(false)
+    if (Object.keys(nextErrors).length > 0) {
+      window.requestAnimationFrame(() => {
+        if (nextErrors.title) titleRef.current?.focus()
+        else if (nextErrors.start) startRef.current?.focus()
+        else endRef.current?.focus()
+      })
+      return
+    }
+
+    const nextDraft = {
+      ...draft,
+      title,
+      start: start!.toISOString(),
+      end: end!.toISOString(),
+    }
+    setDraft(nextDraft)
+    setIsSaving(true)
+    try {
+      await onSave?.(nextDraft, scope)
+    } catch {
+      setSaveError(true)
+    } finally {
+      setIsSaving(false)
+    }
+  }
+  return (
+    <>
+      <div aria-hidden="true" className="ceramic-event-editor-backdrop" onClick={closeEditor} />
+      <aside
+        aria-label={labels.ariaLabel}
+        aria-modal="true"
+        aria-busy={isSaving || undefined}
+        className="ceramic-event-editor"
+        ref={drawerRef}
+        role="dialog"
+        onKeyDown={(keyboardEvent) => {
+          if (keyboardEvent.key === 'Escape') {
+            keyboardEvent.preventDefault()
+            closeEditor()
+          }
+          if (keyboardEvent.key !== 'Tab') return
+          const focusable = [...(drawerRef.current?.querySelectorAll<HTMLElement>(focusableSelector) ?? [])]
+          const first = focusable[0]
+          const last = focusable.at(-1)
+          if (keyboardEvent.shiftKey && document.activeElement === first) {
+            keyboardEvent.preventDefault()
+            last?.focus()
+          } else if (!keyboardEvent.shiftKey && document.activeElement === last) {
+            keyboardEvent.preventDefault()
+            first?.focus()
+          }
+        }}
+        {...props}
+      >
+        <header>
+          <div><span>{labels.eyebrow}</span><h2><bdi>{draft.title || labels.newEvent}</bdi></h2></div>
+          <Button ref={closeRef} aria-label={labels.close} disabled={isSaving} isIconOnly variant="ghost" onClick={closeEditor}>
+            <PhosphorIcon decorative icon={X} size="sm" />
+          </Button>
+        </header>
+        <form aria-busy={isSaving || undefined} noValidate onSubmit={handleSubmit}>
+          {Object.keys(errors).length > 0 ? (
+            <div className="ceramic-event-editor-alert" role="alert">{labels.validationSummary}</div>
+          ) : null}
+          {saveError ? (
+            <div className="ceramic-event-editor-alert" ref={saveErrorRef} role="alert" tabIndex={-1}>
+              {labels.saveError}
+            </div>
+          ) : null}
+          <Field>
+            <FieldLabel htmlFor={titleId}>{labels.title}</FieldLabel>
+            <TextInput
+              aria-describedby={errors.title ? `${titleId}-error` : undefined}
+              aria-invalid={Boolean(errors.title)}
+              disabled={isSaving}
+              id={titleId}
+              ref={titleRef}
+              required
+              value={titleInput}
+              onChange={(changeEvent) => {
+                setTitleInput(changeEvent.target.value)
+                clearError('title')
+              }}
+            />
+            <FieldError id={`${titleId}-error`}>{errors.title}</FieldError>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor={startId}>{labels.starts}</FieldLabel>
+            <TextInput
+              aria-describedby={errors.start ? `${startId}-error` : undefined}
+              aria-invalid={Boolean(errors.start)}
+              disabled={isSaving}
+              id={startId}
+              ref={startRef}
+              required
+              type="datetime-local"
+              value={startInput}
+              onChange={(changeEvent) => {
+                setStartInput(changeEvent.target.value)
+                clearError('start')
+              }}
+            />
+            <FieldError id={`${startId}-error`}>{errors.start}</FieldError>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor={endId}>{labels.ends}</FieldLabel>
+            <TextInput
+              aria-describedby={errors.end ? `${endId}-error` : undefined}
+              aria-invalid={Boolean(errors.end)}
+              disabled={isSaving}
+              id={endId}
+              ref={endRef}
+              required
+              type="datetime-local"
+              value={endInput}
+              onChange={(changeEvent) => {
+                setEndInput(changeEvent.target.value)
+                clearError('end')
+              }}
+            />
+            <FieldError id={`${endId}-error`}>{errors.end}</FieldError>
+          </Field>
+          <label className="ceramic-event-checkbox">
+            <Checkbox disabled={isSaving} checked={Boolean(draft.allDay)} onCheckedChange={(checked) => setDraft({ ...draft, allDay: checked === true })} />
+            <span>{labels.allDay}</span>
+          </label>
+          {draft.recurrenceId || draft.recurrence ? (
+            <Field>
+              <FieldLabel htmlFor={scopeId}>{labels.applyTo}</FieldLabel>
+              <NativeSelect disabled={isSaving} id={scopeId} value={scope} onChange={(changeEvent) => setScope(changeEvent.target.value as 'occurrence' | 'series')}>
+                <NativeSelectOption value="occurrence">{labels.occurrence}</NativeSelectOption>
+                <NativeSelectOption value="series">{labels.series}</NativeSelectOption>
+              </NativeSelect>
+            </Field>
+          ) : null}
+          <div className="ceramic-event-editor-actions">
+            <div>
+              <Button loading={isSaving} loadingText={labels.saving} type="submit">{labels.save}</Button>
+              <Button disabled={isSaving} type="button" variant="outline" onClick={closeEditor}>{labels.cancel}</Button>
+            </div>
+            {canDelete ? (
+              <Button disabled={isSaving} type="button" variant="destructive" onClick={() => onDelete?.(draft)}>{labels.delete}</Button>
+            ) : null}
+          </div>
+        </form>
+      </aside>
+    </>
+  )
+}

package/data/blocks/calendar-application/README.md

@@ -0,0 +1,20 @@
+# Calendar application blocks
+
+Copyable Ceramic blocks for application scheduling: `SchedulerShell`,
+`CalendarSidebar`, `EventEditorDrawer`, `AgendaPanel`, and
+`TimezoneSelector`. Product code owns persistence through controlled events and
+the scheduler mutation adapter.
+
+`EventEditorDrawer` keeps incomplete date/time text in a local draft, validates
+required values and chronological order, and accepts synchronous or asynchronous
+`onSave` handlers. Rejected saves preserve the draft for retry. Pass
+`canDelete={false}` for unsaved events and connect `returnFocusRef` to the
+invoking event or create control so pointer-triggered drawers restore focus in
+Safari as well as Chromium.
+
+`calendar-panel-contract.ts` is the registry-to-runtime boundary used by both
+the Dashboard Composer and Puck adapter. It maps only registered semantic
+configuration—view, timezone, locale, direction mode, week start, secondary
+calendar, initial scroll hour, and agenda alternative—to `SchedulerRoot`.
+Events, permissions, persistence adapters, and localized product data remain
+runtime-owned.