codz-cli 0.1.3 → 0.1.8

package/dist/skills/paging.js

@@ -0,0 +1,185 @@
+// screen add --paginate --search: which of an endpoint's parameters ask for a
+// page, a page size and a search term, in any of the four languages. The UI
+// for each framework is written next to its normal list screen; this only
+// reads the endpoint and decides what the screen can do.
+import { ToolError } from "../core/types.js";
+export const PAGE_SIZE = 20;
+const PAGE = /^(page|pageNumber|pageNo|pageIndex|p)$/i;
+const OFFSET = /^(offset|skip|start|from)$/i;
+const SIZE = /^(limit|pageSize|perPage|per_page|page_size|size|count|take|first)$/i;
+const SEARCH = /^(q|query|search|searchTerm|search_term|term|keyword|keywords|text|filter)$/i;
+/** TS parameters, with the keys of an options object ({ page?: number; search?: string }) flattened in. */
+export function tsPagingParams(ps) {
+    const out = [];
+    for (const p of ps) {
+        const obj = /^\{([^]*)\}\s*(\|\s*undefined)?$/.exec(p.type.trim());
+        if (obj) {
+            for (const m of obj[1].matchAll(/(\w+)\??\s*:\s*([^;,]+)[;,]?/g))
+                out.push({ name: m[1], type: m[2].trim(), inObject: p.name });
+        }
+        else
+            out.push({ name: p.name, type: p.type });
+    }
+    return out;
+}
+export function detectPaging(params, opts) {
+    const numeric = (t) => /^(number|int|Int|Long|Double|num|Int\?|Long\?|int\?|number \| undefined)/.test(t.replace(/\s/g, ' '));
+    const find = (re, num) => params.find((p) => re.test(p.name) && (!num || numeric(p.type)));
+    const page = find(PAGE, true);
+    const offset = page ? undefined : find(OFFSET, true);
+    const size = find(SIZE, true);
+    const search = find(SEARCH);
+    const paging = {
+        paginate: Boolean(opts.paginate),
+        page: page ? { ...page, mode: 'page' } : offset ? { ...offset, mode: 'offset' } : undefined,
+        search: opts.search ? search : undefined,
+        clientSearch: Boolean(opts.search && !search),
+        searchFields: [],
+    };
+    if (opts.paginate && paging.page)
+        paging.size = size;
+    else
+        paging.size = undefined;
+    if (!opts.paginate)
+        paging.page = undefined;
+    if (opts.paginate && !paging.page) {
+        throw new ToolError('no_paging', 'The endpoint has no page or offset parameter, so the screen cannot ask for the next page.', `Its parameters: ${params.map((p) => p.name).join(', ') || 'none'}. Add a page query parameter to the endpoint (codz api add again with ?page=1 in the URL, or api sync from a spec that has it), or leave out --paginate.`);
+    }
+    if (paging.clientSearch) {
+        const fields = [...new Set([opts.titleField, ...opts.modelStringFields].filter((f) => !!f && opts.modelStringFields.includes(f)))];
+        if (!fields.length)
+            throw new ToolError('no_search', 'The endpoint has no search parameter, and its items have no text fields to search in.', 'Add a q or search query parameter to the endpoint, or leave out --search.');
+        paging.searchFields = fields.slice(0, 4);
+    }
+    return paging;
+}
+/** What the screen does, for the summary line. */
+export function pagingSummary(p, more = 'scroll') {
+    const parts = [];
+    if (p.paginate && p.page)
+        parts.push(`loads ${PAGE_SIZE} at a time (${p.page.name}${p.size ? ` + ${p.size.name}` : ''}), ${more === 'scroll' ? 'more as you scroll' : more === 'button' ? 'a Load more button for the next' : 'Previous and Next links'}`);
+    if (p.search)
+        parts.push(`searches on the server (${p.search.name})`);
+    else if (p.clientSearch)
+        parts.push(`searches the loaded items (${p.searchFields.join(', ')})`);
+    return parts.join('; ');
+}
+export function pagingWarnings(p) {
+    const w = [];
+    if (p.clientSearch)
+        w.push(`The endpoint has no search parameter, so search filters the items already loaded${p.paginate ? ' (not the pages not loaded yet)' : ''}. Add a q or search query parameter to the endpoint to search on the server.`);
+    if (p.paginate && !p.size)
+        w.push(`The endpoint has no page-size parameter, so the screen asks for pages until one comes back empty.`);
+    return w;
+}
+/** TypeScript call arguments: positional ones in order, keys of the options object together. */
+export function tsPagingArgs(ps, p, routeArgs, v) {
+    const out = [];
+    for (const param of ps) {
+        if (routeArgs.has(param.name)) {
+            out.push(routeArgs.get(param.name));
+            continue;
+        }
+        const keys = [];
+        const own = (x) => x && (x.inObject ? x.inObject === param.name : x.name === param.name);
+        const val = (x, expr) => (x && expr && own(x) ? (x.inObject ? keys.push(x.name === expr ? x.name : `${x.name}: ${expr}`) : out.push(expr), true) : false);
+        const handled = [val(p.page, v.page), val(p.size, v.page && p.size ? 'PAGE_SIZE' : undefined), val(p.search, v.search)].some(Boolean);
+        if (keys.length)
+            out.push(`{ ${keys.join(', ')} }`);
+        else if (!handled) {
+            if (!param.optional)
+                return out.join(', '); // the caller already reported missing required arguments
+            out.push('undefined');
+        }
+    }
+    while (out[out.length - 1] === 'undefined')
+        out.pop();
+    return out.join(', ');
+}
+/** Named arguments (Dart `name: v`, Kotlin `name = v`, Swift `name: v`) for page, size and search. */
+export function namedPagingArgs(p, v, sep, sizeExpr = String(PAGE_SIZE)) {
+    const out = [];
+    if (p.page && v.page)
+        out.push(`${p.page.name}${sep}${v.page}`);
+    if (p.size && v.page)
+        out.push(`${p.size.name}${sep}${sizeExpr}`);
+    if (p.search && v.search)
+        out.push(`${p.search.name}${sep}${v.search}`);
+    return out;
+}
+/**
+ * The state and loading for a paged or searchable list: plain React state, or
+ * TanStack Query v5 (useInfiniteQuery / useQuery) when the project uses it.
+ * `call(v)` gives the endpoint call for a page and a search expression.
+ */
+export function tsPagedLogic(p, o) {
+    const first = p.page?.mode === 'offset' ? '0' : '1';
+    const top = p.page && p.size ? [`const PAGE_SIZE = ${PAGE_SIZE};`, ''] : [];
+    const more = (rows) => (p.size ? `${rows}.length === PAGE_SIZE` : `${rows}.length > 0`);
+    const searchExpr = p.search ? `search || undefined` : undefined;
+    const body = [];
+    const react = new Set();
+    const query = [];
+    if (p.search || p.clientSearch) {
+        react.add('useState');
+        body.push(`  const [query, setQuery] = useState('');`);
+    }
+    if (p.search) {
+        react.add('useEffect');
+        body.push(`  const [search, setSearch] = useState('');`, '', '  // Search after a short pause in typing, not on every key.', '  useEffect(() => {', '    const t = setTimeout(() => setSearch(query.trim()), 400);', '    return () => clearTimeout(t);', '  }, [query]);', '');
+    }
+    const keyParts = [`'${o.key}'`, ...o.deps, ...(p.search ? ['search'] : [])].join(', ');
+    if (o.reactQuery && p.paginate) {
+        query.push('useInfiniteQuery');
+        body.push(`  const { data, error, isLoading, ${o.refresh ? 'isFetching, ' : ''}isFetchingNextPage, hasNextPage, fetchNextPage, refetch } = useInfiniteQuery({`, `    queryKey: [${keyParts}, 'pages'],`, `    queryFn: ({ pageParam }) => ${o.call({ page: 'pageParam', search: searchExpr })},`, `    initialPageParam: ${first},`, `    getNextPageParam: (last, all) => (${more('last')} ? ${p.page.mode === 'offset' ? 'all.flat().length' : 'all.length + 1'} : undefined),`, '  });', `  const items: ${o.T}[] = data?.pages.flat() ?? [];`, '  const loading = isLoading || isFetchingNextPage;', ...(o.hasMore ? ['  const hasMore = Boolean(hasNextPage);'] : []), '  const loadMore = () => {', '    if (hasNextPage && !isFetchingNextPage) fetchNextPage();', '  };', '  const retry = () => refetch();', ...(o.refresh ? ['  const refresh = () => refetch();', '  const refreshing = isFetching && !isLoading && !isFetchingNextPage;'] : []));
+    }
+    else if (o.reactQuery) {
+        query.push('useQuery');
+        body.push(`  const { data, error, isLoading: loading, ${o.refresh ? 'isFetching, ' : ''}refetch } = useQuery({`, `    queryKey: [${keyParts}],`, `    queryFn: () => ${o.call({ search: searchExpr })},`, '  });', `  const items: ${o.T}[] = data ?? [];`, '  const retry = () => refetch();', ...(o.refresh ? ['  const refresh = () => refetch();', '  const refreshing = isFetching && !loading;'] : []));
+    }
+    else {
+        react.add('useState');
+        react.add('useEffect');
+        react.add('useRef');
+        body.push(`  const [items, setItems] = useState<${o.T}[]>([]);`, ...(p.paginate ? [`  const [hasMore, setHasMore] = useState(true);`] : []), ...(p.paginate && p.page.mode === 'page' ? [`  const [page, setPage] = useState(${first});`] : []), '  const [loading, setLoading] = useState(true);', ...(o.refresh ? ['  const [refreshing, setRefreshing] = useState(false);'] : []), '  const [error, setError] = useState<unknown>(null);', '  // Only the latest request counts: a new search or refresh replaces one still loading.', '  const request = useRef(0);', '', `  /** Loads ${p.paginate ? 'the first page again (reset) or the next one' : 'the list'}. */`, `  async function load(${p.paginate ? 'reset: boolean' : ''}) {`, '    const id = ++request.current;', '    setLoading(true);', '    setError(null);', '    try {', ...(p.paginate ? [`      const next = reset ? ${first} : ${p.page.mode === 'offset' ? 'items.length' : 'page + 1'};`] : []), `      const rows = await ${o.call({ page: p.paginate ? 'next' : undefined, search: searchExpr })};`, '      if (id !== request.current) return;', ...(p.paginate ? ['      setItems((prev) => (reset ? rows : [...prev, ...rows]));', `      setHasMore(${more('rows')});`, ...(p.page.mode === 'page' ? ['      setPage(next);'] : [])] : ['      setItems(rows);']), '    } catch (e) {', '      if (id === request.current) setError(e);', '    } finally {', '      if (id === request.current) {', '        setLoading(false);', ...(o.refresh ? ['        setRefreshing(false);'] : []), '      }', '    }', '  }', '', '  useEffect(() => {', `    load(${p.paginate ? 'true' : ''});`, '    // eslint-disable-next-line react-hooks/exhaustive-deps', `  }, [${[...o.deps, ...(p.search ? ['search'] : [])].join(', ')}]);`, '', ...(p.paginate ? ['  const loadMore = () => {', '    if (hasMore && !loading && !error) load(false);', '  };'] : []), `  const retry = () => load(${p.paginate ? 'items.length === 0' : ''});`, ...(o.refresh ? ['  const refresh = () => {', '    setRefreshing(true);', `    load(${p.paginate ? 'true' : ''});`, '  };'] : []));
+    }
+    if (p.clientSearch) {
+        body.push('', '  const needle = query.trim().toLowerCase();', `  const shown = needle ? items.filter((item) => [${p.searchFields.map((f) => o.access('item', f)).join(', ')}].some((v) => String(v ?? '').toLowerCase().includes(needle))) : items;`);
+    }
+    else
+        body.push('  const shown = items;');
+    return { imports: { react: [...react], query }, top, body };
+}
+// ---------- Dart ----------
+/** Dart call arguments: positional in order (null for unused optional ones), named as name: value. */
+export function dartPagingCall(args, p, route, v, sizeExpr) {
+    const value = (name) => {
+        if (route.has(name))
+            return route.get(name);
+        if (p.page && v.page && p.page.name === name)
+            return v.page;
+        if (p.size && v.page && p.size.name === name)
+            return sizeExpr;
+        if (p.search && v.search && p.search.name === name)
+            return v.search;
+        return undefined;
+    };
+    const positional = [];
+    const named = [];
+    for (const a of args) {
+        const val = value(a.name);
+        if (a.named) {
+            if (val !== undefined)
+                named.push(`${a.name}: ${val}`);
+        }
+        else
+            positional.push(val ?? 'null');
+    }
+    while (positional.length && positional[positional.length - 1] === 'null' && !args.filter((a) => !a.named)[positional.length - 1]?.required)
+        positional.pop();
+    return [...positional, ...named].join(', ');
+}
+/** Dart: does any of these String fields of `item` contain `needle` (already lower-case)? */
+export function dartSearchMatch(fields, item, needle, prop) {
+    return `[${fields.map((f) => `${item}.${prop(f.name)}${f.nullable ? " ?? ''" : ''}`).join(', ')}].any((v) => v.toLowerCase().contains(${needle}))`;
+}

