npm - @lovett/ui - Versions diffs - 0.0.11 → 0.1.0 - Mend

@lovett/ui 0.0.11 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/dist/chunk-RBYWGBQ2.js +2752 -0
package/dist/chunk-RBYWGBQ2.js.map +1 -0
package/dist/index.d.ts +5402 -71
package/dist/index.js +21992 -11618
package/dist/index.js.map +1 -1
package/dist/rich-composer-impl-5NO443A6.js +1859 -0
package/dist/rich-composer-impl-5NO443A6.js.map +1 -0
package/dist/styles.css +1570 -0
package/dist/tokens.css +112 -0
package/package.json +8 -1
package/src/__tests__/avatar.test.tsx +272 -0
package/src/__tests__/bar-chart.test.tsx +809 -0
package/src/__tests__/board.test.tsx +420 -0
package/src/__tests__/chart-math.test.ts +922 -0
package/src/__tests__/chart-series.test.ts +339 -0
package/src/__tests__/code-block.test.tsx +134 -0
package/src/__tests__/display-popover.test.tsx +195 -0
package/src/__tests__/display-store.test.tsx +208 -0
package/src/__tests__/donut-chart.test.tsx +397 -0
package/src/__tests__/dropdown-menu.test.tsx +156 -2
package/src/__tests__/filter-menu.test.tsx +175 -0
package/src/__tests__/gauge-ring.test.tsx +233 -0
package/src/__tests__/line-chart.test.tsx +612 -0
package/src/__tests__/ranked-bars.test.tsx +343 -0
package/src/__tests__/remark-underline.test.ts +194 -0
package/src/__tests__/sparkline.test.tsx +368 -0
package/src/__tests__/stat-layer.test.tsx +271 -0
package/src/__tests__/stat-strip.test.tsx +175 -0
package/src/__tests__/status.test.tsx +293 -0
package/src/__tests__/tabs.test.tsx +303 -0
package/src/__tests__/token-shape.test.ts +132 -2
package/src/avatar.tsx +352 -0
package/src/bar-chart.tsx +1214 -0
package/src/board.tsx +658 -0
package/src/chart-frame.tsx +960 -0
package/src/chart-legend.tsx +304 -0
package/src/chart-tooltip.tsx +267 -0
package/src/code-block.tsx +62 -8
package/src/delta-chip.tsx +263 -0
package/src/detail/__tests__/activity-pane.test.tsx +186 -0
package/src/detail/__tests__/detail-chrome.test.tsx +134 -0
package/src/detail/__tests__/detail-surface.test.tsx +529 -0
package/src/detail/__tests__/field-row.test.tsx +357 -0
package/src/detail/activity-pane.tsx +507 -0
package/src/detail/calendar.tsx +355 -0
package/src/detail/detail-divider.tsx +261 -0
package/src/detail/detail-header.tsx +287 -0
package/src/detail/detail-menu.tsx +254 -0
package/src/detail/detail-surface.tsx +1110 -0
package/src/detail/field-list.tsx +196 -0
package/src/detail/field-row.tsx +1131 -0
package/src/detail/index.ts +58 -0
package/src/detail/segmented-choice.tsx +94 -0
package/src/detail/types.ts +129 -0
package/src/display-popover.tsx +487 -0
package/src/display-store.tsx +242 -0
package/src/donut-chart.tsx +988 -0
package/src/dropdown-menu.tsx +290 -19
package/src/filter-core/EXPORTS.md +85 -0
package/src/filter-core/__tests__/columns.test.ts +159 -0
package/src/filter-core/__tests__/faceting.test.ts +193 -0
package/src/filter-core/__tests__/filter-fns.test.ts +519 -0
package/src/filter-core/__tests__/operators.test.ts +235 -0
package/src/filter-core/__tests__/state.test.ts +268 -0
package/src/filter-core/__tests__/url.test.ts +350 -0
package/src/filter-core/columns.ts +134 -0
package/src/filter-core/date-utils.ts +38 -0
package/src/filter-core/examples/task-filter-columns.ts +121 -0
package/src/filter-core/faceting.ts +120 -0
package/src/filter-core/filter-fns.ts +335 -0
package/src/filter-core/index.ts +105 -0
package/src/filter-core/operators.ts +433 -0
package/src/filter-core/state.ts +280 -0
package/src/filter-core/types.ts +247 -0
package/src/filter-core/url.ts +261 -0
package/src/filter-dropdown.tsx +12 -0
package/src/filter-menu.tsx +649 -0
package/src/floating-drawer.tsx +19 -1
package/src/gauge-ring.tsx +435 -0
package/src/hue.ts +52 -0
package/src/index.ts +296 -0
package/src/kbd.tsx +27 -4
package/src/lib/chart.ts +866 -0
package/src/lib/focus.ts +43 -1
package/src/lib/layer-stack.ts +30 -3
package/src/lib/remark-underline.ts +443 -0
package/src/lib/series.ts +169 -0
package/src/line-chart.tsx +1176 -0
package/src/markdown.tsx +26 -7
package/src/modal.tsx +42 -18
package/src/progress-ledger.tsx +304 -0
package/src/ranked-bars.tsx +386 -0
package/src/segmented-pill.tsx +32 -9
package/src/sortable.tsx +315 -1
package/src/sparkline.tsx +416 -0
package/src/stat-card.tsx +376 -0
package/src/stat-strip.tsx +327 -0
package/src/status.tsx +215 -0
package/src/styles.css +1570 -0
package/src/tabs.tsx +206 -25
package/src/task-card.tsx +610 -0
package/src/thread/__tests__/comment-body-hostile.test.tsx +331 -0
package/src/thread/__tests__/comment-tree.test.ts +151 -0
package/src/thread/__tests__/emoji.test.ts +187 -0
package/src/thread/__tests__/fixtures/thread-fixture.ts +235 -0
package/src/thread/__tests__/link-preview-source.test.ts +120 -0
package/src/thread/__tests__/link-preview.test.tsx +600 -0
package/src/thread/__tests__/markdown-format.test.ts +82 -0
package/src/thread/__tests__/markdown-spec.test.ts +469 -0
package/src/thread/__tests__/relative-time.test.ts +71 -0
package/src/thread/__tests__/rich-composer.test.tsx +799 -0
package/src/thread/__tests__/scroll-caret.test.ts +58 -0
package/src/thread/__tests__/suggestion-list.test.tsx +648 -0
package/src/thread/__tests__/thread-scroll-ownership.test.tsx +88 -0
package/src/thread/__tests__/thread.test.tsx +662 -0
package/src/thread/__tests__/use-attachments.test.tsx +679 -0
package/src/thread/actions.tsx +196 -0
package/src/thread/attachments.tsx +1071 -0
package/src/thread/comment-body.tsx +148 -0
package/src/thread/comment-tree.ts +182 -0
package/src/thread/comment.tsx +915 -0
package/src/thread/composer-footer.tsx +125 -0
package/src/thread/composer.tsx +319 -0
package/src/thread/emoji.ts +283 -0
package/src/thread/index.ts +153 -0
package/src/thread/link-preview.tsx +341 -0
package/src/thread/markdown-format.ts +155 -0
package/src/thread/markdown-spec.ts +754 -0
package/src/thread/rail.tsx +372 -0
package/src/thread/reactions.tsx +415 -0
package/src/thread/relative-time.tsx +94 -0
package/src/thread/rich-composer-impl.tsx +1601 -0
package/src/thread/rich-composer.tsx +195 -0
package/src/thread/scroll-caret.ts +37 -0
package/src/thread/suggestion-list.tsx +182 -0
package/src/thread/thread.tsx +718 -0
package/src/thread/types.ts +218 -0
package/src/thread/use-attachments.ts +598 -0
package/src/thread/use-now.ts +73 -0
package/src/thread/use-thread.ts +316 -0
package/src/tokens.css +112 -0

