@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.1

package/dist/components/types/uhd-viewer/src/model/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Neutral view contract (PB-784). The canvas renders only these types; the
+ * UHD adapter (./from-uhd.ts) produces them from a system ModuleDef.
+ * Every id is a canonical path so layout and selection survive model edits.
+ */
+export type LinkState = "configured" | "partial" | "incompatible" | "unconfigured";
+export type NodeKind = "module" | "group" | "harness" | "board" | "net";
+export type Shape = "rect" | "circle" | "pill";
+/** A child interface revealed when a link is opened (a slot and the leaf bound to it). */
+export interface ViewChildPort {
+    slotId: string;
+    name: string;
+    /** Leaf interface id on the module, e.g. "gnss_uart_tx". */
+    leafId?: string;
+    /** Pad or pin label, e.g. "TX". */
+    pin?: string;
+}
+export interface ViewPort {
+    /** Interface id on its module (or export id on a group/module boundary). */
+    id: string;
+    name: string;
+    domain: string;
+    /** Primary protocol type, used for signal-type classification and grouping. */
+    protocol: string;
+    roles: string[];
+    children: ViewChildPort[];
+    /** True when the port is a boundary export of a child interface. */
+    exported?: {
+        child: string;
+        interfaceId: string;
+    };
+}
+export interface ViewNode {
+    /** Canonical path, e.g. "stack/esc" or "arm_fl". */
+    id: string;
+    label: string;
+    icon: string;
+    kind: NodeKind;
+    /** Parent node path when drawn inside an expanded module or group. */
+    parent?: string;
+    /** True when the node has children and is drawn expanded in place. */
+    expanded?: boolean;
+    ports: ViewPort[];
+    shape: Shape;
+    status: LinkState;
+    /** UHD definition id, for the inspector. */
+    defId?: string;
+    manufacturer?: string;
+    partNumber?: string;
+    description?: string;
+    category?: string;
+    childCount: number;
+    /** A boundary port of the drilled-into module, drawn at the canvas edge. */
+    sheetPort?: boolean;
+    /** A board net (PB-823): drawn as a junction its members' grouped membership links meet at. */
+    net?: ViewNet;
+    /**
+     * A rail drawn in several places (PB-873): this junction is a local tap of the
+     * net junction with this id, joined to the members near it. Selecting a tap
+     * selects the net.
+     */
+    tapOf?: string;
+    /** The bundle does not hold this module's definition: a placeholder with the interfaces its links name. */
+    missing?: boolean;
+}
+/** A net on a board (UHD `Net` interface, exposed: false), as a junction node. */
+export interface ViewNet {
+    /** Net interface id on the board, e.g. "v3v3". */
+    id: string;
+    name: string;
+    /** What the net carries, for the signal classification: "power", "ground", "i2c", "digital"… */
+    signal: string;
+    /** Design voltage as stated on the net ("3.3 V", "2.5–5.5 V"). */
+    voltage?: string;
+    /** A ground net: drawn as ground symbols at its members unless GND wires are on. */
+    ground: boolean;
+    /** Pins on the net. */
+    pins: number;
+}
+export interface ViewEndpoint {
+    node: string;
+    port: string;
+}
+export interface ViewChildLink {
+    id: string;
+    label: string;
+    a: string;
+    b: string;
+    aPin?: string;
+    bPin?: string;
+    state: LinkState;
+}
+/**
+ * One lane of an expanded link (PB-803/805): a child interface of the link,
+ * or a link derived through a cable. A lane with its own children is itself a
+ * bundle and can be opened in place.
+ */
+export interface ViewLane {
+    id: string;
+    name: string;
+    domain: string;
+    protocol: string;
+    state: LinkState;
+    children: ViewLane[];
+    /** Conductor ids this lane carries (ribbon mode groups them under the lane). */
+    conductors?: string[];
+}
+/** One physical conductor of a link, for ribbon (detailed) mode. */
+export interface ViewConductor {
+    id: string;
+    label: string;
+    /** Signal protocol of the conductor, for its colour ("power", "ground", "uart", …). */
+    protocol: string;
+    domain: string;
+    /** DRC state of the connection this conductor carries. */
+    state: LinkState;
+}
+/** The harness a link runs through, drawn as a region along its route. */
+export interface ViewHarnessRun {
+    /** Harness child path at this level. */
+    id: string;
+    /** Its UHD definition id (for the inspector: artifacts, thumbnail, CAD). */
+    defId: string;
+    name: string;
+    icon: string;
+    /** Carried by a physical cable (connector ends) rather than named on a logical link. */
+    physical: boolean;
+    /** Only the first link of a harness carries its name tab. */
+    tab: boolean;
+}
+export interface ViewLink {
+    id: string;
+    source: ViewEndpoint;
+    target: ViewEndpoint;
+    name: string;
+    domain: string;
+    protocol: string;
+    state: LinkState;
+    children: ViewChildLink[];
+    /** Pass-through from a boundary export to the child interface it exposes. */
+    passThrough?: boolean;
+    /** Ground return: drawn as ground symbols at both ports instead of a wire. */
+    ground?: boolean;
+    /** Harness node carrying the link, if any. */
+    harness?: string;
+    /**
+     * A link carried by a harness is drawn as two segments through the harness
+     * node: "a" (source → harness, carries the label) and "b" (harness → target).
+     */
+    segment?: "a" | "b";
+    /** Stored link id (shared by both segments). */
+    linkId: string;
+    /** Other stored link ids drawn by this link (the second half of a cable). */
+    alsoIds?: string[];
+    /** Lanes shown when the link is expanded (basic mode). */
+    lanes?: ViewLane[];
+    /** Conductors shown in ribbon (detailed) mode. */
+    conductors?: ViewConductor[];
+    /** Harness region along the route. */
+    run?: ViewHarnessRun;
+    /** Child links are a stored override (remapped by the user). */
+    manual?: boolean;
+    /** Grouped net membership (PB-823): one line from a component to a net, its pins as children. */
+    net?: {
+        id: string;
+        name: string;
+    };
+    diagnostics: string[];
+}
+/**
+ * A functional link UHD derives over a board's nets (an I2C bus, a supply to
+ * a load). It is not drawn as a line of its own: the membership lines it runs
+ * over (`via`) carry its state, and the inspector lists it by name.
+ */
+export interface ViewDerived {
+    /** Derived link id (long: the membership links it runs over), prefixed like stored link ids. */
+    id: string;
+    /** Its name, "I2C0 ↔ I2C": what the viewer shows instead of the id. */
+    name: string;
+    protocol: string;
+    state: LinkState;
+    a: {
+        node: string;
+        iface: string;
+    };
+    b: {
+        node: string;
+        iface: string;
+    };
+    /** Net node ids it runs over. */
+    nets: string[];
+    /** View link ids (grouped memberships) it runs over. */
+    via: string[];
+    /** Conductors: each slot (or pin) and the one it is wired to. */
+    children: {
+        a: string;
+        aPin?: string;
+        b: string;
+        bPin?: string;
+    }[];
+    diagnostics: string[];
+}
+export interface ViewModel {
+    /** Breadcrumb labels for the level being viewed. */
+    path: {
+        id: string;
+        label: string;
+    }[];
+    nodes: ViewNode[];
+    links: ViewLink[];
+    /** Functional links derived over the level's nets (and nets of modules expanded in place). */
+    derived: ViewDerived[];
+}

package/dist/components/types/uhd-viewer/src/options.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How a host's option changes apply (ViewerHandle.update). Kept apart from
+ * mount.tsx so it can be tested without a page.
+ */
+import type { ViewerLayout, ViewerOptions, ViewerViewport } from "./api";
+/**
+ * The options after `update(change)`: the change is merged into the current
+ * options. A change that names `bundleUrl` and not `bundle` switches to
+ * loading from that URL (a given `bundle` would otherwise keep precedence).
+ */
+export declare function mergeOptions<T extends ViewerOptions>(current: T, change: Partial<ViewerOptions>): T;
+/** The same layout edits (a host passing back what the viewer sent is not a change). */
+export declare function sameLayout(a: ViewerLayout | undefined, b: ViewerLayout | undefined): boolean;
+/** The same saved viewports, whatever order their levels come in (a host passing back what the viewer sent is not a change). */
+export declare function sameViewports(a: Record<string, ViewerViewport> | undefined, b: Record<string, ViewerViewport> | undefined): boolean;
+/**
+ * What a host's `viewports` option asks of a mounted viewer (PB-1037):
+ * `replace` when the viewer must take them (the host passed viewports it was
+ * not sent, or it took over keeping them, or gave that up), `keep` otherwise.
+ * `known` is what the host has: what it passed last or what it was last sent.
+ */
+export declare function hostViewportsChange(o: {
+    hosted: boolean;
+    wasHosted: boolean;
+    host: Record<string, ViewerViewport> | undefined;
+    known: Record<string, ViewerViewport> | undefined;
+}): "replace" | "keep";

