@devcabs/folio-engine 0.0.0-stage → 0.1.1

package/dist/types/history.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Folio Engine - Active Session Undo / Redo Contracts
+ * Location: src/types/history.ts
+ * Specification: docs/tasks/task9_2_active_session_undo_redo_engine.md
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
+ */
+export type UndoActionType = 'canvas_insert_section' | 'canvas_remove_section' | 'canvas_insert_subsection' | 'canvas_remove_subsection' | 'canvas_insert_leaf' | 'canvas_remove_leaf' | 'canvas_move_item' | 'canvas_relocate_item' | 'canvas_update_item' | 'content_text_override';
+export interface UndoAction {
+    id: string;
+    type: UndoActionType;
+    timestamp: number;
+    description: string;
+    /** Function that reverses the action */
+    undo: () => void;
+    /** Function that re-applies the action */
+    redo: () => void;
+}
+export interface UndoRedoState {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoCount: number;
+    redoCount: number;
+    lastActionDescription?: string;
+    nextRedoDescription?: string;
+}
+export interface UndoRedoContextType extends UndoRedoState {
+    /** Push a reversible action pair onto the active stack */
+    pushAction: (action: Omit<UndoAction, 'id' | 'timestamp'>) => void;
+    /** Execute the most recent undo action */
+    undo: () => void;
+    /** Execute the most recent redo action */
+    redo: () => void;
+    /** Clear both stacks (e.g. on dev mode exit or full restore) */
+    clearHistory: () => void;
+}
+import type { NodeCanvasDocument } from './canvas';
+export type SnapshotType = 'milestone' | 'autosave' | 'safety_backup';
+export interface UnifiedPortalSnapshot {
+    id: string;
+    schemaVersion: number;
+    type: SnapshotType;
+    title: string;
+    notes?: string;
+    createdAt: string;
+    authorSessionId: string;
+    /** Canvas layout documents for all 5 nodes keyed by node ID */
+    canvases: Record<string, NodeCanvasDocument>;
+    /** Complete key-value registry of all Content DB text overrides */
+    contentOverrides: Record<string, string>;
+    /** Metrics summary for quick scannability in UI */
+    summary: {
+        totalSections: number;
+        totalSubsections: number;
+        totalLeafElements: number;
+        totalTextOverrides: number;
+    };
+}
+export interface HistoryManifest {
+    lastRestoredId?: string;
+    activePublishedId?: string;
+    activeMilestoneId?: string;
+    snapshots: UnifiedPortalSnapshot[];
+    updatedAt: string;
+}
+export interface PublishedSnapshot {
+    id: string;
+    schemaVersion: number;
+    title: string;
+    description: string;
+    createdAt: string;
+    authorSessionId: string;
+    isActive: boolean;
+    canvases: Record<string, NodeCanvasDocument>;
+    contentOverrides: Record<string, string>;
+    summary: {
+        totalSections: number;
+        totalSubsections: number;
+        totalLeafElements: number;
+        totalTextOverrides: number;
+    };
+}

package/dist/types/media.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Folio Engine - Media & Asset Pipeline Contracts
+ * Location: src/types/media.ts
+ * Specification: docs/tasks/task11_2g_db_draft_and_blob_storage_pipeline.md
+ */
+export interface UploadMediaResult {
+    url: string;
+    sizeBytes: number;
+    format: string;
+}
+export type MediaFolder = 'photos' | 'documents' | 'source';
+export interface ImageDownscaleOptions {
+    maxDimension?: number;
+    quality?: number;
+    mimeType?: 'image/webp' | 'image/jpeg' | 'image/png';
+}

package/dist/types/navigation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical Navigation Type Contracts
+ * Document Reference: docs/07_CODING_STANDARDS.md
+ *
+ * Reusable navigation contracts across AppHeader, EditorialSidebar,
+ * Table of Contents, and Mobile Navigation Menus.
+ */
+export interface NavItem {
+    /** Display label for the navigation item */
+    label: string;
+    /** Navigation destination (URL, route hash e.g. '#stage-1', or path) */
+    href: string;
+    /** Unique element ID targeted by in-page anchors without the '#' prefix */
+    id?: string;
+    /** Optional sequence or stage number prefix (e.g. '01', '02') rendered in JetBrains Mono */
+    number?: string;
+    /** Explicit active state flag when controlled externally */
+    isActive?: boolean;
+}

