@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,81 @@
+/**
+ * The inspector's details for one thing of a bundle, without a viewer around
+ * it: what `ViewerInspector` shows for a selected module, link or net, for a
+ * host that has an inspector of its own (a native side view) and selects by
+ * path. The same components draw both, so a host's inspector and the
+ * viewer's show a module the same way.
+ *
+ *   <ThemeProvider adapter={vscodeThemeAdapter()}>
+ *     <SelectionDetails bundle={bundle} target={{ kind: "module", path: "stack/esc" }} host={{ openArtifact }} />
+ *   </ThemeProvider>
+ *
+ * The level that holds the target is modelled as the viewer models it (its
+ * links, nets and checks), but nothing is laid out or drawn.
+ */
+import { type ReactNode } from "react";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { UhdBundle } from "@deltarobotics/uhd";
+import type { ArtifactResolver } from "../api";
+import { type HostActions } from "../host/context";
+import type { Classification } from "../model/classification";
+import { type HostFinding } from "../model/slots";
+/** An interface card's request to its host: the module's path, the interface, and the links that end on it as their module declares them. */
+export interface InterfaceRequest {
+    /** The module's instance path from the root. */
+    path: string;
+    interfaceId: string;
+    /** The module that declares the links (the level's), from the root. */
+    owner: string;
+    /** Its stored links by their local ids ("rx_fc_pads"). */
+    links: string[];
+}
+/** What to show: a module instance by its path from the root (`""`: the root), a link on the level of its owner, or a definition on its own. */
+export type DetailsTarget = {
+    kind: "module";
+    path: string;
+} | {
+    kind: "link";
+    owner: string;
+    ids: string[];
+} | {
+    kind: "definition";
+    id: string;
+};
+export interface SelectionDetailsProps {
+    /** The bundle the target is in. Not given: only `definition` targets among `definitions` can be shown. */
+    bundle?: UhdBundle;
+    /** Definitions outside the bundle (a library part shown on its own), by their ids. */
+    definitions?: ModuleDef[];
+    target: DetailsTarget;
+    /** URL of a definition's artifact file; not given, files do not resolve (their cards show icons). */
+    resolveArtifact?: ArtifactResolver;
+    /** What the host takes over, and how artifacts are shown (host/context.ts). */
+    host?: HostActions;
+    /** How interface swatches are coloured (default: by domain). */
+    mode?: Classification;
+    /** A board's drawings with pan and zoom, as in the viewer (default false: the drawings are cards, nothing is fetched). */
+    boardDrawings?: boolean;
+    /** The user picked something else in the details (an end of a link, a net's member, a functional link): canonical ids from the root. */
+    onSelect?: (selection: {
+        kind: "node" | "link";
+        id: string;
+    }) => void;
+    /** The user asked for the pair view of the link shown. */
+    onPair?: (request: {
+        linkId: string;
+        a: string;
+        b: string;
+    }) => void;
+    /** Shown when the target is not in the bundle. */
+    missing?: ReactNode;
+    /** The host's findings for the interface cards (with the keys its Locate takes); not given, the viewer's own checks. */
+    findings?: HostFinding[];
+    /** A finding's Locate on an interface card. */
+    onFinding?: (key: string) => void;
+    /** An interface card's Open in source: the line of its link, else of the interface. */
+    onInterfaceSource?: (request: InterfaceRequest) => void;
+    /** An open slot's Connect…. */
+    onConnect?: (request: InterfaceRequest) => void;
+    className?: string;
+}
+export declare function SelectionDetails({ bundle, definitions, target, resolveArtifact, host, mode, boardDrawings, onSelect, onPair, missing, className, findings, onFinding, onInterfaceSource, onConnect }: SelectionDetailsProps): import("react").JSX.Element;

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

