@parallelworks/ui 0.1.0 → 0.3.0

package/dist/form/Form.d.ts

@@ -0,0 +1,105 @@
+import { type FormikProps, type FormikValues } from 'formik';
+import { type WorkflowVariables } from '@parallelworks/workflow-parser';
+import React, { type SetStateAction } from 'react';
+import { type FieldComponent } from './fieldRegistry.js';
+/** Applies `$meta` overrides for `labelPosition` / `spaceCompact`. */
+export declare function resolveMetaOverrides(options: {
+    $meta?: {
+        labelPosition?: 'left' | 'top';
+        spaceCompact?: boolean;
+    };
+} | undefined, labelPosition: 'left' | 'top' | undefined, spaceCompact: boolean): {
+    labelPosition: "left" | "top" | undefined;
+    spaceCompact: boolean;
+};
+/** Collects every field with a `default` for the form-level sync to track. */
+export declare function collectFieldsWithDefaults(options: Record<string, any>, values?: Record<string, any>, prefix?: string): Array<{
+    name: string;
+    defaultValue: any;
+}>;
+export declare function defaultReferencesField(defaultValue: unknown, fieldPath: string): boolean;
+export declare function findSelfReferencingFieldNames(schema: Record<string, any>, values?: Record<string, any>): string[];
+/**
+ * Re-syncs each field's value when its resolved default changes between
+ * renders, unless `meta.touched` (this session) or a synth-touched marker
+ * (cross-session, set on first-seen when saved ≠ default) is set. Must be
+ * remounted via `key` when the run/config context changes.
+ */
+export declare function DynamicDefaultsSync({ options, }: {
+    options: Record<string, any>;
+}): null;
+export declare function GroupHeader({ children, open, setOpen, title, }: {
+    children?: React.ReactNode;
+    open: boolean;
+    setOpen: React.Dispatch<SetStateAction<boolean>>;
+    title: React.ReactNode;
+}): React.JSX.Element;
+export type TSetFormDirty = (dirty: boolean) => void;
+export declare function getInstanceTypesForForm(instances: Record<string, any>): Record<string, any>;
+export declare function StatusBlock({ status }: {
+    status: boolean;
+}): React.JSX.Element;
+export declare function MultiSelectionDropdown({ name, label, invalid, options: initialOptions, setFormDirty, onChange, parentValue, }: {
+    name: string;
+    label: string;
+    invalid?: boolean;
+    options?: {
+        label: string;
+        secondaryLabel?: string;
+        value: any;
+        selected: boolean;
+    }[];
+    setFormDirty: TSetFormDirty;
+    onChange?: (val: any) => void;
+    parentValue?: any;
+    className?: string;
+    secondaryField?: string;
+}): React.JSX.Element;
+export declare function FieldsFromOptions({ options, values, setFormDirty, setFieldValue, setFieldTouched, parentInfo, labelPosition, missingFields, spaceCompact, workflowForm, }: {
+    options: Record<string, any>;
+    values: Record<string, any>;
+    setFormDirty: TSetFormDirty;
+    setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void;
+    setFieldTouched: (field: string, touched?: boolean, shouldValidate?: boolean) => void;
+    /** If fields are part of other field, this is the info needed*/
+    parentInfo?: {
+        computeOn?: boolean;
+        parentName: string;
+        fieldNamePrefix: string;
+        arrayIndex?: number;
+        onChange?: (fieldName: string, index: number, changeOtherValuesTo?: string | boolean, keepOneValueOf?: string | boolean, currentValue?: string | boolean) => void;
+    };
+    labelPosition?: 'left' | 'top';
+    missingFields?: string[];
+    spaceCompact?: boolean;
+    /** Prevents deletion of hidden+ignored field values (workflow forms filter at submit time) */
+    workflowForm?: boolean;
+}): React.JSX.Element[];
+export interface DynamicFormProps {
+    formJSONs: Record<string, any>;
+    reinitialize?: boolean;
+    setFormDirty?: (dirty: boolean) => void;
+    initialValues: Record<string, any>;
+    setValues?: (values: Record<string, any>) => void;
+    formikRef?: React.RefObject<FormikProps<FormikValues> | null>;
+    labelPosition?: 'left' | 'top';
+    missingFields?: string[];
+    spaceCompact?: boolean;
+    organizationVariables?: WorkflowVariables;
+    needsOrganizationVariables?: boolean;
+    onSubmit?: (values: Record<string, any>) => void;
+    submitLabel?: string;
+    className?: string;
+    /** Prevents deletion of hidden+ignored field values (workflow forms filter at submit time).
+     *  Also gates the form-level DynamicDefaultsSync — it only runs for workflow forms. */
+    workflowForm?: boolean;
+    /** Identifier for the load context (e.g. rerun slug, configuration name). When this
+     *  changes, DynamicDefaultsSync remounts so it re-evaluates its prev-default tracking
+     *  and saved-vs-default first-seen synthesis against the new context. */
+    contextKey?: string;
+    /** Skip expression parsing on initial values (for edit forms where saved values may contain user-typed expressions like ${{ var.X }} that should stay literal). Schema-level expressions still resolve. */
+    skipValueParse?: boolean;
+    /** Host-supplied field components, merged over the core registry by type. */
+    fields?: Record<string, FieldComponent>;
+}
+export declare function DynamicForm({ formJSONs: options, reinitialize, initialValues, setValues, setFormDirty, formikRef, labelPosition, missingFields, spaceCompact, organizationVariables, needsOrganizationVariables, onSubmit, submitLabel, className, workflowForm, contextKey, skipValueParse, fields, }: DynamicFormProps): React.JSX.Element;

