react-reason-editor-sidebar 0.1.0

package/dist/layout/sidebar/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module sidebar/index
+ * @description Barrel export for the sidebar "contract": the shared types
+ * and pure panel-toggle config/helpers that the Sidebar/SidebarContent
+ * components (this package) implement, and that `react-reason-editor`'s
+ * ReasonDocs/RightPanel type their `SidebarComponent`/
+ * `SidebarContentComponent` props against.
+ */
+export * from './types';
+export * from './panelOptions';

package/dist/layout/sidebar/panelOptions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module sidebar/panelOptions
+ * @description Shared metadata and pure helpers for the per-side panel
+ * toggle system (Open Tabs / Files / Outline / Related / AI) used by both
+ * the left sidebar and the right panel, and by the {@link SidebarViewMenu}
+ * dropdown that controls them.
+ */
+import { type LucideIcon } from 'lucide-react';
+import type { SidebarPanelType } from './types';
+/**
+ * Ordered list of togglable panel kinds shown in the view menu, with display
+ * metadata. This order is also the canonical stacking order for the panels
+ * within a sidebar (Open Tabs always stacks above the Files tree).
+ */
+export declare const PANEL_OPTIONS: {
+    type: SidebarPanelType;
+    label: string;
+    icon: LucideIcon;
+}[];
+/**
+ * Sorts a panel list into the canonical stacking order defined by
+ * {@link PANEL_OPTIONS} (e.g. Open Tabs above Files), regardless of the
+ * order the panels were toggled on in.
+ */
+export declare function sortPanels(panels: SidebarPanelType[]): SidebarPanelType[];
+/**
+ * Computes the next panel list when a single panel checkbox is toggled.
+ *
+ * Panels are independently added/removed and may stack; whether a side is
+ * "split" is inferred from the result (2 or more panels selected) rather
+ * than being a separate mode.
+ *
+ * @param panels - Current panels visible on this side.
+ * @param type - The panel being toggled.
+ * @param allowEmpty - Whether the resulting list may become empty (hides the side entirely).
+ */
+export declare function togglePanel(panels: SidebarPanelType[], type: SidebarPanelType, allowEmpty: boolean): SidebarPanelType[];

