@djangocfg/ui-core 2.1.556 → 2.1.558

package/README.md

@@ -51,11 +51,11 @@ import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 | Group | Examples |
 |---|---|
 | `components/data/` | Avatar · Badge · Card · Table · BalancedText · Skeleton |
-| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form · DateField · TimeField · DateTimeField · MoneyField |
+| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form · DateField · TimeField · DateTimeField · MoneyField · FilterButton · FilterMenu |
 | `components/feedback/` | Alert · Toast · Banner · Progress · Spinner |
 | `components/overlay/` | Dialog · Drawer · Popover · Tooltip · HoverCard · Sheet · ContextMenu · DropdownMenu |
 | `components/navigation/` | Sidebar · Tabs · Breadcrumb · Pagination · NavigationMenu · Command · Disclosure |
-| `components/layout/` | Container · Grid · Stack · Separator · ScrollArea · Sticky |
+| `components/layout/` | Container · Grid · Stack · Separator · ScrollArea · Sticky · FilterBar |
 | `components/select/` | Combobox · MultiSelect |
 | `components/effects/` | Glass · Marquee · Backdrop |
 | `components/specialized/` | Accordion · Collapsible · Toggle · Calendar · DatePicker (legacy — prefer forms/DateField) |
@@ -71,7 +71,7 @@ fields (`DateField` / `TimeField` / `DateTimeField`) have their own reference in
 
 | Topic | Hooks |
 |---|---|
-| `dom/` | `useSize` · `useResizeObserver` · `useMeasure` · `useMutationObserver` · `useIntersection` |
+| `dom/` | `useSize` · `useResizeObserver` · `useMeasure` · `useMutationObserver` · `useIntersection` · `useHighlight` |
 | `device/` | `useIsMobile` · `useIsTouch` · `useMediaQuery` · `useOnline` · `useViewportSize` · `useOrientation` |
 | `state/` | `useLocalStorage` · `useSessionStorage` · `useToggle` · `useCounter` · `useDebouncedValue` |
 | `events/` | `useEventListener` · `useClickOutside` · `useKeyPress` · `useFocusWithin` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.556",
+  "version": "2.1.558",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -130,7 +130,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.556",
+    "@djangocfg/i18n": "^2.1.558",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,9 +206,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.556",
-    "@djangocfg/i18n": "^2.1.556",
-    "@djangocfg/typescript-config": "^2.1.556",
+    "@djangocfg/eslint-config": "^2.1.558",
+    "@djangocfg/i18n": "^2.1.558",
+    "@djangocfg/typescript-config": "^2.1.558",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/components/data/calendar/calendar.tsx

