@a4ui/core 0.11.1 → 0.12.0

package/src/commerce/ProductCard.tsx

@@ -0,0 +1,121 @@
+// Product summary card: square image with a corner ribbon (Sale/New/…), brand
+// eyebrow, title, category tag, optional rating, price, and an "Add to cart"
+// action. Frosted glass surface with the cursor-following edge glow.
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from '../ui/Button'
+import { Card } from '../ui/Card'
+import { Rating } from '../ui/Rating'
+import { PriceTag } from './PriceTag'
+
+/** Corner-ribbon colour intent. */
+export type ProductBadgeTone = 'sale' | 'new' | 'featured'
+
+const RIBBON_TONE: Record<ProductBadgeTone, string> = {
+  sale: 'bg-destructive text-destructive-foreground',
+  new: 'bg-primary text-primary-foreground',
+  featured: 'bg-accent text-accent-foreground',
+}
+
+export interface ProductCardProps {
+  title: string
+  price: number
+  compareAt?: number
+  image: string
+  /** Brand name — shown as a small eyebrow above the title. */
+  brand?: string
+  /** Category — shown as a small tag under the title. */
+  category?: string
+  /** Rating from 0-5; renders a readonly {@link Rating} when present. */
+  rating?: number
+  /** Corner-ribbon label over the image top-right corner, e.g. `'Sale'`, `'New'`. */
+  badge?: string
+  /** Ribbon colour. Inferred from `badge` text when omitted (sale/new → featured). */
+  badgeTone?: ProductBadgeTone
+  currency?: string
+  locale?: string
+  onAddToCart?: () => void
+  class?: string
+}
+
+/** Guess a ribbon tone from the badge text when one isn't given. */
+function inferTone(badge: string | undefined, tone: ProductBadgeTone | undefined): ProductBadgeTone {
+  if (tone) return tone
+  const b = (badge ?? '').toLowerCase()
+  if (/sale|off|%|deal/.test(b)) return 'sale'
+  if (/new/.test(b)) return 'new'
+  return 'featured'
+}
+
+/**
+ * Card summarizing a single product: image with a corner ribbon, brand, title,
+ * category, optional rating, price (with compare-at/discount), and an optional
+ * "Add to cart" button. Frosted glass with edge glow.
+ *
+ * @example
+ * ```tsx
+ * <ProductCard
+ *   title="Wireless Headphones"
+ *   brand="Acme"
+ *   category="Audio"
+ *   price={79.99}
+ *   compareAt={99.99}
+ *   image="/headphones.jpg"
+ *   rating={4}
+ *   badge="Sale"
+ *   badgeTone="sale"
+ *   onAddToCart={() => addToCart(sku)}
+ * />
+ * ```
+ */
+export function ProductCard(props: ProductCardProps): JSX.Element {
+  return (
+    <Card glass glow class={cn('flex h-full flex-col overflow-hidden p-4', props.class)}>
+      <div class="relative aspect-square overflow-hidden rounded-lg bg-muted">
+        <img src={props.image} alt={props.title} loading="lazy" class="h-full w-full object-cover" />
+        <Show when={props.badge}>
+          {/* Diagonal corner ribbon (clipped by the overflow-hidden image box). */}
+          <span
+            class={cn(
+              'absolute -right-9 top-3.5 w-32 rotate-45 py-1 text-center text-[11px] font-semibold uppercase tracking-wide shadow-md',
+              RIBBON_TONE[inferTone(props.badge, props.badgeTone)],
+            )}
+          >
+            {props.badge}
+          </span>
+        </Show>
+      </div>
+      {/* flex-1 + mt-auto on the button pins "Add to cart" to the bottom, so
+          cards of differing content height still line up in a grid row. */}
+      <div class="mt-3 flex flex-1 flex-col gap-1.5">
+        <Show when={props.brand}>
+          <span class="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+            {props.brand}
+          </span>
+        </Show>
+        <p class="line-clamp-1 font-medium text-foreground">{props.title}</p>
+        <Show when={props.category}>
+          <span class="w-fit rounded bg-muted px-1.5 py-0.5 text-[11px] text-muted-foreground">
+            {props.category}
+          </span>
+        </Show>
+        <Show when={props.rating !== undefined}>
+          <Rating value={props.rating as number} readonly max={5} />
+        </Show>
+        <PriceTag
+          amount={props.price}
+          compareAt={props.compareAt}
+          currency={props.currency}
+          locale={props.locale}
+        />
+        <Show when={props.onAddToCart}>
+          <Button class="mt-auto w-full" onClick={() => props.onAddToCart?.()}>
+            Add to cart
+          </Button>
+        </Show>
+      </div>
+    </Card>
+  )
+}

package/src/commerce/ProductGrid.tsx