package/dist/types/node.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic Sequence Node Model
+ * Document Reference: docs/tasks/task18_2_data_contracts_and_single_source_of_truth.md
+ *
+ * Parameterized milestone node model supporting dynamic sequence length (N >= 1).
+ * Completely decoupled from institutional union constraints.
+ */
+export type NodeCode = string;
+export interface NodeHeroImage {
+    src: string;
+    alt: string;
+    caption?: string;
+    showCaption?: boolean;
+}
+/** Canonical alias for hero image contract */
+export type CanonicalPhoto = NodeHeroImage;
+export interface SourceItem {
+    id: string;
+    title: string;
+    dateStamp?: string;
+    photo?: CanonicalPhoto;
+    imageSrc?: string;
+    reference?: string;
+}
+export interface StageStory {
+    step: number;
+    stageName: string;
+    narrative: string;
+}
+export interface NodeItem {
+    id: string;
+    index: number;
+    title: string;
+    subtitle?: string;
+    summary?: string;
+    tagline?: string;
+    accentColor: string;
+    accentTint?: string;
+    heroImage?: NodeHeroImage;
+    annotation?: string;
+    nodeNumber?: number;
+    stages?: StageStory[];
+    sourceItems?: SourceItem[];
+    metadata?: Record<string, unknown>;
+}
+export interface NodeNavigationLink {
+    id: string;
+    index: number;
+    title: string;
+    path: string;
+}

package/dist/types/source.d.ts

@@ -0,0 +1,88 @@
+import type { NodeCode, SourceItem } from './node';
+export interface SourceSource {
+    pointId: NodeCode | string;
+    folderUrl: string;
+    folderTitle: string;
+    description?: string;
+    lastVerified?: string;
+}
+export type SourceSourceRegistry = Record<string, SourceSource>;
+export interface DrivePhotoFile {
+    id: string;
+    name: string;
+    mimeType: string;
+    thumbnailLink?: string;
+    webContentLink?: string;
+    createdTime?: string;
+    modifiedTime?: string;
+}
+/**
+ * SyncedSourceItem
+ * Contract Unification: Directly extends Canonical SourceItem so all existing
+ * gallery, card, and lightbox components accept it without mapping overhead.
+ */
+export interface SyncedSourceItem extends SourceItem {
+    pointId?: string;
+    driveFileId: string;
+    originalFileName: string;
+    thumbnailUrl: string;
+    fullImageUrl: string;
+    isCustomTitle?: boolean;
+    orderIndex: number;
+    category?: string;
+    date?: string;
+}
+export interface DriveReconciliationStats {
+    added: number;
+    removed: number;
+    retained: number;
+    total: number;
+    hasChanged: boolean;
+}
+export interface DriveReconciliationResult {
+    items: SyncedSourceItem[];
+    stats: DriveReconciliationStats;
+}
+export type SyncState = 'never_synced' | 'syncing' | 'synced_success' | 'synced_empty' | 'sync_error';
+export interface SyncFolderPhotosResult {
+    items: SyncedSourceItem[];
+    stats: DriveReconciliationStats;
+    source: LiveSourceSource;
+}
+export interface UseDrivePhotoSyncResult {
+    syncedPhotos: SyncedSourceItem[];
+    syncState: SyncState;
+    hasSynced: boolean;
+    isSyncing: boolean;
+    error: string | null;
+    lastStats: DriveReconciliationStats | null;
+    syncPhotos: () => Promise<DriveReconciliationStats | null>;
+}
+export interface LiveSourceSource {
+    pointId: NodeCode | string;
+    folderUrl: string;
+    folderTitle: string;
+    description?: string;
+    updatedBy: string;
+    lastVerified: string;
+    createdAt: string;
+    syncedPhotos?: SyncedSourceItem[];
+}
+export type LiveSourceRegistry = Record<string, LiveSourceSource>;
+export interface UpsertSourcePayload {
+    pointId: string;
+    folderUrl: string;
+    folderTitle: string;
+    description?: string;
+    updatedBy?: string;
+    syncedPhotos?: SyncedSourceItem[];
+}
+export type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+export interface UseImageLoaderResult {
+    status: ImageLoadingStatus;
+    isLoading: boolean;
+    isLoaded: boolean;
+    isError: boolean;
+    resolvedSrc?: string;
+    retry: () => void;
+}

