@devcabs/folio-engine 0.0.0-stage → 0.1.0

package/dist/components/ui/Breadcrumb.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+export interface BreadcrumbItem {
+    id?: string;
+    label: React.ReactNode;
+    href?: string;
+    onClick?: (e: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void;
+    isCurrent?: boolean;
+    icon?: React.ReactNode;
+    badge?: React.ReactNode;
+}
+export interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+    separator?: React.ReactNode;
+    className?: string;
+    ariaLabel?: string;
+    endSlot?: React.ReactNode;
+}
+/**
+ * Canonical Breadcrumb Navigation Component
+ *
+ * Implements W3C Breadcrumb Pattern:
+ * - Landmark `<nav aria-label="...">` wrapping `<ol>` and `<li>` elements
+ * - `aria-current="page"` on current terminal items
+ * - Universal Zero Outline Policy compliant
+ * - Pure token-driven styling (zero hardcoded values)
+ * - Optional endSlot for auxiliary status markers or page badges
+ */
+export declare const Breadcrumb: React.FC<BreadcrumbProps>;
+export default Breadcrumb;

package/dist/components/ui/Button.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+export type ButtonVariant = 'revolving-outline' | 'primary' | 'secondary' | 'ghost' | 'admin';
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+export interface ButtonProps {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    outlineWidth?: number | string;
+    revolving?: boolean;
+    pulse?: boolean;
+    as?: 'button' | 'a';
+    href?: string;
+    type?: 'button' | 'submit' | 'reset';
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+    onMouseEnter?: (e: React.MouseEvent<HTMLElement>) => void;
+    onMouseLeave?: (e: React.MouseEvent<HTMLElement>) => void;
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+    'aria-label'?: string;
+    title?: string;
+    disabled?: boolean;
+    target?: string;
+    rel?: string;
+    id?: string;
+    tabIndex?: number;
+    'aria-hidden'?: boolean | 'true' | 'false';
+    ref?: React.Ref<HTMLButtonElement>;
+    [key: `data-${string}`]: unknown;
+}
+export declare const Button: React.FC<ButtonProps>;
+export default Button;

package/dist/components/ui/ColumnSelect.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface DetectedColumnOption {
+    index: number;
+    label: string;
+    type?: 'text' | 'number';
+}
+export interface ColumnSelectProps {
+    id: string;
+    label: string;
+    value: number;
+    onChange: (colIndex: number) => void;
+    columns: DetectedColumnOption[];
+    expectedType?: 'text' | 'number';
+    hint?: string;
+    className?: string;
+}
+export declare const ColumnSelect: React.FC<ColumnSelectProps>;

package/dist/components/ui/ColumnTypeBadge.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export interface ColumnTypeBadgeProps {
+    type: 'text' | 'number';
+    className?: string;
+}
+export declare const ColumnTypeBadge: React.FC<ColumnTypeBadgeProps>;

package/dist/components/ui/DevHelpTooltip.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+export interface DevHelpTooltipProps {
+    /** Explanatory help guidance shown on hover */
+    text: string;
+    /** Accessible concept name for screen readers */
+    label?: string;
+    /** Optional custom class for the trigger button */
+    className?: string;
+}
+export declare const DevHelpTooltip: React.FC<DevHelpTooltipProps>;
+export default DevHelpTooltip;

package/dist/components/ui/DraggableRows.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+export interface DraggableRowItemMeta {
+    index: number;
+    isDragging: boolean;
+    isDragOver: boolean;
+    moveUp: () => void;
+    moveDown: () => void;
+    canMoveUp: boolean;
+    canMoveDown: boolean;
+}
+export interface DraggableRowsProps<T> {
+    items: T[];
+    keyExtractor: (item: T, index: number) => string | number;
+    onReorder: (newItems: T[]) => void;
+    renderItem: (item: T, meta: DraggableRowItemMeta) => React.ReactNode;
+    showMicroArrows?: boolean;
+    className?: string;
+    ariaLabel?: string;
+}
+export declare function DraggableRows<T>({ items, keyExtractor, onReorder, renderItem, showMicroArrows, className, ariaLabel, }: DraggableRowsProps<T>): React.JSX.Element;
+export default DraggableRows;

package/dist/components/ui/Drawer.d.ts

