@skyhook-io/k8s-ui 1.8.7 → 1.8.9

package/src/components/workload/ResourceDetailDrawer.tsx

@@ -1,5 +1,8 @@
-import { useState, useCallback, useEffect, useRef, type ReactNode } from 'react'
-import { TRANSITION_DRAWER } from '../../utils/animation'
+import { useState, useCallback, useEffect, useLayoutEffect, useReducer, useRef, type ReactNode } from 'react'
+import {
+  DURATION_DRAWER_MORPH,
+  EASE_DRAWER_MORPH,
+} from '../../utils/animation'
 import { clsx } from 'clsx'
 import type { SelectedResource } from '../../types'
 import { useDockReservedHeight } from '../dock/DockContext'
@@ -16,8 +19,13 @@ interface ResourceDetailDrawerProps {
   expanded?: boolean
   /** Called when user clicks collapse in expanded mode */
   onCollapse?: () => void
-  /** Called when user clicks expand button */
-  onExpand?: (resource: SelectedResource) => void
+  /** Called when user clicks expand button. `opts.yaml` is true when expanding
+   *  from the drawer's YAML view, so the host can open the full view on YAML. */
+  onExpand?: (resource: SelectedResource, opts?: { yaml?: boolean }) => void
+  /** Whether the expanded view can collapse back to a side drawer. False on
+   *  mobile (no room for a drawer) — the collapse-to-drawer control is hidden
+   *  there and the host's onCollapse should close instead. Default true. */
+  canCollapseToDrawer?: boolean
   /** Navigate to another resource within expanded WorkloadView */
   onNavigateToResource?: (resource: SelectedResource) => void
   /** Height of the host app's top navigation bar in px (default: 49) */
@@ -28,9 +36,16 @@ interface ResourceDetailDrawerProps {
   children: (props: {
     resource: SelectedResource
     expanded: boolean
+    /** false on the outgoing layer mid-transition — suspend shortcuts/interaction */
+    active: boolean
     initialTab?: 'detail' | 'yaml'
     onClose: () => void
-    onExpand?: () => void
+    onExpand?: (opts?: { yaml?: boolean }) => void
+    /** Signal (hover/press the expand control) that expand is likely — pre-mounts
+     *  the heavy fullscreen layer invisibly so the click starts the morph instantly. */
+    onExpandIntent?: () => void
+    /** Intent withdrawn (pointer left the expand control) — discard the pre-mount. */
+    onCancelExpandIntent?: () => void
     onBack?: () => void
     onNavigateToResource?: (resource: SelectedResource) => void
     onCollapseToDrawer?: () => void
@@ -52,18 +67,101 @@ function getDefaultWidth(kind: string): number {
   return WIDE_KINDS.has(kind.toLowerCase()) ? WIDE_WIDTH : DEFAULT_WIDTH
 }
 
-export function ResourceDetailDrawer({ resource, onClose, onNavigate, initialTab, isOpen = true, expanded, onCollapse, onExpand, onNavigateToResource, headerHeight: headerHeightProp, leftOffset = 0, children }: ResourceDetailDrawerProps) {
+function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(
+    () => typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches,
+  )
+  useEffect(() => {
+    const mq = window.matchMedia?.('(prefers-reduced-motion: reduce)')
+    if (!mq) return
+    const onChange = () => setReduced(mq.matches)
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [])
+  return reduced
+}
+
+export function ResourceDetailDrawer({ resource, onClose, onNavigate, initialTab, isOpen = true, expanded, onCollapse, onExpand, canCollapseToDrawer = true, onNavigateToResource, headerHeight: headerHeightProp, leftOffset = 0, children }: ResourceDetailDrawerProps) {
   const [drawerWidth, setDrawerWidth] = useState(() => getDefaultWidth(resource.kind))
   const [isResizing, setIsResizing] = useState(false)
   const resizeStartX = useRef(0)
   const resizeStartWidth = useRef(getDefaultWidth(resource.kind))
+  const containerRef = useRef<HTMLDivElement>(null)
+  const prefersReducedMotion = usePrefersReducedMotion()
+
+  // Expand/collapse crossfade. During the window we mount BOTH the drawer and
+  // full-screen layouts, each pinned to its own width (so neither reflows or
+  // squashes), and crossfade opacity while the container width (the frame)
+  // animates between them.
+  //
+  // `settledExpanded` is the last finished state. While it differs from the
+  // incoming `expanded` prop we're mid-transition: render both layers, fade
+  // `crossfadeArmed` 0→1 once a start frame has painted, then settle.
+  const settledExpanded = useRef(!!expanded)
+  const [crossfadeArmed, setCrossfadeArmed] = useState(false)
+  const [fullWidthPx, setFullWidthPx] = useState<number | null>(null)
+  const [, forceSettle] = useReducer((c: number) => c + 1, 0)
+  const transitioning = settledExpanded.current !== !!expanded
 
-  // Detect collapse direction: was expanded last render, now not.
-  // Width snaps instantly on collapse (0ms) so content and size match.
-  // Expand keeps the nice 300ms width animation via TRANSITION_DRAWER.
-  const wasExpanded = useRef(!!expanded)
-  const isCollapsing = wasExpanded.current && !expanded
-  wasExpanded.current = !!expanded
+  // Pre-mount: hovering/pressing the expand control mounts the heavy fullscreen
+  // layer invisibly ahead of the click, so the click reuses it (same key) and the
+  // morph's first frames aren't competing with the layer's mount cost.
+  const [prewarmExpand, setPrewarmExpand] = useState(false)
+
+  const measureFullWidth = useCallback(() => {
+    const el = containerRef.current
+    const parent = el?.offsetParent as HTMLElement | null
+    const measured = parent ? parent.clientWidth - leftOffset : el?.clientWidth
+    if (measured && measured > 0) setFullWidthPx(measured)
+  }, [leftOffset])
+
+  const handleExpandIntent = useCallback(() => {
+    if (expanded || transitioning) return
+    measureFullWidth()
+    setPrewarmExpand(true)
+  }, [expanded, transitioning, measureFullWidth])
+
+  const handleCancelExpandIntent = useCallback(() => {
+    if (transitioning || expanded) return
+    setPrewarmExpand(false)
+  }, [transitioning, expanded])
+
+  useLayoutEffect(() => {
+    if (settledExpanded.current === !!expanded) return
+    if (prefersReducedMotion) {
+      settledExpanded.current = !!expanded
+      setPrewarmExpand(false)
+      forceSettle()
+      return
+    }
+    // Pin the full-screen layer to the measured expanded width so its content
+    // lays out at its final width from the first frame (no live reflow).
+    measureFullWidth()
+    // The prewarm layer (if any) becomes the real transition layer now (reused by key).
+    setPrewarmExpand(false)
+    // Double-rAF so the incoming layer's mount+paint lands BEFORE the motion starts
+    // (else it drops frames in the first third). Prewarm keeps the heavy mount off
+    // the click path; these two frames are then cheap (the layer's already there).
+    setCrossfadeArmed(false)
+    let raf2 = 0
+    let timer = 0
+    const arm = () => {
+      setCrossfadeArmed(true)
+      timer = window.setTimeout(() => {
+        settledExpanded.current = !!expanded
+        setCrossfadeArmed(false)
+        forceSettle()
+      }, DURATION_DRAWER_MORPH)
+    }
+    const raf1 = requestAnimationFrame(() => {
+      raf2 = requestAnimationFrame(arm)
+    })
+    return () => {
+      cancelAnimationFrame(raf1)
+      cancelAnimationFrame(raf2)
+      clearTimeout(timer)
+    }
+  }, [expanded, prefersReducedMotion, measureFullWidth])
 
   // Reset drawer width when resource kind changes
   useEffect(() => {
@@ -72,14 +170,20 @@ export function ResourceDetailDrawer({ resource, onClose, onNavigate, initialTab
     resizeStartWidth.current = w
   }, [resource.kind])
 
-  // Resize handlers (disabled when expanded)
+  // Drop a pending prewarm if the drawer closes or the target resource changes —
+  // its hover intent is stale, and a reopened drawer shouldn't pre-mount unbidden.
+  useEffect(() => {
+    setPrewarmExpand(false)
+  }, [isOpen, resource.kind, resource.namespace, resource.name])
+
+  // Resize handlers (disabled when expanded or mid-transition)
   const handleResizeStart = useCallback((e: React.MouseEvent) => {
-    if (expanded) return
+    if (expanded || transitioning) return
     e.preventDefault()
     setIsResizing(true)
     resizeStartX.current = e.clientX
     resizeStartWidth.current = drawerWidth
-  }, [drawerWidth, expanded])
+  }, [drawerWidth, expanded, transitioning])
 
   useEffect(() => {
     if (!isResizing) return
@@ -114,27 +218,72 @@ export function ResourceDetailDrawer({ resource, onClose, onNavigate, initialTab
   const headerHeight = headerHeightProp ?? 49
   const dockInset = useDockReservedHeight()
 
+  // Width animates during expand/collapse, but snaps during manual resize and
+  // when the user prefers reduced motion.
+  const animateWidth = !isResizing && !prefersReducedMotion
+
+  // During the pre-mount frames (transitioning but not yet armed) hold the frame
+  // at its START width so the width transition fires only once the incoming
+  // layer has painted; otherwise it snaps to the target.
+  const fullW = `calc(100% - ${leftOffset}px)`
+  const startWidth = settledExpanded.current ? fullW : drawerWidth
+  const targetWidth = expanded ? fullW : drawerWidth
+  const containerWidth = transitioning && !crossfadeArmed ? startWidth : targetWidth
+
+  const renderLayer = (layerExpanded: boolean, active: boolean) =>
+    children({
+      resource,
+      expanded: layerExpanded,
+      active,
+      initialTab,
+      onClose,
+      onExpand: onExpand ? (opts) => onExpand(resource, opts) : undefined,
+      onExpandIntent: onExpand ? handleExpandIntent : undefined,
+      onCancelExpandIntent: onExpand ? handleCancelExpandIntent : undefined,
+      onBack: onCollapse ? () => onCollapse() : undefined,
+      onNavigateToResource: handleNavigate,
+      // Hidden on mobile (no drawer to collapse to) — the host routes the
+      // back/close control through onCollapse instead.
+      onCollapseToDrawer: (canCollapseToDrawer && onCollapse) ? () => onCollapse() : undefined,
+    })
+
+  // While transitioning render both layers (outgoing = settled state, incoming
+  // = target). Keying by expanded-ness keeps the incoming layer's React
+  // identity stable into idle, so it survives (state intact) while only the
+  // outgoing layer unmounts when the window ends. While prewarming (collapsed,
+  // intent signalled) also mount the expanded layer invisibly — keyed 'expanded'
+  // so it's reused (not remounted) when the real expand starts.
+  const showPrewarmLayer = prewarmExpand && isOpen && !transitioning && !expanded
+  const layerExpandedValues = transitioning ? [true, false] : showPrewarmLayer ? [false, true] : [!!expanded]
+
   return (
     <div
+      ref={containerRef}
       className={clsx(
-        'absolute right-0 bg-theme-surface border-l border-theme-border flex flex-col shadow-drawer z-40',
-        TRANSITION_DRAWER,
+        'absolute right-0 bg-theme-surface border-l border-theme-border flex flex-col z-40',
+        // Clip the wider layer only while morphing; keep overflow visible at idle
+        // so drawer popovers/tooltips aren't clipped.
+        transitioning && 'overflow-hidden',
+        // No drawer shadow in fullscreen — it's a full page, not a floating panel.
+        !expanded && 'shadow-drawer',
         isOpen
           ? 'translate-x-0 opacity-100'
           : 'translate-x-full opacity-0',
         expanded && '!border-l-0',
       )}
       style={{
-        width: expanded ? `calc(100% - ${leftOffset}px)` : drawerWidth,
+        width: containerWidth,
         top: headerHeight,
         height: `calc(100% - ${headerHeight}px - ${dockInset}px)`,
-        // Collapse is instant — no animation, content and width snap together.
-        // Expand + slide-in/out animate via TRANSITION_DRAWER class.
-        ...(isCollapsing && { transition: 'none' }),
+        // Inline so the morph duration/easing is controlled precisely (and stays
+        // in lockstep with the crossfade + JS window). Width only animates when
+        // not resizing / reduced-motion.
+        transition: `translate ${DURATION_DRAWER_MORPH}ms ${EASE_DRAWER_MORPH}, opacity ${DURATION_DRAWER_MORPH}ms ${EASE_DRAWER_MORPH}${animateWidth ? `, width ${DURATION_DRAWER_MORPH}ms ${EASE_DRAWER_MORPH}` : ''}`,
+        willChange: 'transform, width',
       }}
     >
-      {/* Resize handle — hidden when expanded or on mobile */}
-      {!expanded && (
+      {/* Resize handle — hidden when expanded or mid-transition or on mobile */}
+      {!expanded && !transitioning && (
         <div
           onMouseDown={handleResizeStart}
           className={clsx(
@@ -145,15 +294,49 @@ export function ResourceDetailDrawer({ resource, onClose, onNavigate, initialTab
         />
       )}
 
-      {children({
-        resource,
-        expanded: !!expanded,
-        initialTab,
-        onClose,
-        onExpand: onExpand ? () => onExpand(resource) : undefined,
-        onBack: onCollapse ? () => onCollapse() : undefined,
-        onNavigateToResource: handleNavigate,
-        onCollapseToDrawer: onCollapse ? () => onCollapse() : undefined,
+      {layerExpandedValues.map((layerExpanded) => {
+        if (!transitioning) {
+          // Prewarm: the expanded layer mounted invisibly ahead of the click.
+          // Pinned at full width + inert + opacity 0 so its mount cost is paid now,
+          // off-screen, and it's reused (same key) when the morph actually starts.
+          if (showPrewarmLayer && layerExpanded) {
+            return (
+              <div
+                key="expanded"
+                aria-hidden
+                inert
+                className="absolute top-0 bottom-0 right-0 overflow-hidden pointer-events-none opacity-0"
+                style={{ width: fullWidthPx ?? `calc(100% - ${leftOffset}px)` }}
+              >
+                {renderLayer(true, false)}
+              </div>
+            )
+          }
+          // Idle (or the visible collapsed layer during prewarm): fills the container.
+          return (
+            <div key={layerExpanded ? 'expanded' : 'collapsed'} className="absolute inset-0">
+              {renderLayer(layerExpanded, true)}
+            </div>
+          )
+        }
+        const isIncoming = layerExpanded === !!expanded
+        return (
+          <div
+            key={layerExpanded ? 'expanded' : 'collapsed'}
+            className="absolute top-0 bottom-0 right-0 overflow-hidden pointer-events-none"
+            style={{
+              width: layerExpanded ? (fullWidthPx ?? `calc(100% - ${leftOffset}px)`) : drawerWidth,
+              opacity: isIncoming ? (crossfadeArmed ? 1 : 0) : (crossfadeArmed ? 0 : 1),
+              transition: `opacity ${DURATION_DRAWER_MORPH}ms ${EASE_DRAWER_MORPH}`,
+              willChange: 'opacity',
+            }}
+            aria-hidden={!isIncoming}
+          >
+            {/* Both layers inactive mid-crossfade — shortcuts shouldn't dispatch
+                during the animation; the settled layer owns them once idle. */}
+            {renderLayer(layerExpanded, false)}
+          </div>
+        )
       })}
     </div>
   )

package/src/components/workload/WorkloadView.tsx

@@ -71,10 +71,17 @@ interface WorkloadViewProps {
   onCollapseToDrawer?: () => void
   /** false = collapsed drawer mode, true (default) = full expanded mode */
   expanded?: boolean
+  /** false on the outgoing layer during an expand/collapse crossfade — suspend
+   *  keyboard shortcuts so the invisible layer doesn't capture them (default true) */
+  active?: boolean
   /** Close the drawer (collapsed mode) */
   onClose?: () => void
-  /** Expand from drawer to full view */
-  onExpand?: () => void
+  /** Expand from drawer to full view. `opts.yaml` true when expanding from the
+   *  drawer's YAML view so the full view opens on the YAML tab (edits carry over). */
+  onExpand?: (opts?: { yaml?: boolean }) => void
+  /** Hover/press the expand control = likely expand → pre-mount the full view. */
+  onExpandIntent?: () => void
+  onCancelExpandIntent?: () => void
   /** Initial view tab — 'yaml' opens YAML directly */
   initialTab?: 'detail' | 'yaml'
   /** API group for CRD resources */
@@ -248,8 +255,11 @@ export function WorkloadView({
   onNavigateToResource,
   onCollapseToDrawer,
   expanded = true,
+  active = true,
   onClose,
   onExpand,
+  onExpandIntent,
+  onCancelExpandIntent,
   initialTab,
   group,
   breadcrumb,
@@ -524,9 +534,12 @@ export function WorkloadView({
       keys: 'Escape',
       description: expanded ? 'Go back' : 'Close drawer',
       category: expanded ? 'Navigation' as const : 'Drawer' as const,
-      scope: expanded ? 'global' as const : 'drawer' as const,
+      // 'drawer' (top priority) in both modes so when this is the fullscreen
+      // overlay its Escape unambiguously wins over any background view's Escape
+      // (incl. another 'global'-scope WorkloadView mounted underneath).
+      scope: 'drawer' as const,
       handler: expanded ? onBack : () => onClose?.(),
-      enabled: true,
+      enabled: active,
     },
     {
       id: 'drawer-yaml',
@@ -535,7 +548,7 @@ export function WorkloadView({
       category: 'Drawer' as const,
       scope: 'drawer' as const,
       handler: () => switchView(true),
-      enabled: !expanded,
+      enabled: active && !expanded,
     },
     {
       id: 'drawer-detail',
@@ -544,9 +557,9 @@ export function WorkloadView({
       category: 'Drawer' as const,
       scope: 'drawer' as const,
       handler: () => switchView(false),
-      enabled: !expanded,
+      enabled: active && !expanded,
     },
-  ], [expanded, onBack, onClose, switchView]))
+  ], [active, expanded, onBack, onClose, switchView]))
 
   const status = getResourceStatus(apiKind, resource)
 
@@ -586,7 +599,12 @@ export function WorkloadView({
             <div className="flex items-center gap-1">
               {onExpand && (
                 <button
-                  onClick={onExpand}
+                  onClick={() => onExpand({ yaml: showYaml })}
+                  // Pre-mount the fullscreen view on hover/press so the click starts
+                  // the morph instantly (its heavy mount is already paid for).
+                  onPointerEnter={onExpandIntent}
+                  onPointerDown={onExpandIntent}
+                  onPointerLeave={onCancelExpandIntent}
                   className="p-1.5 text-theme-text-secondary hover:text-theme-text-primary hover:bg-theme-elevated rounded"
                   title="Open full view"
                 >

package/src/filter-state/filter-state-core.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest'
+import {
+  decodeFilters,
+  defineFilterSchema,
+  withField,
+  withToggle,
+  withCleared,
+  isFilterActive,
+} from './filter-state-core'
+
+const schema = defineFilterSchema({
+  ns: { param: 'namespace', type: 'set' },
+  sev: { param: 'severity', type: 'set' },
+  q: { param: 'q', type: 'text' },
+  group: { param: 'group', type: 'single', default: 'none' },
+  managed: { param: 'managed', type: 'boolean' },
+})
+
+const p = (s = '') => new URLSearchParams(s)
+
+describe('filter-state core', () => {
+  it('decodes params by type', () => {
+    const v = decodeFilters(schema, p('namespace=argocd,default&severity=high&q=foo&managed=1'))
+    expect([...v.ns]).toEqual(['argocd', 'default'])
+    expect([...v.sev]).toEqual(['high'])
+    expect(v.q).toBe('foo')
+    expect(v.managed).toBe(true)
+  })
+
+  it('applies string defaults when the param is absent', () => {
+    const v = decodeFilters(schema, p(''))
+    expect(v.group).toBe('none')
+    expect(v.q).toBe('')
+    expect(v.managed).toBe(false)
+    expect(v.ns.size).toBe(0)
+  })
+
+  it('toggles a set member and omits the param when empty (empty = all)', () => {
+    const added = withToggle(schema, p(''), 'ns', 'argocd')
+    expect(added.toString()).toBe('namespace=argocd')
+    const removed = withToggle(schema, added, 'ns', 'argocd')
+    expect(removed.toString()).toBe('')
+  })
+
+  it('composes successive toggles (each sees the previous result)', () => {
+    let params = p('')
+    params = withToggle(schema, params, 'ns', 'a')
+    params = withToggle(schema, params, 'ns', 'b')
+    expect([...decodeFilters(schema, params).ns].sort()).toEqual(['a', 'b'])
+  })
+
+  it('withField replaces a set wholesale and clears when empty', () => {
+    const set = withField(schema, p('namespace=x'), 'ns', new Set(['a', 'b']))
+    expect([...decodeFilters(schema, set).ns]).toEqual(['a', 'b'])
+    expect(withField(schema, set, 'ns', new Set<string>()).toString()).toBe('')
+  })
+
+  it('omits a string param when equal to its default', () => {
+    expect(withField(schema, p(''), 'group', 'namespace').toString()).toBe('group=namespace')
+    expect(withField(schema, p('group=namespace'), 'group', 'none').toString()).toBe('')
+  })
+
+  it('encodes a boolean as =1 and omits false', () => {
+    expect(withField(schema, p(''), 'managed', true).toString()).toBe('managed=1')
+    expect(withField(schema, p('managed=1'), 'managed', false).toString()).toBe('')
+  })
+
+  it('clears one field or all schema fields, leaving unrelated params', () => {
+    const one = withCleared(schema, p('namespace=a&severity=high&keep=yes'), ['ns'])
+    const oneV = decodeFilters(schema, one)
+    expect(oneV.ns.size).toBe(0)
+    expect(oneV.sev.size).toBe(1)
+    expect(one.get('keep')).toBe('yes')
+    expect(withCleared(schema, p('namespace=a&severity=high&keep=yes')).toString()).toBe('keep=yes')
+  })
+
+  it('isFilterActive is true only when a field diverges from its default', () => {
+    expect(isFilterActive(schema, decodeFilters(schema, p('q=foo')))).toBe(true)
+    expect(isFilterActive(schema, decodeFilters(schema, p('group=none')))).toBe(false)
+    expect(isFilterActive(schema, decodeFilters(schema, p('')))).toBe(false)
+  })
+
+  it('writes set values sorted, so the URL is canonical regardless of order', () => {
+    const a = withToggle(schema, withToggle(schema, p(''), 'ns', 'zebra'), 'ns', 'alpha')
+    expect(a.get('namespace')).toBe('alpha,zebra')
+  })
+
+  it('decodes an empty string param (?group=) as the default', () => {
+    expect(decodeFilters(schema, p('group=')).group).toBe('none')
+    expect(decodeFilters(schema, p('q=')).q).toBe('')
+  })
+
+  it('defineFilterSchema rejects duplicate URL params', () => {
+    expect(() =>
+      defineFilterSchema({ a: { param: 'x', type: 'set' }, b: { param: 'x', type: 'set' } }),
+    ).toThrow(/duplicate/)
+  })
+})

package/src/filter-state/filter-state-core.ts

@@ -0,0 +1,138 @@
+// Pure URL <-> filter-state transforms. No React, no router, no window — just
+// URLSearchParams in, URLSearchParams / typed values out. This is the behavioral
+// contract every list view shares; keeping it pure makes it exhaustively
+// testable and keeps the React hook a thin wrapper.
+
+export interface FilterFieldDef {
+  /** URL query-param name. Stable — this is a durable, shareable public API. */
+  param: string
+  /**
+   * - 'set'     multi-select; comma-list. Empty ⇒ param omitted ⇒ "all" (no
+   *             narrowing). Values must not contain commas (k8s identifiers and
+   *             controlled enums never do). Written sorted, so the URL is
+   *             canonical regardless of selection order. Value: Set<string>.
+   * - 'text'    free-text search; written with history `replace` (no entry per
+   *             keystroke). Omitted when empty / equal to `default`. Value: string.
+   * - 'single'  single choice (enum / dropdown, incl. tri-state all|yes|no);
+   *             pushes a history entry. Omitted when equal to `default`. Value:
+   *             string.
+   * - 'boolean' two-state flag; `param=1` when true, omitted when false. For
+   *             three states use 'single' with an enum default. Value: boolean.
+   */
+  type: 'set' | 'text' | 'single' | 'boolean'
+  /** Default for 'text'/'single' (omitted from the URL when the value equals it). */
+  default?: string
+}
+
+export type FilterSchema = Record<string, FilterFieldDef>
+
+type FieldValue<F extends FilterFieldDef> = F['type'] extends 'set'
+  ? Set<string>
+  : F['type'] extends 'boolean'
+    ? boolean
+    : string
+
+export type FilterValues<S extends FilterSchema> = { [K in keyof S]: FieldValue<S[K]> }
+
+/** Keys of a schema whose field is one of the given kinds — for type-safe setters. */
+export type FieldKeysOfType<S extends FilterSchema, T extends FilterFieldDef['type']> = {
+  [K in keyof S]: S[K]['type'] extends T ? K : never
+}[keyof S]
+
+/**
+ * Identity helper that preserves literal types (so `values.x` is precisely typed)
+ * and validates the schema — duplicate URL params would silently clobber each
+ * other, so we fail loudly at module load.
+ */
+export function defineFilterSchema<const S extends FilterSchema>(schema: S): S {
+  const seen = new Set<string>()
+  for (const key in schema) {
+    const { param } = schema[key]
+    if (seen.has(param)) throw new Error(`defineFilterSchema: duplicate URL param "${param}"`)
+    seen.add(param)
+  }
+  return schema
+}
+
+export function decodeFilters<S extends FilterSchema>(schema: S, params: URLSearchParams): FilterValues<S> {
+  const out = {} as FilterValues<S>
+  for (const key in schema) {
+    const def = schema[key]
+    const raw = params.get(def.param)
+    if (def.type === 'set') {
+      ;(out[key] as Set<string>) = new Set((raw ?? '').split(',').filter(Boolean))
+    } else if (def.type === 'boolean') {
+      ;(out[key] as boolean) = raw === '1'
+    } else {
+      // text / single: an empty param (?f=) reads as the default, same as omission.
+      ;(out[key] as string) = raw ? raw : (def.default ?? '')
+    }
+  }
+  return out
+}
+
+/** Write one field into `params` in place. Read (decode) and write agree exactly. */
+function writeField(params: URLSearchParams, def: FilterFieldDef, value: Set<string> | string | boolean): void {
+  if (def.type === 'set') {
+    const set = value as Set<string>
+    if (set.size === 0) params.delete(def.param)
+    else params.set(def.param, [...set].sort().join(','))
+  } else if (def.type === 'boolean') {
+    if (value) params.set(def.param, '1')
+    else params.delete(def.param)
+  } else {
+    const str = value as string
+    if (!str || str === (def.default ?? '')) params.delete(def.param)
+    else params.set(def.param, str)
+  }
+}
+
+/** Return new params with one field set to `value`. */
+export function withField<S extends FilterSchema>(
+  schema: S,
+  params: URLSearchParams,
+  key: keyof S,
+  value: Set<string> | string | boolean,
+): URLSearchParams {
+  const next = new URLSearchParams(params)
+  writeField(next, schema[key], value)
+  return next
+}
+
+/** Return new params with one member added to / removed from a 'set' field. */
+export function withToggle<S extends FilterSchema>(
+  schema: S,
+  params: URLSearchParams,
+  key: keyof S,
+  value: string,
+): URLSearchParams {
+  const next = new URLSearchParams(params)
+  const cur = new Set((next.get(schema[key].param) ?? '').split(',').filter(Boolean))
+  if (cur.has(value)) cur.delete(value)
+  else cur.add(value)
+  writeField(next, schema[key], cur)
+  return next
+}
+
+/** Default (empty) value for a field, used to reset it. */
+export function emptyValue(def: FilterFieldDef): Set<string> | string | boolean {
+  return def.type === 'set' ? new Set<string>() : def.type === 'boolean' ? false : (def.default ?? '')
+}
+
+/** Return new params with the given schema fields cleared (all of them if omitted). */
+export function withCleared<S extends FilterSchema>(schema: S, params: URLSearchParams, keys?: (keyof S)[]): URLSearchParams {
+  const next = new URLSearchParams(params)
+  for (const key of keys ?? (Object.keys(schema) as (keyof S)[])) next.delete(schema[key].param)
+  return next
+}
+
+export function isFilterActive<S extends FilterSchema>(schema: S, values: FilterValues<S>): boolean {
+  for (const key in schema) {
+    const def = schema[key]
+    const v = values[key]
+    if (def.type === 'set' && (v as Set<string>).size > 0) return true
+    if (def.type === 'boolean' && (v as boolean)) return true
+    if ((def.type === 'text' || def.type === 'single') && (v as string) !== (def.default ?? '')) return true
+  }
+  return false
+}