feat(catalogue): widgetbook v3 component catalogue + pages CI

Author: ethicnology

makefile

@@ -1,4 +1,4 @@
-.PHONY: all setup clean deps deps-update bootstrap analyze build-runner translations hooks ios-pod-update drift-migrations devcontainer container-tools container-app android release debug beta verify test unit-test integration-test fvm-check
+.PHONY: all setup clean deps deps-update bootstrap analyze build-runner translations hooks ios-pod-update drift-migrations devcontainer container-tools container-app android release debug beta verify test unit-test integration-test catalogue fvm-check
 
 fvm-check:
 	@echo "🔍 Checking FVM"
@@ -203,3 +203,12 @@ integration-test:
 	@echo "🧪 integration tests"
 	@fvm dart run tool/gen_all_test.dart
 	@fvm flutter test integration_test/all_test.dart --reporter=expanded
+
+# Build & render the bull_ui design-system catalogue (Widgetbook) locally in the
+# browser. Dev-only tooling — never shipped in the app. Regenerates the
+# @UseCase directories, then runs the catalogue app on Chrome (hot-reload).
+catalogue:
+	@echo "📚 Building & rendering the bull_ui catalogue in the browser"
+	@cd packages/bull_ui_catalogue && \
+		fvm dart run build_runner build --delete-conflicting-outputs && \
+		fvm flutter run -d chrome

packages/bull_ui_catalogue/.gitignore

@@ -0,0 +1,50 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# The root .gitignore ignores all *.g.dart, but the Widgetbook directories
+# file is generated codegen we deliberately commit-to-tree so the catalogue
+# runs locally without a build_runner pass. Negate the parent rule for it.
+!lib/main.directories.g.dart
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

packages/bull_ui_catalogue/.metadata

@@ -0,0 +1,30 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "924134a44c189315be2148659913dda1671cbe99"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: 924134a44c189315be2148659913dda1671cbe99
+      base_revision: 924134a44c189315be2148659913dda1671cbe99
+    - platform: web
+      create_revision: 924134a44c189315be2148659913dda1671cbe99
+      base_revision: 924134a44c189315be2148659913dda1671cbe99
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

packages/bull_ui_catalogue/README.md

