@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/ui/ButtonFrame.tsx

@@ -0,0 +1,230 @@
+import type {
+  CSSProperties,
+  MouseEvent,
+  PointerEvent,
+  ReactElement,
+  ReactNode,
+} from "react"
+
+import { useThemeUiPresentation } from "./theme-presentation"
+
+export interface ButtonFrameProps {
+  pressed?: boolean
+  isTapping?: boolean
+  isHolding?: boolean
+  holdProgress?: number
+  buttonType: string
+  variant?: string
+  onClick?: (event: MouseEvent<HTMLDivElement>) => void
+  onPointerDown?: (event: PointerEvent<HTMLDivElement>) => void
+  onPointerUp?: (event: PointerEvent<HTMLDivElement>) => void
+  onPointerMove?: (event: PointerEvent<HTMLDivElement>) => void
+  onPointerLeave?: (event: PointerEvent<HTMLDivElement>) => void
+  onPointerCancel?: (event: PointerEvent<HTMLDivElement>) => void
+  children: ReactNode
+}
+
+const warnedVariants = new Set<string>()
+
+const isVariantDeclared = (variant: string): boolean => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return true
+  }
+  try {
+    const resolved = window
+      .getComputedStyle(document.documentElement)
+      .getPropertyValue(`--sireno-variant-${variant}-bg`)
+    return resolved.trim().length > 0
+  } catch {
+    return true
+  }
+}
+
+const warnUnknownVariant = (variant: string): void => {
+  if (variant === "default") return
+  if (isVariantDeclared(variant)) return
+  if (warnedVariants.has(variant)) return
+  warnedVariants.add(variant)
+  console.warn(
+    `[sirenodeck] ButtonFrame: unknown variant "${variant}", falling back to "default". Add this variant to your theme's manifest.`,
+  )
+}
+
+const variantVar = (
+  variant: string,
+  slot: "bg" | "border" | "fg" | "glow",
+): string =>
+  `var(--sireno-variant-${variant}-${slot}, var(--sireno-variant-default-${slot}))`
+
+const VARIANT_COLOR_TOKENS = [
+  "primary",
+  "accent",
+  "foreground",
+  "foreground-contrast",
+  "success",
+  "danger",
+  "muted",
+] as const
+
+function variantColorVar(
+  variant: string,
+  token: (typeof VARIANT_COLOR_TOKENS)[number],
+): string {
+  const cssToken =
+    token === "foreground"
+      ? "fg"
+      : token === "foreground-contrast"
+        ? "foreground-contrast"
+        : token
+  return `var(--sireno-variant-${variant}-${cssToken}, var(--sireno-color-${cssToken}))`
+}
+
+/**
+ * Ponytail: every cascade token emits under both `--sireno-color-*` (for
+ * primitives that read the variable directly via `getPropertyValue` or
+ * in style attrs) AND `--color-*` (for Tailwind v4 utility classes such
+ * as `text-primary` → `color: var(--color-primary)`). CSS custom properties
+ * inherit, so children using either form pick up the buttonColor override.
+ *
+ * Themes without a per-buttonColor `tokens` block fall back to theme-level
+ * `colorTokens` because the variant-level entry resolves to undefined.
+ */
+export function buildVariantCascade(variant: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const token of VARIANT_COLOR_TOKENS) {
+    const value = variantColorVar(variant, token)
+    result[`--sireno-color-${token === "foreground" ? "fg" : token}`] = value
+    const cssToken =
+      token === "foreground"
+        ? "fg"
+        : token === "foreground-contrast"
+          ? "foreground-contrast"
+          : token
+    result[`--color-${cssToken}`] = value
+  }
+  result["--sireno-frame-border"] = variantVar(variant, "border")
+  return result
+}
+
+export const ButtonFrame = ({
+  children,
+  pressed = false,
+  isTapping = false,
+  isHolding = false,
+  holdProgress = 0,
+  buttonType,
+  variant = "default",
+  onClick,
+  onPointerDown,
+  onPointerUp,
+  onPointerMove,
+  onPointerLeave,
+  onPointerCancel,
+}: ButtonFrameProps) => {
+  const themeUi = useThemeUiPresentation()
+  if (themeUi?.buttonFrame) {
+    return themeUi.buttonFrame(
+      {
+        pressed,
+        isTapping,
+        isHolding,
+        holdProgress,
+        buttonType,
+        variant,
+        onClick,
+        onPointerDown,
+        onPointerUp,
+        onPointerMove,
+        onPointerLeave,
+        onPointerCancel,
+        children,
+      },
+      undefined,
+      buttonFrameBase,
+    )
+  }
+  warnUnknownVariant(variant)
+  return buttonFrameBase({
+    children,
+    pressed,
+    isTapping,
+    isHolding,
+    holdProgress,
+    buttonType,
+    variant,
+    onClick,
+    onPointerDown,
+    onPointerUp,
+    onPointerMove,
+    onPointerLeave,
+    onPointerCancel,
+  })
+}
+
+export function buttonFrameBase(props: ButtonFrameProps): ReactElement {
+  const {
+    children,
+    pressed = false,
+    isTapping = false,
+    isHolding = false,
+    holdProgress = 0,
+    buttonType,
+    variant = "default",
+    onClick,
+    onPointerDown,
+    onPointerUp,
+    onPointerMove,
+    onPointerLeave,
+    onPointerCancel,
+  } = props
+  warnUnknownVariant(variant)
+  const pressedClass = pressed || isTapping ? "scale-[0.98] opacity-90 " : ""
+  const holdingClass = isHolding ? "ring-2 ring-frame/70 " : ""
+  const style: CSSProperties = {
+    backgroundColor: variantVar(variant, "bg"),
+    borderColor: variantVar(variant, "border"),
+    color: variantVar(variant, "fg"),
+    boxShadow:
+      pressed || isTapping || isHolding
+        ? `0 0 12px ${variantVar(variant, "glow")}`
+        : undefined,
+  }
+
+  const cascadeVars: Record<string, string> = buildVariantCascade(variant)
+
+  return (
+    <div
+      className={`${pressedClass}${holdingClass}flex h-full w-full items-center justify-center overflow-hidden rounded-2xl p-1 border border-solid`}
+      data-sireno-button-frame="true"
+      data-variant={variant}
+      data-button-type={buttonType}
+      data-pressed={pressed || isTapping ? "true" : "false"}
+      data-holding={isHolding ? "true" : "false"}
+      data-held={isHolding ? "true" : undefined}
+      data-hold-progress={
+        holdProgress > 0 ? holdProgress.toFixed(2) : undefined
+      }
+      style={{ ...style, ...cascadeVars }}
+      onClick={onClick}
+      onPointerDown={onPointerDown}
+      onPointerUp={onPointerUp}
+      onPointerMove={onPointerMove}
+      onPointerLeave={onPointerLeave}
+      onPointerCancel={onPointerCancel}
+      role={onClick !== undefined ? "button" : undefined}
+      tabIndex={onClick !== undefined ? 0 : undefined}
+      onKeyDown={
+        onClick !== undefined
+          ? (event) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault()
+                onClick(event as unknown as MouseEvent<HTMLDivElement>)
+              }
+            }
+          : undefined
+      }
+    >
+      {children}
+    </div>
+  )
+}

