@medicaresoft/dicom-viewer 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @medicaresoft/dicom-viewer
+
+Visor DICOM reutilizable para React, basado en Cornerstone v2
+(core/tools/wado-image-loader). Es el **núcleo de visualización** de un PACS:
+sin lógica de negocio, sin permisos, sin router y sin HTTP propio. Todo lo
+específico del host se inyecta por props.
+
+## Instalación
+
+```bash
+npm install @medicaresoft/dicom-viewer
+```
+
+Peer dependencies: `react` y `react-dom` (>= 18).
+
+## Uso mínimo
+
+```tsx
+import { DicomViewer } from "@medicaresoft/dicom-viewer";
+import "@medicaresoft/dicom-viewer/style.css"; // si tu host NO compila Tailwind sobre el paquete
+
+export function App() {
+  return (
+    <DicomViewer
+      study={study}                                     // metadatos (ver DicomStudy)
+      getDicomFile={(uid) => fetchMyDicom(uid)}         // (instanceUid) => Promise<Blob>
+    />
+  );
+}
+```
+
+El host decide de dónde salen los bytes: API propia, DICOMweb, disco local
+(Wails), etc. El visor solo pide `(instanceUid) => Blob`.
+
+## Props principales
+
+| Prop | Tipo | Descripción |
+| --- | --- | --- |
+| `study` | `DicomStudy` | Metadatos del estudio (paciente + series + files con `instanceUid`) |
+| `getDicomFile` | `(instanceUid) => Promise<Blob \| ArrayBuffer>` | Fuente de bytes DICOM (requerido) |
+| `getThumbnailUrl` | `(instanceUid) => string` | Miniaturas de series (opcional) |
+| `presets` | `Record<string, Record<string, { W; C }>>` | Presets de ventana por modalidad (opcional) |
+| `maxConcurrentDownloads` | `number` | Límite global de descargas concurrentes (default 12) |
+| `branding` | `{ logo?, name? }` | Logo/nombre en overlays |
+| `onBack` | `() => void` | Si se define, muestra botón volver |
+| `actions` | `ReactNode` | `<Action/>` inyectadas en slots |
+| `modals` | `ReactNode` | `<ViewerModal/>` inyectados |
+
+## Acciones y modales (slots)
+
+El visor reserva zonas (toolbar/sidebar/footer) donde el host inyecta sus
+botones; los permisos viven en el host:
+
+```tsx
+import { DicomViewer, Action, ViewerModal } from "@medicaresoft/dicom-viewer";
+
+<DicomViewer study={study} getDicomFile={fetcher}>
+  <Action
+    placement="sidebar"
+    id="reports"
+    label="Informes"
+    icon={<FileText size={16} />}
+    visible={() => user.can("reports.view")}   // permisos del host
+    onClick={(ctx) => setShowReports(true)}    // ctx: { study, activeSeriesIndex }
+  />
+  <ViewerModal id="reports" open={showReports}>
+    <MyReportsModal onClose={() => setShowReports(false)} />
+  </ViewerModal>
+</DicomViewer>
+```
+
+`actions` y `modals` también aceptan arrays de `<Action/>`/`<ViewerModal/>`.
+Si una acción trae `children`, se renderiza tal cual (botón 100% custom del
+host).
+
+## Skeleton ligero
+
+Subpath sin Cornerstone para usar como fallback mientras se carga el visor:
+
+```tsx
+import { lazy, Suspense } from "react";
+import { DicomViewerSkeleton } from "@medicaresoft/dicom-viewer/skeleton";
+
+const DicomViewer = lazy(() =>
+  import("@medicaresoft/dicom-viewer").then((m) => ({ default: m.DicomViewer })),
+);
+
+<Suspense fallback={<DicomViewerSkeleton />}>
+  <DicomViewer study={study} getDicomFile={fetcher} />
+</Suspense>
+```
+
+## Estilos
+
+- **Host con Tailwind v4**: agrega el paquete a tu contenido
+  (`@source "../node_modules/@medicaresoft/dicom-viewer/dist";`) y sobreescribe
+  las variables `--dv-primary` / `--dv-secondary` para tu marca.
+- **Host sin Tailwind**: importa `@medicaresoft/dicom-viewer/style.css`.
+
+## Tipos
+
+```ts
+interface DicomStudy {
+  id: string;
+  studyInstanceUid: string;
+  patientName: string;
+  patientId: string;
+  patientBirthDate?: string;
+  patientAge?: string;
+  patientSex?: string;
+  studyDate?: string;
+  studyTime?: string;
+  studyDescription?: string;
+  series: Array<{
+    id: string;
+    seriesInstanceUid: string;
+    modality: string;
+    name: string;
+    files: Array<{ position: number; instanceUid: string }>;
+  }>;
+}
+```
+
+El objeto de estudio de tu app es compatible por asignación estructural
+(campos extra permitidos).
+
+## Notas
+
+- Basado en la generación legacy de Cornerstone (v2); migración a
+  Cornerstone3D prevista como fase posterior, sin cambios de API.
+- El visor asigna dependencias a `window` (cornerstone, hammerjs) al
+  inicializarse — requerido por las libs legacy.

