@devcabs/folio-engine 0.0.0-stage → 0.1.1

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 (193) hide show
  1. package/dist/App.d.ts +7 -0
  2. package/dist/components/canvas/CanvasAddBar.d.ts +28 -0
  3. package/dist/components/canvas/CanvasAddModal.d.ts +38 -0
  4. package/dist/components/canvas/CanvasChart.d.ts +23 -0
  5. package/dist/components/canvas/CanvasDeleteConfirmModal.d.ts +21 -0
  6. package/dist/components/canvas/CanvasGallery.d.ts +20 -0
  7. package/dist/components/canvas/CanvasItemControls.d.ts +33 -0
  8. package/dist/components/canvas/CanvasPhoto.d.ts +28 -0
  9. package/dist/components/canvas/CanvasSection.d.ts +27 -0
  10. package/dist/components/canvas/CanvasSubsection.d.ts +23 -0
  11. package/dist/components/canvas/CanvasText.d.ts +23 -0
  12. package/dist/components/canvas/DocumentCanvas.d.ts +20 -0
  13. package/dist/components/canvas/HeroPhoto.d.ts +17 -0
  14. package/dist/components/canvas/NodeCanvas.d.ts +2 -0
  15. package/dist/components/canvas/index.d.ts +17 -0
  16. package/dist/components/chart/BarChart.d.ts +23 -0
  17. package/dist/components/chart/ChartCard.d.ts +33 -0
  18. package/dist/components/chart/ChartConfigDrawer.d.ts +16 -0
  19. package/dist/components/chart/ChartGhostWireframe.d.ts +16 -0
  20. package/dist/components/chart/ChartLegend.d.ts +14 -0
  21. package/dist/components/chart/ChartRouter.d.ts +8 -0
  22. package/dist/components/chart/ChartSortingControls.d.ts +15 -0
  23. package/dist/components/chart/ChartTableModal.d.ts +26 -0
  24. package/dist/components/chart/ChartTooltip.d.ts +12 -0
  25. package/dist/components/chart/DataPendingCard.d.ts +28 -0
  26. package/dist/components/chart/DonutChart.d.ts +16 -0
  27. package/dist/components/chart/HistogramChart.d.ts +23 -0
  28. package/dist/components/chart/LineChart.d.ts +22 -0
  29. package/dist/components/chart/RangePreviewMatrix.d.ts +19 -0
  30. package/dist/components/chart/ScatterPlot.d.ts +21 -0
  31. package/dist/components/chart/drawer/controls/BarVisualControls.d.ts +9 -0
  32. package/dist/components/chart/drawer/controls/ChartTitlesSection.d.ts +15 -0
  33. package/dist/components/chart/drawer/controls/DonutVisualControls.d.ts +7 -0
  34. package/dist/components/chart/drawer/controls/HistogramVisualControls.d.ts +13 -0
  35. package/dist/components/chart/drawer/controls/LineVisualControls.d.ts +14 -0
  36. package/dist/components/chart/drawer/controls/ScatterDataControls.d.ts +17 -0
  37. package/dist/components/chart/drawer/controls/ScatterVisualControls.d.ts +23 -0
  38. package/dist/components/chart/drawer/controls/SortingAndOrderControls.d.ts +18 -0
  39. package/dist/components/chart/drawer/controls/StandardDataControls.d.ts +31 -0
  40. package/dist/components/chart/drawer/hooks/useChartConfigForm.d.ts +156 -0
  41. package/dist/components/chart/drawer/hooks/useLiveMatrixSync.d.ts +21 -0
  42. package/dist/components/chart/drawer/hooks/useSheetVerification.d.ts +26 -0
  43. package/dist/components/chart/drawer/index.d.ts +17 -0
  44. package/dist/components/chart/drawer/panels/Step1Source.d.ts +18 -0
  45. package/dist/components/chart/drawer/panels/Step1SourceRange.d.ts +32 -0
  46. package/dist/components/chart/drawer/panels/Step2DataRange.d.ts +15 -0
  47. package/dist/components/chart/drawer/panels/Step3ChartSetup.d.ts +17 -0
  48. package/dist/components/chart/drawer/panels/Step4Review.d.ts +11 -0
  49. package/dist/components/chart/index.d.ts +22 -0
  50. package/dist/components/dev/DevActionAffordance.d.ts +4 -0
  51. package/dist/components/dev/DevExitConfirmModal.d.ts +14 -0
  52. package/dist/components/dev/DevLockBlockedModal.d.ts +3 -0
  53. package/dist/components/dev/DevModeBadge.d.ts +3 -0
  54. package/dist/components/dev/DevPinModal.d.ts +3 -0
  55. package/dist/components/dev/DevPublishModal.d.ts +9 -0
  56. package/dist/components/dev/UniversalEditModal.d.ts +40 -0
  57. package/dist/components/dev/index.d.ts +8 -0
  58. package/dist/components/feedback/EmptyState.d.ts +13 -0
  59. package/dist/components/feedback/PageNotFound.d.ts +15 -0
  60. package/dist/components/feedback/Toast.d.ts +25 -0
  61. package/dist/components/feedback/index.d.ts +2 -0
  62. package/dist/components/history/HistoryHubModal.d.ts +44 -0
  63. package/dist/components/history/index.d.ts +1 -0
  64. package/dist/components/layout/AppFooter.d.ts +10 -0
  65. package/dist/components/layout/AppHeader.d.ts +22 -0
  66. package/dist/components/layout/EditorialSection.d.ts +27 -0
  67. package/dist/components/layout/EditorialSidebar.d.ts +34 -0
  68. package/dist/components/layout/HeroSection.d.ts +2 -0
  69. package/dist/components/layout/HeroWelcome.d.ts +11 -0
  70. package/dist/components/layout/SearchField.d.ts +9 -0
  71. package/dist/components/layout/StatusPill.d.ts +2 -0
  72. package/dist/components/layout/index.d.ts +8 -0
  73. package/dist/components/roadmap/RoadmapNode.d.ts +30 -0
  74. package/dist/components/roadmap/RoadmapSection.d.ts +27 -0
  75. package/dist/components/roadmap/RoadmapTrack.d.ts +25 -0
  76. package/dist/components/roadmap/serpentine-generator.d.ts +60 -0
  77. package/dist/components/roadmap/use-roadmap-scroll.d.ts +19 -0
  78. package/dist/components/source/EditPhotoModal.d.ts +22 -0
  79. package/dist/components/source/LightboxPhotoStrip.d.ts +23 -0
  80. package/dist/components/source/LinkFolderModal.d.ts +24 -0
  81. package/dist/components/source/SourceCard.d.ts +31 -0
  82. package/dist/components/source/SourceFolderAttachment.d.ts +25 -0
  83. package/dist/components/source/SourceGallery.d.ts +26 -0
  84. package/dist/components/source/SourceImage.d.ts +26 -0
  85. package/dist/components/source/SourceLightbox.d.ts +28 -0
  86. package/dist/components/source/index.d.ts +9 -0
  87. package/dist/components/ui/AccordionSection.d.ts +21 -0
  88. package/dist/components/ui/Breadcrumb.d.ts +29 -0
  89. package/dist/components/ui/Button.d.ts +31 -0
  90. package/dist/components/ui/ColumnSelect.d.ts +17 -0
  91. package/dist/components/ui/ColumnTypeBadge.d.ts +6 -0
  92. package/dist/components/ui/DevHelpTooltip.d.ts +11 -0
  93. package/dist/components/ui/DraggableRows.d.ts +21 -0
  94. package/dist/components/ui/Drawer.d.ts +50 -0
  95. package/dist/components/ui/DrawerTier.d.ts +8 -0
  96. package/dist/components/ui/EditableText.d.ts +48 -0
  97. package/dist/components/ui/FAB.d.ts +24 -0
  98. package/dist/components/ui/Modal.d.ts +24 -0
  99. package/dist/components/ui/PageTitle.d.ts +33 -0
  100. package/dist/components/ui/ParametricShape.d.ts +57 -0
  101. package/dist/components/ui/RevolvingButton.d.ts +5 -0
  102. package/dist/components/ui/SectionTitle.d.ts +42 -0
  103. package/dist/components/ui/SeriesSelectToolbar.d.ts +10 -0
  104. package/dist/components/ui/StatusPill.d.ts +21 -0
  105. package/dist/components/ui/TieredSlider.d.ts +19 -0
  106. package/dist/components/ui/Toast.d.ts +1 -0
  107. package/dist/components/ui/ValueLabelToggle.d.ts +10 -0
  108. package/dist/components/ui/index.d.ts +21 -0
  109. package/dist/config/engine.config.d.ts +162 -0
  110. package/dist/context/DeveloperModeContext.d.ts +11 -0
  111. package/dist/context/UndoRedoContext.d.ts +20 -0
  112. package/dist/diagnostics/verifyEngineSetup.d.ts +30 -0
  113. package/dist/diagnostics-CpGr1hhi.js +126 -0
  114. package/dist/diagnostics-Dw5PzR78.cjs +5 -0
  115. package/dist/diagnostics.cjs +1 -0
  116. package/dist/diagnostics.d.ts +10 -0
  117. package/dist/diagnostics.js +14 -0
  118. package/dist/edge-1WCVZ0J7.cjs +1 -0
  119. package/dist/edge-CSjifIhA.js +2709 -0
  120. package/dist/edge-Dr41JdrQ.cjs +34 -0
  121. package/dist/edge-h_ge9f1E.js +512 -0
  122. package/dist/edge.cjs +1 -0
  123. package/dist/edge.d.ts +10 -0
  124. package/dist/edge.js +26 -0
  125. package/dist/folio.cjs +9 -0
  126. package/dist/folio.js +21895 -0
  127. package/dist/hooks/use-auto-toc.d.ts +31 -0
  128. package/dist/hooks/use-discrete-step-navigation.d.ts +26 -0
  129. package/dist/hooks/use-dynamic-section-numbers.d.ts +30 -0
  130. package/dist/hooks/use-hash-route.d.ts +36 -0
  131. package/dist/hooks/use-scroll.d.ts +22 -0
  132. package/dist/hooks/use-scrollspy.d.ts +19 -0
  133. package/dist/hooks/useChartTooltip.d.ts +25 -0
  134. package/dist/hooks/useContent.d.ts +36 -0
  135. package/dist/hooks/useDeveloperMode.d.ts +1 -0
  136. package/dist/hooks/useDocumentCanvas.d.ts +53 -0
  137. package/dist/hooks/useDrivePhotoSync.d.ts +15 -0
  138. package/dist/hooks/useImageLoader.d.ts +12 -0
  139. package/dist/hooks/useLightboxHistory.d.ts +14 -0
  140. package/dist/hooks/useNodeCanvas.d.ts +2 -0
  141. package/dist/hooks/useSheetChartData.d.ts +31 -0
  142. package/dist/hooks/useSourcePoint.d.ts +35 -0
  143. package/dist/hooks/useSwipeGesture.d.ts +30 -0
  144. package/dist/hooks/useUndoRedo.d.ts +9 -0
  145. package/dist/hooks/useUnsavedChangesPrompt.d.ts +18 -0
  146. package/dist/index.d.ts +53 -0
  147. package/dist/main.d.ts +1 -0
  148. package/dist/services/canvasLayoutService.d.ts +158 -0
  149. package/dist/services/chartSourceService.d.ts +128 -0
  150. package/dist/services/devLockService.d.ts +76 -0
  151. package/dist/services/draftService.d.ts +129 -0
  152. package/dist/services/drivePhotoSyncService.d.ts +60 -0
  153. package/dist/services/driveVerificationService.d.ts +41 -0
  154. package/dist/services/edgePreBakeService.d.ts +81 -0
  155. package/dist/services/historyService.d.ts +215 -0
  156. package/dist/services/historyStorage.d.ts +17 -0
  157. package/dist/services/mediaService.d.ts +25 -0
  158. package/dist/services/sheetsDataService.d.ts +59 -0
  159. package/dist/services/sheetsVerificationService.d.ts +87 -0
  160. package/dist/services/sourceService.d.ts +43 -0
  161. package/dist/services/undoRedoService.d.ts +63 -0
  162. package/dist/services/unsavedChangesService.d.ts +32 -0
  163. package/dist/style.css +1 -0
  164. package/dist/types/canvas.d.ts +115 -0
  165. package/dist/types/chart.d.ts +117 -0
  166. package/dist/types/developer.d.ts +144 -0
  167. package/dist/types/draft.d.ts +21 -0
  168. package/dist/types/edge.d.ts +232 -0
  169. package/dist/types/history.d.ts +81 -0
  170. package/dist/types/media.d.ts +16 -0
  171. package/dist/types/navigation.d.ts +19 -0
  172. package/dist/types/node.d.ts +51 -0
  173. package/dist/types/source.d.ts +88 -0
  174. package/dist/utils/canvasDefaults.d.ts +43 -0
  175. package/dist/utils/chartColors.d.ts +48 -0
  176. package/dist/utils/chartDimensions.d.ts +50 -0
  177. package/dist/utils/chartMath.d.ts +142 -0
  178. package/dist/utils/chartSanitizer.d.ts +84 -0
  179. package/dist/utils/contentDb.d.ts +86 -0
  180. package/dist/utils/devSecurity.d.ts +84 -0
  181. package/dist/utils/mediaUrl.d.ts +32 -0
  182. package/dist/utils/modalActions.d.ts +32 -0
  183. package/dist/utils/node-sections.d.ts +15 -0
  184. package/dist/utils/page-sections.d.ts +1 -0
  185. package/dist/utils/runtime-env.d.ts +21 -0
  186. package/dist/utils/scrollLock.d.ts +10 -0
  187. package/dist/utils/smooth-scroll.d.ts +24 -0
  188. package/dist/utils/source.d.ts +25 -0
  189. package/dist/utils/storage.d.ts +13 -0
  190. package/dist/utils/supabase-config.d.ts +29 -0
  191. package/dist/utils/supabase-write-guard.d.ts +15 -0
  192. package/package.json +68 -4
  193. package/README.md +0 -3
