@simplysm/solid 13.0.69 → 13.0.71

package/docs/helpers.md

@@ -1,54 +0,0 @@
-# Helpers & Directives
-
-## mergeStyles
-
-Utility for merging inline style strings and `JSX.CSSProperties` objects.
-
-```typescript
-import { mergeStyles } from "@simplysm/solid";
-
-const style = mergeStyles("color: red", { fontSize: "14px" }, props.style);
-```
-
----
-
-## ripple directive
-
-Material Design ripple effect directive. Displays ripple effect on click.
-
-```tsx
-import { ripple } from "@simplysm/solid";
-// Keep reference to register directive
-void ripple;
-
-<button use:ripple={true}>Click</button>
-<button use:ripple={!props.disabled}>Conditional activation</button>
-```
-
-- Creates internal ripple container, operates without affecting parent element
-- Automatically disabled when `prefers-reduced-motion: reduce` is set
-- Single ripple mode: removes previous ripple on new click
-
----
-
-## createAppStructure
-
-See [createAppStructure](hooks.md#createappstructure) in the Hooks documentation for full API details.
-
-Exports the following types:
-
-```typescript
-import {
-  createAppStructure,
-  type AppStructure,
-  type AppStructureItem,
-  type AppStructureGroupItem,
-  type AppStructureLeafItem,
-  type AppStructureSubPerm,
-  type AppRoute,
-  type AppMenu,
-  type AppFlatMenu,
-  type AppPerm,
-  type AppFlatPerm,
-} from "@simplysm/solid";
-```

package/docs/hooks.md

@@ -1,588 +0,0 @@
-# Hooks
-
-## useTheme
-
-Hook to access theme (dark/light/system) state. Must be used inside `ThemeProvider`.
-
-```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>("auth-token");
-
-// Set value
-setToken("abc123");
-
-// Remove value
-setToken(undefined);
-
-// Functional update
-setToken((prev) => prev + "-refreshed");
-```
-
-| Return value | Type | Description |
-|--------------|------|-------------|
-| `[0]` | `Accessor<T \| undefined>` | Value getter |
-| `[1]` | `StorageSetter<T>` | Value setter (accepts value, `undefined` to remove, or updater function) |
-
----
-
-## useSyncConfig
-
-Syncable config hook. Uses `SyncStorageProvider` storage if present, 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, ready] = useSyncConfig("theme", "light");
-
-// ready state indicates initialization is complete
-// When syncStorage is not configured (localStorage), ready is immediately true
-```
-
-| Return value | Type | Description |
-|--------------|------|-------------|
-| `[0]` | `Accessor<T>` | Value getter |
-| `[1]` | `Setter<T>` | Value setter |
-| `[2]` | `Accessor<boolean>` | Ready state (`true` after initialization) |
-
----
-
-## useLogger
-
-Logging hook. If `LoggerProvider` is present, logs are sent to the adapter only. Otherwise, logs fall back to `consola`.
-
-```tsx
-import { useLogger, type Logger } from "@simplysm/solid";
-
-const logger: Logger = useLogger();
-logger.log("user action", { userId: 123 });
-logger.info("app started");
-logger.error("something failed", errorObj);
-logger.warn("deprecation notice");
-```
-
-**Logger interface:**
-
-| 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) |
-| `configure` | `(fn: (origin: LogAdapter) => LogAdapter) => void` | Set or wrap the log adapter (inside `LoggerProvider` only) |
-
-**Configuring a custom adapter (decorator pattern):**
-
-```tsx
-// Replace default consola adapter
-useLogger().configure((origin) => myLogAdapter);
-
-// Wrap default adapter (chaining)
-useLogger().configure((origin) => ({
-  write(severity, ...data) {
-    sendToServer(severity, ...data);
-    origin.write(severity, ...data);  // also log to consola
-  },
-}));
-```
-
-**Global error capturing:** `ErrorLoggerProvider` captures uncaught errors (`window.onerror`) and unhandled promise rejections (`unhandledrejection`) and logs them via `useLogger`.
-
----
-
-## useNotification
-
-Hook to access notification system. Must be used inside `NotificationProvider`. See [Notification](feedback.md#notification) for detailed API.
-
----
-
-## useBusy
-
-Hook to access busy overlay. Must be used inside `BusyProvider`. See [Busy](feedback.md#busy) for detailed API.
-
----
-
-## usePrint
-
-Hook for printing and PDF generation. Must be used inside `<PrintProvider>`. See [Print / usePrint](feedback.md#print--useprint) for detailed API.
-
----
-
-## useConfig
-
-Hook to access app-wide configuration. Must be used inside `ConfigProvider`.
-
-```tsx
-import { useConfig } from "@simplysm/solid";
-
-const config = useConfig();
-console.log(config.clientName); // "my-app"
-```
-
----
-
-## useServiceClient
-
-Hook to access the WebSocket service client context. Must be used inside `ServiceClientProvider`. See [ServiceClientProvider](providers.md#serviceclientprovider) for detailed API.
-
----
-
-## useSharedData
-
-Hook to access shared data managed by `SharedDataProvider`. Must be used inside `SharedDataProvider`. See [SharedDataProvider](providers.md#shareddataprovider) for detailed API.
-
----
-
-## 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 + "!");
-```
-
----
-
-## createControllableStore
-
-Store hook that automatically handles Controlled/Uncontrolled patterns for objects and arrays. Similar to `createControllableSignal` but uses SolidJS `createStore` internally, supporting path-based updates via `SetStoreFunction`.
-
-Operates in controlled mode when `onChange` is provided (setter calls `onChange` with cloned value), uncontrolled mode otherwise (internal store only).
-
-```tsx
-import { createControllableStore } from "@simplysm/solid";
-
-// Controlled mode (parent manages state)
-const [items, setItems] = createControllableStore<Item[]>({
-  value: () => props.items ?? [],
-  onChange: () => props.onItemsChange,
-});
-
-// Uncontrolled mode (internal state only)
-const [items, setItems] = createControllableStore<Item[]>({
-  value: () => [],
-  onChange: () => undefined,
-});
-
-// Supports all SetStoreFunction overloads
-setItems(0, "name", "updated");          // path-based update
-setItems(produce((draft) => { ... }));   // produce
-setItems(reconcile(newItems));           // reconcile
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `value` | `() => TValue` | Reactive value accessor (syncs external changes to internal store) |
-| `onChange` | `() => ((value: TValue) => void) \| undefined` | Change callback accessor. When defined, enables controlled mode |
-
-| Return | Type | Description |
-|--------|------|-------------|
-| `[0]` | `TValue` | Store (reactive proxy) |
-| `[1]` | `SetStoreFunction<TValue>` | Store setter (triggers `onChange` in controlled mode) |
-
----
-
-## 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 `setValue` calls during IME (Korean, CJK, etc.) composition to prevent interrupted input. Use inside contenteditable or custom input components.
-
-```tsx
-import { createIMEHandler } from "@simplysm/solid";
-
-const {
-  composingValue,
-  handleCompositionStart,
-  handleInput,
-  handleCompositionEnd,
-  flushComposition,
-} = createIMEHandler((value) => {
-  // called only when composition is complete
-  setMyValue(value);
-});
-
-// Wire up to DOM element events:
-<div
-  contentEditable
-  onCompositionStart={handleCompositionStart}
-  onCompositionEnd={(e) => handleCompositionEnd(e.currentTarget.textContent ?? "")}
-  onInput={(e) => handleInput(e.currentTarget.textContent ?? "", e.isComposing)}
-/>
-```
-
-| Return value | Type | Description |
-|--------------|------|-------------|
-| `composingValue` | `Accessor<string \| null>` | Current composing value (for display); `null` when not composing |
-| `handleCompositionStart` | `() => void` | Call on `compositionstart` event |
-| `handleInput` | `(value: string, isComposing: boolean) => void` | Call on `input` event |
-| `handleCompositionEnd` | `(value: string) => void` | Call on `compositionend` event |
-| `flushComposition` | `() => void` | Immediately commit any pending composition |
-
----
-
-## createSlotSignal
-
-Signal factory for slot registration pattern. Used internally by compound components (`SelectList`, etc.) to register child slot content.
-
-```tsx
-import { createSlotSignal, type SlotAccessor } from "@simplysm/solid";
-
-const [headerSlot, setHeader] = createSlotSignal();
-
-// Register slot content (typically from a sub-component)
-setHeader(() => <div>Header Content</div>);
-
-// Read slot content (in parent render)
-<Show when={headerSlot()}>
-  {headerSlot()!()}
-</Show>
-
-// Unregister
-setHeader(undefined);
-```
-
-| Return | Type | Description |
-|--------|------|-------------|
-| `[0]` | `Accessor<SlotAccessor>` | Slot accessor (`(() => JSX.Element) \| undefined`) |
-| `[1]` | `(content: SlotAccessor) => void` | Slot setter |
-
-**`SlotAccessor` type:** `(() => JSX.Element) | undefined`
-
----
-
-## useRouterLink
-
-`@solidjs/router`-based navigation hook. Automatically handles Ctrl/Alt + click (new tab), Shift + click (new window), and regular click (SPA routing).
-
-```tsx
-import { useRouterLink } from "@simplysm/solid";
-
-const navigate = useRouterLink();
-
-<List.Item onClick={navigate({ href: "/home/dashboard" })}>
-  Dashboard
-</List.Item>
-
-// Pass state (not visible in URL)
-<List.Item onClick={navigate({ href: "/users/123", state: { from: "list" } })}>
-  User
-</List.Item>
-
-// Custom new window size on Shift+click
-<List.Item onClick={navigate({ href: "/reports/pdf", window: { width: 1200, height: 900 } })}>
-  Report
-</List.Item>
-```
-
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `href` | `string` | (required) | Navigation path (fully-formed URL, e.g., `"/home/dashboard?tab=1"`) |
-| `state` | `Record<string, unknown>` | - | State to pass to the route (not exposed in URL) |
-| `window.width` | `number` | `800` | New window width (Shift+click) |
-| `window.height` | `number` | `800` | New window height (Shift+click) |
-
----
-
-## createAppStructure
-
-Utility for declaratively defining app structure (routing, menus, permissions). Takes a factory function and returns `{ AppStructureProvider, useAppStructure }` for Context-based access with full `InferPerms` type preservation.
-
-```tsx
-// appStructure.ts
-import { createAppStructure } from "@simplysm/solid";
-import { IconHome, IconUsers } from "@tabler/icons-solidjs";
-import { useAuth } from "./AuthProvider";
-
-export const { AppStructureProvider, useAppStructure } = createAppStructure(() => {
-  const auth = useAuth();
-  return {
-    items: [
-      {
-        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 },
-        ],
-      },
-    ],
-    usableModules: () => activeModules(),          // optional: filter by active modules
-    permRecord: () => auth.authInfo()?.permissions, // optional: Record<string, boolean>
-  };
-});
-```
-
-The factory function (`getOpts`) is called inside `AppStructureProvider` at render time, so context hooks like `useAuth()` can be used. The `const TItems` generic preserves item literal types for full `InferPerms` type inference.
-
-**Provider setup:**
-
-```tsx
-// main.tsx or App.tsx
-import { AppStructureProvider } from "./appStructure";
-
-render(
-  () => (
-    <AppStructureProvider>
-      <HashRouter>
-        {/* ... */}
-      </HashRouter>
-    </AppStructureProvider>
-  ),
-  document.getElementById("root")!,
-);
-```
-
-**Using the hook in components:**
-
-```tsx
-import { useAppStructure } from "./appStructure";
-
-function Home(props: RouteSectionProps) {
-  const appStructure = useAppStructure();
-
-  // appStructure.usableRoutes()      -- Accessor<AppRoute[]>
-  // appStructure.usableMenus()       -- Accessor<AppMenu[]>
-  // appStructure.usableFlatMenus()   -- Accessor<AppFlatMenu[]>
-  // appStructure.usablePerms()       -- Accessor<AppPerm[]>
-  // appStructure.allFlatPerms        -- AppFlatPerm[]
-  // appStructure.getTitleChainByHref(href) -- string[]
-  // appStructure.perms               -- typed permission accessor
-
-  return <Sidebar.Menu menus={appStructure.usableMenus()} />;
-}
-```
-
-**Routing integration with `@solidjs/router`:**
-
-```tsx
-import { useAppStructure } from "./appStructure";
-
-function HomeRoutes() {
-  const appStructure = useAppStructure();
-  return (
-    <For each={appStructure.usableRoutes()}>
-      {(r) => <Route path={r.path} component={r.component} />}
-    </For>
-  );
-}
-
-// In your router setup (inside AppStructureProvider):
-<Route path="/home" component={Home}>
-  <Route path="/" component={() => <Navigate href="/home/main" />} />
-  <HomeRoutes />
-  <Route path="/*" component={NotFoundPage} />
-</Route>
-```
-
-`usableRoutes()` is a reactive accessor returning routes filtered by `usableModules` and `permRecord`. Items with `perms: ["use"]` are excluded from routes when the user lacks the `use` permission.
-
-**AppStructure return type:**
-
-```typescript
-interface AppStructure<TModule> {
-  items: AppStructureItem<TModule>[];
-  usableRoutes: Accessor<AppRoute[]>;            // reactive, filtered by modules + permRecord
-  usableMenus: Accessor<AppMenu[]>;              // reactive, filtered by modules + permRecord
-  usableFlatMenus: Accessor<AppFlatMenu[]>;      // reactive, flat version of usableMenus
-  usablePerms: Accessor<AppPerm<TModule>[]>;     // reactive, filtered permission tree
-  allFlatPerms: AppFlatPerm<TModule>[];          // static, all perm entries (not reactive)
-  getTitleChainByHref(href: string): string[];
-  perms: InferPerms<TItems>;                     // typed permission accessor (getter-based reactive booleans)
-}
-
-interface AppRoute {
-  path: string;
-  component: Component;
-}
-
-interface AppMenu {
-  title: string;
-  href?: string;
-  icon?: Component<IconProps>;
-  children?: AppMenu[];
-}
-
-interface AppFlatMenu {
-  titleChain: string[];
-  href: string;
-}
-
-interface AppPerm<TModule = string> {
-  title: string;
-  href?: string;
-  modules?: TModule[];
-  perms?: string[];
-  children?: AppPerm<TModule>[];
-}
-
-interface AppFlatPerm<TModule = string> {
-  titleChain: string[];
-  code: string;
-  modulesChain: TModule[][];
-  requiredModulesChain: TModule[][];
-}
-```
-
-**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
-}
-
-// Sub-permission item
-interface AppStructureSubPerm<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  perms: ("use" | "edit")[];
-}
-
-type AppStructureItem<TModule> = AppStructureGroupItem<TModule> | AppStructureLeafItem<TModule>;
-```
-
-#### getTitleChainByHref
-
-Retrieves the breadcrumb title chain for a given href path. Works on raw items (including `isNotMenu` items).
-
-```tsx
-import { useLocation } from "@solidjs/router";
-import { useAppStructure } from "./appStructure";
-
-function Breadcrumb() {
-  const appStructure = useAppStructure();
-  const location = useLocation();
-
-  // Returns ["Sales", "Invoice"] for /home/sales/invoice
-  const breadcrumb = () => appStructure.getTitleChainByHref(location.pathname);
-
-  return <span>{breadcrumb().join(" > ")}</span>;
-}
-```
-
-#### perms
-
-Typed permission accessor providing dot-notation access with TypeScript autocompletion and reactive boolean values. Built from the `permRecord` signal using `Object.defineProperty` getters.
-
-**Important:** For type inference to work, pass items inline to `createAppStructure`. Declaring items as a separate variable with explicit `AppStructureItem[]` type annotation widens literal types, losing autocompletion.
-
-```typescript
-// appStructure.ts
-import { createAppStructure } from "@simplysm/solid";
-
-export const { AppStructureProvider, useAppStructure } = createAppStructure(() => ({
-  items: [
-    {
-      code: "home",
-      title: "Home",
-      children: [
-        {
-          code: "user",
-          title: "User",
-          perms: ["use", "edit"],
-          subPerms: [
-            { code: "auth", title: "Auth", perms: ["use"] },
-          ],
-        },
-      ],
-    },
-  ],
-  permRecord: () => userPermissions(),
-}));
-
-// In a component (inside AppStructureProvider):
-const appStructure = useAppStructure();
-
-// Typed access with autocompletion:
-appStructure.perms.home.user.use        // boolean (reactive)
-appStructure.perms.home.user.edit       // boolean (reactive)
-appStructure.perms.home.user.auth.use   // boolean (reactive)
-
-// Use in components:
-<Show when={appStructure.perms.home.user.use}>
-  <UserPage />
-</Show>
-```
-
-- Leaf items without `perms`/`subPerms` are excluded from the tree
-- Groups with no permission-bearing descendants are excluded
-- Returns `false` when `permRecord` is not provided or key is missing