package/dist/Action.d.ts

@@ -0,0 +1,8 @@
+import type { ActionProps, ViewerModalProps } from "./types";
+/**
+ * Componentes declarativos para inyectar botones y modales.
+ * No pintan nada por sí mismos: `DicomViewer` lee sus props y los reparte a
+ * los slots reservados (toolbar/sidebar/footer) y a la capa de modales.
+ */
+export declare const Action: (_props: ActionProps) => null;
+export declare const ViewerModal: ({ open, children }: ViewerModalProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/DicomViewer.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+import type { DicomFileFetcher, DicomStudy, PresetsConfig, ThumbnailUrlResolver, ViewerBranding } from "./types";
+export interface DicomViewerProps {
+    /** Metadatos del estudio (el host los obtiene de donde quiera). */
+    study: DicomStudy;
+    /** Fuente de bytes DICOM inyectada por el host: (instanceUid) => Blob. */
+    getDicomFile: DicomFileFetcher;
+    /** Resuelve URLs de miniaturas de series (opcional; sin esto no hay thumbs). */
+    getThumbnailUrl?: ThumbnailUrlResolver;
+    /** Presets de ventana por modalidad (opcional). */
+    presets?: PresetsConfig;
+    /** Máximo global de descargas concurrentes entre todos los viewports. */
+    maxConcurrentDownloads?: number;
+    /** Logo y nombre de institución para overlays/toolbar (opcional). */
+    branding?: ViewerBranding;
+    /** Si se define, se muestra el botón de volver; el paquete no usa router. */
+    onBack?: () => void;
+    /** Acciones inyectadas: <Action placement=... /> para toolbar/sidebar/footer. */
+    actions?: ReactNode;
+    /** Modales inyectados: <ViewerModal open=...>...</ViewerModal>. */
+    modals?: ReactNode;
+    className?: string;
+}
+/**
+ * Visor DICOM reutilizable. Núcleo de visualización: sin permisos, sin
+ * lógica de negocio, sin router y sin HTTP propio. Todo lo específico del
+ * host llega por props (datos, fetchers, branding, acciones y modales).
+ */
+export declare const DicomViewer: ({ study, getDicomFile, getThumbnailUrl, presets, maxConcurrentDownloads, branding, onBack, actions: actionsProp, modals: modalsProp, className, }: DicomViewerProps) => import("react/jsx-runtime").JSX.Element;
+export default DicomViewer;

package/dist/components/DicomOverlays.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+interface DicomOverlaysProps {
+    seriesIndex?: number;
+    currentImageIndex?: number;
+    totalImages?: number;
+    ww?: number | null;
+    wc?: number | null;
+}
+export declare const DicomOverlays: React.FC<DicomOverlaysProps>;
+export {};

package/dist/components/DicomPlaybackControls.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+export declare const DicomPlaybackControls: React.FC;
+export default DicomPlaybackControls;

package/dist/components/DicomToolbar.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const DicomToolbar: React.FC;

package/dist/components/DicomToolbarButton.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+interface DicomToolbarButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    active?: boolean;
+    variant?: "tool" | "action" | "destructive";
+    icon?: React.ReactNode;
+    label?: string;
+    boundButtons?: {
+        left?: boolean;
+        right?: boolean;
+        middle?: boolean;
+    };
+}
+export declare const DicomToolbarButton: React.FC<DicomToolbarButtonProps>;
+export {};

package/dist/components/DicomViewport.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const DicomViewport: React.FC;

package/dist/components/MobileTimelineSlider.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const MobileTimelineSlider: React.FC;
+export default MobileTimelineSlider;

package/dist/components/MobileToolsPanel.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const MobileToolsPanel: React.FC;

package/dist/components/PresetsDropdown.d.ts

@@ -0,0 +1 @@
+export declare const PresetsDropdown: () => import("react/jsx-runtime").JSX.Element;

package/dist/components/footer.d.ts

@@ -0,0 +1,2 @@
+declare const Footer: () => import("react/jsx-runtime").JSX.Element;
+export default Footer;

package/dist/components/sidebar.d.ts

