@multicomma/arkcn 0.1.2 → 0.1.3

package/registry/items/virtual-list.json

@@ -11,6 +11,219 @@
     "VirtualListViewport",
     "useVirtualList"
   ],
+  "parts": [
+    {
+      "name": "VirtualList",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "Content rendered inside the part.",
+          "from": "arkcn"
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "required": true,
+          "description": "Total number of rows.",
+          "from": "arkcn"
+        },
+        {
+          "name": "estimateSize",
+          "type": "number | ((index: number) => number)",
+          "required": false,
+          "default": "36",
+          "description": "Row height before measurement (a number, or per index).",
+          "from": "arkcn"
+        },
+        {
+          "name": "gap",
+          "type": "number",
+          "required": false,
+          "default": "0",
+          "description": "Space between rows in px.",
+          "from": "arkcn"
+        },
+        {
+          "name": "getItemKey",
+          "type": "((index: number) => Key)",
+          "required": false,
+          "default": "(index) => index",
+          "description": "Stable React key for a row index.",
+          "from": "arkcn"
+        },
+        {
+          "name": "onRangeChange",
+          "type": "((range: { start: number; end: number; } | null) => void)",
+          "required": false,
+          "description": "Fires when the rendered window changes.",
+          "from": "arkcn"
+        },
+        {
+          "name": "overscan",
+          "type": "number",
+          "required": false,
+          "default": "6",
+          "description": "Rows rendered beyond the visible window on each side.",
+          "from": "arkcn"
+        },
+        {
+          "name": "paddingEnd",
+          "type": "number",
+          "required": false,
+          "default": "0",
+          "description": "Space after the last row in px.",
+          "from": "arkcn"
+        },
+        {
+          "name": "paddingStart",
+          "type": "number",
+          "required": false,
+          "default": "0",
+          "description": "Space before the first row in px.",
+          "from": "arkcn"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "VirtualListContent",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "VirtualListEmpty",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "VirtualListItem",
+      "props": [
+        {
+          "name": "index",
+          "type": "number",
+          "required": true,
+          "description": "Position of the item in its list.",
+          "from": "arkcn"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    },
+    {
+      "name": "VirtualListItems",
+      "props": [
+        {
+          "name": "children",
+          "type": "(item: VirtualItem) => ReactNode",
+          "required": true,
+          "description": "Content rendered inside the part.",
+          "from": "arkcn"
+        }
+      ]
+    },
+    {
+      "name": "VirtualListViewport",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content rendered inside the part.",
+          "from": "@types/react"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Extra classes merged into the part's own classes with `cn`.",
+          "from": "@types/react"
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "required": false,
+          "description": "Inline styles applied to the rendered element.",
+          "from": "@types/react"
+        }
+      ]
+    }
+  ],
   "dependencies": {},
   "registryDependencies": [
     "lib/utils"
@@ -18,7 +231,7 @@
   "files": [
     {
       "path": "components/ui/virtual-list.tsx",
-      "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"@/lib/utils\"\n\n/* -------------------------------- context -------------------------------- */\n\ntype VirtualItem = {\n  index: number\n  key: React.Key\n  /** Offset from the top of the content, in px. */\n  start: number\n  size: number\n  end: number\n  /** False until the row's real height has been measured. */\n  measured: boolean\n}\n\ntype ScrollAlign = \"auto\" | \"start\" | \"center\" | \"end\"\n\ntype VirtualListContextValue = {\n  count: number\n  items: VirtualItem[]\n  totalSize: number\n  /** First and last rendered index (overscan included), or null when empty. */\n  range: { start: number; end: number } | null\n  measure: (index: number, size: number) => void\n  scrollToIndex: (index: number, options?: { align?: ScrollAlign; behavior?: ScrollBehavior }) => void\n  scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void\n  viewportRef: React.RefObject<HTMLDivElement | null>\n  getItemKey: (index: number) => React.Key\n}\n\nconst VirtualListContext = React.createContext<VirtualListContextValue | null>(null)\n\nfunction useVirtualList() {\n  const ctx = React.useContext(VirtualListContext)\n  if (!ctx) throw new Error(\"VirtualList parts must be used inside <VirtualList>\")\n  return ctx\n}\n\n/* -------------------------------- helpers -------------------------------- */\n\n/** Largest index whose start is <= offset. */\nfunction findIndex(starts: Float64Array, count: number, offset: number) {\n  let lo = 0\n  let hi = count - 1\n  while (lo < hi) {\n    const mid = (lo + hi + 1) >> 1\n    if (starts[mid] <= offset) lo = mid\n    else hi = mid - 1\n  }\n  return lo\n}\n\n/* ---------------------------------- root --------------------------------- */\n\ntype VirtualListProps = Omit<React.ComponentProps<\"div\">, \"children\"> & {\n  count: number\n  /** Row height before measurement (a number, or per index). */\n  estimateSize?: number | ((index: number) => number)\n  /** Rows rendered beyond the visible window on each side. */\n  overscan?: number\n  gap?: number\n  paddingStart?: number\n  paddingEnd?: number\n  getItemKey?: (index: number) => React.Key\n  /** Fires when the rendered window changes. */\n  onRangeChange?: (range: { start: number; end: number } | null) => void\n  children: React.ReactNode\n}\n\nfunction VirtualList({\n  count,\n  estimateSize = 36,\n  overscan = 6,\n  gap = 0,\n  paddingStart = 0,\n  paddingEnd = 0,\n  getItemKey = (index) => index,\n  onRangeChange,\n  className,\n  children,\n  ...props\n}: VirtualListProps) {\n  const viewportRef = React.useRef<HTMLDivElement | null>(null)\n  const sizes = React.useRef(new Map<number, number>())\n  const [version, setVersion] = React.useState(0)\n  const [scrollTop, setScrollTop] = React.useState(0)\n  const [viewportSize, setViewportSize] = React.useState(0)\n  const estimate = React.useCallback(\n    (index: number) => (typeof estimateSize === \"function\" ? estimateSize(index) : estimateSize),\n    [estimateSize]\n  )\n\n  // Prefix sums of row starts; recomputed when a measurement or the count changes.\n  const layout = React.useMemo(() => {\n    const starts = new Float64Array(count)\n    let offset = paddingStart\n    for (let i = 0; i < count; i++) {\n      starts[i] = offset\n      offset += (sizes.current.get(i) ?? estimate(i)) + (i < count - 1 ? gap : 0)\n    }\n    return { starts, totalSize: offset + paddingEnd }\n    // `version` is the measurement tick.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [count, estimate, gap, paddingStart, paddingEnd, version])\n\n  const range = React.useMemo(() => {\n    if (count === 0 || viewportSize === 0) return count === 0 ? null : { start: 0, end: Math.min(count - 1, overscan) }\n    const first = findIndex(layout.starts, count, scrollTop)\n    const last = findIndex(layout.starts, count, scrollTop + viewportSize)\n    return { start: Math.max(0, first - overscan), end: Math.min(count - 1, last + overscan) }\n  }, [count, viewportSize, scrollTop, layout, overscan])\n\n  const items = React.useMemo(() => {\n    if (!range) return []\n    const out: VirtualItem[] = []\n    for (let i = range.start; i <= range.end; i++) {\n      const measured = sizes.current.has(i)\n      const size = sizes.current.get(i) ?? estimate(i)\n      out.push({ index: i, key: getItemKey(i), start: layout.starts[i], size, end: layout.starts[i] + size, measured })\n    }\n    return out\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [range, layout, estimate, getItemKey, version])\n\n  const onRangeRef = React.useRef(onRangeChange)\n  onRangeRef.current = onRangeChange\n  const lastRange = React.useRef<string>(\"\")\n  React.useEffect(() => {\n    const key = range ? `${range.start}-${range.end}` : \"none\"\n    if (key === lastRange.current) return\n    lastRange.current = key\n    onRangeRef.current?.(range)\n  }, [range])\n\n  // Drop stale measurements when the list shrinks.\n  React.useEffect(() => {\n    let dirty = false\n    for (const index of sizes.current.keys()) {\n      if (index >= count) {\n        sizes.current.delete(index)\n        dirty = true\n      }\n    }\n    if (dirty) setVersion((v) => v + 1)\n  }, [count])\n\n  const measure = React.useCallback((index: number, size: number) => {\n    const prev = sizes.current.get(index)\n    if (prev !== undefined && Math.abs(prev - size) < 0.5) return\n    sizes.current.set(index, size)\n    setVersion((v) => v + 1)\n  }, [])\n\n  React.useLayoutEffect(() => {\n    const el = viewportRef.current\n    if (!el) return\n    const update = () => setViewportSize(el.clientHeight)\n    update()\n    const ro = new ResizeObserver(update)\n    ro.observe(el)\n    return () => ro.disconnect()\n  }, [])\n\n  const scrollToOffset = React.useCallback((offset: number, behavior: ScrollBehavior = \"auto\") => {\n    viewportRef.current?.scrollTo({ top: offset, behavior })\n  }, [])\n\n  const pending = React.useRef<{ index: number; align: ScrollAlign; tries: number } | null>(null)\n  const offsetFor = React.useCallback(\n    (index: number, align: ScrollAlign) => {\n      const el = viewportRef.current\n      if (!el) return 0\n      const start = layout.starts[index] ?? 0\n      const size = sizes.current.get(index) ?? estimate(index)\n      const height = el.clientHeight\n      let resolved = align\n      if (align === \"auto\") {\n        if (start < el.scrollTop) resolved = \"start\"\n        else if (start + size > el.scrollTop + height) resolved = \"end\"\n        else return el.scrollTop\n      }\n      if (resolved === \"start\") return start\n      if (resolved === \"end\") return start + size - height\n      return start + size / 2 - height / 2\n    },\n    [layout, estimate]\n  )\n\n  const scrollToIndex = React.useCallback(\n    (index: number, options?: { align?: ScrollAlign; behavior?: ScrollBehavior }) => {\n      const clamped = Math.max(0, Math.min(count - 1, index))\n      const align = options?.align ?? \"auto\"\n      pending.current = { index: clamped, align, tries: 0 }\n      scrollToOffset(offsetFor(clamped, align), options?.behavior)\n    },\n    [count, offsetFor, scrollToOffset]\n  )\n\n  // Estimated rows shift as they get measured: re-aim at the target a few times.\n  React.useLayoutEffect(() => {\n    const p = pending.current\n    const el = viewportRef.current\n    if (!p || !el) return\n    if (p.tries >= 4 || !sizes.current.has(p.index)) {\n      if (p.tries >= 4) pending.current = null\n      return\n    }\n    const target = offsetFor(p.index, p.align === \"auto\" ? \"start\" : p.align)\n    if (Math.abs(el.scrollTop - target) > 1) {\n      p.tries += 1\n      el.scrollTop = target\n    } else pending.current = null\n  })\n\n  const ctx: VirtualListContextValue = {\n    count,\n    items,\n    totalSize: layout.totalSize,\n    range,\n    measure,\n    scrollToIndex,\n    scrollToOffset,\n    viewportRef,\n    getItemKey,\n  }\n\n  return (\n    <VirtualListContext.Provider value={ctx}>\n      <VirtualListScroll onScroll={setScrollTop} />\n      <div data-slot=\"virtual-list\" className={cn(\"flex min-h-0 flex-col\", className)} {...props}>\n        {children}\n      </div>\n    </VirtualListContext.Provider>\n  )\n}\n\n/** Attaches the scroll listener once the viewport mounts (kept out of the root's render). */\nfunction VirtualListScroll({ onScroll }: { onScroll: (top: number) => void }) {\n  const ctx = useVirtualList()\n  React.useEffect(() => {\n    const el = ctx.viewportRef.current\n    if (!el) return\n    const handler = () => onScroll(el.scrollTop)\n    el.addEventListener(\"scroll\", handler, { passive: true })\n    return () => el.removeEventListener(\"scroll\", handler)\n  }, [ctx.viewportRef, onScroll])\n  return null\n}\n\n/* --------------------------------- parts --------------------------------- */\n\nfunction VirtualListViewport({ className, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  return (\n    <div\n      ref={ctx.viewportRef}\n      data-slot=\"virtual-list-viewport\"\n      className={cn(\"relative min-h-0 overflow-y-auto overscroll-contain\", className)}\n      {...props}\n    />\n  )\n}\n\n/** Sized to the whole list so the scrollbar is right; rows position inside it. */\nfunction VirtualListContent({ className, style, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  return (\n    <div\n      data-slot=\"virtual-list-content\"\n      className={cn(\"relative w-full\", className)}\n      style={{ height: ctx.totalSize, ...style }}\n      {...props}\n    />\n  )\n}\n\n/** Renders the visible window. The child renders one row and must return a `VirtualListItem`. */\nfunction VirtualListItems({ children }: { children: (item: VirtualItem) => React.ReactNode }) {\n  const ctx = useVirtualList()\n  return (\n    <>\n      {ctx.items.map((item) => (\n        <React.Fragment key={item.key}>{children(item)}</React.Fragment>\n      ))}\n    </>\n  )\n}\n\nfunction VirtualListItem({ index, className, style, ...props }: React.ComponentProps<\"div\"> & { index: number }) {\n  const { items, measure } = useVirtualList()\n  const item = items.find((i) => i.index === index)\n  const ref = React.useCallback(\n    (el: HTMLDivElement | null) => {\n      if (!el) return\n      const run = () => measure(index, el.getBoundingClientRect().height)\n      run()\n      const ro = new ResizeObserver(run)\n      ro.observe(el)\n      // React 19 ref cleanup\n      return () => ro.disconnect()\n    },\n    [measure, index]\n  )\n  return (\n    <div\n      ref={ref}\n      data-slot=\"virtual-list-item\"\n      data-index={index}\n      className={cn(\"absolute inset-x-0 top-0\", className)}\n      style={{ transform: `translateY(${item?.start ?? 0}px)`, ...style }}\n      {...props}\n    />\n  )\n}\n\nfunction VirtualListEmpty({ className, children, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  if (ctx.count > 0) return null\n  return (\n    <div\n      data-slot=\"virtual-list-empty\"\n      className={cn(\"flex flex-1 items-center justify-center py-8 text-sm text-muted-foreground\", className)}\n      {...props}\n    >\n      {children ?? \"Nothing to show\"}\n    </div>\n  )\n}\n\nexport {\n  VirtualList,\n  VirtualListContent,\n  VirtualListEmpty,\n  VirtualListItem,\n  VirtualListItems,\n  VirtualListViewport,\n  useVirtualList,\n  type VirtualItem,\n  type VirtualListProps,\n}\n"
+      "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"@/lib/utils\"\n\n/* -------------------------------- context -------------------------------- */\n\ntype VirtualItem = {\n  index: number\n  key: React.Key\n  /** Offset from the top of the content, in px. */\n  start: number\n  size: number\n  end: number\n  /** False until the row's real height has been measured. */\n  measured: boolean\n}\n\ntype ScrollAlign = \"auto\" | \"start\" | \"center\" | \"end\"\n\ntype VirtualListContextValue = {\n  /** Total number of rows. */\n  count: number\n  items: VirtualItem[]\n  totalSize: number\n  /** First and last rendered index (overscan included), or null when empty. */\n  range: { start: number; end: number } | null\n  measure: (index: number, size: number) => void\n  scrollToIndex: (index: number, options?: { align?: ScrollAlign; behavior?: ScrollBehavior }) => void\n  scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void\n  viewportRef: React.RefObject<HTMLDivElement | null>\n  /** Stable React key for a row index. */\n  getItemKey: (index: number) => React.Key\n}\n\nconst VirtualListContext = React.createContext<VirtualListContextValue | null>(null)\n\nfunction useVirtualList() {\n  const ctx = React.useContext(VirtualListContext)\n  if (!ctx) throw new Error(\"VirtualList parts must be used inside <VirtualList>\")\n  return ctx\n}\n\n/* -------------------------------- helpers -------------------------------- */\n\n/** Largest index whose start is <= offset. */\nfunction findIndex(starts: Float64Array, count: number, offset: number) {\n  let lo = 0\n  let hi = count - 1\n  while (lo < hi) {\n    const mid = (lo + hi + 1) >> 1\n    if (starts[mid] <= offset) lo = mid\n    else hi = mid - 1\n  }\n  return lo\n}\n\n/* ---------------------------------- root --------------------------------- */\n\ntype VirtualListProps = Omit<React.ComponentProps<\"div\">, \"children\"> & {\n  /** Total number of rows. */\n  count: number\n  /** Row height before measurement (a number, or per index). */\n  estimateSize?: number | ((index: number) => number)\n  /** Rows rendered beyond the visible window on each side. */\n  overscan?: number\n  /** Space between rows in px. */\n  gap?: number\n  /** Space before the first row in px. */\n  paddingStart?: number\n  /** Space after the last row in px. */\n  paddingEnd?: number\n  /** Stable React key for a row index. */\n  getItemKey?: (index: number) => React.Key\n  /** Fires when the rendered window changes. */\n  onRangeChange?: (range: { start: number; end: number } | null) => void\n  children: React.ReactNode\n}\n\nfunction VirtualList({\n  count,\n  estimateSize = 36,\n  overscan = 6,\n  gap = 0,\n  paddingStart = 0,\n  paddingEnd = 0,\n  getItemKey = (index) => index,\n  onRangeChange,\n  className,\n  children,\n  ...props\n}: VirtualListProps) {\n  const viewportRef = React.useRef<HTMLDivElement | null>(null)\n  const sizes = React.useRef(new Map<number, number>())\n  const [version, setVersion] = React.useState(0)\n  const [scrollTop, setScrollTop] = React.useState(0)\n  const [viewportSize, setViewportSize] = React.useState(0)\n  const estimate = React.useCallback(\n    (index: number) => (typeof estimateSize === \"function\" ? estimateSize(index) : estimateSize),\n    [estimateSize]\n  )\n\n  // Prefix sums of row starts; recomputed when a measurement or the count changes.\n  const layout = React.useMemo(() => {\n    const starts = new Float64Array(count)\n    let offset = paddingStart\n    for (let i = 0; i < count; i++) {\n      starts[i] = offset\n      offset += (sizes.current.get(i) ?? estimate(i)) + (i < count - 1 ? gap : 0)\n    }\n    return { starts, totalSize: offset + paddingEnd }\n    // `version` is the measurement tick.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [count, estimate, gap, paddingStart, paddingEnd, version])\n\n  const range = React.useMemo(() => {\n    if (count === 0 || viewportSize === 0) return count === 0 ? null : { start: 0, end: Math.min(count - 1, overscan) }\n    const first = findIndex(layout.starts, count, scrollTop)\n    const last = findIndex(layout.starts, count, scrollTop + viewportSize)\n    return { start: Math.max(0, first - overscan), end: Math.min(count - 1, last + overscan) }\n  }, [count, viewportSize, scrollTop, layout, overscan])\n\n  const items = React.useMemo(() => {\n    if (!range) return []\n    const out: VirtualItem[] = []\n    for (let i = range.start; i <= range.end; i++) {\n      const measured = sizes.current.has(i)\n      const size = sizes.current.get(i) ?? estimate(i)\n      out.push({ index: i, key: getItemKey(i), start: layout.starts[i], size, end: layout.starts[i] + size, measured })\n    }\n    return out\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [range, layout, estimate, getItemKey, version])\n\n  const onRangeRef = React.useRef(onRangeChange)\n  onRangeRef.current = onRangeChange\n  const lastRange = React.useRef<string>(\"\")\n  React.useEffect(() => {\n    const key = range ? `${range.start}-${range.end}` : \"none\"\n    if (key === lastRange.current) return\n    lastRange.current = key\n    onRangeRef.current?.(range)\n  }, [range])\n\n  // Drop stale measurements when the list shrinks.\n  React.useEffect(() => {\n    let dirty = false\n    for (const index of sizes.current.keys()) {\n      if (index >= count) {\n        sizes.current.delete(index)\n        dirty = true\n      }\n    }\n    if (dirty) setVersion((v) => v + 1)\n  }, [count])\n\n  const measure = React.useCallback((index: number, size: number) => {\n    const prev = sizes.current.get(index)\n    if (prev !== undefined && Math.abs(prev - size) < 0.5) return\n    sizes.current.set(index, size)\n    setVersion((v) => v + 1)\n  }, [])\n\n  React.useLayoutEffect(() => {\n    const el = viewportRef.current\n    if (!el) return\n    const update = () => setViewportSize(el.clientHeight)\n    update()\n    const ro = new ResizeObserver(update)\n    ro.observe(el)\n    return () => ro.disconnect()\n  }, [])\n\n  const scrollToOffset = React.useCallback((offset: number, behavior: ScrollBehavior = \"auto\") => {\n    viewportRef.current?.scrollTo({ top: offset, behavior })\n  }, [])\n\n  const pending = React.useRef<{ index: number; align: ScrollAlign; tries: number } | null>(null)\n  const offsetFor = React.useCallback(\n    (index: number, align: ScrollAlign) => {\n      const el = viewportRef.current\n      if (!el) return 0\n      const start = layout.starts[index] ?? 0\n      const size = sizes.current.get(index) ?? estimate(index)\n      const height = el.clientHeight\n      let resolved = align\n      if (align === \"auto\") {\n        if (start < el.scrollTop) resolved = \"start\"\n        else if (start + size > el.scrollTop + height) resolved = \"end\"\n        else return el.scrollTop\n      }\n      if (resolved === \"start\") return start\n      if (resolved === \"end\") return start + size - height\n      return start + size / 2 - height / 2\n    },\n    [layout, estimate]\n  )\n\n  const scrollToIndex = React.useCallback(\n    (index: number, options?: { align?: ScrollAlign; behavior?: ScrollBehavior }) => {\n      const clamped = Math.max(0, Math.min(count - 1, index))\n      const align = options?.align ?? \"auto\"\n      pending.current = { index: clamped, align, tries: 0 }\n      scrollToOffset(offsetFor(clamped, align), options?.behavior)\n    },\n    [count, offsetFor, scrollToOffset]\n  )\n\n  // Estimated rows shift as they get measured: re-aim at the target a few times.\n  React.useLayoutEffect(() => {\n    const p = pending.current\n    const el = viewportRef.current\n    if (!p || !el) return\n    if (p.tries >= 4 || !sizes.current.has(p.index)) {\n      if (p.tries >= 4) pending.current = null\n      return\n    }\n    const target = offsetFor(p.index, p.align === \"auto\" ? \"start\" : p.align)\n    if (Math.abs(el.scrollTop - target) > 1) {\n      p.tries += 1\n      el.scrollTop = target\n    } else pending.current = null\n  })\n\n  const ctx: VirtualListContextValue = {\n    count,\n    items,\n    totalSize: layout.totalSize,\n    range,\n    measure,\n    scrollToIndex,\n    scrollToOffset,\n    viewportRef,\n    getItemKey,\n  }\n\n  return (\n    <VirtualListContext.Provider value={ctx}>\n      <VirtualListScroll onScroll={setScrollTop} />\n      <div data-slot=\"virtual-list\" className={cn(\"flex min-h-0 flex-col\", className)} {...props}>\n        {children}\n      </div>\n    </VirtualListContext.Provider>\n  )\n}\n\n/** Attaches the scroll listener once the viewport mounts (kept out of the root's render). */\nfunction VirtualListScroll({ onScroll }: { onScroll: (top: number) => void }) {\n  const ctx = useVirtualList()\n  React.useEffect(() => {\n    const el = ctx.viewportRef.current\n    if (!el) return\n    const handler = () => onScroll(el.scrollTop)\n    el.addEventListener(\"scroll\", handler, { passive: true })\n    return () => el.removeEventListener(\"scroll\", handler)\n  }, [ctx.viewportRef, onScroll])\n  return null\n}\n\n/* --------------------------------- parts --------------------------------- */\n\nfunction VirtualListViewport({ className, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  return (\n    <div\n      ref={ctx.viewportRef}\n      data-slot=\"virtual-list-viewport\"\n      className={cn(\"relative min-h-0 overflow-y-auto overscroll-contain\", className)}\n      {...props}\n    />\n  )\n}\n\n/** Sized to the whole list so the scrollbar is right; rows position inside it. */\nfunction VirtualListContent({ className, style, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  return (\n    <div\n      data-slot=\"virtual-list-content\"\n      className={cn(\"relative w-full\", className)}\n      style={{ height: ctx.totalSize, ...style }}\n      {...props}\n    />\n  )\n}\n\n/** Renders the visible window. The child renders one row and must return a `VirtualListItem`. */\nfunction VirtualListItems({ children }: { children: (item: VirtualItem) => React.ReactNode }) {\n  const ctx = useVirtualList()\n  return (\n    <>\n      {ctx.items.map((item) => (\n        <React.Fragment key={item.key}>{children(item)}</React.Fragment>\n      ))}\n    </>\n  )\n}\n\nfunction VirtualListItem({ index, className, style, ...props }: React.ComponentProps<\"div\"> & { index: number }) {\n  const { items, measure } = useVirtualList()\n  const item = items.find((i) => i.index === index)\n  const ref = React.useCallback(\n    (el: HTMLDivElement | null) => {\n      if (!el) return\n      const run = () => measure(index, el.getBoundingClientRect().height)\n      run()\n      const ro = new ResizeObserver(run)\n      ro.observe(el)\n      // React 19 ref cleanup\n      return () => ro.disconnect()\n    },\n    [measure, index]\n  )\n  return (\n    <div\n      ref={ref}\n      data-slot=\"virtual-list-item\"\n      data-index={index}\n      className={cn(\"absolute inset-x-0 top-0\", className)}\n      style={{ transform: `translateY(${item?.start ?? 0}px)`, ...style }}\n      {...props}\n    />\n  )\n}\n\nfunction VirtualListEmpty({ className, children, ...props }: React.ComponentProps<\"div\">) {\n  const ctx = useVirtualList()\n  if (ctx.count > 0) return null\n  return (\n    <div\n      data-slot=\"virtual-list-empty\"\n      className={cn(\"flex flex-1 items-center justify-center py-8 text-sm text-muted-foreground\", className)}\n      {...props}\n    >\n      {children ?? \"Nothing to show\"}\n    </div>\n  )\n}\n\nexport {\n  VirtualList,\n  VirtualListContent,\n  VirtualListEmpty,\n  VirtualListItem,\n  VirtualListItems,\n  VirtualListViewport,\n  useVirtualList,\n  type VirtualItem,\n  type VirtualListProps,\n}\n"
     }
   ],
   "docs": "## Virtual list\n`src/components/ui/virtual-list.tsx` is a dependency-free windowed list. `VirtualList { count,\nestimateSize (number or per index), overscan, gap, paddingStart/End, getItemKey, onRangeChange }`\nowns scroll offset, viewport size, and measured row heights (prefix sums + binary search; rows\nmeasure themselves with a ResizeObserver and estimates are replaced as rows appear). Parts:\n`VirtualListViewport` (the scroll container; **the consumer gives it a height**, it must never be\n`flex-1` in an auto-height column or it grows to the whole content and renders every row) >\n`VirtualListContent` (sized to `totalSize`) > `VirtualListItems` (render-prop child gets\n`{ index, key, start, size, measured }` and returns a `VirtualListItem index=`, absolutely\npositioned via translateY, `data-index`), `VirtualListEmpty`. `useVirtualList()` exposes `items`,\n`range`, `totalSize`, `scrollToIndex(index, { align: auto|start|center|end })` (re-aims a few times\nwhile estimated rows get measured) and `scrollToOffset`. Keyboard is the consumer's: keep focus on\nthe viewport with `aria-activedescendant` and call `scrollToIndex` for the active row, as the\ncontacts listbox in `src/demo/virtual-list/` does (`/audit-log`, \"Audit log\": a 100k-line log with mixed\nheights and go-to-line, and a 10k-contact listbox with search)."

package/src/components/ui/app-shell.tsx

@@ -60,6 +60,7 @@ type SidebarCollapsible = "offcanvas" | "icon" | "none"
 type AppShellContextValue = {
   variant: SidebarVariant
   setVariant: (variant: SidebarVariant) => void
+  /** Controlled sidebar collapse mode: `offcanvas`, `icon`, or `none`. */
   collapsible: SidebarCollapsible
   setCollapsible: (collapsible: SidebarCollapsible) => void
   searchOpen: boolean
@@ -91,10 +92,15 @@ function AppShell({
   ...sidebarProviderProps
 }: Omit<React.ComponentProps<typeof SidebarProvider>, "children"> & {
   variant?: SidebarVariant
+  /** Initial sidebar variant when uncontrolled. */
   defaultVariant?: SidebarVariant
+  /** Called when the sidebar variant changes. */
   onVariantChange?: (variant: SidebarVariant) => void
+  /** Controlled sidebar collapse mode: `offcanvas`, `icon`, or `none`. */
   collapsible?: SidebarCollapsible
+  /** Initial collapse mode when uncontrolled. */
   defaultCollapsible?: SidebarCollapsible
+  /** Called when the collapse mode changes. */
   onCollapsibleChange?: (collapsible: SidebarCollapsible) => void
   /** Toggle the search dialog with Cmd/Ctrl+K. */
   searchShortcut?: boolean
@@ -308,6 +314,7 @@ function AppShellNavCollapsible({
   active?: boolean
   defaultOpen?: boolean
   tooltip?: string
+  /** Element rendered as the trigger for the collapsible group. */
   trigger: React.ReactNode
   /** Rendered inside the flyout when the sidebar is collapsed to icons. */
   menu?: React.ReactNode
@@ -674,6 +681,7 @@ function AppShellNotificationsTrigger({
 }: React.ComponentProps<typeof Button> & {
   /** Unread count shown as a badge; hidden when 0. */
   count?: number
+  /** Cap for the badge count; larger counts render as `max+`. */
   max?: number
 }) {
   const label = count > max ? `${max}+` : String(count)
@@ -763,6 +771,7 @@ function AppShellNotificationItem({
   children,
   ...props
 }: React.ComponentProps<"li"> & {
+  /** Mark the notification unread; sets `data-unread` and shows the indicator. */
   unread?: boolean
   /** Render the item's child (e.g. an anchor or button) as the interactive surface. */
   asChild?: boolean
@@ -894,7 +903,9 @@ function AppShellThemeToggle({
   className,
   ...props
 }: Omit<React.ComponentProps<typeof Button>, "onChange"> & {
+  /** Current theme: `light`, `dark`, or `system`. */
   theme: Theme
+  /** Called with the next theme when the toggle is used. */
   onThemeChange: (theme: Theme) => void
 }) {
   return (

package/src/components/ui/attachment.tsx

@@ -31,6 +31,7 @@ function Attachment({
   ...props
 }: React.ComponentProps<"div"> &
   VariantProps<typeof attachmentVariants> & {
+    /** Upload state: `idle`, `uploading`, `processing`, `error`, or `done`; sets `data-state`. */
     state?: "idle" | "uploading" | "processing" | "error" | "done"
   }) {
   return (

package/src/components/ui/calendar.tsx

@@ -18,6 +18,7 @@ function Calendar({
   components,
   ...props
 }: React.ComponentProps<typeof DayPicker> & {
+  /** Button variant used for the navigation buttons. */
   buttonVariant?: React.ComponentProps<typeof Button>["variant"]
 }) {
   const defaultClassNames = getDefaultClassNames()

package/src/components/ui/canvas.tsx

@@ -154,6 +154,7 @@ function Canvas({
           const data = source.data as DragData
           setDragging(data.type === "node" ? { type: "node", id: data.id } : { type: "palette" })
         },
+        /** Called with `{ source, target }` for every drop: a palette item or node onto a node edge or the empty area. */
         onDrop: ({ source, location }) => {
           setDragging(null)
           const data = source.data as DragData
@@ -257,6 +258,7 @@ function CanvasPaletteItem({ data, className, onKeyDown, ...props }: React.Compo
       getInitialData: (): DragData => ({ instanceId, type: "palette", data: dataRef.current }),
       onGenerateDragPreview: (args) => cloneDragPreview(args),
       onDragStart: () => setIsDragging(true),
+      /** Called with `{ source, target }` for every drop: a palette item or node onto a node edge or the empty area. */
       onDrop: () => setIsDragging(false),
     })
   }, [instanceId])
@@ -310,6 +312,7 @@ function CanvasArea({ className, ...props }: React.ComponentProps<"div">) {
           setIsOver((prev) => (prev === over ? prev : over))
         },
         onDragLeave: () => setIsOver(false),
+        /** Called with `{ source, target }` for every drop: a palette item or node onto a node edge or the empty area. */
         onDrop: () => setIsOver(false),
       }),
       autoScrollForElements({ element: el, canScroll: ({ source }) => isOwnData(instanceId, source.data) })
@@ -437,6 +440,7 @@ function CanvasNode({
           setClosestEdge((prev) => (prev === edge ? prev : edge))
         },
         onDragLeave: () => setClosestEdge(null),
+        /** Called with `{ source, target }` for every drop: a palette item or node onto a node edge or the empty area. */
         onDrop: () => setClosestEdge(null),
       }),
     ]
@@ -448,6 +452,7 @@ function CanvasNode({
           getInitialData: (): DragData => ({ instanceId, type: "node", id: value }),
           onGenerateDragPreview: (args) => cloneDragPreview(args),
           onDragStart: () => setIsDragging(true),
+          /** Called with `{ source, target }` for every drop: a palette item or node onto a node edge or the empty area. */
           onDrop: () => setIsDragging(false),
         })
       )
@@ -602,8 +607,11 @@ function CanvasResizeHandle({
   className,
   ...props
 }: Omit<React.ComponentProps<"div">, "onResize"> & {
+  /** Called while dragging with the width change as a fraction of the row width. */
   onResize: (deltaFraction: number) => void
+  /** Called once when the resize drag starts. */
   onResizeStart?: () => void
+  /** Called once when the resize drag ends. */
   onResizeEnd?: () => void
 }) {
   const row = React.useContext(RowContext)

package/src/components/ui/carousel.tsx

@@ -11,9 +11,12 @@ type CarouselOptions = UseCarouselParameters[0]
 type CarouselPlugin = UseCarouselParameters[1]
 
 type CarouselProps = {
+  /** Embla carousel options. */
   opts?: CarouselOptions
+  /** Embla plugins. */
   plugins?: CarouselPlugin
   orientation?: "horizontal" | "vertical"
+  /** Receives the Embla API once the carousel mounts. */
   setApi?: (api: CarouselApi) => void
 }
 

package/src/components/ui/cascader.tsx

@@ -410,6 +410,7 @@ function CascaderValue<T extends TreeNode>({
   ...props
 }: Omit<React.ComponentProps<"span">, "children"> & {
   placeholder?: React.ReactNode
+  /** Rendered between path segments. */
   separator?: React.ReactNode
   children?: (path: T[]) => React.ReactNode
 }) {

package/src/components/ui/chart.tsx

@@ -20,6 +20,7 @@ export type ChartConfig = Record<
 >
 
 type ChartContextProps = {
+  /** Series config: label, icon, and color (or theme colors) per data key; exposed as `--color-<key>`. */
   config: ChartConfig
 }
 
@@ -43,8 +44,10 @@ function ChartContainer({
   initialDimension = INITIAL_DIMENSION,
   ...props
 }: React.ComponentProps<"div"> & {
+  /** Series config: label, icon, and color (or theme colors) per data key; exposed as `--color-<key>`. */
   config: ChartConfig
   children: React.ComponentProps<typeof RechartsPrimitive.ResponsiveContainer>["children"]
+  /** Width and height used before the container measures itself. */
   initialDimension?: {
     width: number
     height: number
@@ -120,10 +123,15 @@ function ChartTooltipContent({
   labelKey,
 }: React.ComponentProps<typeof RechartsPrimitive.Tooltip> &
   React.ComponentProps<"div"> & {
+    /** Hide the tooltip label. */
     hideLabel?: boolean
+    /** Hide the color indicator in each row. */
     hideIndicator?: boolean
+    /** Indicator style: `dot`, `line`, or `dashed`. */
     indicator?: "line" | "dot" | "dashed"
+    /** Data key used for the series name. */
     nameKey?: string
+    /** Data key used for the tooltip label. */
     labelKey?: string
   } & Omit<RechartsPrimitive.DefaultTooltipContentProps<TooltipValueType, TooltipNameType>, "accessibilityLayer">) {
   const { config } = useChart()
@@ -238,7 +246,9 @@ function ChartLegendContent({
   verticalAlign = "bottom",
   nameKey,
 }: React.ComponentProps<"div"> & {
+  /** Hide the series icon. */
   hideIcon?: boolean
+  /** Data key used for the series name. */
   nameKey?: string
 } & RechartsPrimitive.DefaultLegendContentProps) {
   const { config } = useChart()

package/src/components/ui/combobox.tsx

@@ -120,7 +120,9 @@ function ComboboxInput({
   showClear = false,
   ...props
 }: Omit<React.ComponentProps<typeof ComboboxPrimitive.Input>, "id"> & {
+  /** Render the open/close trigger in the control. */
   showTrigger?: boolean
+  /** Render the clear button in the control. */
   showClear?: boolean
 }) {
   return (
@@ -316,6 +318,7 @@ function ComboboxChip({
 }: React.ComponentProps<"div"> & {
   /** The selected value this chip represents. */
   value: string
+  /** Render the remove button on the chip. */
   showRemove?: boolean
 }) {
   const combobox = useComboboxContext()

package/src/components/ui/command.tsx

@@ -167,6 +167,7 @@ function CommandGroup({
   children,
   ...props
 }: React.ComponentProps<typeof CommandPrimitive.ItemGroup> & {
+  /** Group heading text. */
   heading?: React.ReactNode
 }) {
   return (

package/src/components/ui/comment-thread.tsx

@@ -35,8 +35,11 @@ import { useControllable } from "@/lib/controllable"
 type Person = { id: string; name: string; initials?: string; avatar?: string }
 
 type ThreadContextValue = {
+  /** People who can be mentioned and whose names and initials are rendered. */
   people: Person[]
+  /** Id of the signed-in person; their comments get `data-own` and mentions of them `data-self`. */
   currentUserId?: string
+  /** Id of the comment being replied to (controlled). */
   replyTo: string | null
   setReplyTo: (id: string | null) => void
   editing: string | null
@@ -77,9 +80,13 @@ function CommentThread({
   className,
   ...props
 }: React.ComponentProps<"div"> & {
+  /** People who can be mentioned and whose names and initials are rendered. */
   people?: Person[]
+  /** Id of the signed-in person; their comments get `data-own` and mentions of them `data-self`. */
   currentUserId?: string
+  /** Id of the comment being replied to (controlled). */
   replyTo?: string | null
+  /** Called when the reply target changes. */
   onReplyToChange?: (id: string | null) => void
 }) {
   const [replyTo, setReplyTo] = useControllable<string | null>(replyToProp, null, onReplyToChange)
@@ -383,6 +390,7 @@ function CommentEmpty({ className, ...props }: React.ComponentProps<"div">) {
 type MentionState = { query: string; start: number; index: number } | null
 
 type ComposerContextValue = {
+  /** People who can be mentioned and whose names and initials are rendered. */
   people: Person[]
   value: string
   setValue: (value: string) => void
@@ -424,13 +432,16 @@ function CommentComposer({
   children,
   ...props
 }: Omit<React.ComponentProps<"div">, "onSubmit" | "defaultValue"> & {
+  /** People who can be mentioned and whose names and initials are rendered. */
   people?: Person[]
   value?: string
   defaultValue?: string
   onValueChange?: (value: string) => void
   /** Called with the trimmed text and the ids of mentioned people. */
   onSubmit?: (comment: { text: string; mentions: string[] }) => void
+  /** Called when the composer is cancelled with Escape or the cancel trigger. */
   onCancel?: () => void
+  /** Maximum number of mention suggestions shown. */
   maxSuggestions?: number
 }) {
   const [value, setValue] = useControllable(valueProp, defaultValue, onValueChange)

package/src/components/ui/context-menu.tsx

@@ -70,6 +70,7 @@ function ContextMenuItem({
   ...props
 }: Omit<React.ComponentProps<typeof ContextMenuPrimitive.Item>, "value"> & {
   value?: string
+  /** Indent the item to align with items that have an indicator. */
   inset?: boolean
   variant?: "default" | "destructive"
 }) {
@@ -117,8 +118,10 @@ function ContextMenuCheckboxItem({
   value,
   ...props
 }: Omit<React.ComponentProps<typeof ContextMenuPrimitive.CheckboxItem>, "checked" | "value"> & {
+  /** Checked state of the item. */
   checked?: boolean
   value?: string
+  /** Indent the item to align with items that have an indicator. */
   inset?: boolean
 }) {
   const id = React.useId()
@@ -149,6 +152,7 @@ function ContextMenuRadioItem({
   inset,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.RadioItem> & {
+  /** Indent the item to align with items that have an indicator. */
   inset?: boolean
 }) {
   return (
@@ -171,6 +175,7 @@ function ContextMenuLabel({
   inset,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.ItemGroupLabel> & {
+  /** Indent the item to align with items that have an indicator. */
   inset?: boolean
 }) {
   return (
@@ -220,6 +225,7 @@ function ContextMenuSubTrigger({
   children,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.TriggerItem> & {
+  /** Indent the item to align with items that have an indicator. */
   inset?: boolean
 }) {
   return (

package/src/components/ui/data-grid.tsx

@@ -102,6 +102,7 @@ type DataGridContextValue<TData = unknown> = {
   layoutById: Map<string, ColumnLayout>
   templateColumns: string
   totalWidth: number
+  /** Fixed height of every row in px. */
   rowHeight: number
   setWidth: (columnId: string, width: number) => void
   focus: CellAddress | null
@@ -166,12 +167,19 @@ function DataGrid<TData>({
   ...props
 }: Omit<React.ComponentProps<"div">, "children"> & {
   table: DataTableInstance<TData>
+  /** Per-column grid behaviour keyed by column id: editor type, width, pinning, options, format and parse. */
   columns?: DataGridColumnConfig[]
+  /** Fixed height of every row in px. */
   rowHeight?: number
+  /** Rows rendered beyond the visible window on each side. */
   overscan?: number
+  /** Called with `{ row, columnId, value, previous }` when a cell edit commits; the consumer applies it. */
   onCellChange?: (change: DataGridCellChange<TData>) => void
+  /** Controlled column widths by column id. */
   columnSizing?: Record<string, number>
+  /** Initial column widths when uncontrolled. */
   defaultColumnSizing?: Record<string, number>
+  /** Called when a column is resized. */
   onColumnSizingChange?: (sizing: Record<string, number>) => void
   children?: React.ReactNode
 }) {