package/dist/form/SpecialTypes/DropdownWrapper.d.ts

@@ -0,0 +1,14 @@
+import FormikCustomDropdown from './FormikCustomDropdown.js';
+export default function DropdownWrapper({ options, onChange, fieldObj, setFormDirty, invalid, loading, disabled, allowCustomValue, currentValue, setFieldValue, setFieldTouched, }: {
+    options: React.ComponentProps<typeof FormikCustomDropdown>['options'];
+    onChange?: (val: string) => void;
+    fieldObj: any;
+    setFormDirty: React.ComponentProps<typeof FormikCustomDropdown>['setFormDirty'];
+    invalid?: boolean;
+    loading?: boolean;
+    disabled?: boolean;
+    allowCustomValue?: boolean;
+    currentValue: unknown;
+    setFieldValue: React.ComponentProps<typeof FormikCustomDropdown>['setFieldValue'];
+    setFieldTouched: React.ComponentProps<typeof FormikCustomDropdown>['setFieldTouched'];
+}): import("react").JSX.Element;

package/dist/form/SpecialTypes/FormikCustomDropdown.d.ts

@@ -0,0 +1,53 @@
+import Dropdown from '../../components/Dropdown.js';
+import type { TSetFormDirty } from '../Form.js';
+declare function toComparableOptions(options: React.ComponentProps<typeof Dropdown>['options'] | undefined): (string | {
+    category: string | undefined;
+    options: ({
+        label: string;
+        value: unknown;
+        disabled: boolean | undefined;
+    } | {
+        label: string;
+        value: unknown;
+        disabled: boolean | undefined;
+        description: string;
+    })[];
+} | {
+    label: string;
+    value: unknown;
+    disabled: boolean | undefined;
+} | {
+    category?: undefined;
+    options?: undefined;
+    label: string;
+    value: unknown;
+    disabled: boolean | undefined;
+    description: string;
+})[] | undefined;
+type FormikCustomDropdownProps = {
+    name: string;
+    ariaLabel?: string;
+    options: React.ComponentProps<typeof Dropdown>['options'];
+    setFormDirty: TSetFormDirty;
+    onChange?: (val: string) => void;
+    parentValue?: any;
+    className?: string;
+    secondaryField?: string | string[];
+    disabled?: boolean;
+    resetOnChange?: string;
+    loading?: boolean;
+    invalid?: boolean;
+    autoselect?: boolean;
+    value?: string;
+    allowCustomValue?: boolean;
+    customValueLabel?: string;
+    placeholder?: string;
+    currentValue: unknown;
+    setFieldValue: (field: string, value: unknown, shouldValidate?: boolean) => void;
+    setFieldTouched: (field: string, isTouched?: boolean, shouldValidate?: boolean) => void;
+};
+declare const _default: import("react").MemoExoticComponent<({ name, ariaLabel, options, setFormDirty, onChange, parentValue, className, secondaryField, disabled, loading, invalid, autoselect, value, allowCustomValue, customValueLabel, placeholder, currentValue, setFieldValue, setFieldTouched, }: FormikCustomDropdownProps) => import("react").JSX.Element>;
+export default _default;
+export declare const Testables: {
+    toComparableOptions: typeof toComparableOptions;
+};

package/dist/form/SpecialTypes/FormikCustomInput.d.ts

