feat: add favorites section with star button, frontmatter persistence, and drag-to-reorder

Adds FAVORITES sidebar section backed by _favorite and _favorite_index
frontmatter properties. Star button in breadcrumb bar toggles favorite
state. Drag-to-reorder updates _favorite_index on all affected notes.
Section auto-hides when empty.

ADR 0038 documents the decision to use frontmatter for portability.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Test
2026-04-02 14:44:23 +02:00
parent 931fed879b
commit 33db64822d
14 changed files with 256 additions and 7 deletions

View File

@@ -0,0 +1,32 @@
---
type: ADR
id: "0038"
title: "Frontmatter-backed favorites with _favorite and _favorite_index"
status: active
date: 2026-04-02
---
## Context
Users want to pin frequently-accessed notes to a dedicated FAVORITES section in the sidebar for quick navigation. The app needs a persistence mechanism for which notes are favorited and their display order.
## Decision
**Favorites are stored as two system properties in each note's YAML frontmatter: `_favorite: true` and `_favorite_index: <integer>`.**
- `_favorite`: boolean. Present and `true` = favorited. Absent = not favorited. Toggling off deletes the key entirely (no `_favorite: false`).
- `_favorite_index`: integer. Controls display order in the FAVORITES sidebar section (lower = higher). Assigned automatically on favorite, updated on drag-to-reorder.
- Both use the `_` prefix convention (ADR 0008) — they are system-owned and hidden from the Properties panel.
## Options considered
- **Frontmatter per-note (chosen)**: Each note carries its own favorite state. Portable across devices (synced via git). No separate metadata file. Cons: two extra frontmatter writes on reorder.
- **Separate `.laputa/favorites.json` file**: Central list of favorite paths. Simpler reorder (one file write). Cons: not portable if `.laputa/` is gitignored; path references break on rename.
- **SQLite/app-level metadata**: Fast queries. Cons: not synced via git; diverges from frontmatter-first data model established in ADR 0008.
## Consequences
- Favorites survive vault sync via git — any client that reads frontmatter sees them.
- Reorder writes `_favorite_index` to N files (one per affected note). Acceptable for typical favorites lists (< 20 items).
- If `_favorite: true` exists but `_favorite_index` is absent, the note is appended to the end of the list.
- Re-evaluate if favorites list exceeds ~50 items and reorder writes become a performance concern.

View File

@@ -59,6 +59,11 @@ pub struct VaultEntry {
pub view: Option<String>,
/// Whether this Type is visible in the sidebar. Defaults to true when absent.
pub visible: Option<bool>,
/// Whether this note is a user favorite (shown in FAVORITES sidebar section).
pub favorite: bool,
/// Display order within the FAVORITES section (lower = higher).
#[serde(rename = "favoriteIndex")]
pub favorite_index: Option<i64>,
/// Word count of the note body (excludes frontmatter and H1 title).
#[serde(rename = "wordCount")]
pub word_count: u32,

View File

@@ -45,6 +45,14 @@ pub(crate) struct Frontmatter {
pub view: Option<StringOrList>,
#[serde(default)]
pub visible: Option<bool>,
#[serde(
rename = "_favorite",
default,
deserialize_with = "deserialize_bool_or_string"
)]
pub favorite: Option<bool>,
#[serde(rename = "_favorite_index", default)]
pub favorite_index: Option<i64>,
}
/// Custom deserializer for boolean fields that may arrive as strings.
@@ -154,6 +162,8 @@ fn parse_frontmatter(data: &HashMap<String, serde_json::Value>) -> Frontmatter {
"notion_id",
"Status",
"status",
"_favorite",
"_favorite_index",
];
let filtered: serde_json::Map<String, serde_json::Value> = data
.iter()
@@ -184,6 +194,8 @@ const SKIP_KEYS: &[&str] = &[
"view",
"visible",
"status",
"_favorite",
"_favorite_index",
];
/// Extract all wikilink-containing fields from raw YAML frontmatter.

View File

