codz-cli 0.1.2 → 0.1.8

package/dist/skills/screen.js

@@ -19,6 +19,8 @@ import { exists, readText } from "../core/fsutil.js";
 import { ToolError } from "../core/types.js";
 import { camel, kebab, pascal, snake } from "../input/naming.js";
 import { findDeclaration } from "./apiEdit.js";
+import { splitTsParams } from "../adapters/reactQuery.js";
+import { dartPagingCall, dartSearchMatch, detectPaging, PAGE_SIZE, pagingSummary, pagingWarnings, tsPagingArgs, tsPagingParams } from "./paging.js";
 import { planModuleAdd } from "./module.js";
 import { planRouteAdd } from "./route.js";
 /** Dart: the text a Text widget shows for a field: a non-null String as it is, anything else interpolated (never a dead ?? on a field that turns out non-null). */
@@ -101,6 +103,14 @@ export function routeParams(path) {
 function missingArgsError(ep, missing, params, name) {
     return new ToolError('screen_args', `${ep.name}() needs ${missing.map((a) => a.name).join(', ')}, which the screen does not have.`, `Give the route a matching parameter, for example: codz screen add ${name} --api ${ep.name} --path /${kebab(name)}/:${missing[0].name}${params.length ? ` (the route has ${params.join(', ')})` : ''}`);
 }
+/** The item type of a Dart list type: List<ProductModel> → ProductModel. */
+const itemType = (t) => /^List<(.+)>\??$/.exec(t.trim())?.[1] ?? 'dynamic';
+/** Paging for a Dart list endpoint (Flutter screens). */
+function dartPaging(shape, args, opts, name, returnType) {
+    if (!shape.list)
+        throw new ToolError('screen_not_list', `${name}() returns ${returnType}, not a list; --paginate and --search are for list screens.`);
+    return detectPaging(args.map((a) => ({ name: a.name, type: a.type })), { paginate: opts.paginate, search: opts.search, modelStringFields: (shape.model?.fields ?? []).filter((f) => f.type === 'String').map((f) => f.name), titleField: titleField(shape.model) });
+}
 // ---------------- GetX ----------------
 async function getxScreen(root, adapter, map, opts) {
     const ep = opts.api ? findEndpoint(map, opts.api) : undefined;
@@ -112,6 +122,8 @@ async function getxScreen(root, adapter, map, opts) {
     const ctrlChange = cs.changes.find((c) => c.path.endsWith(`/controllers/${snake(opts.name)}_controller.dart`));
     if (!viewChange?.after || !ctrlChange?.after)
         return cs;
+    if (opts.paginate || opts.search)
+        return getxPaged(root, map, opts, ep, cs, viewChange, ctrlChange);
     // The names api wire chose: getProducts → products / isProductsLoading / productsError / loadProducts().
     const stripped = ep.name.replace(/^(get|fetch|load)(?=[A-Z])/, '');
     const base = stripped !== ep.name ? camel(stripped) : ep.name;
@@ -188,6 +200,154 @@ async function getxScreen(root, adapter, map, opts) {
     }
     return cs;
 }
+/** GetX: the module's controller holds items, isLoading, error, query (and hasMore), and its view lists them. */
+function getxPaged(root, map, opts, ep, cs, view, ctrl) {
+    const sig = readMethod(readText(join(root, ep.file)) ?? '', ep.name);
+    if (!sig)
+        throw new ToolError('no_endpoint', `Could not read ${ep.name} in ${ep.file}.`);
+    const args = dartArgs(sig.params);
+    const params = routeParams(opts.path);
+    const missing = args.filter((a) => a.required && !params.includes(a.name));
+    if (missing.length)
+        throw missingArgsError(ep, missing, params, opts.name);
+    const shape = responseShape(sig.returnType, map);
+    const paging = dartPaging(shape, args, opts, ep.name, sig.returnType);
+    const item = itemType(sig.returnType);
+    const repoLine = /^ {2}final (\w+) (_\w+) = Get\.find<\w+>\(\);$/m.exec(ctrl.after);
+    const cls = /class\s+(\w+)\s+extends\s+GetxController/.exec(ctrl.after)?.[1];
+    if (!repoLine || !cls)
+        throw new ToolError('not_supported', `Could not read the controller codz wrote (${ctrl.path}).`);
+    const repo = repoLine[2];
+    const searchable = Boolean(paging.search || paging.clientSearch);
+    const pg = paging.paginate;
+    const first = paging.page?.mode === 'offset' ? '0' : '1';
+    const conv = (a, v) => (/^int\??$/.test(a.type) ? `int.parse(${v})` : /^double\??$/.test(a.type) ? `double.parse(${v})` : v);
+    const routeVals = new Map(args.filter((a) => params.includes(a.name)).map((a) => [a.name, conv(a, `Get.parameters['${a.name}']!`)]));
+    const call = dartPagingCall(args, paging, routeVals, { page: pg ? 'next' : undefined, search: paging.search ? 'query.value.isEmpty ? null : query.value' : undefined }, '_pageSize');
+    const strFields = paging.searchFields.map((f) => ({ name: f, nullable: fieldOf(shape.model, f)?.nullable ?? true }));
+    const imports = ctrl.after.split('\n').filter((l) => l.startsWith('import ') && !l.includes('package:get/get.dart'));
+    ctrl.after = [
+        ...(paging.search ? ["import 'dart:async';", ''] : []),
+        "import 'package:get/get.dart';",
+        '',
+        ...imports,
+        '',
+        `class ${cls} extends GetxController {`,
+        repoLine[0],
+        '',
+        ...(pg && paging.size ? [`  static const _pageSize = ${PAGE_SIZE};`, ''] : []),
+        `  // GET ${ep.path} via ${repoLine[1]}.${ep.name}`,
+        `  final items = <${item}>[].obs;`,
+        '  final isLoading = false.obs;',
+        '  final error = RxnString();',
+        ...(pg ? ['  final hasMore = true.obs;'] : []),
+        ...(searchable ? ["  final query = ''.obs;"] : []),
+        ...(pg && paging.page.mode === 'page' ? ['  int _page = 0;'] : []),
+        '  int _request = 0;',
+        ...(paging.search ? ['  Timer? _debounce;'] : []),
+        '',
+        ...(paging.clientSearch
+            ? ['  /// The items that match the search.', `  List<${item}> get visible => query.value.isEmpty ? items : items.where((item) => ${dartSearchMatch(strFields, 'item', 'query.value', camel)}).toList();`, '']
+            : []),
+        `  /// Loads ${pg ? 'the first page again (reset) or the next one' : 'the list'}. Only the latest request counts.`,
+        `  Future<void> load(${pg ? '{bool reset = false}' : ''}) async {`,
+        ...(pg ? ['    if (!reset && (isLoading.value || !hasMore.value)) return;'] : []),
+        '    final request = ++_request;',
+        '    isLoading.value = true;',
+        '    error.value = null;',
+        '    try {',
+        ...(pg ? [`      final next = reset ? ${first} : ${paging.page.mode === 'offset' ? 'items.length' : '_page + 1'};`] : []),
+        `      final rows = await ${repo}.${ep.name}(${call});`,
+        '      if (request != _request) return;',
+        ...(pg ? ['      if (reset) {', '        items.assignAll(rows);', '      } else {', '        items.addAll(rows);', '      }', ...(paging.page.mode === 'page' ? ['      _page = next;'] : []), `      hasMore.value = ${paging.size ? 'rows.length == _pageSize' : 'rows.isNotEmpty'};`] : ['      items.assignAll(rows);']),
+        '    } catch (e) {',
+        '      if (request == _request) error.value = e.toString();',
+        '    } finally {',
+        '      if (request == _request) isLoading.value = false;',
+        '    }',
+        '  }',
+        ...(paging.search
+            ? ['', '  void search(String text) {', '    _debounce?.cancel();', '    _debounce = Timer(const Duration(milliseconds: 400), () {', '      query.value = text.trim();', `      load(${pg ? 'reset: true' : ''});`, '    });', '  }']
+            : paging.clientSearch
+                ? ['', '  void search(String text) => query.value = text.trim().toLowerCase();']
+                : []),
+        '',
+        '  @override',
+        '  void onInit() {',
+        '    super.onInit();',
+        `    load(${pg ? 'reset: true' : ''});`,
+        '  }',
+        ...(paging.search ? ['', '  @override', '  void onClose() {', '    _debounce?.cancel();', '    super.onClose();', '  }'] : []),
+        '}',
+        '',
+    ].join('\n');
+    const title = titleField(shape.model);
+    const show = (v) => (title ? dartShow(`${v}.${camel(title)}`, fieldOf(shape.model, title)) : `${v}.toString()`);
+    const reset = pg ? 'reset: true' : '';
+    const I = '        ';
+    const list = [
+        'Obx(() {',
+        `${I}final shown = controller.${paging.clientSearch ? 'visible' : 'items'};`,
+        `${I}final error = controller.error.value;`,
+        `${I}if (controller.items.isEmpty && controller.isLoading.value) return const Center(child: CircularProgressIndicator());`,
+        `${I}if (controller.items.isEmpty && error != null) {`,
+        `${I}  return Center(`,
+        `${I}    child: Column(`,
+        `${I}      mainAxisSize: MainAxisSize.min,`,
+        `${I}      children: [`,
+        `${I}        Text(error, textAlign: TextAlign.center),`,
+        `${I}        TextButton(onPressed: () => controller.load(${reset}), child: const Text('Retry')),`,
+        `${I}      ],`,
+        `${I}    ),`,
+        `${I}  );`,
+        `${I}}`,
+        `${I}if (shown.isEmpty${pg ? ' && !controller.hasMore.value' : ''}) return Center(child: Text(${searchable ? "controller.query.value.isEmpty ? 'No items' : 'No matches'" : "'No items'"}));`,
+        `${I}return RefreshIndicator(`,
+        `${I}  onRefresh: () => controller.load(${reset}),`,
+        `${I}  child: ListView.builder(`,
+        `${I}    physics: const AlwaysScrollableScrollPhysics(),`,
+        `${I}    itemCount: shown.length${pg ? ' + (controller.hasMore.value || error != null ? 1 : 0)' : ''},`,
+        `${I}    itemBuilder: (context, index) {`,
+        ...(pg
+            ? [
+                `${I}      if (index == shown.length) {`,
+                `${I}        if (error != null) return TextButton(onPressed: () => controller.load(), child: const Text('Retry'));`,
+                `${I}        // The end of the list is on screen: ask for the next page.`,
+                `${I}        if (!controller.isLoading.value) WidgetsBinding.instance.addPostFrameCallback((_) => controller.load());`,
+                `${I}        return const Padding(padding: EdgeInsets.all(16), child: Center(child: CircularProgressIndicator()));`,
+                `${I}      }`,
+            ]
+            : []),
+        `${I}      return ListTile(title: Text(${show('shown[index]')}));`,
+        `${I}    },`,
+        `${I}  ),`,
+        `${I});`,
+        '      })',
+    ];
+    const body = searchable
+        ? [
+            '      body: Column(',
+            '        children: [',
+            '          Padding(',
+            '            padding: const EdgeInsets.all(12),',
+            "            child: TextField(onChanged: controller.search, decoration: const InputDecoration(hintText: 'Search', prefixIcon: Icon(Icons.search), border: OutlineInputBorder())),",
+            '          ),',
+            `          Expanded(child: ${list.map((l, i) => (i === 0 ? l : `    ${l}`)).join('\n')}),`,
+            '        ],',
+            '      ),',
+        ].join('\n')
+        : `      body: ${list.join('\n')},`;
+    const replaced = view.after.replace(/ {6}body: const Center\(child: Text\('\w+ is working'\)\),/, body);
+    if (replaced === view.after)
+        throw new ToolError('not_supported', `Could not fill the view codz wrote (${view.path}).`);
+    view.after = replaced;
+    cs.summary = cs.summary.filter((l) => !/^In \w+View: Obx|^Update .*controller\.dart: load|^Show /.test(l));
+    cs.summary.push(`${ctrl.path}: items, isLoading, error${searchable ? ', query' : ''}${pg ? ', hasMore' : ''} and load()`, `${view.path} lists them and ${pagingSummary(paging)}`);
+    cs.warnings.push(...pagingWarnings(paging));
+    if (params.length)
+        cs.warnings.push(`The controller reads ${params.join(', ')} from Get.parameters; open the page with Get.toNamed(Routes.X, parameters: {...}).`);
+    return cs;
+}
 // ---------------- Flutter (riverpod, get_it) ----------------
 async function flutterScreen(root, adapter, map, opts) {
     const route = await planRouteAdd(root, adapter, { name: opts.name, path: opts.path, initial: opts.initial });
@@ -233,6 +393,146 @@ async function flutterScreen(root, adapter, map, opts) {
     const stateBase = riverpod ? 'ConsumerStatefulWidget' : 'StatefulWidget';
     const stateCls = riverpod ? `ConsumerState<${cls}>` : `State<${cls}>`;
     const titleText = page.after.match(/AppBar\(title: const Text\('([^']*)'\)\)/)?.[1] ?? pascal(opts.name);
+    if (opts.paginate || opts.search) {
+        const paging = dartPaging(shape, args, opts, ep.name, sig.returnType);
+        const routeVals = new Map(args.filter((a) => params.includes(a.name)).map((a) => [a.name, /^int\??$/.test(a.type) ? `int.parse(widget.${a.name})` : /^double\??$/.test(a.type) ? `double.parse(widget.${a.name})` : `widget.${a.name}`]));
+        const item = itemType(sig.returnType);
+        const searchable = Boolean(paging.search || paging.clientSearch);
+        const first = paging.page?.mode === 'offset' ? '0' : '1';
+        const call = dartPagingCall(args, paging, routeVals, { page: paging.paginate ? 'next' : undefined, search: paging.search ? '_query.isEmpty ? null : _query' : undefined }, '_pageSize');
+        const show = (v) => (title ? dartShow(`${v}.${camel(title)}`, fieldOf(shape.model, title)) : `${v}.toString()`);
+        const strFields = paging.searchFields.map((n) => ({ name: n, nullable: fieldOf(shape.model, n)?.nullable ?? true }));
+        let text = [
+            ...(paging.search ? ["import 'dart:async';", ''] : []),
+            "import 'package:flutter/material.dart';",
+            '',
+            `class ${cls} extends ${stateBase} {`,
+            `  ${ctor}`,
+            ...(fields ? ['', fields.trimEnd()] : []),
+            '',
+            '  @override',
+            `  ${stateCls.replace(/<.*/, '')}<${cls}> createState() => _${cls}State();`,
+            '}',
+            '',
+            `class _${cls}State extends ${stateCls} {`,
+            ...(paging.paginate && paging.size ? [`  static const _pageSize = ${PAGE_SIZE};`, ''] : []),
+            `  final _items = <${item}>[];`,
+            ...(paging.search ? ['  Timer? _debounce;'] : []),
+            ...(searchable ? ["  String _query = '';"] : []),
+            ...(paging.paginate && paging.page.mode === 'page' ? ['  int _page = 0;'] : []),
+            ...(paging.paginate ? ['  bool _hasMore = true;'] : []),
+            '  bool _loading = false;',
+            '  Object? _error;',
+            '  int _request = 0;',
+            '',
+            '  @override',
+            '  void initState() {',
+            '    super.initState();',
+            `    _load(${paging.paginate ? 'reset: true' : ''});`,
+            '  }',
+            ...(paging.search ? ['', '  @override', '  void dispose() {', '    _debounce?.cancel();', '    super.dispose();', '  }'] : []),
+            '',
+            `  /// Loads ${paging.paginate ? 'the first page again (reset) or the next one' : 'the list'}.`,
+            `  Future<void> _load(${paging.paginate ? '{bool reset = false}' : ''}) async {`,
+            ...(paging.paginate ? ['    if (!reset && (_loading || !_hasMore)) return;'] : []),
+            '    // Only the latest request counts: a new search or refresh replaces one still loading.',
+            '    final request = ++_request;',
+            '    setState(() {',
+            '      _loading = true;',
+            '      _error = null;',
+            '    });',
+            '    try {',
+            ...(paging.paginate ? [`      final next = reset ? ${first} : ${paging.page.mode === 'offset' ? '_items.length' : '_page + 1'};`] : []),
+            `      final rows = await ${repoExpr}.${ep.name}(${call});`,
+            '      if (!mounted || request != _request) return;',
+            '      setState(() {',
+            ...(paging.paginate ? ['        if (reset) _items.clear();'] : ['        _items.clear();']),
+            '        _items.addAll(rows);',
+            ...(paging.paginate ? [...(paging.page.mode === 'page' ? ['        _page = next;'] : []), `        _hasMore = ${paging.size ? 'rows.length == _pageSize' : 'rows.isNotEmpty'};`] : []),
+            '      });',
+            '    } catch (e) {',
+            '      if (mounted && request == _request) setState(() => _error = e);',
+            '    } finally {',
+            '      if (mounted && request == _request) setState(() => _loading = false);',
+            '    }',
+            '  }',
+            ...(paging.search
+                ? ['', '  void _onSearch(String text) {', '    _debounce?.cancel();', '    _debounce = Timer(const Duration(milliseconds: 400), () {', '      _query = text.trim();', `      _load(${paging.paginate ? 'reset: true' : ''});`, '    });', '  }']
+                : paging.clientSearch
+                    ? ['', '  void _onSearch(String text) => setState(() => _query = text.trim().toLowerCase());']
+                    : []),
+            '',
+            '  @override',
+            '  Widget build(BuildContext context) {',
+            '    return Scaffold(',
+            `      appBar: AppBar(title: const Text('${titleText}')),`,
+            ...(searchable
+                ? [
+                    '      body: Column(',
+                    '        children: [',
+                    '          Padding(',
+                    '            padding: const EdgeInsets.all(12),',
+                    "            child: TextField(onChanged: _onSearch, decoration: const InputDecoration(hintText: 'Search', prefixIcon: Icon(Icons.search), border: OutlineInputBorder())),",
+                    '          ),',
+                    '          Expanded(child: _list()),',
+                    '        ],',
+                    '      ),',
+                ]
+                : ['      body: _list(),']),
+            '    );',
+            '  }',
+            '',
+            '  Widget _list() {',
+            `    final shown = ${paging.clientSearch ? `_query.isEmpty ? _items : _items.where((item) => ${dartSearchMatch(strFields, 'item', '_query', camel)}).toList()` : '_items'};`,
+            '    if (_items.isEmpty && _loading) return const Center(child: CircularProgressIndicator());',
+            '    if (_items.isEmpty && _error != null) {',
+            '      return Center(',
+            '        child: Column(',
+            '          mainAxisSize: MainAxisSize.min,',
+            '          children: [',
+            "            Text('$_error', textAlign: TextAlign.center),",
+            `            TextButton(onPressed: () => _load(${paging.paginate ? 'reset: true' : ''}), child: const Text('Retry')),`,
+            '          ],',
+            '        ),',
+            '      );',
+            '    }',
+            `    if (shown.isEmpty${paging.paginate ? ' && !_hasMore' : ''}) return Center(child: Text(${searchable ? "_query.isEmpty ? 'No items' : 'No matches'" : "'No items'"}));`,
+            '    return RefreshIndicator(',
+            `      onRefresh: () => _load(${paging.paginate ? 'reset: true' : ''}),`,
+            '      child: ListView.builder(',
+            '        physics: const AlwaysScrollableScrollPhysics(),',
+            `        itemCount: shown.length${paging.paginate ? ' + (_hasMore || _error != null ? 1 : 0)' : ''},`,
+            '        itemBuilder: (context, index) {',
+            ...(paging.paginate
+                ? [
+                    '          if (index == shown.length) {',
+                    "            if (_error != null) return TextButton(onPressed: () => _load(), child: const Text('Retry'));",
+                    '            // The end of the list is on screen: ask for the next page.',
+                    '            if (!_loading) WidgetsBinding.instance.addPostFrameCallback((_) => _load());',
+                    '            return const Padding(padding: EdgeInsets.all(16), child: Center(child: CircularProgressIndicator()));',
+                    '          }',
+                ]
+                : []),
+            `          return ListTile(title: Text(${show('shown[index]')}));`,
+            '        },',
+            '      ),',
+            '    );',
+            '  }',
+            '}',
+            '',
+        ].join('\n');
+        if (riverpod)
+            text = addDartImport(text, 'package:flutter_riverpod/flutter_riverpod.dart');
+        text = addDartImport(text, importUri(page.path, ep.file, c));
+        if (getIt && c.diFile)
+            text = addDartImport(text, importUri(page.path, c.diFile, c));
+        if (shape.model && shape.model.file !== ep.file)
+            text = addDartImport(text, importUri(page.path, shape.model.file, c));
+        page.after = text;
+        route.summary.push(`${page.path} lists ${ep.name}() and ${pagingSummary(paging)}`);
+        route.warnings.push(...pagingWarnings(paging));
+        return route;
+    }
     const I = '          ';
     const dataView = shape.list
         ? [
@@ -344,6 +644,8 @@ function blocScreen(root, route, page, cls, ep, sig, args, params, map, opts) {
     const repoExpr = getIt ? `${c.diInstance || 'getIt'}<${sig.repoClass}>()` : `context.read<${sig.repoClass}>()`;
     if (!getIt)
         route.warnings.push(`${page.path} reads ${sig.repoClass} with context.read, so provide it above this page: RepositoryProvider(create: (_) => ${sig.repoClass}(...), child: ...).`);
+    if (opts.paginate || opts.search)
+        return blocPagedScreen(root, route, page, cls, ep, sig, args, params, map, opts, { cubit, state, cubitFile, repoExpr, base });
     let cubitText = [
         "import 'package:flutter_bloc/flutter_bloc.dart';",
         '',
@@ -469,6 +771,171 @@ function blocScreen(root, route, page, cls, ep, sig, args, params, map, opts) {
     const summary = [...route.summary, `Create ${cubitFile}: ${cubit} with loading, loaded and failure states, calling ${sig.repoClass}.${ep.name}()`, `${page.path} provides ${cubit} and shows loading, error with retry, and the data`];
     return buildChangeSet(root, 'screen add', { files, summary, warnings: route.warnings, generated: [] });
 }
+/** Bloc: a Cubit with one state (items, loading, error, query, hasMore) for a paged or searchable list, and its page. */
+function blocPagedScreen(root, route, page, cls, ep, sig, args, params, map, opts, n) {
+    const c = map.conventions;
+    const T = sig.returnType;
+    const shape = responseShape(T, map);
+    const paging = dartPaging(shape, args, opts, ep.name, T);
+    const item = itemType(T);
+    const { cubit, state } = n;
+    const searchable = Boolean(paging.search || paging.clientSearch);
+    const pg = paging.paginate;
+    const first = paging.page?.mode === 'offset' ? '0' : '1';
+    const conv = (a, v) => (/^int\??$/.test(a.type) ? `int.parse(${v})` : /^double\??$/.test(a.type) ? `double.parse(${v})` : v);
+    const routeVals = new Map(args.filter((a) => params.includes(a.name)).map((a) => [a.name, conv(a, a.name)]));
+    const call = dartPagingCall(args, paging, routeVals, { page: pg ? 'next' : undefined, search: paging.search ? 'state.query.isEmpty ? null : state.query' : undefined }, '_pageSize');
+    const title = titleField(shape.model);
+    const show = (v) => (title ? dartShow(`${v}.${camel(title)}`, fieldOf(shape.model, title)) : `${v}.toString()`);
+    const strFields = paging.searchFields.map((f) => ({ name: f, nullable: fieldOf(shape.model, f)?.nullable ?? true }));
+    const stateFields = [
+        { decl: `final List<${item}> items;`, param: 'this.items = const []', copy: `List<${item}>? items`, set: 'items: items ?? this.items' },
+        { decl: 'final bool loading;', param: 'this.loading = false', copy: 'bool? loading', set: 'loading: loading ?? this.loading' },
+        ...(pg ? [{ decl: 'final bool hasMore;', param: 'this.hasMore = true', copy: 'bool? hasMore', set: 'hasMore: hasMore ?? this.hasMore' }] : []),
+        { decl: 'final String? error;', param: 'this.error', copy: 'String? error, bool clearError = false', set: 'error: clearError ? null : (error ?? this.error)' },
+        ...(searchable ? [{ decl: 'final String query;', param: "this.query = ''", copy: 'String? query', set: 'query: query ?? this.query' }] : []),
+    ];
+    let cubitText = [
+        ...(paging.search ? ["import 'dart:async';", ''] : []),
+        "import 'package:flutter_bloc/flutter_bloc.dart';",
+        '',
+        `class ${state} {`,
+        `  const ${state}({${stateFields.map((f) => f.param).join(', ')}});`,
+        '',
+        ...stateFields.map((f) => `  ${f.decl}`),
+        '',
+        `  ${state} copyWith({${stateFields.map((f) => f.copy).join(', ')}}) => ${state}(`,
+        ...stateFields.map((f) => `        ${f.set},`),
+        '      );',
+        '}',
+        '',
+        `class ${cubit} extends Cubit<${state}> {`,
+        `  ${cubit}(this._api${params.length ? `, {${params.map((p) => `required this.${p}`).join(', ')}}` : ''}) : super(const ${state}());`,
+        '',
+        ...(pg && paging.size ? [`  static const _pageSize = ${PAGE_SIZE};`, ''] : []),
+        `  final ${sig.repoClass} _api;`,
+        ...params.map((p) => `  final String ${p};`),
+        ...(pg && paging.page.mode === 'page' ? ['  int _page = 0;'] : []),
+        '  int _request = 0;',
+        ...(paging.search ? ['  Timer? _debounce;'] : []),
+        '',
+        `  /// Loads ${pg ? 'the first page again (reset) or the next one' : 'the list'}. Only the latest request counts.`,
+        `  Future<void> load(${pg ? '{bool reset = false}' : ''}) async {`,
+        ...(pg ? ['    if (!reset && (state.loading || !state.hasMore)) return;'] : []),
+        '    final request = ++_request;',
+        '    emit(state.copyWith(loading: true, clearError: true));',
+        '    try {',
+        ...(pg ? [`      final next = reset ? ${first} : ${paging.page.mode === 'offset' ? 'state.items.length' : '_page + 1'};`] : []),
+        `      final rows = await _api.${ep.name}(${call});`,
+        '      if (request != _request || isClosed) return;',
+        ...(pg && paging.page.mode === 'page' ? ['      _page = next;'] : []),
+        pg
+            ? `      emit(state.copyWith(items: reset ? rows : [...state.items, ...rows], hasMore: ${paging.size ? 'rows.length == _pageSize' : 'rows.isNotEmpty'}, loading: false));`
+            : '      emit(state.copyWith(items: rows, loading: false));',
+        '    } catch (e) {',
+        '      if (request == _request && !isClosed) emit(state.copyWith(loading: false, error: e.toString()));',
+        '    }',
+        '  }',
+        ...(paging.search
+            ? ['', '  void search(String text) {', '    _debounce?.cancel();', '    _debounce = Timer(const Duration(milliseconds: 400), () {', '      emit(state.copyWith(query: text.trim()));', `      load(${pg ? 'reset: true' : ''});`, '    });', '  }', '', '  @override', '  Future<void> close() {', '    _debounce?.cancel();', '    return super.close();', '  }']
+            : paging.clientSearch
+                ? ['', '  void search(String text) => emit(state.copyWith(query: text.trim().toLowerCase()));']
+                : []),
+        '}',
+        '',
+    ].join('\n');
+    cubitText = addDartImport(cubitText, importUri(n.cubitFile, ep.file, c));
+    if (shape.model && shape.model.file !== ep.file)
+        cubitText = addDartImport(cubitText, importUri(n.cubitFile, shape.model.file, c));
+    const reset = pg ? 'reset: true' : '';
+    const titleText = page.after.match(/AppBar\(title: const Text\('([^']*)'\)\)/)?.[1] ?? n.base;
+    const ctor = params.length ? `const ${cls}({super.key, ${params.map((p) => `required this.${p}`).join(', ')}});` : `const ${cls}({super.key});`;
+    const getIt = c.di === 'get_it';
+    let pageText = [
+        "import 'package:flutter/material.dart';",
+        "import 'package:flutter_bloc/flutter_bloc.dart';",
+        '',
+        `class ${cls} extends StatelessWidget {`,
+        `  ${ctor}`,
+        ...(params.length ? ['', ...params.map((p) => `  final String ${p};`)] : []),
+        '',
+        '  @override',
+        '  Widget build(BuildContext context) {',
+        '    return BlocProvider(',
+        `      create: (context) => ${cubit}(${n.repoExpr}${params.length ? `, ${params.map((p) => `${p}: ${p}`).join(', ')}` : ''})..load(${reset}),`,
+        '      child: Scaffold(',
+        `        appBar: AppBar(title: const Text('${titleText}')),`,
+        `        body: BlocBuilder<${cubit}, ${state}>(`,
+        ...(searchable
+            ? [
+                '          builder: (context, state) => Column(',
+                '            children: [',
+                '              Padding(',
+                '                padding: const EdgeInsets.all(12),',
+                `                child: TextField(onChanged: context.read<${cubit}>().search, decoration: const InputDecoration(hintText: 'Search', prefixIcon: Icon(Icons.search), border: OutlineInputBorder())),`,
+                '              ),',
+                '              Expanded(child: _list(context, state)),',
+                '            ],',
+                '          ),',
+            ]
+            : ['          builder: _list,']),
+        '        ),',
+        '      ),',
+        '    );',
+        '  }',
+        '',
+        `  Widget _list(BuildContext context, ${state} state) {`,
+        `    final shown = ${paging.clientSearch ? `state.query.isEmpty ? state.items : state.items.where((item) => ${dartSearchMatch(strFields, 'item', 'state.query', camel)}).toList()` : 'state.items'};`,
+        '    final error = state.error;',
+        '    if (state.items.isEmpty && state.loading) return const Center(child: CircularProgressIndicator());',
+        '    if (state.items.isEmpty && error != null) {',
+        '      return Center(',
+        '        child: Column(',
+        '          mainAxisSize: MainAxisSize.min,',
+        '          children: [',
+        '            Text(error, textAlign: TextAlign.center),',
+        `            TextButton(onPressed: () => context.read<${cubit}>().load(${reset}), child: const Text('Retry')),`,
+        '          ],',
+        '        ),',
+        '      );',
+        '    }',
+        `    if (shown.isEmpty${pg ? ' && !state.hasMore' : ''}) return Center(child: Text(${searchable ? "state.query.isEmpty ? 'No items' : 'No matches'" : "'No items'"}));`,
+        '    return RefreshIndicator(',
+        `      onRefresh: () => context.read<${cubit}>().load(${reset}),`,
+        '      child: ListView.builder(',
+        '        physics: const AlwaysScrollableScrollPhysics(),',
+        `        itemCount: shown.length${pg ? ' + (state.hasMore || error != null ? 1 : 0)' : ''},`,
+        '        itemBuilder: (context, index) {',
+        ...(pg
+            ? [
+                '          if (index == shown.length) {',
+                `            if (error != null) return TextButton(onPressed: () => context.read<${cubit}>().load(), child: const Text('Retry'));`,
+                '            // The end of the list is on screen: ask for the next page.',
+                `            if (!state.loading) WidgetsBinding.instance.addPostFrameCallback((_) => context.read<${cubit}>().load());`,
+                '            return const Padding(padding: EdgeInsets.all(16), child: Center(child: CircularProgressIndicator()));',
+                '          }',
+            ]
+            : []),
+        `          return ListTile(title: Text(${show('shown[index]')}));`,
+        '        },',
+        '      ),',
+        '    );',
+        '  }',
+        '}',
+        '',
+    ].join('\n');
+    pageText = addDartImport(pageText, importUri(page.path, n.cubitFile, c));
+    if (getIt && c.diFile)
+        pageText = addDartImport(pageText, importUri(page.path, c.diFile, c));
+    pageText = addDartImport(pageText, importUri(page.path, ep.file, c));
+    page.after = pageText;
+    const files = new Map(route.changes.filter((ch) => ch.after !== null).map((ch) => [ch.path, ch.after]));
+    if (exists(join(root, n.cubitFile)))
+        throw new ToolError('file_exists', `${n.cubitFile} already exists.`, 'Pick another screen name.');
+    files.set(n.cubitFile, cubitText);
+    const summary = [...route.summary, `Create ${n.cubitFile}: ${cubit} with items, loading, error${searchable ? ', query' : ''}${pg ? ' and hasMore' : ''}, calling ${sig.repoClass}.${ep.name}()`, `${page.path} lists it and ${pagingSummary(paging)}`];
+    return buildChangeSet(root, 'screen add', { files, summary, warnings: [...route.warnings, ...pagingWarnings(paging)], generated: [] });
+}
 // ---------------- Next.js ----------------
 async function nextScreen(root, adapter, map, opts) {
     const route = await planRouteAdd(root, adapter, { name: opts.name, path: opts.path, initial: opts.initial });
@@ -523,28 +990,91 @@ async function nextScreen(root, adapter, map, opts) {
             ? ['      <dl>', ...shape.model.fields.flatMap((f) => [`        <dt>${f.name}</dt>`, `        <dd>{String(${dataVar}.${f.name} ?? '')}</dd>`]), '      </dl>']
             : [`      <pre>{JSON.stringify(${dataVar}, null, 2)}</pre>`];
     const sigParams = params.length ? `{ params }: { params: Promise<{ ${params.map((p) => `${p}: string`).join('; ')} }> }` : '';
-    page.after = [
-        `import { ${ep.name} } from ${q}${from}${q}${semi}`,
-        '',
-        // Without route parameters Next.js would render the page once at build time,
-        // calling the API then (and failing the build when it is not reachable).
-        ...(params.length ? [] : ['// Rendered on each request: the data comes from the API.', `export const dynamic = ${q}force-dynamic${q}${semi}`, '']),
-        `export default async function ${comp}(${sigParams}) {`,
-        ...(params.length ? [`  const { ${params.join(', ')} } = await params${semi}`] : []),
-        `  const ${dataVar} = await ${ep.name}(${callArgs})${semi}`,
-        '  return (',
-        '    <main>',
-        `      <h1>${title}</h1>`,
-        ...render,
-        '    </main>',
-        `  )${semi}`,
-        '}',
-        '',
-    ].join('\n');
+    const pkgText = readText(join(root, 'package.json')) ?? '';
+    const major = Number(/"next"\s*:\s*"[^\d]*(\d+)/.exec(pkgText)?.[1] ?? 15);
+    let pagingInfo = null;
+    if (opts.paginate || opts.search) {
+        if (!shape.list)
+            throw new ToolError('screen_not_list', `${ep.name}() returns one ${shape.raw || 'value'}, not a list; --paginate and --search are for list screens.`);
+        const ps = splitTsParams(decl.params);
+        const paging = detectPaging(tsPagingParams(ps), { paginate: opts.paginate, search: opts.search, modelStringFields: (shape.model?.fields ?? []).filter((f) => f.type === 'string').map((f) => f.name), titleField: tf });
+        const routeArgs = new Map(ps.filter((x) => params.includes(x.name)).map((x) => [x.name, /^number$/.test(x.type) ? `Number(${x.name})` : x.name]));
+        const searchable = Boolean(paging.search || paging.clientSearch);
+        const offset = paging.page?.mode === 'offset';
+        const urlKeys = [...(paging.paginate ? [offset ? 'offset' : 'page'] : []), ...(searchable ? ['q'] : [])];
+        const sp = urlKeys.map((k) => `${k}?: string`).join('; ');
+        const props = [...(params.length ? [`params: ${major >= 15 ? 'Promise<' : ''}{ ${params.map((x) => `${x}: string`).join('; ')} }${major >= 15 ? '>' : ''}`] : []), `searchParams: ${major >= 15 ? 'Promise<' : ''}{ ${sp} }${major >= 15 ? '>' : ''}`];
+        const aw = major >= 15 ? 'await ' : '';
+        const call = tsPagingArgs(ps, paging, routeArgs, { page: paging.paginate ? (offset ? 'offset' : 'page') : undefined, search: paging.search ? 'q || undefined' : undefined });
+        const access = (v, f) => (/^[A-Za-z_$][\w$]*$/.test(f) ? `${v}.${f}` : `${v}['${f}']`);
+        const more = paging.size ? 'items.length === PAGE_SIZE' : 'items.length > 0';
+        const qs = (pageExpr) => `\`?\${new URLSearchParams({ ${searchable ? '...(q ? { q } : {}), ' : ''}${offset ? 'offset' : 'page'}: String(${pageExpr}) })}\``;
+        page.after = [
+            ...(paging.paginate ? [`import Link from ${q}next/link${q}${semi}`] : []),
+            `import { ${ep.name} } from ${q}${from}${q}${semi}`,
+            '',
+            '// Rendered on each request: the data, the page and the search come from the request.',
+            `export const dynamic = ${q}force-dynamic${q}${semi}`,
+            ...(paging.paginate && paging.size ? [`const PAGE_SIZE = ${20}${semi}`] : []),
+            '',
+            `export default async function ${comp}({ ${[...(params.length ? ['params'] : []), 'searchParams'].join(', ')} }: { ${props.join('; ')} }) {`,
+            ...(params.length ? [`  const { ${params.join(', ')} } = ${aw}params${semi}`] : []),
+            `  const { ${[...(paging.paginate ? [`${offset ? 'offset' : 'page'}: at`] : []), ...(searchable ? [`q = ${q}${q}`] : [])].join(', ')} } = ${aw}searchParams${semi}`,
+            ...(paging.paginate ? [offset ? `  const offset = Math.max(0, Number(at) || 0)${semi}` : `  const page = Math.max(1, Number(at) || 1)${semi}`] : []),
+            `  const items = await ${ep.name}(${call})${semi}`,
+            ...(paging.clientSearch
+                ? [`  const needle = q.trim().toLowerCase()${semi}`, `  const shown = needle ? items.filter((item) => [${paging.searchFields.map((f) => access('item', f)).join(', ')}].some((v) => String(v ?? ${q}${q}).toLowerCase().includes(needle))) : items${semi}`]
+                : [`  const shown = items${semi}`]),
+            '  return (',
+            '    <main>',
+            `      <h1>${title}</h1>`,
+            ...(searchable ? ['      <form role="search">', '        <input type="search" name="q" defaultValue={q} placeholder="Search" aria-label="Search" />', '        <button type="submit">Search</button>', '      </form>'] : []),
+            '      {shown.length === 0 ? (',
+            `        <p>${searchable ? `{q ? 'No matches.' : 'Nothing here yet.'}` : 'Nothing here yet.'}</p>`,
+            '      ) : (',
+            '        <ul>',
+            `          {shown.map((item${idf ? '' : ', index'}) => (`,
+            `            <li key={${idf ? `String(item.${idf})` : 'index'}}>{${tf ? `String(item.${tf})` : 'JSON.stringify(item)'}}</li>`,
+            '          ))}',
+            '        </ul>',
+            '      )}',
+            ...(paging.paginate
+                ? [
+                    '      <nav aria-label="Pages">',
+                    offset ? `        {offset > 0 ? <Link href={${qs('0')}}>First page</Link> : null}` : `        {page > 1 ? <Link href={${qs('page - 1')}}>Previous</Link> : null}`,
+                    `        {${more} ? <Link href={${qs(offset ? 'offset + items.length' : 'page + 1')}}>Next</Link> : null}`,
+                    '      </nav>',
+                ]
+                : []),
+            '    </main>',
+            `  )${semi}`,
+            '}',
+            '',
+        ].join('\n');
+        pagingInfo = { summary: `${page.path} lists ${ep.name}() on the server and ${pagingSummary(paging, 'links')}`, warnings: pagingWarnings(paging) };
+    }
+    else
+        page.after = [
+            `import { ${ep.name} } from ${q}${from}${q}${semi}`,
+            '',
+            // Without route parameters Next.js would render the page once at build time,
+            // calling the API then (and failing the build when it is not reachable).
+            ...(params.length ? [] : ['// Rendered on each request: the data comes from the API.', `export const dynamic = ${q}force-dynamic${q}${semi}`, '']),
+            `export default async function ${comp}(${sigParams}) {`,
+            ...(params.length ? [`  const { ${params.join(', ')} } = await params${semi}`] : []),
+            `  const ${dataVar} = await ${ep.name}(${callArgs})${semi}`,
+            '  return (',
+            '    <main>',
+            `      <h1>${title}</h1>`,
+            ...render,
+            '    </main>',
+            `  )${semi}`,
+            '}',
+            '',
+        ].join('\n');
     // Next 14 passes params directly, not as a promise.
-    const pkg = readText(join(root, 'package.json')) ?? '';
-    const nextMajor = Number(/"next"\s*:\s*"[^\d]*(\d+)/.exec(pkg)?.[1] ?? 15);
-    if (nextMajor < 15 && params.length)
+    const nextMajor = major;
+    if (!pagingInfo && nextMajor < 15 && params.length)
         page.after = page.after.replace(`params: Promise<{`, 'params: {').replace(/ }> }\) \{/, ' } }) {').replace(`= await params${semi}`, `= params${semi}`);
     const folder = posix.dirname(page.path);
     const ext = page.path.endsWith('.tsx') ? 'tsx' : 'jsx';
@@ -571,8 +1101,8 @@ async function nextScreen(root, adapter, map, opts) {
     for (const [f, t] of extra)
         if (!exists(join(root, f)))
             files.set(f, t);
-    const summary = [...route.summary, `${page.path} awaits ${ep.name}() on the server and renders the result`, `Create ${folder}/loading.${ext} and ${folder}/error.${ext} (loading state, and an error with retry)`];
-    return buildChangeSet(root, 'screen add', { files, summary, warnings: route.warnings, generated: [] });
+    const summary = [...route.summary, pagingInfo?.summary ?? `${page.path} awaits ${ep.name}() on the server and renders the result`, `Create ${folder}/loading.${ext} and ${folder}/error.${ext} (loading state, and an error with retry)`];
+    return buildChangeSet(root, 'screen add', { files, summary, warnings: [...route.warnings, ...(pagingInfo?.warnings ?? [])], generated: [] });
 }
 export async function planScreenAdd(root, adapter, opts) {
     const { map } = await loadMap(root, adapter, loadConfig(root).conventions);