{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "components-pinned-list",
  "type": "registry:component",
  "title": "Pinned list",
  "description": "Headers that stay pinned while rows scroll under them",
  "author": "sudo-kw <https://github.com/sudo-kw>",
  "dependencies": [
    "@gpuix/native@0.11.0",
    "@gpuix/react@0.11.0",
    "effect@4.1.2",
    "react@^19.2.4"
  ],
  "registryDependencies": [
    "https://gpuixui.sudokw.com/gpuix-primitives.json",
    "https://gpuixui.sudokw.com/gpuix-tokens.json",
    "https://gpuixui.sudokw.com/gpuix-tw.json"
  ],
  "files": [
    {
      "path": "packages/components/src/internal/measure.ts",
      "target": "@ui/gpuixui/components/internal/measure.ts",
      "type": "registry:lib",
      "content": "import type { EventPayload } from \"@gpuix/react\";\nimport * as Option from \"effect/Option\";\n\nexport interface MeasuredBox {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n}\n\nconst measurable = (value: number | undefined): Option.Option<number> =>\n  Option.filter(Option.fromNullishOr(value), Number.isFinite);\n\nexport const measuredBox = (event: EventPayload): Option.Option<MeasuredBox> =>\n  Option.all({\n    x: measurable(event.x),\n    y: measurable(event.y),\n    width: measurable(event.width),\n    height: measurable(event.height),\n  });\n\nexport const measuredHeight = (event: EventPayload): Option.Option<number> =>\n  measurable(event.height);\n\nexport interface MeasuredPoint {\n  readonly x: number;\n  readonly y: number;\n}\n\nexport const measuredPoint = (\n  event: EventPayload,\n): Option.Option<MeasuredPoint> =>\n  Option.all({\n    x: measurable(event.x),\n    y: measurable(event.y),\n  });\n"
    },
    {
      "path": "packages/components/src/internal/recipe.ts",
      "target": "@ui/gpuixui/components/internal/recipe.ts",
      "type": "registry:lib",
      "content": "import type { StyleDesc } from \"@gpuix/react\";\nimport { createRecipeCache } from \"../../tw/index.js\";\nimport type { Theme } from \"./theme.js\";\n\nexport const recipeStyle: (recipe: string, theme: Theme) => StyleDesc =\n  createRecipeCache(512);\n"
    },
    {
      "path": "packages/components/src/internal/scroll-surface.tsx",
      "target": "@ui/gpuixui/components/internal/scroll-surface.tsx",
      "type": "registry:component",
      "content": "/** @jsxImportSource @gpuix/react */\nimport type { EventPayload, StyleDesc } from \"@gpuix/react\";\nimport { mergeStyles } from \"@gpuix/react/floating\";\nimport { ScrollArea } from \"../../primitives/scroll-area.js\";\nimport { cn } from \"../../tw/index.js\";\nimport { useState, type ReactNode } from \"react\";\nimport { scrollMetrics, type ScrollMetrics } from \"../scroll/metrics.js\";\nimport { recipeStyle } from \"./recipe.js\";\nimport { useTheme } from \"./theme.js\";\n\ninterface ScrollReading {\n  readonly metrics: ScrollMetrics;\n  readonly noteScroll: (event: EventPayload) => void;\n  readonly noteViewport: (event: EventPayload) => void;\n  readonly noteContent: (event: EventPayload) => void;\n}\n\nconst useScrollReading = (): ScrollReading => {\n  const [offsetY, setOffsetY] = useState(0);\n  const [viewportHeight, setViewportHeight] = useState(0);\n  const [contentHeight, setContentHeight] = useState(0);\n  return {\n    metrics: scrollMetrics({ offsetY, viewportHeight, contentHeight }),\n    noteScroll: (event) => setOffsetY(event.scrollY ?? 0),\n    noteViewport: (event) => setViewportHeight(event.height ?? 0),\n    noteContent: (event) => setContentHeight(event.height ?? 0),\n  };\n};\n\nexport interface ScrollSurfaceProps {\n  readonly children?: ReactNode;\n\n  readonly chrome?: (metrics: ScrollMetrics) => ReactNode;\n\n  readonly testId?: string;\n\n  readonly label?: string;\n\n  readonly onScroll?: (event: EventPayload) => void;\n\n  readonly onScrollChange?: (event: EventPayload) => void;\n\n  readonly onLayout?: (event: EventPayload) => void;\n\n  readonly className?: string;\n\n  readonly style?: StyleDesc;\n}\n\nexport const ScrollSurface = ({\n  children,\n  chrome,\n  testId,\n  label,\n  onScroll,\n  onScrollChange,\n  onLayout,\n  className,\n  style,\n}: ScrollSurfaceProps) => {\n  const theme = useTheme();\n  const reading = useScrollReading();\n\n  return (\n    <div\n      style={mergeStyles(\n        recipeStyle(cn(\"relative flex flex-col min-h-0\", className), theme),\n        style,\n      )}\n    >\n      <ScrollArea\n        axis=\"vertical\"\n        viewportTestId={testId}\n        label={label}\n        scrollbarColor={theme.colors.scrollbar}\n        onScroll={onScroll}\n        onScrollChange={(event) => {\n          reading.noteScroll(event);\n          onScrollChange?.(event);\n        }}\n        onLayout={(event) => {\n          reading.noteViewport(event);\n          onLayout?.(event);\n        }}\n        style={{ flexGrow: 1, flexShrink: 1, minHeight: 0 }}\n      >\n        <div onLayout={reading.noteContent} style={{ flexShrink: 0 }}>\n          {children}\n        </div>\n      </ScrollArea>\n      {chrome === undefined ? null : chrome(reading.metrics)}\n    </div>\n  );\n};\n"
    },
    {
      "path": "packages/components/src/internal/text.ts",
      "target": "@ui/gpuixui/components/internal/text.ts",
      "type": "registry:lib",
      "content": "import { pipe } from \"effect\";\nimport * as Option from \"effect/Option\";\nimport * as Str from \"effect/String\";\n\nexport const textOf = (value: unknown): string =>\n  typeof value === \"string\" ? value : \"\";\n\nexport const nameOf = (value: unknown): string | undefined =>\n  pipe(\n    Option.some(textOf(value)),\n    Option.map(Str.trim),\n    Option.filter(Str.isNonEmpty),\n    Option.getOrUndefined,\n  );\n"
    },
    {
      "path": "packages/components/src/internal/theme.ts",
      "target": "@ui/gpuixui/components/internal/theme.ts",
      "type": "registry:lib",
      "content": "import type { StyleDesc } from \"@gpuix/react\";\nimport * as Schema from \"effect/Schema\";\nimport {\n  alpha,\n  avatarPixels,\n  avatarSize,\n  brandTextOn,\n  controlFocusRing,\n  controlHeight,\n  controlPaddingX,\n  currentPlatform,\n  darkTheme,\n  disabledAction,\n  disabledOpacity,\n  elevationShadow,\n  filledHover,\n  filledPressed,\n  findHighlight,\n  focusRing,\n  keyboardFocusRing,\n  lightTheme,\n  nativeTextTheme,\n  pointerWash,\n  selectionOn,\n  statusTone,\n  syntaxColors,\n  targetSize,\n  textStyle,\n  type BoxShadow,\n  type ElevationLevel,\n  type FindHighlightSource,\n  type NativeTextFill,\n  type PlatformName,\n  type PointerWashSurface,\n  type StatusTone,\n  type SyntaxColors,\n  type SyntaxRole,\n  type TextRole,\n  type Theme,\n  type ThemeColors,\n} from \"../../tokens/index.js\";\n\nexport {\n  alpha,\n  avatarPixels,\n  avatarSize,\n  controlFocusRing,\n  controlHeight,\n  controlPaddingX,\n  currentPlatform,\n  darkTheme,\n  disabledAction,\n  disabledOpacity,\n  elevationShadow,\n  filledHover,\n  filledPressed,\n  findHighlight,\n  focusRing,\n  keyboardFocusRing,\n  lightTheme,\n  nativeTextTheme,\n  statusTone,\n  syntaxColors,\n  targetSize,\n  textStyle,\n};\nexport type {\n  BoxShadow,\n  ElevationLevel,\n  FindHighlightSource,\n  NativeTextFill,\n  PlatformName,\n  StatusTone,\n  SyntaxColors,\n  SyntaxRole,\n  TextRole,\n  Theme,\n};\nexport { ThemeProvider, useTheme } from \"../../tokens/react.js\";\n\nexport const keyboardRing = (theme: Theme, invalid = false): StyleDesc =>\n  controlFocusRing(theme, { invalid }) ?? {};\n\nexport interface ControlRingState {\n  readonly disabled?: boolean;\n\n  readonly invalid?: boolean;\n}\n\nexport const controlRing = (\n  theme: Theme,\n  state: ControlRingState = {},\n): StyleDesc => controlFocusRing(theme, state) ?? {};\n\nexport const pressWash = (theme: Theme, replaced: PointerWashSurface): string =>\n  pointerWash(theme, \"active\", replaced) ?? theme.colors.active;\n\nexport const selectionWash = (theme: Theme): StyleDesc => ({\n  selectionColor: theme.colors.selection,\n});\n\nexport const keepContent: StyleDesc = { keyboardFocusDim: false };\n\nexport const disabledFade = (\n  disabled: boolean,\n): { readonly opacity: number } | undefined =>\n  disabled ? { opacity: disabledOpacity } : undefined;\n\nconst Tones = Schema.Literals([\"info\", \"success\", \"warning\", \"danger\"]);\n\nexport type Tone = typeof Tones.Type;\n\nexport const toneOf = (value: unknown): Tone =>\n  Schema.is(Tones)(value) ? value : \"info\";\n\nexport interface ToneStyle {\n  readonly fg: string;\n  readonly bg: string;\n  readonly border: string;\n}\n\nconst TOKEN_TONE: Readonly<Record<Tone, StatusTone>> = {\n  info: \"info\",\n  success: \"success\",\n  warning: \"warning\",\n  danger: \"destructive\",\n};\n\nexport const tone = (theme: Theme, value: Tone): ToneStyle => {\n  const { background, border, foreground } = statusTone(\n    theme,\n    TOKEN_TONE[value],\n  );\n  return { bg: background, border, fg: foreground };\n};\n\nconst softRoles: Readonly<Record<Tone, keyof ThemeColors>> = {\n  info: \"infoSoft\",\n  success: \"successSoft\",\n  warning: \"warningSoft\",\n  danger: \"destructiveSoft\",\n};\n\nexport const messageLink = (theme: Theme, value: Tone): string =>\n  brandTextOn(theme, softRoles[value]);\n\nexport const messageSelection = (theme: Theme, value: Tone): string =>\n  selectionOn(theme, softRoles[value]);\n\nexport const toneSurface = (theme: Theme, value: Tone): StyleDesc => {\n  const { bg, border, fg } = tone(theme, value);\n  return {\n    backgroundColor: bg,\n    color: fg,\n    borderWidth: theme.borderWidth.thin,\n    borderColor: border,\n  };\n};\n"
    },
    {
      "path": "packages/components/src/pinned-list.tsx",
      "target": "@ui/gpuixui/components/pinned-list.tsx",
      "type": "registry:component",
      "content": "/** @jsxImportSource @gpuix/react */\nimport type { EventPayload, StyleDesc } from \"@gpuix/react\";\nimport { cn } from \"../tw/index.js\";\nimport * as Arr from \"effect/Array\";\nimport * as HashMap from \"effect/HashMap\";\nimport * as Option from \"effect/Option\";\nimport { useState } from \"react\";\nimport { measuredHeight } from \"./internal/measure.js\";\nimport { ScrollSurface } from \"./internal/scroll-surface.js\";\nimport { nameOf } from \"./internal/text.js\";\nimport { textStyle, useTheme } from \"./internal/theme.js\";\nimport {\n  headerHeightOf,\n  pinnedHeaders,\n  sectionsOf,\n  type PinnedHeaderFrame,\n  type PinnedListSection,\n} from \"./pinned-list/logic.js\";\n\nexport type { PinnedListSection } from \"./pinned-list/logic.js\";\n\nexport interface PinnedListProps {\n  readonly sections: ReadonlyArray<PinnedListSection>;\n\n  readonly testId?: string;\n\n  readonly \"aria-label\"?: string;\n\n  readonly style?: StyleDesc;\n\n  readonly onScrollChange?: (event: EventPayload) => void;\n\n  readonly onLayout?: (event: EventPayload) => void;\n\n  readonly headerHeight?: number;\n\n  readonly surfaceColor?: string;\n\n  readonly className?: string;\n}\n\nexport const PinnedList = ({\n  sections: storedSections,\n  headerHeight,\n  surfaceColor,\n  className,\n  testId,\n  \"aria-label\": label,\n  style,\n  onScrollChange,\n  onLayout,\n}: PinnedListProps) => {\n  const theme = useTheme();\n  const sections = sectionsOf(storedSections);\n  const header = headerHeightOf(Option.fromNullishOr(headerHeight));\n  const surface = surfaceColor ?? theme.colors.background;\n\n  const [heights, setHeights] = useState<HashMap.HashMap<string, number>>(\n    HashMap.empty(),\n  );\n\n  const noteHeight =\n    (title: string) =>\n    (event: EventPayload): void => {\n      Option.match(measuredHeight(event), {\n        onNone: () => undefined,\n        onSome: (height) =>\n          setHeights((current) => HashMap.set(current, title, height)),\n      });\n    };\n\n  const bands = Arr.map(sections, (section) =>\n    Option.getOrElse(HashMap.get(heights, section.title), () => 0),\n  );\n\n  const headerLayer = (frames: ReadonlyArray<PinnedHeaderFrame>) => (\n    <div\n      testId=\"pinned-layer\"\n      style={{\n        position: \"absolute\",\n        top: 0,\n        right: 0,\n        bottom: 0,\n        left: 0,\n        overflow: \"hidden\",\n\n        pointerEvents: \"none\",\n      }}\n    >\n      {Arr.map(frames, (frame) =>\n        frame.visible ? (\n          <div\n            key={sections[frame.index]?.title ?? frame.index}\n            testId={`pinned-header-${frame.index}`}\n            role=\"presentation\"\n            style={{\n              position: \"absolute\",\n              top: frame.top,\n              left: 0,\n              right: 0,\n              height: header,\n              display: \"flex\",\n              flexDirection: \"row\",\n              alignItems: \"center\",\n              paddingLeft: theme.spacing.md,\n              paddingRight: theme.spacing.md,\n              backgroundColor: surface,\n\n              pointerEvents: \"none\",\n              ...(frame.pinned\n                ? {\n                    borderBottomWidth: theme.borderWidth.thin,\n                    borderColor: theme.colors.border,\n                  }\n                : {}),\n            }}\n          >\n            <text\n              role=\"presentation\"\n              style={{\n                ...textStyle(theme, \"bodyStrong\"),\n                color: theme.colors.foreground,\n                pointerEvents: \"none\",\n              }}\n            >\n              {sections[frame.index]?.title ?? \"\"}\n            </text>\n          </div>\n        ) : null,\n      )}\n    </div>\n  );\n\n  return (\n    <ScrollSurface\n      testId={testId}\n      label={nameOf(label)}\n      style={style}\n      onScrollChange={onScrollChange}\n      onLayout={onLayout}\n      className={cn(\"relative\", className)}\n      chrome={(metrics) =>\n        headerLayer(pinnedHeaders(bands, metrics.offsetY, header))\n      }\n    >\n      {sections.map((section, index) => (\n        <div\n          key={section.title}\n          testId={`pinned-section-${index}`}\n          role=\"group\"\n          aria-label={section.title}\n          onLayout={noteHeight(section.title)}\n          style={{\n            position: \"relative\",\n            display: \"flex\",\n            flexDirection: \"column\",\n          }}\n        >\n          {}\n          <div\n            testId={`pinned-space-${index}`}\n            style={{ height: header, flexShrink: 0 }}\n          />\n          <div>{section.children}</div>\n        </div>\n      ))}\n    </ScrollSurface>\n  );\n};\n\nexport const pinnedListMeta = {\n  name: \"Pinned list\",\n  tier: 5,\n  status: \"done\",\n  gpuixSupport: \"partial\",\n  limitations: [\n    \"the runtime paints no position: sticky, so a header is a layer repositioned from the measured offset rather than a sticky child\",\n    \"the region is vertical only, and an arrow key moves it by the primitives' row height\",\n    \"a header is one line and reserves headerHeight: a wrapped title is clipped rather than made taller\",\n    \"sections are keyed by title, and each measured height is kept with its title — so reordering the sections keeps every header with its own rows; a section that has not reported yet counts as 0 until its layout arrives\",\n  ],\n  docs: \"docs/pinned-list.mdx\",\n  example: \"examples/pinned-list.example.tsx\",\n  testFile: \"src/behaviour/pinned-list.test.tsx\",\n} as const;\n"
    },
    {
      "path": "packages/components/src/pinned-list/logic.ts",
      "target": "@ui/gpuixui/components/pinned-list/logic.ts",
      "type": "registry:lib",
      "content": "import * as Arr from \"effect/Array\";\nimport * as Option from \"effect/Option\";\nimport type { ReactNode } from \"react\";\n\nexport interface PinnedListSection {\n  readonly title: string;\n  readonly children?: ReactNode;\n}\n\nconst isSection = (entry: unknown): entry is PinnedListSection => {\n  if (typeof entry !== \"object\" || entry === null || !(\"title\" in entry)) {\n    return false;\n  }\n  const title = entry.title;\n  return typeof title === \"string\" && title.trim().length > 0;\n};\n\nexport const sectionsOf = (\n  value: ReadonlyArray<PinnedListSection> | null | undefined,\n): ReadonlyArray<PinnedListSection> => {\n  const list = Option.getOrElse(\n    Option.filter(Option.fromNullishOr(value), (entries): boolean =>\n      Arr.isArray(entries),\n    ),\n    () => [],\n  );\n  return Arr.filter(list, isSection);\n};\n\nexport interface PinnedSectionHeight {\n  readonly top: number;\n  readonly height: number;\n}\n\nexport interface PinnedHeaderFrame {\n  readonly index: number;\n\n  readonly top: number;\n\n  readonly pinned: boolean;\n\n  readonly visible: boolean;\n}\n\nexport const pinnedHeaderHeight = 32;\n\nexport const headerHeightOf = (height: Option.Option<number>): number =>\n  Option.getOrElse(\n    Option.map(\n      Option.filter(height, (value) => Number.isFinite(value) && value > 0),\n      Math.round,\n    ),\n    () => pinnedHeaderHeight,\n  );\n\nconst measurable = (height: number): number =>\n  Number.isFinite(height) && height > 0 ? height : 0;\n\nconst tenth = (value: number): number => Math.round(value * 10) / 10;\n\nexport const sectionBands = (\n  heights: ReadonlyArray<number>,\n): ReadonlyArray<PinnedSectionHeight> =>\n  Arr.mapAccum(heights, 0, (top, height) => {\n    const safe = measurable(height);\n    return [top + safe, { top, height: safe }];\n  })[1];\n\nexport const pinnedHeaders = (\n  heights: ReadonlyArray<number>,\n  offsetY: number,\n  headerHeight: number,\n): ReadonlyArray<PinnedHeaderFrame> => {\n  const header = headerHeightOf(Option.some(headerHeight));\n  const offset = Number.isFinite(offsetY) ? Math.min(0, offsetY) : 0;\n  return Arr.map(sectionBands(heights), ({ top, height }, index) => {\n    const natural = top + offset;\n    const bottom = top + height + offset;\n    const painted = Math.min(Math.max(natural, 0), bottom - header);\n    return {\n      index,\n      top: tenth(painted),\n      pinned: natural < 0,\n      visible: height > 0 && painted + header > 0,\n    };\n  });\n};\n"
    },
    {
      "path": "packages/components/src/scroll/metrics.ts",
      "target": "@ui/gpuixui/components/scroll/metrics.ts",
      "type": "registry:lib",
      "content": "import type { LinearGradientBackground } from \"@gpuix/react\";\nimport * as Option from \"effect/Option\";\n\nexport interface ScrollSample {\n  readonly offsetY: number;\n\n  readonly viewportHeight: number;\n\n  readonly contentHeight: number;\n}\n\nexport interface ScrollMetrics {\n  readonly progress: number;\n\n  readonly offsetY: number;\n\n  readonly scrollable: boolean;\n\n  readonly atStart: boolean;\n\n  readonly atEnd: boolean;\n}\n\nexport type ScrollEdge = \"top\" | \"bottom\";\n\nconst finite = (value: number, fallback: number): number =>\n  Number.isFinite(value) ? value : fallback;\n\nexport const scrollMetrics = (sample: ScrollSample): ScrollMetrics => {\n  const viewport = Math.max(0, finite(sample.viewportHeight, 0));\n  const content = Math.max(0, finite(sample.contentHeight, 0));\n  const offset = Math.min(0, finite(sample.offsetY, 0));\n  const overflow = Math.max(0, content - viewport);\n\n  const scrollable = overflow > 1;\n  const travelled = scrollable ? Math.max(0, Math.min(overflow, -offset)) : 0;\n\n  return {\n    progress: scrollable ? travelled / overflow : 0,\n\n    offsetY: travelled === 0 ? 0 : -travelled,\n    scrollable,\n    atStart: !scrollable || -offset <= 1,\n    atEnd: !scrollable || -offset >= overflow - 1,\n  };\n};\n\nexport interface EdgeFadeColors {\n  readonly solid: string;\n\n  readonly clear: string;\n}\n\nexport const edgeGradient = (\n  edge: ScrollEdge,\n  colors: EdgeFadeColors,\n): LinearGradientBackground => ({\n  type: \"linear-gradient\",\n  angle: edge === \"top\" ? 180 : 0,\n  stops: [\n    { color: colors.solid, position: 0 },\n    { color: colors.clear, position: 1 },\n  ],\n});\n\nexport const scrollSize = (\n  value: Option.Option<number>,\n  fallback: number,\n): number =>\n  Option.match(value, {\n    onNone: () => fallback,\n    onSome: (size) =>\n      Number.isFinite(size) && size > 0 ? Math.round(size) : fallback,\n  });\n"
    }
  ],
  "docs": "[Pinned list](https://gpuixui.sudokw.com/components/pinned-list) — These are GPUix native components: the files render through GPUix's reconciler against `@gpuix/react`, not the DOM, and need the per-platform `@gpuix/native` binding. The CLI installs the `@gpuixui/*` runtime the components import as registry items, so the copied tree resolves on its own; wrap it in `ThemeProvider` before it renders.",
  "meta": {
    "url": "/components/pinned-list",
    "kind": "component",
    "runtime": "gpuix",
    "registry": "gpuixui"
  }
}