@campfire-interactive/volume-intelligence-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,401 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Wide = months across columns (IHS/AFS); tall = one row per period (EDI). */
+type VolumeSourceLayout = 'wide' | 'tall';
+interface VolumeSource$1 {
+    id: string;
+    name: string;
+    layout: VolumeSourceLayout;
+    /** e.g. 'base' | 'overlay' — informational; the component does not branch on it. */
+    kind?: string;
+    /** False when the source can't accept an upload yet (unmapped, no calendar…). */
+    ready?: boolean;
+    /** Human-readable reasons the source isn't ready. Rendered as blockers. */
+    blockers?: string[];
+}
+type UploadStatus$1 = 'pending' | 'processing' | 'awaiting_calendar' | 'done' | 'done_with_errors' | 'failed';
+interface UploadStats {
+    programs?: number;
+    volumes?: number;
+    [key: string]: number | undefined;
+}
+interface UploadRecord {
+    id: string;
+    fileName: string;
+    status: UploadStatus$1;
+    createdAt: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    stats?: UploadStats | null;
+    errorCount?: number;
+}
+interface UploadErrorRow {
+    id?: string;
+    /** Typed category from VI (MISSING_KEY, INVALID_VALUE, …). */
+    type: string;
+    message: string;
+    /** 1-based source row, when the error is row-scoped. */
+    row?: number | null;
+}
+/** Parameters for a single upload. Period fields apply to wide-format sources. */
+interface UploadInput {
+    sourceId: string;
+    file: File;
+    uploadYear?: number;
+    /** 1-based month (1 = January). */
+    uploadMonth?: number;
+    /** Months of lag before which data is treated as actuals vs predictions. */
+    actualsLagMonths?: number;
+}
+interface ListErrorsResult {
+    errors: UploadErrorRow[];
+    total: number;
+}
+/**
+ * Everything the component needs from the outside world. The host implements
+ * each method against its own wiring. `reprocess` is optional — hosts that
+ * don't expose it simply hide the reprocess affordance.
+ */
+interface VolumeImportTransport {
+    listSources(): Promise<VolumeSource$1[]>;
+    uploadFile(input: UploadInput): Promise<UploadRecord>;
+    getUpload(uploadId: string): Promise<UploadRecord>;
+    listErrors(uploadId: string, opts?: {
+        page?: number;
+    }): Promise<ListErrorsResult>;
+    reprocess?(uploadId: string): Promise<UploadRecord>;
+}
+interface VolumeImportProps {
+    transport: VolumeImportTransport;
+    /** Pre-select this source id (e.g. a tenant's default automotive source). */
+    defaultSourceId?: string;
+    /** Poll interval (ms) while an upload is in a non-terminal state. Default 3000. */
+    pollIntervalMs?: number;
+    /** Called whenever an upload reaches a terminal state (done / errors / failed). */
+    onUploaded?: (upload: UploadRecord) => void;
+    /** Extra class on the root element, for host layout. */
+    className?: string;
+}
+
+/**
+ * VolumeImport — the shared volume-file import surface.
+ *
+ * Lean scope (data-plane ADR §6, "lean now, rich later"): pick a source, upload
+ * a file, watch it process, see any row errors. No column-mapping / preview /
+ * conflict-resolve wizard — those are a tracked follow-on. The component is
+ * auth- and transport-agnostic; the host wires `transport`.
+ */
+declare function VolumeImport(props: VolumeImportProps): react.JSX.Element;
+
+type SourceLayout = 'wide' | 'tall';
+/** `base` = IHS/AFS historical training signal (one active per tenant);
+ *  `overlay` = EDI-style additive customer-stated demand. */
+type VolumeSourceKind = 'base' | 'overlay';
+interface VolumeSource {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    headerRowIndex: number;
+    volumeHeaderFormat: string;
+    isActive: boolean;
+    uniqueKeySegmentId: string | null;
+    layout: SourceLayout;
+    kind: VolumeSourceKind;
+    valueDateFormat: string;
+    _count?: {
+        segments: number;
+    };
+}
+interface VolumeSourceSegment {
+    id: string;
+    sourceId: string;
+    label: string;
+    dataType: string;
+    sortOrder: number;
+}
+interface SourceWithSegments extends VolumeSource {
+    segments: VolumeSourceSegment[];
+}
+interface TenantVolumeConfig {
+    id: string;
+    tenantId: string;
+    sourceId: string;
+    source: SourceWithSegments;
+}
+type SegmentMappingCategory = 'hierarchy_level' | 'automotive_field' | 'period' | 'value';
+interface SegmentMappingRow {
+    id: string;
+    sourceId: string;
+    targetCategory: SegmentMappingCategory;
+    targetKey: string;
+    segmentId: string;
+    /** Display label of the source column, carried on every row. */
+    segmentLabel: string;
+    transformRule: string | null;
+}
+interface SegmentMappingCategoryKeys {
+    category: SegmentMappingCategory;
+    targetKeys: readonly string[];
+    requiredKeys: readonly string[];
+}
+interface SegmentMappingKeys {
+    categories: SegmentMappingCategoryKeys[];
+    transformRules: readonly string[];
+}
+/** A single entry in a category-replace (`replaceSegmentMappingCategory`). */
+interface SegmentMappingEntry {
+    targetKey: string;
+    segmentId: string;
+    transformRule?: string | null;
+}
+interface SourceValueAlias {
+    id: string;
+    sourceId: string;
+    level: number;
+    rawValue: string;
+    canonicalValue: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ValueAliasEntry {
+    rawValue: string;
+    canonicalValue: string;
+}
+interface RelinkResult {
+    totalOverlay: number;
+    linked: number;
+    unlinked: number;
+    ambiguous: number;
+}
+interface SourceTemplateSummary {
+    code: string;
+    name: string;
+    description: string;
+}
+type UploadStatus = 'pending' | 'processing' | 'awaiting_calendar' | 'done' | 'done_with_errors' | 'failed';
+interface Upload {
+    id: string;
+    tenantId: string;
+    sourceId: string;
+    fileName: string;
+    s3Key: string;
+    uploadYear: number;
+    uploadMonth: number;
+    actualsLagMonths: number;
+    status: UploadStatus;
+    rowsTotal: number;
+    rowsProcessed: number;
+    rowsFailed: number;
+    rowsCanonicalised: number;
+    rowsQueued: number;
+    rowsBound: number;
+    errorSummary: string | null;
+    uploadedBy: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    source: {
+        code: string;
+        name: string;
+        kind: VolumeSourceKind;
+    };
+}
+interface UploadError {
+    id: string;
+    uploadId: string;
+    rowNumber: number;
+    keyValue: string | null;
+    errorType: string;
+    errorDetail: string;
+    severity: 'error' | 'warn' | 'info';
+    createdAt: string;
+}
+interface UploadListParams {
+    limit?: number;
+    offset?: number;
+    status?: UploadStatus;
+    sourceId?: string;
+    year?: number;
+    month?: number;
+}
+interface UploadListResponse {
+    items: Upload[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface CreateSourceInput {
+    code: string;
+    name: string;
+    description?: string;
+    headerRowIndex?: number;
+    volumeHeaderFormat?: string;
+}
+interface UpdateSourceInput {
+    name?: string;
+    description?: string;
+    headerRowIndex?: number;
+    volumeHeaderFormat?: string;
+    isActive?: boolean;
+    uniqueKeySegmentId?: string | null;
+    layout?: SourceLayout;
+    valueDateFormat?: string;
+    kind?: VolumeSourceKind;
+}
+interface CreateSegmentInput {
+    label: string;
+    dataType?: string;
+    sortOrder?: number;
+}
+interface DetectSegmentsResult {
+    detected: number;
+    skipped: number;
+}
+interface ClearSourceDataResult {
+    uploads: number;
+    criteria: number;
+    cleared: true;
+}
+/**
+ * Everything the source-management components need from the host. VI-webapp
+ * implements these against its `adminApi`; OMSF implements them against proxy
+ * routes that mint a `forecast-backend` system token and call VI, so OMSF's
+ * browser never holds a vi-backend token.
+ */
+interface SourceAdminTransport {
+    listSources(): Promise<VolumeSource[]>;
+    getSource(id: string): Promise<SourceWithSegments>;
+    createSource(data: CreateSourceInput): Promise<VolumeSource>;
+    updateSource(id: string, data: UpdateSourceInput): Promise<VolumeSource>;
+    activateSource(id: string): Promise<{
+        activated: boolean;
+        wiped: boolean;
+    }>;
+    listSourceTemplates(): Promise<SourceTemplateSummary[]>;
+    createSourceFromTemplate(templateCode: string): Promise<{
+        id: string;
+    }>;
+    listSegments(sourceId: string): Promise<VolumeSourceSegment[]>;
+    detectSegments(sourceId: string, file: File): Promise<DetectSegmentsResult>;
+    createSegment(sourceId: string, input: CreateSegmentInput): Promise<VolumeSourceSegment>;
+    deleteSegment(segmentId: string): Promise<void>;
+    getSegmentMappingKeys(): Promise<SegmentMappingKeys>;
+    listSegmentMapping(sourceId: string, category?: SegmentMappingCategory): Promise<{
+        items: SegmentMappingRow[];
+    }>;
+    replaceSegmentMappingCategory(sourceId: string, category: SegmentMappingCategory, entries: SegmentMappingEntry[]): Promise<{
+        items: SegmentMappingRow[];
+    }>;
+    listValueAliases(sourceId: string): Promise<SourceValueAlias[]>;
+    replaceLevelValueAliases(sourceId: string, level: number, entries: ValueAliasEntry[]): Promise<SourceValueAlias[]>;
+    deleteValueAlias(aliasId: string): Promise<void>;
+    relinkOverlaySource(sourceId: string): Promise<RelinkResult>;
+    getTenantConfig(): Promise<TenantVolumeConfig | null>;
+    setTenantSource(sourceId: string): Promise<TenantVolumeConfig>;
+    listUploads(params?: UploadListParams): Promise<UploadListResponse>;
+    clearSourceData(sourceId: string, confirm: string): Promise<ClearSourceDataResult>;
+}
+
+interface VolumeSourcesListProps {
+    transport: SourceAdminTransport;
+    /** Open a source's detail view. The host owns routing. */
+    onOpenSource: (sourceId: string) => void;
+    /**
+     * Optional slot rendered inside the *active* source's card. The VI webapp
+     * injects its paid analytical sub-cards (enrichment toggle, backtests) here;
+     * OMSF and other lean hosts simply omit it. Keeps those surfaces VI-only
+     * (ADR §6) while the list itself stays host-agnostic.
+     */
+    renderActiveSourceExtras?: (source: VolumeSource) => ReactNode;
+    className?: string;
+}
+/**
+ * Volume-source list: cards per source, "add from template", manual create,
+ * and activate (with the data-wipe confirm). Transport-agnostic and router-free
+ * — the host supplies `transport` and an `onOpenSource` navigation callback.
+ *
+ * The VI-webapp's active-source analytical sub-cards (enrichment toggle,
+ * backtests) are intentionally NOT here — per ADR §6 they stay VI-webapp-only.
+ */
+declare function VolumeSourcesList({ transport, onOpenSource, renderActiveSourceExtras, className }: VolumeSourcesListProps): react.JSX.Element;
+
+interface AutomotiveSlot {
+    key: string;
+    label: string;
+    required: boolean;
+    defaultTransform?: string;
+    hierarchyCoveredByLevel?: number;
+}
+interface UnifiedSegmentMapperProps {
+    segments: VolumeSourceSegment[];
+    hierarchyInitial: SegmentMappingRow[];
+    automotiveInitial: SegmentMappingRow[];
+    automotiveSlots: AutomotiveSlot[];
+    transformRules: readonly string[];
+    transformRuleLabels: Record<string, string>;
+    onSave: (hierarchy: Array<{
+        targetKey: string;
+        segmentId: string;
+    }>, automotive: Array<{
+        targetKey: string;
+        segmentId: string;
+        transformRule?: string | null;
+    }>) => Promise<void>;
+    saving: boolean;
+    hierarchyMode?: 'tree' | 'sparse';
+    baseHierarchyHint?: Partial<Record<number, string>>;
+}
+declare function UnifiedSegmentMapper({ segments, hierarchyInitial, automotiveInitial, automotiveSlots, transformRules, transformRuleLabels, onSave, saving, hierarchyMode, baseHierarchyHint, }: UnifiedSegmentMapperProps): react.JSX.Element;
+
+interface VolumeSourceDetailProps {
+    transport: SourceAdminTransport;
+    sourceId: string;
+    /** Navigate to another source (the header switcher). Host owns routing. */
+    onOpenSource: (sourceId: string) => void;
+    /** Optional "All sources →" affordance; hidden when omitted. */
+    onBack?: () => void;
+    className?: string;
+}
+/**
+ * Volume-source detail: layout, unique key, segment detect/add/delete, the
+ * segment mapper, tall mappings, value aliases, and the clear-data danger zone.
+ * Ported from forecast's SourceDetailPage; adminApi → injected transport,
+ * react-router → onOpenSource/onBack callbacks, shadcn/Tailwind → plain CSS.
+ */
+declare function VolumeSourceDetail({ transport, sourceId, onOpenSource, onBack, className }: VolumeSourceDetailProps): react.JSX.Element;
+
+interface TallLayoutMappingsProps {
+    transport: SourceAdminTransport;
+    source: SourceWithSegments;
+    locked: boolean;
+}
+declare function TallLayoutMappings({ transport, source, locked }: TallLayoutMappingsProps): react.JSX.Element;
+
+/**
+ * Per-source, per-level value alias editor. Ported from forecast; adminApi
+ * calls lifted to the injected transport. The matcher applies aliases to both
+ * sides of the overlay→base comparison, so an operator can fix vocabulary
+ * drift (e.g. "MICHIGAN" → "MICHIGAN ASSEMBLY") without re-uploading.
+ */
+interface ValueAliasesCardProps {
+    transport: SourceAdminTransport;
+    sourceId: string;
+    locked: boolean;
+    isOverlay: boolean;
+}
+declare function ValueAliasesCard({ transport, sourceId, locked, isOverlay }: ValueAliasesCardProps): react.JSX.Element;
+
+declare const HIERARCHY_LEVEL_COUNT = 6;
+/** Display labels for hierarchy levels 1..6 (the mapping of source columns to
+ *  levels is per-tenant config; this only controls the label). */
+declare const DEFAULT_LEVEL_NAMES: Record<number, string>;
+/** Automotive slots shown in the unified mapper for BASE sources (IHS/AFS/LMC).
+ *  Five auto-cover from the hierarchy (oem_parent←L1, platform←L2, program←L3,
+ *  plant_name←L4, nameplate←L5); `brand` falls back to oem_parent; the rest are
+ *  required and explicitly mapped. Overlay sources pass an empty array. */
+declare const AUTOMOTIVE_SLOTS: AutomotiveSlot[];
+declare const AUTOMOTIVE_TRANSFORM_LABELS: Record<string, string>;
+
+export { AUTOMOTIVE_SLOTS, AUTOMOTIVE_TRANSFORM_LABELS, type AutomotiveSlot, type ClearSourceDataResult, type CreateSegmentInput, type CreateSourceInput, DEFAULT_LEVEL_NAMES, type DetectSegmentsResult, HIERARCHY_LEVEL_COUNT, type ListErrorsResult, type RelinkResult, type SegmentMappingCategory, type SegmentMappingCategoryKeys, type SegmentMappingEntry, type SegmentMappingKeys, type SegmentMappingRow, type SourceAdminTransport, type SourceLayout, type SourceTemplateSummary, type SourceValueAlias, type SourceWithSegments, TallLayoutMappings, type TallLayoutMappingsProps, type TenantVolumeConfig, UnifiedSegmentMapper, type UnifiedSegmentMapperProps, type UpdateSourceInput, type Upload, type UploadError, type UploadErrorRow, type UploadInput, type UploadListParams, type UploadListResponse, type UploadRecord, type UploadStats, type UploadStatus, type ValueAliasEntry, ValueAliasesCard, type ValueAliasesCardProps, VolumeImport, type VolumeImportProps, type VolumeSource$1 as VolumeImportSource, type VolumeImportTransport, type UploadStatus$1 as VolumeImportUploadStatus, type VolumeSource, VolumeSourceDetail, type VolumeSourceDetailProps, type VolumeSourceKind, type VolumeSourceLayout, type VolumeSourceSegment, VolumeSourcesList, type VolumeSourcesListProps };