package/dist/utils/canvasDefaults.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Folio Engine - Default Element Generation Factory
+ * Location: src/utils/canvasDefaults.ts
+ * Specification: docs/tasks/task8_1_data_models_and_default_factory.md
+ *
+ * Rules:
+ * 1. Zero parentheses in all default copy, titles, and placeholders.
+ * 2. Pure, deterministic factory functions without DOM dependencies.
+ * 3. Canonical naming hierarchy for pointIds.
+ */
+import type { CanvasElementType, TextElement, PhotoElement, GalleryElement, ChartElement, SubsectionElement, SectionElement, NodeCanvasDocument } from '../types/canvas';
+/**
+ * Generate a unique element ID with type prefix and collision-resistant entropy.
+ */
+export declare function generateCanvasId(prefix: CanvasElementType): string;
+/**
+ * Generate a default narrative Text block.
+ */
+export declare function createDefaultText(nodeId: string): TextElement;
+/**
+ * Generate a default photographic source block.
+ */
+export declare function createDefaultPhoto(nodeId: string): PhotoElement;
+/**
+ * Generate a default photographic Evidence Gallery block.
+ */
+export declare function createDefaultGallery(nodeId: string): GalleryElement;
+/**
+ * Generate a default Indicator Chart block with pending state.
+ */
+export declare function createDefaultChart(nodeId: string): ChartElement;
+/**
+ * Generate a default mid-level Subsection container.
+ */
+export declare function createDefaultSubsection(nodeId?: string): SubsectionElement;
+/**
+ * Generate a default top-level Section container with auto-assigned numbering.
+ */
+export declare function createDefaultSection(index: number, nodeId?: string): SectionElement;
+/**
+ * Generate a default top-level versioned document for a Node canvas.
+ */
+export declare function createDefaultCanvasDocument(nodeId: string): NodeCanvasDocument;

package/dist/utils/chartColors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical Chart Color Engine & Palette System
+ * Document Reference: docs/tasks/task7_6_common_chart_engine_drawer_components.md
+ *
+ * Enforces:
+ * 1. Deduplicated base palette (replacing duplicate indices 6 & 7 with Academic Indigo and Rich Academic Teal).
+ * 2. Guaranteed intra-chart uniqueness: No chart element ever shares the same color twice.
+ * 3. Automatic Tiered Variants: When chart elements exceed 5, the engine switches to high-contrast
+ *    Super-Dark jewel shades (or Super-Light tints) to prevent collisions.
+ * 4. Token Purity: Strictly consumes CSS custom properties from tokens.css.
+ */
+import type { NodeCode } from '../types/node';
+export declare const NODE_ACCENT_TOKENS: Record<NodeCode, string>;
+/**
+ * 7 Distinct Base Palette Colors (Preserved for backward-compatibility)
+ */
+export declare const CHART_BASE_PALETTE: readonly string[];
+/**
+ * 14 Distinct Bright Palette Colors (Prioritizing vibrant, high-contrast academic hues over dull darks)
+ */
+export declare const CHART_BRIGHT_PALETTE: readonly string[];
+/**
+ * Super-Dark Jewel Tone Palette (>7:1 contrast on light canvas)
+ */
+export declare const CHART_DARK_PALETTE: readonly string[];
+/**
+ * Super-Light Pastel Tint Palette (for soft fills and secondary tiers)
+ */
+export declare const CHART_LIGHT_PALETTE: readonly string[];
+/**
+ * Normalizes synonymous institutional tokens to detect conceptual duplicates.
+ * (e.g. Node 2 #881337 is synonymous with Brand Maroon #881337)
+ */
+export declare function normalizeColorToken(token?: string): string;
+export type ChartTierMode = 'bright' | 'dark' | 'light';
+export interface ResolveColorsOptions {
+    count: number;
+    accentColor?: string;
+    tierMode?: ChartTierMode;
+}
+/**
+ * Resolves a guaranteed unique sequence of chart colors.
+ * - If accentColor is supplied, it is anchored at index 0 and removed from candidate pools.
+ * - By default (tierMode: 'bright'), all 14 vibrant bright base colors are prioritized.
+ * - If tierMode: 'dark' is requested, legacy behavior (5 base, then super-dark) is honored.
+ * - No color is ever repeated within the resolved sequence.
+ */
+export declare function resolveUniqueChartColors(options: ResolveColorsOptions): string[];

