mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 10:30:37 +09:00
Expand plugin host surface (#5205)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The plugin system is the extension boundary for optional product capabilities > - Rich plugins need more than a worker entrypoint: they need scoped database storage, local project folders, managed agents/routines, host navigation, and reusable UI components > - The LLM Wiki work exposed those missing host surfaces while keeping plugin code outside the core control plane > - This pull request expands the core plugin host, SDK, server APIs, and UI bridge so plugins can declare and use those surfaces > - The benefit is that future plugins can integrate with Paperclip through documented, validated contracts instead of bespoke server or UI imports ## What Changed - Added plugin-managed database namespaces and migration tracking, including Drizzle schema/migration files and SQL validation for namespace isolation. - Added server support for plugin local folders, managed agents, managed routines, scoped plugin APIs, and plugin operation visibility. - Expanded shared plugin manifest/types/validators and SDK host/testing/UI exports for richer plugin surfaces. - Added reusable UI pieces for file trees, managed routines, resizable sidebars, route sidebars, and plugin bridge initialization. - Updated plugin docs and example plugins to use the expanded host and SDK surface. ## Verification - `pnpm install --frozen-lockfile` - `pnpm run preflight:workspace-links && pnpm exec vitest run packages/shared/src/validators/plugin.test.ts server/src/__tests__/plugin-database.test.ts server/src/__tests__/plugin-local-folders.test.ts server/src/__tests__/plugin-managed-agents.test.ts server/src/__tests__/plugin-managed-routines.test.ts server/src/__tests__/plugin-orchestration-apis.test.ts ui/src/api/plugins.test.ts ui/src/components/FileTree.test.tsx ui/src/components/ResizableSidebarPane.test.tsx ui/src/pages/PluginPage.test.tsx ui/src/plugins/bridge.test.ts` passed: 11 files, 67 tests. - Confirmed this PR changes 89 files and does not include `pnpm-lock.yaml` or `.github/workflows/*`. ## Risks - Medium: this expands plugin host contracts across db/shared/server/ui and includes a new core migration (`0076_useful_elektra.sql`). - The plugin database namespace validator is intentionally restrictive; plugin authors may need follow-up affordances for SQL patterns that remain blocked. - Merge this before the LLM Wiki plugin PR so the plugin can resolve the new SDK and host APIs. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent, tool-enabled shell/git/GitHub workflow. Context window size was not exposed by the runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
d6bee62f02
commit
3c73ed26b5
89 changed files with 27516 additions and 914 deletions
|
|
@ -125,6 +125,36 @@ export interface TimeseriesChartProps {
|
|||
export interface MarkdownBlockProps {
|
||||
/** Markdown content to render. */
|
||||
content: string;
|
||||
/** Optional CSS class name forwarded to the host renderer. */
|
||||
className?: string;
|
||||
/** Opt into Obsidian-style [[target]] / [[target|label]] wikilinks. */
|
||||
enableWikiLinks?: boolean;
|
||||
/** Base href used for wikilinks when no resolver is supplied. */
|
||||
wikiLinkRoot?: string;
|
||||
/** Optional href resolver for wikilinks. Return null to leave a token as plain text. */
|
||||
resolveWikiLinkHref?: (target: string, label: string) => string | null | undefined;
|
||||
}
|
||||
|
||||
/** Props for `MarkdownEditor`. */
|
||||
export interface MarkdownEditorProps {
|
||||
/** Markdown source controlled by the plugin. */
|
||||
value: string;
|
||||
/** Called whenever the markdown source changes. */
|
||||
onChange: (value: string) => void;
|
||||
/** Placeholder text shown when the document is empty. */
|
||||
placeholder?: string;
|
||||
/** Optional wrapper CSS class name. */
|
||||
className?: string;
|
||||
/** Optional editable content CSS class name. */
|
||||
contentClassName?: string;
|
||||
/** Called when the editor loses focus. */
|
||||
onBlur?: () => void;
|
||||
/** Render the editor with a host border treatment. */
|
||||
bordered?: boolean;
|
||||
/** Render the rich editor without allowing edits. */
|
||||
readOnly?: boolean;
|
||||
/** Called on Cmd/Ctrl+Enter. */
|
||||
onSubmit?: () => void;
|
||||
}
|
||||
|
||||
/** A single key-value pair for `KeyValueList`. */
|
||||
|
|
@ -217,6 +247,211 @@ export interface ErrorBoundaryProps {
|
|||
onError?: (error: Error, info: React.ErrorInfo) => void;
|
||||
}
|
||||
|
||||
/** File or directory node rendered by `FileTree`. */
|
||||
export interface FileTreeNode {
|
||||
/** Display name for this path segment. */
|
||||
name: string;
|
||||
/** Slash-separated path relative to the tree root. */
|
||||
path: string;
|
||||
/** Whether this node is a directory or file. */
|
||||
kind: "dir" | "file";
|
||||
/** Child nodes. Files should use an empty array. */
|
||||
children: FileTreeNode[];
|
||||
/** Optional stable action metadata for host/plugin workflows. */
|
||||
action?: string | null;
|
||||
}
|
||||
|
||||
/** Badge status variants supported by `FileTree`. */
|
||||
export type FileTreeBadgeVariant = "ok" | "warning" | "error" | "info" | "pending";
|
||||
|
||||
/** Serializable badge metadata keyed by file path. */
|
||||
export interface FileTreeBadge {
|
||||
label: string;
|
||||
status: FileTreeBadgeVariant;
|
||||
tooltip?: string;
|
||||
}
|
||||
|
||||
/** Row tone variants supported by `FileTree`. */
|
||||
export type FileTreeTone = "default" | "warning" | "error" | "muted";
|
||||
|
||||
/** Empty-state content shown when a tree has no nodes. */
|
||||
export interface FileTreeEmptyState {
|
||||
title?: string;
|
||||
description?: string;
|
||||
}
|
||||
|
||||
/** Error-state content shown when a tree cannot be loaded. */
|
||||
export interface FileTreeErrorState {
|
||||
message: string;
|
||||
retry?: () => void;
|
||||
}
|
||||
|
||||
/** Accepted path collection shape for expanded and checked file tree state. */
|
||||
export type FileTreePathCollection = ReadonlySet<string> | readonly string[];
|
||||
|
||||
/** Props for `FileTree`. */
|
||||
export interface FileTreeProps {
|
||||
/** Tree nodes to render. */
|
||||
nodes: FileTreeNode[];
|
||||
/** Currently selected file path. */
|
||||
selectedFile?: string | null;
|
||||
/** Expanded directory paths. */
|
||||
expandedPaths?: FileTreePathCollection;
|
||||
/** Checked file paths. */
|
||||
checkedPaths?: FileTreePathCollection;
|
||||
/** Called when a directory row is toggled. */
|
||||
onToggleDir?: (path: string) => void;
|
||||
/** Called when a file row is selected. */
|
||||
onSelectFile?: (path: string) => void;
|
||||
/** Called when a checkbox is toggled. */
|
||||
onToggleCheck?: (path: string, kind: "file" | "dir") => void;
|
||||
/** Badge metadata keyed by path. */
|
||||
fileBadges?: Record<string, FileTreeBadge | undefined>;
|
||||
/** Row tone metadata keyed by path. */
|
||||
fileTones?: Record<string, FileTreeTone | undefined>;
|
||||
/** Whether to render checkboxes. Defaults to false for plugin UIs. */
|
||||
showCheckboxes?: boolean;
|
||||
/** Allow long file and directory names to wrap. */
|
||||
wrapLabels?: boolean;
|
||||
/** Render a loading skeleton instead of nodes. */
|
||||
loading?: boolean;
|
||||
/** Render a structured error state instead of nodes. */
|
||||
error?: FileTreeErrorState | null;
|
||||
/** Empty state content. */
|
||||
empty?: FileTreeEmptyState;
|
||||
/** Accessible label for the tree. */
|
||||
ariaLabel?: string;
|
||||
}
|
||||
|
||||
export interface IssuesListFilters {
|
||||
status?: string;
|
||||
projectId?: string;
|
||||
parentId?: string;
|
||||
assigneeAgentId?: string;
|
||||
participantAgentId?: string;
|
||||
assigneeUserId?: string;
|
||||
labelId?: string;
|
||||
workspaceId?: string;
|
||||
executionWorkspaceId?: string;
|
||||
originKind?: string;
|
||||
originKindPrefix?: string;
|
||||
originId?: string;
|
||||
descendantOf?: string;
|
||||
includeRoutineExecutions?: boolean;
|
||||
}
|
||||
|
||||
export interface IssuesListProps {
|
||||
companyId: string | null;
|
||||
projectId?: string | null;
|
||||
filters?: IssuesListFilters;
|
||||
viewStateKey?: string;
|
||||
initialSearch?: string;
|
||||
createIssueLabel?: string;
|
||||
searchWithinLoadedIssues?: boolean;
|
||||
}
|
||||
|
||||
export interface AssigneePickerSelection {
|
||||
assigneeAgentId: string | null;
|
||||
assigneeUserId: string | null;
|
||||
}
|
||||
|
||||
export interface AssigneePickerProps {
|
||||
/** Company whose agents and users should be listed. Defaults to host context. */
|
||||
companyId?: string | null;
|
||||
/** Controlled value. Use `agent:<id>`, `user:<id>`, or an empty string. */
|
||||
value: string;
|
||||
/** Called with the encoded value plus parsed assignee IDs. */
|
||||
onChange: (value: string, selection: AssigneePickerSelection) => void;
|
||||
/** Button placeholder when no assignee is selected. */
|
||||
placeholder?: string;
|
||||
/** Label for the empty option. */
|
||||
noneLabel?: string;
|
||||
/** Search input placeholder. */
|
||||
searchPlaceholder?: string;
|
||||
/** Empty search result message. */
|
||||
emptyMessage?: string;
|
||||
/** Include active board users alongside agents. Defaults to true. */
|
||||
includeUsers?: boolean;
|
||||
/** Include terminated agents. Defaults to false. */
|
||||
includeTerminatedAgents?: boolean;
|
||||
/** CSS class forwarded to the trigger button. */
|
||||
className?: string;
|
||||
/** Called after the user confirms a selection with Enter, Tab, or click. */
|
||||
onConfirm?: () => void;
|
||||
}
|
||||
|
||||
export interface ProjectPickerProps {
|
||||
/** Company whose projects should be listed. Defaults to host context. */
|
||||
companyId?: string | null;
|
||||
/** Controlled project id, or an empty string for no project. */
|
||||
value: string;
|
||||
/** Called with the selected project id. Empty string means no project. */
|
||||
onChange: (projectId: string) => void;
|
||||
/** Button placeholder when no project is selected. */
|
||||
placeholder?: string;
|
||||
/** Label for the empty option. */
|
||||
noneLabel?: string;
|
||||
/** Search input placeholder. */
|
||||
searchPlaceholder?: string;
|
||||
/** Empty search result message. */
|
||||
emptyMessage?: string;
|
||||
/** Include archived projects. Defaults to false. */
|
||||
includeArchived?: boolean;
|
||||
/** CSS class forwarded to the trigger button. */
|
||||
className?: string;
|
||||
/** Called after the user confirms a selection with Enter, Tab, or click. */
|
||||
onConfirm?: () => void;
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListAgent {
|
||||
id: string;
|
||||
name: string;
|
||||
icon?: string | null;
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListProject {
|
||||
id: string;
|
||||
name: string;
|
||||
color?: string | null;
|
||||
}
|
||||
|
||||
export interface ManagedRoutineMissingRef {
|
||||
resourceKind: string;
|
||||
resourceKey: string;
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListItem {
|
||||
key: string;
|
||||
title: string;
|
||||
status: string;
|
||||
routineId?: string | null;
|
||||
href?: string | null;
|
||||
resourceKey?: string | null;
|
||||
projectId?: string | null;
|
||||
assigneeAgentId?: string | null;
|
||||
cronExpression?: string | null;
|
||||
lastRunAt?: Date | string | null;
|
||||
lastRunStatus?: string | null;
|
||||
managedByPluginDisplayName?: string | null;
|
||||
missingRefs?: ManagedRoutineMissingRef[];
|
||||
}
|
||||
|
||||
export interface ManagedRoutinesListProps {
|
||||
routines: ManagedRoutinesListItem[];
|
||||
agents?: ManagedRoutinesListAgent[];
|
||||
projects?: ManagedRoutinesListProject[];
|
||||
pluginDisplayName?: string | null;
|
||||
emptyMessage?: string;
|
||||
runningRoutineKey?: string | null;
|
||||
statusMutationRoutineKey?: string | null;
|
||||
reconcilingRoutineKey?: string | null;
|
||||
resettingRoutineKey?: string | null;
|
||||
onRunNow?: (routine: ManagedRoutinesListItem) => void;
|
||||
onToggleEnabled?: (routine: ManagedRoutinesListItem, enabled: boolean) => void;
|
||||
onReconcile?: (routine: ManagedRoutinesListItem) => void;
|
||||
onReset?: (routine: ManagedRoutinesListItem) => void;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Component declarations (provided by host at runtime)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
|
@ -266,6 +501,13 @@ export const TimeseriesChart = createSdkUiComponent<TimeseriesChartProps>("Times
|
|||
*/
|
||||
export const MarkdownBlock = createSdkUiComponent<MarkdownBlockProps>("MarkdownBlock");
|
||||
|
||||
/**
|
||||
* Renders Paperclip's shared Markdown editor.
|
||||
*
|
||||
* @see PLUGIN_SPEC.md §19.6 — Shared Components
|
||||
*/
|
||||
export const MarkdownEditor = createSdkUiComponent<MarkdownEditorProps>("MarkdownEditor");
|
||||
|
||||
/**
|
||||
* Renders a definition-list of label/value pairs.
|
||||
*
|
||||
|
|
@ -308,3 +550,40 @@ export const Spinner = createSdkUiComponent<SpinnerProps>("Spinner");
|
|||
* @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
|
||||
*/
|
||||
export const ErrorBoundary = createSdkUiComponent<ErrorBoundaryProps>("ErrorBoundary");
|
||||
|
||||
/**
|
||||
* Renders the host file tree component with a stable plugin-safe prop surface.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* import { FileTree, type FileTreeNode } from "@paperclipai/plugin-sdk/ui";
|
||||
*
|
||||
* const nodes: FileTreeNode[] = [
|
||||
* { name: "README.md", path: "README.md", kind: "file", children: [] },
|
||||
* ];
|
||||
*
|
||||
* <FileTree nodes={nodes} onSelectFile={(path) => console.log(path)} />;
|
||||
* ```
|
||||
*/
|
||||
export const FileTree = createSdkUiComponent<FileTreeProps>("FileTree");
|
||||
|
||||
/**
|
||||
* Renders Paperclip's native issue list component for company-scoped plugin
|
||||
* pages that need a standard board issue view.
|
||||
*/
|
||||
export const IssuesList = createSdkUiComponent<IssuesListProps>("IssuesList");
|
||||
|
||||
/**
|
||||
* Renders the same host assignee picker used by the new issue pane.
|
||||
*/
|
||||
export const AssigneePicker = createSdkUiComponent<AssigneePickerProps>("AssigneePicker");
|
||||
|
||||
/**
|
||||
* Renders the same host project picker used by the new issue pane.
|
||||
*/
|
||||
export const ProjectPicker = createSdkUiComponent<ProjectPickerProps>("ProjectPicker");
|
||||
|
||||
/**
|
||||
* Renders Paperclip's native managed routines list for plugin settings pages.
|
||||
*/
|
||||
export const ManagedRoutinesList = createSdkUiComponent<ManagedRoutinesListProps>("ManagedRoutinesList");
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
import type {
|
||||
PluginDataResult,
|
||||
PluginActionFn,
|
||||
HostLocation,
|
||||
HostNavigation,
|
||||
PluginHostContext,
|
||||
PluginStreamResult,
|
||||
PluginToastFn,
|
||||
|
|
@ -115,6 +117,57 @@ export function useHostContext(): PluginHostContext {
|
|||
return impl();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// useHostNavigation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Navigate within the Paperclip host without forcing a full document reload.
|
||||
*
|
||||
* Use `linkProps()` for links so browser-native behavior still works:
|
||||
* modifier-click, middle-click, copy-link, and open-in-new-tab all use the
|
||||
* returned real `href`.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* function WikiSidebarLink() {
|
||||
* const hostNavigation = useHostNavigation();
|
||||
* return <a {...hostNavigation.linkProps("/wiki")}>Wiki</a>;
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function useHostNavigation(): HostNavigation {
|
||||
const impl = getSdkUiRuntimeValue<() => HostNavigation>("useHostNavigation");
|
||||
return impl();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// useHostLocation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Observe the current host router location.
|
||||
*
|
||||
* Returns a snapshot of the active `pathname`, `search`, and `hash`. The
|
||||
* component re-renders when any of these change (e.g. after the host router
|
||||
* pushes a new entry, or after the browser back/forward gestures). Use this
|
||||
* for URL-driven plugin UI such as a takeover sidebar with section-aware
|
||||
* active state.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* function WikiSection() {
|
||||
* const { pathname } = useHostLocation();
|
||||
* const section = pathname.split("/").filter(Boolean).at(-1) ?? "wiki";
|
||||
* return <div>Active section: {section}</div>;
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function useHostLocation(): HostLocation {
|
||||
const impl = getSdkUiRuntimeValue<() => HostLocation>("useHostLocation");
|
||||
return impl();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// usePluginStream
|
||||
// ---------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -43,20 +43,89 @@
|
|||
* - `usePluginData(key, params)` — fetch data from the worker's `getData` handler
|
||||
* - `usePluginAction(key)` — get a callable that invokes the worker's `performAction` handler
|
||||
* - `useHostContext()` — read the current active company, project, entity, and user IDs
|
||||
* - `useHostNavigation()` — navigate Paperclip-internal links through the host router
|
||||
* - `useHostLocation()` — observe the current host pathname/search/hash for URL-driven UI
|
||||
* - `usePluginStream(channel)` — subscribe to real-time SSE events from the worker
|
||||
*/
|
||||
export {
|
||||
usePluginData,
|
||||
usePluginAction,
|
||||
useHostContext,
|
||||
useHostNavigation,
|
||||
useHostLocation,
|
||||
usePluginStream,
|
||||
usePluginToast,
|
||||
} from "./hooks.js";
|
||||
|
||||
export {
|
||||
MetricCard,
|
||||
StatusBadge,
|
||||
DataTable,
|
||||
TimeseriesChart,
|
||||
MarkdownBlock,
|
||||
MarkdownEditor,
|
||||
KeyValueList,
|
||||
ActionBar,
|
||||
LogView,
|
||||
JsonTree,
|
||||
Spinner,
|
||||
ErrorBoundary,
|
||||
FileTree,
|
||||
IssuesList,
|
||||
AssigneePicker,
|
||||
ProjectPicker,
|
||||
ManagedRoutinesList,
|
||||
} from "./components.js";
|
||||
|
||||
export type {
|
||||
MetricTrend,
|
||||
MetricCardProps,
|
||||
StatusBadgeVariant,
|
||||
StatusBadgeProps,
|
||||
DataTableColumn,
|
||||
DataTableProps,
|
||||
TimeseriesDataPoint,
|
||||
TimeseriesChartProps,
|
||||
MarkdownBlockProps,
|
||||
MarkdownEditorProps,
|
||||
KeyValuePair,
|
||||
KeyValueListProps,
|
||||
ActionBarItem,
|
||||
ActionBarProps,
|
||||
LogViewEntry,
|
||||
LogViewProps,
|
||||
JsonTreeProps,
|
||||
SpinnerProps,
|
||||
ErrorBoundaryProps,
|
||||
FileTreeNode,
|
||||
FileTreeBadgeVariant,
|
||||
FileTreeBadge,
|
||||
FileTreeTone,
|
||||
FileTreeEmptyState,
|
||||
FileTreeErrorState,
|
||||
FileTreePathCollection,
|
||||
FileTreeProps,
|
||||
IssuesListFilters,
|
||||
IssuesListProps,
|
||||
AssigneePickerSelection,
|
||||
AssigneePickerProps,
|
||||
ProjectPickerProps,
|
||||
ManagedRoutineMissingRef,
|
||||
ManagedRoutinesListAgent,
|
||||
ManagedRoutinesListItem,
|
||||
ManagedRoutinesListProject,
|
||||
ManagedRoutinesListProps,
|
||||
} from "./components.js";
|
||||
|
||||
// Bridge error and host context types
|
||||
export type {
|
||||
PluginBridgeError,
|
||||
PluginBridgeErrorCode,
|
||||
HostNavigation,
|
||||
HostNavigationOptions,
|
||||
HostNavigationLinkOptions,
|
||||
HostNavigationLinkProps,
|
||||
HostLocation,
|
||||
PluginHostContext,
|
||||
PluginModalBoundsRequest,
|
||||
PluginRenderCloseEvent,
|
||||
|
|
@ -80,6 +149,7 @@ export type {
|
|||
PluginWidgetProps,
|
||||
PluginDetailTabProps,
|
||||
PluginSidebarProps,
|
||||
PluginRouteSidebarProps,
|
||||
PluginProjectSidebarItemProps,
|
||||
PluginCommentAnnotationProps,
|
||||
PluginCommentContextMenuItemProps,
|
||||
|
|
|
|||
|
|
@ -14,6 +14,10 @@
|
|||
* @see PLUGIN_SPEC.md §29.2 — SDK Versioning
|
||||
*/
|
||||
|
||||
import type {
|
||||
AnchorHTMLAttributes,
|
||||
MouseEvent as ReactMouseEvent,
|
||||
} from "react";
|
||||
import type {
|
||||
PluginBridgeErrorCode,
|
||||
PluginLauncherBounds,
|
||||
|
|
@ -131,6 +135,83 @@ export interface PluginRenderEnvironmentContext
|
|||
closeLifecycle?: PluginRenderCloseLifecycle | null;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Host navigation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Options for host-managed Paperclip navigation from plugin UI.
|
||||
*/
|
||||
export interface HostNavigationOptions {
|
||||
/** Replace the current history entry instead of pushing a new one. */
|
||||
replace?: boolean;
|
||||
/** Optional state forwarded to the host router. */
|
||||
state?: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for `useHostNavigation().linkProps()`.
|
||||
*/
|
||||
export interface HostNavigationLinkOptions extends HostNavigationOptions {
|
||||
/** Standard anchor target. Non-`_self` targets are not intercepted. */
|
||||
target?: AnchorHTMLAttributes<HTMLAnchorElement>["target"];
|
||||
/** Standard anchor rel attribute. */
|
||||
rel?: AnchorHTMLAttributes<HTMLAnchorElement>["rel"];
|
||||
}
|
||||
|
||||
/**
|
||||
* Anchor props returned by `useHostNavigation().linkProps()`.
|
||||
*
|
||||
* The `href` is always real so browser affordances such as copy-link,
|
||||
* modifier-click, middle-click, and open-in-new-tab continue to work.
|
||||
*/
|
||||
export interface HostNavigationLinkProps
|
||||
extends Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "target" | "rel"> {
|
||||
onClick: (event: ReactMouseEvent<HTMLAnchorElement>) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Snapshot of the host router location, exposed to plugin UI through
|
||||
* `useHostLocation()`. Mirrors the relevant subset of `Location` from
|
||||
* `react-router-dom` so plugins can react to URL changes without importing
|
||||
* router internals.
|
||||
*
|
||||
* @see PLUGIN_SPEC.md §19 — UI Extension Model
|
||||
*/
|
||||
export interface HostLocation {
|
||||
/** Current pathname, e.g. `/PAP/wiki`. */
|
||||
pathname: string;
|
||||
/** Current search string, e.g. `?tab=config` (includes the leading `?`). */
|
||||
search: string;
|
||||
/** Current hash, e.g. `#document-plan` (includes the leading `#`). */
|
||||
hash: string;
|
||||
/** Optional state forwarded by the host router for same-tab SPA navigation. */
|
||||
state?: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Host-managed navigation helpers for plugin UI.
|
||||
*/
|
||||
export interface HostNavigation {
|
||||
/**
|
||||
* Resolve a Paperclip-internal path using the active company prefix.
|
||||
*
|
||||
* For example, in company `PAP`, `resolveHref("/wiki")` returns
|
||||
* `"/PAP/wiki"`, while `resolveHref("/PAP/wiki")` stays unchanged.
|
||||
*/
|
||||
resolveHref(to: string): string;
|
||||
/** Navigate through the host router without reloading the document. */
|
||||
navigate(to: string, options?: HostNavigationOptions): void;
|
||||
/**
|
||||
* Build anchor props for host-managed links.
|
||||
*
|
||||
* Plain left-clicks are routed through the host SPA router. Browser-native
|
||||
* link gestures are left alone because the returned props include a real
|
||||
* `href`.
|
||||
*/
|
||||
linkProps(to: string, options?: HostNavigationLinkOptions): HostNavigationLinkProps;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Slot component prop interfaces
|
||||
// ---------------------------------------------------------------------------
|
||||
|
|
@ -188,6 +269,19 @@ export interface PluginSidebarProps {
|
|||
context: PluginHostContext;
|
||||
}
|
||||
|
||||
/**
|
||||
* Props passed to a plugin route sidebar component.
|
||||
*
|
||||
* A route sidebar replaces the normal company sidebar while the user is on a
|
||||
* matching plugin page route declared with the same `routePath`.
|
||||
*
|
||||
* @see PLUGIN_SPEC.md §19.5 — Sidebar Entries
|
||||
*/
|
||||
export interface PluginRouteSidebarProps {
|
||||
/** The current host context. */
|
||||
context: PluginHostContext;
|
||||
}
|
||||
|
||||
/**
|
||||
* Props passed to a plugin project sidebar item component.
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue