LogRegion

A scrolling log view that keeps the newest entry in view as entries arrive, with severity styling, filtering, and copy.

See also: MessageList for a conversation transcript.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

LogRegion(
  entries: const [
    LogEntry(id: 1, message: 'Starting deploy', source: 'deploy'),
    LogEntry(
      id: 2,
      message: 'Health check failed: 503 on /ready',
      severity: LogSeverity.error,
      source: 'probe',
    ),
  ],
  // Narrow what's shown without changing the entries:
  filter: const LogRegionFilterDescriptor(severities: {LogSeverity.error}),
)

Details

To stream output, keep the entries in your state, append each new LogEntry, and rebuild (with setState, for example); the region shows the new rows. If you also drop old entries from the front, give every entry a unique LogEntry.id so the cursor stays on its entry and LogRegionController.unseenCount stays accurate.

The region follows the tail by default, with the cursor on the newest entry. Scrolling up to read history pauses following, and LogRegionController.unseenCount counts the entries that arrive meanwhile. Scrolling back to the end, pressing End, or calling LogRegionController.scrollToBottom resumes it.

Up and Down move the cursor; PageUp, PageDown, and Home jump. Clicking a row moves the cursor to it. Ctrl+C copies the entry under the cursor (see copySelection and copyOptions). filter narrows the rows shown by text, source, or severity without changing entries.

Constructors

LogRegion()

Parameter	Type	Default	Description
entries:	List<LogEntry>	required	The log rows, oldest first. To add rows, append to the list (or pass a new one) and rebuild.
controller:	LogRegionController?	—	Reads and moves the cursor and controls tail following. If null, the region creates its own.
focusNode:	FocusNode?	—	Focus node used for keyboard navigation.
autofocus:	bool	false	Whether the region should request focus when mounted.
semanticLabel:	String	'Logs'	Semantic label (the accessibility name; not rendered) for the region.
showPrefix:	bool	true	Whether each row starts with a [timestamp SEVERITY source] prefix, leaving out the parts an entry doesn’t have.
maxLineLength:	int?	1000	Cuts each message to this many characters, with no ellipsis, on screen and when copied; null never cuts. The prefix doesn’t count.
filter:	LogRegionFilterDescriptor?	—	Narrows the rows shown by text, source, or severity; entries is left unchanged.
searchIndex:	LogRegionSearchIndex?	—	Optional prebuilt search index for large log collections. The region uses it only when it was built over the same list object passed as entries; otherwise it filters without it.
copySelection:	bool	true	Whether Ctrl+C (and the semantic copy action) copies the entry under the cursor.
copyOptions:	LogRegionCopyOptions	const LogRegionCopyOptions()	Whether copied text includes the row prefix, and the clipboard write policy.
onCopy:	void Function(LogRegionCopyResult result)?	—	Called after a copy attempt completes.

Source

LogRegion is defined in packages/fleury/lib/src/catalog/log_region.dart.

Category: Agent surfaces · All widgets

Live demo

logregion_example.dart

Restart Run Expand

Example · editable Revert Format

class _LogRegionExampleState extends State<_LogRegionExample>
    with SingleTickerProviderStateMixin {
  static const _deploy = <(LogSeverity, String, String)>[
    (LogSeverity.info, 'deploy', 'Starting deploy of api@4.2.0'),
    (LogSeverity.info, 'build', 'Compiling 214 files'),
    (LogSeverity.success, 'build', 'Built in 3.8s'),
    (LogSeverity.info, 'deploy', 'Uploading image (48 MB)'),
    (LogSeverity.warning, 'probe', 'Health check slow: 1.9s'),
    (LogSeverity.info, 'deploy', 'Routing 10% of traffic'),
    (LogSeverity.error, 'probe', 'Health check failed: 503 on /ready'),
    (LogSeverity.info, 'deploy', 'Rolling back to api@4.1.3'),
    (LogSeverity.success, 'deploy', 'Rollback complete'),
  ];

  final List<LogEntry> _entries = [];
  int _next = 0;
  Ticker? _ticker;
  Duration _last = Duration.zero;

  @override
  void initState() {
    super.initState();
    for (var i = 0; i < 4; i++) {
      _append();
    }
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // Frames only tick inside a running app.
    if (_ticker == null && TuiBinding.maybeOf(context) != null) {
      _ticker = createTicker(_onTick)..start();
    }
  }

  void _onTick(Duration elapsed) {
    if (elapsed - _last < const Duration(milliseconds: 700)) return;
    _last = elapsed;
    setState(_append);
  }

  void _append() {
    final (severity, source, message) = _deploy[_next % _deploy.length];
    _entries.add(
      LogEntry(id: _next, severity: severity, source: source, message: message),
    );
    _next++;
    if (_entries.length > 200) _entries.removeAt(0);
  }

  @override
  void dispose() {
    _ticker?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) =>
      LogRegion(entries: List.of(_entries), autofocus: true);
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand