@simplysm/solid 13.0.97 → 13.0.98

package/docs/disclosure.md

@@ -0,0 +1,164 @@
+# Disclosure Components
+
+Source: `src/components/disclosure/**/*.tsx`
+
+## Collapse
+
+Animated expand/collapse container using margin-top transition.
+
+```ts
+interface CollapseProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  open?: boolean;  // default: false
+}
+```
+
+- Uses `ResizeObserver` to track content height.
+- Disables transition on initial render to prevent flicker.
+- Sets `visibility: hidden` when closed to prevent focusable element access.
+
+## Dropdown
+
+Positioned popup with trigger element. Uses Portal for rendering.
+
+```ts
+interface DropdownProps {
+  position?: { x: number; y: number };  // absolute position (for context menus)
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  maxHeight?: number;            // default: 300
+  disabled?: boolean;
+  keyboardNav?: boolean;         // arrow key navigation
+  class?: string;
+  style?: JSX.CSSProperties;
+  children: JSX.Element;
+}
+```
+
+- Auto-positions above or below trigger based on available viewport space.
+- Closes on outside click, Escape key, scroll, and resize.
+- `keyboardNav`: ArrowDown/Up navigates between tabbable items in popup.
+
+### Sub-components
+
+- **`Dropdown.Trigger`** -- Click target that toggles the dropdown. Slot component.
+- **`Dropdown.Content`** -- Popup content. Slot component.
+
+## Dialog
+
+Modal or floating dialog with drag, resize, z-index management, and animation.
+
+```ts
+interface DialogProps {
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  withCloseButton?: boolean;           // default: true
+  closeOnInteractOutside?: boolean;    // default: false (uses DialogDefaults)
+  closeOnEscape?: boolean;             // default: true (uses DialogDefaults)
+  resizable?: boolean;                 // default: false
+  draggable?: boolean;                 // default: true
+  mode?: "float" | "fill";
+  width?: number;
+  height?: number;
+  minWidth?: number;
+  minHeight?: number;
+  position?: "bottom-right" | "top-right";
+  headerStyle?: JSX.CSSProperties | string;
+  beforeClose?: () => boolean;         // return false to prevent close
+  onCloseComplete?: () => void;
+  class?: string;
+}
+```
+
+- `mode="float"`: no backdrop, pointer-events pass through.
+- `mode="fill"`: full-screen dialog.
+- 8-direction resize handles when `resizable=true`.
+- Automatic z-index stacking across multiple open dialogs.
+
+### Sub-components
+
+- **`Dialog.Header`** -- Dialog title bar. Enables drag when `draggable=true`.
+- **`Dialog.Action`** -- Action buttons rendered in the header next to the close button.
+
+## DialogProvider
+
+Programmatic dialog provider. Enables `useDialog().show()` to open dialogs as Promises.
+
+```ts
+interface DialogProviderProps extends DialogDefaults {}
+
+interface DialogDefaults {
+  closeOnEscape?: boolean;
+  closeOnInteractOutside?: boolean;
+}
+```
+
+### useDialog()
+
+Hook to open dialogs programmatically.
+
+```ts
+function useDialog(): DialogContextValue;
+
+interface DialogContextValue {
+  show<P extends Record<string, any>>(
+    component: Component<P>,
+    props: Omit<P, "close">,
+    options?: DialogShowOptions,
+  ): Promise<ExtractCloseResult<P> | undefined>;
+}
+
+interface DialogShowOptions {
+  header?: JSX.Element;
+  withCloseButton?: boolean;
+  closeOnInteractOutside?: boolean;
+  closeOnEscape?: boolean;
+  resizable?: boolean;
+  draggable?: boolean;
+  mode?: "float" | "fill";
+  width?: number;
+  height?: number;
+  minWidth?: number;
+  minHeight?: number;
+  position?: "bottom-right" | "top-right";
+  headerStyle?: JSX.CSSProperties | string;
+  beforeClose?: () => boolean;
+}
+```
+
+The dialog component receives a `close` prop. Call `close(result)` to resolve the Promise.
+
+### DialogDefaultsContext
+
+Context providing default dialog configuration. Used by `Dialog` when per-instance props are not set.
+
+```ts
+const DialogDefaultsContext: Context<Accessor<DialogDefaults>>;
+```
+
+## Tabs
+
+Tab bar with value-based selection.
+
+```ts
+interface TabsProps {
+  value?: string;
+  onValueChange?: (value: string) => void;
+  size?: ComponentSize;
+  class?: string;
+  style?: JSX.CSSProperties;
+  children?: JSX.Element;
+}
+```
+
+### Sub-components
+
+- **`Tabs.Tab`** -- Individual tab button.
+
+```ts
+interface TabsTabProps {
+  value: string;
+  disabled?: boolean;
+  class?: string;
+  children?: JSX.Element;
+}
+```