@@ -102,6 +102,8 @@ pub fn parse_md_file(path: &Path) -> Result<VaultEntry, String> {
sort: frontmatter.sort.and_then(|v| v.into_scalar()),
view: frontmatter.view.and_then(|v| v.into_scalar()),
visible: frontmatter.visible,
favorite: frontmatter.favorite.unwrap_or(false),
favorite_index: frontmatter.favorite_index,
word_count,
outgoing_links,
properties,

View File

@@ -488,7 +488,7 @@ function App() {
{sidebarVisible && (
<>
<div className="app__sidebar" style={{ width: layout.sidebarWidth }}>
<Sidebar entries={vault.entries} folders={vault.folders} selection={selection} onSelect={handleSetSelection} onSelectNote={notes.handleSelectNote} onCreateType={notes.handleCreateNoteImmediate} onCreateNewType={dialogs.openCreateType} onCustomizeType={entryActions.handleCustomizeType} onUpdateTypeTemplate={entryActions.handleUpdateTypeTemplate} onReorderSections={entryActions.handleReorderSections} onRenameSection={entryActions.handleRenameSection} onToggleTypeVisibility={entryActions.handleToggleTypeVisibility} onCreateFolder={handleCreateFolder} inboxCount={inboxCount} />
<Sidebar entries={vault.entries} folders={vault.folders} selection={selection} onSelect={handleSetSelection} onSelectNote={notes.handleSelectNote} onSelectFavorite={notes.handleSelectNote} onReorderFavorites={entryActions.handleReorderFavorites} onCreateType={notes.handleCreateNoteImmediate} onCreateNewType={dialogs.openCreateType} onCustomizeType={entryActions.handleCustomizeType} onUpdateTypeTemplate={entryActions.handleUpdateTypeTemplate} onReorderSections={entryActions.handleReorderSections} onRenameSection={entryActions.handleRenameSection} onToggleTypeVisibility={entryActions.handleToggleTypeVisibility} onCreateFolder={handleCreateFolder} inboxCount={inboxCount} />
</div>
<ResizeHandle onResize={layout.handleSidebarResize} />
</>
@@ -532,6 +532,7 @@ function App() {
vaultPath={resolvedPath}
noteList={aiNoteList}
noteListFilter={aiNoteListFilter}
onToggleFavorite={entryActions.handleToggleFavorite}
onTrashNote={entryActions.handleTrashNote}
onRestoreNote={entryActions.handleRestoreNote}
onDeleteNote={deleteActions.handleDeleteNote}

View File

@@ -13,6 +13,7 @@ import {
ArrowCounterClockwise,
Archive,
ArrowUUpLeft,
Star,
} from '@phosphor-icons/react'
interface BreadcrumbBarProps {
@@ -28,6 +29,7 @@ interface BreadcrumbBarProps {
onToggleAIChat?: () => void
inspectorCollapsed?: boolean
onToggleInspector?: () => void
onToggleFavorite?: () => void
onTrash?: () => void
onRestore?: () => void
onArchive?: () => void
@@ -56,10 +58,20 @@ function RawToggleButton({ rawMode, onToggleRaw }: { rawMode?: boolean; onToggle
function BreadcrumbActions({ entry, showDiffToggle, diffMode, diffLoading, onToggleDiff,
rawMode, onToggleRaw,
showAIChat, onToggleAIChat, inspectorCollapsed, onToggleInspector,
onTrash, onRestore, onArchive, onUnarchive,
onToggleFavorite, onTrash, onRestore, onArchive, onUnarchive,
}: Omit<BreadcrumbBarProps, 'wordCount'>) {
return (
<div className="flex items-center" style={{ gap: 12 }}>
<button
className={cn(
"flex items-center justify-center border-none bg-transparent p-0 cursor-pointer transition-colors",
entry.favorite ? "text-yellow-500" : "text-muted-foreground hover:text-foreground"
)}
onClick={onToggleFavorite}
title={entry.favorite ? 'Remove from favorites' : 'Add to favorites'}
>
<Star size={16} weight={entry.favorite ? 'fill' : 'regular'} />
</button>
<button
className="flex items-center justify-center border-none bg-transparent p-0 text-muted-foreground cursor-pointer hover:text-foreground transition-colors"
title="Search in file"

View File

@@ -47,6 +47,7 @@ interface EditorProps {
vaultPath?: string
noteList?: NoteListItem[]
noteListFilter?: { type: string | null; query: string }
onToggleFavorite?: (path: string) => void
onTrashNote?: (path: string) => void
onRestoreNote?: (path: string) => void
onDeleteNote?: (path: string) => void
@@ -206,7 +207,7 @@ export const Editor = memo(function Editor(props: EditorProps) {
onUpdateFrontmatter, onDeleteProperty, onAddProperty, onCreateAndOpenNote, onInitializeProperties,
showAIChat, onToggleAIChat,
vaultPath, noteList, noteListFilter,
onTrashNote, onRestoreNote, onDeleteNote, onArchiveNote, onUnarchiveNote,
onToggleFavorite, onTrashNote, onRestoreNote, onDeleteNote, onArchiveNote, onUnarchiveNote,
onContentChange, onSave, onTitleSync,
onFileCreated, onFileModified, onVaultChanged,
onSetNoteIcon, onRemoveNoteIcon,
@@ -252,6 +253,7 @@ export const Editor = memo(function Editor(props: EditorProps) {
onToggleInspector={onToggleInspector}
onNavigateWikilink={onNavigateWikilink}
onEditorChange={handleEditorChange}
onToggleFavorite={onToggleFavorite}
onTrashNote={onTrashNote}
onRestoreNote={onRestoreNote}
onDeleteNote={onDeleteNote}

View File

@@ -41,6 +41,7 @@ interface EditorContentProps {
onToggleInspector: () => void
onNavigateWikilink: (target: string) => void
onEditorChange?: () => void
onToggleFavorite?: (path: string) => void
onTrashNote?: (path: string) => void
onRestoreNote?: (path: string) => void
onDeleteNote?: (path: string) => void
@@ -144,6 +145,7 @@ function ActiveTabBreadcrumb({ activeTab, barRef, props }: {
onToggleAIChat={props.onToggleAIChat}
inspectorCollapsed={props.inspectorCollapsed}
onToggleInspector={props.onToggleInspector}
onToggleFavorite={bindPath(props.onToggleFavorite, path)}
onTrash={bindPath(props.onTrashNote, path)}
onRestore={bindPath(props.onRestoreNote, path)}
onArchive={bindPath(props.onArchiveNote, path)}
@@ -250,6 +252,8 @@ export function EditorContent({
title={activeTab.entry.title}
filename={activeTab.entry.filename}
editable={!isTrashed}
notePath={activeTab.entry.path}
vaultPath={vaultPath}
onTitleChange={(newTitle) => onTitleChange?.(activeTab.entry.path, newTitle)}
/>
</div>

View File

@@ -922,4 +922,40 @@ describe('Sidebar', () => {
render(<Sidebar entries={entriesWithEmoji} selection={defaultSelection} onSelect={() => {}} />)
expect(screen.queryByText('Build App')).not.toBeInTheDocument()
})
describe('FAVORITES section', () => {
const favEntry: VaultEntry = {
path: '/vault/project/fav.md', filename: 'fav.md', title: 'My Favorite Note',
isA: 'Project', aliases: [], belongsTo: [], relatedTo: [], status: null, owner: null,
cadence: null, archived: false, trashed: false, trashedAt: null, modifiedAt: 1700000000,
createdAt: null, fileSize: 100, snippet: '', wordCount: 0, relationships: {},
icon: null, color: null, order: null, sidebarLabel: null, template: null,
sort: null, view: null, visible: null, outgoingLinks: [], properties: {},
favorite: true, favoriteIndex: 0,
}
it('shows FAVORITES section when there are favorites', () => {
render(<Sidebar entries={[...mockEntries, favEntry]} selection={defaultSelection} onSelect={() => {}} />)
expect(screen.getByText('FAVORITES')).toBeInTheDocument()
expect(screen.getByText('My Favorite Note')).toBeInTheDocument()
})
it('hides FAVORITES section when no favorites', () => {
render(<Sidebar entries={mockEntries} selection={defaultSelection} onSelect={() => {}} />)
expect(screen.queryByText('FAVORITES')).not.toBeInTheDocument()
})
it('hides trashed favorites from the section', () => {
const trashedFav = { ...favEntry, trashed: true }
render(<Sidebar entries={[...mockEntries, trashedFav]} selection={defaultSelection} onSelect={() => {}} />)
expect(screen.queryByText('FAVORITES')).not.toBeInTheDocument()
})
it('calls onSelect with favorites filter when clicking a favorite', () => {
const onSelect = vi.fn()
render(<Sidebar entries={[...mockEntries, favEntry]} selection={defaultSelection} onSelect={onSelect} />)
fireEvent.click(screen.getByText('My Favorite Note'))
expect(onSelect).toHaveBeenCalledWith({ kind: 'filter', filter: 'favorites' })
})
})
})

View File

@@ -12,8 +12,10 @@ import {
} from '@dnd-kit/sortable'
import { CSS } from '@dnd-kit/utilities'
import {
FileText, Trash, Archive, CaretLeft, Tray,
FileText, Trash, Archive, CaretLeft, Tray, CaretRight, CaretDown,
} from '@phosphor-icons/react'
import { isEmoji } from '../utils/emoji'
import { arrayMove } from '@dnd-kit/sortable'
import { SlidersHorizontal } from 'lucide-react'
import {
type SectionGroup, isSelectionActive,
@@ -34,6 +36,8 @@ interface SidebarProps {
onReorderSections?: (orderedTypes: { typeName: string; order: number }[]) => void
onRenameSection?: (typeName: string, label: string) => void
onToggleTypeVisibility?: (typeName: string) => void
onSelectFavorite?: (entry: VaultEntry) => void
onReorderFavorites?: (orderedPaths: string[]) => void
folders?: FolderNode[]
onCreateFolder?: (name: string) => void
inboxCount?: number
@@ -137,6 +141,98 @@ function SortableSection({ group, sectionProps }: {
)
}
function SortableFavoriteItem({ entry, isActive, onSelect }: {
entry: VaultEntry; isActive: boolean; onSelect: () => void
}) {
const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: entry.path })
const icon = entry.icon && isEmoji(entry.icon) ? entry.icon : null
return (
<div ref={setNodeRef} style={{ transform: CSS.Transform.toString(transform), transition, opacity: isDragging ? 0.5 : 1 }} {...attributes} {...listeners}>
<div
className={`flex cursor-pointer select-none items-center gap-1.5 rounded text-[13px] font-normal transition-colors ${isActive ? 'bg-secondary text-foreground' : 'text-muted-foreground hover:bg-accent'}`}
style={{ padding: '4px 16px 4px 28px' }}
onClick={onSelect}
>
{icon && <span className="shrink-0">{icon}</span>}
<span className="truncate">{entry.title}</span>
</div>
</div>
)
}
function FavoritesSection({ entries, selection, onSelect, onSelectNote, onReorder }: {
entries: VaultEntry[]
selection: SidebarSelection
onSelect: (sel: SidebarSelection) => void
onSelectNote?: (entry: VaultEntry) => void
onReorder?: (orderedPaths: string[]) => void
}) {
const [collapsed, setCollapsed] = useState(false)
const favorites = useMemo(
() => entries
.filter((e) => e.favorite && !e.archived && !e.trashed)
.sort((a, b) => (a.favoriteIndex ?? Infinity) - (b.favoriteIndex ?? Infinity)),
[entries],
)
const favIds = useMemo(() => favorites.map((f) => f.path), [favorites])
const sensors = useSensors(
useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
)
const handleDragEnd = useCallback((event: DragEndEvent) => {
const { active, over } = event
if (!over || active.id === over.id) return
const oldIndex = favIds.indexOf(active.id as string)
const newIndex = favIds.indexOf(over.id as string)
if (oldIndex === -1 || newIndex === -1) return
const reordered = arrayMove(favIds, oldIndex, newIndex)
onReorder?.(reordered)
}, [favIds, onReorder])
if (favorites.length === 0) return null
return (
<div style={{ padding: '4px 6px 0' }}>
<button
className="flex w-full cursor-pointer select-none items-center justify-between border-none bg-transparent text-muted-foreground"
style={{ padding: '6px 14px 6px 16px' }}
onClick={() => setCollapsed((v) => !v)}
>
<div className="flex items-center gap-1">
{collapsed ? <CaretRight size={12} /> : <CaretDown size={12} />}
<span className="text-[10px] font-semibold" style={{ letterSpacing: 0.5 }}>FAVORITES</span>
</div>
<span className="flex items-center justify-center text-muted-foreground" style={{ height: 18, borderRadius: 9999, padding: '0 5px', fontSize: 10, background: 'var(--muted)' }}>
{favorites.length}
</span>
</button>
{!collapsed && (
<DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
<SortableContext items={favIds} strategy={verticalListSortingStrategy}>
<div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
{favorites.map((entry) => {
const isActive = isSelectionActive(selection, { kind: 'entity', entry })
return (
<SortableFavoriteItem
key={entry.path}
entry={entry}
isActive={isActive}
onSelect={() => {
onSelect({ kind: 'filter', filter: 'favorites' })
onSelectNote?.(entry)
}}
/>
)
})}
</div>
</SortableContext>
</DndContext>
)}
</div>
)
}
function SidebarTitleBar({ onCollapse }: { onCollapse?: () => void }) {
const { onMouseDown } = useDragRegion()
return (
@@ -204,7 +300,7 @@ function CustomizeOverlay({ target, typeEntryMap, innerRef, onCustomize, onChang
export const Sidebar = memo(function Sidebar({
entries, selection, onSelect,
onCustomizeType, onUpdateTypeTemplate, onReorderSections, onRenameSection,
onToggleTypeVisibility,
onToggleTypeVisibility, onSelectFavorite, onReorderFavorites,
folders = [], onCreateFolder, inboxCount = 0, onCollapse,
}: SidebarProps) {
const [customizeTarget, setCustomizeTarget] = useState<string | null>(null)
@@ -289,6 +385,9 @@ export const Sidebar = memo(function Sidebar({
<NavItem icon={Trash} label="Trash" count={trashedCount} isActive={isSelectionActive(selection, { kind: 'filter', filter: 'trash' })} activeClassName="bg-destructive/10 text-destructive" badgeClassName="text-muted-foreground" badgeStyle={{ background: 'var(--muted)' }} activeBadgeClassName="bg-destructive text-destructive-foreground" onClick={() => onSelect({ kind: 'filter', filter: 'trash' })} />
</div>
{/* Favorites */}
<FavoritesSection entries={entries} selection={selection} onSelect={onSelect} onSelectNote={onSelectFavorite} onReorder={onReorderFavorites} />
{/* Sections header + visibility popover */}
<div ref={customizeRef} style={{ position: 'relative', padding: '4px 6px 0' }}>
<div className="flex w-full select-none items-center justify-between" style={{ padding: '4px 16px' }}>

View File

@@ -12,6 +12,7 @@ const ENTRY_DELETE_MAP: Record<string, Partial<VaultEntry>> = {
aliases: { aliases: [] }, belongs_to: { belongsTo: [] }, related_to: { relatedTo: [] },
archived: { archived: false }, trashed: { trashed: false }, order: { order: null },
template: { template: null }, sort: { sort: null }, visible: { visible: null },
_favorite: { favorite: false }, _favorite_index: { favoriteIndex: null },
}
/** Check if a string contains a wikilink pattern `[[...]]`. */
@@ -58,6 +59,8 @@ export function frontmatterToEntryPatch(
sort: { sort: str },
view: { view: str },
visible: { visible: value === false ? false : null },
_favorite: { favorite: Boolean(value) },
_favorite_index: { favoriteIndex: typeof value === 'number' ? value : null },
}
// Also update the relationships map for wikilink-containing values
const wikilinks = value != null ? extractWikilinks(value) : []

View File

@@ -125,6 +125,42 @@ export function useEntryActions({
onFrontmatterPersisted?.()
}, [entries, handleUpdateFrontmatter, handleDeleteProperty, updateEntry, createTypeEntry, onFrontmatterPersisted])
const handleToggleFavorite = useCallback(async (path: string) => {
const entry = entries.find((e) => e.path === path)
if (!entry) return
if (entry.favorite) {
updateEntry(path, { favorite: false, favoriteIndex: null })
try {
await handleDeleteProperty(path, '_favorite', { silent: true })
await handleDeleteProperty(path, '_favorite_index', { silent: true })
onFrontmatterPersisted?.()
} catch {
updateEntry(path, { favorite: true, favoriteIndex: entry.favoriteIndex })
setToastMessage('Failed to unfavorite — rolled back')
}
} else {
const maxIndex = entries.filter((e) => e.favorite).reduce((max, e) => Math.max(max, e.favoriteIndex ?? 0), 0)
const newIndex = maxIndex + 1
updateEntry(path, { favorite: true, favoriteIndex: newIndex })
try {
await handleUpdateFrontmatter(path, '_favorite', true, { silent: true })
await handleUpdateFrontmatter(path, '_favorite_index', newIndex, { silent: true })
onFrontmatterPersisted?.()
} catch {
updateEntry(path, { favorite: false, favoriteIndex: null })
setToastMessage('Failed to favorite — rolled back')
}
}
}, [entries, updateEntry, handleUpdateFrontmatter, handleDeleteProperty, setToastMessage, onFrontmatterPersisted])
const handleReorderFavorites = useCallback(async (orderedPaths: string[]) => {
for (let i = 0; i < orderedPaths.length; i++) {
updateEntry(orderedPaths[i], { favoriteIndex: i })
await handleUpdateFrontmatter(orderedPaths[i], '_favorite_index', i, { silent: true })
}
onFrontmatterPersisted?.()
}, [updateEntry, handleUpdateFrontmatter, onFrontmatterPersisted])
const handleToggleTypeVisibility = useCallback(async (typeName: string) => {
const typeEntry = await findOrCreateType(entries, typeName, createTypeEntry)
if (typeEntry.visible === false) {
@@ -137,5 +173,5 @@ export function useEntryActions({
onFrontmatterPersisted?.()
}, [entries, handleUpdateFrontmatter, handleDeleteProperty, updateEntry, createTypeEntry, onFrontmatterPersisted])
return { handleTrashNote, handleRestoreNote, handleArchiveNote, handleUnarchiveNote, handleCustomizeType, handleReorderSections, handleUpdateTypeTemplate, handleRenameSection, handleToggleTypeVisibility }
return { handleTrashNote, handleRestoreNote, handleArchiveNote, handleUnarchiveNote, handleCustomizeType, handleReorderSections, handleUpdateTypeTemplate, handleRenameSection, handleToggleTypeVisibility, handleToggleFavorite, handleReorderFavorites }
}

View File

@@ -35,6 +35,10 @@ export interface VaultEntry {
view: string | null
/** Whether this Type is visible in the sidebar. Defaults to true when absent. */
visible: boolean | null
/** Whether this note is a user favorite (shown in FAVORITES sidebar section). */
favorite: boolean
/** Display order within the FAVORITES section (lower = higher). */
favoriteIndex: number | null
/** All wikilink targets found in the note content. Extracted from [[target]] patterns. */
outgoingLinks: string[]
/** Custom scalar frontmatter properties (non-relationship, non-structural). */
@@ -171,7 +175,7 @@ export interface PulseCommit {
deleted: number
}
export type SidebarFilter = 'all' | 'archived' | 'trash' | 'changes' | 'pulse' | 'inbox'
export type SidebarFilter = 'all' | 'archived' | 'trash' | 'changes' | 'pulse' | 'inbox' | 'favorites'
export type InboxPeriod = 'week' | 'month' | 'quarter' | 'all'

View File

@@ -336,6 +336,7 @@ function filterByFilterType(entries: VaultEntry[], filter: string): VaultEntry[]
if (filter === 'all') return entries.filter(isActive)
if (filter === 'archived') return entries.filter((e) => e.archived && !e.trashed)
if (filter === 'trash') return entries.filter((e) => e.trashed)
if (filter === 'favorites') return entries.filter((e) => e.favorite && !e.archived && !e.trashed)
if (filter === 'pulse') return []
return []
}