package/src/ui/contexts/AssetCacheContext.tsx

@@ -0,0 +1,43 @@
+import { createContext, useCallback, useContext, useRef } from "react"
+
+export type AssetCache = Map<string, string>
+
+export const AssetCacheContext = createContext<AssetCache>(new Map())
+
+export const useAssetCache = (): AssetCache => {
+  return useContext(AssetCacheContext)
+}
+
+interface UseAssetCacheMutationsResult {
+  setAsset: (id: string, data: string) => void
+  clearAssets: () => void
+}
+
+export const useAssetCacheMutations = (): UseAssetCacheMutationsResult => {
+  const cache = useContext(AssetCacheContext)
+  const setAsset = useCallback(
+    (id: string, data: string) => {
+      cache.set(id, data)
+    },
+    [cache],
+  )
+  const clearAssets = useCallback(() => {
+    cache.clear()
+  }, [cache])
+  return { setAsset, clearAssets }
+}
+
+interface AssetCacheProviderProps {
+  children: React.ReactNode
+}
+
+export const AssetCacheProvider = ({
+  children,
+}: AssetCacheProviderProps): React.ReactElement => {
+  const cacheRef = useRef<AssetCache>(new Map())
+  return (
+    <AssetCacheContext.Provider value={cacheRef.current}>
+      {children}
+    </AssetCacheContext.Provider>
+  )
+}

