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

package/data/templates/analytics-dashboard/AnalyticsMetricBlocks.tsx

@@ -0,0 +1,87 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import type { ChartState } from '@utopia-studio-design/design-system/Charts'
+import './analytics-dashboard.css'
+
+export interface MetricDefinition {
+  change?: number
+  changeLabel?: string
+  format?: 'number' | 'percent' | 'currency'
+  id: string
+  label: string
+  value: number
+}
+
+export interface KPIGridProps extends React.HTMLAttributes<HTMLDivElement> {
+  currency?: string
+  density?: 'compact' | 'default' | 'comfortable'
+  locale?: string
+  metrics: MetricDefinition[]
+  state?: ChartState
+}
+
+export function KPIGrid({
+  className,
+  currency = 'USD',
+  density = 'default',
+  locale,
+  metrics,
+  state = metrics.length === 0 ? 'empty' : 'ready',
+  ...props
+}: KPIGridProps) {
+  const formatMetric = (metric: MetricDefinition) => {
+    if (metric.format === 'percent') {
+      return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 }).format(metric.value)
+    }
+    if (metric.format === 'currency') {
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        notation: 'compact',
+        maximumFractionDigits: 1,
+      }).format(metric.value)
+    }
+    return new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: 1 }).format(metric.value)
+  }
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-label="Key performance indicators"
+      className={['ceramic-kpi-grid', className].filter(Boolean).join(' ')}
+      data-density={density}
+      data-state={state}
+      {...props}
+    >
+      {state === 'loading' ? (
+        <>
+          {[0, 1, 2].map((item) => <span aria-hidden="true" className="ceramic-kpi-skeleton" key={item} />)}
+          <span className="uds-visually-hidden" role="status">Loading metrics…</span>
+        </>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-kpi-state" role="status">
+          <strong>No metrics available</strong>
+          <span>Choose another period or data source.</span>
+        </div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-kpi-state" role="alert">
+          <strong>Metrics unavailable</strong>
+          <span>Reconnect the data source and try again.</span>
+        </div>
+      ) : null}
+      {state === 'ready' || state === 'partial' ? metrics.map((metric) => (
+        <article className="ceramic-kpi" key={metric.id}>
+          <span>{metric.label}</span>
+          <strong>{formatMetric(metric)}</strong>
+          {metric.change !== undefined ? (
+            <Badge variant="outline">
+              {metric.change > 0 ? '+' : ''}{metric.change.toFixed(1)}% {metric.changeLabel ?? 'vs previous'}
+            </Badge>
+          ) : <span className="ceramic-kpi-unavailable">No comparison</span>}
+        </article>
+      )) : null}
+    </section>
+  )
+}

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

@@ -0,0 +1,6 @@
+# Ceramic analytics dashboard
+
+Runnable integration template for the Ceramic Charts system. It demonstrates all
+chart families, governed data states, semantic series, keyboard exploration,
+RTL, light/dark modes, benchmark annotations, KPI blocks, and an accessible data
+table alternative.

package/data/templates/analytics-dashboard/analytics-dashboard.css

