@simplysm/solid 13.0.96 → 13.0.98

package/docs/hooks.md

@@ -0,0 +1,143 @@
+# Hooks
+
+Source: `src/hooks/*.ts`
+
+## useLocalStorage
+
+localStorage-backed reactive signal. Keys are prefixed with `ConfigContext.clientName`.
+
+```ts
+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.
+
+## useSyncConfig
+
+Storage-synced configuration signal. Uses `SyncStorageProvider` adapter if available, falls back to localStorage.
+
+```ts
+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).
+
+## useLogger
+
+Logging hook with pluggable adapter. Falls back to `consola` if `LoggerProvider` is not present.
+
+```ts
+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
+
+Signal hook supporting the controlled/uncontrolled pattern. Used extensively by form components.
+
+```ts
+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)`.
+
+## createControllableStore
+
+Store hook supporting the controlled/uncontrolled pattern. Uses `solid-js/store` for fine-grained reactivity.
+
+```ts
+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
+
+IME composition handling hook. Delays value commits during IME composition (e.g., Korean input) to prevent DOM recreation and composition breakage.
+
+```ts
+function createIMEHandler(setValue: (value: string) => void): {
+  composingValue: Accessor<string | null>;
+  handleCompositionStart: () => void;
+  handleInput: (value: string, isComposing: boolean) => void;
+  handleCompositionEnd: (value: string) => void;
+  flushComposition: () => void;
+};
+```
+
+- During composition: only `composingValue` is updated (for display).
+- On `compositionEnd`: delays `setValue` via `setTimeout(0)`.
+- `flushComposition()`: immediately commits any pending value.
+
+## createMountTransition
+
+Mount/unmount animation state hook.
+
+```ts
+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`).
+
+## useRouterLink
+
+Router navigation hook supporting modifier keys (Ctrl+click, Shift+click).
+
+```ts
+interface RouterLinkOptions {
+  href: string;
+  state?: Record<string, unknown>;
+  window?: {
+    width?: number;   // default: 800
+    height?: number;  // default: 800
+  };
+}
+
+function useRouterLink(): (
+  options: RouterLinkOptions,
+) => (e: MouseEvent | KeyboardEvent) => void;
+```
+
+- Normal click: SPA routing via `useNavigate`.
+- Ctrl/Alt + click: opens in new tab.
+- Shift + click: opens in new window with specified dimensions.

package/docs/layout.md

