dsh-3d-viewer 0.1.0 → 0.2.0

package/src/ui/ModelViewer.js

@@ -1,278 +0,0 @@
-import * as React from 'react';
-import { isGlbAddress, normalizeFormat } from '../formats.js';
-import { loadModelBytes } from '../loaders/model-loader.js';
-import { collectModelStats, disposeObject } from '../model.js';
-import { createSceneView } from '../scene/createSceneView.js';
-import { ViewerError } from '../scene/viewer-error.js';
-import { en } from './dictionaries.js';
-import { DEFAULT_SETTINGS } from './options.js';
-import { ViewerSurface } from './ViewerSurface.js';
-
-const h = React.createElement;
-
-function fallbackTranslate(key, params) {
-  const template = en[key] ?? key;
-  if (params === undefined) return template;
-  return template.replace(/\{(\w+)\}/g, (_match, name) => String(params[name] ?? ''));
-}
-
-function loadingState() {
-  return { status: 'loading', failure: null, stats: null, clips: [] };
-}
-
-function errorState(error) {
-  return {
-    status: 'error',
-    failure: {
-      code: error instanceof ViewerError ? error.code : 'scene',
-      message: error instanceof Error ? error.message : String(error),
-      detail: error instanceof Error ? (error.stack ?? error.message) : String(error),
-    },
-    stats: null,
-    clips: [],
-  };
-}
-
-function byteLengthOf(data) {
-  if (typeof data === 'string') {
-    try {
-      return new TextEncoder().encode(data).byteLength;
-    } catch {
-      return data.length;
-    }
-  }
-  if (data instanceof ArrayBuffer) return data.byteLength;
-  if (ArrayBuffer.isView(data)) return data.byteLength;
-  return null;
-}
-
-/**
- * Push one settings snapshot into a live view.
- *
- * @param {ReturnType<typeof createSceneView>} view Live scene view.
- * @param {{ grid: boolean, autoRotate: boolean, wireframe: boolean, material: string, environment: string }} settings Desired settings.
- */
-function applyViewSettings(view, settings) {
-  view.setGrid(settings.grid);
-  view.setMaterialPreset(settings.material);
-  view.setEnvironment(settings.environment);
-  view.setWireframe(settings.wireframe);
-  view.setAutoRotate(settings.autoRotate);
-}
-
-/**
- * Right-Sidebar document body for one 3D model.
- *
- * Owns loading, lifecycle, and settings; rendering is delegated to the pure
- * `ViewerSurface`, which can be server-rendered without a WebGL context.
- *
- * @param {{
- *   format: 'fbx' | 'gltf' | 'obj' | 'stl',
- *   content?: { kind?: string, data?: Uint8Array | ArrayBuffer | string },
- *   resourceAddress?: string,
- *   readWorkspaceFile?: Function,
- *   t?: (key: string, params?: Record<string, unknown>) => string,
- *   fallbackT?: (key: string, params?: Record<string, unknown>) => string,
- * }} props Model format, document content, workspace reader, and translator.
- */
-function ModelViewer(props) {
-  const format = normalizeFormat(props.format);
-  const glb = format === 'gltf' && isGlbAddress(props.resourceAddress);
-  const content = props.content;
-  const t = props.t ?? props.fallbackT ?? fallbackTranslate;
-  const data = content !== undefined && content !== null
-    && (content.kind === 'bytes' || content.kind === 'text')
-    ? content.data
-    : null;
-
-  const [runtime, setRuntime] = React.useState(loadingState);
-  const [settings, setSettings] = React.useState(DEFAULT_SETTINGS);
-  const [attempt, setAttempt] = React.useState(0);
-  const hostRef = React.useRef(null);
-  const viewRef = React.useRef(null);
-  const tRef = React.useRef(t);
-  const settingsRef = React.useRef(settings);
-  const readerRef = React.useRef(typeof props.readWorkspaceFile === 'function' ? props.readWorkspaceFile : null);
-  const addressRef = React.useRef(typeof props.resourceAddress === 'string' ? props.resourceAddress : null);
-
-  tRef.current = t;
-  settingsRef.current = settings;
-  readerRef.current = typeof props.readWorkspaceFile === 'function' ? props.readWorkspaceFile : null;
-  addressRef.current = typeof props.resourceAddress === 'string' ? props.resourceAddress : null;
-
-  React.useEffect(() => {
-    const host = hostRef.current;
-    if (host === null) return undefined;
-
-    let disposed = false;
-    let model = null;
-    let view = null;
-    let assets = null;
-    const controller = new AbortController();
-
-    // Release whatever the load produced, whichever stage it reached. A view
-    // owns the model once it adopts the scene, so only one of them is disposed.
-    const release = () => {
-      if (view !== null) {
-        view.dispose();
-        view = null;
-        viewRef.current = null;
-      } else if (model !== null) {
-        disposeObject(model);
-        model = null;
-      }
-      assets?.dispose();
-      assets = null;
-    };
-
-    setRuntime((previous) => previous.status === 'loading' ? previous : loadingState());
-
-    const run = async () => {
-      if (disposed) return;
-
-      try {
-        if (data === null) {
-          throw new ViewerError('parse', 'The preview supplied no binary model content.');
-        }
-
-        let loaded;
-        try {
-          loaded = await loadModelBytes(data, format, {
-            resourceAddress: addressRef.current ?? undefined,
-            readWorkspaceFile: readerRef.current ?? undefined,
-            signal: controller.signal,
-          });
-        } catch (error) {
-          if (disposed || controller.signal.aborted) return;
-          throw new ViewerError(
-            'parse',
-            error instanceof Error ? error.message : String(error),
-            error,
-          );
-        }
-
-        if (disposed || controller.signal.aborted) {
-          loaded.assets?.dispose();
-          disposeObject(loaded.object);
-          return;
-        }
-
-        model = loaded.object;
-        assets = loaded.assets ?? null;
-
-        const nextStats = collectModelStats(model);
-        if (nextStats.renderables === 0) {
-          release();
-          if (!disposed) setRuntime({ status: 'empty', failure: null, stats: null, clips: [] });
-          return;
-        }
-
-        const current = settingsRef.current;
-        assets?.onTextureLoad(() => {
-          if (!disposed) view?.invalidate();
-        });
-        view = createSceneView(host, model, nextStats, {
-          ariaLabel: tRef.current('canvasLabel'),
-          environment: current.environment,
-        });
-        // The view owns the model from here on; disposing the view disposes it.
-        model = null;
-        applyViewSettings(view, current);
-
-        if (disposed) {
-          release();
-          return;
-        }
-
-        viewRef.current = view;
-        setRuntime({
-          status: 'ready',
-          failure: null,
-          stats: nextStats,
-          clips: view.animations,
-          fileSize: byteLengthOf(data),
-        });
-      } catch (error) {
-        if (disposed || controller.signal.aborted) return;
-
-        release();
-        // createSceneView appends its canvas before it can fail; never leave a
-        // half-initialized stage behind. A superseded effect must not clear the
-        // replacement viewer's canvas (its cleanup already ran).
-        host.replaceChildren();
-        viewRef.current = null;
-        setRuntime(errorState(error));
-      }
-    };
-
-    const timer = setTimeout(() => {
-      void run();
-    }, 16);
-
-    return () => {
-      disposed = true;
-      controller.abort();
-      clearTimeout(timer);
-      release();
-    };
-  }, [data, attempt, format]);
-
-  React.useEffect(() => {
-    const view = viewRef.current;
-    if (view !== null) applyViewSettings(view, settings);
-  }, [settings]);
-
-  const updateSettings = (patch) => {
-    setSettings((previous) => ({ ...previous, ...patch }));
-  };
-
-  const retry = () => {
-    setRuntime(loadingState());
-    setAttempt((value) => value + 1);
-  };
-
-  return h(ViewerSurface, {
-    format,
-    glb,
-    t,
-    view: viewRef.current,
-    settings,
-    runtime,
-    hostRef,
-    onSettingsChange: updateSettings,
-    onRetry: retry,
-  });
-}
-
-/**
- * Build a viewer component bound to one document format.
- *
- * @param {'fbx' | 'gltf' | 'obj' | 'stl'} format Registered format name.
- * @returns {(props: object) => unknown} Slot body component.
- */
-function createViewer(format) {
-  function Viewer(props) {
-    return h(ModelViewer, { ...props, format });
-  }
-  return Viewer;
-}
-
-/** FBX document body. */
-export const FbxViewer = createViewer('fbx');
-
-/** OBJ document body. */
-export const ObjViewer = createViewer('obj');
-
-/** glTF / GLB document body. */
-export const GltfViewer = createViewer('gltf');
-
-/** STL document body. */
-export const StlViewer = createViewer('stl');
-
-/** Slot bodies keyed by the format registry id. */
-export const VIEWER_COMPONENTS = Object.freeze({
-  fbx: FbxViewer,
-  obj: ObjViewer,
-  gltf: GltfViewer,
-  stl: StlViewer,
-});

package/src/ui/ViewerSurface.js

@@ -1,87 +0,0 @@
-import * as React from 'react';
-import { AnimationBar } from './AnimationBar.js';
-import {
-  Badge,
-  Hint,
-  StatsPanel,
-  StatusOverlay,
-  Toolbar,
-  ViewControls,
-} from './chrome.js';
-import { CSS } from './styles.js';
-
-const h = React.createElement;
-
-/**
- * Pure presentation of one 3D document body.
- *
- * All load, WebGL, and animation lifecycle lives in `ModelViewer`. Keeping the
- * markup free of hooks makes the ready/loading/empty/error surfaces renderable
- * without a canvas or a WebGL context.
- *
- * @param {{
- *   format: 'fbx' | 'gltf' | 'obj' | 'stl',
- *   glb: boolean,
- *   t: (key: string, params?: Record<string, unknown>) => string,
- *   view: object | null,
- *   settings: { grid: boolean, autoRotate: boolean, wireframe: boolean, material: string, environment: string },
- *   runtime: { status: string, failure: object | null, stats: object | null, clips: Array<{ name: string, duration: number }>, fileSize?: number | null },
- *   hostRef: { current: HTMLElement | null },
- *   onSettingsChange: (patch: Record<string, unknown>) => void,
- *   onRetry: () => void,
- * }} props Surface state and callbacks.
- */
-export function ViewerSurface({
-  format,
-  glb,
-  t,
-  view,
-  settings,
-  runtime,
-  hostRef,
-  onSettingsChange,
-  onRetry,
-}) {
-  const ready = runtime.status === 'ready' && view !== null;
-  const stats = runtime.stats;
-
-  return h('div', { className: 'dsh3dv-root', 'data-dsh3d-viewer': '', 'data-dsh3d-format': format },
-    h('style', null, CSS),
-    h('div', { className: 'dsh3dv-stage', ref: hostRef, 'data-dsh3d-stage': '' }),
-    h('div', { className: 'dsh3dv-top' },
-      h(Badge, { t, format, glb }),
-      h('div', { className: 'dsh3dv-top-actions' },
-        ready
-          ? h(ViewControls, {
-            material: settings.material,
-            environment: settings.environment,
-            onMaterialChange: (id) => onSettingsChange({ material: id, wireframe: false }),
-            onEnvironmentChange: (id) => onSettingsChange({ environment: id }),
-            t,
-          })
-          : null,
-        ready
-          ? h(Toolbar, {
-            view,
-            settings,
-            onChange: onSettingsChange,
-            t,
-          })
-          : null)),
-    ready && stats !== null
-      ? h('div', { className: 'dsh3dv-hud' },
-        h(StatsPanel, { stats, fileSize: runtime.fileSize, t }))
-      : null,
-    ready && runtime.clips.length > 0
-      ? h(AnimationBar, { view, clips: runtime.clips, t })
-      : null,
-    ready
-      ? h(Hint, { t })
-      : null,
-    h(StatusOverlay, {
-      status: runtime.status,
-      failure: runtime.failure,
-      onRetry,
-      t,
-    }));
-}

package/src/ui/chrome.js

@@ -1,220 +0,0 @@
-import * as React from 'react';
-import { badgeKeyFor } from '../formats.js';
-import { CubeIcon, FrameIcon, GridIcon, OrbitIcon, WireframeIcon } from './icons.js';
-import { ENVIRONMENT_OPTIONS, MATERIAL_OPTIONS } from './options.js';
-import { StatRow, ToolButton, errorText, formatBytes, formatCount } from './primitives.js';
-
-const h = React.createElement;
-
-/** Swatch shape used by the material and environment rails. */
-const PICKER_SWATCH = Object.freeze({
-  material: 'dsh3dv-ball',
-  environment: 'dsh3dv-env',
-});
-
-export function Badge({ t, format, glb }) {
-  return h('span', { className: 'dsh3dv-badge' },
-    h(CubeIcon),
-    h('span', null, t(badgeKeyFor(format, glb))));
-}
-
-export function Toolbar({ view, settings, onChange, t }) {
-  return h('div', { className: 'dsh3dv-toolbar', role: 'toolbar', 'aria-label': t('controls') },
-    h(ToolButton, {
-      label: t('reset'),
-      onClick: () => view?.reset(),
-    }, h(FrameIcon)),
-    h(ToolButton, {
-      label: t('autoRotate'),
-      active: settings.autoRotate,
-      onClick: () => onChange({ autoRotate: !settings.autoRotate }),
-    }, h(OrbitIcon)),
-    h(ToolButton, {
-      label: t('grid'),
-      active: settings.grid,
-      onClick: () => onChange({ grid: !settings.grid }),
-    }, h(GridIcon)),
-    h(ToolButton, {
-      label: t('wireframe'),
-      active: settings.wireframe,
-      onClick: () => onChange({ wireframe: !settings.wireframe }),
-    }, h(WireframeIcon)));
-}
-
-export function StatsPanel({ stats, fileSize, t }) {
-  return h('div', {
-    className: 'dsh3dv-stats',
-    'data-dsh3d-stats': '',
-    role: 'group',
-    'aria-label': t('statsTitle'),
-  },
-  Number.isFinite(fileSize) ? h(StatRow, { label: t('statsFileSize'), value: formatBytes(fileSize) }) : null,
-  h(StatRow, { label: t('statsMeshes'), value: formatCount(stats.meshes) }),
-  h(StatRow, { label: t('statsVertices'), value: formatCount(stats.vertices) }),
-  h(StatRow, { label: t('statsTriangles'), value: formatCount(stats.triangles) }));
-}
-
-/**
- * Find the option matching a settings id, falling back to the first one.
- *
- * @param {ReadonlyArray<{ id: string }>} options Rail options.
- * @param {string} value Current settings id.
- * @returns {{ id: string, labelKey: string, className: string }} Selected option.
- */
-function findOption(options, value) {
-  return options.find((option) => option.id === value) ?? options[0];
-}
-
-/**
- * One swatch trigger and its popup menu.
- *
- * The open state is owned by `ViewControls` so opening one rail closes the
- * other; the picker owns only focus management.
- */
-function Picker({ kind, groupLabel, options, value, open, onOpenChange, onSelect, t }) {
-  const triggerRef = React.useRef(null);
-  const menuRef = React.useRef(null);
-  const selected = findOption(options, value);
-  const swatch = PICKER_SWATCH[kind];
-  const label = `${groupLabel}: ${t(selected.labelKey)}`;
-
-  React.useEffect(() => {
-    if (!open) return;
-    menuRef.current?.querySelector('[aria-checked="true"]')?.focus?.();
-  }, [open]);
-
-  return h('div', { className: 'dsh3dv-picker' },
-    h('button', {
-      type: 'button',
-      className: 'dsh3dv-picker-trigger',
-      'data-dsh3d-picker': kind,
-      'aria-haspopup': 'menu',
-      'aria-expanded': open,
-      'aria-label': label,
-      title: label,
-      ref: triggerRef,
-      onClick: () => onOpenChange(open ? null : kind),
-    },
-    h('span', {
-      className: `dsh3dv-picker-swatch ${swatch} ${selected.className}`,
-      'aria-hidden': true,
-    })),
-    open
-      ? h('div', {
-        className: 'dsh3dv-picker-menu',
-        role: 'menu',
-        'data-dsh3d-picker-menu': kind,
-        'aria-label': groupLabel,
-        ref: menuRef,
-      }, options.map((option) => h('button', {
-        key: option.id,
-        type: 'button',
-        className: 'dsh3dv-picker-option',
-        role: 'menuitemradio',
-        'aria-checked': value === option.id,
-        title: t(option.labelKey),
-        onClick: () => {
-          onSelect(option.id);
-          onOpenChange(null);
-          triggerRef.current?.focus?.();
-        },
-      },
-      h('span', {
-        className: `dsh3dv-picker-option-swatch ${swatch} ${option.className}`,
-        'aria-hidden': true,
-      }),
-      h('span', { className: 'dsh3dv-picker-option-label' }, t(option.labelKey)))))
-      : null);
-}
-
-export function ViewControls({ material, environment, onMaterialChange, onEnvironmentChange, t }) {
-  const [open, setOpen] = React.useState(null);
-  const rootRef = React.useRef(null);
-
-  React.useEffect(() => {
-    if (open === null) return undefined;
-
-    const closeOnOutside = (event) => {
-      if (event.type === 'keydown' && event.key !== 'Escape') return;
-      if (event.type === 'pointerdown' && rootRef.current?.contains(event.target)) return;
-      setOpen(null);
-    };
-
-    document.addEventListener('pointerdown', closeOnOutside);
-    document.addEventListener('keydown', closeOnOutside);
-    return () => {
-      document.removeEventListener('pointerdown', closeOnOutside);
-      document.removeEventListener('keydown', closeOnOutside);
-    };
-  }, [open]);
-
-  return h('div', {
-    className: 'dsh3dv-view-controls',
-    'data-dsh3d-controls': '',
-    ref: rootRef,
-  },
-  h(Picker, {
-    kind: 'material',
-    groupLabel: t('materials'),
-    options: MATERIAL_OPTIONS,
-    value: material,
-    open: open === 'material',
-    onOpenChange: setOpen,
-    onSelect: onMaterialChange,
-    t,
-  }),
-  h(Picker, {
-    kind: 'environment',
-    groupLabel: t('environment'),
-    options: ENVIRONMENT_OPTIONS,
-    value: environment,
-    open: open === 'environment',
-    onOpenChange: setOpen,
-    onSelect: onEnvironmentChange,
-    t,
-  }));
-}
-
-export function Hint({ t }) {
-  return h('div', { className: 'dsh3dv-hint' }, t('hint'));
-}
-
-export function StatusOverlay({ status, failure, onRetry, t }) {
-  if (status === 'loading') {
-    return h('div', { className: 'dsh3dv-overlay', 'data-dsh3d-status': 'loading' },
-      h('div', {
-        className: 'dsh3dv-panel dsh3dv-panel--loading',
-        role: 'status',
-        'aria-live': 'polite',
-      },
-      h('span', { className: 'dsh3dv-spinner', 'aria-hidden': true }),
-      h('span', null, t('loading'))));
-  }
-
-  if (status === 'empty') {
-    return h('div', { className: 'dsh3dv-overlay', 'data-dsh3d-status': 'empty' },
-      h('div', { className: 'dsh3dv-panel', role: 'status' },
-        h('div', { className: 'dsh3dv-panel-icon' }, h(CubeIcon)),
-        h('p', { className: 'dsh3dv-panel-title' }, t('emptyTitle')),
-        h('p', { className: 'dsh3dv-panel-text' }, t('empty'))));
-  }
-
-  if (status === 'error') {
-    return h('div', { className: 'dsh3dv-overlay', 'data-dsh3d-status': 'error' },
-      h('div', { className: 'dsh3dv-panel dsh3dv-panel--error', role: 'alert' },
-        h('div', { className: 'dsh3dv-panel-icon' }, h(CubeIcon)),
-        h('p', { className: 'dsh3dv-panel-title' }, t('errorTitle')),
-        h('p', { className: 'dsh3dv-panel-text' }, errorText(failure, t)),
-        h('div', { className: 'dsh3dv-actions' },
-          h('button', {
-            type: 'button',
-            className: 'dsh3dv-action',
-            onClick: onRetry,
-          }, t('retry'))),
-        h('details', { className: 'dsh3dv-details' },
-          h('summary', null, t('details')),
-          h('pre', null, failure?.detail ?? ''))));
-  }
-
-  return null;
-}

package/src/ui/dictionaries.js

@@ -1,99 +0,0 @@
-export const zh = {
-  rendererTitle: 'FBX 3D',
-  objRendererTitle: 'OBJ 3D',
-  gltfRendererTitle: 'glTF / GLB 3D',
-  stlRendererTitle: 'STL 3D',
-  badge: 'FBX',
-  objBadge: 'OBJ',
-  gltfBadge: 'glTF',
-  glbBadge: 'GLB',
-  stlBadge: 'STL',
-  loading: '正在构建三维场景…',
-  emptyTitle: '没有可显示的网格',
-  empty: '这个文件不包含可见的网格模型。',
-  errorTitle: '无法显示这个三维模型',
-  parseFailed: '模型文件解析失败，请确认文件完整且格式受支持。',
-  webglUnavailable: '当前浏览器或设备无法创建 WebGL 2 上下文，暂时不能显示三维模型。',
-  renderFailed: '三维场景初始化失败。',
-  retry: '重试',
-  controls: '三维视图控制',
-  reset: '复位视角',
-  grid: '显示网格',
-  wireframe: '线框模式',
-  materials: '材质球',
-  materialOriginal: '原始材质',
-  materialDiffuse: '纯漫反射',
-  materialPlastic: '亮面塑料',
-  materialMetal: '镜面金属',
-  materialMetalPolished: '抛光金属',
-  materialClay: '雕塑陶土',
-  environment: '环境',
-  envNature: '自然',
-  envCity: '城市',
-  envIndoor: '室内',
-  envStudio: '影棚',
-  autoRotate: '自动旋转',
-  play: '播放',
-  pause: '暂停',
-  animation: '动画',
-  animationProgress: '动画进度',
-  animationFallback: '动画 {n}',
-  statsTitle: '模型统计',
-  statsFileSize: '文件大小',
-  statsMeshes: '网格数量',
-  statsVertices: '顶点数量',
-  statsTriangles: '三角面数量',
-  hint: '拖拽旋转 · 滚轮缩放 · 右键平移',
-  canvasLabel: '三维模型。拖拽旋转，滚轮缩放，右键平移，方向键旋转。',
-  details: '技术详情',
-};
-
-export const en = {
-  rendererTitle: 'FBX 3D',
-  objRendererTitle: 'OBJ 3D',
-  gltfRendererTitle: 'glTF / GLB 3D',
-  stlRendererTitle: 'STL 3D',
-  badge: 'FBX',
-  objBadge: 'OBJ',
-  gltfBadge: 'glTF',
-  glbBadge: 'GLB',
-  stlBadge: 'STL',
-  loading: 'Building 3D scene…',
-  emptyTitle: 'No visible meshes',
-  empty: 'This file contains no visible mesh geometry.',
-  errorTitle: 'Could not display this 3D model',
-  parseFailed: 'The model file could not be parsed. Check that it is complete and uses a supported format.',
-  webglUnavailable: 'This browser or device cannot create a WebGL 2 context, so the 3D model cannot be shown.',
-  renderFailed: 'The 3D scene could not be initialized.',
-  retry: 'Try again',
-  controls: '3D view controls',
-  reset: 'Reset view',
-  grid: 'Show grid',
-  wireframe: 'Wireframe',
-  materials: 'Materials',
-  materialOriginal: 'Original',
-  materialDiffuse: 'Pure Diffuse',
-  materialPlastic: 'Glossy Plastic',
-  materialMetal: 'Mirror Metal',
-  materialMetalPolished: 'Polished Metal',
-  materialClay: 'Sculpt Clay',
-  environment: 'Env',
-  envNature: 'Nature',
-  envCity: 'City',
-  envIndoor: 'Indoor',
-  envStudio: 'Studio',
-  autoRotate: 'Auto-rotate',
-  play: 'Play',
-  pause: 'Pause',
-  animation: 'Animation',
-  animationProgress: 'Animation progress',
-  animationFallback: 'Animation {n}',
-  statsTitle: 'Model statistics',
-  statsFileSize: 'File size',
-  statsMeshes: 'Meshes',
-  statsVertices: 'Vertices',
-  statsTriangles: 'Triangles',
-  hint: 'Drag to rotate · Scroll to zoom · Right-drag to pan',
-  canvasLabel: '3D model. Drag to rotate, scroll to zoom, right-drag to pan, or use the arrow keys.',
-  details: 'Technical details',
-};