fai/chain-studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(studio): Welcome page Phase B — embedded doc reader (v0.38.0)

Browse source 
Second slice of the Welcome surface. Operator-facing
documentation now lives inside Studio as bundled assets and
renders inline via a modal sheet — no browser, no external
link, air-gap-tauglich.

- Four operator-readable explainers under `assets/docs/`,
  each with an EN + DE pair:
    architecture[_de].md  — Hub / Module / Flow + how they fit
    security[_de].md       — sandbox model, declared perms,
                              operator ceiling
    audit[_de].md          — hash-chained log, WORM-1 mechanics,
                              `fai admin verify-events`
    flows[_de].md          — flow YAML, templating reference,
                              extract→summarize example
  These are short (≈ 300-500 words each), operator-shaped
  prose. Not copies of the architecture docs in
  fai_platform/docs/architecture/ — those are
  contributor-dense.

- pubspec.yaml declares `assets/docs/` so the markdown ships
  inside the Studio binary. Air-gap deployments read them
  with no network access.

- New `_DocReaderSheet` modal: 85 %-of-viewport bottom sheet,
  drag handle + title bar with the doc icon and close button,
  scrollable Markdown body styled to match Studio chrome.
  Loads `assets/docs/<slug>_<locale>.md` first, falls back to
  the EN file. Locale comes from
  `Localizations.localeOf(context)`.

- `_DocsRow` on the Welcome page sits below the trust-posture
  deck. Two-column grid on ≥ 640 dp, single column below.
  Each card is icon + title + one-line blurb + chevron;
  click opens the reader sheet for that slug.

- 12 new ARB keys for the docs section (header, blurb, four
  card titles + blurbs, close button, error message).
- 4 new icons reused: `account_tree_outlined` (architecture),
  `shield_outlined` (security), `verified_outlined` (audit),
  `alt_route_outlined` (flows).

Implements Phase B of `docs/landing-page-design.md`. Phase C
(live getting-started checklist with persistent state) is the
last remaining slice.

Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>
This commit is contained in:
flemming-it 2026-05-09 00:24:31 +02:00
parent 3a7d0e74ad
commit 3b07d340d5
16 changed files with 1051 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

299
lib/pages/welcome.dart
View file

