sonamu 0.10.5 → 0.10.7

package/src/skills/sonamu/frontend.md

@@ -1,915 +0,0 @@
----
-name: sonamu-frontend
-description: Sonamu frontend integration. Auto-generated Service, TanStack Query hooks, useTypeForm/useListParams/useSelection, FileInput, MultiSelect, SonamuProvider (react-components v0.1.8+). Use when calling APIs, building forms, handling file uploads, or managing list/selection states.
----
-
-# Frontend Service
-
-## Quick Reference
-
-### Hooks
-
-| Hook            | Purpose                           | Key Return Values                                |
-| --------------- | --------------------------------- | ------------------------------------------------ |
-| `useTypeForm`   | Form state management (Zod-based) | form, setForm, register, submit, addError, reset |
-| `useListParams` | URL-synced list parameters        | listParams, setListParams, register              |
-| `useSelection`  | Checkbox multi-selection          | selectedKeys, toggle, selectAll, deselectAll     |
-| `useModal`      | Modal state management            | open, modal                                      |
-| `useToast`      | Toast notifications               | toast                                            |
-
-### Components
-
-| Component     | Purpose          | Key Props                                           |
-| ------------- | ---------------- | --------------------------------------------------- |
-| `Input`       | Text input       | value, onValueChange                                |
-| `Textarea`    | Multi-line input | value, onValueChange                                |
-| `Checkbox`    | Checkbox         | value (boolean), onValueChange, label               |
-| `Select`      | Single select    | items, value, onValueChange, placeholder, clearable |
-| `MultiSelect` | Multi-select     | options, value (array), onValueChange, maxCount     |
-| `EnumSelect`  | Enum select      | enum, labels, value, onValueChange                  |
-| `FileInput`   | File upload      | uploadMode, viewMode, multiple, maxFiles            |
-
-### Service (Auto-generated)
-
-| Method            | Purpose              | Example                             |
-| ----------------- | -------------------- | ----------------------------------- |
-| `get{Entity}`     | Fetch single record  | `UserService.getUser("A", 123)`     |
-| `get{Entities}`   | Fetch list           | `UserService.getUsers("P", params)` |
-| `save`            | Save (create/update) | `UserService.save([data])`          |
-| `del`             | Delete               | `UserService.del([1, 2, 3])`        |
-| `use{Entity}`     | Single fetch hook    | `UserService.useUser("A", id)`      |
-| `use{Entities}`   | List fetch hook      | `UserService.useUsers("P", params)` |
-| `useSaveMutation` | Save mutation        | `UserService.useSaveMutation()`     |
-
-### Utilities
-
-| Function           | Purpose                  | Example                                           |
-| ------------------ | ------------------------ | ------------------------------------------------- |
-| `dateF`            | Date formatting          | `dateF(new Date())` → `"2024-01-15"`              |
-| `datetimeF`        | Datetime formatting      | `datetimeF(new Date())` → `"2024-01-15 10:30:00"` |
-| `numF`             | Number formatting        | `numF(1234567)` → `"1,234,567"`                   |
-| `hidden`           | Conditional hidden class | `hidden(true)` → `"hidden"`                       |
-| `arrayableToArray` | Convert to array         | `arrayableToArray("a")` → `["a"]`                 |
-
-### Configuration
-
-| Item             | Description                                        | Required                                   |
-| ---------------- | -------------------------------------------------- | ------------------------------------------ |
-| `SonamuProvider` | Global configuration Provider (uploader, auth, SD) | Required (uploader required for FileInput) |
-| `uploader`       | File upload function                               | Required when using FileInput              |
-| `auth`           | Authentication state and functions                 | Optional                                   |
-| `SD`             | Internationalization function                      | Optional                                   |
-
----
-
-# Frontend Service
-
-## Basic Usage
-
-```typescript
-import { UserService } from "@/services/services.generated";
-
-// Single fetch (Subset required) - get{Entity} form
-const user = await UserService.getUser("A", 123);
-
-// List fetch - get{Entities} form
-const { rows, total } = await UserService.getUsers("P", { num: 20, page: 1 });
-
-// Save
-const [userId] = await UserService.save([{ email: "new@test.com", username: "newuser" }]);
-
-// Delete
-const count = await UserService.del([1, 2, 3]);
-```
-
-## TanStack Query Hook
-
-### useQuery
-
-```typescript
-function UserProfile({ userId }: { userId: number }) {
-  // use{Entity} form (single), use{Entities} form (list)
-  const { data: user, isLoading, error } = UserService.useUser("A", userId);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-
-  return <h1>{user?.username}</h1>;
-}
-```
-
-### useMutation
-
-```typescript
-function EditProfile() {
-  const saveMutation = UserService.useSaveMutation();
-
-  async function handleSubmit(data: UserSaveParams) {
-    saveMutation.mutate({ spa: [data] }, {
-      onSuccess: ([userId]) => console.log("Saved:", userId),
-      onError: (error) => console.error("Failed:", error),
-    });
-  }
-
-  return <button disabled={saveMutation.isPending}>Save</button>;
-}
-```
-
-### Conditional Fetching
-
-```typescript
-const { data } = UserService.useUser("A", userId!, {
-  enabled: userId !== null,
-});
-```
-
-### Cache Invalidation
-
-```typescript
-const queryClient = useQueryClient();
-queryClient.invalidateQueries({ queryKey: ["User", "findById", "A", userId] });
-```
-
-## useTypeForm
-
-Type-safe form management based on Zod schemas (react-components v0.1.8+)
-
-### Return Values
-
-```typescript
-const { form, setForm, register, submit, addError, removeError, clearError, reset } = useTypeForm(
-  Schema,
-  defaultValue,
-);
-```
-
-| Return Value  | Type                                                | Description                       |
-| ------------- | --------------------------------------------------- | --------------------------------- |
-| `form`        | `z.infer<Schema>`                                   | Current form data                 |
-| `setForm`     | `React.Dispatch<SetStateAction<...>>`               | Form state update function        |
-| `register`    | `(field: string) => RegisterReturn`                 | Field registration function       |
-| `submit`      | `(callback) => () => Promise<R>`                    | Submit handler factory            |
-| `addError`    | `(path: string, error: string \| ErrorObj) => void` | Manually add an error             |
-| `removeError` | `(path: string) => void`                            | Remove error for a specific field |
-| `clearError`  | `() => void`                                        | Clear all errors                  |
-| `reset`       | `() => void`                                        | Reset form to defaultValue        |
-
-### register Return Object
-
-```typescript
-register(fieldName) // Returns:
-{
-  value: any,                           // Current field value
-  onValueChange: (value: any) => void,  // Value change handler
-  error?: { content: string }           // Error object (if present)
-}
-```
-
-### Basic Usage
-
-```tsx
-import { useTypeForm } from "@sonamu-kit/react-components/lib";
-import { Input } from "@sonamu-kit/react-components/components";
-import { UserSaveParams } from "@/services/user/user.types";
-
-function RegisterForm() {
-  const { form, setForm, register, submit } = useTypeForm(UserSaveParams, {
-    email: "",
-    username: "",
-    password: "",
-  });
-
-  const handleSubmit = submit(async (form) => {
-    await UserService.save([form]);
-  });
-
-  // Method 1: spread operator (recommended)
-  const emailProps = register("email");
-
-  return (
-    <form>
-      <Input {...emailProps} />
-      {emailProps.error && <span className="error">{emailProps.error.content}</span>}
-
-      {/* Method 2: inline (for short cases) */}
-      <Input {...register("username")} />
-      {register("username").error && (
-        <span className="error">{register("username").error.content}</span>
-      )}
-
-      <button onClick={handleSubmit}>Register</button>
-    </form>
-  );
-}
-```
-
-### IMPORTANT: react-components UI Component Usage
-
-All UI components in react-components follow the `value/onValueChange` pattern:
-
-```tsx
-import { Input, Checkbox, Select, Textarea } from "@sonamu-kit/react-components/components";
-
-// Input (string)
-<Input {...register("email")} />
-
-// Textarea (string)
-<Textarea {...register("content")} />
-
-// Checkbox (boolean)
-<Checkbox {...register("agreed")} />
-
-// Select (using items prop)
-<Select
-  {...register("status")}
-  items={[
-    { value: "active", label: "Active" },
-    { value: "inactive", label: "Inactive" }
-  ]}
-  placeholder="Select status"
-/>
-
-// Select simple form (string[] | number[])
-<Select
-  {...register("priority")}
-  items={["high", "medium", "low"]}
-  placeholder="Priority"
-/>
-```
-
-**Select component key props:**
-
-- `items`: Array of selectable items (`V[]` or `{ value: V, label?: ReactNode, disabled?: boolean }[]`)
-- `placeholder`: Text shown before selection
-- `clearable`: Whether the X button can deselect
-- `renderItem`: Custom render function
-
-### IMPORTANT: Form Required Field Initial Values
-
-Fields defined as required in SaveParams **must be included** in the form initial values:
-
-| Type              | Initial Value                  |
-| ----------------- | ------------------------------ |
-| string (required) | `""`                           |
-| number (required) | `0`                            |
-| Date (required)   | `new Date()`                   |
-| enum (required)   | Default value (e.g. `"draft"`) |
-| FK (required)     | `0`                            |
-| nullable          | `null`                         |
-
-```typescript
-const { form, setForm, register } = useTypeForm(TaskSaveParams, {
-  title: "", // string required
-  status: "draft", // enum required
-  budget: 0, // number required
-  begin_date: new Date(), // Date required
-  description: null, // nullable
-  institution_id: 0, // FK required
-});
-```
-
-### IMPORTANT: Accessing Relation Objects When Loading Data
-
-If a scaffolded form accesses relation objects like `row.collection?.id`, that relation must be included in subset A.
-
-**Error**: `Property 'collection' does not exist on type` → Add `"collection.id"` to subset A in entity.json
-
-```json
-// question.entity.json > subsets > A
-["id", "content", "collection.id", "collection.title", "parent.id", "answer_group.id"]
-```
-
-**Alternative**: If the FK is already on `row`, using `...row` alone is sufficient without accessing the relation (no subset modification needed)
-
-### IMPORTANT: SD() Translation Key for FK Fields
-
-Scaffolded forms use `SD("entity.Task.institution_id")`, but `sd.generated.ts` only generates keys without `_id`.
-
-**Fix**: Manually add the `_id` key to `ko.ts`
-
-```typescript
-// packages/api/src/i18n/ko.ts
-"entity.Task.institution_id": "Institution",
-"entity.Question.collection_id": "Collection",
-```
-
-Since `ko.ts` is copied from api → web, you only need to add it once.
-
-## useListParams
-
-List parameter management synchronized with URL query parameters (pagination, filtering)
-
-```typescript
-import { useListParams } from "@sonamu-kit/react-components/lib";
-import { z } from "zod";
-
-const ListParamsSchema = z.object({
-  page: z.coerce.number().default(1),
-  num: z.coerce.number().default(20),
-  search: z.string().optional(),
-  status: z.enum(["active", "inactive"]).optional(),
-});
-
-function UserListPage() {
-  const { listParams, setListParams, register } = useListParams(
-    ListParamsSchema,
-    { page: 1, num: 20 }
-  );
-
-  const { data } = UserService.useUsers("P", listParams);
-
-  return (
-    <div>
-      {/* Search (resets page=1 on change) */}
-      <Input {...register("search")} placeholder="Search" />
-
-      {/* Filter (resets page=1 on change) */}
-      <Select {...register("status")} items={["active", "inactive"]} />
-
-      {/* Pagination (changes page only) */}
-      <button onClick={() => setListParams({ ...listParams, page: listParams.page - 1 })}>
-        Previous
-      </button>
-      <span>Page {listParams.page}</span>
-      <button onClick={() => setListParams({ ...listParams, page: listParams.page + 1 })}>
-        Next
-      </button>
-    </div>
-  );
-}
-```
-
-**Key points:**
-
-- Automatically syncs with URL (`?page=2&status=active`)
-- `register` automatically resets page to 1 when any field other than page changes
-- Type safety guaranteed by Zod schema
-
-## useSelection
-
-Checkbox multi-selection management (supports Shift-click range selection)
-
-```typescript
-import { useSelection } from "@sonamu-kit/react-components/lib";
-
-function UserListPage() {
-  const { data } = UserService.useUsers("P", { num: 20, page: 1 });
-  const userIds = data?.rows.map(row => row.id) ?? [];
-
-  const {
-    getSelected,
-    toggle,
-    selectedKeys,
-    selectAll,
-    deselectAll,
-    isAllSelected,
-    handleCheckboxClick
-  } = useSelection(userIds);
-
-  const handleDelete = async () => {
-    await UserService.del(selectedKeys);
-    deselectAll();
-  };
-
-  return (
-    <div>
-      <Checkbox
-        value={isAllSelected}
-        onValueChange={isAllSelected ? deselectAll : selectAll}
-        label="Select all"
-      />
-      <button onClick={handleDelete} disabled={selectedKeys.length === 0}>
-        Delete selected ({selectedKeys.length})
-      </button>
-
-      {data?.rows.map((user, index) => (
-        <div key={user.id} onClick={(e) => handleCheckboxClick(e, index)}>
-          <Checkbox
-            value={getSelected(user.id)}
-            onValueChange={() => toggle(user.id)}
-          />
-          <span>{user.name}</span>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-**Key points:**
-
-- Range selection with Shift + click
-- `selectedKeys`: Array of currently selected keys
-- `isAllSelected`: Whether all items are selected
-
-## IdAsyncSelect
-
-Component for asynchronously searching and selecting Entity records. The generic type must be specified according to the Entity's Primary Key type.
-
-### Basic Usage
-
-IdAsyncSelect is typically used as a per-Entity wrapper component:
-
-```typescript
-import { IdAsyncSelect } from "@sonamu-kit/react-components/components";
-import { UserAsyncIdConfig } from "@/services/services.generated";
-import type { UserSubsetKey, UserSubsetMapping } from "@/services/sonamu.generated";
-import type { UserListParams } from "@/services/user/user.types";
-
-export type UserIdAsyncSelectProps<T extends UserSubsetKey> = {
-  subset: T;
-  baseListParams?: UserListParams;
-  displayField?: keyof UserSubsetMapping[T] & string;
-  valueField?: keyof UserSubsetMapping[T] & string;
-  placeholder?: string;
-  clearable?: boolean;
-  disabled?: boolean;
-  className?: string;
-  multiple?: boolean;
-  value?: number | number[] | null;  // Number PK
-  onValueChange?: (value: number | number[] | undefined) => void;
-};
-
-export function UserIdAsyncSelect<T extends UserSubsetKey>({
-  subset,
-  value,
-  onValueChange,
-  baseListParams,
-  displayField = "name",
-  valueField = "id",
-  placeholder = "User",
-  clearable,
-  disabled,
-  className,
-  multiple = false,
-}: UserIdAsyncSelectProps<T>) {
-  return (
-    <IdAsyncSelect<number>  // Number PK
-      config={UserAsyncIdConfig}
-      subset={subset}
-      baseListParams={baseListParams}
-      displayField={displayField}
-      valueField={valueField}
-      placeholder={placeholder}
-      clearable={clearable}
-      disabled={disabled}
-      className={className}
-      multiple={multiple}
-      value={value}
-      onValueChange={onValueChange}
-    />
-  );
-}
-```
-
-**Key Props:**
-
-- `config`: Auto-generated AsyncIdConfig (EntityAsyncIdConfig form)
-- `subset`: Subset key to query
-- `baseListParams`: List filter parameters
-- `displayField`: Field name to display (default varies by Entity)
-- `valueField`: Field name used as value (default: "id")
-- `multiple`: Whether multi-selection is enabled
-- `value`: Currently selected value (number or string depending on PK type)
-- `onValueChange`: Value change handler
-
-### Cascade Dropdown Pattern (Hierarchical Selection)
-
-When lower-level lists should change based on higher-level selection (e.g. Department → Division → Lab), pass `baseListParams` dynamically.
-
-**Key behavior**: When the `baseListParams` prop changes, the React Query inside `IdAsyncSelect` automatically re-fetches with the new parameters. (Bug fixed in v0.2.5+ — previous versions only used the initial value and did not reflect changes)
-
-```tsx
-// Example: 3-level cascade Department → Division → Lab
-function UserForm() {
-  const { form, register, setForm } = useTypeForm(UserSaveParams, {
-    dept_id: null,
-    division_id: null,
-    lab_id: null,
-  });
-
-  return (
-    <form>
-      {/* Level 1: Department selection (full list → preload or default IdAsyncSelect) */}
-      <DepartmentIdAsyncSelect
-        subset="A"
-        {...register("dept_id")}
-        onValueChange={(v) => {
-          // Reset lower values when department changes
-          setForm((prev) => ({ ...prev, dept_id: v ?? null, division_id: null, lab_id: null }));
-        }}
-      />
-
-      {/* Level 2: Division selection (only divisions in selected department) */}
-      <DivisionIdAsyncSelect
-        subset="A"
-        baseListParams={form.dept_id ? { department_id: form.dept_id } : undefined}
-        disabled={!form.dept_id}
-        {...register("division_id")}
-        onValueChange={(v) => {
-          // Reset lab when division changes
-          setForm((prev) => ({ ...prev, division_id: v ?? null, lab_id: null }));
-        }}
-      />
-
-      {/* Level 3: Lab selection (only labs in selected division) */}
-      <LabIdAsyncSelect
-        subset="A"
-        baseListParams={form.division_id ? { division_id: form.division_id } : undefined}
-        disabled={!form.division_id}
-        {...register("lab_id")}
-      />
-    </form>
-  );
-}
-```
-
-**Notes**:
-
-- You must explicitly reset lower values to `null` when a higher-level value changes. IdAsyncSelect does not reset automatically.
-- Using the `disabled` prop to disable lower levels when the parent is not selected improves UX.
-- If `baseListParams` is `undefined`, IdAsyncSelect stays in enabled=false state and does not fetch.
-
-**Items to specify in Spec** (recommended to add to acceptanceCriteria in spec.json when cascade is present):
-
-```json
-"acceptanceCriteria": [
-  "When a department is selected, only divisions belonging to that department appear in the dropdown",
-  "When a division is selected, only labs belonging to that division appear in the dropdown",
-  "When the department changes, the lower division/lab selections are reset"
-]
-```
-
-### IMPORTANT: String Primary Key Support
-
-Most Entities use Number PK (`IdAsyncSelect<number>`), but better-auth related Entities use String PK.
-
-**String PK Entities**: User, Account, Session, Verification
-
-**Points to change** (manual modification required after scaffolding):
-
-```typescript
-// Number PK (default)
-value?: number | number[] | null;
-onValueChange?: (value: number | number[] | undefined) => void;
-<IdAsyncSelect<number> config={PostAsyncIdConfig} ... />
-
-// String PK (User, Account, etc.) — change all 3 places to string
-value?: string | string[] | null;
-onValueChange?: (value: string | string[] | undefined) => void;
-<IdAsyncSelect<string> config={AccountAsyncIdConfig} ... />
-```
-
-### Usage in Forms
-
-```tsx
-function PostForm() {
-  const { form, setForm, register } = useTypeForm(PostSaveParams, {
-    title: "",
-    author_id: 0, // or "" for string PK
-  });
-
-  return (
-    <form>
-      <Input {...register("title")} />
-
-      {/* Number PK */}
-      <UserIdAsyncSelect subset="A" {...register("author_id")} />
-
-      {/* String PK */}
-      <AccountIdAsyncSelect subset="A" {...register("account_id")} />
-    </form>
-  );
-}
-```
-
-## FileInput
-
-File upload component (image/general files, eager/lazy modes)
-
-```typescript
-import { FileInput } from "@sonamu-kit/react-components/components";
-import type { SonamuFile } from "@sonamu-kit/react-components/contexts";
-
-function ProfileForm() {
-  const { form, setForm, register, submit } = useTypeForm(ProfileSaveParams, {
-    avatar: null,  // SonamuFile | File | null
-    documents: [], // (SonamuFile | File)[]
-  });
-
-  return (
-    <form>
-      {/* Single image - eager upload */}
-      <FileInput
-        {...register("avatar")}
-        uploadMode="eager"
-        viewMode="image"
-        placeholder="Profile image"
-        accept="image/*"
-        previewSize="md"
-      />
-
-      {/* Multiple files - lazy upload */}
-      <FileInput
-        {...register("documents")}
-        uploadMode="lazy"
-        viewMode="file"
-        multiple
-        maxFiles={5}
-        placeholder="Attach documents"
-      />
-
-      <button onClick={submit(async (form) => {
-        // lazy mode: auto-uploads on submit
-        await ProfileService.save([form]);
-      })}>Save</button>
-    </form>
-  );
-}
-```
-
-**Props:**
-
-- `uploadMode`: `"eager"` (upload immediately) | `"lazy"` (upload on submit)
-- `viewMode`: `"image"` (image preview) | `"file"` (filename)
-- `multiple`: Whether multiple files can be selected
-- `maxFiles`: Maximum number of files
-- `previewSize`: `"sm" | "md" | "lg" | "xl"`
-- `clearable`: Whether the X button can remove the file
-
-**IMPORTANT**: uploader function must be configured in SonamuProvider (see below)
-
-## Select (Multi-select Mode)
-
-Setting `multiple: true` on the `Select` component enables multi-select mode.
-
-```typescript
-import { Select } from "@sonamu-kit/react-components/components";
-
-function TagForm() {
-  const { register } = useTypeForm(PostSaveParams, {
-    tag_ids: [],  // number[]
-  });
-
-  const items = [
-    { value: 1, label: "JavaScript" },
-    { value: 2, label: "TypeScript" },
-    { value: 3, label: "React" },
-    { value: 4, label: "Vue" },
-  ];
-
-  return (
-    <Select
-      {...register("tag_ids")}
-      items={items}
-      multiple
-      placeholder="Select tags"
-    />
-  );
-}
-```
-
-**Multi-select specific Props:**
-
-- `multiple`: `true` (enables multi-select)
-- `maxCount`: Maximum number of badges to display
-- `hideSelectAll`: Hide the select all button
-- `searchable`: Enable search input
-
-**Common Props:**
-
-- `items`: `SelectItemDef[]` (values only or `{ value, label, disabled }` form)
-- `placeholder`: Text shown before selection
-- `clearable`: X button to deselect all
-- `disabled`: Disable the component
-- `renderItem`: Custom render function
-- `async`: When set to `true`, supports async search via `onSearch` callback
-
-## EnumSelect
-
-Select integrated with Zod enum (label mapping)
-
-```typescript
-import { EnumSelect } from "@sonamu-kit/react-components/components";
-import { z } from "zod";
-
-const StatusEnum = z.enum(["draft", "published", "archived"]);
-
-const statusLabels = {
-  draft: "Draft",
-  published: "Published",
-  archived: "Archived",
-} as const;
-
-function PostForm() {
-  const { register } = useTypeForm(PostSaveParams, {
-    status: "draft",
-  });
-
-  return (
-    <EnumSelect
-      {...register("status")}
-      enum={StatusEnum}
-      labels={statusLabels}
-      placeholder="Select status"
-      clearable
-    />
-  );
-}
-```
-
-**Key points:**
-
-- Zod enum type safety
-- Display name mapping via labels object
-- Automatically converts enum.options to items
-
-## SonamuProvider
-
-Global configuration used across react-components
-
-```typescript
-// App.tsx or root component
-import { SonamuProvider } from "@sonamu-kit/react-components/contexts";
-import type { SonamuFile } from "@sonamu-kit/react-components/contexts";
-
-function App() {
-  // File uploader function (used by FileInput, useTypeForm)
-  const uploader = async (files: File[]): Promise<SonamuFile[]> => {
-    const formData = new FormData();
-    files.forEach(file => formData.append("files", file));
-
-    const response = await fetch("/api/upload", {
-      method: "POST",
-      body: formData,
-    });
-
-    return response.json();
-  };
-
-  // Authentication state (optional)
-  const auth = {
-    user: currentUser,
-    loading: isLoading,
-    login: async (params) => { /* ... */ },
-    logout: async () => { /* ... */ },
-    refetch: async () => { /* ... */ },
-  };
-
-  // Internationalization function (optional)
-  const SD = (key: string) => dictionary[key] ?? key;
-
-  return (
-    <SonamuProvider uploader={uploader} auth={auth} SD={SD}>
-      {children}
-    </SonamuProvider>
-  );
-}
-```
-
-**Required Props:**
-
-- `uploader`: `(files: File[]) => Promise<SonamuFile[]>` - Used by FileInput
-- `auth`: Authentication state and functions (optional)
-- `SD`: Internationalization function (optional)
-
-## Utility Functions
-
-```typescript
-import {
-  dateF,
-  datetimeF,
-  numF,
-  hidden,
-  arrayableToArray,
-  sqlDateToDateString,
-} from "@sonamu-kit/react-components/lib";
-
-// Date formatting
-dateF(new Date());           // "2024-01-15"
-dateF("2024-01-15T10:30:00"); // "2024-01-15"
-datetimeF(new Date());       // "2024-01-15 10:30:00"
-
-// Number formatting
-numF(1234567);  // "1,234,567"
-
-// Conditional hidden class
-<div className={hidden(isHidden)}>...</div>
-
-// SQL date → date string
-sqlDateToDateString("2024-01-15T10:30:00.000Z");  // "2024-01-15"
-
-// Convert to array
-arrayableToArray("single");      // ["single"]
-arrayableToArray(["a", "b"]);    // ["a", "b"]
-arrayableToArray(undefined);     // []
-```
-
-## Error Handling
-
-```typescript
-import { isSonamuError } from "@/lib/sonamu.shared";
-
-try {
-  await UserService.save([
-    {
-      /* ... */
-    },
-  ]);
-} catch (error) {
-  if (isSonamuError(error)) {
-    console.log("Status:", error.code);
-    console.log("Message:", error.message);
-    error.issues.forEach((issue) => {
-      console.log(`${issue.path.join(".")}: ${issue.message}`);
-    });
-  }
-}
-```
-
-## SSR
-
-```typescript
-// api/src/ssr/routes.ts
-import { registerSSR } from "sonamu/ssr";
-
-registerSSR({
-  path: "/companies/:companyId",
-  preload: (params) => [UserService.me(), CompanyService.findById("A", Number(params.companyId))],
-});
-```
-
-## Initial Project Setup
-
-**→ See the "Project Name Change" section in `create-sonamu.md`** (change 4 files: index.html, \_\_root.tsx, index.tsx, Sidebar.tsx)
-
-## Rules
-
-- NEVER manually modify `services.generated.ts`
-- MUST specify Subset parameter when calling APIs
-- Use `Promise.all([...])` for parallel requests
-
----
-
-## Full Component Implementation Examples
-
-### List Page
-
-```typescript
-function ConsultationListPage() {
-  const [params, setParams] = useState({ num: 20, page: 1 });
-  const { data, isLoading } = ConsultationService.useConsultations("P", params);
-
-  return (
-    <div>
-      {/* Manage selection with useSelection */}
-      {data?.rows.map((row) => (
-        <div key={row.id}>{row.title} - {row.status}</div>
-      ))}
-      {/* Pagination: manipulate params.page */}
-    </div>
-  );
-}
-```
-
-### Edit Page
-
-```typescript
-function ConsultationFormPage() {
-  const { id } = useParams();
-  const { form, setForm, register, submit } = useTypeForm(ConsultationSaveParams, {
-    title: "", content: "", status: "pending", user_id: 0,
-  });
-
-  // Edit mode: load data
-  useEffect(() => {
-    if (id) ConsultationService.getConsultation("A", Number(id)).then((row) => setForm((prev) => ({ ...prev, ...row })));
-  }, [id]);
-
-  const saveMutation = ConsultationService.useSaveMutation();
-  const handleSubmit = submit(async (form) => {
-    const [cId] = await saveMutation.mutateAsync({ spa: [form] });
-    navigate(`/consultations/${cId}`);
-  });
-
-  return (
-    <form>
-      <Input {...register("title")} />
-      <Textarea {...register("content")} />
-      <Select {...register("status")} items={[{value:"pending",label:"Pending"},{value:"completed",label:"Completed"}]} />
-      <button onClick={handleSubmit} disabled={saveMutation.isPending}>Save</button>
-    </form>
-  );
-}
-```
-
-### Cache Invalidation
-
-```typescript
-const queryClient = useQueryClient();
-await ConsultationService.changeStatus(id, newStatus, "Status change");
-queryClient.invalidateQueries({
-  queryKey: ["Consultation", "findById", "A", id],
-});
-queryClient.invalidateQueries({ queryKey: ["Consultation", "findMany"] });
-```