chore(ui): сохранить основу поэтапной миграции таблиц
This commit is contained in:
Denozordec committed
1 parent
c30f817926
commit
e7755a4d16
100 files changed
+30178
-1089
No files matched your search
@@ -0,0 +1,866 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import { useCascaderState } from "@/components/reui/cascader/cascader-context"
|
||||
import {
|
||||
CASCADER_ROOT_KEY,
|
||||
isCascaderMoreNode,
|
||||
} from "@/components/reui/cascader/cascader-lib"
|
||||
import type {
|
||||
CascaderIndex,
|
||||
CascaderLoadContext,
|
||||
CascaderLoadReason,
|
||||
CascaderLoadResult,
|
||||
CascaderLoadState,
|
||||
CascaderNode,
|
||||
CascaderSearchContext,
|
||||
} from "@/components/reui/cascader/cascader-types"
|
||||
|
||||
/**
|
||||
* Async data for the cascader. Loaded pages live in their own store and are
|
||||
* MERGED onto the index built from `items`, never folded into that build:
|
||||
* `items` changes identity on any parent re-render, and folding would discard
|
||||
* every level the user drilled into. Map membership is the load discriminator:
|
||||
* no `states` entry means never fetched, while an entry with no `loading`, no
|
||||
* `error` and no children means empty for real.
|
||||
*/
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Types */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/** Fetches one level. `node` is `null` for the root level. */
|
||||
export type CascaderGetChildren<T = unknown> = (
|
||||
node: CascaderNode<T> | null,
|
||||
context: CascaderLoadContext
|
||||
) =>
|
||||
| CascaderNode<T>[]
|
||||
| CascaderLoadResult<T>
|
||||
| Promise<CascaderNode<T>[] | CascaderLoadResult<T>>
|
||||
|
||||
/** Server-side search, replacing the local index scan while the query is set. */
|
||||
export type CascaderOnSearch<T = unknown> = (
|
||||
query: string,
|
||||
context: CascaderSearchContext
|
||||
) =>
|
||||
| CascaderNode<T>[]
|
||||
| CascaderLoadResult<T>
|
||||
| Promise<CascaderNode<T>[] | CascaderLoadResult<T>>
|
||||
|
||||
/** Resolves a selected value to its ancestor chain, root first, node last. */
|
||||
export type CascaderResolveValue<T = unknown> = (
|
||||
value: string,
|
||||
context: CascaderLoadContext
|
||||
) => CascaderNode<T>[] | Promise<CascaderNode<T>[]>
|
||||
|
||||
export interface CascaderLoaderStore<T = unknown> {
|
||||
/** Keyed by LEVEL: a parent's value, or `CASCADER_ROOT_KEY` for the root. */
|
||||
pages: Map<string, CascaderNode<T>[]>
|
||||
states: Map<string, CascaderLoadState>
|
||||
/** Keyed by node value: search hits and resolved selections, level-less. */
|
||||
detached: Map<string, CascaderNode<T>>
|
||||
}
|
||||
|
||||
export interface UseCascaderLoaderOptions<T = unknown> {
|
||||
/** The index built from `items`, before any pages are merged in. */
|
||||
base: CascaderIndex<T>
|
||||
getChildren?: CascaderGetChildren<T>
|
||||
onSearch?: CascaderOnSearch<T>
|
||||
resolveValue?: CascaderResolveValue<T>
|
||||
/** Milliseconds of quiet before `onSearch` fires. */
|
||||
searchDebounce?: number
|
||||
/** Changing this drops every cached page, state and detached node. */
|
||||
loadKey?: unknown
|
||||
/** Speculatively fetch a branch's children when it is highlighted. */
|
||||
prefetch?: boolean
|
||||
/** Called when a request fails. Never for an aborted or superseded one. */
|
||||
onLoadError?: (
|
||||
error: unknown,
|
||||
context: { parent: string | null; reason: string }
|
||||
) => void
|
||||
/** Whether the panel is live: the popup is open, or the cascader is inline. */
|
||||
enabled: boolean
|
||||
query: string
|
||||
/** Level keys that are currently on screen. Root is `CASCADER_ROOT_KEY`. */
|
||||
levels: string[]
|
||||
/** The navigation path, handed to `onSearch` as its scope. */
|
||||
path: string[]
|
||||
/** Current selection, for `resolveValue`. */
|
||||
values: string[]
|
||||
}
|
||||
|
||||
export interface CascaderLoader<T = unknown> {
|
||||
/** Whether a `getChildren` loader is configured at all. */
|
||||
active: boolean
|
||||
store: CascaderLoaderStore<T>
|
||||
states: ReadonlyMap<string, CascaderLoadState>
|
||||
/**
|
||||
* Async search hits, `null` when no `onSearch` is running. EMPTY while the
|
||||
* first request is in flight, so the level behind is not shown as the answer.
|
||||
*/
|
||||
searchResults: CascaderNode<T>[] | null
|
||||
searchState: CascaderLoadState | null
|
||||
/**
|
||||
* Fetches a level's FIRST page. No-ops on a `states` entry (in flight,
|
||||
* loaded or failed) or when `items` fills the level; pages are never
|
||||
* consulted, so a `resolveValue` chain still fetches. The level effect fires
|
||||
* only for on-screen levels, so a branch merely PRESSED is asked for by hand.
|
||||
*/
|
||||
ensureLevel: (parentKey: string, reason: CascaderLoadReason) => void
|
||||
/** Fetches the next page of a level. No-ops unless one is available. */
|
||||
loadMore: (parentKey: string) => void
|
||||
/** Refires a failed level. No-ops unless that level is in an error state. */
|
||||
retryLevel: (parentKey: string) => void
|
||||
/** Schedules a speculative fetch. Safe to call on every highlight move. */
|
||||
prefetchNode: (node: CascaderNode<T> | null | undefined) => void
|
||||
/**
|
||||
* Evicts ONE level: aborts its request, drops its `states`/`pages` entries
|
||||
* and paging latch, so the level effect refetches it. `null` = root level.
|
||||
*/
|
||||
invalidateLevel: (value: string | null) => void
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Constants */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Highlight dwell before `prefetch` fetches: long enough that holding ArrowDown
|
||||
* does not fire a request per row, short enough to beat the ArrowRight press.
|
||||
*/
|
||||
const PREFETCH_DELAY = 150
|
||||
|
||||
/** Request keys for the two non-level requests. Never collide with a value. */
|
||||
const SEARCH_KEY = "\u0000search"
|
||||
const RESOLVE_PREFIX = "\u0000resolve:"
|
||||
|
||||
const NO_STATE: CascaderLoadState = {
|
||||
loading: false,
|
||||
error: false,
|
||||
hasMore: false,
|
||||
}
|
||||
|
||||
/** Stable empty result, so an idle search never churns the state context. */
|
||||
const NO_RESULTS: CascaderNode<never>[] = []
|
||||
|
||||
function createStore<T>(): CascaderLoaderStore<T> {
|
||||
return { pages: new Map(), states: new Map(), detached: new Map() }
|
||||
}
|
||||
|
||||
function sameLoadState(a: CascaderLoadState, b: CascaderLoadState): boolean {
|
||||
return (
|
||||
a.loading === b.loading &&
|
||||
a.error === b.error &&
|
||||
a.hasMore === b.hasMore &&
|
||||
a.cursor === b.cursor
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Store transitions */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Copy-on-write, and a NO-OP when nothing changed: the merged index is memoised
|
||||
* on store identity, so a fresh object for an unchanged state would rebuild it.
|
||||
*/
|
||||
function withLoadState<T>(
|
||||
store: CascaderLoaderStore<T>,
|
||||
key: string,
|
||||
update: (state: CascaderLoadState) => CascaderLoadState
|
||||
): CascaderLoaderStore<T> {
|
||||
const current = store.states.get(key) ?? NO_STATE
|
||||
const next = update(current)
|
||||
if (store.states.has(key) && sameLoadState(current, next)) return store
|
||||
const states = new Map(store.states)
|
||||
states.set(key, next)
|
||||
return { pages: store.pages, states, detached: store.detached }
|
||||
}
|
||||
|
||||
function withPage<T>(
|
||||
store: CascaderLoaderStore<T>,
|
||||
key: string,
|
||||
items: readonly CascaderNode<T>[],
|
||||
options: { append: boolean; hasMore: boolean; cursor?: string }
|
||||
): CascaderLoaderStore<T> {
|
||||
// A fresh level REPLACES its page so a `resolveValue` stub can be superseded.
|
||||
const previous = options.append ? (store.pages.get(key) ?? []) : []
|
||||
const seen = new Set(previous.map((node) => node.value))
|
||||
const merged = previous.slice()
|
||||
for (const item of items) {
|
||||
if (seen.has(item.value)) continue
|
||||
seen.add(item.value)
|
||||
merged.push(item)
|
||||
}
|
||||
|
||||
const pages = new Map(store.pages)
|
||||
pages.set(key, merged)
|
||||
const states = new Map(store.states)
|
||||
states.set(key, {
|
||||
loading: false,
|
||||
error: false,
|
||||
hasMore: options.hasMore,
|
||||
cursor: options.cursor,
|
||||
})
|
||||
return { pages, states, detached: store.detached }
|
||||
}
|
||||
|
||||
function withDetached<T>(
|
||||
store: CascaderLoaderStore<T>,
|
||||
items: readonly CascaderNode<T>[]
|
||||
): CascaderLoaderStore<T> {
|
||||
let detached: Map<string, CascaderNode<T>> | null = null
|
||||
for (const item of items) {
|
||||
if (store.detached.get(item.value) === item) continue
|
||||
detached = detached ?? new Map(store.detached)
|
||||
detached.set(item.value, item)
|
||||
}
|
||||
if (!detached) return store
|
||||
return { pages: store.pages, states: store.states, detached }
|
||||
}
|
||||
|
||||
/**
|
||||
* Places a resolved ancestor chain into `pages`, root first. Writes no
|
||||
* `states`, so those levels still read as unloaded and a drill-in still fetches
|
||||
* for real. Mirrored into `detached` so the trigger keeps its label.
|
||||
*/
|
||||
function withChain<T>(
|
||||
store: CascaderLoaderStore<T>,
|
||||
chain: readonly CascaderNode<T>[]
|
||||
): CascaderLoaderStore<T> {
|
||||
if (chain.length === 0) return store
|
||||
const pages = new Map(store.pages)
|
||||
const detached = new Map(store.detached)
|
||||
let parentKey = CASCADER_ROOT_KEY
|
||||
|
||||
for (const node of chain) {
|
||||
const bucket = pages.get(parentKey)
|
||||
if (!bucket) {
|
||||
pages.set(parentKey, [node])
|
||||
} else if (!bucket.some((entry) => entry.value === node.value)) {
|
||||
pages.set(parentKey, [...bucket, node])
|
||||
}
|
||||
detached.set(node.value, node)
|
||||
parentKey = node.value
|
||||
}
|
||||
|
||||
return { pages, states: store.states, detached }
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Hook */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
interface CascaderLoaderLatest<T> {
|
||||
base: CascaderIndex<T>
|
||||
store: CascaderLoaderStore<T>
|
||||
getChildren?: CascaderGetChildren<T>
|
||||
onSearch?: CascaderOnSearch<T>
|
||||
resolveValue?: CascaderResolveValue<T>
|
||||
onLoadError?: (
|
||||
error: unknown,
|
||||
context: { parent: string | null; reason: string }
|
||||
) => void
|
||||
prefetch: boolean
|
||||
path: string[]
|
||||
}
|
||||
|
||||
interface CascaderSearchSlice<T> {
|
||||
query: string
|
||||
results: CascaderNode<T>[]
|
||||
loading: boolean
|
||||
error: boolean
|
||||
}
|
||||
|
||||
/**
|
||||
* The loader. A SIBLING of the `buildCascaderIndex` memo, never inside it: the
|
||||
* build stays pure in `items`, the merge pure in that build plus this store.
|
||||
*/
|
||||
export function useCascaderLoader<T = unknown>({
|
||||
base,
|
||||
getChildren,
|
||||
onSearch,
|
||||
resolveValue,
|
||||
searchDebounce = 250,
|
||||
loadKey,
|
||||
prefetch = false,
|
||||
onLoadError,
|
||||
enabled,
|
||||
query,
|
||||
levels,
|
||||
path,
|
||||
values,
|
||||
}: UseCascaderLoaderOptions<T>): CascaderLoader<T> {
|
||||
const [store, setStore] = React.useState<CascaderLoaderStore<T>>(createStore)
|
||||
const [search, setSearch] = React.useState<CascaderSearchSlice<T> | null>(
|
||||
null
|
||||
)
|
||||
|
||||
/**
|
||||
* Latest callbacks, WRITTEN IN AN EFFECT: `getChildren` is inline in most
|
||||
* consumers, so closing over it would refire every in-flight request per
|
||||
* re-render. The ref is what keeps the request machinery `[]`-dep. Declared
|
||||
* FIRST, since effects run in declaration order, so the level effect below
|
||||
* already sees the current commit.
|
||||
*/
|
||||
const latest = React.useRef<CascaderLoaderLatest<T>>({
|
||||
base,
|
||||
store,
|
||||
getChildren,
|
||||
onSearch,
|
||||
resolveValue,
|
||||
onLoadError,
|
||||
prefetch,
|
||||
path,
|
||||
})
|
||||
|
||||
React.useEffect(() => {
|
||||
latest.current = {
|
||||
base,
|
||||
store,
|
||||
getChildren,
|
||||
onSearch,
|
||||
resolveValue,
|
||||
onLoadError,
|
||||
prefetch,
|
||||
path,
|
||||
}
|
||||
})
|
||||
|
||||
/** One AbortController PER KEY: columns mode runs several levels at once. */
|
||||
const controllers = React.useRef(new Map<string, AbortController>())
|
||||
/** Monotonic per key. The stale guard for out-of-order responses. */
|
||||
const requestIds = React.useRef(new Map<string, number>())
|
||||
/** In-flight `(level, cursor)` signatures, so a duplicate ask is free. */
|
||||
const inflight = React.useRef(new Map<string, string>())
|
||||
/**
|
||||
* The `(child count, cursor)` signature at the last paging fire, per level.
|
||||
* Guards what `hasMore` cannot: a page of zero new items while the server
|
||||
* still says `hasMore`. Cursor is IN the signature because an all-duplicates
|
||||
* page advances it while the count stands still - real progress, which a
|
||||
* count-only latch would brick forever.
|
||||
*/
|
||||
const moreLatch = React.useRef(new Map<string, string>())
|
||||
/** Values `resolveValue` has already been asked about, so it asks once. */
|
||||
const attempted = React.useRef(new Set<string>())
|
||||
/** Every node the loader has seen, so a level key can name its own node. */
|
||||
const known = React.useRef(new Map<string, CascaderNode<T>>())
|
||||
const timers = React.useRef<{
|
||||
prefetch: ReturnType<typeof setTimeout> | null
|
||||
}>({ prefetch: null })
|
||||
/** Bumped by a `loadKey` change, so responses from before it are dropped. */
|
||||
const epoch = React.useRef(0)
|
||||
|
||||
const remember = React.useCallback((nodes: readonly CascaderNode<T>[]) => {
|
||||
const map = known.current
|
||||
const walk = (list: readonly CascaderNode<T>[]) => {
|
||||
for (const node of list) {
|
||||
map.set(node.value, node)
|
||||
if (node.children?.length) walk(node.children)
|
||||
}
|
||||
}
|
||||
walk(nodes)
|
||||
}, [])
|
||||
|
||||
const abortKey = React.useCallback((key: string) => {
|
||||
const controller = controllers.current.get(key)
|
||||
if (!controller) return
|
||||
controllers.current.delete(key)
|
||||
inflight.current.delete(key)
|
||||
controller.abort()
|
||||
}, [])
|
||||
|
||||
/* ------------------------------- level load ------------------------------ */
|
||||
|
||||
const runLoad = React.useCallback(
|
||||
(
|
||||
key: string,
|
||||
reason: CascaderLoadReason,
|
||||
cursor: string | undefined,
|
||||
append: boolean
|
||||
) => {
|
||||
const { getChildren: loader, base: currentBase } = latest.current
|
||||
if (!loader) return
|
||||
|
||||
const signature = `${append ? "1" : "0"}:${cursor ?? ""}`
|
||||
if (inflight.current.get(key) === signature) return
|
||||
|
||||
abortKey(key)
|
||||
const controller = new AbortController()
|
||||
controllers.current.set(key, controller)
|
||||
inflight.current.set(key, signature)
|
||||
|
||||
const requestId = (requestIds.current.get(key) ?? 0) + 1
|
||||
requestIds.current.set(key, requestId)
|
||||
const startEpoch = epoch.current
|
||||
|
||||
const node =
|
||||
key === CASCADER_ROOT_KEY
|
||||
? null
|
||||
: (currentBase.byValue.get(key) ?? known.current.get(key) ?? null)
|
||||
|
||||
setStore((prev) =>
|
||||
withLoadState(prev, key, (state) => ({
|
||||
...state,
|
||||
loading: true,
|
||||
error: false,
|
||||
}))
|
||||
)
|
||||
|
||||
const settle = () => {
|
||||
if (inflight.current.get(key) === signature)
|
||||
inflight.current.delete(key)
|
||||
if (controllers.current.get(key) === controller) {
|
||||
controllers.current.delete(key)
|
||||
}
|
||||
}
|
||||
|
||||
const stale = () =>
|
||||
controller.signal.aborted ||
|
||||
startEpoch !== epoch.current ||
|
||||
requestId !== requestIds.current.get(key)
|
||||
|
||||
// `Promise.resolve().then(...)`, not a direct call: it normalises a
|
||||
// SYNCHRONOUS throw into a rejection instead of taking the render down.
|
||||
Promise.resolve()
|
||||
.then(() => loader(node, { signal: controller.signal, cursor, reason }))
|
||||
.then((result) => {
|
||||
settle()
|
||||
if (stale()) return
|
||||
const items = Array.isArray(result) ? result : result.items
|
||||
const nextCursor = Array.isArray(result)
|
||||
? undefined
|
||||
: result.nextCursor
|
||||
const hasMore = Array.isArray(result)
|
||||
? false
|
||||
: (result.hasMore ?? nextCursor != null)
|
||||
|
||||
if (!append) moreLatch.current.delete(key)
|
||||
remember(items)
|
||||
setStore((prev) =>
|
||||
withPage(prev, key, items, { append, hasMore, cursor: nextCursor })
|
||||
)
|
||||
})
|
||||
.catch((error: unknown) => {
|
||||
settle()
|
||||
if (stale()) return
|
||||
setStore((prev) =>
|
||||
withLoadState(prev, key, (state) => ({
|
||||
...state,
|
||||
loading: false,
|
||||
error: true,
|
||||
}))
|
||||
)
|
||||
// Behind the stale guard: an abort is navigation, not a failure.
|
||||
latest.current.onLoadError?.(error, {
|
||||
parent: key === CASCADER_ROOT_KEY ? null : key,
|
||||
reason,
|
||||
})
|
||||
})
|
||||
},
|
||||
[abortKey, remember]
|
||||
)
|
||||
|
||||
const ensureLevel = React.useCallback(
|
||||
(key: string, reason: CascaderLoadReason) => {
|
||||
const {
|
||||
getChildren: loader,
|
||||
store: current,
|
||||
base: index,
|
||||
} = latest.current
|
||||
if (!loader) return
|
||||
if (current.states.has(key)) return
|
||||
// A level `items` already fills is not the loader's business: that is how
|
||||
// a static root plus `getChildren` for the branches works with no flag.
|
||||
if (index.childrenOf.has(key)) return
|
||||
runLoad(key, reason, undefined, false)
|
||||
},
|
||||
[runLoad]
|
||||
)
|
||||
|
||||
const loadMore = React.useCallback(
|
||||
(key: string) => {
|
||||
const { getChildren: loader, store: current } = latest.current
|
||||
if (!loader) return
|
||||
const state = current.states.get(key)
|
||||
if (!state || state.loading || !state.hasMore) return
|
||||
|
||||
const loaded = current.pages.get(key)?.length ?? 0
|
||||
const signature = `${loaded}:${state.cursor ?? ""}`
|
||||
if (moreLatch.current.get(key) === signature) return
|
||||
moreLatch.current.set(key, signature)
|
||||
|
||||
runLoad(key, "more", state.cursor, true)
|
||||
},
|
||||
[runLoad]
|
||||
)
|
||||
|
||||
const retryLevel = React.useCallback(
|
||||
(key: string) => {
|
||||
const { getChildren: loader, store: current } = latest.current
|
||||
if (!loader) return
|
||||
const state = current.states.get(key)
|
||||
if (!state?.error) return
|
||||
|
||||
const loaded = current.pages.get(key)?.length ?? 0
|
||||
// A retry must be able to re-fire the page the latch just blocked.
|
||||
moreLatch.current.delete(key)
|
||||
runLoad(key, "retry", loaded > 0 ? state.cursor : undefined, loaded > 0)
|
||||
},
|
||||
[runLoad]
|
||||
)
|
||||
|
||||
/**
|
||||
* `detached` is deliberately untouched: chains and search hits belong to no
|
||||
* level, and the trigger needs their labels while the new page is in flight.
|
||||
*/
|
||||
const invalidateLevel = React.useCallback(
|
||||
(value: string | null) => {
|
||||
const key = value ?? CASCADER_ROOT_KEY
|
||||
abortKey(key)
|
||||
// Bump the id too: a response past its signal check must still be stale.
|
||||
requestIds.current.set(key, (requestIds.current.get(key) ?? 0) + 1)
|
||||
moreLatch.current.delete(key)
|
||||
setStore((prev) => {
|
||||
if (!prev.states.has(key) && !prev.pages.has(key)) return prev
|
||||
const states = new Map(prev.states)
|
||||
states.delete(key)
|
||||
const pages = new Map(prev.pages)
|
||||
pages.delete(key)
|
||||
return { pages, states, detached: prev.detached }
|
||||
})
|
||||
},
|
||||
[abortKey]
|
||||
)
|
||||
|
||||
const prefetchNode = React.useCallback(
|
||||
(node: CascaderNode<T> | null | undefined) => {
|
||||
const {
|
||||
prefetch: on,
|
||||
getChildren: loader,
|
||||
store: current,
|
||||
} = latest.current
|
||||
if (!on || !loader || !node) return
|
||||
if (isCascaderMoreNode(node)) return
|
||||
if (!node.hasChildren) return
|
||||
if (current.states.has(node.value)) return
|
||||
|
||||
const holder = timers.current
|
||||
if (holder.prefetch) clearTimeout(holder.prefetch)
|
||||
// A TIMEOUT, not a direct call: `onItemHighlighted` fires from a layout
|
||||
// effect, where a synchronous setState is a render-phase cascade.
|
||||
holder.prefetch = setTimeout(() => {
|
||||
holder.prefetch = null
|
||||
ensureLevel(node.value, "prefetch")
|
||||
}, PREFETCH_DELAY)
|
||||
},
|
||||
[ensureLevel]
|
||||
)
|
||||
|
||||
/* --------------------------------- search -------------------------------- */
|
||||
|
||||
const runSearch = React.useCallback(
|
||||
(text: string) => {
|
||||
const { onSearch: searcher, path: currentPath } = latest.current
|
||||
if (!searcher) return
|
||||
|
||||
abortKey(SEARCH_KEY)
|
||||
const controller = new AbortController()
|
||||
controllers.current.set(SEARCH_KEY, controller)
|
||||
const requestId = (requestIds.current.get(SEARCH_KEY) ?? 0) + 1
|
||||
requestIds.current.set(SEARCH_KEY, requestId)
|
||||
const startEpoch = epoch.current
|
||||
|
||||
setSearch((prev) => ({
|
||||
query: text,
|
||||
results: prev?.results ?? [],
|
||||
loading: true,
|
||||
error: false,
|
||||
}))
|
||||
|
||||
const settle = () => {
|
||||
if (controllers.current.get(SEARCH_KEY) === controller) {
|
||||
controllers.current.delete(SEARCH_KEY)
|
||||
}
|
||||
}
|
||||
const stale = () =>
|
||||
controller.signal.aborted ||
|
||||
startEpoch !== epoch.current ||
|
||||
requestId !== requestIds.current.get(SEARCH_KEY)
|
||||
|
||||
Promise.resolve()
|
||||
.then(() =>
|
||||
searcher(text, { signal: controller.signal, path: currentPath })
|
||||
)
|
||||
.then((result) => {
|
||||
settle()
|
||||
if (stale()) return
|
||||
const items = Array.isArray(result) ? result : result.items
|
||||
remember(items)
|
||||
// Search hits go to `detached`, never a level: a hit lives anywhere in
|
||||
// the tree, and filing it under the open level would misplace it.
|
||||
setStore((prev) => withDetached(prev, items))
|
||||
setSearch({
|
||||
query: text,
|
||||
results: items,
|
||||
loading: false,
|
||||
error: false,
|
||||
})
|
||||
})
|
||||
.catch((error: unknown) => {
|
||||
settle()
|
||||
if (stale()) return
|
||||
setSearch((prev) => ({
|
||||
query: text,
|
||||
results: prev?.results ?? [],
|
||||
loading: false,
|
||||
error: true,
|
||||
}))
|
||||
latest.current.onLoadError?.(error, {
|
||||
parent: null,
|
||||
reason: "search",
|
||||
})
|
||||
})
|
||||
},
|
||||
[abortKey, remember]
|
||||
)
|
||||
|
||||
/* --------------------------------- resolve ------------------------------- */
|
||||
|
||||
const runResolve = React.useCallback(
|
||||
(value: string) => {
|
||||
const { resolveValue: resolver } = latest.current
|
||||
if (!resolver) return
|
||||
|
||||
const key = `${RESOLVE_PREFIX}${value}`
|
||||
abortKey(key)
|
||||
const controller = new AbortController()
|
||||
controllers.current.set(key, controller)
|
||||
const startEpoch = epoch.current
|
||||
|
||||
const settle = () => {
|
||||
if (controllers.current.get(key) === controller) {
|
||||
controllers.current.delete(key)
|
||||
}
|
||||
}
|
||||
|
||||
Promise.resolve()
|
||||
.then(() =>
|
||||
resolver(value, { signal: controller.signal, reason: "resolve" })
|
||||
)
|
||||
.then((chain) => {
|
||||
settle()
|
||||
if (controller.signal.aborted || startEpoch !== epoch.current) return
|
||||
if (!chain?.length) return
|
||||
remember(chain)
|
||||
setStore((prev) => withChain(prev, chain))
|
||||
})
|
||||
.catch((error: unknown) => {
|
||||
settle()
|
||||
// Un-attempt on failure: `attempted` is written BEFORE the call, so
|
||||
// without this a resolver that failed once could never be retried.
|
||||
attempted.current.delete(value)
|
||||
if (controller.signal.aborted || startEpoch !== epoch.current) return
|
||||
latest.current.onLoadError?.(error, {
|
||||
parent: null,
|
||||
reason: "resolve",
|
||||
})
|
||||
})
|
||||
},
|
||||
[abortKey, remember]
|
||||
)
|
||||
|
||||
/* --------------------------------- resets -------------------------------- */
|
||||
|
||||
const cancelAll = React.useCallback(() => {
|
||||
const keys = Array.from(controllers.current.keys())
|
||||
for (const controller of controllers.current.values()) controller.abort()
|
||||
controllers.current.clear()
|
||||
inflight.current.clear()
|
||||
|
||||
const holder = timers.current
|
||||
if (holder.prefetch) {
|
||||
clearTimeout(holder.prefetch)
|
||||
holder.prefetch = null
|
||||
}
|
||||
if (keys.length === 0) return
|
||||
|
||||
setStore((prev) => {
|
||||
let states: Map<string, CascaderLoadState> | null = null
|
||||
for (const key of keys) {
|
||||
const state = prev.states.get(key)
|
||||
if (!state?.loading) continue
|
||||
states = states ?? new Map(prev.states)
|
||||
if ((prev.pages.get(key)?.length ?? 0) > 0) {
|
||||
states.set(key, { ...state, loading: false })
|
||||
} else {
|
||||
// No entry AT ALL: membership is what says "loaded", so a stranded
|
||||
// `loading: true` would read as loaded-and-empty forever.
|
||||
states.delete(key)
|
||||
}
|
||||
}
|
||||
return states ? { ...prev, states } : prev
|
||||
})
|
||||
setSearch((prev) => (prev?.loading ? { ...prev, loading: false } : prev))
|
||||
}, [])
|
||||
|
||||
// A `loadKey` change drops everything. Declared BEFORE the level effect, so
|
||||
// a reset always lands before the levels are asked for again.
|
||||
const loadKeyRef = React.useRef<{ key: unknown } | null>(null)
|
||||
React.useEffect(() => {
|
||||
const previous = loadKeyRef.current
|
||||
loadKeyRef.current = { key: loadKey }
|
||||
if (!previous || Object.is(previous.key, loadKey)) return
|
||||
|
||||
epoch.current += 1
|
||||
for (const controller of controllers.current.values()) controller.abort()
|
||||
controllers.current.clear()
|
||||
inflight.current.clear()
|
||||
// `requestIds` is deliberately NOT cleared: the ids are stale-response
|
||||
// guards, not cache. Reusing an aborted predecessor's id would leave only
|
||||
// the epoch bump and the abort to reject the old response; monotonic per
|
||||
// key keeps all three guards independent. The unmount cleanup clears them.
|
||||
moreLatch.current.clear()
|
||||
attempted.current.clear()
|
||||
known.current.clear()
|
||||
|
||||
const holder = timers.current
|
||||
if (holder.prefetch) {
|
||||
clearTimeout(holder.prefetch)
|
||||
holder.prefetch = null
|
||||
}
|
||||
|
||||
setStore(createStore)
|
||||
setSearch(null)
|
||||
}, [loadKey])
|
||||
|
||||
// Closing the popup aborts every request but does NOT drop the cache:
|
||||
// reopening onto an already-loaded level is the point of keeping it.
|
||||
React.useEffect(() => {
|
||||
if (enabled) return
|
||||
if (controllers.current.size === 0) return
|
||||
cancelAll()
|
||||
}, [enabled, cancelAll])
|
||||
|
||||
React.useEffect(() => {
|
||||
const active = controllers.current
|
||||
const holder = timers.current
|
||||
const pending = inflight.current
|
||||
const ids = requestIds.current
|
||||
return () => {
|
||||
for (const controller of active.values()) controller.abort()
|
||||
active.clear()
|
||||
// Cleared WITH the controllers, for StrictMode's dev remount: a stale
|
||||
// inflight signature would make `runLoad` skip the refetch forever. The
|
||||
// aborted promises are stale-guarded, so emptying the ids is safe.
|
||||
pending.clear()
|
||||
ids.clear()
|
||||
if (holder.prefetch) clearTimeout(holder.prefetch)
|
||||
}
|
||||
}, [])
|
||||
|
||||
/* ------------------------------- the effects ----------------------------- */
|
||||
|
||||
const hasLoader = typeof getChildren === "function"
|
||||
const hasSearch = typeof onSearch === "function"
|
||||
const hasResolve = typeof resolveValue === "function"
|
||||
const trimmed = query.trim()
|
||||
|
||||
// Serialised so the effects key on CONTENT, not on the array identity.
|
||||
const levelsKey = JSON.stringify(levels)
|
||||
const valuesKey = JSON.stringify(values)
|
||||
|
||||
// THE load trigger: one declarative effect on the levels on screen, not a
|
||||
// call from `pushLevel`/`navigate`, which a controlled `path` never touches.
|
||||
React.useEffect(() => {
|
||||
if (!enabled || !hasLoader) return
|
||||
for (const key of levels) ensureLevel(key, "level")
|
||||
// `levels` enters through `levelsKey`; `store` re-runs after a load lands.
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||
}, [enabled, hasLoader, levelsKey, store, ensureLevel])
|
||||
|
||||
React.useEffect(() => {
|
||||
if (!hasSearch) return undefined
|
||||
if (!enabled || !trimmed) {
|
||||
abortKey(SEARCH_KEY)
|
||||
setSearch((prev) => (prev === null ? prev : null))
|
||||
return undefined
|
||||
}
|
||||
const timer = setTimeout(() => runSearch(trimmed), searchDebounce)
|
||||
return () => {
|
||||
clearTimeout(timer)
|
||||
abortKey(SEARCH_KEY)
|
||||
}
|
||||
}, [hasSearch, enabled, trimmed, searchDebounce, abortKey, runSearch])
|
||||
|
||||
React.useEffect(() => {
|
||||
if (!enabled || !hasResolve) return
|
||||
for (const value of values) {
|
||||
if (!value) continue
|
||||
if (attempted.current.has(value)) continue
|
||||
if (base.byValue.has(value) || known.current.has(value)) continue
|
||||
attempted.current.add(value)
|
||||
runResolve(value)
|
||||
}
|
||||
// `values` is depended on through `valuesKey`.
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||
}, [enabled, hasResolve, valuesKey, base, runResolve])
|
||||
|
||||
/* -------------------------------- the value ------------------------------ */
|
||||
|
||||
const searchResults = React.useMemo(() => {
|
||||
if (!hasSearch || !trimmed) return null
|
||||
if (!search || search.query !== trimmed) {
|
||||
return NO_RESULTS as CascaderNode<T>[]
|
||||
}
|
||||
return search.results
|
||||
}, [hasSearch, trimmed, search])
|
||||
|
||||
const searchState = React.useMemo<CascaderLoadState | null>(() => {
|
||||
if (!hasSearch || !trimmed) return null
|
||||
const settled = search?.query === trimmed
|
||||
return {
|
||||
loading: !settled || !!search?.loading,
|
||||
error: settled && !!search?.error,
|
||||
hasMore: false,
|
||||
}
|
||||
}, [hasSearch, trimmed, search])
|
||||
|
||||
return React.useMemo(
|
||||
() => ({
|
||||
active: hasLoader,
|
||||
store,
|
||||
states: store.states,
|
||||
searchResults,
|
||||
searchState,
|
||||
ensureLevel,
|
||||
loadMore,
|
||||
retryLevel,
|
||||
invalidateLevel,
|
||||
prefetchNode,
|
||||
}),
|
||||
[
|
||||
hasLoader,
|
||||
store,
|
||||
searchResults,
|
||||
searchState,
|
||||
ensureLevel,
|
||||
loadMore,
|
||||
retryLevel,
|
||||
invalidateLevel,
|
||||
prefetchNode,
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Consumers */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/** One level's load state, `null` when never fetched. Omit for the root. */
|
||||
export function useCascaderLoadState(
|
||||
parent?: string | null
|
||||
): CascaderLoadState | null {
|
||||
const { loadStates } = useCascaderState()
|
||||
return loadStates.get(parent ?? CASCADER_ROOT_KEY) ?? null
|
||||
}
|
||||
@@ -0,0 +1,263 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import {
|
||||
useCascaderActions,
|
||||
useCascaderState,
|
||||
} from "@/components/reui/cascader/cascader-context"
|
||||
import type { CascaderColumn } from "@/components/reui/cascader/cascader-context"
|
||||
import {
|
||||
CascaderItem,
|
||||
getCascaderMoreProps,
|
||||
} from "@/components/reui/cascader/cascader-item"
|
||||
import {
|
||||
CASCADER_LIST_HEIGHT_CLASS,
|
||||
CASCADER_LIST_PAD_CLASS,
|
||||
CASCADER_ROOT_KEY,
|
||||
CASCADER_ROWS_CLASS,
|
||||
CASCADER_SCROLL_CLASS,
|
||||
warnCascaderOnce,
|
||||
} from "@/components/reui/cascader/cascader-lib"
|
||||
import { Combobox as ComboboxPrimitive } from "@base-ui/react"
|
||||
|
||||
import { cn } from "@/lib/utils"
|
||||
import { ScrollArea } from "@/components/ui/scroll-area"
|
||||
import { LoaderCircleIcon } from "lucide-react"
|
||||
|
||||
export interface CascaderColumnsProps extends Omit<
|
||||
React.ComponentProps<"div">,
|
||||
"children"
|
||||
> {
|
||||
/** Width of each column. */
|
||||
columnWidth?: number | string
|
||||
/** Height CAP per column. Falls back to the root `maxHeight`, then 24rem. */
|
||||
maxHeight?: number | string
|
||||
/** Replaces the default panel; the seam a windowed column plugs into. */
|
||||
children?: (column: CascaderColumn) => React.ReactNode
|
||||
}
|
||||
|
||||
/**
|
||||
* Miller columns: the open trail side by side, one panel per level. Only the
|
||||
* DEEPEST column is a real listbox (Base UI owns exactly one list); the trail
|
||||
* behind is plain buttons, which keeps one state machine instead of a second,
|
||||
* 2D one. `CascaderInput` moves between columns with ArrowLeft/ArrowRight.
|
||||
*/
|
||||
function CascaderColumns({
|
||||
className,
|
||||
columnWidth = 220,
|
||||
maxHeight: maxHeightProp,
|
||||
children,
|
||||
...props
|
||||
}: CascaderColumnsProps) {
|
||||
const { maxHeight, mode, labels } = useCascaderActions()
|
||||
const { columns } = useCascaderState()
|
||||
|
||||
// Before the early return, so the hook count is the same in both modes.
|
||||
React.useEffect(() => {
|
||||
if (process.env.NODE_ENV === "production") return
|
||||
if (mode === "columns") return
|
||||
warnCascaderOnce(
|
||||
`columns-outside-columns-mode:${mode}`,
|
||||
`\`CascaderColumns\` renders nothing in \`mode="${mode}"\`, so \`columnWidth\` and everything else on it does nothing. Set \`mode="columns"\` on the root, or render \`CascaderList\` instead.`
|
||||
)
|
||||
}, [mode])
|
||||
|
||||
if (mode !== "columns") return null
|
||||
|
||||
const height = maxHeightProp ?? maxHeight
|
||||
const toCss = (value: number | string) =>
|
||||
typeof value === "number" ? `${value}px` : value
|
||||
|
||||
return (
|
||||
<div
|
||||
data-slot="cascader-columns"
|
||||
role="group"
|
||||
aria-label={labels.columnsLabel}
|
||||
style={
|
||||
{
|
||||
"--cascader-column-width": toCss(columnWidth),
|
||||
/* Set only from an EXPLICIT cap: unset means "24rem or what the
|
||||
viewport leaves", via the `min()` fallback on the panel. A `?? 280`
|
||||
default here ignored short viewports and wasted tall ones. */
|
||||
...(height != null
|
||||
? { "--cascader-max-height": toCss(height) }
|
||||
: null),
|
||||
} as React.CSSProperties
|
||||
}
|
||||
className={cn(
|
||||
/* `max-h-full` with `min-h-0`: the trail is the panel's shrinking
|
||||
child, and the columns inside it size against this box. */
|
||||
"flex max-h-full min-h-0 items-stretch overflow-x-auto overscroll-x-contain",
|
||||
CASCADER_LIST_PAD_CLASS,
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
>
|
||||
{columns.map((column) =>
|
||||
children ? (
|
||||
<React.Fragment key={column.depth}>{children(column)}</React.Fragment>
|
||||
) : (
|
||||
<CascaderColumnPanel key={column.depth} column={column} />
|
||||
)
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* One column's box. `columnWidth` is the width of the LIST, not the box: under
|
||||
* `border-box` the 1px inline-start divider on every column but the first would
|
||||
* come out of the rows, so bordered columns are widened by that pixel. The box
|
||||
* is also the BOUND, the same `min(--available-height, cap)` the single list
|
||||
* uses, and the `ScrollArea` inside scrolls, so every column shows a thumb.
|
||||
*/
|
||||
const PANEL_CLASS = `flex w-(--cascader-column-width) shrink-0 flex-col overscroll-contain not-first:w-[calc(var(--cascader-column-width)_+_1px)] not-first:border-border/60 not-first:border-s ${CASCADER_LIST_HEIGHT_CLASS}`
|
||||
|
||||
export interface CascaderColumnPanelProps {
|
||||
column: CascaderColumn
|
||||
/** Replaces the panel's rows; the empty state still wins on an empty column. */
|
||||
children?: React.ReactNode
|
||||
/** Containing block for the windowed column's absolutely positioned rows. */
|
||||
virtualized?: boolean
|
||||
}
|
||||
|
||||
function CascaderColumnPanel({
|
||||
column,
|
||||
children,
|
||||
virtualized,
|
||||
}: CascaderColumnPanelProps) {
|
||||
const {
|
||||
labels,
|
||||
baseId,
|
||||
isBranch,
|
||||
isSelectable,
|
||||
isSelected,
|
||||
isIndeterminate,
|
||||
retryLevel,
|
||||
} = useCascaderActions()
|
||||
const { loadStates } = useCascaderState()
|
||||
|
||||
// Keyed per level, not one global flag: columns load and land independently.
|
||||
const columnKey = column.parent?.value ?? CASCADER_ROOT_KEY
|
||||
const loadState = loadStates.get(columnKey)
|
||||
|
||||
let emptyBody: React.ReactNode = labels.empty
|
||||
if (loadState?.error) {
|
||||
emptyBody = (
|
||||
<>
|
||||
{labels.error}{" "}
|
||||
<button
|
||||
type="button"
|
||||
data-slot="cascader-retry"
|
||||
onClick={() => retryLevel(columnKey)}
|
||||
className="text-foreground hover:bg-accent focus-visible:ring-ring/50 rounded-md px-1 font-medium outline-hidden transition-colors focus-visible:ring-2"
|
||||
>
|
||||
{labels.retry}
|
||||
</button>
|
||||
</>
|
||||
)
|
||||
} else if (loadState?.loading) {
|
||||
emptyBody = (
|
||||
<span className="flex items-center gap-1.5">
|
||||
<LoaderCircleIcon className="size-3.5 animate-spin" aria-hidden />
|
||||
{labels.loading}
|
||||
</span>
|
||||
)
|
||||
}
|
||||
|
||||
const rows =
|
||||
column.items.length === 0 ? (
|
||||
<p
|
||||
data-slot="cascader-column-empty"
|
||||
data-state={
|
||||
loadState?.error ? "error" : loadState?.loading ? "loading" : "empty"
|
||||
}
|
||||
className="text-muted-foreground px-2 py-1.5 text-sm"
|
||||
>
|
||||
{emptyBody}
|
||||
</p>
|
||||
) : (
|
||||
(children ??
|
||||
column.items.map((node, i) => {
|
||||
const open = node.value === column.activeValue
|
||||
return (
|
||||
<CascaderItem
|
||||
key={node.value}
|
||||
node={node}
|
||||
/* A trail row must not compete for `aria-activedescendant`. */
|
||||
as={column.active ? "option" : "button"}
|
||||
depth={column.depth}
|
||||
/* Answered here, not in the row: the trail rows are memoised too. */
|
||||
branch={isBranch(node)}
|
||||
selectable={isSelectable(node)}
|
||||
selected={isSelected(node)}
|
||||
indeterminate={isIndeterminate(node)}
|
||||
{...getCascaderMoreProps(node, loadStates)}
|
||||
data-open={open || undefined}
|
||||
className={open ? "bg-accent/60 text-accent-foreground" : undefined}
|
||||
/* Set metadata is option-only; a trail row is a `role="button"`. */
|
||||
{...(column.active
|
||||
? {
|
||||
"aria-setsize": column.items.length,
|
||||
"aria-posinset": i + 1,
|
||||
}
|
||||
: null)}
|
||||
{...(!column.active && open
|
||||
? {
|
||||
"aria-expanded": true,
|
||||
"aria-controls": `${baseId}-column-${column.depth + 1}`,
|
||||
}
|
||||
: null)}
|
||||
/>
|
||||
)
|
||||
}))
|
||||
)
|
||||
|
||||
const shared = {
|
||||
"data-slot": "cascader-column",
|
||||
"data-active": column.active || undefined,
|
||||
"data-depth": column.depth,
|
||||
// Addressable so the opening trail row can point `aria-controls` here, and
|
||||
// named even at the root, which has no parent label to borrow.
|
||||
id: `${baseId}-column-${column.depth}`,
|
||||
"aria-label": column.parent?.label ?? labels.rootLevel,
|
||||
// Conditional spread, never an explicit `undefined`: the active column is a
|
||||
// Base UI element, and its `mergeProps` iterates own keys.
|
||||
...(virtualized ? { "data-virtualized": true } : null),
|
||||
}
|
||||
|
||||
// A windowed row is absolutely positioned, so the ROWS' box is the containing
|
||||
// block, not the scrollport: it carries the padding the geometry is measured
|
||||
// against.
|
||||
const rowsClass = cn(CASCADER_ROWS_CLASS, virtualized && "relative")
|
||||
|
||||
// The active column IS the Combobox list: only rows inside `Combobox.List`
|
||||
// reach the CompositeList, arrow-key navigation and `aria-activedescendant`.
|
||||
const body = column.active ? (
|
||||
<ComboboxPrimitive.List {...shared} className={rowsClass}>
|
||||
{rows}
|
||||
</ComboboxPrimitive.List>
|
||||
) : (
|
||||
// A named `group`, not a second listbox competing with the active column.
|
||||
<div {...shared} role="group" className={rowsClass}>
|
||||
{rows}
|
||||
</div>
|
||||
)
|
||||
|
||||
return (
|
||||
<div
|
||||
data-slot="cascader-column-bounds"
|
||||
/* Repeated from `shared`: this box, not the semantic element, owns the
|
||||
width, the divider and the height, so style hooks must reach it, and
|
||||
`:first-child` on the semantic element no longer means "first column"
|
||||
(it is its own scrollport's only child). */
|
||||
data-active={column.active || undefined}
|
||||
data-depth={column.depth}
|
||||
className={PANEL_CLASS}
|
||||
>
|
||||
<ScrollArea className={CASCADER_SCROLL_CLASS}>{body}</ScrollArea>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export { CascaderColumnPanel, CascaderColumns }
|
||||
@@ -0,0 +1,316 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import type {
|
||||
CascaderActionItem,
|
||||
CascaderChangeReason,
|
||||
CascaderFlatNode,
|
||||
CascaderIndex,
|
||||
CascaderLabels,
|
||||
CascaderLoadState,
|
||||
CascaderMode,
|
||||
CascaderNode,
|
||||
CascaderSearchScope,
|
||||
} from "@/components/reui/cascader/cascader-types"
|
||||
|
||||
/**
|
||||
* Four contexts, not one: actions (config and callbacks, near-stable), state
|
||||
* (every keystroke), render (`renderItem` identity) and highlight (every arrow
|
||||
* key and pointer move). One combined context re-rendered every row on every
|
||||
* keystroke, which is what made `React.memo` on the row worth nothing.
|
||||
*/
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Shared types */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderColumn<T = unknown> {
|
||||
parent: CascaderNode<T> | null
|
||||
items: CascaderNode<T>[]
|
||||
depth: number
|
||||
/** The node in this column that is drilled into, if any. */
|
||||
activeValue: string | null
|
||||
/** Whether this is the deepest column, the one Base UI owns. */
|
||||
active: boolean
|
||||
}
|
||||
|
||||
export interface CascaderItemState<T = unknown> {
|
||||
branch: boolean
|
||||
selected: boolean
|
||||
disabled: boolean
|
||||
depth: number
|
||||
count: number
|
||||
/** Ancestor chain, root first. Populated for deep-search rows. */
|
||||
path: CascaderNode<T>[]
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* State */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Everything derived from the query, the path and the selection. One keystroke
|
||||
* rebuilds most of it, so never subscribe to it from a row.
|
||||
*/
|
||||
export interface CascaderStateContextValue<T = unknown> {
|
||||
/** Same `useMemo` identity as the actions context's `index`. */
|
||||
index: CascaderIndex<T>
|
||||
path: string[]
|
||||
expanded: ReadonlySet<string>
|
||||
query: string
|
||||
currentParent: CascaderNode<T> | null
|
||||
/** Rows for the current level, already filtered. */
|
||||
levelItems: CascaderNode<T>[]
|
||||
deepResults: CascaderNode<T>[] | null
|
||||
/** What `Combobox.Root` is currently rendering, in render order. */
|
||||
renderedItems: CascaderNode<T>[]
|
||||
columns: CascaderColumn<T>[]
|
||||
treeRows: CascaderFlatNode<T>[]
|
||||
selectedValues: string[]
|
||||
/** Selected nodes below each value, at any depth. Absent means zero. */
|
||||
selectedDescendants: ReadonlyMap<string, number>
|
||||
/**
|
||||
* Per level, keyed by parent value or `CASCADER_ROOT_KEY`. MEMBERSHIP is the
|
||||
* discriminator: no entry means never fetched, an entry with no `loading`, no
|
||||
* `error` and no children means fetched and genuinely empty.
|
||||
*/
|
||||
loadStates: ReadonlyMap<string, CascaderLoadState>
|
||||
/** Async search, `null` when idle. Separate: a search belongs to no level. */
|
||||
searchState: CascaderLoadState | null
|
||||
announcement: string
|
||||
}
|
||||
|
||||
const CascaderStateContext = React.createContext<
|
||||
CascaderStateContextValue | undefined
|
||||
>(undefined)
|
||||
|
||||
/**
|
||||
* One provider serves every `T`, so the context holds an erased `unknown` value
|
||||
* and this cast restores it. The primitive never inspects the payload.
|
||||
*/
|
||||
export function useCascaderState<T = unknown>(): CascaderStateContextValue<T> {
|
||||
const context = React.useContext(CascaderStateContext)
|
||||
if (!context) {
|
||||
throw new Error("useCascaderState must be used within a Cascader")
|
||||
}
|
||||
return context as unknown as CascaderStateContextValue<T>
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Actions */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Config and callbacks, slow enough that a memoised row can subscribe: the
|
||||
* mutators are `[]`-dep callbacks over a latest-props ref. The three predicates
|
||||
* are the exception, read DURING RENDER where a ref written in an effect would
|
||||
* return the previous commit's answer, so each is memoised on its own input.
|
||||
*/
|
||||
export interface CascaderActionsContextValue<T = unknown> {
|
||||
index: CascaderIndex<T>
|
||||
mode: CascaderMode
|
||||
multiple: boolean
|
||||
/** Multi-select only: a commit propagates over the LOADED subtree. */
|
||||
cascade: boolean
|
||||
/** Whether a BRANCH is committable. Per-LIST: the check gutter is a COLUMN. */
|
||||
branchesSelectable: boolean
|
||||
/** Draws the SINGLE-SELECT check and its gutter. Ignored in multi-select. */
|
||||
indicator: boolean
|
||||
expandTrigger?: "click" | "hover"
|
||||
actions: CascaderActionItem[]
|
||||
searchScope: CascaderSearchScope
|
||||
maxHeight?: number | string
|
||||
inline: boolean
|
||||
invalid: boolean
|
||||
/**
|
||||
* Id prefix; columns are `${baseId}-column-${depth}`. The SCHEME is contract:
|
||||
* the filters primitive's `FilterMenuPinKeeper` restores its highlight across
|
||||
* a live re-pin through `${baseId}-column-0` and the `cascader-item` slot.
|
||||
*/
|
||||
baseId: string
|
||||
labels: CascaderLabels
|
||||
|
||||
/**
|
||||
* Whether rows are WINDOWED. Also handed to `Combobox.Root`, which is what
|
||||
* makes an explicit row `index` legal: forwarding one while this is false
|
||||
* makes `aria-activedescendant` resolve to nothing. Latched per level.
|
||||
*/
|
||||
virtualized: boolean
|
||||
/** Mounts a windowing renderer, returns its unregister. LAYOUT effect only. */
|
||||
registerVirtualRenderer: () => () => void
|
||||
/** The root's `virtualize` prop. `undefined` means "decide by count". */
|
||||
virtualize?: boolean
|
||||
virtualizeThreshold: number
|
||||
estimateRowSize: number
|
||||
overscan: number
|
||||
|
||||
/** Tells "this level is empty" from "not fetched yet" before a load state. */
|
||||
hasLoader: boolean
|
||||
/** Next page of a level. Latched: a page with nothing new is not re-asked. */
|
||||
loadMore: (parentKey: string) => void
|
||||
retryLevel: (parentKey: string) => void
|
||||
/**
|
||||
* Evicts one level's async cache, `null` for the root, so membership reads
|
||||
* never-loaded. A level that is on screen when evicted refetches at once.
|
||||
*/
|
||||
invalidateLevel: (value: string | null) => void
|
||||
|
||||
/** Index as of the last commit. Use in the stable callbacks, not `index`. */
|
||||
getIndex: () => CascaderIndex<T>
|
||||
getState: () => CascaderStateContextValue<T>
|
||||
/** Highlighted row or null. A getter: the highlight moves per arrow key. */
|
||||
getHighlighted: () => CascaderNode<T> | null
|
||||
|
||||
setPath: (next: string[] | ((prev: string[]) => string[])) => void
|
||||
pushLevel: (value: string) => void
|
||||
popLevel: () => void
|
||||
goToDepth: (depth: number) => void
|
||||
toggleExpanded: (value: string) => void
|
||||
/**
|
||||
* Registers a footer submenu as open or closed. `Combobox` has no
|
||||
* `FloatingTree`, so one Escape would dismiss the flyout AND the cascader;
|
||||
* the root's `onOpenChange` guard cancels the close while any is open, from a
|
||||
* ref so it reads as of that event without re-rendering the root.
|
||||
*/
|
||||
setFlyoutOpen: (key: string, open: boolean) => void
|
||||
hasOpenFlyout: () => boolean
|
||||
setQuery: (next: string) => void
|
||||
/**
|
||||
* Replaces the selection. `onValueChange` diffs it against the current one
|
||||
* for its node and reason; pass `reason` only when the caller knows better.
|
||||
*/
|
||||
setSelection: (values: string[], reason?: CascaderChangeReason) => void
|
||||
/** Commits a node, for rows outside the listbox such as ancestor columns. */
|
||||
commit: (node: CascaderNode<T>) => void
|
||||
navigate: (node: CascaderNode<T>) => void
|
||||
/** Into `node` as a child of `depth`, replacing anything deeper. */
|
||||
navigateAt: (node: CascaderNode<T>, depth: number) => void
|
||||
/** Never undefined: falls back to a remembered label, then a synthetic node. */
|
||||
resolveNode: (value: string) => CascaderNode<T>
|
||||
isBranch: (node: CascaderNode<T>) => boolean
|
||||
isSelectable: (node: CascaderNode<T>) => boolean
|
||||
isSelected: (node: CascaderNode<T>) => boolean
|
||||
/** Always `false` without `cascade`: partial selection needs propagation. */
|
||||
isIndeterminate: (node: CascaderNode<T>) => boolean
|
||||
/**
|
||||
* O(1) read of `selectedDescendants`; a memoised row may not subscribe.
|
||||
* Unlike `isIndeterminate` this answers in every mode.
|
||||
*/
|
||||
selectedDescendantCount: (node: CascaderNode<T>) => number
|
||||
}
|
||||
|
||||
const CascaderActionsContext = React.createContext<
|
||||
CascaderActionsContextValue | undefined
|
||||
>(undefined)
|
||||
|
||||
export function useCascaderActions<
|
||||
T = unknown,
|
||||
>(): CascaderActionsContextValue<T> {
|
||||
const context = React.useContext(CascaderActionsContext)
|
||||
if (!context) {
|
||||
throw new Error("useCascaderActions must be used within a Cascader")
|
||||
}
|
||||
return context as unknown as CascaderActionsContextValue<T>
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Render props */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Their own context, republished every render. They cannot ride on the actions
|
||||
* context: an inline closure read off a memoised object is whichever closure
|
||||
* that object captured, so the row would call a stale prop over stale state.
|
||||
*/
|
||||
export interface CascaderRenderContextValue<T = unknown> {
|
||||
renderItem?: (
|
||||
node: CascaderNode<T>,
|
||||
state: CascaderItemState<T>
|
||||
) => React.ReactNode
|
||||
renderLabel?: (
|
||||
node: CascaderNode<T>,
|
||||
state: CascaderItemState<T>
|
||||
) => React.ReactNode
|
||||
}
|
||||
|
||||
const CascaderRenderContext = React.createContext<CascaderRenderContextValue>(
|
||||
{}
|
||||
)
|
||||
|
||||
export function useCascaderRender<
|
||||
T = unknown,
|
||||
>(): CascaderRenderContextValue<T> {
|
||||
return React.useContext(
|
||||
CascaderRenderContext
|
||||
) as CascaderRenderContextValue<T>
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Highlight store */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderHighlight {
|
||||
index: number
|
||||
value: string | null
|
||||
}
|
||||
|
||||
/**
|
||||
* An external store, deliberately NOT React state: `onItemHighlighted` fires on
|
||||
* every arrow key AND every pointer move over the list, so `setState` would
|
||||
* re-render the whole root at mousemove rate. A store re-renders subscribers
|
||||
* only, which inside the primitive is the virtualizer.
|
||||
*/
|
||||
export interface CascaderHighlightStore {
|
||||
subscribe: (onStoreChange: () => void) => () => void
|
||||
getSnapshot: () => CascaderHighlight
|
||||
set: (next: CascaderHighlight) => void
|
||||
}
|
||||
|
||||
const NO_HIGHLIGHT: CascaderHighlight = { index: -1, value: null }
|
||||
|
||||
export function createCascaderHighlightStore(): CascaderHighlightStore {
|
||||
let snapshot: CascaderHighlight = NO_HIGHLIGHT
|
||||
const listeners = new Set<() => void>()
|
||||
|
||||
return {
|
||||
subscribe(onStoreChange) {
|
||||
listeners.add(onStoreChange)
|
||||
return () => {
|
||||
listeners.delete(onStoreChange)
|
||||
}
|
||||
},
|
||||
// The SAME object until something changes; `useSyncExternalStore` needs it.
|
||||
getSnapshot() {
|
||||
return snapshot
|
||||
},
|
||||
set(next) {
|
||||
if (next.index === snapshot.index && next.value === snapshot.value) return
|
||||
snapshot = next
|
||||
for (const listener of listeners) listener()
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/** Shared and permanently empty, so the hook degrades outside a `Cascader`. */
|
||||
const FALLBACK_HIGHLIGHT_STORE = createCascaderHighlightStore()
|
||||
|
||||
const CascaderHighlightContext = React.createContext<CascaderHighlightStore>(
|
||||
FALLBACK_HIGHLIGHT_STORE
|
||||
)
|
||||
|
||||
/** Subscribes to the highlight. Re-renders ONLY the calling component. */
|
||||
export function useCascaderHighlight(): CascaderHighlight {
|
||||
const store = React.useContext(CascaderHighlightContext)
|
||||
return React.useSyncExternalStore(
|
||||
store.subscribe,
|
||||
store.getSnapshot,
|
||||
store.getSnapshot
|
||||
)
|
||||
}
|
||||
|
||||
export {
|
||||
CascaderActionsContext,
|
||||
CascaderHighlightContext,
|
||||
CascaderRenderContext,
|
||||
CascaderStateContext,
|
||||
}
|
||||
@@ -0,0 +1,733 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import { useCascaderActions } from "@/components/reui/cascader/cascader-context"
|
||||
import {
|
||||
CASCADER_ACTION_CLASS,
|
||||
CascaderGroup,
|
||||
CascaderLabel,
|
||||
} from "@/components/reui/cascader/cascader-item"
|
||||
import {
|
||||
CASCADER_LIST_PAD_CLASS,
|
||||
getCascaderFooterStops,
|
||||
isCascaderRtl,
|
||||
} from "@/components/reui/cascader/cascader-lib"
|
||||
import type { CascaderActionItem } from "@/components/reui/cascader/cascader-types"
|
||||
import { Popover as PopoverPrimitive } from "@base-ui/react"
|
||||
import { useDirection } from "@base-ui/react/direction-provider"
|
||||
|
||||
import { cn } from "@/lib/utils"
|
||||
import { ChevronRightIcon } from "lucide-react"
|
||||
|
||||
/**
|
||||
* The pinned footer, and the side-anchored flyout a footer row can open. These
|
||||
* are COMMANDS: nothing here joins the selection, the filter set or the
|
||||
* highlight. The flyout is a Base UI `Popover` rendered as a REACT CHILD of
|
||||
* `Combobox.Popup` with its OWN `Portal` and NO `container`: a nested portal
|
||||
* resolves to the parent portal node, so it is a DOM sibling of the combobox
|
||||
* popup (not clipped, not `aria-hidden`) but a React descendant, which is what
|
||||
* the outside-press and focus-out whitelists read. `Combobox` builds no
|
||||
* `FloatingTree`, so the flyout is not consulted first and one Escape would
|
||||
* dismiss both; hence `CascaderSubmenu` registering with the root to turn one
|
||||
* Escape into two. `Combobox.List` clicks its highlighted row on Enter, hence
|
||||
* the footer sitting outside `CascaderList`. And a `Positioner` throws without
|
||||
* its `Portal`, while `modal` stays `false` on the `Root` so the combobox
|
||||
* keeps its own dismissal behaviour.
|
||||
*/
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Footer */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Keys the option list acts on, swallowed at the footer boundary. Escape and
|
||||
* Tab are absent on purpose: Escape must reach the root, Tab must keep moving.
|
||||
*/
|
||||
const FOOTER_SWALLOWED_KEYS = new Set([
|
||||
"Enter",
|
||||
" ",
|
||||
"ArrowUp",
|
||||
"ArrowDown",
|
||||
"Home",
|
||||
"End",
|
||||
"PageUp",
|
||||
"PageDown",
|
||||
])
|
||||
|
||||
export type CascaderFooterProps = React.ComponentProps<"div">
|
||||
|
||||
/**
|
||||
* Actions pinned below the list, a SIBLING of `CascaderList`. Children win
|
||||
* over the root's `actions` prop; with neither it renders nothing.
|
||||
*/
|
||||
function CascaderFooter({
|
||||
className,
|
||||
children,
|
||||
onKeyDown,
|
||||
...props
|
||||
}: CascaderFooterProps) {
|
||||
const { actions, labels } = useCascaderActions()
|
||||
const hasChildren = React.Children.count(children) > 0
|
||||
|
||||
const handleKeyDown = React.useCallback(
|
||||
(event: React.KeyboardEvent<HTMLDivElement>) => {
|
||||
onKeyDown?.(event)
|
||||
if (event.defaultPrevented) return
|
||||
if (!FOOTER_SWALLOWED_KEYS.has(event.key)) return
|
||||
event.stopPropagation()
|
||||
|
||||
// The strip's own vertical movement, and the way back from the list's
|
||||
// hand-off: either end returns focus to the search field, from which
|
||||
// Base UI's empty highlight resumes the list. Down wraps to the FIELD,
|
||||
// not a command (traps the arrows) or a row (no imperative highlight).
|
||||
if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return
|
||||
const footer = event.currentTarget
|
||||
const stops = getCascaderFooterStops(footer)
|
||||
const active = document.activeElement as HTMLElement | null
|
||||
const index = active ? stops.indexOf(active) : -1
|
||||
if (index === -1) return
|
||||
event.preventDefault()
|
||||
const next =
|
||||
event.key === "ArrowDown" ? stops[index + 1] : stops[index - 1]
|
||||
if (next) {
|
||||
next.focus()
|
||||
return
|
||||
}
|
||||
if (event.key === "ArrowUp" && index > 0) return
|
||||
footer
|
||||
.closest<HTMLElement>('[data-slot="cascader-panel"]')
|
||||
?.querySelector<HTMLElement>('[data-slot="cascader-input"]')
|
||||
?.focus()
|
||||
},
|
||||
[onKeyDown]
|
||||
)
|
||||
|
||||
if (!hasChildren && actions.length === 0) return null
|
||||
|
||||
return (
|
||||
<div
|
||||
data-slot="cascader-footer"
|
||||
/* Named, not a bare div: without it a screen reader reaches the actions
|
||||
with nothing to say they are not more options. */
|
||||
role="group"
|
||||
aria-label={labels.actionsLabel}
|
||||
onKeyDown={handleKeyDown}
|
||||
className={cn(
|
||||
"border-border/60 flex shrink-0 flex-col gap-0.5 border-t",
|
||||
/* The LIST's padding, not a flat `p-1`: with a padding of its own the
|
||||
two columns of text were 2px out in luma and sera and 4px out in
|
||||
lyra. It also gives a separator in here a number to cancel. */
|
||||
CASCADER_LIST_PAD_CLASS,
|
||||
"p-(--cascader-list-pad,4px)",
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
>
|
||||
{hasChildren ? children : <CascaderFooterActions actions={actions} />}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function CascaderFooterActions({ actions }: { actions: CascaderActionItem[] }) {
|
||||
return (
|
||||
<>
|
||||
{actions.map((action, i) =>
|
||||
action.items?.length ? (
|
||||
<CascaderSubmenu key={actionKey(action, i)}>
|
||||
<CascaderSubmenuTrigger
|
||||
icon={action.icon}
|
||||
disabled={action.disabled}
|
||||
>
|
||||
{action.label}
|
||||
</CascaderSubmenuTrigger>
|
||||
<CascaderSubmenuContent>
|
||||
<CascaderActionList items={action.items} />
|
||||
</CascaderSubmenuContent>
|
||||
</CascaderSubmenu>
|
||||
) : (
|
||||
<CascaderAction
|
||||
key={actionKey(action, i)}
|
||||
icon={action.icon}
|
||||
disabled={action.disabled}
|
||||
onSelect={action.onSelect}
|
||||
>
|
||||
{action.label}
|
||||
</CascaderAction>
|
||||
)
|
||||
)}
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
function actionKey(action: CascaderActionItem, index: number): string {
|
||||
if (action.value != null) return action.value
|
||||
if (typeof action.label === "string") return action.label
|
||||
return String(index)
|
||||
}
|
||||
|
||||
/**
|
||||
* Consecutive entries sharing a `group`, as runs not buckets: two separated
|
||||
* runs with the same name stay two, so the author's order survives.
|
||||
*/
|
||||
function groupActionRuns(
|
||||
items: CascaderActionItem[]
|
||||
): { group?: string; items: CascaderActionItem[] }[] {
|
||||
const runs: { group?: string; items: CascaderActionItem[] }[] = []
|
||||
for (const item of items) {
|
||||
const last = runs[runs.length - 1]
|
||||
if (last && last.group === item.group) last.items.push(item)
|
||||
else runs.push({ group: item.group, items: [item] })
|
||||
}
|
||||
return runs
|
||||
}
|
||||
|
||||
/**
|
||||
* Flyout body for a data-driven submenu. A named run becomes a real
|
||||
* `CascaderGroup`; unnamed runs stay unwrapped, as an unnamed group is noise.
|
||||
*/
|
||||
function CascaderActionList({ items }: { items: CascaderActionItem[] }) {
|
||||
const { close } = useCascaderSubmenu()
|
||||
const runs = React.useMemo(() => groupActionRuns(items), [items])
|
||||
|
||||
const renderAction = (item: CascaderActionItem, i: number) => (
|
||||
<CascaderAction
|
||||
key={actionKey(item, i)}
|
||||
icon={item.icon}
|
||||
disabled={item.disabled}
|
||||
onSelect={() => {
|
||||
item.onSelect?.()
|
||||
/* Closes behind the command, or the entries would read as toggles. */
|
||||
close()
|
||||
}}
|
||||
>
|
||||
{item.label}
|
||||
</CascaderAction>
|
||||
)
|
||||
|
||||
return (
|
||||
<>
|
||||
{runs.map((run, runIndex) =>
|
||||
run.group ? (
|
||||
<CascaderGroup key={`${run.group}-${runIndex}`} className="gap-0.5">
|
||||
<CascaderLabel>{run.group}</CascaderLabel>
|
||||
{run.items.map(renderAction)}
|
||||
</CascaderGroup>
|
||||
) : (
|
||||
<React.Fragment key={`run-${runIndex}`}>
|
||||
{run.items.map(renderAction)}
|
||||
</React.Fragment>
|
||||
)
|
||||
)}
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Action */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderActionProps extends Omit<
|
||||
React.ComponentProps<"button">,
|
||||
"onSelect"
|
||||
> {
|
||||
icon?: React.ReactNode
|
||||
/** Fires on press, after `onClick`, and not at all when disabled. */
|
||||
onSelect?: () => void
|
||||
}
|
||||
|
||||
/**
|
||||
* The cascader popup's panel per style, spelled with `style-<name>:` variants
|
||||
* rather than ReUI theme CSS so an installed footer needs only Tailwind.
|
||||
*/
|
||||
const FLYOUT_SURFACE_CLASS =
|
||||
"bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 max-h-72 overflow-hidden ring-1 duration-100 ring-foreground/10 shadow-md rounded-lg"
|
||||
|
||||
/**
|
||||
* One footer command, shaped like a row and deliberately NOT one. A real
|
||||
* `<button>`, never a `Combobox.Item`: an item would join the arrow-key ring,
|
||||
* appear in `filteredItems`, and vanish the moment a query matched nothing -
|
||||
* exactly when "Create new attribute" is most useful. Disabled is
|
||||
* `aria-disabled`, never the native attribute: that one is not a tab stop and
|
||||
* the panel's Tab order reads `button:not([disabled])`, so a footer whose ONLY
|
||||
* row is a disabled command had no stop after the search field (measured on
|
||||
* `c-cascader-8`). Staying focusable costs the guards below, plus the
|
||||
* greyed-out look: `CASCADER_ACTION_CLASS` keys that off `aria-disabled`
|
||||
* instead of `:disabled`.
|
||||
*/
|
||||
function CascaderAction({
|
||||
className,
|
||||
icon,
|
||||
children,
|
||||
onSelect,
|
||||
onClick,
|
||||
onKeyDown,
|
||||
disabled,
|
||||
...props
|
||||
}: CascaderActionProps) {
|
||||
// Set by `CascaderSubmenuContent`: a plain button in the footer's Tab ring,
|
||||
// a roving-focus `menuitem` inside a flyout, never both.
|
||||
const inMenu = React.useContext(CascaderMenuContext)
|
||||
|
||||
const handleClick = React.useCallback(
|
||||
(event: React.MouseEvent<HTMLButtonElement>) => {
|
||||
// Before the consumer's handler: a disabled command runs none of them.
|
||||
if (disabled) {
|
||||
event.preventDefault()
|
||||
return
|
||||
}
|
||||
onClick?.(event)
|
||||
if (event.defaultPrevented) return
|
||||
onSelect?.()
|
||||
},
|
||||
[disabled, onClick, onSelect]
|
||||
)
|
||||
|
||||
const handleKeyDown = React.useCallback(
|
||||
(event: React.KeyboardEvent<HTMLButtonElement>) => {
|
||||
if (disabled) {
|
||||
// The two keys a `<button>` activates on, and only those.
|
||||
if (event.key === "Enter" || event.key === " ") event.preventDefault()
|
||||
return
|
||||
}
|
||||
onKeyDown?.(event)
|
||||
},
|
||||
[disabled, onKeyDown]
|
||||
)
|
||||
|
||||
return (
|
||||
<button
|
||||
type="button"
|
||||
data-slot="cascader-action"
|
||||
/* Conditional spread: `false` would publish `aria-disabled="false"`. */
|
||||
{...(disabled ? { "aria-disabled": true, "data-disabled": "" } : null)}
|
||||
onClick={handleClick}
|
||||
onKeyDown={handleKeyDown}
|
||||
/* Conditional spread, so a consumer's own `role` or `tabIndex` wins. */
|
||||
{...(inMenu ? { role: "menuitem" as const, tabIndex: -1 } : null)}
|
||||
className={cn(CASCADER_ACTION_CLASS, className)}
|
||||
{...props}
|
||||
>
|
||||
{icon ? (
|
||||
<span
|
||||
data-slot="cascader-action-icon"
|
||||
className="text-muted-foreground flex shrink-0 items-center justify-center"
|
||||
>
|
||||
{icon}
|
||||
</span>
|
||||
) : null}
|
||||
<span className="min-w-0 flex-1 truncate text-start">{children}</span>
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Submenu */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
interface CascaderSubmenuContextValue {
|
||||
rowRef: React.RefObject<HTMLButtonElement | null>
|
||||
open: boolean
|
||||
setOpen: (open: boolean) => void
|
||||
close: () => void
|
||||
/** Names the flyout: a menu is labelled by the control that opens it. */
|
||||
triggerId: string
|
||||
/**
|
||||
* Whether the pending open came from the KEYBOARD. Base UI's own `openType`
|
||||
* calls the opening arrow a POINTER open, because the trigger intercepts it
|
||||
* and calls `setOpen` (measured: focus landed on the popup, not the first
|
||||
* entry). A ref, so reading it in the focus phase cannot render.
|
||||
*/
|
||||
keyboardRef: React.RefObject<boolean>
|
||||
}
|
||||
|
||||
/** Marks the subtree INSIDE a flyout. See `inMenu` in `CascaderAction`. */
|
||||
const CascaderMenuContext = React.createContext(false)
|
||||
|
||||
/**
|
||||
* Every entry a menu's roving focus may land on, in DOM order, read from the
|
||||
* DOM because the entries are whatever the consumer composed. A disabled
|
||||
* `CascaderAction` is INCLUDED: it carries `aria-disabled`, not the native
|
||||
* attribute, so `:not([disabled])` excludes only a consumer's own natively
|
||||
* disabled `menuitem`, which cannot take focus.
|
||||
*/
|
||||
function menuItems(popup: HTMLElement | null): HTMLElement[] {
|
||||
if (!popup) return []
|
||||
return Array.from(
|
||||
popup.querySelectorAll<HTMLElement>('[role="menuitem"]:not([disabled])')
|
||||
)
|
||||
}
|
||||
|
||||
const CascaderSubmenuContext = React.createContext<
|
||||
CascaderSubmenuContextValue | undefined
|
||||
>(undefined)
|
||||
|
||||
/** The flyout's own state. `close()` is the one a custom entry usually wants. */
|
||||
export function useCascaderSubmenu(): CascaderSubmenuContextValue {
|
||||
const context = React.useContext(CascaderSubmenuContext)
|
||||
if (!context) {
|
||||
throw new Error("useCascaderSubmenu must be used within a CascaderSubmenu")
|
||||
}
|
||||
return context
|
||||
}
|
||||
|
||||
export interface CascaderSubmenuProps {
|
||||
open?: boolean
|
||||
defaultOpen?: boolean
|
||||
onOpenChange?: (open: boolean) => void
|
||||
children?: React.ReactNode
|
||||
}
|
||||
|
||||
/**
|
||||
* A footer row plus the flyout it opens. Registers with the cascader root
|
||||
* while open, which turns one Escape into two. Cleared in an EFFECT, so the
|
||||
* flyout still reads as open during the event that closed it.
|
||||
*/
|
||||
function CascaderSubmenu({
|
||||
open: openProp,
|
||||
defaultOpen = false,
|
||||
onOpenChange,
|
||||
children,
|
||||
}: CascaderSubmenuProps) {
|
||||
const { setFlyoutOpen } = useCascaderActions()
|
||||
const key = React.useId()
|
||||
const triggerId = React.useId()
|
||||
const rowRef = React.useRef<HTMLButtonElement | null>(null)
|
||||
const keyboardRef = React.useRef(false)
|
||||
const [uncontrolled, setUncontrolled] = React.useState(defaultOpen)
|
||||
const open = openProp ?? uncontrolled
|
||||
|
||||
const setOpen = React.useCallback(
|
||||
(next: boolean) => {
|
||||
if (openProp == null) setUncontrolled(next)
|
||||
onOpenChange?.(next)
|
||||
},
|
||||
[openProp, onOpenChange]
|
||||
)
|
||||
|
||||
const close = React.useCallback(() => setOpen(false), [setOpen])
|
||||
|
||||
React.useEffect(() => {
|
||||
setFlyoutOpen(key, open)
|
||||
return () => setFlyoutOpen(key, false)
|
||||
}, [setFlyoutOpen, key, open])
|
||||
|
||||
const context = React.useMemo<CascaderSubmenuContextValue>(
|
||||
() => ({ rowRef, open, setOpen, close, triggerId, keyboardRef }),
|
||||
[open, setOpen, close, triggerId]
|
||||
)
|
||||
|
||||
return (
|
||||
<CascaderSubmenuContext.Provider value={context}>
|
||||
<PopoverPrimitive.Root
|
||||
open={open}
|
||||
onOpenChange={setOpen}
|
||||
/* NEVER modal: it would disable the combobox that owns it. */
|
||||
modal={false}
|
||||
>
|
||||
{children}
|
||||
</PopoverPrimitive.Root>
|
||||
</CascaderSubmenuContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export interface CascaderSubmenuTriggerProps extends Omit<
|
||||
React.ComponentProps<"button">,
|
||||
"onSelect"
|
||||
> {
|
||||
icon?: React.ReactNode
|
||||
}
|
||||
|
||||
/** Carries the handler-veto hook, derived so a Base UI bump cannot drift. */
|
||||
type CascaderSubmenuTriggerClickEvent = Parameters<
|
||||
NonNullable<PopoverPrimitive.Trigger.Props["onClick"]>
|
||||
>[0]
|
||||
|
||||
/**
|
||||
* The footer row that opens the flyout, and its anchor. `aria-haspopup="menu"`
|
||||
* rather than the `dialog` Base UI would announce: what opens is a list of
|
||||
* commands with roving focus. `disabled` is intercepted, not forwarded:
|
||||
* `Popover.Trigger` runs it through `useButton`, which writes the NATIVE
|
||||
* attribute for a native `<button>` and takes the row out of the panel's Tab
|
||||
* ring, the defect `CascaderAction` documents, and this component exposes no
|
||||
* `focusableWhenDisabled` to opt out. Published as `aria-disabled`, with the
|
||||
* arrow keys, Enter and Space, and the click closed by hand (`useClick`
|
||||
* ignores `defaultPrevented`).
|
||||
*/
|
||||
function CascaderSubmenuTrigger({
|
||||
className,
|
||||
icon,
|
||||
children,
|
||||
onKeyDown,
|
||||
onClick,
|
||||
disabled,
|
||||
...props
|
||||
}: CascaderSubmenuTriggerProps) {
|
||||
const { labels } = useCascaderActions()
|
||||
const { rowRef, setOpen, triggerId, keyboardRef } = useCascaderSubmenu()
|
||||
const direction = useDirection()
|
||||
|
||||
const handleClick = React.useCallback(
|
||||
(event: CascaderSubmenuTriggerClickEvent) => {
|
||||
if (disabled) {
|
||||
// `mergeProps` runs right to left, so this drops Base UI's own handler.
|
||||
event.preventDefault()
|
||||
event.preventBaseUIHandler()
|
||||
return
|
||||
}
|
||||
onClick?.(event)
|
||||
},
|
||||
[disabled, onClick]
|
||||
)
|
||||
|
||||
const handleKeyDown = React.useCallback(
|
||||
(event: React.KeyboardEvent<HTMLButtonElement>) => {
|
||||
if (disabled) {
|
||||
if (event.key === "Enter" || event.key === " ") event.preventDefault()
|
||||
return
|
||||
}
|
||||
|
||||
onKeyDown?.(event)
|
||||
if (event.defaultPrevented) return
|
||||
|
||||
// The opening key points AT the flyout, so it flips with the writing
|
||||
// direction; ArrowDown stays "next command". Resolved per keydown, never
|
||||
// `useDirection()` alone: with no provider that answers "ltr" in RTL.
|
||||
const openKey = isCascaderRtl(event.currentTarget, direction)
|
||||
? "ArrowLeft"
|
||||
: "ArrowRight"
|
||||
|
||||
// Enter and Space open through the button's own click, so only FLAGGED.
|
||||
if (event.key === "Enter" || event.key === " ") {
|
||||
keyboardRef.current = true
|
||||
return
|
||||
}
|
||||
|
||||
if (event.key !== openKey) return
|
||||
|
||||
event.preventDefault()
|
||||
keyboardRef.current = true
|
||||
setOpen(true)
|
||||
},
|
||||
[disabled, onKeyDown, direction, setOpen, keyboardRef]
|
||||
)
|
||||
|
||||
return (
|
||||
<PopoverPrimitive.Trigger
|
||||
ref={rowRef}
|
||||
id={triggerId}
|
||||
data-slot="cascader-submenu-trigger"
|
||||
aria-haspopup="menu"
|
||||
/* NOT `disabled={disabled}`: Base UI writes the native attribute. */
|
||||
{...(disabled ? { "aria-disabled": true, "data-disabled": "" } : null)}
|
||||
onClick={handleClick}
|
||||
onKeyDown={handleKeyDown}
|
||||
className={cn(
|
||||
CASCADER_ACTION_CLASS,
|
||||
/* Painted while the flyout is open, as shadcn paints a SubTrigger.
|
||||
Keyed off `aria-expanded`, not shadcn's `data-[state=open]`: the
|
||||
popover trigger carries `aria-expanded` in both states. */
|
||||
"aria-expanded:bg-accent aria-expanded:text-accent-foreground",
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
>
|
||||
{icon ? (
|
||||
<span
|
||||
data-slot="cascader-action-icon"
|
||||
className="text-muted-foreground flex shrink-0 items-center justify-center"
|
||||
>
|
||||
{icon}
|
||||
</span>
|
||||
) : null}
|
||||
<span className="min-w-0 flex-1 truncate text-start">{children}</span>
|
||||
{/* Nothing else says the row opens a MENU, not another tree level. */}
|
||||
<span className="sr-only">, {labels.submenuAffordance}</span>
|
||||
<ChevronRightIcon aria-hidden="true" className="text-muted-foreground -me-0.5 size-4 shrink-0 rtl:-scale-x-100" />
|
||||
</PopoverPrimitive.Trigger>
|
||||
)
|
||||
}
|
||||
|
||||
export interface CascaderSubmenuContentProps
|
||||
extends
|
||||
PopoverPrimitive.Popup.Props,
|
||||
Pick<
|
||||
PopoverPrimitive.Positioner.Props,
|
||||
"side" | "align" | "sideOffset" | "alignOffset"
|
||||
> {}
|
||||
|
||||
/** Carries Base UI's handler-veto hook, so a plain React event will not do. */
|
||||
type CascaderSubmenuKeyEvent = Parameters<
|
||||
NonNullable<PopoverPrimitive.Popup.Props["onKeyDown"]>
|
||||
>[0]
|
||||
|
||||
/**
|
||||
* The flyout itself. `Portal` with NO `container`: a nested portal resolves to
|
||||
* the parent portal node, the mechanism the file header describes.
|
||||
*/
|
||||
function CascaderSubmenuContent({
|
||||
className,
|
||||
children,
|
||||
onKeyDown,
|
||||
side = "inline-end",
|
||||
align = "end",
|
||||
sideOffset = 8,
|
||||
alignOffset = 0,
|
||||
...props
|
||||
}: CascaderSubmenuContentProps) {
|
||||
const { rowRef, close, triggerId, keyboardRef } = useCascaderSubmenu()
|
||||
const direction = useDirection()
|
||||
const popupRef = React.useRef<HTMLDivElement | null>(null)
|
||||
const typeaheadRef = React.useRef({ buffer: "", at: 0 })
|
||||
|
||||
/**
|
||||
* Keyboard opens land on the first entry; a pointer open falls through to
|
||||
* Base UI's default, the popup, so a click paints no focus ring. Not an
|
||||
* effect of our own: Base UI's focus manager runs on open and wins the race.
|
||||
*/
|
||||
const initialFocus = React.useCallback(() => {
|
||||
const byKeyboard = keyboardRef.current
|
||||
keyboardRef.current = false
|
||||
if (!byKeyboard) return true
|
||||
return menuItems(popupRef.current)[0] ?? true
|
||||
}, [keyboardRef])
|
||||
|
||||
const closeAndReturn = React.useCallback(() => {
|
||||
close()
|
||||
rowRef.current?.focus()
|
||||
}, [close, rowRef])
|
||||
|
||||
const handleKeyDown = React.useCallback(
|
||||
(event: CascaderSubmenuKeyEvent) => {
|
||||
onKeyDown?.(event)
|
||||
// A DOM sibling of the combobox popup but a REACT descendant, so keys in
|
||||
// here reach its handlers unless stopped. Enter would commit a row.
|
||||
event.stopPropagation()
|
||||
if (event.defaultPrevented) return
|
||||
|
||||
const popup = popupRef.current
|
||||
const items = menuItems(popup)
|
||||
if (items.length === 0) return
|
||||
|
||||
const active = document.activeElement as HTMLElement | null
|
||||
const index = active ? items.indexOf(active) : -1
|
||||
const move = (next: number) => {
|
||||
event.preventDefault()
|
||||
items[(next + items.length) % items.length]?.focus()
|
||||
}
|
||||
|
||||
// Mirrors the open key on the SAME per-keydown answer as the trigger.
|
||||
const closeKey = isCascaderRtl(event.currentTarget, direction)
|
||||
? "ArrowRight"
|
||||
: "ArrowLeft"
|
||||
|
||||
switch (event.key) {
|
||||
case "ArrowDown":
|
||||
return move(index + 1)
|
||||
case "ArrowUp":
|
||||
// From the popup itself (a pointer open) Up means the LAST entry.
|
||||
return move(index === -1 ? items.length - 1 : index - 1)
|
||||
case "Home":
|
||||
return move(0)
|
||||
case "End":
|
||||
return move(items.length - 1)
|
||||
case closeKey:
|
||||
event.preventDefault()
|
||||
return closeAndReturn()
|
||||
case "Tab":
|
||||
// A menu never holds Tab: it closes and focus carries on from its row.
|
||||
close()
|
||||
rowRef.current?.focus()
|
||||
return
|
||||
default:
|
||||
break
|
||||
}
|
||||
|
||||
// Typeahead, after the switch so it can never swallow a navigation key.
|
||||
if (
|
||||
event.key.length !== 1 ||
|
||||
event.metaKey ||
|
||||
event.ctrlKey ||
|
||||
event.altKey
|
||||
)
|
||||
return
|
||||
const now = event.timeStamp
|
||||
const state = typeaheadRef.current
|
||||
state.buffer = now - state.at > 500 ? event.key : state.buffer + event.key
|
||||
state.at = now
|
||||
const prefix = state.buffer.toLowerCase()
|
||||
const from = index === -1 ? 0 : index
|
||||
// Starts AFTER the current entry so one letter cycles rather than sticks.
|
||||
const ordered = [
|
||||
...items.slice(state.buffer.length > 1 ? from : from + 1),
|
||||
...items.slice(0, state.buffer.length > 1 ? from : from + 1),
|
||||
]
|
||||
const hit = ordered.find((item) =>
|
||||
(item.textContent ?? "").trim().toLowerCase().startsWith(prefix)
|
||||
)
|
||||
if (hit) {
|
||||
event.preventDefault()
|
||||
hit.focus()
|
||||
}
|
||||
},
|
||||
[onKeyDown, direction, close, closeAndReturn, rowRef]
|
||||
)
|
||||
|
||||
return (
|
||||
<PopoverPrimitive.Portal>
|
||||
<PopoverPrimitive.Positioner
|
||||
/* The ROW, not whatever Base UI last treated as the trigger. */
|
||||
anchor={rowRef}
|
||||
side={side}
|
||||
align={align}
|
||||
sideOffset={sideOffset}
|
||||
alignOffset={alignOffset}
|
||||
className="isolate z-50"
|
||||
>
|
||||
<PopoverPrimitive.Popup
|
||||
ref={popupRef}
|
||||
initialFocus={initialFocus}
|
||||
data-slot="cascader-submenu-content"
|
||||
/* Roving focus, named by the row that opens it. `tabIndex={-1}` lets
|
||||
a pointer open park focus here without adding a Tab stop. */
|
||||
role="menu"
|
||||
aria-orientation="vertical"
|
||||
aria-labelledby={triggerId}
|
||||
tabIndex={-1}
|
||||
onKeyDown={handleKeyDown}
|
||||
/* Marks a menu surface for the docs design-system picker, which
|
||||
repaints menus by walking the DOM. An attribute, not a class. */
|
||||
data-menu-target=""
|
||||
className={cn(
|
||||
FLYOUT_SURFACE_CLASS,
|
||||
"flex max-w-(--available-width) min-w-48 flex-col gap-0.5 outline-hidden",
|
||||
CASCADER_LIST_PAD_CLASS,
|
||||
"p-(--cascader-list-pad,4px)",
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
>
|
||||
<CascaderMenuContext.Provider value={true}>
|
||||
{children}
|
||||
</CascaderMenuContext.Provider>
|
||||
</PopoverPrimitive.Popup>
|
||||
</PopoverPrimitive.Positioner>
|
||||
</PopoverPrimitive.Portal>
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the footer would render anything, for a wrapper (a separator, a grid
|
||||
* row) that has to make the same call `CascaderFooter` already makes.
|
||||
*/
|
||||
export function useCascaderHasActions(): boolean {
|
||||
const { actions } = useCascaderActions()
|
||||
return actions.length > 0
|
||||
}
|
||||
|
||||
export {
|
||||
CascaderAction,
|
||||
CascaderFooter,
|
||||
CascaderSubmenu,
|
||||
CascaderSubmenuContent,
|
||||
CascaderSubmenuTrigger,
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
import type {
|
||||
CascaderLabels,
|
||||
CascaderMode,
|
||||
} from "@/components/reui/cascader/cascader-types"
|
||||
|
||||
/** Name of the root level. Hoisted so the root announcement can reuse it. */
|
||||
const ROOT_LEVEL = "Top level"
|
||||
|
||||
/** Hoisted for the same reason: several defaults end in an item count. */
|
||||
const itemCount = (count: number) =>
|
||||
`${count} ${count === 1 ? "item" : "items"}`
|
||||
|
||||
/**
|
||||
* English defaults. Every string the primitive can render lives here, so a
|
||||
* consumer can translate the whole surface by passing `labels`.
|
||||
*/
|
||||
export const CASCADER_LABELS: CascaderLabels = {
|
||||
// Deliberately NOT lowercased. `toLowerCase()` is locale-hostile - it maps
|
||||
// Turkish "İ" to a two-code-point sequence and German "İstanbul" style
|
||||
// proper nouns lose their casing - and a label is already written the way
|
||||
// its author wants it read.
|
||||
search: (parentLabel) =>
|
||||
parentLabel ? `Search ${parentLabel}...` : "Search...",
|
||||
back: "Back",
|
||||
loading: "Loading...",
|
||||
loadingMore: "Loading more...",
|
||||
loadMore: "Load more",
|
||||
error: "Could not load items.",
|
||||
retry: "Retry",
|
||||
empty: "No results found.",
|
||||
selectedCount: (count) => `${count} selected`,
|
||||
breadcrumbLabel: "Breadcrumb",
|
||||
chipsLabel: "Selected items",
|
||||
removeChip: (label) => `Remove ${label}`,
|
||||
pathSeparator: "/",
|
||||
rootLevel: ROOT_LEVEL,
|
||||
itemCount,
|
||||
branchAffordance: "submenu",
|
||||
selectedState: "selected",
|
||||
partiallySelectedState: "partially selected",
|
||||
columnsLabel: "Levels",
|
||||
actionsLabel: "Actions",
|
||||
submenuAffordance: "opens a menu",
|
||||
panelLabel: "Options",
|
||||
keyboardHint: (mode: CascaderMode, dir: "ltr" | "rtl") => {
|
||||
// "Deeper" is the direction the text runs, so the level keys mirror in
|
||||
// RTL and the hint has to name the mirrored pair there - an LTR-worded
|
||||
// hint would teach exactly the wrong keys.
|
||||
const open = dir === "rtl" ? "Left" : "Right"
|
||||
const back = dir === "rtl" ? "Right" : "Left"
|
||||
if (mode === "tree") {
|
||||
return `Use the ${open} Arrow key to expand and the ${back} Arrow key to collapse.`
|
||||
}
|
||||
if (mode === "columns") {
|
||||
return `Use the ${open} Arrow key to open the next column and the ${back} Arrow key to go back.`
|
||||
}
|
||||
return `Use the ${open} Arrow key to open a branch and the ${back} Arrow key to go back.`
|
||||
},
|
||||
rootAnnouncement: (count) => `${ROOT_LEVEL}, ${itemCount(count)}`,
|
||||
expandedAnnouncement: (label, count) =>
|
||||
`${label} expanded, ${itemCount(count)}`,
|
||||
collapsedAnnouncement: (label) => `${label} collapsed`,
|
||||
levelAnnouncement: (parentLabel, depth, count) =>
|
||||
`${parentLabel}, level ${depth}, ${itemCount(count)}`,
|
||||
resultsAnnouncement: (count) =>
|
||||
count === 1 ? "1 result" : `${count} results`,
|
||||
maxReachedAnnouncement: (max) => `Selection limit of ${max} reached`,
|
||||
cascadeAnnouncement: (label, count, selecting) =>
|
||||
`${label} ${selecting ? "selected" : "deselected"}, ${itemCount(count)} followed`,
|
||||
searchingAnnouncement: "Searching...",
|
||||
}
|
||||
|
||||
/**
|
||||
* Shallow-merges consumer overrides over the defaults, so `labels` can carry a
|
||||
* single key without restating the rest.
|
||||
*/
|
||||
export function resolveCascaderLabels(
|
||||
labels?: Partial<CascaderLabels>
|
||||
): CascaderLabels {
|
||||
if (!labels) return CASCADER_LABELS
|
||||
return { ...CASCADER_LABELS, ...labels }
|
||||
}
|
||||
|
||||
/** Resolves the search placeholder, which may be a string or a function. */
|
||||
export function resolveCascaderSearchLabel(
|
||||
labels: CascaderLabels,
|
||||
parentLabel?: string
|
||||
): string {
|
||||
return typeof labels.search === "function"
|
||||
? labels.search(parentLabel)
|
||||
: labels.search
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,854 @@
|
||||
import type {
|
||||
CascaderCollapse,
|
||||
CascaderFlatNode,
|
||||
CascaderIndex,
|
||||
CascaderNode,
|
||||
CascaderPathSegment,
|
||||
CascaderSelectable,
|
||||
} from "@/components/reui/cascader/cascader-types"
|
||||
|
||||
/** Root level key in `childrenOf`. NUL-prefixed so no real value collides. */
|
||||
export const CASCADER_ROOT_KEY = "\u0000root"
|
||||
|
||||
/**
|
||||
* Paging pseudo-node prefix. Written as an escape sequence, not a raw 0x00
|
||||
* byte: a literal NUL makes this module read as binary and `grep -I` skips it.
|
||||
*/
|
||||
export const CASCADER_MORE_PREFIX = "\u0000more:"
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Scroll layout */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* The four scroll classes. In the lib because `cascader-columns.tsx` needs them
|
||||
* too and must not import `cascader.tsx`. Shell > bound > scrollport > rows.
|
||||
*/
|
||||
|
||||
/**
|
||||
* The bound. `min()` over an undefined custom property is an INVALID
|
||||
* declaration that drops the whole max-height, hence the `100vh` fallback: an
|
||||
* inline panel has no positioner, so no `--available-height`. `24rem` is the
|
||||
* default cap, so the common case sets no variable at all.
|
||||
*/
|
||||
export const CASCADER_LIST_HEIGHT_CLASS =
|
||||
"max-h-[min(var(--available-height,100vh),var(--cascader-max-height,24rem))]"
|
||||
|
||||
/**
|
||||
* Each style's list padding: rows take it as `padding`, the scrollport as
|
||||
* `scroll-padding` floored at 4px so lyra's `0` does not strand a row.
|
||||
* Mirrored per style from `registry/styles/style-*.css`; keep them in step.
|
||||
*/
|
||||
export const CASCADER_LIST_PAD_CLASS =
|
||||
"[--cascader-list-pad:4px]"
|
||||
|
||||
/** The scrollport: a `max-h-*` on the ScrollArea ROOT bounds nothing. */
|
||||
export const CASCADER_SCROLL_CLASS =
|
||||
"size-full min-h-0 **:data-[slot=scroll-area-viewport]:h-full **:data-[slot=scroll-area-viewport]:overscroll-contain **:data-[slot=scroll-area-viewport]:scroll-py-[max(var(--cascader-list-pad,4px),4px)]"
|
||||
|
||||
/** The rows' box; `data-empty:p-0` keeps an empty state from double inset. */
|
||||
export const CASCADER_ROWS_CLASS = "p-(--cascader-list-pad,4px) data-empty:p-0"
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Tab order */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* What counts as a keyboard stop. Base UI's ScrollArea viewport makes ITSELF
|
||||
* tabbable when content overflows (`hiddenState.x && hiddenState.y ? -1 : 0`),
|
||||
* an unnamed stop per level that `ui/scroll-area.tsx` will not let us suppress.
|
||||
*/
|
||||
const CASCADER_TAB_STOP_SELECTOR =
|
||||
'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'
|
||||
|
||||
/** The stop to step over: nothing here focuses the scrollport on purpose. */
|
||||
const CASCADER_TAB_SKIP_SELECTOR = '[data-slot="scroll-area-viewport"]'
|
||||
|
||||
/** Out of the tab order whatever they contain; layout is never consulted. */
|
||||
const CASCADER_TAB_HIDDEN_SELECTOR = "[hidden],[inert],[aria-hidden='true']"
|
||||
|
||||
/** The panel's real keyboard stops, in DOM order. */
|
||||
function getCascaderTabStops(panel: HTMLElement): HTMLElement[] {
|
||||
const stops = Array.from(
|
||||
panel.querySelectorAll<HTMLElement>(CASCADER_TAB_STOP_SELECTOR)
|
||||
)
|
||||
return stops.filter(
|
||||
(stop) =>
|
||||
// Option and trail rows are real `<button>`s with `tabindex="-1"`.
|
||||
stop.getAttribute("tabindex") !== "-1" &&
|
||||
!stop.matches(CASCADER_TAB_SKIP_SELECTOR) &&
|
||||
!stop.closest(CASCADER_TAB_HIDDEN_SELECTOR)
|
||||
)
|
||||
}
|
||||
|
||||
/** The footer's own stops; an `aria-disabled` command still counts as one. */
|
||||
export function getCascaderFooterStops(scope: HTMLElement): HTMLElement[] {
|
||||
const footer = scope.matches('[data-slot="cascader-footer"]')
|
||||
? scope
|
||||
: scope.querySelector<HTMLElement>('[data-slot="cascader-footer"]')
|
||||
if (!footer) return []
|
||||
return getCascaderTabStops(footer)
|
||||
}
|
||||
|
||||
/** Where Tab lands, or `null` to let the browser out: focus is never trapped. */
|
||||
export function getCascaderTabTarget(
|
||||
panel: HTMLElement,
|
||||
from: Element | null,
|
||||
backwards: boolean
|
||||
): HTMLElement | null {
|
||||
const stops = getCascaderTabStops(panel)
|
||||
if (stops.length === 0 || !from) return null
|
||||
|
||||
const index = stops.indexOf(from as HTMLElement)
|
||||
if (index !== -1) return stops[index + (backwards ? -1 : 1)] ?? null
|
||||
|
||||
if (backwards) {
|
||||
for (let i = stops.length - 1; i >= 0; i -= 1) {
|
||||
const position = from.compareDocumentPosition(stops[i])
|
||||
if (position & Node.DOCUMENT_POSITION_PRECEDING) return stops[i]
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
for (const stop of stops) {
|
||||
const position = from.compareDocumentPosition(stop)
|
||||
if (position & Node.DOCUMENT_POSITION_FOLLOWING) return stop
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* The writing direction at `element`. `DirectionProvider` may only vote yes:
|
||||
* unmounted it answers `"ltr"`, which would override a real `<html dir="rtl">`.
|
||||
*/
|
||||
export function isCascaderRtl(element: Element, provided: string): boolean {
|
||||
if (provided === "rtl") return true
|
||||
const explicit = element.closest("[dir]")?.getAttribute("dir")?.toLowerCase()
|
||||
if (explicit === "rtl") return true
|
||||
if (explicit === "ltr") return false
|
||||
return (
|
||||
element.ownerDocument?.defaultView?.getComputedStyle(element).direction ===
|
||||
"rtl"
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* The paging row as a REAL node, not a DOM-only row after the list: every index
|
||||
* Base UI hands out indexes the RENDERED array, so a DOM-only row shifts them.
|
||||
*/
|
||||
export function createCascaderMoreNode<T = unknown>(
|
||||
parentKey: string,
|
||||
loadedCount = 0
|
||||
): CascaderNode<T> {
|
||||
return {
|
||||
value: `${CASCADER_MORE_PREFIX}${parentKey}`,
|
||||
// Empty on purpose: a typeahead letter must never reach the paging row.
|
||||
label: "",
|
||||
// Feeds the row's "Loading more..." wording, with no second prop to thread.
|
||||
count: loadedCount,
|
||||
}
|
||||
}
|
||||
|
||||
export function isCascaderMoreNode<T>(node: CascaderNode<T>): boolean {
|
||||
return node.value.startsWith(CASCADER_MORE_PREFIX)
|
||||
}
|
||||
|
||||
/** The level key a paging pseudo-node belongs to, or `null` for a real node. */
|
||||
export function getCascaderMoreParent<T>(node: CascaderNode<T>): string | null {
|
||||
if (!isCascaderMoreNode(node)) return null
|
||||
return node.value.slice(CASCADER_MORE_PREFIX.length)
|
||||
}
|
||||
|
||||
/** Either input shape into one index. Cycle-guarded depths; first wins. */
|
||||
export function buildCascaderIndex<T = unknown>(
|
||||
items: readonly CascaderNode<T>[] | undefined,
|
||||
getParent?: (node: CascaderNode<T>) => string | null | undefined
|
||||
): CascaderIndex<T> {
|
||||
const byValue = new Map<string, CascaderNode<T>>()
|
||||
const childrenOf = new Map<string, CascaderNode<T>[]>()
|
||||
const parentOf = new Map<string, string | null>()
|
||||
const depthOf = new Map<string, number>()
|
||||
const all: CascaderNode<T>[] = []
|
||||
|
||||
const push = (parentKey: string, node: CascaderNode<T>) => {
|
||||
const bucket = childrenOf.get(parentKey)
|
||||
if (bucket) {
|
||||
bucket.push(node)
|
||||
} else {
|
||||
childrenOf.set(parentKey, [node])
|
||||
}
|
||||
}
|
||||
|
||||
if (getParent) {
|
||||
for (const node of items ?? []) {
|
||||
// A nullish entry is a data bug: skip it like a duplicate, say so in dev.
|
||||
if (node == null) {
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
warnCascaderOnce(
|
||||
"nullish-entry",
|
||||
"Ignored a null or undefined entry in `items` or `children`. Check the arrays you pass in."
|
||||
)
|
||||
}
|
||||
continue
|
||||
}
|
||||
if (byValue.has(node.value)) continue
|
||||
byValue.set(node.value, node)
|
||||
all.push(node)
|
||||
}
|
||||
|
||||
for (const node of all) {
|
||||
const rawParent = getParent(node)
|
||||
// An unknown parent makes the node a root rather than dropping the row.
|
||||
const parent =
|
||||
rawParent != null && byValue.has(rawParent) ? rawParent : null
|
||||
parentOf.set(node.value, parent)
|
||||
push(parent ?? CASCADER_ROOT_KEY, node)
|
||||
}
|
||||
|
||||
for (const node of all) {
|
||||
let depth = 0
|
||||
let cursor = parentOf.get(node.value) ?? null
|
||||
const seen = new Set<string>([node.value])
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
depth += 1
|
||||
cursor = parentOf.get(cursor) ?? null
|
||||
}
|
||||
depthOf.set(node.value, depth)
|
||||
}
|
||||
} else {
|
||||
const walk = (
|
||||
nodes: readonly CascaderNode<T>[] | undefined,
|
||||
parent: string | null,
|
||||
depth: number
|
||||
) => {
|
||||
for (const node of nodes ?? []) {
|
||||
// Same degradation as the flat path above.
|
||||
if (node == null) {
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
warnCascaderOnce(
|
||||
"nullish-entry",
|
||||
"Ignored a null or undefined entry in `items` or `children`. Check the arrays you pass in."
|
||||
)
|
||||
}
|
||||
continue
|
||||
}
|
||||
if (byValue.has(node.value)) continue
|
||||
byValue.set(node.value, node)
|
||||
parentOf.set(node.value, parent)
|
||||
depthOf.set(node.value, depth)
|
||||
all.push(node)
|
||||
push(parent ?? CASCADER_ROOT_KEY, node)
|
||||
if (node.children?.length) walk(node.children, node.value, depth + 1)
|
||||
}
|
||||
}
|
||||
walk(items, null, 0)
|
||||
}
|
||||
|
||||
return {
|
||||
byValue,
|
||||
childrenOf,
|
||||
parentOf,
|
||||
depthOf,
|
||||
roots: childrenOf.get(CASCADER_ROOT_KEY) ?? [],
|
||||
all,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Folds loaded pages into an index built from `items`, so a re-render with a
|
||||
* new `items` array keeps what the user drilled into. Static `items` wins;
|
||||
* `detached` is `byValue` ONLY, or deep search doubles it and `childrenOf` lies.
|
||||
*/
|
||||
export function mergeCascaderIndex<T = unknown>(
|
||||
base: CascaderIndex<T>,
|
||||
pages: ReadonlyMap<string, readonly CascaderNode<T>[]>,
|
||||
detached?: ReadonlyMap<string, CascaderNode<T>>
|
||||
): CascaderIndex<T> {
|
||||
// Identity stability: every downstream `useMemo` is keyed on this index.
|
||||
if (pages.size === 0 && !detached?.size) return base
|
||||
|
||||
const byValue = new Map(base.byValue)
|
||||
const childrenOf = new Map(base.childrenOf)
|
||||
const parentOf = new Map(base.parentOf)
|
||||
const depthOf = new Map(base.depthOf)
|
||||
|
||||
// Copy-on-write per bucket: only levels that got a page pay for a new array.
|
||||
const copied = new Set<string>()
|
||||
const append = (parentKey: string, node: CascaderNode<T>) => {
|
||||
let bucket = childrenOf.get(parentKey)
|
||||
if (!copied.has(parentKey)) {
|
||||
bucket = bucket ? bucket.slice() : []
|
||||
childrenOf.set(parentKey, bucket)
|
||||
copied.add(parentKey)
|
||||
}
|
||||
bucket!.push(node)
|
||||
}
|
||||
|
||||
const insert = (parentKey: string, nodes: readonly CascaderNode<T>[]) => {
|
||||
for (const node of nodes) {
|
||||
if (byValue.has(node.value)) continue
|
||||
byValue.set(node.value, node)
|
||||
parentOf.set(
|
||||
node.value,
|
||||
parentKey === CASCADER_ROOT_KEY ? null : parentKey
|
||||
)
|
||||
append(parentKey, node)
|
||||
if (node.children?.length) insert(node.value, node.children)
|
||||
}
|
||||
}
|
||||
|
||||
for (const [parentKey, nodes] of pages) insert(parentKey, nodes)
|
||||
|
||||
for (const value of byValue.keys()) {
|
||||
if (depthOf.has(value)) continue
|
||||
let depth = 0
|
||||
let cursor = parentOf.get(value) ?? null
|
||||
const seen = new Set<string>([value])
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
depth += 1
|
||||
cursor = parentOf.get(cursor) ?? null
|
||||
}
|
||||
depthOf.set(value, depth)
|
||||
}
|
||||
|
||||
const roots = childrenOf.get(CASCADER_ROOT_KEY) ?? []
|
||||
|
||||
// Depth first over the MERGED tree, so `all` keeps document order.
|
||||
const all: CascaderNode<T>[] = []
|
||||
const visited = new Set<string>()
|
||||
const walk = (nodes: readonly CascaderNode<T>[]) => {
|
||||
for (const node of nodes) {
|
||||
if (visited.has(node.value)) continue
|
||||
visited.add(node.value)
|
||||
all.push(node)
|
||||
const children = childrenOf.get(node.value)
|
||||
if (children?.length) walk(children)
|
||||
}
|
||||
}
|
||||
walk(roots)
|
||||
|
||||
// A page whose parent never arrived stays searchable rather than vanishing.
|
||||
for (const [value, node] of byValue) {
|
||||
if (visited.has(value)) continue
|
||||
visited.add(value)
|
||||
all.push(node)
|
||||
}
|
||||
|
||||
if (detached) {
|
||||
for (const [value, node] of detached) {
|
||||
if (byValue.has(value)) continue
|
||||
byValue.set(value, node)
|
||||
}
|
||||
}
|
||||
|
||||
return { byValue, childrenOf, parentOf, depthOf, roots, all }
|
||||
}
|
||||
|
||||
/** Children of `parent`, or the root level when `parent` is nullish. */
|
||||
export function getCascaderChildren<T>(
|
||||
index: CascaderIndex<T>,
|
||||
parent?: string | null
|
||||
): CascaderNode<T>[] {
|
||||
return index.childrenOf.get(parent ?? CASCADER_ROOT_KEY) ?? []
|
||||
}
|
||||
|
||||
/** A branch has known children, or `hasChildren` for an unfetched level. */
|
||||
export function isCascaderBranch<T>(
|
||||
index: CascaderIndex<T>,
|
||||
node: CascaderNode<T>
|
||||
): boolean {
|
||||
if (node.hasChildren) return true
|
||||
return (index.childrenOf.get(node.value)?.length ?? 0) > 0
|
||||
}
|
||||
|
||||
/** Trailing count for the default row. Explicit `count` wins over the tree. */
|
||||
export function getCascaderCount<T>(
|
||||
index: CascaderIndex<T>,
|
||||
node: CascaderNode<T>
|
||||
): number {
|
||||
if (typeof node.count === "number") return node.count
|
||||
return index.childrenOf.get(node.value)?.length ?? 0
|
||||
}
|
||||
|
||||
/** Whether a node may be committed as a selection. */
|
||||
export function isCascaderSelectable<T>(
|
||||
index: CascaderIndex<T>,
|
||||
node: CascaderNode<T>,
|
||||
selectable: CascaderSelectable<T>
|
||||
): boolean {
|
||||
// Before the branches a consumer controls: `selectable="any"` says yes to
|
||||
// every node, and committing the paging row would select a level's name.
|
||||
if (isCascaderMoreNode(node)) return false
|
||||
if (node.disabled) return false
|
||||
// A disabled ANCESTOR refuses the whole subtree: `searchCascaderDeep` still
|
||||
// surfaces children of a branch the UI will not let anyone open.
|
||||
{
|
||||
const seen = new Set<string>([node.value])
|
||||
let cursor = index.parentOf.get(node.value) ?? null
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
if (index.byValue.get(cursor)?.disabled) return false
|
||||
cursor = index.parentOf.get(cursor) ?? null
|
||||
}
|
||||
}
|
||||
if (typeof selectable === "function") return selectable(node)
|
||||
if (selectable === "any") return true
|
||||
return !isCascaderBranch(index, node)
|
||||
}
|
||||
|
||||
/** Ancestor chain for `value`, root first. Empty while async data loads. */
|
||||
export function getCascaderPath<T>(
|
||||
index: CascaderIndex<T>,
|
||||
value: string | null | undefined
|
||||
): CascaderNode<T>[] {
|
||||
if (value == null) return []
|
||||
const chain: CascaderNode<T>[] = []
|
||||
const seen = new Set<string>()
|
||||
let cursor: string | null | undefined = value
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
const node = index.byValue.get(cursor)
|
||||
if (!node) break
|
||||
chain.push(node)
|
||||
cursor = index.parentOf.get(cursor) ?? null
|
||||
}
|
||||
return chain.reverse()
|
||||
}
|
||||
|
||||
/**
|
||||
* `toLocaleLowerCase`, not `toLowerCase`: the invariant mapping turns Turkish
|
||||
* "I" into "i" not "ı", so "ışık" would never match "IŞIK". Both sides fold here.
|
||||
*/
|
||||
export function foldCascaderText(text: string): string {
|
||||
return text.toLocaleLowerCase()
|
||||
}
|
||||
|
||||
/** Folds once so callers can hoist the cost out of a per-node loop. */
|
||||
export function normalizeCascaderQuery(query: string): string {
|
||||
return foldCascaderText(query.trim())
|
||||
}
|
||||
|
||||
/** Case-insensitive substring over label and keywords; pre-fold the query. */
|
||||
export function matchesCascaderQuery<T>(
|
||||
node: CascaderNode<T>,
|
||||
normalized: string
|
||||
): boolean {
|
||||
if (!normalized) return true
|
||||
// Coerced, not trusted: a label-less node is malformed data, not a crash.
|
||||
if (foldCascaderText(node.label ?? "").includes(normalized)) return true
|
||||
if (node.keywords) {
|
||||
for (const keyword of node.keywords) {
|
||||
if (foldCascaderText(keyword).includes(normalized)) return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
/** Filters one level in place-order. Returns the input when the query is empty. */
|
||||
export function filterCascaderLevel<T>(
|
||||
nodes: readonly CascaderNode<T>[],
|
||||
query: string,
|
||||
matches: (
|
||||
node: CascaderNode<T>,
|
||||
normalized: string
|
||||
) => boolean = matchesCascaderQuery
|
||||
): CascaderNode<T>[] {
|
||||
const normalized = normalizeCascaderQuery(query)
|
||||
if (!normalized) return nodes as CascaderNode<T>[]
|
||||
return nodes.filter((node) => matches(node, normalized))
|
||||
}
|
||||
|
||||
/** Searches every node, optionally under `within`, in one pass over `all`. */
|
||||
export function searchCascaderDeep<T>(
|
||||
index: CascaderIndex<T>,
|
||||
query: string,
|
||||
options: {
|
||||
within?: string | null
|
||||
limit?: number
|
||||
matches?: (node: CascaderNode<T>, normalized: string) => boolean
|
||||
} = {}
|
||||
): CascaderNode<T>[] {
|
||||
const normalized = normalizeCascaderQuery(query)
|
||||
if (!normalized) return []
|
||||
|
||||
const { within, limit = 200, matches = matchesCascaderQuery } = options
|
||||
const results: CascaderNode<T>[] = []
|
||||
|
||||
// One memoised ancestry map per query. The provisional `false` written on the
|
||||
// way up doubles as the cycle guard; the trail is promoted once `within` hits.
|
||||
const ancestry = within == null ? null : new Map<string, boolean>()
|
||||
const isWithin = (node: CascaderNode<T>) => {
|
||||
if (within == null || !ancestry) return true
|
||||
const trail: string[] = []
|
||||
let answer = false
|
||||
let cursor: string | null | undefined = index.parentOf.get(node.value)
|
||||
while (cursor != null) {
|
||||
if (cursor === within) {
|
||||
answer = true
|
||||
break
|
||||
}
|
||||
const cached = ancestry.get(cursor)
|
||||
if (cached !== undefined) {
|
||||
answer = cached
|
||||
break
|
||||
}
|
||||
ancestry.set(cursor, false)
|
||||
trail.push(cursor)
|
||||
cursor = index.parentOf.get(cursor) ?? null
|
||||
}
|
||||
if (answer) for (const value of trail) ancestry.set(value, true)
|
||||
return answer
|
||||
}
|
||||
|
||||
for (const node of index.all) {
|
||||
if (results.length >= limit) break
|
||||
if (!matches(node, normalized)) continue
|
||||
if (!isWithin(node)) continue
|
||||
results.push(node)
|
||||
}
|
||||
|
||||
return results
|
||||
}
|
||||
|
||||
/**
|
||||
* Flattens the tree into tree mode's visible rows. A `sentinels` paging row
|
||||
* COUNTS as a sibling in `aria-setsize`: it holds an index of its own.
|
||||
*/
|
||||
export function flattenCascaderTree<T>(
|
||||
index: CascaderIndex<T>,
|
||||
expanded: ReadonlySet<string>,
|
||||
sentinels?: ReadonlySet<string>
|
||||
): CascaderFlatNode<T>[] {
|
||||
const rows: CascaderFlatNode<T>[] = []
|
||||
|
||||
const walk = (
|
||||
nodes: readonly CascaderNode<T>[],
|
||||
parentKey: string,
|
||||
depth: number
|
||||
) => {
|
||||
const sentinel = sentinels?.has(parentKey) ?? false
|
||||
const setSize = nodes.length + (sentinel ? 1 : 0)
|
||||
for (let i = 0; i < nodes.length; i += 1) {
|
||||
const node = nodes[i]
|
||||
const branch = isCascaderBranch(index, node)
|
||||
const isExpanded = branch && expanded.has(node.value)
|
||||
rows.push({
|
||||
node,
|
||||
depth,
|
||||
branch,
|
||||
expanded: isExpanded,
|
||||
setSize,
|
||||
posInSet: i + 1,
|
||||
})
|
||||
if (isExpanded) {
|
||||
walk(index.childrenOf.get(node.value) ?? [], node.value, depth + 1)
|
||||
}
|
||||
}
|
||||
if (sentinel) {
|
||||
rows.push({
|
||||
node: createCascaderMoreNode<T>(parentKey, nodes.length),
|
||||
depth,
|
||||
branch: false,
|
||||
expanded: false,
|
||||
setSize,
|
||||
posInSet: setSize,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
walk(index.roots, CASCADER_ROOT_KEY, 0)
|
||||
return rows
|
||||
}
|
||||
|
||||
/** Shortens a path; the ellipsis segment still carries the hidden nodes. */
|
||||
export function collapseCascaderPath<T>(
|
||||
path: readonly CascaderNode<T>[],
|
||||
options: { maxSegments?: number; collapse?: CascaderCollapse } = {}
|
||||
): CascaderPathSegment<T>[] {
|
||||
const { maxSegments = 3, collapse = "middle" } = options
|
||||
|
||||
const asNodes = (
|
||||
nodes: readonly CascaderNode<T>[]
|
||||
): CascaderPathSegment<T>[] =>
|
||||
nodes.map((node) => ({ type: "node" as const, node }))
|
||||
|
||||
if (collapse === "none" || maxSegments <= 0 || path.length <= maxSegments) {
|
||||
return asNodes(path)
|
||||
}
|
||||
|
||||
if (collapse === "start") {
|
||||
const tail = path.slice(path.length - maxSegments)
|
||||
return [
|
||||
{ type: "ellipsis", hidden: path.slice(0, path.length - maxSegments) },
|
||||
...asNodes(tail),
|
||||
]
|
||||
}
|
||||
|
||||
// "middle": keep the root for orientation and as much of the tail as fits.
|
||||
const head = path.slice(0, 1)
|
||||
const tailCount = maxSegments - 1
|
||||
const tail = path.slice(path.length - tailCount)
|
||||
const hidden = path.slice(1, path.length - tailCount)
|
||||
|
||||
if (hidden.length === 0) return asNodes(path)
|
||||
|
||||
return [...asNodes(head), { type: "ellipsis", hidden }, ...asNodes(tail)]
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Cascade selection */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Every LOADED node under `value`, root first. Reaching an unfetched descendant
|
||||
* would mean a network request per level of the subtree on every selection.
|
||||
*/
|
||||
export function collectCascaderSubtree<T>(
|
||||
index: CascaderIndex<T>,
|
||||
value: string
|
||||
): CascaderNode<T>[] {
|
||||
const root = index.byValue.get(value)
|
||||
if (!root) return []
|
||||
|
||||
const out: CascaderNode<T>[] = []
|
||||
const seen = new Set<string>()
|
||||
const walk = (node: CascaderNode<T>) => {
|
||||
if (seen.has(node.value)) return
|
||||
seen.add(node.value)
|
||||
out.push(node)
|
||||
const children = index.childrenOf.get(node.value)
|
||||
if (children) for (const child of children) walk(child)
|
||||
}
|
||||
walk(root)
|
||||
return out
|
||||
}
|
||||
|
||||
/**
|
||||
* Toggles `value` with its loaded subtree, then reconciles ancestors. One flat
|
||||
* array, no hidden "checked" state: a branch is in the selection exactly when
|
||||
* every selectable loaded child of it is, which keeps a row's checked state an
|
||||
* O(1) lookup. Nodes `isSelectable` rejects are skipped down AND ignored up,
|
||||
* the pressed node excepted.
|
||||
*/
|
||||
export function applyCascadeSelection<T>(
|
||||
index: CascaderIndex<T>,
|
||||
selected: readonly string[],
|
||||
value: string,
|
||||
select: boolean,
|
||||
isSelectable: (node: CascaderNode<T>) => boolean = () => true
|
||||
): string[] {
|
||||
const next = new Set(selected)
|
||||
const subtree = collectCascaderSubtree(index, value)
|
||||
|
||||
// An unknown value still toggles itself, so an early async selection lands.
|
||||
if (subtree.length === 0) {
|
||||
if (select) next.add(value)
|
||||
else next.delete(value)
|
||||
}
|
||||
|
||||
for (const node of subtree) {
|
||||
// The pressed node is exempt: it was committed, so it is selectable.
|
||||
if (node.value !== value && !isSelectable(node)) continue
|
||||
if (select) next.add(node.value)
|
||||
else next.delete(node.value)
|
||||
}
|
||||
|
||||
// Bottom up: a parent can only answer once its children have.
|
||||
const seen = new Set<string>([value])
|
||||
let cursor = index.parentOf.get(value) ?? null
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
const parent = index.byValue.get(cursor)
|
||||
const children = index.childrenOf.get(cursor) ?? []
|
||||
const selectable = children.filter((child) => isSelectable(child))
|
||||
const full =
|
||||
selectable.length > 0 &&
|
||||
selectable.every((child) => next.has(child.value)) &&
|
||||
// Never promote a node the consumer said may not be committed. Under
|
||||
// `selectable="leaf"` no branch qualifies, hence the `cascade` warning.
|
||||
!!parent &&
|
||||
isSelectable(parent)
|
||||
if (full) next.add(cursor)
|
||||
else next.delete(cursor)
|
||||
cursor = index.parentOf.get(cursor) ?? null
|
||||
}
|
||||
|
||||
return Array.from(next)
|
||||
}
|
||||
|
||||
/**
|
||||
* How many selected nodes each value has BELOW it, itself excluded. Walks UP
|
||||
* from each selection: a per-row subtree scan would be quadratic and re-paid.
|
||||
*/
|
||||
export function getCascaderSelectedDescendants<T>(
|
||||
index: CascaderIndex<T>,
|
||||
selected: readonly string[]
|
||||
): Map<string, number> {
|
||||
const counts = new Map<string, number>()
|
||||
|
||||
for (const value of selected) {
|
||||
const seen = new Set<string>([value])
|
||||
let cursor = index.parentOf.get(value) ?? null
|
||||
while (cursor != null && !seen.has(cursor)) {
|
||||
seen.add(cursor)
|
||||
counts.set(cursor, (counts.get(cursor) ?? 0) + 1)
|
||||
cursor = index.parentOf.get(cursor) ?? null
|
||||
}
|
||||
}
|
||||
|
||||
return counts
|
||||
}
|
||||
|
||||
/** The PARTIALLY selected values, read off counts the caller already holds. */
|
||||
export function getCascaderIndeterminateFrom(
|
||||
counts: ReadonlyMap<string, number>,
|
||||
selected: readonly string[]
|
||||
): Set<string> {
|
||||
const selectedSet = new Set(selected)
|
||||
const partial = new Set<string>()
|
||||
|
||||
for (const [value, count] of counts) {
|
||||
if (count > 0 && !selectedSet.has(value)) partial.add(value)
|
||||
}
|
||||
|
||||
return partial
|
||||
}
|
||||
|
||||
/** The one-call form; the root uses the two halves above and its own counts. */
|
||||
export function getCascaderIndeterminate<T>(
|
||||
index: CascaderIndex<T>,
|
||||
selected: readonly string[]
|
||||
): Set<string> {
|
||||
return getCascaderIndeterminateFrom(
|
||||
getCascaderSelectedDescendants(index, selected),
|
||||
selected
|
||||
)
|
||||
}
|
||||
|
||||
/** How `getCascaderCheckedValues` condenses a full-closure selection. */
|
||||
export type CascaderCheckedStrategy = "all" | "parent" | "child"
|
||||
|
||||
/**
|
||||
* The cascade selection under a reporting strategy. DERIVED OUTPUT ONLY: the
|
||||
* STORED value stays the full closure, which keeps a checked state an O(1)
|
||||
* lookup. `"all"` is the closure; `"parent"` drops a value whose parent is
|
||||
* selected; `"child"` drops one with a selected child.
|
||||
*/
|
||||
export function getCascaderCheckedValues<T>(
|
||||
index: CascaderIndex<T>,
|
||||
selected: readonly string[],
|
||||
strategy: CascaderCheckedStrategy
|
||||
): readonly string[] {
|
||||
if (strategy === "all") return selected
|
||||
|
||||
const set = new Set(selected)
|
||||
if (strategy === "parent") {
|
||||
return selected.filter((value) => {
|
||||
const parent = index.parentOf.get(value)
|
||||
return parent == null || !set.has(parent)
|
||||
})
|
||||
}
|
||||
|
||||
return selected.filter((value) => {
|
||||
const children = index.childrenOf.get(value)
|
||||
if (!children?.length) return true
|
||||
return !children.some((child) => set.has(child.value))
|
||||
})
|
||||
}
|
||||
|
||||
/** Values in `nodes` whose label collides, so the chip must show its path. */
|
||||
export function findAmbiguousCascaderLabels<T>(
|
||||
nodes: readonly CascaderNode<T>[]
|
||||
): Set<string> {
|
||||
const firstByLabel = new Map<string, string>()
|
||||
const ambiguous = new Set<string>()
|
||||
|
||||
for (const node of nodes) {
|
||||
const first = firstByLabel.get(node.label)
|
||||
if (first === undefined) {
|
||||
firstByLabel.set(node.label, node.value)
|
||||
continue
|
||||
}
|
||||
ambiguous.add(node.value)
|
||||
ambiguous.add(first)
|
||||
}
|
||||
|
||||
return ambiguous
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Development only */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
/** Warnings already emitted. Module scoped, or they repeat once per render. */
|
||||
const CASCADER_WARNED = new Set<string>()
|
||||
|
||||
/** Warns once per `key`, never in production, never by throwing. */
|
||||
export function warnCascaderOnce(key: string, message: string): void {
|
||||
if (process.env.NODE_ENV === "production") return
|
||||
if (CASCADER_WARNED.has(key)) return
|
||||
CASCADER_WARNED.add(key)
|
||||
console.warn(`[Cascader] ${message}`)
|
||||
}
|
||||
|
||||
/** Empties the ledger. Tests only; a warning is meant to be seen once. */
|
||||
export function resetCascaderWarnings(): void {
|
||||
CASCADER_WARNED.clear()
|
||||
}
|
||||
|
||||
/** What a dev-time scan of the consumer's `items` found wrong with it. */
|
||||
export interface CascaderDataIssues {
|
||||
/** Values appearing more than once. First wins, so a duplicate drops a row. */
|
||||
duplicates: string[]
|
||||
/** Values on a `getParent` cycle. Depth is clamped, so the tree reads wrong. */
|
||||
cycles: string[]
|
||||
}
|
||||
|
||||
/** Dev-time scan, kept out of `buildCascaderIndex` so the build stays hot. */
|
||||
export function findCascaderDataIssues<T>(
|
||||
items: readonly CascaderNode<T>[] | undefined,
|
||||
getParent?: (node: CascaderNode<T>) => string | null | undefined
|
||||
): CascaderDataIssues {
|
||||
const seen = new Set<string>()
|
||||
const duplicates = new Set<string>()
|
||||
const flat: CascaderNode<T>[] = []
|
||||
|
||||
const visit = (nodes: readonly CascaderNode<T>[] | undefined) => {
|
||||
for (const node of nodes ?? []) {
|
||||
// The build skips a nullish entry, and this runs BEFORE its warning.
|
||||
if (node == null) continue
|
||||
if (seen.has(node.value)) duplicates.add(node.value)
|
||||
else seen.add(node.value)
|
||||
flat.push(node)
|
||||
// Flat mode walks them too: BOTH `children` and `getParent` is a bug.
|
||||
if (node.children?.length) visit(node.children)
|
||||
}
|
||||
}
|
||||
visit(items)
|
||||
|
||||
const cycles: string[] = []
|
||||
if (getParent) {
|
||||
const parentOf = new Map<string, string | null>()
|
||||
for (const node of flat) {
|
||||
if (parentOf.has(node.value)) continue
|
||||
const raw = getParent(node)
|
||||
parentOf.set(node.value, raw != null && seen.has(raw) ? raw : null)
|
||||
}
|
||||
for (const node of flat) {
|
||||
const walked = new Set<string>([node.value])
|
||||
let cursor = parentOf.get(node.value) ?? null
|
||||
while (cursor != null) {
|
||||
if (walked.has(cursor)) {
|
||||
cycles.push(node.value)
|
||||
break
|
||||
}
|
||||
walked.add(cursor)
|
||||
cursor = parentOf.get(cursor) ?? null
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { duplicates: Array.from(duplicates), cycles }
|
||||
}
|
||||
@@ -0,0 +1,639 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import {
|
||||
useCascaderActions,
|
||||
useCascaderState,
|
||||
} from "@/components/reui/cascader/cascader-context"
|
||||
import { resolveCascaderSearchLabel } from "@/components/reui/cascader/cascader-i18n"
|
||||
import {
|
||||
collapseCascaderPath,
|
||||
getCascaderFooterStops,
|
||||
getCascaderPath,
|
||||
isCascaderRtl,
|
||||
} from "@/components/reui/cascader/cascader-lib"
|
||||
import type {
|
||||
CascaderCollapse,
|
||||
CascaderNode,
|
||||
CascaderValueDisplay,
|
||||
} from "@/components/reui/cascader/cascader-types"
|
||||
import { Combobox as ComboboxPrimitive } from "@base-ui/react"
|
||||
import { useDirection } from "@base-ui/react/direction-provider"
|
||||
import { mergeProps } from "@base-ui/react/merge-props"
|
||||
import { useRender } from "@base-ui/react/use-render"
|
||||
|
||||
import { cn } from "@/lib/utils"
|
||||
import { ChevronRightIcon, ChevronLeftIcon } from "lucide-react"
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Separator */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
function PathChevron() {
|
||||
return (
|
||||
<ChevronRightIcon className="size-3 shrink-0 opacity-50 rtl:-scale-x-100" />
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Nav */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export type CascaderNavProps = useRender.ComponentProps<"div">
|
||||
|
||||
/**
|
||||
* Header: back control, search input, and the separator under them. The
|
||||
* breadcrumb belongs with the list below: it describes the rows, not the field.
|
||||
*/
|
||||
function CascaderNav({ className, ...props }: CascaderNavProps) {
|
||||
const defaultProps = {
|
||||
"data-slot": "cascader-nav",
|
||||
className: cn(
|
||||
// `py-1`, not `py-1.5`: the row inside sets its own per-style height, so
|
||||
// even padding read too tall. 6px beside the field, 4px above and below.
|
||||
"border-border/60 flex shrink-0 flex-col gap-1 border-b px-1.5 py-1",
|
||||
className
|
||||
),
|
||||
}
|
||||
|
||||
return useRender({
|
||||
defaultTagName: "div",
|
||||
render: props.render,
|
||||
props: mergeProps<"div">(defaultProps, props),
|
||||
})
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Back */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderBackProps extends Omit<
|
||||
useRender.ComponentProps<"button">,
|
||||
"children"
|
||||
> {
|
||||
children?: React.ReactNode
|
||||
}
|
||||
|
||||
/** Pops one level. Renders nothing at the root, so no dead header space. */
|
||||
function CascaderBack({ className, children, ...props }: CascaderBackProps) {
|
||||
const { popLevel, labels, mode } = useCascaderActions()
|
||||
const { path } = useCascaderState()
|
||||
|
||||
// Checked after `useRender`, never before it: an early return would change
|
||||
// the hook count between the root level and any deeper one.
|
||||
const hidden = mode !== "drill" || path.length === 0
|
||||
|
||||
const defaultProps = {
|
||||
"data-slot": "cascader-back",
|
||||
type: "button" as const,
|
||||
"aria-label": labels.back,
|
||||
onClick: () => popLevel(),
|
||||
className: cn(
|
||||
"text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:ring-ring/50 flex shrink-0 items-center justify-center rounded-md outline-hidden transition-colors focus-visible:ring-2",
|
||||
// A notch under the row height: an affordance, not a second field.
|
||||
"size-6",
|
||||
className
|
||||
),
|
||||
children: children ?? (
|
||||
<ChevronLeftIcon className="size-4 rtl:-scale-x-100" />
|
||||
),
|
||||
}
|
||||
|
||||
const element = useRender({
|
||||
defaultTagName: "button",
|
||||
render: props.render,
|
||||
props: mergeProps<"button">(defaultProps, props),
|
||||
})
|
||||
|
||||
return hidden ? null : element
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Breadcrumb */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderBreadcrumbProps extends Omit<
|
||||
useRender.ComponentProps<"nav">,
|
||||
"children"
|
||||
> {
|
||||
/** Maximum visible node segments before the middle collapses. */
|
||||
maxSegments?: number
|
||||
collapse?: CascaderCollapse
|
||||
/** Clicking a segment navigates back to that level. Defaults to true. */
|
||||
interactive?: boolean
|
||||
}
|
||||
|
||||
/**
|
||||
* Compact trail of the current level AND its ancestors, collapsed by the same
|
||||
* helper as `CascaderValue` so panel and trigger cannot disagree. The current
|
||||
* level IS the last crumb: dropping it read as a rendering bug, a trail naming
|
||||
* only the places you are not.
|
||||
*/
|
||||
function CascaderBreadcrumb({
|
||||
className,
|
||||
maxSegments = 3,
|
||||
collapse = "middle",
|
||||
interactive = true,
|
||||
...props
|
||||
}: CascaderBreadcrumbProps) {
|
||||
const { goToDepth, mode, labels } = useCascaderActions()
|
||||
const { path, index } = useCascaderState()
|
||||
|
||||
// The WHOLE path, current level included; unresolvable entries drop out.
|
||||
const nodes = path
|
||||
.map((value) => index.byValue.get(value))
|
||||
.filter(Boolean) as CascaderNode[]
|
||||
const segments = collapseCascaderPath(nodes, { maxSegments, collapse })
|
||||
// `collapseCascaderPath` never collapses the last node away, so this is
|
||||
// always the final segment - derived rather than assumed, so a `collapse`
|
||||
// mode that ever changes that cannot mark an ancestor as the current page.
|
||||
const currentValue = nodes.length ? nodes[nodes.length - 1].value : null
|
||||
|
||||
// See `CascaderBack`: the hide check must not short-circuit past `useRender`.
|
||||
const hidden = mode !== "drill" || nodes.length === 0
|
||||
|
||||
const goTo = (node: CascaderNode) => {
|
||||
const depth = path.indexOf(node.value)
|
||||
if (depth < 0) return
|
||||
// `goToDepth`, not a bare `setPath`: it reports `reason: "breadcrumb"`,
|
||||
// clears the query and drops any pending navigation.
|
||||
goToDepth(depth + 1)
|
||||
}
|
||||
|
||||
const defaultProps = {
|
||||
"data-slot": "cascader-breadcrumb",
|
||||
"aria-label": labels.breadcrumbLabel,
|
||||
className: cn(
|
||||
"text-muted-foreground flex min-w-0 shrink-0 items-center gap-0.5 pt-1.5 pb-0.5 text-xs",
|
||||
// Lines up with the ROWS, not the header: each style's list padding plus
|
||||
// its row inset. vega/mira/rhea `p-1`+`pl-2`, nova `p-1`+`pl-1.5`, maia
|
||||
// `p-1`+`pl-3`, lyra `pl-2`, luma/sera `p-1.5`+`pl-3`, per style-*.css.
|
||||
"px-2.5",
|
||||
className
|
||||
),
|
||||
children: segments.map((segment, i) => (
|
||||
<React.Fragment
|
||||
key={segment.type === "node" ? segment.node.value : `gap-${i}`}
|
||||
>
|
||||
{i > 0 ? <PathChevron /> : null}
|
||||
{segment.type === "ellipsis" ? (
|
||||
<span
|
||||
data-slot="cascader-breadcrumb-ellipsis"
|
||||
title={segment.hidden
|
||||
.map((n) => n.label)
|
||||
.join(` ${labels.pathSeparator} `)}
|
||||
className="shrink-0"
|
||||
>
|
||||
…
|
||||
</span>
|
||||
) : interactive && segment.node.value !== currentValue ? (
|
||||
<button
|
||||
type="button"
|
||||
data-slot="cascader-breadcrumb-item"
|
||||
onClick={() => goTo(segment.node)}
|
||||
className="hover:text-foreground focus-visible:ring-ring/50 max-w-32 truncate rounded-sm outline-hidden transition-colors focus-visible:ring-2"
|
||||
>
|
||||
{segment.node.label}
|
||||
</button>
|
||||
) : (
|
||||
<span
|
||||
data-slot="cascader-breadcrumb-item"
|
||||
/* The level on screen: a span because it goes nowhere, plus
|
||||
`aria-current="page"` so it is not read as one of a flat list. */
|
||||
{...(segment.node.value === currentValue
|
||||
? { "aria-current": "page" as const }
|
||||
: null)}
|
||||
className={cn(
|
||||
"max-w-32 truncate",
|
||||
segment.node.value === currentValue &&
|
||||
"text-foreground font-medium"
|
||||
)}
|
||||
>
|
||||
{segment.node.label}
|
||||
</span>
|
||||
)}
|
||||
</React.Fragment>
|
||||
)),
|
||||
}
|
||||
|
||||
const element = useRender({
|
||||
defaultTagName: "nav",
|
||||
render: props.render,
|
||||
props: mergeProps<"nav">(defaultProps, props),
|
||||
})
|
||||
|
||||
return hidden ? null : element
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Input */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderInputProps extends ComboboxPrimitive.Input.Props {
|
||||
/** Renders the back control inline, before the field. Defaults to true. */
|
||||
showBack?: boolean
|
||||
}
|
||||
|
||||
/** Base UI hands its input handlers an event carrying the veto hook. */
|
||||
type CascaderInputKeyEvent = Parameters<
|
||||
NonNullable<ComboboxPrimitive.Input.Props["onKeyDown"]>
|
||||
>[0]
|
||||
|
||||
/**
|
||||
* Search field. MUST render inside the positioner: only there does Base UI skip
|
||||
* the refill from the committed selection that would fight every level swap.
|
||||
*/
|
||||
function CascaderInput({
|
||||
className,
|
||||
showBack = true,
|
||||
placeholder,
|
||||
onKeyDown,
|
||||
"aria-describedby": ariaDescribedBy,
|
||||
...props
|
||||
}: CascaderInputProps) {
|
||||
const {
|
||||
labels,
|
||||
popLevel,
|
||||
mode,
|
||||
getHighlighted,
|
||||
isBranch,
|
||||
navigate,
|
||||
index,
|
||||
toggleExpanded,
|
||||
inline,
|
||||
invalid,
|
||||
baseId,
|
||||
} = useCascaderActions()
|
||||
const direction = useDirection()
|
||||
const { currentParent, query, path, renderedItems, treeRows } =
|
||||
useCascaderState()
|
||||
|
||||
const resolvedPlaceholder =
|
||||
placeholder ?? resolveCascaderSearchLabel(labels, currentParent?.label)
|
||||
|
||||
// Not `showBack`: `CascaderBack` renders nothing at the root or outside
|
||||
// drill mode, where the field's own leading `px-1.5` is wanted. Beside the
|
||||
// button it stacks with the row's `gap-1` into a 10px hole, hence `ps-0`.
|
||||
const backVisible = showBack && mode === "drill" && path.length > 0
|
||||
|
||||
const hintId = `${baseId}-hint`
|
||||
// Base UI names no list while inline; columns mode moves the real listbox to
|
||||
// the deepest panel, which is the `path.length` one.
|
||||
const listId = `${baseId}-column-${mode === "columns" ? path.length : 0}`
|
||||
|
||||
// The direction the HINT is worded for. `handleKeyDown` re-reads
|
||||
// `isCascaderRtl` per keystroke; this is text on screen before any key, so
|
||||
// the same check runs once against the mounted DOM (on the hint span, so no
|
||||
// second ref into Base UI's input). SSR renders the "ltr" default and
|
||||
// corrects on hydration. `direction` is the only dep: a `dir` attribute and
|
||||
// the stylesheet are declarations, not state, so nothing to resubscribe to.
|
||||
const hintRef = React.useRef<HTMLSpanElement>(null)
|
||||
const [hintDir, setHintDir] = React.useState<"ltr" | "rtl">("ltr")
|
||||
React.useLayoutEffect(() => {
|
||||
const hint = hintRef.current
|
||||
if (!hint) return
|
||||
setHintDir(isCascaderRtl(hint, direction) ? "rtl" : "ltr")
|
||||
}, [direction])
|
||||
|
||||
/**
|
||||
* Moves the highlight to `targetIndex` in `treeRows`. Base UI has no
|
||||
* imperative setter (`actionsRef` is `{ unmount }`), so the move is arrow
|
||||
* presses, sound only because `useListNavigation` fires `onItemHighlighted`
|
||||
* SYNCHRONOUSLY per keydown. A press that fails to close the gap ends it.
|
||||
*/
|
||||
const moveHighlightTo = (field: HTMLInputElement, targetIndex: number) => {
|
||||
const rowIndex = () => {
|
||||
const highlighted = getHighlighted()
|
||||
if (!highlighted) return -1
|
||||
return treeRows.findIndex((row) => row.node.value === highlighted.value)
|
||||
}
|
||||
|
||||
let current = rowIndex()
|
||||
for (let step = 0; step < treeRows.length; step += 1) {
|
||||
if (current === -1 || current === targetIndex) return
|
||||
const key = current > targetIndex ? "ArrowUp" : "ArrowDown"
|
||||
field.dispatchEvent(
|
||||
new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
|
||||
)
|
||||
const next = rowIndex()
|
||||
const progressed =
|
||||
key === "ArrowUp"
|
||||
? next < current && next >= targetIndex
|
||||
: next > current && next <= targetIndex
|
||||
if (next === -1 || !progressed) return
|
||||
current = next
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The tree pattern's two level keys; Base UI leaves both alone (list
|
||||
* navigation is vertical-only, the chip handler no-ops without
|
||||
* `Combobox.Chips`). Passed in rather than hardcoded because RTL swaps them:
|
||||
* APG defines them as "toward the children", not as a physical arrow.
|
||||
*/
|
||||
const handleTreeKeyDown = (
|
||||
event: CascaderInputKeyEvent,
|
||||
field: HTMLInputElement,
|
||||
caretAtStart: boolean,
|
||||
caretAtEnd: boolean,
|
||||
forwardKey: "ArrowLeft" | "ArrowRight",
|
||||
backKey: "ArrowLeft" | "ArrowRight"
|
||||
) => {
|
||||
const forward = event.key === forwardKey
|
||||
if (!forward && event.key !== backKey) return
|
||||
if (forward ? !caretAtEnd : !caretAtStart) return
|
||||
|
||||
const highlighted = getHighlighted()
|
||||
if (!highlighted) return
|
||||
const rowIndex = treeRows.findIndex(
|
||||
(row) => row.node.value === highlighted.value
|
||||
)
|
||||
if (rowIndex < 0) return
|
||||
const row = treeRows[rowIndex]
|
||||
|
||||
if (forward) {
|
||||
if (!row.branch) return
|
||||
event.preventDefault()
|
||||
if (!row.expanded) {
|
||||
// `navigate`, not `toggleExpanded`: it waits for an unloaded branch's
|
||||
// children, so the keyboard path in matches the expander.
|
||||
navigate(row.node)
|
||||
return
|
||||
}
|
||||
// `flattenCascaderTree` emits children right after their parent, so the
|
||||
// first child is the next row. The depth check covers an empty branch.
|
||||
const child = treeRows[rowIndex + 1]
|
||||
if (child && child.depth === row.depth + 1) {
|
||||
moveHighlightTo(field, rowIndex + 1)
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
if (row.branch && row.expanded) {
|
||||
event.preventDefault()
|
||||
toggleExpanded(row.node.value)
|
||||
return
|
||||
}
|
||||
|
||||
const parentValue = index.parentOf.get(row.node.value)
|
||||
if (!parentValue) return
|
||||
const parentIndex = treeRows.findIndex(
|
||||
(entry) => entry.node.value === parentValue
|
||||
)
|
||||
if (parentIndex < 0) return
|
||||
event.preventDefault()
|
||||
moveHighlightTo(field, parentIndex)
|
||||
}
|
||||
|
||||
const handleKeyDown = (event: CascaderInputKeyEvent) => {
|
||||
onKeyDown?.(event)
|
||||
if (event.defaultPrevented) return
|
||||
|
||||
const field = event.currentTarget
|
||||
const caretAtStart = field.selectionStart === 0 && field.selectionEnd === 0
|
||||
const caretAtEnd =
|
||||
field.selectionStart === query.length &&
|
||||
field.selectionEnd === query.length
|
||||
|
||||
// ArrowDown at the END of the list hands real focus to the pinned footer,
|
||||
// the key a combobox is actually navigated with; Tab still works and still
|
||||
// skips the scroll area. An EMPTY list hands off at once, and the footer
|
||||
// owns the way back. Counted from state, so a windowed list still answers.
|
||||
if (event.key === "ArrowDown" && !event.altKey) {
|
||||
const rowCount = mode === "tree" ? treeRows.length : renderedItems.length
|
||||
const lastValue =
|
||||
mode === "tree"
|
||||
? treeRows[rowCount - 1]?.node.value
|
||||
: renderedItems[rowCount - 1]?.value
|
||||
const highlighted = getHighlighted()
|
||||
const atEnd =
|
||||
rowCount === 0 ||
|
||||
(highlighted != null && highlighted.value === lastValue)
|
||||
if (atEnd) {
|
||||
const panel = field.closest<HTMLElement>('[data-slot="cascader-panel"]')
|
||||
const stop = panel ? getCascaderFooterStops(panel)[0] : undefined
|
||||
if (stop) {
|
||||
event.preventDefault()
|
||||
// Base UI's handler is deliberately NOT vetoed: its wrap's first
|
||||
// press CLEARS the highlight, so no stale row stays active behind the
|
||||
// focused command, and the emptied highlight completes the ring.
|
||||
stop.focus()
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The level keys are LOGICAL, not physical: in RTL, ArrowLeft opens a
|
||||
// branch and ArrowRight goes back. They act only at the caret edge, and
|
||||
// those guards do NOT mirror: `selectionStart === 0` is the logical start.
|
||||
const rtl = isCascaderRtl(field, direction)
|
||||
const forwardKey = rtl ? "ArrowLeft" : "ArrowRight"
|
||||
const backKey = rtl ? "ArrowRight" : "ArrowLeft"
|
||||
|
||||
if (mode === "tree") {
|
||||
handleTreeKeyDown(
|
||||
event,
|
||||
field,
|
||||
caretAtStart,
|
||||
caretAtEnd,
|
||||
forwardKey,
|
||||
backKey
|
||||
)
|
||||
return
|
||||
}
|
||||
|
||||
if (event.key === forwardKey && caretAtEnd) {
|
||||
const highlighted = getHighlighted()
|
||||
if (highlighted && isBranch(highlighted)) {
|
||||
event.preventDefault()
|
||||
navigate(highlighted)
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
// Backspace on an empty query pops a level too, so the keyboard way out of
|
||||
// a level is symmetric with typing into it.
|
||||
if (
|
||||
(event.key === backKey && caretAtStart) ||
|
||||
(event.key === "Backspace" && query.length === 0)
|
||||
) {
|
||||
if (path.length > 0) {
|
||||
event.preventDefault()
|
||||
popLevel()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div
|
||||
data-slot="cascader-input-row"
|
||||
className={cn(
|
||||
"flex shrink-0 items-center gap-1",
|
||||
/* Each style sizes a combobox search field only as a DIRECT child of
|
||||
the popup; this row is nested, so the ladder is mirrored here rather
|
||||
than hardcoding one height for all eight styles. */
|
||||
"h-8"
|
||||
)}
|
||||
>
|
||||
{showBack ? <CascaderBack /> : null}
|
||||
<ComboboxPrimitive.Input
|
||||
data-slot="cascader-input"
|
||||
placeholder={resolvedPlaceholder}
|
||||
onKeyDown={handleKeyDown}
|
||||
/* Nothing on screen says the level keys exist. */
|
||||
aria-describedby={[ariaDescribedBy, hintId].filter(Boolean).join(" ")}
|
||||
/* Conditional: an explicit `undefined` deletes Base UI's own value. */
|
||||
{...(mode === "tree" ? { "aria-haspopup": "tree" as const } : null)}
|
||||
/* Base UI omits BOTH `aria-expanded` and `aria-controls` while inline,
|
||||
and an embedded panel is permanently expanded, so supply both. */
|
||||
{...(inline
|
||||
? { "aria-expanded": true, "aria-controls": listId }
|
||||
: null)}
|
||||
/* No trigger to carry the invalid state in the `inline` case. */
|
||||
{...(invalid ? { "aria-invalid": true, "data-invalid": "" } : null)}
|
||||
className={cn(
|
||||
"placeholder:text-muted-foreground h-full w-full min-w-0 flex-1 bg-transparent px-1.5 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
|
||||
backVisible && "ps-0",
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
/>
|
||||
<span id={hintId} ref={hintRef} className="sr-only">
|
||||
{/* `hintDir`, not `direction`: the context alone misses an RTL app that
|
||||
uses a `dir` attribute instead of `DirectionProvider`. */}
|
||||
{labels.keyboardHint(mode, hintDir)}
|
||||
</span>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Value */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderValueProps extends Omit<
|
||||
useRender.ComponentProps<"span">,
|
||||
"children"
|
||||
> {
|
||||
/** `path` shows the full trail, `leaf` only the node, `count` only a total. */
|
||||
display?: CascaderValueDisplay
|
||||
maxSegments?: number
|
||||
collapse?: CascaderCollapse
|
||||
separator?: React.ReactNode
|
||||
/** Renders the selected node's icon before the trail. */
|
||||
showIcon?: boolean
|
||||
placeholder?: React.ReactNode
|
||||
/** Replaces the whole rendering. Receives the resolved selection and path. */
|
||||
children?: (selected: CascaderNode[], path: CascaderNode[]) => React.ReactNode
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger display. Defaults to the collapsed selection path rather than a bare
|
||||
* leaf label, which in a nested picker is frequently ambiguous.
|
||||
*/
|
||||
function CascaderValue({
|
||||
className,
|
||||
display = "path",
|
||||
maxSegments = 3,
|
||||
collapse = "middle",
|
||||
separator,
|
||||
showIcon = true,
|
||||
placeholder,
|
||||
children,
|
||||
...props
|
||||
}: CascaderValueProps) {
|
||||
const { labels, multiple, resolveNode } = useCascaderActions()
|
||||
const { index, selectedValues } = useCascaderState()
|
||||
|
||||
// `resolveNode`, not `index.byValue`: a selection missing from `items` (async
|
||||
// children, a removed item) must still render a label, not an empty trigger.
|
||||
const selected = selectedValues.map(resolveNode)
|
||||
|
||||
const resolvedPath =
|
||||
selectedValues.length === 1 ? getCascaderPath(index, selectedValues[0]) : []
|
||||
// No ancestor chain: fall back to the node so `display="path"` shows a leaf.
|
||||
const path =
|
||||
resolvedPath.length > 0
|
||||
? resolvedPath
|
||||
: selected.length === 1
|
||||
? selected
|
||||
: []
|
||||
|
||||
let content: React.ReactNode
|
||||
|
||||
if (children) {
|
||||
content = children(selected, path)
|
||||
} else if (selectedValues.length === 0) {
|
||||
content = (
|
||||
<span className="text-muted-foreground truncate">{placeholder}</span>
|
||||
)
|
||||
} else if (display === "count" || (multiple && selectedValues.length > 1)) {
|
||||
content = labels.selectedCount(selectedValues.length)
|
||||
} else {
|
||||
const leaf = path[path.length - 1] ?? selected[0]
|
||||
const segments =
|
||||
display === "leaf"
|
||||
? [{ type: "node" as const, node: leaf }]
|
||||
: collapseCascaderPath(path, { maxSegments, collapse })
|
||||
|
||||
content = (
|
||||
<>
|
||||
{showIcon && leaf?.icon ? (
|
||||
<span
|
||||
data-slot="cascader-value-icon"
|
||||
className="text-muted-foreground flex shrink-0 items-center"
|
||||
>
|
||||
{leaf.icon}
|
||||
</span>
|
||||
) : null}
|
||||
{segments.map((segment, i) => (
|
||||
<React.Fragment
|
||||
key={segment.type === "node" ? segment.node.value : `gap-${i}`}
|
||||
>
|
||||
{i > 0 ? (separator ?? <PathChevron />) : null}
|
||||
{segment.type === "ellipsis" ? (
|
||||
<span
|
||||
data-slot="cascader-value-ellipsis"
|
||||
title={segment.hidden
|
||||
.map((n) => n.label)
|
||||
.join(` ${labels.pathSeparator} `)}
|
||||
className="text-muted-foreground shrink-0"
|
||||
>
|
||||
…
|
||||
</span>
|
||||
) : (
|
||||
<span
|
||||
className={cn(
|
||||
"truncate",
|
||||
i < segments.length - 1 && "text-muted-foreground"
|
||||
)}
|
||||
>
|
||||
{segment.node?.label}
|
||||
</span>
|
||||
)}
|
||||
</React.Fragment>
|
||||
))}
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
const defaultProps = {
|
||||
"data-slot": "cascader-value",
|
||||
className: cn("flex min-w-0 items-center gap-1 truncate", className),
|
||||
children: content,
|
||||
}
|
||||
|
||||
return useRender({
|
||||
defaultTagName: "span",
|
||||
render: props.render,
|
||||
props: mergeProps<"span">(defaultProps, props),
|
||||
})
|
||||
}
|
||||
|
||||
export {
|
||||
CascaderNav,
|
||||
CascaderBack,
|
||||
CascaderBreadcrumb,
|
||||
CascaderInput,
|
||||
CascaderValue,
|
||||
}
|
||||
@@ -0,0 +1,209 @@
|
||||
import type * as React from "react"
|
||||
|
||||
/**
|
||||
* A node in the cascader tree. Two input shapes normalize to one internal
|
||||
* index: nested (nodes carry `children`), or flat adjacency plus the root's
|
||||
* `getParent`, which skips the re-nesting step for large datasets.
|
||||
*/
|
||||
export interface CascaderNode<T = unknown> {
|
||||
/** Stable id. Also the committed selection value. */
|
||||
value: string
|
||||
label: string
|
||||
icon?: React.ReactNode
|
||||
description?: string
|
||||
children?: CascaderNode<T>[]
|
||||
/** Declares a branch before load; async nodes read as leaves without it. */
|
||||
hasChildren?: boolean
|
||||
/** Trailing count. Defaults to known children; set it for async nodes. */
|
||||
count?: number
|
||||
disabled?: boolean
|
||||
keywords?: string[]
|
||||
/**
|
||||
* Only read on a node nested inside a `getChildren` result. For the level a
|
||||
* node OWNS the authoritative signal is that level's `CascaderLoadResult`.
|
||||
*/
|
||||
hasMore?: boolean
|
||||
data?: T
|
||||
}
|
||||
|
||||
/**
|
||||
* One footer ACTION. Deliberately not a `CascaderNode`, so a command can never
|
||||
* be passed where an option is expected and join the ring, filter or selection.
|
||||
*/
|
||||
export interface CascaderActionItem {
|
||||
/** Stable key. Falls back to the label when it is a string, then the index. */
|
||||
value?: string
|
||||
label: React.ReactNode
|
||||
icon?: React.ReactNode
|
||||
disabled?: boolean
|
||||
/** Ignored when `items` is present - a flyout opens instead. */
|
||||
onSelect?: () => void
|
||||
/** Turns the row into a submenu trigger. One level deep on purpose. */
|
||||
items?: CascaderActionItem[]
|
||||
/** Consecutive entries sharing a heading are drawn under one. */
|
||||
group?: string
|
||||
}
|
||||
|
||||
/** Panel layout. See the docs for the keyboard map of each. */
|
||||
export type CascaderMode = "drill" | "columns" | "tree"
|
||||
|
||||
export type CascaderSearchScope = "level" | "deep"
|
||||
|
||||
/**
|
||||
* Which nodes may be committed. The predicate arm is generic over the payload
|
||||
* rather than quantified per call: a per-call `<T>` would force every predicate
|
||||
* to accept EVERY payload, so `(node: CascaderNode<Member>) => boolean` could
|
||||
* never satisfy it.
|
||||
*/
|
||||
export type CascaderSelectable<T = unknown> =
|
||||
| "leaf"
|
||||
| "any"
|
||||
| ((node: CascaderNode<T>) => boolean)
|
||||
|
||||
export type CascaderCollapse = "middle" | "start" | "none"
|
||||
|
||||
export type CascaderValueDisplay = "path" | "leaf" | "count"
|
||||
|
||||
export type CascaderChangeReason = "select" | "deselect" | "clear"
|
||||
|
||||
/** Second argument to `onValueChange`: resolved nodes, so no re-lookup. */
|
||||
export interface CascaderChangeDetails<T = unknown> {
|
||||
/** The node committed or toggled. Null when the selection was cleared. */
|
||||
node: CascaderNode<T> | null
|
||||
/** Ancestor chain of `node`, root first, node last. */
|
||||
path: CascaderNode<T>[]
|
||||
nodes: CascaderNode<T>[]
|
||||
reason: CascaderChangeReason
|
||||
}
|
||||
|
||||
/** Normalized tree, built once per `items` identity, shared by every mode. */
|
||||
export interface CascaderIndex<T = unknown> {
|
||||
byValue: Map<string, CascaderNode<T>>
|
||||
/** Children by parent value. Root children are keyed by `ROOT_KEY`. */
|
||||
childrenOf: Map<string, CascaderNode<T>[]>
|
||||
parentOf: Map<string, string | null>
|
||||
/** Zero-based depth by node value. */
|
||||
depthOf: Map<string, number>
|
||||
/** Top level nodes, in input order. */
|
||||
roots: CascaderNode<T>[]
|
||||
/** Every node in a stable, depth-first order. Used by deep search. */
|
||||
all: CascaderNode<T>[]
|
||||
}
|
||||
|
||||
export interface CascaderFlatNode<T = unknown> {
|
||||
node: CascaderNode<T>
|
||||
depth: number
|
||||
/** Known children, or a declared `hasChildren`. */
|
||||
branch: boolean
|
||||
expanded: boolean
|
||||
/** Sibling count, plus one when the level has a paging row. */
|
||||
setSize: number
|
||||
/** One-based index among siblings. */
|
||||
posInSet: number
|
||||
}
|
||||
|
||||
/** One segment of a rendered path, after collapsing. */
|
||||
export type CascaderPathSegment<T = unknown> =
|
||||
| { type: "node"; node: CascaderNode<T> }
|
||||
| { type: "ellipsis"; hidden: CascaderNode<T>[] }
|
||||
|
||||
/**
|
||||
* Async load state for one node's children. Deliberately WITHOUT a `status`
|
||||
* field: "declared a branch, never fetched" and "fetched and genuinely empty"
|
||||
* are told apart by MAP MEMBERSHIP, and a second source of that truth would
|
||||
* eventually disagree with the first.
|
||||
*/
|
||||
export interface CascaderLoadState {
|
||||
loading: boolean
|
||||
error: boolean
|
||||
hasMore: boolean
|
||||
/** Opaque cursor handed back to `getChildren` for the next page. */
|
||||
cursor?: string
|
||||
}
|
||||
|
||||
/** Why a level was fetched. `resolve`: `resolveValue` hit an unloaded node. */
|
||||
export type CascaderLoadReason =
|
||||
| "level"
|
||||
| "more"
|
||||
| "prefetch"
|
||||
| "retry"
|
||||
| "resolve"
|
||||
|
||||
/** Argument handed to `getChildren`. */
|
||||
export interface CascaderLoadContext {
|
||||
/** Aborted when the request is superseded or the popup closes. */
|
||||
signal: AbortSignal
|
||||
cursor?: string
|
||||
reason?: CascaderLoadReason
|
||||
}
|
||||
|
||||
/** Value returned by `getChildren`. A bare array is also accepted. */
|
||||
export interface CascaderLoadResult<T = unknown> {
|
||||
items: CascaderNode<T>[]
|
||||
nextCursor?: string
|
||||
/** Defaults to whether `nextCursor` was supplied. */
|
||||
hasMore?: boolean
|
||||
}
|
||||
|
||||
/** Argument handed to `onSearch`. */
|
||||
export interface CascaderSearchContext {
|
||||
signal: AbortSignal
|
||||
/** The path the user is searching within, deepest last. */
|
||||
path: string[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Every user facing string, so the primitive ships no hardcoded copy. The
|
||||
* callbacks take plain labels, not nodes: a `CascaderNode<T>` parameter would
|
||||
* force this object to carry the item generic. `*Announcement` is live-region.
|
||||
*/
|
||||
export interface CascaderLabels {
|
||||
search: string | ((parentLabel?: string) => string)
|
||||
back: string
|
||||
/** A level's FIRST page. `loadingMore` is the next, `loadMore` its idle row. */
|
||||
loading: string
|
||||
loadingMore: string
|
||||
loadMore: string
|
||||
error: string
|
||||
retry: string
|
||||
empty: string
|
||||
/** Rendered by `CascaderValue` when `display="count"`. */
|
||||
selectedCount: (count: number) => string
|
||||
breadcrumbLabel: string
|
||||
chipsLabel: string
|
||||
removeChip: (label: string) => string
|
||||
/** Trail separator. Not every locale writes one with a slash. */
|
||||
pathSeparator: string
|
||||
/** Names the root level wherever there is no parent node to name it. */
|
||||
rootLevel: string
|
||||
itemCount: (count: number) => string
|
||||
/** Appended to a branch row's name outside tree mode: it opens another list. */
|
||||
branchAffordance: string
|
||||
/** Columns-trail rows are plain buttons, so they carry no `aria-selected`. */
|
||||
selectedState: string
|
||||
/** Same for the mixed state, which a `role="button"` row may not carry. */
|
||||
partiallySelectedState: string
|
||||
columnsLabel: string
|
||||
actionsLabel: string
|
||||
submenuAffordance: string
|
||||
panelLabel: string
|
||||
/** Read per mode AND per direction: the level keys mirror in RTL. */
|
||||
keyboardHint: (mode: CascaderMode, dir: "ltr" | "rtl") => string
|
||||
rootAnnouncement: (count: number) => string
|
||||
expandedAnnouncement: (label: string, count: number) => string
|
||||
collapsedAnnouncement: (label: string) => string
|
||||
levelAnnouncement: (
|
||||
parentLabel: string,
|
||||
depth: number,
|
||||
count: number
|
||||
) => string
|
||||
resultsAnnouncement: (count: number) => string
|
||||
maxReachedAnnouncement: (max: number) => string
|
||||
/** `count` is the descendants swept along; `selecting` is the direction. */
|
||||
cascadeAnnouncement: (
|
||||
label: string,
|
||||
count: number,
|
||||
selecting: boolean
|
||||
) => string
|
||||
searchingAnnouncement: string
|
||||
}
|
||||
@@ -0,0 +1,458 @@
|
||||
"use client"
|
||||
|
||||
import * as React from "react"
|
||||
import { CascaderColumnPanel } from "@/components/reui/cascader/cascader-columns"
|
||||
import {
|
||||
useCascaderActions,
|
||||
useCascaderHighlight,
|
||||
useCascaderState,
|
||||
} from "@/components/reui/cascader/cascader-context"
|
||||
import type { CascaderColumn } from "@/components/reui/cascader/cascader-context"
|
||||
import {
|
||||
CascaderItem,
|
||||
CascaderItems,
|
||||
getCascaderMoreProps,
|
||||
} from "@/components/reui/cascader/cascader-item"
|
||||
import {
|
||||
defaultRangeExtractor,
|
||||
useVirtualizer,
|
||||
type Range,
|
||||
type Virtualizer,
|
||||
} from "@tanstack/react-virtual"
|
||||
|
||||
/**
|
||||
* Windowing for the cascader, in its own file so the primitive's own install
|
||||
* never pulls `@tanstack/react-virtual` in. Base UI forces three rules:
|
||||
*
|
||||
* 1. A windowed row MUST carry an explicit `index`; the fallback
|
||||
* `findItemIndex` is O(n) per row and returns `-1` on the frame a level swap
|
||||
* renders empty, dangling `aria-activedescendant`.
|
||||
* 2. That index is DESTRUCTIVE while unvirtualized (`useCompositeListItem`
|
||||
* skips registration, `CompositeList` truncates `elementsRef` to zero and
|
||||
* the first arrow key highlights nothing), so rows stay plain until the root
|
||||
* flips `virtualized`, gated inside `CascaderItem`.
|
||||
* 3. No `Combobox.Collection` and no FUNCTION CHILD on `Combobox.List`, which
|
||||
* implicitly wraps one in a Collection: a Collection renders every filtered
|
||||
* item.
|
||||
*/
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Virtualizer */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface UseCascaderVirtualizerOptions {
|
||||
count: number
|
||||
getScrollElement: () => HTMLElement | null
|
||||
estimateSize?: number
|
||||
overscan?: number
|
||||
/** Key rows by node value, never by index: a tree expand shifts every index. */
|
||||
getItemKey: (index: number) => string | number
|
||||
/** Render index of the highlighted row, or `-1`. Pinned into the window. */
|
||||
activeIndex?: number
|
||||
}
|
||||
|
||||
export type CascaderVirtualizer = Virtualizer<HTMLElement, HTMLElement>
|
||||
|
||||
/**
|
||||
* The cascader's virtualizer: TanStack plus the highlight pinning and
|
||||
* scroll-into-view a combobox list needs. `activeIndex` is clamped here, not by
|
||||
* the caller: emitted from a layout effect, it can be one commit ahead of a
|
||||
* level that just shrank and would otherwise scroll to a row that is gone.
|
||||
*/
|
||||
export function useCascaderVirtualizer({
|
||||
count,
|
||||
getScrollElement,
|
||||
estimateSize = 32,
|
||||
overscan = 8,
|
||||
getItemKey,
|
||||
activeIndex = -1,
|
||||
}: UseCascaderVirtualizerOptions): CascaderVirtualizer {
|
||||
const active = activeIndex >= 0 && activeIndex < count ? activeIndex : -1
|
||||
|
||||
// Keeps the highlighted row mounted so `aria-activedescendant` never dangles.
|
||||
const rangeExtractor = React.useCallback(
|
||||
(range: Range) => {
|
||||
const indices = new Set(defaultRangeExtractor(range))
|
||||
if (active !== -1) indices.add(active)
|
||||
return Array.from(indices).sort((a, b) => a - b)
|
||||
},
|
||||
[active]
|
||||
)
|
||||
|
||||
const measureEstimate = React.useCallback(() => estimateSize, [estimateSize])
|
||||
|
||||
// React Compiler bails on `useVirtualizer`; harmless, rows memoise one by one.
|
||||
// eslint-disable-next-line react-hooks/incompatible-library
|
||||
const virtualizer = useVirtualizer<HTMLElement, HTMLElement>({
|
||||
count,
|
||||
getScrollElement,
|
||||
estimateSize: measureEstimate,
|
||||
overscan,
|
||||
getItemKey,
|
||||
rangeExtractor,
|
||||
})
|
||||
|
||||
// Base UI's scroll-into-view no-ops on a windowed-out row (empty `listRef`).
|
||||
React.useEffect(() => {
|
||||
if (active === -1) return
|
||||
virtualizer.scrollToIndex(active, { align: "auto" })
|
||||
}, [active, count, virtualizer])
|
||||
|
||||
return virtualizer
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Geometry */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
interface CascaderVirtualGutter {
|
||||
block: number
|
||||
inline: number
|
||||
}
|
||||
|
||||
const NO_GUTTER: CascaderVirtualGutter = { block: 0, inline: 0 }
|
||||
|
||||
/**
|
||||
* The ROWS' BOX's own padding, never the scrollport's (separate element, reads
|
||||
* a flat zero). Measured because every style sets its own: a windowed row is
|
||||
* positioned against this box's PADDING box while the scroll-height spacer is
|
||||
* an in-flow child of its CONTENT box, so without it rows sit flush.
|
||||
*/
|
||||
function useCascaderVirtualGutter(
|
||||
contentElement: HTMLElement | null
|
||||
): CascaderVirtualGutter {
|
||||
const [gutter, setGutter] = React.useState<CascaderVirtualGutter>(NO_GUTTER)
|
||||
|
||||
React.useLayoutEffect(() => {
|
||||
if (!contentElement) return
|
||||
const styles = getComputedStyle(contentElement)
|
||||
const block = Number.parseFloat(styles.paddingTop) || 0
|
||||
const inline =
|
||||
Number.parseFloat(styles.paddingInlineStart || styles.paddingLeft) || 0
|
||||
setGutter((previous) =>
|
||||
previous.block === block && previous.inline === inline
|
||||
? previous
|
||||
: { block, inline }
|
||||
)
|
||||
}, [contentElement])
|
||||
|
||||
return gutter
|
||||
}
|
||||
|
||||
/** Logical insets, not `left` / `width`, so RTL needs no second code path. */
|
||||
function cascaderVirtualRowStyle(
|
||||
start: number,
|
||||
gutter: CascaderVirtualGutter
|
||||
): React.CSSProperties {
|
||||
return {
|
||||
position: "absolute",
|
||||
top: 0,
|
||||
insetInlineStart: gutter.inline,
|
||||
insetInlineEnd: gutter.inline,
|
||||
transform: `translateY(${start + gutter.block}px)`,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The element that actually SCROLLS: the `ScrollArea` viewport above the rows'
|
||||
* box, not the rows' box itself, which never overflows, so a virtualizer aimed
|
||||
* at it would read a full `clientHeight` and render every row. `closest` rather
|
||||
* than `parentElement`, plus a fallback to the content element, keeps a
|
||||
* hand-written `overflow-y-auto` container working.
|
||||
*/
|
||||
function cascaderScrollElement(
|
||||
content: HTMLElement | null
|
||||
): HTMLElement | null {
|
||||
if (!content) return null
|
||||
return (
|
||||
content.closest<HTMLElement>('[data-slot="scroll-area-viewport"]') ??
|
||||
content
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* `role="presentation"` keeps the listbox owning nothing but options, and this
|
||||
* node's parent IS the rows' box, saving a ref threaded through `CascaderList`.
|
||||
*/
|
||||
function CascaderVirtualSpacer({
|
||||
height,
|
||||
onContentElement,
|
||||
}: {
|
||||
height: number
|
||||
onContentElement: (element: HTMLElement | null) => void
|
||||
}) {
|
||||
return (
|
||||
<div
|
||||
ref={(node) => onContentElement(node?.parentElement ?? null)}
|
||||
role="presentation"
|
||||
data-slot="cascader-virtual-spacer"
|
||||
style={{ height }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Rows */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderVirtualItemsProps {
|
||||
/** Row height before measurement. Defaults to the root `estimateRowSize`. */
|
||||
estimateSize?: number
|
||||
/** Rows rendered beyond each edge. Defaults to the root `overscan`. */
|
||||
overscan?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Windowed replacement for `CascaderItems`, dropped inside `CascaderList`. The
|
||||
* registration is a LAYOUT effect because the root derives `virtualized` from
|
||||
* it and the flip has to land before the browser paints. Until the root has
|
||||
* seen it, this renders exactly what `CascaderItems` does, so no frame carries
|
||||
* indexed rows while Base UI still owns the composite list.
|
||||
*/
|
||||
function CascaderVirtualItems(props: CascaderVirtualItemsProps) {
|
||||
const { virtualized, registerVirtualRenderer } = useCascaderActions()
|
||||
|
||||
React.useLayoutEffect(
|
||||
() => registerVirtualRenderer(),
|
||||
[registerVirtualRenderer]
|
||||
)
|
||||
|
||||
if (!virtualized) return <CascaderItems />
|
||||
|
||||
return <CascaderVirtualRows {...props} />
|
||||
}
|
||||
|
||||
function CascaderVirtualRows({
|
||||
estimateSize,
|
||||
overscan,
|
||||
}: CascaderVirtualItemsProps) {
|
||||
const {
|
||||
estimateRowSize,
|
||||
overscan: rootOverscan,
|
||||
mode,
|
||||
isBranch,
|
||||
isSelectable,
|
||||
isSelected,
|
||||
isIndeterminate,
|
||||
} = useCascaderActions()
|
||||
const { renderedItems, treeRows, deepResults, loadStates } =
|
||||
useCascaderState()
|
||||
// Re-renders on every highlight change, and has to: the pinned row and the
|
||||
// scroll target are both derived from it.
|
||||
const highlight = useCascaderHighlight()
|
||||
|
||||
const [contentElement, setContentElement] =
|
||||
React.useState<HTMLElement | null>(null)
|
||||
const gutter = useCascaderVirtualGutter(contentElement)
|
||||
|
||||
const tree = mode === "tree"
|
||||
const count = tree ? treeRows.length : renderedItems.length
|
||||
const showPath = !tree && deepResults !== null
|
||||
|
||||
const getItemKey = React.useCallback(
|
||||
(index: number) =>
|
||||
(tree ? treeRows[index]?.node.value : renderedItems[index]?.value) ??
|
||||
index,
|
||||
[tree, treeRows, renderedItems]
|
||||
)
|
||||
|
||||
const virtualizer = useCascaderVirtualizer({
|
||||
count,
|
||||
getScrollElement: () => cascaderScrollElement(contentElement),
|
||||
estimateSize: estimateSize ?? estimateRowSize,
|
||||
overscan: overscan ?? rootOverscan,
|
||||
getItemKey,
|
||||
activeIndex: highlight.index,
|
||||
})
|
||||
|
||||
return (
|
||||
<>
|
||||
<CascaderVirtualSpacer
|
||||
height={virtualizer.getTotalSize()}
|
||||
onContentElement={setContentElement}
|
||||
/>
|
||||
{virtualizer.getVirtualItems().map((row) => {
|
||||
const flat = tree ? treeRows[row.index] : undefined
|
||||
const node = tree ? flat?.node : renderedItems[row.index]
|
||||
// For one commit after a query narrows the level, the window can name
|
||||
// a row it no longer has; the count recomputes on the same tick.
|
||||
if (!node) return null
|
||||
|
||||
return (
|
||||
<CascaderItem
|
||||
key={row.key}
|
||||
/* Measured, not estimated: rows are two lines with a `description`
|
||||
and three in deep search, and row height is per style. An
|
||||
estimate alone would make `scrollToIndex` land on the wrong row. */
|
||||
ref={virtualizer.measureElement}
|
||||
data-index={row.index}
|
||||
style={cascaderVirtualRowStyle(row.start, gutter)}
|
||||
node={node}
|
||||
index={row.index}
|
||||
depth={flat?.depth}
|
||||
expanded={flat?.expanded}
|
||||
branch={flat ? flat.branch : isBranch(node)}
|
||||
selectable={isSelectable(node)}
|
||||
selected={isSelected(node)}
|
||||
indeterminate={isIndeterminate(node)}
|
||||
{...getCascaderMoreProps(node, loadStates)}
|
||||
showPath={showPath}
|
||||
aria-setsize={flat ? flat.setSize : count}
|
||||
aria-posinset={flat ? flat.posInSet : row.index + 1}
|
||||
/>
|
||||
)
|
||||
})}
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------------- */
|
||||
/* Column */
|
||||
/* -------------------------------------------------------------------------- */
|
||||
|
||||
export interface CascaderVirtualColumnProps extends CascaderVirtualItemsProps {
|
||||
column: CascaderColumn
|
||||
}
|
||||
|
||||
/**
|
||||
* Windowed replacement for one Miller column, passed through the
|
||||
* `CascaderColumns` render slot. One virtualizer PER COLUMN, since columns
|
||||
* scroll independently, and only the deepest is Base UI's listbox: the trail
|
||||
* behind is `as="button"` rows outside Base UI, so it windows on its own row
|
||||
* count rather than waiting for the root to flip.
|
||||
*/
|
||||
function CascaderVirtualColumn({
|
||||
column,
|
||||
estimateSize,
|
||||
overscan,
|
||||
}: CascaderVirtualColumnProps) {
|
||||
const {
|
||||
virtualized,
|
||||
registerVirtualRenderer,
|
||||
virtualize,
|
||||
virtualizeThreshold,
|
||||
} = useCascaderActions()
|
||||
|
||||
React.useLayoutEffect(
|
||||
() => registerVirtualRenderer(),
|
||||
[registerVirtualRenderer]
|
||||
)
|
||||
|
||||
const windowed = column.active
|
||||
? virtualized
|
||||
: (virtualize ?? column.items.length >= virtualizeThreshold)
|
||||
|
||||
if (!windowed) return <CascaderColumnPanel column={column} />
|
||||
|
||||
return (
|
||||
<CascaderColumnPanel column={column} virtualized>
|
||||
{column.active ? (
|
||||
<CascaderVirtualActiveColumnRows
|
||||
column={column}
|
||||
estimateSize={estimateSize}
|
||||
overscan={overscan}
|
||||
/>
|
||||
) : (
|
||||
<CascaderVirtualColumnRows
|
||||
column={column}
|
||||
estimateSize={estimateSize}
|
||||
overscan={overscan}
|
||||
activeIndex={-1}
|
||||
/>
|
||||
)}
|
||||
</CascaderColumnPanel>
|
||||
)
|
||||
}
|
||||
|
||||
/** Only the active column subscribes to the highlight; a trail column must not. */
|
||||
function CascaderVirtualActiveColumnRows(props: CascaderVirtualColumnProps) {
|
||||
const highlight = useCascaderHighlight()
|
||||
return <CascaderVirtualColumnRows {...props} activeIndex={highlight.index} />
|
||||
}
|
||||
|
||||
function CascaderVirtualColumnRows({
|
||||
column,
|
||||
estimateSize,
|
||||
overscan,
|
||||
activeIndex,
|
||||
}: CascaderVirtualColumnProps & { activeIndex: number }) {
|
||||
const {
|
||||
estimateRowSize,
|
||||
overscan: rootOverscan,
|
||||
baseId,
|
||||
isBranch,
|
||||
isSelectable,
|
||||
isSelected,
|
||||
isIndeterminate,
|
||||
} = useCascaderActions()
|
||||
const { loadStates } = useCascaderState()
|
||||
|
||||
const [contentElement, setContentElement] =
|
||||
React.useState<HTMLElement | null>(null)
|
||||
const gutter = useCascaderVirtualGutter(contentElement)
|
||||
|
||||
const items = column.items
|
||||
const getItemKey = React.useCallback(
|
||||
(index: number) => items[index]?.value ?? index,
|
||||
[items]
|
||||
)
|
||||
|
||||
const virtualizer = useCascaderVirtualizer({
|
||||
count: items.length,
|
||||
getScrollElement: () => cascaderScrollElement(contentElement),
|
||||
estimateSize: estimateSize ?? estimateRowSize,
|
||||
overscan: overscan ?? rootOverscan,
|
||||
getItemKey,
|
||||
activeIndex,
|
||||
})
|
||||
|
||||
return (
|
||||
<>
|
||||
<CascaderVirtualSpacer
|
||||
height={virtualizer.getTotalSize()}
|
||||
onContentElement={setContentElement}
|
||||
/>
|
||||
{virtualizer.getVirtualItems().map((row) => {
|
||||
const node = items[row.index]
|
||||
if (!node) return null
|
||||
const open = node.value === column.activeValue
|
||||
|
||||
return (
|
||||
<CascaderItem
|
||||
key={row.key}
|
||||
ref={virtualizer.measureElement}
|
||||
data-index={row.index}
|
||||
style={cascaderVirtualRowStyle(row.start, gutter)}
|
||||
node={node}
|
||||
as={column.active ? "option" : "button"}
|
||||
depth={column.depth}
|
||||
branch={isBranch(node)}
|
||||
selectable={isSelectable(node)}
|
||||
selected={isSelected(node)}
|
||||
indeterminate={isIndeterminate(node)}
|
||||
{...getCascaderMoreProps(node, loadStates)}
|
||||
data-open={open || undefined}
|
||||
className={open ? "bg-accent/60 text-accent-foreground" : undefined}
|
||||
/* Only the listbox column may carry an index or listbox metadata.
|
||||
A trail row is a `role="button"`, which allows neither. */
|
||||
{...(column.active
|
||||
? {
|
||||
index: row.index,
|
||||
"aria-setsize": items.length,
|
||||
"aria-posinset": row.index + 1,
|
||||
}
|
||||
: null)}
|
||||
{...(!column.active && open
|
||||
? {
|
||||
"aria-expanded": true,
|
||||
"aria-controls": `${baseId}-column-${column.depth + 1}`,
|
||||
}
|
||||
: null)}
|
||||
/>
|
||||
)
|
||||
})}
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
export { CascaderVirtualColumn, CascaderVirtualItems }
|
||||
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user