@simplysm/solid 13.0.0-beta.6 → 13.0.2

package/docs/disclosure.md

@@ -0,0 +1,208 @@
+# Disclosure Components
+
+## 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`)
+
+---
+
+## 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, fullscreen mode, and programmatic opening via `useDialog`.
+
+**Declarative usage:**
+
+```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>
+```
+
+**Programmatic usage with `useDialog`:**
+
+```tsx
+import { useDialog, useDialogInstance, Button, TextInput } from "@simplysm/solid";
+import { createSignal } from "solid-js";
+
+// Dialog content component
+function EditDialog() {
+  const dialogInstance = useDialogInstance<string>();
+  const [name, setName] = createSignal("");
+
+  return (
+    <div class="p-4 space-y-4">
+      <TextInput value={name()} onValueChange={setName} placeholder="Enter name" />
+      <Button theme="primary" onClick={() => dialogInstance?.close(name())}>
+        Save
+      </Button>
+    </div>
+  );
+}
+
+// Opening dialog programmatically
+function MyPage() {
+  const dialog = useDialog();
+
+  const handleOpen = async () => {
+    const result = await dialog.show<string>(
+      () => <EditDialog />,
+      { title: "Edit Name", widthPx: 400, closeOnBackdrop: true },
+    );
+    if (result != null) {
+      // result is the value passed to dialogInstance.close()
+      console.log("Saved:", result);
+    }
+  };
+
+  return <Button onClick={handleOpen}>Open Editor</Button>;
+}
+```
+
+**Dialog Props:**
+
+| 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 |
+| `headerStyle` | `JSX.CSSProperties \| string` | - | Header style |
+| `canDeactivate` | `() => boolean` | - | Pre-close confirmation function |
+| `onCloseComplete` | `() => void` | - | Post-close animation callback |
+
+**useDialog API:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `show` | `<T>(factory: () => JSX.Element, options: DialogShowOptions) => Promise<T \| undefined>` | Open dialog, returns result on close |
+
+`DialogShowOptions` accepts all Dialog props except `open`, `onOpenChange`, and `children`.
+
+**useDialogInstance API:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `close` | `(result?: T) => void` | Close dialog with optional return value |

package/docs/display.md

@@ -0,0 +1,136 @@
+# Display Components
+
+## 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 |

package/docs/feedback.md

@@ -0,0 +1,188 @@
+# Feedback Components
+
+## Notification
+
+Notification system. `InitializeProvider` automatically sets up `NotificationProvider` and `NotificationBanner`, so you only need to use the `useNotification` hook and optionally add `NotificationBell` in your layout.
+
+```tsx
+import {
+  NotificationBell,
+  useNotification,
+} from "@simplysm/solid";
+
+// 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:**
+- `NotificationBanner` -- Top-of-screen notification banner (automatically included by `InitializeProvider`)
+- `NotificationBell` -- Notification bell icon (shows unread count, add to your layout as needed)
+
+---
+
+## Loading
+
+Loading overlay system. `InitializeProvider` automatically sets up `LoadingProvider` and `LoadingContainer`. Use the `loadingVariant` option in `AppConfig` to choose between `"spinner"` (default) and `"bar"` variants. Control the loading state using the `useLoading` hook.
+
+```tsx
+import { useLoading } from "@simplysm/solid";
+
+// 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 / usePrint
+
+Browser printing and PDF generation. Must be used inside `InitializeProvider`.
+
+```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:**
+
+| 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)
+
+**usePrintInstance (for async data in print content):**
+
+Use `usePrintInstance` inside print content components when you need to load async data before rendering. Call `ready()` to signal that the content is ready to print.
+
+```tsx
+import { usePrintInstance } from "@simplysm/solid";
+import { createResource, Show } from "solid-js";
+
+function InvoicePrintContent(props: { invoiceId: number }) {
+  const printInstance = usePrintInstance();
+  const [invoice] = createResource(() => fetchInvoice(props.invoiceId));
+
+  createEffect(() => {
+    if (invoice()) {
+      printInstance?.ready();  // signal that content is ready
+    }
+  });
+
+  return (
+    <Show when={invoice()}>
+      {(inv) => (
+        <Print>
+          <Print.Page>
+            <h1>Invoice #{inv().id}</h1>
+            {/* invoice content */}
+          </Print.Page>
+        </Print>
+      )}
+    </Show>
+  );
+}
+
+// Usage
+const { toPrinter } = usePrint();
+await toPrinter(() => <InvoicePrintContent invoiceId={123} />, { size: "A4", margin: "10mm" });
+```