package/dist/layout/sidebar/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @module sidebar/types
+ * @description The sidebar "contract" owned by reason-editor: SidebarProps,
+ * SidebarContentProps, and the panel-based view configuration types. The
+ * actual sidebar UI (Sidebar, SidebarContent, SidebarToolbar, SidebarFooter,
+ * SidebarViewMenu) lives in the separate `react-reason-editor-sidebar`
+ * package and is injected into ReasonDocs/RightPanel via props typed
+ * against these interfaces, so reason-editor never imports that package
+ * directly (avoiding a circular workspace dependency).
+ */
+import type { RefObject } from "react";
+import { Document } from "../../documents/DocumentTree";
+import type { TocEntry } from "../../app-types/toc";
+import type { ActiveHeadingEditorHandle } from "../../search/useActiveHeading";
+import type { DocumentTreeHandle } from "../../file-tree/filetree";
+import type { OutlineViewHandle } from "../../search/OutlineView";
+/** A single togglable panel kind that can appear in the left or right sidebar. */
+export type SidebarPanelType = "ai" | "files" | "outline" | "openTabs" | "related";
+/** The kind of resource a tab in the "Open Tabs" panel represents. */
+export type OpenTabKind = "file" | "chat";
+/**
+ * A single entry in the unified "Open Tabs" list. When provided, this
+ * overrides the legacy document-only tab rendering so tabs for other
+ * resource kinds (e.g. chat conversations) can be interleaved with files.
+ */
+export interface OpenTabItem {
+    id: string;
+    title: string;
+    kind: OpenTabKind;
+}
+/** Shared AI-suggestion props needed to render an "ai" panel. */
+export interface SidebarAiProps {
+    isAiLoading?: boolean;
+    aiSuggestion?: {
+        originalText: string;
+        suggestedText: string;
+        range: {
+            from: number;
+            to: number;
+        };
+        mode?: string;
+    } | null;
+    onAiApprove?: () => void;
+    onAiReject?: () => void;
+    onAiRegenerate?: (mode: any) => void;
+}
+/**
+ * AI-generated tips about the currently active document, shown as a section
+ * of the "ai" panel. Omitted entirely (and the section hidden) when the
+ * host app has no tips-generation capability to offer.
+ */
+export interface SidebarTipsProps {
+    /** Tips generated for the active document by the most recent request. */
+    tips?: string[];
+    /** Whether a tips-generation request is in flight. */
+    isTipsLoading?: boolean;
+    /** Requests (re)generation of tips for the active document. */
+    onGenerateTips?: () => void;
+}
+/**
+ * AI-generated suggested search queries ("topics") related to the currently
+ * active document, shown as a section of the "related" panel. Omitted
+ * entirely (and the section hidden) when the host app has no
+ * topics-generation capability to offer.
+ */
+export interface SidebarTopicsProps {
+    /** Suggested search queries generated for the active document by the most recent request. */
+    topics?: string[];
+    /** Whether a topics-generation request is in flight. */
+    isTopicsLoading?: boolean;
+    /** Requests (re)generation of topics for the active document. */
+    onGenerateTopics?: () => void;
+    /** Runs a search for the given topic (e.g. opens a new chat seeded with it). */
+    onSearchTopic?: (topic: string) => void;
+}
+export interface SidebarProps {
+    documents: Document[];
+    activeId: string | null;
+    activeDocument: Document | undefined;
+    onSelect: (id: string) => void;
+    onAdd: (parentId: string | null, isFolder?: boolean) => void;
+    onDelete: (id: string) => void;
+    onDuplicate: (id: string) => void;
+    onToggleExpand: (id: string) => void;
+    /**
+     * Replaces the set of expanded folders wholesale, used by the toolbar's
+     * expand/collapse toggle as it steps through folder levels. Hosts should
+     * persist it the same way they persist `onToggleExpand`; without it the
+     * stepped expansion lives only in the tree and is lost on the next
+     * document change.
+     */
+    onSetExpandedFolders?: (folderIds: string[]) => void;
+    onMove: (draggedId: string, targetId: string | null, position: "before" | "after" | "child") => void;
+    onManageTags?: (id: string) => void;
+    onRename?: (id: string, newTitle: string) => void;
+    searchQuery: string;
+    onSearchChange: (query: string) => void;
+    onSearchClear: () => void;
+    onSearchFocus: () => void;
+    isOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    isMobile?: boolean;
+    leftPanels: SidebarPanelType[];
+    onLeftPanelsChange: (panels: SidebarPanelType[]) => void;
+    rightPanels: SidebarPanelType[];
+    onRightPanelsChange: (panels: SidebarPanelType[]) => void;
+    onSettingsClick?: (section?: string) => void;
+    onInviteClick?: () => void;
+    onRestore?: (id: string) => void;
+    onPermanentDelete?: (id: string) => void;
+    newDocumentId?: string | null;
+    showDynamicIsland?: boolean;
+    onToggleDynamicIsland?: () => void;
+    activeFileSourceId?: string;
+    onFileSourceChange?: (sourceId: string) => void;
+    headings?: TocEntry[];
+    onNavigate?: (key: string) => void;
+    editorRef?: RefObject<ActiveHeadingEditorHandle | null>;
+    openTabs?: string[];
+    activeTab?: string | null;
+    onTabChange?: (id: string) => void;
+    onTabClose?: (id: string) => void;
+    onTabsClose?: (ids: string[]) => void;
+    onTabRename?: (id: string, newTitle: string) => void;
+    onSplitRight?: (id: string) => void;
+    onReopenLastClosed?: () => void;
+    canReopenLastClosed?: boolean;
+    tabItems?: OpenTabItem[];
+    onNewChat?: () => void;
+    aiProps?: SidebarAiProps;
+    tipsProps?: SidebarTipsProps;
+    topicsProps?: SidebarTopicsProps;
+}
+/** Props for the `SidebarContent` component (the shared panel-body renderer used by both the left sidebar and `RightPanel`). */
+export interface SidebarContentProps {
+    /** Which panels are active on this side. Two or more panels render stacked in a split (canonical stacking order applies). */
+    panels: SidebarPanelType[];
+    /** Storage key suffix so left/right panel sizes persist independently. */
+    persistenceKey: string;
+    /** Filtered/flat document list to pass down to the file tree. */
+    activeDocuments: Document[];
+    /** Heading entries from the Tiptap table of contents. */
+    headings?: TocEntry[];
+    /** ID of the currently active/selected document. */
+    activeId: string | null;
+    /** The full `Document` object for `activeId` (used for outline section search). */
+    activeDocument?: Document;
+    /** Whether the sidebar is being displayed in a mobile sheet. */
+    isMobile?: boolean;
+    /** Selects a document by ID; closes the mobile sheet when on mobile. */
+    onSelect: (id: string) => void;
+    /** Creates a new note or folder under `parentId`. */
+    onAdd: (parentId: string | null, isFolder?: boolean) => void;
+    /** Soft-deletes a document by ID. */
+    onDelete: (id: string) => void;
+    /** Duplicates a document by ID. */
+    onDuplicate: (id: string) => void;
+    /** Moves a document in the tree via drag-and-drop. */
+    onMove: (draggedId: string, targetId: string | null, position: 'before' | 'after' | 'child') => void;
+    /** Opens the tag management UI for a document. */
+    onManageTags?: (id: string) => void;
+    /** Renames a document. */
+    onRename?: (id: string, newTitle: string) => void;
+    /** Callback to control the mobile sidebar sheet open state. */
+    onOpenChange?: (open: boolean) => void;
+    /** Ref forwarded to the `FileTree` component for imperative control. */
+    treeRef?: RefObject<DocumentTreeHandle | null>;
+    /**
+     * Reports the file tree's live expansion depth (and the tree's deepest
+     * folder level) so the toolbar's expand/collapse toggle can label the next
+     * step of its one-level-at-a-time cycle.
+     */
+    onExpandStateChange?: (state: {
+        level: number;
+        maxLevel: number;
+    }) => void;
+    /**
+     * Replaces the set of expanded folders wholesale when the toolbar steps the
+     * tree to a new expansion level, so the host can persist it.
+     */
+    onSetExpandedFolders?: (folderIds: string[]) => void;
+    /** Ref forwarded to the `OutlineView` component for imperative control. */
+    outlineRef?: RefObject<OutlineViewHandle | null>;
+    /** Editor handle passed to `OutlineView` to scroll-spy the active heading. */
+    editorRef?: RefObject<ActiveHeadingEditorHandle | null>;
+    /** Currently open tab IDs shown in the top pane. */
+    openTabs?: string[];
+    /** ID of the currently active tab. */
+    activeTab?: string | null;
+    /** Switches to a tab. */
+    onTabChange?: (id: string) => void;
+    /** Closes a tab. */
+    onTabClose?: (id: string) => void;
+    /**
+     * Closes several tabs in one operation (used by "Close Tabs Below" and
+     * "Close Other Tabs"). When omitted the panel falls back to calling
+     * `onTabClose` once per tab, which only works if the host applies each
+     * close against the latest state.
+     */
+    onTabsClose?: (ids: string[]) => void;
+    /** Renames a tab's document. */
+    onTabRename?: (id: string, newTitle: string) => void;
+    /** Opens a tab in a split view to the right. */
+    onSplitRight?: (id: string) => void;
+    /** Reopens the last closed tab. */
+    onReopenLastClosed?: () => void;
+    /** Whether there is a closed tab that can be reopened. */
+    canReopenLastClosed?: boolean;
+    /** Navigates the editor to a heading (used by the "outline" panel). */
+    onNavigate?: (key: string) => void;
+    /** AI suggestion state/handlers (used by the "ai" panel). */
+    aiProps?: SidebarAiProps;
+    /** AI-generated page tips state/handlers (used by the "ai" panel). */
+    tipsProps?: SidebarTipsProps;
+    /** AI-generated search topics state/handlers (used by the "related" panel). */
+    topicsProps?: SidebarTopicsProps;
+    /** Unified tab list (files + chats). Overrides file-only tab derivation when set. */
+    tabItems?: OpenTabItem[];
+    /** Opens a new chat tab from the "Open Tabs" panel header. */
+    onNewChat?: () => void;
+    /** Opens the file manager modal from the "Files" panel header. */
+    onFileManagerOpen?: () => void;
+    /** Soft-deleted documents listed in the "Files" panel header trash menu. */
+    deletedDocs?: Document[];
+    /** Restores a soft-deleted document by ID (from the trash menu). */
+    onRestore?: (id: string) => void;
+}