package/dist/components/types/uhd-viewer/src/source/source.d.ts

@@ -0,0 +1,109 @@
+import { type UhdBundle, type UhdBundleDiagnostic } from "@deltarobotics/uhd";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import type { LevelLayout } from "../layout/layout";
+import type { ArtifactResolver, ViewerOptions } from "../api";
+import { type LeftOut, type MissingDefinition } from "./tolerant";
+export interface ViewerScenario {
+    id: string;
+    label: string;
+    description: string;
+    system: ModuleDef;
+    lookup: ModuleLookup;
+    /** Definitions the bundle names and does not hold: drawn as placeholders (source/tolerant.ts). */
+    missing: MissingDefinition[];
+    /** Links and exports that could not be resolved, and are not drawn. */
+    leftOut: LeftOut[];
+}
+/** Surface appearance for a definition (and optionally named sub-bodies of its CAD). */
+export interface Appearance {
+    color?: string;
+    metalness?: number;
+    roughness?: number;
+    opacity?: number;
+    parts?: Record<string, Omit<Appearance, "parts">>;
+}
+export interface LabelHint {
+    title?: string;
+    sub?: string;
+    hide?: boolean;
+}
+/** Presentation hints keyed by instance path. Never topology. */
+export interface DisplayConfig {
+    diagram?: {
+        /** Hand layouts per drill level ("" = top). */
+        layouts?: Record<string, LevelLayout>;
+        /** Instance paths drawn expanded in place by default. */
+        expanded?: string[];
+        /** Links opened (conductors shown) by default. */
+        openLinks?: string[];
+    };
+    spatial?: {
+        /** Instance path the assembly is placed from (default: the best-connected structure). */
+        root?: string;
+        /** Explicit placements for modules no mate reaches (row-major 4×4, root coordinates). */
+        placements?: Record<string, {
+            matrix: number[];
+            note?: string;
+        }>;
+        labels?: {
+            modules?: Record<string, LabelHint>;
+            /** Fastener harnesses and routed wire harnesses, by instance path. */
+            harnesses?: Record<string, LabelHint>;
+        };
+        /** By definition id. */
+        appearance?: Record<string, Appearance>;
+        /** How the 3D view opens (PB-873). */
+        view?: SpatialView;
+    };
+}
+/**
+ * The 3D view's opening camera, in the root's coordinates. Presentation only:
+ * a watch modelled display-down (its case's frame has the display at −z)
+ * says `up: [0, 0, -1]` and opens display-up, without changing the model.
+ */
+export interface SpatialView {
+    /** The direction drawn up (default [0, 0, 1]): the camera's up, the orbit axis and the ground grid follow it. */
+    up?: [number, number, number];
+    /** A saved camera: azimuth and elevation (degrees, about `up`), distance (mm) and target. Without a distance the model is fitted. */
+    camera?: {
+        azimuth?: number;
+        elevation?: number;
+        distance?: number;
+        target?: [number, number, number];
+    };
+}
+export interface LoadedSource {
+    name: string;
+    bundleUrl: string;
+    scenarios: ViewerScenario[];
+    /** URL for a definition's artifact file path, or undefined if it cannot be resolved. */
+    resolveArtifact: ArtifactResolver;
+    /** Findings from the bundle's producer (e.g. Protoboard's aggregated check). */
+    hostDiagnostics: UhdBundleDiagnostic[];
+    display: DisplayConfig;
+    /** The bundle as loaded (for host views that read more of it than the viewer draws). */
+    bundle: UhdBundle;
+}
+export interface SourceOptions {
+    /** Development only: absolute filesystem bases are served through Vite's /@fs route. */
+    fsRoute?: boolean;
+    /** A host's resolver; it receives the default one as `fallback`. */
+    resolveArtifact?: ViewerOptions["resolveArtifact"];
+}
+/**
+ * The bundle URL for the standalone app: `?bundle=<url>`, then the URL a
+ * server injected into the page, then the development default (none in a
+ * production build).
+ */
+export declare function pickBundleUrl(search: string, injected?: string | null, fallback?: string | null): string | undefined;
+/**
+ * URL prefix for an artifact base (`UhdBundle.artifactBases`: an absolute
+ * path or a URL prefix), or undefined when it cannot be fetched over HTTP.
+ * Absolute filesystem paths only resolve in development, through /@fs.
+ */
+export declare function baseToUrl(base: string, options?: Pick<SourceOptions, "fsRoute">): string | undefined;
+/** The default resolver: a definition's artifact base, or the bundle's own location. */
+export declare function bundleResolver(bundle: UhdBundle, bundleUrl: string, options?: Pick<SourceOptions, "fsRoute">): ArtifactResolver;
+export declare function loadBundle(url: string, options?: SourceOptions): Promise<LoadedSource>;
+export declare function sourceFromBundle(bundle: UhdBundle, url: string, options?: SourceOptions): LoadedSource;