package/dist/utils/chartDimensions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Universal Viewport, Canvas & Margin Constants
+ * Document Reference: docs/tasks/task7_6_common_chart_engine_drawer_components.md
+ */
+export declare const CHART_CANVAS_DIMENSIONS: {
+    readonly viewBoxWidth: 800;
+    readonly viewBoxHeight: 360;
+    readonly margins: {
+        readonly top: 28;
+        readonly right: 32;
+        readonly bottom: 48;
+        readonly left: 56;
+    };
+    readonly compactMargins: {
+        readonly top: 16;
+        readonly right: 16;
+        readonly bottom: 36;
+        readonly left: 44;
+    };
+};
+export interface ChartPlotMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface ChartPlotAreaOptions {
+    width?: number;
+    height?: number;
+    margins?: Partial<ChartPlotMargins>;
+    dynamicLeftMargin?: number;
+    isCompact?: boolean;
+}
+export interface ChartPlotAreaResult {
+    width: number;
+    height: number;
+    margin: ChartPlotMargins;
+    innerWidth: number;
+    innerHeight: number;
+    baselineY: number;
+}
+/**
+ * Pure calculation function for chart plot area bounds, baseline, and dynamic category margins.
+ */
+export declare function calculateChartPlotArea(options?: ChartPlotAreaOptions): ChartPlotAreaResult;
+/**
+ * Unified Plot Area Calculation Hook.
+ * Calculates inner dimensions and baseline across all Folio Engine chart engines.
+ */
+export declare function useChartPlotArea(options?: ChartPlotAreaOptions): ChartPlotAreaResult;

package/dist/utils/chartMath.d.ts