package/src/dropdown-menu.tsx CHANGED Viewed

@@ -29,9 +29,33 @@
  * `--border`). Consumers can pass custom trigger content; the wrapper
  * applies the button-style classes unless `unstyled` is set.
  *
- * Focus stays on the trigger when the menu opens (menus do not steal
- * focus here; items are reached with Tab). Escape closes and refocuses the
- * trigger. Roving arrow-key focus is a follow-up.
+ * Keyboard model (ARIA APG "menu button", added 2026-09-06 — before this
+ * the menu had NO keyboard model at all: opening it left focus on the
+ * trigger, ArrowDown did nothing, and Tab walked off into the page behind
+ * while the menu stayed open):
+ *   • Opening moves focus INTO the menu — the first item, or the last when
+ *     the menu was opened with ArrowUp. A menu whose content is a small
+ *     form rather than a list of items (the keywords range-filter chip)
+ *     focuses its first focusable field instead, and the bare surface when
+ *     it has none.
+ *   • Up / Down / Home / End move between items on a ROVING TABINDEX — the
+ *     focused item is `0`, every other item `-1`, so the menu is one tab
+ *     stop. Movement wraps at both ends.
+ *   • Tab from an item closes the menu and hands focus back to the trigger,
+ *     so the browser's own sequential navigation continues from there.
+ *     Tab inside a form-shaped menu is left alone.
+ *   • Escape, item activation and outside-click all CLOSE and RESTORE focus
+ *     to the trigger (outside-click only when focus was still inside the
+ *     menu — otherwise the element you clicked keeps it). Dropping focus to
+ *     <body> here also broke Modal, which captures `document.activeElement`
+ *     as its restore target; a dialog opened from a menu item now restores
+ *     correctly because the trigger is focused before it mounts.
+ *   • Typeahead (jump to the item starting with a typed letter) is NOT
+ *     implemented — printable keys are left to the content, because menus
+ *     here legitimately host text inputs.
+ * Arrow keys are yielded to any target that owns them: text-entry fields
+ * and dnd-kit sortable handles (`aria-roledescription="sortable"`, the
+ * DataGrid column reorder handles).
  *
  * Token discipline: surface chrome is `POPOVER_SURFACE_STYLE` (shared with
  * Popover — internal `--popover` tokens are allowed inside packages/ui);