package/docs/display.md

@@ -0,0 +1,94 @@
+# Display Components
+
+Source: `src/components/display/**/*.tsx`
+
+## Barcode
+
+SVG barcode renderer powered by bwip-js.
+
+```ts
+interface BarcodeProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  type: BarcodeType;
+  value?: string;
+}
+```
+
+### BarcodeType
+
+Union type of all supported barcode formats. Common values include: `"qrcode"`, `"code128"`, `"ean13"`, `"datamatrix"`, `"pdf417"`, `"azteccode"`, `"code39"`, `"upca"`, `"isbn"`.
+
+Full list exported from `src/components/display/Barcode.types.ts` with 100+ formats.
+
+## Card
+
+Elevated container with shadow and fade-in animation.
+
+```ts
+interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {}
+```
+
+Applies surface background, rounded corners, shadow with hover/focus-within elevation.
+
+## Echarts
+
+Apache ECharts wrapper with reactive option updates and resize handling.
+
+```ts
+interface EchartsProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  option: echarts.EChartsOption;
+  busy?: boolean;  // shows/hides loading indicator
+}
+```
+
+- Uses SVG renderer.
+- Automatically resizes with container via `ResizeObserver`.
+
+## Icon
+
+Tabler icon wrapper using `Dynamic` rendering.
+
+```ts
+interface IconProps extends Omit<TablerIconProps, "size"> {
+  icon: Component<TablerIconProps>;
+  size?: string | number;  // default: "1.25em"
+}
+```
+
+Adds `inline` display and vertical alignment.
+
+## Tag
+
+Themed inline tag/badge with solid background.
+
+```ts
+type TagTheme = SemanticTheme;
+
+interface TagProps extends JSX.HTMLAttributes<HTMLSpanElement> {
+  theme?: TagTheme;  // default: "base"
+}
+```
+
+## Link
+
+Themed anchor link with hover underline.
+
+```ts
+type LinkTheme = SemanticTheme;
+
+interface LinkProps extends JSX.AnchorHTMLAttributes<HTMLAnchorElement> {
+  theme?: LinkTheme;    // default: "primary"
+  disabled?: boolean;
+}
+```
+
+## Alert
+
+Themed alert/callout box with light background.
+
+```ts
+type AlertTheme = SemanticTheme;
+
+interface AlertProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  theme?: AlertTheme;  // default: "base"
+}
+```

package/docs/features.md

@@ -0,0 +1,279 @@
+# Feature Components
+
+Source: `src/components/features/**/*.tsx`
+
+## AddressSearchContent
+
+Korean address search component using Daum Postcode API.
+
+```ts
+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.
+
+## SharedDataSelect
+
+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;
+};
+```
+
+### Sub-components
+
+- **`SharedDataSelect.ItemTemplate`** -- Render template for items.
+
+## SharedDataSelectButton
+
+Button that opens a shared data selection dialog.
+
+```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
+};
+```
+
+## SharedDataSelectList
+
+List component bound to shared data, rendering items from a shared data definition.
+
+```ts
+interface SharedDataSelectListProps<TItem> {
+  dataKey: string;
+  value?: unknown[];
+  onValueChange?: (value: unknown[]) => void;
+  // ...list configuration props
+}
+```
+
+### Sub-components
+
+- **`SharedDataSelectList.ItemTemplate`** -- Render template for list items.
+
+## DataSelectButton
+
+Button that opens a custom data selection dialog. Generic over key type and dialog props.
+
+```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;
+}
+
+interface DataSelectDialogResult<TKey> {
+  selectedKeys: TKey[];
+}
+
+interface SelectDialogBaseProps<TKey> {
+  close?: (result?: DataSelectDialogResult<TKey>) => void;
+  initialSelectedKeys?: TKey[];
+  selectionMode?: "single" | "multiple";
+}
+```
+
+## CrudSheet
+
+Full-featured CRUD data grid combining DataSheet with search, pagination, sorting, inline/dialog editing, selection, and Excel import/export.
+
+```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> {
+  items: TItem[];
+  pageCount?: number;
+}
+
+interface InlineEditConfig<TItem> {
+  submit: (diffs: ArrayOneWayDiffResult<TItem>[]) => Promise<void>;
+  newItem: () => TItem;
+  deleteProp?: keyof TItem & string;
+  diffsExcludes?: string[];
+}
+
+interface DialogEditConfig<TItem> {
+  editItem: (item?: TItem) => Promise<boolean | undefined>;
+  deleteItems?: (items: TItem[]) => Promise<boolean>;
+  restoreItems?: (items: TItem[]) => Promise<boolean>;
+}
+
+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;
+}
+
+interface CrudSheetCellContext<TItem> {
+  item: TItem;
+  index: number;
+  row: number;
+  depth: number;
+  setItem: <TKey extends keyof TItem>(key: TKey, value: TItem[TKey]) => void;
+}
+```
+
+- **`CrudSheet.Filter<TFilter>`** -- Filter panel slot.
+
+```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> {
+  items(): TItem[];
+  selection(): TItem[];
+  page(): number;
+  sorts(): SortingDef[];
+  busy(): boolean;
+  hasChanges(): boolean;
+  save(): Promise<void>;
+  refresh(): Promise<void>;
+  addItem(): void;
+  clearSelection(): void;
+  setPage(page: number): void;
+  setSorts(sorts: SortingDef[]): void;
+}
+```
+
+## CrudDetail
+
+CRUD detail form with load, save, delete, and change tracking.
+
+```ts
+interface CrudDetailProps<TData extends object> {
+  load: () => Promise<{ data: TData; info: CrudDetailInfo }>;
+  children: (ctx: CrudDetailContext<TData>) => JSX.Element;
+  submit?: (data: TData) => Promise<boolean | undefined>;
+  toggleDelete?: (del: boolean) => Promise<boolean | undefined>;
+  editable?: boolean;
+  deletable?: boolean;
+  data?: TData;
+  onDataChange?: (data: TData) => void;
+  close?: (result?: boolean) => void;
+  class?: string;
+}
+
+interface CrudDetailInfo {
+  isNew: boolean;
+  isDeleted: boolean;
+  lastModifiedAt?: DateTime;
+  lastModifiedBy?: string;
+}
+
+interface CrudDetailContext<TData> {
+  data: TData;
+  setData: SetStoreFunction<TData>;
+  info: () => CrudDetailInfo;
+  busy: () => boolean;
+  hasChanges: () => boolean;
+  save: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+```
+
+### Sub-components
+
+- **`CrudDetail.Header`** -- Header content slot.
+
+## PermissionTable
+
+Permission matrix table displaying app permissions with checkboxes.
+
+```ts
+interface PermissionTableProps<TModule = string> {
+  perms: AppPerm<TModule>[];
+  value?: string[];
+  onValueChange?: (value: string[]) => void;
+  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[];
+```