Sync: auto-height mode, maxHeight prop, visibility metadata

Author: jpmarindiaz

BROWSER.md

@@ -28,7 +28,7 @@ function App() {
         { Name: 'Bob', Age: 25, Active: false },
       ]}
       onChange={(rows) => console.log('Updated:', rows)}
-      height={400}
+      height="auto"
     />
   );
 }
@@ -75,11 +75,12 @@ function App() {
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `height` | `number \| string` | `'100%'` | Container height (number = pixels) |
+| `height` | `'auto' \| number \| string` | `'100%'` | `'auto'` fits content, number = fixed pixels (ghost rows on), string = CSS |
+| `maxHeight` | `number` | — | Max height in px. Caps `'auto'` growth or fluid containers |
 | `rowHeight` | `RowHeightOption` | `'medium'` | `'short'` \| `'medium'` \| `'tall'` \| `'extra-tall'` \| `'fit'` |
 | `showRowNumbers` | `boolean` | `false` | Show row number column |
 | `compactMode` | `boolean` | `false` | Denser layout — smaller fonts, tighter padding |
-| `ghostGrid` | `boolean \| { rows?: number, columns?: number }` | — | Show faint placeholder cells to fill the viewport |
+| `ghostGrid` | `boolean \| { rows?: number, columns?: number }` | — | Show faint placeholder cells to fill the viewport. Defaults to `true` when `height` is a number |
 
 ### Permissions
 

README.md

@@ -33,7 +33,7 @@ function App() {
         { Name: 'Beta', Score: 7.2, Status: 'done', Due: '2026-04-01', Approved: false },
       ]}
       onChange={(rows) => console.log('Updated:', rows)}
-      height={500}
+      height="auto"
     />
   );
 }

docs/guides/getting-started.md

@@ -28,7 +28,7 @@ function App() {
         { Name: 'Bob', Age: 25, Active: false },
       ]}
       onChange={(rows) => console.log('Updated:', rows)}
-      height={400}
+      height="auto"
     />
   );
 }

examples/browser-standalone/index.html

