@ostack.tech/ui-kform 0.3.4 → 0.4.1

package/dist/types/components/Annexes/Annex.d.ts

@@ -1,11 +1,9 @@
-import { Path } from '@ostack.tech/kform';
 import { ErrorBoundary, TabContent } from '@ostack.tech/ui';
 import { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from 'react';
 import { IssueMessagesByCode } from '../IssueMessages';
+import { AnnexObject } from './Annexes.tsx';
 /** Properties of the annex component. */
-export interface AnnexProps extends Omit<ComponentPropsWithoutRef<typeof TabContent>, "value" | "children"> {
-    /** Annex path. This should match the path of the annex provided to `Annexes`. */
-    path?: string | Path;
+export interface AnnexProps extends AnnexObject, Omit<ComponentPropsWithoutRef<typeof TabContent>, "value" | "title" | "children"> {
     /** Sets the annex as disabled. */
     disabled?: boolean;
     /** Sets the annex as read-only. */

package/dist/types/components/Annexes/AnnexRegistrar.d.ts

@@ -0,0 +1,7 @@
+import { ResolvedAnnexObject } from './AnnexesContext.ts';
+/** Properties of the `AnnexRegistrar` component. */
+export interface AnnexRegistrarProps extends ResolvedAnnexObject {
+    index?: number;
+}
+/** Component used to register a form annex. */
+export declare function AnnexRegistrar({ path, title, subtitle, description, issuesPanelLabel, itemTitle, itemIssuesPanelLabel, index, documentTitle, }: AnnexRegistrarProps): null;

package/dist/types/components/Annexes/Annexes.d.ts

@@ -5,8 +5,11 @@ import { ComponentPropsWithoutRef, ReactNode } from 'react';
 export interface AnnexesProps extends Omit<ComponentPropsWithoutRef<typeof Tabs>, "defaultValue" | "value" | "onValueChange"> {
     /** Base path for all declared annexes. */
     path?: string | Path;
-    /** List of all annexes. */
-    annexes: AnnexObject[];
+    /**
+     * List of all annexes. When not provided, the list of annexes is obtained
+     * from the direct children `Annex` components.
+     */
+    annexes?: AnnexObject[];
     /** Default active annex. */
     defaultActiveAnnex?: string | Path;
     /** Controlled active annex. */
@@ -38,9 +41,9 @@ export interface AnnexObject<T = any> {
      * the elements of a collection should be counted as annexes. Otherwise, the
      * path may contain no other wildcards.
      */
-    path: string | Path;
+    path?: string | Path;
     /** Annex's title. */
-    title: ReactNode | ((value: T) => ReactNode);
+    title?: ReactNode | ((value: T) => ReactNode);
     /** Annex's subtitle. */
     subtitle?: ReactNode | ((value: T, index?: number) => ReactNode);
     /** Annex's description. */

package/dist/types/components/Annexes/RepetitiveAnnexRegistrar.d.ts

@@ -0,0 +1,6 @@
+import { ResolvedAnnexObject } from './AnnexesContext.ts';
+/** Properties of the `RepetitiveAnnexRegistrar` component. */
+export interface RepetitiveAnnexRegistrarProps extends ResolvedAnnexObject {
+}
+/** Component used to register a repetitive form annex. */
+export declare function RepetitiveAnnexRegistrar({ path, maxAnnexes, ...annexProps }: RepetitiveAnnexRegistrarProps): import("react/jsx-runtime").JSX.Element[] | undefined;

package/dist/types/components/Annexes/index.d.ts

@@ -1,3 +1,5 @@
 export * from './Annex.tsx';
 export * from './Annexes.tsx';
 export * from './AnnexesManager.tsx';
+export { AnnexRegistrar } from './AnnexRegistrar.tsx';
+export { RepetitiveAnnexRegistrar } from './RepetitiveAnnexRegistrar.tsx';

package/dist/types/components/FormApp/FormApp.d.ts

@@ -2,6 +2,7 @@ import { AbsolutePath, Path, Schema, SchemaKt } from '@ostack.tech/kform';
 import { Controller, FormOptions } from '@ostack.tech/kform-react';
 import { Responsive, Root } from '@ostack.tech/ui';
 import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+import { OnActivePathChangeNavigationOptions } from '../../providers/ActivePathProvider';
 import { LocalizationObject } from '../../providers/LocalizationProvider';
 import { IssueMessagesByCode } from '../IssueMessages';
 /** Mode of displaying issue messages. */
@@ -83,6 +84,23 @@ export type FormAppProps<T = any> = Pick<ComponentPropsWithoutRef<typeof Root>,
      * @default false
      */
     displayIssueCodes?: boolean;
+    /**
+     * When provided, the form app's active path will be controlled by a URL
+     * search parameter with the provided name.
+     */
+    activePathSearchParam?: string;
+    /** Uncontrolled default active path to use. */
+    defaultActivePath?: string | Path;
+    /** Controlled active path to use. */
+    activePath?: string | Path;
+    /**
+     * Callback called whenever the active path changes.
+     *
+     * @param activePath New active path.
+     * @param options Navigation options to use when controlling the active path
+     *   via the browser's URL.
+     */
+    onActivePathChange?: (activePath: AbsolutePath, options: OnActivePathChangeNavigationOptions) => void;
     /**
      * Function called when a form path is focused.
      *
@@ -201,6 +219,23 @@ export declare const FormApp: import('react').ForwardRefExoticComponent<Pick<Omi
      * @default false
      */
     displayIssueCodes?: boolean;
+    /**
+     * When provided, the form app's active path will be controlled by a URL
+     * search parameter with the provided name.
+     */
+    activePathSearchParam?: string;
+    /** Uncontrolled default active path to use. */
+    defaultActivePath?: string | Path;
+    /** Controlled active path to use. */
+    activePath?: string | Path;
+    /**
+     * Callback called whenever the active path changes.
+     *
+     * @param activePath New active path.
+     * @param options Navigation options to use when controlling the active path
+     *   via the browser's URL.
+     */
+    onActivePathChange?: (activePath: AbsolutePath, options: OnActivePathChangeNavigationOptions) => void;
     /**
      * Function called when a form path is focused.
      *

package/dist/types/components/FormApp/FormAppContext.d.ts

@@ -22,7 +22,7 @@ export interface FormAppState<T> {
     leftSidebarWidth: number;
     bottomPanelHeight: number;
     startIssuesNavigation?: () => void;
-    activePath: AbsolutePath;
+    latestInteraction: AbsolutePath;
     registeredControllers: [PathMultimap<Controller>];
     registeredIssueMessages: [
         PathMultimap<{
@@ -50,7 +50,7 @@ export interface FormAppActions {
     resetFocus: () => void;
     registerController: (path: AbsolutePath, controller?: Controller<any> | null) => (() => void) | void;
     isRegistered: (path: AbsolutePath) => boolean;
-    setActivePath: (path: AbsolutePath) => void;
+    setLatestInteraction: (path: AbsolutePath) => void;
     registerIssueMessages: (basePath: AbsolutePath, issueMessages?: Record<string, IssueMessagesByCode>, priority?: number) => (() => void) | void;
     getRegisteredIssueMessage: (path: AbsolutePath, code: string) => IssueMessageValue | null;
     registerLabel: (path: AbsolutePath, label: ReactNode, priority?: number) => (() => void) | void;
@@ -118,8 +118,8 @@ export declare function useSetLeftSidebarWidth(): (width?: number) => void;
  */
 export declare function useSetBottomPanelHeight(): (height?: number) => void;
 /**
- * Returns the current active path of the form app and a function that can be
- * used to set it, ala `useState`.
+ * Returns the current issues panel path of the form app and a function that can
+ * be used to set it, ala `useState`.
  */
 export declare function useIssuesPanelPath(): [
     AbsolutePath | null,
@@ -136,10 +136,10 @@ export declare function useResetFocus(): FormAppActions["resetFocus"];
 export declare function useRegisterController(controller: Controller<any>): void;
 /** Hook to check whether there is a registered controller for the provided path. */
 export declare function useIsRegistered(path?: AbsolutePath | null): boolean;
-/** Hook exposing the active path. */
-export declare function useActivePath(): AbsolutePath;
-/** Hook exposing a function to set the active path. */
-export declare function useSetActivePath(): FormAppActions["setActivePath"];
+/** Hook exposing the latest path that the user has interacted with. */
+export declare function useLatestInteraction(): AbsolutePath;
+/** Hook exposing a function to set the latest path the user has interacted with. */
+export declare function useSetLatestInteraction(): FormAppActions["setLatestInteraction"];
 /** Hook used to register issue messages within the form app. */
 export declare function useRegisterIssueMessages(path: AbsolutePath | null | undefined, issueMessages?: Record<string, IssueMessagesByCode>, priority?: number): void;
 /** Hook used to get the issue message value for the provided path and code. */
@@ -159,7 +159,7 @@ export declare function useStartIssuesNavigation(): FormAppActions["startIssuesN
 /** Options available to the {@link useOnPathFocus} hook. */
 export interface UseOnFocusedPathChangeOptions {
     /**
-     * Whether to run the callback immediately with the current active path.
+     * Whether to run the callback immediately with the current focused path.
      *
      * @default true
      */

package/dist/types/components/FormPages/FormPage.d.ts

@@ -1,15 +1,10 @@
-import { Path } from '@ostack.tech/kform';
 import { Container, ErrorBoundary, IconButton, Popover, PopoverContent, Stack } from '@ostack.tech/ui';
 import { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from 'react';
 import { IssueMessages, IssueMessagesByCode } from '../IssueMessages';
 import { IssuesPopover } from '../IssuesPopover';
+import { FormPageObject } from './FormPages.tsx';
 /** Properties of the form page component. */
-export interface FormPageProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
-    /**
-     * Form page path. This should match the path of the page provided to
-     * `FormPages`.
-     */
-    path?: string | Path;
+export interface FormPageProps extends FormPageObject, Omit<ComponentPropsWithoutRef<"div">, "title" | "children"> {
     /** Sets the form page as disabled. */
     disabled?: boolean;
     /** Sets the form page as read-only. */

package/dist/types/components/FormPages/FormPageRegistrar.d.ts

@@ -0,0 +1,6 @@
+import { ResolvedFormPageObject } from './FormPagesContext.ts';
+/** Properties of the `FormPageRegistrar` component. */
+export interface FormPageRegistrarProps extends ResolvedFormPageObject {
+}
+/** Component used to register a form page. */
+export declare function FormPageRegistrar({ path, title, documentTitle, code, issuesPanelLabel, }: FormPageRegistrarProps): null;

package/dist/types/components/FormPages/FormPages.d.ts

@@ -4,8 +4,11 @@ import { ComponentPropsWithoutRef, ReactNode } from 'react';
 export interface FormPagesProps extends ComponentPropsWithoutRef<"div"> {
     /** Base path for all declared form pages. */
     path?: string | Path;
-    /** List of all form pages. */
-    pages: FormPageObject[];
+    /**
+     * List of all form pages. When not provided, the list of pages is obtained
+     * from the direct children `FormPage` components.
+     */
+    pages?: FormPageObject[];
     /** Default active form page. */
     defaultActivePage?: string | Path;
     /** Controlled active form page. */
@@ -23,7 +26,7 @@ export interface FormPageObject<T = any> {
     /** Form page path. */
     path?: string | Path;
     /** Form page's title */
-    title: ReactNode | ((value: T) => ReactNode);
+    title?: ReactNode | ((value: T) => ReactNode);
     /**
      * Title of the form page as a string to display in the document's title.
      *

package/dist/types/components/FormPages/index.d.ts

@@ -1,3 +1,4 @@
 export * from './FormPage.tsx';
+export { FormPageRegistrar } from './FormPageRegistrar.tsx';
 export * from './FormPages.tsx';
 export * from './FormPagesNavigation.tsx';

package/dist/types/components/FormStepper/FormStepRegistrar.d.ts

@@ -0,0 +1,6 @@
+import { ResolvedFormStepObject } from './FormStepperContext.ts';
+/** Properties of the `FormStepRegistrar` component. */
+export interface FormStepRegistrarProps extends ResolvedFormStepObject {
+}
+/** Component used to register a form step. */
+export declare function FormStepRegistrar({ index, path, title, documentTitle, issuesPanelLabel, }: FormStepRegistrarProps): null;

package/dist/types/components/FormStepper/FormStepperContext.d.ts

@@ -45,7 +45,7 @@ export declare const FormStepperContext: import('react').Context<(Omit<import('z
         } | undefined): () => void;
     };
 }) | null>;
-/** Options used to create the form stepped context. */
+/** Options used to create the form stepper context. */
 export interface UseCreateFormStepperContextOptions extends Pick<FormStepperProps, "defaultActiveStep" | "activeStep" | "onActiveStepChange" | "onStepValidation" | "skipStepValidationOnForwardNavigation" | "allowForwardNavigationOnError" | "preventFocusOnError"> {
     formManager: FormManager;
     basePath: AbsolutePath;

package/dist/types/components/FormStepper/index.d.ts

@@ -1,3 +1,4 @@
 export * from './FormStepContent.tsx';
 export * from './FormStepList.tsx';
 export * from './FormStepper.tsx';
+export { FormStepRegistrar } from './FormStepRegistrar.tsx';

package/dist/types/index.d.ts

@@ -25,6 +25,7 @@ export * from './components/TableControl';
 export * from './components/TextControl';
 export * from './components/TopBar';
 export * from './components/ValidateAction';
+export * from './providers/ActivePathProvider';
 export * from './providers/LocalizationProvider';
 export * from './providers/PrefixSuffixProvider';
 export * from './utils/displayStatusConversions.ts';

package/dist/types/providers/ActivePathProvider/ActivePathContext.d.ts

@@ -0,0 +1,10 @@
+import { AbsolutePath } from '@ostack.tech/kform';
+/** Value of the active path context. */
+export interface ActivePathContextValue {
+    activePath: AbsolutePath;
+    onActivePathChange: (activePath: AbsolutePath | string | null) => void;
+}
+/** Active path context. */
+export declare const ActivePathContext: import('react').Context<ActivePathContextValue | null>;
+/** Hook providing access to the active path context. */
+export declare function useActivePathContext(): ActivePathContextValue;

package/dist/types/providers/ActivePathProvider/ActivePathProvider.d.ts

@@ -0,0 +1,28 @@
+import { AbsolutePath, Path } from '@ostack.tech/kform';
+import { ReactNode } from 'react';
+/**
+ * Navigation options to use when controlling the active path via the browser's
+ * URL.
+ */
+export interface OnActivePathChangeNavigationOptions {
+    /** Whether to replace the current history entry. */
+    replace: boolean;
+}
+/** Properties of the active path provider. */
+export interface ActivePathProviderProps {
+    /** Uncontrolled default active path to use. */
+    defaultActivePath?: string | Path;
+    /** Controlled active path to use. */
+    activePath?: string | Path;
+    /**
+     * Callback called whenever the active path is changed.
+     *
+     * @param activePath New active path.
+     * @param options Navigation options to use when controlling the active path
+     *   via the browser's URL.
+     */
+    onActivePathChange?: (activePath: AbsolutePath, options: OnActivePathChangeNavigationOptions) => void;
+    children?: ReactNode;
+}
+/** Provider which controls the active path in a section of a form. */
+export declare function ActivePathProvider({ defaultActivePath, activePath: controlledActivePath, onActivePathChange, children, }: ActivePathProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/providers/ActivePathProvider/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ActivePathContext.ts';
+export * from './ActivePathProvider.tsx';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ostack.tech/ui-kform",
   "description": "Integration of ostack/UI with ostack/KForm.",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "homepage": "https://ui.ostack.tech/",
   "author": {
     "name": "Opensoft",
@@ -52,7 +52,7 @@
     "@fortawesome/free-solid-svg-icons": "^6.2.0 || ^7.0.0",
     "@ostack.tech/kform": "~0.31.0",
     "@ostack.tech/kform-react": "~0.31.0",
-    "@ostack.tech/ui": "~0.3.4",
+    "@ostack.tech/ui": "~0.4.1",
     "@types/react": "^18.0.0 || ^19.0.0",
     "@types/react-dom": "^18.0.0 || ^19.0.0",
     "date-fns": "^4.1.0",