@simplysm/solid 13.0.0-beta.6 → 13.0.1

package/docs/hooks.md

@@ -0,0 +1,313 @@
+# Hooks
+
+## createPwaUpdate
+
+PWA Service Worker update detection hook. Automatically polls for Service Worker updates every 5 minutes. When a new version is detected, shows a notification with a reload action button.
+
+**Automatic Integration:** Already integrated into `InitializeProvider` -- no manual setup required for most applications. The hook runs automatically inside the notification system.
+
+**Manual Usage (Custom Provider Tree):**
+
+```tsx
+import { createPwaUpdate } from "@simplysm/solid";
+
+function MyProvider(props) {
+  // Must be called inside NotificationProvider
+  createPwaUpdate();
+
+  return (
+    <NotificationProvider>
+      {props.children}
+    </NotificationProvider>
+  );
+}
+```
+
+**Graceful No-ops:** Works safely in the following scenarios where Service Workers are unavailable:
+- HTTP protocol (non-HTTPS dev servers)
+- Browsers that don't support Service Workers
+- Development/test environments without SW registration
+
+**Requirements:**
+- Must be called inside `NotificationProvider` (to display the update notification)
+- `InitializeProvider` already includes both, so manual setup only needed for custom provider trees
+
+---
+
+## useTheme
+
+Hook to access theme (dark/light/system) state. Must be used inside `InitializeProvider`.
+
+```tsx
+import { useTheme } from "@simplysm/solid";
+
+const theme = useTheme();
+theme.mode();          // "light" | "dark" | "system"
+theme.resolvedTheme(); // "light" | "dark" (follows OS setting when system)
+theme.setMode("dark");
+theme.cycleMode();     // light -> system -> dark -> light
+```
+
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `mode` | `() => ThemeMode` | Current theme mode |
+| `resolvedTheme` | `() => ResolvedTheme` | Actual applied theme |
+| `setMode` | `(mode: ThemeMode) => void` | Set theme mode |
+| `cycleMode` | `() => void` | Cycle to next mode |
+
+---
+
+## useLocalStorage
+
+Local-only persistent storage hook. Always uses `localStorage` regardless of `syncStorage` setting. Keys are automatically prefixed as `{clientName}.{key}`. Use for data that should never leave the device (auth tokens, device-specific state).
+
+```tsx
+import { useLocalStorage } from "@simplysm/solid";
+
+const [token, setToken] = useLocalStorage<string | undefined>("auth-token", undefined);
+```
+
+| Return value | Type | Description |
+|--------------|------|-------------|
+| `[0]` | `Accessor<T>` | Value getter |
+| `[1]` | `Setter<T>` | Value setter |
+
+---
+
+## useSyncConfig
+
+Syncable config hook. Uses `syncStorage` if configured, falls back to `localStorage` otherwise. Keys are automatically prefixed as `{clientName}.{key}`. Use for user preferences that should sync across devices (theme, DataSheet column configs, filter presets).
+
+```tsx
+import { useSyncConfig } from "@simplysm/solid";
+
+const [theme, setTheme, loading] = useSyncConfig("theme", "light");
+
+// loading state is useful when syncStorage is async (e.g., DB-backed)
+// When syncStorage is not configured, loading is always false
+```
+
+| Return value | Type | Description |
+|--------------|------|-------------|
+| `[0]` | `Accessor<T>` | Value getter |
+| `[1]` | `Setter<T>` | Value setter |
+| `[2]` | `Accessor<boolean>` | Loading state (async storage only) |
+
+---
+
+## useLogger
+
+Logging hook. If `logger` adapter is configured in `AppConfig`, logs are sent to the adapter only. Otherwise, logs fall back to `consola`. Must be used inside `InitializeProvider`.
+
+```tsx
+import { useLogger } from "@simplysm/solid";
+
+const logger = useLogger();
+logger.log("user action", { userId: 123 });
+logger.info("app started");
+logger.error("something failed", errorObj);
+logger.warn("deprecation notice");
+```
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `log` | `(...args: unknown[]) => void` | Log message (general) |
+| `info` | `(...args: unknown[]) => void` | Log message (informational) |
+| `warn` | `(...args: unknown[]) => void` | Log message (warning) |
+| `error` | `(...args: unknown[]) => void` | Log message (error) |
+
+**Global error capturing:** `InitializeProvider` automatically captures uncaught errors (`window.onerror`) and unhandled promise rejections (`unhandledrejection`) and logs them via `useLogger`. No additional setup required.
+
+---
+
+## useNotification
+
+Hook to access notification system. Must be used inside `InitializeProvider`. See [Notification](feedback.md#notification) for detailed API.
+
+---
+
+## useLoading
+
+Hook to access loading overlay. Must be used inside `InitializeProvider`. See [Loading](feedback.md#loading) for detailed API.
+
+---
+
+## usePrint
+
+Hook for printing and PDF generation. Must be used inside `InitializeProvider`. See [Print / usePrint](feedback.md#print--useprint) for detailed API.
+
+---
+
+## useConfig
+
+Hook to access app-wide configuration. Must be used inside `InitializeProvider`.
+
+```tsx
+import { useConfig } from "@simplysm/solid";
+
+const config = useConfig();
+console.log(config.clientName); // "my-app"
+```
+
+---
+
+## createControllableSignal
+
+Signal hook that automatically handles Controlled/Uncontrolled patterns. Operates in controlled mode when `onChange` is provided, uncontrolled mode otherwise.
+
+```tsx
+import { createControllableSignal } from "@simplysm/solid";
+
+// Use inside components
+const [value, setValue] = createControllableSignal({
+  value: () => props.value ?? "",
+  onChange: () => props.onValueChange,
+});
+
+// Supports functional setter
+setValue((prev) => prev + "!");
+```
+
+---
+
+## createMountTransition
+
+Mount transition hook for open/close CSS animations. Control DOM rendering with `mounted()` and toggle CSS classes with `animating()`.
+
+```tsx
+import { createMountTransition } from "@simplysm/solid";
+
+const { mounted, animating, unmount } = createMountTransition(() => open());
+```
+
+| Return value | Type | Description |
+|--------------|------|-------------|
+| `mounted` | `() => boolean` | Whether mounted in DOM |
+| `animating` | `() => boolean` | Animation active state |
+| `unmount` | `() => void` | Manual unmount |
+
+---
+
+## createIMEHandler
+
+Hook that delays `onValueChange` calls during IME (Korean, etc.) composition to prevent interrupted input.
+
+---
+
+## useRouterLink
+
+`@solidjs/router`-based navigation hook. Automatically handles Ctrl/Alt + click (new tab), Shift + click (new window).
+
+```tsx
+import { useRouterLink } from "@simplysm/solid";
+
+const navigate = useRouterLink();
+
+<List.Item onClick={navigate({ href: "/home/dashboard" })}>
+  Dashboard
+</List.Item>
+
+// Pass state
+<List.Item onClick={navigate({ href: "/users/123", state: { from: "list" } })}>
+  User
+</List.Item>
+```
+
+---
+
+## createAppStructure
+
+Utility for declaratively defining app structure (routing, menus, permissions). Takes a single options object.
+
+```tsx
+import { createAppStructure, type AppStructureItem } from "@simplysm/solid";
+import { IconHome, IconUsers } from "@tabler/icons-solidjs";
+
+const items: AppStructureItem<string>[] = [
+  {
+    code: "home",
+    title: "Home",
+    icon: IconHome,
+    component: HomePage,
+    perms: ["use"],
+  },
+  {
+    code: "admin",
+    title: "Admin",
+    icon: IconUsers,
+    children: [
+      { code: "users", title: "User Management", component: UsersPage, perms: ["use", "edit"] },
+      { code: "roles", title: "Role Management", component: RolesPage, perms: ["use"], isNotMenu: true },
+    ],
+  },
+];
+
+const structure = createAppStructure({
+  items,
+  usableModules: () => activeModules(),  // optional: filter by active modules
+  permRecord: () => userPermissions(),   // optional: user permission state
+});
+
+// structure.routes         -- Route array (pass to @solidjs/router)
+// structure.usableMenus()  -- SidebarMenuItem[] for Sidebar.Menu
+// structure.usableFlatMenus() -- Flat menu list
+// structure.permRecord()   -- Record<string, boolean> permission state
+```
+
+**Routing integration with `@solidjs/router`:**
+
+```tsx
+import { render } from "solid-js/web";
+import { HashRouter, Navigate, Route } from "@solidjs/router";
+import { For } from "solid-js";
+import { appStructure } from "./appStructure";
+
+render(
+  () => (
+    <HashRouter>
+      <Route path="/" component={App}>
+        <Route path="/home" component={Home}>
+          <Route path="/" component={() => <Navigate href="/home/main" />} />
+          <For each={appStructure.routes}>
+            {(r) => <Route path={r.path} component={r.component} />}
+          </For>
+          <Route path="/*" component={NotFoundPage} />
+        </Route>
+        <Route path="/" component={() => <Navigate href="/home" />} />
+      </Route>
+    </HashRouter>
+  ),
+  document.getElementById("root")!,
+);
+```
+
+Each route object in `structure.routes` has `path` (derived from nested `code` values) and `component` properties, ready to pass directly to `<Route>`.
+
+**AppStructureItem types:**
+
+```typescript
+// Group item (has children, no component)
+interface AppStructureGroupItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  children: AppStructureItem<TModule>[];
+}
+
+// Leaf item (has component, no children)
+interface AppStructureLeafItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  component?: Component;
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPerm<TModule>[];
+  isNotMenu?: boolean;  // exclude from menu but include in routing
+}
+
+type AppStructureItem<TModule> = AppStructureGroupItem<TModule> | AppStructureLeafItem<TModule>;
+```

package/docs/layout.md

@@ -0,0 +1,289 @@
+# Layout Components
+
+## Sidebar
+
+Sidebar navigation with responsive support (mobile overlay below 520px). Open/closed state is in-memory only (resets on page refresh).
+
+```tsx
+import { Sidebar, Topbar } from "@simplysm/solid";
+import { useNavigate } from "@solidjs/router";
+
+const navigate = useNavigate();
+
+<Sidebar.Container>
+  <Sidebar>
+    <Sidebar.User
+      name="John Doe"
+      description="john@example.com"
+      menus={[
+        { title: "Profile", onClick: () => navigate("/profile") },
+        { title: "Logout", onClick: handleLogout },
+      ]}
+    />
+    <Sidebar.Menu menus={menuItems} />
+  </Sidebar>
+  <div class="flex flex-1 flex-col">
+    <Topbar>
+      <h1>App Name</h1>
+    </Topbar>
+    <main class="flex-1 overflow-auto p-4">
+      {/* main content */}
+    </main>
+  </div>
+</Sidebar.Container>
+```
+
+**Sub-components:**
+- `Sidebar.Container` -- Container wrapping sidebar and main area (required)
+- `Sidebar.Menu` -- Menu items list (`menus: SidebarMenuItem[]`)
+- `Sidebar.User` -- User info area with avatar and optional dropdown menu
+
+**Sidebar.User Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | **(required)** | User name |
+| `description` | `string` | - | Optional additional info (email, role, etc.). If omitted, only name is shown |
+| `icon` | `Component<TablerIconProps>` | `IconUser` | Avatar icon (Tabler Icons component). Rendered in a circular badge |
+| `menus` | `SidebarUserMenu[]` | - | Dropdown menu items. When present, component becomes clickable |
+
+**SidebarUserMenu type:**
+
+```typescript
+interface SidebarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+**SidebarMenuItem type:**
+
+```typescript
+interface SidebarMenuItem {
+  title: string;
+  href?: string;
+  icon?: Component<IconProps>;
+  children?: SidebarMenuItem[];
+}
+```
+
+**useSidebarContext hook:**
+
+```tsx
+import { useSidebarContext } from "@simplysm/solid";
+
+const sidebar = useSidebarContext();
+sidebar.toggle();          // current open/closed state
+sidebar.setToggle(false);  // programmatically close
+```
+
+---
+
+## Topbar
+
+Top navigation bar. When used inside `Sidebar.Container`, a sidebar toggle button appears automatically.
+
+```tsx
+import { Topbar } from "@simplysm/solid";
+import { IconSettings, IconUser } from "@tabler/icons-solidjs";
+
+const menuItems: TopbarMenuItem[] = [
+  { title: "Settings", icon: IconSettings, href: "/settings" },
+  {
+    title: "Admin",
+    icon: IconUser,
+    children: [
+      { title: "Users", href: "/admin/users" },
+      { title: "Roles", href: "/admin/roles" },
+    ],
+  },
+];
+
+const userMenus: TopbarUserMenu[] = [
+  { title: "Profile", onClick: () => navigate("/profile") },
+  { title: "Logout", onClick: handleLogout },
+];
+
+<Topbar>
+  <h1 class="text-lg font-bold">App Name</h1>
+  <Topbar.Menu menus={menuItems} />
+  <div class="flex-1" />
+  <Topbar.User menus={userMenus}>User</Topbar.User>
+</Topbar>
+```
+
+**Sub-components:**
+- `Topbar.Container` -- Container wrapping main content below topbar
+- `Topbar.Menu` -- Menu items list
+- `Topbar.User` -- User menu (dropdown)
+
+**TopbarMenuItem type:**
+
+```typescript
+interface TopbarMenuItem {
+  title: string;
+  href?: string;
+  icon?: Component<IconProps>;
+  children?: TopbarMenuItem[];  // supports unlimited nesting
+}
+```
+
+**TopbarUserMenu type:**
+
+```typescript
+interface TopbarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+---
+
+## FormGroup
+
+Layout component for arranging form fields with labels vertically or inline.
+
+```tsx
+import { FormGroup, TextInput } from "@simplysm/solid";
+
+// Vertical layout (default)
+<FormGroup>
+  <FormGroup.Item label="Name">
+    <TextInput value={name()} onValueChange={setName} />
+  </FormGroup.Item>
+  <FormGroup.Item label="Email">
+    <TextInput type="email" value={email()} onValueChange={setEmail} />
+  </FormGroup.Item>
+</FormGroup>
+
+// Inline layout
+<FormGroup inline>
+  <FormGroup.Item label="Search">
+    <TextInput value={query()} onValueChange={setQuery} />
+  </FormGroup.Item>
+  <FormGroup.Item>
+    <Button theme="primary">Search</Button>
+  </FormGroup.Item>
+</FormGroup>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `inline` | `boolean` | `false` | Inline layout mode |
+
+**Sub-components:**
+- `FormGroup.Item` -- Form item (`label?: JSX.Element`)
+
+---
+
+## FormTable
+
+`<table>`-based form layout. Labels go in `<th>`, input fields in `<td>`.
+
+```tsx
+import { FormTable, TextInput, NumberInput } from "@simplysm/solid";
+
+<FormTable>
+  <tbody>
+    <tr>
+      <th>Name</th>
+      <td><TextInput value={name()} onValueChange={setName} /></td>
+      <th>Age</th>
+      <td><NumberInput value={age()} onValueChange={setAge} /></td>
+    </tr>
+    <tr>
+      <th>Email</th>
+      <td colSpan={3}><TextInput type="email" value={email()} onValueChange={setEmail} /></td>
+    </tr>
+  </tbody>
+</FormTable>
+```
+
+---
+
+## Kanban
+
+Kanban board layout component with drag-and-drop cards, lane collapse, multi-select, and loading states.
+
+```tsx
+import { createSignal, For } from "solid-js";
+import { Button, Icon, Kanban, type KanbanDropInfo } from "@simplysm/solid";
+import { IconPlus } from "@tabler/icons-solidjs";
+
+const [selected, setSelected] = createSignal<unknown[]>([]);
+
+const handleDrop = (info: KanbanDropInfo) => {
+  // info.sourceValue: dragged card value
+  // info.targetLaneValue: target lane value
+  // info.targetCardValue: target card value (undefined if dropped on empty area)
+  // info.position: "before" | "after" | undefined
+  moveCard(info);
+};
+
+<div class="h-[500px]">
+  <Kanban
+    selectedValues={selected()}
+    onSelectedValuesChange={setSelected}
+    onDrop={handleDrop}
+  >
+    <For each={lanes()}>
+      {(lane) => (
+        <Kanban.Lane value={lane.id} collapsible busy={lane.loading}>
+          <Kanban.LaneTitle>
+            {lane.title} ({lane.cards.length})
+          </Kanban.LaneTitle>
+          <Kanban.LaneTools>
+            <Button size="sm" variant="ghost">
+              <Icon icon={IconPlus} />
+            </Button>
+          </Kanban.LaneTools>
+          <For each={lane.cards}>
+            {(card) => (
+              <Kanban.Card value={card.id} selectable draggable contentClass="p-2">
+                {card.title}
+              </Kanban.Card>
+            )}
+          </For>
+        </Kanban.Lane>
+      )}
+    </For>
+  </Kanban>
+</div>
+```
+
+**Kanban Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onDrop` | `(info: KanbanDropInfo) => void` | - | Drop event handler |
+| `selectedValues` | `unknown[]` | - | Selected card values |
+| `onSelectedValuesChange` | `(values: unknown[]) => void` | - | Selection change callback |
+
+`KanbanDropInfo`: `{ sourceValue: unknown; targetLaneValue: unknown; targetCardValue: unknown | undefined; position: "before" | "after" | undefined }`
+
+**Kanban.Lane Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `unknown` | - | Lane identifier |
+| `busy` | `boolean` | - | Show loading bar |
+| `collapsible` | `boolean` | - | Allow collapse/expand |
+| `collapsed` | `boolean` | - | Collapsed state (controlled) |
+| `onCollapsedChange` | `(collapsed: boolean) => void` | - | Collapse state callback |
+
+**Kanban.Card Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `unknown` | - | Card identifier |
+| `draggable` | `boolean` | `true` | Enable drag |
+| `selectable` | `boolean` | `false` | Enable selection |
+| `contentClass` | `string` | - | Card content class |
+
+**Sub-components:**
+- `Kanban.Lane` -- Board lane/column
+- `Kanban.LaneTitle` -- Lane header title area
+- `Kanban.LaneTools` -- Lane header action buttons
+- `Kanban.Card` -- Draggable card
+
+**Selection:** Shift+Click for multi-select, long press for single select. Lane header checkbox toggles all cards in the lane.

package/docs/providers.md

@@ -0,0 +1,35 @@
+# Providers
+
+## InitializeProvider
+
+Root provider that wraps the entire application. Automatically sets up all required providers: configuration context, theme (dark/light/system), notification system with banner, global error capturing (window.onerror, unhandledrejection), loading overlay, and programmatic dialog support.
+
+See [Getting Started](getting-started.md#provider-setup) for setup instructions and `AppConfig` options.
+
+---
+
+## ServiceClientProvider
+
+WebSocket client provider for RPC communication with `@simplysm/service-server`. Wraps `ServiceClient` from `@simplysm/service-client`.
+
+```tsx
+import { ServiceClientProvider } from "@simplysm/solid";
+
+<ServiceClientProvider url="ws://localhost:3000">
+  <App />
+</ServiceClientProvider>
+```
+
+---
+
+## SharedDataProvider
+
+Shared data provider for managing server-side data subscriptions. Works with `ServiceClientProvider` to provide reactive shared data across components.
+
+```tsx
+import { SharedDataProvider, SharedDataChangeEvent } from "@simplysm/solid";
+
+<SharedDataProvider>
+  <App />
+</SharedDataProvider>
+```

package/docs/styling.md

@@ -0,0 +1,67 @@
+# Styling & Tailwind Theme
+
+`@simplysm/solid` provides the following custom themes via Tailwind CSS preset.
+
+## Semantic Colors
+
+| Name | Base Color | Usage |
+|------|------------|-------|
+| `primary` | blue | Primary actions |
+| `info` | sky | Information |
+| `success` | green | Success |
+| `warning` | amber | Warning |
+| `danger` | red | Danger/error |
+| `base` | zinc | Neutral (backgrounds, borders, secondary text, etc.) |
+
+> Use `base-*` instead of directly using `zinc-*`.
+
+## Custom Sizes
+
+| Class | Description |
+|-------|-------------|
+| `h-field` / `size-field` | Default field height (based on `py-1`) |
+| `h-field-sm` / `size-field-sm` | Small field height (based on `py-0.5`) |
+| `h-field-lg` / `size-field-lg` | Large field height (based on `py-2`) |
+| `h-field-inset` / `size-field-inset` | Inset field height (excludes border) |
+| `h-field-inset-sm` / `size-field-inset-sm` | Small inset field height |
+| `h-field-inset-lg` / `size-field-inset-lg` | Large inset field height |
+
+## z-index Layers
+
+| Class | Value | Description |
+|-------|-------|-------------|
+| `z-sidebar` | 100 | Sidebar |
+| `z-sidebar-backdrop` | 99 | Sidebar backdrop |
+| `z-busy` | 500 | Loading overlay |
+| `z-dropdown` | 1000 | Dropdown popup |
+| `z-modal-backdrop` | 1999 | Modal backdrop |
+| `z-modal` | 2000 | Modal dialog |
+
+## Dark Mode
+
+Uses Tailwind's `class` strategy. `InitializeProvider` automatically toggles the `dark` class on the `<html>` element via the built-in theme provider.
+
+```html
+<!-- Light mode -->
+<html>
+<!-- Dark mode -->
+<html class="dark">
+```
+
+## Styling Patterns
+
+When using Tailwind classes in components, group them by semantic units with `clsx` and resolve conflicts with `twMerge`:
+
+```typescript
+import clsx from "clsx";
+import { twMerge } from "tailwind-merge";
+
+const baseClass = clsx(
+  "inline-flex items-center",
+  "px-2 py-1",
+  "rounded",
+  "border border-transparent",
+);
+
+const className = twMerge(baseClass, props.class);
+```