feat(garage_ui): an item view in four layouts, a breadcrumb and a file drop target

ItemView draws a set of named things as a list, a two line list, a table
with sortable headers or a grid, and ItemViewModeSwitch lets whoever is
looking pick. Columns drop from the end on a narrow pane before the name
gets squeezed.

Breadcrumb is ghost buttons with chevrons. FileDropTarget takes files
dragged in from outside and shows the focus ring while one is held over
it; it sits on desktop_drop, which is a new dependency.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KHotisA4hV2xmuZsHTksFX
This commit is contained in:
ImBenji
2026-10-11 06:09:03 +01:00
co-authored by Claude Opus 5.5
parent cc2fe99d02
commit 444933b004
6 changed files with 861 additions and 0 deletions
+590
View File
@@ -0,0 +1,590 @@
import "package:flutter/gestures.dart" show kSecondaryMouseButton;
import "package:flutter/widgets.dart";
import "package:flutter_lucide/flutter_lucide.dart";
import "button.dart";
import "surface.dart" show Divider;
import "theme/garage_theme.dart";
/// How an [ItemView] lays its entries out.
///
/// Four, because theres no one right answer for a list of things with names:
/// its a matter of how many there are, how much the picture of one tells you,
/// and what the person looking is trying to find. So the mode is a value the
/// caller holds, and [ItemViewModeSwitch] is there to let whoevers looking
/// pick it.
enum ItemViewMode {
/// One line each: picture, name, then the cells down the right.
list,
/// Name with the cells as a muted second line under it. The one that still
/// reads on a phone.
twoLine,
/// [list] with a header row, and the headers sort.
table,
/// Tiles. For when the picture is the point.
grid,
}
/// A column of cells in an [ItemView], after the name.
class ItemColumn {
const ItemColumn({
required this.id,
required this.label,
this.ems = 7,
this.sortable = true,
});
/// What [ItemEntry.cells] is keyed on, and what comes back from onSort.
final String id;
final String label;
/// Width, in multiples of the density's font size rather than pixels - so a
/// denser theme gets narrower columns along with its smaller text, instead
/// of the same columns with more air in them.
final double ems;
final bool sortable;
}
/// One thing in an [ItemView].
class ItemEntry {
const ItemEntry({
required this.id,
required this.title,
required this.leading,
this.cells = const {},
this.trailing,
this.onOpen,
this.onContext,
});
final String id;
final String title;
/// The picture: an icon, a thumbnail. Built at whatever size the mode wants
/// it, which is an icon's worth in a row and most of a tile in the grid - so
/// its a builder and not a widget. Fill the square you are given.
final Widget Function(BuildContext context, double extent) leading;
/// column id -> what to show under it. A missing one is an empty cell.
final Map<String, String> cells;
/// Far right of a row, top corner of a tile. An overflow button, usually.
final Widget? trailing;
final VoidCallback? onOpen;
/// Right click, or a long press where theres no right button. Handed the
/// global position so a context menu can open where the pointer is.
final ValueChanged<Offset>? onContext;
}
/// The id [ItemView] reports when the NAME header is pressed. Its not one of
/// the caller's columns, so it needs a name of its own.
const String kItemTitleColumn = "title";
/// A set of named things - files, mostly - in one of four layouts.
///
/// It doesnt sort, page or load. It draws what its given in the order its
/// given, and says when a header was pressed; what that means is the callers
/// business, since only the caller knows whether "size" sorts as a number.
///
/// Not a scroller either. Height comes from the entries and a pane does the
/// scrolling, same as [SettingsList] and a run of sections.
class ItemView extends StatelessWidget {
const ItemView({
super.key,
required this.mode,
required this.entries,
this.columns = const [],
this.titleLabel = "Name",
this.sortColumn,
this.sortAscending = true,
this.onSort,
});
final ItemViewMode mode;
final List<ItemEntry> entries;
final List<ItemColumn> columns;
/// Header over the names, in [ItemViewMode.table].
final String titleLabel;
final String? sortColumn;
final bool sortAscending;
final ValueChanged<String>? onSort;
/// Columns that fit beside a name thats still worth reading.
///
/// They go from the END. The last column is the least important one by
/// convention - a date after a size after a kind - and a row that kept all
/// its columns and squeezed the name down to "inv…" has thrown away the one
/// thing every row is for.
List<ItemColumn> _fitting(double width, double em) {
final nameFloor = em * 14;
var kept = [...columns];
double used() => kept.fold(0.0, (n, c) => n + c.ems * em);
while (kept.isNotEmpty && width - used() < nameFloor) {
kept.removeLast();
}
return kept;
}
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
if (mode == ItemViewMode.grid) {
return _ItemGrid(entries: entries, columns: columns);
}
return LayoutBuilder(
builder: (context, box) {
final shown = mode == ItemViewMode.twoLine
? const <ItemColumn>[]
: _fitting(box.maxWidth, density.fontSize);
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
mainAxisSize: MainAxisSize.min,
children: [
if (mode == ItemViewMode.table) ...[
_HeaderRow(
titleLabel: titleLabel,
columns: shown,
sortColumn: sortColumn,
sortAscending: sortAscending,
onSort: onSort,
hasTrailing: entries.any((e) => e.trailing != null),
),
Divider(color: theme.colorScheme.divider),
],
for (var i = 0; i < entries.length; i++) ...[
// between, not around - see SettingsList, its the same list
if (i > 0) Divider(color: theme.colorScheme.divider),
_ItemRow(
key: ValueKey("item-${entries[i].id}"),
entry: entries[i],
columns: shown,
// every column, whatever fitted: the second line is where the
// ones that didnt fit go
subtitleColumns: mode == ItemViewMode.twoLine ? columns : const [],
),
],
],
);
},
);
}
}
String _joined(ItemEntry entry, List<ItemColumn> columns) => [
for (final c in columns)
if ((entry.cells[c.id] ?? "").isNotEmpty) entry.cells[c.id]!,
].join(" · ");
/// Hover fill, tap to open, right click for the menu. Shared by a row and a
/// tile so the two cant drift into behaving differently.
class _Pressable extends StatefulWidget {
const _Pressable({required this.entry, required this.builder});
final ItemEntry entry;
final Widget Function(BuildContext context, bool hovered) builder;
@override
State<_Pressable> createState() => _PressableState();
}
class _PressableState extends State<_Pressable> {
bool _hover = false;
@override
Widget build(BuildContext context) {
final entry = widget.entry;
final open = entry.onOpen;
final menu = entry.onContext;
return MouseRegion(
cursor: open == null ? MouseCursor.defer : SystemMouseCursors.click,
onEnter: (_) => setState(() => _hover = true),
onExit: (_) => setState(() => _hover = false),
child: Listener(
// a Listener and not onSecondaryTap: the trailing button sits inside
// this, and a gesture detector out here would fight it for the tap
onPointerDown: menu == null
? null
: (e) {
if (e.buttons == kSecondaryMouseButton) menu(e.position);
},
child: GestureDetector(
behavior: HitTestBehavior.opaque,
onTap: open,
onLongPressStart: menu == null ? null : (d) => menu(d.globalPosition),
child: Semantics(
button: open != null,
label: entry.title,
child: widget.builder(context, _hover && open != null),
),
),
),
);
}
}
class _ItemRow extends StatelessWidget {
const _ItemRow({
super.key,
required this.entry,
required this.columns,
required this.subtitleColumns,
});
final ItemEntry entry;
final List<ItemColumn> columns;
final List<ItemColumn> subtitleColumns;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final twoLine = subtitleColumns.isNotEmpty;
final subtitle = twoLine ? _joined(entry, subtitleColumns) : "";
// an icon's worth on one line. two lines have the height for a picture
// you can actualy make out, so it gets the whole label stack
final extent = twoLine ? density.labelColumnHeight : density.iconSize;
return _Pressable(
entry: entry,
builder: (context, hovered) => ColoredBox(
color: hovered ? scheme.rowHovered : const Color(0x00000000),
child: Padding(
padding: EdgeInsets.symmetric(
horizontal: density.listRowIndent,
vertical: twoLine ? density.gapSm : density.explorerRowPaddingY,
),
child: Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
SizedBox.square(
dimension: extent,
child: entry.leading(context, extent),
),
SizedBox(width: density.gapSm),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
entry.title,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(color: scheme.foreground),
),
if (subtitle.isNotEmpty) ...[
SizedBox(height: density.gapXxs),
Text(
subtitle,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontSize: density.textXxs,
color: scheme.mutedForeground,
),
),
],
],
),
),
for (final c in columns)
SizedBox(
width: c.ems * density.fontSize,
child: Text(
entry.cells[c.id] ?? "",
maxLines: 1,
overflow: TextOverflow.ellipsis,
textAlign: TextAlign.end,
style: TextStyle(color: scheme.mutedForeground),
),
),
if (entry.trailing != null) ...[
SizedBox(width: density.gapSm),
entry.trailing!,
],
],
),
),
),
);
}
}
class _HeaderRow extends StatelessWidget {
const _HeaderRow({
required this.titleLabel,
required this.columns,
required this.sortColumn,
required this.sortAscending,
required this.onSort,
required this.hasTrailing,
});
final String titleLabel;
final List<ItemColumn> columns;
final String? sortColumn;
final bool sortAscending;
final ValueChanged<String>? onSort;
final bool hasTrailing;
Widget _label(
BuildContext context,
String id,
String text, {
required bool end,
required bool sortable,
}) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final sorted = sortColumn == id;
final press = sortable && onSort != null ? () => onSort!(id) : null;
final style = TextStyle(
fontSize: density.textXxs,
color: sorted ? scheme.foreground : scheme.mutedForeground,
);
return MouseRegion(
cursor: press == null ? MouseCursor.defer : SystemMouseCursors.click,
child: GestureDetector(
behavior: HitTestBehavior.opaque,
onTap: press,
child: Semantics(
button: press != null,
label: sorted
? "$text, sorted ${sortAscending ? "ascending" : "descending"}"
: text,
excludeSemantics: true,
child: Row(
mainAxisAlignment: end ? MainAxisAlignment.end : MainAxisAlignment.start,
children: [
Flexible(
child: Text(text, maxLines: 1, overflow: TextOverflow.ellipsis, style: style),
),
if (sorted) ...[
SizedBox(width: density.gapXxs),
Icon(
sortAscending ? LucideIcons.arrow_up : LucideIcons.arrow_down,
size: density.textXxs,
color: scheme.foreground,
),
],
],
),
),
),
);
}
@override
Widget build(BuildContext context) {
final density = GarageTheme.of(context).density;
return Padding(
padding: EdgeInsets.symmetric(
horizontal: density.listRowIndent,
vertical: density.gapXs,
),
child: Row(
children: [
// over the names, not over the pictures: the header starts where
// the text of a row starts
SizedBox(width: density.iconSize + density.gapSm),
Expanded(
child: _label(context, kItemTitleColumn, titleLabel, end: false, sortable: true),
),
for (final c in columns)
SizedBox(
width: c.ems * density.fontSize,
child: _label(context, c.id, c.label, end: true, sortable: c.sortable),
),
// holds the place of the rows' trailing button, or every column
// sits one button to the right of its header
if (hasTrailing) SizedBox(width: density.gapSm + density.controlHeight),
],
),
);
}
}
class _ItemGrid extends StatelessWidget {
const _ItemGrid({required this.entries, required this.columns});
final List<ItemEntry> entries;
final List<ItemColumn> columns;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final gap = density.gapMd;
return LayoutBuilder(
builder: (context, box) {
// as many as fit at about this wide, then stretched to share the row
// out evenly so theres no ragged strip down the right
final want = density.fontSize * 12;
final across = ((box.maxWidth + gap) / (want + gap)).floor().clamp(1, 12);
final tile = (box.maxWidth - gap * (across - 1)) / across;
return Wrap(
spacing: gap,
runSpacing: gap,
children: [
for (final entry in entries)
SizedBox(
key: ValueKey("item-${entry.id}"),
width: tile,
child: _Pressable(
entry: entry,
builder: (context, hovered) => DecoratedBox(
decoration: BoxDecoration(
color: hovered ? scheme.rowHovered : null,
borderRadius: BorderRadius.circular(theme.radiusSm),
),
child: Padding(
padding: EdgeInsets.all(density.gapXs),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
mainAxisSize: MainAxisSize.min,
children: [
AspectRatio(
aspectRatio: 4 / 3,
child: DecoratedBox(
decoration: BoxDecoration(
color: scheme.surfaceSunken,
borderRadius: BorderRadius.circular(theme.radiusXs),
border: Border.all(
color: scheme.border,
width: density.controlBorderWidth,
),
),
child: ClipRRect(
borderRadius: BorderRadius.circular(theme.radiusXs),
child: LayoutBuilder(
builder: (context, inner) => Center(
child: SizedBox.square(
dimension: inner.maxHeight,
child: entry.leading(context, inner.maxHeight),
),
),
),
),
),
),
SizedBox(height: density.gapXs),
Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
entry.title,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(color: scheme.foreground),
),
SizedBox(height: density.gapXxs),
Text(
_joined(entry, columns),
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontSize: density.textXxs,
color: scheme.mutedForeground,
),
),
],
),
),
if (entry.trailing != null) entry.trailing!,
],
),
],
),
),
),
),
),
],
);
},
);
}
}
/// The four layouts as a row of buttons, for whoever is looking to pick one.
///
/// The one thats on is primary and the rest secondary, the way a tool thats
/// armed is drawn everywhere else.
class ItemViewModeSwitch extends StatelessWidget {
const ItemViewModeSwitch({
super.key,
required this.mode,
required this.onChanged,
this.modes = ItemViewMode.values,
});
final ItemViewMode mode;
final ValueChanged<ItemViewMode> onChanged;
/// Leave some out where they make no sense - a grid of things with no
/// picture, say.
final List<ItemViewMode> modes;
static IconData _icon(ItemViewMode m) => switch (m) {
ItemViewMode.list => LucideIcons.list,
ItemViewMode.twoLine => LucideIcons.rows_2,
ItemViewMode.table => LucideIcons.table,
ItemViewMode.grid => LucideIcons.layout_grid,
};
static String _name(ItemViewMode m) => switch (m) {
ItemViewMode.list => "List",
ItemViewMode.twoLine => "Detailed list",
ItemViewMode.table => "Table",
ItemViewMode.grid => "Grid",
};
@override
Widget build(BuildContext context) {
return ButtonGroup.horizontal(
children: [
for (final m in modes)
if (m == mode)
IconButton.primary(
icon: Icon(_icon(m)),
semanticLabel: "${_name(m)} view, selected",
onPressed: () => onChanged(m),
)
else
IconButton.secondary(
icon: Icon(_icon(m)),
semanticLabel: "${_name(m)} view",
onPressed: () => onChanged(m),
),
],
);
}
}