Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart

Add per-book notes with markdown, welcome sheet, tips updates

Nathan Poulson0311127d0c58
diff --git a/lib/screens/app_shell.dart b/lib/screens/app_shell.dart
index dab79682..458255de 100644
--- a/lib/screens/app_shell.dart
+++ b/lib/screens/app_shell.dart
@@ -17,6 +17,7 @@ import 'home_screen.dart';
import 'library_screen.dart';
import 'stats_screen.dart';
import 'settings_screen.dart';
+import '../widgets/welcome_sheet.dart';
class AppShell extends StatefulWidget {
const AppShell({super.key});
@@ -148,6 +149,7 @@ class _AppShellState extends State<AppShell> with WidgetsBindingObserver, Ticker
// Try immediately; _onLibraryChanged picks it up once data loads.
_deriveCoverScheme();
context.read<LibraryProvider>().addListener(_onLibraryChanged);
+ WelcomeSheet.showIfNeeded(context);
}
@override
diff --git a/lib/screens/settings_screen.dart b/lib/screens/settings_screen.dart
index bff9888b..68bb45fc 100644
--- a/lib/screens/settings_screen.dart
+++ b/lib/screens/settings_screen.dart
@@ -354,6 +354,21 @@ class _SettingsScreenState extends State<SettingsScreen> {
title: 'Download for Offline',
desc: 'Tap the download button in any book\'s detail popup to save it for offline listening. Downloaded books are available in offline mode without any internet connection.',
),
+ _tipCard(cs, tt,
+ icon: Icons.dashboard_customize_rounded,
+ title: 'Customize Home',
+ desc: 'Tap the edit button in the top right of the Home screen to rearrange, hide, or show sections. Drag sections into your preferred order.',
+ ),
+ _tipCard(cs, tt,
+ icon: Icons.playlist_play_rounded,
+ title: 'Playlists',
+ desc: 'Create and manage playlists on your Audiobookshelf server and they\'ll appear as sections on your Home screen. Add books to playlists from any book\'s detail popup.',
+ ),
+ _tipCard(cs, tt,
+ icon: Icons.collections_bookmark_rounded,
+ title: 'Collections',
+ desc: 'Collections group related books together and show up as Home sections. Root admins can add books and edit collections from the detail popup.',
+ ),
],
),
),
diff --git a/lib/services/backup_service.dart b/lib/services/backup_service.dart
index 9e258b88..4e9d61e5 100644
--- a/lib/services/backup_service.dart
+++ b/lib/services/backup_service.dart
@@ -121,6 +121,17 @@ class BackupService {
}
}
+ // Notes for current account (scoped)
+ final notes = <String, String>{};
+ final notesPrefix = scope.isNotEmpty ? '$scope:notes_' : 'notes_';
+ for (final key in prefs.getKeys()) {
+ if (key.startsWith(notesPrefix)) {
+ final itemId = key.substring(notesPrefix.length);
+ final value = prefs.getString(key);
+ if (value != null && value.isNotEmpty) notes[itemId] = value;
+ }
+ }
+
// Saved ebooks (scoped)
final savedEbooks = await ScopedPrefs.getStringList('saved_ebooks');
@@ -154,6 +165,7 @@ class BackupService {
'bookSpeeds': bookSpeeds,
'offlineMode': offlineMode,
'bookmarks': bookmarks,
+ 'notes': notes,
'savedEbooks': savedEbooks,
'rollingDownloadSeries': rollingDownloadSeries,
'accounts': accounts,
@@ -286,6 +298,14 @@ class BackupService {
}
}
+ // Notes (scoped)
+ final notes = data['notes'] as Map<String, dynamic>?;
+ if (notes != null) {
+ for (final entry in notes.entries) {
+ await ScopedPrefs.setString('notes_${entry.key}', entry.value as String);
+ }
+ }
+
// Saved ebooks (scoped)
final savedEbooks = data['savedEbooks'] as List<dynamic>?;
if (savedEbooks != null && savedEbooks.isNotEmpty) {
diff --git a/lib/services/notes_service.dart b/lib/services/notes_service.dart
new file mode 100644
index 00000000..1d3c0a16
--- /dev/null
+++ b/lib/services/notes_service.dart
@@ -0,0 +1,95 @@
+import 'dart:convert';
+import 'package:flutter/foundation.dart';
+import 'scoped_prefs.dart';
+
+/// A single note attached to a library item.
+class Note {
+ String title;
+ String body;
+ final DateTime createdAt;
+ DateTime updatedAt;
+
+ Note({
+ required this.title,
+ required this.body,
+ DateTime? createdAt,
+ DateTime? updatedAt,
+ }) : createdAt = createdAt ?? DateTime.now(),
+ updatedAt = updatedAt ?? DateTime.now();
+
+ Map<String, dynamic> toJson() => {
+ 'title': title,
+ 'body': body,
+ 'createdAt': createdAt.toIso8601String(),
+ 'updatedAt': updatedAt.toIso8601String(),
+ };
+
+ factory Note.fromJson(Map<String, dynamic> json) => Note(
+ title: json['title'] as String? ?? '',
+ body: json['body'] as String? ?? '',
+ createdAt: DateTime.tryParse(json['createdAt'] as String? ?? ''),
+ updatedAt: DateTime.tryParse(json['updatedAt'] as String? ?? ''),
+ );
+}
+
+/// Manages per-item notes stored in ScopedPrefs.
+class NotesService {
+ static final NotesService _instance = NotesService._();
+ factory NotesService() => _instance;
+ NotesService._();
+
+ static String _key(String itemId) => 'notes_$itemId';
+
+ /// Get all notes for an item, newest first.
+ Future<List<Note>> getNotes(String itemId) async {
+ final raw = await ScopedPrefs.getString(_key(itemId));
+ if (raw == null || raw.isEmpty) return [];
+ try {
+ final list = jsonDecode(raw) as List<dynamic>;
+ return list
+ .map((e) => Note.fromJson(e as Map<String, dynamic>))
+ .toList()
+ ..sort((a, b) => b.updatedAt.compareTo(a.updatedAt));
+ } catch (e) {
+ debugPrint('[Notes] Failed to parse notes for $itemId: $e');
+ return [];
+ }
+ }
+
+ /// Save notes for an item.
+ Future<void> saveNotes(String itemId, List<Note> notes) async {
+ final json = jsonEncode(notes.map((n) => n.toJson()).toList());
+ await ScopedPrefs.setString(_key(itemId), json);
+ }
+
+ /// Add a new note to an item.
+ Future<void> addNote(String itemId, {required String title, required String body}) async {
+ final notes = await getNotes(itemId);
+ notes.insert(0, Note(title: title, body: body));
+ await saveNotes(itemId, notes);
+ }
+
+ /// Update a note at the given index.
+ Future<void> updateNote(String itemId, int index, {required String title, required String body}) async {
+ final notes = await getNotes(itemId);
+ if (index < 0 || index >= notes.length) return;
+ notes[index].title = title;
+ notes[index].body = body;
+ notes[index].updatedAt = DateTime.now();
+ await saveNotes(itemId, notes);
+ }
+
+ /// Delete a note at the given index.
+ Future<void> deleteNote(String itemId, int index) async {
+ final notes = await getNotes(itemId);
+ if (index < 0 || index >= notes.length) return;
+ notes.removeAt(index);
+ await saveNotes(itemId, notes);
+ }
+
+ /// Count notes for an item (lightweight, for badge display).
+ Future<int> countNotes(String itemId) async {
+ final notes = await getNotes(itemId);
+ return notes.length;
+ }
+}
diff --git a/lib/widgets/absorbing_card.dart b/lib/widgets/absorbing_card.dart
index 982e1696..76447110 100644
--- a/lib/widgets/absorbing_card.dart
+++ b/lib/widgets/absorbing_card.dart
@@ -22,6 +22,7 @@ import '../services/chromecast_service.dart';
import '../services/progress_sync_service.dart';
import 'expanded_card.dart';
import '../screens/car_mode_screen.dart';
+import 'notes_sheet.dart';
class AbsorbingCard extends StatefulWidget {
final Map<String, dynamic> item;
@@ -1027,6 +1028,12 @@ class AbsorbingCardState extends State<AbsorbingCard> with AutomaticKeepAliveCli
accent: accent, isActive: true, alwaysEnabled: true, large: large,
onTap: () => _openCarMode(context),
);
+ case 'notes':
+ return CardWideButton(
+ icon: Icons.note_rounded, label: 'Notes',
+ accent: accent, isActive: true, alwaysEnabled: true, large: large,
+ onTap: () => _showNotes(context, accent),
+ );
default:
return const SizedBox.shrink();
}
@@ -1134,11 +1141,24 @@ class AbsorbingCardState extends State<AbsorbingCard> with AutomaticKeepAliveCli
icon: Icons.directions_car_rounded, label: 'Car Mode', accent: accent,
onTap: () { Navigator.pop(ctx); _openCarMode(context); },
);
+ case 'notes':
+ return MoreMenuItem(
+ icon: Icons.note_rounded, label: 'Notes', accent: accent,
+ onTap: () { Navigator.pop(ctx); _showNotes(context, accent); },
+ );
default:
return const SizedBox.shrink();
}
}
+ void _showNotes(BuildContext context, Color accent) {
+ NotesSheet.show(context,
+ itemId: _itemId,
+ itemTitle: _title,
+ accent: accent,
+ );
+ }
+
void _openCarMode(BuildContext context) {
Navigator.of(context).push(MaterialPageRoute(
builder: (_) => CarModeScreen(
diff --git a/lib/widgets/card_button_config.dart b/lib/widgets/card_button_config.dart
index 13d831cf..19422d75 100644
--- a/lib/widgets/card_button_config.dart
+++ b/lib/widgets/card_button_config.dart
@@ -18,6 +18,7 @@ const allCardButtons = [
CardButtonDef('history', 'Playback History', Icons.history_rounded),
CardButtonDef('remove', 'Remove from Absorbing', Icons.remove_circle_outline_rounded),
CardButtonDef('car', 'Car Mode', Icons.directions_car_rounded),
+ CardButtonDef('notes', 'Notes', Icons.note_rounded),
];
/// Look up a button definition by ID.
diff --git a/lib/widgets/expanded_card.dart b/lib/widgets/expanded_card.dart
index a67be272..a79f6269 100644
--- a/lib/widgets/expanded_card.dart
+++ b/lib/widgets/expanded_card.dart
@@ -20,6 +20,7 @@ import 'card_buttons.dart';
import 'chromecast_button.dart';
import 'sleep_timer_sheet.dart';
import '../screens/car_mode_screen.dart';
+import 'notes_sheet.dart';
// ─── Custom route: slide-up + fade ────────────────────────────
@@ -1102,6 +1103,12 @@ class _ExpandedCardState extends State<ExpandedCard> {
accent: accent, isActive: true, alwaysEnabled: true, large: large,
onTap: () => _openCarMode(context),
);
+ case 'notes':
+ return CardWideButton(
+ icon: Icons.note_rounded, label: 'Notes',
+ accent: accent, isActive: true, alwaysEnabled: true, large: large,
+ onTap: () => _showNotes(context, accent),
+ );
default:
return const SizedBox.shrink();
}
@@ -1209,11 +1216,24 @@ class _ExpandedCardState extends State<ExpandedCard> {
icon: Icons.directions_car_rounded, label: 'Car Mode', accent: accent,
onTap: () { Navigator.pop(ctx); _openCarMode(context); },
);
+ case 'notes':
+ return MoreMenuItem(
+ icon: Icons.note_rounded, label: 'Notes', accent: accent,
+ onTap: () { Navigator.pop(ctx); _showNotes(context, accent); },
+ );
default:
return const SizedBox.shrink();
}
}
+ void _showNotes(BuildContext context, Color accent) {
+ NotesSheet.show(context,
+ itemId: _itemId,
+ itemTitle: _title,
+ accent: accent,
+ );
+ }
+
void _openCarMode(BuildContext context) {
Navigator.of(context).push(MaterialPageRoute(
builder: (_) => CarModeScreen(
diff --git a/lib/widgets/notes_sheet.dart b/lib/widgets/notes_sheet.dart
new file mode 100644
index 00000000..60206eb7
--- /dev/null
+++ b/lib/widgets/notes_sheet.dart
@@ -0,0 +1,547 @@
+import 'dart:io';
+import 'package:flutter/material.dart';
+import 'package:flutter_markdown_plus/flutter_markdown_plus.dart';
+import 'package:path_provider/path_provider.dart';
+import 'package:share_plus/share_plus.dart';
+import 'package:url_launcher/url_launcher.dart';
+import '../services/notes_service.dart';
+
+/// Bottom sheet displaying notes for a library item.
+class NotesSheet extends StatefulWidget {
+ final String itemId;
+ final String itemTitle;
+ final Color accent;
+ final ScrollController? scrollController;
+
+ const NotesSheet({
+ super.key,
+ required this.itemId,
+ required this.itemTitle,
+ required this.accent,
+ this.scrollController,
+ });
+
+ static void show(BuildContext context, {
+ required String itemId,
+ required String itemTitle,
+ required Color accent,
+ }) {
+ showModalBottomSheet(
+ context: context,
+ isScrollControlled: true,
+ useSafeArea: true,
+ backgroundColor: Colors.transparent,
+ builder: (_) => DraggableScrollableSheet(
+ initialChildSize: 0.75,
+ minChildSize: 0.05,
+ snap: true,
+ maxChildSize: 0.95,
+ expand: false,
+ builder: (_, scrollController) => NotesSheet(
+ itemId: itemId,
+ itemTitle: itemTitle,
+ accent: accent,
+ scrollController: scrollController,
+ ),
+ ),
+ );
+ }
+
+ @override
+ State<NotesSheet> createState() => _NotesSheetState();
+}
+
+class _NotesSheetState extends State<NotesSheet> {
+ List<Note> _notes = [];
+ bool _isLoading = true;
+
+ @override
+ void initState() {
+ super.initState();
+ _loadNotes();
+ }
+
+ Future<void> _loadNotes() async {
+ final notes = await NotesService().getNotes(widget.itemId);
+ if (mounted) setState(() { _notes = notes; _isLoading = false; });
+ }
+
+ Future<void> _addNote() async {
+ final result = await _showEditor(context);
+ if (result == null) return;
+ await NotesService().addNote(widget.itemId, title: result.title, body: result.body);
+ _loadNotes();
+ }
+
+ Future<void> _editNote(int index) async {
+ final note = _notes[index];
+ final result = await _showEditor(context, title: note.title, body: note.body);
+ if (result == null) return;
+ await NotesService().updateNote(widget.itemId, index, title: result.title, body: result.body);
+ _loadNotes();
+ }
+
+ Future<void> _deleteNote(int index) async {
+ final confirmed = await showDialog<bool>(
+ context: context,
+ builder: (ctx) => AlertDialog(
+ title: const Text('Delete note?'),
+ content: Text('This will delete "${_notes[index].title.isEmpty ? "Untitled note" : _notes[index].title}".'),
+ actions: [
+ TextButton(onPressed: () => Navigator.pop(ctx, false), child: const Text('Cancel')),
+ FilledButton(onPressed: () => Navigator.pop(ctx, true), child: const Text('Delete')),
+ ],
+ ),
+ );
+ if (confirmed != true) return;
+ await NotesService().deleteNote(widget.itemId, index);
+ _loadNotes();
+ }
+
+ Future<void> _exportNotes(BuildContext context) async {
+ final cs = Theme.of(context).colorScheme;
+ final format = await showModalBottomSheet<String>(
+ context: context,
+ backgroundColor: Colors.transparent,
+ builder: (ctx) => Container(
+ decoration: BoxDecoration(
+ color: cs.surface,
+ borderRadius: const BorderRadius.vertical(top: Radius.circular(24)),
+ ),
+ padding: const EdgeInsets.fromLTRB(16, 8, 16, 24),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Center(child: Container(
+ width: 32, height: 4, margin: const EdgeInsets.only(bottom: 16),
+ decoration: BoxDecoration(
+ color: cs.onSurface.withValues(alpha: 0.2),
+ borderRadius: BorderRadius.circular(2),
+ ),
+ )),
+ ListTile(
+ leading: const Icon(Icons.description_rounded),
+ title: const Text('Markdown (.md)'),
+ subtitle: const Text('Keeps formatting intact'),
+ shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
+ onTap: () => Navigator.pop(ctx, 'md'),
+ ),
+ ListTile(
+ leading: const Icon(Icons.text_snippet_rounded),
+ title: const Text('Plain Text (.txt)'),
+ subtitle: const Text('Simple text, no formatting'),
+ shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
+ onTap: () => Navigator.pop(ctx, 'txt'),
+ ),
+ ],
+ ),
+ ),
+ );
+ if (format == null || !mounted) return;
+
+ final buffer = StringBuffer();
+ final isMd = format == 'md';
+ buffer.writeln(isMd ? '# ${widget.itemTitle} - Notes' : '${widget.itemTitle} - Notes');
+ buffer.writeln();
+ for (final note in _notes) {
+ final title = note.title.isEmpty ? 'Untitled' : note.title;
+ buffer.writeln(isMd ? '## $title' : '--- $title ---');
+ if (note.body.isNotEmpty) {
+ buffer.writeln();
+ buffer.writeln(isMd ? note.body : note.body.replaceAll(RegExp(r'[*_`#>]'), ''));
+ }
+ buffer.writeln();
+ }
+
+ final dir = await getTemporaryDirectory();
+ final safe = widget.itemTitle.replaceAll(RegExp(r'[<>:"/\\|?*]'), '_');
+ final file = File('${dir.path}/${safe}_notes.$format');
+ await file.writeAsString(buffer.toString());
+ await Share.shareXFiles([XFile(file.path)]);
+ }
+
+ Future<_NoteEditResult?> _showEditor(BuildContext context, {String title = '', String body = ''}) {
+ return showModalBottomSheet<_NoteEditResult>(
+ context: context,
+ isScrollControlled: true,
+ useSafeArea: true,
+ backgroundColor: Colors.transparent,
+ builder: (_) => _NoteEditor(title: title, body: body, accent: widget.accent),
+ );
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ final cs = Theme.of(context).colorScheme;
+ final tt = Theme.of(context).textTheme;
+
+ return Container(
+ decoration: BoxDecoration(
+ color: cs.surface,
+ borderRadius: const BorderRadius.vertical(top: Radius.circular(24)),
+ ),
+ child: Column(
+ children: [
+ // Handle
+ const SizedBox(height: 8),
+ Center(child: Container(
+ width: 32, height: 4,
+ decoration: BoxDecoration(
+ color: cs.onSurface.withValues(alpha: 0.2),
+ borderRadius: BorderRadius.circular(2),
+ ),
+ )),
+ // Header
+ Padding(
+ padding: const EdgeInsets.fromLTRB(16, 12, 8, 8),
+ child: Row(children: [
+ Icon(Icons.note_rounded, color: widget.accent, size: 22),
+ const SizedBox(width: 10),
+ Expanded(child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text('Notes', style: tt.titleMedium?.copyWith(fontWeight: FontWeight.w600)),
+ Text(widget.itemTitle, maxLines: 1, overflow: TextOverflow.ellipsis,
+ style: tt.bodySmall?.copyWith(color: cs.onSurfaceVariant)),
+ ],
+ )),
+ if (_notes.isNotEmpty)
+ IconButton(
+ icon: const Icon(Icons.ios_share_rounded),
+ tooltip: 'Export',
+ onPressed: () => _exportNotes(context),
+ ),
+ IconButton(
+ icon: const Icon(Icons.add_rounded),
+ tooltip: 'New note',
+ onPressed: _addNote,
+ ),
+ ]),
+ ),
+ const Divider(height: 1),
+ // Notes list
+ Expanded(
+ child: _isLoading
+ ? const Center(child: CircularProgressIndicator())
+ : _notes.isEmpty
+ ? Center(child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Icon(Icons.note_add_rounded, size: 48,
+ color: cs.onSurface.withValues(alpha: 0.15)),
+ const SizedBox(height: 12),
+ Text('No notes yet', style: tt.bodyMedium?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.4))),
+ const SizedBox(height: 8),
+ Text('Markdown is supported', style: tt.bodySmall?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.25))),
+ ],
+ ))
+ : ListView.separated(
+ controller: widget.scrollController,
+ padding: const EdgeInsets.fromLTRB(16, 8, 16, 32),
+ itemCount: _notes.length,
+ separatorBuilder: (_, __) => const SizedBox(height: 8),
+ itemBuilder: (context, index) {
+ final note = _notes[index];
+ return Dismissible(
+ key: ValueKey('${note.createdAt.toIso8601String()}_$index'),
+ direction: DismissDirection.endToStart,
+ background: Container(
+ alignment: Alignment.centerRight,
+ padding: const EdgeInsets.only(right: 20),
+ decoration: BoxDecoration(
+ color: cs.error.withValues(alpha: 0.12),
+ borderRadius: BorderRadius.circular(14),
+ ),
+ child: Icon(Icons.delete_outline_rounded, color: cs.error),
+ ),
+ confirmDismiss: (_) async {
+ return await showDialog<bool>(
+ context: context,
+ builder: (ctx) => AlertDialog(
+ title: const Text('Delete note?'),
+ actions: [
+ TextButton(onPressed: () => Navigator.pop(ctx, false), child: const Text('Cancel')),
+ FilledButton(onPressed: () => Navigator.pop(ctx, true), child: const Text('Delete')),
+ ],
+ ),
+ ) ?? false;
+ },
+ onDismissed: (_) async {
+ await NotesService().deleteNote(widget.itemId, index);
+ _loadNotes();
+ },
+ child: _NoteCard(
+ note: note,
+ accent: widget.accent,
+ onTap: () => _editNote(index),
+ onDelete: () => _deleteNote(index),
+ ),
+ );
+ },
+ ),
+ ),
+ ],
+ ),
+ );
+ }
+}
+
+// ── Note Card ──
+
+class _NoteCard extends StatelessWidget {
+ final Note note;
+ final Color accent;
+ final VoidCallback onTap;
+ final VoidCallback onDelete;
+
+ const _NoteCard({
+ required this.note,
+ required this.accent,
+ required this.onTap,
+ required this.onDelete,
+ });
+
+ @override
+ Widget build(BuildContext context) {
+ final cs = Theme.of(context).colorScheme;
+ final tt = Theme.of(context).textTheme;
+ final title = note.title.isEmpty ? 'Untitled' : note.title;
+
+ return GestureDetector(
+ onTap: onTap,
+ onLongPress: onDelete,
+ child: Container(
+ padding: const EdgeInsets.all(14),
+ decoration: BoxDecoration(
+ color: cs.surfaceContainerHigh,
+ borderRadius: BorderRadius.circular(14),
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Row(children: [
+ Expanded(child: Text(title,
+ style: tt.titleSmall?.copyWith(fontWeight: FontWeight.w600),
+ maxLines: 1, overflow: TextOverflow.ellipsis)),
+ Text(_formatDate(note.updatedAt),
+ style: tt.labelSmall?.copyWith(color: cs.onSurfaceVariant)),
+ ]),
+ if (note.body.isNotEmpty) ...[
+ const SizedBox(height: 8),
+ MarkdownBody(
+ data: note.body,
+ shrinkWrap: true,
+ selectable: true,
+ onTapLink: (_, href, __) {
+ if (href != null) launchUrl(Uri.parse(href));
+ },
+ styleSheet: MarkdownStyleSheet(
+ p: tt.bodySmall?.copyWith(color: cs.onSurface.withValues(alpha: 0.8), height: 1.5),
+ h1: tt.titleMedium?.copyWith(fontWeight: FontWeight.w700),
+ h2: tt.titleSmall?.copyWith(fontWeight: FontWeight.w600),
+ h3: tt.bodyMedium?.copyWith(fontWeight: FontWeight.w600),
+ code: tt.bodySmall?.copyWith(
+ fontFamily: 'monospace',
+ color: accent,
+ backgroundColor: cs.surfaceContainerHighest,
+ ),
+ codeblockDecoration: BoxDecoration(
+ color: cs.surfaceContainerHighest,
+ borderRadius: BorderRadius.circular(8),
+ ),
+ blockquoteDecoration: BoxDecoration(
+ border: Border(left: BorderSide(color: accent, width: 3)),
+ ),
+ blockquotePadding: const EdgeInsets.only(left: 12),
+ listBullet: tt.bodySmall?.copyWith(color: cs.onSurfaceVariant),
+ ),
+ ),
+ ],
+ ],
+ ),
+ ),
+ );
+ }
+
+ String _formatDate(DateTime dt) {
+ final now = DateTime.now();
+ final diff = now.difference(dt);
+ if (diff.inMinutes < 1) return 'Just now';
+ if (diff.inHours < 1) return '${diff.inMinutes}m ago';
+ if (diff.inDays < 1) return '${diff.inHours}h ago';
+ if (diff.inDays < 7) return '${diff.inDays}d ago';
+ return '${dt.month}/${dt.day}/${dt.year}';
+ }
+}
+
+// ── Note Editor ──
+
+class _NoteEditResult {
+ final String title;
+ final String body;
+ const _NoteEditResult(this.title, this.body);
+}
+
+class _NoteEditor extends StatefulWidget {
+ final String title;
+ final String body;
+ final Color accent;
+
+ const _NoteEditor({required this.title, required this.body, required this.accent});
+
+ @override
+ State<_NoteEditor> createState() => _NoteEditorState();
+}
+
+class _NoteEditorState extends State<_NoteEditor> {
+ late final TextEditingController _titleCtrl;
+ late final TextEditingController _bodyCtrl;
+ bool _preview = false;
+
+ @override
+ void initState() {
+ super.initState();
+ _titleCtrl = TextEditingController(text: widget.title);
+ _bodyCtrl = TextEditingController(text: widget.body);
+ }
+
+ @override
+ void dispose() {
+ _titleCtrl.dispose();
+ _bodyCtrl.dispose();
+ super.dispose();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ final cs = Theme.of(context).colorScheme;
+ final tt = Theme.of(context).textTheme;
+ final bottomInset = MediaQuery.of(context).viewInsets.bottom;
+
+ return Container(
+ constraints: BoxConstraints(
+ maxHeight: MediaQuery.of(context).size.height * 0.85,
+ ),
+ padding: EdgeInsets.only(bottom: bottomInset),
+ decoration: BoxDecoration(
+ color: cs.surface,
+ borderRadius: const BorderRadius.vertical(top: Radius.circular(24)),
+ ),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ const SizedBox(height: 8),
+ Center(child: Container(
+ width: 32, height: 4,
+ decoration: BoxDecoration(
+ color: cs.onSurface.withValues(alpha: 0.2),
+ borderRadius: BorderRadius.circular(2),
+ ),
+ )),
+ Padding(
+ padding: const EdgeInsets.fromLTRB(16, 12, 8, 0),
+ child: Row(children: [
+ Expanded(child: Text(
+ widget.title.isEmpty ? 'New Note' : 'Edit Note',
+ style: tt.titleMedium?.copyWith(fontWeight: FontWeight.w600),
+ )),
+ IconButton(
+ icon: Icon(_preview ? Icons.edit_rounded : Icons.preview_rounded),
+ tooltip: _preview ? 'Edit' : 'Preview',
+ onPressed: () => setState(() => _preview = !_preview),
+ ),
+ TextButton(
+ onPressed: () {
+ final title = _titleCtrl.text.trim();
+ final body = _bodyCtrl.text.trim();
+ if (title.isEmpty && body.isEmpty) {
+ Navigator.pop(context);
+ return;
+ }
+ Navigator.pop(context, _NoteEditResult(title, body));
+ },
+ child: const Text('Save'),
+ ),
+ ]),
+ ),
+ const Divider(height: 1),
+ Flexible(
+ child: SingleChildScrollView(
+ padding: const EdgeInsets.fromLTRB(16, 12, 16, 24),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ TextField(
+ controller: _titleCtrl,
+ decoration: InputDecoration(
+ hintText: 'Title',
+ border: OutlineInputBorder(borderRadius: BorderRadius.circular(12)),
+ contentPadding: const EdgeInsets.symmetric(horizontal: 14, vertical: 12),
+ ),
+ style: tt.titleSmall?.copyWith(fontWeight: FontWeight.w600),
+ ),
+ const SizedBox(height: 12),
+ if (_preview)
+ Container(
+ width: double.infinity,
+ constraints: const BoxConstraints(minHeight: 200),
+ padding: const EdgeInsets.all(14),
+ decoration: BoxDecoration(
+ color: cs.surfaceContainerHigh,
+ borderRadius: BorderRadius.circular(12),
+ ),
+ child: _bodyCtrl.text.trim().isEmpty
+ ? Text('Nothing to preview', style: tt.bodySmall?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.3)))
+ : MarkdownBody(
+ data: _bodyCtrl.text,
+ selectable: true,
+ onTapLink: (_, href, __) {
+ if (href != null) launchUrl(Uri.parse(href));
+ },
+ styleSheet: MarkdownStyleSheet(
+ p: tt.bodySmall?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.8), height: 1.5),
+ h1: tt.titleMedium?.copyWith(fontWeight: FontWeight.w700),
+ h2: tt.titleSmall?.copyWith(fontWeight: FontWeight.w600),
+ h3: tt.bodyMedium?.copyWith(fontWeight: FontWeight.w600),
+ code: tt.bodySmall?.copyWith(
+ fontFamily: 'monospace',
+ color: widget.accent,
+ backgroundColor: cs.surfaceContainerHighest,
+ ),
+ codeblockDecoration: BoxDecoration(
+ color: cs.surfaceContainerHighest,
+ borderRadius: BorderRadius.circular(8),
+ ),
+ blockquoteDecoration: BoxDecoration(
+ border: Border(left: BorderSide(color: widget.accent, width: 3)),
+ ),
+ blockquotePadding: const EdgeInsets.only(left: 12),
+ listBullet: tt.bodySmall?.copyWith(color: cs.onSurfaceVariant),
+ ),
+ ),
+ )
+ else
+ TextField(
+ controller: _bodyCtrl,
+ decoration: InputDecoration(
+ hintText: 'Write your note... (supports markdown)',
+ border: OutlineInputBorder(borderRadius: BorderRadius.circular(12)),
+ contentPadding: const EdgeInsets.all(14),
+ ),
+ maxLines: null,
+ minLines: 8,
+ style: tt.bodySmall?.copyWith(height: 1.5),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ ),
+ );
+ }
+}
diff --git a/lib/widgets/welcome_sheet.dart b/lib/widgets/welcome_sheet.dart
new file mode 100644
index 00000000..b17b6c6f
--- /dev/null
+++ b/lib/widgets/welcome_sheet.dart
@@ -0,0 +1,239 @@
+import 'package:flutter/material.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// Shows a one-time welcome sheet explaining the Absorbing system.
+class WelcomeSheet {
+ static const _prefKey = 'has_seen_welcome';
+
+ /// Show the welcome sheet if the user hasn't seen it before.
+ static Future<void> showIfNeeded(BuildContext context) async {
+ final prefs = await SharedPreferences.getInstance();
+ if (prefs.getBool(_prefKey) == true) return;
+ await prefs.setBool(_prefKey, true);
+ if (!context.mounted) return;
+ // Small delay so the app finishes its initial layout first
+ await Future.delayed(const Duration(milliseconds: 800));
+ if (!context.mounted) return;
+ showModalBottomSheet(
+ context: context,
+ isScrollControlled: true,
+ useSafeArea: true,
+ backgroundColor: Colors.transparent,
+ builder: (_) => const _WelcomeContent(),
+ );
+ }
+}
+
+class _WelcomeContent extends StatelessWidget {
+ const _WelcomeContent();
+
+ @override
+ Widget build(BuildContext context) {
+ final cs = Theme.of(context).colorScheme;
+ final tt = Theme.of(context).textTheme;
+
+ return Container(
+ constraints: BoxConstraints(
+ maxHeight: MediaQuery.of(context).size.height * 0.85,
+ ),
+ decoration: BoxDecoration(
+ color: cs.surface,
+ borderRadius: const BorderRadius.vertical(top: Radius.circular(24)),
+ ),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ const SizedBox(height: 12),
+ Center(
+ child: Container(
+ width: 40, height: 4,
+ decoration: BoxDecoration(
+ color: cs.onSurface.withValues(alpha: 0.2),
+ borderRadius: BorderRadius.circular(2),
+ ),
+ ),
+ ),
+ Flexible(
+ child: SingleChildScrollView(
+ padding: const EdgeInsets.fromLTRB(24, 20, 24, 32),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ // Header
+ Row(
+ children: [
+ Icon(Icons.waves_rounded, color: cs.primary, size: 28),
+ const SizedBox(width: 12),
+ Text('Welcome to Absorb',
+ style: tt.headlineSmall?.copyWith(
+ fontWeight: FontWeight.w700,
+ )),
+ ],
+ ),
+ const SizedBox(height: 8),
+ Text(
+ 'Here\'s a quick overview of how things work.',
+ style: tt.bodyMedium?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.6),
+ ),
+ ),
+ const SizedBox(height: 24),
+
+ _section(cs, tt,
+ icon: Icons.home_rounded,
+ title: 'Home',
+ body: 'Your personalized shelves from Audiobookshelf - continue listening, '
+ 'discover new titles, and browse your playlists and collections. '
+ 'Use the edit button in the top right to customize which sections appear and their order.',
+ ),
+
+ _section(cs, tt,
+ icon: Icons.library_books_rounded,
+ title: 'Library',
+ body: 'Browse your full library with tabs for books, series, and authors. '
+ 'Tap the active tab to open sort and filter options.',
+ ),
+
+ _section(cs, tt,
+ icon: Icons.waves_rounded,
+ title: 'Absorbing',
+ body: 'Your active listening queue. Books you start playing automatically '
+ 'appear here as swipeable cards with full playback controls.',
+ ),
+
+ _subsection(cs, tt,
+ title: 'Queue modes',
+ items: [
+ 'Off - playback stops when a book finishes',
+ 'Manual - auto-plays the next card in your queue',
+ 'Auto Absorb - automatically finds and plays the next book in a series',
+ ],
+ ),
+
+ _subsection(cs, tt,
+ title: 'Managing your queue',
+ items: [
+ 'Tap the reorder icon to drag cards into your preferred order or swipe to remove',
+ 'Add books manually from any book\'s detail sheet',
+ 'When a book finishes, choose to listen again, remove it, or let it auto-release',
+ ],
+ ),
+
+ _subsection(cs, tt,
+ title: 'Merge libraries',
+ items: [
+ 'Enable in Settings to show all your libraries together in one queue',
+ ],
+ ),
+
+ _section(cs, tt,
+ icon: Icons.download_rounded,
+ title: 'Downloads & Offline',
+ body: 'Download books for offline listening. Toggle offline mode with the '
+ 'airplane icon on the Absorbing screen. Your progress syncs back '
+ 'to the server automatically when you reconnect.',
+ ),
+
+ _section(cs, tt,
+ icon: Icons.settings_rounded,
+ title: 'Settings',
+ body: 'Configure queue behavior, sleep timers, playback speed, '
+ 'local server connections, and more.',
+ ),
+
+ const SizedBox(height: 16),
+ SizedBox(
+ width: double.infinity,
+ child: FilledButton(
+ onPressed: () => Navigator.pop(context),
+ style: FilledButton.styleFrom(
+ padding: const EdgeInsets.symmetric(vertical: 14),
+ shape: RoundedRectangleBorder(
+ borderRadius: BorderRadius.circular(14),
+ ),
+ ),
+ child: const Text('Get Started'),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ ),
+ );
+ }
+
+ Widget _section(ColorScheme cs, TextTheme tt, {
+ required IconData icon,
+ required String title,
+ required String body,
+ }) {
+ return Padding(
+ padding: const EdgeInsets.only(bottom: 20),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Row(children: [
+ Icon(icon, size: 18, color: cs.primary),
+ const SizedBox(width: 8),
+ Text(title, style: tt.titleSmall?.copyWith(
+ fontWeight: FontWeight.w600,
+ )),
+ ]),
+ const SizedBox(height: 6),
+ Padding(
+ padding: const EdgeInsets.only(left: 26),
+ child: Text(body, style: tt.bodySmall?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.7),
+ height: 1.5,
+ )),
+ ),
+ ],
+ ),
+ );
+ }
+
+ Widget _subsection(ColorScheme cs, TextTheme tt, {
+ required String title,
+ required List<String> items,
+ }) {
+ return Padding(
+ padding: const EdgeInsets.only(left: 26, bottom: 16),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(title, style: tt.labelMedium?.copyWith(
+ fontWeight: FontWeight.w600,
+ color: cs.onSurface.withValues(alpha: 0.8),
+ )),
+ const SizedBox(height: 4),
+ ...items.map((item) => Padding(
+ padding: const EdgeInsets.only(top: 3),
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Padding(
+ padding: const EdgeInsets.only(top: 6, right: 8),
+ child: Container(
+ width: 4, height: 4,
+ decoration: BoxDecoration(
+ color: cs.onSurface.withValues(alpha: 0.4),
+ shape: BoxShape.circle,
+ ),
+ ),
+ ),
+ Expanded(
+ child: Text(item, style: tt.bodySmall?.copyWith(
+ color: cs.onSurface.withValues(alpha: 0.6),
+ height: 1.4,
+ )),
+ ),
+ ],
+ ),
+ )),
+ ],
+ ),
+ );
+ }
+}
diff --git a/pubspec.lock b/pubspec.lock
index 66d7854e..efc65d8d 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -334,6 +334,14 @@ packages:
url: "https://pub.dev"
source: hosted
version: "7.2.0"
+ flutter_markdown_plus:
+ dependency: "direct main"
+ description:
+ name: flutter_markdown_plus
+ sha256: "039177906850278e8fb1cd364115ee0a46281135932fa8ecea8455522166d2de"
+ url: "https://pub.dev"
+ source: hosted
+ version: "1.0.7"
flutter_native_splash:
dependency: "direct main"
description:
@@ -503,6 +511,14 @@ packages:
url: "https://pub.dev"
source: hosted
version: "1.3.0"
+ markdown:
+ dependency: transitive
+ description:
+ name: markdown
+ sha256: "935e23e1ff3bc02d390bad4d4be001208ee92cc217cb5b5a6c19bc14aaa318c1"
+ url: "https://pub.dev"
+ source: hosted
+ version: "7.3.0"
marquee:
dependency: transitive
description:
diff --git a/pubspec.yaml b/pubspec.yaml
index 55d3c5a2..93493817 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -76,6 +76,7 @@ dependencies:
flutter_native_splash: ^2.4.4
vibration: ^3.1.8
webview_flutter: ^4.13.1
+ flutter_markdown_plus: ^1.0.7
dev_dependencies:
flutter_test: