@simplysm/solid 13.0.97 → 13.0.99

package/docs/helpers.md

@@ -0,0 +1,206 @@
+# Helpers
+
+Source: `src/helpers/**`
+
+## `mergeStyles`
+
+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.
+
+```typescript
+export function mergeStyles(
+  ...styles: (JSX.CSSProperties | string | undefined)[]
+): JSX.CSSProperties;
+```
+
+---
+
+## `createAppStructure`
+
+Factory function for defining app navigation structure with type-safe permission inference. Generates routes, menus, and permission trees from a declarative item definition.
+
+```typescript
+export function createAppStructure<TModule, const TItems extends AppStructureItem<TModule>[]>(
+  getOpts: () => {
+    items: TItems;
+    usableModules?: Accessor<TModule[] | undefined>;
+    permRecord?: Accessor<Record<string, boolean> | undefined>;
+  },
+): {
+  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
+
+```typescript
+export type AppStructureItem<TModule> =
+  | AppStructureGroupItem<TModule>
+  | AppStructureLeafItem<TModule>;
+
+export interface AppStructureGroupItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  children: AppStructureItem<TModule>[];
+}
+
+export interface AppStructureLeafItem<TModule> {
+  code: string;
+  title: string;
+  icon?: Component<IconProps>;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  component?: Component;
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPerm<TModule>[];
+  isNotMenu?: boolean;
+}
+
+export interface AppStructureSubPerm<TModule> {
+  code: string;
+  title: string;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  perms: ("use" | "edit")[];
+}
+```
+
+| 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.
+
+### Output Types
+
+```typescript
+export interface AppMenu {
+  title: string;
+  href?: string;
+  icon?: Component<IconProps>;
+  children?: AppMenu[];
+}
+
+export interface AppRoute {
+  path: string;
+  component: Component;
+}
+
+export interface AppPerm<TModule = string> {
+  title: string;
+  href?: string;
+  modules?: TModule[];
+  perms?: string[];
+  children?: AppPerm<TModule>[];
+}
+
+export interface AppFlatPerm<TModule = string> {
+  titleChain: string[];
+  code: string;
+  modulesChain: TModule[][];
+  requiredModulesChain: TModule[][];
+}
+
+export interface AppFlatMenu {
+  titleChain: string[];
+  href: string;
+}
+```
+
+---
+
+## `createSlot`
+
+Creates a single-occupancy slot pattern for compound components.
+
+```typescript
+export function createSlot<TItem>(): [
+  SlotComponent: (props: TItem) => null,
+  createSlotAccessor: () => [Accessor<TItem | undefined>, ParentComponent],
+];
+```
+
+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
+
+---
+
+## `createSlots`
+
+Creates a multi-occupancy slot pattern for compound components (multiple items).
+
+```typescript
+export function createSlots<TItem>(): [
+  SlotComponent: (props: TItem) => null,
+  createSlotsAccessor: () => [Accessor<TItem[]>, ParentComponent],
+];
+```
+
+### `SlotRegistrar`
+
+```typescript
+export interface SlotRegistrar<TItem> {
+  add: (item: TItem) => void;
+  remove: (item: TItem) => void;
+}
+```
+
+---
+
+## `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;
+```
+
+| 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

@@ -0,0 +1,142 @@
+# Hooks
+
+Source: `src/hooks/**`
+
+## `useLocalStorage`
+
+LocalStorage-based storage hook. Always uses localStorage regardless of SyncStorage settings. Keys are prefixed with `clientName`.
+
+```typescript
+export function useLocalStorage<TValue>(
+  key: string,
+  initialValue?: TValue,
+): [Accessor<TValue | undefined>, StorageSetter<TValue>];
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Storage key (auto-prefixed with `clientName`) |
+| `initialValue` | `TValue` | Default value if nothing stored |
+
+---
+
+## `useSyncConfig`
+
+Reactive signal that syncs to storage via SyncStorageProvider (falls back to localStorage). Designed for data that should persist and sync across devices.
+
+```typescript
+export function useSyncConfig<TValue>(
+  key: string,
+  defaultValue: TValue,
+): [Accessor<TValue>, Setter<TValue>, Accessor<boolean>];
+```
+
+| 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`
+
+Logging hook that delegates to LoggerProvider adapter (defaults to consola).
+
+```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;
+}
+```
+
+---
+
+## `createControllableSignal`
+
+Signal hook supporting the controlled/uncontrolled pattern.
+
+```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` is absent: uncontrolled mode (uses internal state)
+- Supports functional setter: `setValue(prev => !prev)`
+
+---
+
+## `createControllableStore`
+
+Store hook supporting the controlled/uncontrolled pattern. Supports all `SetStoreFunction` overloads (path-based, produce, reconcile).
+
+```typescript
+export function createControllableStore<TValue extends object>(options: {
+  value: () => TValue;
+  onChange: () => ((value: TValue) => void) | undefined;
+}): [TValue, SetStoreFunction<TValue>];
+```
+
+---
+
+## `createIMEHandler`
+
+IME composition handling hook. Delays value changes during IME composition (e.g., Korean) to prevent DOM recreation.
+
+```typescript
+export function createIMEHandler(setValue: (value: string) => void): {
+  composingValue: Accessor<string | null>;
+  handleCompositionStart: () => void;
+  handleInput: (value: string, isComposing: boolean) => void;
+  handleCompositionEnd: (value: string) => void;
+  flushComposition: () => void;
+};
+```
+
+---
+
+## `createMountTransition`
+
+Mount transition hook for open/close CSS animations. Returns `mounted` for DOM rendering and `animating` for CSS class toggling.
+
+```typescript
+export function createMountTransition(open: () => boolean): {
+  mounted: () => boolean;
+  animating: () => boolean;
+  unmount: () => void;
+};
+```
+
+- `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 with modifier key support.
+
+```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: new tab
+- Shift + click: new window with configurable size

package/docs/layout.md

@@ -0,0 +1,212 @@
+# Layout Components
+
+Source: `src/components/layout/**`
+
+## `FormGroup`
+
+Vertical or inline form field grouping component.
+
+```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`** -- Individual form field with optional label
+
+```typescript
+export interface FormGroupItemProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  label?: JSX.Element;
+}
+```
+
+---
+
+## `FormTable`
+
+Table-based form layout with label-value pairs.
+
+```typescript
+export interface FormTableProps extends JSX.HTMLAttributes<HTMLTableElement> {}
+```
+
+### Sub-components
+
+- **`FormTable.Row`** -- Table row wrapper
+- **`FormTable.Item`** -- Table cell with optional label (`th` + `td`)
+
+```typescript
+export interface FormTableItemProps extends JSX.TdHTMLAttributes<HTMLTableCellElement> {
+  label?: JSX.Element;
+}
+```
+
+---
+
+## `Sidebar`
+
+Responsive sidebar navigation with user info and menu sections. Collapses on mobile with overlay backdrop.
+
+```typescript
+export interface SidebarProps extends JSX.HTMLAttributes<HTMLElement> {
+  children: JSX.Element;
+}
+```
+
+### 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
+
+### `Sidebar.Container`
+
+```typescript
+export interface SidebarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  children: JSX.Element;
+}
+```
+
+### `Sidebar.Menu`
+
+```typescript
+export interface SidebarMenuProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
+  menus: AppMenu[];
+  defaultOpen?: boolean;
+}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `menus` | `AppMenu[]` | Menu items array |
+| `defaultOpen` | `boolean` | Expand all nested menus initially. Default: `false` |
+
+### `Sidebar.User`
+
+```typescript
+export interface SidebarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+  name: string;
+  icon?: Component<TablerIconProps>;
+  description?: string;
+  menus?: 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;
+}
+```
+
+### `SidebarContextValue`
+
+```typescript
+export interface SidebarContextValue {
+  toggle: Accessor<boolean>;
+  setToggle: Setter<boolean>;
+}
+```
+
+### `useSidebar`
+
+Hook to access sidebar toggle state. Also has `useSidebar.optional()` variant.
+
+### `SM_MEDIA_QUERY`
+
+```typescript
+export const SM_MEDIA_QUERY = "(min-width: 640px)";
+```
+
+---
+
+## `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;
+}
+```
+
+### 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()`
+
+### `Topbar.Container`
+
+```typescript
+export interface TopbarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  children: JSX.Element;
+}
+```
+
+### `Topbar.Menu`
+
+```typescript
+export interface TopbarMenuProps extends Omit<JSX.HTMLAttributes<HTMLElement>, "children"> {
+  menus: TopbarMenuItem[];
+}
+```
+
+### `TopbarMenuItem`
+
+```typescript
+export interface TopbarMenuItem {
+  title: string;
+  href?: string;
+  icon?: Component<IconProps>;
+  children?: TopbarMenuItem[];
+}
+```
+
+### `Topbar.User`
+
+```typescript
+export interface TopbarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+  menus?: TopbarUserMenu[];
+  children: JSX.Element;
+}
+```
+
+### `TopbarUserMenu`
+
+```typescript
+export interface TopbarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+### `TopbarContextValue`
+
+```typescript
+export interface TopbarContextValue {
+  actions: Accessor<JSX.Element | undefined>;
+  setActions: Setter<JSX.Element | undefined>;
+}
+```
+
+### Hooks
+
+- **`useTopbarActions(accessor: () => JSX.Element)`** -- Register dynamic actions for display in Topbar
+- **`useTopbarActionsAccessor()`** -- Read registered actions