package/dist/components/types/uhd-viewer/src/source/tolerant.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A bundle that does not hold everything it names still draws.
+ *
+ * UHD's resolvers throw on a child whose definition is not in the bundle, and
+ * on a link or an export that names an interface nobody has. A producer that
+ * could not fetch some definitions (a library that was unreachable) writes
+ * exactly such a bundle, and the viewer drew nothing at all for it.
+ *
+ * `tolerantSystem` gives the viewer a system the resolvers accept: a missing
+ * definition is stood in for by a placeholder that has the interfaces its
+ * parents' links and exports name, and a link or an export that still cannot
+ * be resolved is left out. What was stood in for and what was left out is
+ * returned, so the views can say so.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { type ModuleLookup } from "@deltarobotics/uhd";
+/** A definition the bundle names and does not hold. */
+export interface MissingDefinition {
+    /** The definition id the children name. */
+    id: string;
+    /** Where it is used: the parent definition and the child's id and label there. */
+    usedBy: {
+        parent: string;
+        child: string;
+        name?: string;
+    }[];
+}
+/** A link or an export left out because it could not be resolved. */
+export interface LeftOut {
+    kind: "link" | "export";
+    /** The definition it was on. */
+    on: string;
+    id: string;
+    /** The resolver's message. */
+    why: string;
+}
+export interface TolerantSystem {
+    root: ModuleDef;
+    lookup: ModuleLookup;
+    missing: MissingDefinition[];
+    leftOut: LeftOut[];
+}
+/** Whether a definition is a placeholder for one the bundle does not hold. */
+export declare function isPlaceholder(def: ModuleDef | undefined): boolean;
+export declare function tolerantSystem(root: ModuleDef, lookup: ModuleLookup): TolerantSystem;