package/dist/search/OutlineView.d.ts

@@ -0,0 +1,51 @@
+import { type RefObject } from 'react';
+import type { TocEntry } from '../app-types/toc';
+import { type ActiveHeadingEditorHandle } from './useActiveHeading';
+/**
+ * Imperative handle exposed to parent components via a forwarded ref.
+ * Allows programmatic expand/collapse of the entire outline.
+ */
+export interface OutlineViewHandle {
+    /** Expands all heading nodes. */
+    expandAll: () => void;
+    /** Collapses all H1 nodes (hiding their children). */
+    collapseAll: () => void;
+}
+/** Props for the {@link OutlineView} component. */
+interface OutlineViewProps {
+    /** Heading entries from the Tiptap editor's TOC extractor. */
+    headings?: TocEntry[];
+    /** Called when the user clicks a heading; receives the heading key. */
+    onNavigate?: (key: string) => void;
+    /** Optional drag-reorder callback receiving source and target indices. */
+    onReorder?: (fromIndex: number, toIndex: number) => void;
+    /** Filters the heading list to items whose text contains this query. */
+    searchQuery?: string;
+    /**
+     * Ref to the editor's imperative handle, used to resolve heading DOM
+     * elements for scroll-spy active-heading highlighting. When omitted, no
+     * heading is ever highlighted as active.
+     */
+    editorRef?: RefObject<ActiveHeadingEditorHandle | null>;
+}
+/**
+ * Given the outline panel's own scroll container (`scrollTop`/`clientHeight`)
+ * and the active row's offset within it (`offsetTop`/`offsetHeight`), returns
+ * the `scrollTop` needed to bring the row fully into view — scrolling up if
+ * it's above the visible area, down if it's below — or `null` if the row is
+ * already fully visible and no scrolling is needed.
+ */
+export declare function computeScrollIntoViewOffset(container: {
+    scrollTop: number;
+    clientHeight: number;
+}, row: {
+    offsetTop: number;
+    offsetHeight: number;
+}): number | null;
+/**
+ * Collapsible document outline panel. Renders a heading tree built from
+ * `headings` with click-to-navigate, expand/collapse, drag-to-reorder,
+ * search filtering, and a context menu for bulk collapse-level controls.
+ */
+export declare const OutlineView: import("react").ForwardRefExoticComponent<OutlineViewProps & import("react").RefAttributes<OutlineViewHandle>>;
+export {};