@@ -15,6 +15,8 @@
     .tab:hover { background: #f3f4f6; color: #374151; }
     .tab-active { background: #111827; color: white; border-color: #111827; }
     .tab-active:hover { background: #1f2937; }
+    .tab-private { border-color: #dc2626 !important; color: #dc2626 !important; }
+    .tab-private.tab-active { background: #dc2626 !important; border-color: #dc2626 !important; color: white !important; }
     .controls { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
     .tab-panel { }
     .example { background: white; border-radius: 8px; border: 1px solid #e5e7eb; padding: 24px; margin-bottom: 32px; }

examples/browser-standalone/main.tsx

@@ -425,16 +425,153 @@ function EmptyTableExample({ locale, language, ghostGrid, compactMode }: { local
   );
 }
 
-const TABS = [
+// ---------------------------------------------------------------------------
+// Example 7: Height modes comparison
+// ---------------------------------------------------------------------------
+
+const HEIGHT_COLUMNS = [
+  { id: 'Organization' },
+  { id: 'Slug' },
+  { id: 'Status', type: 'SingleSelect' as const, options: { options: [
+    { value: 'Synced', label: 'Synced', color: '#dcfce7' },
+    { value: 'Pending', label: 'Pending', color: '#fef3c7' },
+    { value: 'Error', label: 'Error', color: '#fecaca' },
+  ]}},
+  { id: 'Filter' },
+  { id: 'Link', type: 'URL' as const },
+];
+
+const HEIGHT_ROWS_3 = [
+  { Organization: 'test', Slug: 'test', Status: 'Synced', Filter: "filter(org_slug == 'test')", Link: '/test/db/news-articles' },
+  { Organization: 'testorg', Slug: 'testorg', Status: 'Synced', Filter: "filter(org_slug == 'testorg')", Link: '/testorg/db/news-articles' },
+  { Organization: 'acme', Slug: 'acme', Status: 'Pending', Filter: "filter(org_slug == 'acme')", Link: '/acme/db/news-articles' },
+];
+
+const HEIGHT_ROWS_1 = [HEIGHT_ROWS_3[0]];
+
+type HeightMode = 'auto' | 'auto-capped' | 'fixed-400' | 'fixed-400-no-ghost' | 'fill';
+
+const HEIGHT_MODES: { id: HeightMode; label: string; code: string }[] = [
+  { id: 'auto', label: 'auto', code: 'height="auto"' },
+  { id: 'auto-capped', label: 'auto + maxHeight', code: 'height="auto" maxHeight={300}' },
+  { id: 'fixed-400', label: '400px (ghost on)', code: 'height={400}' },
+  { id: 'fixed-400-no-ghost', label: '400px (ghost off)', code: 'height={400} ghostGrid={false}' },
+  { id: 'fill', label: '100% (fill parent)', code: 'height="100%"' },
+];
+
+function HeightModeTable({ rows, mode, locale, language, compactMode }: {
+  rows: Array<Record<string, Value>>;
+  mode: HeightMode;
+  locale: string;
+  language: string;
+  compactMode: boolean;
+}) {
+  const heightProps = (() => {
+    switch (mode) {
+      case 'auto': return { height: 'auto' as const };
+      case 'auto-capped': return { height: 'auto' as const, maxHeight: 300 };
+      case 'fixed-400': return { height: 400 };
+      case 'fixed-400-no-ghost': return { height: 400, ghostGrid: false as const };
+      case 'fill': return { height: '100%' };
+    }
+  })();
+
+  const needsContainer = mode === 'fill';
+
+  const table = (
+    <MonkeyTable
+      columns={HEIGHT_COLUMNS}
+      rows={rows}
+      editable={false}
+      showToolbar={false}
+      compactMode={compactMode}
+      locale={locale}
+      language={language}
+      {...heightProps}
+    />
+  );
+
+  if (needsContainer) {
+    return <div style={{ height: '300px', border: '1px dashed #d1d5db', borderRadius: '6px' }}>{table}</div>;
+  }
+  return table;
+}
+
+function HeightModesExample({ locale, language, compactMode }: { locale: string; language: string; compactMode: boolean }) {
+  const [mode, setMode] = useState<HeightMode>('auto');
+
+  const currentMode = HEIGHT_MODES.find((m) => m.id === mode)!;
+
+  return (
+    <div className="example">
+      <h2>Height Modes</h2>
+      <div className="desc" style={{ display: 'flex', alignItems: 'center', gap: '12px', flexWrap: 'wrap', marginBottom: '12px' }}>
+        <span>Compare how different <code>height</code> modes handle 0, 1, and 3 rows.</span>
+        <div style={{ display: 'flex', gap: '4px' }}>
+          {HEIGHT_MODES.map((m) => (
+            <button
+              key={m.id}
+              onClick={() => setMode(m.id)}
+              style={{
+                padding: '3px 10px',
+                fontSize: '12px',
+                fontWeight: mode === m.id ? 600 : 400,
+                borderRadius: '4px',
+                border: '1px solid',
+                borderColor: mode === m.id ? '#111827' : '#d1d5db',
+                background: mode === m.id ? '#111827' : 'white',
+                color: mode === m.id ? 'white' : '#374151',
+                cursor: 'pointer',
+              }}
+            >
+              {m.label}
+            </button>
+          ))}
+        </div>
+      </div>
+      <div style={{ marginBottom: '16px', padding: '6px 12px', background: '#f9fafb', borderRadius: '4px', fontFamily: 'monospace', fontSize: '13px', color: '#6b7280' }}>
+        {'<MonkeyTable '}{currentMode.code}{' />'}
+        {mode === 'fill' && <span style={{ color: '#9ca3af' }}> (inside a 300px container)</span>}
+      </div>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+        {([
+          { label: '0 rows (empty)', rows: [] as Array<Record<string, Value>> },
+          { label: '1 row', rows: HEIGHT_ROWS_1 },
+          { label: '3 rows', rows: HEIGHT_ROWS_3 },
+        ]).map((scenario) => (
+          <div key={scenario.label}>
+            <div style={{ fontSize: '13px', fontWeight: 600, color: '#374151', marginBottom: '6px' }}>
+              {scenario.label}
+            </div>
+            <div style={{ border: '1px solid #e5e7eb', borderRadius: '6px', overflow: 'hidden' }}>
+              <HeightModeTable
+                rows={scenario.rows}
+                mode={mode}
+                locale={locale}
+                language={language}
+                compactMode={compactMode}
+              />
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+
+const TABS: Array<{ id: string; label: string; private?: boolean }> = [
   { id: 'editable', label: 'Editable' },
+  { id: 'height', label: 'Height Modes' },
   { id: 'columns', label: 'Column Options' },
   { id: 'empty', label: 'Empty Table' },
   { id: 'readonly', label: 'Read-Only' },
   { id: 'large', label: 'Large Dataset' },
   { id: 'pagination', label: 'Pagination' },
-] as const;
+];
 
-type TabId = typeof TABS[number]['id'];
+type TabId = string;
 
 function App() {
   const [tab, setTab] = useState<TabId>('editable');
@@ -467,7 +604,7 @@ function App() {
           {TABS.map((t) => (
             <button
               key={t.id}
-              className={`tab ${tab === t.id ? 'tab-active' : ''}`}
+              className={`tab ${tab === t.id ? 'tab-active' : ''}${t.private ? ' tab-private' : ''}`}
               onClick={() => setTab(t.id)}
             >
               {t.label}
@@ -550,6 +687,10 @@ function App() {
           </div>
         )}
 
+        {tab === 'height' && (
+          <HeightModesExample locale={locale} language={language} compactMode={compactMode} />
+        )}
+
         {tab === 'columns' && (
           <div className="example" style={{ display: 'flex', flexDirection: 'column', minHeight: 'calc(100vh - 200px)' }}>
             <h2>Column Options</h2>
@@ -602,6 +743,7 @@ function App() {
         {tab === 'pagination' && (
           <PaginationExample locale={locale} language={language} />
         )}
+
       </div>
     </div>
   );

src/browser/MonkeyTable.tsx

@@ -111,8 +111,14 @@ export interface MonkeyTableProps {
   /** Show faint ghost rows/columns to fill the viewport, spreadsheet-style.
    *  `true` auto-fills the visible area. Pass `{ rows, columns }` for explicit counts. */
   ghostGrid?: boolean | { rows?: number; columns?: number };
-  /** CSS height for the container (number = pixels, string = CSS value) */
-  height?: string | number;
+  /** Container height.
+   *  - `'auto'`: fits content exactly — no scrollbar for small tables. Pair with `maxHeight` to cap.
+   *  - `number`: fixed pixel height. `ghostGrid` defaults to `true` to fill empty space.
+   *  - CSS string (`'100%'`, `'50vh'`): fills parent (default `'100%'`). */
+  height?: 'auto' | number | string;
+  /** Maximum height in pixels. Useful with `height="auto"` to cap growth, or with
+   *  `height="100%"` to limit fluid containers. Ignored when `height` is a fixed number. */
+  maxHeight?: number;
   /** Row height preset (default: 'medium') */
   rowHeight?: RowHeightOption;
   /** Show row number column (default: false) */
@@ -190,6 +196,14 @@ export interface MonkeyTableProps {
 const BASE_ID = 'base-1';
 const TABLE_ID = 'table-1';
 
+// Chrome heights for auto-height calculation (must match Grid/TableView layout)
+const AUTO_HEIGHT_HEADER = 44;
+const AUTO_HEIGHT_TOOLBAR = 40;
+const AUTO_HEIGHT_FOOTER = 37;
+const AUTO_HEIGHT_CHROME = 2;
+const AUTO_ROW_HEIGHTS: Record<string, number> = { short: 32, medium: 44, tall: 64, 'extra-tall': 88 };
+const AUTO_COMPACT_ROW_HEIGHTS: Record<string, number> = { short: 24, medium: 28, tall: 40, 'extra-tall': 60 };
+
 export function MonkeyTable({
   // Data
   columns,
@@ -214,6 +228,7 @@ export function MonkeyTable({
   // Layout
   ghostGrid,
   height = '100%',
+  maxHeight,
   rowHeight,
   showRowNumbers,
   compactMode,
@@ -635,8 +650,33 @@ export function MonkeyTable({
     );
   }
 
+  // ── Height mode resolution ───────────────────────────────────────────
+  const isAutoHeight = height === 'auto';
+  const isFixedHeight = typeof height === 'number';
+
+  let resolvedHeight: string | number = height;
+  if (isAutoHeight) {
+    const rowHeightKey = rowHeight ?? 'medium';
+    const cellH = rowHeightKey === 'fit'
+      ? (compactMode ? 28 : 44)
+      : (compactMode ? AUTO_COMPACT_ROW_HEIGHTS : AUTO_ROW_HEIGHTS)[rowHeightKey] ?? 44;
+    const rowCount = inputRows?.length ?? 0;
+    const computed = AUTO_HEIGHT_HEADER
+      + (showToolbar !== false ? AUTO_HEIGHT_TOOLBAR : 0)
+      + rowCount * cellH
+      + AUTO_HEIGHT_FOOTER
+      + AUTO_HEIGHT_CHROME;
+    resolvedHeight = maxHeight ? Math.min(computed, maxHeight) : computed;
+  }
+
+  // Ghost grid: default to true for fixed-pixel heights so empty space is filled
+  const resolvedGhostGrid = ghostGrid !== undefined
+    ? ghostGrid
+    : isFixedHeight ? true : undefined;
+
   const containerStyle: React.CSSProperties = {
-    height: typeof height === 'number' ? `${height}px` : height,
+    height: typeof resolvedHeight === 'number' ? `${resolvedHeight}px` : resolvedHeight,
+    ...(maxHeight && !isFixedHeight && !isAutoHeight && { maxHeight: `${maxHeight}px` }),
     display: 'flex',
     flexDirection: 'column',
     overflow: 'hidden',
@@ -671,7 +711,7 @@ export function MonkeyTable({
                 page={page}
                 pageSize={pageSize}
                 onPageChange={onPageChange}
-                ghostGrid={ghostGrid}
+                ghostGrid={resolvedGhostGrid}
                 paginationMode={paginationMode}
                 paginationLoading={paginationLoading}
               />

src/browser/embed/EmbedMonkeyTable.tsx

@@ -209,6 +209,7 @@ export function EmbedMonkeyTable({
       rows={allRows}
       editable={false}
       height={config.height ?? '100%'}
+      maxHeight={config.maxHeight}
       rowHeight={config.rowHeight}
       showRowNumbers={config.rowNumbers}
       compactMode={config.compact}

src/browser/embed/TableViewConfig.ts

@@ -37,8 +37,10 @@ export interface TableViewConfig {
   rowNumbers?: boolean;
   /** Show ghost grid to fill viewport */
   ghostGrid?: boolean;
-  /** Container height in pixels (omit for auto/100%) */
-  height?: number;
+  /** Container height: 'auto' to fit content, or pixels. Omit for 100%. */
+  height?: 'auto' | number;
+  /** Maximum height in pixels (useful with height='auto') */
+  maxHeight?: number;
 
   // ── Toolbar & chrome ─────────────────────────────────────────────────────
   /** Show the toolbar (default: true for pages, false for embeds) */

src/browser/embed/configParams.ts

@@ -12,7 +12,8 @@
  *   compact=true
  *   rowNumbers=true
  *   ghostGrid=true
- *   height=500
+ *   height=500                     (or height=auto)
+ *   maxHeight=600
  *   toolbar=false
  *   showSearch=false
  *   showFilters=false
@@ -59,6 +60,7 @@ export function configToParams(config: TableViewConfig): URLSearchParams {
   if (config.rowNumbers !== undefined) p.set('rowNumbers', String(config.rowNumbers));
   if (config.ghostGrid !== undefined) p.set('ghostGrid', String(config.ghostGrid));
   if (config.height) p.set('height', String(config.height));
+  if (config.maxHeight) p.set('maxHeight', String(config.maxHeight));
 
   if (config.toolbar !== undefined) p.set('toolbar', String(config.toolbar));
   if (config.showSearch !== undefined) p.set('showSearch', String(config.showSearch));
@@ -124,8 +126,18 @@ export function paramsToConfig(params: URLSearchParams): TableViewConfig {
 
   const height = params.get('height');
   if (height) {
-    const n = parseInt(height, 10);
-    if (n > 0) config.height = n;
+    if (height === 'auto') {
+      config.height = 'auto';
+    } else {
+      const n = parseInt(height, 10);
+      if (n > 0) config.height = n;
+    }
+  }
+
+  const maxHeight = params.get('maxHeight');
+  if (maxHeight) {
+    const n = parseInt(maxHeight, 10);
+    if (n > 0) config.maxHeight = n;
   }
 
   const locale = params.get('locale');