@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/components/node-canvas/types.d.ts

@@ -0,0 +1,207 @@
+import type { ReactNode } from "react";
+/**
+ * One node of the graph.
+ *
+ * `Extra` carries the consumer's own fields, so `renderNode` receives their
+ * type rather than ours plus a cast:
+ *
+ * ```ts
+ * type Service = { owner: string; deployed: boolean };
+ * const nodes: CanvasNode<Service>[] = [
+ *   { id: "api", label: "API", owner: "ada", deployed: true },
+ * ];
+ * <NodeCanvas graph={{ nodes, edges }} renderNode={(node) => <span>{node.owner}</span>} />
+ * ```
+ */
+export type CanvasNode<Extra = unknown> = Extra & {
+    /** Stable across renders. Node positions, focus and drag offsets are keyed on it. */
+    id: string;
+    /**
+     * The accessible name, the list-view row text, and the default body.
+     *
+     * A plain string, not a `ReactNode`, and that is deliberate: it is read
+     * aloud and printed into a row, and neither of those can do anything with
+     * an element tree. Rich content belongs in `renderNode`.
+     */
+    label: string;
+    /**
+     * Which `CanvasGroup` this node belongs to, if any. A node with no group
+     * sits at the top level next to every declared group's own aggregate node.
+     * Groups are flat — a group cannot itself belong to another group — which
+     * matches every real case this shipped with (a domain, a package, a team):
+     * one level of clustering is what "collapse the noisy part" needs, and nested
+     * clustering is a UI nobody asked for yet. Add it if a real consumer needs it.
+     */
+    groupId?: string;
+    /** Along-axis extent for this node only, when it differs from the canvas default. */
+    width?: number;
+    /** Cross-axis extent for this node only, when it differs from the canvas default. */
+    height?: number;
+};
+/**
+ * A directed connection between two node ids.
+ *
+ * `kind` is a free-form string the library assigns NO meaning to — same rule
+ * as `label`'s absence of a `type` field. A consumer distinguishing "imports"
+ * from "calls" reads `kind` back out in `edgeClassName` or in its own styling;
+ * the library never brands one kind as more important than another.
+ */
+export interface CanvasEdge {
+    from: string;
+    to: string;
+    kind?: string;
+}
+/**
+ * A named cluster of nodes, collapsed to one box by default.
+ *
+ * COLLAPSED IS THE DEFAULT because a real graph worth drawing (the spike's
+ * 402-node/2,099-edge import graph) is unreadable — and, for a graph with
+ * enough cross-cluster cycles, catastrophically slow to lay out — at full
+ * detail. A group's aggregate node stands in for every member until a
+ * consumer drills into it; see `NodeCanvasProps.expandedGroupId`.
+ */
+export interface CanvasGroup {
+    id: string;
+    label: string;
+    /** Along-axis extent of this group's collapsed box, when it differs from the default. */
+    width?: number;
+    /** Cross-axis extent of this group's collapsed box, when it differs from the default. */
+    height?: number;
+}
+/** The whole graph. Never mutated by the canvas. */
+export interface CanvasGraph<Extra = unknown> {
+    nodes: readonly CanvasNode<Extra>[];
+    edges: readonly CanvasEdge[];
+}
+/**
+ * The scope drilled into when a consumer clicks a CONDENSED CYCLE rather than
+ * a declared group — captured directly from the `PlacedNode.memberIds` the
+ * click landed on, since a cycle has no stable, externally-nameable id of its
+ * own the way a `CanvasGroup` does.
+ *
+ * `layoutGraph` treats this shape as an instruction to skip its own
+ * cycle-condensing pre-pass for this call: every member of a genuine strongly
+ * connected component is, by definition, reachable from every other member
+ * using ONLY edges between members of that same component (that is what
+ * "strongly connected" means) — so re-running Tarjan on exactly this member
+ * set would immediately re-discover the identical single component and
+ * collapse it right back to one box, drilling in would show nothing new, and
+ * a naive implementation of "drill into a cycle" is a no-op wearing a
+ * breadcrumb. Skipping condensation here hands the (now small, already
+ * isolated) subgraph to dagre's OWN cycle-breaking pass directly — the exact
+ * cost/quality tradeoff this card's condensing pre-pass exists to avoid at
+ * the FULL graph's scale is perfectly acceptable once bounded to one cycle's
+ * membership.
+ */
+export interface CanvasCycleScope {
+    cycleMemberIds: readonly string[];
+}
+/**
+ * What `layoutGraph`'s third argument names: the top level (`null`), a
+ * declared group's own members (its `CanvasGroup.id`), or a condensed
+ * cycle's own members (`CanvasCycleScope`). See `CanvasCycleScope` for why
+ * the last case is not just "another group id".
+ */
+export type CanvasScope = string | null | CanvasCycleScope;
+/**
+ * Which way the chart grows.
+ *
+ * `vertical` ranks top to bottom — the shape most people picture. `horizontal`
+ * ranks left to right, which is what a graph with long labels and few ranks
+ * actually wants: label text runs along the rank axis in one and across it in
+ * the other, so a horizontal chart of the same graph is narrower and reads
+ * without truncation.
+ */
+export type CanvasOrientation = "vertical" | "horizontal";
+/**
+ * A node with its box resolved, in plane coordinates. `x`/`y` are its
+ * TOP-LEFT. This is what the layout actually drew — which is not always one
+ * real node: a collapsed group or a condensed cycle draws as ONE placed node
+ * standing in for several.
+ */
+export interface PlacedNode<Extra = unknown> {
+    id: string;
+    /** Null for a placed node standing in for a group or a condensed cycle. */
+    node: CanvasNode<Extra> | null;
+    /** Set when this placed node IS a collapsed group's aggregate box. */
+    group: CanvasGroup | null;
+    /**
+     * Set when this placed node is a condensed strongly-connected cluster —
+     * nodes that mutually reach each other with no acyclic rank to give them.
+     * Collapsing a cycle is not a user-facing "group" (nobody named it), but it
+     * renders and drills in exactly like one: see the module doc in `layout.ts`.
+     */
+    cycle: boolean;
+    /**
+     * How many real graph nodes this placed node stands for. `1` for an
+     * ordinary node; more than one for a collapsed group or a condensed cycle.
+     */
+    memberCount: number;
+    /** Ids of the real nodes this placed node stands for. `[id]` for an ordinary node. */
+    memberIds: readonly string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One drawn connection. Both ends are always present in the returned `nodes`. */
+export interface CanvasPlacedEdge {
+    from: string;
+    to: string;
+    kind?: string;
+    /** How many raw edges this drawn edge aggregates. `1` for an ordinary edge. */
+    weight: number;
+    /** The route dagre computed, in plane coordinates, at least two points. */
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
+}
+export interface CanvasLayout<Extra = unknown> {
+    nodes: PlacedNode<Extra>[];
+    edges: CanvasPlacedEdge[];
+    /** Extent of the laid-out nodes. The plane is this plus padding on each side. */
+    width: number;
+    height: number;
+}
+export interface LayoutOptions {
+    /** Along-axis extent of a node that does not declare its own. */
+    nodeWidth?: number;
+    /** Cross-axis extent of a node that does not declare its own. */
+    nodeHeight?: number;
+    /** Clear space between two adjacent nodes on the same rank. */
+    siblingGap?: number;
+    /** Clear space between one rank and the next. */
+    levelGap?: number;
+    orientation?: CanvasOrientation;
+}
+/**
+ * What `renderNode` is told about the node it is drawing.
+ *
+ * Every field is structural — a fact about the node's place in the graph or
+ * in the current interaction. None of them is a fact about what the node is.
+ */
+export interface NodeRenderContext {
+    /**
+     * This placed node stands in for a whole group or a condensed cycle rather
+     * than one real node. `renderNode` still receives a `CanvasNode`-shaped
+     * value for it (see `NodeCanvas`'s synthetic node), but `memberCount` is
+     * what says there is more inside.
+     */
+    isGroup: boolean;
+    /** How many real nodes this placed node represents. `1` for an ordinary node. */
+    memberCount: number;
+    /** This node carries the canvas's single tab stop. */
+    isFocused: boolean;
+    /** A pointer is carrying this node right now. */
+    isDragging: boolean;
+    /**
+     * Hops from the focused node, along either edge direction: `0` is the
+     * focused node itself, `1`/`2` its one- and two-hop neighbours. `null` when
+     * nothing is focused, or this node is further away than the canvas tracks.
+     * Lets `renderNode` dim everything outside the neighbourhood a keyboard or
+     * screen-reader user is currently reading.
+     */
+    focusDistance: number | null;
+}
+export type NodeRenderer<Extra = unknown> = (node: CanvasNode<Extra>, context: NodeRenderContext) => ReactNode;

package/dist/types/components/node-canvas/use-canvas-gestures.d.ts

@@ -0,0 +1,39 @@
+import type { Point } from "@/lib/dnd/types";
+/** Plane-local box of a node, as the layout placed it. */
+export interface NodeBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CanvasGestureOptions {
+    /** Where a node sits before any drag offset. Null for an id not on screen. */
+    layoutBoxOf: (id: string) => NodeBox | null;
+    /** Extent of the scrolled plane. Node positions are clamped inside it. */
+    planeSize: {
+        width: number;
+        height: number;
+    };
+    /** A press that released without activating — the click that descends. */
+    onNodeClick: (id: string) => void;
+    /** A drag that committed. Offsets stay owned here either way. */
+    onNodeDragEnd?: (event: {
+        id: string;
+        offset: Point;
+    }) => void;
+    disabled?: boolean;
+}
+export interface CanvasGestures {
+    /** Drag offsets from the layout position, by node id. */
+    offsets: Readonly<Record<string, Point>>;
+    /** The node a pointer is currently carrying, or null. */
+    draggingId: string | null;
+    panning: boolean;
+    /** Ref callback for the scroll viewport. Stable — see the note at its use. */
+    bindViewport: (node: HTMLDivElement | null) => void;
+    /** Ref callback for one node's element. Stable per id. */
+    bindNode: (id: string) => (node: HTMLElement | null) => void;
+    /** Drop every offset — called when the layout underneath them changes. */
+    clearOffsets: () => void;
+}
+export declare function useCanvasGestures(options: CanvasGestureOptions): CanvasGestures;

package/dist/types/components/openapi/OpenApiViewer.d.ts

@@ -0,0 +1,14 @@
+import type { OpenApiDocument } from "./types";
+export interface OpenApiViewerProps {
+    /** A complete OpenAPI 3.1 (or 3.0) document. This component never fetches
+     * or merges partial specs itself — a caller combining several discovery
+     * responses (e.g. danxbot's own permission-scoped `GET /api/routes` +
+     * `GET /api/openapi?endpoints=`) does that before handing the result here. */
+    spec: OpenApiDocument;
+    /** Group names to start expanded. Defaults to none — the filter box is the
+     * primary way to find one operation in a large spec, and starting every
+     * group closed keeps the first paint short regardless of spec size. */
+    defaultExpandedGroups?: readonly string[];
+    className?: string;
+}
+export declare function OpenApiViewer({ spec, defaultExpandedGroups, className }: OpenApiViewerProps): import("react").JSX.Element;

package/dist/types/components/openapi/OperationCard.d.ts

@@ -0,0 +1,33 @@
+import type { OpenApiDocument, ResolvedOperation } from "./types";
+export interface OperationHeaderProps {
+    resolved: ResolvedOperation;
+    /** Renders the deep-link "copy link" control. Off for a caller (like
+     * `OpenApiViewer`'s list row) that renders its own, positioned relative to
+     * a wrapper this component doesn't own. */
+    showCopyLink?: boolean;
+    className?: string;
+}
+/** The cheap, always-rendered part of one operation: method, path, summary,
+ * deprecated flag, description, operationId. No schema, no tabs — safe to
+ * mount for every operation in a large document at once. */
+export declare function OperationHeader({ resolved, showCopyLink, className }: OperationHeaderProps): import("react").JSX.Element;
+export interface OperationDetailProps {
+    doc: OpenApiDocument;
+    resolved: ResolvedOperation;
+    className?: string;
+}
+/** The expensive part: parameters, request body, responses (each with a
+ * `SchemaView` tree and a synthesised example) and security — everything
+ * `OpenApiViewer` lazy-mounts per operation. */
+export declare function OperationDetail({ doc, resolved, className }: OperationDetailProps): import("react").JSX.Element;
+export interface OperationCardProps {
+    doc: OpenApiDocument;
+    resolved: ResolvedOperation;
+    className?: string;
+}
+/** One operation, header AND detail both always mounted — for a consumer
+ * embedding a single operation's full detail on its own page (nothing to
+ * lazy-mount when there's only one). `OpenApiViewer`'s own list uses
+ * `OperationHeader`/`OperationDetail` directly instead, so it can lazy-mount
+ * the detail per row — see this file's own header comment. */
+export declare function OperationCard({ doc, resolved, className }: OperationCardProps): import("react").JSX.Element;

package/dist/types/components/openapi/SchemaView.d.ts

@@ -0,0 +1,14 @@
+import type { OpenApiDocument, OpenApiSchema } from "./types";
+export interface SchemaViewProps {
+    doc: Pick<OpenApiDocument, "components">;
+    schema: OpenApiSchema | undefined;
+    /** Rendered as `<dt>` at depth 0 — a parameter name, `requestBody`, a
+     * response status. Omit at depth 0 for an anonymous root (an array's item
+     * schema, a combinator branch). */
+    name?: string;
+    required?: boolean;
+    depth?: number;
+    seen?: ReadonlySet<string>;
+    className?: string;
+}
+export declare function SchemaView({ doc, schema, name, required, depth, seen, className }: SchemaViewProps): import("react").JSX.Element | null;

package/dist/types/components/openapi/index.d.ts

@@ -0,0 +1,6 @@
+export { OpenApiViewer, type OpenApiViewerProps } from "./OpenApiViewer";
+export { OperationCard, type OperationCardProps } from "./OperationCard";
+export { OperationHeader, type OperationHeaderProps, OperationDetail, type OperationDetailProps } from "./OperationCard";
+export { SchemaView, type SchemaViewProps } from "./SchemaView";
+export { groupOperations, isHttpMethod, mergedParameters, operationAnchorId, resolveSchema, resolveWebhooks, schemaToExample, type SchemaResolution, } from "./resolve";
+export { HTTP_METHODS, type HttpMethod, type OpenApiDocument, type OpenApiMediaType, type OpenApiOperation, type OpenApiParameter, type OpenApiParameterLocation, type OpenApiPathItem, type OpenApiRequestBody, type OpenApiResponse, type OpenApiSchema, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiTag, type OperationGroup, type ResolvedOperation, } from "./types";

package/dist/types/components/openapi/resolve.d.ts

@@ -0,0 +1,72 @@
+import type { HttpMethod, OpenApiDocument, OpenApiParameter, OpenApiSchema, OperationGroup, ResolvedOperation } from "./types";
+export declare function isHttpMethod(key: string): key is HttpMethod;
+/**
+ * Resolves a single `{ $ref: "#/components/schemas/Foo" }` against the
+ * document's `components.schemas`, one hop. Only the LOCAL `#/components/…`
+ * form is supported — an external or remote `$ref` is a shape this
+ * component's producers (danxbot's own generators) never emit, and resolving
+ * one would mean a network fetch this pure function cannot make; it is
+ * returned unresolved (`{ $ref, unresolved: true }`) instead of thrown, so a
+ * viewer degrades to showing the raw pointer rather than crashing the page.
+ */
+export interface SchemaResolution {
+    readonly schema: OpenApiSchema;
+    /** The `$ref` this schema came from, when it was one. */
+    readonly ref?: string;
+    /** True when `ref` pointed somewhere this function could not follow (a
+     * non-local ref, or a name absent from `components.schemas`). */
+    readonly unresolved?: boolean;
+}
+/**
+ * Follows `$ref` chains until it reaches a non-`$ref` schema, a document
+ * boundary, or a cycle — a schema that refers back to one already on the
+ * current chain renders as `unresolved` rather than looping forever (a
+ * self-referential "Tree"-shaped schema, e.g. `TaskInput.subtasks: Task[]`,
+ * is common enough that this is a real case, not a defensive nicety).
+ */
+export declare function resolveSchema(doc: Pick<OpenApiDocument, "components">, schema: OpenApiSchema | undefined, seen?: ReadonlySet<string>): SchemaResolution | undefined;
+/**
+ * `PathItem`-level parameters merged with the operation's own — 3.1 §4.8.10:
+ * "If a parameter is already defined at the Path Item, the new definition
+ * will override it, but can never remove it", matched by `name`+`in`. Path
+ * parameters win because an operation that redeclares one is documenting it
+ * more specifically, never withdrawing it.
+ */
+export declare function mergedParameters(pathParameters: readonly OpenApiParameter[], operationParameters: readonly OpenApiParameter[] | undefined): OpenApiParameter[];
+/** The one word `groupOperations` needs; the viewer passes `useUiStrings().openApiViewer`. */
+export interface GroupOperationsStrings {
+    untaggedGroup: string;
+}
+/**
+ * Groups every operation by tag, falling back to the first path segment ONLY
+ * when the document declares no tag on any operation at all — a document
+ * that tags SOME operations and not others puts the untagged remainder in
+ * `strings.untaggedGroup` rather than silently switching the whole document to path-based
+ * grouping, so a partially-tagged spec still reads as "the author meant to
+ * group by tag". Groups are ordered the way `locale` sorts their names (DX-4740).
+ */
+export declare function groupOperations(doc: OpenApiDocument, strings: GroupOperationsStrings, locale: string): OperationGroup[];
+/**
+ * Every operation of the document's top-level `webhooks` (DX-4178), in
+ * document order, each carrying its webhook NAME as `path` and `webhook:
+ * true`. Webhooks are not grouped by tag: they are a short, named list of the
+ * calls a consumer must receive, shown as their own section.
+ */
+export declare function resolveWebhooks(doc: OpenApiDocument): ResolvedOperation[];
+/** A stable per-operation id for a deep link / anchor — same input, same id,
+ * across renders and across documents (used as both the section `id` and the
+ * `#fragment` a "copy link" control writes). */
+export declare function operationAnchorId(method: HttpMethod, path: string, webhook?: boolean): string;
+/** `operationAnchorId` for a resolved operation — the one place a caller
+ * cannot forget the webhook namespace. */
+export declare function resolvedAnchorId(resolved: ResolvedOperation): string;
+/**
+ * Synthesises a representative JSON value from a schema when the document
+ * supplies no explicit `example`/`examples` — the same fallback every
+ * OpenAPI-viewing tool makes, because a schema-only operation (which is most
+ * of danxbot's own generated spec today) would otherwise have no example
+ * tab at all. `depth` guards a self-referential schema (`resolveSchema`
+ * already breaks `$ref` cycles; a schema can still recurse structurally,
+ * e.g. `additionalProperties: <self>`, without ever repeating a `$ref`).
+ */
+export declare function schemaToExample(doc: Pick<OpenApiDocument, "components">, schema: OpenApiSchema | undefined, depth?: number): unknown;

package/dist/types/components/openapi/types.d.ts

@@ -0,0 +1,128 @@
+/** A JSON Schema node (or an OpenAPI "Schema Object", which 3.1 defines as
+ * one). Loose on purpose — see the file header. */
+export type OpenApiSchema = Record<string, unknown>;
+export type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
+export interface OpenApiParameter {
+    readonly name: string;
+    readonly in: OpenApiParameterLocation;
+    readonly required?: boolean;
+    readonly deprecated?: boolean;
+    readonly description?: string;
+    readonly schema?: OpenApiSchema;
+    readonly example?: unknown;
+}
+export interface OpenApiMediaType {
+    readonly schema?: OpenApiSchema;
+    readonly example?: unknown;
+    readonly examples?: Record<string, {
+        readonly summary?: string;
+        readonly value?: unknown;
+    }>;
+}
+export interface OpenApiRequestBody {
+    readonly required?: boolean;
+    readonly description?: string;
+    readonly content: Record<string, OpenApiMediaType>;
+}
+export interface OpenApiResponse {
+    readonly description: string;
+    readonly content?: Record<string, OpenApiMediaType>;
+}
+/** `{securitySchemeName: scopes[]}` — one alternative a caller may satisfy.
+ * An operation's `security` is an array of these; several entries in the
+ * SAME object mean "all of these together", several objects in the array
+ * mean "any one of these". An empty array (`[]` on the operation) means
+ * "no security" and overrides the document-level default. */
+export type OpenApiSecurityRequirement = Record<string, readonly string[]>;
+export interface OpenApiOperation {
+    readonly operationId?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    readonly parameters?: readonly OpenApiParameter[];
+    readonly requestBody?: OpenApiRequestBody;
+    readonly responses: Record<string, OpenApiResponse>;
+    readonly security?: readonly OpenApiSecurityRequirement[];
+    /** Vendor extensions (`x-...`) ride along unread by name, so a caller can
+     * still reach `operation["x-served-by"]` off the resolved operation this
+     * package hands back from `groupOperations`. */
+    readonly [extension: `x-${string}`]: unknown;
+}
+export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+export type OpenApiPathItem = Partial<Record<HttpMethod, OpenApiOperation>> & {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly parameters?: readonly OpenApiParameter[];
+};
+export interface OpenApiSecurityScheme {
+    readonly type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
+    readonly scheme?: string;
+    readonly bearerFormat?: string;
+    readonly in?: "query" | "header" | "cookie";
+    readonly name?: string;
+    readonly description?: string;
+    readonly openIdConnectUrl?: string;
+    readonly flows?: Record<string, {
+        readonly scopes?: Record<string, string>;
+    }>;
+}
+export interface OpenApiTag {
+    readonly name: string;
+    readonly description?: string;
+}
+export interface OpenApiDocument {
+    readonly openapi: string;
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+    };
+    readonly servers?: readonly {
+        readonly url: string;
+        readonly description?: string;
+    }[];
+    readonly tags?: readonly OpenApiTag[];
+    readonly paths: Record<string, OpenApiPathItem>;
+    /** OpenAPI 3.1 top-level `webhooks` (DX-4178): calls the API's server
+     * MAKES to a consumer, keyed by a name rather than a path. Each value is a
+     * Path Item whose operations are the requests the consumer must receive. */
+    readonly webhooks?: Record<string, OpenApiPathItem>;
+    readonly components?: {
+        readonly schemas?: Record<string, OpenApiSchema>;
+        readonly securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    };
+    readonly security?: readonly OpenApiSecurityRequirement[];
+}
+/** One operation, already paired with its method + path — `groupOperations`'s
+ * output unit, and `OperationCard`'s own prop. Carrying `path`/`method`
+ * alongside the raw `OpenApiOperation` means every renderer below the group
+ * level can stay a pure function of "one operation", never reaching back up
+ * for context its parent already had. */
+export interface ResolvedOperation {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly operation: OpenApiOperation;
+    /** Parameters declared on the shared `PathItem` (never overridden — 3.1
+     * merges these with the operation's own, operation-level winning on a
+     * `name`+`in` collision — see `resolve.ts#mergedParameters`). */
+    readonly pathParameters: readonly OpenApiParameter[];
+    /** DX-4178: true when this is an OpenAPI `webhooks` entry — `path` then
+     * holds the webhook's NAME, not a URL path the API serves. A webhook has no
+     * document-level default security (the document's `security` governs the
+     * calls INTO the API, not the one a consumer's receiver is sent) and its
+     * anchor id is namespaced apart from every path's. */
+    readonly webhook?: true;
+}
+/** One tag/path group of operations, in document order. */
+export interface OperationGroup {
+    /** The tag name, or — when the document declares no tags at all on the
+     * operations it carries — the first non-empty path segment (`resolve.ts`).
+     * Never both in the same document: a document that tags ANY operation is
+     * grouped by tag, with untagged operations falling into the group the
+     * provider names (`openApiViewer.untaggedGroup`). */
+    readonly name: string;
+    readonly description?: string;
+    readonly operations: readonly ResolvedOperation[];
+}