package/dist/components/types/uhd-viewer/src/theme/ThemeProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Puts a theme on the viewer's root element and tells the components that
+ * draw outside CSS (the 3D scene) when it changes. Everything rendered inside
+ * reads the tokens as CSS variables; popovers portal into the same root so
+ * they keep them.
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import { type Theme, type ThemeToken } from "./tokens";
+import { type ThemeAdapter } from "./adapters";
+export interface ThemeState {
+    theme: Theme;
+    /** The themed element: tooltips and menus portal here so they keep the tokens. */
+    root: HTMLElement | null;
+}
+/** The current theme and the themed root element. */
+export declare const useTheme: () => ThemeState;
+export interface ThemeProviderProps {
+    /** Where the theme comes from (default: the viewer's own, following the system). */
+    adapter?: ThemeAdapter;
+    /** Or one theme (wins over `adapter`). */
+    theme?: Theme;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/** The themed root: a full-size element carrying the tokens. */
+export declare function ThemeProvider({ adapter, theme: fixed, className, style, children }: ThemeProviderProps): import("react").JSX.Element;
+/**
+ * A token's colour as `#rrggbb` (alpha dropped), resolved on `element`:
+ * for canvases that cannot read CSS variables or modern colour syntax
+ * (`oklch()`, `color-mix()`), like the 3D scene's background and grid.
+ */
+export declare function tokenColor(element: Element | null, name: ThemeToken, fallback?: string): string;

package/dist/components/types/uhd-viewer/src/theme/adapters.d.ts

@@ -0,0 +1,28 @@
+import { type Theme, type ThemeScheme } from "./tokens";
+export interface ThemeAdapter {
+    id: string;
+    /** The theme to show now. */
+    current(): Theme;
+    /** Calls `onChange` whenever the theme changes; returns the unsubscribe. Absent: the theme never changes. */
+    subscribe?(onChange: (theme: Theme) => void): () => void;
+}
+/** One fixed theme. */
+export declare const staticTheme: (theme: Theme) => ThemeAdapter;
+/** Several adapters' worth of themes, picked by id (a host's theme switcher). */
+export declare function pickTheme(themes: readonly Theme[], id: string | null | undefined, fallback: Theme): Theme;
+/** The viewer's own themes: dark, light, or the system's preference (default). */
+export declare function defaultThemeAdapter(scheme?: "dark" | "light" | "system", win?: Window | undefined): ThemeAdapter;
+/** The scheme of a VS Code webview, from the class VS Code puts on its body. */
+export declare function vscodeScheme(body: {
+    classList: {
+        contains(c: string): boolean;
+    };
+} | undefined): ThemeScheme;
+/** The VS Code tokens for one scheme. */
+export declare function vscodeTheme(scheme: ThemeScheme): Theme;
+/**
+ * Follows the VS Code colour theme of the webview the viewer runs in: the
+ * tokens refer to VS Code's variables, so a colour change inside a scheme
+ * needs nothing; a change of scheme (VS Code swaps its body class) re-themes.
+ */
+export declare function vscodeThemeAdapter(doc?: Document | undefined): ThemeAdapter;

package/dist/components/types/uhd-viewer/src/theme/resolve.d.ts

@@ -0,0 +1,19 @@
+/** A host's `theme` option (api.ts) as a theme adapter. */
+import type { ViewerThemeOption } from "../api";
+import { type ThemeAdapter } from "./adapters";
+import { type Theme } from "./tokens";
+/** A theme given with some tokens: the rest from the default of its scheme. */
+export declare function completeTheme(theme: {
+    id: string;
+    label: string;
+    scheme: Theme["scheme"];
+    tokens: Partial<Record<string, string>>;
+}): Theme;
+/**
+ * - absent or `"dark"` / `"light"`: the viewer's own dark (as it has always
+ *   looked) or light theme; `"system"`: whichever the system prefers;
+ * - `"vscode"`: the VS Code adapter (in a VS Code webview);
+ * - a theme object: that theme (missing tokens from the default);
+ * - an adapter (`{ current, subscribe? }`): the host's own.
+ */
+export declare function resolveTheme(option: ViewerThemeOption | undefined): ThemeAdapter;

package/dist/components/types/uhd-viewer/src/theme/themes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The viewer's own themes: neutral dark and light. They carry no brand; a
+ * host's brand theme starts from one of these (`defineTheme`) and changes the
+ * accent, surfaces or faces it needs.
+ */
+import { type Theme } from "./tokens";
+/** DRC health and finding severity read the same in every theme (owner decision, PB-894 §5). */
+export declare const DRC_TOKENS: {
+    drcConfigured: string;
+    drcPartial: string;
+    drcIncompatible: string;
+    drcUnconfigured: string;
+    severityError: string;
+    severityWarning: string;
+    severityInfo: string;
+    severityOk: string;
+};
+/** Domain and signal colours on dark surfaces. */
+export declare const DARK_DATA_TOKENS: {
+    domainElectrical: string;
+    domainMechanical: string;
+    domainPneumatic: string;
+    domainHydraulic: string;
+    domainThermal: string;
+    domainNetwork: string;
+    domainSoftware: string;
+    domainOther: string;
+    signalPower: string;
+    signalGround: string;
+    signalDigital: string;
+    signalAnalog: string;
+    signalI2c: string;
+    signalSpi: string;
+    signalUart: string;
+    signalCan: string;
+    signalPwm: string;
+    signalPhase: string;
+    signalRf: string;
+    signalOther: string;
+};
+/** The same on light surfaces: one step darker, so thin lines keep their contrast. */
+export declare const LIGHT_DATA_TOKENS: {
+    domainElectrical: string;
+    domainMechanical: string;
+    domainPneumatic: string;
+    domainHydraulic: string;
+    domainThermal: string;
+    domainNetwork: string;
+    domainSoftware: string;
+    domainOther: string;
+    signalPower: string;
+    signalGround: string;
+    signalDigital: string;
+    signalAnalog: string;
+    signalI2c: string;
+    signalSpi: string;
+    signalUart: string;
+    signalCan: string;
+    signalPwm: string;
+    signalPhase: string;
+    signalRf: string;
+    signalOther: string;
+};
+export declare const defaultDark: Theme;
+export declare const defaultLight: Theme;
+/** The theme a scheme falls back to. */
+export declare const defaultTheme: (scheme?: "dark" | "light") => Theme;