@simplysm/solid 13.0.78 → 13.0.81

package/docs/hooks.md

@@ -0,0 +1,146 @@
+# Hooks
+
+## useLocalStorage
+
+```typescript
+function useLocalStorage<TValue>(
+  key: string,
+  initialValue?: TValue,
+): [Accessor<TValue | undefined>, StorageSetter<TValue>];
+```
+
+Reactive `localStorage` binding. Returns a signal-like tuple. Automatically serializes/deserializes values as JSON.
+
+---
+
+## useSyncConfig
+
+```typescript
+function useSyncConfig<TValue>(
+  key: string,
+  defaultValue: TValue,
+): [Accessor<TValue>, Setter<TValue>, Accessor<boolean>];
+```
+
+Persisted configuration backed by `SyncStorageProvider`. Returns `[value, setValue, ready]`. The `ready` accessor becomes `true` once the stored value has been loaded.
+
+---
+
+## useLogger
+
+```typescript
+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;
+```
+
+Access the logging system from `LoggerProvider`. Supports middleware composition via `configure()`.
+
+---
+
+## createControllableSignal
+
+```typescript
+function createControllableSignal<TValue>(options: {
+  value: Accessor<TValue>;
+  onChange: Accessor<((value: TValue) => void) | undefined>;
+}): [Accessor<TValue>, (newValue: TValue | ((prev: TValue) => TValue)) => TValue];
+```
+
+Creates a signal that supports both controlled and uncontrolled modes. When `onChange` is provided, the component is controlled; otherwise, internal state is used. This is the primitive behind all form control `value`/`onValueChange` pairs.
+
+---
+
+## createControllableStore
+
+```typescript
+function createControllableStore<TValue extends object>(options: {
+  value: () => TValue;
+  onChange: () => ((value: TValue) => void) | undefined;
+}): [TValue, SetStoreFunction<TValue>];
+```
+
+Like `createControllableSignal` but for SolidJS stores (deep reactive objects).
+
+---
+
+## createIMEHandler
+
+```typescript
+function createIMEHandler(setValue: (value: string) => void): {
+  composingValue: Accessor<string | null>;
+  handleCompositionStart(): void;
+  handleInput(value: string, isComposing: boolean): void;
+  handleCompositionEnd(value: string): void;
+  flushComposition(): void;
+};
+```
+
+Handles IME composition events (Korean, Chinese, Japanese input). Buffers intermediate composition states and only commits the final value. Used internally by `TextInput` and `Textarea`.
+
+---
+
+## createMountTransition
+
+```typescript
+function createMountTransition(
+  open: () => boolean,
+): {
+  mounted: () => boolean;
+  animating: () => boolean;
+  unmount: () => void;
+};
+```
+
+Manages mount/unmount transitions. While `open()` is true, `mounted` and `animating` are true. When `open()` becomes false, `animating` becomes false (triggering CSS transition), and `unmount()` should be called after the transition ends to set `mounted` to false.
+
+---
+
+## useRouterLink
+
+```typescript
+interface RouterLinkOptions {
+  href: string;
+  state?: Record<string, unknown>;
+  window?: { width?: number; height?: number };
+}
+
+function useRouterLink(): (options: RouterLinkOptions) => (e: MouseEvent | KeyboardEvent) => void;
+```
+
+Creates click handlers for SolidJS Router navigation. Supports opening links in new windows with specified dimensions via the `window` option.
+
+---
+
+## Usage Examples
+
+```typescript
+import {
+  useLocalStorage,
+  useSyncConfig,
+  createControllableSignal,
+  useLogger,
+} from "@simplysm/solid";
+
+// Local storage
+const [theme, setTheme] = useLocalStorage<string>("app-theme", "light");
+
+// Sync config (persisted to SyncStorageProvider)
+const [pageSize, setPageSize, ready] = useSyncConfig("pageSize", 20);
+
+// Logger
+const logger = useLogger();
+logger.info("Application started");
+
+// Controlled/uncontrolled primitive
+const [value, setValue] = createControllableSignal({
+  value: () => props.value,
+  onChange: () => props.onValueChange,
+});
+```