package/dist/types/components/overlay-shell.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The backdrop every overlay dims the page with. Callers may only ADD
+ * classes (e.g. `AppShell`'s `lg:hidden`, scoping its copy to viewports
+ * below the drawer breakpoint) — never override what is defined here, or the
+ * three stop being the same backdrop again.
+ */
+export declare function overlayBackdropClassName(...extra: Array<string | false | null | undefined>): string;
+/** The floated panel's background/border/shadow — identical for `Dialog` and
+ *  `CommandPalette`, which both float a centered/anchored `rounded-xl` panel
+ *  (as opposed to `AppShell`'s edge-to-edge side drawer, which is genuinely
+ *  different chrome and keeps its own). */
+export declare const OVERLAY_POPUP_SURFACE = "dx-ground-overlay rounded-xl border border-border bg-surface-overlay shadow-xl outline-none";
+/** The motion halves shared by every `OVERLAY_POPUP_SURFACE` consumer — the
+ *  entry transition and the exit half of the starting/ending-style pair. The
+ *  ENTRY starting-style stays per-caller (each panel enters from a slightly
+ *  different transform: `Dialog` scales in place, `CommandPalette` also
+ *  drifts up a couple pixels), so it is deliberately not included here. */
+export declare const OVERLAY_POPUP_MOTION: string[];
+/** The surface of every popup ANCHORED to a control — `Menu`, `Select`,
+ *  `Combobox`, `MultiCombobox`, `Popover` (DX-4265). Same paint as
+ *  `OVERLAY_POPUP_SURFACE` minus the modal panel's radius, so the five
+ *  stop hand-copying it. `bg-surface-overlay` is opaque in both themes.
+ *  `dx-ground-overlay` tells the interaction ramp what the popup is painted ON:
+ *  without it every hover inside mixes from `--surface`, which on dark is two
+ *  ramp steps below `--surface-overlay`, so the hover fill lands DARKER than
+ *  the popup and reads as nothing happening (tokens.css). */
+export declare const ANCHORED_POPUP_SURFACE = "dx-ground-overlay rounded-lg border border-border bg-surface-overlay shadow-lg outline-none";
+/** The motion every `ANCHORED_POPUP_SURFACE` consumer shares.
+ *
+ *  DX-4265: ENTRY DOES NOT FADE. Opacity animates the whole element, background
+ *  included, so a popup that fades in is see-through for its first
+ *  `--dur-slow`: the page behind it reads through the option list. That is
+ *  invisible in dark, where popup and page are both near-black, and obvious in
+ *  light, where the list is white text-on-white over page text; it was filed as
+ *  "the light popup is translucent" when the surface token was opaque all along.
+ *  The popup arrives by scale + a one-step drift, opaque from the first frame.
+ *  EXIT still fades: a closing popup being see-through says "leaving". */
+export declare const ANCHORED_POPUP_MOTION: string[];
+/**
+ * DXUI-93: the host's own controls in a `Dialog` or `Drawer` header (`headerActions`), pushed to the row's end beside the close
+ * button. They sit OUTSIDE the title element, so they are no part of the overlay's accessible name.
+ */
+export declare const OVERLAY_HEADER_ACTIONS_CLASS = "ml-auto flex flex-none items-center gap-1.5";
+/**
+ * DXUI-94: `headerActionsGrow`: the host's controls fill the row beside the title (start-aligned, truncating inside it) instead of hugging
+ * the close button. The title block then takes only the room its content needs, so the controls get the rest.
+ */
+export declare const OVERLAY_HEADER_ACTIONS_GROW_CLASS = "flex min-w-0 flex-1 items-center gap-1.5";