@@ -0,0 +1,2 @@
+declare const SideBar: () => import("react/jsx-runtime").JSX.Element;
+export default SideBar;

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+import { type LucideIcon } from "lucide-react";
+export interface ToolButtonConfig {
+    id: "Wwwc" | "Zoom" | "Pan" | "Length" | "Angle" | "CobbAngle" | "Probe" | "EllipticalRoi" | "RectangleRoi" | "Magnify";
+    label: string;
+    Icon: LucideIcon;
+    title: string;
+}
+export declare const toolButtons: readonly ToolButtonConfig[];

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+import type { DicomStudy, ActionPlacement, ActionProps } from "./types";
+import type { DicomContextType, DicomViewerAction, DicomViewerState } from "./interfaces";
+export declare const DicomViewerContext: import("react").Context<DicomContextType | undefined>;
+export declare const useDicomContext: () => DicomContextType;
+export declare const initialDicomState: (study: DicomStudy) => DicomViewerState;
+export declare function dicomViewerReducer(state: DicomViewerState, action: DicomViewerAction): DicomViewerState;
+/**
+ * Devuelve las acciones inyectadas para un slot, ya filtradas por `visible()`.
+ * La evaluación ocurre en cada render del slot (los permisos del host viven
+ * en `visible` y se re-evalúan cuando el wrapper re-renderiza).
+ */
+export declare const useViewerActions: (placement: ActionPlacement) => ActionProps[];

package/dist/downloadQueue.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cola global de descargas compartida entre todos los viewports del visor.
+ * Cada viewport encola la descarga de sus instancias; la cola limita el total
+ * de peticiones concurrentes del visor completo (evita 4×8=32 con layout 2x2).
+ */
+export declare class DownloadQueue {
+    private readonly maxConcurrent;
+    private active;
+    private waiting;
+    constructor(maxConcurrent: number);
+    run<T>(task: () => Promise<T>): Promise<T>;
+}

package/dist/hooks/useCornerstoneViewer.d.ts

@@ -0,0 +1,27 @@
+import type { DicomFileFetcher, DicomStudy } from "../types";
+import type { DownloadQueue } from "../downloadQueue";
+export declare function useCornerstoneViewer(study: DicomStudy, seriesIndex?: number, onImageIndexChange?: (index: number) => void, playSpeed?: number, showReferenceLines?: boolean, referenceLinesSynchronizer?: any, getDicomFile?: DicomFileFetcher, downloadQueue?: DownloadQueue): {
+    viewportRef: import("react").RefObject<HTMLDivElement | null>;
+    isLoading: boolean;
+    loadingProgress: number;
+    downloadedCount: number;
+    totalImages: number;
+    currentImageIndex: number;
+    activeTool: string;
+    toolBindings: Record<number, string>;
+    isPlaying: boolean;
+    ww: number | null;
+    wc: number | null;
+    zoomScale: number;
+    changeTool: (toolName: string, mouseButtonMask?: number) => void;
+    handleSliderChange: (index: number) => Promise<void>;
+    togglePlay: () => void;
+    handleResetView: () => void;
+    handleClearMeasurements: () => void;
+    setWindowing: (width: number, center: number) => void;
+    handleInvert: () => void;
+    handleRotateCw: () => void;
+    handleRotateCcw: () => void;
+    handleFlipHorizontal: () => void;
+    handleFlipVertical: () => void;
+};

package/dist/hooks/useDicomViewerState.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement } from "react";
+import type { DicomContextType } from "../interfaces";
+import type { ActionProps, DicomFileFetcher, DicomStudy, PresetsConfig, ThumbnailUrlResolver, ViewerBranding, ViewerModalProps } from "../types";
+/** Configuración inyectada por el host al componente DicomViewer. */
+export interface ViewerSetupConfig {
+    getDicomFile: DicomFileFetcher;
+    getThumbnailUrl?: ThumbnailUrlResolver;
+    presets?: PresetsConfig;
+    maxConcurrentDownloads?: number;
+    branding?: ViewerBranding;
+    onBack?: () => void;
+    actions?: ReactElement<ActionProps>[];
+    modals?: ReactElement<ViewerModalProps>[];
+}
+export declare const useDicomViewerState: (study: DicomStudy, config: ViewerSetupConfig) => DicomContextType;

package/dist/hooks/useDragScroll.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Drag-scroll horizontal para contenedores overflow (toolbar de herramientas
+ * y lista de series). Utilidad genérica sin lógica de negocio.
+ */
+export declare function useDragScroll(): {
+    onMouseDown: (e: React.MouseEvent<HTMLDivElement>) => void;
+    onMouseLeave: () => void;
+    onMouseUp: () => void;
+    onMouseMove: (e: React.MouseEvent<HTMLDivElement>) => void;
+    onClickCapture: (e: React.MouseEvent<HTMLDivElement>) => void;
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import "./style.css";
+export { DicomViewer } from "./DicomViewer";
+export type { DicomViewerProps } from "./DicomViewer";
+export { Action, ViewerModal } from "./Action";
+export { DicomToolbarButton } from "./components/DicomToolbarButton";
+export { useDicomContext, useViewerActions, DicomViewerContext } from "./context";
+export type { ActionContext, ActionPlacement, ActionProps, DicomFile, DicomFileFetcher, DicomSeries, DicomStudy, PresetsConfig, ThumbnailUrlResolver, ViewerBranding, ViewerModalProps, } from "./types";