@tiny-server/core 0.0.0

package/dist/app/features/modals/types.d.ts

@@ -0,0 +1,84 @@
+import { ComponentType } from 'react';
+import { ModalProps } from './Modal';
+import { ModalBodyProps } from './ModalBody';
+import { ModalFooterProps } from './ModalFooter';
+import { ModalHeaderProps } from './ModalHeader';
+declare module '../../types' {
+    interface AppInstance {
+        /**
+         * Shows a registered modal window.
+         * @param name The name of the modal to be shown.
+         * @param params The parameters to be passed to the modal.
+         */
+        showModal<TModalName extends ModalName>(name: TModalName, params: ModalParams<TModalName>): void;
+    }
+    interface AppComponents {
+        Modal: ComponentType<ModalProps>;
+        ModalBody: ComponentType<ModalBodyProps>;
+        ModalFooter: ComponentType<ModalFooterProps>;
+        ModalHeader: ComponentType<ModalHeaderProps>;
+    }
+}
+/**
+ * A map of all known modals.
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface ModalParamsMap {
+ *     'my-modal': MyModalParams;
+ *   }
+ * }
+ * ```
+ */
+export interface ModalParamsMap {
+    '': never;
+}
+/**
+ * Defines all known modal types.
+ */
+export type ModalName = keyof ModalParamsMap;
+/**
+ * The parameters of the modal with the given `TName`.
+ */
+export type ModalParams<TName extends ModalName> = ModalParamsMap[TName];
+export interface ModalComponentProps<TName extends ModalName> {
+    /**
+     * The modal name.
+     */
+    name: TName;
+    /**
+     * The parameters to be forwarded to the modal component.
+     */
+    params: ModalParams<TName>;
+    /**
+     * Closes/unmounts the modal.
+     */
+    onClose(): void;
+}
+/**
+ * Optional configuration values for the modal container.
+ */
+export interface ModalOptions {
+    /**
+     * The modal's size.
+     */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto' | (string & {});
+}
+export interface ModalRegistration<TName extends ModalName> {
+    /**
+     * The name of the modal to be registered.
+     */
+    name: TName;
+    /**
+     * Optional configuration values for the modal container.
+     */
+    options?: ModalOptions;
+    /**
+     * The component to be rendered for the modal.
+     */
+    component: ComponentType<ModalComponentProps<TName>>;
+}
+export type AnyModalRegistration = {
+    [Key in ModalName]: ModalRegistration<Key>;
+}[ModalName];

package/dist/app/features/query/AppQueryClientProvider.d.ts

