fassad_ui 0.1.1

Flutter widgets and HTTP client for querying dblm fassad templates — render database results as charts and tables.

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