@@ -48,12 +72,15 @@ import {
   forwardRef,
   useCallback,
   useContext,
+  useEffect,
   useId,
   useMemo,
   useRef,
   useState,
   type ButtonHTMLAttributes,
+  type FocusEvent as ReactFocusEvent,
   type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
   type ReactNode,
   type RefObject,
 } from 'react'
@@ -73,11 +100,80 @@ import { POPOVER_SURFACE_STYLE } from './popover'
 type Align = AnchorAlign
 type Side = AnchorSide
+/** Where focus lands when the menu opens. */
+type InitialFocus = 'first' | 'last'
 interface DropdownMenuContextValue {
   open: boolean
   setOpen: (next: boolean) => void
+  /** Open (or, when already open, move focus into) the menu. */
+  openMenu: (initialFocus: InitialFocus) => void
+  /** Close, restoring focus to the trigger unless told not to. */
+  closeMenu: (options?: { restoreFocus?: boolean }) => void
   triggerRef: RefObject<HTMLButtonElement | null>
   contentId: string
+  initialFocusRef: RefObject<InitialFocus>
+  /** Content registers its edge-focus fn here so the trigger can reach it. */
+  focusEdgeRef: RefObject<((where: InitialFocus) => void) | null>
+}
+/* --------------------------------------------------------------------- *
+ * Roving-tabindex helpers. DOM-driven rather than a registration context:
+ * items arrive through Groups, through consumer wrappers (the DataGrid's
+ * sortable column rows), and through `children` this file never sees, so
+ * querying the live subtree is the only ordering that is always right.
+ * --------------------------------------------------------------------- */
+const MENU_ITEM_SELECTOR =
+  '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]'
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+function isEnabledItem(el: HTMLElement): boolean {
+  return (
+    !el.hasAttribute('disabled') &&
+    el.getAttribute('aria-disabled') !== 'true' &&
+    !el.hidden
+  )
+}
+function menuItemsIn(container: HTMLElement | null): HTMLElement[] {
+  if (!container) return []
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
+  ).filter(isEnabledItem)
+}
+/** Active item is the ONE tab stop; the rest are -1. Never a positive value. */
+function applyRoving(items: readonly HTMLElement[], activeIndex: number): void {
+  items.forEach((item, index) => {
+    item.tabIndex = index === activeIndex ? 0 : -1
+  })
+}
+/**
+ * Targets that own the arrow keys themselves — text entry (a menu is
+ * allowed to host a small form) and dnd-kit sortable handles, whose
+ * keyboard drag IS arrow keys.
+ */
+function ownsArrowKeys(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.closest('[aria-roledescription="sortable"]')) return true
+  if (target.isContentEditable) return true
+  const tag = target.tagName
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return true
+  if (tag === 'INPUT') {
+    const type = (target as HTMLInputElement).type
+    return type !== 'checkbox' && type !== 'radio' && type !== 'button'
+  }
+  return false
 }
 const DropdownMenuCtx = createContext<DropdownMenuContextValue | null>(null)