@@ -0,0 +1,47 @@
+# bull_ui_catalogue
+
+Dev-only [Widgetbook](https://pub.dev/packages/widgetbook)-powered catalogue for
+the `bull_ui` design system.
+
+This package is **not** part of the production app. The app must never depend on
+it, so it is never compiled into the APK and has zero reproducible-build impact
+(it lives alongside the app like melos tooling). It exists purely to browse and
+review every `Bull*` component in isolation, in light and dark themes at
+different text scales.
+
+## Why use-cases live here
+
+`bull_ui` stays codegen-free and Widgetbook-free. All `@widgetbook.UseCase`
+functions live in this package (`lib/use_cases/use_cases.dart`), so the design
+system carries no Widgetbook annotations or generated files.
+
+The `BullTheme` colours are normally injected by the app from its `AppColors`.
+This package must not import the app, so `lib/catalogue_theme.dart` holds small
+**catalogue-local** sample light/dark palettes mirroring the app — literals are
+acceptable here in dev-only code, keeping `bull_ui` itself literal-free.
+
+## Run locally
+
+```bash
+fvm flutter pub get                       # from repo root (workspace resolve)
+cd packages/bull_ui_catalogue
+fvm dart run build_runner build           # regenerate main.directories.g.dart
+fvm flutter run -d chrome                 # browse the catalogue
+```
+
+`lib/main.directories.g.dart` is committed to the tree (the root `.gitignore`
+ignores `*.g.dart`; this package's `.gitignore` negates that for the directories
+file) so the catalogue runs without a build_runner pass.
+
+## Publishing (deferred — local-only for now)
+
+There is **no CI/Pages publishing in this PR** — browse the catalogue locally
+with `make catalogue` (or the commands above).
+
+Intended hosting for a follow-up: this repo's GitHub Pages serves `main:/docs`
+(custom domain `wallet.bullbitcoin.com`), and a repo has only one Pages site, so
+the catalogue would be published as a **subfolder** — built for web with
+`--base-href /catalogue/` and dropped into `main:/docs/catalogue/` (preserving
+the rest of `/docs`), served at `https://wallet.bullbitcoin.com/catalogue/`. That
+requires CI to commit to `main`, so it's left for a dedicated change once the
+catalogue renders cleanly (currently on widgetbook v3, pending a v4 migration).

packages/bull_ui_catalogue/analysis_options.yaml

@@ -0,0 +1,17 @@
+include: package:flutter_lints/flutter.yaml
+
+# This is a dev-only catalogue app, not the design-system package. We relax the
+# documentation / const-perfection lints that bull_ui itself is held to — the
+# use-cases are illustrative sample code, not production API surface.
+analyzer:
+  errors:
+    # Generated *.directories.g.dart is checked into the tree; never lint it.
+    todo: ignore
+  exclude:
+    - "**/*.g.dart"
+
+linter:
+  rules:
+    public_member_api_docs: false
+    prefer_const_constructors: false
+    prefer_const_literals_to_create_immutables: false

packages/bull_ui_catalogue/lib/catalogue_theme.dart

@@ -0,0 +1,85 @@
+import 'package:bull_ui/bull_ui.dart';
+import 'package:flutter/material.dart';
+
+/// Catalogue-local sample palettes for the theme addon.
+///
+/// `bull_ui` is intentionally brightness-agnostic and literal-free: in the real
+/// app the [BullTheme] values are injected from `AppColors` (which lives in the
+/// app and which this package must NOT import). To render the components with
+/// the right fidelity in the catalogue we keep a small *representative* copy of
+/// the app palette here. Literals are acceptable in this dev-only catalogue —
+/// they keep `bull_ui` itself free of any colour values.
+///
+/// These mirror `lib/core/themes/colors.dart` closely enough for visual review;
+/// they are not the single source of truth and may drift slightly.
+class CatalogueColors {
+  const CatalogueColors._();
+
+  static const BullTheme light = BullTheme(
+    red: Color(0xFFC50909),
+    onRed: Color(0xFFFFFFFF),
+    surface: Color(0xFFFFFFFF),
+    card: Color(0xFFFFFFFF),
+    text: Color(0xFF15171C),
+    muted: Color(0xFF70747D),
+    info: Color(0xFF0063F7),
+    success: Color(0xFF34C759),
+    warning: Color(0xFFFB9300),
+    btc: Color(0xFFFF9500),
+    outlineVariant: Color(0xFFE8E8E8),
+    shimmerBase: Color(0xFFE0E0E0),
+    shimmerHighlight: Color(0xFFF5F5F5),
+    secondary: Color(0xFF15171C),
+    onSecondary: Color(0xFFFFFFFF),
+    secondaryFixedDim: Color(0xFFC9CACD),
+    border: Color(0xFFC9CACD),
+    onSurface: Color(0xFF15171C),
+    onSurfaceVariant: Color(0xFF70747D),
+    scrim: Color(0x26000000),
+  );
+
+  static const BullTheme dark = BullTheme(
+    red: Color(0xFFC50909),
+    onRed: Color(0xFFFFFFFF),
+    surface: Color(0xFF1C1C1E),
+    card: Color(0xFF2C2C2E),
+    text: Color(0xFFFFFFFF),
+    muted: Color(0xFF8E8E93),
+    info: Color(0xFF0A84FF),
+    success: Color(0xFF32D74B),
+    warning: Color(0xFFFF9F0A),
+    btc: Color(0xFFFF9F0A),
+    outlineVariant: Color(0xFF3C3C3E),
+    shimmerBase: Color(0xFF3C3C3E),
+    shimmerHighlight: Color(0xFF48484A),
+    secondary: Color(0xFFFFFFFF),
+    onSecondary: Color(0xFF15171C),
+    secondaryFixedDim: Color(0xFF58585A),
+    border: Color(0xFF58585A),
+    onSurface: Color(0xFFFFFFFF),
+    onSurfaceVariant: Color(0xFF8E8E93),
+    scrim: Color(0x26000000),
+  );
+}
+
+/// Builds a Material [ThemeData] carrying the [BullTheme] extension, matching
+/// how the app wires `bull_ui` (extension on `ThemeData.extensions`). Components
+/// read their colours via `context.bull`, so the extension is what matters.
+ThemeData catalogueThemeData(Brightness brightness) {
+  final bull = brightness == Brightness.dark
+      ? CatalogueColors.dark
+      : CatalogueColors.light;
+  return ThemeData(
+    useMaterial3: true,
+    brightness: brightness,
+    fontFamily: 'Golos Text',
+    extensions: [bull],
+    colorScheme: ColorScheme.fromSeed(
+      seedColor: bull.red,
+      brightness: brightness,
+      primary: bull.red,
+    ),
+    scaffoldBackgroundColor: bull.surface,
+    canvasColor: bull.card,
+  );
+}

packages/bull_ui_catalogue/lib/main.dart

@@ -0,0 +1,54 @@
+import 'package:bull_ui_catalogue/catalogue_theme.dart';
+import 'package:flutter/material.dart';
+import 'package:widgetbook/widgetbook.dart';
+import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;
+
+// Generated by build_runner from every `@widgetbook.UseCase` in lib/.
+// Checked into the tree (CI does not regenerate on the deploy path's behalf
+// only — it does run build_runner — but the file is committed for local runs).
+import 'main.directories.g.dart';
+
+void main() {
+  runApp(const BullUiCatalogue());
+}
+
+@widgetbook.App()
+class BullUiCatalogue extends StatelessWidget {
+  const BullUiCatalogue({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Widgetbook.material(
+      directories: directories,
+      // WORKAROUND (widgetbook 3.24.0 on Flutter 3.44.1): the default
+      // `materialAppBuilder` wraps each use-case in a nested `MaterialApp`,
+      // whose Navigator trips `_history.isNotEmpty` during layout on 3.44.1.
+      // The catalogue's outer app already provides MediaQuery/Directionality/
+      // Overlay, and the theme is injected by `MaterialThemeAddon` (a `Theme`
+      // widget), so the per-use-case shell only needs a `Material` ancestor —
+      // no second `MaterialApp`/Navigator. Drop this once on widgetbook v4.
+      appBuilder: (context, child) =>
+          Material(type: MaterialType.transparency, child: child),
+      addons: [
+        // Light + dark, each carrying the BullTheme extension that components
+        // read via `context.bull`. This is exactly how the app wires bull_ui.
+        MaterialThemeAddon(
+          themes: [
+            WidgetbookTheme(name: 'Light', data: catalogueThemeData(Brightness.light)),
+            WidgetbookTheme(name: 'Dark', data: catalogueThemeData(Brightness.dark)),
+          ],
+          initialTheme: WidgetbookTheme(
+            name: 'Light',
+            data: catalogueThemeData(Brightness.light),
+          ),
+        ),
+        // NOTE: ViewportAddon (device frames) is intentionally omitted —
+        // widgetbook 3.24.0's viewport addon trips a Navigator
+        // `_history.isNotEmpty` assertion on Flutter 3.44.1 (its nested
+        // Navigator asserts during layout). Re-add once widgetbook/Flutter
+        // compatibility is resolved (e.g. widgetbook v4).
+        TextScaleAddon(initialScale: 1.0, min: 1.0, max: 2.0, divisions: 4),
+      ],
+    );
+  }
+}