@ostack.tech/ui-kform 0.1.0

package/dist/types/components/TableControl/TableControlRemoveRowTrigger.d.ts

@@ -0,0 +1,61 @@
+import { IconButton } from "@ostack.tech/ui";
+import * as React from "react";
+/** Properties of the table control remove row trigger component. */
+export interface TableControlRemoveRowTriggerProps extends Omit<Partial<React.ComponentPropsWithoutRef<typeof IconButton>>, "children"> {
+    /**
+     * Whether to show a confirmation message when removing a row.
+     *
+     * @default false
+     */
+    showConfirmation?: boolean;
+    /**
+     * Function called after confirmation that the row is to be removed (this
+     * function is called even if `showConfirmation` is not set).
+     */
+    onConfirmRowRemoval?: () => void;
+    /** Function called after the row has been removed. */
+    onRowRemoved?: () => void;
+    /**
+     * Label displayed on the icon button rendered by default when no `children`
+     * are provided. If `children` are provided, this property has no effect.
+     */
+    defaultButtonLabel?: React.ReactNode;
+    /** Title of the confirmation dialog when `showConfirmation` is `true`. */
+    confirmDialogTitle?: React.ReactNode;
+    /**
+     * Message of the confirmation dialog when `showConfirmation` is `true`.
+     *
+     * @param index Index of the row being removed.
+     */
+    confirmDialogMessage?: (index: number) => React.ReactNode;
+    /**
+     * Ok button text of the confirmation dialog when `showConfirmation` is
+     * `true`.
+     */
+    confirmDialogOkText?: React.ReactNode;
+    /**
+     * Cancel button text of the confirmation dialog when `showConfirmation` is
+     * `true`.
+     */
+    confirmDialogCancelText?: React.ReactNode;
+    /**
+     * Whether to show the trigger when the table is read-only.
+     *
+     * @default false
+     */
+    showWhenReadOnly?: boolean;
+    /**
+     * Children of the remove row trigger component. By default, it is an
+     * `IconButton` with label `defaultButtonLabel`. A function can be optionally
+     * passed as children which will receive an argument with whether the row is
+     * currently being removed.
+     */
+    children?: React.ReactNode;
+}
+/**
+ * Trigger used to remove a row of a table controlled by a table control.
+ *
+ * By default, it renders an icon button with label `defaultButtonLabel`,
+ * however, this can be overriden by providing `children`.
+ */
+export declare const TableControlRemoveRowTrigger: React.ForwardRefExoticComponent<TableControlRemoveRowTriggerProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/types/components/TableControl/TableControlRow.d.ts

@@ -0,0 +1,7 @@
+import { DataTableRow } from "@ostack.tech/ui";
+import * as React from "react";
+/** Properties of the table control row. */
+export interface TableControlRowProps extends React.ComponentPropsWithoutRef<typeof DataTableRow> {
+}
+/** Row of a table control. */
+export declare const TableControlRow: React.NamedExoticComponent<TableControlRowProps & React.RefAttributes<HTMLTableRowElement>>;

package/dist/types/components/TableControl/TableControlRowsPerPage.d.ts

@@ -0,0 +1,2 @@
+/** Table control rows per page. */
+export declare const TableControlRowsPerPage: import("react").ForwardRefExoticComponent<import("@ostack.tech/ui").DataTableRowsPerPageProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,8 @@
+export * from "./TableControl.tsx";
+export * from "./TableControlAddRowTrigger.tsx";
+export * from "./TableControlApi.ts";
+export * from "./TableControlColumn.tsx";
+export * from "./TableControlContent.tsx";
+export * from "./TableControlPagination.tsx";
+export * from "./TableControlRemoveRowTrigger.tsx";
+export * from "./TableControlRowsPerPage.tsx";

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

@@ -0,0 +1,66 @@
+import { type Path } from "@ostack.tech/kform";
+import { type InputController, type InputOptions } from "@ostack.tech/kform-react";
+import { Input, TextArea } from "@ostack.tech/ui";
+import * as React from "react";
+import { type IssueMessages, type IssueMessagesByCode } from "../IssueMessages";
+/** Properties of the text control component. */
+export type TextControlProps<T extends string | null = string | null> = TextControlPropsSingleline<T> | TextControlPropsMultiline<T>;
+export type TextControlPropsSingleline<T extends string | null = string | null> = Omit<React.ComponentPropsWithoutRef<typeof Input>, "defaultValue" | "value" | "status"> & TextControlPropsBase<T> & {
+    multiline?: false;
+};
+export type TextControlPropsMultiline<T extends string | null = string | null> = Omit<React.ComponentPropsWithoutRef<typeof TextArea>, "defaultValue" | "value" | "status"> & TextControlPropsBase<T> & {
+    multiline: true;
+    pattern?: never;
+};
+export type TextControlPropsBase<T extends string | null = string | null> = Omit<InputOptions<T, string, React.ComponentRef<typeof Input | typeof TextArea>>, "enabled" | "format" | "parse"> & {
+    /** Path to the value. */
+    path?: string | Path;
+    /**
+     * Issue messages of this control.
+     *
+     * Mapping from an issue's code to its message.
+     */
+    issueMessages?: IssueMessagesByCode;
+    /**
+     * Label to use in the issues panel when displaying issues associated with
+     * this field.
+     *
+     * This label has priority over the field's `ControlLabel`.
+     */
+    issuesPanelLabel?: React.ReactNode;
+    /**
+     * Whether to display the issues associated with this control.
+     *
+     * @default true
+     */
+    displayIssues?: boolean;
+    /**
+     * Whether to prevent the auto-focusing behaviour that causes this control
+     * to be focused when the form app's `focus` is called with this control's
+     * path.
+     *
+     * Preventing this behaviour is useful when multiple controls for the same
+     * path are rendered at once, and only one of them should be focused.
+     *
+     * @default false
+     */
+    preventAutoFocus?: boolean;
+    /** Whether to render a multiline text control. */
+    multiline?: boolean;
+    /** Reference to the control's API. */
+    apiRef?: React.Ref<InputController<T, string, React.ComponentRef<typeof Input | typeof TextArea>> | undefined>;
+    /** Properties to pass to the `IssueMessages` component. */
+    issueMessagesProps?: Omit<React.ComponentPropsWithRef<typeof IssueMessages>, "path" | "issues" | "messages">;
+};
+/**
+ * Text control component supporting (possibly nullable) schemas of type
+ * "String".
+ *
+ * If the schema is nullable, this component sets the form value to `null` when
+ * the control is empty. Note, however, that the form may still hold an empty
+ * string as value if set programmatically.
+ *
+ * The component further supports either single or multiple lines via the
+ * `multiline` prop.
+ */
+export declare const TextControl: React.ForwardRefExoticComponent<TextControlProps<string | null> & React.RefAttributes<HTMLInputElement | HTMLTextAreaElement>>;

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

@@ -0,0 +1 @@
+export * from "./TextControl.tsx";

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

@@ -0,0 +1,6 @@
+import * as React from "react";
+/** Properties of the top bar component. */
+export interface TopBarProps extends React.ComponentPropsWithoutRef<"div"> {
+}
+/** Top bar component. */
+export declare const TopBar: React.ForwardRefExoticComponent<TopBarProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/components/TopBar/TopBarActions.d.ts

@@ -0,0 +1,7 @@
+import { Stack } from "@ostack.tech/ui";
+import * as React from "react";
+/** Properties of the top bar actions component. */
+export interface TopBarActionsProps extends React.ComponentPropsWithoutRef<typeof Stack> {
+}
+/** Container used to display actions within the top bar. */
+export declare const TopBarActions: React.ForwardRefExoticComponent<TopBarActionsProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,2 @@
+export * from "./TopBar.tsx";
+export * from "./TopBarActions.tsx";

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

