papyr-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RayKong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# papyr-react
+
+## Components vs. Blocks
+
+Papyr exposes two layers, similar to shadcn/ui:
+
+- **Components** – focused building blocks such as `FileHierarchy`, `FileSearch`, `NoteViewer`, and `TableOfContents`.
+- **Blocks** – opinionated compositions that wire multiple components together. The new `WorkspaceBlock` uses `DoubleSidebarLayout` to render a file hierarchy + main + outline surface with independent scrolling.
+
+```tsx
+import {
+  WorkspaceBlock,
+  hydrateSearchIndex,
+  type WorkspaceBlockProps
+} from 'papyr-react'
+
+const searchIndex = hydrateSearchIndex(serializedIndex)
+
+const workspaceProps: WorkspaceBlockProps = {
+  notes,
+  tree,
+  searchIndex,
+  graph,
+  initialSlug: notes[0]?.slug
+}
+
+export function App() {
+  return <WorkspaceBlock {...workspaceProps} />
+}
+```
+
+Blocks accept slots so you can swap any pane:
+
+```tsx
+<WorkspaceBlock
+  {...workspaceProps}
+  rightSidebar={({ activeNote }) => (
+    <CustomMetadataPanel note={activeNote} />
+  )}
+/>
+```
+
+Use components directly when you need finer control, or drop in a block for a ready-made layout.
+
+## Hydrating build output
+
+When you load JSON produced by `papyr-core`, hydrate the search index before
+passing it to `PapyrProvider`:
+
+```ts
+import { hydrateSearchIndex } from 'papyr-react'
+import { type SerializedSearchIndex } from 'papyr-core/runtime'
+
+const serialized: SerializedSearchIndex = /* build output */
+const searchIndex = hydrateSearchIndex(serialized)
+```
+
+This accepts either the serialized payload or an already hydrated index, so it
+can be used safely in shared code paths.
+
+## Syncing with a router
+
+Use `useRoutableActiveNote` to keep Papyr state in sync with your routing
+library. Provide two callbacks: one to read the current slug from the router and
+another to push updates when the user selects a different note.
+
+```tsx
+import { useCallback } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import { useRoutableActiveNote } from 'papyr-react'
+
+const navigate = useNavigate()
+const { slug } = useParams<{ slug?: string }>()
+
+const { activeNote, activeSlug, setActiveSlug } = useRoutableActiveNote(notes, {
+  getCurrentSlug: useCallback(() => slug ?? null, [slug]),
+  onSlugChange: useCallback(
+    (nextSlug) => {
+      navigate(nextSlug ? `/notes/${nextSlug}` : '/')
+    },
+    [navigate]
+  )
+})
+```
+
+The hook exposes the same API as `useActiveNote`, so existing components (e.g.
+sidebar or note viewer) continue to work while the URL stays in sync.

package/dist/blocks/WorkspaceBlock/WorkspaceBlock.d.ts