package/dist/types/components/overlay-stack.d.ts

@@ -0,0 +1,18 @@
+/** The scopes of every Popover whose content the reader is inside, outermost first. */
+export declare const PopoverScopeContext: import("react").Context<readonly symbol[]>;
+interface OpenPopover {
+    scope: symbol;
+    close: () => void;
+    /** Hide or show the popover without unmounting it. */
+    setCovered: (covered: boolean) => void;
+    /** How many open dialogs inside it are covering it right now. */
+    covers: number;
+}
+/** A Popover is open. Returns the call that says it no longer is. */
+export declare function registerOpenPopover(entry: OpenPopover): () => void;
+/** A Dialog is opening inside `ancestry`: close every open Popover outside it. */
+export declare function dismissPopoversOutside(ancestry: readonly symbol[]): void;
+/** A Dialog is open inside `ancestry`: hide those popovers until it closes.
+    Returns the call that says it has. */
+export declare function coverPopovers(ancestry: readonly symbol[]): () => void;
+export {};

package/dist/types/components/paged-window/PageBlock.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode, Ref } from "react";
+import type { BlockStatus } from "../../lib/paged-window/layout";
+export interface PageBlockProps {
+    page: number;
+    status: BlockStatus;
+    /** The cards of a `ready` page. Ignored for every other status: they have none to show. */
+    children?: ReactNode;
+    /** How many cards a `ready` page shows (`data-count`, which the pitch measurement reads). */
+    count: number;
+    /** The height the page holds when it has no cards: items on it x the measured item height. */
+    height: number;
+    /** One item's height, for the loading rows. */
+    pitch: number;
+    /** Ref callback that returns its cleanup: how the list's observers find this block. */
+    blockRef: Ref<HTMLDivElement>;
+    errorText: string;
+    retryText: string;
+    onRetry: () => void;
+}
+/**
+ * THE ONE ELEMENT A PAGE IS, in every state. A page turns from placeholder to
+ * cards (a load), to placeholder again (a drop) and to an error row and back
+ * without this element being replaced: it is the same component type at the same
+ * key, so React keeps the same DOM node. That is what keeps the browser's scroll
+ * anchoring on the element under the viewport and keeps the observers attached
+ * (visibility and pitch) instead of detaching and re-attaching on every change.
+ * What changes is only what it holds and how it is drawn: the cards of a ready
+ * page, otherwise the page's height (and, while loading, faint rows; on failure,
+ * a Retry row).
+ */
+export declare function PageBlock({ page, status, children, count, height, pitch, blockRef, errorText, retryText, onRetry, }: PageBlockProps): import("react").JSX.Element;