@@ -0,0 +1,21 @@
+import { type ButtonProps } from "@ostack.tech/ui";
+import * as React from "react";
+/** Properties of the validate action. */
+export interface ValidateActionProps extends Omit<ButtonProps, "children"> {
+    /** Action's label. */
+    label?: React.ReactNode;
+    /**
+     * Keybinds for triggering the action. Set to `null` to disable the keyboard
+     * shortcut.
+     *
+     * Keyboard handling is built on top of the
+     * [`tinykeys`](https://jamiebuilds.github.io/tinykeys) library. For
+     * information on keybinding syntax, read the [`tinykeys`
+     * documentation](https://github.com/jamiebuilds/tinykeys).
+     *
+     * Defaults to the keybinds defined by the current locale.
+     */
+    keybinds?: string | string[] | null;
+}
+/** Action used to validate the form. */
+export declare function ValidateAction({ label, keybinds, loading, disabled, onClick, ...otherProps }: ValidateActionProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export * from "./ValidateAction.tsx";

package/dist/types/index.d.ts

@@ -0,0 +1,36 @@
+export * from "./locale";
+export * from "./components/Annexes";
+export * from "./components/CheckboxControl";
+export * from "./components/CheckboxGroupControl";
+export * from "./components/ControlField";
+export * from "./components/DateControl";
+export * from "./components/DateRangeControl";
+export * from "./components/FileControl";
+export * from "./components/FormApp";
+export * from "./components/FormPages";
+export * from "./components/FormStepper";
+export * from "./components/IssueAlert";
+export * from "./components/IssueMessages";
+export * from "./components/IssuesPanel";
+export * from "./components/IssuesPopover";
+export * from "./components/LoadAction";
+export * from "./components/NumericControl";
+export * from "./components/PathLink";
+export * from "./components/RadioGroupControl";
+export * from "./components/SaveAction";
+export * from "./components/SelectControl";
+export * from "./components/SelectMultipleControl";
+export * from "./components/SubmitAction";
+export * from "./components/TableControl";
+export * from "./components/TextControl";
+export * from "./components/TopBar";
+export * from "./components/ValidateAction";
+export * from "./providers/LocalizationProvider";
+export * from "./providers/PrefixSuffixProvider";
+export * from "./utils/displayStatusConversions.ts";
+export * from "./utils/options.ts";
+export * from "./utils/useControlIssues.tsx";
+export * from "./utils/useFormLoader.tsx";
+export * from "./utils/useFormSaver.tsx";
+export * from "./utils/useFormValidator.ts";
+export * from "./utils/useRegisterControl.tsx";

package/dist/types/locale/LocalizationObject.d.ts

@@ -0,0 +1,34 @@
+import { type LocalizationObject as UiLocalizationObject } from "@ostack.tech/ui";
+import { type AnnexesManagerProps } from "../components/Annexes";
+import { type DateRangeControlProps } from "../components/DateRangeControl";
+import { type FileControlProps } from "../components/FileControl";
+import { type FormAppProps } from "../components/FormApp";
+import { type FormPageProps, type FormPagesNavigationProps } from "../components/FormPages";
+import { type IssueMessagesProps } from "../components/IssueMessages";
+import { type IssuesPanelProps } from "../components/IssuesPanel";
+import { type IssuesPopoverProps } from "../components/IssuesPopover";
+import { type LoadActionProps } from "../components/LoadAction";
+import { type SaveActionProps } from "../components/SaveAction";
+import { type SubmitActionProps } from "../components/SubmitAction";
+import { type TableControlAddRowTriggerProps, type TableControlRemoveRowTriggerProps } from "../components/TableControl";
+import { type ValidateActionProps } from "../components/ValidateAction";
+/** Localization object representation. */
+export interface LocalizationObject {
+    languageTag: string;
+    uiLocale: UiLocalizationObject;
+    AnnexesManager: Pick<AnnexesManagerProps, "aria-label" | "menuButtonText" | "addAnnexText" | "removeAnnexButtonLabel" | "removeAnnexKeyboardHint" | "removeAnnexConfirmDialogTitle" | "removeAnnexConfirmDialogMessage" | "removeAnnexConfirmDialogOkText" | "removeAnnexConfirmDialogCancelText">;
+    DateRangeControl: Pick<DateRangeControlProps, "issuesPanelStartLabelSuffix" | "issuesPanelEndLabelSuffix">;
+    FileControl: Pick<FileControlProps, "viewFileButtonLabel" | "downloadFileButtonLabel" | "fallbackText">;
+    FormApp: Pick<FormAppProps, "issuesPanelLabel" | "issueMessages" | "confirmUnloadMessage">;
+    FormPage: Pick<FormPageProps, "helperButtonLabel">;
+    FormPagesNavigation: Pick<FormPagesNavigationProps, "aria-label">;
+    IssueMessages: Pick<IssueMessagesProps, "unknownErrorMessage" | "unknownWarningMessage">;
+    IssuesPanel: Pick<IssuesPanelProps, "errorsLabel" | "warningsLabel" | "focusButtonLabel" | "previousIssueButtonLabel" | "nextIssueButtonLabel" | "firstIssueButtonLabel" | "lastIssueButtonLabel" | "paginationLabel" | "noIssuesMessage" | "resolvedTitle" | "resolvedMessage">;
+    IssuesPopover: Pick<IssuesPopoverProps, "label">;
+    LoadAction: Pick<LoadActionProps, "label" | "keybinds" | "successMessage" | "errorMessage">;
+    SaveAction: Pick<SaveActionProps, "label" | "keybinds" | "saveOptionsLabel" | "saveAsLabel" | "saveAsKeybinds" | "successMessage" | "errorMessage">;
+    SubmitAction: Pick<SubmitActionProps, "label" | "keybinds" | "dialogTitle" | "dialogDescription" | "dialogBody" | "dialogOkText" | "dialogCancelText" | "confirmWarningsCheckboxLabel" | "successMessage" | "errorMessage">;
+    TableControlAddRowTrigger: Pick<TableControlAddRowTriggerProps, "defaultButtonText">;
+    TableControlRemoveRowTrigger: Pick<TableControlRemoveRowTriggerProps, "defaultButtonLabel" | "confirmDialogTitle" | "confirmDialogMessage" | "confirmDialogOkText" | "confirmDialogCancelText">;
+    ValidateAction: Pick<ValidateActionProps, "label" | "keybinds">;
+}

package/dist/types/locale/defaultLocale.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** Default locale. */
+export declare const defaultLocale: LocalizationObject;

package/dist/types/locale/en-GB.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** `en-GB` locale. */
+export declare const enGB: LocalizationObject;

package/dist/types/locale/en-US.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** `en-US` locale. */
+export declare const enUS: LocalizationObject;

package/dist/types/locale/en.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** `en` locale (partial). */
+export declare const en: Omit<LocalizationObject, "languageTag" | "uiLocale">;

package/dist/types/locale/fr-FR.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** `fr-FR` locale. */
+export declare const frFR: LocalizationObject;

package/dist/types/locale/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./LocalizationObject.ts";
+export * from "./defaultLocale.ts";
+export * from "./en-GB.ts";
+export * from "./en-US.ts";
+export * from "./fr-FR.tsx";
+export * from "./pt-PT.tsx";

package/dist/types/locale/pt-PT.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "./LocalizationObject.ts";
+/** `pt-PT` locale. */
+export declare const ptPT: LocalizationObject;

package/dist/types/providers/LocalizationProvider/LocalizationContext.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { type LocalizationObject } from "../../locale/LocalizationObject.ts";
+/** Value of the localisation context. */
+export type LocalizationContextValue = LocalizationObject;
+/** Localisation context. */
+export declare const LocalizationContext: React.Context<LocalizationObject>;

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

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { type LocalizationObject } from "../../locale/LocalizationObject.ts";
+/** Properties of the localisation provider. */
+export interface LocalizationProviderProps {
+    /** Locale to use for the components. */
+    locale?: LocalizationObject;
+    children: React.ReactNode;
+}
+/** Localisation provider. */
+export declare function LocalizationProvider({ locale, children, }: LocalizationProviderProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;

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

@@ -0,0 +1,3 @@
+export * from "./LocalizationContext.ts";
+export * from "./LocalizationProvider.tsx";
+export * from "./useLocale.ts";

package/dist/types/providers/LocalizationProvider/useLocale.d.ts

@@ -0,0 +1,3 @@
+import { type LocalizationObject } from "../../locale/LocalizationObject.ts";
+/** Hook used to get the current locale. */
+export declare function useLocale(): LocalizationObject;

package/dist/types/providers/PrefixSuffixProvider/PrefixSuffixContext.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+/** Default library prefix-suffix. */
+export declare const DEFAULT_PREFIX_SUFFIX = "kform-";
+/** Prefix-suffix context. */
+export declare const PrefixSuffixContext: React.Context<string>;

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

@@ -0,0 +1,9 @@
+import * as React from "react";
+/** Properties of the prefix-suffix provider. */
+export interface PrefixSuffixProviderProps {
+    /** Suffix to add to ostack/UI's prefix. */
+    prefixSuffix?: string;
+    children: React.ReactNode;
+}
+/** Prefix-suffix provider. */
+export declare function PrefixSuffixProvider({ prefixSuffix, children, }: PrefixSuffixProviderProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;

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

@@ -0,0 +1,3 @@
+export * from "./PrefixSuffixContext.ts";
+export * from "./PrefixSuffixProvider.tsx";
+export * from "./usePrefix.ts";

package/dist/types/providers/PrefixSuffixProvider/usePrefix.d.ts

@@ -0,0 +1,6 @@
+import { type PrefixFn } from "@ostack.tech/ui";
+/**
+ * Hook which returns a function which can be used to prefix a string with the
+ * current prefix.
+ */
+export declare function usePrefix(): PrefixFn;

package/dist/types/utils/dateRestrictions.d.ts

@@ -0,0 +1,6 @@
+import { type Schema } from "@ostack.tech/kform";
+import { type Temporal } from "@ostack.tech/kform-react";
+/** Returns the minimum date allowed based on a temporal schema's restrictions. */
+export declare function minDateRestriction<T extends Temporal | null>(schema: Schema<T>): Date | undefined;
+/** Returns the maximum date allowed based on a temporal schema's restrictions. */
+export declare function maxDateRestriction<T extends Temporal | null>(schema: Schema<T>): Date | undefined;

package/dist/types/utils/displayStatusConversions.d.ts

@@ -0,0 +1,6 @@
+import { type DisplayStatus } from "@ostack.tech/kform";
+import { type ControlStatus } from "@ostack.tech/ui";
+/** Transforms ostack/KForm's display status into ostack/UI's control status. */
+export declare function displayStatusToControlStatus(displayStatus: DisplayStatus | undefined): ControlStatus | undefined;
+/** Transforms ostack/KForm's display status into a "danger" or "warning" colour. */
+export declare function displayStatusToColor(displayStatus: DisplayStatus | undefined): "danger" | "warning" | undefined;

package/dist/types/utils/mostSpecificPath.d.ts

@@ -0,0 +1,13 @@
+import { AbsolutePath } from "@ostack.tech/kform";
+/**
+ * Function which selects the most "specific" path from a list of paths, given a
+ * path to match. `currentActivePath` contains the path that is currently
+ * active.
+ *
+ * The list of paths may contain paths with a single trailing wildcard.
+ *
+ * This function is used by the `Annexes`, `FormPages`, and `FormStepper`
+ * components to select the next path that should be focused when the focused
+ * path changes.
+ */
+export declare function mostSpecificPath(toMatch: AbsolutePath | null, paths: AbsolutePath[], currentActivePath: AbsolutePath | null): AbsolutePath | null;

package/dist/types/utils/options.d.ts

@@ -0,0 +1,18 @@
+import { type OptionProps, type OptionsGroupProps } from "@ostack.tech/ui";
+import type * as React from "react";
+/** Object representation of an options group. */
+export type OptionsGroupObject<T = unknown> = Omit<OptionsGroupProps, "children"> & {
+    /** Group's options. */
+    options: OptionObject<T>[];
+    /** Group's unique key. */
+    key?: React.Key;
+};
+/** Object representation of an option. */
+export type OptionObject<T = unknown> = Omit<OptionProps, "value" | "children"> & {
+    /** Option value. */
+    value: T;
+    /** Option's rendered text. */
+    text?: React.ReactNode;
+    /** Option's unique key. */
+    key?: React.Key;
+};

package/dist/types/utils/pathSpecificity.d.ts

@@ -0,0 +1,18 @@
+import { type AbsolutePath } from "@ostack.tech/kform";
+/**
+ * Given two paths, returns a number > 0 if the first path is more specific than
+ * the second, a number < 0 if the first path is less specific than the second,
+ * or 0 if both paths have the same specificity.
+ *
+ * Specificity is not incredibly well specified (and may change over time if a
+ * need arises), but the idea is that wildcards make paths less specific, so
+ * `/a/∗` is less specific than `/a/b`, and `/∗∗` is the least specific path.
+ *
+ * Both `/a` and `/a/b/c` have the same specificity since both paths uniquely
+ * identify a resource.
+ *
+ * @param path1 First path to compare.
+ * @param path2 Second path to compare.
+ * @returns Number representing which path is more specific.
+ */
+export declare function comparePathsBySpecificity(path1: AbsolutePath, path2: AbsolutePath): number;

package/dist/types/utils/selectionTransformations.d.ts

@@ -0,0 +1,32 @@
+import { type Schema } from "@ostack.tech/kform";
+import { type Listable } from "@ostack.tech/kform-react";
+import { type OptionObject, type OptionsGroupObject } from "./options.ts";
+/**
+ * Parses a selection value from the (string) index of an option (or empty
+ * string).
+ */
+export declare function parseSelectionValueFromOptionIndex<T>(formattedValue: string, schema: Schema<T>, options: {
+    value: T;
+}[]): T;
+/**
+ * Formats a selection value as the (string) index of an option (or empty
+ * string).
+ */
+export declare function formatSelectionValueAsOptionIndex<T>(value: T | undefined, options: {
+    value: T;
+}[]): string;
+/** Parses an array of selection values from an array of (string) option indices. */
+export declare function parseSelectionValuesFromOptionIndices<T, TListable extends Listable<T> | null>(formattedValue: string[], schema: Schema<TListable>, options: {
+    value: T;
+}[]): T[] | null;
+/** Formats an array of selection values as an array of (string) option indices. */
+export declare function formatSelectionValuesAsOptionIndices<T>(arrayValue: T[] | null | undefined, options: {
+    value: T;
+}[]): string[];
+/**
+ * Transforms option objects into React nodes.
+ *
+ * @param options Option objects.
+ * @returns React nodes representing the objects.
+ */
+export declare function optionObjectsToNodes<T>(options: (OptionsGroupObject<T> | OptionObject<T>)[]): React.JSX.Element[];

package/dist/types/utils/useControlAutofocus.d.ts

@@ -0,0 +1,32 @@
+import { type Controller } from "@ostack.tech/kform-react";
+import * as React from "react";
+/**
+ * Function used to scroll an element into view.
+ *
+ * @param el Element to scroll into view.
+ * @param options Scroll into view options.
+ */
+export type ScrollIntoViewFn = (el: HTMLElement, options?: ScrollIntoViewOptions) => void;
+/**
+ * Hook used to autofocus a control when the active path changes, given the
+ * control's path.
+ *
+ * @param controller Control's controller.
+ * @param enabled Whether to enable the auto-focus behaviour.
+ * @returns Reference that should be set on the focusable element of the
+ *   control.
+ */
+export declare function useControlAutofocus<T = unknown, TElem extends HTMLElement = HTMLElement>({ usePath, useExists }: Controller<T>, enabled?: boolean): React.MutableRefObject<TElem | null>;
+/**
+ * Visibly focuses the provided element.
+ *
+ * @param el Element to visibly focus.
+ * @param options Focus options.
+ */
+export declare function visiblyFocus(el: HTMLElement, options?: FocusOptions): void;
+/**
+ * Returns a function used the scroll an element into view, taking into account
+ * the form app's sticky elements, so that elements don't end up hidden behind
+ * them.
+ */
+export declare function useScrollIntoView(): ScrollIntoViewFn;

package/dist/types/utils/useControlIssues.d.ts

@@ -0,0 +1,27 @@
+import { type SealedValidationIssue } from "@ostack.tech/kform";
+import * as React from "react";
+import { IssueMessages, type IssueMessagesByCode } from "../components/IssueMessages";
+/** Options of the `useControlIssues` hook. */
+export interface UseControlIssuesOptions {
+    /** Mapping from path to issues to display. */
+    issuesToDisplay: Record<string, SealedValidationIssue[]>;
+    /** Mapping from path to issue messages by code. */
+    issueMessages?: Record<string, IssueMessagesByCode | undefined>;
+    /** Whether issues should be displayed. */
+    displayIssues?: boolean;
+    /** Properties to pass to the `IssueMessages` component. */
+    issueMessagesProps?: Omit<React.ComponentPropsWithRef<typeof IssueMessages>, "path" | "issues" | "messages" | "unwrapped">;
+}
+/**
+ * Hook which helps a control component render its issues.
+ *
+ * This hook returns a pair containing two React nodes:
+ *
+ * - The first element of the pair contains the node that should be rendered when
+ *   the issues are to appear inline. This will be `null` if the issues should
+ *   not appear inline.
+ * - The second element of the pair contains the node that should be rendered when
+ *   the issues are to appear within a popover. This will be `null` if the
+ *   issues should not appear in a popover.
+ */
+export declare function useControlIssues({ issuesToDisplay, issueMessages, displayIssues, issueMessagesProps, }: UseControlIssuesOptions): [React.ReactNode, React.ReactNode];

package/dist/types/utils/useEqualityFn.d.ts

@@ -0,0 +1 @@
+export declare function useEqualityFn<TState, TResult>(selector: (state: TState) => TResult, equalityFn?: (v1: TResult, v2: TResult) => boolean): (state: TState) => TResult;

package/dist/types/utils/useFormLoader.d.ts

@@ -0,0 +1,83 @@
+import { AbsolutePath } from "@ostack.tech/kform";
+import { type FileSystemHandle, type FileWithHandle, type WellKnownDirectory } from "browser-fs-access";
+import * as React from "react";
+/**
+ * Options that can be passed to the {@link useFormLoader} hook, or to its
+ * resulting `load` function.
+ */
+export interface FormLoaderOptions<T = unknown> {
+    /**
+     * Function used to decode the form, given its file.
+     *
+     * If decoding a text-based format, one may use `await file.text()` to get the
+     * content of the file as a string.
+     *
+     * @param file File containing the form to decode.
+     * @returns Decoded form value.
+     */
+    decode?: (file: FileWithHandle) => PromiseLike<T>;
+    /**
+     * Path of the value being loaded.
+     *
+     * @default AbsolutePath.ROOT
+     */
+    path?: string | AbsolutePath;
+    /** Acceptable file extensions. */
+    extensions?: string[];
+    /** Acceptable MIME types. */
+    mimeTypes?: string[];
+    /** Suggested file description. */
+    description?: string;
+    /** Directory to present when starting to load. */
+    startIn?: WellKnownDirectory | FileSystemHandle;
+    /**
+     * By specifying an ID, the user agent can remember different directories for
+     * different IDs.
+     */
+    id?: string;
+    /**
+     * Whether to set the form as pristine when it is loaded.
+     *
+     * @default true
+     */
+    setPristineOnLoad?: boolean;
+    /**
+     * Whether to validate the form (and show the issues panel) when it is loaded.
+     *
+     * @default true
+     */
+    validateOnLoad?: boolean;
+    /**
+     * Message to show in a toast when successfully loading a form from a file.
+     *
+     * @param file Loaded file.
+     * @returns Message to show in a toast.
+     */
+    successMessage?: (file: FileWithHandle) => React.ReactNode;
+    /**
+     * Message to show in a toast when an error occurs while loading the form from
+     * a file.
+     *
+     * @param file File from which the load was attempted (or `null` if the file
+     *   could not be accessed).
+     * @param error Error that occurred.
+     * @returns Message to show in a toast.
+     */
+    errorMessage?: (file: FileWithHandle | null, error: unknown) => React.ReactNode;
+}
+/** Result of the {@link useFormLoader} hook. */
+export interface FormLoaderResult<T> {
+    /**
+     * Function used to load the form.
+     *
+     * @param options Options used for loading the form.
+     * @returns Promise which resolves once the form has been loaded.
+     */
+    load: (options?: FormLoaderOptions<T>) => Promise<void>;
+    /** Whether the browser supports modern file system APIs used for loading. */
+    supportsFileSystemAPIs: boolean;
+}
+/** Hook exposing a function used to load the form from a file. */
+export declare function useFormLoader<T = unknown>({ decode, path, extensions, mimeTypes, description, startIn, id, setPristineOnLoad, validateOnLoad, successMessage, errorMessage, }?: FormLoaderOptions<T>): FormLoaderResult<T>;
+/** Hook exposing whether the form is currently being loaded. */
+export declare function useFormIsLoading(): any;