@rchemist/listgrid 0.2.6

package/docs/PRIMITIVES.md

@@ -0,0 +1,271 @@
+# @rchemist/listgrid — Primitive Catalog
+
+Reference for the CSS primitive classes + their `data-*` variants. This is the public contract for external consumers; host apps can build with these primitives alone (no Tailwind required) and theme via the token set in [`tokens.css`](../src/listgrid/styles/tokens.css).
+
+- **File**: `src/listgrid/styles/primitives.css`
+- **Import**: `import '@rchemist/listgrid/styles.css'` (or `./styles/primitives.css` alone)
+- **Philosophy**: Each primitive is a *what* (class name) + *how* (data-attr variants). Base class describes the element; `data-variant` / `data-size` / `data-color` / `data-tone` / `data-state` describe modifications.
+- **Cascade order**: `tokens → primitives → layouts → components → base`. Hosts override by writing CSS after `@rchemist/listgrid/styles.css`.
+
+---
+
+## Layout
+
+### `.rcm-row`
+Horizontal flex container.
+- `data-justify="start|center|end|between|around"` — justify-content
+- `data-align="start|center|end|baseline|stretch"` — align-items
+- `data-gap="none|xs|sm|md|lg|xl"` — gap (default `sm`)
+- `data-wrap="wrap|nowrap"` — flex-wrap
+
+```html
+<div class="rcm-row" data-justify="between" data-gap="md">
+  <span>Left</span><span>Right</span>
+</div>
+```
+
+### `.rcm-stack`
+Vertical flex container.
+- `data-gap="none|xs|sm|md|lg|xl"` (default `md`)
+- `data-align="start|center|end|stretch"`
+
+### `.rcm-grid`
+CSS grid container.
+- `data-cols="1|2|3|4"` — column count at default breakpoint
+- `data-gap="none|xs|sm|md|lg|xl"`
+
+### `.rcm-panel`
+Surface card with border + radius.
+- `data-elevation="none|sm|md|lg"` — box-shadow
+- `data-padding="none|sm|md|lg"`
+
+### `.rcm-divider`
+Horizontal rule with consistent spacing.
+
+---
+
+## Buttons
+
+### `.rcm-button`
+- `data-variant="default|primary|outline|ghost|link"` (default: neutral surface)
+- `data-color="error"` (pairs with `primary` / `outline` / `ghost` for danger actions)
+- `data-size="sm|md|lg"` (default `md`)
+- `:disabled` or `data-state="disabled"` — reduces opacity to 0.5, disables pointer events
+
+```html
+<button class="rcm-button" data-variant="primary">저장</button>
+<button class="rcm-button" data-variant="outline" data-color="error" data-size="sm">삭제</button>
+```
+
+### `.rcm-icon-btn`
+Square icon-only button (same data-attr API as `.rcm-button`, but auto-sizes for icon content).
+
+### `.rcm-button-group`
+Wraps multiple `.rcm-button` elements with shared border-radius (first/last button get rounded corners; inner borders collapse).
+
+---
+
+## Form inputs
+
+### `.rcm-input`, `.rcm-textarea`, `.rcm-select`
+- `data-size="sm|md|lg"`
+- `data-state="error"` — red border + focus ring
+- `:disabled` / `[readonly]` — muted surface
+
+### `.rcm-checkbox`, `.rcm-radio`
+Native input replacements with token-driven border/fill.
+
+### `.rcm-label`
+Form label with optional required/optional marker.
+- `data-required` — shows red asterisk
+- `data-optional` — shows muted "(optional)" hint
+
+### `.rcm-input-group` + `.rcm-input-addon`
+Compose input with left/right addon (e.g., currency prefix, search icon).
+
+```html
+<div class="rcm-input-group">
+  <span class="rcm-input-addon">₩</span>
+  <input class="rcm-input" />
+  <span class="rcm-input-addon">KRW</span>
+</div>
+```
+
+---
+
+## Display
+
+### `.rcm-text`
+Generic text span/paragraph with semantic variants.
+- `data-size="xs|sm|md|lg|xl"`
+- `data-weight="normal|medium|semibold|bold"`
+- `data-tone="muted|disabled|inherit"`
+- `data-color="primary|error|success|warning|info|inherit"`
+
+### `.rcm-heading`
+Heading tag wrapper.
+- `data-level="1|2|3|4|5|6"` — font-size ladder (independent of HTML tag)
+
+### `.rcm-badge`
+Pill-shaped small count / label.
+- `data-color="primary|secondary|neutral|error|success|warning|info"`
+- `data-size="sm|md"`
+
+### `.rcm-tag`
+Same visual family as badge but rectangular, usually for metadata.
+- Same `data-color` / `data-size` as badge.
+
+### `.rcm-chip`
+Interactive chip (filter chip, selection).
+- `data-interactive` — adds hover/cursor
+- `data-state="selected"` — active state
+- `data-color="primary|neutral"`
+
+### `.rcm-icon`
+Unified icon sizing / tone wrapper.
+- `data-size="xs|sm|md|lg|xl"` — 12 / 14 / 16 / 20 / 24 px
+- `data-tone="muted|disabled|inherit"`
+- `data-color="primary|error|success|warning|info|secondary"`
+
+### `.rcm-icon-frame`
+Icon placed inside a colored surface chip.
+- `data-shape="circle|square|rounded"` (default `rounded`)
+- `data-size="xs|sm|md|lg"`
+- `data-color="primary|secondary|neutral|error|success|warning|info"`
+
+### `.rcm-skeleton`
+Loading placeholder rect.
+- `data-shape="line|circle|box"`
+- `data-size="sm|md|lg"` (when shape is line)
+- Legacy aliases: `.rcm-skeleton-accent` (primary tint), `.rcm-skeleton-danger` (error tint)
+
+---
+
+## Surface / messaging
+
+### `.rcm-notice`
+Info/warning/error callout box.
+- `data-tone="info|success|warning|error"` (preferred)
+- `data-variant="compact"` — smaller padding + xs font
+- Legacy class aliases: `.rcm-notice-info` / `-success` / `-warning` / `-error` (identical to `data-tone`, for host themes that emit className strings)
+
+### `.rcm-card`
+Bordered surface for card layouts.
+- `data-state="selected"` — primary-tinted border
+- `data-interactive` — hover ring
+
+### `.rcm-scroll-area`
+Container with custom scrollbar styling (WebKit).
+
+---
+
+## Navigation
+
+### `.rcm-tab-list`
+Horizontal tab nav container.
+
+### `.rcm-tab`
+Individual tab.
+- `data-state="selected"` — active tab (primary underline)
+- `data-state="disabled"` — muted + no cursor
+
+### `.rcm-menu` + `.rcm-menu-item` + `.rcm-menu-separator`
+Vertical menu list used in dropdowns.
+
+---
+
+## Utilities
+
+All utility classes are prefix `rcm-` and do exactly what their name says:
+
+- `.rcm-cursor-pointer` / `-grab` / `-grabbing` / `-help` / `-not-allowed`
+- `.rcm-bg-info-surface` / `-warning-surface` / `-error-surface` / `-success-surface`
+- `.rcm-radius-full` (pill)
+- `.rcm-flex-1`
+- `.rcm-gap-{xs|sm|md|lg|xl}`
+- `.rcm-ml-auto`
+- `.rcm-truncate` (ellipsis)
+- `.rcm-visually-hidden` (screen-reader-only)
+- `.rcm-scroll-y`
+- `.rcm-text-xs` / `-sm` / `-muted` / `-emphasis` / `-info` / `-warning` / `-error`
+- `.rcm-heading-sm`
+
+---
+
+## Theming
+
+### Token overrides
+Override design tokens in your own CSS, loaded **after** `@rchemist/listgrid/styles.css`:
+
+```css
+@import "@rchemist/listgrid/styles.css";
+
+:root {
+    --rcm-color-primary: #7c3aed;        /* purple brand */
+    --rcm-color-primary-hover: #6d28d9;
+    --rcm-font-family: "Pretendard", sans-serif;
+}
+```
+
+See [`tokens.css`](../src/listgrid/styles/tokens.css) for the full list (~50 tokens covering color, typography, spacing, sizing, radius, shadow, motion, z-index).
+
+### Dark mode
+Two activation paths:
+
+1. **Automatic** — respects OS preference:
+    ```html
+    <!-- nothing to do -->
+    ```
+    `@media (prefers-color-scheme: dark)` block in `tokens.css` kicks in automatically.
+
+2. **Explicit opt-in** — host controls via attribute:
+    ```html
+    <html data-theme="dark">   <!-- force dark -->
+    <html data-theme="light">  <!-- force light, ignore system -->
+    ```
+
+Only **surface / text / border / shadow** tokens flip by default. Brand colors (primary, secondary, info/success/warning/error) keep their light values — override them in your own `:root` if you want a different dark accent.
+
+### Runtime theming
+For multi-tenant apps, scope tokens to a class or data-attr on a specific ancestor:
+
+```css
+.brand-acme { --rcm-color-primary: #dc2626; }
+.brand-globex { --rcm-color-primary: #2563eb; }
+```
+
+```html
+<div class="brand-acme">
+  <ViewListGrid … />
+</div>
+```
+
+### Per-instance override via `classNames` prop
+Components accept a `classNames` prop with a slot map. See `ViewListGridClassNames` / `ViewEntityFormClassNames` types.
+
+```tsx
+<ViewListGrid
+  classNames={{
+    table: { container: 'my-custom-table' },
+    header: { buttonGroup: 'my-header-buttons' },
+  }}
+/>
+```
+
+---
+
+## Browser support
+
+Requires a browser with:
+- Container queries (Chrome 105+, Firefox 110+, Safari 16+)
+- `color-mix()` (Chrome 111+, Firefox 113+, Safari 16.2+)
+- CSS custom properties (all modern browsers)
+
+Practical floor: **browsers from 2023 onward**.
+
+---
+
+## See also
+
+- [`tokens.css`](../src/listgrid/styles/tokens.css) — all CSS custom properties
+- [`primitives.css`](../src/listgrid/styles/primitives.css) — primitive rules

