Create basic Widget Grid library

.vscode/settings.json

@@ -23,10 +23,10 @@
 	// File nesting in explorer
 	"explorer.fileNesting.enabled": true,
 	"explorer.fileNesting.patterns": {
-		"*.ts": "${capture}.js, ${capture}.test.ts",
-		"*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts, ${capture}.test.js",
-		"*.jsx": "${capture}.js",
-		"*.tsx": "${capture}.ts, ${capture}.stories.tsx",
+		"*.ts": "${capture}.js, ${capture}.test.ts, ${capture}.md",
+		"*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts, ${capture}.test.js, ${capture}.md",
+		"*.jsx": "${capture}.js, ${capture}.md",
+		"*.tsx": "${capture}.ts, ${capture}.stories.tsx, ${capture}.md",
 		".npmrc": ".nvmrc, .yarnrc.yml",
 		".gitignore": ".eslintignore, .prettierignore, .dockerignore",
 		"README.md": "CONTRIBUTING.md, CODE_OF_CONDUCT.md",

README.md

@@ -33,6 +33,7 @@ A collection of open source libraries maintained by [builder.group](https://buil
 | [validatenv](https://github.com/builder-group/community/blob/develop/packages/validatenv)                         | Type-safe, straightforward, and lightweight library for validating environment variables using existing validation libraries like Zod, Valibot, and Yup.                       | [`validatenv`](https://www.npmjs.com/package/validatenv)                         |
 | [validation-adapter](https://github.com/builder-group/community/blob/develop/packages/validation-adapter)         | Universal validation adapter that integrates various validation libraries like Zod, Valibot, and Yup                                                                           | [`validation-adapter`](https://www.npmjs.com/package/validation-adapter)         |
 | [validation-adapters](https://github.com/builder-group/community/blob/develop/packages/validation-adapters)       | Pre-made validation adapters for the validation-adapter library, including adapters for Zod and Valibot                                                                        | [`validation-adapters`](https://www.npmjs.com/package/validation-adapters)       |
+| [widget-grid](https://github.com/builder-group/community/blob/develop/packages/widget-grid)                       | Framework agnostic library for creating and manipulating widget grids                                                                                                          | [`widget-grid`](https://www.npmjs.com/package/widget-grid)                       |
 | [xml-tokenizer](https://github.com/builder-group/community/blob/develop/packages/xml-tokenizer)                   | Straightforward and typesafe XML tokenizer that streams tokens through a callback mechanism                                                                                    | [`xml-tokenizer`](https://www.npmjs.com/package/xml-tokenizer)                   |
 
 ### 📚 Examples
@@ -109,3 +110,9 @@ createState({
 We currently use the "wrapper pattern" because it ensures better TypeScript type inference. Each wrapper function modifies the state's type in a specific sequence, which is harder to achieve reliably with a feature array.
 
 We're [actively exploring solutions](https://github.com/builder-group/community/blob/develop/packages/feature-state/src/_experimental) to support both patterns, combining the type safety of the wrapper pattern with the simplicity of declarative APIs. Contributions and ideas are always welcome :)
+
+### Why do feature-based libraries use Objects instead of Classes?
+
+This [Medium post](https://medium.com/@markmiro/thoughts-on-choosing-between-plain-js-objects-and-classes-6422af8aaad5) explains the key differences well.
+
+In short, we use objects because they are more flexible and allow for the kind of extensibility we need. Achieving this level of extensibility with classes isn't feasible for our use case, so using objects was the better choice.

examples/widget-grid/react/basic/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/widget-grid/react/basic/README.md

@@ -0,0 +1,50 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+
+- Configure the top-level `parserOptions` property like this:
+
+```js
+export default tseslint.config({
+	languageOptions: {
+		// other options...
+		parserOptions: {
+			project: ['./tsconfig.node.json', './tsconfig.app.json'],
+			tsconfigRootDir: import.meta.dirname
+		}
+	}
+});
+```
+
+- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
+- Optionally add `...tseslint.configs.stylisticTypeChecked`
+- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
+
+```js
+// eslint.config.js
+import react from 'eslint-plugin-react';
+
+export default tseslint.config({
+	// Set the react version
+	settings: { react: { version: '18.3' } },
+	plugins: {
+		// Add the react plugin
+		react
+	},
+	rules: {
+		// other rules...
+		// Enable its recommended rules
+		...react.configs.recommended.rules,
+		...react.configs['jsx-runtime'].rules
+	}
+});
+```

examples/widget-grid/react/basic/eslint.config.js

@@ -0,0 +1,25 @@
+import js from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+	{ ignores: ['dist'] },
+	{
+		extends: [js.configs.recommended, ...tseslint.configs.recommended],
+		files: ['**/*.{ts,tsx}'],
+		languageOptions: {
+			ecmaVersion: 2020,
+			globals: globals.browser
+		},
+		plugins: {
+			'react-hooks': reactHooks,
+			'react-refresh': reactRefresh
+		},
+		rules: {
+			...reactHooks.configs.recommended.rules,
+			'react-refresh/only-export-components': ['warn', { allowConstantExport: true }]
+		}
+	}
+);

examples/widget-grid/react/basic/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React + TS</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/widget-grid/react/basic/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "basic",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "tsc -b && vite build",
+		"dev": "vite",
+		"lint": "eslint .",
+		"preview": "vite preview"
+	},
+	"dependencies": {
+		"feature-react": "workspace:*",
+		"feature-state": "workspace:*",
+		"react": "^18.3.1",
+		"react-dom": "^18.3.1",
+		"widget-grid": "workspace:*"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.17.0",
+		"@types/react": "^18.3.18",
+		"@types/react-dom": "^18.3.5",
+		"@vitejs/plugin-react": "^4.3.4",
+		"eslint": "^9.17.0",
+		"eslint-plugin-react-hooks": "^5.0.0",
+		"eslint-plugin-react-refresh": "^0.4.16",
+		"globals": "^15.14.0",
+		"typescript": "~5.6.2",
+		"typescript-eslint": "^8.18.2",
+		"vite": "^6.0.5"
+	}
+}

examples/widget-grid/react/basic/src/App.tsx

@@ -0,0 +1,63 @@
+import { withGlobalBind } from 'feature-react/state';
+import React, { useState } from 'react';
+import { WidgetGrid } from './components';
+import './index.css';
+import { TWidgetGridPresetKey, widgetGridPresets } from './widget-grid';
+
+const App: React.FC = () => {
+	const [currentWidgetGridPresetKey, setWidgetGridPresetKey] =
+		useState<TWidgetGridPresetKey>('playground');
+
+	const preset = React.useMemo(
+		() => withGlobalBind('__widgetGrid', widgetGridPresets[currentWidgetGridPresetKey]),
+		[currentWidgetGridPresetKey]
+	);
+
+	return (
+		<div style={{ width: '100%', height: '100vh', backgroundColor: 'blue', padding: '48px' }}>
+			<div style={{ marginBottom: '20px' }}>
+				<select
+					value={currentWidgetGridPresetKey}
+					onChange={(e) => setWidgetGridPresetKey(e.target.value as TWidgetGridPresetKey)}
+					style={{ marginRight: '10px' }}
+				>
+					<option value="playground">Playground</option>
+					<option value="performance">Performance Test</option>
+				</select>
+
+				{preset.actions.map((action, index) => (
+					<button
+						key={index}
+						onClick={() => action.action(preset.grid as any)}
+						style={{ marginRight: '10px' }}
+					>
+						{action.label}
+					</button>
+				))}
+			</div>
+
+			<WidgetGrid
+				widgetGrid={preset.grid as any}
+				renderItem={(item) => {
+					return (
+						<div
+							style={{
+								backgroundColor: 'red',
+								width: '100%',
+								height: '100%',
+								display: 'flex',
+								justifyContent: 'center',
+								alignItems: 'center',
+								border: '1px solid black'
+							}}
+						>
+							{item.id}
+						</div>
+					);
+				}}
+			/>
+		</div>
+	);
+};
+
+export default App;