Skip to content

Commit f3777b1

Browse files
author
John Tore Simonsen
committed
Merge branch 'verji-main' of https://github.com/verji/matrix-react-sdk-module-api into verji-main
2 parents 69ef44a + ac428aa commit f3777b1

File tree

80 files changed

+3868
-3293
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+3868
-3293
lines changed

‎lib/ModuleApi.d.ts

Lines changed: 132 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,132 +1,132 @@
1-
import React from "react";
2-
import { PlainSubstitution, TranslationStringsObject } from "./types/translations";
3-
import { DialogContent, DialogProps } from "./components/DialogContent";
4-
import { AccountAuthInfo } from "./types/AccountAuthInfo";
5-
import { ModuleUiDialogOptions } from "./types/ModuleUiDialogOptions";
6-
import { App } from "./types/App";
7-
import { Container } from "./types/Container";
8-
/**
9-
* A module API surface for the react-sdk. Provides a stable API for modules to
10-
* interact with the internals of the react-sdk without having to update themselves
11-
* for refactorings or code changes within the react-sdk.
12-
*
13-
* An instance of a ModuleApi is provided to all modules at runtime.
14-
*/
15-
export interface ModuleApi {
16-
/**
17-
* Register strings with the translation engine. This supports overriding strings which
18-
* the system is already aware of.
19-
* @param translations The translations to load.
20-
*/
21-
registerTranslations(translations: TranslationStringsObject): void;
22-
/**
23-
* Runs a string through the translation engine. If variables are needed, use %(varName)s
24-
* as a placeholder for varName in the variables object.
25-
* @param s The string. Should already be known to the engine.
26-
* @param variables The variables to replace, if any.
27-
* @returns The translated string.
28-
*/
29-
translateString(s: string, variables?: Record<string, PlainSubstitution>): string;
30-
/**
31-
* Opens a dialog in the client.
32-
* @param initialTitleOrOptions Initial options for the dialog. Can be the title of the dialog, or a
33-
* configuration object. Note that the dialog implementation may later
34-
* modify its own options via the {@link DialogProps.setOptions} callback.
35-
* @param body The function which creates a body component for the dialog.
36-
* @param props Optional props to provide to {@link body}, in addition to the common set in {@link DialogProps}.
37-
* @returns Whether the user submitted the dialog or closed it, and the model returned by the
38-
* dialog component if submitted.
39-
*/
40-
openDialog<M extends object, P extends DialogProps = DialogProps, C extends DialogContent<P> = DialogContent<P>>(initialTitleOrOptions: string | ModuleUiDialogOptions, body: (props: P, ref: React.RefObject<C>) => React.ReactNode, props?: Omit<P, keyof DialogProps>): Promise<{
41-
didOkOrSubmit: boolean;
42-
model: M;
43-
}>;
44-
/**
45-
* Registers for an account on the currently connected homeserver. This requires that the homeserver
46-
* offer a password-only flow without other flows. This means it is not traditionally compatible with
47-
* homeservers like matrix.org which also generally require a combination of reCAPTCHA, email address,
48-
* terms of service acceptance, etc.
49-
* @param username The username to register.
50-
* @param password The password to register.
51-
* @param displayName Optional display name to set.
52-
* @returns Resolves to the authentication info for the created account.
53-
*/
54-
registerSimpleAccount(username: string, password: string, displayName?: string): Promise<AccountAuthInfo>;
55-
/**
56-
* Switches the user's currently logged-in account to the one specified. The user will not
57-
* be warned.
58-
* @param accountAuthInfo The authentication info to log in with.
59-
* @returns Resolves when complete.
60-
*/
61-
overwriteAccountAuth(accountAuthInfo: AccountAuthInfo): Promise<void>;
62-
/**
63-
* Switches the user's current view to look at the given permalink. If the permalink is
64-
* a room, it can optionally be joined automatically if required.
65-
*
66-
* Permalink must be a matrix.to permalink at this time.
67-
* @param uri The URI to navigate to.
68-
* @param andJoin True to also join the room if needed. Does nothing if the link isn't to
69-
* a room.
70-
* @returns Resolves when complete.
71-
*/
72-
navigatePermalink(uri: string, andJoin?: boolean): Promise<void>;
73-
/**
74-
* Gets a value verbatim from the config. The returned value will be of the type specified
75-
* by the user - it is not verified against a schema. If the value does not exist in the
76-
* config then this will return undefined;
77-
*
78-
* The caller should provide a namespace which it owns to retrieve settings from. During
79-
* read, the `key` will be treated as a sub-key of the namespace on the overall configuration
80-
* object. For example:
81-
*
82-
* ```json
83-
* {
84-
* "inaccessible_root_level_config": "hello world",
85-
* "org.example.my_module_namespace": {
86-
* "my_key": 42
87-
* }
88-
* }
89-
* ```
90-
*
91-
* The caller would use `getConfigValue<number>("org.example.my_module_namespace", "my_key")`
92-
* to get the targeted config value.
93-
*
94-
* There is no root namespace, thus root-level config values cannot be read.
95-
* @param namespace The module's namespace.
96-
* @param key The key to look up.
97-
* @returns The config value verbatim.
98-
*/
99-
getConfigValue<T>(namespace: string, key: string): T | undefined;
100-
/**
101-
* Gets the apps for a given room.
102-
*
103-
* @param roomId The room ID to get the apps for.
104-
* @returns The apps for the given room.
105-
*/
106-
getApps(roomId: string): Array<App>;
107-
/**
108-
* Gets the avatar URL for an app.
109-
*
110-
* @param app The app to get the avatar URL for.
111-
* @param width The width of the avatar.
112-
* @param height The height of the avatar.
113-
* @param resizeMethod The resize method to use, either "crop" or "scale".
114-
*/
115-
getAppAvatarUrl(app: App, width?: number, height?: number, resizeMethod?: string): string | null;
116-
/**
117-
* Checks if an app is in a container for a given room.
118-
*
119-
* @param app The app to check.
120-
* @param container The container to check.
121-
* @param roomId The room ID to check.
122-
*/
123-
isAppInContainer(app: App, container: Container, roomId: string): boolean;
124-
/**
125-
* Moves apps to containers for a given room.
126-
*
127-
* @param app The app to move.
128-
* @param container The container to move the app to.
129-
* @param roomId The room ID to move the app in.
130-
*/
131-
moveAppToContainer(app: App, container: Container, roomId: string): void;
132-
}
1+
import React from "react";
2+
import { PlainSubstitution, TranslationStringsObject } from "./types/translations";
3+
import { DialogContent, DialogProps } from "./components/DialogContent";
4+
import { AccountAuthInfo } from "./types/AccountAuthInfo";
5+
import { ModuleUiDialogOptions } from "./types/ModuleUiDialogOptions";
6+
import { App } from "./types/App";
7+
import { Container } from "./types/Container";
8+
/**
9+
* A module API surface for the react-sdk. Provides a stable API for modules to
10+
* interact with the internals of the react-sdk without having to update themselves
11+
* for refactorings or code changes within the react-sdk.
12+
*
13+
* An instance of a ModuleApi is provided to all modules at runtime.
14+
*/
15+
export interface ModuleApi {
16+
/**
17+
* Register strings with the translation engine. This supports overriding strings which
18+
* the system is already aware of.
19+
* @param translations The translations to load.
20+
*/
21+
registerTranslations(translations: TranslationStringsObject): void;
22+
/**
23+
* Runs a string through the translation engine. If variables are needed, use %(varName)s
24+
* as a placeholder for varName in the variables object.
25+
* @param s The string. Should already be known to the engine.
26+
* @param variables The variables to replace, if any.
27+
* @returns The translated string.
28+
*/
29+
translateString(s: string, variables?: Record<string, PlainSubstitution>): string;
30+
/**
31+
* Opens a dialog in the client.
32+
* @param initialTitleOrOptions Initial options for the dialog. Can be the title of the dialog, or a
33+
* configuration object. Note that the dialog implementation may later
34+
* modify its own options via the {@link DialogProps.setOptions} callback.
35+
* @param body The function which creates a body component for the dialog.
36+
* @param props Optional props to provide to {@link body}, in addition to the common set in {@link DialogProps}.
37+
* @returns Whether the user submitted the dialog or closed it, and the model returned by the
38+
* dialog component if submitted.
39+
*/
40+
openDialog<M extends object, P extends DialogProps = DialogProps, C extends DialogContent<P> = DialogContent<P>>(initialTitleOrOptions: string | ModuleUiDialogOptions, body: (props: P, ref: React.RefObject<C>) => React.ReactNode, props?: Omit<P, keyof DialogProps>): Promise<{
41+
didOkOrSubmit: boolean;
42+
model: M;
43+
}>;
44+
/**
45+
* Registers for an account on the currently connected homeserver. This requires that the homeserver
46+
* offer a password-only flow without other flows. This means it is not traditionally compatible with
47+
* homeservers like matrix.org which also generally require a combination of reCAPTCHA, email address,
48+
* terms of service acceptance, etc.
49+
* @param username The username to register.
50+
* @param password The password to register.
51+
* @param displayName Optional display name to set.
52+
* @returns Resolves to the authentication info for the created account.
53+
*/
54+
registerSimpleAccount(username: string, password: string, displayName?: string): Promise<AccountAuthInfo>;
55+
/**
56+
* Switches the user's currently logged-in account to the one specified. The user will not
57+
* be warned.
58+
* @param accountAuthInfo The authentication info to log in with.
59+
* @returns Resolves when complete.
60+
*/
61+
overwriteAccountAuth(accountAuthInfo: AccountAuthInfo): Promise<void>;
62+
/**
63+
* Switches the user's current view to look at the given permalink. If the permalink is
64+
* a room, it can optionally be joined automatically if required.
65+
*
66+
* Permalink must be a matrix.to permalink at this time.
67+
* @param uri The URI to navigate to.
68+
* @param andJoin True to also join the room if needed. Does nothing if the link isn't to
69+
* a room.
70+
* @returns Resolves when complete.
71+
*/
72+
navigatePermalink(uri: string, andJoin?: boolean): Promise<void>;
73+
/**
74+
* Gets a value verbatim from the config. The returned value will be of the type specified
75+
* by the user - it is not verified against a schema. If the value does not exist in the
76+
* config then this will return undefined;
77+
*
78+
* The caller should provide a namespace which it owns to retrieve settings from. During
79+
* read, the `key` will be treated as a sub-key of the namespace on the overall configuration
80+
* object. For example:
81+
*
82+
* ```json
83+
* {
84+
* "inaccessible_root_level_config": "hello world",
85+
* "org.example.my_module_namespace": {
86+
* "my_key": 42
87+
* }
88+
* }
89+
* ```
90+
*
91+
* The caller would use `getConfigValue<number>("org.example.my_module_namespace", "my_key")`
92+
* to get the targeted config value.
93+
*
94+
* There is no root namespace, thus root-level config values cannot be read.
95+
* @param namespace The module's namespace.
96+
* @param key The key to look up.
97+
* @returns The config value verbatim.
98+
*/
99+
getConfigValue<T>(namespace: string, key: string): T | undefined;
100+
/**
101+
* Gets the apps for a given room.
102+
*
103+
* @param roomId The room ID to get the apps for.
104+
* @returns The apps for the given room.
105+
*/
106+
getApps(roomId: string): Array<App>;
107+
/**
108+
* Gets the avatar URL for an app.
109+
*
110+
* @param app The app to get the avatar URL for.
111+
* @param width The width of the avatar.
112+
* @param height The height of the avatar.
113+
* @param resizeMethod The resize method to use, either "crop" or "scale".
114+
*/
115+
getAppAvatarUrl(app: App, width?: number, height?: number, resizeMethod?: string): string | null;
116+
/**
117+
* Checks if an app is in a container for a given room.
118+
*
119+
* @param app The app to check.
120+
* @param container The container to check.
121+
* @param roomId The room ID to check.
122+
*/
123+
isAppInContainer(app: App, container: Container, roomId: string): boolean;
124+
/**
125+
* Moves apps to containers for a given room.
126+
*
127+
* @param app The app to move.
128+
* @param container The container to move the app to.
129+
* @param roomId The room ID to move the app in.
130+
*/
131+
moveAppToContainer(app: App, container: Container, roomId: string): void;
132+
}

‎lib/ModuleApi.js

Lines changed: 2 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎lib/ModuleApi.js.map

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)