package/src/ui/index.ts

@@ -0,0 +1,20 @@
+export * from "./ButtonFrame"
+export * from "./primitives"
+export * from "./surfaces"
+export {
+  ThemeUiPresentationProvider,
+  useThemeUiPresentation,
+} from "./theme-presentation"
+export type {
+  ThemeUiPresentation,
+  ThemeOverrideContext,
+} from "./theme-presentation"
+export { buildPresentation } from "./theme-presentation-builder"
+export { cn } from "./utils/cn"
+
+export {
+  AssetCacheProvider,
+  useAssetCache,
+  useAssetCacheMutations,
+  type AssetCache,
+} from "./contexts/AssetCacheContext"

package/src/ui/primitives/Chip.tsx

@@ -0,0 +1,53 @@
+import { type ReactElement } from "react"
+
+import { useThemeUiPresentation } from "../theme-presentation"
+import { cn } from "../utils/cn"
+import { Text, TextProps } from "./Text"
+
+const TONE_CLASS = {
+  accent: "border-accent text-accent bg-accent/20",
+  danger: "border-danger text-danger bg-danger/20",
+  foreground: "border-foreground text-foreground bg-foreground/20",
+  primary: "border-primary text-primary bg-primary/20",
+  success: "border-success text-success bg-success/20",
+  muted: "border-grey text-grey bg-grey/0",
+} as const
+
+export type ChipTone = keyof typeof TONE_CLASS
+
+export interface ChipProps {
+  text: string
+  tone?: ChipTone
+  size?: TextProps["size"]
+}
+
+export function Chip(props: ChipProps): ReactElement {
+  const tone = props.tone ?? "foreground"
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.primitives?.chip) {
+    return themeUi.primitives.chip(
+      { text: props.text, tone, size: props.size },
+      undefined,
+      chipBase,
+    )
+  }
+
+  return chipBase({ text: props.text, tone, size: props.size })
+}
+
+export function chipBase(props: ChipProps): ReactElement {
+  const tone = props.tone ?? "foreground"
+
+  return (
+    <Text
+      className={cn([
+        "inline-flex items-center justify-center rounded-full border px-2 py-0 font-aux  uppercase tracking-wide font-bold",
+        TONE_CLASS[tone],
+      ])}
+      size={props.size ?? "sm"}
+      data-sireno-ui-chip="true"
+      text={props.text}
+    />
+  )
+}

package/src/ui/primitives/Icon.tsx