@@ -117,6 +213,9 @@ export function DropdownMenu({
   const generatedId = useId()
   const contentId = `dropdown-${generatedId.replace(/:/g, '')}`
+  const initialFocusRef = useRef<InitialFocus>('first')
+  const focusEdgeRef = useRef<((where: InitialFocus) => void) | null>(null)
   const setOpen = useCallback(
     (next: boolean) => {
       if (!isControlled) setUncontrolledOpen(next)
@@ -125,9 +224,40 @@ export function DropdownMenu({
     [isControlled, onOpenChange],
   )
+  const openMenu = useCallback(
+    (initialFocus: InitialFocus) => {
+      initialFocusRef.current = initialFocus
+      // Already open (ArrowDown on the trigger of an open menu): jump
+      // straight in, since the open effect will not fire again.
+      if (open) {
+        focusEdgeRef.current?.(initialFocus)
+        return
+      }
+      setOpen(true)
+    },
+    [open, setOpen],
+  )
+  const closeMenu = useCallback(
+    (options?: { restoreFocus?: boolean }) => {
+      setOpen(false)
+      if (options?.restoreFocus !== false) triggerRef.current?.focus()
+    },
+    [setOpen],
+  )
   const value = useMemo<DropdownMenuContextValue>(
-    () => ({ open, setOpen, triggerRef, contentId }),
-    [open, setOpen, contentId],
+    () => ({
+      open,
+      setOpen,
+      openMenu,
+      closeMenu,
+      triggerRef,
+      contentId,
+      initialFocusRef,
+      focusEdgeRef,
+    }),
+    [open, setOpen, openMenu, closeMenu, contentId],
   )
   return (
@@ -153,10 +283,10 @@ export const DropdownMenuTrigger = forwardRef<
   HTMLButtonElement,
   DropdownMenuTriggerProps
 >(function DropdownMenuTrigger(
-  { unstyled, className, onClick, children, ...rest },
+  { unstyled, className, onClick, onKeyDown, children, ...rest },
   forwardedRef,
 ) {
-  const { open, setOpen, triggerRef, contentId } =
+  const { open, openMenu, closeMenu, triggerRef, contentId } =
     useDropdownMenuCtx('DropdownMenuTrigger')
   const ref = useMemo(
     () => composeRefs<HTMLButtonElement>(forwardedRef, triggerRef),
@@ -177,7 +307,21 @@ export const DropdownMenuTrigger = forwardRef<
       )}
       onClick={(event) => {
         onClick?.(event)
-        if (!event.defaultPrevented) setOpen(!open)
+        if (event.defaultPrevented) return
+        if (open) closeMenu()
+        else openMenu('first')
+      }}
+      onKeyDown={(event) => {
+        onKeyDown?.(event)
+        if (event.defaultPrevented) return
+        // APG menu button: Down opens onto the first item, Up onto the last.
+        if (event.key === 'ArrowDown') {
+          event.preventDefault()
+          openMenu('first')
+        } else if (event.key === 'ArrowUp') {
+          event.preventDefault()
+          openMenu('last')
+        }
       }}
       {...rest}
     >
@@ -215,11 +359,13 @@ export const DropdownMenuContent = forwardRef<
     sideOffset = 6,
     className,
     style,
+    onKeyDown,
+    onFocus,
     ...rest
   },
   forwardedRef,
 ) {
-  const { open, setOpen, triggerRef, contentId } =
+  const { open, closeMenu, triggerRef, contentId, initialFocusRef, focusEdgeRef } =
     useDropdownMenuCtx('DropdownMenuContent')
   const contentRef = useRef<HTMLDivElement | null>(null)
@@ -242,22 +388,138 @@ export const DropdownMenuContent = forwardRef<
     enabled: open,
     kind: 'popover',
     elementRef: contentRef,
-    onEscape: () => {
-      setOpen(false)
-      triggerRef.current?.focus()
-    },
+    onEscape: () => closeMenu(),
   })
-  useOutsideClick([triggerRef, contentRef], () => setOpen(false), {
-    enabled: open,
-    layer,
-  })
+  useOutsideClick(
+    [triggerRef, contentRef],
+    () => {
+      // Restore only when focus is still ours to give back. If the pointer
+      // landed on another focusable control, the browser's own mousedown
+      // focus (which runs after this pointerdown) must win.
+      const active = document.activeElement
+      const inside =
+        active instanceof HTMLElement && Boolean(contentRef.current?.contains(active))
+      closeMenu({ restoreFocus: inside })
+    },
+    { enabled: open, layer },
+  )
   const ref = useMemo(
     () => composeRefs<HTMLDivElement>(forwardedRef, contentRef, positionRef),
     [forwardedRef, positionRef],
   )
+  /** Focus item `index`, wrapping, and rove the tab stop onto it. */
+  const focusIndex = useCallback((index: number) => {
+    const items = menuItemsIn(contentRef.current)
+    if (items.length === 0) return
+    const wrapped = ((index % items.length) + items.length) % items.length
+    applyRoving(items, wrapped)
+    items[wrapped]?.focus()
+  }, [])
+  /**
+   * Entry point for "put focus in the menu". Items first; a menu that is
+   * really a small form (range-filter chip) falls back to its first field,
+   * and a menu with nothing focusable to the surface itself — anything but
+   * leaving focus behind on the trigger with the menu open.
+   */
+  const focusEdge = useCallback(
+    (where: InitialFocus) => {
+      const content = contentRef.current
+      if (!content) return
+      const items = menuItemsIn(content)
+      if (items.length > 0) {
+        focusIndex(where === 'last' ? items.length - 1 : 0)
+        return
+      }
+      const focusable = Array.from(
+        content.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      )
+      const fallback =
+        where === 'last' ? focusable[focusable.length - 1] : focusable[0]
+      ;(fallback ?? content).focus()
+    },
+    [focusIndex],
+  )
+  // The trigger reaches back in here for ArrowDown on an already-open menu.
+  useEffect(() => {
+    focusEdgeRef.current = focusEdge
+    return () => {
+      if (focusEdgeRef.current === focusEdge) focusEdgeRef.current = null
+    }
+  }, [focusEdge, focusEdgeRef])
+  // Focus on open — gated on `positioned` because the first paint is parked
+  // off-screen with `visibility: hidden`, and a hidden element cannot take
+  // focus. Once per open.
+  const didFocusRef = useRef(false)
+  useEffect(() => {
+    if (!open) {
+      didFocusRef.current = false
+      return
+    }
+    if (!positioned || didFocusRef.current) return
+    didFocusRef.current = true
+    focusEdge(initialFocusRef.current)
+  }, [open, positioned, focusEdge, initialFocusRef])
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event)
+    if (event.defaultPrevented) return
+    const { key } = event
+    if (
+      key !== 'ArrowDown' &&
+      key !== 'ArrowUp' &&
+      key !== 'Home' &&
+      key !== 'End' &&
+      key !== 'Tab'
+    ) {
+      return
+    }
+    const target = event.target
+    const current =
+      target instanceof HTMLElement
+        ? target.closest<HTMLElement>(MENU_ITEM_SELECTOR)
+        : null
+    if (key === 'Tab') {
+      // APG: Tab closes the menu. Only from an item — a form-shaped menu
+      // must keep ordinary tabbing between its own fields.
+      if (!current) return
+      // Land on the trigger rather than letting the default action continue:
+      // the content is portaled to the END of <body>, so the "next element
+      // after it" is nothing at all — the tab sequence falls off the
+      // document. One extra Tab from the trigger then moves on normally.
+      event.preventDefault()
+      closeMenu()
+      return
+    }
+    if (ownsArrowKeys(target)) return
+    const items = menuItemsIn(contentRef.current)
+    if (items.length === 0) return
+    event.preventDefault()
+    const index = current ? items.indexOf(current) : -1
+    if (key === 'Home') focusIndex(0)
+    else if (key === 'End') focusIndex(items.length - 1)
+    else if (key === 'ArrowDown') focusIndex(index + 1)
+    else focusIndex(index <= 0 ? items.length - 1 : index - 1)
+  }
+  const handleFocus = (event: ReactFocusEvent<HTMLDivElement>) => {
+    onFocus?.(event)
+    // Keep the single tab stop on whatever actually holds focus, including
+    // focus arriving by pointer.
+    const item = event.target.closest<HTMLElement>(MENU_ITEM_SELECTOR)
+    if (!item) return
+    const items = menuItemsIn(contentRef.current)
+    const index = items.indexOf(item)
+    if (index >= 0) applyRoving(items, index)
+  }
   if (!open || typeof document === 'undefined') return null
   // Two-phase render (see lib/anchor.ts): the hook parks the first paint
@@ -270,6 +532,12 @@ export const DropdownMenuContent = forwardRef<
       ref={ref}
       id={contentId}
       role="menu"
+      aria-orientation="vertical"
+      // Focusable surface, so a menu with nothing focusable inside still
+      // has somewhere to put focus instead of dropping it to <body>.
+      tabIndex={-1}
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
       data-slot="dropdown-menu-content"
       data-state="open"
       data-side={placement?.side}
@@ -310,7 +578,7 @@ export const DropdownMenuItem = forwardRef<
   { variant = 'default', inset, className, onClick, children, ...rest },
   forwardedRef,
 ) {
-  const { setOpen } = useDropdownMenuCtx('DropdownMenuItem')
+  const { closeMenu } = useDropdownMenuCtx('DropdownMenuItem')
   return (
     <button
       ref={forwardedRef}
@@ -332,7 +600,10 @@ export const DropdownMenuItem = forwardRef<
       )}
       onClick={(event) => {
         onClick?.(event)
-        if (!event.defaultPrevented) setOpen(false)
+        // Activation closes AND hands focus back to the trigger. Without the
+        // restore, a dialog opened from here has no `activeElement` to
+        // capture and its own close drops focus to <body>.
+        if (!event.defaultPrevented) closeMenu()
       }}
       {...rest}
     >

package/src/filter-core/EXPORTS.md ADDED Viewed

@@ -0,0 +1,85 @@
+# filter-core — export wiring
+`packages/ui/src/filter-core/**` is self-contained and currently reachable
+only by its own path. Nothing outside this directory was edited.
+## The one line to add
+Append to `packages/ui/src/index.ts`:
+```ts
+// Board filter model — pure TypeScript, no React. See src/filter-core/index.ts.
+export * from './filter-core'
+```
+`filter-core/index.ts` is an explicit barrel (no wildcard re-exports of its
+own), so `export *` here surfaces exactly the list below and nothing else.
+Every type is exported with `export type`, so `verbatimModuleSyntax` is
+satisfied and none of it survives into the JS bundle.
+### If you would rather namespace it
+The alternative, if `@lovett/ui`'s top level should stay component-only:
+```json
+// packages/ui/package.json — "exports"
+"./filter-core": "./src/filter-core/index.ts"
+```
+…plus the matching `publishConfig.exports` entry and a second `tsup` entry
+(`entry: { index: 'src/index.ts', 'filter-core': 'src/filter-core/index.ts' }`).
+That is three edits instead of one; the flat `export *` is the cheaper default
+and there are no name collisions (checked against the current `src/index.ts`).
+## What that line surfaces
+**Values**
+```
+COLUMN_DATA_TYPES
+DEFAULT_OPERATORS, FILTER_OPERATOR_DETAILS
+textFilterOperators, numberFilterOperators, dateFilterOperators,
+optionFilterOperators, multiOptionFilterOperators
+operatorsForType, operatorDetails, operatorValueArity, relatedOperators,
+isOperatorOf, negateOperator, determineNewOperator
+defineColumns, indexColumns, isColumnOfType
+textFilterFn, numberFilterFn, dateFilterFn, optionFilterFn, multiOptionFilterFn
+rowMatchesFilter, rowMatchesFilters, pruneFilters, filterRows
+facetedCounts, facetedRowsFor, facetedMinMax
+getFilter, upsertFilter, removeFilter, clearFilters, setFilterOperator
+setTextFilter, setNumberFilter, setDateFilter, setOptionFilter,
+setMultiOptionFilter, toggleOptionValue, toggleMultiOptionValue
+FILTERS_SEARCH_PARAM, serializeFilters, parseFilters
+```
+**Types**
+```
+Nullable, ElementType
+ColumnDataType, OptionBasedColumnDataType, ColumnDataNativeMap, ColumnValueMap
+ColumnOption, ColumnAccessor, ColumnConfig, AnyColumnConfig
+FilterValues, FilterModel, FiltersState
+FilterOperators, FilterOperatorTarget, FilterOperatorArity
+FilterOperatorDetails, FilterOperatorDetailsShape, FilterDetails,
+FilterTypeOperatorDetails
+TextFilterOperator, NumberFilterOperator, DateFilterOperator,
+OptionFilterOperator, MultiOptionFilterOperator
+```
+## What it deliberately does NOT surface
+`./examples/task-filter-columns` — the Tasks-board column set is illustration,
+not API. The lens declares its own columns over its own row type. Import it
+only from a test or while reading.
+## Notes for whoever wires this
+- **No new dependency.** Nothing was added to `package.json` and nothing was
+  installed. `date-fns` (four helpers) is inlined in `date-utils.ts`.
+- **`zod` was asked for and is NOT used**, because zod is not a dependency of
+  `@lovett/ui` and adding one to the design system is an ADR-level call plus a
+  `package.json` edit — outside this change's scope. `url.ts` hand-validates to
+  the same standard (every field, every bound, fresh object literals) and is
+  funnelled through a single `parseEntry` so a zod schema can replace it in one
+  place if you want it later.
+- **CSS: none.** Nothing to add to `styles.css`.

package/src/filter-core/__tests__/columns.test.ts ADDED Viewed

@@ -0,0 +1,159 @@
+/**
+ * Config-time validation.
+ *
+ * BUG 2, the other half: a column type with no predicate must FAIL LOUDLY
+ * where the columns are declared. In the source, declaring a date column was
+ * accepted and then silently filtered to everything.
+ */
+import { describe, expect, it } from 'vitest'
+import { defineColumns, indexColumns, isColumnOfType } from '../index'
+import type { AnyColumnConfig } from '../index'
+interface Row {
+  readonly id: string
+  readonly name: string
+}
+/**
+ * Build a config the type system would reject, to exercise the RUNTIME gate.
+ * The double assertion is confined to this helper and is the only way to
+ * reach a validator whose whole job is catching what types cannot.
+ */
+function illegal(config: unknown): AnyColumnConfig<Row> {
+  return config as AnyColumnConfig<Row>
+}
+const ok = { id: 'name', displayName: 'Name', accessor: (r: Row) => r.name }
+describe('defineColumns', () => {
+  it('returns the columns it was given', () => {
+    const columns = defineColumns<Row>([{ ...ok, type: 'text' }])
+    expect(columns).toHaveLength(1)
+    expect(columns[0]?.id).toBe('name')
+  })
+  it('throws on an unsupported column type', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, type: 'boolean' })]),
+    ).toThrow(/unsupported type "boolean"/)
+  })
+  it('throws on a missing type', () => {
+    expect(() => defineColumns<Row>([illegal({ ...ok })])).toThrow(
+      /unsupported type/,
+    )
+  })
+  it('throws on a blank id', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, id: '  ', type: 'text' })]),
+    ).toThrow(/non-empty string id/)
+  })
+  it('throws on a reserved id', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, id: '__proto__', type: 'text' })]),
+    ).toThrow(/reserved/)
+  })
+  it('throws on duplicate ids', () => {
+    expect(() =>
+      defineColumns<Row>([
+        { ...ok, type: 'text' },
+        { ...ok, type: 'text' },
+      ]),
+    ).toThrow(/duplicate column id/)
+  })
+  it('throws on a missing accessor or displayName', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ id: 'x', displayName: 'X', type: 'text' })]),
+    ).toThrow(/accessor function/)
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, displayName: '', type: 'text' })]),
+    ).toThrow(/displayName/)
+  })
+  it('throws on a malformed option', () => {
+    expect(() =>
+      defineColumns<Row>([
+        illegal({ ...ok, type: 'option', options: [{ label: 'No value' }] }),
+      ]),
+    ).toThrow(/malformed option/)
+  })
+  it('throws on duplicate option values', () => {
+    expect(() =>
+      defineColumns<Row>([
+        {
+          ...ok,
+          type: 'option',
+          options: [
+            { value: 'a', label: 'A' },
+            { value: 'a', label: 'Also A' },
+          ],
+        },
+      ]),
+    ).toThrow(/duplicate option value/)
+  })
+  it('throws when a number column has min above max', () => {
+    expect(() =>
+      defineColumns<Row>([
+        illegal({ ...ok, type: 'number', min: 10, max: 1 }),
+      ]),
+    ).toThrow(/min greater than max/)
+  })
+  it('accepts every supported type', () => {
+    const columns = defineColumns<Row>([
+      { id: 'a', displayName: 'A', type: 'text', accessor: (r) => r.name },
+      { id: 'b', displayName: 'B', type: 'number', accessor: () => 1, min: 0, max: 5 },
+      { id: 'c', displayName: 'C', type: 'date', accessor: () => new Date() },
+      {
+        id: 'd',
+        displayName: 'D',
+        type: 'option',
+        accessor: (r) => r.name,
+        options: [{ value: 'x', label: 'X' }],
+      },
+      {
+        id: 'e',
+        displayName: 'E',
+        type: 'multiOption',
+        accessor: () => ['x'],
+        options: [{ value: 'x', label: 'X' }],
+      },
+    ])
+    expect(columns).toHaveLength(5)
+  })
+})
+describe('indexColumns / isColumnOfType', () => {
+  const columns = defineColumns<Row>([
+    { id: 'a', displayName: 'A', type: 'text', accessor: (r) => r.name },
+    {
+      id: 'b',
+      displayName: 'B',
+      type: 'option',
+      accessor: (r) => r.name,
+      options: [{ value: 'x', label: 'X' }],
+    },
+  ])
+  it('indexes by id', () => {
+    const index = indexColumns(columns)
+    expect(index.get('a')?.type).toBe('text')
+    expect(index.get('missing')).toBeUndefined()
+  })
+  it('narrows on the discriminant', () => {
+    const column = columns[1]
+    if (!column) throw new Error('fixture missing')
+    expect(isColumnOfType(column, 'option')).toBe(true)
+    expect(isColumnOfType(column, 'text')).toBe(false)
+    if (isColumnOfType(column, 'option')) {
+      expect(column.options?.[0]?.value).toBe('x')
+    }
+  })
+})