@dsh-workbench/module-tools 0.3.2 → 0.3.4

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' };
+}

package/template-diy/src/plugin.test.ts.tpl

@@ -3,35 +3,23 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, 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;
-      },
-    },
+    hooks: { useApiResource: () => ({ phase: 'loading' }) },
     components: {
       Card: () => null,
       CenteredState: () => null,
       EmptyState: () => null,
       StateBlock: () => null,
       IconPanelScreen: () => null,
+      Rows: () => null,
+      Row: () => null,
     },
   },
 }));
 
 import { apply, inject, name, OVERVIEW_ROUTE, readOverview } from './host';
-import { apply as applyClient, formatBytes, inject as injectClient, overviewStateOf } from './client';
+import { apply as applyClient, inject as injectClient } from './client';
 
 interface HostFace {
   readonly unit: string;
@@ -99,42 +87,11 @@ function overview(search: Record<string, string>): Promise<unknown> {
   return hostFace().mount().routes[OVERVIEW_ROUTE](new URLSearchParams(search));
 }
 
-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 scratch = mkdtempSync(join(tmpdir(), 'dsh-wb-diy-'));
 afterAll(() => {
   rmSync(scratch, { recursive: true, force: true });
 });
 
-const cardProps = {
-  world: { current: { workspace: { path: '/tmp/__UNIT__-workspace' } } },
-  refreshToken: 1,
-  onRefresh: () => {},
-  t: (key: string) => key,
-};
-
 describe('__NAME__ 的面', () => {
   it('插件名就是包名', () => {
     expect(name).toBe('__NAME__');
@@ -200,96 +157,3 @@ describe('宿主侧的只读路由', () => {
     expect(readOverview(join(scratch, 'sample'), 5).bytes).toBe(160);
   });
 });
-
-describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
-  it('没有选中工作区时不发请求，画待机那一屏', () => {
-    const face = clientFace();
-    shell.resource = { phase: 'idle' };
-    const withoutProject = { ...cardProps, world: { current: { workspace: null } } };
-
-    expect(textOf(face.card(withoutProject)).join(' ')).toContain('__UNIT__.needProject');
-    expect(shell.readEnabled).toBe(false);
-
-    shell.resource = { phase: 'loading' };
-    expect(textOf(face.card(cardProps)).join(' ')).not.toContain('__UNIT__.needProject');
-    expect(shell.readEnabled).toBe(true);
-  });
-
-  it('四态各画得出来', () => {
-    const face = clientFace();
-
-    shell.resource = { phase: 'loading' };
-    expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.loading');
-
-    shell.resource = { phase: 'error', error: { code: 'internal', message: 'boom' } };
-    expect(textOf(face.card(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(face.card(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(face.card(cardProps)).join(' ')).toContain('__UNIT__.empty');
-  });
-
-  it('刷新中旧数据还在（不退回加载态）', () => {
-    const face = clientFace();
-    shell.resource = {
-      phase: 'loading',
-      value: { ok: true, path: '/real/workbench', files: 1, dirs: 0, bytes: 10, largest: [] },
-    };
-    const text = textOf(face.card(cardProps)).join(' ');
-    expect(text).toContain('/real/workbench');
-    expect(text).not.toContain('__UNIT__.loading');
-  });
-
-});
-
-describe('状态映射', () => {
-  it('phase 与读数一起解出那一屏（待机 / 加载 / 就绪 / 就绪但空 / 出错）', () => {
-    const at = (input: Parameters<typeof overviewStateOf>[0]): string => overviewStateOf(input).kind;
-
-    expect(at({ phase: 'idle', value: undefined, error: undefined })).toBe('idle');
-    expect(at({ phase: 'loading', value: undefined, error: undefined })).toBe('loading');
-    expect(
-      at({
-        phase: 'ready',
-        value: { ok: true, path: '/p', files: 2, dirs: 1, bytes: 10, largest: [] },
-        error: undefined,
-      }),
-    ).toBe('ready');
-    expect(
-      at({
-        phase: 'ready',
-        value: { ok: true, path: '/p', files: 0, dirs: 0, bytes: 0, largest: [] },
-        error: undefined,
-      }),
-    ).toBe('empty');
-    expect(at({ phase: 'error', value: undefined, error: { code: 'internal', message: 'boom' } })).toBe('error');
-  });
-});
-
-describe('格式化', () => {
-  it('字节格式化不炸也不乱', () => {
-    expect(formatBytes(0)).toBe('0 B');
-    expect(formatBytes(2048)).toBe('2.0 KB');
-    expect(formatBytes(3145728)).toBe('3.0 MB');
-  });
-});

package/template-diy/types/styles.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 组件样式（CSS Modules）的类名表。
+ *
+ * 构建时类名会被哈希，`import styles from './X.module.css'` 拿到的是**表**而不是文本
+ * （构建让它进产物里的那份内联样式）；少了这条声明，`styles.xxx` 会被当成 string 的属性，
+ * `pnpm typecheck` 直接红。
+ *
+ * 单独一个文件：`types/globals.d.ts` 里有 import，是模块，里面的 `declare module`
+ * 会变成模块增强而不是环境声明 —— 与外壳 `packages/workbench/types/assets.d.ts` 同一个理由。
+ */
+declare module '*.module.css' {
+  const classes: Record<string, string>;
+  export default classes;
+}