@sito/dashboard-app 0.0.53 → 0.0.55

package/README.md

@@ -2,6 +2,24 @@
 
 `@sito/dashboard-app` is a React 18 component and utilities library for building Sito-style admin dashboards, CRUD screens, and internal tools. It packages UI components, hooks, providers, typed API helpers, and styles in a single npm package.
 
+## Documentation scope and source of truth
+
+Use documentation by target package:
+
+| Document                | Primary audience              | Source of truth for                                     |
+| ----------------------- | ----------------------------- | ------------------------------------------------------- |
+| `README.md` (this file) | Consumer apps and maintainers | Public usage of `@sito/dashboard-app`                   |
+| `AGENTS.md`             | AI agents and maintainers     | Implementation rules for `@sito/dashboard-app`          |
+| `.sito/*.md`            | Internal team and agents      | Upstream reference notes for `@sito/dashboard` behavior |
+
+Important:
+
+- `.sito/*.md` is not the canonical integration guide for this package.
+- For `@sito/dashboard-app` provider setup, use `ConfigProvider -> ManagerProvider -> AuthProvider -> NotificationProvider -> DrawerMenuProvider` (`NavbarProvider` when needed).
+- `IconButton` differs by package:
+  - `@sito/dashboard`: `icon` accepts a React node.
+  - `@sito/dashboard-app`: `icon` expects `IconDefinition` (FontAwesome wrapper export).
+
 ## Installation
 
 ```bash
@@ -18,16 +36,17 @@ pnpm add @sito/dashboard-app
 - React `18.3.1`
 - React DOM `18.3.1`
 - `@tanstack/react-query` `5.83.0`
+- `@supabase/supabase-js` `2.100.0` (optional; only if using Supabase backend)
 - `react-hook-form` `7.61.1`
-- `@sito/dashboard` `^0.0.72`
-- Font Awesome + Emotion peers defined in `package.json`
+- `@sito/dashboard` `^0.0.74`
+- Font Awesome peers defined in `package.json`
 
 Install all peers in consumer apps:
 
 ```bash
 npm install \
   react@18.3.1 react-dom@18.3.1 \
-  @sito/dashboard@^0.0.72 \
+  @sito/dashboard@^0.0.74 \
   @tanstack/react-query@5.83.0 \
   react-hook-form@7.61.1 \
   @fortawesome/fontawesome-svg-core@7.0.0 \
