@nuasite/cms 0.29.0 → 0.30.0

package/src/editor/components/markdown-inline-editor.tsx

@@ -20,6 +20,7 @@ import { config, mdxComponentPickerOpen, openMediaLibraryWithCallback, resetMark
 import { LinkEditPopover } from './link-edit-popover'
 import { MdxComponentIcon } from './mdx-block-view'
 import { MdxComponentPicker } from './mdx-component-picker'
+import { Spinner } from './spinner'
 
 export interface MarkdownInlineEditorProps {
 	elementId: string
@@ -649,7 +650,7 @@ export function MarkdownInlineEditor({
 				{/* Loading state */}
 				{!isReady && (
 					<div class="absolute inset-0 flex items-center justify-center bg-cms-dark/80">
-						<div class="animate-spin rounded-full h-6 w-6 border-2 border-white/30 border-t-cms-primary" />
+						<Spinner size="lg" className="text-cms-primary" />
 					</div>
 				)}
 			</div>

package/src/editor/components/mdx-component-picker.tsx

@@ -2,7 +2,7 @@ import { useState } from 'preact/hooks'
 import { getComponentDefinitions } from '../manifest'
 import { manifest, mdxComponentPickerOpen } from '../signals'
 import { ComponentCard, getDefaultProps } from './component-card'
-import { CancelButton, ModalBackdrop, ModalHeader } from './modal-shell'
+import { CancelButton, ModalBackdrop, ModalHeader, PrimaryButton } from './modal-shell'
 import { PropEditor } from './prop-editor'
 
 export interface MdxComponentPickerProps {
@@ -106,12 +106,9 @@ export function MdxComponentPicker({ onInsert }: MdxComponentPickerProps) {
 						</div>
 						<div class="px-5 py-4 border-t border-white/10 flex gap-2 justify-end">
 							<CancelButton onClick={resetSelection} label="Back" />
-							<button
-								onClick={handleConfirmInsert}
-								class="px-4 py-2.5 bg-cms-primary text-cms-primary-text rounded-cms-pill cursor-pointer hover:bg-cms-primary-hover transition-all font-medium"
-							>
+							<PrimaryButton onClick={handleConfirmInsert} className="px-4">
 								Insert
-							</button>
+							</PrimaryButton>
 						</div>
 					</>
 				)

package/src/editor/components/media-library.tsx

@@ -1,8 +1,11 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import { Z_INDEX } from '../constants'
+import { useSearchFilter } from '../hooks/useSearchFilter'
 import { createMediaFolder, fetchMediaLibrary, fetchProjectImages, uploadMedia } from '../markdown-api'
 import { config, isMediaLibraryOpen, mediaLibraryState, resetMediaLibraryState, showToast } from '../signals'
 import type { MediaFolderItem, MediaItem, MediaTypeFilter } from '../types'
+import { CloseButton, PrimaryButton } from './modal-shell'
+import { Spinner } from './spinner'
 
 const VECTOR_TYPES = new Set(['image/svg+xml', 'image/x-icon'])
 
@@ -187,18 +190,12 @@ export function MediaLibrary() {
 		setShowNewFolderInput(false)
 	}
 
-	// Client-side filtering: both search query AND type filter
-	const filteredItems = useMemo(() => {
-		let items = allItems
-		if (typeFilter !== 'all') {
-			items = items.filter((item) => matchesTypeFilter(item.contentType, typeFilter))
-		}
-		if (searchQuery) {
-			const q = searchQuery.toLowerCase()
-			items = items.filter((item) => item.filename.toLowerCase().includes(q))
-		}
-		return items
-	}, [searchQuery, typeFilter, allItems])
+	// Client-side filtering: type filter, then search query
+	const typeFiltered = useMemo(
+		() => typeFilter === 'all' ? allItems : allItems.filter(item => matchesTypeFilter(item.contentType, typeFilter)),
+		[typeFilter, allItems],
+	)
+	const filteredItems = useSearchFilter(typeFiltered, searchQuery, item => item.filename)
 
 	// Build breadcrumb segments
 	const breadcrumbs = useMemo(() => {
@@ -230,16 +227,7 @@ export function MediaLibrary() {
 				{/* Header */}
 				<div class="flex items-center justify-between p-5 border-b border-white/10">
 					<h2 class="text-lg font-semibold text-white">Media Library</h2>
-					<button
-						type="button"
-						onClick={handleClose}
-						class="text-white/50 hover:text-white p-1.5 hover:bg-white/10 rounded-full transition-colors"
-						data-cms-ui
-					>
-						<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-							<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
-						</svg>
-					</button>
+					<CloseButton onClick={handleClose} />
 				</div>
 
 				{/* Breadcrumbs */}
@@ -307,14 +295,9 @@ export function MediaLibrary() {
 								/>
 							</svg>
 						</button>
-						<button
-							type="button"
-							onClick={handleUploadClick}
-							class="px-5 py-2.5 bg-cms-primary text-cms-primary-text rounded-cms-pill text-sm font-medium hover:bg-cms-primary-hover transition-colors"
-							data-cms-ui
-						>
+						<PrimaryButton onClick={handleUploadClick}>
 							Upload
-						</button>
+						</PrimaryButton>
 						<input
 							ref={fileInputRef}
 							type="file"
@@ -372,14 +355,9 @@ export function MediaLibrary() {
 							class="flex-1 px-3 py-1.5 bg-white/10 border border-white/20 rounded-cms-md text-sm text-white placeholder:text-white/40 focus:outline-none focus:border-white/40"
 							data-cms-ui
 						/>
-						<button
-							type="button"
-							onClick={handleCreateFolder}
-							class="px-3 py-1.5 bg-cms-primary text-cms-primary-text rounded-cms-md text-xs font-medium hover:bg-cms-primary-hover transition-colors"
-							data-cms-ui
-						>
+						<PrimaryButton onClick={handleCreateFolder} className="px-3 py-1.5 rounded-cms-md text-xs">
 							Create
-						</button>
+						</PrimaryButton>
 						<button
 							type="button"
 							onClick={() => {
@@ -414,7 +392,7 @@ export function MediaLibrary() {
 					{isLoading
 						? (
 							<div class="flex items-center justify-center h-48">
-								<div class="animate-spin rounded-full h-8 w-8 border-b-2 border-cms-primary" />
+								<Spinner size="xl" className="text-cms-primary" />
 							</div>
 						)
 						: folders.length === 0 && filteredItems.length === 0

package/src/editor/components/modal-shell.tsx

@@ -1,5 +1,6 @@
 import type { ComponentChildren } from 'preact'
 import { Z_INDEX } from '../constants'
+import { cn } from '../lib/cn'
 
 export function ModalBackdrop({ onClose, maxWidth = 'max-w-lg', extraClass, children }: {
 	onClose: () => void
@@ -15,7 +16,7 @@ export function ModalBackdrop({ onClose, maxWidth = 'max-w-lg', extraClass, chil
 			data-cms-ui
 		>
 			<div
-				class={`bg-cms-dark rounded-cms-xl shadow-[0_8px_32px_rgba(0,0,0,0.4)] ${maxWidth} w-full border border-white/10 ${extraClass ?? ''}`}
+				class={cn('bg-cms-dark rounded-cms-xl shadow-[0_8px_32px_rgba(0,0,0,0.4)] w-full border border-white/10', maxWidth, extraClass)}
 				onClick={(e) => e.stopPropagation()}
 				data-cms-ui
 			>
@@ -58,7 +59,7 @@ export function ModalFooter({ children }: { children: ComponentChildren }) {
 	)
 }
 
-export function CloseButton({ onClick }: { onClick: () => void }) {
+export function CloseButton({ onClick, size = 'md' }: { onClick: () => void; size?: 'sm' | 'md' }) {
 	return (
 		<button
 			type="button"
@@ -66,22 +67,50 @@ export function CloseButton({ onClick }: { onClick: () => void }) {
 			class="text-white/50 hover:text-white p-1.5 hover:bg-white/10 rounded-full transition-colors cursor-pointer"
 			data-cms-ui
 		>
-			<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+			<svg class={size === 'sm' ? 'w-4 h-4' : 'w-5 h-5'} fill="none" stroke="currentColor" viewBox="0 0 24 24">
 				<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
 			</svg>
 		</button>
 	)
 }
 
-export function CancelButton({ onClick, label = 'Cancel' }: { onClick: () => void; label?: string }) {
+export function CancelButton({ onClick, label = 'Cancel', className }: { onClick: () => void; label?: string; className?: string }) {
 	return (
 		<button
 			type="button"
 			onClick={onClick}
-			class="px-4 py-2.5 text-sm text-white/80 font-medium rounded-cms-pill hover:bg-white/10 hover:text-white transition-colors cursor-pointer"
+			class={cn(
+				'px-4 py-2.5 text-sm text-white/80 font-medium rounded-cms-pill hover:bg-white/10 hover:text-white transition-colors cursor-pointer',
+				className,
+			)}
 			data-cms-ui
 		>
 			{label}
 		</button>
 	)
 }
+
+export function PrimaryButton({ onClick, children, disabled, type = 'button', className }: {
+	onClick?: () => void
+	children: ComponentChildren
+	disabled?: boolean
+	type?: 'button' | 'submit'
+	className?: string
+}) {
+	return (
+		<button
+			type={type}
+			onClick={onClick}
+			disabled={disabled}
+			class={cn(
+				'px-5 py-2.5 text-sm font-medium rounded-cms-pill transition-colors cursor-pointer',
+				'bg-cms-primary text-cms-primary-text hover:bg-cms-primary-hover',
+				'disabled:opacity-40 disabled:cursor-not-allowed',
+				className,
+			)}
+			data-cms-ui
+		>
+			{children}
+		</button>
+	)
+}

package/src/editor/components/prop-editor.tsx

@@ -1,8 +1,10 @@
-import { useMemo, useRef, useState } from 'preact/hooks'
+import { useCallback, useMemo, useRef, useState } from 'preact/hooks'
 import { slugify } from '../../shared'
+import { useSearchFilter } from '../hooks/useSearchFilter'
 import { getCollectionEntryOptions } from '../manifest'
 import { manifest, openMediaLibraryWithCallback, pendingCollectionEntries } from '../signals'
 import type { ComponentProp } from '../types'
+import { DropdownPanel } from './fields'
 import { SchemaFrontmatterField } from './frontmatter-fields'
 
 export interface PropEditorProps {
@@ -181,20 +183,14 @@ function ReferenceSelect({ collection, value, required, onChange }: {
 		[collection, currentManifest],
 	)
 	const collectionDef = currentManifest?.collectionDefinitions?.[collection]
-	const containerRef = useRef<HTMLDivElement>(null)
+	const inputRef = useRef<HTMLInputElement>(null)
 	const [search, setSearch] = useState('')
 	const [isOpen, setIsOpen] = useState(false)
 	const [isCreating, setIsCreating] = useState(false)
 	const [newName, setNewName] = useState('')
 	const [formData, setFormData] = useState<Record<string, unknown>>({})
 
-	const filtered = useMemo(
-		() =>
-			search
-				? options.filter(o => o.label.toLowerCase().includes(search.toLowerCase()) || o.value.toLowerCase().includes(search.toLowerCase()))
-				: options,
-		[options, search],
-	)
+	const filtered = useSearchFilter(options, search, o => `${o.label} ${o.value}`)
 
 	const selectedLabel = useMemo(
 		() => value ? (options.find(o => o.value === value)?.label ?? value) : '',
@@ -206,6 +202,8 @@ function ReferenceSelect({ collection, value, required, onChange }: {
 		[collectionDef],
 	)
 
+	const closeDropdown = useCallback(() => setIsOpen(false), [])
+
 	const resetCreateForm = () => {
 		setIsCreating(false)
 		setNewName('')
@@ -309,8 +307,9 @@ function ReferenceSelect({ collection, value, required, onChange }: {
 	}
 
 	return (
-		<div class="relative" ref={containerRef}>
+		<div>
 			<input
+				ref={inputRef}
 				type="text"
 				value={isOpen ? search : selectedLabel}
 				onInput={(e) => {
@@ -318,67 +317,67 @@ function ReferenceSelect({ collection, value, required, onChange }: {
 					setIsOpen(true)
 				}}
 				onFocus={() => setIsOpen(true)}
-				onBlur={(e) => {
-					const related = (e as FocusEvent).relatedTarget as Node | null
-					if (containerRef.current && related && containerRef.current.contains(related)) return
-					setIsOpen(false)
-				}}
+				onBlur={() => setTimeout(closeDropdown, 150)}
 				placeholder={`Select ${collection} entry...`}
 				class="w-full px-4 py-2.5 bg-white/10 border border-white/20 text-[13px] text-white placeholder:text-white/40 outline-none focus:border-white/40 focus:ring-1 focus:ring-white/10 transition-all rounded-cms-md"
 			/>
-			{isOpen && (
-				<div class="absolute z-10 mt-1 w-full max-h-48 overflow-y-auto bg-cms-dark border border-white/20 rounded-cms-md shadow-lg">
-					{!required && (
-						<button
-							type="button"
-							onMouseDown={(e) => e.preventDefault()}
-							onClick={() => {
-								onChange('')
-								setSearch('')
-								setIsOpen(false)
-							}}
-							class="w-full px-4 py-2 text-left text-[13px] text-white/50 hover:bg-white/10 transition-colors"
-						>
-							— None —
-						</button>
-					)}
-					{filtered.map((opt) => (
-						<button
-							key={opt.value}
-							type="button"
-							onMouseDown={(e) => e.preventDefault()}
-							onClick={() => {
-								onChange(opt.value)
-								setSearch('')
-								setIsOpen(false)
-							}}
-							class={`w-full px-4 py-2 text-left text-[13px] transition-colors ${
-								opt.value === value ? 'bg-cms-primary/20 text-white' : 'text-white/80 hover:bg-white/10'
-							}`}
-						>
-							<div>{opt.label}</div>
-							{opt.label !== opt.value && <div class="text-[11px] text-white/40 font-mono">{opt.value}</div>}
-						</button>
-					))}
-					{filtered.length === 0 && <div class="px-4 py-2 text-[13px] text-white/40">No entries found</div>}
-					{collectionDef && (
-						<button
-							type="button"
-							onMouseDown={(e) => e.preventDefault()}
-							onClick={() => {
-								setIsCreating(true)
-								setIsOpen(false)
-							}}
-							class="w-full px-4 py-2 text-left text-[13px] text-cms-primary hover:bg-cms-primary/10 transition-colors border-t border-white/10 flex items-center gap-2"
-						>
-							<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2.5">
-								<path stroke-linecap="round" stroke-linejoin="round" d="M12 4v16m8-8H4" />
-							</svg>
-							Create new {collectionDef.label?.toLowerCase() ?? collection}
-						</button>
-					)}
-				</div>
-			)}
+			<DropdownPanel
+				triggerRef={inputRef}
+				isOpen={isOpen}
+				onClose={closeDropdown}
+				maxHeight={192}
+				className="border border-white/20 rounded-cms-md"
+			>
+				{!required && (
+					<button
+						type="button"
+						onMouseDown={(e) => e.preventDefault()}
+						onClick={() => {
+							onChange('')
+							setSearch('')
+							setIsOpen(false)
+						}}
+						class="w-full px-4 py-2 text-left text-[13px] text-white/50 hover:bg-white/10 transition-colors"
+					>
+						— None —
+					</button>
+				)}
+				{filtered.map((opt) => (
+					<button
+						key={opt.value}
+						type="button"
+						onMouseDown={(e) => e.preventDefault()}
+						onClick={() => {
+							onChange(opt.value)
+							setSearch('')
+							setIsOpen(false)
+						}}
+						class={`w-full px-4 py-2 text-left text-[13px] transition-colors ${
+							opt.value === value ? 'bg-cms-primary/20 text-white' : 'text-white/80 hover:bg-white/10'
+						}`}
+					>
+						<div>{opt.label}</div>
+						{opt.label !== opt.value && <div class="text-[11px] text-white/40 font-mono">{opt.value}</div>}
+					</button>
+				))}
+				{filtered.length === 0 && <div class="px-4 py-2 text-[13px] text-white/40">No entries found</div>}
+				{collectionDef && (
+					<button
+						type="button"
+						onMouseDown={(e) => e.preventDefault()}
+						onClick={() => {
+							setIsCreating(true)
+							setIsOpen(false)
+						}}
+						class="w-full px-4 py-2 text-left text-[13px] text-cms-primary hover:bg-cms-primary/10 transition-colors border-t border-white/10 flex items-center gap-2"
+					>
+						<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2.5">
+							<path stroke-linecap="round" stroke-linejoin="round" d="M12 4v16m8-8H4" />
+						</svg>
+						Create new {collectionDef.label?.toLowerCase() ?? collection}
+					</button>
+				)}
+			</DropdownPanel>
 		</div>
 	)
 }

package/src/editor/components/reference-picker.tsx

@@ -1,8 +1,11 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import { clampPanelPosition, Z_INDEX } from '../constants'
+import { useClickOutsideEscape } from '../hooks/useClickOutsideEscape'
+import { useSearchFilter } from '../hooks/useSearchFilter'
 import { getCollectionEntryOptions } from '../manifest'
 import { updateMarkdownPage } from '../markdown-api'
 import { closeReferencePicker, config, manifest, referencePickerState, showToast } from '../signals'
+import { Spinner } from './spinner'
 
 const PANEL_WIDTH = 320
 
@@ -27,11 +30,7 @@ export function ReferencePicker() {
 		}
 	}, [state.isOpen])
 
-	const filtered = useMemo(() => {
-		if (!query) return options
-		const q = query.toLowerCase()
-		return options.filter(o => o.label.toLowerCase().includes(q) || o.value.toLowerCase().includes(q))
-	}, [query, options])
+	const filtered = useSearchFilter(options, query, o => `${o.label} ${o.value}`)
 
 	const currentLabel = useMemo(() => {
 		if (state.isArray) return null
@@ -69,24 +68,7 @@ export function ReferencePicker() {
 		updateReference([...current])
 	}, [state.currentValues, updateReference])
 
-	// Close on outside click or Escape
-	useEffect(() => {
-		if (!state.isOpen) return
-		const onMouseDown = (e: MouseEvent) => {
-			if (panelRef.current && !panelRef.current.contains(e.target as Node)) {
-				closeReferencePicker()
-			}
-		}
-		const onKeyDown = (e: KeyboardEvent) => {
-			if (e.key === 'Escape') closeReferencePicker()
-		}
-		document.addEventListener('mousedown', onMouseDown)
-		document.addEventListener('keydown', onKeyDown)
-		return () => {
-			document.removeEventListener('mousedown', onMouseDown)
-			document.removeEventListener('keydown', onKeyDown)
-		}
-	}, [state.isOpen])
+	useClickOutsideEscape([panelRef], state.isOpen, closeReferencePicker)
 
 	if (!state.isOpen || !state.cursorPos) return null
 
@@ -113,7 +95,7 @@ export function ReferencePicker() {
 			{saving
 				? (
 					<div class="flex items-center justify-center gap-2 px-4 py-6">
-						<span class="inline-block w-4 h-4 border-2 border-white/80 border-t-transparent rounded-full animate-spin" />
+						<Spinner className="text-white/80" />
 						<span class="text-sm text-white/80">Updating...</span>
 					</div>
 				)

package/src/editor/components/seo-editor.tsx

@@ -16,7 +16,8 @@ import {
 } from '../signals'
 import type { ChangePayload, PageSeoData, PendingSeoChange } from '../types'
 import { ColorField, ComboBoxField, ImageField } from './fields'
-import { CloseButton, ModalBackdrop } from './modal-shell'
+import { CancelButton, CloseButton, ModalBackdrop } from './modal-shell'
+import { Spinner } from './spinner'
 
 const OG_TYPE_OPTIONS = [
 	{ value: 'website', label: 'Website', description: 'Default type for most pages' },
@@ -549,14 +550,7 @@ export function SeoEditor() {
 			{/* Footer */}
 			{hasSeoData && (
 				<div class="flex items-center justify-end gap-3 px-5 py-4 border-t border-white/10">
-					<button
-						type="button"
-						onClick={handleClose}
-						class="px-4 py-2 text-sm font-medium text-white/70 hover:text-white hover:bg-white/10 rounded-cms-pill transition-colors"
-						data-cms-ui
-					>
-						Cancel
-					</button>
+					<CancelButton onClick={handleClose} />
 					<button
 						type="button"
 						onClick={handleSaveAll}
@@ -568,7 +562,7 @@ export function SeoEditor() {
 						}`}
 						data-cms-ui
 					>
-						{isSaving && <span class="inline-block w-4 h-4 border-2 border-current border-t-transparent rounded-full animate-spin" />}
+						{isSaving && <Spinner />}
 						{isSaving ? 'Saving...' : 'Save Changes'}
 					</button>
 				</div>

package/src/editor/components/spinner.tsx

@@ -0,0 +1,17 @@
+import { cn } from '../lib/cn'
+
+const sizes = {
+	xs: 'h-3 w-3',
+	sm: 'h-3.5 w-3.5',
+	md: 'h-4 w-4',
+	lg: 'h-6 w-6',
+	xl: 'h-8 w-8',
+} as const
+
+export function Spinner({ size = 'md', className }: { size?: keyof typeof sizes; className?: string }) {
+	return (
+		<span
+			class={cn('inline-block animate-spin rounded-full border-2 border-current/30 border-t-current', sizes[size], className)}
+		/>
+	)
+}

package/src/editor/components/toolbar.tsx

@@ -5,6 +5,7 @@ import { cn } from '../lib/cn'
 import * as signals from '../signals'
 import { showConfirmDialog } from '../signals'
 import type { CollectionDefinition } from '../types'
+import { Spinner } from './spinner'
 
 export interface ToolbarCallbacks {
 	onEdit: () => void
@@ -229,7 +230,7 @@ export const Toolbar = ({ callbacks, collectionDefinitions }: ToolbarProps) => {
 					{/* Saving indicator */}
 					{isSaving && !showingOriginal && (
 						<div class="flex items-center gap-1.5 px-3 py-2 sm:px-5 sm:py-2.5 text-sm font-medium text-white/80">
-							<span class="inline-block w-3.5 h-3.5 border-2 border-white/80 border-t-transparent rounded-full animate-spin" />
+							<Spinner size="sm" className="text-white/80" />
 							<span>Saving</span>
 						</div>
 					)}

package/src/editor/constants.ts

@@ -136,3 +136,36 @@ export function clampPanelPosition(
 		maxHeight: `${maxHeight}px`,
 	}
 }
+
+/**
+ * Calculate fixed-position style for a dropdown that needs to escape parent overflow clipping.
+ * Positions below the trigger element by default, flipping above when space is insufficient.
+ */
+export function getDropdownPosition(
+	trigger: HTMLElement | null,
+	maxHeight: number,
+	padding = LAYOUT.VIEWPORT_PADDING,
+): Record<string, string> | undefined {
+	if (!trigger) return undefined
+	const rect = trigger.getBoundingClientRect()
+	const spaceBelow = window.innerHeight - rect.bottom - padding
+	const spaceAbove = rect.top - padding
+	const showAbove = spaceBelow < 80 && spaceAbove > spaceBelow
+
+	const style: Record<string, string> = {
+		position: 'fixed',
+		left: `${rect.left}px`,
+		width: `${rect.width}px`,
+		zIndex: String(Z_INDEX.MODAL),
+	}
+
+	if (showAbove) {
+		style.bottom = `${window.innerHeight - rect.top + 4}px`
+		style.maxHeight = `${Math.max(Math.min(maxHeight, spaceAbove), 80)}px`
+	} else {
+		style.top = `${rect.bottom + 4}px`
+		style.maxHeight = `${Math.max(Math.min(maxHeight, spaceBelow), 80)}px`
+	}
+
+	return style
+}

package/src/editor/hooks/index.ts

@@ -17,3 +17,7 @@ export type { ImageHoverState } from './useImageHoverDetection'
 
 export { useBgImageHoverDetection } from './useBgImageHoverDetection'
 export type { BgImageHoverState } from './useBgImageHoverDetection'
+
+export { useClickOutsideEscape } from './useClickOutsideEscape'
+
+export { useSearchFilter } from './useSearchFilter'

package/src/editor/hooks/useClickOutsideEscape.ts

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from 'preact/hooks'
+
+/**
+ * Dismiss handler for floating UI: closes on outside mousedown or Escape key.
+ * Pass all refs that should be considered "inside" (e.g. panel + trigger).
+ *
+ * Uses composedPath() so it works correctly inside Shadow DOM, and registers
+ * in the capture phase so stopPropagation() in bubble-phase handlers
+ * (e.g. modal overlays) doesn't block detection.
+ */
+export function useClickOutsideEscape(
+	refs: ReadonlyArray<{ readonly current: HTMLElement | null }>,
+	isOpen: boolean,
+	onClose: () => void,
+): void {
+	// Store refs and onClose in a ref so the effect never needs to re-register
+	// when the caller creates a new array (e.g. from spreading exemptRefs).
+	// The actual .current values of each ref are read at event time, not capture time.
+	const stableRefs = useRef(refs)
+	stableRefs.current = refs
+	const stableOnClose = useRef(onClose)
+	stableOnClose.current = onClose
+
+	useEffect(() => {
+		if (!isOpen) return
+		const onMouseDown = (e: MouseEvent) => {
+			const path = e.composedPath()
+			for (const ref of stableRefs.current) {
+				if (ref.current && path.includes(ref.current)) return
+			}
+			stableOnClose.current()
+		}
+		const onKeyDown = (e: KeyboardEvent) => {
+			if (e.key === 'Escape') stableOnClose.current()
+		}
+		document.addEventListener('mousedown', onMouseDown, true)
+		document.addEventListener('keydown', onKeyDown)
+		return () => {
+			document.removeEventListener('mousedown', onMouseDown, true)
+			document.removeEventListener('keydown', onKeyDown)
+		}
+	}, [isOpen])
+}

package/src/editor/hooks/useSearchFilter.ts

@@ -0,0 +1,21 @@
+import { useMemo, useRef } from 'preact/hooks'
+
+/**
+ * Filter a list of items by a search query.
+ * The `getSearchableText` callback returns the text to match against (e.g. `o => \`${o.label} ${o.value}\``).
+ * Uses a ref internally so callers don't need to memoize the callback.
+ */
+export function useSearchFilter<T>(
+	items: T[],
+	query: string,
+	getSearchableText: (item: T) => string,
+): T[] {
+	const fnRef = useRef(getSearchableText)
+	fnRef.current = getSearchableText
+
+	return useMemo(() => {
+		if (!query) return items
+		const q = query.toLowerCase()
+		return items.filter(item => fnRef.current(item).toLowerCase().includes(q))
+	}, [items, query])
+}