@@ -0,0 +1,79 @@
+import { FolderNode, NoteGraph, SearchIndex, Slug, WebReadyNote } from 'papyr-core/runtime';
+import { ReactNode } from 'react';
+import { DoubleSidebarLayoutProps } from '../../components/DoubleSidebarLayout';
+import { FileHierarchyProps } from '../../components/FileHierarchy';
+import { TableOfContentsProps } from '../../components/TableOfContents';
+
+export interface WorkspaceBlockContext {
+    notes: WebReadyNote[];
+    searchIndex: SearchIndex;
+    graph: NoteGraph | null;
+    activeSlug: Slug | null;
+    activeNote: WebReadyNote | null;
+    setActiveSlug: (slug: Slug | null) => void;
+    setActiveNote: (note: WebReadyNote | null) => void;
+}
+type SlotRenderer = ReactNode | ((context: WorkspaceBlockContext) => ReactNode);
+type FileHierarchyOverrides = Omit<FileHierarchyProps, 'tree' | 'onNoteClick' | 'activeSlug' | 'notes' | 'searchable' | 'searchIndex'>;
+type TableOfContentsOverrides = Omit<TableOfContentsProps, 'note'>;
+export interface WorkspaceBlockProps {
+    notes: WebReadyNote[];
+    tree: FolderNode[] | FolderNode;
+    searchIndex: SearchIndex;
+    graph?: NoteGraph | null;
+    /**
+     * UNCONTROLLED MODE: Initial slug for internal state management.
+     * Use this when you don't need to sync with external state (e.g., router).
+     */
+    initialSlug?: Slug | null;
+    /**
+     * CONTROLLED MODE: Current active slug managed by parent.
+     * When provided, WorkspaceBlock delegates state to parent via onActiveSlugChange.
+     * Use with useRoutableActiveNote for router integration.
+     */
+    activeSlug?: Slug | null;
+    /**
+     * CONTROLLED MODE: Callback when active slug should change.
+     * Required when using controlled mode (activeSlug prop).
+     */
+    onActiveSlugChange?: (slug: Slug | null) => void;
+    className?: string;
+    /**
+     * Customise layout widths. Defaults to 280px for each sidebar.
+     */
+    leftWidth?: DoubleSidebarLayoutProps['leftWidth'];
+    rightWidth?: DoubleSidebarLayoutProps['rightWidth'];
+    /**
+     * Render custom content for each pane. Provide either a React node or a
+     * function that receives the block context.
+     */
+    leftSidebar?: SlotRenderer;
+    main?: SlotRenderer;
+    rightSidebar?: SlotRenderer;
+    /**
+     * When true, omits the default table of contents from the right sidebar.
+     */
+    hideTableOfContents?: boolean;
+    /**
+     * Called whenever the active note changes.
+     */
+    onNoteChange?: (note: WebReadyNote | null) => void;
+    /**
+     * Optional overrides forwarded to the default FileHierarchy implementation.
+     */
+    fileHierarchyProps?: FileHierarchyOverrides;
+    /**
+     * Optional overrides forwarded to the default TableOfContents implementation.
+     */
+    tableOfContentsProps?: TableOfContentsOverrides;
+    /**
+     * Custom empty state rendered when no note is selected.
+     */
+    emptyState?: ReactNode;
+    /**
+     * Toggle native sidebar scrollbars. Default: hidden.
+     */
+    hideSidebarScrollbars?: boolean;
+}
+export declare const WorkspaceBlock: ({ notes, tree, searchIndex, graph, initialSlug, activeSlug: controlledActiveSlug, onActiveSlugChange, className, leftWidth, rightWidth, leftSidebar, main, rightSidebar, hideTableOfContents, onNoteChange, fileHierarchyProps, tableOfContentsProps, emptyState, hideSidebarScrollbars }: WorkspaceBlockProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/blocks/index.d.ts

@@ -0,0 +1,2 @@
+export { WorkspaceBlock } from './WorkspaceBlock/WorkspaceBlock';
+export type { WorkspaceBlockProps, WorkspaceBlockContext } from './WorkspaceBlock/WorkspaceBlock';

package/dist/components/Breadcrumbs/Breadcrumbs.d.ts

@@ -0,0 +1,12 @@
+import { FC } from 'react';
+
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+export interface BreadcrumbsProps {
+    trail: BreadcrumbItem[];
+    className?: string;
+    separator?: string;
+}
+export declare const Breadcrumbs: FC<BreadcrumbsProps>;

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

@@ -0,0 +1,2 @@
+export type { BreadcrumbItem, BreadcrumbsProps } from './Breadcrumbs';
+export { Breadcrumbs } from './Breadcrumbs';

package/dist/components/DoubleSidebarLayout/DoubleSidebarLayout.d.ts

@@ -0,0 +1,49 @@
+import { FC, ReactNode } from 'react';
+
+type SidebarWidth = string | number;
+export interface DoubleSidebarLayoutProps {
+    /**
+     * Node rendered in the left sidebar column.
+     */
+    leftSidebar: ReactNode;
+    /**
+     * Node rendered as the primary content column.
+     */
+    main: ReactNode;
+    /**
+     * Optional node rendered in the right sidebar column.
+     */
+    rightSidebar?: ReactNode;
+    /**
+     * Custom width for the left sidebar column.
+     * @default 280
+     */
+    leftWidth?: SidebarWidth;
+    /**
+     * Custom width for the right sidebar column.
+     * @default 480
+     */
+    rightWidth?: SidebarWidth;
+    /**
+     * When true (default) the layout stretches to fill the viewport height and
+     * constrains scrolling to the individual panes. Set to false to allow the
+     * page to dictate overall height/scrolling.
+     */
+    fullHeight?: boolean;
+    /**
+     * When true (default) sidebars hide native scrollbars while keeping their
+     * content scrollable.
+     */
+    hideSidebarScrollbars?: boolean;
+    /**
+     * Additional className forwarded to the root container.
+     */
+    className?: string;
+}
+/**
+ * Three column workspace layout with independent scrolling for each pane.
+ * Mirrors the behaviour of the Obsidian help site where the main pane owns the
+ * visible scrollbar and sidebars scroll without showing native scrollbars.
+ */
+export declare const DoubleSidebarLayout: FC<DoubleSidebarLayoutProps>;
+export {};

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

@@ -0,0 +1,2 @@
+export { DoubleSidebarLayout } from './DoubleSidebarLayout';
+export type { DoubleSidebarLayoutProps } from './DoubleSidebarLayout';

package/dist/components/EmptyState/EmptyState.d.ts

@@ -0,0 +1,31 @@
+import { FC, ReactNode } from 'react';
+
+export interface EmptyStateProps {
+    icon?: ReactNode;
+    title: string;
+    description?: string;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Generic empty state component for displaying placeholder content
+ * when no data is available.
+ *
+ * @example
+ * // Simple usage
+ * <EmptyState
+ *   title="No notes found"
+ *   description="Add some markdown files to get started"
+ * />
+ *
+ * @example
+ * // With icon and custom content
+ * <EmptyState
+ *   icon="📝"
+ *   title="No notes selected"
+ *   description="Choose a note from the sidebar"
+ * >
+ *   <button>Create New Note</button>
+ * </EmptyState>
+ */
+export declare const EmptyState: FC<EmptyStateProps>;

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

@@ -0,0 +1,2 @@
+export { EmptyState } from './EmptyState';
+export type { EmptyStateProps } from './EmptyState';

package/dist/components/FileHierarchy/FileHierarchy.d.ts

@@ -0,0 +1,19 @@
+import { FC } from 'react';
+import { FolderNode, Slug, SearchIndex } from 'papyr-core/runtime';
+import { NoteLinkRenderer } from './types';
+
+export interface FileHierarchyProps {
+    tree: FolderNode[] | FolderNode;
+    className?: string;
+    onNoteClick?: (slug: Slug) => void;
+    renderNoteLink?: NoteLinkRenderer;
+    activeSlug?: string;
+    notes?: Array<{
+        slug: string;
+        title?: string;
+    }>;
+    searchable?: boolean;
+    searchIndex?: SearchIndex;
+    searchPlaceholder?: string;
+}
+export declare const FileHierarchy: FC<FileHierarchyProps>;

package/dist/components/FileHierarchy/FileHierarchy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/FileHierarchy/MemoizedFolderTree.d.ts

@@ -0,0 +1,16 @@
+import { FC } from 'react';
+import { FolderNode, Slug } from 'papyr-core/runtime';
+import { NoteLinkRenderer } from './types';
+import { NoteTitleMap } from './utils';
+
+export interface MemoizedFolderTreeProps {
+    node: FolderNode;
+    onNoteClick?: (slug: Slug) => void;
+    renderNoteLink?: NoteLinkRenderer;
+    activeSlug?: string;
+    noteTitleMap?: NoteTitleMap;
+    depth?: number;
+    isSearching?: boolean;
+    searchQuery?: string;
+}
+export declare const MemoizedFolderTree: FC<MemoizedFolderTreeProps>;

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

@@ -0,0 +1,3 @@
+export type { FileHierarchyProps } from './FileHierarchy';
+export type { NoteLinkRenderContext, NoteLinkRenderer } from './types';
+export { FileHierarchy } from './FileHierarchy';

package/dist/components/FileHierarchy/types.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { Slug } from 'papyr-core/runtime';
+
+export interface NoteLinkRenderContext {
+    onClick?: () => void;
+    isActive: boolean;
+    isSearchMatch: boolean;
+}
+export type NoteLinkRenderer = (slug: Slug, context: NoteLinkRenderContext) => ReactNode;

package/dist/components/FileHierarchy/utils.d.ts

@@ -0,0 +1,5 @@
+import { Slug } from 'papyr-core/runtime';
+
+export type NoteTitleMap = Record<string, string | undefined>;
+export declare const formatFolderName: (name: string) => string;
+export declare const getNoteDisplayText: (slug: Slug, noteTitleMap?: NoteTitleMap) => string;

package/dist/components/FileSearch/FileSearch.d.ts

@@ -0,0 +1,27 @@
+import { FC } from 'react';
+
+export interface FileSearchProps {
+    query: string;
+    onChange: (query: string) => void;
+    placeholder?: string;
+    className?: string;
+    /** When true, applies compact styling suitable for sidebars */
+    compact?: boolean;
+}
+/**
+ * Standalone search input component for filtering files/notes.
+ * Can be used independently or embedded in other components like FileHierarchy.
+ *
+ * @example
+ * // Standalone usage
+ * <FileSearch query={query} onChange={setQuery} />
+ *
+ * @example
+ * // In sidebar with compact styling
+ * <FileSearch query={query} onChange={setQuery} compact />
+ *
+ * @example
+ * // Custom styling
+ * <FileSearch query={query} onChange={setQuery} className="my-search" />
+ */
+export declare const FileSearch: FC<FileSearchProps>;

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

@@ -0,0 +1,2 @@
+export { FileSearch } from './FileSearch';
+export type { FileSearchProps } from './FileSearch';

package/dist/components/GraphView/GraphView.d.ts

@@ -0,0 +1,19 @@
+import { GraphNode, NoteGraph, Slug } from 'papyr-core/runtime';
+
+interface GraphCanvasProps {
+    graph: NoteGraph | null;
+    className?: string;
+    filterNode?: (node: GraphNode) => boolean;
+    focusPredicate?: (node: GraphNode) => boolean;
+    nodeColor?: (node: GraphNode) => string;
+    zoomExtent?: [number, number];
+    focusNodeId?: string | null;
+    onNodeSelect?: (node: GraphNode) => void;
+}
+export interface GraphViewProps extends GraphCanvasProps {
+    activeSlug?: Slug | null;
+    showFullscreenToggle?: boolean;
+    fullscreenTitle?: string;
+}
+export declare const GraphView: ({ graph, className, activeSlug, filterNode, focusPredicate, nodeColor, zoomExtent, onNodeSelect, showFullscreenToggle, fullscreenTitle }: GraphViewProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,2 @@
+export type { GraphViewProps } from './GraphView';
+export { GraphView } from './GraphView';

package/dist/components/HoverPreview/HoverPreview.d.ts

@@ -0,0 +1,12 @@
+import { FC, ReactNode } from 'react';
+
+export interface HoverPreviewProps {
+    trigger: ReactNode;
+    renderPreview: () => ReactNode;
+    /**
+     * When true, applies the default dotted underline styling to visually indicate the trigger is interactive.
+     * Set to false when the supplied trigger already communicates interactivity (e.g. buttons, links).
+     */
+    highlightTrigger?: boolean;
+}
+export declare const HoverPreview: FC<HoverPreviewProps>;

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

@@ -0,0 +1,2 @@
+export type { HoverPreviewProps } from './HoverPreview';
+export { HoverPreview } from './HoverPreview';

package/dist/components/MiniGraph/MiniGraph.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { NoteGraph } from 'papyr-core/runtime';
+
+export interface MiniGraphProps {
+    graph: NoteGraph;
+    className?: string;
+}
+export declare const MiniGraph: FC<MiniGraphProps>;

package/dist/components/MiniGraph/MiniGraph.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export type { MiniGraphProps } from './MiniGraph';
+export { MiniGraph } from './MiniGraph';

package/dist/components/NotePreview/NotePreviewContent.d.ts

@@ -0,0 +1,14 @@
+import { FC } from 'react';
+
+export interface NotePreviewData {
+    slug: string;
+    title?: string | null;
+    excerpt?: string | null;
+    description?: string | null;
+    tags?: string[];
+}
+interface NotePreviewContentProps {
+    note: NotePreviewData;
+}
+export declare const NotePreviewContent: FC<NotePreviewContentProps>;
+export {};

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

@@ -0,0 +1,2 @@
+export { NotePreviewContent } from './NotePreviewContent';
+export type { NotePreviewData } from './NotePreviewContent';

package/dist/components/NoteViewer/NoteViewer.d.ts

@@ -0,0 +1,15 @@
+import { FC, ReactNode } from 'react';
+import { WebReadyNote, Slug } from 'papyr-core/runtime';
+
+export interface NoteViewerNavigateOptions {
+    fragment?: string;
+}
+export interface NoteViewerProps {
+    note: WebReadyNote | null;
+    emptyState?: ReactNode;
+    onNavigateNote?: (slug: Slug, options?: NoteViewerNavigateOptions) => void;
+}
+/**
+ * Rich note renderer with link previews, breadcrumbs, and metadata.
+ */
+export declare const NoteViewer: FC<NoteViewerProps>;

package/dist/components/NoteViewer/NoteViewer.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export type { NoteViewerProps } from './NoteViewer';
+export { NoteViewer } from './NoteViewer';

package/dist/components/SearchBar/SearchBar.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+
+export interface SearchBarProps {
+    query: string;
+    onQueryChange: (value: string) => void;
+    placeholder?: string;
+    className?: string;
+}
+export declare const SearchBar: FC<SearchBarProps>;

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

@@ -0,0 +1,2 @@
+export type { SearchBarProps } from './SearchBar';
+export { SearchBar } from './SearchBar';

package/dist/components/SearchDropdown/SearchDropdown.d.ts

@@ -0,0 +1,12 @@
+import { FC } from 'react';
+import { SearchIndex } from 'papyr-core/runtime';
+
+export interface SearchDropdownProps {
+    searchIndex: SearchIndex;
+    onResultClick: (slug: string) => void;
+    placeholder?: string;
+    className?: string;
+    maxResults?: number;
+    showCategories?: boolean;
+}
+export declare const SearchDropdown: FC<SearchDropdownProps>;

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

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

package/dist/components/SidebarLayout/SidebarLayout.d.ts

@@ -0,0 +1,33 @@
+import { FC, ReactNode } from 'react';
+
+export interface SidebarLayoutProps {
+    sidebar: ReactNode;
+    main: ReactNode;
+    className?: string;
+    sidebarWidth?: string | number;
+    /**
+     * When true (default), the layout fills the viewport height and scrolls the main pane.
+     * Set to false to allow the page to control scrolling.
+     */
+    fullHeight?: boolean;
+}
+/**
+ * Common two-column layout with sidebar and main content area.
+ * Provides a responsive, full-height layout pattern.
+ *
+ * @example
+ * // Basic usage
+ * <SidebarLayout
+ *   sidebar={<FileHierarchy tree={tree} />}
+ *   main={<NoteViewer note={note} />}
+ * />
+ *
+ * @example
+ * // Custom sidebar width
+ * <SidebarLayout
+ *   sidebar={<FileHierarchy tree={tree} />}
+ *   main={<NoteViewer note={note} />}
+ *   sidebarWidth={320}
+ * />
+ */
+export declare const SidebarLayout: FC<SidebarLayoutProps>;

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

@@ -0,0 +1,2 @@
+export { SidebarLayout } from './SidebarLayout';
+export type { SidebarLayoutProps } from './SidebarLayout';

package/dist/components/TableOfContents/TableOfContents.d.ts

@@ -0,0 +1,10 @@
+import { FC } from 'react';
+import { WebReadyNote, Heading } from 'papyr-core/runtime';
+
+export interface TableOfContentsProps {
+    note: WebReadyNote | null;
+    className?: string;
+    title?: string;
+    onNavigate?: (heading: Heading) => void;
+}
+export declare const TableOfContents: FC<TableOfContentsProps>;

package/dist/components/TableOfContents/TableOfContents.test.d.ts

@@ -0,0 +1 @@
+export {};

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

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

package/dist/components/TagFilter/TagFilter.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+
+export interface TagFilterProps {
+    availableTags: string[];
+    selectedTags: string[];
+    onChange: (tags: string[]) => void;
+    className?: string;
+}
+export declare const TagFilter: FC<TagFilterProps>;

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

@@ -0,0 +1,2 @@
+export type { TagFilterProps } from './TagFilter';
+export { TagFilter } from './TagFilter';

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

@@ -0,0 +1,11 @@
+import { FC } from 'react';
+
+export interface ToastDescriptor {
+    id: string;
+    message: string;
+}
+export interface ToastContainerProps {
+    toasts: ToastDescriptor[];
+    onDismiss: (id: string) => void;
+}
+export declare const ToastContainer: FC<ToastContainerProps>;

package/dist/components/index.d.ts

@@ -0,0 +1,16 @@
+export * from './GraphView';
+export * from './MiniGraph';
+export * from './NoteViewer';
+export * from './SearchBar';
+export * from './Breadcrumbs';
+export * from './HoverPreview';
+export * from './NotePreview';
+export * from './TagFilter';
+export * from './FileHierarchy';
+export * from './FileSearch';
+export * from './EmptyState';
+export * from './SidebarLayout';
+export * from './DoubleSidebarLayout';
+export * from './SearchDropdown';
+export * from './TableOfContents';
+export * from './Toast/Toast';

package/dist/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './useNotes';
+export * from './useActiveNote';
+export * from './useRoutableActiveNote';