@dsh-workbench/module-tools 0.3.1 → 0.3.3

package/template-diy/src/client.tsx.tpl

@@ -1,16 +1,9 @@
-import { createElement as h } from 'react';
-import { kit } from '@dsh-workbench/core/client';
+import type { ReactElement } from 'react';
+import { OverviewCard } from './components/OverviewCard';
 import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
-const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
-const LIST_LIMIT = 5;
-const KB = 1024;
 
-const { Card, CenteredState, EmptyState, Row, Rows, StateBlock, IconPanelScreen } = kit.components;
-const { useApiResource } = kit.hooks;
-
-type Rendered = ReturnType<typeof h>;
 type Translate = (key: string, params?: Record<string, unknown>) => string;
 
 interface WorkspaceView {
@@ -27,7 +20,7 @@ interface BoardProps {
 interface UnitClientFace {
   readonly unit: string;
   readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
-  readonly card: (props: BoardProps) => Rendered;
+  readonly card: (props: BoardProps) => ReactElement;
 }
 
 interface UnitClientApi {
@@ -39,148 +32,16 @@ interface ClientContext {
   effect(effect: () => void | (() => void), label?: string): () => void;
 }
 
-export interface OverviewFile {
-  readonly name: string;
-  readonly bytes: number;
-  readonly mtime: string;
-}
-
-export interface OverviewPayload {
-  readonly path: string;
-  readonly files: number;
-  readonly dirs: number;
-  readonly bytes: number;
-  readonly largest: readonly OverviewFile[];
-}
-
-type OverviewReady = { readonly ok: true } & OverviewPayload;
-
-interface Failure {
-  readonly code: string;
-  readonly message: string;
-}
-
-export type OverviewState =
-  | { readonly kind: 'idle' }
-  | { readonly kind: 'loading' }
-  | { readonly kind: 'ready'; readonly payload: OverviewPayload }
-  | { readonly kind: 'empty'; readonly payload: OverviewPayload }
-  | { readonly kind: 'error'; readonly detail: string };
-
-export interface OverviewInput {
-  readonly phase: 'idle' | 'loading' | 'ready' | 'error';
-  readonly value: OverviewReady | undefined;
-  readonly error: Failure | undefined;
-}
-
-export function formatBytes(bytes: number): string {
-  if (bytes < KB) return `${String(bytes)} B`;
-  if (bytes < KB * KB) return `${(bytes / KB).toFixed(1)} KB`;
-  if (bytes < KB * KB * KB) return `${(bytes / (KB * KB)).toFixed(1)} MB`;
-  return `${(bytes / (KB * KB * KB)).toFixed(1)} GB`;
-}
-
-function payloadState(payload: OverviewPayload): OverviewState {
-  const blank = payload.files === 0 && payload.dirs === 0;
-  return blank ? { kind: 'empty', payload } : { kind: 'ready', payload };
-}
-
-export function overviewStateOf(input: OverviewInput): OverviewState {
-  if (input.phase === 'idle') return { kind: 'idle' };
-  if (input.phase === 'error') {
-    const error = input.error;
-    return { kind: 'error', detail: error === undefined ? '' : `${error.code}: ${error.message}` };
-  }
-  if (input.value !== undefined && (input.phase === 'ready' || input.phase === 'loading')) {
-    return payloadState(input.value);
-  }
-  return { kind: 'loading' };
-}
-
-function bodyOf(state: OverviewState, t: Translate): Rendered {
-  if (state.kind === 'idle') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.needProject`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'loading') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.loading`),
-      hint: t(`${UNIT_ID}.loadingHint`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'error') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.errorTitle`),
-      detail: state.detail,
-      hint: t(`${UNIT_ID}.errorHint`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'empty') {
-    return h(EmptyState, {
-      text: t(`${UNIT_ID}.empty`),
-      icon: h(IconPanelScreen, { size: 20 }),
-      compact: true,
-    });
-  }
-  const payload = state.payload;
-  return h(
-    StateBlock,
-    {
-      title: payload.path,
-      hint:
-        `${String(payload.files)}${t(`${UNIT_ID}.fileUnit`)} · ` +
-        `${String(payload.dirs)}${t(`${UNIT_ID}.dirUnit`)} · ${formatBytes(payload.bytes)}`,
-      resolving: t(`${UNIT_ID}.largest`),
-    },
-    h(
-      Rows,
-      null,
-      ...payload.largest.map((file) =>
-        h(Row, {
-          key: file.name,
-          label: file.name,
-          value: `${formatBytes(file.bytes)} · ${file.mtime}`,
-        }),
-      ),
-    ),
-  );
-}
-
 const face: UnitClientFace = {
   unit: UNIT_ID,
   messages,
-  card: (props) => {
-    const workspace = props.world.current.workspace;
-    const path = workspace?.path ?? '';
-    const resource = useApiResource<OverviewReady>(
-      OVERVIEW_ROUTE,
-      { path: path === '' ? undefined : path, limit: LIST_LIMIT },
-      props.refreshToken,
-      { enabled: path !== '' },
-    );
-    const state = overviewStateOf({
-      phase: resource.phase,
-      value: resource.value,
-      error: resource.error,
-    });
-    return h(
-      Card,
-      {
-        t: props.t,
-        title: props.t(`${UNIT_ID}.cardTitle`),
-        refreshing: resource.phase === 'loading',
-        onRefresh: props.onRefresh,
-      },
-      bodyOf(state, props.t),
-    );
-  },
+  card: (props) =>
+    OverviewCard({
+      path: props.world.current.workspace?.path ?? '',
+      refreshToken: props.refreshToken,
+      onRefresh: props.onRefresh,
+      t: props.t,
+    }),
 };
 
 export const inject = ['workbenchUnits'];

package/template-diy/src/components/OverviewCard.module.css.tpl

@@ -0,0 +1,5 @@
+.largest {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wb-len-8);
+}

package/template-diy/src/components/OverviewCard.test.ts.tpl

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const shell = vi.hoisted(() => ({
+  resource: { phase: 'loading' } as {
+    readonly phase: string;
+    readonly value?: unknown;
+    readonly error?: { readonly code: string; readonly message: string };
+  },
+  readEnabled: undefined as boolean | undefined,
+}));
+
+vi.mock('@dsh-workbench/core/client', () => ({
+  kit: {
+    hooks: {
+      useApiResource: (_route: string, _query: unknown, _refreshToken: number, options?: { readonly enabled?: boolean }) => {
+        shell.readEnabled = options?.enabled;
+        return shell.resource;
+      },
+    },
+    components: {
+      Card: () => null,
+      CenteredState: () => null,
+      EmptyState: () => null,
+      StateBlock: () => null,
+      IconPanelScreen: () => null,
+      Rows: () => null,
+      Row: () => null,
+    },
+  },
+}));
+
+import { OverviewCard } from './OverviewCard';
+
+function textOf(value: unknown, out: string[] = []): string[] {
+  if (typeof value === 'string') {
+    out.push(value);
+    return out;
+  }
+  if (typeof value === 'number') {
+    out.push(String(value));
+    return out;
+  }
+  if (typeof value === 'boolean' || value === null || value === undefined) return out;
+  if (Array.isArray(value)) {
+    for (const one of value) textOf(one, out);
+    return out;
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const source = 'type' in record && 'props' in record ? (record.props as Record<string, unknown>) : record;
+    for (const one of Object.values(source)) {
+      if (typeof one !== 'function') textOf(one, out);
+    }
+  }
+  return out;
+}
+
+const cardProps = {
+  path: '/tmp/__UNIT__-workspace',
+  refreshToken: 1,
+  onRefresh: () => {},
+  t: (key: string) => key,
+};
+
+describe('OverviewCard：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
+  it('没有选中工作区时不发请求，画待机那一屏', () => {
+    shell.resource = { phase: 'idle' };
+
+    expect(textOf(OverviewCard({ ...cardProps, path: '' })).join(' ')).toContain('__UNIT__.needProject');
+    expect(shell.readEnabled).toBe(false);
+
+    shell.resource = { phase: 'loading' };
+    expect(textOf(OverviewCard(cardProps)).join(' ')).not.toContain('__UNIT__.needProject');
+    expect(shell.readEnabled).toBe(true);
+  });
+
+  it('五态各画得出来', () => {
+    shell.resource = { phase: 'loading' };
+    expect(textOf(OverviewCard(cardProps)).join(' ')).toContain('__UNIT__.loading');
+
+    shell.resource = { phase: 'error', error: { code: 'internal', message: 'boom' } };
+    expect(textOf(OverviewCard(cardProps)).join(' ')).toContain('internal: boom');
+
+    shell.resource = {
+      phase: 'ready',
+      value: {
+        ok: true,
+        path: '/real/workbench',
+        files: 2,
+        dirs: 1,
+        bytes: 2048,
+        largest: [{ name: 'big.bin', bytes: 2048, mtime: '2026-01-02T03:04:05.000Z' }],
+      },
+    };
+    const ready = textOf(OverviewCard(cardProps)).join(' ');
+    expect(ready).toContain('/real/workbench');
+    expect(ready).toContain('big.bin');
+    expect(ready).toContain('2.0 KB');
+    expect(ready).toContain('__UNIT__.fileUnit');
+    expect(ready).toContain('__UNIT__.largest');
+
+    shell.resource = {
+      phase: 'ready',
+      value: { ok: true, path: '/real/empty', files: 0, dirs: 0, bytes: 0, largest: [] },
+    };
+    expect(textOf(OverviewCard(cardProps)).join(' ')).toContain('__UNIT__.empty');
+  });
+
+  it('刷新中旧数据还在（不退回加载态）', () => {
+    shell.resource = {
+      phase: 'loading',
+      value: { ok: true, path: '/real/workbench', files: 1, dirs: 0, bytes: 10, largest: [] },
+    };
+    const text = textOf(OverviewCard(cardProps)).join(' ');
+    expect(text).toContain('/real/workbench');
+    expect(text).not.toContain('__UNIT__.loading');
+  });
+});

package/template-diy/src/components/OverviewCard.tsx.tpl

@@ -0,0 +1,92 @@
+import { createElement as h } from 'react';
+import { kit } from '@dsh-workbench/core/client';
+import { LIST_LIMIT, formatBytes, overviewStateOf, type OverviewReady, type OverviewState } from '../model/overview';
+import styles from './OverviewCard.module.css';
+
+const UNIT_ID = '__UNIT__';
+const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
+
+const { Card, CenteredState, EmptyState, IconPanelScreen, Row, Rows, StateBlock } = kit.components;
+const { useApiResource } = kit.hooks;
+
+type Rendered = ReturnType<typeof h>;
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+export interface OverviewCardProps {
+  readonly path: string;
+  readonly refreshToken: number;
+  readonly onRefresh: () => void;
+  readonly t: Translate;
+}
+
+function bodyOf(state: OverviewState, t: Translate): Rendered {
+  if (state.kind === 'idle') {
+    return h(CenteredState, { icon: null, title: t(`${UNIT_ID}.needProject`), compact: true });
+  }
+  if (state.kind === 'loading') {
+    return h(CenteredState, {
+      icon: null,
+      title: t(`${UNIT_ID}.loading`),
+      hint: t(`${UNIT_ID}.loadingHint`),
+      compact: true,
+    });
+  }
+  if (state.kind === 'error') {
+    return h(CenteredState, {
+      icon: null,
+      title: t(`${UNIT_ID}.errorTitle`),
+      detail: state.detail,
+      hint: t(`${UNIT_ID}.errorHint`),
+      compact: true,
+    });
+  }
+  if (state.kind === 'empty') {
+    return h(EmptyState, { text: t(`${UNIT_ID}.empty`), icon: h(IconPanelScreen, { size: 20 }), compact: true });
+  }
+  const payload = state.payload;
+  return h(
+    StateBlock,
+    {
+      title: payload.path,
+      hint:
+        `${String(payload.files)}${t(`${UNIT_ID}.fileUnit`)} · ` +
+        `${String(payload.dirs)}${t(`${UNIT_ID}.dirUnit`)} · ${formatBytes(payload.bytes)}`,
+      resolving: t(`${UNIT_ID}.largest`),
+    },
+    h(
+      'div',
+      { className: styles.largest },
+      h(
+        Rows,
+        null,
+        ...payload.largest.map((file) =>
+          h(Row, {
+            key: file.name,
+            label: file.name,
+            value: `${formatBytes(file.bytes)} · ${file.mtime}`,
+          }),
+        ),
+      ),
+    ),
+  );
+}
+
+export function OverviewCard(props: OverviewCardProps): Rendered {
+  const resource = useApiResource<OverviewReady>(
+    OVERVIEW_ROUTE,
+    { path: props.path === '' ? undefined : props.path, limit: LIST_LIMIT },
+    props.refreshToken,
+    { enabled: props.path !== '' },
+  );
+  const state = overviewStateOf({ phase: resource.phase, value: resource.value, error: resource.error });
+  return h(
+    Card,
+    {
+      t: props.t,
+      title: props.t(`${UNIT_ID}.cardTitle`),
+      refreshing: resource.phase === 'loading',
+      onRefresh: props.onRefresh,
+    },
+    bodyOf(state, props.t),
+  );
+}

package/template-diy/src/host.ts.tpl

@@ -1,5 +1,6 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import type { OverviewFile, OverviewPayload } from './model/overview';
 
 const UNIT_ID = '__UNIT__';
 const PLUGIN_ID = '__NAME__';
@@ -8,20 +9,6 @@ const MAX_LIMIT = 50;
 
 export const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
 
-export interface OverviewFile {
-  readonly name: string;
-  readonly bytes: number;
-  readonly mtime: string;
-}
-
-export interface OverviewPayload {
-  readonly path: string;
-  readonly files: number;
-  readonly dirs: number;
-  readonly bytes: number;
-  readonly largest: readonly OverviewFile[];
-}
-
 export type RouteHandler = (search: URLSearchParams) => Promise<unknown> | unknown;
 
 export function readOverview(path: string, limit: number): OverviewPayload {

package/template-diy/src/model/overview.test.ts.tpl

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { formatBytes, overviewStateOf } from './overview';
+
+describe('overviewStateOf', () => {
+  it('待机就是待机', () => {
+    expect(overviewStateOf({ phase: 'idle', value: undefined, error: undefined })).toEqual({ kind: 'idle' });
+  });
+
+  it('还在读、又没有旧值，就是加载那一屏', () => {
+    expect(overviewStateOf({ phase: 'loading', value: undefined, error: undefined })).toEqual({ kind: 'loading' });
+  });
+
+  it('读到了、还有东西，就是就绪', () => {
+    const payload = { path: '/p', files: 2, dirs: 1, bytes: 10, largest: [] };
+    const value = { ok: true as const, ...payload };
+    expect(overviewStateOf({ phase: 'ready', value, error: undefined })).toEqual({ kind: 'ready', payload: value });
+  });
+
+  it('读到了但两个数都是零就是空态', () => {
+    const payload = { path: '/tmp', files: 0, dirs: 0, bytes: 0, largest: [] };
+    const value = { ok: true as const, ...payload };
+    expect(overviewStateOf({ phase: 'ready', value, error: undefined })).toEqual({ kind: 'empty', payload: value });
+  });
+
+  it('出错时把 code 与 message 拼成 detail', () => {
+    const state = overviewStateOf({
+      phase: 'error',
+      value: undefined,
+      error: { code: 'network', message: '宿主没有响应' },
+    });
+    expect(state).toEqual({ kind: 'error', detail: 'network: 宿主没有响应' });
+  });
+
+  it('刷新时旧值还在：继续画旧数据，不退回加载态', () => {
+    const payload = { path: '/p', files: 3, dirs: 1, bytes: 100, largest: [] };
+    const value = { ok: true as const, ...payload };
+    expect(overviewStateOf({ phase: 'loading', value, error: undefined })).toEqual({ kind: 'ready', payload: value });
+  });
+});
+
+describe('formatBytes', () => {
+  it('四档单位', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(12)).toBe('12 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(3 * 1024 * 1024)).toBe('3.0 MB');
+    expect(formatBytes(4 * 1024 * 1024 * 1024)).toBe('4.0 GB');
+  });
+});

package/template-diy/src/model/overview.ts.tpl

@@ -0,0 +1,61 @@
+export interface OverviewFile {
+  readonly name: string;
+  readonly bytes: number;
+  readonly mtime: string;
+}
+
+export interface OverviewPayload {
+  readonly path: string;
+  readonly files: number;
+  readonly dirs: number;
+  readonly bytes: number;
+  readonly largest: readonly OverviewFile[];
+}
+
+export type OverviewReady = { readonly ok: true } & OverviewPayload;
+
+export interface Failure {
+  readonly code: string;
+  readonly message: string;
+}
+
+export type OverviewState =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'loading' }
+  | { readonly kind: 'ready'; readonly payload: OverviewPayload }
+  | { readonly kind: 'empty'; readonly payload: OverviewPayload }
+  | { readonly kind: 'error'; readonly detail: string };
+
+export interface OverviewInput {
+  readonly phase: 'idle' | 'loading' | 'ready' | 'error';
+  readonly value: OverviewReady | undefined;
+  readonly error: Failure | undefined;
+}
+
+export const LIST_LIMIT = 5;
+
+const KB = 1024;
+
+export function formatBytes(bytes: number): string {
+  if (bytes < KB) return `${String(bytes)} B`;
+  if (bytes < KB * KB) return `${(bytes / KB).toFixed(1)} KB`;
+  if (bytes < KB * KB * KB) return `${(bytes / (KB * KB)).toFixed(1)} MB`;
+  return `${(bytes / (KB * KB * KB)).toFixed(1)} GB`;
+}
+
+function payloadState(payload: OverviewPayload): OverviewState {
+  const blank = payload.files === 0 && payload.dirs === 0;
+  return blank ? { kind: 'empty', payload } : { kind: 'ready', payload };
+}
+
+export function overviewStateOf(input: OverviewInput): OverviewState {
+  if (input.phase === 'idle') return { kind: 'idle' };
+  if (input.phase === 'error') {
+    const error = input.error;
+    return { kind: 'error', detail: error === undefined ? '' : `${error.code}: ${error.message}` };
+  }
+  if (input.value !== undefined && (input.phase === 'ready' || input.phase === 'loading')) {
+    return payloadState(input.value);
+  }
+  return { kind: 'loading' };
+}