@@ -0,0 +1,82 @@
+import { type HierarchyNode, type HierarchyPanelState } from "../model/hierarchy";
+/** What a host asks of the panel: show a module's row, put the keyboard in the filter, open or fold it. */
+export interface HierarchyCommand {
+    type: "reveal" | "filter" | "open" | "close" | "toggle";
+    /** For `reveal`: the module's instance path. */
+    path?: string;
+    /** A new number for every command (the same command twice is two). */
+    seq: number;
+}
+export interface ViewerHierarchyProps {
+    /** What the host kept for this tab (`onStateChange` gave it); anything malformed is ignored. */
+    state?: unknown;
+    /** The panel's state changed (open, width, open rows): a host keeps it per tab. */
+    onStateChange?: (state: HierarchyPanelState) => void;
+    /** The panel opened or folded (at once). */
+    onOpenChange?: (open: boolean) => void;
+    command?: HierarchyCommand;
+    /** Attributes a host puts on every row (`data-*`), e.g. for its own context menu. */
+    rowAttributes?: (node: HierarchyNode) => Record<`data-${string}`, string>;
+    /** Show the panel's own context menu (default). A host with a menu of its own passes false: a right-click then only selects the row. */
+    ownMenu?: boolean;
+    /** Below this width of the window the panel starts folded when nothing was kept (default 640). */
+    narrow?: number;
+    className?: string;
+}
+/** What the folded panel keeps of the view's width: nothing (its button to open it again floats over the view). */
+export declare const RAIL_WIDTH = 0;
+/** The gap between the floating card and the view's edges, the host's header above it and the canvas beside it (px). */
+export declare const CARD_GAP = 4;
+/** How long the card takes to open or fold (ms); none when the system asks for reduced motion. */
+export declare const FOLD_MS = 200;
+/**
+ * The panel's look, in one place (PB-1042, PB-1070): a floating card like the
+ * host's header, 4 px from the view's edges and below the header, with the
+ * panel radius, a border all round and the panel shadow; rows highlighted in
+ * the theme's selection colour. Only the viewer's tokens, so a host's theme
+ * decides the colours (orange only under the Protoboard theme). Swap these to
+ * restyle it.
+ */
+export declare const HIERARCHY_LOOK: {
+    readonly dock: "uhd-hierarchy-dock absolute bottom-1 left-1 z-30 flex flex-col top-[calc(var(--uhd-inset-top,0px)+4px)] transition-[transform,opacity] duration-200 ease-out motion-reduce:transition-none";
+    /** The dock while it opens or folds (and while folded): slid out to the left, faded. */
+    readonly dockAway: "pointer-events-none -translate-x-[calc(100%+8px)] opacity-0";
+    readonly panel: "relative flex min-h-0 flex-1 flex-col overflow-hidden rounded-panel border border-line bg-surface font-ui text-fg shadow-panel outline outline-1 -outline-offset-1 outline-contrast";
+    /**
+     * The folded panel: the icon alone, floating over the canvas at the card's
+     * corner (no border, face or shadow of its own), that opens it again. On
+     * hover it takes a soft rounded fill with a faint glow, in the theme's
+     * toolbar hover colour (high contrast: a dashed outline instead). It fades
+     * in as the card leaves and out as it comes.
+     */
+    readonly folded: "uhd-hierarchy-reopen absolute left-1 z-30 top-[calc(var(--uhd-inset-top,0px)+4px)] grid size-8 cursor-pointer place-items-center rounded-md border-0 bg-transparent p-0 text-fg-muted transition-[opacity,background-color,color,box-shadow] duration-200 ease-out motion-reduce:transition-none hover:bg-hover hover:text-fg hover:shadow-[0_0_10px_1px_var(--uhd-hover)] hover:outline hover:outline-1 hover:outline-dashed hover:-outline-offset-1 hover:outline-contrast-active focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus";
+    /** The button while it fades in or out (and while the panel is open). */
+    readonly foldedAway: "pointer-events-none opacity-0";
+    readonly header: "flex h-8 shrink-0 items-center gap-0.5 pr-1 pl-3";
+    readonly title: "min-w-0 flex-1 truncate font-label text-[11px] tracking-[0.08em] text-fg-muted uppercase";
+    readonly filterBox: "mx-2 mb-1.5 flex h-7 shrink-0 items-center gap-1.5 rounded-md border border-line bg-sunken px-2 focus-within:outline focus-within:outline-1 focus-within:-outline-offset-1 focus-within:outline-focus";
+    readonly row: "uhd-tree-row group relative flex h-[26px] cursor-pointer items-center gap-1.5 pr-3 text-[12.5px] leading-none outline-none select-none";
+    readonly rowSelected: "bg-selection text-selection-fg outline outline-1 -outline-offset-1 outline-focus";
+    readonly rowIdle: "text-fg hover:bg-hover";
+    /** Filtering: a row that only leads to what matches. */
+    readonly rowDim: "text-fg-faint hover:bg-hover hover:text-fg";
+    readonly rowFocus: "focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus";
+    readonly groupRow: "mt-1 border-t border-line-subtle text-fg-muted";
+    readonly badge: "shrink-0 rounded border border-line px-1.5 font-code text-[10px] leading-[16px] text-fg-muted";
+    readonly legend: "flex shrink-0 flex-wrap items-center gap-x-3 gap-y-1 border-t border-line-subtle px-3 py-1.5 text-[10.5px] text-fg-muted";
+};
+/** The panel, docked at the left of the view: render it beside the shell's `.workspace` (its sibling, before it), which then starts after it. */
+export declare function ViewerHierarchy({ state: given, onStateChange, onOpenChange, command, rowAttributes, ownMenu, narrow, className }: ViewerHierarchyProps): import("react").JSX.Element;
+/**
+ * A toolbar button that opens and folds the panel from a host's header.
+ *
+ * @deprecated The panel has its own fold button and, folded, its own button to
+ * open it again (PB-1070); a host needs no toggle of its own. Kept for hosts
+ * written against 0.2.0; it will be removed in a later minor release.
+ */
+export declare function HierarchyToggle({ open, onClick, disabled, className }: {
+    open: boolean;
+    onClick: () => void;
+    disabled?: boolean;
+    className?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+/**
+ * Renders a viewer shell into an element: the standalone app (app/main.tsx,
+ * lib.tsx's mountViewer) or a host's own shell built from the library's views
+ * (`renderViewer(el, options, Shell)`). The handle carries the host channel:
+ * its methods send host messages, events go to the options' callbacks and,
+ * with `parentWindow`, to the parent window. The shell receives the options
+ * and the channel (`host`) as props and passes them to `UhdViewer`.
+ */
+import { type ComponentType } from "react";
+import type { AppProps } from "./controller";
+import type { ViewerHandle } from "../api";
+export declare function renderViewer<P extends AppProps>(element: HTMLElement, props: P, Shell: ComponentType<P>): ViewerHandle;

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

@@ -0,0 +1,187 @@
+/**
+ * The library's views of a loaded model, each reading the viewer's state
+ * (`useViewer`): the diagram canvas with its toolbar and legend, the 3D
+ * scene, the inspector panels and a module's context menu. Shells place them;
+ * none of them is app chrome.
+ */
+import { type ReactNode } from "react";
+export interface DiagramCanvasProps {
+    /** Draw the floating toolbar (fit, zoom, reset layout). Default true. */
+    toolbar?: boolean;
+    /** Draw the classification's legend. Default true. */
+    legend?: boolean;
+    /** A panel floats over the canvas's right side: fitting leaves room for it. Default: the inspector panel is open. */
+    coveredRight?: boolean;
+    /** What the shell adds to the notice about definitions the bundle does not hold (how its producer gets them). */
+    missingHint?: ReactNode;
+    /**
+     * What a level with no modules offers: a dashed box with a plus and this
+     * label, a button (the shell's way to add one, such as its parts library).
+     * Without it the empty level only says so.
+     */
+    emptyAction?: {
+        label: string;
+        onClick: () => void;
+    };
+    className?: string;
+}
+/** The diagram of the current level: modules, interfaces, links and harnesses. */
+export declare function DiagramCanvas({ toolbar, legend, coveredRight, missingHint, emptyAction, className }: DiagramCanvasProps): import("react").JSX.Element;
+/** The scenario being shown, when it is not the nominal build. */
+export declare function ScenarioBanner(): import("react").JSX.Element | null;
+/**
+ * Definitions the bundle names and does not hold (source/tolerant.ts): they are
+ * drawn as placeholders, and this says which. It can be put away; a bundle
+ * that lacks something else brings it back.
+ */
+export declare function MissingNotice({ hint, className }: {
+    hint?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** The diagram's view controls as icon toggles (each with a tooltip). */
+export declare const CLASSIFICATION_OPTIONS: readonly [{
+    readonly id: "domain";
+    readonly icon: "layers";
+    readonly label: "Colour by domain";
+}, {
+    readonly id: "drc";
+    readonly icon: "shield-check";
+    readonly label: "Colour by DRC health";
+}, {
+    readonly id: "signal";
+    readonly icon: "activity";
+    readonly label: "Colour by signal type";
+}];
+export declare const DETAIL_OPTIONS: readonly [{
+    readonly id: "bundled";
+    readonly icon: "minus";
+    readonly label: "One line per link";
+}, {
+    readonly id: "conductors";
+    readonly icon: "rows-3";
+    readonly label: "Every conductor";
+}];
+/**
+ * The pointer's tool: select (a drag on the empty canvas draws a selection
+ * box) or pan (a drag moves the view). For a shell's own toolbar.
+ */
+export declare function ToolToggle({ tooltipSide, size }: {
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+    size?: "sm" | "md";
+}): import("react").JSX.Element;
+/** Fit and zoom, as the canvas does them (a fit asked for here is also what the level opens on next time). */
+export declare function ViewButtons({ tooltipSide }: {
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+}): import("react").JSX.Element;
+/**
+ * The diagram's controls (classification, detail, grounds; `controls={false}` leaves them out), then fit, zoom and reset.
+ * When the legend has no room beside it, it starts with the legend's button (`legend`: what that opens; default the
+ * viewer's legend).
+ */
+export declare function DiagramToolbar({ coveredRight, className, controls, legend }: {
+    coveredRight?: boolean;
+    className?: string;
+    controls?: boolean;
+    legend?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The entries of the current classification's legend, as buttons: a click
+ * isolates one (its links stay, with the interfaces and modules they touch;
+ * the rest of the level fades), a click on it again shows everything, a
+ * click on another switches, and Shift, Ctrl or Cmd holds several. Each
+ * reads as its name and, under it, what it stands for. For a shell that
+ * draws its own legend card.
+ */
+export declare function DiagramLegendItems({ compact, columns }?: {
+    compact?: boolean;
+    columns?: number;
+}): import("react").JSX.Element;
+/** The way back from an isolated legend entry to everything (shown only while something is isolated). */
+export declare function IsolationClear({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * The legend's fold button, at the right of its header: the legend becomes a
+ * tab at the right edge. Nothing where the legend does not fold (the
+ * toolbar's popover).
+ */
+export declare function LegendFold({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * What the legend shows in a form: `full` the title and the entries with their
+ * names and meanings; `compact` the classification's icon and the swatches
+ * alone (each named by its label).
+ */
+export declare function DiagramLegendBody({ form }: {
+    form: "full" | "compact";
+}): import("react").JSX.Element;
+/** What the link colours mean in the current classification; a click on an entry isolates it. It gives way to the toolbar as the canvas narrows (`FittedLegend`). */
+export declare function DiagramLegend({ className, coveredRight }: {
+    className?: string;
+    coveredRight?: boolean;
+}): import("react").JSX.Element;
+export interface FittedLegendProps {
+    label: string;
+    /** Draws a form of the card. `LegendFold` inside it folds the legend. */
+    render: (form: "full" | "compact") => ReactNode;
+    className?: string;
+    /** Open (the card) or folded (the tab at the right edge). Given: the shell keeps it, with `onOpenChange`; else the legend does, from `defaultOpen`. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Where an uncontrolled legend starts. Default open. */
+    defaultOpen?: boolean;
+    /** A panel floats over the canvas's right side (an inspector): the legend sits left of it. */
+    coveredRight?: boolean;
+}
+/**
+ * A legend card at the canvas's bottom right that stays there and gives way
+ * to the bottom toolbar (ui/legendFit.ts): the full form while it fits beside
+ * the toolbar, then the compact one, and at its smallest none, the toolbar
+ * then offering it behind a button (`LegendToolbarButton`). Folded, it is a
+ * tab at the right edge with a dot per colour, which opens it; a canvas
+ * shorter than `LEGEND_SHORT` folds it until the user opens it there. It
+ * measures the room it has (a `ResizeObserver` on the canvas, the toolbar and
+ * every form) from hidden copies of the forms, so it never overlaps the
+ * toolbar. `render` draws a form; the card is a sibling of the toolbar
+ * (`.toolbar`).
+ */
+export declare function FittedLegend({ label, render, className, open: given, onOpenChange, defaultOpen, coveredRight }: FittedLegendProps): import("react").JSX.Element;
+/**
+ * The legend's button in the toolbar, shown only when the legend has no room
+ * beside it (`FittedLegend`): it opens the legend (`children`) as a popover
+ * above the toolbar. Escape, a click elsewhere or the button closes it, and
+ * the keyboard goes back to the button.
+ */
+export declare function LegendToolbarButton({ children, label }: {
+    children: ReactNode;
+    label?: string;
+}): import("react").JSX.Element | null;
+export interface Scene3DProps {
+    /** Show the 3D view's own inspector card. Default: the inspector panel is open. */
+    inspector?: boolean;
+    /**
+     * The module to show, by instance path from the root. Default: the level
+     * the viewer is on (`drill`), so the root shows the whole assembly and a
+     * module shows that module alone. A shell whose tab is on a module with no
+     * level of its own (a part) passes that module's path.
+     */
+    scope?: string[];
+    /** What the shell adds where a module has nothing to draw (how its 3D model is made). */
+    emptyHint?: ReactNode;
+}
+/**
+ * The 3D model of what is being viewed: the whole assembly at the root, one
+ * module alone (in its own coordinates) on that module's level. With its own
+ * toolbar and (optionally) its inspector.
+ */
+export declare function Scene3D({ inspector, scope, emptyHint }: Scene3DProps): import("react").JSX.Element;
+/**
+ * The inspector of the current level: the selected module or link, else the
+ * hierarchy or the system checks (`panel`). Hidden while no panel is open.
+ */
+export declare function ViewerInspector({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/** A module's context menu, where the pointer opened it. */
+export declare function ViewerNodeMenu(): import("react").JSX.Element | null;

package/dist/headless/index.d.ts

@@ -0,0 +1,71 @@
+import type { UhdBundle } from "@deltarobotics/uhd";
+import type { LinkLayout } from "../lib/api.js";
+
+export interface Box { x: number; y: number; w: number; h: number }
+/** One level of `diagram.layouts` in the display file. */
+export interface LevelLayout {
+  nodes: Record<string, { x?: number; y?: number; w?: number; h?: number }>;
+  ports?: Record<string, "left" | "right" | "top" | "bottom">;
+  links?: Record<string, LinkLayout>;
+}
+/** A level layout with the nodes the layout step must not move (the viewer ignores the list). */
+export type PinnedLevelLayout = LevelLayout & { pinned?: string[] };
+export interface LayoutMetrics {
+  cards: number;
+  boundary: number;
+  links: number;
+  crossings: number;
+  overlaps: number;
+  aspect: number;
+  width: number;
+  height: number;
+  strip: number;
+  stripAxis: "row" | "column";
+  stripCards: string[];
+  underCards: number;
+  length: number;
+  detail: { overlaps: [string, string][]; underCards: { link: string; card: string }[] };
+}
+export interface LayoutFinding {
+  severity: "warning" | "info";
+  code: "strip" | "crossings" | "overlaps" | "under-cards" | "aspect";
+  message: string;
+}
+export interface LayoutLimits {
+  strip: (cards: number) => number;
+  crossings: (links: number) => number;
+  aspect: [number, number];
+}
+export declare const LAYOUT_LIMITS: LayoutLimits;
+export declare function layoutFindings(m: LayoutMetrics, limits?: LayoutLimits): LayoutFinding[];
+export interface DiagramLevel { level: string; label: string; board: boolean }
+export declare function diagramLevels(bundle: UhdBundle, maxDepth?: number): DiagramLevel[];
+export interface LevelOptions {
+  layout?: LevelLayout | null;
+  expanded?: string[];
+  legacy?: boolean;
+}
+export interface MeasuredLevel {
+  level: string;
+  saved: boolean;
+  metrics: LayoutMetrics;
+  findings: LayoutFinding[];
+  /** What the viewer draws (internal shapes: read `layout.boxes` and `layout.routes` only). */
+  view: { nodes: { id: string; label: string; parent?: string; kind: string }[] };
+  layout: { boxes: Record<string, Box>; routes: Record<string, [number, number][]> };
+}
+export declare function measureLevel(bundle: UhdBundle, level: string, opts?: LevelOptions): MeasuredLevel;
+export interface ProposeOptions extends LevelOptions {
+  mode?: "default" | "tidy";
+  pinned?: string[];
+}
+export interface Proposal {
+  level: string;
+  before: MeasuredLevel;
+  after: MeasuredLevel;
+  layout: PinnedLevelLayout;
+  better: boolean;
+}
+export declare function proposeLevel(bundle: UhdBundle, level: string, opts?: ProposeOptions): Proposal;
+export declare function reads(m: LayoutMetrics): number;
+export declare function readsBetter(a: LayoutMetrics, b: LayoutMetrics): boolean;