@a4ui/core 0.11.1 → 0.13.0

package/src/index.ts

@@ -0,0 +1,186 @@
+// A4ui — public entry point.
+//
+// Components are extracted incrementally from the source project
+// (sonora precision/alfredorust/solid/src/components). As each lands under
+// src/ui/ or src/layout/, re-export it here. See CLAUDE.md → "Extraction plan".
+//
+// Consumers import the styles once (tokens + motion) and the components:
+//   import '@a4ui/core/styles.css'
+//   import { Button, Card, Modal } from '@a4ui/core'
+
+export const A4UI_VERSION = '0.13.0'
+
+// Helpers (src/lib) — generic, framework-level utilities.
+export { cn } from './lib/cn'
+export { useTheme, toggleTheme, setTheme, storedTheme, applyTheme, toggled, type Theme } from './lib/theme'
+export { useEffects, isCalm, setEffects } from './lib/effects'
+export {
+  prefersReducedMotion,
+  motionReduced,
+  useMotionForced,
+  setMotionForced,
+  createCountUp,
+  animateIn,
+  revealOnScroll,
+  // Motion (motion.dev) imperative API, re-exported so the whole app shares one
+  // engine (used by Stat's entrance / count-up; reach for these for scroll-linked
+  // reveals, staggered lists, springs, etc.).
+  animate,
+  inView,
+  scroll,
+  stagger,
+  spring,
+} from './lib/motion'
+export { useMediaQuery } from './lib/media'
+export { remeasureAfterLayout } from './lib/virtual'
+
+// UI components (src/ui) — all 18 extracted. See CLAUDE.md.
+export { Accordion, type AccordionItem } from './ui/Accordion'
+export { Badge, type BadgeTone } from './ui/Badge'
+export { Button, type ButtonVariant } from './ui/Button'
+export { Card, CardHeader, CardTitle, CardContent } from './ui/Card'
+export { Checkbox } from './ui/Checkbox'
+export { DateField } from './ui/DateField'
+export { TimeField, type TimeFieldProps } from './ui/TimeField'
+export { DateTimeField, type DateTimeFieldProps } from './ui/DateTimeField'
+export { DateRangePicker, type DateRange, type DateRangePickerProps } from './ui/DateRangePicker'
+export { FormField, FormLabel, FormControl, FormDescription, FormError, type FormFieldProps } from './ui/Form'
+export { FileUpload, type UploadFile, type FileUploadProps } from './ui/FileUpload'
+export { MultiSelect, type MultiSelectOption, type MultiSelectProps } from './ui/MultiSelect'
+export { Drawer } from './ui/Drawer'
+export { Dropdown, type DropdownItem } from './ui/Dropdown'
+export { Dropzone } from './ui/Dropzone'
+export { Input } from './ui/Input'
+export { Modal } from './ui/Modal'
+export { PageHeader } from './ui/PageHeader'
+export { Pagination } from './ui/Pagination'
+export { Select } from './ui/Select'
+export { Spinner } from './ui/Spinner'
+export { Stat, type StatTone } from './ui/Stat'
+export { Table, TableHead, TableBody, TableRow, TableHeadCell, TableCell } from './ui/Table'
+export { VirtualList } from './ui/VirtualList'
+export { Tabs, type TabItem } from './ui/Tabs'
+export { toast, Toaster, type ToastTone } from './ui/Toast'
+export { Switch } from './ui/Switch'
+export { RadioGroup, type RadioOption } from './ui/RadioGroup'
+export { Textarea } from './ui/Textarea'
+export { Tooltip } from './ui/Tooltip'
+export { Popover } from './ui/Popover'
+export { HoverCard } from './ui/HoverCard'
+export { Alert, type AlertTone } from './ui/Alert'
+export { Avatar } from './ui/Avatar'
+export { Skeleton } from './ui/Skeleton'
+export { Separator } from './ui/Separator'
+export { Progress } from './ui/Progress'
+export { Meter } from './ui/Meter'
+export { Slider } from './ui/Slider'
+export { NumberInput } from './ui/NumberInput'
+export { Toggle } from './ui/Toggle'
+export { ToggleGroup, type ToggleGroupOption } from './ui/ToggleGroup'
+export { SegmentedControl, type SegmentedOption } from './ui/SegmentedControl'
+export { Breadcrumb, type BreadcrumbItem } from './ui/Breadcrumb'
+export { AlertDialog } from './ui/AlertDialog'
+export { ContextMenu, type ContextMenuItem } from './ui/ContextMenu'
+export { Combobox } from './ui/Combobox'
+export { Carousel, type CarouselProps } from './ui/Carousel'
+export { Stepper, type StepItem, type StepperProps } from './ui/Stepper'
+export { Timeline, type TimelineItem, type TimelineTone, type TimelineProps } from './ui/Timeline'
+export { Rating, type RatingProps } from './ui/Rating'
+export { Empty, type EmptyProps } from './ui/Empty'
+export { Calendar, type CalendarProps } from './ui/Calendar'
+export { Tree, type TreeNode, type TreeProps } from './ui/Tree'
+export { Kbd } from './ui/Kbd'
+export { AvatarGroup, type AvatarGroupProps } from './ui/AvatarGroup'
+export { Descriptions, type DescriptionItem, type DescriptionsProps } from './ui/Descriptions'
+export { Result, type ResultStatus, type ResultProps } from './ui/Result'
+export { Splitter, type SplitterProps } from './ui/Splitter'
+export { Command, type CommandItem, type CommandProps } from './ui/Command'
+export { TagInput, type TagInputProps } from './ui/TagInput'
+export { Collapse } from './ui/Collapse'
+export { RingProgress, type RingProgressProps } from './ui/RingProgress'
+export { BackToTop, type BackToTopProps } from './ui/BackToTop'
+export {
+  FloatingActionButton,
+  type FloatingActionButtonProps,
+  type FloatingActionButtonPosition,
+} from './ui/FloatingActionButton'
+export { Anchor, type AnchorItem, type AnchorProps } from './ui/Anchor'
+export { Highlight, type HighlightProps } from './ui/Highlight'
+export { List, type ListItem } from './ui/List'
+export { Countdown, type CountdownProps } from './ui/Countdown'
+export { Affix } from './ui/Affix'
+export { Transfer, type TransferItem, type TransferProps } from './ui/Transfer'
+export { Image, type ImageProps } from './ui/Image'
+export { SpeedDial, type SpeedDialAction, type SpeedDialProps } from './ui/SpeedDial'
+export { BottomNavigation, type BottomNavItem, type BottomNavigationProps } from './ui/BottomNavigation'
+export { Marquee } from './ui/Marquee'
+export { DataGrid, type DataGridColumn, type DataGridProps } from './ui/DataGrid'
+export { TreeSelect, type TreeSelectProps } from './ui/TreeSelect'
+export { Cascader, type CascaderOption, type CascaderProps } from './ui/Cascader'
+export { Mentions, type MentionOption, type MentionsProps } from './ui/Mentions'
+export { Tour, type TourStep, type TourProps } from './ui/Tour'
+export {
+  NotificationCenter,
+  type NotificationItem,
+  type NotificationCenterProps,
+} from './ui/NotificationCenter'
+export { ColorPicker, type ColorPickerProps } from './ui/ColorPicker'
+export { Comment, type CommentData, type CommentProps } from './ui/Comment'
+export { CalendarHeatmap, type HeatmapValue, type CalendarHeatmapProps } from './ui/CalendarHeatmap'
+export { Portal, type PortalProps } from './ui/Portal'
+export { Sortable, type SortableProps } from './ui/Sortable'
+export { Clock, type ClockProps } from './ui/Clock'
+
+// Motion components (src/ui) — animation primitives built on the `motion` engine
+// (adapted from motion.dev examples). All tree-shakeable and reduced-motion aware;
+// `motion` is external, so importing one of these is the only thing that pulls it.
+export { ScrambleText, type ScrambleTextProps } from './ui/ScrambleText'
+export { TextReveal, type TextRevealProps } from './ui/TextReveal'
+export { HoldToConfirm, type HoldToConfirmProps } from './ui/HoldToConfirm'
+export { LoadingDots, type LoadingDotsProps } from './ui/LoadingDots'
+export { Curtain, type CurtainProps, type CurtainVariant } from './ui/Curtain'
+export { Parallax, type ParallaxProps } from './ui/Parallax'
+export { FillText, type FillTextProps } from './ui/FillText'
+export {
+  NotificationStack,
+  type NotificationStackProps,
+  type StackNotification,
+} from './ui/NotificationStack'
+export { MultiStateBadge, type MultiStateBadgeProps, type BadgeState } from './ui/MultiStateBadge'
+export { NowPlaying, type NowPlayingProps } from './ui/NowPlaying'
+export { Expandable, type ExpandableProps } from './ui/Expandable'
+export { flyToCart, type FlyToCartOptions } from './lib/flyToCart'
+
+// Layout (src/layout) — generic shell + backdrop + toggles. App-coupled pieces
+// (Sidebar, Topbar, CompanySwitcher, DemoBanner, CommandPalette) stay in the app.
+export { AppShell } from './layout/AppShell'
+export { SpaceBackground } from './layout/SpaceBackground'
+export { ThemedScenery, type ThemedSceneryProps } from './layout/ThemedScenery'
+export { SnowScenery } from './layout/SnowScenery'
+export { ChristmasBackground } from './layout/ChristmasBackground'
+export { ThemeToggle } from './layout/ThemeToggle'
+export { EffectsToggle } from './layout/EffectsToggle'
+export { NavGroup } from './layout/NavGroup'
+
+// Themes (src/themes) — swappable color palettes (Space is the default). Pick one
+// with `selectTheme('dino')`, restore the saved one with `initTheme()`, or build
+// your own from a ThemeDefinition. Distinct from the light/dark `setTheme` above.
+export {
+  themes,
+  space,
+  dino,
+  doctor,
+  scientist,
+  soccer,
+  snow,
+  christmas,
+  activeTheme,
+  selectTheme,
+  applyThemeDefinition,
+  initTheme,
+  themeToCss,
+  themeToJson,
+  TOKEN_ORDER,
+  type ThemeDefinition,
+  type Palette,
+} from './themes'

package/src/layout/AppShell.tsx

@@ -0,0 +1,102 @@
+// Generic app shell: the fixed SpaceBackground (z-0) behind a flex layout of an
+// optional sidebar slot + a content column (optional banner + topbar + routed
+// <main>). Unlike the source app's AppShell, this is slot-based and unopinionated
+// about the sidebar — pass your own via the `sidebar` prop, and it manages its
+// own width/collapse (the flex layout reflows the content column automatically,
+// so no --sidebar-w padding coupling). The <main> is wrapped in Suspense + an
+// ErrorBoundary so a route chunk failing or still loading never blanks the shell.
+import { ErrorBoundary, Show, Suspense, type JSX, type ParentProps } from 'solid-js'
+
+import { Button } from '../ui/Button'
+import { Spinner } from '../ui/Spinner'
+import { SpaceBackground } from './SpaceBackground'
+
+/** Props for {@link AppShell}. All slots are optional — pass only what your app needs. */
+interface AppShellProps extends ParentProps {
+  /** Left column (e.g. a Sidebar). Rendered as a flex child; owns its own width. */
+  sidebar?: JSX.Element
+  /** Top bar inside the content column, above <main>. */
+  topbar?: JSX.Element
+  /** Full-width strip above the topbar (e.g. a demo/announcement banner). */
+  banner?: JSX.Element
+  /** Fixed z-0 backdrop. Defaults to <SpaceBackground/>; pass a node to override,
+      or `null` for a plain background. */
+  background?: JSX.Element
+  /** Max content width for <main>. Default '1400px'. */
+  maxWidth?: string
+  /** Override the default error fallback shown when a route throws. Receives
+      the caught error and a `reset` callback that re-renders the ErrorBoundary's
+      children. */
+  errorFallback?: (err: unknown, reset: () => void) => JSX.Element
+}
+
+function defaultErrorFallback(err: unknown, reset: () => void): JSX.Element {
+  return (
+    <div class="mx-auto max-w-md py-20 text-center">
+      <p class="text-lg font-semibold">Something went wrong loading this page</p>
+      <p class="mt-1 break-words text-sm text-muted-foreground">{String((err as Error)?.message ?? err)}</p>
+      <div class="mt-4 flex justify-center gap-2">
+        <Button variant="outline" onClick={reset}>
+          Retry
+        </Button>
+        <Button onClick={() => window.location.reload()}>Reload</Button>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Generic app shell: a fixed {@link SpaceBackground} behind a flex layout of
+ * an optional sidebar slot plus a content column (optional banner + topbar +
+ * routed `<main>`). Slot-based and unopinionated about the sidebar — pass
+ * your own component via `sidebar` and it manages its own width/collapse.
+ * `<main>` is wrapped in `Suspense` + an `ErrorBoundary` so a route chunk
+ * failing or still loading never blanks the shell.
+ *
+ * @example
+ * ```tsx
+ * <AppShell sidebar={<Sidebar />} topbar={<Topbar />}>
+ *   <Route />
+ * </AppShell>
+ * ```
+ */
+export function AppShell(props: ParentProps<AppShellProps>): JSX.Element {
+  const fallback = (err: unknown, reset: () => void) =>
+    (props.errorFallback ?? defaultErrorFallback)(err, reset)
+  return (
+    <div class="relative min-h-screen">
+      <Show when={props.background !== null} fallback={null}>
+        {props.background ?? <SpaceBackground />}
+      </Show>
+      <div class="relative z-10 flex min-h-screen">
+        {props.sidebar}
+        <div class="flex min-w-0 flex-1 flex-col">
+          {props.banner}
+          {props.topbar}
+          <main
+            class="relative mx-auto w-full min-w-0 flex-1 px-4 py-6 sm:px-6"
+            style={{ 'max-width': props.maxWidth ?? '1400px' }}
+          >
+            {/* Never blank the content column: Suspense shows a spinner while a
+                route's chunk streams in, and the ErrorBoundary catches any other
+                runtime error with a friendly retry/reload — the shell stays put. */}
+            <ErrorBoundary fallback={fallback}>
+              <Suspense
+                fallback={
+                  <div class="flex justify-center py-24 text-muted-foreground">
+                    <Spinner />
+                  </div>
+                }
+              >
+                {/* Routed content. No page cross-fade transition: solid-transition-group
+                    left the outgoing (lazy) page mounted, which stacked its height
+                    below the new page and created a huge phantom scroll region. */}
+                {props.children}
+              </Suspense>
+            </ErrorBoundary>
+          </main>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/layout/ChristmasBackground.tsx

@@ -0,0 +1,177 @@
+// Christmas scenery for the "christmas" theme: a cozy night sky, drifting snow, a
+// twinkling light garland across the top, a pine tree, and — instead of a
+// shooting star — Santa's sleigh crossing the sky (ambiently + on a background
+// click). Shares the cursor-glow / magnetic / edge-glow pointer effects. Motion
+// is skipped under motionReduced().
+import { createEffect, For, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { motionReduced } from '../lib/motion'
+import { bindPointerFx } from './sceneEffects'
+
+const FLAKE_COUNT = 60
+const LIGHT_COLORS = ['#ff5a5a', '#4ade80', '#ffd23f', '#5aa9ff', '#ff8ad8']
+const GARLAND = Array.from({ length: 22 }, (_, i) => i)
+
+function buildFlakes(animate: boolean): string {
+  const rnd = Math.random
+  let html = ''
+  for (let i = 0; i < FLAKE_COUNT; i++) {
+    const size = (2 + rnd() * 4).toFixed(1)
+    const op = (0.4 + rnd() * 0.6).toFixed(2)
+    const left = (rnd() * 100).toFixed(2)
+    const dur = (6 + rnd() * 9).toFixed(1)
+    const delay = (-rnd() * 15).toFixed(1)
+    const sway = (rnd() * 2 - 1) * (8 + rnd() * 12)
+    const anim = animate
+      ? `animation:snowFall ${dur}s linear ${delay}s infinite;`
+      : `top:${(rnd() * 100).toFixed(1)}%;`
+    html +=
+      `<span class="flake" style="left:${left}%;width:${size}px;height:${size}px;opacity:${op};` +
+      `--sway:${sway.toFixed(0)}px;${anim}"></span>`
+  }
+  return html
+}
+
+/**
+ * Festive backdrop for the `christmas` theme: night sky, falling snow, a
+ * twinkling light garland, a pine tree, and Santa's sleigh flying across (ambient
+ * + on background click). Mount as {@link AppShell}'s `background`. Motion is
+ * skipped under `motionReduced()`.
+ */
+export function ChristmasBackground(): JSX.Element {
+  let root!: HTMLDivElement
+  let field!: HTMLDivElement
+
+  createEffect(() => {
+    field.innerHTML = buildFlakes(!motionReduced())
+  })
+
+  onMount(() => {
+    const cleanups: Array<() => void> = []
+    const timers: number[] = []
+
+    // Santa's sleigh crosses from one side to the other with a gentle arc.
+    const launchSanta = (rtl: boolean): void => {
+      const el = document.createElement('span')
+      el.textContent = '🎅🛷'
+      const top = 6 + Math.random() * 26
+      const size = 30 + Math.random() * 16
+      el.style.cssText =
+        `position:absolute;top:${top}vh;${rtl ? 'right' : 'left'}:-14%;font-size:${size.toFixed(0)}px;` +
+        `white-space:nowrap;pointer-events:none;filter:drop-shadow(0 0 6px hsl(var(--primary) / 0.5));`
+      if (rtl) el.style.transform = 'scaleX(-1)'
+      root.appendChild(el)
+      const dist = window.innerWidth * 1.3
+      const ex = rtl ? -dist : dist
+      const dur = 6500 + Math.random() * 4000
+      const anim = el.animate(
+        [
+          { opacity: 0, transform: `translate(0,0) ${rtl ? 'scaleX(-1)' : ''}` },
+          {
+            opacity: 1,
+            transform: `translate(${ex * 0.15}px,-18px) ${rtl ? 'scaleX(-1)' : ''}`,
+            offset: 0.15,
+          },
+          {
+            opacity: 1,
+            transform: `translate(${ex * 0.85}px,-18px) ${rtl ? 'scaleX(-1)' : ''}`,
+            offset: 0.85,
+          },
+          { opacity: 0, transform: `translate(${ex}px,0) ${rtl ? 'scaleX(-1)' : ''}` },
+        ],
+        { duration: dur, easing: 'cubic-bezier(.4,0,.6,1)', fill: 'forwards' },
+      )
+      anim.onfinish = () => el.remove()
+      timers.push(window.setTimeout(() => el.remove(), dur + 400))
+    }
+
+    const INTERACTIVE =
+      'a, button, input, select, textarea, label, [role="button"], [role="tab"], [role="menuitem"], [role="dialog"], [contenteditable]'
+    const onClick = (e: MouseEvent): void => {
+      if ((e.target as Element | null)?.closest?.(INTERACTIVE)) return
+      launchSanta(Math.random() < 0.5)
+    }
+    document.addEventListener('click', onClick)
+    cleanups.push(() => document.removeEventListener('click', onClick))
+
+    if (!motionReduced()) {
+      cleanups.push(bindPointerFx(root))
+      const loop = (): void => {
+        launchSanta(Math.random() < 0.5)
+        timers.push(window.setTimeout(loop, 9000 + Math.random() * 9000))
+      }
+      timers.push(window.setTimeout(loop, 3000))
+    }
+
+    onCleanup(() => {
+      cleanups.forEach((fn) => fn())
+      timers.forEach((t) => clearTimeout(t))
+    })
+  })
+
+  return (
+    <div id="xmas" ref={root} aria-hidden="true">
+      <div class="xmas-sky" />
+      <div ref={field} class="absolute inset-0" />
+
+      {/* Light garland across the top */}
+      <div style={{ position: 'absolute', top: '0', left: '0', right: '0', height: '26px' }}>
+        <For each={GARLAND}>
+          {(i) => {
+            const c = LIGHT_COLORS[i % LIGHT_COLORS.length]
+            return (
+              <span
+                class="light"
+                style={{
+                  left: `${((i / (GARLAND.length - 1)) * 100).toFixed(2)}%`,
+                  background: c,
+                  color: c,
+                  'animation-delay': `${(i % 5) * 0.3}s`,
+                }}
+              />
+            )
+          }}
+        </For>
+      </div>
+
+      {/* Pine tree (accent = pine green, so it follows the theme) */}
+      <svg
+        viewBox="0 0 200 270"
+        style={{
+          position: 'absolute',
+          bottom: '0',
+          left: '50%',
+          transform: 'translateX(-50%)',
+          width: '240px',
+          height: 'auto',
+          opacity: '0.9',
+        }}
+      >
+        <rect x="92" y="228" width="16" height="42" fill="hsl(25 45% 28%)" />
+        <polygon points="100,64 60,150 140,150" fill="hsl(var(--accent))" />
+        <polygon points="100,110 48,196 152,196" fill="hsl(var(--accent))" />
+        <polygon points="100,158 38,240 162,240" fill="hsl(var(--accent))" />
+        <polygon points="100,40 106,58 125,58 110,70 116,88 100,77 84,88 90,70 75,58 94,58" fill="#ffd23f" />
+        <circle cx="82" cy="180" r="5" fill="#ff5a5a" />
+        <circle cx="120" cy="205" r="5" fill="#5aa9ff" />
+        <circle cx="100" cy="150" r="5" fill="#ffd23f" />
+        <circle cx="72" cy="225" r="5" fill="#ff8ad8" />
+        <circle cx="132" cy="228" r="5" fill="#ffd23f" />
+      </svg>
+
+      <div
+        id="cursorGlow"
+        style={{
+          position: 'absolute',
+          width: '520px',
+          height: '520px',
+          'border-radius': '50%',
+          background: 'radial-gradient(circle, hsl(var(--primary) / 0.1), transparent 70%)',
+          transform: 'translate(-50%,-50%)',
+          opacity: '0',
+          transition: 'opacity .4s ease',
+        }}
+      />
+    </div>
+  )
+}

package/src/layout/EffectsToggle.tsx

@@ -0,0 +1,41 @@
+// Single "visual effects" toggle. Pressed (default) = full space-glass
+// experience: translucent glass, starfield, animations. Un-press it for calm
+// mode (opaque surfaces, no starfield, no motion) — friendlier for contrast,
+// motion sensitivity and low-power devices.
+import { Sparkles } from 'lucide-solid'
+
+import { setEffects, useEffects } from '../lib/effects'
+
+/** Props for {@link EffectsToggle}. */
+interface EffectsToggleProps {
+  /** Accessible label / tooltip text. Defaults to `'Visual effects'`. */
+  label?: string
+}
+
+/**
+ * Icon button that toggles the "visual effects" switch: pressed (default) is
+ * the full space-glass experience (translucent glass, starfield, animation);
+ * un-pressed is calm mode (opaque surfaces, no starfield, no motion) — useful
+ * for contrast, motion sensitivity, and low-power devices. Wraps
+ * {@link useEffects} + {@link setEffects}.
+ *
+ * @example
+ * ```tsx
+ * <EffectsToggle label="Toggle effects" />
+ * ```
+ */
+export function EffectsToggle(props: EffectsToggleProps) {
+  const on = useEffects()
+  return (
+    <button
+      type="button"
+      class="grid h-9 w-9 place-items-center rounded-lg text-muted-foreground transition hover:bg-muted hover:text-foreground aria-pressed:text-primary"
+      aria-pressed={on()}
+      aria-label={props.label ?? 'Visual effects'}
+      title={on() ? 'Visual effects on — click for calm mode' : 'Calm mode — click to enable effects'}
+      onClick={() => setEffects(!on())}
+    >
+      <Sparkles class="h-[18px] w-[18px]" />
+    </button>
+  )
+}

package/src/layout/NavGroup.tsx

@@ -0,0 +1,45 @@
+// Collapsible sidebar category — native <details>/<summary>, no JS state, chevron
+// rotates via the `group-[[open]]:rotate-90` arbitrary-variant selector. Open by
+// default (every group starts expanded).
+import type { JSX, ParentProps } from 'solid-js'
+
+/** Props for {@link NavGroup}. */
+interface NavGroupProps extends ParentProps {
+  /** Category heading shown in the summary row (rendered uppercase). */
+  title: string
+}
+
+/**
+ * Collapsible sidebar nav category. Uses native `<details>`/`<summary>` (no
+ * JS state), with a chevron that rotates via a `group-[[open]]` CSS variant.
+ * Expanded by default; wrap a list of nav links as `children`.
+ *
+ * @example
+ * ```tsx
+ * <NavGroup title="Settings">
+ *   <NavLink href="/settings/profile">Profile</NavLink>
+ *   <NavLink href="/settings/billing">Billing</NavLink>
+ * </NavGroup>
+ * ```
+ */
+export function NavGroup(props: NavGroupProps): JSX.Element {
+  return (
+    <details open class="group">
+      <summary class="mt-3 flex cursor-pointer list-none select-none items-center justify-between rounded-md px-3 py-1.5 text-xs font-semibold uppercase tracking-wide text-muted-foreground transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden">
+        <span>{props.title}</span>
+        <svg
+          class="h-3.5 w-3.5 shrink-0 transition-transform duration-200 group-[[open]]:rotate-90"
+          viewBox="0 0 20 20"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path d="M7 5l6 5-6 5" />
+        </svg>
+      </summary>
+      <div class="ml-4 mt-1 space-y-0.5 border-l border-border pl-2">{props.children}</div>
+    </details>
+  )
+}

package/src/layout/SnowScenery.tsx

@@ -0,0 +1,76 @@
+// Snow scenery for the "snow" theme: snowflakes drifting DOWN with a sideways
+// sway, a snow bank building at the bottom, and a frosted cap on cards (via the
+// `data-scene="snow"` flag on <html>). Shares the cursor glow / magnetic / edge-
+// glow pointer effects. Motion is skipped under motionReduced().
+import { createEffect, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { motionReduced } from '../lib/motion'
+import { bindPointerFx } from './sceneEffects'
+
+const FLAKE_COUNT = 80
+
+function buildFlakes(animate: boolean): string {
+  const rnd = Math.random
+  let html = ''
+  for (let i = 0; i < FLAKE_COUNT; i++) {
+    const size = (2 + rnd() * 5).toFixed(1)
+    const op = (0.4 + rnd() * 0.6).toFixed(2)
+    const left = (rnd() * 100).toFixed(2)
+    const dur = (5 + rnd() * 9).toFixed(1)
+    const delay = (-rnd() * 14).toFixed(1)
+    const sway = (rnd() * 2 - 1) * (8 + rnd() * 14)
+    const blur = rnd() < 0.3 ? 'filter:blur(1px);' : ''
+    const anim = animate
+      ? `animation:snowFall ${dur}s linear ${delay}s infinite;`
+      : `top:${(rnd() * 100).toFixed(1)}%;`
+    html +=
+      `<span class="flake" style="left:${left}%;width:${size}px;height:${size}px;opacity:${op};` +
+      `--sway:${sway.toFixed(0)}px;${blur}${anim}"></span>`
+  }
+  return html
+}
+
+/**
+ * Falling-snow backdrop for the `snow` theme: snowflakes drift down, a snow bank
+ * gathers at the bottom, and cards get a frosted cap. Mount as {@link AppShell}'s
+ * `background`. Motion is skipped under `motionReduced()`.
+ */
+export function SnowScenery(): JSX.Element {
+  let root!: HTMLDivElement
+  let field!: HTMLDivElement
+
+  createEffect(() => {
+    field.innerHTML = buildFlakes(!motionReduced())
+  })
+
+  onMount(() => {
+    document.documentElement.dataset.scene = 'snow'
+    const cleanups: Array<() => void> = []
+    if (!motionReduced()) cleanups.push(bindPointerFx(root))
+    onCleanup(() => {
+      if (document.documentElement.dataset.scene === 'snow') delete document.documentElement.dataset.scene
+      cleanups.forEach((fn) => fn())
+    })
+  })
+
+  return (
+    <div id="snow" ref={root} aria-hidden="true">
+      <div class="snow-sky" />
+      <div ref={field} class="absolute inset-0" />
+      <div class="snow-bank" />
+      <div
+        id="cursorGlow"
+        style={{
+          position: 'absolute',
+          width: '520px',
+          height: '520px',
+          'border-radius': '50%',
+          background: 'radial-gradient(circle, hsl(var(--primary) / 0.1), transparent 70%)',
+          transform: 'translate(-50%,-50%)',
+          opacity: '0',
+          transition: 'opacity .4s ease',
+        }}
+      />
+    </div>
+  )
+}