@@ -0,0 +1,209 @@
+import type { ReactElement } from "react"
+
+import * as lucideIcons from "lucide-react"
+import { type LucideIcon } from "lucide-react"
+
+import { EMOJI_RE, ICON_FALLBACK, isIconSource } from "../../core/icon-source"
+import { useAssetCache } from "../contexts/AssetCacheContext"
+import { useThemeUiPresentation } from "../theme-presentation"
+import { cn } from "../utils/cn"
+
+const TONE_CLASS = {
+  accent: "text-accent",
+  danger: "text-danger",
+  foreground: "text-fg",
+  primary: "text-primary",
+  success: "text-success",
+  background: "text-background",
+  "foreground-contrast": "text-foreground-contrast",
+} as const
+
+export type IconTone = keyof typeof TONE_CLASS
+
+export interface IconProps {
+  readonly source?: string
+  readonly size?: number
+  readonly tone?: IconTone
+  readonly fill?: boolean
+}
+
+const TONE_FALLBACK: IconTone = "danger"
+
+function renderLucide(
+  props: { size?: number; tone?: IconTone; fill?: boolean },
+  LucideComponent: LucideIcon,
+): ReactElement {
+  const size = props.size ?? 20
+  return (
+    <LucideComponent
+      className={cn([
+        "inline-block shrink-0",
+        TONE_CLASS[props.tone ?? "foreground"],
+      ])}
+      data-sireno-icon-source="generic"
+      data-sireno-ui-icon="true"
+      focusable="false"
+      size={size}
+      strokeWidth={1.8}
+      fill={props.fill ? "currentColor" : "none"}
+    />
+  )
+}
+
+function renderEmoji(
+  emoji: string,
+  props: { size?: number; tone?: IconTone },
+): ReactElement {
+  const size = props.size ?? 20
+  return (
+    <span
+      className={cn([
+        "inline-block shrink-0 leading-none",
+        TONE_CLASS[props.tone ?? "foreground"],
+      ])}
+      data-sireno-icon-source="emoji"
+      data-sireno-ui-icon="true"
+      style={{ fontSize: `${size}px` }}
+    >
+      {emoji}
+    </span>
+  )
+}
+
+const LUCIDE_ICON_EXPORTS = Object.fromEntries(
+  Object.entries(lucideIcons).filter((entry): entry is [string, LucideIcon] => {
+    const [exportName, value] = entry
+    return (
+      typeof value === "object" &&
+      exportName[0] === exportName[0]?.toUpperCase()
+    )
+  }),
+) satisfies Record<string, LucideIcon>
+
+function toLucideExportName(name: string): string {
+  return name
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map(
+      (segment) => segment[0]!.toUpperCase() + segment.slice(1).toLowerCase(),
+    )
+    .join("")
+}
+
+function resolveLucideIcon(name: string): LucideIcon | undefined {
+  const exportName = toLucideExportName(name)
+  return (
+    LUCIDE_ICON_EXPORTS[exportName] ??
+    Object.entries(LUCIDE_ICON_EXPORTS).find(
+      ([candidate]) =>
+        candidate.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase() ===
+        name.trim().toLowerCase(),
+    )?.[1]
+  )
+}
+
+/**
+ * Last-resort fallback. Renders the alert-circle Lucide icon with a
+ * danger tone so the user sees something went wrong. Never throws —
+ * even if the fallback icon name itself can't be resolved (it always
+ * can), we return an empty span.
+ */
+function renderFallbackIcon(props: {
+  size?: number
+  tone?: IconTone
+}): ReactElement {
+  const fallbackProps = { ...props, tone: props.tone ?? TONE_FALLBACK }
+  const icon = resolveLucideIcon("alert-circle")
+  if (icon !== undefined) return renderLucide(fallbackProps, icon)
+  return <></>
+}
+
+/**
+ * Warn once per offending source string about an invalid icon. This keeps
+ * the console quiet for legitimate icon:// / asset:// / emoji sources while
+ * still surfacing typos like icon://arrowleft that the user might miss.
+ */
+const warnedSources = new Set<string>()
+const warnInvalidIcon = (source: string): void => {
+  if (warnedSources.has(source)) return
+  warnedSources.add(source)
+  console.warn(
+    `[Icon] invalid icon source "${source}" — using fallback ${ICON_FALLBACK}. Expected icon://<name>, asset://<id>, or a single emoji.`,
+  )
+}
+
+export function Icon(props: IconProps): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.primitives?.icon) {
+    return themeUi.primitives.icon(props, undefined, iconBase)
+  }
+
+  return iconBase(props)
+}
+
+export function iconBase(props: IconProps): ReactElement {
+  const source = props.source
+  const size = props.size ?? 20
+
+  if (typeof source !== "string" || source.length === 0) {
+    return renderFallbackIcon(props)
+  }
+
+  if (!isIconSource(source)) {
+    warnInvalidIcon(source)
+    return renderFallbackIcon(props)
+  }
+
+  if (EMOJI_RE.test(source)) {
+    return renderEmoji(source, props)
+  }
+
+  if (source.startsWith("icon://")) {
+    const name = source.slice("icon://".length)
+    const LucideComponent = resolveLucideIcon(name)
+    if (LucideComponent === undefined) {
+      warnInvalidIcon(source)
+      return renderFallbackIcon(props)
+    }
+    return renderLucide(props, LucideComponent)
+  }
+
+  if (source.startsWith("asset://")) {
+    const id = source.slice("asset://".length)
+    const cache = useAssetCache()
+    const src = cache.get(id)
+    if (src === undefined) {
+      warnInvalidIcon(source)
+      return renderFallbackIcon(props)
+    }
+    return (
+      <img
+        alt=""
+        className={cn(["inline-block shrink-0"])}
+        data-sireno-icon-source="asset"
+        data-sireno-ui-icon="true"
+        src={src}
+        style={{
+          height: `${size}px`,
+          objectFit: "contain",
+          width: `${size}px`,
+        }}
+      />
+    )
+  }
+
+  return renderFallbackIcon(props)
+}
+
+/** @internal exposed for tests */
+export const _testHelpers = {
+  EMOJI_RE,
+  ICON_FALLBACK,
+  isIconSource,
+  resolveLucideIcon,
+  toLucideExportName,
+  renderFallbackIcon,
+}