package/dist/skills/reactNativeUi.js

@@ -19,6 +19,8 @@ import { camel, kebab, pascal, words } from "../input/naming.js";
 import { findDeclaration } from "./apiEdit.js";
 import { responseShape, titleField } from "./screen.js";
 import { reactPrefill } from "./prefill.js";
+import { detectPaging, pagingSummary, pagingWarnings, tsPagedLogic, tsPagingArgs, tsPagingParams } from "./paging.js";
+import { queryMajor } from "./reactUi.js";
 const IDENT = /^[A-Za-z_$][\w$]*$/;
 function routeParamsOf(path) {
     return [...(path ?? '').matchAll(/[:{[]([\w-]+)[\]}]?/g)].map((m) => camel(m[1]));
@@ -183,6 +185,76 @@ export function planRnScreen(root, map, opts) {
     const fromApi = importPath(p.file, barrel ?? ep.file, c).replace(/\.tsx?$/, '');
     const T = shape.raw || 'unknown';
     const access = (v, f) => (IDENT.test(f) ? `${v}.${f}` : `${v}['${f}']`);
+    if (opts.paginate || opts.search) {
+        if (!shape.list)
+            throw new ToolError('screen_not_list', `${ep.name}() returns one ${T}, 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 item = shape.model?.name ?? T.replace(/\[\]$/, '');
+        const logic = tsPagedLogic(paging, { T: item, call: (v) => `${ep.name}(${tsPagingArgs(ps, paging, routeArgs, v)})`, key: kebab(ep.name), deps: params, reactQuery: c.dataFetching === 'react-query' && queryMajor(root) >= 5, refresh: true, hasMore: false, access });
+        const searchable = paging.search || paging.clientSearch;
+        const rn = ['ActivityIndicator', 'Button', 'FlatList', 'StyleSheet', 'Text', ...(searchable ? ['TextInput'] : []), 'View'];
+        const paged = [
+            ...(logic.imports.react.length ? [`import { ${logic.imports.react.sort().join(', ')} } from 'react';`] : []),
+            `import { ${rn.join(', ')} } from 'react-native';`,
+            ...(logic.imports.query.length ? [`import { ${logic.imports.query.join(', ')} } from '@tanstack/react-query';`] : []),
+            ...pc.imports,
+            `import { ${ep.name} } from '${fromApi}';`,
+            ...(shape.model ? [`import type { ${shape.model.name} } from '${importPath(p.file, shape.model.file, c).replace(/\.tsx?$/, '')}';`] : []),
+            '',
+            ...logic.top,
+            `export default function ${n.component}(${pc.signature}) {`,
+            ...pc.lines,
+            ...logic.body,
+            '',
+            '  return (',
+            '    <FlatList',
+            '      data={shown}',
+            `      keyExtractor={(item, index) => ${idf ? `String(${access('item', idf)})` : 'String(index)'}}`,
+            '      refreshing={refreshing}',
+            '      onRefresh={refresh}',
+            ...(paging.paginate ? ['      onEndReached={loadMore}', '      onEndReachedThreshold={0.5}'] : []),
+            ...(searchable ? ['      keyboardShouldPersistTaps="handled"', '      ListHeaderComponent={<TextInput style={styles.search} placeholder="Search" value={query} onChangeText={setQuery} autoCorrect={false} clearButtonMode="while-editing" />}'] : []),
+            '      ListEmptyComponent={',
+            '        loading ? (',
+            '          <ActivityIndicator style={styles.footer} />',
+            '        ) : error ? (',
+            '          <View style={styles.center}>',
+            '            <Text style={styles.error}>{error instanceof Error ? error.message : String(error)}</Text>',
+            '            <Button title="Retry" onPress={retry} />',
+            '          </View>',
+            '        ) : (',
+            `          <Text style={styles.empty}>${searchable ? `{query.trim() ? 'No matches.' : 'Nothing here yet.'}` : 'Nothing here yet.'}</Text>`,
+            '        )',
+            '      }',
+            ...(paging.paginate
+                ? ['      ListFooterComponent={', '        items.length > 0 && loading ? <ActivityIndicator style={styles.footer} /> : items.length > 0 && error ? <Button title="Retry" onPress={retry} /> : null', '      }']
+                : []),
+            `      renderItem={({ item }) => <Text style={styles.row}>{${tf ? `String(${access('item', tf)})` : 'JSON.stringify(item)'}}</Text>}`,
+            '    />',
+            '  );',
+            '}',
+            '',
+            'const styles = StyleSheet.create({',
+            "  center: { alignItems: 'center', justifyContent: 'center', padding: 16 },",
+            "  error: { marginBottom: 12, textAlign: 'center' },",
+            "  empty: { padding: 16, textAlign: 'center' },",
+            "  footer: { padding: 16 },",
+            ...(searchable ? ["  search: { margin: 12, padding: 10, borderWidth: StyleSheet.hairlineWidth, borderColor: '#999', borderRadius: 8 },"] : []),
+            "  row: { padding: 16, borderBottomWidth: StyleSheet.hairlineWidth, borderBottomColor: '#ccc' },",
+            '});',
+            '',
+        ].join('\n');
+        const files = new Map([[p.file, paged]]);
+        const summary = [`Create ${p.file}: ${n.component} lists ${ep.name}() and ${pagingSummary(paging)}`];
+        if (p.navigator) {
+            files.set(p.navigator.file, register(p.navigator, p.file, opts, map));
+            summary.push(`Update ${p.navigator.file}: add ${n.route} to RootStackParamList and the stack`);
+        }
+        summary.push(navHint(map, opts));
+        return finish(root, 'screen add', files, summary, [...warnings, ...pagingWarnings(paging)]);
+    }
     const dataView = shape.list
         ? [
             '    <FlatList',

package/dist/skills/reactUi.js

@@ -19,6 +19,7 @@ import { camel, kebab, pascal, words } from "../input/naming.js";
 import { findDeclaration } from "./apiEdit.js";
 import { responseShape, titleField } from "./screen.js";
 import { reactPrefill } from "./prefill.js";
+import { detectPaging, pagingSummary, pagingWarnings, tsPagedLogic, tsPagingArgs, tsPagingParams } from "./paging.js";
 const IDENT = /^[A-Za-z_$][\w$]*$/;
 function routeParamsOf(path) {
     return [...(path ?? '').matchAll(/[:{]([\w-]+)\}?/g)].map((m) => camel(m[1]));
@@ -119,6 +120,11 @@ export function planReactRoute(root, map, opts) {
     const page = [...pc.imports, ...(pc.imports.length ? [''] : []), `export default function ${n.component}() {`, ...pc.lines, '  return (', '    <main>', `      <h1>${n.title}${params.length ? ` {${params[0]}}` : ''}</h1>`, '    </main>', '  );', '}', ''].join('\n');
     return finish(root, 'route add', p, page, map, opts, [`Create ${p.file}: ${n.component}`], []);
 }
+/** The installed TanStack Query major version (5 when it cannot be read). */
+export function queryMajor(root) {
+    const pkg = readText(join(root, 'package.json')) ?? '';
+    return Number(/"@tanstack\/react-query"\s*:\s*"[^\d]*(\d+)/.exec(pkg)?.[1] ?? 5);
+}
 function findEp(map, name) {
     const ep = map.endpoints.find((e) => e.name === name) ?? map.endpoints.find((e) => e.name.toLowerCase() === name.toLowerCase());
     if (!ep)
@@ -174,6 +180,55 @@ export function planReactScreen(root, map, opts) {
     const c = map.conventions;
     const T = shape.raw || 'unknown';
     const access = (v, f) => (IDENT.test(f) ? `${v}.${f}` : `${v}['${f}']`);
+    if (opts.paginate || opts.search) {
+        if (!shape.list)
+            throw new ToolError('screen_not_list', `${ep.name}() returns one ${T}, 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 item = shape.model?.name ?? T.replace(/\[\]$/, '');
+        const logic = tsPagedLogic(paging, { T: item, call: (v) => `${ep.name}(${tsPagingArgs(ps, paging, routeArgs, v)})`, key: kebab(ep.name), deps: params, reactQuery: c.dataFetching === 'react-query' && queryMajor(root) >= 5, refresh: false, hasMore: true, access });
+        const searchable = paging.search || paging.clientSearch;
+        const pagedPage = [
+            ...(logic.imports.react.length ? [`import { ${logic.imports.react.sort().join(', ')} } from 'react';`] : []),
+            ...(logic.imports.query.length ? [`import { ${logic.imports.query.join(', ')} } from '@tanstack/react-query';`] : []),
+            ...pc.imports,
+            `import { ${ep.name} } from '${apiImport(root, map, p.file, ep)}';`,
+            ...(shape.model ? [`import type { ${shape.model.name} } from '${importPath(p.file, shape.model.file, c).replace(/\.tsx?$/, '')}';`] : []),
+            '',
+            ...logic.top,
+            `export default function ${n.component}() {`,
+            ...pc.lines,
+            ...logic.body,
+            '',
+            '  return (',
+            '    <main>',
+            `      <h1>${n.title}</h1>`,
+            ...(searchable ? ['      <input type="search" placeholder="Search" aria-label="Search" value={query} onChange={(e) => setQuery(e.target.value)} />'] : []),
+            '      {error ? (',
+            '        <div role="alert">',
+            '          <p>{error instanceof Error ? error.message : String(error)}</p>',
+            '          <button type="button" onClick={() => retry()}>Retry</button>',
+            '        </div>',
+            '      ) : null}',
+            '      {shown.length === 0 ? (',
+            `        loading || error ? null : <p>${searchable ? `{query.trim() ? 'No matches.' : 'Nothing here yet.'}` : 'Nothing here yet.'}</p>`,
+            '      ) : (',
+            '        <ul>',
+            `          {shown.map((${idf ? 'item' : 'item, index'}) => (`,
+            `            <li key={${idf ? `String(${access('item', idf)})` : 'index'}}>{${tf ? `String(${access('item', tf)})` : 'JSON.stringify(item)'}}</li>`,
+            '          ))}',
+            '        </ul>',
+            '      )}',
+            '      {loading ? <p>Loading…</p> : null}',
+            ...(paging.paginate ? ['      {hasMore && !loading && !error ? (', '        <button type="button" onClick={loadMore}>Load more</button>', '      ) : null}'] : []),
+            '    </main>',
+            '  );',
+            '}',
+            '',
+        ].join('\n');
+        return finish(root, 'screen add', p, pagedPage, map, opts, [`Create ${p.file}: ${n.component} lists ${ep.name}() and ${pagingSummary(paging, 'button')}`], pagingWarnings(paging));
+    }
     const view = shape.list
         ? [
             '      {data.length === 0 ? (',