@@ -0,0 +1,31 @@
1
+ import type { NavItem } from '../types/navigation';
2
+ export interface UseAutoTableOfContentsOptions {
3
+ /** Target container DOM ID to observe (default: 'node-content') */
4
+ containerId?: string;
5
+ /** React ref to container element (overrides containerId if provided) */
6
+ containerRef?: React.RefObject<HTMLElement | null>;
7
+ /** Selector for section elements (default: 'section[id], [data-toc-title][id], [data-toc="true"][id]') */
8
+ sectionSelector?: string;
9
+ /** Optional custom ID to title formatter */
10
+ formatIdToTitle?: (id: string) => string;
11
+ }
12
+ /**
13
+ * Converts a kebab-case or snake_case element ID into a readable title fallback.
14
+ * e.g. "node-overview" -> "Overview", "source-proof" -> "Evidence & Proof"
15
+ */
16
+ export declare function defaultFormatIdToTitle(id: string): string;
17
+ /**
18
+ * Pure function to extract canonical NavItems from a given container element.
19
+ */
20
+ export declare function extractNavItemsFromContainer(container: HTMLElement, sectionSelector?: string, formatTitle?: typeof defaultFormatIdToTitle): NavItem[];
21
+ /**
22
+ * useAutoTableOfContents Hook
23
+ *
24
+ * Canonical DOM-driven table of contents discovery for long-form editorial views:
25
+ * - Scans a content container for semantic sections with IDs
26
+ * - Automatically extracts labels and numbers using a robust cascade
27
+ * - Dynamic reactivity: attaches a MutationObserver to instantly capture added/removed sections
28
+ * - Debounced via requestAnimationFrame to guarantee smooth 60fps performance without layout thrashing
29
+ */
30
+ export declare function useAutoTableOfContents(options?: UseAutoTableOfContentsOptions): NavItem[];
31
+ export default useAutoTableOfContents;
@@ -0,0 +1,26 @@
1
+ import type { RoadmapScrollZone } from '../components/roadmap/RoadmapSection';
2
+ export interface UseDiscreteStepNavigationOptions {
3
+ enabled: boolean;
4
+ activeStage: number;
5
+ scrollZone: RoadmapScrollZone;
6
+ onNextStage: () => void;
7
+ onPrevStage: () => void;
8
+ onScrollToTop: () => void;
9
+ onScrollToFooter: () => void;
10
+ onDirectStage: (stage: number) => void;
11
+ /** Cooldown buffer in ms after transition completes before accepting new gestures. Defaults to 200ms. */
12
+ cooldownMs?: number;
13
+ }
14
+ export interface DiscreteStepNavigationHandle {
15
+ isTransitioning: boolean;
16
+ lockTransition: (estimatedDurationMs?: number) => void;
17
+ unlockTransition: () => void;
18
+ }
19
+ /**
20
+ * useDiscreteStepNavigation (Task 4.2.1b / Approach B)
21
+ *
22
+ * Disables continuous manual document scrolling on the landing page across
23
+ * desktop mouse wheels, trackpads, and mobile touch devices. Converts gestures
24
+ * into discrete, debounced milestone-to-milestone transitions with transition locking.
25
+ */
26
+ export declare function useDiscreteStepNavigation({ enabled, activeStage, scrollZone, onNextStage, onPrevStage, onScrollToTop, onScrollToFooter, onDirectStage, cooldownMs, }: UseDiscreteStepNavigationOptions): DiscreteStepNavigationHandle;
@@ -0,0 +1,30 @@
1
+ import type { SectionElement } from '../types/canvas';
2
+ export interface DynamicSectionItem {
3
+ id: string;
4
+ isNumbered: boolean;
5
+ }
6
+ /**
7
+ * Pure function to compute sequential section numbers skipping unnumbered sections.
8
+ * e.g.:
9
+ * [numbered, numbered] -> { sec1: "01", sec2: "02" }
10
+ * [unnumbered, numbered] -> { sec1: null, sec2: "01" } (preceding section skipped in iteration)
11
+ * [numbered, unnumbered, numbered] -> { sec1: "01", sec2: null, sec3: "02" }
12
+ */
13
+ export declare function computeDynamicSectionNumbers(sections: DynamicSectionItem[]): Record<string, string | null>;
14
+ export interface UseNodeSectionNumbersReturn {
15
+ isSourceNumbered: boolean;
16
+ isChartNumbered: boolean;
17
+ sourceNumber: string | null;
18
+ chartNumber: string | null;
19
+ }
20
+ /**
21
+ * Reactive hook providing dynamic section numbers for PillarPage.
22
+ * If Evidence Gallery is unnumbered, Indicator Chart dynamically increments from 01.
23
+ */
24
+ export declare function useNodeSectionNumbers(nodeId: string): UseNodeSectionNumbersReturn;
25
+ /**
26
+ * Reactive hook providing sequential section numbers for dynamic canvas sections.
27
+ * Reactively recalculates whenever a section's numbering toggle is updated in Content DB.
28
+ */
29
+ export declare function useDynamicCanvasSectionNumbers(nodeId: string, sections: SectionElement[]): Record<string, string | null>;
30
+ export default useNodeSectionNumbers;
@@ -0,0 +1,36 @@
1
+ import type { NodeCode } from "../types/node";
2
+ export type RouteType = "home" | "node" | "page" | "not-found";
3
+ export interface RouteState {
4
+ type: "home" | "node" | "not-found";
5
+ nodeId: NodeCode | null;
6
+ /** Backwards compatibility alias */
7
+ pageId: NodeCode | null;
8
+ targetStage: number | null;
9
+ rawHash: string;
10
+ pathname?: string;
11
+ }
12
+ export declare const VALID_NODES: NodeCode[];
13
+ export declare const NODE_TO_STAGE: Record<NodeCode, number>;
14
+ export declare const STAGE_TO_NODE: Record<number, NodeCode>;
15
+ /**
16
+ * Universal route parser supporting both modern HTML5 path routes (/node/:id/)
17
+ * and legacy hash routes (#node/:id).
18
+ * Parameterized to support arbitrary custom node identifiers, stages, and subpaths.
19
+ */
20
+ export declare function parseRoute(pathname?: string, hash?: string, validNodes?: NodeCode[], basePath?: string): RouteState;
21
+ /**
22
+ * Backwards compatibility helper for legacy hash parser
23
+ */
24
+ export declare function parseHash(hash: string, validNodes?: NodeCode[]): RouteState;
25
+ export declare function useHashRoute(validNodes?: NodeCode[], basePath?: string): {
26
+ route: "node" | "home" | "not-found";
27
+ nodeId: string | null;
28
+ pageId: string | null;
29
+ targetStage: number | null;
30
+ rawHash: string;
31
+ pathname: string | undefined;
32
+ navigateToNode: (nodeId: NodeCode) => void;
33
+ navigateToPage: (nodeId: NodeCode) => void;
34
+ navigateToHome: (stage?: number) => void;
35
+ };
36
+ export declare const useAppRoute: typeof useHashRoute;
@@ -0,0 +1,22 @@
1
+ export interface UseScrollOptions {
2
+ target?: React.RefObject<HTMLElement | null>;
3
+ }
4
+ export interface ScrollValues {
5
+ scrollY: number;
6
+ scrollProgress: number;
7
+ }
8
+ /**
9
+ * useScroll Hook
10
+ *
11
+ * Tracks scroll position and normalized scroll progress (0 to 1)
12
+ * relative to the window or a designated container element.
13
+ *
14
+ * Provides:
15
+ * - Reactive state: `scrollProgress` and `scrollY`
16
+ * - High-performance subscription: `subscribeScroll` (for zero-rerender direct DOM manipulation)
17
+ */
18
+ export declare const useScroll: (options?: UseScrollOptions) => {
19
+ subscribeScroll: (callback: (values: ScrollValues) => void) => () => void;
20
+ scrollY: number;
21
+ scrollProgress: number;
22
+ };
@@ -0,0 +1,19 @@
1
+ export interface UseScrollspyOptions {
2
+ /** Reading reference line distance in px from top of viewport. Defaults to 140px (clearing AppHeader) */
3
+ offsetPx?: number;
4
+ /** Fallback active ID when no monitored element is found */
5
+ defaultActiveId?: string;
6
+ }
7
+ /**
8
+ * useScrollspy Hook
9
+ *
10
+ * High-performance, passive scroll tracking hook for editorial long-form layouts.
11
+ * Uses document-order threshold detection to determine the active reading section.
12
+ * Perfectly handles short sections sharing the viewport without skipping or getting stuck.
13
+ *
14
+ * @param itemIds Array of element DOM IDs (without '#') to monitor
15
+ * @param options Configuration for offsetPx and defaultActiveId
16
+ * @returns The active element ID currently in the reading viewport zone
17
+ */
18
+ export declare function useScrollspy(itemIds: string[], options?: UseScrollspyOptions): string;
19
+ export default useScrollspy;
@@ -0,0 +1,25 @@
1
+ export interface ChartTooltipState<T = unknown> {
2
+ visible: boolean;
3
+ x: number;
4
+ y: number;
5
+ title?: string;
6
+ seriesName?: string;
7
+ value: number | string | null;
8
+ unit?: string;
9
+ color?: string;
10
+ extra?: T;
11
+ }
12
+ export interface UseChartTooltipOptions {
13
+ clampX?: [number, number];
14
+ clampY?: [number, number];
15
+ }
16
+ /**
17
+ * Canonical Tooltip Hook & Boundary Clamping
18
+ * Standardizes tooltip state management and coordinates across all charts.
19
+ */
20
+ export declare function useChartTooltip<T = unknown>(options?: UseChartTooltipOptions): {
21
+ tooltipState: ChartTooltipState<T>;
22
+ setTooltipState: import("react").Dispatch<import("react").SetStateAction<ChartTooltipState<T>>>;
23
+ showTooltip: (params: Omit<ChartTooltipState<T>, "visible">) => void;
24
+ hideTooltip: () => void;
25
+ };
@@ -0,0 +1,36 @@
1
+ export interface UseContentReturn {
2
+ /** The current resolved text content (from DB or default) */
3
+ text: string;
4
+ /** Whether this content key currently has a custom override saved in DB */
5
+ isModified: boolean;
6
+ /** Update the text override in the DB */
7
+ setText: (value: string) => void;
8
+ /** Alias for setText matching useContentObject signature */
9
+ setValue: (value: string) => void;
10
+ /** Revert to the hardcoded system default */
11
+ resetText: () => void;
12
+ /** Alias for resetText matching useContentObject signature */
13
+ resetValue: () => void;
14
+ }
15
+ /**
16
+ * Reactive hook to dynamically consume and modify text content from the Content DB.
17
+ * Rebuilt on React 19's useSyncExternalStore for zero-overhead, flicker-free updates.
18
+ * Guarantees that wildcard and unrelated notifications trigger zero re-renders.
19
+ */
20
+ export declare function useContent(key: string, defaultValue: string, explicitDevMode?: boolean): UseContentReturn;
21
+ export interface UseContentObjectReturn<T> {
22
+ /** The current resolved object content (from DB or default) */
23
+ value: T;
24
+ /** Whether this content key currently has a custom override saved in DB */
25
+ isModified: boolean;
26
+ /** Update the object override in the DB */
27
+ setValue: (value: T) => void;
28
+ /** Revert to the hardcoded system default */
29
+ resetValue: () => void;
30
+ }
31
+ /**
32
+ * Reactive hook to dynamically consume and modify structured content (e.g. image payloads) from Content DB.
33
+ * Derives its state from useContent's useSyncExternalStore primitive string snapshots, eliminating ghost re-renders.
34
+ */
35
+ export declare function useContentObject<T>(key: string, defaultValue: T, explicitDevMode?: boolean): UseContentObjectReturn<T>;
36
+ export default useContent;
@@ -0,0 +1 @@
1
+ export { useDeveloperMode } from '../context/DeveloperModeContext';
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Folio Engine - Reactive Dynamic Canvas Hook
3
+ * Location: src/hooks/useNodeCanvas.ts
4
+ * Specification: docs/tasks/task8_2_storage_and_sync_service.md
5
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
6
+ *
7
+ * Implements:
8
+ * 1. Synchronous state initialization from local-first storage.
9
+ * 2. Cross-component synchronization via CustomEvent subscription.
10
+ * 3. Non-blocking UI updates using React 19 startTransition (rerender-transitions).
11
+ * 4. Atomic, immutable CRUD dispatchers for sections, subsections, and leaf elements.
12
+ */
13
+ import type { CanvasElement, CanvasLeafElement, SectionElement, SubsectionElement, NodeCanvasDocument } from '../types/canvas';
14
+ export interface UseNodeCanvasReturn {
15
+ /** Active in-memory canvas document tree */
16
+ document: NodeCanvasDocument;
17
+ /** True when a canvas layout transition is pending */
18
+ isPending: boolean;
19
+ /** Add a new section container with automatic numbering */
20
+ addSection: (targetIndex?: number) => void;
21
+ /** Add a new subsection container inside a section */
22
+ addSubsection: (sectionId: string, targetIndex?: number) => void;
23
+ /** Add a leaf element (text, photo, chart) to a section or subsection */
24
+ addElement: (sectionId: string, element: CanvasLeafElement, targetIndex?: number, subsectionId?: string) => void;
25
+ /** Restore or insert an existing section at target index (for undo) */
26
+ restoreSection: (section: SectionElement, targetIndex?: number) => void;
27
+ /** Restore or insert an existing subsection at target index (for undo) */
28
+ restoreSubsection: (sectionId: string, subsection: SubsectionElement, targetIndex?: number) => void;
29
+ /** Restore or insert an existing leaf element at target index (for undo) */
30
+ restoreElement: (sectionId: string, element: CanvasLeafElement, targetIndex?: number, subsectionId?: string) => void;
31
+ /** Move an item up or down within its container */
32
+ moveItem: (itemId: string, direction: 'up' | 'down', parentId?: string) => void;
33
+ /** Relocate an item anywhere across the canvas to a target container */
34
+ relocateItem: (sourceItemId: string, targetContainerId: string, targetIndex?: number) => void;
35
+ /** Remove an item and all its nested children */
36
+ removeItem: (itemId: string, parentId?: string) => void;
37
+ /** Update attributes of an element by ID */
38
+ updateItem: <T extends CanvasElement>(itemId: string, updates: Partial<T>) => void;
39
+ /** Reset node canvas back to default structure */
40
+ resetToDefault: () => void;
41
+ /** Deploy active canvas document to cloud storage (Supabase) */
42
+ deployToCloud: () => Promise<boolean>;
43
+ /** Error message if saving canvas to storage failed (e.g. storage quota exceeded) */
44
+ saveError: string | null;
45
+ /** Dismiss the active save error */
46
+ clearSaveError: () => void;
47
+ }
48
+ /**
49
+ * Hook providing reactive state and atomic dispatchers for managing a node's Dynamic Canvas.
50
+ */
51
+ export declare const useNodeCanvas: typeof useDocumentCanvas;
52
+ export declare function useDocumentCanvas(nodeId: string): UseNodeCanvasReturn;
53
+ export default useDocumentCanvas;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Reactive SWR Google Drive Photo Sync Hook
3
+ * Folio Engine
4
+ * Subtask 6.2: Zero-Quota Public Cache & Persistence Layer
5
+ *
6
+ * Implements a non-blocking React 19 SWR hook for Google Drive photo synchronization:
7
+ * - Deterministic 5-State Coexistence Lifecycle:
8
+ * never_synced | syncing | synced_success | synced_empty | sync_error
9
+ * - React 19 useTransition wrapper to eliminate UI render blocking
10
+ * - Synchronous local storage reading for zero layout shift (CLS = 0)
11
+ * - Cross-tab / multi-window synchronization via storage events
12
+ */
13
+ import type { UseDrivePhotoSyncResult } from '../types/source';
14
+ export declare function useDrivePhotoSync(nodeId: string): UseDrivePhotoSyncResult;
15
+ export default useDrivePhotoSync;
@@ -0,0 +1,12 @@
1
+ import type { UseImageLoaderResult } from '../types/source';
2
+ /**
3
+ * useImageLoader Hook
4
+ *
5
+ * Fault-tolerant finite state machine governing image asset loading lifecycle.
6
+ * - Handles 4 deterministic states: idle, loading, loaded, error
7
+ * - Fast-path bypass for cached images to eliminate layout flicker
8
+ * - Subscription flag cleanup to prevent memory leaks and state updates after unmount
9
+ * - Stable retry callback for recovery from network interruptions
10
+ */
11
+ export declare function useImageLoader(src?: string, fallbackSrc?: string): UseImageLoaderResult;
12
+ export default useImageLoader;
@@ -0,0 +1,14 @@
1
+ export interface UseLightboxHistoryProps {
2
+ isOpen: boolean;
3
+ onClose: () => void;
4
+ hash?: string;
5
+ }
6
+ /**
7
+ * useLightboxHistory Hook
8
+ *
9
+ * Synchronizes modal visibility with browser history and popstate events.
10
+ * Guarantees that pressing the browser or hardware Back button on mobile
11
+ * dismisses the lightbox and returns to the exact source page and scroll position.
12
+ */
13
+ export declare function useLightboxHistory({ isOpen, onClose, hash, }: UseLightboxHistoryProps): void;
14
+ export default useLightboxHistory;
@@ -0,0 +1,2 @@
1
+ export * from "./useDocumentCanvas";
2
+ export { default } from "./useDocumentCanvas";
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Reactive Chart Data Hook (SWR + Instant Synchronous Baseline Paint)
3
+ * Folio Engine — Subtask 7.4.6
4
+ * Document Reference: docs/tasks/task7_4_drawer_range_matrix_supabase_deploy.md
5
+ *
6
+ * Implements:
7
+ * 1. Instant <10ms synchronous initial render from baked JSON & local storage cache.
8
+ * 2. SWR background re-validation from Supabase cloud storage.
9
+ * 3. Live in-drawer configuration override support for real-time previewing.
10
+ */
11
+ import type { ChartDataset, SheetChartConfig, ChartSyncStatus } from '../types/chart';
12
+ import type { NodeCode } from '../types/node';
13
+ export declare const getMatrixCacheKey: (chartId: string) => string;
14
+ export interface UseSheetChartDataOptions {
15
+ chartId: string;
16
+ nodeId?: NodeCode;
17
+ initialDataset?: ChartDataset;
18
+ pollIntervalMs?: number;
19
+ isDevMode?: boolean;
20
+ }
21
+ export interface UseSheetChartDataReturn {
22
+ dataset: ChartDataset | null;
23
+ config: SheetChartConfig | null;
24
+ status: ChartSyncStatus;
25
+ errorMessage?: string;
26
+ lastSyncedAt?: string;
27
+ reload: () => Promise<void>;
28
+ syncLiveSheet: () => Promise<(string | number | null)[][] | null>;
29
+ setOverrideConfig: (config: Partial<SheetChartConfig> | null) => void;
30
+ }
31
+ export declare function useSheetChartData({ chartId, nodeId, initialDataset, pollIntervalMs, isDevMode, }: UseSheetChartDataOptions): UseSheetChartDataReturn;
@@ -0,0 +1,35 @@
1
+ import type { LiveSourceSource } from '../types/source';
2
+ export interface UseSourcePointResult {
3
+ /** The current live source source record or null if unset */
4
+ source: LiveSourceSource | null;
5
+ /** Sanitized Google Drive folder URL */
6
+ folderUrl: string;
7
+ /** Official or custom folder title */
8
+ folderTitle: string;
9
+ /** Optional editorial description */
10
+ description?: string;
11
+ /** ISO date when source was last verified */
12
+ lastVerified?: string;
13
+ /** Whether the initial background fetch is running */
14
+ isLoading: boolean;
15
+ /** Whether a mutation update is in-flight */
16
+ isUpdating: boolean;
17
+ /** Error message string if fetch or mutation failed */
18
+ error: string | null;
19
+ /** Optimistic mutation handler to update folder metadata */
20
+ updateFolder: (newUrl: string, newTitle?: string, description?: string) => Promise<LiveSourceSource>;
21
+ /** Convenience flag indicating whether a non-empty valid folder URL exists */
22
+ hasFolder: boolean;
23
+ }
24
+ /**
25
+ * useSourcePoint Hook
26
+ * Folio Engine — Subtask 5.3: Contextual Point Anchor & Integration
27
+ *
28
+ * Reactive state machine for anchoring any component or photo point across Folio Engine
29
+ * directly to a verified Google Drive folder:
30
+ * 1. Immediate synchronous resolution via getSourceSourceSync to guarantee zero layout shift.
31
+ * 2. Background live resolution against BaaS / Supabase database.
32
+ * 3. Bidirectional reactive subscriptions to cross-tab/window storage & mutation events.
33
+ * 4. Optimistic mutation handler updateFolder with automatic rollbacks on network failure.
34
+ */
35
+ export declare function useSourcePoint(pointId: string): UseSourcePointResult;
@@ -0,0 +1,30 @@
1
+ export interface SwipeGestureOptions {
2
+ onSwipeLeft?: () => void;
3
+ onSwipeRight?: () => void;
4
+ onSwipeDown?: () => void;
5
+ minDistance?: number;
6
+ disabled?: boolean;
7
+ }
8
+ export interface UseSwipeGestureResult {
9
+ onTouchStart: (e: React.TouchEvent) => void;
10
+ onTouchMove: (e: React.TouchEvent) => void;
11
+ onTouchEnd: (e: React.TouchEvent) => void;
12
+ onTouchCancel: (e: React.TouchEvent) => void;
13
+ onPointerDown: (e: React.PointerEvent) => void;
14
+ onPointerMove: (e: React.PointerEvent) => void;
15
+ onPointerUp: (e: React.PointerEvent) => void;
16
+ onPointerCancel: (e: React.PointerEvent) => void;
17
+ wasSwipeJustTriggered: () => boolean;
18
+ }
19
+ /**
20
+ * useSwipeGesture Hook
21
+ *
22
+ * Captures mobile touch and pointer interactions for native photo gallery conventions:
23
+ * - Horizontal swipe left/right for carousel navigation
24
+ * - Vertical pull-down gesture to dismiss the modal
25
+ * - Supports both Touch Events and Pointer Events with touchcancel/pointercancel resilience
26
+ * - Prevents collision with interactive elements (photo strip, buttons, links)
27
+ * - Exposes wasSwipeJustTriggered() to suppress synthetic click events after swiping
28
+ */
29
+ export declare function useSwipeGesture({ onSwipeLeft, onSwipeRight, onSwipeDown, minDistance, disabled, }: SwipeGestureOptions): UseSwipeGestureResult;
30
+ export default useSwipeGesture;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Folio Engine - Active Session Undo / Redo Hook
3
+ * Location: src/hooks/useUndoRedo.ts
4
+ * Specification: docs/tasks/task9_2_active_session_undo_redo_engine.md
5
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
6
+ */
7
+ import type { UndoRedoContextType } from '../types/history';
8
+ export declare function useUndoRedo(): UndoRedoContextType;
9
+ export default useUndoRedo;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Folio Engine - Reusable Unsaved Changes Prompt Hook
3
+ * Location: src/hooks/useUnsavedChangesPrompt.ts
4
+ * Specification: docs/tasks/task12_0_prevent_refresh_unsaved_changes.md
5
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
6
+ *
7
+ * Implements:
8
+ * 1. Automatic registration into the central unsavedChangesService.
9
+ * 2. Window beforeunload event interception for active dirty editors.
10
+ * 3. Graceful cleanup on unmount or when form resets to clean state.
11
+ */
12
+ /**
13
+ * Hook to safeguard open modals, drawers, and form editors from accidental browser refresh or closure.
14
+ *
15
+ * @param isDirty Whether the editor currently has unsaved modifications.
16
+ * @param editorId Unique identifier for this editor (e.g. 'universal-edit-modal', 'chart-config-drawer').
17
+ */
18
+ export declare function useUnsavedChangesPrompt(isDirty: boolean, editorId: string): void;
@@ -0,0 +1,53 @@
1
+ export { App } from './App';
2
+ import './styles/tokens.css';
3
+ import './styles/reset.css';
4
+ export * from './types/node';
5
+ export * from './types/canvas';
6
+ export * from './types/chart';
7
+ export * from './types/developer';
8
+ export * from './types/draft';
9
+ export * from './types/source';
10
+ export * from './types/history';
11
+ export * from './types/media';
12
+ export * from './types/navigation';
13
+ export * from './config/engine.config';
14
+ export * from './diagnostics/verifyEngineSetup';
15
+ export * from './components/feedback';
16
+ export * from './components/ui';
17
+ export * from './utils/scrollLock';
18
+ export * from './utils/modalActions';
19
+ export * from "./components/roadmap/serpentine-generator";
20
+ export * from "./components/roadmap/use-roadmap-scroll";
21
+ export * from "./components/roadmap/RoadmapNode";
22
+ export * from "./components/roadmap/RoadmapTrack";
23
+ export * from "./components/roadmap/RoadmapSection";
24
+ export * from "./hooks/use-hash-route";
25
+ export * from "./hooks/use-scroll";
26
+ export * from "./hooks/use-scrollspy";
27
+ export * from "./utils/smooth-scroll";
28
+ export * from "./components/canvas";
29
+ export * from "./hooks/useDocumentCanvas";
30
+ export * from "./hooks/useNodeCanvas";
31
+ export * from "./hooks/useLightboxHistory";
32
+ export * from "./services/canvasLayoutService";
33
+ export * from "./components/layout";
34
+ export * from "./services/draftService";
35
+ export * from "./services/historyService";
36
+ export * from "./services/historyStorage";
37
+ export * from "./services/devLockService";
38
+ export * from "./services/mediaService";
39
+ export * from "./services/sourceService";
40
+ export * from "./services/undoRedoService";
41
+ export * from "./services/unsavedChangesService";
42
+ export * from "./utils/contentDb";
43
+ export * from "./utils/storage";
44
+ export * from "./utils/devSecurity";
45
+ export * from "./utils/supabase-config";
46
+ export * from "./components/dev";
47
+ export * from "./components/history";
48
+ export * from "./context/DeveloperModeContext";
49
+ export * from "./context/UndoRedoContext";
50
+ export * from "./hooks/useDeveloperMode";
51
+ export * from "./hooks/useUndoRedo";
52
+ export * from './components/chart';
53
+ export * from './services/chartSourceService';
package/dist/main.d.ts ADDED
@@ -0,0 +1 @@
1
+ export {};