package/docs/layout.md

@@ -0,0 +1,94 @@
+# Layout
+
+## FormGroup
+
+```typescript
+interface FormGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  inline?: boolean;
+}
+```
+
+Groups form fields vertically (default) or horizontally with `inline`.
+
+**Sub-component:** `FormGroup.Item` — `{ label?: JSX.Element } & JSX.HTMLAttributes<HTMLDivElement>`
+
+---
+
+## FormTable
+
+```typescript
+interface FormTableProps extends JSX.HTMLAttributes<HTMLTableElement> {}
+```
+
+Arranges form fields in a label-value table layout.
+
+**Sub-components:**
+- `FormTable.Row` — table row
+- `FormTable.Item` — `{ label?: JSX.Element } & JSX.TdHTMLAttributes<HTMLTableCellElement>`
+
+---
+
+## Sidebar
+
+```typescript
+interface SidebarProps extends JSX.HTMLAttributes<HTMLElement> {
+  children: JSX.Element;
+}
+```
+
+Collapsible sidebar navigation. Must be wrapped in `Sidebar.Container`.
+
+**Sub-components:**
+- `Sidebar.Container` — layout wrapper that includes both sidebar and main content
+- `Sidebar.Menu` — `{ menus: AppMenu[] }` — renders navigation tree from `AppMenu` data
+- `Sidebar.User` — `{ name: string; icon?: Component; description?: string; menus?: SidebarUserMenu[] }` — user profile section with optional dropdown menus
+
+**Hook:** `useSidebar()` — access sidebar state (collapsed, toggle, etc.)
+
+---
+
+## Topbar
+
+```typescript
+interface TopbarProps extends JSX.HTMLAttributes<HTMLElement> {
+  children: JSX.Element;
+}
+```
+
+Top navigation bar. Must be wrapped in `Topbar.Container`.
+
+**Sub-components:**
+- `Topbar.Container` — layout wrapper
+- `Topbar.Menu` — `{ menus: TopbarMenuItem[] }` — renders top-level navigation
+- `Topbar.User` — `{ menus?: TopbarUserMenu[]; children: JSX.Element }` — user section with dropdown
+
+**Hooks:**
+- `useTopbarActionsAccessor()` — access topbar actions element
+- `useTopbarActions(accessor)` — register topbar actions from child components
+
+---
+
+## Usage Examples
+
+```typescript
+import { Sidebar, FormGroup, FormTable } from "@simplysm/solid";
+
+// Sidebar layout
+<Sidebar.Container>
+  <Sidebar>
+    <Sidebar.User name="John" description="Admin" />
+    <Sidebar.Menu menus={appMenus} />
+  </Sidebar>
+  <main>Content</main>
+</Sidebar.Container>
+
+// Form with labeled fields
+<FormGroup>
+  <FormGroup.Item label="Name">
+    <TextInput value={name()} onValueChange={setName} />
+  </FormGroup.Item>
+  <FormGroup.Item label="Email">
+    <TextInput value={email()} onValueChange={setEmail} type="email" />
+  </FormGroup.Item>
+</FormGroup>
+```

package/docs/providers.md

