fassad_ui

Flutter widgets and HTTP client for querying dblm fassad templates — render your database results as charts and tables with a few lines of code.

What is a fassad?

A fassad is a reusable, parameterized query template stored in dblm. You define the query once (dblm fassad create), give it named parameters, and then run it from anywhere — including this Flutter package — without writing SQL or touching a DSN.

Architecture

Flutter app  ──►  fassad_ui  ──►  @dblm/middleware (HTTP)  ──►  dblm  ──►  database

This package talks to @dblm/middleware, which must be running before your app starts.

Setup

1. Start the middleware

npx @dblm/middleware
# set API_KEY=your-secret in .env or environment

2. Add the package

dependencies:
  fassad_ui: ^0.1.0

3. Run flutter pub get

Usage

Query and display data

import 'package:fassad_ui/fassad_ui.dart';

final client = FassadClient(
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key',
);

// Execute a fassad template
final result = await client.run('top-users', params: {'limit': '10'});

// Render as a bar chart
FassadChart(
  result: result,
  xColumn: 'name',
  yColumn: 'count',
  type: FassadChartType.bar,
)

// Render as a scrollable table
FassadTable(result: result)

Full widget example

class SalesDashboard extends StatefulWidget {
  @override
  State<SalesDashboard> createState() => _SalesDashboardState();
}

class _SalesDashboardState extends State<SalesDashboard> {
  final _client = FassadClient(
    baseUrl: 'http://localhost:3000',
    apiKey: 'your-api-key',
  );
  late Future<FassadResult> _data;

  @override
  void initState() {
    super.initState();
    _data = _client.run('monthly-sales', params: {'year': '2024'});
  }

  @override
  void dispose() {
    _client.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<FassadResult>(
      future: _data,
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return const CircularProgressIndicator();
        }
        if (snapshot.hasError) return Text('Error: ${snapshot.error}');
        return Column(
          children: [
            FassadChart(
              result: snapshot.data!,
              xColumn: 'month',
              yColumn: 'revenue',
              type: FassadChartType.line,
              height: 250,
            ),
            FassadTable(result: snapshot.data!),
          ],
        );
      },
    );
  }
}

API reference

FassadClient

FassadClient({
  required String baseUrl,  // middleware base URL, e.g. 'http://localhost:3000'
  required String apiKey,   // must match API_KEY set on the middleware
  http.Client? httpClient,  // optional — inject for testing
})
Method Returns Description
list() Future<List<FassadSummary>> List all available fassad templates
show(name) Future<FassadDetail> Get template details and parameter definitions
run(name, {params}) Future<FassadResult> Execute a template and return rows
dispose() void Close the underlying HTTP client

Throws FassadException(statusCode, body) on any non-2xx response.

FassadChart

Property Type Default Description
result FassadResult required Data from client.run()
xColumn String required Column name for X axis / pie labels
yColumn String required Column name for Y axis / pie values
type FassadChartType bar Chart type: bar, line, or pie
height double 300 Widget height in logical pixels

Shows "No data" when result.rows is empty.

Chart types:

Value Description
FassadChartType.bar Vertical bar chart
FassadChartType.line Curved line chart
FassadChartType.pie Pie chart with labels

FassadTable

Property Type Default Description
result FassadResult required Data from client.run()
columnWidth double? null Optional fixed column width

Renders a scrollable DataTable (horizontal + vertical scroll). Shows "No rows returned" when empty.

Models

FassadResult

class FassadResult {
  final List<String> columns;
  final List<List<dynamic>> rows;
  final String source;

  // Convenience accessor — returns null if column not found
  dynamic cell(int row, String column);
}

FassadSummary — name, mode, paramCount, createdAt

FassadDetail — name, mode, connection, module, body, params, createdAt, updatedAt

FassadParam — name, kind, required, defaultValue

Requirements

Dependency Version
Dart SDK ≥ 3.0.0
Flutter ≥ 3.10.0
http ^1.2.0
fl_chart ^0.68.0

License

MIT

Libraries

fassad_ui