sonamu 0.10.7 → 0.10.9

package/src/skills/sonamu-frontend/references/components.md

@@ -1,323 +0,0 @@
-# Components
-
-## 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

package/src/skills/sonamu-frontend/references/examples.md

@@ -1,64 +0,0 @@
-# Full Component Implementation Examples
-
-## 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"] });
-```

package/src/skills/sonamu-frontend/references/hooks.md

@@ -1,273 +0,0 @@
-# Form and List Hooks
-
-## 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