@@ -0,0 +1,50 @@
+import React from 'react';
+export interface DrawerTabItem {
+    id: string | number;
+    label: React.ReactNode;
+    badge?: React.ReactNode;
+    disabled?: boolean;
+    completed?: boolean;
+}
+export interface DrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: React.ReactNode;
+    kicker?: React.ReactNode;
+    headerActions?: React.ReactNode;
+    showCloseButton?: boolean;
+    closeOnOutsideClick?: boolean;
+    closeOnBackdropClick?: boolean;
+    position?: 'right' | 'left';
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    tabs?: DrawerTabItem[];
+    activeTab?: string | number;
+    onTabChange?: (tabId: string | number) => void;
+    tabsContent?: React.ReactNode;
+    footer?: React.ReactNode;
+    footerLeft?: React.ReactNode;
+    footerRight?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+    bodyClassName?: string;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    ariaDescribedBy?: string;
+    onConfirm?: () => void | Promise<void>;
+    enableCtrlEnter?: boolean;
+    companionContent?: React.ReactNode;
+}
+/**
+ * Drawer Component
+ * Folio Engine — Canonical Modern Academic Editorial Slide-Out Drawer
+ *
+ * Adheres strictly to:
+ * 1. Background blur with frosted glass tokens (var(--backdrop-blur), var(--overlay-scrim)).
+ * 2. Synchronous body scroll locking with desktop scrollbar jitter compensation.
+ * 3. First-class tabbed/stepper layout with accessible ARIA semantics.
+ * 4. Sticky drawer footer with flexible button placeholders.
+ * 5. Universal Zero Outline Policy & pure token styling.
+ * 6. Optional companionContent rendering into remaining viewport area.
+ */
+export declare const Drawer: React.FC<DrawerProps>;
+export default Drawer;

package/dist/components/ui/DrawerTier.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export interface DrawerTierProps {
+    title: string;
+    subtitle?: string;
+    children: React.ReactNode;
+    className?: string;
+}
+export declare const DrawerTier: React.FC<DrawerTierProps>;

package/dist/components/ui/EditableText.d.ts

@@ -0,0 +1,48 @@
+import React from 'react';
+export interface EditableTextProps {
+    /** Dynamic content key in Content DB (e.g. 'hero.title', 'footer.orgName') */
+    pointId: string;
+    /** Hardcoded initial fallback text */
+    defaultText: string;
+    /** HTML element or component to render as (defaults to 'span') */
+    as?: React.ElementType;
+    /** Optional CSS class name */
+    className?: string;
+    /** Optional wrapper CSS class name for dev mode affordance */
+    wrapperClassName?: string;
+    /** Optional inline styles */
+    style?: React.CSSProperties;
+    /** Optional child element or render prop `(text: string) => React.ReactNode` */
+    children?: React.ReactNode | ((resolvedText: string) => React.ReactNode);
+    /** Accessibility label */
+    ariaLabel?: string;
+    /** Direct update handler if custom action needed on save */
+    onSave?: (newValue: string) => void;
+    /** Direct reset handler */
+    onReset?: () => void;
+    /** Optional custom edit handler to intercept edit clicks and delegate up */
+    onEditText?: () => void;
+    /** Whether to render as an inline container in dev mode */
+    inline?: boolean;
+    /** Whether the target content belongs to a section heading */
+    isSection?: boolean;
+    /** Whether the section is currently numbered */
+    isNumbered?: boolean;
+    /** Default numbering fallback */
+    defaultNumbered?: boolean;
+    /** Callback when section numbering is toggled */
+    onNumberedChange?: (isNumbered: boolean) => void;
+    /** Optional deterministic trigger identifier for canvas controls targeting */
+    editTriggerId?: string;
+}
+/**
+ * EditableText Component (Canonical Typography Primitive)
+ *
+ * Implements universal in-place editing across all portal views in Developer Mode:
+ * - Reads reactively from Content DB via useContent
+ * - Displays discrete '✎ Edit' button on hover when Developer Mode is active (PIN 1997)
+ * - Returns pure rendered content with ZERO wrapping markup in public mode
+ * - Strictly adheres to Uniform Administrative Edit Button Standard and Universal Zero Outline Policy
+ */
+export declare const EditableText: React.FC<EditableTextProps>;
+export default EditableText;

