@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/ui/surfaces/PaginatedSurface.tsx

@@ -0,0 +1,164 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+} from "react"
+
+import { cn } from "../utils/cn"
+import { useThemeUiPresentation } from "../theme-presentation"
+
+export interface PaginatedGestureEvent {
+  gesture: "tap" | "dbl-tap" | "hold"
+  at: number
+}
+
+export interface PaginatedPage<T> {
+  render: (props: T) => ReactElement
+  config: T
+}
+
+export interface PaginatedSurfaceProps<T> {
+  pages: PaginatedPage<T> | PaginatedPage<T>[]
+  gesture?: PaginatedGestureEvent | null
+  intervalMs?: number
+  autoReturnMs?: number
+  className?: string
+  style?: CSSProperties
+}
+
+function normalizePages<T>(
+  pages: PaginatedPage<T> | PaginatedPage<T>[],
+): PaginatedPage<T>[] {
+  return Array.isArray(pages) ? pages : [pages]
+}
+
+const DOT_ACTIVE = "bg-white"
+const DOT_INACTIVE = "bg-white/30"
+
+export function PaginatedSurface<T>({
+  pages,
+  gesture,
+  intervalMs,
+  autoReturnMs,
+  className,
+  style,
+}: PaginatedSurfaceProps<T>): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.surfaces?.paginated) {
+    return themeUi.surfaces.paginated(
+      {
+        pages,
+        gesture,
+        intervalMs,
+        autoReturnMs,
+        className,
+        style,
+      } as PaginatedSurfaceProps<unknown>,
+      undefined,
+      paginatedSurfaceBase,
+    )
+  }
+
+  return paginatedSurfaceBase({
+    pages,
+    gesture,
+    intervalMs,
+    autoReturnMs,
+    className,
+    style,
+  } as PaginatedSurfaceProps<T>)
+}
+
+export function paginatedSurfaceBase<T>({
+  pages,
+  gesture,
+  intervalMs,
+  autoReturnMs,
+  className,
+  style,
+}: PaginatedSurfaceProps<T>): ReactElement {
+  const allPages = normalizePages(pages)
+  const count = allPages.length
+  const [current, setCurrent] = useState(0)
+  const lastGestureAt = useRef(0)
+  const timerRef = useRef<number | null>(null)
+  const autoReturnTimerRef = useRef<number | null>(null)
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearInterval(timerRef.current)
+      timerRef.current = null
+    }
+  }, [])
+
+  const clearAutoReturnTimer = useCallback(() => {
+    if (autoReturnTimerRef.current !== null) {
+      window.clearTimeout(autoReturnTimerRef.current)
+      autoReturnTimerRef.current = null
+    }
+  }, [])
+
+  const advance = useCallback(() => {
+    setCurrent((p) => (p + 1) % count)
+  }, [count])
+
+  // gesture-driven cycling
+  useEffect(() => {
+    if (gesture?.gesture === "tap" && gesture.at !== lastGestureAt.current) {
+      lastGestureAt.current = gesture.at
+      clearTimer()
+      advance()
+    }
+  }, [gesture, advance, clearTimer])
+
+  // auto-advance timer
+  useEffect(() => {
+    if (intervalMs === undefined || count <= 1) return
+    clearTimer()
+    timerRef.current = window.setInterval(advance, intervalMs)
+    return clearTimer
+  }, [intervalMs, count, advance, clearTimer])
+
+  // auto-return to page 0
+  useEffect(() => {
+    clearAutoReturnTimer()
+    if (autoReturnMs === undefined || current === 0) return
+    autoReturnTimerRef.current = window.setTimeout(() => {
+      setCurrent(0)
+    }, autoReturnMs)
+    return clearAutoReturnTimer
+  }, [current, autoReturnMs, clearAutoReturnTimer])
+
+  // reset current page when pages array changes length
+  useEffect(() => {
+    setCurrent((p) => (p >= count ? 0 : p))
+  }, [count])
+
+  const page = allPages[current]!
+
+  return (
+    <div
+      className={cn("relative flex h-full w-full flex-col", className)}
+      style={style}
+    >
+      <div className="min-h-0 flex-1">{page.render(page.config as T)}</div>
+      {count > 1 && (
+        <div className="absolute bottom-[-4px] left-0 right-0 flex items-center justify-center gap-1">
+          {allPages.map((_, i) => (
+            <div
+              key={i}
+              className={cn(
+                "h-1 w-1 rounded-full",
+                i === current ? DOT_ACTIVE : DOT_INACTIVE,
+              )}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/ui/surfaces/SplitActionSurface.tsx

@@ -0,0 +1,98 @@
+import { ReactNode, type ReactElement } from "react"
+
+import {
+  TapIndicator,
+  TapIndicatorType,
+  type TapIndicatorProps,
+} from "../primitives/TapIndicator"
+import { useThemeUiPresentation } from "../theme-presentation"
+import { cn } from "../utils/cn"
+
+type ActionProps = {
+  children: ReactNode
+  tapType: TapIndicatorType
+  className?: string
+  position: "bottom-right" | "top-left"
+}
+
+const Action = ({ tapType, children, className, position }: ActionProps) => {
+  return (
+    <div className={cn("w-full", className)}>
+      <div
+        className={cn(
+          "absolute z-10",
+          position === "bottom-right" ? "bottom-0 left-1" : "top-1 right-1",
+        )}
+      >
+        <TapIndicator type={tapType} size="xs" />
+      </div>
+      <div
+        className={cn([
+          "flex",
+          position === "bottom-right" ? "justify-end" : "justify-start",
+        ])}
+      >
+        <div
+          className={cn([
+            "scale-[0.62]",
+            position === "bottom-right"
+              ? "origin-bottom-right"
+              : "origin-top-left",
+          ])}
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export interface SplitActionSurfaceProps {
+  primary: ReactElement
+  secondary?: ReactElement
+  secondaryIndicatorType?: NonNullable<TapIndicatorProps["type"]>
+}
+
+export function SplitActionSurface(
+  props: SplitActionSurfaceProps,
+): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.surfaces?.splitAction) {
+    return themeUi.surfaces.splitAction(
+      props,
+      undefined,
+      splitActionSurfaceBase,
+    )
+  }
+
+  return splitActionSurfaceBase(props)
+}
+
+export function splitActionSurfaceBase(
+  props: SplitActionSurfaceProps,
+): ReactElement {
+  if (!props.secondary) {
+    return <div className="contents">{props.primary}</div>
+  }
+
+  return (
+    <div className="relative size-full flex flex-col">
+      <hr className="absolute w-10 border-none h-px background-accent top-1/2 left-1/2 bg-accent -ml-5 -rotate-45" />
+      <Action
+        className="absolute top-0 left-0 z-10"
+        tapType="tap"
+        position="top-left"
+      >
+        {props.primary}
+      </Action>
+      <Action
+        className="absolute bottom-0 right-0 z-10"
+        tapType={props.secondaryIndicatorType ?? "dbltap"}
+        position="bottom-right"
+      >
+        {props.secondary}
+      </Action>
+    </div>
+  )
+}

package/src/ui/surfaces/TemporaryErrorSurface.tsx

@@ -0,0 +1,68 @@
+import { type HTMLAttributes, type ReactElement } from "react"
+
+import { Icon } from "../primitives/Icon"
+import { Label } from "../primitives/Label"
+import { useThemeUiPresentation } from "../theme-presentation"
+
+export interface TemporaryErrorSurfaceProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "children"
+> {
+  source?: string
+  label?: string
+  details: string
+}
+
+const FALLBACK_LABEL = "Error"
+const FALLBACK_DETAILS = "check logs"
+
+export function TemporaryErrorSurface(
+  props: TemporaryErrorSurfaceProps,
+): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.surfaces?.temporaryError) {
+    return themeUi.surfaces.temporaryError(
+      props,
+      undefined,
+      temporaryErrorSurfaceBase,
+    )
+  }
+
+  return temporaryErrorSurfaceBase(props)
+}
+
+export function temporaryErrorSurfaceBase(
+  props: TemporaryErrorSurfaceProps,
+): ReactElement {
+  const {
+    className: consumerClassName,
+    source,
+    label: labelProp,
+    details: detailsProp,
+    ...rest
+  } = props
+  const layoutClassName =
+    "flex h-full w-full flex-col items-center justify-center gap-1"
+  const mergedClassName = consumerClassName
+    ? `${layoutClassName} ${consumerClassName}`
+    : layoutClassName
+
+  const label = labelProp ?? FALLBACK_LABEL
+  const details =
+    (detailsProp ?? "").length > 0 ? detailsProp : FALLBACK_DETAILS
+
+  return (
+    <div
+      className={mergedClassName}
+      data-sireno-surface="temporary-error"
+      {...rest}
+    >
+      <div className="flex items-center justify-center gap-1">
+        <Icon source={source} size={16} tone="danger" />
+        <Label text={label} variant="secondary" />
+      </div>
+      <Label text={details} variant="small" lines={3} />
+    </div>
+  )
+}

package/src/ui/surfaces/ValueChart.tsx

@@ -0,0 +1,218 @@
+import { type CSSProperties, type ReactElement } from "react"
+
+import { Icon } from "../primitives/Icon"
+import { useThemeUiPresentation } from "../theme-presentation"
+import { cn } from "../utils/cn"
+
+export interface ValueChartPoint {
+  at: number
+  value: number
+}
+
+export interface ValueChartSeries {
+  id: string
+  color: string
+  icon: string
+  label?: string
+  unit?: string
+  points: ReadonlyArray<ValueChartPoint>
+  yMax: number
+}
+
+type ValueChartSeriesTuple =
+  | readonly [ValueChartSeries]
+  | readonly [ValueChartSeries, ValueChartSeries]
+
+export interface ValueChartProps {
+  series: ValueChartSeriesTuple
+  windowSeconds: number
+  resolution?: number
+  className?: string
+  style?: CSSProperties
+}
+
+const CHART_VIEWBOX_SIZE = 100
+
+function clipPoints(
+  points: ReadonlyArray<ValueChartPoint>,
+  windowSeconds: number,
+): ValueChartPoint[] {
+  const cutoff = Date.now() - windowSeconds * 1000
+  return points.filter((p) => p.at >= cutoff)
+}
+
+function downsample(
+  points: ReadonlyArray<ValueChartPoint>,
+  maxPoints: number,
+): ValueChartPoint[] {
+  if (points.length <= maxPoints) return [...points]
+  const bucketSize = Math.ceil(points.length / maxPoints)
+  const result: ValueChartPoint[] = []
+  for (let i = 0; i < points.length; i += bucketSize) {
+    const bucket = points.slice(i, i + bucketSize)
+    const maxP = bucket.reduce((a, b) => (a.value > b.value ? a : b))
+    result.push(maxP)
+  }
+  const last = points[points.length - 1]
+  if (last && result[result.length - 1] !== last) result.push(last)
+  return result
+}
+
+function buildAreaPath(
+  points: ReadonlyArray<ValueChartPoint>,
+  yMax: number,
+): string {
+  if (points.length === 0) return ""
+
+  const minX = points[0]!.at
+  const maxX = points[points.length - 1]!.at
+  const rangeX = Math.max(maxX - minX, 1)
+  const size = CHART_VIEWBOX_SIZE
+  const normalY = (v: number) => ((1 - v / Math.max(yMax, 1)) * size).toFixed(1)
+
+  const parts: string[] = []
+  for (let i = 0; i < points.length; i++) {
+    const x = (((points[i]!.at - minX) / rangeX) * size).toFixed(1)
+    const y = normalY(points[i]!.value)
+    parts.push(`${i === 0 ? "M" : "L"}${x},${y}`)
+  }
+
+  const lastX = (
+    ((points[points.length - 1]!.at - minX) / rangeX) *
+    size
+  ).toFixed(1)
+  parts.push(`L${lastX},${size} L0,${size} Z`)
+  return parts.join(" ")
+}
+
+function LegendSwatch({
+  color,
+  variant,
+}: {
+  color: string
+  variant: "solid" | "dashed"
+}): ReactElement {
+  return (
+    <svg
+      width={14}
+      height={4}
+      viewBox="0 0 14 4"
+      preserveAspectRatio="none"
+      aria-hidden
+      data-variant={variant}
+    >
+      <line
+        x1="0"
+        y1="2"
+        x2="14"
+        y2="2"
+        stroke={color}
+        strokeWidth={2}
+        strokeLinecap="round"
+        {...(variant === "dashed" ? { strokeDasharray: "3 2" } : {})}
+      />
+    </svg>
+  )
+}
+
+export function ValueChart(props: ValueChartProps): ReactElement {
+  if (props.series.length < 1 || props.series.length > 2) {
+    throw new Error(
+      `ValueChart supports 1-2 series. Received ${props.series.length}.`,
+    )
+  }
+
+  const themeUi = useThemeUiPresentation()
+  if (themeUi?.surfaces?.valueChart) {
+    return themeUi.surfaces.valueChart(props, undefined, valueChartBase)
+  }
+
+  return valueChartBase(props)
+}
+
+export function valueChartBase(props: ValueChartProps): ReactElement {
+  if (props.series.length < 1 || props.series.length > 2) {
+    throw new Error(
+      `ValueChart supports 1-2 series. Received ${props.series.length}.`,
+    )
+  }
+
+  const clipped = props.series.map((s) => ({
+    ...s,
+    clipped: clipPoints(s.points, props.windowSeconds),
+  }))
+
+  const resolution = props.resolution ?? 120
+  const variantFor = (index: number): "solid" | "dashed" =>
+    index === 0 ? "solid" : "dashed"
+
+  return (
+    <div
+      className={cn(
+        "flex h-full min-h-6 min-w-0 w-full flex-col",
+        props.className,
+      )}
+      data-sireno-ui-valuechart="true"
+      style={props.style}
+    >
+      <div className="flex shrink-0 items-center justify-center gap-2">
+        {clipped.map((s, index) => {
+          const variant = variantFor(index)
+          return (
+            <div
+              className="flex items-center gap-1 whitespace-nowrap"
+              key={s.id}
+              data-series-id={s.id}
+              data-variant={variant}
+            >
+              <Icon source={s.icon} size={10} />
+              <LegendSwatch color={s.color} variant={variant} />
+            </div>
+          )
+        })}
+      </div>
+
+      <div className="relative flex-1 min-w-0">
+        <svg
+          className="h-full w-full"
+          preserveAspectRatio="none"
+          viewBox={`0 0 ${CHART_VIEWBOX_SIZE} ${CHART_VIEWBOX_SIZE}`}
+          data-sireno-chart-svg="true"
+        >
+          {clipped.map((s, index) => {
+            const variant = variantFor(index)
+            const downsampled = downsample(s.clipped, resolution)
+            if (downsampled.length === 0) {
+              return (
+                <line
+                  key={s.id}
+                  x1="0"
+                  y1={CHART_VIEWBOX_SIZE}
+                  x2={CHART_VIEWBOX_SIZE}
+                  y2={CHART_VIEWBOX_SIZE}
+                  stroke={s.color}
+                  strokeWidth={1.5}
+                  opacity={0.3}
+                  {...(variant === "dashed" ? { strokeDasharray: "4 3" } : {})}
+                />
+              )
+            }
+            return (
+              <path
+                key={s.id}
+                d={buildAreaPath(downsampled, s.yMax)}
+                fill={s.color}
+                fillOpacity={0.5}
+                stroke={s.color}
+                strokeWidth={1.5}
+                strokeLinejoin="round"
+                strokeLinecap="round"
+                {...(variant === "dashed" ? { strokeDasharray: "4 3" } : {})}
+              />
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}

package/src/ui/surfaces/index.ts

@@ -0,0 +1,32 @@
+export * from "./BarsSurface"
+export * from "./IconLabelProgressSurface"
+export * from "./IconLabelSurface"
+export * from "./LabelValueListSurface"
+export * from "./TemporaryErrorSurface"
+export * from "./ValueChart"
+
+export { BarsSurface } from "./BarsSurface"
+export type { BarsItem, BarsSurfaceProps as BarsProps } from "./BarsSurface"
+export { IconLabelProgressSurface } from "./IconLabelProgressSurface"
+export type { IconLabelProgressSurfaceProps } from "./IconLabelProgressSurface"
+export { IconLabelSurface } from "./IconLabelSurface"
+export type { IconLabelSurfaceProps } from "./IconLabelSurface"
+
+export { PaginatedSurface } from "./PaginatedSurface"
+export type {
+  PaginatedGestureEvent,
+  PaginatedPage,
+  PaginatedSurfaceProps,
+} from "./PaginatedSurface"
+export { pagesSchema } from "./paginated-schema"
+
+export { SplitActionSurface } from "./SplitActionSurface"
+export type { SplitActionSurfaceProps } from "./SplitActionSurface"
+export { TemporaryErrorSurface } from "./TemporaryErrorSurface"
+export type { TemporaryErrorSurfaceProps } from "./TemporaryErrorSurface"
+export { ValueChart } from "./ValueChart"
+export type {
+  ValueChartPoint,
+  ValueChartProps,
+  ValueChartSeries,
+} from "./ValueChart"

package/src/ui/surfaces/paginated-schema.ts

@@ -0,0 +1,22 @@
+import { z } from "zod"
+
+/**
+ * Wraps a page schema to accept either a single page object or an array.
+ * Normalizes to `{ pages: [...] }`.
+ *
+ * @example
+ * const Config = pagesSchema(z.discriminatedUnion("type", [BarPage, ChartPage]))
+ * // single:  { type: "bars", metrics: ["cpu"] }  → { pages: [{ type: "bars", metrics: [...] }] }
+ * // array:   [{ type: "bars", ... }, { type: "chart", ... }] → { pages: [...] }
+ */
+export function pagesSchema<T extends z.ZodTypeAny>(page: T) {
+  return z.preprocess(
+    (input) => {
+      if (Array.isArray(input)) return { pages: input }
+      if (input && typeof input === "object" && !("pages" in input))
+        return { pages: [input] }
+      return input
+    },
+    z.object({ pages: z.array(page).min(1).max(5) }).strict(),
+  )
+}