@nocobase/app-template-default 1.0.0-beta.69 → 1.0.0-beta.70

package/client/components/lifecycle-diagram.tsx

@@ -0,0 +1,310 @@
+import {
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { ChevronDownIcon, Settings2Icon } from 'lucide-react';
+import { useTranslation } from '@nocobase/i18n/client';
+import { Button } from '#components/ui/button';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from '#components/ui/popover';
+import type { LifecycleDescription } from '@nocobase/lifecycle';
+import { FlowDiagram, type FlowDiagramProps } from '#components/flow-diagram';
+import type { FlowDiagramNode } from '#components/flow-layout';
+
+import {
+  lifecycleDiagramGraph,
+  lifecycleConfigurationSelection,
+  lifecycleNodeConfigurationSelections,
+  type LifecycleConfigurationSelection,
+  type LifecycleConfigurationTarget,
+  type LifecycleDiagramConfiguration,
+  type LifecycleDiagramOptions,
+} from './lifecycle-diagram-model.js';
+
+export interface LifecycleDiagramProps
+  extends
+    LifecycleDiagramOptions,
+    Omit<
+      FlowDiagramProps,
+      | 'nodes'
+      | 'edges'
+      | 'renderNode'
+      | 'nodeActions'
+      | 'onNodeClick'
+      | 'onEdgeClick'
+    > {
+  readonly description: LifecycleDescription;
+  /** Opens the application-owned, authorized parameter editor for declared bindings. */
+  readonly configuration?: LifecycleDiagramConfiguration;
+  readonly stateActions?: (
+    state: LifecycleDescription['stateInfo'][number],
+  ) => ReactNode;
+  readonly renderState?: (
+    state: LifecycleDescription['stateInfo'][number],
+    node: FlowDiagramNode,
+  ) => ReactNode;
+  readonly onStateClick?: (
+    state: LifecycleDescription['stateInfo'][number],
+  ) => void;
+  readonly onTransitionClick?: (
+    transition: LifecycleDescription['transitions'][number],
+  ) => void;
+}
+
+/** Definitions are source-owned; clicking opens consumer-owned details, never fires a transition. */
+export function LifecycleDiagram({
+  description,
+  currentState,
+  endLabel,
+  history,
+  visitedStates,
+  availableTransitions,
+  stateLabel,
+  transitionLabel,
+  renderState,
+  stateActions,
+  configuration,
+  onStateClick,
+  onTransitionClick,
+  ...props
+}: LifecycleDiagramProps): ReactElement {
+  const sourceGraph = useMemo(
+    () =>
+      lifecycleDiagramGraph(description, {
+        currentState,
+        endLabel,
+        history,
+        visitedStates,
+        availableTransitions,
+        stateLabel,
+        transitionLabel,
+      }),
+    [
+      description,
+      currentState,
+      endLabel,
+      history,
+      visitedStates,
+      availableTransitions,
+      stateLabel,
+      transitionLabel,
+    ],
+  );
+  const graph = configuration
+    ? {
+        nodes: sourceGraph.nodes.map((node) => ({
+          ...node,
+          configurable: Boolean(
+            lifecycleNodeConfigurationSelections(
+              description,
+              node.id,
+              configuration.canConfigure,
+            ).length,
+          ),
+        })),
+        edges: sourceGraph.edges.map((edge) => ({
+          ...edge,
+          configurable:
+            !edge.decorative &&
+            Boolean(
+              lifecycleConfigurationSelection(
+                description,
+                {
+                  kind: 'transition',
+                  name: (JSON.parse(edge.id) as string[])[0],
+                },
+                configuration.canConfigure,
+              ),
+            ),
+        })),
+      }
+    : sourceGraph;
+  return (
+    <FlowDiagram
+      direction='DOWN'
+      initialMinZoom={0.7}
+      autoHeight
+      {...props}
+      {...graph}
+      nodeActions={(node) => {
+        const state = description.stateInfo.find(
+          (state) => state.name === node.id,
+        );
+        if (!state) return undefined;
+        const actions = stateActions?.(state);
+        const selections =
+          configuration &&
+          lifecycleNodeConfigurationSelections(
+            description,
+            state.name,
+            configuration.canConfigure,
+          );
+        if (!selections?.length || !configuration) return actions;
+        return (
+          <div className='nodrag nopan flex items-center gap-1'>
+            {actions}
+            <NodeConfigurationActions
+              configuration={configuration}
+              selections={selections}
+              state={{ kind: 'state', name: state.name }}
+              title={(target) => {
+                if (target.kind === 'state')
+                  return stateLabel?.(state) ?? state.title;
+                const transition = description.transitions.find(
+                  (item) => item.name === target.name,
+                )!;
+                return transitionLabel?.(transition) ?? transition.title;
+              }}
+            />
+          </div>
+        );
+      }}
+      renderNode={(node) => {
+        const state = description.stateInfo.find(
+          (state) => state.name === node.id,
+        );
+        return state && renderState ? renderState(state, node) : node.label;
+      }}
+      onNodeClick={(node) => {
+        const state = description.stateInfo.find(
+          (state) => state.name === node.id,
+        );
+        if (state) onStateClick?.(state);
+      }}
+      onEdgeClick={(edge) => {
+        if (edge.decorative) return;
+        const [name] = JSON.parse(edge.id) as string[];
+        const transition = description.transitions.find(
+          (item) => item.name === name,
+        );
+        if (!transition) return;
+        const selection =
+          configuration &&
+          lifecycleConfigurationSelection(
+            description,
+            { kind: 'transition', name: transition.name },
+            configuration.canConfigure,
+          );
+        if (selection && configuration) configuration.onConfigure(selection);
+        else onTransitionClick?.(transition);
+      }}
+    />
+  );
+}
+
+/** Reuse the authoritative editor; this chooser never invents or saves values. */
+function NodeConfigurationActions({
+  configuration,
+  selections,
+  state,
+  title,
+}: {
+  readonly configuration: LifecycleDiagramConfiguration;
+  readonly selections: readonly LifecycleConfigurationSelection[];
+  readonly state: LifecycleConfigurationTarget;
+  readonly title: (target: LifecycleConfigurationTarget) => string;
+}): ReactElement {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+  const pendingRef = useRef<LifecycleConfigurationSelection | undefined>(
+    undefined,
+  );
+  const first = selections[0];
+  const direct =
+    first.target.kind === 'state' || selections.length === 1
+      ? first
+      : undefined;
+  const choices = direct ? selections.slice(1) : selections;
+  const label = t('flowDiagram.configure', { defaultValue: 'Configure' });
+  const className =
+    'h-6 border border-primary/15 bg-primary/5 px-1.5 text-xs text-primary hover:bg-primary/10';
+  return (
+    <>
+      {direct && (
+        <Button
+          type='button'
+          variant='ghost'
+          size='sm'
+          className={className}
+          onClick={(event) => {
+            event.stopPropagation();
+            configuration.onConfigure(direct);
+          }}
+        >
+          <Settings2Icon aria-hidden />
+          {configuration.label(direct.target)}
+        </Button>
+      )}
+      {choices.length > 0 && (
+        <Popover
+          open={open}
+          onOpenChange={(nextOpen) => {
+            if (nextOpen) pendingRef.current = undefined;
+            setOpen(nextOpen);
+          }}
+          onOpenChangeComplete={(nextOpen) => {
+            // Open the editor only after the chooser has closed and restored focus.
+            // Otherwise its focus restoration can steal focus from the editor.
+            if (!nextOpen && pendingRef.current) {
+              const selection = pendingRef.current;
+              pendingRef.current = undefined;
+              configuration.onConfigure(selection);
+            }
+          }}
+        >
+          <PopoverTrigger
+            render={
+              <Button
+                type='button'
+                variant='ghost'
+                size='sm'
+                className={className}
+                aria-label={`${label}: ${title(state)}`}
+                onClick={(event) => event.stopPropagation()}
+              />
+            }
+          >
+            {!direct && (
+              <>
+                <Settings2Icon aria-hidden />
+                {label}
+              </>
+            )}
+            <ChevronDownIcon aria-hidden />
+          </PopoverTrigger>
+          <PopoverContent
+            align='end'
+            className='w-auto max-w-[min(var(--container-sm),var(--available-width))]'
+            onClick={(event) => event.stopPropagation()}
+          >
+            <PopoverTitle className='sr-only'>
+              {label}: {title(state)}
+            </PopoverTitle>
+            {choices.map((selection) => (
+              <Button
+                key={`${selection.target.kind}:${selection.target.name}`}
+                type='button'
+                variant='ghost'
+                className='h-auto justify-start whitespace-normal text-left'
+                onClick={() => {
+                  pendingRef.current = selection;
+                  setOpen(false);
+                }}
+              >
+                {configuration.label(selection.target)} ·{' '}
+                {title(selection.target)}
+              </Button>
+            ))}
+          </PopoverContent>
+        </Popover>
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,70 @@
+# 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.
+
+| File                   | Exports and responsibility                                                                                                                                                         |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `layout.tsx`           | `WorkflowManagementLayout`: page container, shared header and line-style tabs, hidden in detail mode. `WorkflowDefinitionDetail`: diagram and parameter form cards in two columns. |
+| `definition-list.tsx`  | `WorkflowDefinitionList`: optional category rail, search slot, refresh and execution-activity sort controls, adapted definition rows and empty/status content.                     |
+| `execution-list.tsx`   | `WorkflowExecutionList`: filters slot, refresh, controlled ordering, adapted execution rows, empty/status content and controlled pagination.                                       |
+| `execution-detail.tsx` | `WorkflowExecutionDetail`: ordered history, step selection, diagram rendering callback, effects and optional recorded-parameter content.                                           |
+
+## Routes and ownership
+
+Register one clickable Workflow management entry directly under the application's System management or Settings group. Declare `navigation` only on that parent within the workflow route subtree. Use `definitions` and `executions` child routes without `navigation`, with deeper definition/execution detail routes. Set `tab` from the URL and navigate in `onTabChange`; redirect the parent to its default accessible child. Render the application's `Outlet` inside `WorkflowManagementLayout` and set `detail` while a detail route is active, so details replace the list header and tabs while the same sidebar entry stays active. Retain breadcrumb links with the list's query parameters for returning to the list.
+
+For example, keep the tab routes out of sidebar navigation while retaining direct URLs (the application supplies these page modules and registers the matching settings permission on the server):
+
+```tsx
+import { defineAppRoutes } from '@nocobase/app-client/plugins';
+
+const routes = defineAppRoutes([
+  {
+    name: 'systemManagement',
+    navigation: { title: 'navigation.systemManagement' },
+    children: [
+      {
+        name: 'workflows',
+        path: '/workflows',
+        auth: 'required',
+        authz: {
+          resource: { type: 'settings', id: 'workflow-management' },
+          action: 'read',
+        },
+        navigation: { title: 'navigation.workflows' },
+        componentLoader: () => import('./pages/workflows/index.js'),
+        children: [
+          {
+            name: 'workflowDefinitions',
+            path: 'definitions',
+            componentLoader: () => import('./pages/workflows/definitions.js'),
+          },
+          {
+            name: 'workflowExecutions',
+            path: 'executions',
+            componentLoader: () => import('./pages/workflows/executions.js'),
+          },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+Add definition and execution detail routes beneath the corresponding tab route, also without `navigation`. The parent page maps the URL to `tab`, navigates in `onTabChange`, and supplies its `Outlet` as children. Reuse an existing system group instead of registering another one.
+
+Keep requests, query parameters, IME-aware search, filtering, pagination, category CRUD and permissions in application adapters. Map rows into display values and router links before passing them to the lists. `loaded` distinguishes an empty response from data that has not arrived; `loading` disables refresh, and the caller disables pagination while pending. Supply error/loading/retry content through `status`, and separate empty-catalog and no-results wording through `empty`. The search slot is constrained beside Refresh on wider screens; the category rail stacks above the list on small screens. Omit `categories` when classification is unnecessary. The installable demo provides in-memory category filtering, named color selection and add/edit/delete dialogs as an application adapter; deleting a category preserves its workflows and clears the selected category filter. Its definition header also demonstrates a colored category dropdown with an Uncategorized option; assignment uses the same category state as list filtering. The production adapter keeps the assignment API and read/update permission checks in the application.
+
+`WorkflowDefinitionDetail` accepts a diagram slot and a parameter form slot. Render the installed `@nocobase/lifecycle-diagram` or an existing compatible diagram in a definite-height or content-sized canvas. Keep schema validation, effective timing, complete-group saves, CAS conflicts and read-only permissions in the application's parameter editor. Show a translated empty state when a definition declares no adjustable parameters.
+
+`WorkflowExecutionDetail` sorts transitions by version, timestamp and id without mutating the input. Selecting a step passes only that history prefix and its destination state to `renderDiagram`; no transition or server action occurs. Pass the runtime's transition records directly, retaining extra fields through its generic history type. `effects` displays persisted statuses, attempts and failures; it does not retry them. Pass recorded parameter content through `parameters` and label historical facts separately from current configuration. Remount the detail on record changes or an explicit refresh to reset historical selection, as the example application does.
+
+The application owns authentication, initial administrator grants, navigation and direct-page guards, server read/update authorization and any recovery actions. Configuration permission does not grant business approval permission. Installing this block creates source files, not routes, permissions, runtime services or database collections.
+
+## Standard diagram and contextual configuration
+
+Current application templates already contain these parts and the standard React Flow/ELK components. Reuse the installed `LifecycleDiagram` and preserve its default visuals unless the user explicitly asks to customize them. UI Library entries are shadcn registry source, not npm packages; use `shadcn view/add`, never an npm 404 as a fallback decision.
+
+Connect `LifecycleDiagram.configuration` to the application's existing authorized parameter editor. Native `parameterConfiguration` bindings supply the exact state/transition fields; the component automatically renders bound state controls and sends bound transition selections to `onConfigure`. `canConfigure` is mandatory and controls the affordance only, never server security. The application editor reads current values/revision, preserves other group fields, validates and saves the complete authorized group with CAS, and refreshes the diagram summary from persisted data. Avoid replacing a group with the callback's filtered field subset. Keep historical snapshots read-only.
+
+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.

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

@@ -0,0 +1,148 @@
+import type { ReactElement, ReactNode } from 'react';
+import type {
+  CellContext,
+  ColumnMeta,
+  HeaderContext,
+} from '@tanstack/react-table';
+import { ArrowDown, ArrowUp } from 'lucide-react';
+import { Button } from '#components/ui/button';
+import { Empty, EmptyDescription } from '#components/ui/empty';
+import { DataTable } from '#components/data-table/data-table';
+
+export interface WorkflowDefinitionRow {
+  id: string;
+  name: string;
+  title: ReactNode;
+  activity: ReactNode;
+}
+export interface WorkflowDefinitionListProps {
+  rows: readonly WorkflowDefinitionRow[];
+  categories?: ReactNode;
+  search: ReactNode;
+  status?: ReactNode;
+  loaded: boolean;
+  loading: boolean;
+  empty: ReactNode;
+  labels: {
+    refresh: string;
+    workflow: string;
+    executionCount: string;
+    executionActivity: string;
+  };
+  sort?: { ascending: boolean };
+  onSort: () => void;
+  onRefresh: () => void;
+}
+
+type DefinitionActivityMeta = ColumnMeta<WorkflowDefinitionRow, unknown> &
+  Pick<WorkflowDefinitionListProps, 'labels' | 'sort' | 'onSort'>;
+
+export function WorkflowDefinitionList({
+  rows,
+  categories,
+  search,
+  status,
+  loaded,
+  loading,
+  empty,
+  labels,
+  sort,
+  onSort,
+  onRefresh,
+}: WorkflowDefinitionListProps): ReactElement {
+  const activityMeta: DefinitionActivityMeta = { labels, sort, onSort };
+  return (
+    <section className='flex flex-col items-stretch gap-3 sm:flex-row sm:items-start sm:gap-4'>
+      {categories !== undefined && (
+        <aside className='w-full shrink-0 space-y-4 border-b pb-3 sm:w-48 sm:border-r sm:border-b-0 sm:pr-4 sm:pb-0'>
+          {categories}
+        </aside>
+      )}
+      <div className='flex w-full min-w-0 flex-1 flex-col gap-4'>
+        <div className='flex flex-col items-stretch justify-between gap-2 sm:flex-row sm:items-center'>
+          <div className='min-w-0 flex-1 sm:max-w-xs'>{search}</div>
+          <Button
+            className='shrink-0 self-start sm:self-auto'
+            variant='outline'
+            disabled={loading}
+            onClick={onRefresh}
+          >
+            {labels.refresh}
+          </Button>
+        </div>
+        {status}
+        {loaded && rows.length > 0 && (
+          <div className='bg-card'>
+            <DataTable
+              data={rows}
+              getRowId={(row) => row.id}
+              pagination={false}
+              manualSorting
+              sortingState={
+                sort ? [{ id: 'activity', desc: !sort.ascending }] : []
+              }
+              columns={[
+                {
+                  id: 'workflow',
+                  header: labels.workflow,
+                  enableSorting: false,
+                  cell: DefinitionTitleCell,
+                },
+                {
+                  id: 'activity',
+                  accessorFn: (row) => row.activity,
+                  enableSorting: true,
+                  meta: activityMeta,
+                  header: DefinitionActivityHeader,
+                  cell: DefinitionActivityCell,
+                },
+              ]}
+            />
+          </div>
+        )}
+        {loaded && rows.length === 0 && (
+          <Empty>
+            <EmptyDescription>{empty}</EmptyDescription>
+          </Empty>
+        )}
+      </div>
+    </section>
+  );
+}
+
+// Stable renderer identities preserve mounted links and keyboard focus while
+// the owning application refreshes rows, labels or sorting callbacks.
+function DefinitionTitleCell({
+  row,
+}: CellContext<WorkflowDefinitionRow, unknown>) {
+  return (
+    <>
+      {row.original.title}
+      <p className='text-xs text-muted-foreground'>{row.original.name}</p>
+    </>
+  );
+}
+function DefinitionActivityCell({
+  row,
+}: CellContext<WorkflowDefinitionRow, unknown>) {
+  return <div className='text-right tabular-nums'>{row.original.activity}</div>;
+}
+function DefinitionActivityHeader({
+  column,
+}: HeaderContext<WorkflowDefinitionRow, unknown>) {
+  const { labels, sort, onSort } = column.columnDef
+    .meta as DefinitionActivityMeta;
+  return (
+    <div className='text-right'>
+      <Button
+        variant='ghost'
+        size='sm'
+        title={labels.executionCount}
+        onClick={onSort}
+      >
+        {labels.executionActivity}
+        {sort && (sort.ascending ? <ArrowUp /> : <ArrowDown />)}
+      </Button>
+    </div>
+  );
+}