@krizaka/ui 2.10.0 → 3.0.0

package/skills/data-table/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: krizaka-data-table
+description: Tables of records in a Krizaka web app with @krizaka/ui/data-table v2 (TanStack Table v9 behind the Krizaka facade) — sorting, text/facet/range filters, grouping, detail panels and trees, pagination, selection, column visibility, pinning, resizing, CSV export, server mode with @krizaka/query, windowing of long lists, cards on a phone. Use it before writing any table, list of records, admin grid or <table> in a Krizaka product.
+---
+
+# @krizaka/ui/data-table (v2)
+
+## Rules
+
+1. Import from `@krizaka/ui/data-table` — **never `@tanstack/react-table`** (ESLint `krizaka/no-direct-tanstack-import`,
+   dependency-cruiser). The escape hatch is `useDataTable().table` (the TanStack instance), inside the table's `toolbar`.
+2. **No `<table>` written by hand** in an app for records (ratchet `krizaka/no-local-table-or-form`).
+3. `rows` and `columns` are **stable**: module scope, state, a query's `data`, or `useMemo`. Never `rows={data ?? []}` —
+   use a module constant (`const NONE: Row[] = []`).
+4. Words are props, passed translated: `header` of each column, `caption`, `labels` (`dataTableLabels` lists them).
+5. A server list: `manual={{ sorting: true, filtering: true, pagination: true }}`, `rowCount`, `onStateChange` → the
+   `DataTableQuery` in state (or the URL) → the query key (`defineKeys`) → `krizakaFetch`. `placeholderData:
+   keepPreviousData` keeps the page while the next loads; `meta: { list: true }` keeps errors in the table.
+
+## Columns
+
+```ts
+const columns: DataTableColumn<Job>[] = [
+  { id: "name", header: t.jobs.name, sortable: true, card: "title", filter: "text" },
+  { id: "status", header: t.jobs.status, filter: "facet", groupable: true, options: statusOptions, cell: (j) => <Badge>…</Badge> },
+  { id: "cost", header: t.jobs.cost, align: "end", filter: "range", value: (j) => j.cents, aggregate: (rows) => sum(rows) },
+];
+```
+
+`value` is what sorts, filters, groups and exports (default `row[id]`); `cell` is what shows.
+
+## Recipes
+
+```tsx
+// Client table with filters, columns menu, export and pages
+<DataTable caption={t.jobs.title} rows={jobs} columns={columns} getRowId={(j) => j.id} rowLabel={(j) => j.name}
+  selectable onSelectedChange={setSelected} defaultPageSize={25} pageSizeOptions={[25, 50, 100]}
+  toolbar={<><DataTableFilters /><DataTableColumnsMenu /><DataTableExport filename="jobs.csv" /></>}
+  labels={t.dataTable} />
+
+// Server table
+const [query, setQuery] = useState<DataTableQuery>({ sort: null, filters: {}, page: 1, pageSize: 25 });
+const { data, isPending, error } = useQuery({ ...jobsQuery(query), placeholderData: keepPreviousData });
+<DataTable rows={data?.rows ?? NONE} rowCount={data?.total} manual={{ sorting: true, filtering: true, pagination: true }}
+  defaultPageSize={25} onStateChange={setQuery} loading={isPending} error={error && <ErrorState … />} … />
+```
+
+Also: `groupBy` / `defaultGroupBy`, `renderDetail` (a panel under a row), `getSubRows` (a tree), `pinning={{ start:
+["name"], end: ["actions"] }}`, `resizing`, `columnVisibility`, `virtualized={{ height: 480 }}` (thousands of rows
+loaded at once), `layout="cards"` / `auto` (cards below 36rem), `density="compact"`, `loading` / `empty` / `error`.
+
+## Accessibility (built in)
+
+Caption, `scope="col"`, `aria-sort`, `aria-expanded` on expand buttons, focusable resize separators (← →), a named
+filters group with an announced count, `aria-busy` while loading, `role="alert"` on errors, `aria-rowcount` /
+`aria-rowindex` when windowed. Give `caption` and `rowLabel` real words.