@@ -0,0 +1,17 @@
+export default function FormikCustomInput({ name, type, step, placeholder, onChange, disabled, min, max, sanitize, invalid, lowercase, minLength, maxLength, defaultValue, value, }: {
+    name: string;
+    type: 'string' | 'number' | 'password';
+    placeholder?: string;
+    onChange?: (val: string | boolean) => void;
+    disabled?: boolean;
+    step?: number;
+    min?: number;
+    max?: number;
+    sanitize?: string;
+    invalid?: boolean;
+    lowercase?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    defaultValue?: any;
+    value?: any;
+}): import("react").JSX.Element;

package/dist/form/SpecialTypes/FormikMultiSelectDropdown.d.ts

@@ -0,0 +1,13 @@
+import type { ICategory, IOptions } from '../../components/dropdownUtils.js';
+import type { TSetFormDirty } from '../Form.js';
+export default function FormikMultiSelectDropdown<T>({ name, options, setFormDirty, onChange, disabled, loading, invalid, placeholder, compareBy, }: {
+    name: string;
+    options: (ICategory<T> | IOptions<T>)[];
+    setFormDirty: TSetFormDirty;
+    onChange?: (val: T[]) => void;
+    disabled?: boolean;
+    loading?: boolean;
+    invalid?: boolean;
+    placeholder?: string;
+    compareBy?: (a: T, b: T) => boolean;
+}): import("react").JSX.Element;

package/dist/form/SpecialTypes/FormikNumericInput.d.ts

@@ -0,0 +1,9 @@
+export default function FormikNumericInput({ name, placeholder, onChange, disabled, min, max, invalid, }: {
+    name: string;
+    placeholder?: string;
+    onChange?: (val: number | undefined) => void;
+    disabled?: boolean;
+    min?: number;
+    max?: number;
+    invalid?: boolean;
+}): import("react").JSX.Element;

package/dist/form/SpecialTypes/index.d.ts

@@ -0,0 +1,3 @@
+export { default as FormikCustomDropdown } from './FormikCustomDropdown.js';
+export { default as FormikCustomInput } from './FormikCustomInput.js';
+export { default as FormikNumericInput } from './FormikNumericInput.js';

package/dist/form/Wizard/WizardContainer.d.ts

@@ -0,0 +1,5 @@
+import type { WizardContainerProps } from './types.js';
+export declare function WizardContainer({ wizardConfig, values, onChange, onSubmit, className, labelPosition, missingFields, spaceCompact, workflowForm, setFieldValue, setFieldTouched, }: WizardContainerProps & {
+    setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void;
+    setFieldTouched: (field: string, touched?: boolean, shouldValidate?: boolean) => void;
+}): import("react").JSX.Element;

package/dist/form/Wizard/WizardNavigation.d.ts

@@ -0,0 +1,2 @@
+import type { WizardNavigationProps } from './types.js';
+export declare function WizardNavigation({ currentStep, stepOrder, canGoToNext, canGoBack, isCurrentStepValid, nextLabel, prevLabel, submitLabel, onNext, onPrevious, onSubmit, }: WizardNavigationProps): import("react").JSX.Element;

package/dist/form/Wizard/WizardStepContent.d.ts

@@ -0,0 +1,8 @@
+import type { TSetFormDirty } from '../Form.js';
+import type { WizardStepContentProps } from './types.js';
+export declare function WizardStepContent({ currentStep, stepConfig, flatten, values, onValuesChange, setFormDirty, setFieldValue, setFieldTouched, ...fieldsProps }: WizardStepContentProps & {
+    setFormDirty: TSetFormDirty;
+    setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void;
+    setFieldTouched: (field: string, touched?: boolean, shouldValidate?: boolean) => void;
+    flatten?: boolean;
+}): import("react").JSX.Element | null;

package/dist/form/Wizard/WizardStepIndicator.d.ts

@@ -0,0 +1,2 @@
+import type { WizardStepIndicatorProps } from './types.js';
+export declare function WizardStepIndicator({ stepOrder, currentStep, steps, visitedSteps, invalidSteps, onStepClick, allowJump, hideStepNumbers, }: WizardStepIndicatorProps): import("react").JSX.Element;

package/dist/form/Wizard/types.d.ts