@@ -0,0 +1,182 @@
+# Layout
+
+Source: `src/components/layout/**/*.tsx`
+
+## FormGroup
+
+Vertical or inline form field group.
+
+```ts
+interface FormGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  inline?: boolean;  // horizontal layout with wrapping
+}
+```
+
+### Sub-components
+
+- **`FormGroup.Item`** -- Labeled form item.
+
+```ts
+interface FormGroupItemProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  label?: JSX.Element;
+}
+```
+
+## FormTable
+
+Table-based form layout using `<table>` elements.
+
+```ts
+interface FormTableProps extends JSX.HTMLAttributes<HTMLTableElement> {}
+```
+
+### Sub-components
+
+- **`FormTable.Row`** -- Table row. Extends `JSX.HTMLAttributes<HTMLTableRowElement>`.
+- **`FormTable.Item`** -- Labeled table cell. When `label` is omitted, the cell spans the label column.
+
+```ts
+interface FormTableItemProps extends JSX.TdHTMLAttributes<HTMLTableCellElement> {
+  label?: JSX.Element;
+}
+```
+
+## Sidebar
+
+Collapsible sidebar panel. Must be used inside `Sidebar.Container`.
+
+```ts
+interface SidebarProps extends JSX.HTMLAttributes<HTMLElement> {
+  children: JSX.Element;
+}
+```
+
+### Sidebar.Container
+
+Layout container that holds the Sidebar and content area. Provides `SidebarContext` for toggle state. Parent element must have height specified (use `h-full`).
+
+```ts
+interface SidebarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  children: JSX.Element;
+}
+```
+
+- Desktop (640px+): uses `padding-left` transition to expand/collapse.
+- Mobile (<640px): renders backdrop overlay. Auto-closes on navigation.
+
+### Sidebar.Menu
+
+Recursive sidebar menu with route-based selection.
+
+```ts
+interface SidebarMenuProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
+  menus: AppMenu[];
+  defaultOpen?: boolean;  // expand all nested menus on initial render (default: false)
+}
+```
+
+- Parent items of the selected route auto-expand on initial render.
+- External links (containing `://`) open in a new tab.
+
+### Sidebar.User
+
+User information area with optional dropdown menu.
+
+```ts
+interface SidebarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+  name: string;
+  icon?: Component<TablerIconProps>;
+  description?: string;
+  menus?: SidebarUserMenu[];
+}
+
+interface SidebarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+### useSidebar()
+
+Hook to access sidebar toggle state. Throws if used outside `Sidebar.Container`.
+
+```ts
+function useSidebar(): {
+  toggle: Accessor<boolean>;
+  setToggle: Setter<boolean>;
+};
+// Also available: useSidebar.optional() returns undefined if no context
+```
+
+## Topbar
+
+Top navigation bar. Automatically shows a sidebar toggle button if used inside `Sidebar.Container`.
+
+```ts
+interface TopbarProps extends JSX.HTMLAttributes<HTMLElement> {
+  children: JSX.Element;
+}
+```
+
+### Topbar.Container
+
+Vertical layout container wrapping Topbar and content area. Provides `TopbarContext` for actions.
+
+```ts
+interface TopbarContainerProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  children: JSX.Element;
+}
+```
+
+### Topbar.Menu
+
+Dropdown navigation menu. Shows desktop buttons on 640px+ and a hamburger menu on mobile.
+
+```ts
+interface TopbarMenuProps extends Omit<JSX.HTMLAttributes<HTMLElement>, "children"> {
+  menus: TopbarMenuItem[];
+}
+
+interface TopbarMenuItem {
+  title: string;
+  href?: string;
+  icon?: Component<IconProps>;
+  children?: TopbarMenuItem[];
+}
+```
+
+### Topbar.User
+
+User information component with optional dropdown menu.
+
+```ts
+interface TopbarUserProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "onClick"> {
+  menus?: TopbarUserMenu[];
+  children: JSX.Element;
+}
+
+interface TopbarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+### Topbar.Actions
+
+Renders action elements registered by `useTopbarActions()`.
+
+### useTopbarActions()
+
+Register action elements that appear in the Topbar. Automatically cleaned up on component unmount.
+
+```ts
+function useTopbarActions(accessor: () => JSX.Element): void;
+```
+
+### useTopbarActionsAccessor()
+
+Read the current topbar actions signal.
+
+```ts
+function useTopbarActionsAccessor(): Accessor<JSX.Element | undefined>;
+```

package/docs/providers.md