@@ -0,0 +1,27 @@
+// Responsive grid wrapper for arranging ProductCards (or any children).
+import type { JSX, ParentProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface ProductGridProps extends ParentProps {
+  class?: string
+}
+
+/**
+ * Responsive grid wrapper: 2 columns by default, 3 at `sm`, 4 at `lg`.
+ * Typically used to lay out a list of {@link ProductCard}s.
+ *
+ * @example
+ * ```tsx
+ * <ProductGrid>
+ *   <For each={products()}>{(p) => <ProductCard {...p} />}</For>
+ * </ProductGrid>
+ * ```
+ */
+export function ProductGrid(props: ProductGridProps): JSX.Element {
+  return (
+    <div class={cn('grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4', props.class)}>
+      {props.children}
+    </div>
+  )
+}

package/src/commerce/QuantityStepper.tsx

@@ -0,0 +1,59 @@
+// Inline quantity stepper: a bordered "−"/value/"+" group, clamped to [min, max].
+import { Minus, Plus } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface QuantityStepperProps {
+  value: number
+  onChange: (value: number) => void
+  /** Minimum allowed value. Defaults to `0`. */
+  min?: number
+  /** Maximum allowed value. Defaults to `Number.MAX_SAFE_INTEGER`. */
+  max?: number
+  disabled?: boolean
+  class?: string
+}
+
+/**
+ * Bordered "−"/value/"+" control for adjusting an integer quantity, clamped to
+ * `[min, max]`.
+ *
+ * @example
+ * ```tsx
+ * <QuantityStepper value={qty()} onChange={setQty} min={1} max={10} />
+ * ```
+ */
+export function QuantityStepper(props: QuantityStepperProps): JSX.Element {
+  const min = () => props.min ?? 0
+  const max = () => props.max ?? Number.MAX_SAFE_INTEGER
+
+  const clamp = (n: number) => Math.min(max(), Math.max(min(), n))
+
+  const decrement = () => props.onChange(clamp(props.value - 1))
+  const increment = () => props.onChange(clamp(props.value + 1))
+
+  return (
+    <div class={cn('inline-flex items-stretch rounded-md border border-input', props.class)}>
+      <button
+        type="button"
+        aria-label="Decrease quantity"
+        class="grid h-8 w-8 place-items-center hover:bg-muted disabled:opacity-40"
+        disabled={props.disabled || props.value <= min()}
+        onClick={decrement}
+      >
+        <Minus class="h-4 w-4" />
+      </button>
+      <span class="grid min-w-[2.5rem] place-items-center tabular-nums">{props.value}</span>
+      <button
+        type="button"
+        aria-label="Increase quantity"
+        class="grid h-8 w-8 place-items-center hover:bg-muted disabled:opacity-40"
+        disabled={props.disabled || props.value >= max()}
+        onClick={increment}
+      >
+        <Plus class="h-4 w-4" />
+      </button>
+    </div>
+  )
+}

package/src/commerce/index.ts

@@ -0,0 +1,10 @@
+// A4ui commerce components — storefront/cart building blocks, kept in their own
+// entry (`@a4ui/core/commerce`) so the base package stays lean. Import styles the
+// same way as the core (`@a4ui/core/styles.css` or the Tailwind preset).
+export { PriceTag, type PriceTagProps } from './PriceTag'
+export { QuantityStepper, type QuantityStepperProps } from './QuantityStepper'
+export { ProductCard, type ProductCardProps, type ProductBadgeTone } from './ProductCard'
+export { ProductGrid, type ProductGridProps } from './ProductGrid'
+export { CartLine, type CartLineProps } from './CartLine'
+export { CartSummary, type CartSummaryProps, type CartSummaryItem } from './CartSummary'
+export { FilterGroup, type FilterGroupProps, type FacetOption } from './FilterGroup'

package/src/elements.tsx

@@ -0,0 +1,167 @@
+// Web Components entry (`@a4ui/core/elements`) — a curated subset of A4ui's
+// presentational components registered as framework-agnostic custom elements so
+// they can be used from React/Next.js, Vue, Svelte, or plain HTML.
+//
+// Design notes:
+// - Each element renders in LIGHT DOM (noShadowDOM) so the global stylesheet
+//   (`@a4ui/core/elements.css`) and CSS theme variables apply normally — Shadow
+//   DOM would isolate the Tailwind utility classes the components rely on.
+// - Props map to attributes/properties (solid-element coerces by the declared
+//   default's type: number/boolean/string). Text content is taken from a `label`
+//   or `text` attribute, falling back to the element's initial text.
+// - Only leaf, primitive-prop components are wrapped. Rich/interactive/portalled
+//   components (Modal, Combobox, DataGrid, …) remain SolidJS-only — see the docs.
+//
+// This bundle is self-contained (solid-js is bundled in), so non-Solid apps need
+// no Solid toolchain: `import '@a4ui/core/elements'` once, then use the tags.
+import { customElement, noShadowDOM } from 'solid-element'
+import type { JSX } from 'solid-js'
+
+import { Alert, type AlertTone } from './ui/Alert'
+import { Avatar } from './ui/Avatar'
+import { Badge, type BadgeTone } from './ui/Badge'
+import { Button, type ButtonVariant } from './ui/Button'
+import { Clock } from './ui/Clock'
+import { Countdown } from './ui/Countdown'
+import { Kbd } from './ui/Kbd'
+import { Meter } from './ui/Meter'
+import { Progress } from './ui/Progress'
+import { Rating } from './ui/Rating'
+import { RingProgress } from './ui/RingProgress'
+import { Separator } from './ui/Separator'
+import { Spinner } from './ui/Spinner'
+import { Stat, type StatTone } from './ui/Stat'
+
+/** The initial text an author put between the tags, before Solid renders over it. */
+function initialText(element: unknown): string {
+  return ((element as HTMLElement).textContent ?? '').trim()
+}
+
+/** Register every A4ui custom element. Import for its side effect. */
+export function defineA4uiElements(): void {
+  customElement(
+    'a4-button',
+    { variant: 'primary', disabled: false, type: 'button', label: '' },
+    (props, { element }): JSX.Element => {
+      noShadowDOM()
+      const text = props.label || initialText(element)
+      return (
+        <Button
+          variant={props.variant as ButtonVariant}
+          disabled={props.disabled}
+          type={props.type as 'button' | 'submit' | 'reset'}
+        >
+          {text}
+        </Button>
+      )
+    },
+  )
+
+  customElement('a4-badge', { tone: 'neutral', label: '' }, (props, { element }): JSX.Element => {
+    noShadowDOM()
+    return <Badge tone={props.tone as BadgeTone}>{props.label || initialText(element)}</Badge>
+  })
+
+  customElement(
+    // `heading`, not `title` — the latter is a global HTML attribute and would
+    // clash with the element's native `title` (tooltip) property.
+    'a4-alert',
+    { tone: 'info', heading: '', text: '' },
+    (props, { element }): JSX.Element => {
+      noShadowDOM()
+      return (
+        <Alert tone={props.tone as AlertTone} title={props.heading || undefined}>
+          {props.text || initialText(element)}
+        </Alert>
+      )
+    },
+  )
+
+  customElement('a4-spinner', { label: 'Loading' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Spinner label={props.label} />
+  })
+
+  customElement('a4-avatar', { src: '', alt: '', fallback: '' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Avatar src={props.src || undefined} alt={props.alt} fallback={props.fallback || ''} />
+  })
+
+  customElement('a4-progress', { value: 0, max: 100, label: '' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Progress value={props.value} max={props.max} label={props.label || undefined} />
+  })
+
+  customElement('a4-meter', { value: 0, max: 100, label: '' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Meter value={props.value} max={props.max} label={props.label || undefined} />
+  })
+
+  customElement('a4-ring-progress', { value: 0, size: 96, thickness: 8, label: '' }, (props): JSX.Element => {
+    noShadowDOM()
+    return (
+      <RingProgress
+        value={props.value}
+        size={props.size}
+        thickness={props.thickness}
+        label={props.label || undefined}
+      />
+    )
+  })
+
+  customElement('a4-stat', { label: '', value: 0, tone: 'neutral' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Stat label={props.label} value={props.value} tone={props.tone as StatTone} />
+  })
+
+  customElement('a4-kbd', { label: '' }, (props, { element }): JSX.Element => {
+    noShadowDOM()
+    return <Kbd>{props.label || initialText(element)}</Kbd>
+  })
+
+  customElement('a4-separator', { orientation: 'horizontal' }, (props): JSX.Element => {
+    noShadowDOM()
+    return <Separator orientation={props.orientation as 'horizontal' | 'vertical'} />
+  })
+
+  customElement('a4-rating', { value: 0, max: 5, readonly: false }, (props, { element }): JSX.Element => {
+    noShadowDOM()
+    return (
+      <Rating
+        value={props.value}
+        max={props.max}
+        readonly={props.readonly}
+        onChange={(v) =>
+          (element as unknown as HTMLElement).dispatchEvent(new CustomEvent('change', { detail: v }))
+        }
+      />
+    )
+  })
+
+  customElement('a4-countdown', { to: '' }, (props): JSX.Element => {
+    noShadowDOM()
+    // eslint-disable-next-line solid/reactivity -- read the `to` attribute once to fix the target
+    const target = props.to ? new Date(props.to) : new Date(Date.now() + 86_400_000)
+    return <Countdown to={target} />
+  })
+
+  customElement(
+    'a4-clock',
+    { variant: 'digital', seconds: true, hour12: false, timezone: '', size: 160 },
+    (props): JSX.Element => {
+      noShadowDOM()
+      return (
+        <Clock
+          variant={props.variant as 'digital' | 'analog'}
+          seconds={props.seconds}
+          hour12={props.hour12}
+          timeZone={props.timezone || undefined}
+          size={props.size}
+        />
+      )
+    },
+  )
+}
+
+// Registering on import is the ergonomic default for `import '@a4ui/core/elements'`.
+defineA4uiElements()

package/src/index.ts

@@ -0,0 +1,166 @@
+// 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.12.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'
+
+// 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>
+  )
+}