@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.0

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;

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

@@ -0,0 +1,175 @@
+/**
+ * The viewer's theme-token contract: every colour, surface, shadow and face
+ * the viewer draws with is one of these semantic tokens, read as a CSS
+ * variable (`--uhd-<kebab-name>`). Nothing in the viewer's styles names a raw
+ * colour; a host restyles the viewer by giving these tokens values (a theme),
+ * never by overriding class rules.
+ *
+ * A theme is plain data (`Theme`). Values may be any CSS value, including
+ * `var(...)` references to the host's own variables (the VS Code adapter maps
+ * every token onto `--vscode-*`) and `color-mix(...)` of other tokens.
+ *
+ * Nothing here names a host product: hosts bring their own themes through
+ * `defineTheme` (or a `ThemeAdapter`, ./adapters.ts).
+ */
+/** Every token, grouped as the contract documents them. */
+export interface ThemeTokens {
+    /** The page behind everything (the app shell). */
+    background: string;
+    /** The diagram canvas. */
+    canvas: string;
+    /** The canvas's dot grid. */
+    canvasDot: string;
+    /** Panels and floating cards (inspector, legend, toolbars). */
+    surface: string;
+    /** Popovers, menus and tooltips above a surface. */
+    surfaceRaised: string;
+    /** Wells inside a surface: inputs, code, table bands, drawing frames. */
+    surfaceSunken: string;
+    /** Floating chrome laid over the canvas (translucent surface). */
+    overlay: string;
+    /** Behind a modal view (dims the canvas). */
+    scrim: string;
+    /** Muted fill (chips, progress tracks). */
+    muted: string;
+    /** Hover fill on a control or row. */
+    hover: string;
+    /** Pressed / active fill on a control. */
+    active: string;
+    /** A module card on the canvas. */
+    node: string;
+    /** A selected module card. */
+    nodeSelected: string;
+    /** A group container's fill. */
+    group: string;
+    /** Behind artifact image previews (most part drawings are made for paper). */
+    preview: string;
+    /** Behind board drawings (PCB layers). */
+    drawing: string;
+    text: string;
+    textMuted: string;
+    textFaint: string;
+    /** Text on an accent fill. */
+    textOnAccent: string;
+    /** A link-like text button. */
+    textLink: string;
+    border: string;
+    borderSubtle: string;
+    borderStrong: string;
+    /** A module card's outline. */
+    nodeBorder: string;
+    /** A module card's outline under the pointer. */
+    nodeBorderHover: string;
+    /** A group container's dashed outline. */
+    groupBorder: string;
+    /** Extra outline drawn around every control in a high-contrast theme (transparent otherwise). */
+    contrastBorder: string;
+    /** Outline of the active / selected control in a high-contrast theme (transparent otherwise). */
+    contrastActiveBorder: string;
+    /** The one accent: selection, active toggles, the focused link. */
+    accent: string;
+    accentHover: string;
+    /** A light wash of the accent (an active tab, a selected row). */
+    accentTint: string;
+    /** The accent's glow around a selected card. */
+    accentGlow: string;
+    /** A second highlight, distinct from the accent (a counterpart, an interface). */
+    highlight: string;
+    /** Keyboard focus outline. */
+    focusRing: string;
+    /** A selected row's or item's fill. */
+    selection: string;
+    /** Text on a selected row. */
+    selectionText: string;
+    domainElectrical: string;
+    domainMechanical: string;
+    domainPneumatic: string;
+    domainHydraulic: string;
+    domainThermal: string;
+    domainNetwork: string;
+    domainSoftware: string;
+    /** Items outside the classification's focus (signal mode's other domains). */
+    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;
+    drcConfigured: string;
+    drcPartial: string;
+    drcIncompatible: string;
+    drcUnconfigured: string;
+    severityError: string;
+    severityWarning: string;
+    severityInfo: string;
+    severityOk: string;
+    scrollbarThumb: string;
+    scrollbarThumbHover: string;
+    sceneBackground: string;
+    sceneGrid: string;
+    sceneGridMinor: string;
+    radius: string;
+    shadowSm: string;
+    shadowMd: string;
+    shadowLg: string;
+    /** Interface text (labels, buttons, values). */
+    fontUi: string;
+    /** Display face for headings and card titles. */
+    fontLabel: string;
+    /** Code, ids and numbers. */
+    fontMono: string;
+}
+export type ThemeToken = keyof ThemeTokens;
+/** Light or dark surfaces, and whether the host asks for high contrast. */
+export type ThemeScheme = "dark" | "light" | "high-contrast" | "high-contrast-light";
+export interface Theme {
+    /** A stable id (`default-dark`, `vscode`, a host's own). */
+    id: string;
+    /** For people choosing a theme. */
+    label: string;
+    scheme: ThemeScheme;
+    tokens: ThemeTokens;
+}
+/** The CSS variable of a token: `textMuted` → `--uhd-text-muted`. */
+export declare const tokenVar: (token: ThemeToken) => string;
+/** `var(--uhd-…)` for a token, to use in inline styles and SVG attributes. */
+export declare const token: (name: ThemeToken) => string;
+/** Every token name, in contract order (used by tests, adapters and docs). */
+export declare const TOKEN_NAMES: readonly ThemeToken[];
+/** A wash of another token: `mix("accent", 15)` is the accent at 15 % over transparent. */
+export declare const mix: (name: ThemeToken, percent: number, over?: string) => string;
+/**
+ * Tokens that follow from others unless a theme sets them: the accent's tint
+ * and glow, hover and active washes of the text colour, the selection. A
+ * theme that sets only the accent still gets a coherent set.
+ */
+export declare const DERIVED: Partial<ThemeTokens>;
+/**
+ * A complete theme from a base and the tokens that change. Derived tokens
+ * (DERIVED) are recomputed from the result unless `tokens` sets them.
+ */
+export declare function defineTheme(base: Theme, change: {
+    id: string;
+    label: string;
+    scheme?: ThemeScheme;
+    tokens?: Partial<ThemeTokens>;
+}): Theme;
+/** The CSS declarations of a theme (`--uhd-x: value;` …), for a stylesheet or an inline style. */
+export declare function themeDeclarations(theme: Theme): string;
+/** A stylesheet rule applying a theme under `selector`. */
+export declare const themeCss: (theme: Theme, selector?: string) => string;
+/**
+ * Applies a theme to an element: every token as an inline CSS variable, and
+ * `data-uhd-theme` / `data-uhd-scheme` for rules that differ by scheme (high
+ * contrast draws thicker outlines). Returns a function that removes it.
+ */
+export declare function applyTheme(element: HTMLElement, theme: Theme): () => void;
+/** A token's resolved value on an element (for canvases that cannot read CSS: the 3D scene). */
+export declare function readToken(element: Element, name: ThemeToken): string;

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

@@ -0,0 +1,45 @@
+/**
+ * Base inspector primitives: a panel with a header and a scrolling body,
+ * titled sections, key/value rows, badges and status dots. Shells build their
+ * inspectors (and hosts their native-looking side views) from these.
+ */
+import type { ReactNode } from "react";
+export interface InspectorPanelProps {
+    /** The header's title ("Inspector", a module's name). */
+    title?: ReactNode;
+    /** Icon buttons or tabs at the header's right. */
+    actions?: ReactNode;
+    children?: ReactNode;
+    className?: string;
+    /** Classes of the scrolled content. */
+    bodyClassName?: string;
+}
+/** A panel: header, then a body that scrolls with the themed scrollbar. */
+export declare function InspectorPanel({ title, actions, children, className, bodyClassName }: InspectorPanelProps): import("react").JSX.Element;
+export declare function Section({ title, count, actions, children }: {
+    title: ReactNode;
+    count?: number;
+    actions?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** A key and its value on one line (nothing when the value is empty). */
+export declare function PropertyRow({ name, value, mono }: {
+    name: ReactNode;
+    value?: ReactNode;
+    mono?: boolean;
+}): import("react").JSX.Element | null;
+export type Tone = "neutral" | "accent" | "ok" | "warning" | "error" | "info";
+export declare function Badge({ tone, children }: {
+    tone?: Tone;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function StatusDot({ tone, label }: {
+    tone?: Tone;
+    label?: string;
+}): import("react").JSX.Element;
+/** A quiet message where a panel has nothing to show yet. */
+export declare function EmptyState({ icon, title, children }: {
+    icon?: ReactNode;
+    title: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,40 @@
+/**
+ * Legend primitives: a floating card with a title and swatches. A swatch is
+ * a short line (links) or a dot (states). An item given `onSelect` is a
+ * button: the legend then isolates what it stands for. A compact item is
+ * its swatch alone, named by its label (`LegendSwatches` lays them out).
+ */
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+export interface LegendProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    title?: ReactNode;
+    ref?: Ref<HTMLDivElement>;
+    /** As narrow as its content (a compact legend of swatches); else at least 150 px. */
+    compact?: boolean;
+}
+export declare function Legend({ title, children, className, compact, ...rest }: LegendProps): import("react").JSX.Element;
+export interface LegendItemProps {
+    color: string;
+    label: ReactNode;
+    shape?: "line" | "dot" | "dash";
+    /** Given: the item is a button. `add` says a modifier key was held (add to, or take from, the ones held). */
+    onSelect?: (add: boolean) => void;
+    /** The item is the one (or one of those) isolated. */
+    pressed?: boolean;
+    /** Another item is isolated: this one steps back. */
+    dimmed?: boolean;
+    /** Nothing here is of this kind: the button is disabled and says so. */
+    absent?: boolean;
+    /** The button's tooltip. */
+    hint?: string;
+    /** A second line of the tooltip (how to hold several). */
+    hintShortcut?: string;
+    /** The swatch alone (a narrow legend): the label names the button and is its tooltip. */
+    compact?: boolean;
+}
+export declare function LegendItem({ color, label, shape, onSelect, pressed, dimmed, absent, hint, hintShortcut, compact }: LegendItemProps): import("react").JSX.Element;
+/** Compact items side by side, `columns` to a row: a legend as narrow as its swatches. */
+export declare function LegendSwatches({ columns, children, label }: {
+    columns?: number;
+    children?: ReactNode;
+    label?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+export interface ScrollAreaProps {
+    children?: ReactNode;
+    /**
+     * Classes of the root. It is a flex column, so a height (a flex child with
+     * min-h-0) or a max height (`max-h-64`) is all the scrolled viewport needs.
+     */
+    className?: string;
+    /** Classes of the scrolled viewport's content wrapper. */
+    contentClassName?: string;
+    /** Which bars to offer (default vertical). */
+    axis?: "vertical" | "horizontal" | "both";
+    /** `hover` shows the bars while the pointer is over the area; `scroll` only while scrolling (default hover). */
+    type?: "hover" | "scroll" | "auto" | "always";
+}
+export declare const ScrollArea: import("react").ForwardRefExoticComponent<ScrollAreaProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,49 @@
+/**
+ * Toolbar primitives: a floating card of icon buttons, each naming itself in
+ * a tooltip (no text toolbars). Toggles show their state with an accent wash,
+ * an accent outline and `aria-pressed`; a high-contrast theme outlines them
+ * instead.
+ */
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
+export interface ToolbarProps {
+    children?: ReactNode;
+    className?: string;
+    orientation?: "horizontal" | "vertical";
+    /** For assistive technology ("Diagram tools"). */
+    label?: string;
+}
+/** A floating card holding icon buttons and separators. */
+export declare function Toolbar({ children, className, orientation, label }: ToolbarProps): import("react").JSX.Element;
+export declare function ToolbarSeparator({ orientation }: {
+    orientation?: "vertical" | "horizontal";
+}): import("react").JSX.Element;
+export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /** A Lucide icon name (kebab-case), or the icon itself. */
+    icon: string | ReactNode;
+    /** What the button does: its tooltip and accessible name. */
+    label: string;
+    /** A toggle's state (absent: a plain action). */
+    pressed?: boolean;
+    shortcut?: string;
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+    size?: "sm" | "md";
+    /** A count or dot over the icon (errors on a checks button). */
+    badge?: ReactNode;
+}
+export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface ToggleGroupProps<T extends string> {
+    /** The choices, each an icon with a label for its tooltip. */
+    options: readonly {
+        id: T;
+        icon: string | ReactNode;
+        label: string;
+        disabled?: boolean;
+    }[];
+    value: T;
+    onChange: (value: T) => void;
+    label?: string;
+    tooltipSide?: IconButtonProps["tooltipSide"];
+    size?: IconButtonProps["size"];
+}
+/** One of several, as icon buttons side by side. */
+export declare function ToggleGroup<T extends string>({ options, value, onChange, label, tooltipSide, size }: ToggleGroupProps<T>): import("react").JSX.Element;

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

@@ -0,0 +1,3 @@
+export declare function Tooltips({ root }: {
+    root: HTMLElement | null;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,2 @@
+/** Class names joined, falsy ones dropped. */
+export declare const cx: (...names: (string | false | null | undefined)[]) => string;

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

@@ -0,0 +1,42 @@
+/**
+ * How much of the diagram's legend fits beside the bottom toolbar. The legend
+ * stays where it is (bottom left) and gives way as the toolbar comes near:
+ * the full card, then a compact one (swatches without their labels), then,
+ * at its smallest, a button in the toolbar that opens it. No DOM here: the
+ * legend measures, this decides.
+ */
+export type LegendStage = "full" | "compact" | "button";
+/** Space kept between the legend and the toolbar (px). */
+export declare const LEGEND_GAP = 8;
+/** A larger form comes back only with this much room to spare (px), so a width at the edge does not flicker between two. */
+export declare const LEGEND_HYSTERESIS = 6;
+export interface Box {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface LegendMeasure {
+    /** Where the legend's left edge is (the same for every form). */
+    left: number;
+    /** Each form's box, as it would sit (bottom left). */
+    full: Box;
+    compact: Box;
+    /** The toolbar's box, or none (no toolbar, or hidden). */
+    toolbar?: Box | null;
+    /** The legend's button in the toolbar takes this much of it (its width and gap), when it is there: the toolbar is measured as if it were not. */
+    slot?: number;
+}
+/**
+ * The room the legend has before the toolbar (px): from its left edge to
+ * the toolbar's, less the gap. The toolbar is centred, so its button for the
+ * legend moves its left edge by half the button: that half is given back,
+ * and the room is the same whether or not the button is in it.
+ */
+export declare function legendRoom(m: Pick<LegendMeasure, "left" | "toolbar" | "slot">): number;
+/**
+ * The largest form that does not run into the toolbar. A form fits when it is
+ * clear of the toolbar's height, or narrower than the room. Moving up to a
+ * larger form than `current` takes `LEGEND_HYSTERESIS` more.
+ */
+export declare function legendStage(m: LegendMeasure, current?: LegendStage): LegendStage;