@mieweb/ui 0.3.0-dev.64 → 0.3.0-dev.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/dist/{chunk-R4DM4635.cjs → chunk-FSBFQBNE.cjs} +86 -2
  2. package/dist/chunk-FSBFQBNE.cjs.map +1 -0
  3. package/dist/{chunk-CP7NPDQW.js → chunk-Q7NBJFEB.js} +87 -4
  4. package/dist/chunk-Q7NBJFEB.js.map +1 -0
  5. package/dist/hooks/index.cjs +14 -10
  6. package/dist/hooks/index.d.cts +37 -1
  7. package/dist/hooks/index.d.ts +37 -1
  8. package/dist/hooks/index.js +1 -1
  9. package/dist/index.cjs +197 -13
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.d.cts +82 -2
  12. package/dist/index.d.ts +82 -2
  13. package/dist/index.js +182 -3
  14. package/dist/index.js.map +1 -1
  15. package/dist/styles.css +1 -1
  16. package/package.json +1 -1
  17. package/dist/chunk-CP7NPDQW.js.map +0 -1
  18. package/dist/chunk-R4DM4635.cjs.map +0 -1
package/dist/{chunk-R4DM4635.cjs → chunk-FSBFQBNE.cjs} RENAMED
@@ -95,6 +95,89 @@ function useIsLargeDesktop() {
95
95
  function useIsMobileOrTablet() {
96
96
  return useMediaQuery("(max-width: 1023px)");
97
97
  }
98
+ function useScrollSpy({
99
+ selectors,
100
+ ids,
101
+ rootMargin = "0px 0px -60% 0px",
102
+ threshold = 0,
103
+ root,
104
+ enabled = true
105
+ } = {}) {
106
+ const [activeId, setActiveId] = react.useState(null);
107
+ const visibleEntries = react.useRef(
108
+ /* @__PURE__ */ new Map()
109
+ );
110
+ const rootEl = root?.current ?? null;
111
+ react.useEffect(() => {
112
+ if (!enabled) return;
113
+ const container = rootEl ?? document;
114
+ function resolveElements() {
115
+ let els = [];
116
+ if (ids && ids.length > 0) {
117
+ els = ids.map((id) => document.getElementById(id)).filter((el) => el !== null);
118
+ } else if (selectors) {
119
+ els = Array.from(container.querySelectorAll(selectors));
120
+ }
121
+ return els.filter((el) => el.id);
122
+ }
123
+ let intersectionObserver = null;
124
+ let mutationObserver = null;
125
+ function startObserving() {
126
+ const elements = resolveElements();
127
+ if (elements.length === 0) return false;
128
+ intersectionObserver = new IntersectionObserver(
129
+ (entries2) => {
130
+ for (const entry of entries2) {
131
+ if (entry.isIntersecting) {
132
+ visibleEntries.current.set(entry.target.id, entry);
133
+ } else {
134
+ visibleEntries.current.delete(entry.target.id);
135
+ }
136
+ }
137
+ if (visibleEntries.current.size > 0) {
138
+ let topmost = null;
139
+ let topmostTop = Infinity;
140
+ for (const [id, entry] of visibleEntries.current) {
141
+ const top = entry.boundingClientRect.top;
142
+ if (top < topmostTop) {
143
+ topmostTop = top;
144
+ topmost = id;
145
+ }
146
+ }
147
+ if (topmost) {
148
+ setActiveId(topmost);
149
+ }
150
+ }
151
+ },
152
+ {
153
+ root: rootEl,
154
+ rootMargin,
155
+ threshold
156
+ }
157
+ );
158
+ for (const el of elements) {
159
+ intersectionObserver.observe(el);
160
+ }
161
+ mutationObserver?.disconnect();
162
+ mutationObserver = null;
163
+ return true;
164
+ }
165
+ if (!startObserving()) {
166
+ const watchRoot = rootEl ?? document.body;
167
+ mutationObserver = new MutationObserver(() => {
168
+ startObserving();
169
+ });
170
+ mutationObserver.observe(watchRoot, { childList: true, subtree: true });
171
+ }
172
+ const entries = visibleEntries.current;
173
+ return () => {
174
+ mutationObserver?.disconnect();
175
+ intersectionObserver?.disconnect();
176
+ entries.clear();
177
+ };
178
+ }, [selectors, ids, rootMargin, threshold, rootEl, enabled]);
179
+ return { activeId };
180
+ }
98
181
 
99
182
  exports.useCommandK = useCommandK;
100
183
  exports.useIsDesktop = useIsDesktop;
@@ -105,5 +188,6 @@ exports.useIsSmallTablet = useIsSmallTablet;
105
188
  exports.useIsTablet = useIsTablet;
106
189
  exports.useKeyboardShortcut = useKeyboardShortcut;
107
190
  exports.useMediaQuery = useMediaQuery;
108
- //# sourceMappingURL=chunk-R4DM4635.cjs.map
109
- //# sourceMappingURL=chunk-R4DM4635.cjs.map
191
+ exports.useScrollSpy = useScrollSpy;
192
+ //# sourceMappingURL=chunk-FSBFQBNE.cjs.map
193
+ //# sourceMappingURL=chunk-FSBFQBNE.cjs.map
package/dist/chunk-FSBFQBNE.cjs.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/hooks/useKeyboardShortcut.ts","../src/hooks/useMediaQuery.ts","../src/hooks/useScrollSpy.ts"],"names":["useCallback","useEffect","useState","useRef","entries"],"mappings":"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","file":"chunk-FSBFQBNE.cjs","sourcesContent":["import { useEffect, useCallback } from 'react';\n\n/**\n * Options for keyboard shortcut hook\n */\nexport interface KeyboardShortcutOptions {\n /** Whether the shortcut is currently enabled (default: true) */\n enabled?: boolean;\n /** Modifier keys required (default: none) */\n modifiers?: {\n ctrl?: boolean;\n shift?: boolean;\n alt?: boolean;\n meta?: boolean;\n };\n /** Whether to prevent default browser behavior (default: true) */\n preventDefault?: boolean;\n /** Whether to stop event propagation (default: false) */\n stopPropagation?: boolean;\n /** Element types to ignore when the shortcut is pressed (default: ['INPUT', 'TEXTAREA', 'SELECT']) */\n ignoreInputs?: boolean;\n}\n\n/**\n * Hook that triggers a callback when a specific keyboard shortcut is pressed.\n * Supports modifier keys (Ctrl, Shift, Alt, Meta) and ignores input fields by default.\n *\n * @param key - The key to listen for (e.g., 'k', 'Enter', 'Escape', '/')\n * @param callback - Function to call when the shortcut is pressed\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Cmd/Ctrl+K to open search\n * useKeyboardShortcut('k', openSearch, { modifiers: { meta: true, ctrl: true } });\n *\n * // Forward slash to focus search (ignoring when typing)\n * useKeyboardShortcut('/', focusSearch);\n *\n * // Escape to close modal\n * useKeyboardShortcut('Escape', closeModal);\n * ```\n */\nexport function useKeyboardShortcut(\n key: string,\n callback: (event: KeyboardEvent) => void,\n options: KeyboardShortcutOptions = {}\n): void {\n const {\n enabled = true,\n modifiers = {},\n preventDefault = true,\n stopPropagation = false,\n ignoreInputs = true,\n } = options;\n\n const handleKeyDown = useCallback(\n (event: KeyboardEvent) => {\n // Check if we should ignore input fields\n if (ignoreInputs) {\n const target = event.target as HTMLElement;\n const tagName = target.tagName.toUpperCase();\n if (\n tagName === 'INPUT' ||\n tagName === 'TEXTAREA' ||\n tagName === 'SELECT' ||\n target.isContentEditable\n ) {\n return;\n }\n }\n\n // Check modifiers\n const { ctrl, shift, alt, meta } = modifiers;\n\n // For Cmd+K style shortcuts, allow either meta (Mac) or ctrl (Windows/Linux)\n const metaOrCtrl = meta || ctrl;\n if (metaOrCtrl) {\n if (!(event.metaKey || event.ctrlKey)) return;\n } else {\n // If no meta/ctrl modifier specified, ensure neither is pressed\n if (event.metaKey || event.ctrlKey) return;\n }\n\n if (shift && !event.shiftKey) return;\n if (alt && !event.altKey) return;\n\n // Check key match (case-insensitive for letters)\n const eventKey =\n event.key.length === 1 ? event.key.toLowerCase() : event.key;\n const targetKey = key.length === 1 ? key.toLowerCase() : key;\n if (eventKey !== targetKey) return;\n\n if (preventDefault) {\n event.preventDefault();\n }\n if (stopPropagation) {\n event.stopPropagation();\n }\n\n callback(event);\n },\n [key, callback, modifiers, preventDefault, stopPropagation, ignoreInputs]\n );\n\n useEffect(() => {\n if (!enabled) return;\n\n document.addEventListener('keydown', handleKeyDown);\n return () => document.removeEventListener('keydown', handleKeyDown);\n }, [handleKeyDown, enabled]);\n}\n\n/**\n * Hook for the common Cmd/Ctrl+K shortcut pattern (command palette, search, etc.)\n *\n * @param callback - Function to call when Cmd/Ctrl+K is pressed\n * @param enabled - Whether the shortcut is active (default: true)\n *\n * @example\n * ```tsx\n * useCommandK(() => setIsOpen(true));\n * ```\n */\nexport function useCommandK(callback: () => void, enabled = true): void {\n useKeyboardShortcut('k', callback, {\n enabled,\n modifiers: { meta: true, ctrl: true },\n ignoreInputs: false, // Cmd+K should work even in inputs\n });\n}\n","import { useState, useEffect } from 'react';\n\n/**\n * Hook that tracks whether a media query matches.\n * Uses the native `matchMedia` API for efficient media query tracking.\n *\n * @param query - CSS media query string (e.g., '(min-width: 768px)')\n * @returns Boolean indicating whether the media query matches\n *\n * @example\n * ```tsx\n * function ResponsiveComponent() {\n * const isMobile = useMediaQuery('(max-width: 767px)');\n * const isTablet = useMediaQuery('(min-width: 768px) and (max-width: 1023px)');\n * const isDesktop = useMediaQuery('(min-width: 1024px)');\n *\n * return (\n * <div>\n * {isMobile && <MobileLayout />}\n * {isTablet && <TabletLayout />}\n * {isDesktop && <DesktopLayout />}\n * </div>\n * );\n * }\n * ```\n */\nexport function useMediaQuery(query: string): boolean {\n // Initialize with null to indicate SSR/initial state\n const [matches, setMatches] = useState<boolean>(() => {\n // Check if we're in a browser environment\n if (typeof window === 'undefined') return false;\n return window.matchMedia(query).matches;\n });\n\n useEffect(() => {\n if (typeof window === 'undefined') return;\n\n const mediaQuery = window.matchMedia(query);\n\n // Set initial value\n setMatches(mediaQuery.matches);\n\n // Handler for media query changes\n const handler = (event: MediaQueryListEvent) => {\n setMatches(event.matches);\n };\n\n // Modern browsers use addEventListener\n if (mediaQuery.addEventListener) {\n mediaQuery.addEventListener('change', handler);\n return () => mediaQuery.removeEventListener('change', handler);\n }\n\n // Fallback for older browsers\n mediaQuery.addListener(handler);\n return () => mediaQuery.removeListener(handler);\n }, [query]);\n\n return matches;\n}\n\n/**\n * Preset breakpoint hooks following common responsive design patterns\n */\n\n/** Returns true when viewport is smaller than 640px (mobile) */\nexport function useIsMobile(): boolean {\n return useMediaQuery('(max-width: 639px)');\n}\n\n/** Returns true when viewport is 640px-767px (large mobile / small tablet) */\nexport function useIsSmallTablet(): boolean {\n return useMediaQuery('(min-width: 640px) and (max-width: 767px)');\n}\n\n/** Returns true when viewport is 768px-1023px (tablet) */\nexport function useIsTablet(): boolean {\n return useMediaQuery('(min-width: 768px) and (max-width: 1023px)');\n}\n\n/** Returns true when viewport is 1024px or larger (desktop) */\nexport function useIsDesktop(): boolean {\n return useMediaQuery('(min-width: 1024px)');\n}\n\n/** Returns true when viewport is 1280px or larger (large desktop) */\nexport function useIsLargeDesktop(): boolean {\n return useMediaQuery('(min-width: 1280px)');\n}\n\n/** Returns true when viewport is smaller than 1024px (mobile/tablet) */\nexport function useIsMobileOrTablet(): boolean {\n return useMediaQuery('(max-width: 1023px)');\n}\n","import { useEffect, useState, useRef, type RefObject } from 'react';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface UseScrollSpyOptions {\n /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */\n selectors?: string;\n /** Explicit list of element IDs to observe (alternative to selectors) */\n ids?: string[];\n /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */\n rootMargin?: string;\n /** IntersectionObserver threshold (default: 0) */\n threshold?: number | number[];\n /** Scroll container element ref. Defaults to document viewport. */\n root?: RefObject<HTMLElement | null>;\n /** Whether the hook is active (default: true) */\n enabled?: boolean;\n}\n\nexport interface UseScrollSpyReturn {\n /** The ID of the currently active (in-view) element */\n activeId: string | null;\n}\n\n// =============================================================================\n// Hook\n// =============================================================================\n\n/**\n * Tracks which section is currently in the viewport using IntersectionObserver.\n * Pairs naturally with `TableOfContents` to highlight the active heading.\n *\n * @example\n * ```tsx\n * function DocsPage() {\n * const { activeId } = useScrollSpy({ selectors: 'h2, h3' });\n * return (\n * <aside>\n * <TableOfContents activeId={activeId} />\n * </aside>\n * );\n * }\n * ```\n */\nexport function useScrollSpy({\n selectors,\n ids,\n rootMargin = '0px 0px -60% 0px',\n threshold = 0,\n root,\n enabled = true,\n}: UseScrollSpyOptions = {}): UseScrollSpyReturn {\n const [activeId, setActiveId] = useState<string | null>(null);\n const visibleEntries = useRef<Map<string, IntersectionObserverEntry>>(\n new Map()\n );\n\n // Track root.current so the effect re-runs when the ref attaches\n const rootEl = root?.current ?? null;\n\n useEffect(() => {\n if (!enabled) return;\n\n const container = rootEl ?? document;\n\n // Resolve target elements from the DOM\n function resolveElements(): Element[] {\n let els: Element[] = [];\n if (ids && ids.length > 0) {\n els = ids\n .map((id) => document.getElementById(id))\n .filter((el): el is HTMLElement => el !== null);\n } else if (selectors) {\n els = Array.from(container.querySelectorAll(selectors));\n }\n return els.filter((el) => el.id);\n }\n\n let intersectionObserver: IntersectionObserver | null = null;\n let mutationObserver: MutationObserver | null = null;\n\n function startObserving(): boolean {\n const elements = resolveElements();\n if (elements.length === 0) return false;\n\n intersectionObserver = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (entry.isIntersecting) {\n visibleEntries.current.set(entry.target.id, entry);\n } else {\n visibleEntries.current.delete(entry.target.id);\n }\n }\n\n // Pick the topmost visible heading (by DOM order)\n if (visibleEntries.current.size > 0) {\n let topmost: string | null = null;\n let topmostTop = Infinity;\n\n for (const [id, entry] of visibleEntries.current) {\n const top = entry.boundingClientRect.top;\n if (top < topmostTop) {\n topmostTop = top;\n topmost = id;\n }\n }\n\n if (topmost) {\n setActiveId(topmost);\n }\n }\n },\n {\n root: rootEl,\n rootMargin,\n threshold,\n }\n );\n\n for (const el of elements) {\n intersectionObserver.observe(el);\n }\n\n // Elements found — stop watching for new DOM nodes\n mutationObserver?.disconnect();\n mutationObserver = null;\n return true;\n }\n\n // If target elements don't exist yet (e.g. headings mount after ToC),\n // watch for DOM changes and retry until they appear.\n if (!startObserving()) {\n const watchRoot = rootEl ?? document.body;\n mutationObserver = new MutationObserver(() => {\n startObserving();\n });\n mutationObserver.observe(watchRoot, { childList: true, subtree: true });\n }\n\n const entries = visibleEntries.current;\n return () => {\n mutationObserver?.disconnect();\n intersectionObserver?.disconnect();\n entries.clear();\n };\n }, [selectors, ids, rootMargin, threshold, rootEl, enabled]);\n\n return { activeId };\n}\n"]}
package/dist/{chunk-CP7NPDQW.js → chunk-Q7NBJFEB.js} RENAMED
@@ -1,4 +1,4 @@
1
- import { useCallback, useEffect, useState } from 'react';
1
+ import { useCallback, useEffect, useState, useRef } from 'react';
2
2
 
3
3
  // src/hooks/useKeyboardShortcut.ts
4
4
  function useKeyboardShortcut(key, callback, options = {}) {
@@ -93,7 +93,90 @@ function useIsLargeDesktop() {
93
93
  function useIsMobileOrTablet() {
94
94
  return useMediaQuery("(max-width: 1023px)");
95
95
  }
96
+ function useScrollSpy({
97
+ selectors,
98
+ ids,
99
+ rootMargin = "0px 0px -60% 0px",
100
+ threshold = 0,
101
+ root,
102
+ enabled = true
103
+ } = {}) {
104
+ const [activeId, setActiveId] = useState(null);
105
+ const visibleEntries = useRef(
106
+ /* @__PURE__ */ new Map()
107
+ );
108
+ const rootEl = root?.current ?? null;
109
+ useEffect(() => {
110
+ if (!enabled) return;
111
+ const container = rootEl ?? document;
112
+ function resolveElements() {
113
+ let els = [];
114
+ if (ids && ids.length > 0) {
115
+ els = ids.map((id) => document.getElementById(id)).filter((el) => el !== null);
116
+ } else if (selectors) {
117
+ els = Array.from(container.querySelectorAll(selectors));
118
+ }
119
+ return els.filter((el) => el.id);
120
+ }
121
+ let intersectionObserver = null;
122
+ let mutationObserver = null;
123
+ function startObserving() {
124
+ const elements = resolveElements();
125
+ if (elements.length === 0) return false;
126
+ intersectionObserver = new IntersectionObserver(
127
+ (entries2) => {
128
+ for (const entry of entries2) {
129
+ if (entry.isIntersecting) {
130
+ visibleEntries.current.set(entry.target.id, entry);
131
+ } else {
132
+ visibleEntries.current.delete(entry.target.id);
133
+ }
134
+ }
135
+ if (visibleEntries.current.size > 0) {
136
+ let topmost = null;
137
+ let topmostTop = Infinity;
138
+ for (const [id, entry] of visibleEntries.current) {
139
+ const top = entry.boundingClientRect.top;
140
+ if (top < topmostTop) {
141
+ topmostTop = top;
142
+ topmost = id;
143
+ }
144
+ }
145
+ if (topmost) {
146
+ setActiveId(topmost);
147
+ }
148
+ }
149
+ },
150
+ {
151
+ root: rootEl,
152
+ rootMargin,
153
+ threshold
154
+ }
155
+ );
156
+ for (const el of elements) {
157
+ intersectionObserver.observe(el);
158
+ }
159
+ mutationObserver?.disconnect();
160
+ mutationObserver = null;
161
+ return true;
162
+ }
163
+ if (!startObserving()) {
164
+ const watchRoot = rootEl ?? document.body;
165
+ mutationObserver = new MutationObserver(() => {
166
+ startObserving();
167
+ });
168
+ mutationObserver.observe(watchRoot, { childList: true, subtree: true });
169
+ }
170
+ const entries = visibleEntries.current;
171
+ return () => {
172
+ mutationObserver?.disconnect();
173
+ intersectionObserver?.disconnect();
174
+ entries.clear();
175
+ };
176
+ }, [selectors, ids, rootMargin, threshold, rootEl, enabled]);
177
+ return { activeId };
178
+ }
96
179
 
97
- export { useCommandK, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery };
98
- //# sourceMappingURL=chunk-CP7NPDQW.js.map
99
- //# sourceMappingURL=chunk-CP7NPDQW.js.map
180
+ export { useCommandK, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, useScrollSpy };
181
+ //# sourceMappingURL=chunk-Q7NBJFEB.js.map
182
+ //# sourceMappingURL=chunk-Q7NBJFEB.js.map
package/dist/chunk-Q7NBJFEB.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/hooks/useKeyboardShortcut.ts","../src/hooks/useMediaQuery.ts","../src/hooks/useScrollSpy.ts"],"names":["useEffect","useState","entries"],"mappings":"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","file":"chunk-Q7NBJFEB.js","sourcesContent":["import { useEffect, useCallback } from 'react';\n\n/**\n * Options for keyboard shortcut hook\n */\nexport interface KeyboardShortcutOptions {\n /** Whether the shortcut is currently enabled (default: true) */\n enabled?: boolean;\n /** Modifier keys required (default: none) */\n modifiers?: {\n ctrl?: boolean;\n shift?: boolean;\n alt?: boolean;\n meta?: boolean;\n };\n /** Whether to prevent default browser behavior (default: true) */\n preventDefault?: boolean;\n /** Whether to stop event propagation (default: false) */\n stopPropagation?: boolean;\n /** Element types to ignore when the shortcut is pressed (default: ['INPUT', 'TEXTAREA', 'SELECT']) */\n ignoreInputs?: boolean;\n}\n\n/**\n * Hook that triggers a callback when a specific keyboard shortcut is pressed.\n * Supports modifier keys (Ctrl, Shift, Alt, Meta) and ignores input fields by default.\n *\n * @param key - The key to listen for (e.g., 'k', 'Enter', 'Escape', '/')\n * @param callback - Function to call when the shortcut is pressed\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Cmd/Ctrl+K to open search\n * useKeyboardShortcut('k', openSearch, { modifiers: { meta: true, ctrl: true } });\n *\n * // Forward slash to focus search (ignoring when typing)\n * useKeyboardShortcut('/', focusSearch);\n *\n * // Escape to close modal\n * useKeyboardShortcut('Escape', closeModal);\n * ```\n */\nexport function useKeyboardShortcut(\n key: string,\n callback: (event: KeyboardEvent) => void,\n options: KeyboardShortcutOptions = {}\n): void {\n const {\n enabled = true,\n modifiers = {},\n preventDefault = true,\n stopPropagation = false,\n ignoreInputs = true,\n } = options;\n\n const handleKeyDown = useCallback(\n (event: KeyboardEvent) => {\n // Check if we should ignore input fields\n if (ignoreInputs) {\n const target = event.target as HTMLElement;\n const tagName = target.tagName.toUpperCase();\n if (\n tagName === 'INPUT' ||\n tagName === 'TEXTAREA' ||\n tagName === 'SELECT' ||\n target.isContentEditable\n ) {\n return;\n }\n }\n\n // Check modifiers\n const { ctrl, shift, alt, meta } = modifiers;\n\n // For Cmd+K style shortcuts, allow either meta (Mac) or ctrl (Windows/Linux)\n const metaOrCtrl = meta || ctrl;\n if (metaOrCtrl) {\n if (!(event.metaKey || event.ctrlKey)) return;\n } else {\n // If no meta/ctrl modifier specified, ensure neither is pressed\n if (event.metaKey || event.ctrlKey) return;\n }\n\n if (shift && !event.shiftKey) return;\n if (alt && !event.altKey) return;\n\n // Check key match (case-insensitive for letters)\n const eventKey =\n event.key.length === 1 ? event.key.toLowerCase() : event.key;\n const targetKey = key.length === 1 ? key.toLowerCase() : key;\n if (eventKey !== targetKey) return;\n\n if (preventDefault) {\n event.preventDefault();\n }\n if (stopPropagation) {\n event.stopPropagation();\n }\n\n callback(event);\n },\n [key, callback, modifiers, preventDefault, stopPropagation, ignoreInputs]\n );\n\n useEffect(() => {\n if (!enabled) return;\n\n document.addEventListener('keydown', handleKeyDown);\n return () => document.removeEventListener('keydown', handleKeyDown);\n }, [handleKeyDown, enabled]);\n}\n\n/**\n * Hook for the common Cmd/Ctrl+K shortcut pattern (command palette, search, etc.)\n *\n * @param callback - Function to call when Cmd/Ctrl+K is pressed\n * @param enabled - Whether the shortcut is active (default: true)\n *\n * @example\n * ```tsx\n * useCommandK(() => setIsOpen(true));\n * ```\n */\nexport function useCommandK(callback: () => void, enabled = true): void {\n useKeyboardShortcut('k', callback, {\n enabled,\n modifiers: { meta: true, ctrl: true },\n ignoreInputs: false, // Cmd+K should work even in inputs\n });\n}\n","import { useState, useEffect } from 'react';\n\n/**\n * Hook that tracks whether a media query matches.\n * Uses the native `matchMedia` API for efficient media query tracking.\n *\n * @param query - CSS media query string (e.g., '(min-width: 768px)')\n * @returns Boolean indicating whether the media query matches\n *\n * @example\n * ```tsx\n * function ResponsiveComponent() {\n * const isMobile = useMediaQuery('(max-width: 767px)');\n * const isTablet = useMediaQuery('(min-width: 768px) and (max-width: 1023px)');\n * const isDesktop = useMediaQuery('(min-width: 1024px)');\n *\n * return (\n * <div>\n * {isMobile && <MobileLayout />}\n * {isTablet && <TabletLayout />}\n * {isDesktop && <DesktopLayout />}\n * </div>\n * );\n * }\n * ```\n */\nexport function useMediaQuery(query: string): boolean {\n // Initialize with null to indicate SSR/initial state\n const [matches, setMatches] = useState<boolean>(() => {\n // Check if we're in a browser environment\n if (typeof window === 'undefined') return false;\n return window.matchMedia(query).matches;\n });\n\n useEffect(() => {\n if (typeof window === 'undefined') return;\n\n const mediaQuery = window.matchMedia(query);\n\n // Set initial value\n setMatches(mediaQuery.matches);\n\n // Handler for media query changes\n const handler = (event: MediaQueryListEvent) => {\n setMatches(event.matches);\n };\n\n // Modern browsers use addEventListener\n if (mediaQuery.addEventListener) {\n mediaQuery.addEventListener('change', handler);\n return () => mediaQuery.removeEventListener('change', handler);\n }\n\n // Fallback for older browsers\n mediaQuery.addListener(handler);\n return () => mediaQuery.removeListener(handler);\n }, [query]);\n\n return matches;\n}\n\n/**\n * Preset breakpoint hooks following common responsive design patterns\n */\n\n/** Returns true when viewport is smaller than 640px (mobile) */\nexport function useIsMobile(): boolean {\n return useMediaQuery('(max-width: 639px)');\n}\n\n/** Returns true when viewport is 640px-767px (large mobile / small tablet) */\nexport function useIsSmallTablet(): boolean {\n return useMediaQuery('(min-width: 640px) and (max-width: 767px)');\n}\n\n/** Returns true when viewport is 768px-1023px (tablet) */\nexport function useIsTablet(): boolean {\n return useMediaQuery('(min-width: 768px) and (max-width: 1023px)');\n}\n\n/** Returns true when viewport is 1024px or larger (desktop) */\nexport function useIsDesktop(): boolean {\n return useMediaQuery('(min-width: 1024px)');\n}\n\n/** Returns true when viewport is 1280px or larger (large desktop) */\nexport function useIsLargeDesktop(): boolean {\n return useMediaQuery('(min-width: 1280px)');\n}\n\n/** Returns true when viewport is smaller than 1024px (mobile/tablet) */\nexport function useIsMobileOrTablet(): boolean {\n return useMediaQuery('(max-width: 1023px)');\n}\n","import { useEffect, useState, useRef, type RefObject } from 'react';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface UseScrollSpyOptions {\n /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */\n selectors?: string;\n /** Explicit list of element IDs to observe (alternative to selectors) */\n ids?: string[];\n /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */\n rootMargin?: string;\n /** IntersectionObserver threshold (default: 0) */\n threshold?: number | number[];\n /** Scroll container element ref. Defaults to document viewport. */\n root?: RefObject<HTMLElement | null>;\n /** Whether the hook is active (default: true) */\n enabled?: boolean;\n}\n\nexport interface UseScrollSpyReturn {\n /** The ID of the currently active (in-view) element */\n activeId: string | null;\n}\n\n// =============================================================================\n// Hook\n// =============================================================================\n\n/**\n * Tracks which section is currently in the viewport using IntersectionObserver.\n * Pairs naturally with `TableOfContents` to highlight the active heading.\n *\n * @example\n * ```tsx\n * function DocsPage() {\n * const { activeId } = useScrollSpy({ selectors: 'h2, h3' });\n * return (\n * <aside>\n * <TableOfContents activeId={activeId} />\n * </aside>\n * );\n * }\n * ```\n */\nexport function useScrollSpy({\n selectors,\n ids,\n rootMargin = '0px 0px -60% 0px',\n threshold = 0,\n root,\n enabled = true,\n}: UseScrollSpyOptions = {}): UseScrollSpyReturn {\n const [activeId, setActiveId] = useState<string | null>(null);\n const visibleEntries = useRef<Map<string, IntersectionObserverEntry>>(\n new Map()\n );\n\n // Track root.current so the effect re-runs when the ref attaches\n const rootEl = root?.current ?? null;\n\n useEffect(() => {\n if (!enabled) return;\n\n const container = rootEl ?? document;\n\n // Resolve target elements from the DOM\n function resolveElements(): Element[] {\n let els: Element[] = [];\n if (ids && ids.length > 0) {\n els = ids\n .map((id) => document.getElementById(id))\n .filter((el): el is HTMLElement => el !== null);\n } else if (selectors) {\n els = Array.from(container.querySelectorAll(selectors));\n }\n return els.filter((el) => el.id);\n }\n\n let intersectionObserver: IntersectionObserver | null = null;\n let mutationObserver: MutationObserver | null = null;\n\n function startObserving(): boolean {\n const elements = resolveElements();\n if (elements.length === 0) return false;\n\n intersectionObserver = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (entry.isIntersecting) {\n visibleEntries.current.set(entry.target.id, entry);\n } else {\n visibleEntries.current.delete(entry.target.id);\n }\n }\n\n // Pick the topmost visible heading (by DOM order)\n if (visibleEntries.current.size > 0) {\n let topmost: string | null = null;\n let topmostTop = Infinity;\n\n for (const [id, entry] of visibleEntries.current) {\n const top = entry.boundingClientRect.top;\n if (top < topmostTop) {\n topmostTop = top;\n topmost = id;\n }\n }\n\n if (topmost) {\n setActiveId(topmost);\n }\n }\n },\n {\n root: rootEl,\n rootMargin,\n threshold,\n }\n );\n\n for (const el of elements) {\n intersectionObserver.observe(el);\n }\n\n // Elements found — stop watching for new DOM nodes\n mutationObserver?.disconnect();\n mutationObserver = null;\n return true;\n }\n\n // If target elements don't exist yet (e.g. headings mount after ToC),\n // watch for DOM changes and retry until they appear.\n if (!startObserving()) {\n const watchRoot = rootEl ?? document.body;\n mutationObserver = new MutationObserver(() => {\n startObserving();\n });\n mutationObserver.observe(watchRoot, { childList: true, subtree: true });\n }\n\n const entries = visibleEntries.current;\n return () => {\n mutationObserver?.disconnect();\n intersectionObserver?.disconnect();\n entries.clear();\n };\n }, [selectors, ids, rootMargin, threshold, rootEl, enabled]);\n\n return { activeId };\n}\n"]}
package/dist/hooks/index.cjs CHANGED
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- var chunkR4DM4635_cjs = require('../chunk-R4DM4635.cjs');
3
+ var chunkFSBFQBNE_cjs = require('../chunk-FSBFQBNE.cjs');
4
4
  var chunk2O7D6F67_cjs = require('../chunk-2O7D6F67.cjs');
5
5
  var chunk6HFFWEM3_cjs = require('../chunk-6HFFWEM3.cjs');
6
6
  var chunkNNEFAUHV_cjs = require('../chunk-NNEFAUHV.cjs');
@@ -12,39 +12,43 @@ require('../chunk-SCV7C55E.cjs');
12
12
 
13
13
  Object.defineProperty(exports, "useCommandK", {
14
14
  enumerable: true,
15
- get: function () { return chunkR4DM4635_cjs.useCommandK; }
15
+ get: function () { return chunkFSBFQBNE_cjs.useCommandK; }
16
16
  });
17
17
  Object.defineProperty(exports, "useIsDesktop", {
18
18
  enumerable: true,
19
- get: function () { return chunkR4DM4635_cjs.useIsDesktop; }
19
+ get: function () { return chunkFSBFQBNE_cjs.useIsDesktop; }
20
20
  });
21
21
  Object.defineProperty(exports, "useIsLargeDesktop", {
22
22
  enumerable: true,
23
- get: function () { return chunkR4DM4635_cjs.useIsLargeDesktop; }
23
+ get: function () { return chunkFSBFQBNE_cjs.useIsLargeDesktop; }
24
24
  });
25
25
  Object.defineProperty(exports, "useIsMobile", {
26
26
  enumerable: true,
27
- get: function () { return chunkR4DM4635_cjs.useIsMobile; }
27
+ get: function () { return chunkFSBFQBNE_cjs.useIsMobile; }
28
28
  });
29
29
  Object.defineProperty(exports, "useIsMobileOrTablet", {
30
30
  enumerable: true,
31
- get: function () { return chunkR4DM4635_cjs.useIsMobileOrTablet; }
31
+ get: function () { return chunkFSBFQBNE_cjs.useIsMobileOrTablet; }
32
32
  });
33
33
  Object.defineProperty(exports, "useIsSmallTablet", {
34
34
  enumerable: true,
35
- get: function () { return chunkR4DM4635_cjs.useIsSmallTablet; }
35
+ get: function () { return chunkFSBFQBNE_cjs.useIsSmallTablet; }
36
36
  });
37
37
  Object.defineProperty(exports, "useIsTablet", {
38
38
  enumerable: true,
39
- get: function () { return chunkR4DM4635_cjs.useIsTablet; }
39
+ get: function () { return chunkFSBFQBNE_cjs.useIsTablet; }
40
40
  });
41
41
  Object.defineProperty(exports, "useKeyboardShortcut", {
42
42
  enumerable: true,
43
- get: function () { return chunkR4DM4635_cjs.useKeyboardShortcut; }
43
+ get: function () { return chunkFSBFQBNE_cjs.useKeyboardShortcut; }
44
44
  });
45
45
  Object.defineProperty(exports, "useMediaQuery", {
46
46
  enumerable: true,
47
- get: function () { return chunkR4DM4635_cjs.useMediaQuery; }
47
+ get: function () { return chunkFSBFQBNE_cjs.useMediaQuery; }
48
+ });
49
+ Object.defineProperty(exports, "useScrollSpy", {
50
+ enumerable: true,
51
+ get: function () { return chunkFSBFQBNE_cjs.useScrollSpy; }
48
52
  });
49
53
  Object.defineProperty(exports, "useTheme", {
50
54
  enumerable: true,
package/dist/hooks/index.d.cts CHANGED
@@ -1,6 +1,42 @@
1
1
  export { R as ResolvedTheme, T as Theme, u as useTheme } from '../useTheme-B9SWu6ui.cjs';
2
2
  import { RefObject } from 'react';
3
3
 
4
+ interface UseScrollSpyOptions {
5
+ /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
6
+ selectors?: string;
7
+ /** Explicit list of element IDs to observe (alternative to selectors) */
8
+ ids?: string[];
9
+ /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
10
+ rootMargin?: string;
11
+ /** IntersectionObserver threshold (default: 0) */
12
+ threshold?: number | number[];
13
+ /** Scroll container element ref. Defaults to document viewport. */
14
+ root?: RefObject<HTMLElement | null>;
15
+ /** Whether the hook is active (default: true) */
16
+ enabled?: boolean;
17
+ }
18
+ interface UseScrollSpyReturn {
19
+ /** The ID of the currently active (in-view) element */
20
+ activeId: string | null;
21
+ }
22
+ /**
23
+ * Tracks which section is currently in the viewport using IntersectionObserver.
24
+ * Pairs naturally with `TableOfContents` to highlight the active heading.
25
+ *
26
+ * @example
27
+ * ```tsx
28
+ * function DocsPage() {
29
+ * const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
30
+ * return (
31
+ * <aside>
32
+ * <TableOfContents activeId={activeId} />
33
+ * </aside>
34
+ * );
35
+ * }
36
+ * ```
37
+ */
38
+ declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
39
+
4
40
  /**
5
41
  * Hook that detects if the user prefers reduced motion.
6
42
  * Useful for disabling animations for accessibility.
@@ -176,4 +212,4 @@ declare function useIsLargeDesktop(): boolean;
176
212
  /** Returns true when viewport is smaller than 1024px (mobile/tablet) */
177
213
  declare function useIsMobileOrTablet(): boolean;
178
214
 
179
- export { type KeyboardShortcutOptions, useClickOutside, useCommandK, useEscapeKey, useFocusTrap, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, usePrefersReducedMotion };
215
+ export { type KeyboardShortcutOptions, type UseScrollSpyOptions, type UseScrollSpyReturn, useClickOutside, useCommandK, useEscapeKey, useFocusTrap, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, usePrefersReducedMotion, useScrollSpy };
package/dist/hooks/index.d.ts CHANGED
@@ -1,6 +1,42 @@
1
1
  export { R as ResolvedTheme, T as Theme, u as useTheme } from '../useTheme-B9SWu6ui.js';
2
2
  import { RefObject } from 'react';
3
3
 
4
+ interface UseScrollSpyOptions {
5
+ /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
6
+ selectors?: string;
7
+ /** Explicit list of element IDs to observe (alternative to selectors) */
8
+ ids?: string[];
9
+ /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
10
+ rootMargin?: string;
11
+ /** IntersectionObserver threshold (default: 0) */
12
+ threshold?: number | number[];
13
+ /** Scroll container element ref. Defaults to document viewport. */
14
+ root?: RefObject<HTMLElement | null>;
15
+ /** Whether the hook is active (default: true) */
16
+ enabled?: boolean;
17
+ }
18
+ interface UseScrollSpyReturn {
19
+ /** The ID of the currently active (in-view) element */
20
+ activeId: string | null;
21
+ }
22
+ /**
23
+ * Tracks which section is currently in the viewport using IntersectionObserver.
24
+ * Pairs naturally with `TableOfContents` to highlight the active heading.
25
+ *
26
+ * @example
27
+ * ```tsx
28
+ * function DocsPage() {
29
+ * const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
30
+ * return (
31
+ * <aside>
32
+ * <TableOfContents activeId={activeId} />
33
+ * </aside>
34
+ * );
35
+ * }
36
+ * ```
37
+ */
38
+ declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
39
+
4
40
  /**
5
41
  * Hook that detects if the user prefers reduced motion.
6
42
  * Useful for disabling animations for accessibility.
@@ -176,4 +212,4 @@ declare function useIsLargeDesktop(): boolean;
176
212
  /** Returns true when viewport is smaller than 1024px (mobile/tablet) */
177
213
  declare function useIsMobileOrTablet(): boolean;
178
214
 
179
- export { type KeyboardShortcutOptions, useClickOutside, useCommandK, useEscapeKey, useFocusTrap, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, usePrefersReducedMotion };
215
+ export { type KeyboardShortcutOptions, type UseScrollSpyOptions, type UseScrollSpyReturn, useClickOutside, useCommandK, useEscapeKey, useFocusTrap, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, usePrefersReducedMotion, useScrollSpy };
package/dist/hooks/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export { useCommandK, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery } from '../chunk-CP7NPDQW.js';
1
+ export { useCommandK, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery, useScrollSpy } from '../chunk-Q7NBJFEB.js';
2
2
  export { useTheme } from '../chunk-KJZNEVYM.js';
3
3
  export { usePrefersReducedMotion } from '../chunk-HB7C7NB5.js';
4
4
  export { useFocusTrap } from '../chunk-4SMSH4OY.js';