@nocobase/app-template-default 1.0.0-beta.84 → 1.0.0-beta.85

package/AGENTS.md

@@ -95,7 +95,7 @@ Put a package your **server** code (`server/`, `database/`, `cli/`) imports in `
 
 ### Plugins
 
-**Read a plugin's Skill before building what it already does.** Building a permission system, a notification sender, or a job scheduler by hand when a registered plugin already provides one is the most expensive mistake available here. Register and update plugins with `pnpm nocobase plugin register` and `pnpm nocobase plugin update`; customize a plugin's page through its options, a source extension or `client/route-overrides.ts`, never by redeclaring its route. `.agents/skills/` is generated output; never edit a file there. See [plugins](.agents/skills/nocobase-app-development/references/plugins.md).
+**Read a plugin's Skill before building what it already does.** Building a permission system, a notification sender, or a job scheduler by hand when a registered plugin already provides one is the most expensive mistake available here. Register and update plugins with `pnpm nocobase plugin register` and `pnpm nocobase plugin update`; customize a plugin's page through its options or an explicitly registered route component override, never by redeclaring its route. `.agents/skills/` is generated output; never edit a file there. See [plugins](.agents/skills/nocobase-app-development/references/plugins.md).
 
 ### Running the application
 

package/client/components/data-table/data-table.tsx

@@ -1,4 +1,5 @@
-import { useTranslation } from '@nocobase/i18n/client';
+import type { ListState } from '@nocobase/app-client';
+import { ListFeedback, ListFeedbackActions } from '#components/list-feedback';
 import {
   type ColumnDef,
   type PaginationState,
@@ -41,13 +42,17 @@ export interface DataTableProps<TData, TValue = unknown> {
   readonly onSortingChange?: OnChangeFn<SortingState>;
   readonly showSelectedCount?: boolean;
   readonly loading?: boolean;
+  readonly listState?: ListState;
+  readonly onRetry?: () => void;
+  readonly onClearFilters?: () => void;
+  readonly emptyAction?: ReactNode;
   readonly className?: string;
   /**
    * Rendered above the table and handed the table instance, so filters and
    * `DataTableViewOptions` can read and drive its state.
    */
   readonly toolbar?: (table: TableInstance<TData>) => ReactNode;
-  /** Shown in place of the body when no row survives filtering. */
+  /** Shown in the table body when no row survives filtering. */
   readonly emptyMessage?: ReactNode;
   /** Set to `false` to render every row and hide the pagination footer. */
   readonly pagination?: boolean;
@@ -91,8 +96,11 @@ export function DataTable<TData, TValue = unknown>({
   onSortingChange,
   showSelectedCount = true,
   loading = false,
+  listState,
+  onRetry,
+  onClearFilters,
+  emptyAction,
 }: DataTableProps<TData, TValue>): ReactElement {
-  const { t } = useTranslation();
   const tableData = useMemo(() => [...data], [data]);
   const [sorting, setSorting] = useState<SortingState>([]);
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
@@ -134,12 +142,56 @@ export function DataTable<TData, TValue = unknown>({
   });
 
   const rows = table.getRowModel().rows;
+  const requestedState =
+    (listState === 'ready' && rows.length === 0
+      ? columnFilters.length > 0
+        ? 'no-results'
+        : 'empty'
+      : listState) ??
+    (loading && data.length === 0
+      ? 'loading'
+      : rows.length
+        ? 'ready'
+        : columnFilters.length
+          ? 'no-results'
+          : 'empty');
+  const state =
+    (requestedState === 'empty' || requestedState === 'no-results') &&
+    ((manualPagination && columnFilters.length === 0 && (rowCount ?? 0) > 0) ||
+      (!manualPagination && table.getPrePaginationRowModel().rows.length > 0))
+      ? 'loading'
+      : requestedState;
+  const clearFilters = () => {
+    table.resetColumnFilters();
+    table.setPageIndex(0);
+    onClearFilters?.();
+  };
+  const hasStateActions =
+    (state === 'no-results' &&
+      (columnFilters.length > 0 || onClearFilters !== undefined)) ||
+    ((state === 'failed' || state === 'refresh-failed') &&
+      onRetry !== undefined) ||
+    state === 'unauthenticated';
+  const showRows =
+    rows.length > 0 && (state === 'ready' || state === 'refresh-failed');
+  const showFeedback = !showRows || state === 'refresh-failed';
+  const feedbackColumnCount = Math.max(1, table.getVisibleLeafColumns().length);
 
   return (
     <div className={cn('flex flex-col gap-4', className)}>
-      {toolbar ? (
+      {toolbar || hasStateActions ? (
         <div className='flex flex-wrap items-center gap-2'>
-          {toolbar(table)}
+          {toolbar?.(table)}
+          <ListFeedbackActions
+            state={state}
+            onClear={
+              columnFilters.length > 0 || onClearFilters
+                ? clearFilters
+                : undefined
+            }
+            onRetry={onRetry}
+            busy={loading}
+          />
         </div>
       ) : null}
       <div className='overflow-hidden rounded-lg border'>
@@ -173,39 +225,41 @@ export function DataTable<TData, TValue = unknown>({
             ))}
           </TableHeader>
           <TableBody>
-            {rows.length > 0 ? (
-              rows.map((row) => (
-                <TableRow
-                  key={row.id}
-                  data-state={row.getIsSelected() ? 'selected' : undefined}
-                  className={onRowClick ? 'cursor-pointer' : undefined}
-                  onClick={onRowClick ? () => onRowClick(row) : undefined}
-                >
-                  {row.getVisibleCells().map((cell) => (
-                    <TableCell key={cell.id}>
-                      {flexRender(
-                        cell.column.columnDef.cell,
-                        cell.getContext(),
-                      )}
-                    </TableCell>
-                  ))}
-                </TableRow>
-              ))
-            ) : (
+            {showFeedback ? (
               <TableRow>
-                <TableCell
-                  colSpan={columns.length}
-                  className='h-24 text-center text-muted-foreground'
-                >
-                  {emptyMessage ??
-                    t('dataTable.noResults', { defaultValue: 'No results.' })}
+                <TableCell colSpan={feedbackColumnCount} className='p-0'>
+                  <ListFeedback
+                    state={state}
+                    empty={emptyMessage}
+                    emptyAction={emptyAction}
+                  />
                 </TableCell>
               </TableRow>
-            )}
+            ) : null}
+            {showRows
+              ? rows.map((row) => (
+                  <TableRow
+                    key={row.id}
+                    data-state={row.getIsSelected() ? 'selected' : undefined}
+                    className={onRowClick ? 'cursor-pointer' : undefined}
+                    onClick={onRowClick ? () => onRowClick(row) : undefined}
+                  >
+                    {row.getVisibleCells().map((cell) => (
+                      <TableCell key={cell.id}>
+                        {flexRender(
+                          cell.column.columnDef.cell,
+                          cell.getContext(),
+                        )}
+                      </TableCell>
+                    ))}
+                  </TableRow>
+                ))
+              : null}
           </TableBody>
         </Table>
       </div>
-      {pagination ? (
+      {pagination &&
+      (state === 'ready' || (state === 'refresh-failed' && rows.length > 0)) ? (
         <DataTablePagination
           table={table}
           pageSizeOptions={pageSizeOptions}

package/client/components/list-feedback.tsx

@@ -0,0 +1,174 @@
+import type { ListState } from '@nocobase/app-client';
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  CircleAlert,
+  Inbox,
+  LoaderCircle,
+  LockKeyhole,
+  LogIn,
+  RefreshCw,
+  SearchX,
+  X,
+} from 'lucide-react';
+import { Fragment, type ReactElement, type ReactNode } from 'react';
+import { Link } from 'react-router';
+import { Button } from '#components/ui/button';
+import { Alert } from '#components/ui/alert';
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyMedia,
+  EmptyTitle,
+} from '#components/ui/empty';
+
+const feedback = {
+  loading: ['listFeedback.loading', 'Loading', LoaderCircle],
+  empty: ['listFeedback.empty', 'No data yet', Inbox],
+  'no-results': ['listFeedback.noResults', 'No results', SearchX],
+  forbidden: ['listFeedback.forbidden', 'Access denied', LockKeyhole],
+  unauthenticated: ['listFeedback.unauthenticated', 'Session expired', LogIn],
+  failed: ['listFeedback.failed', 'Unable to load list', CircleAlert],
+} as const;
+
+export interface ListFeedbackProps {
+  readonly state: ListState;
+  readonly children?: ReactNode;
+  /** Business empty content applies only after a successful unfiltered read. */
+  readonly empty?: ReactNode;
+  /** Optional business-specific action; the standard create action belongs in the page header. */
+  readonly emptyAction?: ReactNode;
+}
+
+export interface ListFeedbackActionsProps {
+  readonly state: ListState;
+  readonly onClear?: () => void;
+  readonly onRetry?: () => void;
+  readonly busy?: boolean;
+}
+
+/** Render state-appropriate recovery controls inside the host's existing toolbar. */
+export function ListFeedbackActions({
+  state,
+  onClear,
+  onRetry,
+  busy = false,
+}: ListFeedbackActionsProps): ReactElement | null {
+  const { t } = useTranslation();
+
+  if (state === 'no-results' && onClear) {
+    return (
+      <Button variant='outline' onClick={onClear}>
+        <X aria-hidden='true' />
+        {t('listFeedback.clear', { defaultValue: 'Clear filters' })}
+      </Button>
+    );
+  }
+
+  if ((state === 'failed' || state === 'refresh-failed') && onRetry) {
+    return (
+      <Button variant='outline' disabled={busy} onClick={onRetry}>
+        {busy ? (
+          <LoaderCircle
+            aria-hidden='true'
+            className='motion-safe:animate-spin'
+          />
+        ) : (
+          <RefreshCw aria-hidden='true' />
+        )}
+        {busy
+          ? t('listFeedback.retrying', { defaultValue: 'Retrying…' })
+          : t('listFeedback.retry', { defaultValue: 'Retry' })}
+      </Button>
+    );
+  }
+
+  if (state === 'unauthenticated') {
+    return (
+      <Button
+        variant='outline'
+        nativeButton={false}
+        render={<Link to='/login' />}
+      >
+        <LogIn aria-hidden='true' />
+        {t('listFeedback.signIn', { defaultValue: 'Sign in' })}
+      </Button>
+    );
+  }
+
+  return null;
+}
+
+/** Shared by tables and card lists. Authorization is decided by the host. */
+export function ListFeedback({
+  state,
+  children,
+  empty,
+  emptyAction,
+}: ListFeedbackProps): ReactElement {
+  const { t } = useTranslation();
+
+  if (state === 'ready') {
+    return <Fragment key='list-feedback-content'>{children}</Fragment>;
+  }
+
+  if (state === 'refresh-failed') {
+    return (
+      <>
+        <Alert
+          className='flex min-w-0 items-center gap-2 border-border px-3 py-2 text-sm'
+          role='alert'
+        >
+          <CircleAlert
+            aria-hidden='true'
+            className='size-4 shrink-0 text-destructive'
+          />
+          <p className='min-w-0 flex-1 wrap-anywhere'>
+            {t('listFeedback.refreshFailed', {
+              defaultValue: 'Refresh failed; showing previous data',
+            })}
+          </p>
+        </Alert>
+        <Fragment key='list-feedback-content'>{children}</Fragment>
+      </>
+    );
+  }
+
+  const [key, fallback, Icon] = feedback[state];
+  const isError =
+    state === 'failed' || state === 'forbidden' || state === 'unauthenticated';
+  const showCustomEmpty =
+    state === 'empty' && (empty !== undefined || emptyAction !== undefined);
+
+  return (
+    <>
+      <Empty
+        role={isError ? 'alert' : 'status'}
+        className='min-h-24 flex-row flex-none gap-2 rounded-none border-0 px-4 py-6 text-pretty text-card-foreground'
+        aria-busy={state === 'loading'}
+      >
+        <EmptyMedia className='mb-0 size-4 text-muted-foreground'>
+          <Icon
+            aria-hidden='true'
+            className={
+              state === 'loading' ? 'size-4 motion-safe:animate-spin' : 'size-4'
+            }
+          />
+        </EmptyMedia>
+        <EmptyTitle className='text-sm font-medium text-muted-foreground'>
+          {t(key, { defaultValue: fallback })}
+        </EmptyTitle>
+      </Empty>
+      {showCustomEmpty ? (
+        <EmptyContent className='max-w-full px-4 pb-4 text-center'>
+          {empty !== undefined ? (
+            <EmptyDescription className='max-w-md wrap-anywhere'>
+              {empty}
+            </EmptyDescription>
+          ) : null}
+          {emptyAction}
+        </EmptyContent>
+      ) : null}
+    </>
+  );
+}

package/client/components/permission-editor.tsx

@@ -538,8 +538,6 @@ function PermissionRow({
 }): ReactElement {
   const hasControls =
     row.enabled && Boolean(row.levels?.length || row.scopes?.length);
-  const singleRange =
-    hasControls && (row.scopes?.length ?? 0) + (row.levels ? 1 : 0) === 1;
   const describedBy =
     [
       row.hint ? `${controlId}-hint` : undefined,
@@ -554,19 +552,14 @@ function PermissionRow({
       className={cn(
         'group/field grid min-w-0 gap-2 rounded-md px-2 py-2 hover:bg-hover',
         presentation === 'inline' && 'inline-flex items-start',
-        singleRange && 'sm:flex sm:flex-wrap sm:items-start sm:gap-x-5',
       )}
     >
-      <div
-        className={cn(
-          'flex min-w-0 items-start gap-3',
-          singleRange && 'sm:max-w-lg',
-        )}
-      >
+      <div className='flex min-w-0 items-start gap-3'>
         <Checkbox
           id={controlId}
           className='mt-0.5 shrink-0'
           checked={row.enabled}
+          aria-label={row.label}
           disabled={readOnly || row.toggleable === false}
           onCheckedChange={(on: boolean) => onEnabledChange(row.id, on)}
           aria-describedby={describedBy}
@@ -606,29 +599,35 @@ function PermissionRow({
       {hasControls && (
         <div
           data-slot='permission-scopes'
-          className={cn(
-            'grid min-w-0 gap-x-5 gap-y-2 pl-7 sm:grid-cols-2',
-            singleRange && 'w-full sm:w-80 sm:shrink-0 sm:grid-cols-1 sm:pl-0',
-          )}
+          className='grid min-w-0 max-w-[60rem] gap-x-6 gap-y-2 pl-7 @min-[48rem]/permissions:grid-cols-2'
         >
-          {row.levels && (
-            <LevelControl
-              label={labels.levelFor(row.label)}
-              levels={row.levels}
-              value={row.level ?? ''}
-              disabled={readOnly}
-              onChange={(level) => onLevelChange(row.id, level)}
-            />
+          {row.levels && row.levels.length > 0 && (
+            <div className='grid min-w-0 items-start gap-x-3 gap-y-1 @min-[26rem]/permissions:grid-cols-[8.5rem_minmax(0,1fr)]'>
+              <span aria-hidden />
+              <div className='grid min-w-0 grid-cols-[minmax(0,1fr)_1.5rem] items-start gap-x-1'>
+                <LevelControl
+                  label={labels.levelFor(row.label)}
+                  levels={row.levels}
+                  value={row.level ?? ''}
+                  disabled={readOnly}
+                  onChange={(level) => onLevelChange(row.id, level)}
+                />
+              </div>
+            </div>
           )}
           {row.scopes?.map((scope) => (
             <div
               key={scope.id}
-              className='grid min-w-0 grid-cols-[minmax(4rem,auto)_minmax(0,1fr)] items-center gap-2'
+              data-slot='permission-scope'
+              className='grid min-w-0 items-start gap-x-3 gap-y-1 @min-[26rem]/permissions:grid-cols-[8.5rem_minmax(0,1fr)]'
             >
-              <span className='max-w-36 text-xs break-words text-muted-foreground'>
+              <span
+                title={scope.label}
+                className='line-clamp-2 min-w-0 pt-1 text-xs break-words text-muted-foreground'
+              >
                 {scope.label}
               </span>
-              <div className='flex min-w-0 items-center gap-1'>
+              <div className='grid min-w-0 grid-cols-[minmax(0,1fr)_1.5rem] items-start gap-x-1 gap-y-1'>
                 <LevelControl
                   label={labels.levelFor(`${row.label} · ${scope.label}`)}
                   levels={scope.levels}
@@ -636,13 +635,21 @@ function PermissionRow({
                   disabled={readOnly}
                   onChange={(level) => onLevelChange(scope.id, level)}
                 />
-                {scope.configuration}
-                {scope.hint && (
-                  <ScopeHint
-                    label={labels.scopeHintFor(`${row.label} · ${scope.label}`)}
-                  >
-                    {scope.hint}
-                  </ScopeHint>
+                <div className='col-start-2 row-start-1'>
+                  {scope.hint && (
+                    <ScopeHint
+                      label={labels.scopeHintFor(
+                        `${row.label} · ${scope.label}`,
+                      )}
+                    >
+                      {scope.hint}
+                    </ScopeHint>
+                  )}
+                </div>
+                {scope.configuration && (
+                  <div className='col-start-1 min-w-0'>
+                    {scope.configuration}
+                  </div>
                 )}
               </div>
             </div>
@@ -652,7 +659,7 @@ function PermissionRow({
           ].map((hint) => (
             <p
               key={hint}
-              className='text-xs leading-5 text-muted-foreground sm:col-span-full'
+              className='col-span-full text-xs leading-5 text-muted-foreground'
             >
               {hint}
             </p>
@@ -797,7 +804,7 @@ export function PermissionEditor({
         setQuery('');
         setStatus('all');
       }}
-      className='min-w-0 gap-3'
+      className='@container/permissions min-w-0 gap-3'
     >
       {available.length > 0 && (
         <div className='overflow-x-auto pb-1'>

package/client/extensions/nocobase-workflow-management/README.md

@@ -1,6 +1,6 @@
 # Workflow management
 
-Install with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. This block provides the workflow example's administration layout and interactions as presentational parts in `client/extensions/nocobase-workflow-management/`. Read `@nocobase/workflow-management-demo` for a standalone composition. Every label and formatted value is supplied by the caller; the block imports no example plugin, API client, authorization provider or router.
+Install with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. This block provides the workflow example's administration layout and interactions as presentational parts in `client/extensions/nocobase-workflow-management/`. Read `@nocobase/workflow-management-demo` for a standalone composition. Business labels and formatted values are supplied by the caller; the block imports no example plugin, API client, authorization provider or router.
 
 | File                   | Exports and responsibility                                                                                                                                                         |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -70,3 +70,5 @@ Connect `LifecycleDiagram.configuration` to the application's existing authorize
 Omit `WorkflowDefinitionDetail.parameters` when the editor opens contextually so the diagram spans the available width; keep the slot when the same editor is visible beside the diagram. No editor, API, sample business registration or menu is installed by this block. Definition and execution lists use the same TanStack DataTable as the templates, with no second local pagination over a server page.
 
 Ordering is optional: omit `onSort` when activity ordering is not supported so the header stays plain text. Omit a row's optional `name` when its linked `title` already supplies the complete display name. Hosts own filtering, pagination and their URL state; keep that state when opening and returning from a definition or execution.
+
+List hosts pass `listState={resolveListState(request, rows.length, hasEffectiveFilters)}` and `onClearFilters`, using the current request error and data. The DataTable dependency supplies shared loading, denial, session and failure copy; merge the `listFeedback` English/Chinese keys from the components README into application translations. `onRefresh` is reused for retry and must preserve the current query. Keep `loaded`, `loading`, custom `empty` content and existing permission checks when reconciling installed copies. A successful empty filter is `no-results`; an empty unfiltered read is `empty`. Hosts that retain the legacy status slot without a listState still own their error rendering.

package/client/extensions/nocobase-workflow-management/definition-list.tsx

@@ -1,3 +1,4 @@
+import type { ListState } from '@nocobase/app-client';
 import type { ReactElement, ReactNode } from 'react';
 import type {
   CellContext,
@@ -16,13 +17,15 @@ export interface WorkflowDefinitionRow {
   activity: ReactNode;
 }
 export interface WorkflowDefinitionListProps {
+  listState?: ListState;
+  onClearFilters?: () => void;
   rows: readonly WorkflowDefinitionRow[];
   categories?: ReactNode;
   search: ReactNode;
   status?: ReactNode;
   loaded: boolean;
   loading: boolean;
-  empty: ReactNode;
+  empty?: ReactNode;
   labels: {
     refresh: string;
     workflow: string;
@@ -39,6 +42,8 @@ type DefinitionActivityMeta = ColumnMeta<WorkflowDefinitionRow, unknown> &
 
 export function WorkflowDefinitionList({
   rows,
+  listState,
+  onClearFilters,
   categories,
   search,
   status,
@@ -71,10 +76,22 @@ export function WorkflowDefinitionList({
           </Button>
         </div>
         {status}
-        {loaded && rows.length > 0 && (
+        {(listState !== undefined || loaded || loading) && (
           <div className='bg-card'>
             <DataTable
               data={rows}
+              loading={loading}
+              listState={
+                listState ??
+                (!loaded ? 'loading' : rows.length ? 'ready' : 'empty')
+              }
+              onRetry={onRefresh}
+              onClearFilters={onClearFilters}
+              emptyMessage={
+                <Empty>
+                  <EmptyDescription>{empty}</EmptyDescription>
+                </Empty>
+              }
               getRowId={(row) => row.id}
               pagination={false}
               manualSorting
@@ -100,11 +117,6 @@ export function WorkflowDefinitionList({
             />
           </div>
         )}
-        {loaded && rows.length === 0 && (
-          <Empty>
-            <EmptyDescription>{empty}</EmptyDescription>
-          </Empty>
-        )}
       </div>
     </section>
   );