package/package.json

@@ -0,0 +1,201 @@
+{
+    "name": "@rchemist/listgrid",
+    "version": "0.2.6",
+    "private": false,
+    "description": "Framework-free React CRUD UI engine — primitive-based design system, data-attr theming, and a full list/form renderer for RCM-framework-style entity backends.",
+    "keywords": [
+        "react",
+        "listgrid",
+        "crud",
+        "entity",
+        "form",
+        "table",
+        "design-system",
+        "css-primitives",
+        "data-attr",
+        "framework-free"
+    ],
+    "author": "rchemist.io",
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./next": {
+            "types": "./dist/adapters/next/index.d.ts",
+            "default": "./dist/adapters/next/index.js"
+        },
+        "./form/SearchForm": {
+            "types": "./dist/listgrid/form/SearchForm.d.ts",
+            "default": "./dist/listgrid/form/SearchForm.js"
+        },
+        "./form/Type": {
+            "types": "./dist/listgrid/form/Type.d.ts",
+            "default": "./dist/listgrid/form/Type.js"
+        },
+        "./api": {
+            "types": "./dist/listgrid/api/index.d.ts",
+            "default": "./dist/listgrid/api/index.js"
+        },
+        "./misc": {
+            "types": "./dist/listgrid/misc/index.d.ts",
+            "default": "./dist/listgrid/misc/index.js"
+        },
+        "./styles.css": "./dist/styles.css",
+        "./styles/tokens.css": "./dist/styles/tokens.css",
+        "./styles/primitives.css": "./dist/styles/primitives.css",
+        "./styles/layouts.css": "./dist/styles/layouts.css",
+        "./styles/components.css": "./dist/styles/components.css",
+        "./styles/base.css": "./dist/styles/base.css"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE",
+        "docs/PRIMITIVES.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rchemist/rcm-listgrid.git"
+    },
+    "bugs": {
+        "url": "https://github.com/rchemist/rcm-listgrid/issues"
+    },
+    "homepage": "https://github.com/rchemist/rcm-listgrid#readme",
+    "scripts": {
+        "type-check": "tsc --noEmit",
+        "build": "tsc -p tsconfig.build.json && npm run build:styles",
+        "build:styles": "mkdir -p dist/styles && cp src/listgrid/styles/tokens.css src/listgrid/styles/primitives.css src/listgrid/styles/layouts.css src/listgrid/styles/components.css src/listgrid/styles/base.css dist/styles/ && cat src/listgrid/styles/tokens.css src/listgrid/styles/primitives.css src/listgrid/styles/layouts.css src/listgrid/styles/components.css src/listgrid/styles/base.css > dist/styles.css",
+        "clean": "rm -rf dist",
+        "lint": "eslint 'src/**/*.{ts,tsx}'",
+        "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix",
+        "format": "prettier --write 'src/**/*.{ts,tsx,css,json}'",
+        "format:check": "prettier --check 'src/**/*.{ts,tsx,css,json}'",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "docs": "typedoc",
+        "docs:watch": "typedoc --watch"
+    },
+    "dependencies": {
+        "clsx": "^2.1.1",
+        "crypto-js": "^4.2.0",
+        "tailwind-merge": "^2.5.4",
+        "uuid": "^9.0.0",
+        "zustand": "^4.4.0"
+    },
+    "peerDependencies": {
+        "@headlessui/react": "^2.0.0",
+        "@iconify/react": "^4.0.0 || ^5.0.0",
+        "@tabler/icons-react": "^2.30.0 || ^3.0.0",
+        "date-fns": "^2.0.0 || ^3.0.0 || ^4.0.0",
+        "file-saver": "^2.0.5",
+        "next": ">=14",
+        "nuqs": ">=2.0.0",
+        "qrcode.react": "^3.0.0 || ^4.0.0",
+        "react": ">=18",
+        "react-daum-postcode": "^3.0.0",
+        "react-dom": ">=18",
+        "react-kakao-maps-sdk": "^1.0.0",
+        "react-select": "^5.0.0",
+        "react-sortablejs": "^6.0.0 || ^7.0.0",
+        "sweetalert2": "^11.0.0",
+        "sweetalert2-react-content": "^5.0.0",
+        "xlsx-js-style": "^1.2.0"
+    },
+    "peerDependenciesMeta": {
+        "@tabler/icons-react": {
+            "optional": false
+        },
+        "@headlessui/react": {
+            "optional": false
+        },
+        "next": {
+            "optional": true
+        },
+        "nuqs": {
+            "optional": true
+        },
+        "@iconify/react": {
+            "optional": true
+        },
+        "react-select": {
+            "optional": true
+        },
+        "react-sortablejs": {
+            "optional": true
+        },
+        "qrcode.react": {
+            "optional": true
+        },
+        "react-kakao-maps-sdk": {
+            "optional": true
+        },
+        "react-daum-postcode": {
+            "optional": true
+        },
+        "xlsx-js-style": {
+            "optional": true
+        },
+        "file-saver": {
+            "optional": true
+        },
+        "sweetalert2": {
+            "optional": true
+        },
+        "sweetalert2-react-content": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@headlessui/react": "^2.2.9",
+        "@iconify/react": "^4.1.1",
+        "@tabler/icons-react": "^2.30.0",
+        "@testing-library/dom": "^10.4.1",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@types/crypto-js": "^4.2.2",
+        "@types/file-saver": "^2.0.7",
+        "@types/node": "^22.0.2",
+        "@types/react": "^19.2.7",
+        "@types/react-dom": "^19.2.0",
+        "@types/sortablejs": "^1.15.9",
+        "@types/uuid": "^9.0.0",
+        "@typescript-eslint/eslint-plugin": "^8.58.2",
+        "@typescript-eslint/parser": "^8.58.2",
+        "@vitest/coverage-v8": "^4.1.4",
+        "date-fns": "^3.6.0",
+        "eslint": "^10.2.1",
+        "eslint-plugin-react": "^7.37.5",
+        "eslint-plugin-react-hooks": "^7.1.1",
+        "file-saver": "^2.0.5",
+        "globals": "^16.5.0",
+        "jsdom": "^29.0.2",
+        "next": "^15.0.0",
+        "nuqs": "^2.0.0",
+        "prettier": "^3.8.3",
+        "qrcode.react": "^3.1.0",
+        "react": "^19.2.1",
+        "react-daum-postcode": "^3.1.3",
+        "react-dom": "^19.2.1",
+        "react-kakao-maps-sdk": "^1.1.27",
+        "react-select": "^5.10.2",
+        "react-sortablejs": "^6.1.4",
+        "sortablejs": "^1.15.7",
+        "sweetalert2": "^11.6.13",
+        "sweetalert2-react-content": "^5.0.7",
+        "typedoc": "^0.28.19",
+        "typedoc-plugin-markdown": "^4.11.0",
+        "typescript": "^5.5.0",
+        "typescript-eslint": "^8.58.2",
+        "vitest": "^4.1.4",
+        "xlsx-js-style": "^1.2.0"
+    }
+}