@@ -0,0 +1,92 @@
+.ceramic-kpi-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr));
+  gap: var(--interaction-density-default);
+  min-inline-size: 0;
+}
+
+.ceramic-kpi-grid[data-density='compact'] {
+  gap: var(--interaction-density-compact);
+}
+
+.ceramic-kpi-grid[data-density='comfortable'] {
+  gap: var(--interaction-density-comfortable);
+}
+
+.ceramic-kpi {
+  display: grid;
+  align-content: start;
+  gap: var(--space-2);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--surface);
+}
+
+.ceramic-kpi > span:first-child,
+.ceramic-kpi-unavailable {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+.ceramic-kpi > strong {
+  font-size: var(--font-size-marketing-h3);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-tight);
+}
+
+.ceramic-kpi .uds-badge {
+  inline-size: fit-content;
+}
+
+.ceramic-kpi-state {
+  display: grid;
+  grid-column: 1 / -1;
+  justify-items: center;
+  gap: var(--space-2);
+  min-block-size: 10rem;
+  padding: var(--space-6);
+  border: var(--border-width-hairline) dashed var(--border);
+  color: var(--muted-foreground);
+  text-align: center;
+}
+
+.ceramic-kpi-state strong {
+  color: var(--foreground);
+}
+
+.ceramic-kpi-skeleton {
+  min-block-size: 9rem;
+  background: var(--surface-strong);
+}
+
+.ceramic-analytics-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);
+}
+
+.ceramic-analytics-header > div {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.ceramic-analytics-header :is(h1, p) {
+  margin: 0;
+}
+
+.ceramic-analytics-header > div > span,
+.ceramic-analytics-header p {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+
+@media (max-width: 44rem) {
+  .ceramic-analytics-header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+}

package/data/templates/analytics-dashboard/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Ceramic Analytics Dashboard</title>
+  </head>
+  <body>
+    <a class="skip-link" href="#main-content">Skip to analytics dashboard</a>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/data/templates/analytics-dashboard/main.tsx

@@ -0,0 +1,196 @@
+import { StrictMode, useMemo, useState } from 'react'
+import { createRoot } from 'react-dom/client'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import type {
+  ChartDatum,
+  ChartSeriesDefinition,
+  ChartState,
+  ChartType,
+} from '@utopia-studio-design/design-system/Charts'
+import {
+  AnalyticsChartCard,
+  AnalyticsDashboardHeader,
+  ChartWithDataTable,
+  ComparisonChartPanel,
+  KPIGrid,
+} from './AnalyticsDashboardBlocks'
+import '@utopia-studio-design/design-system/core.css'
+import '@utopia-studio-design/design-system/themes/utopia-default.css'
+import './analytics-dashboard.css'
+import './styles.css'
+
+const baseData: ChartDatum[] = [
+  { id: 'jan', label: 'Jan', values: { revenue: 42, previous: 35, forecast: 44 } },
+  { id: 'feb', label: 'Feb', values: { revenue: 46, previous: 38, forecast: 47 } },
+  { id: 'mar', label: 'Mar', values: { revenue: 51, previous: 43, forecast: 52 } },
+  { id: 'apr', label: 'Apr', values: { revenue: 49, previous: 45, forecast: 55 } },
+  { id: 'may', label: 'May', values: { revenue: 58, previous: 48, forecast: 59 } },
+  { id: 'jun', label: 'Jun', values: { revenue: 63, previous: 52, forecast: 64 } },
+  { id: 'jul', label: 'Jul', values: { revenue: 68, previous: 57, forecast: 70 } },
+  { id: 'aug', label: 'Aug', values: { revenue: 74, previous: 61, forecast: 76 } },
+]
+
+const series: ChartSeriesDefinition[] = [
+  { id: 'revenue', label: 'Current revenue', tone: 'primary' },
+  { id: 'previous', label: 'Previous period', tone: 'benchmark', pattern: 'dash' },
+  { id: 'forecast', label: 'Forecast', tone: 'forecast', pattern: 'dot' },
+]
+
+const chartTypes: ChartType[] = ['line', 'bar', 'area', 'stacked', 'scatter', 'donut']
+const chartStates: ChartState[] = ['ready', 'partial', 'loading', 'empty', 'error']
+
+function App() {
+  const [dark, setDark] = useState(false)
+  const [direction, setDirection] = useState<'ltr' | 'rtl'>('ltr')
+  const [state, setState] = useState<ChartState>('ready')
+  const [type, setType] = useState<ChartType>('line')
+  const [refreshCount, setRefreshCount] = useState(0)
+  const data = useMemo(() => {
+    if (state !== 'partial') return baseData
+    return baseData.map((datum, index) => index === 3
+      ? { ...datum, values: { ...datum.values, previous: null } }
+      : datum)
+  }, [state])
+
+  return (
+    <main
+      className="analytics-template"
+      data-color-mode={dark ? 'dark' : 'light'}
+      data-theme="utopia-default"
+      dir="ltr"
+      id="main-content"
+    >
+      <AnalyticsDashboardHeader
+        onRefresh={() => setRefreshCount((value) => value + 1)}
+        periodLabel={`Jan–Aug 2026 · refreshed ${refreshCount} times`}
+        title="Growth performance"
+      />
+
+      <section aria-label="Analytics preview controls" className="analytics-controls">
+        <div>
+          <span>Chart family</span>
+          <div className="analytics-control-row">
+            {chartTypes.map((chartType) => (
+              <Button
+                aria-pressed={type === chartType}
+                key={chartType}
+                size="sm"
+                variant={type === chartType ? 'default' : 'outline'}
+                onClick={() => setType(chartType)}
+              >
+                {chartType}
+              </Button>
+            ))}
+          </div>
+        </div>
+        <div>
+          <span>Data state</span>
+          <div className="analytics-control-row">
+            {chartStates.map((chartState) => (
+              <Button
+                aria-pressed={state === chartState}
+                key={chartState}
+                size="sm"
+                variant={state === chartState ? 'default' : 'outline'}
+                onClick={() => setState(chartState)}
+              >
+                {chartState}
+              </Button>
+            ))}
+          </div>
+        </div>
+        <div className="analytics-mode-controls">
+          <Button
+            aria-pressed={direction === 'rtl'}
+            size="sm"
+            variant="outline"
+            onClick={() => setDirection((value) => value === 'ltr' ? 'rtl' : 'ltr')}
+          >
+            {direction === 'ltr' ? 'Switch charts to RTL' : 'Switch charts to LTR'}
+          </Button>
+          <Button
+            aria-pressed={dark}
+            size="sm"
+            variant="outline"
+            onClick={() => setDark((value) => !value)}
+          >
+            {dark ? 'Switch to light' : 'Switch to dark'}
+          </Button>
+        </div>
+      </section>
+
+      <section aria-labelledby="metrics-title" className="analytics-section">
+        <header>
+          <span>Overview</span>
+          <h2 id="metrics-title">Key metrics</h2>
+        </header>
+        <KPIGrid
+          metrics={[
+            { id: 'revenue', label: 'Revenue', value: 742000, format: 'currency', change: 12.4 },
+            { id: 'conversion', label: 'Conversion', value: 0.184, format: 'percent', change: 2.1 },
+            { id: 'accounts', label: 'Active accounts', value: 12840, change: 8.7 },
+            { id: 'retention', label: 'Retention', value: 0.916, format: 'percent' },
+          ]}
+          state={state === 'partial' ? 'ready' : state}
+        />
+      </section>
+
+      <section aria-labelledby="trend-title" className="analytics-section analytics-grid">
+        <header>
+          <span>Analysis</span>
+          <h2 id="trend-title">Revenue trend</h2>
+          <p>Keyboard exploration, semantic series, benchmark, forecast, and exact-value alternatives.</p>
+        </header>
+        <div className="analytics-primary-chart" dir={direction}>
+          <AnalyticsChartCard
+            data={state === 'empty' ? [] : data}
+            description="Monthly recurring revenue, USD thousands"
+            direction={direction}
+            series={series}
+            state={state}
+            title="Monthly revenue"
+            type={type}
+          />
+        </div>
+        <div dir={direction}>
+          <ComparisonChartPanel
+            benchmarkLabel="Annual target"
+            benchmarkValue={70}
+            data={state === 'empty' ? [] : data}
+            description="Current period against target"
+            direction={direction}
+            series={series.slice(0, 2)}
+            state={state}
+            title="Target comparison"
+            type="bar"
+          />
+        </div>
+      </section>
+
+      <section aria-labelledby="evidence-title" className="analytics-section">
+        <header>
+          <span>Accessible evidence</span>
+          <h2 id="evidence-title">Chart with data table</h2>
+          <p>The table remains the exact-value and screen-reader alternative to the visual plot.</p>
+        </header>
+        <div dir={direction}>
+          <ChartWithDataTable
+            data={state === 'empty' ? [] : data}
+            description="Exact values for audit and comparison"
+            direction={direction}
+            series={series}
+            state={state}
+            title="Revenue evidence"
+            type="line"
+          />
+        </div>
+      </section>
+    </main>
+  )
+}
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/data/templates/analytics-dashboard/styles.css

@@ -0,0 +1,120 @@
+* {
+  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;
+}
+
+.analytics-template {
+  min-block-size: 100vh;
+  padding-inline: var(--page-gutter);
+  background: var(--background);
+  color: var(--foreground);
+}
+
+.analytics-template > * {
+  max-inline-size: var(--container-standard);
+  margin-inline: auto;
+}
+
+.analytics-controls {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr)) auto;
+  align-items: end;
+  gap: var(--space-4);
+  padding-block: var(--space-4);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.analytics-controls > div {
+  display: grid;
+  gap: var(--space-2);
+  min-inline-size: 0;
+}
+
+.analytics-controls > div > span,
+.analytics-section > 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;
+}
+
+.analytics-control-row,
+.analytics-mode-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-1);
+}
+
+.analytics-section {
+  display: grid;
+  gap: var(--space-4);
+  padding-block: var(--space-6);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+
+.analytics-section > header {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.analytics-section > header :is(h2, p) {
+  margin: 0;
+}
+
+.analytics-section > header p {
+  color: var(--muted-foreground);
+}
+
+.analytics-grid {
+  grid-template-columns: minmax(0, 2fr) minmax(18rem, 1fr);
+}
+
+.analytics-grid > header {
+  grid-column: 1 / -1;
+}
+
+.analytics-grid > div {
+  min-inline-size: 0;
+}
+
+@media (max-width: 64rem) {
+  .analytics-controls,
+  .analytics-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .analytics-grid > header {
+    grid-column: auto;
+  }
+}
+
+@media (max-width: 44rem) {
+  .analytics-mode-controls {
+    flex-direction: column;
+  }
+}

package/data/templates/analytics-dashboard/template.manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "analytics-dashboard",
+  "title": "Analytics Dashboard",
+  "status": "available",
+  "route": "/templates/analytics-dashboard/",
+  "entry": "templates/analytics-dashboard/main.tsx",
+  "blocks": [
+    "analytics-chart-card",
+    "kpi-grid",
+    "comparison-chart-panel",
+    "chart-with-data-table"
+  ],
+  "states": ["loading", "empty", "error", "partial", "ready"],
+  "themes": ["utopia-default"],
+  "directions": ["ltr", "rtl"],
+  "responsiveMinimum": "320px"
+}