@@ -83,7 +83,7 @@ function Calendar({
           defaultClassNames.dropdowns
         ),
         dropdown_root: cn(
-          "has-focus:border-ring border-input shadow-xs has-focus:ring-ring has-focus:ring-1 relative rounded-[var(--radius)] border",
+          "has-focus:border-ring border-border shadow-xs has-focus:ring-ring has-focus:ring-1 relative rounded-[var(--radius)] border",
           defaultClassNames.dropdown_root
         ),
         dropdown: cn(

package/src/components/data/toggle/index.tsx

@@ -14,7 +14,7 @@ const toggleVariants = cva(
       variant: {
         default: "bg-transparent",
         outline:
-          "border border-input bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground",
+          "border border-border bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground",
       },
       size: {
         default: "h-9 px-2 min-w-9",

package/src/components/forms/button/index.tsx

@@ -18,8 +18,13 @@ const buttonVariants = cva(
           "bg-primary text-primary-foreground shadow hover:bg-primary/90",
         destructive:
           "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        // `border-border`, never `border-input`: `--input` is the FILL token
+        // for a field's surface, and in the light theme it is the page colour
+        // itself (97% L) — an outline button drawn with it had no visible edge
+        // at all. `--border` (86% L) is the token for an edge. Same pairing
+        // `Input` and `InputGroup` use.
         outline:
-          "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+          "border border-border bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
         secondary:
           "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
         ghost: "hover:bg-accent hover:text-accent-foreground",

package/src/components/forms/checkbox/index.tsx

@@ -16,7 +16,7 @@ const Checkbox = React.forwardRef<
     className={cn(
       // `select-none`: the box itself is a click target, and a drag that starts
       // on it must not paint a text selection across the row it lives in.
-      "peer h-[1.125rem] w-[1.125rem] shrink-0 select-none rounded-[4px] border border-input bg-background shadow-none",
+      "peer h-[1.125rem] w-[1.125rem] shrink-0 select-none rounded-[4px] border border-border bg-background shadow-none",
       "transition-colors duration-150",
       "focus-visible:border-ring focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
       "disabled:cursor-not-allowed disabled:opacity-40",

package/src/components/forms/filter-button/index.tsx

@@ -0,0 +1,145 @@
+"use client"
+
+import * as React from 'react'
+
+import { cn } from '../../../lib/utils'
+
+export interface FilterButtonProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'value'> {
+  /** Leading icon. Rendered decoratively — the name comes from the label. */
+  icon?: React.ComponentType<{ className?: string }>
+  /** Trailing icon, typically a chevron for a control that opens a menu. */
+  trailingIcon?: React.ComponentType<{ className?: string }>
+  /**
+   * The chosen option, shown in place of the label.
+   *
+   * A pill showing an answer keeps it visible when the row is tight, while the
+   * ones still asking a question collapse to their icon: "SUV" is worth the
+   * space, "Body type" is what the icon already says.
+   */
+  value?: React.ReactNode
+  /** Marks a filter that is applied. Tints the control. */
+  active?: boolean
+  /**
+   * A number worth showing on the control — active filters, or available
+   * options. Zero and `undefined` both render nothing, so a caller can pass a
+   * count straight through without guarding it.
+   */
+  count?: number
+  /** Filled rather than outlined. For the one control that opens the panel. */
+  variant?: 'outline' | 'solid'
+}
+
+/**
+ * A filter control in a toolbar: a pill with an icon, a label, and optionally a
+ * count.
+ *
+ * Its one piece of behaviour is that the label collapses when the row runs out
+ * of room — see `filter-bar.css`, which owns the query. The button keeps its
+ * accessible name through that collapse via `aria-label`, which is the part
+ * both product frontends lost: they hid the text with `clip-path: inset(50%)`,
+ * which removes it from sight while leaving it in the accessibility tree, so
+ * the icon-only state reads correctly to a screen reader by accident and only
+ * for as long as the text stays in the DOM.
+ *
+ * Must be rendered inside a `FilterBar`: the height and the container query
+ * both come from the row.
+ */
+export const FilterButton = React.forwardRef<HTMLButtonElement, FilterButtonProps>(
+  (
+    {
+      className,
+      icon: Icon,
+      trailingIcon: TrailingIcon,
+      children,
+      value,
+      active = false,
+      count,
+      variant = 'outline',
+      'aria-label': ariaLabel,
+      ...props
+    },
+    ref
+  ) => {
+    const answered = value != null && value !== ''
+    const label = answered ? value : children
+    const showCount = typeof count === 'number' && count > 0
+
+    // The name has to survive the label collapsing to nothing, and it has to
+    // read as the question plus its answer ("Body type: SUV") rather than the
+    // answer alone, which says nothing about what was chosen. The count joins
+    // it because the badge itself is decorative — a bare "3" announced after a
+    // label is a number without a noun.
+    const base =
+      answered && typeof children === 'string' && typeof value === 'string'
+        ? `${children}: ${value}`
+        : typeof children === 'string'
+          ? children
+          : undefined
+    const name = ariaLabel ?? (base && showCount ? `${base} (${count})` : base)
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-slot="filter-pill"
+        data-active={active || undefined}
+        data-answered={answered || undefined}
+        aria-label={name}
+        className={cn(
+          'filter-pill inline-flex shrink-0 items-center gap-2 rounded-full',
+          'h-[var(--filter-control-h,2.375rem)] px-3.5',
+          'text-sm font-medium whitespace-nowrap',
+          'transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'disabled:pointer-events-none disabled:opacity-50',
+          '[&_svg]:size-4 [&_svg]:shrink-0',
+          variant === 'solid'
+            ? 'bg-primary text-primary-foreground hover:bg-primary/90'
+            : cn(
+                'border bg-background hover:bg-accent hover:text-accent-foreground',
+                // An applied filter reads as chosen without shouting: the edge
+                // carries it, not a fill that would compete with the solid
+                // control beside it.
+                //
+                // Both states keep `text-foreground`. `text-muted-foreground`
+                // was the obvious choice for "not applied" and measured 4.21:1
+                // on the light theme — under AA for a control label. An unset
+                // filter is a normal control, not a de-emphasised one; what
+                // marks the applied one is the border.
+                'text-foreground',
+                // Weight as well as colour: a border tint alone would make
+                // "applied" a colour-only signal, which the accessibility rules
+                // rule out. Usually the label also changes — an applied filter
+                // shows its `value` — but `active` can be set without one.
+                active
+                  ? 'border-primary/60 font-semibold'
+                  : 'border-border'
+              ),
+          className
+        )}
+        {...props}
+      >
+        {Icon && <Icon aria-hidden className="opacity-70" />}
+        {label != null && <span className="filter-pill-label">{label}</span>}
+        {showCount && (
+          <span
+            aria-hidden
+            className={cn(
+              'inline-flex min-w-5 items-center justify-center rounded-full px-1.5',
+              'text-xs font-semibold tabular-nums',
+              // On the filled control the badge has to invert, or it disappears
+              // into its own background. Both frontends wrote this pair by hand.
+              variant === 'solid'
+                ? 'bg-primary-foreground text-primary'
+                : 'bg-muted text-foreground'
+            )}
+          >
+            {count}
+          </span>
+        )}
+        {TrailingIcon && <TrailingIcon aria-hidden className="opacity-50" />}
+      </button>
+    )
+  }
+)
+FilterButton.displayName = 'FilterButton'

package/src/components/forms/filter-menu/index.tsx

@@ -0,0 +1,203 @@
+"use client"
+
+import { Check, ChevronDown } from 'lucide-react'
+import * as React from 'react'
+
+import { useAppT } from '@djangocfg/i18n'
+import { cn } from '../../../lib/utils'
+import {
+  Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList
+} from '../../navigation/command'
+import { Popover, PopoverContent, PopoverTrigger } from '../../overlay/popover'
+import { useHighlight } from '../../../hooks';
+import { FilterButton, type FilterButtonProps } from '../filter-button'
+
+export interface FilterMenuOption {
+  value: string
+  label: string
+  /** Matches on top of the label — a synonym, a code, a native spelling. */
+  keywords?: string[]
+  /** How many results this option would leave. Shown after the label. */
+  count?: number
+  disabled?: boolean
+}
+
+type TriggerProps = Pick<
+  FilterButtonProps,
+  'icon' | 'variant' | 'className' | 'disabled'
+>
+
+export interface FilterMenuProps extends TriggerProps {
+  /** The question the control asks: "Body type", "Fuel". */
+  label: string
+  /**
+   * The options to choose from. Omit and pass `children` instead to supply a
+   * body of your own — a range slider, a date pair, a colour grid.
+   */
+  options?: FilterMenuOption[]
+  /** Selected option, or `null` for none. */
+  value?: string | null
+  onValueChange?: (value: string | null) => void
+  /**
+   * When to show the search field.
+   *
+   * A number is a threshold on the option count; `true` / `false` force it.
+   * The default is the point where the list stops fitting its own popover —
+   * `.popover-scroll-region` caps at 300px and a row is ~30px, so beyond ten
+   * options the reader is scrolling blind and a search field earns its place.
+   * Below that it is one more thing between them and four visible answers.
+   */
+  searchable?: boolean | number
+  searchPlaceholder?: string
+  emptyText?: string
+  /**
+   * A body of your own, in place of `options`. The popover, the trigger and
+   * its state stay this component's; what goes inside is yours.
+   */
+  children?: React.ReactNode
+  /** Width of the popover. Defaults to the trigger's width, min 220px. */
+  contentClassName?: string
+}
+
+/** The option count past which a list needs a search field. */
+const SEARCHABLE_FROM = 10
+
+/**
+ * A filter control and the menu it opens.
+ *
+ * Pass `options` and it renders the list, adding a search field once the list
+ * outgrows its popover. Pass `children` instead and the body is yours — the
+ * control still owns the trigger, the popover and the open state, which is the
+ * part every caller was rewriting.
+ *
+ * The selected option replaces the label on the trigger ("SUV", not "Body
+ * type"), so a row of these reads as the current query rather than as a row of
+ * unanswered questions.
+ */
+export function FilterMenu({
+  label,
+  options,
+  value,
+  onValueChange,
+  searchable,
+  searchPlaceholder,
+  emptyText,
+  children,
+  contentClassName,
+  icon,
+  variant,
+  className,
+  disabled,
+}: FilterMenuProps) {
+  const t = useAppT()
+  const [open, setOpen] = React.useState(false)
+  const [search, setSearch] = React.useState('')
+  // Opens on the current choice and scrolls to it — the same hook the
+  // comboboxes use, so a long facet behaves like every other long list here.
+  const highlight = useHighlight(open, value)
+
+  const resolvedSearchPlaceholder = searchPlaceholder ?? t('ui.select.search')
+  const resolvedEmptyText = emptyText ?? t('ui.select.noResults')
+
+  const showSearch =
+    typeof searchable === 'number'
+      ? (options?.length ?? 0) >= searchable
+      : (searchable ?? (options?.length ?? 0) >= SEARCHABLE_FROM)
+
+  const selected = options?.find((option) => option.value === value)
+
+  const filtered = React.useMemo(() => {
+    if (!options || !search) return options ?? []
+    const needle = search.toLowerCase()
+    return options.filter(
+      (option) =>
+        option.label.toLowerCase().includes(needle) ||
+        option.value.toLowerCase().includes(needle) ||
+        option.keywords?.some((k) => k.toLowerCase().includes(needle))
+    )
+  }, [options, search])
+
+  const handleSelect = React.useCallback(
+    (next: string) => {
+      // Selecting the chosen option again clears it: the trigger is the only
+      // affordance a filter row has, and a dead-end "chosen" state would need
+      // a second one.
+      onValueChange?.(next === value ? null : next)
+      setOpen(false)
+    },
+    [onValueChange, value]
+  )
+
+  const handleOpenChange = React.useCallback((next: boolean) => {
+    setOpen(next)
+    if (!next) setSearch('')
+  }, [])
+
+  return (
+    <Popover open={open} onOpenChange={handleOpenChange}>
+      <PopoverTrigger asChild>
+        <FilterButton
+          icon={icon}
+          variant={variant}
+          className={className}
+          disabled={disabled}
+          trailingIcon={ChevronDown}
+          value={selected?.label}
+          active={Boolean(selected)}
+          aria-expanded={open}
+        >
+          {label}
+        </FilterButton>
+      </PopoverTrigger>
+      <PopoverContent
+        align="start"
+        className={cn('w-[max(220px,var(--radix-popover-trigger-width))] p-0', contentClassName)}
+      >
+        {children ?? (
+          <Command
+            shouldFilter={false}
+            value={highlight.value}
+            onValueChange={highlight.setValue}
+            className="flex min-h-0 flex-col"
+          >
+            {showSearch && (
+              <CommandInput
+                placeholder={resolvedSearchPlaceholder}
+                className="shrink-0"
+                value={search}
+                onValueChange={setSearch}
+              />
+            )}
+            <CommandList ref={highlight.listRef}>
+              {filtered.length === 0 ? (
+                <CommandEmpty>{resolvedEmptyText}</CommandEmpty>
+              ) : (
+                <CommandGroup>
+                  {filtered.map((option) => (
+                    <CommandItem
+                      key={option.value}
+                      value={option.value}
+                      disabled={option.disabled}
+                      onSelect={handleSelect}
+                    >
+                      <span className="truncate">{option.label}</span>
+                      {option.count != null && (
+                        <span className="ml-auto text-xs tabular-nums text-muted-foreground">
+                          {option.count}
+                        </span>
+                      )}
+                      {option.value === value && (
+                        <Check className={cn('h-4 w-4 shrink-0', option.count != null ? 'ml-2' : 'ml-auto')} />
+                      )}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+            </CommandList>
+          </Command>
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
+FilterMenu.displayName = 'FilterMenu'

package/src/components/forms/mask-input/index.tsx

@@ -458,7 +458,7 @@ const MaskInput = React.forwardRef<HTMLInputElement, MaskInputProps>(
         ref={composedRef}
         value={displayValue}
         className={cn(
-          "flex h-10 w-full rounded-[var(--radius)] border border-input bg-transparent px-3 py-2 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+          "flex h-10 w-full rounded-[var(--radius)] border border-border bg-transparent px-3 py-2 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
           className
         )}
         onChange={handleChange}

package/src/components/forms/segmented-input/index.tsx

@@ -258,7 +258,7 @@ const SegmentedInput = React.forwardRef<HTMLDivElement, SegmentedInputProps>(
           data-active={isActive ? "" : undefined}
           data-filled={char ? "" : undefined}
           className={cn(
-            "relative flex items-center justify-center border-y border-r border-input text-center text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md",
+            "relative flex items-center justify-center border-y border-r border-border text-center text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md",
             "focus-visible:outline-none focus-visible:z-10 focus-visible:ring-1 focus-visible:ring-ring",
             "disabled:cursor-not-allowed disabled:opacity-50",
             fluid ? `flex-1 min-w-0 aspect-square ${sizeVariants[size]}` : sizeVariants[size],

package/src/components/forms/tags-input/index.tsx

@@ -481,7 +481,7 @@ const TagsInput = React.forwardRef<HTMLDivElement, TagsInputRootProps>(
           data-invalid={isInvalidInput ? "" : undefined}
           data-readonly={readOnly ? "" : undefined}
           className={cn(
-            "flex flex-wrap items-center gap-1.5 rounded-[var(--radius)] border border-input bg-transparent px-2 py-1.5 text-sm shadow-sm transition-colors",
+            "flex flex-wrap items-center gap-1.5 rounded-[var(--radius)] border border-border bg-transparent px-2 py-1.5 text-sm shadow-sm transition-colors",
             "focus-within:ring-1 focus-within:ring-ring",
             disabled && "cursor-not-allowed opacity-50",
             className

package/src/components/index.ts

@@ -207,6 +207,12 @@ export { Calendar, CalendarDayButton } from './data/calendar';
 export { DatePicker, DateRangePicker } from './data/calendar';
 export type { DatePickerProps, DateRangePickerProps, DateRange } from './data/calendar';
 export { Toggle, toggleVariants } from './data/toggle';
+export { FilterBar } from './layout/filter-bar';
+export type { FilterBarProps } from './layout/filter-bar';
+export { FilterButton } from './forms/filter-button';
+export { FilterMenu } from './forms/filter-menu';
+export type { FilterMenuProps, FilterMenuOption } from './forms/filter-menu';
+export type { FilterButtonProps } from './forms/filter-button';
 export { ToggleGroup, ToggleGroupItem } from './data/toggle-group';
 export { AvatarGroup } from './data/avatar-group';
 export type { AvatarGroupProps } from './data/avatar-group';

package/src/components/layout/filter-bar/index.tsx

@@ -0,0 +1,48 @@
+"use client"
+
+import * as React from 'react'
+
+import { cn } from '../../../lib/utils'
+
+export interface FilterBarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * What a row that does not fit does.
+   *
+   * `wrap` (default) drops controls onto a second line — right for a filter row
+   * above a result list, where every control should stay reachable.
+   * `scroll` keeps one line and scrolls it — right under a header, where a
+   * second line would push the content down.
+   */
+  overflow?: 'wrap' | 'scroll'
+  /**
+   * Row height, any CSS length. Every control inside reads it, so a toolbar
+   * lines up without anyone restyling a neighbour's component.
+   * @default '2.375rem'
+   */
+  height?: string
+}
+
+/**
+ * The row a set of filter controls sits in.
+ *
+ * It owns two things the controls cannot own individually: the shared height,
+ * and the container the pills measure themselves against so their labels
+ * collapse when THIS ROW is tight rather than when the window is.
+ *
+ * Both product frontends were missing exactly this piece, and paid for it by
+ * restyling whatever component happened to be next in the row — `SelectTrigger`
+ * in one, `Button size="sm"` in the other — to make the heights agree.
+ */
+export const FilterBar = React.forwardRef<HTMLDivElement, FilterBarProps>(
+  ({ className, overflow = 'wrap', height, style, ...props }, ref) => (
+    <div
+      ref={ref}
+      data-slot="filter-bar"
+      data-overflow={overflow}
+      className={cn('filter-bar', className)}
+      style={height ? ({ '--filter-control-h': height, ...style } as React.CSSProperties) : style}
+      {...props}
+    />
+  )
+)
+FilterBar.displayName = 'FilterBar'

package/src/components/navigation/command/index.tsx

@@ -16,7 +16,7 @@ const Command = React.forwardRef<
   <CommandPrimitive
     ref={ref}
     className={cn(
-      "flex h-full w-full flex-col rounded-[var(--radius-popover)] bg-popover text-popover-foreground",
+      "flex h-full min-h-0 w-full flex-col rounded-[var(--radius-popover)] bg-popover text-popover-foreground",
       className
     )}
     {...props}
@@ -62,45 +62,24 @@ CommandInput.displayName = CommandPrimitive.Input.displayName
 const CommandList = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.List>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
->(({ className, style, ...props }, ref) => {
-  const listRef = React.useRef<React.ElementRef<typeof CommandPrimitive.List> | null>(null)
-
-  // The element is needed locally (for the cssText fix below) AND by the
-  // caller, so it is captured and forwarded in one callback. useImperativeHandle
-  // cannot be used here: it must produce a non-null handle, and the element is
-  // genuinely null until the primitive mounts.
-  const setRef = React.useCallback(
-    (node: React.ElementRef<typeof CommandPrimitive.List> | null) => {
-      listRef.current = node
-      if (typeof ref === 'function') {
-        ref(node)
-      } else if (ref) {
-        ref.current = node
-      }
-    },
-    [ref]
-  )
-
-  React.useEffect(() => {
-    if (listRef.current) {
-      listRef.current.style.cssText += 'max-height: 300px !important; overflow-y: auto !important; overflow-x: hidden !important;'
-    }
-  }, [])
-
-  return (
-    <CommandPrimitive.List
-      ref={setRef}
-      className={cn("max-h-[300px] overflow-y-auto overflow-x-hidden", className)}
-      style={{
-        maxHeight: '300px',
-        overflowY: 'auto',
-        overflowX: 'hidden',
-        ...style
-      }}
-      {...props}
-    />
-  )
-})
+>(({ className, style, ...props }, ref) => (
+  // THIS ELEMENT IS THE SCROLLER, and must stay it: cmdk moves the highlight
+  // with `scrollIntoView({ block: 'nearest' })`, which acts on the item's
+  // nearest scrollable ancestor. Cap the height here — `.popover-scroll-region`
+  // owns the rule — never on a wrapper, or the arrow keys walk the highlight
+  // out of view.
+  //
+  // Raise or lower the comfortable ceiling with `--popover-scroll-max`. Staying
+  // inside the WINDOW is the panel's job (`.popover-panel`), and this element
+  // shrinks to whatever the panel has left. (`--cmdk-list-height` is cmdk's
+  // measurement of the content, not a constraint — it caps nothing.)
+  <CommandPrimitive.List
+    ref={ref}
+    className={cn("popover-scroll-region", className)}
+    style={style}
+    {...props}
+  />
+))
 
 CommandList.displayName = CommandPrimitive.List.displayName