@simplysm/solid 13.0.98 → 13.0.100

package/docs/features.md

@@ -1,175 +1,198 @@
 # Feature Components
 
-Source: `src/components/features/**/*.tsx`
+Source: `src/components/features/**`
 
-## AddressSearchContent
+## `AddressSearchContent`
 
-Korean address search component using Daum Postcode API.
+Korean address search dialog content using Daum Postcode API.
 
-```ts
-interface AddressSearchResult {
+```typescript
+export interface AddressSearchResult {
   postNumber: string | undefined;
   address: string | undefined;
   buildingName: string | undefined;
 }
-
-const AddressSearchContent: Component<{
-  close?: (result?: AddressSearchResult) => void;
-}>;
 ```
 
-Designed for use with `useDialog().show()`. Loads the Daum Postcode script on mount.
+Props: `{ close?: (result?: AddressSearchResult) => void }`
 
-## SharedDataSelect
+Designed to be used with `useDialog().show()`.
 
-Select component bound to a shared data definition. Supports single and multiple modes with the same prop variants as `Select`.
+---
 
-```ts
-type SharedDataSelectProps<TItem, TDataKey extends string> = {
-  dataKey: TDataKey;
-  // ...inherits Select props (value, onValueChange, multiple, etc.)
-  // plus shared data specific:
-  getItemSearchText?: (item: TItem) => string;
-  isItemHidden?: (item: TItem) => boolean;
-};
-```
+## `SharedDataSelect`
 
-### Sub-components
+Select component integrated with `SharedDataAccessor` for reactive shared data selection. Supports single and multiple modes with search, tree structure, and dialog selection.
 
-- **`SharedDataSelect.ItemTemplate`** -- Render template for items.
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `SharedDataAccessor<TItem>` | Shared data accessor |
+| `value` | `TKey \| TKey[]` | Selected key(s) |
+| `onValueChange` | `(value) => void` | Value change callback |
+| `multiple` | `boolean` | Multiple selection mode |
+| `required` | `boolean` | Required input |
+| `disabled` | `boolean` | Disabled state |
+| `size` | `ComponentSize` | Trigger size |
+| `inset` | `boolean` | Borderless style |
+| `filterFn` | `(item, index) => boolean` | Item filter function |
+| `dialog` | `Component<TDialogProps>` | Selection dialog component |
+| `dialogOptions` | `DialogShowOptions` | Dialog display options |
 
-## SharedDataSelectButton
+---
 
-Button that opens a shared data selection dialog.
+## `SharedDataSelectButton`
 
-```ts
-type SharedDataSelectButtonProps<TItem, TDataKey extends string> = {
-  dataKey: TDataKey;
-  value?: TItem | TItem[];
-  onValueChange?: (value: TItem | TItem[] | undefined) => void;
-  renderValue?: (value: TItem) => JSX.Element;
-  // ...plus button/validation props
-};
-```
+Button-based select component for shared data. Opens a dialog for selection. Supports single and multiple modes.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `SharedDataAccessor<TItem>` | Shared data accessor |
+| `value` | `string \| number \| (string \| number)[]` | Selected key(s) |
+| `onValueChange` | `(value) => void` | Value change callback |
+| `multiple` | `boolean` | Multiple selection mode |
+| `required` | `boolean` | Required input |
+| `disabled` | `boolean` | Disabled state |
+| `size` | `ComponentSize` | Trigger size |
+| `inset` | `boolean` | Borderless style |
+| `dialog` | `Component<TDialogProps>` | Selection dialog component (required) |
+| `dialogOptions` | `DialogShowOptions` | Dialog display options |
+| `children` | `(item: TItem) => JSX.Element` | Item rendering function |
 
-## SharedDataSelectList
+---
 
-List component bound to shared data, rendering items from a shared data definition.
+## `SharedDataSelectList`
 
-```ts
-interface SharedDataSelectListProps<TItem> {
-  dataKey: string;
-  value?: unknown[];
-  onValueChange?: (value: unknown[]) => void;
-  // ...list configuration props
+List-based selection component for shared data with pagination and search.
+
+```typescript
+export interface SharedDataSelectListProps<TItem> {
+  data: SharedDataAccessor<TItem>;
+  value?: TItem;
+  onValueChange?: (value: TItem | undefined) => void;
+  required?: boolean;
+  disabled?: boolean;
+  filterFn?: (item: TItem, index: number) => boolean;
 }
 ```
 
 ### Sub-components
 
-- **`SharedDataSelectList.ItemTemplate`** -- Render template for list items.
-
-## DataSelectButton
+- **`SharedDataSelectList.ItemTemplate`** -- Template for item rendering
+- **`SharedDataSelectList.Filter`** -- Custom filter UI slot
 
-Button that opens a custom data selection dialog. Generic over key type and dialog props.
+### `SharedDataSelectListContextValue`
 
-```ts
-interface DataSelectButtonProps<TKey, TDialogProps> {
-  value?: TKey | TKey[];
-  onValueChange?: (value: TKey | TKey[] | undefined) => void;
-  renderValue?: (value: TKey) => JSX.Element;
-  dialog: Component<TDialogProps>;
-  dialogProps?: Omit<TDialogProps, "close">;
-  multiple?: boolean;
-  disabled?: boolean;
-  required?: boolean;
-  size?: ComponentSize;
-  inset?: boolean;
-  class?: string;
-  style?: JSX.CSSProperties;
+```typescript
+export interface SharedDataSelectListContextValue {
+  setItemTemplate: (fn: ((...args: unknown[]) => JSX.Element) | undefined) => void;
 }
+```
+
+---
+
+## `DataSelectButton`
+
+Generic button-based select component that opens a dialog for selection. Works with any data source (not tied to SharedData).
+
+### `SelectDialogBaseProps`
 
-interface DataSelectDialogResult<TKey> {
+```typescript
+export interface SelectDialogBaseProps<TKey = string | number> {
+  close?: (result?: DataSelectDialogResult<TKey>) => void;
+  selectionMode: "single" | "multiple";
   selectedKeys: TKey[];
 }
+```
 
-interface SelectDialogBaseProps<TKey> {
-  close?: (result?: DataSelectDialogResult<TKey>) => void;
-  initialSelectedKeys?: TKey[];
-  selectionMode?: "single" | "multiple";
+### `DataSelectDialogResult`
+
+```typescript
+export interface DataSelectDialogResult<TKey> {
+  selectedKeys: TKey[];
 }
 ```
 
-## CrudSheet
+### `DialogPropsField`
 
-Full-featured CRUD data grid combining DataSheet with search, pagination, sorting, inline/dialog editing, selection, and Excel import/export.
+Conditional type that makes `dialogProps` required only when the dialog component has required custom props.
 
-```ts
-type CrudSheetProps<TItem, TFilter extends Record<string, unknown>> = {
-  search: (filter: TFilter, page: number | undefined, sorts: SortingDef[]) => Promise<SearchResult<TItem>>;
-  getItemKey: (item: TItem) => string | number | undefined;
-  storageKey?: string;
-  editable?: boolean;
-  isItemEditable?: (item: TItem) => boolean;
-  isItemDeletable?: (item: TItem) => boolean;
-  isItemDeleted?: (item: TItem) => boolean;
-  isItemSelectable?: (item: TItem) => boolean | string;
-  lastModifiedAtProp?: string;
-  lastModifiedByProp?: string;
-  filterInitial?: TFilter;
-  items?: TItem[];
-  onItemsChange?: (items: TItem[]) => void;
-  excel?: ExcelConfig<TItem>;
-  selectionMode?: "single" | "multiple";
-  selectedKeys?: (string | number)[];
-  onSelectedKeysChange?: (keys: (string | number)[]) => void;
-  onSelect?: (result: SelectResult<TItem>) => void;
-  onSubmitComplete?: () => void;
-  hideAutoTools?: boolean;
-  close?: () => void;
-  class?: string;
-  children: JSX.Element;
-} & (
-  | { inlineEdit: InlineEditConfig<TItem>; dialogEdit?: never }
-  | { dialogEdit: DialogEditConfig<TItem>; inlineEdit?: never }
-  | { inlineEdit?: never; dialogEdit?: never }
-);
-
-interface SearchResult<TItem> {
+```typescript
+export type DialogPropsField<P, TKey = string | number> =
+  {} extends UserDialogProps<P, TKey>
+    ? { dialogProps?: UserDialogProps<P, TKey> }
+    : { dialogProps: UserDialogProps<P, TKey> };
+```
+
+---
+
+## `CrudSheet`
+
+Full-featured CRUD data grid with inline/dialog editing, sorting, pagination, selection, excel import/export, and toolbar management.
+
+```typescript
+export type CrudSheetProps<TItem, TFilter extends Record<string, unknown>> =
+  CrudSheetBaseProps<TItem, TFilter> & (
+    | { inlineEdit: InlineEditConfig<TItem>; dialogEdit?: never }
+    | { dialogEdit: DialogEditConfig<TItem>; inlineEdit?: never }
+    | { inlineEdit?: never; dialogEdit?: never }
+  );
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `search` | `(filter, page, sorts) => Promise<SearchResult<TItem>>` | Data fetch function |
+| `getItemKey` | `(item) => string \| number \| undefined` | Item key extractor |
+| `storageKey` | `string` | Config persistence key |
+| `editable` | `boolean` | Enable editing |
+| `inlineEdit` | `InlineEditConfig<TItem>` | Inline editing configuration |
+| `dialogEdit` | `DialogEditConfig<TItem>` | Dialog editing configuration |
+| `excel` | `ExcelConfig<TItem>` | Excel download/upload |
+| `selectionMode` | `"single" \| "multiple"` | Selection mode |
+| `filterInitial` | `TFilter` | Initial filter state |
+
+### `SearchResult`
+
+```typescript
+export interface SearchResult<TItem> {
   items: TItem[];
   pageCount?: number;
 }
+```
 
-interface InlineEditConfig<TItem> {
+### `InlineEditConfig`
+
+```typescript
+export interface InlineEditConfig<TItem> {
   submit: (diffs: ArrayOneWayDiffResult<TItem>[]) => Promise<void>;
   newItem: () => TItem;
   deleteProp?: keyof TItem & string;
   diffsExcludes?: string[];
 }
+```
 
-interface DialogEditConfig<TItem> {
+### `DialogEditConfig`
+
+```typescript
+export interface DialogEditConfig<TItem> {
   editItem: (item?: TItem) => Promise<boolean | undefined>;
   deleteItems?: (items: TItem[]) => Promise<boolean>;
   restoreItems?: (items: TItem[]) => Promise<boolean>;
 }
+```
+
+### `ExcelConfig`
 
-interface ExcelConfig<TItem> {
+```typescript
+export interface ExcelConfig<TItem> {
   download: (items: TItem[]) => Promise<void>;
   upload?: (file: File) => Promise<void>;
 }
 ```
 
-### Sub-components
-
-- **`CrudSheet.Column<TItem>`** -- Column definition with cell context.
-
-```ts
-interface CrudSheetColumnProps<TItem> extends Omit<DataSheetColumnProps<TItem>, "children"> {
-  editTrigger?: boolean;
-  children: (ctx: CrudSheetCellContext<TItem>) => JSX.Element;
-}
+### `CrudSheetCellContext`
 
-interface CrudSheetCellContext<TItem> {
+```typescript
+export interface CrudSheetCellContext<TItem> {
   item: TItem;
   index: number;
   row: number;
@@ -178,23 +201,10 @@ interface CrudSheetCellContext<TItem> {
 }
 ```
 
-- **`CrudSheet.Filter<TFilter>`** -- Filter panel slot.
+### `CrudSheetContext`
 
-```ts
-interface CrudSheetFilterSlotProps<TFilter> {
-  filter: TFilter;
-  setFilter: SetStoreFunction<TFilter>;
-}
-```
-
-- **`CrudSheet.Tools<TItem>`** -- Toolbar slot with context.
-
-```ts
-interface CrudSheetToolsSlotProps<TItem> {
-  ctx: CrudSheetContext<TItem>;
-}
-
-interface CrudSheetContext<TItem> {
+```typescript
+export interface CrudSheetContext<TItem> {
   items(): TItem[];
   selection(): TItem[];
   page(): number;
@@ -210,12 +220,32 @@ interface CrudSheetContext<TItem> {
 }
 ```
 
-## CrudDetail
+### `SelectResult`
+
+```typescript
+export interface SelectResult<TItem> {
+  items: TItem[];
+  keys: (string | number)[];
+}
+```
+
+### `CrudSheetColumnProps`
+
+```typescript
+export interface CrudSheetColumnProps<TItem> extends Omit<DataSheetColumnProps<TItem>, "children"> {
+  editTrigger?: boolean;
+  children: (ctx: CrudSheetCellContext<TItem>) => JSX.Element;
+}
+```
+
+---
 
-CRUD detail form with load, save, delete, and change tracking.
+## `CrudDetail`
 
-```ts
-interface CrudDetailProps<TData extends object> {
+CRUD detail view with controlled store, save/refresh lifecycle, and delete toggle.
+
+```typescript
+export interface CrudDetailProps<TData extends object> {
   load: () => Promise<{ data: TData; info: CrudDetailInfo }>;
   children: (ctx: CrudDetailContext<TData>) => JSX.Element;
   submit?: (data: TData) => Promise<boolean | undefined>;
@@ -227,15 +257,23 @@ interface CrudDetailProps<TData extends object> {
   close?: (result?: boolean) => void;
   class?: string;
 }
+```
 
-interface CrudDetailInfo {
+### `CrudDetailInfo`
+
+```typescript
+export interface CrudDetailInfo {
   isNew: boolean;
   isDeleted: boolean;
   lastModifiedAt?: DateTime;
   lastModifiedBy?: string;
 }
+```
 
-interface CrudDetailContext<TData> {
+### `CrudDetailContext`
+
+```typescript
+export interface CrudDetailContext<TData> {
   data: TData;
   setData: SetStoreFunction<TData>;
   info: () => CrudDetailInfo;
@@ -246,34 +284,27 @@ interface CrudDetailContext<TData> {
 }
 ```
 
-### Sub-components
-
-- **`CrudDetail.Header`** -- Header content slot.
+---
 
-## PermissionTable
+## `PermissionTable`
 
-Permission matrix table displaying app permissions with checkboxes.
+Permission management table displaying a tree of `AppPerm` items with checkbox columns for each permission type.
 
-```ts
-interface PermissionTableProps<TModule = string> {
-  perms: AppPerm<TModule>[];
-  value?: string[];
-  onValueChange?: (value: string[]) => void;
+```typescript
+export interface PermissionTableProps<TModule = string> {
+  items?: AppPerm<TModule>[];
+  value?: Record<string, boolean>;
+  onValueChange?: (value: Record<string, boolean>) => void;
+  modules?: TModule[];
   disabled?: boolean;
   class?: string;
   style?: JSX.CSSProperties;
 }
 ```
 
-### Helper Functions
-
-```ts
-function collectAllPerms<TModule>(items: AppPerm<TModule>[]): string[];
-function filterByModules<TModule>(items: AppPerm<TModule>[], enabledModules: TModule[]): AppPerm<TModule>[];
-function changePermCheck<TModule>(
-  items: AppPerm<TModule>[],
-  currentPerms: string[],
-  changedPerm: string,
-  checked: boolean,
-): string[];
+### Utility Functions
+
+```typescript
+export function collectAllPerms<TModule>(items: AppPerm<TModule>[]): string[];
+export function filterByModules<TModule>(items: AppPerm<TModule>[], modules: TModule[]): AppPerm<TModule>[];
 ```