package/skills/native-list/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: krizaka-native-list
+description: Lists in a Krizaka React Native / Expo app with @krizaka/ui/native/list — List on FlashList v2 (separators, skeleton rows, empty/error states, pull to refresh, spinner for the next page) and useInfiniteList (useInfiniteQuery of @krizaka/query wired to onEndReached). Use it instead of FlatList, ScrollView+map or a direct @shopify/flash-list import.
+---
+
+# @krizaka/ui/native/list
+
+## Rules
+
+1. Import `List` and `useInfiniteList` from `@krizaka/ui/native/list` — not `FlatList`, not `@shopify/flash-list`
+   directly. The app installs the optional peers: `@shopify/flash-list` (v2) and `@krizaka/query`.
+2. Server data goes through `@krizaka/query` (never `@tanstack/react-query`): one `KrizakaQueryProvider` at the root.
+3. `keyExtractor` returns an id; `renderItem` stays light (views are recycled); words are passed translated.
+
+## Recipes
+
+```tsx
+// A paginated API
+const { listProps, error } = useInfiniteList({
+  queryKey: notificationKeys.list(),
+  queryFn: ({ pageParam, signal }) => krizakaFetch("/api/notifications", { schema: NotificationPage, query: { cursor: pageParam }, signal }),
+  initialPageParam: null as string | null,
+  getNextPageParam: (last) => last.nextCursor,
+  getItems: (page) => page.items,
+});
+return (
+  <List label={t.notifications.title} {...listProps} keyExtractor={(n) => n.id} separator="inset"
+    renderItem={(n) => <NotificationRow notification={n} />}
+    error={error ? <ErrorState title={t.errors.load} action={…} /> : undefined}
+    empty={{ title: t.notifications.empty, description: t.notifications.emptyHint }}
+    loadingMoreLabel={t.common.loadingMore} />
+);
+
+// Static data
+<List label={t.settings.devices} data={devices} keyExtractor={(d) => d.id} renderItem={(d) => <DeviceRow device={d} />} />
+```
+
+`listProps` = `{ data, loading, refreshing, onRefresh, onEndReached, loadingMore }`: the next page is asked once at a
+time and never past the last; pull to refresh refetches every loaded page.

package/skills/virtual/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: krizaka-virtual
+description: Long lists, feeds and galleries in a Krizaka web app with @krizaka/ui/virtual (TanStack Virtual v3 behind the Krizaka facade) — VirtualList (own region or window scroll, measured items), VirtualGrid (responsive columns), infinite loading with @krizaka/query. Use it before rendering more than ~100 items, an infinite feed or a gallery.
+---
+
+# @krizaka/ui/virtual
+
+## Rules
+
+1. Import from `@krizaka/ui/virtual` — **never `@tanstack/react-virtual`**, `react-window` or `react-virtualized`.
+   The raw hooks come through the facade: `useVirtualizer`, `useWindowVirtualizer`.
+2. Records compared on columns → `@krizaka/ui/data-table` (`virtualized`), not a list. React Native → `@krizaka/ui/native/list`.
+3. Always `getKey` (an id) and a `label` (translated): it names the focusable scrolling region.
+
+## Recipes
+
+```tsx
+// Messages of different heights, in their own region
+<VirtualList items={messages} getKey={(m) => m.id} estimateSize={64} gap={8} height={480} label={t.chat.messages}
+  renderItem={(m) => <MessageBubble message={m} />} />
+
+// A feed that scrolls the page, infinite with @krizaka/query
+const feed = useInfiniteQuery({ ...feedQuery(), meta: { list: true } });
+const posts = useMemo(() => feed.data?.pages.flatMap((p) => p.items) ?? NONE, [feed.data]);
+<VirtualList scroll="window" items={posts} getKey={(p) => p.id} estimateSize={320} label={t.feed.title}
+  onEndReached={() => feed.hasNextPage && !feed.isFetchingNextPage && feed.fetchNextPage()}
+  footer={feed.isFetchingNextPage ? <Spinner label={t.common.loadingMore} /> : null} renderItem={(p) => <Post post={p} />} />
+
+// A gallery: as many columns as fit (or `columns={4}`)
+<VirtualGrid items={videos} getKey={(v) => v.id} estimateRowHeight={260} minItemWidth={220} label={t.explore.videos}
+  renderItem={(v) => <VideoCard video={v} />} />
+```
+
+`ref` gives `scrollToIndex(i, align)` — smooth, or instant under reduced motion. Items are `listitem`s with
+`aria-setsize` / `aria-posinset`.