@openpawlabs/diy-guides-ui 1.7.2 → 1.7.3

package/dist/hooks/useGuideStepUrlSync.d.ts

@@ -5,15 +5,18 @@ export interface UseGuideStepUrlSyncOptions {
     rootRef: RefObject<HTMLElement | null>;
     /** Overview anchor from `GuideLayout` — used when the URL has no step. */
     guideTopRef?: RefObject<HTMLElement | null> | null;
+    /** Top of `GuideLayout.Content` — bounds the overview region for URL sync. */
+    guideContentRef?: RefObject<HTMLElement | null> | null;
     stepNumbers: number[];
     mode?: GuideStepUrlMode;
     stepUrlKey?: string;
-    /** Top scroll margin (px) — should match each step's `scrollMarginTop`. @default 0 */
+    /** Step scroll margin (px) — parent offset plus library progress-bar clearance. */
     scrollMarginTop?: number;
+    /** Overview scroll margin (px) — parent offset only. */
+    overviewScrollMarginTop?: number;
     /**
-     * Fraction of a step's height that must remain visible in the viewport for it
-     * to stay active. When less than this remains on screen, the next step takes
-     * over. @default 0.2
+     * Fraction of a section's height that must remain visible below fixed chrome for
+     * it to stay active. Applies to the overview and steps alike. @default 0.2
      */
     activeStepMinVisibleRatio?: number;
     onActiveStepChange?: (step: number | null) => void;
@@ -22,5 +25,5 @@ export interface UseGuideStepUrlSyncOptions {
  * Keeps the page URL in sync with the guide step in view and smooth-scrolls when
  * the URL names a step (including on load and `hashchange`).
  */
-export declare function useGuideStepUrlSync({ enabled, rootRef, guideTopRef, stepNumbers, mode, stepUrlKey, scrollMarginTop, activeStepMinVisibleRatio, onActiveStepChange, }: UseGuideStepUrlSyncOptions): void;
+export declare function useGuideStepUrlSync({ enabled, rootRef, guideTopRef, guideContentRef, stepNumbers, mode, stepUrlKey, scrollMarginTop, overviewScrollMarginTop, activeStepMinVisibleRatio, onActiveStepChange, }: UseGuideStepUrlSyncOptions): void;
 //# sourceMappingURL=useGuideStepUrlSync.d.ts.map

package/dist/hooks/useGuideStepUrlSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGuideStepUrlSync.d.ts","sourceRoot":"","sources":["../../src/hooks/useGuideStepUrlSync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACpD;AAqBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,OAAO,EACP,WAAkB,EAClB,WAAW,EACX,IAAa,EACb,UAAmB,EACnB,eAAmB,EACnB,yBAA+B,EAC/B,kBAAkB,GACnB,EAAE,0BAA0B,QAmM5B"}
+{"version":3,"file":"useGuideStepUrlSync.d.ts","sourceRoot":"","sources":["../../src/hooks/useGuideStepUrlSync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAMvE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,8EAA8E;IAC9E,eAAe,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACpD;AAgBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,OAAO,EACP,WAAkB,EAClB,eAAsB,EACtB,WAAW,EACX,IAAa,EACb,UAAmB,EACnB,eAAmB,EACnB,uBAA2B,EAC3B,yBAA+B,EAC/B,kBAAkB,GACnB,EAAE,0BAA0B,QAoP5B"}

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export type { GuideStepProps, GuideStepBulletProps, GuideStepBulletVariant, Guid
 export { GuideStepList } from "./components/GuideStepList";
 export type { GuideStepListProps, GuideProgress, } from "./components/GuideStepList";
 export { guideStepUrlId, parseGuideStepFromHash, parseGuideStepFromSearch, readGuideStepFromLocation, buildGuideStepUrl, type GuideStepUrlMode, } from "./utils/guideStepUrl";
-export { computeGuideStepScrollMarginTop, useGuideScrollMargin, GuideScrollMarginContext, } from "./context/guideScrollMargin";
+export { computeGuideLibraryScrollMarginTop, computeGuideOverviewScrollMarginTop, computeGuideStepScrollMarginTop, computeParentScrollMarginTop, useGuideContentRef, useGuideScrollMargin, GuideScrollMarginContext, } from "./context/guideScrollMargin";
 export { GuideLayout } from "./components/GuideLayout";
 export type { GuideLayoutProps, GuideLayoutHeaderProps, GuideLayoutIntroProps, } from "./components/GuideLayout";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,oBAAoB,CAAC;AAG5B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,KAAK,WAAW,EAChB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EACV,oBAAoB,EACpB,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EACL,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,aAAa,GACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,oBAAoB,CAAC;AAG5B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,KAAK,WAAW,EAChB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EACV,oBAAoB,EACpB,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EACL,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,aAAa,GACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,kCAAkC,EAClC,mCAAmC,EACnC,+BAA+B,EAC/B,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/utils/pickActiveGuideStep.d.ts

@@ -1,19 +1,37 @@
-/** Fraction of a step's height that is visible in the viewport. */
-export declare function getStepVisibleRatio(rect: DOMRect, innerHeight?: number): number;
+/** Fraction of a section's height visible below fixed chrome at the top of the viewport. */
+export declare function getStepVisibleRatio(rect: DOMRect, innerHeight?: number, contentInsetTop?: number): number;
 /**
- * Picks the active step while scrolling: the earliest step that still has at
- * least `activeStepMinVisibleRatio` of its height on screen. Later steps do
- * not take over until every earlier step has fallen below that threshold.
+ * Overview region from the guide top anchor through the top of `GuideLayout.Content`
+ * (header, intro, and sidebar — not the steps).
  */
-export declare function pickActiveGuideStep(stepNumbers: number[], activeStepMinVisibleRatio: number, getRect: (step: number) => DOMRect | null, innerHeight?: number): number | null;
-/** Whether the guide overview anchor is aligned with the top of the viewport. */
-export declare function isGuideOverviewVisible(anchorRect: DOMRect | null, scrollMarginTop: number): boolean;
-/** True when the reader is back at the guide overview — no step should be in the URL. */
-export declare function shouldClearGuideStepFromUrl({ guideTopRect, firstStepRect, scrollMarginTop, activeStepMinVisibleRatio, innerHeight, }: {
-    guideTopRect: DOMRect | null;
-    firstStepRect: DOMRect | null;
-    scrollMarginTop: number;
+export declare function getOverviewRect(guideTopRect: DOMRect | null, contentTopRect: DOMRect | null): DOMRect | null;
+/** True when the viewport has reached (or nearly reached) the document bottom. */
+export declare function isAtPageBottom(scrollY?: number, innerHeight?: number, thresholdPx?: number): boolean;
+export interface PickActiveGuideSectionOptions {
+    overviewRect: DOMRect | null;
+    overviewContentInsetTop: number;
+    stepNumbers: number[];
+    getStepRect: (step: number) => DOMRect | null;
     activeStepMinVisibleRatio: number;
+    stepContentInsetTop: number;
     innerHeight?: number;
-}): boolean;
+    /**
+     * When true, the final step wins if the reader has reached the document bottom.
+     * Pass `isAtPageBottom()` from scroll handlers; defaults to `false`.
+     */
+    atPageBottom?: boolean;
+}
+/**
+ * Picks the active guide section while scrolling. The overview (`null`) competes
+ * with steps using the same `activeStepMinVisibleRatio` rule — the earliest
+ * section with enough visible area below its content inset wins, except the
+ * final step wins when the reader reaches the document bottom or has scrolled it
+ * into the primary reading position (top at or above the step content inset).
+ */
+export declare function pickActiveGuideSection({ overviewRect, overviewContentInsetTop, stepNumbers, getStepRect, activeStepMinVisibleRatio, stepContentInsetTop, innerHeight, atPageBottom, }: PickActiveGuideSectionOptions): number | null;
+/**
+ * Picks the active step while scrolling — overview is not considered.
+ * @deprecated Prefer `pickActiveGuideSection` when an overview region is available.
+ */
+export declare function pickActiveGuideStep(stepNumbers: number[], activeStepMinVisibleRatio: number, getRect: (step: number) => DOMRect | null, innerHeight?: number, contentInsetTop?: number): number | null;
 //# sourceMappingURL=pickActiveGuideStep.d.ts.map

package/dist/utils/pickActiveGuideStep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pickActiveGuideStep.d.ts","sourceRoot":"","sources":["../../src/utils/pickActiveGuideStep.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,WAAW,GAAE,MAA2B,GACvC,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EAAE,EACrB,yBAAyB,EAAE,MAAM,EACjC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,EACzC,WAAW,GAAE,MAA2B,GACvC,MAAM,GAAG,IAAI,CAiCf;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,GAAG,IAAI,EAC1B,eAAe,EAAE,MAAM,GACtB,OAAO,CAMT;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,EAC1C,YAAY,EACZ,aAAa,EACb,eAAe,EACf,yBAAyB,EACzB,WAAgC,GACjC,EAAE;IACD,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,yBAAyB,EAAE,MAAM,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAYV"}
+{"version":3,"file":"pickActiveGuideStep.d.ts","sourceRoot":"","sources":["../../src/utils/pickActiveGuideStep.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,WAAW,GAAE,MAA2B,EACxC,eAAe,GAAE,MAAU,GAC1B,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,OAAO,GAAG,IAAI,EAC5B,cAAc,EAAE,OAAO,GAAG,IAAI,GAC7B,OAAO,GAAG,IAAI,CAsBhB;AAkCD,kFAAkF;AAClF,wBAAgB,cAAc,CAC5B,OAAO,GAAE,MAA2B,EACpC,WAAW,GAAE,MAA4B,EACzC,WAAW,GAAE,MAAU,GACtB,OAAO,CAYT;AAED,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAC9C,yBAAyB,EAAE,MAAM,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,YAAY,EACZ,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,yBAAyB,EACzB,mBAAmB,EACnB,WAAgC,EAChC,YAAoB,GACrB,EAAE,6BAA6B,GAAG,MAAM,GAAG,IAAI,CA4E/C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EAAE,EACrB,yBAAyB,EAAE,MAAM,EACjC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,EACzC,WAAW,GAAE,MAA2B,EACxC,eAAe,GAAE,MAAU,GAC1B,MAAM,GAAG,IAAI,CAUf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpawlabs/diy-guides-ui",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "React UI library for building open-source, iFixit-style step-by-step diy guides",
   "license": "MIT",
   "type": "module",