@ -9,8 +9,12 @@
// getting-started checklist.
import 'package:flutter/material.dart';
import 'package:flutter/services.dart' show rootBundle;
import 'package:flutter_markdown/flutter_markdown.dart';
import '../data/system_actions.dart';
import '../l10n/app_localizations.dart';
import '../theme/theme.dart';
import '../theme/tokens.dart';
class WelcomePage extends StatelessWidget {
@ -48,6 +52,10 @@ class WelcomePage extends StatelessWidget {
_SectionLabel(textKey: _SectionLabelKey.trust),
SizedBox(height: FaiSpace.md),
_TrustPosture(),
SizedBox(height: FaiSpace.xxl),
_SectionLabel(textKey: _SectionLabelKey.docs),
SizedBox(height: FaiSpace.md),
_DocsRow(),
],
),
),
@ -128,7 +136,7 @@ class _Hero extends StatelessWidget {
}
}
enum _SectionLabelKey { pillars, trust }
enum _SectionLabelKey { pillars, trust, docs }
class _SectionLabel extends StatelessWidget {
final _SectionLabelKey textKey;
@ -141,6 +149,7 @@ class _SectionLabel extends StatelessWidget {
final text = switch (textKey) {
_SectionLabelKey.pillars => l.welcomePillarsHeader,
_SectionLabelKey.trust => l.welcomeTrustHeader,
_SectionLabelKey.docs => l.welcomeDocsHeader,
};
return Text(
text,
@ -349,3 +358,291 @@ class _TrustRow extends StatelessWidget {
);
}
}
/// Doc-card entries — each links to a bundled markdown file
/// under `assets/docs/`. The slug is the filename stem; the
/// loader picks `<slug>.md` or `<slug>_de.md` per locale.
class _DocEntry {
final String slug;
final IconData icon;
final String Function(AppLocalizations) title;
final String Function(AppLocalizations) blurb;
const _DocEntry({
required this.slug,
required this.icon,
required this.title,
required this.blurb,
});
}
final List<_DocEntry> _kDocs = <_DocEntry>[
_DocEntry(
slug: 'architecture',
icon: Icons.account_tree_outlined,
title: (l) => l.welcomeDocArchitectureTitle,
blurb: (l) => l.welcomeDocArchitectureBlurb,
),
_DocEntry(
slug: 'security',
icon: Icons.shield_outlined,
title: (l) => l.welcomeDocSecurityTitle,
blurb: (l) => l.welcomeDocSecurityBlurb,
),
_DocEntry(
slug: 'audit',
icon: Icons.verified_outlined,
title: (l) => l.welcomeDocAuditTitle,
blurb: (l) => l.welcomeDocAuditBlurb,
),
_DocEntry(
slug: 'flows',
icon: Icons.alt_route_outlined,
title: (l) => l.welcomeDocFlowsTitle,
blurb: (l) => l.welcomeDocFlowsBlurb,
),
];
/// Two-by-two doc grid on wide windows, single column on
/// narrow. Each card opens `_DocReaderSheet` for its slug.
class _DocsRow extends StatelessWidget {
const _DocsRow();
@override
Widget build(BuildContext context) {
final l = AppLocalizations.of(context)!;
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
l.welcomeDocsBody,
style: Theme.of(context).textTheme.bodySmall?.copyWith(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
const SizedBox(height: FaiSpace.md),
LayoutBuilder(
builder: (context, constraints) {
final twoCols = constraints.maxWidth >= 640;
final cardWidth =
twoCols ? (constraints.maxWidth - FaiSpace.md) / 2 : double.infinity;
return Wrap(
spacing: FaiSpace.md,
runSpacing: FaiSpace.md,
children: [
for (final d in _kDocs)
SizedBox(
width: cardWidth,
child: _DocCard(entry: d),
),
],
);
},
),
],
);
}
}
class _DocCard extends StatelessWidget {
final _DocEntry entry;
const _DocCard({required this.entry});
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final l = AppLocalizations.of(context)!;
return Material(
color: theme.colorScheme.surfaceContainer,
borderRadius: BorderRadius.circular(FaiRadius.md),
child: InkWell(
onTap: () => _DocReaderSheet.show(context, entry),
borderRadius: BorderRadius.circular(FaiRadius.md),
child: Container(
padding: const EdgeInsets.all(FaiSpace.lg),
decoration: BoxDecoration(
borderRadius: BorderRadius.circular(FaiRadius.md),
border: Border.all(color: theme.colorScheme.outlineVariant),
),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Icon(entry.icon, size: 22, color: theme.colorScheme.primary),
const SizedBox(width: FaiSpace.lg),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
entry.title(l),
style: theme.textTheme.titleSmall?.copyWith(
fontWeight: FontWeight.w600,
),
),
const SizedBox(height: 4),
Text(
entry.blurb(l),
style: theme.textTheme.bodySmall?.copyWith(
color: theme.colorScheme.onSurfaceVariant,
height: 1.4,
),
),
],
),
),
Icon(
Icons.chevron_right,
size: 18,
color: theme.colorScheme.onSurfaceVariant,
),
],
),
),
),
);
}
}
/// Modal bottom-sheet that loads the markdown for a doc entry
/// from `assets/docs/<slug>[_de].md` and renders it inline via
/// flutter_markdown. No browser, no network — KRITIS-friendly.
class _DocReaderSheet extends StatefulWidget {
final _DocEntry entry;
const _DocReaderSheet({required this.entry});
static Future<void> show(BuildContext context, _DocEntry entry) {
return showModalBottomSheet<void>(
context: context,
isScrollControlled: true,
backgroundColor: Theme.of(context).colorScheme.surfaceContainer,
shape: const RoundedRectangleBorder(
borderRadius: BorderRadius.vertical(top: Radius.circular(FaiRadius.md)),
),
builder: (_) => _DocReaderSheet(entry: entry),
);
}
@override
State<_DocReaderSheet> createState() => _DocReaderSheetState();
}
class _DocReaderSheetState extends State<_DocReaderSheet> {
late final Future<String> _content;
@override
void initState() {
super.initState();
_content = _load();
}
Future<String> _load() async {
final locale = Localizations.localeOf(context).languageCode;
final localised = 'assets/docs/${widget.entry.slug}_$locale.md';
final fallback = 'assets/docs/${widget.entry.slug}.md';
try {
return await rootBundle.loadString(localised);
} catch (_) {
return rootBundle.loadString(fallback);
}
}
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final l = AppLocalizations.of(context)!;
final maxHeight = MediaQuery.of(context).size.height * 0.85;
return ConstrainedBox(
constraints: BoxConstraints(maxHeight: maxHeight),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Padding(
padding: const EdgeInsets.symmetric(vertical: FaiSpace.sm),
child: Container(
width: 40,
height: 4,
decoration: BoxDecoration(
color: theme.colorScheme.outlineVariant,
borderRadius: BorderRadius.circular(2),
),
),
),
Padding(
padding: const EdgeInsets.fromLTRB(
FaiSpace.xxl,
FaiSpace.sm,
FaiSpace.lg,
FaiSpace.sm,
),
child: Row(
children: [
Icon(widget.entry.icon, size: 20, color: theme.colorScheme.primary),
const SizedBox(width: FaiSpace.sm),
Expanded(
child: Text(
widget.entry.title(l),
style: theme.textTheme.titleMedium?.copyWith(
fontWeight: FontWeight.w600,
),
),
),
IconButton(
icon: const Icon(Icons.close, size: 18),
visualDensity: VisualDensity.compact,
tooltip: l.welcomeDocClose,
onPressed: () => Navigator.pop(context),
),
],
),
),
const Divider(height: 1),
Flexible(
child: FutureBuilder<String>(
future: _content,
builder: (context, snap) {
if (snap.connectionState == ConnectionState.waiting) {
return const Padding(
padding: EdgeInsets.all(FaiSpace.xxl),
child: Center(child: CircularProgressIndicator()),
);
}
if (snap.hasError) {
return Padding(
padding: const EdgeInsets.all(FaiSpace.xxl),
child: Text(
l.welcomeDocFailedToLoad(snap.error.toString()),
style: theme.textTheme.bodyMedium?.copyWith(
color: theme.colorScheme.error,
),
),
);
}
return Markdown(
data: snap.data ?? '',
padding: const EdgeInsets.all(FaiSpace.xxl),
selectable: true,
onTapLink: (text, href, title) async {
if (href != null && href.isNotEmpty) {
await SystemActions.openInOs(href);
}
},
styleSheet: MarkdownStyleSheet.fromTheme(theme).copyWith(
p: theme.textTheme.bodyMedium?.copyWith(height: 1.5),
code: FaiTheme.mono(
size: 12,
color: theme.colorScheme.onSurface,
),
codeblockDecoration: BoxDecoration(
color: theme.colorScheme.surfaceContainerHigh,
borderRadius: BorderRadius.circular(FaiRadius.sm),
),
),
);
},
),
),
],
),
);
}
}