halkyon-days/halkyon
Watch
1
0
Fork
You've already forked halkyon
 0
Code Issues Pull requests Projects Releases 37 Packages Wiki Activity Actions

feat(ui): every app's frame around its tabs, Learn's moved into halkyon_ui

Browse source 
NavigationFrame is Learn's AppShell without its router and its tabs: a
navigation rail from medium windows on with the app's icon on top,
leading to the first tab, a bar floating above the foot below, the
background of the screen in view around it, and a tick on every choice.
TabsStack is Learn's container of the tabs' navigators, every tab kept
alive and told whether it shows. Learn's shell is built on both, its
tests unchanged; Train's is next.

The rail's icon is drawn from 120 px at most in memory, as Learn's was.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
This commit is contained in:
Tizian 「ティツィアーン」 2026-10-30 23:52:39 +01:00
commit b45db6ea7c
Signed by: raisondetredev
GPG key ID: 07F6FCF405488B64
3 changed files with 444 additions and 171 deletions
Download patch file Download diff file Expand all files Collapse all files

2
apps/learn/AGENTS.md
View file

@ -35,7 +35,7 @@ A spaced-repetition learning app: studysets of flashcards, reviewed on an FSRS s
- **UTC for storing and sending, local time for display and day boundaries.** Serverpod sends `DateTime` as UTC and stores it in `timestamp without time zone` columns. Compare and compute in UTC; call `.toLocal()` only to display. "Due today", streaks and daily goals use the learner's **local** calendar day, computed on the client; the server never needs day boundaries.
- **Build configuration comes from `--dart-define`.** The client holds no secrets, ever.
- **Material comes from `package:material_ui`** (Cupertino from `package:cupertino_ui`), never from `package:flutter/material.dart`, which Flutter deprecates from its November 2026 release on. Packages still on the SDK's copy get the app's theme and localizations through `MaterialUiCompatibilityBridge` in `MaterialApp.builder`; remove it once they have moved.
- **Navigation is `go_router`**: the routes in `lib/src/app/app_router.dart`, their paths in `core/router/route_paths.dart`. Four tabs (Home, Library, Explore, Profile) are the branches of a `StatefulShellRoute`, each keeping its own stack of screens alive while another tab shows (`tabsContainer`, go_router's indexed stack plus `TabVisibility`, which a screen depends on to stop something once its tab is hidden); `AppShell` shows them as a navigation rail from 600 dp on and as a navigation bar below (Material 3 Expressive's shorter one, 64 dp, set in the theme: Flutter's Material library has none yet), floating above the bottom edge (`FloatingNavigationBar`): the tab screens run on beneath it (the shell's `extendBody`), every list ending with room for it (the body's bottom padding) and floating buttons lifted by `FloatingNavigationBar.coverOf`, with the background of the screen in view around it in between (`ScreenTint`); it steps aside inside a studyset (its screen, notes, paths and dictionary: `RoutePaths.isInsideStudyset`), whose own bar at the bottom takes its place, leaving a strip as high as the system's bar (decided 2026-10-11, as Material 3 puts toolbars below the top level and Vaia does), and choosing the open tab again returns to its first screen. A tab's own screens are routes nested in its branch, reached with `context.go` (a studyset's screen in the library), and **the screens behind a studyset are its path** (decided 2026-10-11; `feature/studyset/widget/studyset_navigation.dart`): a topic, at any depth, opens with the screens of the levels between pushed beneath it (`openStudysetWithin`; the same route, keyed by id and named by its location, so several stack), the path's steps and the levels a long press on back lists go up by popping to that page (`goUpTo`), and a studyset opened from elsewhere gets its levels beneath it (`openStudyset`). So back, Android's predictive back, iOS's swipe from the edge and the path all lead one level up. Below expanded windows the topics open in a sheet from the end of the path's line, never a drawer, whose swipe from the edge is iOS's way back. A studyset's notes and learning paths (working through one, writing it, writing a step) are routes of the Library branch too, so the tabs stay beside them. What needs the whole window (studying, a card, a PDF, settings) is a top-level route over the tabs, reached with `context.push`. Explore lists what is published (see *Explore and copies*).
- **Navigation is `go_router`**: the routes in `lib/src/app/app_router.dart`, their paths in `core/router/route_paths.dart`. Four tabs (Home, Library, Explore, Profile) are the branches of a `StatefulShellRoute`, each keeping its own stack of screens alive while another tab shows (`tabsContainer`, halkyon_ui's `TabsStack`: go_router's indexed stack plus `TabVisibility`, which a screen depends on to stop something once its tab is hidden); `AppShell` shows them through halkyon_ui's `NavigationFrame`, every Halkyon app's (decided 2026-10-30), as a navigation rail from 600 dp on and as a navigation bar below (Material 3 Expressive's shorter one, 64 dp, set in the theme: Flutter's Material library has none yet), floating above the bottom edge (`FloatingNavigationBar`): the tab screens run on beneath it (the shell's `extendBody`), every list ending with room for it (the body's bottom padding) and floating buttons lifted by `FloatingNavigationBar.coverOf`, with the background of the screen in view around it in between (`ScreenTint`); it steps aside inside a studyset (its screen, notes, paths and dictionary: `RoutePaths.isInsideStudyset`), whose own bar at the bottom takes its place, leaving a strip as high as the system's bar (decided 2026-10-11, as Material 3 puts toolbars below the top level and Vaia does), and choosing the open tab again returns to its first screen. A tab's own screens are routes nested in its branch, reached with `context.go` (a studyset's screen in the library), and **the screens behind a studyset are its path** (decided 2026-10-11; `feature/studyset/widget/studyset_navigation.dart`): a topic, at any depth, opens with the screens of the levels between pushed beneath it (`openStudysetWithin`; the same route, keyed by id and named by its location, so several stack), the path's steps and the levels a long press on back lists go up by popping to that page (`goUpTo`), and a studyset opened from elsewhere gets its levels beneath it (`openStudyset`). So back, Android's predictive back, iOS's swipe from the edge and the path all lead one level up. Below expanded windows the topics open in a sheet from the end of the path's line, never a drawer, whose swipe from the edge is iOS's way back. A studyset's notes and learning paths (working through one, writing it, writing a step) are routes of the Library branch too, so the tabs stay beside them. What needs the whole window (studying, a card, a PDF, settings) is a top-level route over the tabs, reached with `context.push`. Explore lists what is published (see *Explore and copies*).
- **Routes carry ids, never objects.** A screen finds its item in the repository's live list with `FoundById`: a spinner until the list arrives, then the item, or a screen saying it no longer exists (deleted on another device, or an old link). A screen that deletes its item closes, and keeps showing the item while it goes. Why: every location can be built from its path alone, and no screen goes on showing something that has gone.
- **The look is one theme, every Halkyon app's**: the theme, its fonts, the window sizes and the shared widgets come from `halkyon_ui` (`packages/halkyon_ui`, decided 2026-10-18). Change them there, not here. `appTheme(brightness, extensions:)` with hand-written light and dark colour schemes around the brand's cobalt and copper, which Learn calls as `learnTheme` (`core/theme/`) with its own colours beside; `Theme.of(context).extras` (`ThemeExtras`) for the states Material has no role for, and `Theme.of(context).learnColors` (`LearnColors`) for Learn's own (the four FSRS ratings, a starred star); `PaletteColor` for the 20 colours a person can give content; snack bars floating above the navigation bar as Material 3 places them, in its inverse colours (dark in the light theme), lined up with the floating bar, 560 wide and centred from medium windows on (`FittedSnackBars`, decided 2026-10-12; Flutter's default is Material 2's fixed bar across the foot); `TopGradient` for a colour washing down from the top of every tab's first screen and Settings (cobalt) and of every screen of a studyset (its colour, own or inherited, which `_inStudyset` in the router hands down as `ScreenColor`): the studyset, studying it, its cards, writing them, its notes, paths and dictionary; behind a clear app bar, in dark mode a deep shade (42 % of the colour over black), in light mode a tint, held to WCAG AA for the theme's text. From medium windows on, a `TintFrame` takes the colour of the screen in view (`ScreenTint`, claimed by the `TopGradient` whose tab shows and whose route is on top), fading out by 60 % of the height: the rail sits on it, transparent, and the screen is a rounded panel inset beside it, its own wash half as strong; screens over the tabs (studying, the card browser and composer, Settings) sit in the same frame without the rail (`FramedScreen`). As Vaia does, decided 2026-10-10. The PDF reader and the reading timeline stay plain. halkyon_ui's `theme_test.dart` holds text to WCAG AA contrast (4.5:1) on each palette colour and on the dark theme's primary colour and surface, and Learn's `learn_theme_test.dart` a starred star to 3:1 on the cards. **Fonts are bundled, never fetched** (halkyon_ui's `app_fonts.dart`; the CJK fonts are the app's own, `assets/fonts/ATTRIBUTION.md`, their licence registered by `core/theme/cjk_fonts.dart`, under the families halkyon_ui's fallback names): Noto Sans, from halkyon_ui, is the app's font on every device (Latin, Greek with polytonic, Cyrillic); Noto Sans JP, SC, TC and KR fill in Japanese, Chinese and Korean, Japanese first unless a studyset's language puts its own first (`StudysetLanguageScope`, which every studyset route wraps its screen in through `_inStudyset`, and the library's and Explore's cards each around their studyset; Han characters take the first listed font's shapes); each is one variable font holding every weight, and their OFL licences join the licence list. Scripts none covers (Arabic, Hebrew, Thai, …) fall back to the device's own fonts. A studyset's languages (`frontLanguage`, `backLanguage`, BCP 47) are given together or inherited together from the nearest studyset above (`languagesOf`). Never add `google_fonts` or anything else that downloads fonts. Layouts follow Material 3's window-size classes (`context.windowSize`), and running text stays within `readableContentMaxWidth`. Icons are Lucide (`lucide_icons_flutter`), except a starred star and the marks of a choice not yet checked (filled box and circle), which need the fill Lucide lacks; the Material icons left in older screens go when those are restyled. Shared widgets come from halkyon_ui (`SectionCard`, `AppLoadingIndicator` (every spinner is Material 3 Expressive's, in buttons `ButtonLoadingIndicator`, pulling a list down `AppRefreshIndicator`, never Flutter's older circular one), `confirmDestructiveAction`, `FoundById`, `TitleWithKicker`, `showUndoSnackBar`, `ScrollHidingFab`, `PaletteColorPicker`, `CountStepper`, `requiredDecoration` (every required field: while empty its outline stronger, in the primary colour, and "Required" below it; never an asterisk) and `FieldInfoButton`, `ReorderToggle`, `ReorderGrip`, `CollapsingRow`, `CountBadge`, `liftWhileDragged`, `LaunchScreen` and `BrandWordmark` ("Halkyon" over an app's word), `SliverCentered` and `EmptyListMessage` (what an empty list shows: icon, "No … yet", and which menus add some), and the sheets below), with texts of their own (`HalkyonUiLocalizations`); Learn's own are in `core/widget/` (`ConflictVersions`, the versions of a conflict each editor shows, with Keep, its save status beside it `SaveStatusLabel` in `core/editor/`; `ContentCountsLine`; `AppLaunchScreen`, what shows while the app opens: the kingfisher, "Halkyon" over "Learn", whose wordmark the first start shows too).
- **A studyset's options are the same wherever a menu of it opens** (`studysetOptions` and `doStudysetOption` in `studyset_actions.dart`, decided 2026-10-12): its card in the library, its own screen, a topic beside it. Import content runs where the studyset's blocs are, on its screen: from elsewhere it opens the screen, which asks what to import as it opens (`?import=content`).

