domet 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 blksmr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# domet
+
+domet is a lightweight scroll spy hook for React. Track which section is in view, highlight nav items, and build smooth scrolling experiences.
+
+Uses `requestAnimationFrame` with throttling for 60fps performance. Hysteresis prevents jittery switching near section boundaries.
+
+For the source code, check out the [GitHub](https://github.com/blksmr/domet).
+
+## Installation
+
+```bash
+npm install domet
+```
+
+## Quick Start
+
+```tsx
+import { useDomet } from 'domet'
+
+const sections = ['intro', 'features', 'api']
+
+function Page() {
+  const { activeId, sectionProps, navProps } = useDomet(sections)
+
+  return (
+    <>
+      <nav>
+        {sections.map(id => (
+          <button key={id} {...navProps(id)}>
+            {id}
+          </button>
+        ))}
+      </nav>
+
+      <section {...sectionProps('intro')}>...</section>
+      <section {...sectionProps('features')}>...</section>
+      <section {...sectionProps('api')}>...</section>
+    </>
+  )
+}
+```
+
+## API Reference
+
+### Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `sectionIds` | `string[]` | Array of section IDs to track |
+| `containerRef` | `RefObject<HTMLElement> \| null` | Scrollable container (defaults to `window`) |
+| `options` | `DometOptions` | Configuration options |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `offset` | `number` | `0` | Trigger offset from top in pixels |
+| `offsetRatio` | `number` | `0.08` | Viewport ratio for trigger line calculation |
+| `debounceMs` | `number` | `10` | Throttle delay in milliseconds |
+| `visibilityThreshold` | `number` | `0.6` | Minimum visibility ratio (0-1) for section to get priority |
+| `hysteresisMargin` | `number` | `150` | Score margin to prevent rapid section switching |
+| `behavior` | `'smooth' \| 'instant' \| 'auto'` | `'auto'` | Scroll behavior. `'auto'` respects `prefers-reduced-motion` |
+
+### Callbacks
+
+| Callback | Type | Description |
+|----------|------|-------------|
+| `onActiveChange` | `(id: string \| null, prevId: string \| null) => void` | Called when active section changes |
+| `onSectionEnter` | `(id: string) => void` | Called when a section enters the viewport |
+| `onSectionLeave` | `(id: string) => void` | Called when a section leaves the viewport |
+| `onScrollStart` | `() => void` | Called when scrolling starts |
+| `onScrollEnd` | `() => void` | Called when scrolling stops |
+
+### Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `activeId` | `string \| null` | ID of the currently active section |
+| `activeIndex` | `number` | Index of the active section in `sectionIds` (-1 if none) |
+| `scroll` | `ScrollState` | Global scroll state |
+| `sections` | `Record<string, SectionState>` | Per-section state indexed by ID |
+| `sectionProps` | `(id: string) => SectionProps` | Props to spread on section elements |
+| `navProps` | `(id: string) => NavProps` | Props to spread on nav items |
+| `registerRef` | `(id: string) => (el: HTMLElement \| null) => void` | Manual ref registration |
+| `scrollToSection` | `(id: string) => void` | Programmatically scroll to a section |
+
+## Types
+
+### ScrollState
+
+Global scroll information updated on every scroll event.
+
+```ts
+type ScrollState = {
+  y: number                        // Current scroll position in pixels
+  progress: number                 // Overall scroll progress (0-1)
+  direction: 'up' | 'down' | null  // Scroll direction
+  velocity: number                 // Scroll speed
+  isScrolling: boolean             // True while actively scrolling
+  maxScroll: number                // Maximum scroll value
+  viewportHeight: number           // Viewport height in pixels
+  offset: number                   // Effective trigger offset
+}
+```
+
+### SectionState
+
+Per-section state available for each tracked section.
+
+```ts
+type SectionState = {
+  bounds: SectionBounds  // Position and dimensions
+  visibility: number     // Visibility ratio (0-1)
+  progress: number       // Section scroll progress (0-1)
+  isInViewport: boolean  // True if any part is visible
+  isActive: boolean      // True if this is the active section
+}
+
+type SectionBounds = {
+  top: number
+  bottom: number
+  height: number
+}
+```
+
+## Examples
+
+### With Callbacks
+
+```tsx
+const { activeId } = useDomet(sections, null, {
+  onActiveChange: (id, prevId) => {
+    console.log(`Changed from ${prevId} to ${id}`)
+  },
+  onSectionEnter: (id) => {
+    console.log(`Entered: ${id}`)
+  },
+})
+```
+
+### Using Scroll State
+
+```tsx
+const { scroll, sections } = useDomet(sectionIds)
+
+// Global progress bar
+<div style={{ width: `${scroll.progress * 100}%` }} />
+
+// Per-section animations
+{sectionIds.map(id => (
+  <div style={{ opacity: sections[id]?.visibility }} />
+))}
+```
+
+### Custom Container
+
+```tsx
+const containerRef = useRef<HTMLDivElement>(null)
+const { activeId } = useDomet(sections, containerRef)
+
+return (
+  <div ref={containerRef} style={{ overflow: 'auto', height: '100vh' }}>
+    {/* sections */}
+  </div>
+)
+```
+
+### Fine-tuning Behavior
+
+```tsx
+useDomet(sections, null, {
+  visibilityThreshold: 0.8,  // Require 80% visibility
+  hysteresisMargin: 200,     // More resistance to switching
+})
+```
+
+## Why domet?
+
+This library was born from a real need at work. I wanted a scroll-spy solution that was powerful and completely headless, but above all, extremely lightweight. No bloated dependencies, no opinionated styling, just a hook that does one thing well.
+
+The name **domet** comes from Bosnian/Serbian/Croatian and means "reach" or "range" — the distance something can cover. Pronounced `/ˈdɔ.met/`: stress on the first syllable, open "o", and a hard "t" at the end.
+
+## Support
+
+For issues or feature requests, open an issue on [GitHub](https://github.com/blksmr/domet).
+
+You can also reach out to me on [Twitter](https://x.com/blkasmir).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { DometOptions, NavProps, ScrollBehavior, ScrollState, SectionBounds, SectionProps, SectionState, UseDometReturn, } from "./useDomet";
+export { default, useDomet } from "./useDomet";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { default, useDomet } from "./useDomet";

package/dist/useDomet.d.ts

@@ -0,0 +1,60 @@
+import type { RefObject } from "react";
+export type SectionBounds = {
+    top: number;
+    bottom: number;
+    height: number;
+};
+export type ScrollState = {
+    y: number;
+    progress: number;
+    direction: "up" | "down" | null;
+    velocity: number;
+    isScrolling: boolean;
+    maxScroll: number;
+    viewportHeight: number;
+    offset: number;
+};
+export type SectionState = {
+    bounds: SectionBounds;
+    visibility: number;
+    progress: number;
+    isInViewport: boolean;
+    isActive: boolean;
+};
+export type ScrollBehavior = "smooth" | "instant" | "auto";
+export type DometOptions = {
+    offset?: number;
+    offsetRatio?: number;
+    debounceMs?: number;
+    visibilityThreshold?: number;
+    hysteresisMargin?: number;
+    behavior?: ScrollBehavior;
+    onActiveChange?: (id: string | null, prevId: string | null) => void;
+    onSectionEnter?: (id: string) => void;
+    onSectionLeave?: (id: string) => void;
+    onScrollStart?: () => void;
+    onScrollEnd?: () => void;
+};
+export type SectionProps = {
+    id: string;
+    ref: (el: HTMLElement | null) => void;
+    "data-domet": string;
+};
+export type NavProps = {
+    onClick: () => void;
+    "aria-current": "page" | undefined;
+    "data-active": boolean;
+};
+export type UseDometReturn = {
+    activeId: string | null;
+    activeIndex: number;
+    scroll: ScrollState;
+    sections: Record<string, SectionState>;
+    registerRef: (id: string) => (el: HTMLElement | null) => void;
+    scrollToSection: (id: string) => void;
+    sectionProps: (id: string) => SectionProps;
+    navProps: (id: string) => NavProps;
+};
+export declare function useDomet(sectionIds: string[], containerRef?: RefObject<HTMLElement> | null, options?: DometOptions): UseDometReturn;
+export default useDomet;
+//# sourceMappingURL=useDomet.d.ts.map

package/dist/useDomet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDomet.d.ts","sourceRoot":"","sources":["../src/useDomet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAgBvC,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACpE,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvC,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9D,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,YAAY,CAAC;IAC3C,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,QAAQ,CAAC;CACpC,CAAC;AAaF,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,GAAE,SAAS,CAAC,WAAW,CAAC,GAAG,IAAW,EAClD,OAAO,GAAE,YAAiB,GACzB,cAAc,CAulBhB;AAED,eAAe,QAAQ,CAAC"}