@@ -37,6 +56,12 @@ npm install \
   @fortawesome/react-fontawesome@0.2.3
 ```
 
+If your app uses the Supabase backend:
+
+```bash
+npm install @supabase/supabase-js@2.100.0
+```
+
 ## Core exports
 
 - Layout and navigation: `Page`, `Navbar`, `Drawer`, `TabsLayout`, `PrettyGrid`, `ToTop`
@@ -44,7 +69,7 @@ npm install \
 - Dialogs and forms: `Dialog`, `FormDialog`, `ImportDialog`, form inputs
 - Feedback: `Notification`, `Loading`, `Empty`, `Error`, `Onboarding`
 - Hooks: `useFormDialog` (generic state/entity), `usePostDialog`, `usePutDialog`, `useImportDialog`, `useDeleteDialog`, `usePostForm`, `useDeleteAction`, `useNavbar`, and more — all action hooks ship with default `sticky`, `multiple`, `id`, `icon`, and `tooltip` values so only `onClick` is required
-- Providers and utilities: `ConfigProvider`, `ManagerProvider`, `AuthProvider`, `NotificationProvider`, `DrawerMenuProvider`, `NavbarProvider`, DTOs, API clients
+- Providers and utilities: `ConfigProvider`, `ManagerProvider`, `SupabaseManagerProvider`, `AuthProvider`, `SupabaseAuthProvider`, `NotificationProvider`, `DrawerMenuProvider`, `NavbarProvider`, DTOs, API clients (`BaseClient`, `IndexedDBClient`, `SupabaseDataClient`), and `useSupabase`
 
 ## Component usage patterns
 
@@ -232,6 +257,101 @@ Main optional props:
 - `scrollOnClick?: boolean` (default `true`)
 - `onClick?: () => void`
 
+## Dialog hook migration (`v0.0.54`)
+
+`v0.0.54` removes the legacy entity-coupled `useFormDialog` contract.
+
+### Breaking changes
+
+- `useFormDialog` is now core lifecycle only (`mode: "state" | "entity"`).
+- Legacy props were removed from `useFormDialog`: `mutationFn`, `queryKey`, `getFunction`, `dtoToForm`, `formToDto`.
+- Deprecated aliases were removed:
+  - `useFormDialogLegacy`
+  - `useEntityFormDialog`
+
+### What to use now
+
+- Local/state-only dialog (filters/settings): `useFormDialog`
+- Create flow (POST): `usePostDialog`
+- Edit flow (PUT + get by id): `usePutDialog`
+
+### Before -> After
+
+```tsx
+// BEFORE (no longer supported in v0.0.54+)
+const createDialog = useFormDialog<
+  ProductDto,
+  CreateProductDto,
+  ProductDto,
+  ProductForm
+>({
+  title: "Create product",
+  defaultValues: { name: "", price: 0 },
+  mutationFn: (dto) => api.products.insert(dto),
+  formToDto: (form) => ({ name: form.name, price: form.price }),
+  queryKey: ["products"],
+});
+
+// AFTER
+const createDialog = usePostDialog<CreateProductDto, ProductDto, ProductForm>({
+  title: "Create product",
+  defaultValues: { name: "", price: 0 },
+  mutationFn: (dto) => api.products.insert(dto),
+  mapOut: (form) => ({ name: form.name, price: form.price }),
+  queryKey: ["products"],
+});
+```
+
+```tsx
+// BEFORE (no longer supported in v0.0.54+)
+const editDialog = useFormDialog<
+  ProductDto,
+  UpdateProductDto,
+  ProductDto,
+  ProductForm
+>({
+  title: "Edit product",
+  defaultValues: { name: "", price: 0 },
+  getFunction: (id) => api.products.getById(id),
+  dtoToForm: (dto) => ({ name: dto.name, price: dto.price }),
+  mutationFn: (dto) => api.products.update(dto),
+  formToDto: (form) => ({ id: 0, ...form }),
+  queryKey: ["products"],
+});
+
+// AFTER
+const editDialog = usePutDialog<
+  ProductDto,
+  UpdateProductDto,
+  ProductDto,
+  ProductForm
+>({
+  title: "Edit product",
+  defaultValues: { name: "", price: 0 },
+  getFunction: (id) => api.products.getById(id),
+  dtoToForm: (dto) => ({ name: dto.name, price: dto.price }),
+  mutationFn: (dto) => api.products.update(dto),
+  mapOut: (form, dto) => ({ id: dto?.id ?? 0, ...form }),
+  queryKey: ["products"],
+});
+```
+
+### Core `useFormDialog` error handling
+
+`useFormDialog` supports a core `onError` callback for failures in submit/apply/clear paths.
+
+```tsx
+const filtersDialog = useFormDialog<ProductFilters>({
+  mode: "state",
+  title: "Filters",
+  defaultValues: { search: "", minPrice: 0 },
+  onSubmit: async (values) => setTableFilters(values),
+  onError: (error, { phase, values }) => {
+    console.error("Dialog error", { error, phase, values });
+  },
+});
+```
+
 ## Initial setup example
 
 Wrap your app with providers in this order to enable routing integration, React Query, auth, notifications, and drawer/navbar state.
@@ -319,6 +439,132 @@ Notes:
 - `NavbarProvider` is required when using `Navbar` or `useNavbar`; otherwise it can be omitted.
 - If you customize auth storage keys in `AuthProvider`, pass the same keys to `IManager`/`BaseClient` auth config.
 
+## Supabase setup (optional backend)
+
+The library does not read `.env` values directly. The consumer app must create the Supabase client and pass it to `SupabaseManagerProvider`.
+
+Use frontend-safe keys only:
+
+- `VITE_SUPABASE_URL`
+- `VITE_SUPABASE_ANON_KEY`
+
+Do not expose service-role keys in the browser.
+
+```tsx
+import type { ReactNode } from "react";
+import { createClient } from "@supabase/supabase-js";
+import { Link } from "react-router-dom";
+import {
+  ConfigProvider,
+  SupabaseManagerProvider,
+  SupabaseAuthProvider,
+  NotificationProvider,
+  DrawerMenuProvider,
+  NavbarProvider,
+} from "@sito/dashboard-app";
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+);
+
+function AppProviders({ children }: { children: ReactNode }) {
+  return (
+    <ConfigProvider
+      location={window.location}
+      navigate={() => {}}
+      linkComponent={Link}
+    >
+      <SupabaseManagerProvider supabase={supabase}>
+        <SupabaseAuthProvider>
+          <NotificationProvider>
+            <DrawerMenuProvider>
+              <NavbarProvider>{children}</NavbarProvider>
+            </DrawerMenuProvider>
+          </NotificationProvider>
+        </SupabaseAuthProvider>
+      </SupabaseManagerProvider>
+    </ConfigProvider>
+  );
+}
+```
+
+`useAuth` keeps the same contract with `SupabaseAuthProvider` (`account`, `logUser`, `logoutUser`, `logUserFromLocal`, `isInGuestMode`, `setGuestMode`).
+
+`SupabaseDataClient` follows the same generic surface as `BaseClient` and `IndexedDBClient`, so entity clients can switch backend with minimal UI/hook changes.
+It also supports optional configuration for conventional columns: `idColumn` (default `"id"`), `deletedAtColumn` (default `"deletedAt"`), and `defaultSortColumn`.
+
+### Supabase entity client example
+
+```ts
+import type { SupabaseClient } from "@supabase/supabase-js";
+import {
+  BaseCommonEntityDto,
+  BaseEntityDto,
+  BaseFilterDto,
+  DeleteDto,
+  ImportPreviewDto,
+  SupabaseDataClient,
+} from "@sito/dashboard-app";
+
+interface ProductDto extends BaseEntityDto {
+  name: string;
+  price: number;
+  categoryId?: number;
+}
+
+interface ProductCommonDto extends BaseCommonEntityDto {
+  name: string;
+}
+
+interface CreateProductDto {
+  name: string;
+  price: number;
+  categoryId?: number;
+}
+
+interface UpdateProductDto extends DeleteDto {
+  name?: string;
+  price?: number;
+  categoryId?: number;
+}
+
+interface ProductFilterDto extends BaseFilterDto {
+  categoryId?: number;
+}
+
+interface ProductImportPreviewDto extends ImportPreviewDto {
+  id: number;
+  name: string;
+  price: number;
+}
+
+class ProductsSupabaseClient extends SupabaseDataClient<
+  "products",
+  ProductDto,
+  ProductCommonDto,
+  CreateProductDto,
+  UpdateProductDto,
+  ProductFilterDto,
+  ProductImportPreviewDto
+> {
+  constructor(supabase: SupabaseClient) {
+    super("products", supabase, {
+      defaultSortColumn: "id",
+    });
+  }
+}
+
+const productsClient = new ProductsSupabaseClient(supabase);
+```
+
+### Compatibility and incremental migration
+
+- The REST flow stays intact: existing apps using `ManagerProvider` + `AuthProvider` + `BaseClient` do not need changes.
+- You can migrate entity by entity: move one resource client at a time from `BaseClient` to `SupabaseDataClient`.
+- During migration, mixed data backends are valid (`BaseClient` for some entities, `SupabaseDataClient` for others) as long as each UI flow uses the corresponding client methods.
+- If you switch auth to Supabase, use `SupabaseManagerProvider` + `SupabaseAuthProvider`; if you keep REST auth, continue with `ManagerProvider` + `AuthProvider`.
+
 ## Built-in auth refresh behavior
 
 `APIClient` and `BaseClient` already include refresh/retry behavior for secured requests:
@@ -358,6 +604,7 @@ Notes:
 - `npm run build`: compile TypeScript and build the library
 - `npm run preview`: preview the Vite build locally
 - `npm run lint`: run ESLint
+- `npm run docs:check`: validate docs policy markers, relative links, and docs consistency rules
 - `npm run test`: run unit/component tests once (Vitest)
 - `npm run test:watch`: run tests in watch mode
 - `npm run format`: run Prettier write mode
@@ -453,9 +700,11 @@ Contract and filtering notes:
 - Preferred update contract is `update(value)` (aligned with `BaseClient.update(value)`).
 - Legacy `update(id, value)` remains temporarily supported for backward compatibility.
 - Filtering uses strict equality for regular keys.
-- `deletedAt` also supports boolean filtering:
-  - `deletedAt: true` => deleted rows (`deletedAt` not null/undefined)
-  - `deletedAt: false` => active rows (`deletedAt` null/undefined)
+- `deletedAt` remains a date filter (`Date | null`) for exact-match filtering.
+- Use `softDeleteScope` for trash filters:
+  - `softDeleteScope: "ACTIVE"` => active rows (`deletedAt` null/undefined)
+  - `softDeleteScope: "DELETED"` => deleted rows (`deletedAt` not null/undefined)
+  - `softDeleteScope: "ALL"` => all rows
 
 ## Tests
 
@@ -476,6 +725,7 @@ npm run test:watch
 Current validation stack:
 
 - `npm run lint`
+- `npm run docs:check`
 - `npm run test`
 - `npm run build`
 - Storybook/manual behavior checks (optional visual validation)
@@ -498,8 +748,8 @@ npm run format
 
 CI is available through GitHub Actions:
 
-- `.github/workflows/ci.yml`: runs `lint + test + build` on `push` and `pull_request`
-- `.github/workflows/lint.yml`: runs lint checks on `push` and `pull_request`
+- `.github/workflows/ci.yml`: runs `lint + docs:check + test + build` on `push` and `pull_request`
+- `.github/workflows/lint.yml`: runs `lint + docs:check` on `push` and `pull_request`
 
 Package release/publish is still handled manually.