@djangocfg/ui-core 2.1.557 → 2.1.559

package/README.md

@@ -51,7 +51,7 @@ 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 · FilterButton |
+| `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 |
@@ -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.557",
+  "version": "2.1.559",
   "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.557",
+    "@djangocfg/i18n": "^2.1.559",
     "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.557",
-    "@djangocfg/i18n": "^2.1.557",
-    "@djangocfg/typescript-config": "^2.1.557",
+    "@djangocfg/eslint-config": "^2.1.559",
+    "@djangocfg/i18n": "^2.1.559",
+    "@djangocfg/typescript-config": "^2.1.559",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

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/index.ts

@@ -210,6 +210,8 @@ 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';

package/src/components/select/combobox-async.tsx

@@ -12,7 +12,7 @@ import {
 } from '../navigation/command';
 import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
 import { SELECT_TRIGGER_CLASS } from './trigger';
-import { useHighlight } from './use-highlight';
+import { useHighlight } from '../../hooks';
 
 export interface ComboboxAsyncOption {
   value: string

package/src/components/select/combobox.tsx

@@ -4,7 +4,7 @@ import { Check, ChevronsUpDown } from 'lucide-react';
 import * as React from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../hooks';
+import { useStoredValue, type StorageType, type UseStoredValueOptions, useHighlight } from '../../hooks';
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
 import { Button } from '../forms/button';
@@ -13,7 +13,6 @@ import {
 } from '../navigation/command';
 import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
 import { SELECT_TRIGGER_CLASS } from './trigger';
-import { useHighlight } from './use-highlight';
 
 export interface ComboboxOption {
   value: string

package/src/components/select/country-select.tsx

@@ -16,7 +16,7 @@ import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
 import { ScrollArea } from '../layout/scroll-area';
 import { Flag } from '../specialized/flag';
 import { SELECT_TRIGGER_MULTI_CLASS } from './trigger';
-import { useHighlight } from './use-highlight';
+import { useHighlight } from '../../hooks';
 
 export interface CountryOption {
   code: TCountryCode;

package/src/components/select/language-select.tsx

@@ -17,7 +17,7 @@ import { Input } from '../forms/input';
 import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
 import { ScrollArea } from '../layout/scroll-area';
 import { SELECT_TRIGGER_CLASS } from './trigger';
-import { useHighlight } from './use-highlight';
+import { useHighlight } from '../../hooks';
 
 export interface LanguageOption {
   code: TLanguageCode;

package/src/hooks/dom/index.ts

@@ -16,3 +16,4 @@ export { useResizeObserver } from './useResizeObserver';
 export type { Size } from './useResizeObserver';
 export { useFormReset } from './useFormReset';
 export type { UseFormResetParams } from './useFormReset';
+export { useHighlight } from './useHighlight';

package/src/styles/css/presets/dense.css

@@ -15,6 +15,18 @@
   --radius-2xl: calc(0.25rem + 8px);
   --radius-3xl: calc(0.25rem + 12px);
   --radius-4xl: calc(0.25rem + 16px);
+  /* Type scale — a notch tighter than every other preset, which is the whole
+     point of this one. It previously set radii and colours only, so "dense"
+     rendered text at exactly the same size as the rest: the name promised a
+     density the tokens never delivered.
+     In `:root` only; a size does not change with the theme. */
+  --font-size-base: 0.75rem;
+  --font-size-sm: 0.6875rem;
+  --font-size-xs: 0.625rem;
+  --font-size-lg: 0.875rem;
+  --font-size-xl: 1rem;
+  --line-height-base: 1.4;
+
 }
 
 .dark {

package/src/styles/css/presets/ios.css

@@ -57,6 +57,18 @@
   --radius-2xl: calc(0.75rem + 8px);
   --radius-3xl: calc(0.75rem + 12px);
   --radius-4xl: calc(0.75rem + 16px);
+  /* Type scale. Lives in `:root` only — a size is not a colour and does not
+     change with the theme; `macos`/`windows` duplicate it into `.dark`, which
+     is two places to edit for one value.
+     Without these a preset silently inherits base.css (14px body / 13px
+     `text-sm`) while `macos` renders 13/12, so the same component measured a
+     pixel apart depending on which preset an app loaded. */
+  --font-size-base: 0.8125rem;
+  --font-size-sm: 0.75rem;
+  --font-size-xs: 0.6875rem;
+  --font-size-lg: 0.9375rem;
+  --font-size-xl: 1.0625rem;
+
 }
 
 .dark {

package/src/styles/css/presets/soft.css

@@ -23,6 +23,18 @@
   --radius-2xl: calc(1rem + 8px);
   --radius-3xl: calc(1rem + 12px);
   --radius-4xl: calc(1rem + 16px);
+  /* Type scale. Lives in `:root` only — a size is not a colour and does not
+     change with the theme; `macos`/`windows` duplicate it into `.dark`, which
+     is two places to edit for one value.
+     Without these a preset silently inherits base.css (14px body / 13px
+     `text-sm`) while `macos` renders 13/12, so the same component measured a
+     pixel apart depending on which preset an app loaded. */
+  --font-size-base: 0.8125rem;
+  --font-size-sm: 0.75rem;
+  --font-size-xs: 0.6875rem;
+  --font-size-lg: 0.9375rem;
+  --font-size-xl: 1.0625rem;
+
 }
 
 .dark {