package/dist/search/relatedDocuments.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module relatedDocuments
+ * @description Client-side "related documents" suggestions for the sidebar's
+ * Related panel. Scores every other document by how many significant
+ * keywords it shares with the active document's title and plain-text
+ * content — no server calls or embeddings involved — boosted by any shared
+ * user-assigned tags, a more deliberate relatedness signal than incidental
+ * keyword overlap.
+ */
+import type { Document } from '../documents/DocumentTree';
+/** A related-document suggestion returned by {@link findRelatedDocuments}. */
+export interface RelatedDocumentResult {
+    /** The related document. */
+    document: Document;
+    /** Number of significant keywords shared with the active document. */
+    sharedKeywordCount: number;
+    /** Number of tags shared with the active document (case-insensitive). */
+    sharedTagCount: number;
+}
+/**
+ * Ranks candidate documents by how many significant keywords and tags they
+ * share with `activeDocument`. Each shared tag counts as {@link
+ * TAG_MATCH_WEIGHT} shared keywords when ranking, since a user-assigned tag
+ * is a more deliberate relatedness signal than incidental keyword overlap. A
+ * document with no shared keywords but at least one shared tag still
+ * qualifies. Folders, soft-deleted documents, and the active document itself
+ * are never suggested.
+ *
+ * @param documents - Candidate documents to search (typically all documents).
+ * @param activeDocument - The currently open document, or `undefined`/`null` when none is active.
+ * @param limit - Maximum number of suggestions to return (default 10).
+ */
+export declare function findRelatedDocuments(documents: Document[], activeDocument: Document | undefined | null, limit?: number): RelatedDocumentResult[];
+/** The single top-ranked suggestion, split from the rest, returned by {@link splitTopSuggestion}. */
+export interface RelatedDocumentsSplit {
+    /** The highest-ranked related document, or `null` when there are no results. */
+    suggested: RelatedDocumentResult | null;
+    /** The remaining results, in their existing rank order. */
+    others: RelatedDocumentResult[];
+}
+/**
+ * Splits an already-ranked {@link findRelatedDocuments} result list into its
+ * single top match — the "suggested next" document — and the rest, so the
+ * sidebar can render the top match more prominently than the flat list.
+ */
+export declare function splitTopSuggestion(results: RelatedDocumentResult[]): RelatedDocumentsSplit;

