@alepha/react 0.7.5 → 0.7.7

package/dist/index.browser.d.ts

@@ -0,0 +1,523 @@
+import * as _alepha_core1 from "@alepha/core";
+import * as _alepha_core5 from "@alepha/core";
+import * as _alepha_core7 from "@alepha/core";
+import { Alepha, Async, KIND, Module, OPTIONS, Service, Static, TObject, TSchema } from "@alepha/core";
+import { Route, RouterProvider } from "@alepha/router";
+import * as react12 from "react";
+import * as react13 from "react";
+import React, { AnchorHTMLAttributes, ErrorInfo, FC, PropsWithChildren, ReactNode } from "react";
+import * as react_jsx_runtime10 from "react/jsx-runtime";
+import * as react_jsx_runtime11 from "react/jsx-runtime";
+import { ClientScope, HttpVirtualClient, LinkProvider } from "@alepha/server-links";
+import { Root } from "react-dom/client";
+import { ApiLinksResponse, ServerRequest } from "@alepha/server";
+import { ServerRouteCache } from "@alepha/server-cache";
+import * as _sinclair_typebox0 from "@sinclair/typebox";
+
+//#region src/components/ClientOnly.d.ts
+interface ClientOnlyProps {
+  fallback?: ReactNode;
+  disabled?: boolean;
+}
+/**
+ * A small utility component that renders its children only on the client side.
+ *
+ * Optionally, you can provide a fallback React node that will be rendered.
+ *
+ * You should use this component when
+ * - you have code that relies on browser-specific APIs
+ * - you want to avoid server-side rendering for a specific part of your application
+ * - you want to prevent pre-rendering of a component
+ */
+declare const ClientOnly: (props: PropsWithChildren<ClientOnlyProps>) => ReactNode;
+//#endregion
+//#region src/components/ErrorBoundary.d.ts
+/**
+ * Props for the ErrorBoundary component.
+ */
+interface ErrorBoundaryProps {
+  /**
+   * Fallback React node to render when an error is caught.
+   * If not provided, a default error message will be shown.
+   */
+  fallback: (error: Error) => ReactNode;
+  /**
+   * Optional callback that receives the error and error info.
+   * Use this to log errors to a monitoring service.
+   */
+  onError?: (error: Error, info: ErrorInfo) => void;
+}
+/**
+ * State of the ErrorBoundary component.
+ */
+interface ErrorBoundaryState {
+  error?: Error;
+}
+/**
+ * A reusable error boundary for catching rendering errors
+ * in any part of the React component tree.
+ */
+declare class ErrorBoundary extends React.Component<PropsWithChildren<ErrorBoundaryProps>, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps);
+  /**
+   * Update state so the next render shows the fallback UI.
+   */
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+  /**
+   * Lifecycle method called when an error is caught.
+   * You can log the error or perform side effects here.
+   */
+  componentDidCatch(error: Error, info: ErrorInfo): void;
+  render(): ReactNode;
+}
+//#endregion
+//#region src/providers/PageDescriptorProvider.d.ts
+declare const envSchema: _alepha_core1.TObject<{
+  REACT_STRICT_MODE: _sinclair_typebox0.TBoolean;
+}>;
+declare module "@alepha/core" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+declare class PageDescriptorProvider {
+  protected readonly log: _alepha_core1.Logger;
+  protected readonly env: {
+    REACT_STRICT_MODE: boolean;
+  };
+  protected readonly alepha: Alepha;
+  protected readonly pages: PageRoute[];
+  getPages(): PageRoute[];
+  page(name: string): PageRoute;
+  url(name: string, options?: {
+    params?: Record<string, string>;
+    base?: string;
+  }): URL;
+  root(state: RouterState, context: PageReactContext): ReactNode;
+  createLayers(route: PageRoute, request: PageRequest): Promise<CreateLayersResult>;
+  protected getErrorHandler(route: PageRoute): ((error: Error) => ReactNode) | undefined;
+  protected createElement(page: PageRoute, props: Record<string, any>): Promise<ReactNode>;
+  renderError(error: Error): ReactNode;
+  renderEmptyView(): ReactNode;
+  href(page: {
+    options: {
+      name?: string;
+    };
+  }, params?: Record<string, any>): string;
+  compile(path: string, params?: Record<string, string>): string;
+  protected renderView(index: number, path: string, view: ReactNode | undefined, page: PageRoute): ReactNode;
+  protected readonly configure: _alepha_core1.HookDescriptor<"configure">;
+  protected map(pages: Array<{
+    value: {
+      [OPTIONS]: PageDescriptorOptions;
+    };
+  }>, target: {
+    [OPTIONS]: PageDescriptorOptions;
+  }): PageRouteEntry;
+  add(entry: PageRouteEntry): void;
+  protected createMatch(page: PageRoute): string;
+  protected _next: number;
+  protected nextId(): string;
+}
+declare const isPageRoute: (it: any) => it is PageRoute;
+interface PageRouteEntry extends Omit<PageDescriptorOptions, "children" | "parent"> {
+  children?: PageRouteEntry[];
+}
+interface PageRoute extends PageRouteEntry {
+  type: "page";
+  name: string;
+  parent?: PageRoute;
+  match: string;
+}
+interface Layer {
+  config?: {
+    query?: Record<string, any>;
+    params?: Record<string, any>;
+    context?: Record<string, any>;
+  };
+  name: string;
+  props?: Record<string, any>;
+  error?: Error;
+  part?: string;
+  element: ReactNode;
+  index: number;
+  path: string;
+  route?: PageRoute;
+}
+type PreviousLayerData = Omit<Layer, "element" | "index" | "path">;
+interface AnchorProps {
+  href: string;
+  onClick: (ev: any) => any;
+}
+interface RouterState {
+  pathname: string;
+  search: string;
+  layers: Array<Layer>;
+}
+interface TransitionOptions {
+  state?: RouterState;
+  previous?: PreviousLayerData[];
+  context?: PageReactContext;
+}
+interface RouterStackItem {
+  route: PageRoute;
+  config?: Record<string, any>;
+  props?: Record<string, any>;
+  error?: Error;
+}
+interface RouterRenderResult {
+  state: RouterState;
+  context: PageReactContext;
+  redirect?: string;
+}
+interface PageRequest extends PageReactContext {
+  params: Record<string, any>;
+  query: Record<string, string>;
+  previous?: PreviousLayerData[];
+}
+interface CreateLayersResult extends RouterState {
+  redirect?: string;
+}
+/**
+ * It's like RouterState, but publicly available in React context.
+ * This is where we store all plugin data!
+ */
+interface PageReactContext {
+  url: URL;
+  onError: (error: Error) => ReactNode;
+  links?: ApiLinksResponse;
+}
+//#endregion
+//#region src/descriptors/$page.d.ts
+declare const KEY = "PAGE";
+interface PageConfigSchema {
+  query?: TSchema;
+  params?: TSchema;
+}
+type TPropsDefault = any;
+type TPropsParentDefault = {};
+interface PageDescriptorOptions<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
+  /**
+   * Name your page.
+   *
+   * @default Descriptor key
+   */
+  name?: string;
+  /**
+   * Optional description of the page.
+   */
+  description?: string;
+  /**
+   * Add a pathname to the page.
+   *
+   * Pathname can contain parameters, like `/post/:slug`.
+   *
+   * @default ""
+   */
+  path?: string;
+  /**
+   * Add an input schema to define:
+   * - `params`: parameters from the pathname.
+   * - `query`: query parameters from the URL.
+   */
+  schema?: TConfig;
+  /**
+   * Load data before rendering the page.
+   *
+   * This function receives
+   * - the request context and
+   * - the parent props (if page has a parent)
+   *
+   * In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
+   *
+   * Resolve can be stopped by throwing an error, which will be handled by the `errorHandler` function.
+   * It's common to throw a `NotFoundError` to display a 404 page.
+   *
+   * RedirectError can be thrown to redirect the user to another page.
+   */
+  resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
+  /**
+   * The component to render when the page is loaded.
+   *
+   * If `lazy` is defined, this will be ignored.
+   * Prefer using `lazy` to improve the initial loading time.
+   */
+  component?: FC<TProps & TPropsParent>;
+  /**
+   * Lazy load the component when the page is loaded.
+   *
+   * It's recommended to use this for components to improve the initial loading time
+   * and enable code-splitting.
+   */
+  lazy?: () => Promise<{
+    default: FC<TProps & TPropsParent>;
+  }>;
+  /**
+   * Set some children pages and make the page a parent page.
+   *
+   * /!\ Parent page can't be rendered directly. /!\
+   *
+   * If you still want to render at this pathname, add a child page with an empty path.
+   */
+  children?: Array<{
+    [OPTIONS]: PageDescriptorOptions;
+  }>;
+  parent?: {
+    [OPTIONS]: PageDescriptorOptions<PageConfigSchema, TPropsParent>;
+  };
+  can?: () => boolean;
+  errorHandler?: (error: Error) => ReactNode;
+  prerender?: boolean | {
+    entries?: Array<Partial<PageRequestConfig<TConfig>>>;
+  };
+  /**
+   * If true, the page will be rendered on the client-side.
+   */
+  client?: boolean | ClientOnlyProps;
+  afterHandler?: (request: ServerRequest) => any;
+  cache?: ServerRouteCache;
+}
+interface PageDescriptor<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
+  [KIND]: typeof KEY;
+  [OPTIONS]: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
+  /**
+   * For testing or build purposes, this will render the page (with or without the HTML layout) and return the HTML and context.
+   * Only valid for server-side rendering, it will throw an error if called on the client-side.
+   */
+  render: (options?: PageDescriptorRenderOptions) => Promise<PageDescriptorRenderResult>;
+}
+/**
+ * Main descriptor for defining a React route in the application.
+ */
+declare const $page: {
+  <TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = any, TPropsParent extends object = TPropsParentDefault>(options: PageDescriptorOptions<TConfig, TProps, TPropsParent>): PageDescriptor<TConfig, TProps, TPropsParent>;
+  [KIND]: string;
+};
+interface PageDescriptorRenderOptions {
+  params?: Record<string, string>;
+  query?: Record<string, string>;
+  html?: boolean;
+  hydration?: boolean;
+}
+interface PageDescriptorRenderResult {
+  html: string;
+  context: PageReactContext;
+}
+interface PageRequestConfig<TConfig extends PageConfigSchema = PageConfigSchema> {
+  params: TConfig["params"] extends TSchema ? Static<TConfig["params"]> : Record<string, string>;
+  query: TConfig["query"] extends TSchema ? Static<TConfig["query"]> : Record<string, string>;
+}
+type PageResolve<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & PageReactContext;
+//#endregion
+//#region src/components/Link.d.ts
+interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  to: string | PageDescriptor;
+  children?: React.ReactNode;
+}
+declare const Link: (props: LinkProps) => react_jsx_runtime10.JSX.Element | null;
+//#endregion
+//#region src/components/NestedView.d.ts
+interface NestedViewProps {
+  children?: ReactNode;
+}
+/**
+ * A component that renders the current view of the nested router layer.
+ *
+ * To be simple, it renders the `element` of the current child page of a parent page.
+ *
+ * @example
+ * ```tsx
+ * import { NestedView } from "@alepha/react";
+ *
+ * class App {
+ *   parent = $page({
+ *     component: () => <NestedView />,
+ *   });
+ *
+ *   child = $page({
+ *     parent: this.root,
+ *     component: () => <div>Child Page</div>,
+ *   });
+ * }
+ * ```
+ */
+declare const NestedView: (props: NestedViewProps) => react_jsx_runtime11.JSX.Element;
+//#endregion
+//#region src/contexts/RouterContext.d.ts
+interface RouterContextValue {
+  alepha: Alepha;
+  state: RouterState;
+  context: PageReactContext;
+}
+declare const RouterContext: react12.Context<RouterContextValue | undefined>;
+//#endregion
+//#region src/contexts/RouterLayerContext.d.ts
+interface RouterLayerContextValue {
+  index: number;
+  path: string;
+}
+declare const RouterLayerContext: react13.Context<RouterLayerContextValue | undefined>;
+//#endregion
+//#region src/providers/BrowserRouterProvider.d.ts
+interface BrowserRoute extends Route {
+  page: PageRoute;
+}
+declare class BrowserRouterProvider extends RouterProvider<BrowserRoute> {
+  protected readonly log: _alepha_core5.Logger;
+  protected readonly alepha: Alepha;
+  protected readonly pageDescriptorProvider: PageDescriptorProvider;
+  add(entry: PageRouteEntry): void;
+  protected readonly configure: _alepha_core5.HookDescriptor<"configure">;
+  transition(url: URL, options?: TransitionOptions): Promise<RouterRenderResult>;
+  root(state: RouterState, context: PageReactContext): ReactNode;
+}
+//#endregion
+//#region src/providers/ReactBrowserProvider.d.ts
+declare class ReactBrowserProvider {
+  protected readonly log: _alepha_core7.Logger;
+  protected readonly client: LinkProvider;
+  protected readonly alepha: Alepha;
+  protected readonly router: BrowserRouterProvider;
+  protected root: Root;
+  transitioning?: {
+    to: string;
+  };
+  state: RouterState;
+  get document(): Document;
+  get history(): History;
+  get url(): string;
+  invalidate(props?: Record<string, any>): Promise<void>;
+  go(url: string, options?: RouterGoOptions): Promise<void>;
+  protected render(options?: {
+    url?: string;
+    previous?: PreviousLayerData[];
+  }): Promise<RouterRenderResult>;
+  /**
+   * Get embedded layers from the server.
+   */
+  protected getHydrationState(): ReactHydrationState | undefined;
+  readonly ready: _alepha_core7.HookDescriptor<"ready">;
+}
+interface RouterGoOptions {
+  replace?: boolean;
+  match?: TransitionOptions;
+  params?: Record<string, string>;
+}
+interface ReactHydrationState {
+  layers?: Array<PreviousLayerData>;
+  links?: ApiLinksResponse;
+}
+//#endregion
+//#region src/hooks/RouterHookApi.d.ts
+declare class RouterHookApi {
+  private readonly pages;
+  private readonly state;
+  private readonly layer;
+  private readonly browser?;
+  constructor(pages: PageRoute[], state: RouterState, layer: {
+    path: string;
+  }, browser?: ReactBrowserProvider | undefined);
+  get current(): RouterState;
+  get pathname(): string;
+  get query(): Record<string, string>;
+  back(): Promise<void>;
+  forward(): Promise<void>;
+  invalidate(props?: Record<string, any>): Promise<void>;
+  /**
+   * Create a valid href for the given pathname.
+   *
+   * @param pathname
+   * @param layer
+   */
+  createHref(pathname: HrefLike, layer?: {
+    path: string;
+  }, options?: {
+    params?: Record<string, any>;
+  }): string;
+  go(path: string, options?: RouterGoOptions): Promise<void>;
+  go<T extends object>(path: keyof VirtualRouter<T>, options?: RouterGoOptions): Promise<void>;
+  anchor(path: string, options?: {
+    params?: Record<string, any>;
+  }): AnchorProps;
+  anchor<T extends object>(path: keyof VirtualRouter<T>, options?: {
+    params?: Record<string, any>;
+  }): AnchorProps;
+  /**
+   * Set query params.
+   *
+   * @param record
+   * @param options
+   */
+  setQueryParams(record: Record<string, any> | ((queryParams: Record<string, any>) => Record<string, any>), options?: {
+    /**
+     * If true, this will add a new entry to the history stack.
+     */
+    push?: boolean;
+  }): void;
+}
+type HrefLike = string | {
+  options: {
+    path?: string;
+    name?: string;
+  };
+};
+type VirtualRouter<T> = { [K in keyof T as T[K] extends PageDescriptor ? K : never]: T[K] };
+//#endregion
+//#region src/errors/RedirectionError.d.ts
+declare class RedirectionError extends Error {
+  readonly page: HrefLike;
+  constructor(page: HrefLike);
+}
+//#endregion
+//#region src/hooks/useActive.d.ts
+declare const useActive: (path: HrefLike) => UseActiveHook;
+interface UseActiveHook {
+  isActive: boolean;
+  anchorProps: AnchorProps;
+  isPending: boolean;
+  name?: string;
+}
+//#endregion
+//#region src/hooks/useAlepha.d.ts
+declare const useAlepha: () => Alepha;
+//#endregion
+//#region src/hooks/useClient.d.ts
+declare const useClient: <T extends object>(_scope?: ClientScope) => HttpVirtualClient<T>;
+//#endregion
+//#region src/hooks/useInject.d.ts
+declare const useInject: <T extends object>(clazz: Service<T>) => T;
+//#endregion
+//#region src/hooks/useQueryParams.d.ts
+interface UseQueryParamsHookOptions {
+  format?: "base64" | "querystring";
+  key?: string;
+  push?: boolean;
+}
+declare const useQueryParams: <T extends TObject>(schema: T, options?: UseQueryParamsHookOptions) => [Static<T>, (data: Static<T>) => void];
+//#endregion
+//#region src/hooks/useRouter.d.ts
+declare const useRouter: () => RouterHookApi;
+//#endregion
+//#region src/hooks/useRouterEvents.d.ts
+declare const useRouterEvents: (opts?: {
+  onBegin?: (ev: {
+    state: RouterState;
+  }) => void;
+  onEnd?: (ev: {
+    state: RouterState;
+  }) => void;
+  onError?: (ev: {
+    state: RouterState;
+    error: Error;
+  }) => void;
+}, deps?: any[]) => void;
+//#endregion
+//#region src/hooks/useRouterState.d.ts
+declare const useRouterState: () => RouterState;
+//#endregion
+//#region src/index.browser.d.ts
+declare class AlephaReact implements Module {
+  readonly name = "alepha.react";
+  readonly $services: (alepha: Alepha) => Alepha;
+}
+//#endregion
+export { $page, AlephaReact, AnchorProps, BrowserRoute, BrowserRouterProvider, ClientOnly, CreateLayersResult, ErrorBoundary, HrefLike, Layer, Link, NestedView, PageConfigSchema, PageDescriptor, PageDescriptorOptions, PageDescriptorProvider, PageDescriptorRenderOptions, PageDescriptorRenderResult, PageReactContext, PageRequest, PageRequestConfig, PageResolve, PageRoute, PageRouteEntry, PreviousLayerData, ReactBrowserProvider, ReactHydrationState, RedirectionError, RouterContext, RouterContextValue, RouterGoOptions, RouterHookApi, RouterLayerContext, RouterLayerContextValue, RouterRenderResult, RouterStackItem, RouterState, TPropsDefault, TPropsParentDefault, TransitionOptions, UseActiveHook, UseQueryParamsHookOptions, VirtualRouter, isPageRoute, useActive, useAlepha, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };
+//# sourceMappingURL=index.browser.d.ts.map