@krizaka/ui 2.10.0 → 3.1.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/form/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: krizaka-form
+description: Forms in a Krizaka app (Next.js or Expo) with @krizaka/ui/form and @krizaka/ui/native/form — createKrizakaForm({ schema, defaultValues }) on a zod 4 schema shared with the server, typed fields (TextField, TextArea, Checkbox, Switch, RadioGroup, Select, Combobox, DateField, TagInput, FileUpload, Money, Slider), Submit, FormError, FieldArray, Watch, async checks (username availability), server Problem Details mapped onto fields, useFormWithAction for Server Actions. Use it instead of a hand-made <form>, useState per field, react-hook-form or a direct @tanstack/react-form import.
+---
+
+# @krizaka/ui/form · @krizaka/ui/native/form
+
+## Rules
+
+1. A form = a schema (zod 4) + defaults, defined once beside the API contract (`packages/core` of a product):
+   `const signUp = createKrizakaForm({ schema, defaultValues })`. Web imports from `@krizaka/ui/form`, Expo from
+   `@krizaka/ui/native/form` — same definition, same `useForm`.
+2. Never import `@tanstack/react-form`. Need a control the package lacks? `form.Field name="x">{(f) => …}` gives value,
+   setter, error and ids (`useKrizakaField`).
+3. Words are keys: name refusals in the schema (`z.string().regex(re, "signUp.username.format")`), give the words in
+   `messages/*.json`, pass `i18n: { t, locale }`. Generic keys are `form.errors.*` (`required`, `tooShort {minimum}`,
+   `tooLong {maximum}`, `invalidEmail`, `invalidUrl`, `invalidDate`, `invalidNumber`, `tooFew`, `tooMany`, `invalid`);
+   the whole-form refusals are `apiErrors.<code>` (as `KrizakaApiError.messageKey()`).
+4. Send with a mutation (`onSubmit: (v) => mutation.mutateAsync(v)`) or a Server Action (`form.useFormWithAction(action)`,
+   the action answers `{ ok: true, data } | { ok: false, problem }`, re-validating with `validateForm(schema, input)` of
+   `@krizaka/ui/form/server`). A thrown `KrizakaApiError` lands on its `fields`; `codeFields: { UNDERAGE: "dateOfBirth" }`
+   puts a code under its field; the rest shows in `<form.FormError />`.
+5. Never disable Submit for an invalid form. Errors show once a field is left (or on submit) and go as soon as fixed.
+
+## Recipes
+
+```tsx
+const form = signUp.useForm({ i18n: { t }, codeFields: { USERNAME_RESERVED: "username" }, onSubmit: (v) => register.mutateAsync(v) });
+<form.Form aria-label={t("signUp.title")}>
+  <form.TextField name="email" label={t("signUp.email")} type="email" autoComplete="email" />
+  <form.TextField name="username" label={t("signUp.username")} availableHint={t("signUp.free")}
+    validateAsync={async (u, signal) => ((await checkUsername(u, signal)).available ? null : { key: "signUp.username.taken" })} />
+  <form.DateField name="dateOfBirth" label={t("signUp.birth")} entry="parts" autoComplete="bday" />   {/* 18+: z.iso.date().refine((d) => d <= latestBirthDate(18), "form.errors.UNDERAGE") */}
+  <form.Checkbox name="acceptTerms" label={t("signUp.terms")} />
+  <form.FormError />
+  <form.Submit>{t("signUp.submit")}</form.Submit>
+</form.Form>
+```
+
+- Amounts: `form.Money name="amount" currency="EUR"` stores integer cents (`z.number().int()`).
+- Lists: `<form.FieldArray name="links">{(a) => a.items.map((_, i) => <form.TextField name={`links[${i}].url`} … />)}</form.FieldArray>`.
+- Conditional parts: `<form.Watch name="audience">{(v) => v === "subscribers" ? <form.Money name="price" … /> : null}</form.Watch>`.
+- Native: `<form.Form scroll>` makes the form the screen's scrolling content above the keyboard; the return key walks the
+  text fields and the last one sends; `<form.Submit label=… brand="orochia" />` turns the product's mark while sending.

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`.