@simplysm/solid 13.0.98 → 13.0.99

package/docs/helpers.md

@@ -1,41 +1,67 @@
 # Helpers
 
-Source: `src/helpers/*.ts`
+Source: `src/helpers/**`
 
-## mergeStyles
+## `mergeStyles`
 
-Utility function that merges CSS styles from multiple sources (objects and strings).
+Utility function that merges CSS styles. Supports string, object, and mixed formats. Converts kebab-case CSS strings to camelCase object properties. Later values take precedence.
 
-```ts
-function mergeStyles(
+```typescript
+export function mergeStyles(
   ...styles: (JSX.CSSProperties | string | undefined)[]
 ): JSX.CSSProperties;
 ```
 
-- Object styles are merged with later values taking precedence.
-- String styles are parsed (semicolon-delimited, kebab-case converted to camelCase).
-- `undefined` values are ignored.
+---
 
-## createAppStructure
+## `createAppStructure`
 
-Builds app menus, routes, permissions, and flat menu lists from a declarative structure definition. Supports module-based filtering and permission inference.
+Factory function for defining app navigation structure with type-safe permission inference. Generates routes, menus, and permission trees from a declarative item definition.
 
-```ts
-function createAppStructure<TModule, const TItems extends AppStructureItem<TModule>[]>(
-  items: TItems,
-  options: {
-    basePath: string;
-    enabledModules?: TModule[];
-    enabledPerms?: string[];
-    homeCode?: string;
+```typescript
+export function createAppStructure<TModule, const TItems extends AppStructureItem<TModule>[]>(
+  getOpts: () => {
+    items: TItems;
+    usableModules?: Accessor<TModule[] | undefined>;
+    permRecord?: Accessor<Record<string, boolean> | undefined>;
   },
-): AppStructure<TModule>;
+): {
+  AppStructureProvider: ParentComponent;
+  useAppStructure: () => AppStructure<TModule> & { perms: InferPerms<TItems> };
+};
 ```
 
+### `AppStructure`
+
+```typescript
+export interface AppStructure<TModule> {
+  items: AppStructureItem<TModule>[];
+  usableRoutes: Accessor<AppRoute[]>;
+  usableMenus: Accessor<AppMenu[]>;
+  usableFlatMenus: Accessor<AppFlatMenu[]>;
+  usablePerms: Accessor<AppPerm<TModule>[]>;
+  allFlatPerms: AppFlatPerm<TModule>[];
+  getTitleChainByHref(href: string): string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `usableRoutes` | `Accessor<AppRoute[]>` | Routes filtered by module and permission |
+| `usableMenus` | `Accessor<AppMenu[]>` | Menu tree filtered by module and permission |
+| `usableFlatMenus` | `Accessor<AppFlatMenu[]>` | Flat menu list with title chains |
+| `usablePerms` | `Accessor<AppPerm[]>` | Permission tree filtered by module |
+| `allFlatPerms` | `AppFlatPerm[]` | All permissions flattened (static) |
+| `getTitleChainByHref` | `(href) => string[]` | Get breadcrumb title chain for URL |
+
 ### Input Types
 
-```ts
-interface AppStructureGroupItem<TModule> {
+```typescript
+export type AppStructureItem<TModule> =
+  | AppStructureGroupItem<TModule>
+  | AppStructureLeafItem<TModule>;
+
+export interface AppStructureGroupItem<TModule> {
   code: string;
   title: string;
   icon?: Component<IconProps>;
@@ -44,7 +70,7 @@ interface AppStructureGroupItem<TModule> {
   children: AppStructureItem<TModule>[];
 }
 
-interface AppStructureLeafItem<TModule> {
+export interface AppStructureLeafItem<TModule> {
   code: string;
   title: string;
   icon?: Component<IconProps>;
@@ -56,11 +82,7 @@ interface AppStructureLeafItem<TModule> {
   isNotMenu?: boolean;
 }
 
-type AppStructureItem<TModule> =
-  | AppStructureGroupItem<TModule>
-  | AppStructureLeafItem<TModule>;
-
-interface AppStructureSubPerm<TModule> {
+export interface AppStructureSubPerm<TModule> {
   code: string;
   title: string;
   modules?: TModule[];
@@ -69,27 +91,37 @@ interface AppStructureSubPerm<TModule> {
 }
 ```
 
-### Output Types
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `string` | Unique item identifier |
+| `title` | `string` | Display title |
+| `icon` | `Component<IconProps>` | Navigation icon |
+| `modules` | `TModule[]` | Required modules (any match) |
+| `requiredModules` | `TModule[]` | Strictly required modules (all match) |
+| `children` | `AppStructureItem[]` | Child items (group only) |
+| `component` | `Component` | Page component (leaf only) |
+| `perms` | `("use" \| "edit")[]` | Permission types (leaf only) |
+| `subPerms` | `AppStructureSubPerm[]` | Sub-permission definitions (leaf only) |
+| `isNotMenu` | `boolean` | Exclude from menu (leaf only) |
+
+Discriminated union: items with `children` are groups; items without are leaves.
 
-```ts
-interface AppStructure<TModule> {
-  items: AppStructureItem<TModule>[];
-  usableRoutes: Accessor<AppRoute[]>;
-  usableMenus: Accessor<AppMenu[]>;
-  usableFlatMenus: Accessor<AppFlatMenu[]>;
-  usablePerms: Accessor<AppPerm<TModule>[]>;
-  allFlatPerms: AppFlatPerm<TModule>[];
-  getTitleChainByHref(href: string): string[];
-}
+### Output Types
 
-interface AppMenu {
+```typescript
+export interface AppMenu {
   title: string;
   href?: string;
   icon?: Component<IconProps>;
   children?: AppMenu[];
 }
 
-interface AppPerm<TModule = string> {
+export interface AppRoute {
+  path: string;
+  component: Component;
+}
+
+export interface AppPerm<TModule = string> {
   title: string;
   href?: string;
   modules?: TModule[];
@@ -97,72 +129,78 @@ interface AppPerm<TModule = string> {
   children?: AppPerm<TModule>[];
 }
 
-interface AppRoute {
-  path: string;
-  component: Component;
-}
-
-interface AppFlatMenu {
-  titleChain: string[];
-  href: string;
-}
-
-interface AppFlatPerm<TModule = string> {
+export interface AppFlatPerm<TModule = string> {
   titleChain: string[];
   code: string;
   modulesChain: TModule[][];
   requiredModulesChain: TModule[][];
 }
+
+export interface AppFlatMenu {
+  titleChain: string[];
+  href: string;
+}
 ```
 
-## createSlot
+---
 
-Single-item slot pattern for parent-child communication. Used for patterns like `Dialog.Header`, `Select.Header`.
+## `createSlot`
 
-```ts
-function createSlot<TItem>(): [
+Creates a single-occupancy slot pattern for compound components.
+
+```typescript
+export function createSlot<TItem>(): [
   SlotComponent: (props: TItem) => null,
   createSlotAccessor: () => [Accessor<TItem | undefined>, ParentComponent],
 ];
 ```
 
-Usage pattern:
+Returns a tuple of `[SlotComponent, createSlotAccessor]`:
+- **`SlotComponent`** -- Rendered inside provider to register slot content (throws if slot already occupied)
+- **`createSlotAccessor`** -- Returns `[accessor, Provider]` for reading and providing the slot
 
-```tsx
-// 1. Create slot at module level
-const [HeaderSlot, createHeaderAccessor] = createSlot<{ children: JSX.Element }>();
+---
 
-// 2. In parent component
-const [header, HeaderProvider] = createHeaderAccessor();
+## `createSlots`
 
-return (
-  <HeaderProvider>
-    {props.children}
-    <Show when={header()}>{header()!.children}</Show>
-  </HeaderProvider>
-);
+Creates a multi-occupancy slot pattern for compound components (multiple items).
 
-// 3. In child usage
-<Parent>
-  <HeaderSlot>My Header Content</HeaderSlot>
-  {/* other content */}
-</Parent>
+```typescript
+export function createSlots<TItem>(): [
+  SlotComponent: (props: TItem) => null,
+  createSlotsAccessor: () => [Accessor<TItem[]>, ParentComponent],
+];
 ```
 
-## createSlots
+### `SlotRegistrar`
 
-Multi-item slot pattern. Like `createSlot` but collects an array of items.
-
-```ts
-interface SlotRegistrar<TItem> {
+```typescript
+export interface SlotRegistrar<TItem> {
   add: (item: TItem) => void;
   remove: (item: TItem) => void;
 }
+```
 
-function createSlots<TItem>(): [
-  SlotComponent: (props: TItem) => null,
-  createSlotsAccessor: () => [Accessor<TItem[]>, ParentComponent],
-];
+---
+
+## `startPointerDrag`
+
+Sets up pointer capture and manages pointermove/pointerup lifecycle for drag operations.
+
+```typescript
+export function startPointerDrag(
+  target: HTMLElement,
+  pointerId: number,
+  options: {
+    onMove: (e: PointerEvent) => void;
+    onEnd: (e: PointerEvent) => void;
+  },
+): void;
 ```
 
-Items are collected in order of registration and removed on cleanup.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `target` | `HTMLElement` | Element to capture pointer on |
+| `pointerId` | `number` | Pointer ID from the initiating PointerEvent |
+| `options.onMove` | `(e: PointerEvent) => void` | Called on each pointermove |
+| `options.onEnd` | `(e: PointerEvent) => void` | Called on pointerup or pointercancel |

package/docs/hooks.md

@@ -1,95 +1,99 @@
 # Hooks
 
-Source: `src/hooks/*.ts`
+Source: `src/hooks/**`
 
-## useLocalStorage
+## `useLocalStorage`
 
-localStorage-backed reactive signal. Keys are prefixed with `ConfigContext.clientName`.
+LocalStorage-based storage hook. Always uses localStorage regardless of SyncStorage settings. Keys are prefixed with `clientName`.
 
-```ts
-function useLocalStorage<TValue>(
+```typescript
+export function useLocalStorage<TValue>(
   key: string,
   initialValue?: TValue,
 ): [Accessor<TValue | undefined>, StorageSetter<TValue>];
-
-type StorageSetter<TValue> = (
-  value: TValue | undefined | ((prev: TValue | undefined) => TValue | undefined),
-) => TValue | undefined;
 ```
 
-- Always uses localStorage regardless of `SyncStorageProvider`.
-- Used for device-specific data (auth tokens, local state).
-- Setting `undefined` removes the item from localStorage.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Storage key (auto-prefixed with `clientName`) |
+| `initialValue` | `TValue` | Default value if nothing stored |
+
+---
 
-## useSyncConfig
+## `useSyncConfig`
 
-Storage-synced configuration signal. Uses `SyncStorageProvider` adapter if available, falls back to localStorage.
+Reactive signal that syncs to storage via SyncStorageProvider (falls back to localStorage). Designed for data that should persist and sync across devices.
 
-```ts
-function useSyncConfig<TValue>(
+```typescript
+export function useSyncConfig<TValue>(
   key: string,
   defaultValue: TValue,
 ): [Accessor<TValue>, Setter<TValue>, Accessor<boolean>];
 ```
 
-- Returns `[value, setValue, ready]`.
-- `ready()` becomes `true` after the initial value is loaded from storage.
-- When the adapter changes via `useSyncStorage().configure()`, re-reads from the new adapter.
-- Used for data that should persist and sync across devices (theme, preferences, DataSheet configs).
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Storage key (auto-prefixed with `clientName`) |
+| `defaultValue` | `TValue` | Default value |
+
+Returns `[value, setValue, ready]` where `ready()` is `true` after initial storage read completes.
+
+---
 
-## useLogger
+## `useLogger`
 
-Logging hook with pluggable adapter. Falls back to `consola` if `LoggerProvider` is not present.
+Logging hook that delegates to LoggerProvider adapter (defaults to consola).
 
-```ts
-interface Logger {
+```typescript
+export function useLogger(): Logger;
+
+export interface Logger {
   log: (...args: unknown[]) => void;
   info: (...args: unknown[]) => void;
   warn: (...args: unknown[]) => void;
   error: (...args: unknown[]) => void;
   configure: (fn: (origin: LogAdapter) => LogAdapter) => void;
 }
-
-function useLogger(): Logger;
 ```
 
-`configure` is only usable inside `LoggerProvider`.
+---
 
-## createControllableSignal
+## `createControllableSignal`
 
-Signal hook supporting the controlled/uncontrolled pattern. Used extensively by form components.
+Signal hook supporting the controlled/uncontrolled pattern.
 
-```ts
-function createControllableSignal<TValue>(options: {
+```typescript
+export function createControllableSignal<TValue>(options: {
   value: Accessor<TValue>;
   onChange: Accessor<((value: TValue) => void) | undefined>;
 }): [Accessor<TValue>, (newValue: TValue | ((prev: TValue) => TValue)) => TValue];
 ```
 
-- When `onChange` is provided: controlled mode, value managed externally.
-- When `onChange` returns `undefined`: uncontrolled mode, uses internal state.
-- Supports functional setter: `setValue(prev => !prev)`.
+- When `onChange` is provided: controlled mode (value managed externally)
+- When `onChange` is absent: uncontrolled mode (uses internal state)
+- Supports functional setter: `setValue(prev => !prev)`
+
+---
 
-## createControllableStore
+## `createControllableStore`
 
-Store hook supporting the controlled/uncontrolled pattern. Uses `solid-js/store` for fine-grained reactivity.
+Store hook supporting the controlled/uncontrolled pattern. Supports all `SetStoreFunction` overloads (path-based, produce, reconcile).
 
-```ts
-function createControllableStore<TValue extends object>(options: {
+```typescript
+export function createControllableStore<TValue extends object>(options: {
   value: () => TValue;
   onChange: () => ((value: TValue) => void) | undefined;
 }): [TValue, SetStoreFunction<TValue>];
 ```
 
-- Supports all `SetStoreFunction` overloads (path-based, produce, reconcile).
-- In controlled mode: calls `onChange` with a deep clone when the store changes.
+---
 
-## createIMEHandler
+## `createIMEHandler`
 
-IME composition handling hook. Delays value commits during IME composition (e.g., Korean input) to prevent DOM recreation and composition breakage.
+IME composition handling hook. Delays value changes during IME composition (e.g., Korean) to prevent DOM recreation.
 
-```ts
-function createIMEHandler(setValue: (value: string) => void): {
+```typescript
+export function createIMEHandler(setValue: (value: string) => void): {
   composingValue: Accessor<string | null>;
   handleCompositionStart: () => void;
   handleInput: (value: string, isComposing: boolean) => void;
@@ -98,46 +102,41 @@ function createIMEHandler(setValue: (value: string) => void): {
 };
 ```
 
-- During composition: only `composingValue` is updated (for display).
-- On `compositionEnd`: delays `setValue` via `setTimeout(0)`.
-- `flushComposition()`: immediately commits any pending value.
+---
 
-## createMountTransition
+## `createMountTransition`
 
-Mount/unmount animation state hook.
+Mount transition hook for open/close CSS animations. Returns `mounted` for DOM rendering and `animating` for CSS class toggling.
 
-```ts
-function createMountTransition(open: () => boolean): {
+```typescript
+export function createMountTransition(open: () => boolean): {
   mounted: () => boolean;
   animating: () => boolean;
   unmount: () => void;
 };
 ```
 
-- `open=true`: immediately sets `mounted=true`, then `animating=true` after double `requestAnimationFrame`.
-- `open=false`: immediately sets `animating=false`, then `mounted=false` after `transitionend` or 200ms fallback.
-- Use `mounted()` for DOM rendering, `animating()` for CSS class toggling.
-- Call `unmount()` to manually remove from DOM (e.g., in `onTransitionEnd`).
+- `open=true`: `mounted=true` immediately, `animating=true` after double rAF
+- `open=false`: `animating=false` immediately, `mounted=false` after transitionend or 200ms fallback
 
-## useRouterLink
+---
 
-Router navigation hook supporting modifier keys (Ctrl+click, Shift+click).
+## `useRouterLink`
 
-```ts
-interface RouterLinkOptions {
-  href: string;
-  state?: Record<string, unknown>;
-  window?: {
-    width?: number;   // default: 800
-    height?: number;  // default: 800
-  };
-}
+Router navigation hook with modifier key support.
 
-function useRouterLink(): (
+```typescript
+export function useRouterLink(): (
   options: RouterLinkOptions,
 ) => (e: MouseEvent | KeyboardEvent) => void;
+
+export interface RouterLinkOptions {
+  href: string;
+  state?: Record<string, unknown>;
+  window?: { width?: number; height?: number };
+}
 ```
 
-- Normal click: SPA routing via `useNavigate`.
-- Ctrl/Alt + click: opens in new tab.
-- Shift + click: opens in new window with specified dimensions.
+- Normal click: SPA routing via `useNavigate`
+- Ctrl/Alt + click: new tab
+- Shift + click: new window with configurable size