174
apps/learn/halkyon_learn_flutter/lib/src/core/router/app_shell.dart
View file

@ -1,26 +1,17 @@
import 'package:flutter/services.dart';
import 'package:go_router/go_router.dart';
import 'package:halkyon_learn_flutter/l10n/app_localizations.dart';
import 'package:halkyon_ui/halkyon_ui.dart';
import 'package:lucide_icons_flutter/lucide_icons.dart';
import 'package:material_ui/material_ui.dart';
/// The frame around the four tabs: a navigation rail at the side from medium
/// windows on, a navigation bar floating above the bottom below that
/// ([FloatingNavigationBar]), the background of the screen in view around
/// it ([ScreenTint]). Every tab keeps its
/// own stack of screens, and the navigation stays visible on all of them;
/// screens that need the whole window are routes outside the shell.
///
/// From medium windows on, the window takes the colour of the screen in view
/// ([ScreenTint], decided 2026-10-10, as Vaia does): the rail sits on it,
/// and the screen is a rounded panel inset on it, with its own wash at the
/// top. Below that, each screen washes its top itself.
/// The frame around the four tabs, every Halkyon app's ([NavigationFrame]):
/// a navigation rail at the side from medium windows on, the kingfisher atop
/// it, and a navigation bar floating above the bottom below that. Every tab
/// keeps its own stack of screens, and the navigation stays visible on all
/// of them; screens that need the whole window are routes outside the shell.
///
/// Choosing the tab that is already selected goes back to its first screen,
/// as Material prescribes. Every choice ticks: the lightest haptic the
/// platform has (a clock tick on Android), where the device has a motor and
/// the system's touch feedback is on.
/// as Material prescribes.
class const AppShell({
/// The tabs' navigators, from `StatefulShellRoute`.
required final StatefulNavigationShell navigationShell,
@ -30,32 +21,17 @@ class const AppShell({
final int Function(BuildContext context)? profileBadge,
/// Whether the navigation bar below medium windows steps aside, for a
/// screen with a bar of its own at the bottom: Material 3 puts the
/// navigation bar on the top-level screens and the actions of those below
/// in a toolbar, never both at once (decided 2026-10-11, as Vaia does). The
/// rail of wider windows stays.
/// screen with a bar of its own at the bottom (decided 2026-10-11,
/// [NavigationFrame.hidesNavigationBar]).
final bool hidesNavigationBar = false,
super.key,
}) extends StatefulWidget {
@override
State<AppShell> createState() => _AppShellState();
}
class _AppShellState() extends State<AppShell> {
final _tint = ScreenTint();
@override
void dispose() {
_tint.dispose();
super.dispose();
}
}) extends StatelessWidget {
@override
Widget build(BuildContext context) {
final navigationShell = widget.navigationShell;
final destinations = _destinations(AppLocalizations.of(context));
final l10n = AppLocalizations.of(context);
final destinations = _destinations(l10n);
// The Profile tab says how many things are new behind it.
final unseen = widget.profileBadge?.call(context) ?? 0;
final unseen = profileBadge?.call(context) ?? 0;
Widget icon(_Destination destination, IconData data) =>
identical(destination, destinations.last)
? Badge.count(
@ -64,116 +40,26 @@ class _AppShellState() extends State<AppShell> {
child: Icon(data),
)
: Icon(data);
if (context.windowSize.isAtLeastMedium) {
return ScreenTintScope(
notifier: _tint,
child: TintFrame(
tint: _tint,
rail: NavigationRail(
backgroundColor: Colors.transparent,
selectedIndex: navigationShell.currentIndex,
labelType: NavigationRailLabelType.all,
onDestinationSelected: _select,
leading: _RailLogo(onTap: () => _select(0)),
destinations: [
for (final destination in destinations)
NavigationRailDestination(
icon: icon(destination, destination.icon),
selectedIcon: icon(destination, destination.selectedIcon),
label: Text(destination.label),
),
],
),
child: navigationShell,
),
);
}
final bar = FloatingNavigationBar(
bar: NavigationBar(
backgroundColor: Colors.transparent,
elevation: 0,
selectedIndex: navigationShell.currentIndex,
onDestinationSelected: _select,
destinations: [
for (final destination in destinations)
NavigationDestination(
icon: icon(destination, destination.icon),
selectedIcon: icon(destination, destination.selectedIcon),
label: destination.label,
),
],
return NavigationFrame(
appName: l10n.appTitle,
// The kingfisher has a white background, which the frame's rounded
// tile keeps reading on light and dark rails alike.
icon: const AssetImage('assets/icon/halkyon_icon.png'),
selectedIndex: navigationShell.currentIndex,
onSelected: (index) => navigationShell.goBranch(
index,
initialLocation: index == navigationShell.currentIndex,
),
);
final surface = Theme.of(context).colorScheme.surface;
return ScreenTintScope(
notifier: _tint,
// Around the bar, the background of the screen in view, changing as
// the frame's colour does.
child: ListenableBuilder(
listenable: _tint,
builder: (context, _) => TweenAnimationBuilder<Color?>(
tween: ColorTween(end: _tint.background ?? surface),
duration: const Duration(milliseconds: 250),
builder: (context, background, _) => Scaffold(
backgroundColor: background,
// The screens run on beneath the floating bar, showing around
// it, as iOS 26's tab bar floats over content; their lists end
// with room for it (the body's bottom padding says how much).
extendBody: !widget.hidesNavigationBar,
body: navigationShell,
// Without the bar, a strip as high as the system's own bar, in
// the screen's background, keeps every screen inside clear of
// it.
bottomNavigationBar: widget.hidesNavigationBar
? SizedBox(height: MediaQuery.paddingOf(context).bottom)
: bar,
hidesNavigationBar: hidesNavigationBar,
destinations: [
for (final destination in destinations)
(
label: destination.label,
icon: icon(destination, destination.icon),
selectedIcon: icon(destination, destination.selectedIcon),
),
),
),
);
}
void _select(int index) {
HapticFeedback.selectionClick();
widget.navigationShell.goBranch(
index,
initialLocation: index == widget.navigationShell.currentIndex,
);
}
}
/// The kingfisher atop the rail, leading Home ([onTap]) as a website's
/// logo does. The icon has a white background, so it sits in a rounded tile
/// that reads on light and dark rails alike.
class const _RailLogo({required final VoidCallback onTap})
extends StatelessWidget {
@override
Widget build(BuildContext context) {
final l10n = AppLocalizations.of(context);
return Padding(
padding: const EdgeInsets.symmetric(vertical: 12),
child: Tooltip(
message: l10n.shellTabHome,
child: Material(
type: MaterialType.transparency,
child: InkWell(
onTap: onTap,
borderRadius: BorderRadius.circular(9),
child: ClipRRect(
borderRadius: BorderRadius.circular(9),
child: Image.asset(
'assets/icon/halkyon_icon.png',
width: 40,
height: 40,
// The source is 1024 px square; a 40 dp logo needs no more
// than this in memory, even at three times the density.
cacheWidth: 120,
semanticLabel: l10n.appTitle,
),
),
),
),
),
],
child: navigationShell,
);
}
}

23
apps/learn/halkyon_learn_flutter/lib/src/core/router/tab_visibility.dart
View file

@ -2,27 +2,10 @@ import 'package:go_router/go_router.dart';
import 'package:halkyon_ui/halkyon_ui.dart';
import 'package:material_ui/material_ui.dart';
/// The container of the tabs' navigators for a `StatefulShellRoute`, as
/// go_router's indexed stack builds it: every tab stays alive, the hidden
/// ones offstage with their animations paused. Each also learns from
/// [TabVisibility] whether it shows.
/// The container of the tabs' navigators for a `StatefulShellRoute`:
/// halkyon_ui's [TabsStack], every tab alive and learning whether it shows.
Widget tabsContainer(
BuildContext context,
StatefulNavigationShell shell,
List<Widget> tabs,
) => IndexedStack(
index: shell.currentIndex,
children: [
for (final (index, tab) in tabs.indexed)
Offstage(
offstage: index != shell.currentIndex,
child: TickerMode(
enabled: index == shell.currentIndex,
child: TabVisibility(
visible: index == shell.currentIndex,
child: tab,
),
),
),
],
);
) => TabsStack(index: shell.currentIndex, children: tabs);