@simplysm/solid 13.0.98 → 13.0.100

package/docs/layout.md

@@ -1,143 +1,177 @@
-# Layout
+# Layout Components
 
-Source: `src/components/layout/**/*.tsx`
+Source: `src/components/layout/**`
 
-## FormGroup
+## `FormGroup`
 
-Vertical or inline form field group.
+Vertical or inline form field grouping component.
 
-```ts
-interface FormGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
-  inline?: boolean;  // horizontal layout with wrapping
+```typescript
+export interface FormGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  inline?: boolean;
 }
 ```
 
+| Prop | Type | Description |
+|------|------|-------------|
+| `inline` | `boolean` | Display items horizontally in a row |
+
 ### Sub-components
 
-- **`FormGroup.Item`** -- Labeled form item.
+- **`FormGroup.Item`** -- Individual form field with optional label
 
-```ts
-interface FormGroupItemProps extends JSX.HTMLAttributes<HTMLDivElement> {
+```typescript
+export interface FormGroupItemProps extends JSX.HTMLAttributes<HTMLDivElement> {
   label?: JSX.Element;
 }
 ```
 
-## FormTable
+---
+
+## `FormTable`
 
-Table-based form layout using `<table>` elements.
+Table-based form layout with label-value pairs.
 
-```ts
-interface FormTableProps extends JSX.HTMLAttributes<HTMLTableElement> {}
+```typescript
+export interface FormTableProps extends JSX.HTMLAttributes<HTMLTableElement> {}
 ```
 
 ### Sub-components
 
-- **`FormTable.Row`** -- Table row. Extends `JSX.HTMLAttributes<HTMLTableRowElement>`.
-- **`FormTable.Item`** -- Labeled table cell. When `label` is omitted, the cell spans the label column.
+- **`FormTable.Row`** -- Table row wrapper
+- **`FormTable.Item`** -- Table cell with optional label (`th` + `td`)
 
-```ts
-interface FormTableItemProps extends JSX.TdHTMLAttributes<HTMLTableCellElement> {
+```typescript
+export interface FormTableItemProps extends JSX.TdHTMLAttributes<HTMLTableCellElement> {
   label?: JSX.Element;
 }
 ```
 
-## Sidebar
+---
+
+## `Sidebar`
 
-Collapsible sidebar panel. Must be used inside `Sidebar.Container`.
+Responsive sidebar navigation with user info and menu sections. Collapses on mobile with overlay backdrop.
 
-```ts
-interface SidebarProps extends JSX.HTMLAttributes<HTMLElement> {
+```typescript
+export interface SidebarProps extends JSX.HTMLAttributes<HTMLElement> {
   children: JSX.Element;
 }
 ```
 
-### Sidebar.Container
+### Sub-components
+
+- **`Sidebar.Container`** -- Root container providing sidebar context and responsive padding
+- **`Sidebar.Menu`** -- Recursive menu list with pathname-based selection
+- **`Sidebar.User`** -- User info section with optional dropdown menus
 
-Layout container that holds the Sidebar and content area. Provides `SidebarContext` for toggle state. Parent element must have height specified (use `h-full`).
+### `Sidebar.Container`
 
-```ts
-interface SidebarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+```typescript
+export interface SidebarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
   children: JSX.Element;
 }
 ```
 
-- Desktop (640px+): uses `padding-left` transition to expand/collapse.
-- Mobile (<640px): renders backdrop overlay. Auto-closes on navigation.
+### `Sidebar.Menu`
 
-### Sidebar.Menu
-
-Recursive sidebar menu with route-based selection.
-
-```ts
-interface SidebarMenuProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
+```typescript
+export interface SidebarMenuProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
   menus: AppMenu[];
-  defaultOpen?: boolean;  // expand all nested menus on initial render (default: false)
+  defaultOpen?: boolean;
 }
 ```
 
-- Parent items of the selected route auto-expand on initial render.
-- External links (containing `://`) open in a new tab.
+| Prop | Type | Description |
+|------|------|-------------|
+| `menus` | `AppMenu[]` | Menu items array |
+| `defaultOpen` | `boolean` | Expand all nested menus initially. Default: `false` |
 
-### Sidebar.User
+### `Sidebar.User`
 
-User information area with optional dropdown menu.
-
-```ts
-interface SidebarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+```typescript
+export interface SidebarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
   name: string;
   icon?: Component<TablerIconProps>;
   description?: string;
   menus?: SidebarUserMenu[];
 }