@@ -0,0 +1,177 @@
+# Providers
+
+Source: `src/providers/**/*.tsx`
+
+## ConfigContext / ConfigProvider
+
+App-level configuration providing the `clientName` used as a prefix for storage keys.
+
+```ts
+interface AppConfig {
+  clientName: string;
+}
+
+const ConfigContext: Context<AppConfig>;
+
+function useConfig(): AppConfig;
+
+const ConfigProvider: ParentComponent<{ clientName: string }>;
+```
+
+## SyncStorageProvider / useSyncStorage
+
+Pluggable storage provider. Components use this adapter for persistent storage (localStorage fallback when no adapter is configured).
+
+```ts
+interface StorageAdapter {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+}
+
+interface SyncStorageContextValue {
+  adapter: Accessor<StorageAdapter | undefined>;
+  configure: (adapter: StorageAdapter | undefined) => void;
+}
+
+const SyncStorageContext: Context<SyncStorageContextValue>;
+
+function useSyncStorage(): SyncStorageContextValue | undefined;
+
+const SyncStorageProvider: ParentComponent;
+```
+
+## LoggerProvider
+
+Logging adapter provider. Allows plugging in custom log writers.
+
+```ts
+interface LogAdapter {
+  write: (level: "log" | "info" | "warn" | "error", ...args: unknown[]) => void | Promise<void>;
+}
+
+interface LoggerContextValue {
+  adapter: Accessor<LogAdapter | undefined>;
+  configure: (fn: (origin: LogAdapter) => LogAdapter) => void;
+}
+
+const LoggerContext: Context<LoggerContextValue>;
+
+const LoggerProvider: ParentComponent;
+```
+
+## ThemeContext / ThemeProvider / useTheme
+
+Light/dark/system theme management. Persists mode to synced storage.
+
+```ts
+type ThemeMode = "light" | "dark" | "system";
+type ResolvedTheme = "light" | "dark";
+
+interface ThemeContextValue {
+  mode: Accessor<ThemeMode>;
+  resolved: Accessor<ResolvedTheme>;
+  setMode: (mode: ThemeMode) => void;
+  cycleMode: () => void;
+}
+
+function useTheme(): ThemeContextValue;
+
+const ThemeProvider: ParentComponent;
+```
+
+- `cycleMode()`: light -> system -> dark -> light.
+- `resolved`: the actual applied theme after resolving "system" via `prefers-color-scheme`.
+
+## ServiceClientProvider / useServiceClient
+
+Service client connection provider for `@simplysm/service-client`.
+
+```ts
+interface ServiceClientContextValue {
+  client: Accessor<SdServiceClient | undefined>;
+  connected: Accessor<boolean>;
+  configure: (url: string) => void;
+}
+
+const ServiceClientContext: Context<ServiceClientContextValue>;
+
+function useServiceClient(): ServiceClientContextValue;
+
+const ServiceClientProvider: ParentComponent;
+```
+
+## SystemProvider
+
+Composite provider that bundles commonly used providers together.
+
+```ts
+const SystemProvider: ParentComponent<{
+  clientName: string;
+  busyVariant?: BusyVariant;
+}>;
+```
+
+Internally wraps: `ConfigProvider`, `I18nProvider`, `SyncStorageProvider`, `LoggerProvider`, `ThemeProvider`, `BusyProvider`, `NotificationProvider`, `DialogProvider`, `PrintProvider`, `ErrorLoggerProvider`, `ClipboardProvider`, `PwaUpdateProvider`.
+
+## I18nProvider / useI18n
+
+Internationalization provider with flat dictionary-based translations.
+
+```ts
+interface I18nContextValue {
+  locale: Accessor<string>;
+  t: (key: string, params?: Record<string, string>) => string;
+  configure: (options: I18nConfigureOptions) => void;
+}
+
+interface I18nConfigureOptions {
+  locale?: string;
+  dict?: Record<string, unknown>;  // nested dict, auto-flattened
+  flatDict?: FlatDict;             // pre-flattened dict
+}
+
+type FlatDict = Record<string, string>;
+
+function useI18n(): I18nContextValue;
+
+const I18nProvider: ParentComponent;
+```
+
+- `t("key", { name: "value" })`: interpolates `{name}` placeholders.
+- `configure()`: merges new dictionaries into existing translations.
+
+## SharedDataProvider / useSharedData
+
+Shared data cache provider. Loads and caches data from service, auto-refreshes on change events.
+
+```ts
+interface SharedDataDefinition<TData> {
+  key: string;
+  loader: () => Promise<TData[]>;
+  getKey: (item: TData) => string | number;
+  getSearchText?: (item: TData) => string;
+  getChildren?: (item: TData, allItems: TData[]) => TData[];
+}
+
+interface SharedDataAccessor<TData> {
+  items: Accessor<TData[]>;
+  loading: Accessor<boolean>;
+  refresh: () => Promise<void>;
+  getByKey: (key: string | number) => TData | undefined;
+}
+
+function useSharedData<TSharedData extends Record<string, unknown>>(): SharedDataValue<TSharedData>;
+
+function SharedDataProvider(props: { children: JSX.Element }): JSX.Element;
+```
+
+### SharedDataChangeEvent
+
+Event emitted when shared data changes, triggering refresh.
+
+```ts
+const SharedDataChangeEvent: EventDefinition<{
+  key: string;
+}>;
+```

package/docs/styles.md