@@ -0,0 +1,179 @@
+# Providers
+
+## ConfigProvider
+
+```typescript
+export const ConfigProvider: ParentComponent<{ clientName: string }>;
+export function useConfig(): { clientName: string };
+```
+
+Application-level configuration. `clientName` identifies the client app.
+
+---
+
+## ThemeProvider
+
+```typescript
+type ThemeMode = "light" | "dark" | "system";
+type ResolvedTheme = "light" | "dark";
+
+interface ThemeContextValue {
+  mode(): ThemeMode;
+  setMode(mode: ThemeMode): void;
+  resolvedTheme(): ResolvedTheme;
+  cycleMode(): void;
+}
+
+export const ThemeProvider: ParentComponent;
+export function useTheme(): ThemeContextValue;
+```
+
+Light/Dark mode management with system preference detection. `cycleMode()` rotates through light → dark → system.
+
+---
+
+## I18nProvider
+
+```typescript
+interface I18nContextValue {
+  t(key: string, params?: Record<string, string>): string;
+  locale: Accessor<string>;
+  setLocale(locale: string): void;
+  configure(options: I18nConfigureOptions): void;
+}
+
+interface I18nConfigureOptions {
+  locale?: string;
+  dict?: Record<string, Record<string, unknown>>;
+}
+
+export const I18nProvider: ParentComponent;
+export function useI18n(): I18nContextValue;
+```
+
+Internationalization provider. Supports nested dictionary keys and parameter interpolation via `t("key", { name: "John" })`.
+
+---
+
+## SyncStorageProvider
+
+```typescript
+interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<unknown>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+interface SyncStorageContextValue {
+  adapter: Accessor<StorageAdapter>;
+  configure(fn: (origin: StorageAdapter) => StorageAdapter): void;
+}
+
+export const SyncStorageProvider: ParentComponent;
+export function useSyncStorage(): SyncStorageContextValue | undefined;
+```
+
+Pluggable storage adapter used by components like `StatePreset`, `DataSheet` (column config), and `useSyncConfig`. Defaults to `localStorage`. Override with `configure()` for server-backed storage.
+
+---
+
+## LoggerProvider
+
+```typescript
+interface LogAdapter {
+  write(severity: "error" | "warn" | "info" | "log", ...data: any[]): Promise<void> | void;
+}
+
+interface LoggerContextValue {
+  adapter: Accessor<LogAdapter>;
+  configure(fn: (origin: LogAdapter) => LogAdapter): void;
+}
+
+export const LoggerProvider: ParentComponent;
+```
+
+Configurable logging provider. Middleware pattern via `configure()`.
+
+---
+
+## ServiceClientProvider
+
+```typescript
+interface ServiceClientContextValue {
+  connect(key?: string, options?: Partial<ServiceConnectionOptions>): Promise<void>;
+  close(key?: string): Promise<void>;
+  get(key?: string): ServiceClient;
+  isConnected(key?: string): boolean;
+}
+
+export const ServiceClientProvider: ParentComponent;
+export function useServiceClient(): ServiceClientContextValue;
+```
+
+Service communication provider. Manages WebSocket connections to backend services. Multiple named connections supported via `key`.
+
+---
+
+## SharedDataProvider
+
+```typescript
+interface SharedDataDefinition<TData> {
+  serviceKey?: string;
+  fetch(changeKeys?: (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;
+}
+
+interface SharedDataAccessor<TData> {
+  items: Accessor<TData[]>;
+  get(key: string | number | undefined): TData | undefined;
+  emit(changeKeys?: (string | number)[]): Promise<void>;
+  getKey(item: TData): string | number;
+  itemSearchText?: (item: TData) => string;
+  isItemHidden?: (item: TData) => boolean;
+  getParentKey?: (item: TData) => string | number | undefined;
+}
+
+export const SharedDataProvider: (props: { children: JSX.Element }) => JSX.Element;
+export function useSharedData<TSharedData>(): SharedDataValue<TSharedData>;
+```
+
+Centralized data management for shared lookup data (e.g. code tables). Data is fetched once and shared across all consumers. `emit()` triggers a re-fetch.
+
+---
+
+## SystemProvider
+
+```typescript
+export const SystemProvider: ParentComponent<{
+  clientName: string;
+  busyVariant?: BusyVariant;
+}>;
+```
+
+Convenience provider that composes `ConfigProvider`, `SyncStorageProvider`, `LoggerProvider`, `ThemeProvider`, `I18nProvider`, `NotificationProvider`, and `BusyProvider` into a single wrapper.
+
+---
+
+## Usage Examples
+
+```typescript
+import { SystemProvider, DialogProvider, PrintProvider } from "@simplysm/solid";
+
+// Typical app provider tree
+<SystemProvider clientName="my-app">
+  <ServiceClientProvider>
+    <SharedDataProvider>
+      <DialogProvider>
+        <PrintProvider>
+          <App />
+        </PrintProvider>
+      </DialogProvider>
+    </SharedDataProvider>
+  </ServiceClientProvider>
+</SystemProvider>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/solid",
-  "version": "13.0.78",
+  "version": "13.0.81",
   "description": "Simplysm package - SolidJS library",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -15,6 +15,7 @@
   "files": [
     "dist",
     "src",
+    "docs",
     "tests",
     "tailwind.config.ts",
     "tailwind.css"
@@ -28,19 +29,19 @@
     "@solid-primitives/resize-observer": "^2.1.5",
     "@solid-primitives/storage": "^4.3.4",
     "@solidjs/router": "^0.15.4",
-    "@tabler/icons-solidjs": "^3.38.0",
-    "@tiptap/core": "^3.20.0",
-    "@tiptap/extension-color": "^3.20.0",
-    "@tiptap/extension-highlight": "^3.20.0",
-    "@tiptap/extension-image": "^3.20.0",
-    "@tiptap/extension-table": "^3.20.0",
-    "@tiptap/extension-table-cell": "^3.20.0",
-    "@tiptap/extension-table-header": "^3.20.0",
-    "@tiptap/extension-table-row": "^3.20.0",
-    "@tiptap/extension-text-align": "^3.20.0",
-    "@tiptap/extension-text-style": "^3.20.0",
-    "@tiptap/pm": "^3.20.0",
-    "@tiptap/starter-kit": "^3.20.0",
+    "@tabler/icons-solidjs": "^3.40.0",
+    "@tiptap/core": "^3.20.1",
+    "@tiptap/extension-color": "^3.20.1",
+    "@tiptap/extension-highlight": "^3.20.1",
+    "@tiptap/extension-image": "^3.20.1",
+    "@tiptap/extension-table": "^3.20.1",
+    "@tiptap/extension-table-cell": "^3.20.1",
+    "@tiptap/extension-table-header": "^3.20.1",
+    "@tiptap/extension-table-row": "^3.20.1",
+    "@tiptap/extension-text-align": "^3.20.1",
+    "@tiptap/extension-text-style": "^3.20.1",
+    "@tiptap/pm": "^3.20.1",
+    "@tiptap/starter-kit": "^3.20.1",
     "bwip-js": "^4.8.0",
     "clsx": "^2.1.1",
     "consola": "^3.4.2",
@@ -51,10 +52,10 @@
     "tabbable": "^6.4.0",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^3.4.19",
-    "@simplysm/core-browser": "13.0.78",
-    "@simplysm/core-common": "13.0.78",
-    "@simplysm/service-client": "13.0.78",
-    "@simplysm/service-common": "13.0.78"
+    "@simplysm/core-browser": "13.0.81",
+    "@simplysm/core-common": "13.0.81",
+    "@simplysm/service-client": "13.0.81",
+    "@simplysm/service-common": "13.0.81"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10"

package/src/components/data/Pagination.tsx

@@ -22,7 +22,7 @@ export interface PaginationProps extends JSX.HTMLAttributes<HTMLElement> {
 const btnClass = clsx("border-none font-normal");
 
 const gapClasses: Record<ComponentSize, string> = {
-  default: gap.default,
+  md: gap.md,
   xs: gap.xs,
   sm: gap.sm,
   lg: gap.lg,
@@ -54,7 +54,7 @@ export const Pagination: Component<PaginationProps> = (props) => {
   const hasPrev = () => (pages()[0] ?? 1) > 1;
   const hasNext = () => (pages()[pages().length - 1] ?? 1) < local.totalPageCount;
 
-  const getClassName = () => twMerge("inline-flex items-center", gapClasses[local.size ?? "default"], local.class);
+  const getClassName = () => twMerge("inline-flex items-center", gapClasses[local.size ?? "md"], local.class);
 
   return (
     <nav {...rest} data-pagination class={getClassName()}>

package/src/components/data/Table.tsx

@@ -23,7 +23,7 @@ const TableTh: ParentComponent<JSX.ThHTMLAttributes<HTMLTableCellElement>> = (pr
   return (
     <th
       class={twMerge(
-        clsx("border-l border-t", border.default, pad.default, bg.muted, "text-left font-bold"),
+        clsx("border-l border-t", border.default, pad.md, bg.muted, "text-left font-bold"),
         ctx.inset && "first:border-l-0",
         local.class,
       )}
@@ -40,7 +40,7 @@ const TableTd: ParentComponent<JSX.TdHTMLAttributes<HTMLTableCellElement>> = (pr
   return (
     <td
       class={twMerge(
-        clsx("border-l border-t", border.default, pad.default),
+        clsx("border-l border-t", border.default, pad.md),
         ctx.inset && "first:border-l-0",
         local.class,
       )}

package/src/components/data/calendar/Calendar.tsx

@@ -108,7 +108,7 @@ function CalendarBase<TValue>(props: CalendarProps<TValue>) {
                 class={clsx(
                   "border-l border-t",
                   border.default,
-                  pad.default,
+                  pad.md,
                   bg.muted,
                   "text-center text-sm font-bold",
                 )}
@@ -141,7 +141,7 @@ function CalendarBase<TValue>(props: CalendarProps<TValue>) {
                     >
                       {cell.date.day}
                     </div>
-                    <div class={clsx("flex flex-col", gap.default)}>
+                    <div class={clsx("flex flex-col", gap.md)}>
                       <For each={cell.items}>
                         {(entry) => local.renderItem(entry.item, entry.index)}
                       </For>

package/src/components/data/kanban/Kanban.tsx

@@ -494,13 +494,13 @@ const KanbanLane: ParentComponent<KanbanLaneProps> = (props) => {
                 </Button>
               </Show>
               <Show when={hasSelectableCards()}>
-                <Checkbox value={isAllSelected()} onValueChange={handleSelectAll} inline />
+                <Checkbox checked={isAllSelected()} onCheckedChange={handleSelectAll} inline />
               </Show>
               <div class="flex-1">
                 <Show when={title()}>{title()!.children}</Show>
               </div>
               <Show when={tools()}>
-                <div class={clsx("flex items-center", gap.default)}>{tools()!.children}</div>
+                <div class={clsx("flex items-center", gap.md)}>{tools()!.children}</div>
               </Show>
             </div>
           </Show>

package/src/components/data/list/ListItem.styles.ts

@@ -18,7 +18,7 @@ export const listItemBaseClass = clsx(
 
 // Size-based styles
 export const listItemSizeClasses: Record<ComponentSize, string> = {
-  default: pad.default,
+  md: pad.md,
   xs: pad.xs,
   sm: pad.sm,
   lg: pad.lg,

package/src/components/data/list/ListItem.tsx

@@ -142,7 +142,7 @@ const ListItemInner: ParentComponent<ListItemProps> = (props) => {
   const getHeaderClassName = () =>
     twMerge(
       listItemBaseClass,
-      listItemSizeClasses[local.size ?? "default"],
+      listItemSizeClasses[local.size ?? "md"],
       local.selected && listItemSelectedClass,
       local.readOnly && listItemReadonlyClass,
       local.disabled && listItemDisabledClass,

package/src/components/data/sheet/DataSheet.styles.ts

@@ -21,7 +21,7 @@ export const thClass = clsx(
   "align-middle",
 );
 
-export const thContentClass = clsx(pad.default);
+export const thContentClass = clsx(pad.md);
 
 export const tdClass = clsx(
   "bg-white dark:bg-base-950",
@@ -54,7 +54,7 @@ export const sortIconClass = clsx("bg-base-100 dark:bg-base-900");
 // Top toolbar (settings button + pagination)
 export const toolbarClass = clsx(
   "flex items-center gap-2",
-  pad.default,
+  pad.md,
   "border-b",
   border.default,
 );