package/src/ui/primitives/Label.tsx

@@ -0,0 +1,82 @@
+import { type ReactElement } from "react"
+
+import { useThemeUiPresentation } from "../theme-presentation"
+import { cn } from "../utils/cn"
+import { Text, type TextFit, TextSize, TextWeight } from "./Text"
+
+export const labelVariants = ["primary", "secondary", "small", "xxs"] as const
+export type LabelVariant = (typeof labelVariants)[number]
+
+export interface LabelProps {
+  text: string
+  lines?: 1 | 2 | 3
+  variant?: LabelVariant
+  className?: string
+}
+
+export function Label(props: LabelProps): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.primitives?.label) {
+    return themeUi.primitives.label(props, undefined, labelBase)
+  }
+
+  return labelBase(props)
+}
+
+export function labelBase(props: LabelProps): ReactElement {
+  const variantsStyle: Record<
+    LabelVariant,
+    {
+      size: TextSize
+      className?: string
+      weight: TextWeight
+    }
+  > = {
+    primary: {
+      size: "md",
+      className: "uppercase",
+      weight: "bold",
+    },
+    secondary: {
+      size: "sm",
+      className: "uppercase",
+      weight: "bold",
+    },
+    small: {
+      size: "xs",
+      weight: "bold",
+    },
+    xxs: {
+      size: "xxs",
+      weight: "bold",
+    },
+  }
+
+  const variantStyle = variantsStyle[props.variant ?? "primary"]
+  const lines = props.lines || 1
+  const fit: TextFit = {
+    type: "fit",
+    lines,
+    reserveSpace: false,
+    ellipsis: true,
+  }
+
+  return (
+    <Text
+      data-sireno-ui-label="true"
+      size={variantStyle.size}
+      className={cn(
+        "tracking-tight max-w-full wrap-anywhere",
+        variantStyle.className,
+        props.className,
+      )}
+      lineHeight={1.25}
+      fit={fit}
+      tone="primary"
+      typography="main"
+      text={props.text}
+      weight={variantStyle.weight}
+    />
+  )
+}

package/src/ui/primitives/ProgressBar.tsx

@@ -0,0 +1,38 @@
+import { cn } from "../utils/cn"
+import type { ReactElement } from "react"
+
+import { useThemeUiPresentation } from "../theme-presentation"
+
+export interface ProgressBarProps {
+  value: number
+  className?: string
+  bgColor?: string
+  bgColorAlt?: string
+}
+
+export function ProgressBar(props: ProgressBarProps): ReactElement {
+  const themeUi = useThemeUiPresentation()
+
+  if (themeUi?.primitives?.progressBar) {
+    return themeUi.primitives.progressBar(props, undefined, progressBarBase)
+  }
+
+  return progressBarBase(props)
+}
+
+export function progressBarBase(props: ProgressBarProps): ReactElement {
+  const {
+    value,
+    className,
+    bgColor = "bg-primary",
+    bgColorAlt = "bg-primary/30",
+  } = props
+  return (
+    <div className={cn("h-2 w-full rounded-4xl", bgColorAlt, className)}>
+      <div
+        className={cn("h-2 rounded-4xl transition-all", bgColor)}
+        style={{ width: `${Math.min(100, Math.max(0, value))}%` }}
+      />
+    </div>
+  )
+}