jsoc-dev · amanx5 · Jul 30, 2026 · Apr 15, 2026 · Apr 28, 2026 · May 15, 2026
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -7,5 +7,5 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": []
+  "ignore": ["docs", "example-*"]
 }
diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml
@@ -0,0 +1,46 @@
+name: Commitlint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate commit messages
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            from="${{ github.event.pull_request.base.sha }}"
+            to="${{ github.event.pull_request.head.sha }}"
+          else
+            from="${{ github.event.before }}"
+            to="${{ github.event.after }}"
+            if [ "$from" = "0000000000000000000000000000000000000000" ]; then
+              from="origin/main"
+            fi
+          fi
+          pnpm exec commitlint --from "$from" --to "$to"
diff --git a/.gitignore b/.gitignore
@@ -45,3 +45,5 @@ out
 
 # ---------------VSC---------------
 !.vscode/extensions.json
+
+commit-msg.txt
diff --git a/.husky/commit-msg b/.husky/commit-msg
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,14 @@
+{
+  "css.lint.unknownAtRules": "ignore",
+  "editor.detectIndentation": true,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+
+  // settings for the latest VSCode version
+  "js/ts.tsdk.path": "node_modules/.pnpm/@typescript+typescript6@6.0.2/node_modules/@typescript/old/lib",
+  "js/ts.preferences.importModuleSpecifier": "non-relative",
+
+  // settings for the older VSCode versions
+  "typescript.tsdk": "node_modules/.pnpm/@typescript+typescript6@6.0.2/node_modules/@typescript/old/lib",
+  "typescript.preferences.importModuleSpecifier": "non-relative"
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -3,14 +3,28 @@
 ## Tools
 
 - This project uses `pnpm` as the package manager. Use `pnpm` commands whenever possible.
+- Before committing changes, verify that the commit message and body adhere to [commitlint](commitlint.config.ts) rules:
+  - Draft message: `pnpm commitlint` (pipe the message on stdin)
+  - Last commit: `pnpm commitlint -- --last`
 
-## Code Style
+---
+
+## General Code Practices
 
 ### Imports
 
+- Follow import/export sorting rules as specified in the root [ESLint config](eslint.config.ts).
 - Avoid using relative paths in imports.
 - Use absolute paths in the imports using Node Subpath imports if configured in the project's `package.json`.
 
 ### TypeScript
 
 - Avoid using 'any' in types/casts/assertions.
+
+---
+
+## Example Apps
+
+- All the example apps are located in [Examples](examples) grouped by frameworks.
+- Examples must be pure NPM packages so that they can be also run directly on environments like CodeSandbox/StackBlitz/etc.
+- Use NPM supported version specifiers only. Don't use PNPM "catalog:" or "workspace:" in package.json.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,22 +22,43 @@
 
 ## Commits
 
-- Please follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This is enforced by [commitlint](https://commitlint.js.org/) via a Husky hook. Refer to examples below:
-
-  | Change Type           | Commit Type | Example                                                         |
-  | :-------------------- | :---------- | :-------------------------------------------------------------- |
-  | **New Feature**       | `feat`      | `feat(core): add new feature`                                   |
-  | **Bug Fix**           | `fix`       | `fix(react): resolve bug`                                       |
-  | **Documentation**     | `docs`      | `docs: update contribution guide`                               |
-  | **Style Changes**     | `style`     | `style: fix indentation in config`                              |
-  | **Code Refactor**     | `refactor`  | `refactor(core): rename variable for clarity`                   |
-  | **Performance**       | `perf`      | `perf: optimized query execution`                               |
-  | **Testing**           | `test`      | `test(core): add unit tests` or `test: cover edge case in grid` |
-  | **Build System**      | `build`     | `build: update tsconfig.json` or `build: modify vite config`    |
-  | **CI/CD**             | `ci`        | `ci: add github action for tests`                               |
-  | **Chore/Maintenance** | `chore`     | `chore: update eslint rules` or `chore: add .gitignore entry`   |
-  | **Revert**            | `revert`    | `revert: "feat: add temporary logging"`                         |
-
-- This project uses [Husky](https://typicode.github.io/husky/) to run automated checks:
-  - `pre-commit`: Runs lint checks and formatting via [lint-staged](https://github.com/lint-staged/lint-staged) (using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)).
-  - `commit-msg`: Validates the commit message format using [commitlint](https://commitlint.js.org/).
+- Please follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+
+- Commit messages are validated in CI with [commitlint](https://commitlint.js.org/) on pull requests and pushes to `main` (see [.github/workflows/commitlint.yml](.github/workflows/commitlint.yml)).
+- Locally, [Husky](https://typicode.github.io/husky/) runs `pre-commit` only: lint and format staged files via [lint-staged](https://github.com/lint-staged/lint-staged) (using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)).
+
+
+### Commit Types
+
+Refer to the examples below:
+
+| Commit Type | Change Type           | Description                                                                                                                 | Example                                                                  |
+| :---------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
+| `feat`      | **New Feature**       | Introduces a new feature to the codebase or application.                                                                    | `feat(core): add new feature`                                            |
+| `fix`       | **Bug Fix**           | Resolves a bug or issue.                                                                                                    | `fix(react): resolve bug`                                                |
+| `docs`      | **Documentation**     | Updates or additions to documentation only.                                                                                 | `docs: update contribution guide`                                        |
+| `style`     | **Style Changes**     | Use style if the change only affects code formatting, white space, or visual polish without changing how the feature works. | `style: fix indentation in config`<br>`style: change text color to blue` |
+| `refactor`  | **Code Refactor**     | A code change that neither fixes a bug nor adds a feature (e.g., restructuring code).                                       | `refactor(core): rename variable for clarity`                            |
+| `perf`      | **Performance**       | A code change specifically aimed at improving performance.                                                                  | `perf: optimized query execution`                                        |
+| `test`      | **Testing**           | Adding missing tests or correcting existing tests.                                                                          | `test(core): add unit tests`<br>`test: cover edge case in grid`          |
+| `build`     | **Build System**      | Changes affecting the build system, compilers, or external dependencies.                                                    | `build: update tsconfig.json`<br>`build: modify vite config`             |
+| `ci`        | **CI/CD**             | Changes to CI/CD configuration files and scripts.                                                                           | `ci: add github action for tests`                                        |
+| `chore`     | **Chore/Maintenance** | Maintenance tasks, dependency updates, or changes that don't modify source/test files.                                      | `chore: update eslint rules`<br>`chore: add .gitignore entry`            |
+| `revert`    | **Revert**            | Reverts a previous commit.                                                                                                  | `revert: "feat: add temporary logging"`                                  |
+
+### Commit Scopes
+
+Use the published package name for reusable packages:
+
+- `grid`
+- `react-grid`
+- `grid-docs`
+- `grid-examples`
+
+Use the repository path for internal apps and examples:
+
+- `docs`
+- `examples`
+- `examples/react-grid/ant`
+- `examples/vue/basic`
+
diff --git a/README.md b/README.md
@@ -4,12 +4,6 @@ JSOC Grid brings the JSOC (JSON Structure Oriented Components) philosophy to dat
 
 With support for multiple popular grid libraries, it enables a plug-and-play architecture where grid configurations are automatically generated based on the JSON data.
 
-## Packages
-
-- [@jsoc/grid-core](https://github.com/jsoc-dev/grid/tree/main/packages/grid-core/README.md)
-- [@jsoc/react-grid](https://github.com/jsoc-dev/grid/tree/main/packages/react-grid/README.md)
-- [@jsoc/utils](https://github.com/jsoc-dev/grid/tree/main/packages/utils/README.md)
-
 ## Documentation
 
 Coming soon!
@@ -18,10 +12,10 @@ Coming soon!
 
 ## Contributing
 
-Please read the [contributing guide](https://github.com/jsoc-dev/grid/blob/main/CONTRIBUTING.md).
+Please read the [contributing guide](CONTRIBUTING.md).
 
 ---
 
 ## License
 
-Licensed under the [MIT license](https://github.com/jsoc-dev/grid/blob/main/LICENSE).
+Licensed under the [MIT license](LICENSE).
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# others
+public/examples
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -0,0 +1,7 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+
+<!-- END:nextjs-agent-rules -->
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/docs/eslint.config.ts b/docs/eslint.config.ts
@@ -0,0 +1,31 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+    // Ignore statically built examples
+    "public/examples/**",
+    // Ignore postcss config
+    "postcss.config.mjs",
+  ]),
+
+  {
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+]);
+
+export default eslintConfig;
diff --git a/docs/next.config.ts b/docs/next.config.ts
@@ -0,0 +1,37 @@
+import { CONTENT_DIR_BASE_PATH } from "@/config";
+import nextra from "nextra";
+
+const withNextra = nextra({
+  contentDirBasePath: CONTENT_DIR_BASE_PATH,
+  defaultShowCopyCode: true,
+});
+
+export default withNextra({
+  turbopack: {
+    rules: {
+      "*.svg": {
+        loaders: ["@svgr/webpack"],
+        as: "*.js",
+      },
+    },
+    resolveAlias: {
+      "next-mdx-import-source-file": "./src/mdx-components.tsx",
+    },
+  },
+
+  // mirror turbopack configs for webpack, so that next dev --webpack works too
+  webpack(config) {
+    config.module.rules.push({
+      test: /\.svg$/,
+      use: ["@svgr/webpack"],
+    });
+
+    config.resolve.fallback = {
+      ...config.resolve.fallback,
+      // Suppress missing module warnings from ts-morph's internal typescript compiler
+      "source-map-support": false,
+    };
+
+    return config;
+  },
+});
diff --git a/docs/package.json b/docs/package.json
@@ -0,0 +1,48 @@
+{
+  "name": "docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --webpack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@headless-tree/core": "^1.7.0",
+    "@headless-tree/react": "^1.7.0",
+    "@headlessui/react": "^2.2.10",
+    "@jsoc/grid-docs": "workspace:*",
+    "@jsoc/grid-examples-core": "workspace:*",
+    "@jsoc/react-grid-examples": "workspace:*",
+    "@jsoc/utils": "workspace:*",
+    "@monaco-editor/react": "^4.7.0",
+    "@radix-ui/react-scroll-area": "^1.2.13",
+    "@tanstack/react-query": "5.100.11",
+    "clsx": "^2.1.1",
+    "cookie": "^2.0.1",
+    "lucide-react": "^1.8.0",
+    "next": "16.2.6",
+    "next-themes": "^0.4.6",
+    "nextra": "^4.6.1",
+    "nextra-theme-docs": "^4.6.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-resizable-panels": "^4.12.1",
+    "shiki": "^4.2.0",
+    "vscode-icons-js": "^11.6.1"
+  },
+  "devDependencies": {
+    "@svgr/webpack": "^8.1.0",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "tailwindcss": "^4",
+    "ts-morph": "^28.0.0",
+    "typescript": "catalog:"
+  }
+}
diff --git a/docs/postcss.config.mjs b/docs/postcss.config.mjs
@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
diff --git a/docs/public/.well-known/appspecific/com.chrome.devtools.json b/docs/public/.well-known/appspecific/com.chrome.devtools.json
@@ -0,0 +1 @@
+{}
diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico
Original file line number	Diff line number	Diff line change
Expand Up		@@ -45,3 +45,5 @@ out

		# ---------------VSC---------------
		!.vscode/extensions.json

		commit-msg.txt