fix(kanban): surface off-column records in an Uncategorized lane (#2792) (#2804)

Records whose groupBy value matched no declared column were bucketed into
`groups` and then dropped — `groups[col.id]` never reads a key that isn't a
column id — so the board rendered empty while the list footer still counted
the rows, reading as data loss. Triggered by a status the board doesn't
render, an edited/removed picklist option, imported legacy data, or an
empty value.

- Extract the flat-data→columns bucketing into a pure, exported
  `bucketCardsIntoColumns` (the single choke point, now unit-testable).
- Append a trailing 'Uncategorized' lane (sentinel id KANBAN_UNCOLUMNED_ID)
  holding every record whose key matched no column, so nothing is invisible
  and the visible card total reconciles with the record count.
- Guard the drag-persist handler: dragging a card OUT of the lane into a
  real column repairs its status; dropping one IN is refused (the sentinel
  is not a real option).
- Add kanban.uncategorized to the en/zh bundles.

Tests (both red-verified against the pre-fix code): index.bucket.test.ts
covers the pure bucketing (off-column, empty/null, static cards, cover
mapping, no-groupBy); KanbanRenderer.uncolumned.test.tsx renders the real
board through Suspense and asserts the lane + orphan card appear in the
DOM. type-check caught (and this fixes) the hook-destructure at the call
site — the pure test alone would have shipped it.

Closes #2792

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/kanban-uncolumned-fallback.md

@@ -0,0 +1,8 @@
+---
+"@object-ui/plugin-kanban": patch
+"@object-ui/i18n": patch
+---
+
+fix(kanban): surface off-column records in an "Uncategorized" lane instead of dropping them (#2792)
+
+Records whose `groupBy` value matched no declared column were bucketed and then silently discarded — the board rendered empty while the list footer still counted the rows, so it read as data loss (a status the board doesn't render, an edited/removed picklist option, imported legacy data, or an empty value all triggered it). They now land in a trailing "Uncategorized" lane so no record is invisible and the visible card total reconciles with the record count. Dragging a card out of that lane into a real column repairs its status; the drag handler refuses to persist a move *into* the lane (its sentinel id is not a real option). Adds `kanban.uncategorized` to the en/zh bundles.

packages/i18n/src/locales/en.ts

@@ -416,6 +416,7 @@ const en = {
     deleteColumn: 'Delete column',
     noCards: 'No cards',
     cardTitlePlaceholder: 'Enter card title...',
+    uncategorized: 'Uncategorized',
   },
   timeline: {
     bucket: {

packages/i18n/src/locales/zh.ts

@@ -492,6 +492,7 @@ const zh = {
     deleteColumn: '删除列',
     noCards: '暂无卡片',
     cardTitlePlaceholder: '输入卡片标题...',
+    uncategorized: '未分类',
   },
   timeline: {
     bucket: {

packages/plugin-kanban/src/KanbanRenderer.uncolumned.test.tsx

@@ -0,0 +1,63 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Integration DOM test for #2792: render the real KanbanRenderer (flat-data
+ * adapter → lazy KanbanImpl) with an off-column record and assert the
+ * "Uncategorized" lane and its card actually appear on screen — the outcome
+ * the pure bucketing test can't observe (hook wiring + real render).
+ */
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { KanbanRenderer } from './index';
+
+const columns = [
+  { id: 'todo', title: 'To Do' },
+  { id: 'in_progress', title: 'In Progress' },
+];
+
+describe('KanbanRenderer — uncategorized lane (#2792)', () => {
+  it('renders an Uncategorized lane holding the off-column card', async () => {
+    render(
+      <KanbanRenderer
+        schema={{
+          type: 'kanban',
+          groupBy: 'status',
+          columns,
+          data: [
+            { id: '1', title: 'On the board', status: 'todo' },
+            { id: '2', title: 'Orphaned card', status: 'done' }, // no 'done' column
+          ],
+        }}
+      />,
+    );
+
+    // Lazy KanbanImpl resolves through Suspense.
+    expect(await screen.findByText('Orphaned card')).toBeInTheDocument();
+    expect(screen.getByText('On the board')).toBeInTheDocument();
+    // The fallback lane header is present — the orphan is visible, not dropped.
+    expect(screen.getByText('Uncategorized')).toBeInTheDocument();
+  });
+
+  it('renders no Uncategorized lane when every record matches a column', async () => {
+    render(
+      <KanbanRenderer
+        schema={{
+          type: 'kanban',
+          groupBy: 'status',
+          columns,
+          data: [{ id: '1', title: 'Matches', status: 'in_progress' }],
+        }}
+      />,
+    );
+
+    expect(await screen.findByText('Matches')).toBeInTheDocument();
+    expect(screen.queryByText('Uncategorized')).not.toBeInTheDocument();
+  });
+});

packages/plugin-kanban/src/ObjectKanban.tsx

@@ -20,7 +20,7 @@ import { toast } from '@object-ui/components';
 import { RecordDetailDrawer, deriveRecordPageHref } from '@object-ui/plugin-detail';
 import { extractRecords, buildExpandFields, getRecordDisplayName } from '@object-ui/core';
 import { getBadgeColorClasses, getCellRenderer, resolveCellRendererType } from '@object-ui/fields';
-import { KanbanRenderer } from './index';
+import { KanbanRenderer, KANBAN_UNCOLUMNED_ID } from './index';
 import { KanbanSchema } from './types';
 
 /**
@@ -521,6 +521,11 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
       const groupBy = schema.groupBy;
       const objectName = schema.objectName;
       if (!groupBy || fromColumnId === toColumnId) return;
+      // #2792: the "Uncategorized" lane is a display bucket, not a real option.
+      // Dragging a card OUT of it into a real column repairs the record's
+      // status (handled below); dropping one IN would write the sentinel id as
+      // a bogus status, so refuse to persist that direction.
+      if (toColumnId === KANBAN_UNCOLUMNED_ID) return;
 
       // Optimistic local update so the card visibly stays in the new column.
       // Skipped when data is owned by a parent (ListView) — the parent's

packages/plugin-kanban/src/index.bucket.test.ts

@@ -0,0 +1,105 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Unit tests for `bucketCardsIntoColumns` — the single site that distributes
+ * flat `data` + `groupBy` into per-column card arrays. Guards #2792: records
+ * whose group value matches no declared column must NOT vanish; they land in
+ * the trailing "Uncategorized" lane so the visible card total reconciles with
+ * the record count.
+ */
+import { describe, it, expect } from 'vitest';
+import { bucketCardsIntoColumns, KANBAN_UNCOLUMNED_ID } from './index';
+
+const columns = [
+  { id: 'todo', title: 'To Do' },
+  { id: 'in_progress', title: 'In Progress' },
+];
+
+describe('bucketCardsIntoColumns', () => {
+  it('distributes matching records into their columns', () => {
+    const data = [
+      { id: '1', title: 'A', status: 'todo' },
+      { id: '2', title: 'B', status: 'in_progress' },
+    ];
+    const result = bucketCardsIntoColumns(columns, data, 'status', undefined, 'Uncategorized');
+    expect(result).toHaveLength(2);
+    expect(result[0].cards.map((c: any) => c.id)).toEqual(['1']);
+    expect(result[1].cards.map((c: any) => c.id)).toEqual(['2']);
+  });
+
+  it('matches by column title/label as well as id (case-insensitive)', () => {
+    const data = [{ id: '1', title: 'A', status: 'In Progress' }];
+    const result = bucketCardsIntoColumns(columns, data, 'status', undefined, 'Uncategorized');
+    expect(result.find((c) => c.id === 'in_progress')!.cards).toHaveLength(1);
+    expect(result.find((c) => c.id === KANBAN_UNCOLUMNED_ID)).toBeUndefined();
+  });
+
+  it('surfaces off-column records in an Uncategorized lane instead of dropping them (#2792)', () => {
+    const data = [
+      { id: '1', title: 'Matches', status: 'todo' },
+      { id: '2', title: 'Off-column', status: 'done' }, // 'done' is no column
+      { id: '3', title: 'Also off', status: 'archived' },
+    ];
+    const result = bucketCardsIntoColumns(columns, data, 'status', undefined, 'Uncategorized');
+
+    // Every record is visible: the whole board's cards equal the input count.
+    const total = result.reduce((n, col) => n + col.cards.length, 0);
+    expect(total).toBe(data.length);
+
+    const fallback = result.find((c) => c.id === KANBAN_UNCOLUMNED_ID);
+    expect(fallback).toBeDefined();
+    expect(fallback!.title).toBe('Uncategorized');
+    expect(fallback!.cards.map((c: any) => c.id).sort()).toEqual(['2', '3']);
+    expect(result[result.length - 1].id).toBe(KANBAN_UNCOLUMNED_ID); // trailing
+  });
+
+  it('treats empty / null group values as uncategorized rather than losing them', () => {
+    const data = [
+      { id: '1', title: 'No status', status: null },
+      { id: '2', title: 'Empty', status: '' },
+    ];
+    const result = bucketCardsIntoColumns(columns, data, 'status', undefined, 'Uncategorized');
+    const fallback = result.find((c) => c.id === KANBAN_UNCOLUMNED_ID);
+    expect(fallback!.cards.map((c: any) => c.id).sort()).toEqual(['1', '2']);
+  });
+
+  it('adds no Uncategorized lane when every record matches a column', () => {
+    const data = [{ id: '1', title: 'A', status: 'todo' }];
+    const result = bucketCardsIntoColumns(columns, data, 'status', undefined, 'Uncategorized');
+    expect(result.find((c) => c.id === KANBAN_UNCOLUMNED_ID)).toBeUndefined();
+    expect(result).toHaveLength(2);
+  });
+
+  it('preserves static per-column cards alongside distributed data', () => {
+    const withStatic = [
+      { id: 'todo', title: 'To Do', cards: [{ id: 'static-1', title: 'Pinned' }] },
+    ];
+    const data = [{ id: '1', title: 'A', status: 'todo' }];
+    const result = bucketCardsIntoColumns(withStatic, data, 'status', undefined, 'Uncategorized');
+    expect(result[0].cards.map((c: any) => c.id)).toEqual(['static-1', '1']);
+  });
+
+  it('returns columns as-is (cover-mapped) when there is no groupBy', () => {
+    const withCards = [{ id: 'todo', title: 'To Do', cards: [{ id: '1', title: 'A' }] }];
+    const result = bucketCardsIntoColumns(withCards, undefined, undefined, undefined, 'Uncategorized');
+    expect(result).toHaveLength(1);
+    expect(result[0].cards).toHaveLength(1);
+    expect(result.find((c) => c.id === KANBAN_UNCOLUMNED_ID)).toBeUndefined();
+  });
+
+  it('maps the cover image field onto cards (including uncategorized ones)', () => {
+    const data = [
+      { id: '1', title: 'A', status: 'todo', avatar: 'https://img/a.png' },
+      { id: '2', title: 'B', status: 'gone', avatar: { url: 'https://img/b.png' } },
+    ];
+    const result = bucketCardsIntoColumns(columns, data, 'status', 'avatar', 'Uncategorized');
+    expect(result.find((c) => c.id === 'todo')!.cards[0].coverImage).toBe('https://img/a.png');
+    expect(result.find((c) => c.id === KANBAN_UNCOLUMNED_ID)!.cards[0].coverImage).toBe('https://img/b.png');
+  });
+});

packages/plugin-kanban/src/index.tsx

@@ -10,9 +10,99 @@ import React, { Suspense } from 'react';
 import { ComponentRegistry } from '@object-ui/core';
 import { useSchemaContext } from '@object-ui/react';
 import { Skeleton } from '@object-ui/components';
+import { createSafeTranslation } from '@object-ui/i18n';
 import type { KanbanConditionalFormattingRule } from '@object-ui/types';
 import { ObjectKanban } from './ObjectKanban';
 
+/**
+ * Sentinel column id for records whose `groupBy` value matches no declared
+ * column (a status the board doesn't render, an edited/removed picklist
+ * option, imported legacy data, or an empty value). Before #2792 these were
+ * accumulated during bucketing and then silently dropped — the board looked
+ * empty while the list footer still counted the rows. They now surface in a
+ * trailing "Uncategorized" lane so no record is invisible and the visible
+ * card total reconciles with the record count. Exported so the drag handler
+ * can refuse to persist this non-option value as a real status.
+ */
+export const KANBAN_UNCOLUMNED_ID = '__uncolumned__';
+
+const useUncolumnedT = createSafeTranslation(
+  { 'kanban.uncategorized': 'Uncategorized' },
+  'kanban.uncategorized',
+);
+
+/**
+ * The single place flat `data` + `groupBy` is bucketed into per-column card
+ * arrays. Kept pure (title passed in, not translated here) so it can be unit
+ * tested directly — see index.bucket.test.ts. Records whose group value maps
+ * to no declared column land in a trailing `KANBAN_UNCOLUMNED_ID` lane
+ * instead of being dropped (#2792).
+ */
+export function bucketCardsIntoColumns(
+  columns: Array<any>,
+  data: Array<any> | undefined,
+  groupBy: string | undefined,
+  coverImageField: string | undefined,
+  uncolumnedTitle: string,
+): Array<any> {
+  const mapCoverImage = (item: any) => {
+    if (!coverImageField) return item;
+    const imgValue = item[coverImageField];
+    if (!imgValue) return item;
+    const coverImage = typeof imgValue === 'string' ? imgValue : imgValue?.url;
+    return coverImage ? { ...item, coverImage } : item;
+  };
+
+  // No flat data / grouping key: return columns as-is (cover-mapped).
+  if (!data || !groupBy || !Array.isArray(data)) {
+    return columns.map((col: any) => ({
+      ...col,
+      cards: (col.cards || []).map(mapCoverImage),
+    }));
+  }
+
+  // Build label→id mapping so data values (labels like "In Progress") match
+  // column IDs (option values like "in_progress").
+  const labelToColumnId: Record<string, string> = {};
+  columns.forEach((col: any) => {
+    if (col.id) labelToColumnId[String(col.id).toLowerCase()] = col.id;
+    if (col.title) labelToColumnId[String(col.title).toLowerCase()] = col.id;
+  });
+
+  // 1. Group data by key, normalizing via label→id mapping.
+  const groups = data.reduce((acc, item) => {
+    const rawKey = String(item[groupBy] ?? '');
+    const key = labelToColumnId[rawKey.toLowerCase()] ?? rawKey;
+    if (!acc[key]) acc[key] = [];
+    acc[key].push(mapCoverImage(item));
+    return acc;
+  }, {} as Record<string, any[]>);
+
+  // 2. Inject into declared columns.
+  const mapped = columns.map((col: any) => ({
+    ...col,
+    cards: [
+      ...(col.cards || []).map(mapCoverImage), // Preserve static cards
+      ...(groups[col.id] || []),               // Add dynamic cards
+    ],
+  }));
+
+  // 3. Catch records whose group key matched no column (#2792). Without this
+  // they sit in `groups` and are dropped — `groups[col.id]` never reads a key
+  // that isn't a column id — so the board silently loses rows the list footer
+  // still counts. Surface them in a trailing "Uncategorized" lane; dragging
+  // one out to a real column repairs its status (the drag handler refuses to
+  // persist a move INTO here).
+  const knownIds = new Set(columns.map((col: any) => col.id));
+  const uncolumnedCards = Object.keys(groups)
+    .filter((key) => !knownIds.has(key))
+    .flatMap((key) => groups[key]);
+  if (uncolumnedCards.length > 0) {
+    mapped.push({ id: KANBAN_UNCOLUMNED_ID, title: uncolumnedTitle, cards: uncolumnedCards });
+  }
+  return mapped;
+}
+
 // Export types for external use
 export type { KanbanSchema, KanbanCard, KanbanColumn, CardTemplate, ColumnWidthConfig, InlineFieldDefinition } from './types';
 export { ObjectKanban };
@@ -57,54 +147,19 @@ export interface KanbanRendererProps {
  * This wrapper handles lazy loading internally using React.Suspense
  */
 export const KanbanRenderer: React.FC<KanbanRendererProps> = ({ schema }) => {
-  // ⚡️ Adapter: Map flat 'data' + 'groupBy' to nested 'cards' structure
-  const processedColumns = React.useMemo(() => {
-    const { columns = [], data, groupBy, coverImageField } = schema;
-    
-    // Helper to map cover image field onto cards
-    const mapCoverImage = (item: any) => {
-      if (!coverImageField) return item;
-      const imgValue = item[coverImageField];
-      if (!imgValue) return item;
-      const coverImage = typeof imgValue === 'string' ? imgValue : imgValue?.url;
-      return coverImage ? { ...item, coverImage } : item;
-    };
-    
-    // If we have flat data and a grouping key, distribute items into columns
-    if (data && groupBy && Array.isArray(data)) {
-      // Build label→id mapping so data values (labels like "In Progress")
-      // match column IDs (option values like "in_progress")
-      const labelToColumnId: Record<string, string> = {};
-      columns.forEach((col: any) => {
-        if (col.id) labelToColumnId[String(col.id).toLowerCase()] = col.id;
-        if (col.title) labelToColumnId[String(col.title).toLowerCase()] = col.id;
-      });
-
-      // 1. Group data by key, normalizing via label→id mapping
-      const groups = data.reduce((acc, item) => {
-        const rawKey = String(item[groupBy] ?? '');
-        const key = labelToColumnId[rawKey.toLowerCase()] ?? rawKey;
-        if (!acc[key]) acc[key] = [];
-        acc[key].push(mapCoverImage(item));
-        return acc;
-      }, {} as Record<string, any[]>);
-
-      // 2. Inject into columns
-      return columns.map((col: any) => ({
-        ...col,
-        cards: [
-           ...(col.cards || []).map(mapCoverImage),     // Preserve static cards
-           ...(groups[col.id] || []) // Add dynamic cards
-        ]
-      }));
-    }
-    
-    // Default: Return columns as-is, mapping cover images
-    return columns.map((col: any) => ({
-      ...col,
-      cards: (col.cards || []).map(mapCoverImage),
-    }));
-  }, [schema]);
+  const { t } = useUncolumnedT();
+  // ⚡️ Adapter: Map flat 'data' + 'groupBy' to nested 'cards' structure.
+  const processedColumns = React.useMemo(
+    () =>
+      bucketCardsIntoColumns(
+        schema.columns ?? [],
+        schema.data,
+        schema.groupBy,
+        schema.coverImageField,
+        t('kanban.uncategorized'),
+      ),
+    [schema, t],
+  );
 
   return (
     <Suspense fallback={<Skeleton className="w-full h-[600px]" />}>

vitest.config.mts

@@ -91,6 +91,7 @@ const heavyDomTests = [
   'packages/plugin-dashboard/src/__tests__/DashboardRenderer.filters.test.tsx',
   'packages/plugin-dashboard/src/__tests__/DashboardRenderer.legacyRetired.test.tsx',
   'packages/plugin-kanban/src/registration.test.tsx',
+  'packages/plugin-kanban/src/KanbanRenderer.uncolumned.test.tsx',
 ];
 
 export default defineConfig({