@codenotch/codenotch.react 1.0.81

package/src/models/Codenotch.ts

@@ -0,0 +1,285 @@
+import { ProjectManifest } from "@codenotch/codenotch.core";
+import { ICodenotchSignal, IDisposable } from "./Misc";
+import { ApplicationManifest } from "./AppManifestModels";
+
+/**
+ * Runtime environment of a Codenotch application.
+ *
+ * Populated by `init()` from the environment variables injected by the Codenotch
+ * runtime into the hosting page, and exposed read-only through {@link ICodenotchApi.env}.
+ */
+export interface ICodenotchEnv {
+    /** Name of the current application. */
+    appName?: string;
+    /** Base URL of the Codenotch cluster hosting the project, e.g. `https://cluster.example.com`. */
+    clusterUrl?: string;
+    /** Service name of the project (`serviceName` in the project's `manifest.json`). Used to build every server URL. */
+    serviceName?: string;
+    /** Name of the tenant hosting the project. Required when authenticating with an access token. */
+    tenantName?: string;
+    /** Access token used to authenticate server calls, sent as the `<tenantName>AccessToken` HTTP header. */
+    accessToken?: string;
+    /** Base URL of the current application. */
+    baseUrl?: string;
+    /** Translation dictionaries, keyed by language then by translation key: `i18n[language][key] = text`. */
+    i18n?: { [language: string]: { [key: string]: string } };
+    /** Current language code (e.g. `"en"`). Defaults to the first language found in {@link i18n}. */
+    language?: string;
+    /** Current UI theme. Resolved from the `_theme` URL parameter, or `prefers-color-scheme` as a fallback. */
+    theme?: 'light' | 'dark';
+
+    /** Manifest of the current application (the `<AppName>.manifest.json` file next to the app). */
+    appManifest?: ApplicationManifest;
+    /** Manifest of the Codenotch project (the project's `manifest.json` file). */
+    projectManifest?: ProjectManifest;
+
+    /** Any additional environment variable passed to `init()`. */
+    [key: string]: any; // Allow additional properties
+}
+
+
+/**
+ * Registry of the project's BPMN processes, used to type {@link ICodenotchApi.startProcess}.
+ *
+ * Empty by default: the Codenotch IDE fills it through declaration merging in the
+ * auto-generated `typings/process.d.ts` file of each project, with one entry per
+ * BPMN process. Each entry maps the process name to its start events (`nodes`,
+ * keyed by start node id, valued with the start event's input parameters) and to
+ * the `output` of its end event.
+ *
+ * When the registry has not been augmented (project built without the IDE
+ * typings), `startProcess` falls back to plain string names and untyped inputs,
+ * so the code still compiles.
+ *
+ * @example
+ * // typings/process.d.ts (auto-generated by the Codenotch IDE)
+ * import 'codenotch-react';
+ * declare module 'codenotch-react' {
+ *     interface ProcessRegistry {
+ *         'getTodos': {
+ *             nodes: { 'start': { UserId: string } };
+ *             output: { todos: any[] };
+ *         };
+ *     }
+ * }
+ */
+export interface ProcessRegistry {
+    // Extended by codenotch IDE
+}
+
+/**
+ * Registry of the project's translation keys, used to type {@link ICodenotchApi.i18n}.
+ *
+ * Empty by default: the Codenotch IDE fills it through declaration merging in the
+ * auto-generated `typings/i18n.d.ts` file of each project, from the project's
+ * `.i18n.csv` files. Each entry maps a translation key to the tuple of arguments
+ * expected by its `{0}`, `{1}`, … placeholders.
+ *
+ * When the registry has not been augmented (project built without the IDE
+ * typings), `i18n` falls back to plain string keys and untyped arguments,
+ * so the code still compiles.
+ *
+ * @example
+ * // typings/i18n.d.ts (auto-generated by the Codenotch IDE)
+ * import 'codenotch-react';
+ * declare module 'codenotch-react' {
+ *     interface TranslationRegistry {
+ *         'welcome': [];
+ *         'greeting': [arg1: any, arg2: any];
+ *     }
+ * }
+ */
+export interface TranslationRegistry {
+    // Extended by codenotch IDE
+}
+
+// When the codenotch IDE has not augmented the registries, `keyof Registry` is `never`
+// and every call would fail to compile. These helpers fall back to plain string keys
+// and untyped arguments so the API stays usable without code generation.
+
+/** A BPMN process name: a key of {@link ProcessRegistry}, or any string when the registry is empty. */
+export type ProcessName = keyof ProcessRegistry extends never ? string : keyof ProcessRegistry;
+
+/** The start nodes of process `P`: its `nodes` map from {@link ProcessRegistry}, or an open map when unknown. */
+export type ProcessNodes<P> = P extends keyof ProcessRegistry
+    ? ProcessRegistry[P] extends { nodes: infer N } ? N : { [nodeId: string]: any }
+    : { [nodeId: string]: any };
+
+/** The end-event output of process `P` from {@link ProcessRegistry}, or `any` when unknown. */
+export type ProcessOutput<P> = P extends keyof ProcessRegistry
+    ? ProcessRegistry[P] extends { output: infer O } ? O : any
+    : any;
+
+/** A translation key: a key of {@link TranslationRegistry}, or any string when the registry is empty. */
+export type TranslationKey = keyof TranslationRegistry extends never ? string : keyof TranslationRegistry;
+
+/** The placeholder arguments of translation key `K` from {@link TranslationRegistry}, or `any[]` when unknown. */
+export type TranslationArgs<K> = K extends keyof TranslationRegistry
+    ? TranslationRegistry[K] extends any[] ? TranslationRegistry[K] : any[]
+    : any[];
+
+
+/**
+ * Result of a BPMN process execution started with {@link ICodenotchApi.startProcess}.
+ */
+export interface IProcessResult<T = any> {
+
+    /** Unique id of this execution of the process. */
+    processInstanceId: string;
+    /** Output parameters of the end event reached by the process. */
+    output: T;
+    /** `true` if the process ended in error; check it before reading {@link output}. */
+    isError: boolean;
+    /** Error details when {@link isError} is `true`. */
+    errorMessage: string;
+}
+
+/**
+ * The Codenotch client API, obtained by calling `useCodenotch()`.
+ *
+ * It is the bridge between a React app and the Codenotch runtime: it starts
+ * server-side BPMN processes, runs SioQL queries, translates i18n keys,
+ * listens to real-time signals and manages theme/language.
+ *
+ * @example
+ * import { useCodenotch } from 'codenotch-react';
+ *
+ * const cn = useCodenotch();
+ * const title = cn.i18n('welcome');
+ * const result = await cn.startProcess('getTodos', 'start', { UserId: '42' });
+ */
+export interface ICodenotchApi {
+
+    /**
+     * Start a server-side BPMN process and wait for its completion.
+     *
+     * @param processName Name of the process — the `.bpmn` file name without extension (e.g. `processes/getTodos.bpmn` → `'getTodos'`).
+     * @param startNodeId Id of the start event to trigger (conventionally `'start'`).
+     * @param inputs Input parameters declared by that start event.
+     * @returns The process result; check `isError` before using `output` (the parameters of the end event reached).
+     * @example
+     * const result = await cn.startProcess('getTodos', 'start', { UserId: userId });
+     * if (!result.isError) {
+     *     setTodos(result.output.todos);
+     * }
+     */
+    startProcess<P extends ProcessName, N extends keyof ProcessNodes<P>>(
+        processName: P,
+        startNodeId: N,
+        inputs: ProcessNodes<P>[N]
+    ): Promise<IProcessResult<ProcessOutput<P>>>;
+
+    /**
+     * Translate a key for the current language ({@link ICodenotchEnv.language}).
+     *
+     * Placeholders `{0}`, `{1}`, … in the translated text are replaced by `args`.
+     * Never throws: if the key or the language is missing, a warning is logged
+     * and the key itself is returned.
+     *
+     * @param key Translation key, as defined in the project's `.i18n.csv` files.
+     * @param args Values for the `{0}`, `{1}`, … placeholders of the translation.
+     * @example
+     * cn.i18n('welcome');                    // "Bienvenue"
+     * cn.i18n('greeting', 'Fabian', 3);      // "Bonjour Fabian, 3 messages" (from "Bonjour {0}, {1} messages")
+     */
+    i18n<K extends TranslationKey>(
+        key: K,
+        ...args: TranslationArgs<K>
+    ): string;
+
+    /** Runtime environment (cluster, service, language, theme, i18n dictionaries, manifests…). Populated by `init()`. */
+    readonly env: ICodenotchEnv;
+
+    /**
+     * Execute a SioQL query (XML, SELECT-only) against the project's SQL tables and return the parsed JSON result.
+     *
+     * The root element's `xmlns` must be the project's `serviceName`. Results are
+     * keyed by the `Ref` attribute of each queried table.
+     *
+     * @param sioql The SioQL XML query.
+     * @param verbose When `true`, asks the server for a verbose response (debugging).
+     * @example
+     * const data = await cn.requestSioql(`
+     *     <SioQL xmlns="myproject" PageSize="10" PageIndex="0">
+     *         <Users Ref="results">
+     *             <Id />
+     *             <Email />
+     *         </Users>
+     *     </SioQL>`);
+     * console.log(data.results); // [{ Id: ..., Email: ... }, ...]
+     */
+    readonly requestSioql: (sioql: string, verbose?: boolean) => Promise<any>;
+
+    /**
+     * Render the given React element in a fullscreen modal `<dialog>` overlay.
+     *
+     * The dialog is not closed automatically: keep the returned handle and call
+     * its `close()` method (typically from a button inside the dialog content).
+     *
+     * @example
+     * const dialog = cn.showDialog(
+     *     <div className="bg-white p-4 rounded">
+     *         <p>Are you sure?</p>
+     *         <button onClick={() => dialog.close()}>Close</button>
+     *     </div>
+     * );
+     */
+    readonly showDialog: (node: JSX.Element) => ICodenotchDialog;
+
+    /**
+     * Fetch the text content of a file of the deployed Codenotch project.
+     * @param relativePath Path of the file relative to the project root (e.g. `'readme.md'`).
+     */
+    readonly getProjectFile: (relativePath: string) => Promise<string | undefined>;
+
+    /**
+     * Build the URL serving a file of the deployed Codenotch project
+     * (useful as `src` for images or links).
+     * @param relativePath Path of the file relative to the project root.
+     */
+    readonly getProjectFileUrl: (relativePath: string) => string;
+
+    /**
+     * Subscribe to a real-time signal emitted by the project's BPMN processes (via SignalR).
+     *
+     * @param signalId Id of the signal, as declared in the BPMN process.
+     * @param callback Called each time the signal is received, with `{ signalId, data }`.
+     * @returns A disposable — call `dispose()` to unsubscribe (e.g. in a `useEffect` cleanup).
+     * @example
+     * useEffect(() => {
+     *     let sub: IDisposable | undefined;
+     *     cn.listenSignal('todosChanged', () => refresh()).then(s => sub = s);
+     *     return () => sub?.dispose();
+     * }, []);
+     */
+    readonly listenSignal: (signalId: string, callback: (data: ICodenotchSignal) => void) => Promise<IDisposable>;
+
+    /** Set the UI theme. Also toggles the `light`/`dark` class on `<html>` (Tailwind `dark:` variants). */
+    readonly setTheme: (theme: 'light' | 'dark') => void;
+    /** Current UI theme, if resolved. */
+    readonly getTheme: () => 'light' | 'dark' | undefined;
+    /** Set the current language used by {@link i18n}. Must be one of the project's languages. */
+    readonly setLanguage: (lang: string) => void;
+    /** Current language code, if any. */
+    readonly getLanguage: () => string | undefined;
+    /** Languages declared in the project's `manifest.json`. */
+    readonly getLanguages: () => string[];
+    /** Query-string parameters of the current URL, as a plain object (first value wins for duplicated keys). */
+    readonly getUrlParams: () => { [key: string]: string };
+    /** Generate a random UUID v4. */
+    readonly uuid: () => string;
+    /** Manifest of the Codenotch project. Throws if not available in the environment. */
+    readonly getProjectManifest: () => ProjectManifest;
+    /** Manifest of the current application, if any. */
+    readonly getAppManifest: () => ApplicationManifest | undefined;
+}
+
+/**
+ * Handle on a dialog opened with {@link ICodenotchApi.showDialog}.
+ */
+export interface ICodenotchDialog {
+    /** DOM id of the underlying `<dialog>` element. */
+    id: string;
+    /** Close the dialog and remove it from the DOM. */
+    close: () => void;
+}

package/src/models/Misc.ts

@@ -0,0 +1,32 @@
+import { IProcessResult } from "./Codenotch";
+
+/**
+ * Internal callbacks used while a BPMN process instance is running.
+ */
+export interface IProcessCallbacks
+{
+    /** Called once when the process instance completes (successfully or not). */
+    onOver: (processResult: IProcessResult) => void,
+    /** Called for each intermediate callback emitted by the process. */
+    onCallback:( callback: any) => void
+}
+
+/**
+ * A real-time signal emitted by a BPMN process,
+ * received through `useCodenotch().listenSignal()`.
+ */
+export interface ICodenotchSignal
+{
+    /** Id of the signal, as declared in the BPMN process. */
+    signalId: string;
+    /** Payload attached to the signal by the process. */
+    data: any;
+}
+
+/**
+ * A subscription that can be released.
+ */
+export interface IDisposable {
+    /** Release the subscription (e.g. stop listening to a signal). */
+    dispose: () => void;
+}