@@ -0,0 +1,171 @@
+interface WizardNavigation {
+    /** Show step indicator (dots with connecting lines) */
+    showSteps?: boolean;
+    /** Allow clicking on completed steps to jump to them */
+    allowJump?: boolean;
+    /** Hide step numbers in step dots, show only titles */
+    hideStepNumbers?: boolean;
+}
+/**
+ * Wizard-specific configuration in $meta
+ */
+export interface WizardConfig {
+    /** Must be 'wizard' to activate wizard mode */
+    mode: 'wizard';
+    /** Navigation UI options */
+    navigation?: WizardNavigation;
+    /** Label for the final submit button */
+    submitLabel?: string;
+    /** Use URL-based routing instead of component state */
+    urlBased?: boolean;
+    /** Flatten step fields into top-level inputs (default: true). Set false to preserve step keys as nested objects. */
+    flatten?: boolean;
+}
+export interface StepFieldConfig {
+    /** Must be 'step' */
+    type: 'step';
+    /** Title shown in step indicator */
+    title: string;
+    /** Optional description/subtitle shown below title */
+    description?: string;
+    /** Schema for fields within this step */
+    options: Record<string, any>;
+    /** Validate current step before proceeding to next (default: true) */
+    validateOnNext?: boolean;
+    /** Allow skipping this step without validation */
+    canSkip?: boolean;
+    /** Custom label for next button on this step */
+    nextLabel?: string;
+    /** Custom label for previous button on this step */
+    prevLabel?: string;
+    /** Optional tooltip text */
+    tooltip?: string | string[];
+    /** Hidden field support */
+    hidden?: boolean;
+    /** Disable this step */
+    disabled?: boolean;
+}
+/**
+ * Internal wizard state managed by useWizardState hook
+ */
+export interface WizardState {
+    /** Current step ID/key */
+    currentStep: string;
+    /** Set of step IDs that have been visited */
+    visitedSteps: Set<string>;
+    /** Set of step IDs that have validation errors */
+    invalidSteps: Set<string>;
+    /** List of all step keys in order */
+    stepOrder: string[];
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether the wizard is on the last step */
+    isLastStep: boolean;
+    /** Whether the wizard can proceed to next step */
+    canProceedToNext: boolean;
+    /** Whether user can go back */
+    canGoBack: boolean;
+}
+/**
+ * Extracted wizard configuration and step information
+ */
+export interface ParsedWizardConfig {
+    /** Wizard configuration from $meta */
+    config: WizardConfig;
+    /** Steps keyed by their field name */
+    steps: Record<string, StepFieldConfig>;
+    /** Ordered list of step keys */
+    stepOrder: string[];
+    /** Schema for non-step fields (should be none in pure wizard) */
+    otherFields: Record<string, any>;
+}
+/**
+ * Wizard navigation parameters
+ */
+/**
+ * Props for WizardContainer component
+ */
+export interface WizardContainerProps {
+    /** Parsed wizard configuration and steps */
+    wizardConfig: ParsedWizardConfig;
+    /** Current form values */
+    values: Record<string, any>;
+    /** Callback when values change */
+    onChange?: (values: Record<string, any>) => void;
+    /** Callback when wizard is submitted */
+    onSubmit?: (values: Record<string, any>) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Label position for fields */
+    labelPosition?: 'left' | 'top';
+    /** Missing fields list */
+    missingFields?: string[];
+    /** Space compact mode */
+    spaceCompact?: boolean;
+    /** Workflow form mode */
+    workflowForm?: boolean;
+}
+/**
+ * Props for WizardStepIndicator component
+ */
+export interface WizardStepIndicatorProps {
+    /** Ordered list of step keys */
+    stepOrder: string[];
+    /** Current step key */
+    currentStep: string;
+    /** Steps configuration */
+    steps: Record<string, StepFieldConfig>;
+    /** Set of visited step keys */
+    visitedSteps: Set<string>;
+    /** Set of invalid step keys */
+    invalidSteps: Set<string>;
+    /** Callback when step is clicked */
+    onStepClick?: (stepKey: string) => boolean;
+    /** Whether clicking completed steps is allowed */
+    allowJump?: boolean;
+    /** Hide step numbers */
+    hideStepNumbers?: boolean;
+}
+/**
+ * Props for WizardNavigation component
+ */
+export interface WizardNavigationProps {
+    /** Current step key */
+    currentStep: string;
+    /** List of step keys in order */
+    stepOrder: string[];
+    /** Whether user can go to next step */
+    canGoToNext: boolean;
+    /** Whether user can go back */
+    canGoBack: boolean;
+    /** Whether current step is valid */
+    isCurrentStepValid: boolean;
+    /** Custom label for next button */
+    nextLabel?: string;
+    /** Custom label for previous button */
+    prevLabel?: string;
+    /** Custom label for submit button (on last step) */
+    submitLabel?: string;
+    /** Callback to go to next step */
+    onNext: () => Promise<boolean>;
+    /** Callback to go to previous step */
+    onPrevious: () => void;
+    /** Callback to submit wizard */
+    onSubmit: () => Promise<void>;
+}
+/**
+ * Props for WizardStepContent component
+ */
+export interface WizardStepContentProps {
+    /** Current step key */
+    currentStep: string;
+    /** Current step configuration */
+    stepConfig: StepFieldConfig;
+    /** Form values */
+    values: Record<string, any>;
+    /** Update form values */
+    onValuesChange?: (values: Record<string, any>) => void;
+    /** Additional props to pass to FieldsFromOptions */
+    [key: string]: any;
+}
+export {};