@@ -0,0 +1,142 @@
+/**
+ * D3 Math Primitives & Geometric Scaling Utilities
+ * Document Reference: docs/tasks/task7_1_contracts_d3_math_sanitizer.md
+ *
+ * Lightweight mathematical wrappers around tree-shakable d3-scale and d3-array modules.
+ * Strictly adheres to bundle-barrel-imports (direct subpackage imports) and js-early-exit.
+ */
+import { type ScaleLinear, type ScaleBand } from 'd3-scale';
+import type { ChartSeries, ScatterPoint } from '../types/chart';
+export interface Point2D {
+    x: number;
+    y: number;
+}
+export interface ComputedBin {
+    x0: number;
+    x1: number;
+    count: number;
+}
+/**
+ * Creates a continuous linear scale with optional domain rounding (.nice())
+ */
+export declare function createLinearScale(domain: [number, number], range: [number, number], nice?: boolean): ScaleLinear<number, number>;
+/**
+ * Creates a discrete band scale for categorical bar positioning
+ */
+export declare function createBandScale(domain: string[], range: [number, number], padding?: number): ScaleBand<string>;
+export declare const HUMAN_FRIENDLY_STEPS: number[];
+export declare function roundToHumanFriendlyStep(raw: number): number;
+/**
+ * Calculates optimal bin width using the Freedman-Diaconis Rule:
+ * h = 2 * IQR(x) / cbrt(N)
+ * Rounded to the nearest human-friendly interval step (1, 2, 5, 10, 20, 25, 50, 100).
+ */
+export declare function calculateFreedmanDiaconisBinWidth(data: number[]): number;
+export interface SummaryStats {
+    n: number;
+    mean: number;
+    median: number;
+    mode?: number | string;
+    stdDev: number;
+}
+/**
+ * Calculates sample size, mean, median, mode, and sample standard deviation
+ */
+export declare function computeSummaryStats(data: number[]): SummaryStats;
+export interface HistogramBinOptions {
+    strategy?: 'auto' | 'custom';
+    binCount?: number;
+    bucketSize?: number;
+    min?: number;
+    max?: number;
+}
+/**
+ * Computes frequency distribution bins with standard half-open intervals [x0, x1),
+ * with the maximum value included in the final bin [xk-1, xk].
+ */
+export declare function computeHistogramBins(data: number[], options?: number | HistogramBinOptions): ComputedBin[];
+/**
+ * Calculates extent [min, max] safely ignoring nulls, NaNs, and infinite values
+ */
+export declare function computeDataExtent(values: (number | null)[]): [number, number];
+/**
+ * Generates a smooth cubic Bézier SVG path string ("M... C...") for line charts
+ */
+export declare function generateCubicBezierPath(points: Point2D[]): string;
+/**
+ * Generates a straight linear SVG path string ("M... L...") for line charts
+ */
+export declare function generateStraightLinePath(points: Point2D[]): string;
+export interface CornerRadii {
+    tl?: number;
+    tr?: number;
+    br?: number;
+    bl?: number;
+}
+/**
+ * Generates an SVG path string for a rectangle with individual corner radii.
+ * Essential for stacked bar charts where interior/middle boundaries must have 0 radius.
+ */
+export declare function createRoundedRectPath(x: number, y: number, w: number, h: number, radii?: CornerRadii): string;
+/**
+ * Universal Two-Dropdown Sorting Engine
+ * Sorts tabular categories and series data consistently by category name, series values, or original order.
+ */
+export declare function applyChartSorting(categories: string[], series: ChartSeries[], sortField?: string, sortDirection?: 'asc' | 'desc'): {
+    categories: string[];
+    series: ChartSeries[];
+};
+export interface LinearRegressionResult {
+    slope: number;
+    intercept: number;
+    r: number;
+    rSquared: number;
+    n: number;
+}
+/**
+ * Computes standard least-squares linear regression (y = mx + b),
+ * Pearson correlation coefficient (r), and coefficient of determination (R²).
+ */
+export declare function computeLinearRegression(points: ScatterPoint[]): LinearRegressionResult;
+export interface ConfidenceBandPoint {
+    x: number;
+    y0: number;
+    y1: number;
+}
+/**
+ * Computes 95% confidence interval ribbon bounds around the linear regression line.
+ */
+export declare function computeConfidenceBand(points: ScatterPoint[], m: number, b: number): ConfidenceBandPoint[];
+/**
+ * Computes 95% confidence interval ribbon bounds along a non-linear curve (Polynomial or LOESS).
+ */
+export declare function computeCurveConfidenceBand(points: ScatterPoint[], curvePoints: Point2D[], degreesOfFreedom?: number): ConfidenceBandPoint[];
+/**
+ * Computes locally estimated scatterplot smoothing (LOESS) curve coordinates
+ * using a tricube kernel weight.
+ */
+export declare function computeLoessCurve(points: ScatterPoint[], bandwidth?: number): Point2D[];
+export interface CohortMeans {
+    meanX: number;
+    meanY: number;
+}
+/**
+ * Computes cohort averages (meanX, meanY) for mean quadrant crosshair guides.
+ */
+export declare function computeCohortMeans(points: ScatterPoint[]): CohortMeans;
+/**
+ * Sorts scatter plot points by sheet order, x, y, point label, or group name.
+ */
+export declare function sortScatterPoints(points: ScatterPoint[], sortField?: string, sortDirection?: 'asc' | 'desc'): ScatterPoint[];
+export interface PolynomialRegressionResult {
+    a: number;
+    b: number;
+    c: number;
+    rSquared: number;
+    points: Point2D[];
+}
+/**
+ * Computes quadratic polynomial regression (y = a*x^2 + b*x + c)
+ * Solves the normal equations using Cramer's rule and samples smooth curve coordinates.
+ */
+export declare function computePolynomialRegression(points: ScatterPoint[], sampleCount?: number): PolynomialRegressionResult;