package/dist/search/useActiveHeading.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module useActiveHeading
+ * @description Scroll-spy: tracks which heading is currently "active" (in
+ * view) as the user scrolls the editor, for highlighting in a table-of-
+ * contents / outline sidebar. Mirrors the scroll-spy logic already used by
+ * {@link DynamicIslandTOC}, factored out so other TOC-style views (like the
+ * sidebar outline) can reuse it instead of re-deriving it.
+ */
+import { type RefObject } from 'react';
+import type { TocEntry } from '../app-types/toc';
+/** Minimal shape this hook needs from an editor ref — matches `TiptapEditorHandle`. */
+export interface ActiveHeadingEditorHandle {
+    getElementByKey: (key: string) => HTMLElement | null;
+}
+interface HeadingTop {
+    key: string;
+    /** Heading element's top offset relative to the scroll container's top. */
+    top: number;
+}
+/**
+ * Given each visible heading's top offset (relative to the scroll
+ * container) and a threshold distance from the container's top, returns the
+ * key of the last heading whose top is at or above the threshold — i.e. the
+ * heading the reader has scrolled past most recently. Falls back to the
+ * first heading when none qualify (e.g. the reader is above the first
+ * heading), and to `null` when there are no headings at all.
+ */
+export declare function computeActiveHeadingKey(headings: HeadingTop[], threshold: number): string | null;
+/**
+ * Tracks the currently active heading key while the document scrolls.
+ * Resolves heading DOM elements via `editorRef.current.getElementByKey`, so
+ * it stays in sync with whatever container the editor actually scrolls in
+ * (found by walking up from the first heading to its nearest scrollable
+ * ancestor, falling back to `window`).
+ *
+ * Returns `null` when there is no `editorRef`/no headings, or before the
+ * first scroll-position measurement.
+ */
+export declare function useActiveHeading(headings: TocEntry[], editorRef?: RefObject<ActiveHeadingEditorHandle | null>): string | null;
+export {};