npm - @simplysm/solid - Versions diffs - 13.0.0-beta.6 → 13.0.2 - Mend

@simplysm/solid 13.0.0-beta.6 → 13.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (782) hide show

package/README.md CHANGED Viewed

@@ -37,1602 +37,163 @@ export default {
 ### Provider Setup
-Wrap your app root with `InitializeProvider` and `ThemeProvider`. `InitializeProvider` provides app-wide configuration (clientName, storage), and `ThemeProvider` manages dark mode state.
+Wrap your app root with `InitializeProvider`. It automatically sets up all required providers internally: configuration context, theme (dark/light/system), notification system with banner, global error capturing (window.onerror, unhandledrejection), loading overlay, and programmatic dialog support.
 ```tsx
-import { InitializeProvider, ThemeProvider } from "@simplysm/solid";
+import { InitializeProvider } from "@simplysm/solid";
 function App() {
   return (
     <InitializeProvider config={{ clientName: "my-app" }}>
-      <ThemeProvider>
-        {/* app content */}
-      </ThemeProvider>
+      {/* app content */}
     </InitializeProvider>
   );
 }
 ```
-Alternatively, you can use `ConfigContext.Provider` directly:
-```tsx
-import { ConfigContext, ThemeProvider } from "@simplysm/solid";
-function App() {
-  return (
-    <ConfigContext.Provider value={{ clientName: "my-app" }}>
-      <ThemeProvider>
-        {/* app content */}
-      </ThemeProvider>
-    </ConfigContext.Provider>
-  );
-}
-```
-### Base CSS
-Import the base CSS in your entry point:
-```typescript
-// entry point (e.g., index.tsx)
-import "@simplysm/solid/base.css";
-```
----
-## Components
-### Form Control
-#### Button
-Interactive button component with built-in Material Design ripple effect.
-```tsx
-import { Button } from "@simplysm/solid";
-<Button theme="primary" variant="solid">Confirm</Button>
-<Button theme="danger" variant="outline" size="sm">Delete</Button>
-<Button variant="ghost">Cancel</Button>
-<Button disabled>Disabled</Button>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"primary" \| "info" \| "success" \| "warning" \| "danger" \| "base"` | `"base"` | Color theme |
-| `variant` | `"solid" \| "outline" \| "ghost"` | `"outline"` | Style variant |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style (removes border/rounded corners) |
-| `disabled` | `boolean` | - | Disabled state |
-All standard HTML `<button>` element attributes can also be passed.
----
-#### TextInput
-Text input field with format mask and IME (Korean, etc.) composition support.
-```tsx
-import { TextInput } from "@simplysm/solid";
-// Basic usage
-<TextInput value={name()} onValueChange={setName} placeholder="Enter name" />
-// Password
-<TextInput type="password" />
-// Format mask (e.g., phone number)
-<TextInput format="XXX-XXXX-XXXX" value={phone()} onValueChange={setPhone} />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | `""` | Input value |
-| `onValueChange` | `(value: string) => void` | - | Value change callback |
-| `type` | `"text" \| "password" \| "email"` | `"text"` | Input type |
-| `format` | `string` | - | Input format (`X` represents character position, rest are separators) |
-| `placeholder` | `string` | - | Placeholder |
-| `disabled` | `boolean` | - | Disabled state |
-| `readonly` | `boolean` | - | Read-only state |
-| `error` | `boolean` | - | Error state (red border) |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
----
-#### NumberInput
-Number input field with thousand separators and minimum decimal places support.
-```tsx
-import { NumberInput } from "@simplysm/solid";
-// Basic usage (thousand separators auto-applied)
-<NumberInput value={amount()} onValueChange={setAmount} />
-// Without thousand separators
-<NumberInput value={num()} comma={false} />
-// Minimum 2 decimal places
-<NumberInput value={price()} minDigits={2} />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `number` | - | Input value |
-| `onValueChange` | `(value: number \| undefined) => void` | - | Value change callback |
-| `comma` | `boolean` | `true` | Show thousand separators |
-| `minDigits` | `number` | - | Minimum decimal places |
-| `placeholder` | `string` | - | Placeholder |
-| `disabled` | `boolean` | - | Disabled state |
-| `readonly` | `boolean` | - | Read-only state |
-| `error` | `boolean` | - | Error state |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
----
-#### DatePicker
-Date input field supporting year, month, and date units. Values are handled using the `DateOnly` type.
-```tsx
-import { DatePicker } from "@simplysm/solid";
-import { DateOnly } from "@simplysm/core-common";
-// Date input
-<DatePicker unit="date" value={date()} onValueChange={setDate} />
-// Year-month input
-<DatePicker unit="month" value={monthDate()} onValueChange={setMonthDate} />
-// Year-only input
-<DatePicker unit="year" value={yearDate()} onValueChange={setYearDate} />
-// min/max constraints
-<DatePicker
-  unit="date"
-  value={date()}
-  onValueChange={setDate}
-  min={new DateOnly(2025, 1, 1)}
-  max={new DateOnly(2025, 12, 31)}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `DateOnly` | - | Input value |
-| `onValueChange` | `(value: DateOnly \| undefined) => void` | - | Value change callback |
-| `unit` | `"year" \| "month" \| "date"` | `"date"` | Date unit |
-| `min` | `DateOnly` | - | Minimum date |
-| `max` | `DateOnly` | - | Maximum date |
-| `disabled` | `boolean` | - | Disabled state |
-| `readonly` | `boolean` | - | Read-only state |
-| `error` | `boolean` | - | Error state |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
-> `DateTimePicker` and `TimePicker` follow the same pattern for datetime (`DateTime`) and time (`Time`) input.
----
-#### DateRangePicker
-Component for inputting date ranges with period type selection (day/month/range). The from/to values are automatically adjusted when periodType changes.
-```tsx
-import { DateRangePicker, type DateRangePeriodType } from "@simplysm/solid";
-import { createSignal } from "solid-js";
-import { DateOnly } from "@simplysm/core-common";
-const [periodType, setPeriodType] = createSignal<DateRangePeriodType>("range");
-const [from, setFrom] = createSignal<DateOnly>();
-const [to, setTo] = createSignal<DateOnly>();
-<DateRangePicker
-  periodType={periodType()}
-  onPeriodTypeChange={setPeriodType}
-  from={from()}
-  onFromChange={setFrom}
-  to={to()}
-  onToChange={setTo}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `periodType` | `"day" \| "month" \| "range"` | `"range"` | Period type |
-| `onPeriodTypeChange` | `(value: DateRangePeriodType) => void` | - | Period type change callback |
-| `from` | `DateOnly` | - | Start date |
-| `onFromChange` | `(value: DateOnly \| undefined) => void` | - | Start date change callback |
-| `to` | `DateOnly` | - | End date |
-| `onToChange` | `(value: DateOnly \| undefined) => void` | - | End date change callback |
-| `disabled` | `boolean` | - | Disabled state |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `periodLabels` | `Partial<Record<DateRangePeriodType, string>>` | `{ day: "Day", month: "Month", range: "Range" }` | Period type labels |
----
-#### Textarea
-Multi-line text input field. Height adjusts automatically based on content, with IME composition support.
-```tsx
-import { Textarea } from "@simplysm/solid";
-<Textarea value={text()} onValueChange={setText} />
-// Minimum 3 rows height
-<Textarea minRows={3} value={text()} onValueChange={setText} />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | `""` | Input value |
-| `onValueChange` | `(value: string) => void` | - | Value change callback |
-| `placeholder` | `string` | - | Placeholder |
-| `minRows` | `number` | `1` | Minimum number of rows |
-| `disabled` | `boolean` | - | Disabled state |
-| `readonly` | `boolean` | - | Read-only state |
-| `error` | `boolean` | - | Error state |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
----
-#### Select
-Dropdown selection component. Supports both items prop approach and children (Compound Components) approach. Single and multiple selection supported.
-```tsx
-import { Select } from "@simplysm/solid";
-// items approach (simple array)
-<Select
-  items={["Apple", "Banana", "Strawberry"]}
-  value={fruit()}
-  onValueChange={setFruit}
-  placeholder="Select fruit"
-/>
-// children approach (Compound Components)
-<Select value={fruit()} onValueChange={setFruit} renderValue={(v) => v.name}>
-  <Select.Item value={item1}>{item1.name}</Select.Item>
-  <Select.Item value={item2}>{item2.name}</Select.Item>
-</Select>
-// items approach + ItemTemplate for custom rendering
-<Select items={users} value={selectedUser()} onValueChange={setSelectedUser}>
-  <Select.ItemTemplate>
-    {(user) => <>{user.name} ({user.email})</>}
-  </Select.ItemTemplate>
-</Select>
-// Multiple selection
-<Select items={options} value={selected()} onValueChange={setSelected} multiple />
-// With action buttons and header
-<Select value={item()} onValueChange={setItem} renderValue={(v) => v.name}>
-  <Select.Header><div>Custom header</div></Select.Header>
-  <Select.Action onClick={handleAdd}>+</Select.Action>
-  <Select.Item value={item1}>{item1.name}</Select.Item>
-</Select>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `T \| T[]` | - | Selected value |
-| `onValueChange` | `(value: T \| T[]) => void` | - | Value change callback |
-| `items` | `T[]` | - | Items array (items approach) |
-| `getChildren` | `(item: T, index: number, depth: number) => T[] \| undefined` | - | Tree structure children getter |
-| `renderValue` | `(value: T) => JSX.Element` | - | Value rendering function (required for children approach) |
-| `multiple` | `boolean` | `false` | Multiple selection |
-| `multiDisplayDirection` | `"horizontal" \| "vertical"` | `"horizontal"` | Display direction for multiple selection |
-| `hideSelectAll` | `boolean` | - | Hide select all button (multiple selection) |
-| `placeholder` | `string` | - | Placeholder |
-| `disabled` | `boolean` | - | Disabled state |
-| `required` | `boolean` | - | Required field |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
-**Sub-components:**
-- `Select.Item` -- Selection item
-- `Select.Action` -- Right-side action button
-- `Select.Header` -- Dropdown top custom area
-- `Select.ItemTemplate` -- Item rendering template for items approach
----
-#### Combobox
-Autocomplete component with async search and item selection support. Debouncing is built-in.
-```tsx
-import { Combobox } from "@simplysm/solid";
-<Combobox
-  loadItems={async (query) => {
-    const response = await fetch(`/api/search?q=${query}`);
-    return response.json();
-  }}
-  renderValue={(item) => item.name}
-  value={selected()}
-  onValueChange={setSelected}
-  placeholder="Search..."
->
-  <Combobox.ItemTemplate>
-    {(item) => <>{item.name}</>}
-  </Combobox.ItemTemplate>
-</Combobox>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `T` | - | Selected value |
-| `onValueChange` | `(value: T) => void` | - | Value change callback |
-| `loadItems` | `(query: string) => Promise<T[]>` | **(required)** | Item loading function |
-| `renderValue` | `(value: T) => JSX.Element` | **(required)** | Value rendering function |
-| `debounceMs` | `number` | `300` | Debounce delay (ms) |
-| `allowCustomValue` | `boolean` | - | Allow custom values |
-| `parseCustomValue` | `(text: string) => T` | - | Custom value parsing function |
-| `placeholder` | `string` | - | Placeholder |
-| `disabled` | `boolean` | - | Disabled state |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
-**Sub-components:**
-- `Combobox.Item` -- Selection item
-- `Combobox.ItemTemplate` -- Item rendering template
----
-#### Checkbox / Radio
-Checkbox and radio button components.
-```tsx
-import { Checkbox, Radio } from "@simplysm/solid";
-<Checkbox value={checked()} onValueChange={setChecked}>I agree</Checkbox>
-<Checkbox theme="success" value={active()} onValueChange={setActive}>Activate</Checkbox>
-<Radio value={option() === "a"} onValueChange={() => setOption("a")}>Option A</Radio>
-<Radio value={option() === "b"} onValueChange={() => setOption("b")}>Option B</Radio>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `boolean` | `false` | Checked state |
-| `onValueChange` | `(value: boolean) => void` | - | Value change callback |
-| `theme` | `"primary" \| "info" \| "success" \| "warning" \| "danger" \| "base"` | `"primary"` | Color theme |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `disabled` | `boolean` | - | Disabled state |
-| `inset` | `boolean` | - | Inset style |
-| `inline` | `boolean` | - | Inline style |
----
-#### CheckboxGroup / RadioGroup
-Group components for managing multiple/single selection across items.
-```tsx
-import { CheckboxGroup, RadioGroup } from "@simplysm/solid";
-// Multiple selection
-<CheckboxGroup value={selectedColors()} onValueChange={setSelectedColors}>
-  <CheckboxGroup.Item value="red">Red</CheckboxGroup.Item>
-  <CheckboxGroup.Item value="green">Green</CheckboxGroup.Item>
-  <CheckboxGroup.Item value="blue">Blue</CheckboxGroup.Item>
-</CheckboxGroup>
-// Single selection
-<RadioGroup value={size()} onValueChange={setSize}>
-  <RadioGroup.Item value="sm">Small</RadioGroup.Item>
-  <RadioGroup.Item value="md">Medium</RadioGroup.Item>
-  <RadioGroup.Item value="lg">Large</RadioGroup.Item>
-</RadioGroup>
-```
-**CheckboxGroup Props:**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `T[]` | `[]` | Selected values array |
-| `onValueChange` | `(value: T[]) => void` | - | Value change callback |
-| `theme` | `SemanticTheme` | `"primary"` | Color theme |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `disabled` | `boolean` | - | Disable all items |
-| `inline` | `boolean` | - | Inline style |
-| `inset` | `boolean` | - | Inset style |
-**RadioGroup Props:**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `T` | - | Selected value |
-| `onValueChange` | `(value: T) => void` | - | Value change callback |
-| `theme` | `SemanticTheme` | `"primary"` | Color theme |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `disabled` | `boolean` | - | Disable all items |
-| `inline` | `boolean` | - | Inline style |
-| `inset` | `boolean` | - | Inset style |
----
-#### ColorPicker
-Color selection component.
-```tsx
-import { ColorPicker } from "@simplysm/solid";
-<ColorPicker value={color()} onValueChange={setColor} />
-<ColorPicker value={color()} size="sm" disabled />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | `"#000000"` | Color value (#RRGGBB format) |
-| `onValueChange` | `(value: string) => void` | - | Value change callback |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `disabled` | `boolean` | - | Disabled state |
----
-#### ThemeToggle
-Dark/light/system theme cycle toggle button. Must be used inside `ThemeProvider`.
-```tsx
-import { ThemeToggle } from "@simplysm/solid";
-<ThemeToggle />
-<ThemeToggle size="sm" />
-<ThemeToggle size="lg" />
-```
-Clicking cycles through `light -> system -> dark -> light`, displaying an icon matching the current mode.
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` | `"sm" \| "lg"` | - | Button size |
----
-#### RichTextEditor
-Tiptap-based rich text editor. Supports text formatting (bold, italic, strikethrough), alignment, colors, highlights, tables, and image insertion.
-```tsx
-import { RichTextEditor } from "@simplysm/solid";
-<RichTextEditor value={html()} onValueChange={setHtml} />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | - | HTML string value |
-| `onValueChange` | `(value: string) => void` | - | Value change callback |
-| `disabled` | `boolean` | - | Disabled state |
-| `error` | `boolean` | - | Error state |
-| `size` | `"sm" \| "lg"` | - | Size |
----
-#### Numpad
-Numeric keypad component. Used in environments requiring touch-based number input.
-```tsx
-import { Numpad } from "@simplysm/solid";
-<Numpad value={amount()} onValueChange={setAmount} />
-// With ENT/minus buttons
-<Numpad
-  value={amount()}
-  onValueChange={setAmount}
-  useEnterButton
-  useMinusButton
-  onEnterButtonClick={handleSubmit}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `number` | - | Input value |
-| `onValueChange` | `(value: number \| undefined) => void` | - | Value change callback |
-| `placeholder` | `string` | - | Placeholder |
-| `required` | `boolean` | - | Required field |
-| `inputDisabled` | `boolean` | - | Disable direct text field input |
-| `useEnterButton` | `boolean` | - | Show ENT button |
-| `useMinusButton` | `boolean` | - | Show minus button |
-| `onEnterButtonClick` | `() => void` | - | ENT click callback |
-| `size` | `"sm" \| "lg"` | - | Size |
----
-#### StatePreset
-Component for saving/loading screen state (search conditions, etc.) as presets. Persisted in localStorage.
-```tsx
-import { StatePreset } from "@simplysm/solid";
-<StatePreset
-  presetKey="user-search"
-  value={searchState()}
-  onValueChange={setSearchState}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `presetKey` | `string` | **(required)** | Preset storage key |
-| `value` | `T` | **(required)** | Current state value |
-| `onValueChange` | `(value: T) => void` | **(required)** | State restore callback |
-| `size` | `"sm" \| "lg"` | - | Size |
----
-### Navigation
-#### Tabs
-Tab navigation component.
-```tsx
-import { Tabs } from "@simplysm/solid";
-<Tabs value={activeTab()} onValueChange={setActiveTab}>
-  <Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
-  <Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
-  <Tabs.Tab value="tab3" disabled>Tab 3</Tabs.Tab>
-</Tabs>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | - | Selected tab value |
-| `onValueChange` | `(value: string) => void` | - | Tab change callback |
-| `size` | `"sm" \| "lg"` | - | Size |
-**Sub-components:**
-- `Tabs.Tab` -- Individual tab (`value: string`, `disabled?: boolean`)
----
-### Display
-#### Card
-Container with shadow effect.
-```tsx
-import { Card } from "@simplysm/solid";
-<Card>Card content</Card>
-<Card class="p-4">Card with padding</Card>
-```
----
-#### Tag
-Inline tag/badge component.
-```tsx
-import { Tag } from "@simplysm/solid";
-<Tag theme="primary">New</Tag>
-<Tag theme="success">Complete</Tag>
-<Tag theme="danger">Urgent</Tag>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"primary" \| "info" \| "success" \| "warning" \| "danger" \| "base"` | `"base"` | Color theme |
----
-#### Alert
-Block-level alert/notice component.
-```tsx
-import { Alert } from "@simplysm/solid";
-<Alert theme="info">This is an information message.</Alert>
-<Alert theme="warning">Please pay attention to this.</Alert>
-<Alert theme="danger">An error has occurred.</Alert>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"primary" \| "info" \| "success" \| "warning" \| "danger" \| "base"` | `"base"` | Color theme |
----
-#### Icon
-Tabler Icons wrapper component. Displayed in `em` units to scale proportionally with surrounding text.
-```tsx
-import { Icon } from "@simplysm/solid";
-import { IconCheck, IconAlertTriangle } from "@tabler/icons-solidjs";
-<Icon icon={IconCheck} />
-<Icon icon={IconAlertTriangle} size="2em" />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `icon` | `Component` | **(required)** | Tabler icon component |
-| `size` | `string \| number` | `"1.25em"` | Icon size |
----
-#### Progress
-Progress indicator component.
-```tsx
-import { Progress } from "@simplysm/solid";
-<Progress value={0.65} />
-<Progress value={0.8} theme="success" size="lg" />
-// Custom text
-<Progress value={progress()}>
-  {Math.round(progress() * 100)}% complete
-</Progress>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `number` | **(required)** | Progress (0~1) |
-| `theme` | `"primary" \| "info" \| "success" \| "warning" \| "danger" \| "base"` | `"primary"` | Color theme |
-| `size` | `"sm" \| "lg"` | - | Size |
-| `inset` | `boolean` | - | Inset style |
----
-#### Barcode
-bwip-js-based barcode/QR code rendering component. Supports over 100 barcode types.
-```tsx
-import { Barcode } from "@simplysm/solid";
-<Barcode type="qrcode" value="https://example.com" />
-<Barcode type="code128" value="ABC-12345" />
-<Barcode type="ean13" value="4901234567890" />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `BarcodeType` | **(required)** | Barcode type (`"qrcode"`, `"code128"`, `"ean13"`, etc.) |
-| `value` | `string` | - | Barcode value |
----
-#### Echarts
-Apache ECharts chart wrapper component. Requires `echarts` peer dependency installation.
-```tsx
-import { Echarts } from "@simplysm/solid";
-<Echarts
-  option={{
-    xAxis: { type: "category", data: ["Mon", "Tue", "Wed"] },
-    yAxis: { type: "value" },
-    series: [{ data: [120, 200, 150], type: "bar" }],
-  }}
-/>
-<Echarts option={chartOption()} loading={isLoading()} />
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `option` | `echarts.EChartsOption` | **(required)** | ECharts option object |
-| `loading` | `boolean` | - | Show loading state |
----
-### Layout
-#### Sidebar
-Sidebar navigation with responsive support (mobile overlay below 520px). Open/closed state is saved in localStorage.
-```tsx
-import { Sidebar } from "@simplysm/solid";
-<Sidebar.Container>
-  <Sidebar>
-    <Sidebar.User name="John Doe" menus={userMenus}>
-      <span>John Doe</span>
-    </Sidebar.User>
-    <Sidebar.Menu menus={menuItems} />
-  </Sidebar>
-  <div class="flex flex-1 flex-col">
-    <Topbar>
-      <h1>App Name</h1>
-    </Topbar>
-    <main class="flex-1 overflow-auto p-4">
-      {/* main content */}
-    </main>
-  </div>
-</Sidebar.Container>
-```
-**Sub-components:**
-- `Sidebar.Container` -- Container wrapping sidebar and main area (required)
-- `Sidebar.Menu` -- Menu items list (`menus: SidebarMenuItem[]`)
-- `Sidebar.User` -- User info area
----
-#### Topbar
-Top navigation bar. When used inside `Sidebar.Container`, a sidebar toggle button appears automatically.
-```tsx
-import { Topbar } from "@simplysm/solid";
-<Topbar>
-  <h1 class="text-lg font-bold">App Name</h1>
-  <Topbar.Menu menus={menuItems} />
-  <div class="flex-1" />
-  <Topbar.User menus={userMenus}>User</Topbar.User>
-</Topbar>
-```
-**Sub-components:**
-- `Topbar.Container` -- Container wrapping main content below topbar
-- `Topbar.Menu` -- Menu items list
-- `Topbar.User` -- User menu (dropdown)
----
-#### FormGroup
-Layout component for arranging form fields with labels vertically or inline.
-```tsx
-import { FormGroup, TextInput } from "@simplysm/solid";
-// Vertical layout (default)
-<FormGroup>
-  <FormGroup.Item label="Name">
-    <TextInput value={name()} onValueChange={setName} />
-  </FormGroup.Item>
-  <FormGroup.Item label="Email">
-    <TextInput type="email" value={email()} onValueChange={setEmail} />
-  </FormGroup.Item>
-</FormGroup>
-// Inline layout
-<FormGroup inline>
-  <FormGroup.Item label="Search">
-    <TextInput value={query()} onValueChange={setQuery} />
-  </FormGroup.Item>
-  <FormGroup.Item>
-    <Button theme="primary">Search</Button>
-  </FormGroup.Item>
-</FormGroup>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `inline` | `boolean` | `false` | Inline layout mode |
-**Sub-components:**
-- `FormGroup.Item` -- Form item (`label?: JSX.Element`)
----
-#### FormTable
-`<table>`-based form layout. Labels go in `<th>`, input fields in `<td>`.
-```tsx
-import { FormTable, TextInput, NumberInput } from "@simplysm/solid";
-<FormTable>
-  <tbody>
-    <tr>
-      <th>Name</th>
-      <td><TextInput value={name()} onValueChange={setName} /></td>
-      <th>Age</th>
-      <td><NumberInput value={age()} onValueChange={setAge} /></td>
-    </tr>
-    <tr>
-      <th>Email</th>
-      <td colSpan={3}><TextInput type="email" value={email()} onValueChange={setEmail} /></td>
-    </tr>
-  </tbody>
-</FormTable>
-```
----
-#### Kanban
-Kanban board layout component.
----
-### Data
-#### Table
-Basic HTML table wrapper. Provides consistent styling for borders, header backgrounds, etc.
-```tsx
-import { Table } from "@simplysm/solid";
-<Table>
-  <thead>
-    <tr><th>Name</th><th>Age</th></tr>
-  </thead>
-  <tbody>
-    <tr><td>John Doe</td><td>30</td></tr>
-    <tr><td>Jane Smith</td><td>25</td></tr>
-  </tbody>
-</Table>
-// Inset style (removes outer border, fits parent container)
-<Table inset>...</Table>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `inset` | `boolean` | - | Inset style |
----
-#### DataSheet
-Advanced data table component. Supports sorting, pagination, row selection, tree expansion, column resize, column configuration, and row reordering.
-```tsx
-import { DataSheet } from "@simplysm/solid";
-<DataSheet items={users()} key="user-table">
-  <DataSheet.Column key="name" header="Name" sortable>
-    {({ item }) => <>{item.name}</>}
-  </DataSheet.Column>
-  <DataSheet.Column key="age" header="Age" sortable width="80px">
-    {({ item }) => <>{item.age}</>}
-  </DataSheet.Column>
-  <DataSheet.Column key="email" header="Email">
-    {({ item }) => <>{item.email}</>}
-  </DataSheet.Column>
-</DataSheet>
-// With pagination + sorting + selection
-<DataSheet
-  items={data()}
-  key="data-table"
-  page={page()}
-  onPageChange={setPage}
-  totalPageCount={totalPages()}
-  sorts={sorts()}
-  onSortsChange={setSorts}
-  selectMode="multiple"
-  selectedItems={selectedItems()}
-  onSelectedItemsChange={setSelectedItems}
->
-  {/* columns */}
-</DataSheet>
-```
-**DataSheet Props (key items):**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `T[]` | - | Data array |
-| `key` | `string` | - | Column configuration storage key |
-| `inset` | `boolean` | - | Inset style |
-| `sorts` | `SortingDef[]` | - | Sort definition |
-| `onSortsChange` | `(sorts: SortingDef[]) => void` | - | Sort change callback |
-| `autoSort` | `boolean` | - | Client-side auto-sorting |
-| `page` | `number` | - | Current page (0-based) |
-| `onPageChange` | `(page: number) => void` | - | Page change callback |
-| `totalPageCount` | `number` | - | Total page count |
-| `selectMode` | `"single" \| "multiple"` | - | Selection mode |
-| `selectedItems` | `T[]` | - | Selected items |
-| `onSelectedItemsChange` | `(items: T[]) => void` | - | Selection change callback |
-| `getChildren` | `(item: T, index: number) => T[] \| undefined` | - | Tree structure children getter |
-| `hideConfigBar` | `boolean` | - | Hide configuration bar |
-**DataSheet.Column Props:**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `key` | `string` | **(required)** | Column identifier key |
-| `header` | `string \| string[]` | - | Header text (array for multi-level headers) |
-| `headerContent` | `() => JSX.Element` | - | Custom header rendering |
-| `summary` | `() => JSX.Element` | - | Summary row rendering |
-| `width` | `string` | - | Column width |
-| `fixed` | `boolean` | - | Fixed column |
-| `hidden` | `boolean` | - | Hidden column |
-| `sortable` | `boolean` | - | Sortable |
-| `resizable` | `boolean` | - | Resizable |
-| `children` | `(ctx: { item: T, index: number, depth: number }) => JSX.Element` | **(required)** | Cell rendering function |
----
-#### List
-Tree-view style list component. Supports keyboard navigation.
-```tsx
-import { List } from "@simplysm/solid";
-<List>
-  <List.Item>Item 1</List.Item>
-  <List.Item>Item 2</List.Item>
-  <List.Item>
-    Parent item
-    <List.Item.Children>
-      <List.Item>Child item 1</List.Item>
-      <List.Item>Child item 2</List.Item>
-    </List.Item.Children>
-  </List.Item>
-</List>
-// Inset style
-<List inset>
-  <List.Item>Inset item</List.Item>
-</List>
-```
-**Keyboard navigation:**
-- `ArrowUp` / `ArrowDown` -- Move focus to previous/next item
-- `Space` / `Enter` -- Click current item
-- `ArrowRight` -- Expand if collapsed, focus first child if expanded
-- `ArrowLeft` -- Collapse if expanded, focus parent if collapsed
-- `Home` / `End` -- Focus first/last item
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `inset` | `boolean` | - | Transparent background style |
----
-#### Pagination
-Page navigation component.
-```tsx
-import { Pagination } from "@simplysm/solid";
-<Pagination
-  page={currentPage()}
-  onPageChange={setCurrentPage}
-  totalPageCount={20}
-  displayPageCount={10}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `page` | `number` | **(required)** | Current page (0-based) |
-| `onPageChange` | `(page: number) => void` | - | Page change callback |
-| `totalPageCount` | `number` | **(required)** | Total page count |
-| `displayPageCount` | `number` | `10` | Number of pages to display at once |
-| `size` | `"sm" \| "lg"` | - | Size |
----
-#### Calendar
-Calendar-style data display component.
-```tsx
-import { Calendar } from "@simplysm/solid";
-<Calendar
-  items={events()}
-  getItemDate={(event) => event.date}
-  renderItem={(event) => <div>{event.title}</div>}
-  yearMonth={yearMonth()}
-  onYearMonthChange={setYearMonth}
-/>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `T[]` | **(required)** | Data array |
-| `getItemDate` | `(item: T, index: number) => DateOnly` | **(required)** | Item date extraction function |
-| `renderItem` | `(item: T, index: number) => JSX.Element` | **(required)** | Item rendering function |
-| `yearMonth` | `DateOnly` | - | Year-month to display |
-| `onYearMonthChange` | `(value: DateOnly) => void` | - | Year-month change callback |
-| `weekStartDay` | `number` | `0` (Sunday) | Week start day |
----
-#### PermissionTable
-Permission management table component.
----
-### Disclosure
-#### Collapse
-Content collapse/expand animation component. Uses `margin-top`-based transition for smooth open/close effects.
-```tsx
-import { Collapse, Button } from "@simplysm/solid";
-import { createSignal } from "solid-js";
-const [open, setOpen] = createSignal(false);
-<Button
-  aria-expanded={open()}
-  aria-controls="content"
-  onClick={() => setOpen(!open())}
->
-  Toggle
-</Button>
-<Collapse id="content" open={open()}>
-  <p>Collapsible content</p>
-</Collapse>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | `false` | Open state |
-Animation is automatically disabled when `prefers-reduced-motion` is set.
----
-#### Dropdown
-Positioned dropdown popup. Position is determined relative to trigger element or absolute coordinates.
-```tsx
-import { Dropdown, Button } from "@simplysm/solid";
-import { createSignal } from "solid-js";
-const [open, setOpen] = createSignal(false);
-let triggerRef!: HTMLButtonElement;
-<Button ref={triggerRef} onClick={() => setOpen(!open())}>Open</Button>
-<Dropdown triggerRef={() => triggerRef} open={open()} onOpenChange={setOpen}>
-  <p class="p-3">Dropdown content</p>
-</Dropdown>
-// Context menu (absolute position)
-<Dropdown position={{ x: 100, y: 200 }} open={menuOpen()} onOpenChange={setMenuOpen}>
-  <List inset>
-    <List.Item>Menu item 1</List.Item>
-    <List.Item>Menu item 2</List.Item>
-  </List>
-</Dropdown>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `triggerRef` | `() => HTMLElement \| undefined` | - | Trigger element reference (mutually exclusive with position) |
-| `position` | `{ x: number; y: number }` | - | Absolute position (mutually exclusive with triggerRef) |
-| `open` | `boolean` | - | Open state |
-| `onOpenChange` | `(open: boolean) => void` | - | State change callback |
-| `maxHeight` | `number` | `300` | Maximum height (px) |
-| `keyboardNav` | `boolean` | - | Enable keyboard navigation (used by Select, etc.) |
----
-#### Dialog
-Modal dialog component. Supports drag movement, resize, floating mode, and fullscreen mode.
-```tsx
-import { Dialog, Button } from "@simplysm/solid";
-import { createSignal } from "solid-js";
-const [open, setOpen] = createSignal(false);
-<Button onClick={() => setOpen(true)}>Open</Button>
-<Dialog
-  title="Dialog Title"
-  open={open()}
-  onOpenChange={setOpen}
-  closeOnBackdrop
-  widthPx={600}
->
-  <div class="p-4">
-    Dialog content
-  </div>
-</Dialog>
-// Floating mode (no backdrop)
-<Dialog
-  title="Notification"
-  open={open()}
-  onOpenChange={setOpen}
-  float
-  position="bottom-right"
->
-  <div class="p-4">Floating dialog</div>
-</Dialog>
-```
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | - | Open state |
-| `onOpenChange` | `(open: boolean) => void` | - | State change callback |
-| `title` | `string` | **(required)** | Modal title |
-| `hideHeader` | `boolean` | - | Hide header |
-| `closable` | `boolean` | `true` | Show close button |
-| `closeOnBackdrop` | `boolean` | - | Close on backdrop click |
-| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
-| `resizable` | `boolean` | `false` | Resizable |
-| `movable` | `boolean` | `true` | Draggable |
-| `float` | `boolean` | - | Floating mode (no backdrop) |
-| `fill` | `boolean` | - | Fullscreen mode |
-| `widthPx` | `number` | - | Width (px) |
-| `heightPx` | `number` | - | Height (px) |
-| `minWidthPx` | `number` | - | Minimum width (px) |
-| `minHeightPx` | `number` | - | Minimum height (px) |
-| `position` | `"bottom-right" \| "top-right"` | - | Fixed position |
-| `headerAction` | `JSX.Element` | - | Header action area |
-| `canDeactivate` | `() => boolean` | - | Pre-close confirmation function |
-| `onCloseComplete` | `() => void` | - | Post-close animation callback |
----
-### Feedback
-#### Notification
-Notification system. Wrap with `NotificationProvider` and trigger notifications using the `useNotification` hook.
-```tsx
-import {
-  NotificationProvider,
-  NotificationBanner,
-  NotificationBell,
-  useNotification,
-} from "@simplysm/solid";
-// Set up Provider at app root
-<NotificationProvider>
-  <NotificationBanner />
-  <header>
-    <NotificationBell />
-  </header>
-  <MyApp />
-</NotificationProvider>
-// Trigger notifications within components
-function MyComponent() {
-  const notification = useNotification();
-  const handleSave = () => {
-    notification.success("Success", "Saved successfully.");
-  };
-  const handleError = () => {
-    notification.danger("Error", "An issue occurred.", {
-      action: { label: "Retry", onClick: handleRetry },
-    });
-  };
-  return <Button onClick={handleSave}>Save</Button>;
-}
-```
-**useNotification API:**
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `info` | `(title: string, message?: string, options?: NotificationOptions) => string` | Info notification |
-| `success` | `(title: string, message?: string, options?: NotificationOptions) => string` | Success notification |
-| `warning` | `(title: string, message?: string, options?: NotificationOptions) => string` | Warning notification |
-| `danger` | `(title: string, message?: string, options?: NotificationOptions) => string` | Error notification |
-| `update` | `(id: string, updates: Partial<NotificationItem>, options?: { renotify?: boolean }) => void` | Update notification |
-| `remove` | `(id: string) => void` | Remove notification |
-| `markAsRead` | `(id: string) => void` | Mark as read |
-| `markAllAsRead` | `() => void` | Mark all as read |
-| `dismissBanner` | `() => void` | Dismiss banner |
-| `clear` | `() => void` | Clear all |
-**Components:**
-- `NotificationProvider` -- Notification state management Provider
-- `NotificationBanner` -- Top-of-screen notification banner
-- `NotificationBell` -- Notification bell icon (shows unread count)
----
-#### Loading
-Loading overlay system. Wrap with `LoadingProvider` and control loading state using the `useLoading` hook.
-```tsx
-import {
-  LoadingProvider,
-  LoadingContainer,
-  useLoading,
-} from "@simplysm/solid";
-// Set up Provider at app root
-<LoadingProvider>
-  <LoadingContainer />
-  <MyApp />
-</LoadingProvider>
-// Control loading within components
-function MyComponent() {
-  const loading = useLoading();
-  const fetchData = async () => {
-    loading.show("Loading data...");
-    try {
-      await fetch("/api/data");
-    } finally {
-      loading.hide();
-    }
-  };
-  return <Button onClick={fetchData}>Load Data</Button>;
-}
-```
-**useLoading API:**
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `show` | `(message?: string) => void` | Show loading |
-| `hide` | `() => void` | Hide loading |
-| `setProgress` | `(percent: number \| undefined) => void` | Set progress |
----
-### Print
-#### Print / usePrint
-Browser printing and PDF generation. Requires `LoadingProvider`.
-```tsx
-import { Print, usePrint } from "@simplysm/solid";
-function MyComponent() {
-  const { toPrinter, toPdf } = usePrint();
-  const handlePrint = async () => {
-    await toPrinter(
-      () => (
-        <Print>
-          <Print.Page>
-            <h1>Print content</h1>
-            <p>Page 1</p>
-          </Print.Page>
-          <Print.Page>
-            <p>Page 2</p>
-          </Print.Page>
-        </Print>
-      ),
-      { size: "A4", margin: "10mm" },
-    );
-  };
-  const handlePdf = async () => {
-    const pdfData = await toPdf(
-      () => (
-        <Print>
-          <Print.Page>
-            <h1>PDF content</h1>
-          </Print.Page>
-        </Print>
-      ),
-      { size: "A4 landscape" },
-    );
-    // pdfData: Uint8Array
-  };
-  return (
-    <>
-      <Button onClick={handlePrint}>Print</Button>
-      <Button onClick={handlePdf}>Download PDF</Button>
-    </>
-  );
-}
-```
-**usePrint API:**
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `toPrinter` | `(factory: () => JSX.Element, options?: PrintOptions) => Promise<void>` | Browser print |
-| `toPdf` | `(factory: () => JSX.Element, options?: PrintOptions) => Promise<Uint8Array>` | PDF generation |
-**PrintOptions:**
+**AppConfig options:**
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `size` | `string` | `"A4"` | Paper size (`"A4"`, `"A3"`, `"A4 landscape"`, `"210mm 297mm"`, etc.) |
-| `margin` | `string` | `"0"` | Margins (`"10mm"`, `"1cm"`, etc.) |
-**Sub-components:**
-- `Print.Page` -- Explicit page breaks (auto-breaks if not used)
----
+| `clientName` | `string` | **(required)** | Client identifier (used as storage key prefix) |
+| `syncStorage` | `StorageAdapter` | `localStorage` | Custom sync storage adapter (used by `useSyncConfig`) |
+| `logger` | `LogAdapter` | - | Log adapter for remote logging (used by `useLogger`) |
+| `loadingVariant` | `"spinner" \| "bar"` | `"spinner"` | Root loading overlay variant |
-## Context & Hooks
+**StorageAdapter interface:**
-### 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
+```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>;
+}
 ```
-| 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 |
----
-### usePersisted
-localStorage-based persistent signal. Must be used inside `ConfigContext`, and keys are automatically stored as `{clientName}.{key}`. Supports serialization of `@simplysm/core-common` custom types like `DateTime`, `DateOnly`.
-```tsx
-import { usePersisted } from "@simplysm/solid";
-const [value, setValue] = usePersisted("settings.view", "grid");
+**LogAdapter interface:**
-// loading state (for async storage)
-const [data, setData, loading] = usePersisted("cache.data", defaultData);
+```typescript
+interface LogAdapter {
+  write(severity: "error" | "warn" | "info" | "log", ...data: any[]): Promise<void> | void;
+}
 ```
-| Return value | Type | Description |
-|--------------|------|-------------|
-| `[0]` | `Accessor<T>` | Value getter |
-| `[1]` | `Setter<T>` | Value setter |
-| `[2]` | `Accessor<boolean>` | Loading state (async storage only) |
----
-### useNotification
-Hook to access notification system. Must be used inside `NotificationProvider`. See [Notification](#notification) section for detailed API.
----
-### useLoading
-Hook to access loading overlay. Must be used inside `LoadingProvider`. See [Loading](#loading) section for detailed API.
----
-### usePrint
-Hook for printing and PDF generation. Must be used inside `LoadingProvider`. See [Print](#print--useprint) section for detailed API.
----
-### useConfig
-Hook to access app-wide configuration. Must be used inside `ConfigContext.Provider` or `InitializeProvider`.
+### Base CSS
-```tsx
-import { useConfig } from "@simplysm/solid";
+Import the base CSS in your entry point:
-const config = useConfig();
-console.log(config.clientName); // "my-app"
+```typescript
+// entry point (e.g., index.tsx)
+import "@simplysm/solid/tailwind.css";
 ```
 ---
-### 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";
+## Components
-// Use inside components
-const [value, setValue] = createControllableSignal({
-  value: () => props.value ?? "",
-  onChange: () => props.onValueChange,
-});
+### Form Controls
+- [`Button`](docs/form-controls.md#button) - Interactive button with Material Design ripple effect
+- [`TextInput`](docs/form-controls.md#textinput) - Text input with format mask and IME composition support
+- [`NumberInput`](docs/form-controls.md#numberinput) - Number input with thousand separators and decimal places
+- [`DatePicker`](docs/form-controls.md#datepicker) - Date input supporting year, month, and date units (`DateOnly` type)
+- [`DateRangePicker`](docs/form-controls.md#daterangepicker) - Date range input with period type selection (day/month/range)
+- [`Textarea`](docs/form-controls.md#textarea) - Multi-line text input with auto-height and IME support
+- [`Select`](docs/form-controls.md#select) - Dropdown selection with single/multiple, hierarchical items, and compound components
+- [`Combobox`](docs/form-controls.md#combobox) - Autocomplete with async search and debouncing
+- [`Checkbox`](docs/form-controls.md#checkbox--radio) / [`Radio`](docs/form-controls.md#checkbox--radio) - Checkbox and radio button
+- [`CheckboxGroup`](docs/form-controls.md#checkboxgroup--radiogroup) / [`RadioGroup`](docs/form-controls.md#checkboxgroup--radiogroup) - Group components for multiple/single selection
+- [`ColorPicker`](docs/form-controls.md#colorpicker) - Color selection component
+- [`ThemeToggle`](docs/form-controls.md#themetoggle) - Dark/light/system theme cycle toggle
+- [`RichTextEditor`](docs/form-controls.md#richtexteditor) - Tiptap-based rich text editor with formatting, tables, images
+- [`Invalid`](docs/form-controls.md#invalid) - Wrapper component for form validation using native browser validation
+- [`Numpad`](docs/form-controls.md#numpad) - Numeric keypad for touch-based input
+- [`StatePreset`](docs/form-controls.md#statepreset) - Save/load screen state as presets
-// Supports functional setter
-setValue((prev) => prev + "!");
-```
+### Data
----
+- [`Table`](docs/data-components.md#table) - Basic HTML table wrapper with consistent styling
+- [`DataSheet`](docs/data-components.md#datasheet) - Advanced data table with sorting, pagination, selection, tree expansion, column resize, drag reorder
+- [`List`](docs/data-components.md#list) - Tree-view list with keyboard navigation
+- [`Pagination`](docs/data-components.md#pagination) - Page navigation component
+- [`Calendar`](docs/data-components.md#calendar) - Calendar-style data display
+- [`PermissionTable`](docs/data-components.md#permissiontable) - Hierarchical permission management table with cascading checks
-### createMountTransition
+### Layout
-Mount transition hook for open/close CSS animations. Control DOM rendering with `mounted()` and toggle CSS classes with `animating()`.
+- [`Sidebar`](docs/layout.md#sidebar) - Sidebar navigation with responsive mobile overlay
+- [`Topbar`](docs/layout.md#topbar) - Top navigation bar with menus and user dropdown
+- [`FormGroup`](docs/layout.md#formgroup) - Form fields layout with labels (vertical/inline)
+- [`FormTable`](docs/layout.md#formtable) - Table-based form layout
+- [`Kanban`](docs/layout.md#kanban) - Kanban board with drag-and-drop, lane collapse, multi-select
-```tsx
-import { createMountTransition } from "@simplysm/solid";
+### Display
-const { mounted, animating, unmount } = createMountTransition(() => open());
-```
+- [`Card`](docs/display.md#card) - Container with shadow effect
+- [`Tag`](docs/display.md#tag) - Inline tag/badge component
+- [`Alert`](docs/display.md#alert) - Block-level alert/notice component
+- [`Icon`](docs/display.md#icon) - Tabler Icons wrapper (scales with surrounding text)
+- [`Progress`](docs/display.md#progress) - Progress indicator
+- [`Barcode`](docs/display.md#barcode) - Barcode/QR code rendering (100+ barcode types)
+- [`Echarts`](docs/display.md#echarts) - Apache ECharts chart wrapper
-| Return value | Type | Description |
-|--------------|------|-------------|
-| `mounted` | `() => boolean` | Whether mounted in DOM |
-| `animating` | `() => boolean` | Animation active state |
-| `unmount` | `() => void` | Manual unmount |
+### Disclosure
----
+- [`Tabs`](docs/disclosure.md#tabs) - Tab navigation component
+- [`Collapse`](docs/disclosure.md#collapse) - Content collapse/expand animation
+- [`Dropdown`](docs/disclosure.md#dropdown) - Positioned dropdown popup
+- [`Dialog`](docs/disclosure.md#dialog) - Modal dialog with drag, resize, floating mode, and programmatic `useDialog`
-### createIMEHandler
+### Feedback
-Hook that delays `onValueChange` calls during IME (Korean, etc.) composition to prevent interrupted input.
+- [`Notification`](docs/feedback.md#notification) - Notification system with banner and bell (`useNotification`)
+- [`Loading`](docs/feedback.md#loading) - Loading overlay with spinner/bar variants (`useLoading`)
+- [`Print`](docs/feedback.md#print--useprint) - Browser printing and PDF generation (`usePrint`)
 ---
-### useRouterLink
-`@solidjs/router`-based navigation hook. Automatically handles Ctrl/Alt + click (new tab), Shift + click (new window).
-```tsx
-import { useRouterLink } from "@simplysm/solid";
-const navigate = useRouterLink();
+## Hooks
-<List.Item onClick={navigate({ href: "/home/dashboard" })}>
-  Dashboard
-</List.Item>
-// Pass state
-<List.Item onClick={navigate({ href: "/users/123", state: { from: "list" } })}>
-  User
-</List.Item>
-```
+- [`useTheme`](docs/hooks.md#usetheme) - Dark/light/system theme state access
+- [`useLocalStorage`](docs/hooks.md#uselocalstorage) - Local-only persistent storage (never syncs)
+- [`useSyncConfig`](docs/hooks.md#usesyncconfig) - Syncable config storage (cross-device sync support)
+- [`useLogger`](docs/hooks.md#uselogger) - Logging with optional remote adapter
+- [`useConfig`](docs/hooks.md#useconfig) - App-wide configuration access
+- [`useNotification`](docs/hooks.md#usenotification) - Notification system access
+- [`useLoading`](docs/hooks.md#useloading) - Loading overlay control
+- [`usePrint`](docs/hooks.md#useprint) - Printing and PDF generation
+- [`createControllableSignal`](docs/hooks.md#createcontrollablesignal) - Controlled/Uncontrolled signal pattern
+- [`createMountTransition`](docs/hooks.md#createmounttransition) - Mount/unmount CSS animation hook
+- [`createIMEHandler`](docs/hooks.md#createimehandler) - IME composition delay handler
+- [`useRouterLink`](docs/hooks.md#userouterlink) - Navigation with Ctrl/Shift+click support
+- [`createAppStructure`](docs/hooks.md#createappstructure) - Declarative app structure (routing, menus, permissions)
+- [`createPwaUpdate`](docs/hooks.md#createpwaupdate) - PWA Service Worker update detection
 ---
-### createAppStructure
+## Providers
-Utility for declaratively defining app structure (routing, menus, permissions).
-```tsx
-import { createAppStructure, type AppStructureItem } from "@simplysm/solid";
-const items: AppStructureItem<string>[] = [
-  {
-    code: "home",
-    title: "Home",
-    component: HomePage,
-    perms: ["use"],
-  },
-  {
-    code: "admin",
-    title: "Admin",
-    children: [
-      { code: "users", title: "User Management", component: UsersPage, perms: ["use", "edit"] },
-    ],
-  },
-];
-const structure = createAppStructure(items, {
-  modules: () => activeModules(),
-  basePath: "/app",
-});
-// structure.routes -- Route array (pass to Route component)
-// structure.usableMenus() -- Sidebar menu array
-// structure.permRecord() -- Permission record (Record<string, boolean>)
-```
+- [`InitializeProvider`](docs/providers.md#initializeprovider) - Root provider (theme, notification, loading, dialog, error capturing)
+- [`ServiceClientProvider`](docs/providers.md#serviceclientprovider) - WebSocket RPC client provider
+- [`SharedDataProvider`](docs/providers.md#shareddataprovider) - Server-side data subscription provider
 ---
-## Directives
-### ripple
-Material Design ripple effect directive. Displays ripple effect on click.
+## Styling
-```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
+- [Semantic Colors](docs/styling.md#semantic-colors) - primary, info, success, warning, danger, base
+- [Custom Sizes](docs/styling.md#custom-sizes) - Field height classes (h-field, h-field-sm, h-field-lg)
+- [z-index Layers](docs/styling.md#z-index-layers) - Sidebar, dropdown, modal z-index values
+- [Dark Mode](docs/styling.md#dark-mode) - Class-based dark mode with auto-toggle
+- [Styling Patterns](docs/styling.md#styling-patterns) - clsx + twMerge usage patterns
 ---
-## Tailwind Theme
-`@simplysm/solid` provides the following custom themes via Tailwind CSS preset.
-### Semantic Colors
-| Name | Base Color | Usage |
-|------|------------|-------|
-| `primary` | blue | Primary actions |
-| `info` | sky | Information |
-| `success` | green | Success |
-| `warning` | amber | Warning |
-| `danger` | red | Danger/error |
-| `base` | zinc | Neutral (backgrounds, borders, secondary text, etc.) |
-> Use `base-*` instead of directly using `zinc-*`.
+## Helpers & Directives
-### Custom Sizes
-| Class | Description |
-|-------|-------------|
-| `h-field` / `size-field` | Default field height (based on `py-1`) |
-| `h-field-sm` / `size-field-sm` | Small field height (based on `py-0.5`) |
-| `h-field-lg` / `size-field-lg` | Large field height (based on `py-2`) |
-| `h-field-inset` / `size-field-inset` | Inset field height (excludes border) |
-| `h-field-inset-sm` / `size-field-inset-sm` | Small inset field height |
-| `h-field-inset-lg` / `size-field-inset-lg` | Large inset field height |
-### z-index Layers
-| Class | Value | Description |
-|-------|-------|-------------|
-| `z-sidebar` | 100 | Sidebar |
-| `z-sidebar-backdrop` | 99 | Sidebar backdrop |
-| `z-busy` | 500 | Loading overlay |
-| `z-dropdown` | 1000 | Dropdown popup |
-| `z-modal-backdrop` | 1999 | Modal backdrop |
-| `z-modal` | 2000 | Modal dialog |
-### Dark Mode
-Uses Tailwind's `class` strategy. `ThemeProvider` automatically toggles the `dark` class on the `<html>` element.
-```html
-<!-- Light mode -->
-<html>
-<!-- Dark mode -->
-<html class="dark">
-```
-### Styling Patterns
-When using Tailwind classes in components, group them by semantic units with `clsx` and resolve conflicts with `twMerge`:
-```typescript
-import clsx from "clsx";
-import { twMerge } from "tailwind-merge";
-const baseClass = clsx(
-  "inline-flex items-center",
-  "px-2 py-1",
-  "rounded",
-  "border border-transparent",
-);
-const className = twMerge(baseClass, props.class);
-```
+- [`mergeStyles`](docs/helpers.md#mergestyles) - Merge inline style strings and CSSProperties objects
+- [`splitSlots`](docs/helpers.md#splitslots) - Split children into named slots by component type
+- [`ripple`](docs/helpers.md#ripple-directive) - Material Design ripple effect directive
 ---
@@ -1645,8 +206,6 @@ pnpm dev
 # http://localhost:40081 (port may vary)
 ```
----
 ## License
 Apache-2.0