package/dist/components/ui/FAB.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+export interface FABProps {
+    label: string;
+    isVisible: boolean;
+    position?: 'left' | 'right';
+    direction?: 'down' | 'up';
+    revolving?: boolean;
+    pulse?: boolean;
+    onClick: (e?: React.MouseEvent) => void;
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * FAB Component (Floating Action Button) — Folio Engine
+ *
+ * All FABs are designed as a revolving variant of the button:
+ * - Positioned at bottom-left or bottom-right with dynamic keyboard & visual viewport adjustment
+ * - Conic gradient revolving outline border
+ * - Attention-grabbing flick micro-motion & golden halo flash (every 1.5s)
+ * - Directional motion cues: ↓ for advancing to next stage, ↑ for Previous or Back to Top
+ * - Spring-interpolated entrance and exit animations
+ */
+export declare const FAB: React.FC<FABProps>;
+export default FAB;

package/dist/components/ui/Modal.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+export interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: React.ReactNode;
+    children: React.ReactNode;
+    maxWidth?: string | number;
+    className?: string;
+    cardClassName?: string;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    ariaDescribedBy?: string;
+    showCloseButton?: boolean;
+    role?: 'dialog' | 'alertdialog';
+    'aria-modal'?: boolean | 'true' | 'false';
+    closeOnOutsideClick?: boolean;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    onConfirm?: () => void | Promise<void>;
+    enableCtrlEnter?: boolean;
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+}
+export declare const Modal: React.FC<ModalProps>;
+export default Modal;

package/dist/components/ui/PageTitle.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+export interface PageTitleProps {
+    /** Main page headline (rendered as a semantic h1) */
+    title: string;
+    /** Content DB pointId for live editing */
+    titlePointId?: string;
+    /** Optional institutional eyebrow/kicker above the title */
+    kicker?: string;
+    /** Content DB pointId for kicker */
+    kickerPointId?: string;
+    /** Optional descriptive subtitle or summary below the title */
+    subtitle?: string;
+    /** Content DB pointId for subtitle */
+    subtitlePointId?: string;
+    /** Optional institutional accent color (defaults to var(--folio-primary)) */
+    accentColor?: string;
+    /** Optional custom CSS class */
+    className?: string;
+    /** Optional supplementary elements or action slots */
+    children?: React.ReactNode;
+}
+/**
+ * PageTitle Component (Canonical Typography Primitive)
+ *
+ * Implements Modern Academic Editorial page heading:
+ * - Single h1 per page for strict SEO and document outline hierarchy
+ * - Elegant serif typography (Fraunces) with tightened editorial tracking
+ * - High-contrast readable lead subtitle
+ * - Pure token-driven styling
+ * - Integrated live editing via Content DB pointIds
+ */
+export declare const PageTitle: React.FC<PageTitleProps>;
+export default PageTitle;

package/dist/components/ui/ParametricShape.d.ts

@@ -0,0 +1,57 @@
+import React from 'react';
+export interface WavyPolygonOptions {
+    /** Number of polygon lobes/sides (default: 5) */
+    sides?: number;
+    /** Base radius in coordinate space (default: 50) */
+    radius?: number;
+    /** Wave amplitude: crest height vs trough depth (default: 10, or 0-1 as fraction of radius) */
+    waviness?: number;
+    /** Corner roundness factor / tangent handle tension (default: 1) */
+    roundness?: number;
+    /** Outline path stroke width (default: 12) */
+    strokeWidth?: number;
+}
+export interface WavyPolygonResult {
+    pathData: string;
+    viewBox: string;
+}
+/**
+ * Mathematically generates an auto-centered, tangent-continuous closed cubic-bezier wavy polygon path
+ * with an auto-fitted viewBox that guarantees zero clipping.
+ */
+export declare function generateWavyPolygonPath({ sides, radius, waviness, roundness, strokeWidth, }?: WavyPolygonOptions): WavyPolygonResult;
+/**
+ * Computes an SVG closed path string using the parametric rosette formula.
+ */
+export declare function generateParametricPath(sides?: number, waviness?: number, radius?: number): string;
+export interface ParametricShapeProps extends WavyPolygonOptions {
+    /** Size preset or custom pixel number */
+    size?: 'sm' | 'md' | 'lg' | number;
+    /** Outline path stroke width (default: 12) */
+    strokeWidth?: number;
+    /** Optional glyph or letter centered in the outline (e.g. "P") */
+    letter?: string;
+    /** Custom additional CSS class */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+    /** SVG fill color if rendering direct vector */
+    fill?: string;
+    /** SVG stroke color */
+    stroke?: string;
+    /** Accessibility label */
+    ariaLabel?: string;
+    /** Whether screen readers should ignore the visual mark */
+    ariaHidden?: boolean;
+    /** Optional child elements */
+    children?: React.ReactNode;
+}
+/**
+ * ParametricShape — Parametric Geometric Brand Mark
+ * Renders an auto-centered, tangent-continuous cubic-Bézier wavy polygon
+ * with CSS `--gradient-conic` design token masking or direct SVG fill.
+ */
+export declare const ParametricShape: React.FC<ParametricShapeProps>;
+export default ParametricShape;
+export { ParametricShape as EnzoLogo };
+export type { ParametricShapeProps as EnzoLogoProps };

