@capybara-hq/plugin-client 0.1.0-rc.2 → 0.1.0-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -3
- package/dist/context.d.ts +2 -1
- package/dist/hooks.d.ts +6 -1
- package/dist/hooks.js +7 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/testing/index.d.ts +3 -1
- package/dist/testing/index.js +4 -1
- package/dist/types.d.ts +11 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ The client SDK for writing plugin UI for [Capybara](https://github.com/capybara-
|
|
|
4
4
|
open-source enterprise agent platform. A plugin's client entry (`src/client.tsx`) imports from this
|
|
5
5
|
package: `defineClientExtension`, `defineComponent`, the hooks (`useView`, `useAction`, `useAccess`,
|
|
6
6
|
`useLocale`, `useRunState`, `useCapybaraEvents`, `usePrefersReducedMotion`, `useTheme`,
|
|
7
|
-
`useClientStorage`, `useAssetUrl`) and a versioned subset of the design components (`Button`,
|
|
7
|
+
`useClientStorage`, `useAssetUrl`, `useSignIn`) and a versioned subset of the design components (`Button`,
|
|
8
8
|
`Badge`, `Icon`, `KeyValue`, `Kbd`, `Logo`, `Spinner`, `Stack`, `Text`, `Tooltip`,
|
|
9
9
|
`PropertySection`, `ViewBlocks`).
|
|
10
10
|
|
|
@@ -15,8 +15,14 @@ npm install @capybara-hq/plugin-client
|
|
|
15
15
|
In the browser the specifier `@capybara-hq/plugin-client` resolves to the host's own implementation
|
|
16
16
|
of this interface (through an import map); `react` is provided by the host too. The package's own
|
|
17
17
|
runtime serves tests and type checking: `@capybara-hq/plugin-client/testing` has
|
|
18
|
-
`renderWithFakeHost(element, { slot, args?, role?, locale?, runState?, view?, onAction?, events
|
|
19
|
-
which renders a component inside a fake host (jsdom needed).
|
|
18
|
+
`renderWithFakeHost(element, { slot, args?, role?, locale?, runState?, view?, onAction?, events?,
|
|
19
|
+
reducedMotion?, signInId? })`, which renders a component inside a fake host (jsdom needed).
|
|
20
|
+
|
|
21
|
+
`useSignIn().id` (and `api.signIn.id` in `events` listeners) is an opaque id that stays the same
|
|
22
|
+
for one sign-in and changes on the next one: to do something once per sign-in, store the id you
|
|
23
|
+
acted on with `useClientStorage` and act again when it differs. It is no credential. It is a
|
|
24
|
+
different string per plugin, but not a secret between plugins: client code runs with full trust in
|
|
25
|
+
the page.
|
|
20
26
|
|
|
21
27
|
`CLIENT_API_VERSION` (1) is bumped only when a name is removed or its props change; the host
|
|
22
28
|
accepts a bundle built against its own version.
|
package/dist/context.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ComponentSlotId } from "./slots.generated.js";
|
|
2
|
-
import type { CapybaraEvent, ClientRole, ClientStorage, JsonValue, RunState, UiView } from "./types.js";
|
|
2
|
+
import type { CapybaraEvent, ClientRole, ClientStorage, JsonValue, RunState, SignIn, UiView } from "./types.js";
|
|
3
3
|
/** Thrown by a hook used outside a component the host rendered. */
|
|
4
4
|
export declare class PluginClientContextError extends Error {
|
|
5
5
|
constructor(hook: string);
|
|
@@ -36,6 +36,7 @@ export interface HostApi {
|
|
|
36
36
|
};
|
|
37
37
|
storage: ClientStorage;
|
|
38
38
|
assetUrl(path: string): string;
|
|
39
|
+
signIn: SignIn;
|
|
39
40
|
/** Subscribes to client events; returns the unsubscribe function. */
|
|
40
41
|
subscribe(handler: (e: CapybaraEvent) => void): () => void;
|
|
41
42
|
}
|
package/dist/hooks.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type ActionFn, type ViewState } from "./context.js";
|
|
2
|
-
import type { CapybaraEvent, CapybaraEventType, ClientStorage, RunState } from "./types.js";
|
|
2
|
+
import type { CapybaraEvent, CapybaraEventType, ClientStorage, RunState, SignIn } from "./types.js";
|
|
3
3
|
/** The view the extension registered under this component's id, refreshed like any view. */
|
|
4
4
|
export declare function useView(): ViewState;
|
|
5
5
|
/** Calls the `ctx.ui.action` registered under this component's id. */
|
|
@@ -32,3 +32,8 @@ export declare function useTheme(): {
|
|
|
32
32
|
export declare function useClientStorage(): ClientStorage;
|
|
33
33
|
/** URL of a file under dist/client/assets/ of this plugin's build. */
|
|
34
34
|
export declare function useAssetUrl(): (path: string) => string;
|
|
35
|
+
/**
|
|
36
|
+
* The viewer's sign-in for this plugin: `id` stays the same for one sign-in and changes on the
|
|
37
|
+
* next one (once per sign-in: compare it with the id stored when the thing last ran).
|
|
38
|
+
*/
|
|
39
|
+
export declare function useSignIn(): SignIn;
|
package/dist/hooks.js
CHANGED
|
@@ -54,3 +54,10 @@ export function useClientStorage() {
|
|
|
54
54
|
export function useAssetUrl() {
|
|
55
55
|
return useHost("useAssetUrl").api.assetUrl;
|
|
56
56
|
}
|
|
57
|
+
/**
|
|
58
|
+
* The viewer's sign-in for this plugin: `id` stays the same for one sign-in and changes on the
|
|
59
|
+
* next one (once per sign-in: compare it with the id stored when the thing last ran).
|
|
60
|
+
*/
|
|
61
|
+
export function useSignIn() {
|
|
62
|
+
return useHost("useSignIn").api.signIn;
|
|
63
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export { type ActionFn, PluginClientContextError, type ViewState } from "./context.js";
|
|
2
2
|
export { CLIENT_API_VERSION, type ClientComponent, type ClientExtension, type ClientExtensionDefinition, type ComponentProps, defineClientExtension, defineComponent, } from "./define.js";
|
|
3
3
|
export { Badge, type BadgeProps, Button, type ButtonProps, Icon, type IconProps, Kbd, type KbdProps, KeyValue, type KeyValueProps, Logo, type LogoProps, PropertySection, type PropertySectionProps, Spinner, type SpinnerProps, Stack, type StackProps, Text, type TextProps, Tooltip, type TooltipProps, ViewBlocks, type ViewBlocksProps, } from "./design.js";
|
|
4
|
-
export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useTheme, useView, } from "./hooks.js";
|
|
4
|
+
export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useSignIn, useTheme, useView, } from "./hooks.js";
|
|
5
5
|
export type { ComponentSlotId } from "./slots.generated.js";
|
|
6
|
-
export type { BaseComponentProps, CapybaraEvent, CapybaraEventOf, CapybaraEventType, ClientApi, ClientRole, ClientStorage, EventBase, JsonValue, RunState, SlotComponentProps, UiView, } from "./types.js";
|
|
6
|
+
export type { BaseComponentProps, CapybaraEvent, CapybaraEventOf, CapybaraEventType, ClientApi, ClientRole, ClientStorage, EventBase, JsonValue, RunState, SignIn, SlotComponentProps, UiView, } from "./types.js";
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
export { PluginClientContextError } from "./context.js";
|
|
2
2
|
export { CLIENT_API_VERSION, defineClientExtension, defineComponent, } from "./define.js";
|
|
3
3
|
export { Badge, Button, Icon, Kbd, KeyValue, Logo, PropertySection, Spinner, Stack, Text, Tooltip, ViewBlocks, } from "./design.js";
|
|
4
|
-
export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useTheme, useView, } from "./hooks.js";
|
|
4
|
+
export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useSignIn, useTheme, useView, } from "./hooks.js";
|
package/dist/testing/index.d.ts
CHANGED
|
@@ -20,6 +20,8 @@ export interface FakeHostOptions {
|
|
|
20
20
|
/** Listeners of a client extension's `events`, called on `emit` like in the real host. */
|
|
21
21
|
events?: ClientExtension["events"];
|
|
22
22
|
reducedMotion?: boolean;
|
|
23
|
+
/** The id `useSignIn()` and the listeners' `api.signIn` carry; default "test-sign-in". */
|
|
24
|
+
signInId?: string;
|
|
23
25
|
}
|
|
24
26
|
export interface FakeHost {
|
|
25
27
|
emit(e: CapybaraEvent): void;
|
|
@@ -29,6 +31,6 @@ export interface FakeHost {
|
|
|
29
31
|
}
|
|
30
32
|
/**
|
|
31
33
|
* Renders `element` inside a fake host (what the real host provides per component): the slot, the
|
|
32
|
-
* role, the locale, the run state, the view and the design stand-ins. Needs a DOM (jsdom).
|
|
34
|
+
* role, the locale, the run state, the sign-in, the view and the design stand-ins. Needs a DOM (jsdom).
|
|
33
35
|
*/
|
|
34
36
|
export declare function renderWithFakeHost(element: ReactElement, options: FakeHostOptions): FakeHost;
|
package/dist/testing/index.js
CHANGED
|
@@ -12,7 +12,7 @@ function fakeDesign() {
|
|
|
12
12
|
}
|
|
13
13
|
/**
|
|
14
14
|
* Renders `element` inside a fake host (what the real host provides per component): the slot, the
|
|
15
|
-
* role, the locale, the run state, the view and the design stand-ins. Needs a DOM (jsdom).
|
|
15
|
+
* role, the locale, the run state, the sign-in, the view and the design stand-ins. Needs a DOM (jsdom).
|
|
16
16
|
*/
|
|
17
17
|
export function renderWithFakeHost(element, options) {
|
|
18
18
|
globalThis.IS_REACT_ACT_ENVIRONMENT = true;
|
|
@@ -24,11 +24,13 @@ export function renderWithFakeHost(element, options) {
|
|
|
24
24
|
const storage = createPrefixedStorage(plugin);
|
|
25
25
|
const locale = options.locale ?? "en";
|
|
26
26
|
const assetUrl = (path) => `/api/v1/client/${plugin}/test-build/assets/${path}`;
|
|
27
|
+
const signIn = { id: options.signInId ?? "test-sign-in" };
|
|
27
28
|
const clientApi = {
|
|
28
29
|
locale,
|
|
29
30
|
reducedMotion: options.reducedMotion ?? false,
|
|
30
31
|
storage,
|
|
31
32
|
assetUrl,
|
|
33
|
+
signIn,
|
|
32
34
|
};
|
|
33
35
|
const previousHost = clientHost();
|
|
34
36
|
setClientHost({ design: fakeDesign() });
|
|
@@ -57,6 +59,7 @@ export function renderWithFakeHost(element, options) {
|
|
|
57
59
|
theme: { key: null, scheme: "dark" },
|
|
58
60
|
storage,
|
|
59
61
|
assetUrl,
|
|
62
|
+
signIn,
|
|
60
63
|
subscribe,
|
|
61
64
|
};
|
|
62
65
|
const value = {
|
package/dist/types.d.ts
CHANGED
|
@@ -59,12 +59,23 @@ export type CapybaraEvent = ({
|
|
|
59
59
|
export type CapybaraEventOf<K extends CapybaraEventType> = Extract<CapybaraEvent, {
|
|
60
60
|
type: K;
|
|
61
61
|
}>;
|
|
62
|
+
/**
|
|
63
|
+
* The viewer's sign-in as this plugin sees it. `id` is opaque: the same for one sign-in (every
|
|
64
|
+
* page and tab of it, across token refreshes) and new after the next sign-in, so client code can
|
|
65
|
+
* do something once per sign-in (store the last id it acted on). It is never empty, is no
|
|
66
|
+
* credential and reveals nothing else about the session. It is a different string per plugin, but
|
|
67
|
+
* that is no isolation boundary: client code runs with full trust and can read other plugins' ids.
|
|
68
|
+
*/
|
|
69
|
+
export interface SignIn {
|
|
70
|
+
id: string;
|
|
71
|
+
}
|
|
62
72
|
/** What `events` listeners get (no React context there). */
|
|
63
73
|
export interface ClientApi {
|
|
64
74
|
locale: "zh" | "en";
|
|
65
75
|
reducedMotion: boolean;
|
|
66
76
|
storage: ClientStorage;
|
|
67
77
|
assetUrl(path: string): string;
|
|
78
|
+
signIn: SignIn;
|
|
68
79
|
}
|
|
69
80
|
/** Props every component receives, plus its slot's own. */
|
|
70
81
|
export interface BaseComponentProps {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@capybara-hq/plugin-client",
|
|
3
|
-
"version": "0.1.0-rc.
|
|
3
|
+
"version": "0.1.0-rc.3",
|
|
4
4
|
"description": "Capybara plugin client SDK: the types, hooks and design re-exports a plugin's client entry is written against",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|