+```
 
-interface SidebarUserMenu {
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | `string` | User name (required) |
+| `icon` | `Component<TablerIconProps>` | Avatar icon. Default: user icon |
+| `description` | `string` | Additional info (email, etc.) |
+| `menus` | `SidebarUserMenu[]` | Dropdown menu items |
+
+### `SidebarUserMenu`
+
+```typescript
+export interface SidebarUserMenu {
   title: string;
   onClick: () => void;
 }
 ```
 
-### useSidebar()
+### `SidebarContextValue`
 
-Hook to access sidebar toggle state. Throws if used outside `Sidebar.Container`.
-
-```ts
-function useSidebar(): {
+```typescript
+export interface SidebarContextValue {
   toggle: Accessor<boolean>;
   setToggle: Setter<boolean>;
-};
-// Also available: useSidebar.optional() returns undefined if no context
+}
 ```
 
-## Topbar
+### `useSidebar`
+
+Hook to access sidebar toggle state. Also has `useSidebar.optional()` variant.
+
+### `SM_MEDIA_QUERY`
+
+```typescript
+export const SM_MEDIA_QUERY = "(min-width: 640px)";
+```
 
-Top navigation bar. Automatically shows a sidebar toggle button if used inside `Sidebar.Container`.
+---
 
-```ts
-interface TopbarProps extends JSX.HTMLAttributes<HTMLElement> {
+## `Topbar`
+
+Top navigation bar with sidebar toggle integration, dropdown menus, user section, and dynamic actions.
+
+```typescript
+export interface TopbarProps extends JSX.HTMLAttributes<HTMLElement> {
   children: JSX.Element;
 }
 ```
 
-### Topbar.Container
+### Sub-components
+
+- **`Topbar.Container`** -- Layout container wrapping Topbar and content, provides actions context
+- **`Topbar.Menu`** -- Dropdown navigation menu (responsive: desktop buttons / mobile hamburger)
+- **`Topbar.User`** -- User information section with optional dropdown
+- **`Topbar.Actions`** -- Renders actions set via `useTopbarActions()`
 
-Vertical layout container wrapping Topbar and content area. Provides `TopbarContext` for actions.
+### `Topbar.Container`
 
-```ts
-interface TopbarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+```typescript
+export interface TopbarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
   children: JSX.Element;
 }
 ```
 
-### Topbar.Menu
+### `Topbar.Menu`
 
-Dropdown navigation menu. Shows desktop buttons on 640px+ and a hamburger menu on mobile.
-
-```ts
-interface TopbarMenuProps extends Omit<JSX.HTMLAttributes<HTMLElement>, "children"> {
+```typescript
+export interface TopbarMenuProps extends Omit<JSX.HTMLAttributes<HTMLElement>, "children"> {
   menus: TopbarMenuItem[];
 }
+```
 
-interface TopbarMenuItem {
+### `TopbarMenuItem`
+
+```typescript
+export interface TopbarMenuItem {
   title: string;
   href?: string;
   icon?: Component<IconProps>;
@@ -145,38 +179,34 @@ interface TopbarMenuItem {
 }
 ```
 
-### Topbar.User
-
-User information component with optional dropdown menu.
+### `Topbar.User`
 
-```ts
-interface TopbarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+```typescript
+export interface TopbarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
   menus?: TopbarUserMenu[];
   children: JSX.Element;
 }
+```
+
+### `TopbarUserMenu`
 
-interface TopbarUserMenu {
+```typescript
+export interface TopbarUserMenu {
   title: string;
   onClick: () => void;
 }
 ```
 
-### Topbar.Actions
-
-Renders action elements registered by `useTopbarActions()`.
-
-### useTopbarActions()
+### `TopbarContextValue`
 
-Register action elements that appear in the Topbar. Automatically cleaned up on component unmount.
-
-```ts
-function useTopbarActions(accessor: () => JSX.Element): void;
+```typescript
+export interface TopbarContextValue {
+  actions: Accessor<JSX.Element | undefined>;
+  setActions: Setter<JSX.Element | undefined>;
+}
 ```
 
-### useTopbarActionsAccessor()
+### Hooks
 
-Read the current topbar actions signal.
-
-```ts
-function useTopbarActionsAccessor(): Accessor<JSX.Element | undefined>;
-```
+- **`useTopbarActions(accessor: () => JSX.Element)`** -- Register dynamic actions for display in Topbar
+- **`useTopbarActionsAccessor()`** -- Read registered actions

package/docs/providers.md

@@ -1,177 +1,197 @@
 # Providers
 
-Source: `src/providers/**/*.tsx`
+Source: `src/providers/**`
 
-## ConfigContext / ConfigProvider
+## `ConfigProvider`
 
-App-level configuration providing the `clientName` used as a prefix for storage keys.
+App-wide configuration context providing `clientName` used as storage key prefix.
 
-```ts
-interface AppConfig {
+```typescript
+export interface AppConfig {
   clientName: string;
 }
 
-const ConfigContext: Context<AppConfig>;
-
-function useConfig(): AppConfig;
-
-const ConfigProvider: ParentComponent<{ clientName: string }>;
+export const ConfigContext: Context<AppConfig>;
+export function useConfig(): AppConfig;
+export const ConfigProvider: ParentComponent<{ clientName: string }>;
 ```
 
-## SyncStorageProvider / useSyncStorage
+---
 
-Pluggable storage provider. Components use this adapter for persistent storage (localStorage fallback when no adapter is configured).
+## `SyncStorageProvider`
 
-```ts
-interface StorageAdapter {
-  getItem: (key: string) => Promise<string | null>;
-  setItem: (key: string, value: string) => Promise<void>;
-  removeItem: (key: string) => Promise<void>;
-}
+Sync storage provider with configurable adapter (defaults to localStorage). Supports async adapters for cross-device sync.
 
-interface SyncStorageContextValue {
-  adapter: Accessor<StorageAdapter | undefined>;
-  configure: (adapter: StorageAdapter | undefined) => void;
+```typescript
+export interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<unknown>;
+  removeItem(key: string): void | Promise<void>;
 }
 
-const SyncStorageContext: Context<SyncStorageContextValue>;
-
-function useSyncStorage(): SyncStorageContextValue | undefined;
+export interface SyncStorageContextValue {
+  adapter: Accessor<StorageAdapter>;
+  configure: (fn: (origin: StorageAdapter) => StorageAdapter) => void;
+}
 
-const SyncStorageProvider: ParentComponent;
+export const SyncStorageContext: Context<SyncStorageContextValue>;
+export function useSyncStorage(): SyncStorageContextValue | undefined;
+export const SyncStorageProvider: ParentComponent;
 ```
 
-## LoggerProvider
+---
+
+## `LoggerProvider`
 
-Logging adapter provider. Allows plugging in custom log writers.
+Logger adapter provider. Defaults to consola. Configurable via decorator pattern.
 
-```ts
-interface LogAdapter {
-  write: (level: "log" | "info" | "warn" | "error", ...args: unknown[]) => void | Promise<void>;
+```typescript
+export interface LogAdapter {
+  write(severity: "error" | "warn" | "info" | "log", ...data: any[]): Promise<void> | void;
 }
 
-interface LoggerContextValue {
-  adapter: Accessor<LogAdapter | undefined>;
+export interface LoggerContextValue {
+  adapter: Accessor<LogAdapter>;
   configure: (fn: (origin: LogAdapter) => LogAdapter) => void;
 }
 
-const LoggerContext: Context<LoggerContextValue>;
-
-const LoggerProvider: ParentComponent;
+export const LoggerContext: Context<LoggerContextValue>;
+export const LoggerProvider: ParentComponent;
 ```
 
-## ThemeContext / ThemeProvider / useTheme
+---
+
+## `ThemeProvider`
 
-Light/dark/system theme management. Persists mode to synced storage.
+Theme mode provider with OS dark mode detection. Persists to storage via `useSyncConfig`. Toggles `dark` class on `<html>`.
 
-```ts
-type ThemeMode = "light" | "dark" | "system";
-type ResolvedTheme = "light" | "dark";
+```typescript
+export type ThemeMode = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
 
-interface ThemeContextValue {
-  mode: Accessor<ThemeMode>;
-  resolved: Accessor<ResolvedTheme>;
+export function useTheme(): {
+  mode: () => ThemeMode;
   setMode: (mode: ThemeMode) => void;
+  resolvedTheme: () => ResolvedTheme;
   cycleMode: () => void;
-}
+};
 
-function useTheme(): ThemeContextValue;
-
-const ThemeProvider: ParentComponent;
+export const ThemeProvider: ParentComponent;
 ```
 
-- `cycleMode()`: light -> system -> dark -> light.
-- `resolved`: the actual applied theme after resolving "system" via `prefers-color-scheme`.
+---
 
-## ServiceClientProvider / useServiceClient
+## `ServiceClientProvider`
 
-Service client connection provider for `@simplysm/service-client`.
+WebSocket service client provider with key-based multi-connection management. Displays request/response progress via notifications.
 
-```ts
-interface ServiceClientContextValue {
-  client: Accessor<SdServiceClient | undefined>;
-  connected: Accessor<boolean>;
-  configure: (url: string) => void;
+```typescript
+export interface ServiceClientContextValue {
+  connect: (key?: string, options?: Partial<ServiceConnectionOptions>) => Promise<void>;
+  close: (key?: string) => Promise<void>;
+  get: (key?: string) => ServiceClient;
+  isConnected: (key?: string) => boolean;
 }
 
-const ServiceClientContext: Context<ServiceClientContextValue>;
+export const ServiceClientContext: Context<ServiceClientContextValue>;
+export function useServiceClient(): ServiceClientContextValue;
+export const ServiceClientProvider: ParentComponent;
+```
 
-function useServiceClient(): ServiceClientContextValue;
+---
 
-const ServiceClientProvider: ParentComponent;
-```
+## `SharedDataProvider`
 
-## SystemProvider
+Reactive shared data provider that subscribes to server events for real-time data updates.
 
-Composite provider that bundles commonly used providers together.
+### `SharedDataDefinition`
 
-```ts
-const SystemProvider: ParentComponent<{
-  clientName: string;
-  busyVariant?: BusyVariant;
-}>;
+```typescript
+export interface SharedDataDefinition<TData> {
+  serviceKey?: string;
+  fetch: (changeKeys?: Array<string | number>) => Promise<TData[]>;
+  getKey: (item: TData) => string | number;
+  orderBy: [(item: TData) => unknown, "asc" | "desc"][];
+  filter?: unknown;
+  itemSearchText?: (item: TData) => string;
+  isItemHidden?: (item: TData) => boolean;
+  getParentKey?: (item: TData) => string | number | undefined;
+}
 ```
 
-Internally wraps: `ConfigProvider`, `I18nProvider`, `SyncStorageProvider`, `LoggerProvider`, `ThemeProvider`, `BusyProvider`, `NotificationProvider`, `DialogProvider`, `PrintProvider`, `ErrorLoggerProvider`, `ClipboardProvider`, `PwaUpdateProvider`.
+### `SharedDataAccessor`
 
-## I18nProvider / useI18n
+```typescript
+export interface SharedDataAccessor<TData> {
+  items: Accessor<TData[]>;
+  get: (key: string | number | undefined) => TData | undefined;
+  emit: (changeKeys?: Array<string | number>) => Promise<void>;
+  getKey: (item: TData) => string | number;
+  itemSearchText?: (item: TData) => string;
+  isItemHidden?: (item: TData) => boolean;
+  getParentKey?: (item: TData) => string | number | undefined;
+}
+```
 
-Internationalization provider with flat dictionary-based translations.
+---
 
-```ts
-interface I18nContextValue {
-  locale: Accessor<string>;
-  t: (key: string, params?: Record<string, string>) => string;
-  configure: (options: I18nConfigureOptions) => void;
-}
+## `SharedDataChangeEvent`
 
-interface I18nConfigureOptions {
-  locale?: string;
-  dict?: Record<string, unknown>;  // nested dict, auto-flattened
-  flatDict?: FlatDict;             // pre-flattened dict
-}
+Server-client shared data change event definition.
+
+```typescript
+export const SharedDataChangeEvent: EventDefinition<
+  { name: string; filter: unknown },
+  (string | number)[] | undefined
+>;
+```
 
-type FlatDict = Record<string, string>;
+---
 
-function useI18n(): I18nContextValue;
+## `SystemProvider`
 
-const I18nProvider: ParentComponent;
+All-in-one provider that composes Config, I18n, SyncStorage, Logger, Notification, ErrorLogger, PwaUpdate, Clipboard, Theme, ServiceClient, SharedData, and Busy providers.
+
+```typescript
+export const SystemProvider: ParentComponent<{
+  clientName: string;
+  busyVariant?: BusyVariant;
+}>;
 ```
 
-- `t("key", { name: "value" })`: interpolates `{name}` placeholders.
-- `configure()`: merges new dictionaries into existing translations.
+---
 
-## SharedDataProvider / useSharedData
+## `I18nProvider`
 
-Shared data cache provider. Loads and caches data from service, auto-refreshes on change events.
+Internationalization provider with built-in `en` and `ko` dictionaries.
 
-```ts
-interface SharedDataDefinition<TData> {
-  key: string;
-  loader: () => Promise<TData[]>;
-  getKey: (item: TData) => string | number;
-  getSearchText?: (item: TData) => string;
-  getChildren?: (item: TData, allItems: TData[]) => TData[];
-}
+```typescript
+export function useI18n(): I18nContextValue;
+export const I18nProvider: ParentComponent;
+```
 
-interface SharedDataAccessor<TData> {
-  items: Accessor<TData[]>;
-  loading: Accessor<boolean>;
-  refresh: () => Promise<void>;
-  getByKey: (key: string | number) => TData | undefined;
+### `I18nContextValue`
+
+```typescript
+export interface I18nContextValue {
+  t: (key: string, params?: Record<string, string>) => string;
+  locale: Accessor<string>;
+  setLocale: (locale: string) => void;
+  configure: (options: I18nConfigureOptions) => void;
 }
+```
 
-function useSharedData<TSharedData extends Record<string, unknown>>(): SharedDataValue<TSharedData>;
+### `I18nConfigureOptions`
 
-function SharedDataProvider(props: { children: JSX.Element }): JSX.Element;
+```typescript
+export interface I18nConfigureOptions {
+  locale?: string;
+  dict?: Record<string, Record<string, unknown>>;
+}
 ```
 
-### SharedDataChangeEvent
+### `FlatDict`
 
-Event emitted when shared data changes, triggering refresh.
-
-```ts
-const SharedDataChangeEvent: EventDefinition<{
-  key: string;
-}>;
+```typescript
+export type FlatDict = Record<string, string>;
 ```