package/dist/components/ui/RevolvingButton.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import { ButtonProps } from './Button';
+export type RevolvingButtonProps = Omit<ButtonProps, 'variant'>;
+export declare const RevolvingButton: React.FC<RevolvingButtonProps>;
+export default RevolvingButton;

package/dist/components/ui/SectionTitle.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+export interface SectionTitleProps {
+    /** The primary section title text */
+    title: string;
+    /** Content DB pointId for title */
+    titlePointId?: string;
+    /** Optional section numbering (e.g. "01", 1, or "Section 01") */
+    number?: string | number | null;
+    /** Optional default numbered status (defaults to true if number was specified) */
+    defaultNumbered?: boolean;
+    /** @deprecated Subtitles removed for sections: only the page title gets a subtitle */
+    subtitle?: string;
+    /** @deprecated Subtitles removed for sections: only the page title gets a subtitle */
+    subtitlePointId?: string;
+    /** Heading level tag to render (defaults to "h2") */
+    as?: 'h2' | 'h3' | 'h4' | 'h5';
+    /** Optional element ID for in-page anchor linking */
+    id?: string;
+    /** Optional accent color for visual branding */
+    accentColor?: string;
+    /** Optional custom CSS class */
+    className?: string;
+    /** Optional supplementary elements or action slots */
+    children?: React.ReactNode;
+    /** Optional deterministic trigger identifier for canvas controls targeting */
+    editTriggerId?: string;
+    /** Optional custom edit callback to delegate to parent coordinator */
+    onEdit?: () => void;
+}
+/**
+ * SectionTitle Component (Canonical Typography Primitive)
+ *
+ * Implements Modern Academic Editorial section titles:
+ * - Uses the editorial serif font (Fraunces) for BOTH numbered and unnumbered sections
+ * - Serif section numbering (italic or classical numeral)
+ * - Configurable heading level (defaults to h2)
+ * - Pure token-driven styling
+ * - Integrated live editing via Content DB pointIds
+ * - Subtitles removed: only the page title (PageTitle) gets a subtitle
+ */
+export declare const SectionTitle: React.FC<SectionTitleProps>;
+export default SectionTitle;

package/dist/components/ui/SeriesSelectToolbar.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export interface SeriesSelectToolbarProps {
+    title?: string;
+    selectedCount?: number;
+    totalCount?: number;
+    onSelectAll: () => void;
+    onClear: () => void;
+    className?: string;
+}
+export declare const SeriesSelectToolbar: React.FC<SeriesSelectToolbarProps>;

package/dist/components/ui/StatusPill.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+export type StatusPillVariant = 'white' | 'primary' | 'accent' | 'green' | 'blue' | 'amber' | 'neutral' | 'mono' | 'link' | 'interactive';
+export type StatusPillSize = 'sm' | 'md';
+export interface StatusPillProps {
+    label: React.ReactNode;
+    variant?: StatusPillVariant;
+    size?: StatusPillSize;
+    icon?: React.ReactNode;
+    pulse?: boolean;
+    href?: string;
+    target?: string;
+    rel?: string;
+    type?: 'button' | 'submit' | 'reset';
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+    className?: string;
+    ariaLabel?: string;
+    title?: string;
+    showExternalIcon?: boolean;
+}
+export declare const StatusPill: React.FC<StatusPillProps>;
+export default StatusPill;