package/dist/form/Wizard/useWizardState.d.ts

@@ -0,0 +1,28 @@
+import type { StepFieldConfig, WizardState } from './types.js';
+interface UseWizardStateProps {
+    /** Ordered list of step keys */
+    stepOrder: string[];
+    /** Step configurations keyed by step ID */
+    steps: Record<string, StepFieldConfig>;
+    /** Function to validate current step */
+    validateStep: (stepKey: string) => Promise<boolean>;
+    /** Initial step to start with (default: first step) */
+    initialStep?: string;
+}
+export declare function useWizardState({ stepOrder, steps, validateStep, initialStep, }: UseWizardStateProps): {
+    currentStep: string;
+    visitedSteps: Set<string>;
+    invalidSteps: Set<string>;
+    isLastStep: boolean;
+    canGoBack: boolean;
+    currentStepIndex: number;
+    totalSteps: number;
+    goToNext: () => Promise<boolean>;
+    goToPrevious: () => void;
+    jumpToStep: (stepKey: string) => boolean;
+    reset: () => void;
+    markStepVisited: (stepKey: string) => void;
+    markStepInvalid: (stepKey: string, invalid: boolean) => void;
+    getState: () => WizardState;
+};
+export {};

package/dist/form/Wizard/utils.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedWizardConfig } from './types.js';
+export declare function parseWizardConfig(options: Record<string, any>): ParsedWizardConfig | null;

package/dist/form/fieldRegistry.d.ts

@@ -0,0 +1,7 @@
+import type React from 'react';
+import type { FieldComponentProps } from './types/fieldComponentTypes.js';
+export type FieldComponent = React.ComponentType<FieldComponentProps<any, any>>;
+export declare const FieldRegistryContext: React.Context<Record<string, FieldComponent>>;
+/** Returns null for field types no registry knows. Per-form `fields` win over
+ * the provider's `slots.formFields`, which win over the core registry. */
+export declare function Registry(props: FieldComponentProps<any>): React.JSX.Element | null;

package/dist/form/index.d.ts

@@ -0,0 +1,16 @@
+export { DynamicForm, DynamicDefaultsSync, FieldsFromOptions, GroupHeader, MultiSelectionDropdown, StatusBlock, collectFieldsWithDefaults, findSelfReferencingFieldNames, getInstanceTypesForForm, resolveMetaOverrides, type DynamicFormProps, type TSetFormDirty, } from './Form.js';
+export { type FieldComponent, FieldRegistryContext, Registry, } from './fieldRegistry.js';
+export { FieldWrapper } from './FieldWrapper.js';
+export { enforceOneMustBeTrue, flattenGroups, impureSetValueFromPath, initializeValues, resolvedFlag, } from './lib.js';
+export { default as DropdownWrapper } from './SpecialTypes/DropdownWrapper.js';
+export { FormikCustomDropdown, FormikCustomInput, FormikNumericInput, } from './SpecialTypes/index.js';
+export { default as FormikMultiSelectDropdown } from './SpecialTypes/FormikMultiSelectDropdown.js';
+export { resolvePwString, resolvePwValue, type PwResolverOptions, } from './utils/pwResolver.js';
+export { ResourceOptionIcon } from './Fields/ResourceOptionIcon.js';
+export { default as NumberField, type INumberField, } from './Fields/NumberField.js';
+export { getInvalidDurationPaths, setDurationValidity, } from './Fields/durationValidity.js';
+export { FLEX_MAX_DURATION_RANGE, FLEX_WAIT_TIME_RANGE, STANDARD_MAX_DURATION_RANGE, collectPartitionDurationIssues, formatSecondsAsSlurmDuration, parseSlurmDuration, } from './utils/slurmDuration.js';
+export { applySecondaryField } from './utils/secondaryField.js';
+export { useParsedOpts } from './useParsedOpts.js';
+export * from './types/fieldTypes.js';
+export * from './types/fieldComponentTypes.js';