@tiny-server/core 0.0.0

package/src/app/features/menu/Menu.tsx

@@ -0,0 +1,66 @@
+import { Suspense, useMemo, type ComponentType } from 'react';
+import type {
+  AnyMenuItemRegistration,
+  MenuComponentProps,
+  MenuItemComponentProps,
+  MenuParams,
+  MenuType,
+} from './types';
+import { ErrorBoundary } from '../../../components';
+import { useApp } from '../../context';
+
+export interface MenuProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {}
+
+/**
+ * Renders the menu of the given type.
+ */
+export function Menu({ type, params }: MenuProps) {
+  const {
+    components: { MenuContainer, Loading, Error },
+    modules,
+  } = useApp();
+
+  const items = useMemo(() => {
+    const itemsOfType = modules.flatMap((m) => m.menuItems).filter((item) => item.menu === type);
+    const rootItems = itemsOfType.filter((item) => !item.parentId);
+    return rootItems.map((item) => (
+      <MenuItem key={item.id} type={type} params={params} thisItem={item} allItems={itemsOfType} />
+    ));
+  }, [type, params, modules]);
+
+  return (
+    <ErrorBoundary fallback={<Error kind="menu" />}>
+      <Suspense fallback={<Loading kind="menu" />}>
+        <MenuContainer type={type} params={params}>
+          {items}
+        </MenuContainer>
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+interface MenuItemProps {
+  type: MenuType;
+  params: MenuParams<MenuType>;
+  thisItem: AnyMenuItemRegistration;
+  allItems: Array<AnyMenuItemRegistration>;
+}
+
+function MenuItem({ type, params, thisItem, allItems }: MenuItemProps) {
+  const Component = thisItem.component as ComponentType<MenuItemComponentProps>;
+
+  const children = useMemo(() => {
+    const childItems = allItems
+      .filter((item) => item.parentId === thisItem.id)
+      .map((item) => <MenuItem key={item.id} type={type} params={params} thisItem={item} allItems={allItems} />);
+
+    // Do not return empty arrays. This plays better with Mantine's NavLink children.
+    return childItems.length > 0 ? childItems : undefined;
+  }, [type, params, thisItem, allItems]);
+
+  return (
+    <Component id={thisItem.id} type={type} params={params}>
+      {children}
+    </Component>
+  );
+}

package/src/app/features/menu/MenuContainer.tsx

@@ -0,0 +1,9 @@
+import type { MenuComponentProps, MenuType } from '.';
+
+export interface MenuContainerProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {}
+
+export function DefaultMenuContainer<TMenuType extends MenuType = MenuType>({
+  children,
+}: MenuContainerProps<TMenuType>) {
+  return <>{children}</>;
+}

package/src/app/features/menu/MenuItem.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from 'react';
+import { NavLink, type NavLinkProps } from '@mantine/core';
+import { NavLink as RouterNavLink } from 'react-router';
+import type { MenuItemComponentProps, MenuType } from '../../..';
+
+export interface MenuItemProps<TMenuType extends MenuType = MenuType> extends MenuItemComponentProps<TMenuType> {
+  label?: ReactNode;
+  description?: ReactNode;
+  leftSection?: ReactNode;
+  rightSection?: ReactNode;
+  to?: string;
+  onClick?: () => void;
+}
+
+export function DefaultMenuItem<TMenuType extends MenuType = MenuType>({
+  id,
+  label,
+  description,
+  leftSection,
+  rightSection,
+  to,
+  onClick,
+  children,
+}: MenuItemProps<TMenuType>) {
+  const props: NavLinkProps = {
+    label,
+    description,
+    leftSection,
+    rightSection,
+    onClick,
+  };
+
+  if (to) {
+    return (
+      <NavLink component={RouterNavLink} to={to} {...props}>
+        {children}
+      </NavLink>
+    );
+  }
+
+  return (
+    <NavLink href={`#${id}`} {...props}>
+      {children}
+    </NavLink>
+  );
+}

package/src/app/features/menu/index.ts

@@ -0,0 +1,5 @@
+export * from './initializer';
+export * from './Menu';
+export * from './MenuContainer';
+export * from './MenuItem';
+export * from './types';

package/src/app/features/menu/initializer.ts

@@ -0,0 +1,8 @@
+import type { AppInitializer } from '../../types';
+import { DefaultMenuContainer } from './MenuContainer';
+import { DefaultMenuItem } from './MenuItem';
+
+export const menuInitializer: AppInitializer = (app) => {
+  app.components.MenuContainer ??= DefaultMenuContainer;
+  app.components.MenuItem ??= DefaultMenuItem;
+};

package/src/app/features/menu/types.ts

@@ -0,0 +1,84 @@
+import type { ComponentType, PropsWithChildren } from 'react';
+import type { MenuContainerProps } from './MenuContainer';
+import type { MenuItemProps } from './MenuItem';
+
+declare module '../../types' {
+  export interface AppComponents {
+    MenuContainer: ComponentType<MenuContainerProps>;
+    MenuItem: ComponentType<MenuItemProps>;
+  }
+}
+
+/**
+ * A map of all known menus.
+ * This interface can be extended by modules via declaration merging.
+ *
+ * ```ts
+ * declare module '@tiny-server/core' {
+ *   export interface MenuParamsMap {
+ *     'my-menu': MyMenuParams;
+ *   }
+ * }
+ * ```
+ */
+export interface MenuParamsMap {
+  default: {};
+}
+
+/**
+ * Defines all typed/known menu types.
+ */
+export type KnownMenuType = keyof MenuParamsMap;
+
+/**
+ * Defines a menu type, both typed/known and untyped/unknown.
+ */
+export type MenuType = KnownMenuType | (string & {});
+
+/**
+ * The parameters of the menu with the given `TType`.
+ */
+export type MenuParams<TType extends MenuType> = TType extends KnownMenuType ? MenuParamsMap[TType] : unknown;
+
+export interface MenuComponentProps<TMenuType extends MenuType = MenuType> extends PropsWithChildren {
+  /**
+   * The type of the menu that the item belongs to.
+   */
+  type: TMenuType;
+  /**
+   * The parameters to be forwarded to the menu item component.
+   */
+  params: MenuParams<TMenuType>;
+}
+
+export interface MenuItemComponentProps<TMenuType extends MenuType = MenuType> extends MenuComponentProps<TMenuType> {
+  /**
+   * The unique identifier of the menu item.
+   */
+  id: string;
+}
+
+export interface MenuItemRegistration<TMenuType extends MenuType> {
+  /**
+   * A unique identifier for the menu item.
+   */
+  id: string;
+  /**
+   * The unique identifier of the parent menu item.
+   * Must reference an existing parent menu item within the same menu.
+   * If no parent is found, the child is not rendered.
+   */
+  parentId?: string;
+  /**
+   * The menu that the item belongs to.
+   */
+  menu: TMenuType;
+  /**
+   * The component to be rendered for the menu item.
+   */
+  component: ComponentType<MenuItemComponentProps<TMenuType>>;
+}
+
+export type AnyMenuItemRegistration = {
+  [TMenuType in MenuType]: MenuItemRegistration<TMenuType>;
+}[MenuType];

package/src/app/features/modals/Modal.tsx

@@ -0,0 +1,20 @@
+import { Modal } from '@mantine/core';
+import { ModalContent, type ModalComponentProps, type ModalName, type ModalOptions } from '.';
+import { useDisclosure } from '@mantine/hooks';
+
+export interface ModalProps<TModalName extends ModalName = ModalName> extends ModalComponentProps<TModalName> {
+  options?: ModalOptions;
+}
+
+export function DefaultModal({ name, params, options, onClose }: ModalProps) {
+  const [opened, { close }] = useDisclosure(true);
+
+  return (
+    <Modal.Root {...options} opened={opened} onClose={close} onExitTransitionEnd={onClose}>
+      <Modal.Overlay />
+      <Modal.Content>
+        <ModalContent name={name} params={params} onClose={close} />
+      </Modal.Content>
+    </Modal.Root>
+  );
+}

package/src/app/features/modals/ModalBody.tsx

@@ -0,0 +1,8 @@
+import { Modal } from '@mantine/core';
+import type { PropsWithChildren } from 'react';
+
+export interface ModalBodyProps extends PropsWithChildren {}
+
+export function DefaultModalBody({ children }: ModalBodyProps) {
+  return <Modal.Body>{children}</Modal.Body>;
+}

package/src/app/features/modals/ModalContent.tsx

@@ -0,0 +1,35 @@
+import { Suspense, useMemo } from 'react';
+import { ErrorBoundary } from '../../../components';
+import type { ModalComponentProps, ModalName } from './types';
+import { useApp } from '../../context';
+
+export interface ModalContentProps<TModalName extends ModalName = ModalName> extends ModalComponentProps<TModalName> {}
+
+/**
+ * Renders registered modal content.
+ */
+export function ModalContent({ name, params, onClose }: ModalContentProps) {
+  const {
+    components: { Loading, Error },
+    modules,
+  } = useApp();
+
+  const modalComponents = useMemo(() => {
+    return modules
+      .flatMap((module) => module.modals)
+      .filter((modal) => modal.name === name)
+      .map((modal) => modal.component);
+  }, [modules, name]);
+
+  return (
+    <>
+      {modalComponents.map((Component, index) => (
+        <ErrorBoundary key={index} fallback={<Error kind="modal" />}>
+          <Suspense fallback={<Loading kind="modal" />}>
+            <Component name={name} params={params} onClose={onClose} />
+          </Suspense>
+        </ErrorBoundary>
+      ))}
+    </>
+  );
+}

package/src/app/features/modals/ModalFooter.tsx

@@ -0,0 +1,19 @@
+import { Group, Modal } from '@mantine/core';
+import type { PropsWithChildren, ReactNode } from 'react';
+
+export interface ModalFooterProps extends PropsWithChildren {
+  actions?: ReactNode;
+}
+
+export function DefaultModalFooter({ children, actions }: ModalFooterProps) {
+  return (
+    <Modal.Body component="footer">
+      {children}
+      {actions && (
+        <Group gap="sm" justify="flex-end">
+          {actions}
+        </Group>
+      )}
+    </Modal.Body>
+  );
+}

package/src/app/features/modals/ModalHeader.tsx

@@ -0,0 +1,15 @@
+import { Modal } from '@mantine/core';
+import type { ReactNode } from 'react';
+
+export interface ModalHeaderProps {
+  title?: ReactNode;
+}
+
+export function DefaultModalHeader({ title }: ModalHeaderProps) {
+  return (
+    <Modal.Header>
+      <Modal.Title>{title}</Modal.Title>
+      <Modal.CloseButton />
+    </Modal.Header>
+  );
+}

package/src/app/features/modals/Modals.tsx

@@ -0,0 +1,33 @@
+import type { ModalComponentProps, ModalName } from './types';
+import { useMemo } from 'react';
+import { useStore } from 'zustand';
+import { modalsStore } from './store';
+import { useApp } from '../../context';
+
+/**
+ * Renders all currently opened application modals.
+ */
+export function Modals() {
+  const { Modal } = useApp().components;
+  const { modals, closeModal } = useStore(modalsStore);
+
+  const onCloseCallbacks = useMemo(
+    () =>
+      modals.reduce(
+        (acc, { id }) => {
+          acc[id] = () => closeModal(id);
+          return acc;
+        },
+        {} as Record<string, ModalComponentProps<ModalName>['onClose']>,
+      ),
+    [modals, closeModal],
+  );
+
+  return (
+    <>
+      {modals.map(({ id, name, params }) => {
+        return <Modal key={id} name={name} params={params} onClose={onCloseCallbacks[id]} />;
+      })}
+    </>
+  );
+}

package/src/app/features/modals/index.ts

@@ -0,0 +1,8 @@
+export * from './initializer';
+export * from './Modal';
+export * from './ModalBody';
+export * from './ModalContent';
+export * from './ModalFooter';
+export * from './ModalHeader';
+export * from './Modals';
+export * from './types';

package/src/app/features/modals/initializer.ts

@@ -0,0 +1,17 @@
+import type { AppInitializer } from '../../types';
+import { DefaultModal } from './Modal';
+import { DefaultModalBody } from './ModalBody';
+import { DefaultModalFooter } from './ModalFooter';
+import { DefaultModalHeader } from './ModalHeader';
+import { modalsStore } from './store';
+
+export const modalsInitializer: AppInitializer = (app) => {
+  app.components.Modal ??= DefaultModal;
+  app.components.ModalBody ??= DefaultModalBody;
+  app.components.ModalHeader ??= DefaultModalHeader;
+  app.components.ModalFooter ??= DefaultModalFooter;
+
+  app.showModal ??= (name, params) => {
+    modalsStore.getState().openModal(name, params);
+  };
+};

package/src/app/features/modals/store.ts

@@ -0,0 +1,35 @@
+import { createStore } from 'zustand/vanilla';
+import type { ModalName, ModalParams } from './types';
+
+interface OpenModal<TModalName extends ModalName = ModalName> {
+  id: string;
+  name: TModalName;
+  params: ModalParams<TModalName>;
+}
+
+interface ModalsStore {
+  _lastId: number;
+  modals: Array<OpenModal>;
+  openModal<TModalName extends ModalName>(name: TModalName, params: ModalParams<TModalName>): string;
+  closeModal(id: string): void;
+}
+
+export const modalsStore = createStore<ModalsStore>((set) => ({
+  _lastId: 0,
+  modals: [],
+  openModal(name, params) {
+    const id = `modal-${this._lastId + 1}`;
+
+    set((state) => ({
+      _lastId: state._lastId + 1,
+      modals: [...state.modals, { id, name, params }],
+    }));
+
+    return id;
+  },
+  closeModal(id) {
+    set((state) => ({
+      modals: state.modals.filter((modal) => modal.id !== id),
+    }));
+  },
+}));

package/src/app/features/modals/types.ts

@@ -0,0 +1,94 @@
+import type { ComponentType } from 'react';
+import type { ModalProps } from './Modal';
+import type { ModalBodyProps } from './ModalBody';
+import type { ModalFooterProps } from './ModalFooter';
+import type { ModalHeaderProps } from './ModalHeader';
+
+declare module '../../types' {
+  export 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;
+  }
+
+  export 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 {}
+
+/**
+ * Defines all typed/known modal names.
+ */
+export type KnownModalName = keyof ModalParamsMap;
+
+/**
+ * Defines a modal name, both typed/known and untyped/unknown.
+ */
+export type ModalName = KnownModalName | (string & {});
+
+/**
+ * The parameters of the modal with the given `TName`.
+ */
+export type ModalParams<TName extends ModalName> = TName extends KnownModalName ? ModalParamsMap[TName] : unknown;
+
+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/src/app/features/query/AppQueryClientProvider.tsx

@@ -0,0 +1,7 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import type { PropsWithChildren } from 'react';
+import { queryClient } from './client';
+
+export function AppQueryClientProvider({ children }: PropsWithChildren) {
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}

package/src/app/features/query/client.ts

@@ -0,0 +1,3 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient();

package/src/app/features/query/index.ts

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

package/src/app/features/query/initializer.ts

@@ -0,0 +1,6 @@
+import type { AppInitializer } from '../../types';
+import { queryClient } from './client';
+
+export const queryInitializer: AppInitializer = (app) => {
+  app.queryClient ??= queryClient;
+};

package/src/app/features/query/types.ts

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

package/src/app/features/router/AppLayout.tsx

@@ -0,0 +1,18 @@
+import { Suspense } from 'react';
+import { Outlet } from 'react-router';
+import { useApp } from '../../context';
+
+export function AppLayout() {
+  const app = useApp();
+  const { Loading, Layout } = app.components;
+
+  return (
+    // Error boundary/fallback is defined in the route as errorElement so that it also catches
+    // and handles router errors.
+    <Suspense fallback={<Loading kind="app" />}>
+      <Layout>
+        <Outlet />
+      </Layout>
+    </Suspense>
+  );
+}

package/src/app/features/router/AppRouteLayout.tsx

@@ -0,0 +1,31 @@
+import { Suspense } from 'react';
+import { Outlet, useLocation, useNavigation } from 'react-router';
+import { ErrorBoundary } from '../../../components';
+import { useApp } from '../../context';
+
+/**
+ * The app's top-level route layout.
+ * Acts as a suspense and error boundary for all routes.
+ */
+export function AppRouteLayout() {
+  const app = useApp();
+  const { Loading, Error } = app.components;
+  const isNavigating = useNavigation().state === 'loading';
+
+  // This key forces the below Suspense to remount on every navigation.
+  // This counteracts react-router's default startTransition behavior which circumvents Suspense
+  // falbacks on navigation - a behavior, that we are explicitly interested in here at the
+  // root route because we know that nearly any route rendered here will run into some kind of
+  // suspense, e.g., due to chunk loading.
+  // We're effectively applying this here:
+  // https://react.dev/reference/react/Suspense#resetting-suspense-boundaries-on-navigation
+  const suspenseKey = useLocation().key;
+
+  return (
+    <ErrorBoundary fallback={<Error kind="route" />}>
+      <Suspense key={suspenseKey} fallback={<Loading kind="route" />}>
+        {isNavigating ? <Loading kind="route" /> : <Outlet />}
+      </Suspense>
+    </ErrorBoundary>
+  );
+}

package/src/app/features/router/AppRouter.tsx

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+import { createBrowserRouter, RouterContextProvider, type RouteObject } from 'react-router';
+import { RouterProvider } from 'react-router/dom';
+import { RouterErrorBoundary } from './RouterErrorBoundary';
+import { AppLayout } from './AppLayout';
+import { AppRouteLayout } from './AppRouteLayout';
+import { useApp } from '../../context';
+import { appContext } from './context';
+
+/**
+ * Renders the app's router based on the app configuration.
+ */
+export function AppRouter() {
+  const app = useApp();
+
+  const router = useMemo(() => {
+    const { Loading, Error } = app.components;
+    const appRoutes = app.modules.flatMap((m) => m.routes);
+    const routes: Array<RouteObject> = [
+      {
+        Component: AppLayout,
+        hydrateFallbackElement: <Loading kind="app" />,
+        errorElement: <Error kind="app" />,
+        children: [
+          {
+            Component: AppRouteLayout,
+            hydrateFallbackElement: <Loading kind="route" />,
+            errorElement: <RouterErrorBoundary />,
+            children: appRoutes,
+          },
+        ],
+      },
+    ];
+
+    const getContext = () => {
+      const provider = new RouterContextProvider();
+      provider.set(appContext, app);
+      return provider;
+    };
+
+    return createBrowserRouter(routes, { getContext });
+  }, [app]);
+
+  return <RouterProvider router={router} />;
+}

package/src/app/features/router/RouterErrorBoundary.tsx

@@ -0,0 +1,20 @@
+import { isRouteErrorResponse, useRouteError } from 'react-router';
+import { useApp } from '../../context';
+
+export function RouterErrorBoundary() {
+  const app = useApp();
+  const { Error } = app.components;
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error)) {
+    if (error.status === 403) {
+      return <Error kind="route-forbidden" />;
+    }
+
+    if (error.status === 404) {
+      return <Error kind="route-not-found" />;
+    }
+  }
+
+  return <Error kind="route" />;
+}