package/dist/utils/chartSanitizer.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Tabular Data Sanitizer & Range Parser
+ * Document Reference: docs/tasks/task7_1_contracts_d3_math_sanitizer.md
+ *
+ * Enforces pure numbers (never coerces missing values/errors into 0),
+ * canonical string sanitization, automatic summary row detection,
+ * bounding box cell range parsing, and public CSV receipt generation.
+ */
+import type { ChartSeries } from '../types/chart';
+export interface CellCoordinate {
+    col: number;
+    row: number;
+}
+export interface BoundingBoxRange {
+    sheetName?: string;
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow?: number;
+}
+/**
+ * Trims whitespace and collapses consecutive spaces into single spaces.
+ */
+export declare function sanitizeString(val: unknown): string;
+/**
+ * Parses numeric cell values strictly preserving null for blanks or formula errors.
+ * Never coerces empty cells, hyphens, or errors into 0.
+ */
+export declare function parsePureNumber(val: unknown): number | null;
+/**
+ * Extracts semantic units enclosed in parentheses or brackets from column headers.
+ * e.g., "Enrolment (learners)" -> "learners", "Budget [₱]" -> "₱", "Passing Rate (%)" -> "%"
+ */
+export declare function extractHeaderUnit(header: string): string | null;
+/**
+ * Checks if a row label represents an aggregate summary row (Total, Grand Total, Average, Mean)
+ */
+export declare function isSummaryRow(rowLabel: string): boolean;
+/**
+ * Converts spreadsheet column letters to 0-indexed column number (e.g., A -> 0, Z -> 25, AA -> 26).
+ */
+export declare function colLetterToIndex(letters: string): number;
+/**
+ * Converts 0-indexed column number to spreadsheet column letters (e.g., 0 -> A, 25 -> Z, 26 -> AA).
+ */
+export declare function indexToColLetter(index: number): string;
+/**
+ * Parses ranges such as "A5:D12", "A1:D", "A:D", "Sheet1!B2:F20", or "'Enrolment Summary'!A1:C15"
+ * into bounding 0-indexed grid coordinates. Supports open-ended column ranges.
+ */
+export declare function parseRangeNotation(rangeStr: string): BoundingBoxRange | null;
+/**
+ * Detects the bounding cell range of filled content within a 2D sheet matrix.
+ * Determines the minimum and maximum row and column indices containing non-empty cells,
+ * and returns the bounding A1-notation range (e.g. "A1:D14"), or null if matrix is empty.
+ */
+export declare function detectFilledRange(matrix: (string | number | null)[][]): string | null;
+/**
+ * Generates an RFC 4180-compliant public CSV blob with all internal URLs and sensitive metadata stripped.
+ */
+export declare function generatePublicCsv(categories: string[], series: ChartSeries[], title?: string, unit?: string): string;
+/**
+ * Formats a timestamp string safe for filesystem usage (e.g. "2026-10-24_032503").
+ */
+export declare function formatFilenameTimestamp(date?: Date): string;
+/**
+ * Strips or replaces filesystem-reserved and control characters.
+ */
+export declare function sanitizeFilename(name: string): string;
+export interface CsvFilenameOptions {
+    title?: string | null;
+    sheetName?: string | null;
+    chartId?: string | null;
+    date?: Date;
+}
+/**
+ * Generates the CSV export filename.
+ * Rules:
+ * - Uses the Chart Title if present.
+ * - If absent, falls back to the Sheet Name (tab name).
+ * - If both are absent, falls back to chartId or 'chart-data'.
+ * - Appends a timestamp: `${cleanBase}_${timestamp}.csv`
+ */
+export declare function generateCsvDownloadFilename(options: CsvFilenameOptions): string;