@@ -0,0 +1,127 @@
+# Styles + Directives
+
+Source: `src/styles/*.ts`, `src/directives/*.ts`
+
+## Base Styles
+
+Source: `src/styles/base.styles.ts`
+
+Design tokens for borders, backgrounds, and text.
+
+```ts
+const border = {
+  default: "border-base-200 dark:border-base-700",
+  subtle: "border-base-200 dark:border-base-700",
+};
+
+const bg = {
+  surface: "bg-white dark:bg-base-900",
+  muted: "bg-base-100 dark:bg-base-800",
+  subtle: "bg-base-200 dark:bg-base-700",
+};
+
+const text = {
+  default: "text-base-900 dark:text-base-100",
+  muted: "text-base-400 dark:text-base-500",
+  placeholder: "placeholder:text-base-400 dark:placeholder:text-base-500",
+};
+```
+
+## Control Styles
+
+Source: `src/styles/control.styles.ts`
+
+Tokens for interactive component sizing, padding, gaps, and states.
+
+```ts
+const state = {
+  disabled: "pointer-events-none cursor-default opacity-30",
+};
+
+type ComponentSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+const pad: Record<ComponentSize | string, string> = {
+  md: "px-2 py-1",
+  xs: "px-1 py-0",
+  sm: "px-1.5 py-0.5",
+  lg: "px-3 py-2",
+  xl: "px-4 py-3",
+};
+
+const gap: Record<ComponentSize | string, string> = {
+  md: "gap-1",
+  xs: "gap-0",
+  sm: "gap-0.5",
+  lg: "gap-1.5",
+  xl: "gap-2",
+};
+```
+
+## Theme Styles
+
+Source: `src/styles/theme.styles.ts`
+
+Semantic color tokens for six themes: `primary`, `info`, `success`, `warning`, `danger`, `base`.
+
+```ts
+type SemanticTheme = "primary" | "info" | "success" | "warning" | "danger" | "base";
+
+const themeTokens: Record<SemanticTheme, {
+  solid: string;       // solid background + white text
+  solidHover: string;  // hover state for solid
+  light: string;       // light background + dark text
+  text: string;        // text color only
+  hoverBg: string;     // hover background
+  border: string;      // border color
+}>;
+```
+
+Each theme provides six variants:
+
+| Variant | Usage |
+|---------|-------|
+| `solid` | Tag, Button(solid), Progress bar fill |
+| `solidHover` | Button(solid) hover state |
+| `light` | Alert background |
+| `text` | Link color, Tab selected |
+| `hoverBg` | Button(ghost) hover, List item hover |
+| `border` | Button(outline) border |
+
+Example values for `primary`:
+```
+solid:     "bg-primary-500 text-white"
+solidHover: "hover:bg-primary-600 dark:hover:bg-primary-400"
+light:     "bg-primary-100 text-primary-900 dark:bg-primary-900/40 dark:text-primary-100"
+text:      "text-primary-600 dark:text-primary-400"
+hoverBg:   "hover:bg-primary-100 dark:hover:bg-primary-800/30"
+border:    "border-primary-300 dark:border-primary-600"
+```
+
+## Directives
+
+### ripple
+
+Directive that adds a material-design-style ripple effect on pointer down.
+
+```ts
+function ripple(el: HTMLElement, accessor: Accessor<boolean>): void;
+```
+
+Usage in TSX:
+
+```tsx
+<button use:ripple={!props.disabled}>Click me</button>
+```
+
+Behavior:
+- Creates an internal ripple container with `overflow: hidden`.
+- Changes element position to `relative` if it is `static` (restored on cleanup).
+- Single ripple mode: removes previous ripple on new click.
+- Respects `prefers-reduced-motion: reduce`.
+- Ripple radius based on distance from click point to farthest corner.
+
+To use the directive, import and void it at the top of your file:
+```tsx
+import { ripple } from "@simplysm/solid";
+void ripple;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/solid",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm package - SolidJS library",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -30,42 +30,35 @@
     "@solid-primitives/storage": "^4.3.4",
     "@solidjs/router": "^0.15.4",
     "@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",
+    "@tiptap/core": "^3.20.4",
+    "@tiptap/extension-color": "^3.20.4",
+    "@tiptap/extension-highlight": "^3.20.4",
+    "@tiptap/extension-image": "^3.20.4",
+    "@tiptap/extension-table": "^3.20.4",
+    "@tiptap/extension-table-cell": "^3.20.4",
+    "@tiptap/extension-table-header": "^3.20.4",
+    "@tiptap/extension-table-row": "^3.20.4",
+    "@tiptap/extension-text-align": "^3.20.4",
+    "@tiptap/extension-text-style": "^3.20.4",
+    "@tiptap/pm": "^3.20.4",
+    "@tiptap/starter-kit": "^3.20.4",
     "bwip-js": "^4.8.0",
     "clsx": "^2.1.1",
     "consola": "^3.4.2",
+    "echarts": "^6.0.0",
     "html-to-image": "^1.11.13",
-    "jspdf": "^4.2.0",
+    "jspdf": "^4.2.1",
     "solid-js": "^1.9.11",
     "solid-tiptap": "^0.8.0",
     "tabbable": "^6.4.0",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^3.4.19",
-    "@simplysm/core-browser": "13.0.96",
-    "@simplysm/core-common": "13.0.96",
-    "@simplysm/service-client": "13.0.96",
-    "@simplysm/service-common": "13.0.96"
+    "@simplysm/core-browser": "13.0.98",
+    "@simplysm/core-common": "13.0.98",
+    "@simplysm/service-common": "13.0.98",
+    "@simplysm/service-client": "13.0.98"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10"
-  },
-  "peerDependencies": {
-    "echarts": "^6.0.0"
-  },
-  "peerDependenciesMeta": {
-    "echarts": {
-      "optional": true
-    }
   }
 }