package/dist/components/ui/TieredSlider.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+export interface TieredSliderTier {
+    value: number;
+    label: string;
+    sublabel?: string;
+}
+export interface TieredSliderProps {
+    id: string;
+    label: string;
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    tiers?: TieredSliderTier[];
+    badgeFormatter?: (val: number) => string;
+    onChange: (val: number) => void;
+    disabled?: boolean;
+}
+export declare const TieredSlider: React.FC<TieredSliderProps>;

package/dist/components/ui/Toast.d.ts

@@ -0,0 +1 @@
+export * from '../feedback/Toast';

package/dist/components/ui/ValueLabelToggle.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export interface ValueLabelToggleProps {
+    id?: string;
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    label?: string;
+    hint?: string;
+    className?: string;
+}
+export declare const ValueLabelToggle: React.FC<ValueLabelToggleProps>;

package/dist/components/ui/index.d.ts

@@ -0,0 +1,21 @@
+export * from './Button';
+export * from './Drawer';
+export * from './Modal';
+export * from './StatusPill';
+export * from './Breadcrumb';
+export * from './AccordionSection';
+export * from './DrawerTier';
+export * from './FAB';
+export * from './RevolvingButton';
+export * from './ParametricShape';
+export * from './ColumnSelect';
+export * from './ColumnTypeBadge';
+export * from './DraggableRows';
+export * from './SeriesSelectToolbar';
+export * from './TieredSlider';
+export * from './ValueLabelToggle';
+export * from './DevHelpTooltip';
+export * from './EditableText';
+export * from './PageTitle';
+export * from './SectionTitle';
+export * from './Toast';

package/dist/config/engine.config.d.ts

@@ -0,0 +1,31 @@
+import type { NodeItem } from "../types/node";
+export interface EngineBrandingConfig {
+    appName: string;
+    tagline?: string;
+    logoText?: string;
+    markSides?: number;
+    markWaviness?: number;
+    heroKicker?: string;
+    heroTitle?: string;
+    heroSubtitle?: string;
+    orgName?: string;
+}
+export interface EngineConfig {
+    appId: string;
+    appNamespace: string;
+    nodes: NodeItem[];
+    branding: EngineBrandingConfig;
+    securitySalt?: string;
+    expectedPinHash?: string;
+    features?: {
+        enableChartDrawer?: boolean;
+        enableEditorMode?: boolean;
+        enableHistoryLedger?: boolean;
+    };
+}
+export declare function createDefaultEngineConfig(overrides?: Partial<EngineConfig>): EngineConfig;
+export declare function getEngineConfig(): EngineConfig;
+export declare function setEngineConfig(config: Partial<EngineConfig>): EngineConfig;
+export declare function resetEngineConfig(): void;
+export declare function getStorageNamespace(): string;
+export declare function getStorageKey(key: string, namespace?: string): string;

package/dist/context/DeveloperModeContext.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { DeveloperModeContextType } from '../types/developer';
+declare const DeveloperModeContext: React.Context<DeveloperModeContextType | null>;
+export interface DeveloperModeProviderProps {
+    children: React.ReactNode;
+    securitySalt?: string;
+    expectedPinHash?: string;
+}
+export declare const DeveloperModeProvider: React.FC<DeveloperModeProviderProps>;
+export declare const useDeveloperMode: () => DeveloperModeContextType;
+export default DeveloperModeContext;

package/dist/context/UndoRedoContext.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Folio Engine - Active Session Undo / Redo Context
+ * Location: src/context/UndoRedoContext.tsx
+ * 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
+ *
+ * Implements:
+ * 1. Global UndoRedoProvider wrapping the application.
+ * 2. React 19 startTransition to guarantee non-blocking layout reconciliations (rerender-transitions).
+ * 3. Unified keyboard shortcut handling (Cmd+Z / Ctrl+Z / Cmd+Shift+Z / Ctrl+Shift+Z / Ctrl+Y).
+ * 4. Resilient input focus guards (isTextInput) to prevent shortcut collisions with native inputs.
+ */
+import React from 'react';
+import type { UndoRedoContextType } from '../types/history';
+export declare const UndoRedoContext: React.Context<UndoRedoContextType | null>;
+export interface UndoRedoProviderProps {
+    children: React.ReactNode;
+}
+export declare const UndoRedoProvider: React.FC<UndoRedoProviderProps>;
+export default UndoRedoProvider;