release v0.5.0

Author: jpmarindiaz

BROWSER.md

@@ -200,6 +200,77 @@ interface MonkeyTableColumn {
 
 ---
 
+## Config-driven API
+
+If you'd rather describe a whole table as one JSON blob — for example to store
+a user's table layout, serve a table from a REST endpoint, or have an LLM emit
+it from a sample of rows — use `<MonkeyTableFromConfig>`.
+
+```tsx
+import { MonkeyTableFromConfig, type MonkeyTableConfig } from '@datasketch/monkeytab';
+
+const config: MonkeyTableConfig = {
+  columns: [
+    { id: 'Name' },
+    { id: 'Age', type: 'Number', options: { format: 'decimal' } },
+    { id: 'Signup', type: 'Date', options: { dateFormat: 'iso' } },
+    { id: 'Status', type: 'SingleSelect', options: {
+      options: [
+        { value: 'active', label: 'Active', color: '#22c55e' },
+        { value: 'paused', label: 'Paused', color: '#f59e0b' },
+      ],
+    } },
+    { id: 'Website', type: 'URL' },
+  ],
+  rows: [
+    { Name: 'Alice', Age: 30, Signup: '2024-01-05', Status: 'active',  Website: 'https://example.com' },
+    { Name: 'Bob',   Age: 25, Signup: '2024-02-10', Status: 'paused',  Website: 'https://example.org' },
+  ],
+  settings: {
+    editable: true,
+    height: 'auto',
+    pageSize: 25,
+    locale: 'en-US',
+  },
+};
+
+<MonkeyTableFromConfig config={config} onChange={setRows} />
+```
+
+### Shape
+
+```ts
+interface MonkeyTableConfig {
+  schemaVersion?: number;              // reserved for future migrators
+  columns: MonkeyTableConfigColumn[];  // same as MonkeyTableColumn, minus render/icon
+  rows: Array<Record<string, Value>>;
+  settings?: MonkeyTableConfigSettings;
+}
+```
+
+`settings` is a flat bucket that mirrors the scalar/enum props documented
+above — `editable`, `height`, `pageSize`, `locale`, `groupBy`, `sortBy`,
+`dateDisplayFormat`, etc. Anything not serializable (React handlers, custom
+renderers/editors, `render`/`icon` on a column, `functions`/`constraints`,
+`presence`) stays as ordinary component props on `<MonkeyTableFromConfig>`.
+
+### resolveConfig
+
+If you'd rather keep using `<MonkeyTable>` directly, import `resolveConfig`
+to turn a config into the flat prop object it consumes:
+
+```tsx
+import { MonkeyTable, resolveConfig } from '@datasketch/monkeytab';
+
+const props = resolveConfig(config);
+<MonkeyTable {...props} onChange={setRows} />
+```
+
+The two forms are interchangeable — `<MonkeyTableFromConfig>` is a thin
+forwardRef wrapper that does exactly this internally.
+
+---
+
 ## Keyboard Shortcuts
 
 | Key | Action |

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-04-19
+
+### New
+- **`<MonkeyTableFromConfig>` + `resolveConfig()`** — describe a whole table as one JSON blob (`{ columns, rows, settings }`) and render it with a single component. The settings bucket mirrors the flat `<MonkeyTable>` props exactly; anything not serializable (handlers, custom renderers/editors, per-column `render`/`icon`) stays as ordinary React props on the wrapper. Use `resolveConfig(config)` to get the same props object if you'd rather keep using `<MonkeyTable>` directly. Useful for persisting user layouts, embedding tables in REST payloads, or having an LLM emit a table from a row sample. See [BROWSER.md → Config-driven API](./BROWSER.md#config-driven-api).
+
 ## [0.4.0] — 2026-04-18
 
 ### New
@@ -113,7 +118,8 @@ First public release.
 - `onUpload` prop — bring your own file upload (S3, Cloudinary, etc.)
 - Drag-and-drop and paste support for Image cells
 
-[Unreleased]: https://github.com/datasketch/monkeytab/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/datasketch/monkeytab/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/datasketch/monkeytab/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/datasketch/monkeytab/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/datasketch/monkeytab/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/datasketch/monkeytab/compare/v0.2.0...v0.2.1

examples/browser-standalone/main.tsx

@@ -6,7 +6,7 @@
 
 import React, { useState, useMemo, useRef, useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
-import { MonkeyTable, type MonkeyTableHandle } from '@monkeytab/browser';
+import { MonkeyTable, MonkeyTableFromConfig, type MonkeyTableHandle, type MonkeyTableConfig } from '@monkeytab/browser';
 import type { Value, PresenceUser, RemoteChangeEvent } from '@monkeytab/browser';
 
 // ---------------------------------------------------------------------------
@@ -833,8 +833,131 @@ function applyToLocalRows(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Example: Config-driven table — one JSON blob renders the whole thing
+//
+// Shows <MonkeyTableFromConfig> in action. Everything you'd normally spread
+// across columns + props + options lives in one serializable object that
+// round-trips through JSON.stringify. Non-serializable pieces (here: onChange)
+// stay as ordinary React props on the wrapper.
+// ---------------------------------------------------------------------------
+
+const FROM_CONFIG_INITIAL: MonkeyTableConfig = {
+  schemaVersion: 1,
+  columns: [
+    { id: 'Name' },
+    { id: 'Email', type: 'Email' },
+    { id: 'Role', type: 'SingleSelect', options: {
+      options: [
+        { value: 'Engineer', label: 'Engineer', color: '#dbeafe' },
+        { value: 'Designer', label: 'Designer', color: '#fce7f3' },
+        { value: 'Manager',  label: 'Manager',  color: '#dcfce7' },
+      ],
+    } },
+    { id: 'Salary',  type: 'Number',  options: { format: 'currency', precision: 0 } },
+    { id: 'Joined',  type: 'Date',    options: { dateFormat: 'iso' } },
+    { id: 'Active',  type: 'Boolean' },
+    { id: 'Website', type: 'URL' },
+  ],
+  rows: [
+    { Name: 'Alice Chen', Email: 'alice@acme.com', Role: 'Engineer', Salary: 95000,  Joined: '2022-03-15', Active: true,  Website: 'https://alicechen.dev' },
+    { Name: 'Bob Smith',  Email: 'bob@acme.com',   Role: 'Designer', Salary: 82000,  Joined: '2021-07-01', Active: true,  Website: 'https://bobsmith.design' },
+    { Name: 'Carol Wu',   Email: 'carol@acme.com', Role: 'Manager',  Salary: 110000, Joined: '2020-11-20', Active: false, Website: 'https://carolwu.io' },
+  ],
+  settings: {
+    editable: true,
+    height: 'auto',
+    rowHeight: 'medium',
+    pageSize: 25,
+    locale: 'en-US',
+    currencyCode: 'USD',
+    showRowNumbers: true,
+  },
+};
+
+function FromConfigExample({ locale, language, compactMode }: { locale: string; language: string; compactMode: boolean }) {
+  const [config, setConfig] = useState<MonkeyTableConfig>(FROM_CONFIG_INITIAL);
+  const [configText, setConfigText] = useState(() => JSON.stringify(FROM_CONFIG_INITIAL, null, 2));
+  const [parseError, setParseError] = useState<string | null>(null);
+
+  // Merge the tab-level locale/compact controls onto the config's own settings
+  // so the top-bar switches still work for this tab.
+  const effectiveConfig = useMemo<MonkeyTableConfig>(() => ({
+    ...config,
+    settings: {
+      ...config.settings,
+      locale,
+      language,
+      compactMode,
+    },
+  }), [config, locale, language, compactMode]);
+
+  const handleConfigChange = (text: string) => {
+    setConfigText(text);
+    try {
+      const parsed = JSON.parse(text) as MonkeyTableConfig;
+      setConfig(parsed);
+      setParseError(null);
+    } catch (err) {
+      setParseError(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  const handleRowsChange = (rows: Array<Record<string, Value>>) => {
+    // Reflect live edits back into the config so the JSON pane stays in sync.
+    setConfig((prev) => ({ ...prev, rows }));
+    setConfigText(JSON.stringify({ ...config, rows }, null, 2));
+  };
+
+  return (
+    <div className="example">
+      <h2>From Config</h2>
+      <div className="desc">
+        One <code>MonkeyTableConfig</code> blob — <code>{`{ columns, rows, settings }`}</code> — rendered by{' '}
+        <code>&lt;MonkeyTableFromConfig&gt;</code>. Edit the JSON on the right and the table re-renders live.
+        Edit cells in the table and the JSON updates to match.
+      </div>
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 440px', gap: 16, alignItems: 'stretch' }}>
+        <div className="table-container" style={{ height: 420 }}>
+          <MonkeyTableFromConfig
+            config={effectiveConfig}
+            onChange={handleRowsChange}
+          />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+          <div style={{ fontSize: 12, fontWeight: 600, color: '#374151' }}>config (live JSON)</div>
+          <textarea
+            value={configText}
+            onChange={(e) => handleConfigChange(e.target.value)}
+            spellCheck={false}
+            style={{
+              flex: 1,
+              minHeight: 380,
+              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+              fontSize: 12,
+              lineHeight: 1.5,
+              padding: 10,
+              borderRadius: 6,
+              border: `1px solid ${parseError ? '#ef4444' : '#d1d5db'}`,
+              background: '#fafafa',
+              color: '#111827',
+              resize: 'vertical',
+            }}
+          />
+          {parseError && (
+            <div style={{ fontSize: 12, color: '#b91c1c' }}>
+              JSON parse error: {parseError} — table still shows the last valid config.
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
 const TABS: Array<{ id: string; label: string; private?: boolean }> = [
   { id: 'editable', label: 'Editable' },
+  { id: 'from-config', label: 'From Config' },
   { id: 'async-crud', label: 'Async CRUD' },
   { id: 'multiplayer', label: 'Multiplayer' },
   { id: 'height', label: 'Height Modes' },
@@ -1011,6 +1134,10 @@ function App() {
           </div>
         )}
 
+        {tab === 'from-config' && (
+          <FromConfigExample locale={locale} language={language} compactMode={compactMode} />
+        )}
+
         {tab === 'height' && (
           <HeightModesExample locale={locale} language={language} compactMode={compactMode} />
         )}

examples/browser-standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-standalone",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "scripts": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datasketch/monkeytab",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Embeddable, editable React table component",
   "keywords": [
     "react",

src/browser/MonkeyTableFromConfig.tsx

@@ -0,0 +1,52 @@
+/**
+ * MonkeyTableFromConfig — façade that accepts a flat JSON config and forwards
+ * everything non-serializable (handlers, presence, custom renderers, ref) as
+ * ordinary React props.
+ *
+ *   <MonkeyTableFromConfig
+ *     config={{ columns, rows, settings }}
+ *     onChange={handle}
+ *   />
+ */
+import { forwardRef } from 'react';
+import type { ForwardedRef } from 'react';
+import { MonkeyTable, type MonkeyTableHandle, type MonkeyTableProps } from './MonkeyTable.tsx';
+import { resolveConfig, type MonkeyTableConfig } from './config.ts';
+
+/**
+ * Anything that can't live in JSON: React handlers, presence data, custom
+ * function/constraint/renderer/editor registrations, selection actions,
+ * upload hook, column lifecycle callbacks. These stay as component props.
+ */
+export type MonkeyTableRuntimeProps = Pick<MonkeyTableProps,
+  | 'onChange' | 'onRowsChange' | 'onSelectionChange' | 'onRowClick'
+  | 'onCellChange' | 'onActiveCellChange'
+  | 'onRowCreate' | 'onCellSave' | 'onRowDelete' | 'onHookError'
+  | 'onGroupByChange' | 'onColorByChange' | 'onSortChange' | 'onPageChange'
+  | 'onColumnRename' | 'onColumnDelete' | 'onColumnCreate'
+  | 'onColumnChangeType' | 'onColumnUpdateOptions'
+  | 'onUpload'
+  | 'rowKey'
+  | 'selectionActions'
+  | 'presence'
+  | 'functions' | 'constraints' | 'renderers' | 'editors'
+>;
+
+export interface MonkeyTableFromConfigProps extends MonkeyTableRuntimeProps {
+  config: MonkeyTableConfig;
+}
+
+function MonkeyTableFromConfigInner(
+  { config, ...runtime }: MonkeyTableFromConfigProps,
+  ref: ForwardedRef<MonkeyTableHandle>,
+) {
+  const resolved = resolveConfig(config);
+  // Runtime `rowKey` (including the function form) takes precedence over any
+  // string in the config — lets consumers escalate from JSON to code gradually.
+  return <MonkeyTable ref={ref} {...resolved} {...runtime} />;
+}
+
+export const MonkeyTableFromConfig = forwardRef<MonkeyTableHandle, MonkeyTableFromConfigProps>(
+  MonkeyTableFromConfigInner,
+);
+MonkeyTableFromConfig.displayName = 'MonkeyTableFromConfig';