@@ -0,0 +1,2 @@
+import { PropsWithChildren } from 'react';
+export declare function AppQueryClientProvider({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/query/client.d.ts

@@ -0,0 +1,2 @@
+import { QueryClient } from '@tanstack/react-query';
+export declare const queryClient: QueryClient;

package/dist/app/features/query/index.d.ts

@@ -0,0 +1,3 @@
+export * from './AppQueryClientProvider';
+export * from './initializer';
+export * from './types';

package/dist/app/features/query/initializer.d.ts

@@ -0,0 +1,2 @@
+import { AppInitializer } from '../../types';
+export declare const queryInitializer: AppInitializer;

package/dist/app/features/query/types.d.ts

@@ -0,0 +1,9 @@
+import { QueryClient } from '@tanstack/react-query';
+declare module '../../types' {
+    interface AppInstance {
+        /**
+         * The application's central {@link QueryClient} instance.
+         */
+        queryClient: QueryClient;
+    }
+}

package/dist/app/features/router/AppLayout.d.ts

@@ -0,0 +1 @@
+export declare function AppLayout(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/router/AppRouteLayout.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The app's top-level route layout.
+ * Acts as a suspense and error boundary for all routes.
+ */
+export declare function AppRouteLayout(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/router/AppRouter.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Renders the app's router based on the app configuration.
+ */
+export declare function AppRouter(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/router/RouterErrorBoundary.d.ts

@@ -0,0 +1 @@
+export declare function RouterErrorBoundary(): import("react/jsx-runtime").JSX.Element;

package/dist/app/features/router/context.d.ts

@@ -0,0 +1,5 @@
+import { AppInstance } from '../../types';
+/**
+ * A router context which grants access to current {@link AppInstance}.
+ */
+export declare const appContext: import('react-router').RouterContext<AppInstance>;

package/dist/app/features/router/index.d.ts

@@ -0,0 +1,3 @@
+export * from './AppRouter';
+export * from './context';
+export * from './middlewares';

package/dist/app/features/router/middlewares.d.ts

@@ -0,0 +1,42 @@
+import { MiddlewareFunction } from 'react-router';
+import { Permission } from '../../../api';
+export interface RequireSessionMiddlewareOptions {
+    /**
+     * The URL to which an anonymous user should be redirected to.
+     * @default '/'
+     */
+    redirectUrl?: string;
+    /**
+     * A set of permissions which are required to access the route.
+     */
+    permissions?: Array<Permission>;
+    /**
+     * A custom callback which allows custom handling of unauthorized access errors, i.e., situations
+     * where no active session exists.
+     * If not provided, the middleware will redirect to {@link redirectUrl}.
+     */
+    onUnauthorized?: () => void | Promise<void>;
+    /**
+     * A custom callback which allows custom handling of forbidden access errors, i.e., situations
+     * where the user session does not have the required permissions.
+     * If not provided, the middleware will throw a `403` data error.
+     */
+    onForbidden?: () => void | Promise<void>;
+}
+/**
+ * Creates a router middleware function which ensures that an active user session exists.
+ * If no session exists, the user is redirected to {@link RequireSessionMiddlewareOptions#redirectUrl}.
+ */
+export declare function requireSession({ redirectUrl, permissions, onUnauthorized, onForbidden, }?: RequireSessionMiddlewareOptions): MiddlewareFunction;
+export interface RequireAnonymousMiddlewareOptions {
+    /**
+     * The URL to which a logged in user should be redirected to.
+     * @default '/'
+     */
+    redirectUrl?: string;
+}
+/**
+ * Creates a router middleware function which ensures that no user session exists.
+ * If a session exists, the user is redirected to {@link RequireAnonymousMiddlewareOptions#redirectUrl}.
+ */
+export declare function requireAnonymous({ redirectUrl }?: RequireAnonymousMiddlewareOptions): MiddlewareFunction;

package/dist/app/index.d.ts

@@ -0,0 +1,5 @@
+export * from './features';
+export * from './App';
+export { useApp } from './context';
+export * from './create';
+export * from './types';

package/dist/app/types.d.ts

@@ -0,0 +1,78 @@
+import { RouteObject } from 'react-router';
+import { AnyExtensionRegistration } from './features/extensions';
+import { AnyMenuItemRegistration } from './features/menu';
+import { AnyModalRegistration } from './features/modals';
+import { ComponentType, PropsWithChildren } from 'react';
+/**
+ * Represents an instance of a configured application.
+ * {@link AppInstance} objects provide the app's central orchestration API.
+ */
+export interface AppInstance {
+    /**
+     * The set of modules which make up this application instance.
+     */
+    modules: Array<Module>;
+    /**
+     * A set of application specific components.
+     */
+    components: AppComponents;
+}
+/**
+ * Represents a set of configurable components which can be declared by modules
+ * and used by any component that has access to the application instance.
+ *
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface AppComponents {
+ *     MyComponent: ComponentType<MyComponentProps>;
+ *   }
+ * }
+ * ```
+ */
+export interface AppComponents {
+}
+/**
+ * An initializer function which can be registered as part of a module configuration.
+ *
+ * App initializers are called during app creation, receiving an {@link AppInstance}.
+ * They can perform any necessary setup or (re-)configuration of the app instance.
+ *
+ * App initializers *may* mutate the given app instance.
+ */
+export type AppInitializer = (app: AppInstance) => AppInstance | void;
+/**
+ * Initialization values for {@link Module} objects.
+ */
+export type ModuleInit = Partial<Module>;
+/**
+ * Represents an application module.
+ */
+export interface Module {
+    /**
+     * Module-provided {@link AppInitializer} functions.
+     */
+    appInitializers: Array<AppInitializer>;
+    /**
+     * Module-provided provider components.
+     * These are rendered at the very top of the app's component tree.
+     */
+    providers: Array<ComponentType<PropsWithChildren>>;
+    /**
+     * Module-provided routes.
+     */
+    routes: Array<RouteObject>;
+    /**
+     * Module-provided extensions.
+     */
+    extensions: Array<AnyExtensionRegistration>;
+    /**
+     * Module-provided menu items.
+     */
+    menuItems: Array<AnyMenuItemRegistration>;
+    /**
+     * Module-provided modals.
+     */
+    modals: Array<AnyModalRegistration>;
+}

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,19 @@
+import { Component, PropsWithChildren, ReactNode } from 'react';
+interface State {
+    hasError: boolean;
+}
+export interface ErrorBoundaryProps extends PropsWithChildren {
+    /**
+     * The fallback to render when an error is caught.
+     */
+    fallback?: ReactNode;
+}
+/**
+ * A generic error boundary component which renders a fallback when an error is caught.
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(): State;
+    render(): ReactNode;
+}
+export {};

package/dist/components/WithPermissions.d.ts

@@ -0,0 +1,30 @@
+import { ComponentType, ReactNode } from 'react';
+import { Permission } from '../api';
+export interface WithPermissionsProps {
+    /**
+     * The required permissions.
+     * @default []
+     */
+    permissions?: Array<Permission>;
+    /**
+     * The operator to use for checking permissions.
+     * @default 'and'
+     */
+    operator?: 'and' | 'or';
+    /**
+     * The content to render when the user has the required permissions.
+     */
+    children?: ReactNode;
+    /**
+     * The content to render when the user is lacking the required permissions.
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Renders content depending on whether the users has one or more given permissions.
+ */
+export declare function WithPermissions({ permissions, operator, children, fallback }: WithPermissionsProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Wraps the given component in a {@link WithPermissions} component.
+ */
+export declare function withPermissions<T extends object>(withPermissionProps: Omit<WithPermissionsProps, 'children'>, WrappedComponent: ComponentType<T>): ComponentType<T>;

package/dist/components/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ErrorBoundary';
+export * from './WithPermissions';

package/dist/fetch.d.ts

@@ -0,0 +1,84 @@
+import { ProblemDetails } from './api';
+/**
+ * Arguments for making an HTTP request using {@link appFetch}.
+ */
+export interface AppFetchArgs<TResult = void> extends Omit<RequestInit, 'body'> {
+    /**
+     * The base URL to be used for the request.
+     * @default window.location.origin
+     */
+    baseUrl?: string;
+    /**
+     * The request URL.
+     */
+    url: string;
+    /**
+     * The body of the request.
+     * This body is, by default, automatically serialized as JSON **unless** the `Content-Type` header
+     * is set to a value other than `application/json`.
+     */
+    body?: BodyInit | object;
+    /**
+     * Additional query parameters to be appended to the URL.
+     * If set, these overwrite existing query parameters in {@link url} with the same name.
+     */
+    params?: AppFetchQueryParams;
+    /**
+     * Defines the handler which should be used to parse the response.
+     * @default 'json'
+     */
+    responseHandler?: DefaultResponseHandler | AppFetchResponseHandler<TResult>;
+    /**
+     * Defines the validators which should be used to validate the response.
+     * @default ['statusOk']
+     */
+    responseValidators?: Array<DefaultResponseValidator | AppFetchResponseValidator<TResult>>;
+}
+/**
+ * Supported query param types.
+ */
+export type AppFetchQueryParams = Record<string, any>;
+/**
+ * Represents a function which handles/processes a {@link Response} object.
+ * These handlers are supposed
+ */
+export type AppFetchResponseHandler<TResult = void> = (response: Response) => Promise<TResult>;
+/**
+ * Represents a function which validates that a response produced by {@link appFetch} is valid.
+ */
+export type AppFetchResponseValidator<TResult = void> = (response: Response, result: TResult) => Promise<void>;
+declare const defaultResponseHandlers: {
+    json: (response: Response) => Promise<any>;
+};
+declare const defaultResponseValidators: {
+    statusOk: (response: Response, result: unknown) => Promise<void>;
+};
+export type DefaultResponseHandler = keyof typeof defaultResponseHandlers;
+export type DefaultResponseValidator = keyof typeof defaultResponseValidators;
+/**
+ * A function similar to {@link fetch}, but tailored for the application's conventional backend API.
+ * {@link appFetch} implements automatic response (de-serialization) and validation.
+ * By default, {@link appFetch} assumes that requests and responses are based on JSON and that
+ * any non-2xx status code represents an error.
+ * These defaults can be overwritten via {@link args}.
+ * @param args The arguments for the fetch request. This can be a string representing the URL if no additional options are required.
+ */
+export declare function appFetch<TResult = void>(args: string | AppFetchArgs<TResult>): Promise<TResult>;
+/**
+ * An error thrown by {@link appFetch} when a default validation fails.
+ */
+export declare class AppFetchError extends Error {
+    /**
+     * The received fetch response.
+     */
+    readonly response: Response;
+    constructor(response: Response, message?: string | null);
+}
+/**
+ * An error thrown by {@link appFetch} when the response contains a problem details object.
+ */
+export declare class ProblemDetailsError extends AppFetchError {
+    readonly problem: Readonly<ProblemDetails>;
+    constructor(response: Response, problem: ProblemDetails);
+}
+export {};

package/dist/i18n/InitI18n.d.ts

@@ -0,0 +1,6 @@
+import { PropsWithChildren } from 'react';
+import { InitOptions } from 'i18next';
+export interface InitI18nProps extends PropsWithChildren {
+    options?: InitOptions<unknown>;
+}
+export declare function InitI18n({ options, children }: InitI18nProps): import('react').ReactNode;

package/dist/i18n/defineLocales.d.ts

@@ -0,0 +1,10 @@
+type KeyPrefixOrFn = string | ((...args: Array<any>) => any);
+/**
+ * Registers a translation resource bundle and creates a `useT` hook that returns a translation
+ * function which translates the registered keys.
+ * @param keyPrefixOrFn The key prefix or function that the translations are registered for.
+ * @param translations The set of translations to register, keyed by the language.
+ * @returns A `useT` hook that returns a {@link TFunction} that returns the registered translations.
+ */
+export declare function defineLocales<T extends Record<string, Record<string, unknown>>>(keyPrefixOrFn: KeyPrefixOrFn | Array<KeyPrefixOrFn>, translations: T): () => import('i18next').TFunction<"translation", string>;
+export {};

package/dist/i18n/index.d.ts

@@ -0,0 +1,3 @@
+export * from './defineLocales';
+export * from './InitI18n';
+export * from './useGlobalT';

package/dist/i18n/useGlobalT.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a non-scoped translation function.
+ * To be used for accessing global translations.
+ * If possible, use {@link defineLocales} instead.
+ * @param keyPrefix An optional key prefix.
+ */
+export declare function useGlobalT(keyPrefix?: string): import('i18next').TFunction<"translation", string>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './api';
+export * from './app';
+export * from './components';
+export * from './utils';
+export * from './fetch';
+export * from './i18n/defineLocales';
+export * from './module';