@morscherlab/mint-sdk 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/composables/useControlSchema.d.ts

@@ -0,0 +1,321 @@
+import { ComputedRef, Ref } from 'vue';
+import { PillNavItem, SidebarToolSection, SelectOption, SettingsModalSchema, TopBarSettingsConfig, TopBarTab } from '../types';
+import { FieldCondition, FieldValidation, FormFieldSchema, FormFieldType, FormSchema, FormSectionSchema } from '../types/form-builder';
+import { WellConcentration } from './useDoseCalculator';
+export type ControlOptionValue = string | number | boolean;
+export type ControlOption = ControlOptionValue | SelectOption<unknown>;
+export type ControlPrimitive = string | number | boolean;
+export type ControlShorthand = ControlPrimitive | readonly ControlOption[];
+export type ControlInput = ControlDefinition | ControlShorthand;
+export interface ControlSectionConfig {
+    id?: string;
+    label?: string;
+    title?: string;
+    description?: string;
+    subtitle?: string;
+    icon?: string | string[];
+    iconColor?: string;
+    iconBg?: string;
+    columns?: 1 | 2 | 3;
+    condition?: FieldCondition;
+    defaultOpen?: boolean;
+    showToggle?: boolean;
+}
+export interface ControlViewConfig {
+    label?: string;
+    icon?: string;
+    to?: string;
+    href?: string;
+    disabled?: boolean;
+    children?: TopBarTab['children'];
+}
+export interface ControlSidebarConfig extends Omit<ControlSectionConfig, 'id' | 'title' | 'description' | 'columns'> {
+    enabled?: boolean;
+}
+export interface ControlDefinition {
+    type?: FormFieldType;
+    label?: string;
+    default?: unknown;
+    defaultValue?: unknown;
+    placeholder?: string;
+    hint?: string;
+    size?: 'sm' | 'md' | 'lg';
+    disabled?: boolean;
+    readonly?: boolean;
+    required?: boolean | string;
+    min?: number | {
+        value: number;
+        message: string;
+    };
+    max?: number | {
+        value: number;
+        message: string;
+    };
+    minLength?: number | {
+        value: number;
+        message: string;
+    };
+    maxLength?: number | {
+        value: number;
+        message: string;
+    };
+    email?: boolean | string;
+    pattern?: string | {
+        value: string;
+        message: string;
+    };
+    validation?: FieldValidation;
+    condition?: FieldCondition;
+    options?: readonly ControlOption[];
+    section?: string;
+    sectionLabel?: string;
+    sectionDescription?: string;
+    sectionSubtitle?: string;
+    view?: string;
+    order?: number;
+    colSpan?: number;
+    props?: Record<string, unknown>;
+    sidebar?: boolean | ControlSidebarConfig;
+}
+export type ControlSchema = Record<string, ControlInput>;
+export type ControlFormSchema = Extract<FormSchema, {
+    sections: FormSectionSchema[];
+}>;
+export interface ControlSchemaOptions {
+    view?: string;
+    views?: Record<string, ControlViewConfig>;
+    section?: string;
+    sectionLabel?: string;
+    sections?: Record<string, ControlSectionConfig>;
+    columns?: 1 | 2 | 3;
+    submitLabel?: string;
+    cancelLabel?: string;
+    showCancel?: boolean;
+}
+export interface ControlWorkspaceOptions extends ControlSchemaOptions {
+    initialValues?: Record<string, unknown>;
+    topBarSettings?: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions' | 'values'>;
+}
+export interface ControlModelSectionConfig extends ControlSectionConfig {
+    controls: ControlSchema;
+    sidebar?: boolean | ControlSidebarConfig;
+}
+export interface ControlModelViewConfig extends ControlViewConfig {
+    controls?: ControlSchema;
+    section?: string;
+    sectionLabel?: string;
+    sectionDescription?: string;
+    sections?: Record<string, ControlModelSectionConfig>;
+}
+export interface ControlModel extends Omit<ControlWorkspaceOptions, 'sections' | 'views'> {
+    controls?: ControlSchema;
+    sections?: Record<string, ControlModelSectionConfig>;
+    views?: Record<string, ControlModelViewConfig>;
+    /** Optional ControlWorkspaceView componentProps mapping returned with the generated controls/options. */
+    componentProps?: ControlComponentPropsMap;
+    /** Optional named componentProps mappings returned for multiple SDK components. */
+    componentPropsById?: ControlComponentPropsByIdMap;
+}
+export interface ControlModelBinding {
+    controls: ControlSchema;
+    controlOptions: ControlWorkspaceOptions;
+    componentProps?: ControlComponentPropsMap;
+    componentPropsById?: ControlComponentPropsByIdMap;
+}
+export interface ControlSidebarBinding {
+    panels: Record<string, SidebarToolSection[]>;
+    forms: Record<string, ControlFormSchema>;
+    viewIds: string[];
+    viewItems: PillNavItem[];
+    defaultView: string;
+}
+export interface ControlFormBinding {
+    schema: ControlFormSchema;
+}
+export interface ControlSettingsBinding {
+    schema: SettingsModalSchema;
+}
+export interface ControlTopBarSettingsBinding {
+    showSettings: true;
+    settingsConfig: TopBarSettingsConfig;
+}
+export interface ControlWorkspaceFormBinding extends ControlFormBinding {
+    modelValue: Record<string, unknown>;
+    'onUpdate:modelValue': (values: Record<string, unknown>) => void;
+}
+export interface ControlWorkspaceSidebarBinding extends ControlSidebarBinding {
+    activeView: string;
+    modelValue: Record<string, unknown>;
+    'onUpdate:modelValue': (values: Record<string, unknown>) => void;
+    values: Record<string, unknown>;
+    'onUpdate:values': (values: Record<string, unknown>) => void;
+}
+export interface ControlWorkspaceTopBarSettingsBinding extends ControlTopBarSettingsBinding {
+    onSettingsValuesChange: (values: Record<string, unknown>) => void;
+}
+export interface ControlWorkspaceTopBarBinding {
+    tabs: TopBarTab[];
+    currentTabId: string;
+    onTabSelect: (tab: TopBarTab) => void;
+}
+export interface ControlWorkspacePillNavBinding {
+    items: PillNavItem[];
+    currentItemId: string;
+    onSelect: (item: PillNavItem) => void;
+}
+export interface ControlWorkspaceAppTopBarPillBinding extends ControlWorkspaceTopBarSettingsBinding {
+    pillNav: PillNavItem[];
+    currentPillId: string;
+    onPillSelect: (item: PillNavItem) => void;
+}
+export interface ControlWorkspaceAppTopBarTabsBinding extends ControlWorkspaceTopBarSettingsBinding {
+    tabs: TopBarTab[];
+    currentTabId: string;
+    onTabSelect: (tab: TopBarTab) => void;
+}
+export interface ControlWorkspaceComponentBindings {
+    form: ControlWorkspaceFormBinding;
+    sidebar: ControlWorkspaceSidebarBinding;
+    topBar: ComputedRef<ControlWorkspaceAppTopBarPillBinding>;
+    topBarTabs: ComputedRef<ControlWorkspaceAppTopBarTabsBinding>;
+    topBarSettings: ControlWorkspaceTopBarSettingsBinding;
+    pillNav: ControlWorkspacePillNavBinding;
+    componentProps: ComputedRef<Record<string, unknown>>;
+    componentPropsById: ComputedRef<Record<string, Record<string, unknown>>>;
+}
+export type ControlComponentPropSource<TValues extends Record<string, unknown> = Record<string, unknown>> = (keyof TValues & string) | ((values: TValues) => unknown);
+export type ControlComponentPropsMap<TValues extends Record<string, unknown> = Record<string, unknown>> = readonly (keyof TValues & string)[] | Record<string, ControlComponentPropSource<TValues>>;
+export type ControlComponentPropsByIdMap<TValues extends Record<string, unknown> = Record<string, unknown>> = Record<string, ControlComponentPropsMap<TValues>>;
+export interface WellPlateControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    selectedWells?: ControlComponentPropSource<TValues>;
+    format?: ControlComponentPropSource<TValues>;
+    wells?: ControlComponentPropSource<TValues>;
+    disabled?: ControlComponentPropSource<TValues>;
+    readonly?: ControlComponentPropSource<TValues>;
+    showLegend?: ControlComponentPropSource<TValues>;
+    showSampleTypeIndicator?: ControlComponentPropSource<TValues>;
+    /** Listener for WellPlate v-model updates. Set false to keep generated props one-way. */
+    onUpdateModelValue?: ((values: TValues) => (wellIds: string[]) => void) | false;
+}
+export interface DoseCalculatorControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    mode?: ControlComponentPropSource<TValues>;
+    targetWells?: ControlComponentPropSource<TValues>;
+    /** Control value key used by the default apply-to-wells handler. */
+    wells?: ControlComponentPropSource<TValues>;
+    disabled?: ControlComponentPropSource<TValues>;
+    molecularWeight?: ControlComponentPropSource<TValues>;
+    /** Listener for DoseCalculator apply-to-wells. Set false to keep generated props one-way. */
+    onApplyToWells?: ((values: TValues) => (results: WellConcentration[]) => void) | false;
+}
+export interface WellPlateDoseControlPropsOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    plateId?: string;
+    doseId?: string;
+    plate?: WellPlateControlPropsOptions<TValues>;
+    dose?: DoseCalculatorControlPropsOptions<TValues>;
+}
+export interface DoseDesignControlModelOptions {
+    viewId?: string;
+    viewLabel?: string;
+    sectionId?: string;
+    sectionLabel?: string;
+    sectionDescription?: string;
+    selectedWells?: readonly string[];
+    plateFormat?: number;
+    plateFormats?: readonly number[];
+    doseMode?: 'serial' | 'dilution' | 'conversion';
+    doseModes?: readonly ('serial' | 'dilution' | 'conversion')[];
+    disabled?: boolean;
+    includeMolecularWeight?: boolean;
+    molecularWeight?: number;
+    componentProps?: WellPlateDoseControlPropsOptions;
+}
+export interface UseControlSchemaReturn<TControls extends ControlSchema> {
+    controls: TControls;
+    fields: FormFieldSchema[];
+    formSchema: ControlFormSchema;
+    form: ControlFormBinding;
+    settingsSchema: SettingsModalSchema;
+    settings: ControlSettingsBinding;
+    topBarSettingsConfig: TopBarSettingsConfig;
+    topBarSettings: ControlTopBarSettingsBinding;
+    sidebarPanels: Record<string, SidebarToolSection[]>;
+    viewIds: string[];
+    viewItems: PillNavItem[];
+    topBarTabs: TopBarTab[];
+    defaultView: string;
+    sectionSchemas: Record<string, ControlFormSchema>;
+    sidebar: ControlSidebarBinding;
+    initialValues: ControlValues<TControls>;
+    sectionSchema: (sectionId: string) => ControlFormSchema;
+}
+export interface UseControlWorkspaceReturn<TControls extends ControlSchema> extends Omit<UseControlSchemaReturn<TControls>, 'form' | 'sidebar' | 'topBarSettings'> {
+    schema: UseControlSchemaReturn<TControls>;
+    values: ControlValues<TControls> & Record<string, unknown>;
+    activeView: Ref<string>;
+    form: ControlWorkspaceFormBinding;
+    sidebar: ControlWorkspaceSidebarBinding;
+    topBar: ControlWorkspaceTopBarBinding;
+    pillNav: ControlWorkspacePillNavBinding;
+    topBarSettings: ControlWorkspaceTopBarSettingsBinding;
+    bindings: ControlWorkspaceComponentBindings;
+    componentProps: ComputedRef<Record<string, unknown>>;
+    componentPropsById: ComputedRef<Record<string, Record<string, unknown>>>;
+    setActiveView: (viewId: string) => void;
+    setValues: (values: Record<string, unknown>) => void;
+    resetValues: (values?: Record<string, unknown>) => void;
+    getComponentProps: (mapping?: ControlComponentPropsMap<ControlValues<TControls> & Record<string, unknown>>) => Record<string, unknown>;
+    getComponentPropsById: (mappings?: ControlComponentPropsByIdMap<ControlValues<TControls> & Record<string, unknown>>) => Record<string, Record<string, unknown>>;
+}
+export type ControlValues<TControls extends ControlSchema> = {
+    [K in keyof TControls]: ControlValue<TControls[K]>;
+};
+type ControlValue<TControl> = TControl extends {
+    default: infer TDefault;
+} ? TDefault : TControl extends {
+    defaultValue: infer TDefaultValue;
+} ? TDefaultValue : TControl extends readonly [infer First, ...unknown[]] ? OptionValue<First> : TControl extends ControlPrimitive ? TControl : unknown;
+type OptionValue<TOption> = TOption extends SelectOption<infer TValue> ? TValue : TOption;
+/** Preserve literal control keys while marking an object as a MINT control schema. */
+export declare function defineControls<TControls extends ControlSchema>(controls: TControls): TControls;
+/** Flatten a simple view/section control data model into ControlWorkspaceView props for generated forms and sidebars. */
+export declare function defineControlModel(model: ControlModel): ControlModelBinding;
+/** Build default values for a control schema, matching FormBuilder field defaults. */
+export declare function getControlDefaults<TControls extends ControlSchema>(controls: TControls): ControlValues<TControls>;
+/** Map control workspace values into component props for direct `v-bind` usage. */
+export declare function controlValuesToComponentProps<TValues extends Record<string, unknown>>(values: TValues, mapping?: ControlComponentPropsMap<TValues>): Record<string, unknown>;
+/** Return a default WellPlate prop mapping for generated control workspaces. */
+export declare function defineWellPlateControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(options?: WellPlateControlPropsOptions<TValues>): ControlComponentPropsMap<TValues>;
+/** Return a default DoseCalculator prop mapping for generated control workspaces. */
+export declare function defineDoseCalculatorControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(options?: DoseCalculatorControlPropsOptions<TValues>): ControlComponentPropsMap<TValues>;
+/** Return named WellPlate + DoseCalculator prop mappings for one dose-design control model. */
+export declare function defineWellPlateDoseControlProps<TValues extends Record<string, unknown> = Record<string, unknown>>(options?: WellPlateDoseControlPropsOptions<TValues>): ControlComponentPropsByIdMap<TValues>;
+/** Return a complete ControlWorkspaceView model for WellPlate + DoseCalculator dose design. */
+export declare function defineDoseDesignControlModel(options?: DoseDesignControlModelOptions): ControlModelBinding;
+export declare function mergeControlWorkspaceOptions(base?: ControlWorkspaceOptions, override?: ControlWorkspaceOptions): ControlWorkspaceOptions;
+/** Convert a compact control schema into a FormBuilder schema. */
+export declare function controlsToFormSchema(controls: ControlSchema, options?: ControlSchemaOptions): ControlFormSchema;
+/** Convert controls into AppSidebar panels grouped by view and section. */
+export declare function controlsToSidebarPanels(controls: ControlSchema, options?: ControlSchemaOptions): Record<string, SidebarToolSection[]>;
+/** Convert controls into a SettingsModal schema grouped by the same sections. */
+export declare function controlsToSettingsSchema(controls: ControlSchema, options?: ControlSchemaOptions): SettingsModalSchema;
+/** Convert controls into an AppTopBar settingsConfig object that passes compact controls through to SettingsModal. */
+export declare function controlsToTopBarSettingsConfig(controls: ControlSchema, options?: ControlSchemaOptions, config?: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions'>): TopBarSettingsConfig;
+/** Return generated control view IDs that have at least one sidebar panel. */
+export declare function controlsToViewIds(controls: ControlSchema, options?: ControlSchemaOptions): string[];
+/** Return AppPillNav-compatible view items for switching generated control sidebars. */
+export declare function controlsToViewItems(controls: ControlSchema, options?: ControlSchemaOptions): PillNavItem[];
+/** Return AppTopBar-compatible tabs for the same views that drive generated AppSidebar panels. */
+export declare function controlsToTopBarTabs(controls: ControlSchema, options?: ControlSchemaOptions): TopBarTab[];
+/** Return the first generated sidebar view ID, or an empty string when controls render no sidebar panels. */
+export declare function getDefaultControlView(controls: ControlSchema, options?: ControlSchemaOptions): string;
+/** Return a headerless single-section FormBuilder schema for rendering inside an AppSidebar section slot. */
+export declare function controlsToSectionFormSchema(controls: ControlSchema, sectionId: string, options?: ControlSchemaOptions): ControlFormSchema;
+/** Return headerless FormBuilder schemas keyed by section ID for AppSidebar auto-rendering. */
+export declare function controlsToSectionFormSchemas(controls: ControlSchema, options?: ControlSchemaOptions): Record<string, ControlFormSchema>;
+/** Prepare FormBuilder, SettingsModal, AppTopBar settings, AppSidebar, and initial values from one compact control model. */
+export declare function useControlSchema<TControls extends ControlSchema>(controls: TControls, options?: ControlSchemaOptions): UseControlSchemaReturn<TControls>;
+/** Prepare shared reactive values plus AppTopBar/AppSidebar/FormBuilder bindings from one simple controls data model. */
+export declare function useControlWorkspace<TControls extends ControlSchema>(controlsOrModel: TControls | (ControlModelBinding & {
+    controls: TControls;
+}), options?: ControlWorkspaceOptions): UseControlWorkspaceReturn<TControls>;
+export {};

package/dist/composables/useDebouncedWatch.d.ts

@@ -0,0 +1,20 @@
+import { Ref, WatchOptions, WatchSource, WatchStopHandle } from 'vue';
+export type DebouncedWatchCleanup = () => void;
+export type DebouncedWatchSource<T> = WatchSource<T> | WatchSource<unknown>[] | (() => T);
+export type DebouncedWatchCallback<T> = (value: T, oldValue: T | undefined, onCleanup: (cleanup: DebouncedWatchCleanup) => void) => void | Promise<void>;
+export interface UseDebouncedWatchOptions extends WatchOptions {
+    /** Debounce interval in milliseconds. */
+    delay?: number;
+}
+export interface UseDebouncedWatchReturn {
+    /** Whether a callback is currently scheduled. */
+    isPending: Ref<boolean>;
+    /** Cancel the pending callback without stopping the watcher. */
+    cancel: () => void;
+    /** Run the pending callback immediately, if one is scheduled. */
+    flush: () => void;
+    /** Stop the watcher and clear pending callbacks. */
+    stop: WatchStopHandle;
+}
+/** Watch a Vue source with debounced callback execution and explicit cancel/flush controls. */
+export declare function useDebouncedWatch<T>(source: DebouncedWatchSource<T>, callback: DebouncedWatchCallback<T>, options?: UseDebouncedWatchOptions): UseDebouncedWatchReturn;

package/dist/composables/useDropdownState.d.ts

@@ -0,0 +1,19 @@
+import { Ref } from 'vue';
+export interface UseDropdownStateOptions {
+    closeOnOutsideClick?: boolean;
+    closeOnEscape?: boolean;
+    insideRefs?: Array<Ref<HTMLElement | null>>;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+export interface UseDropdownStateReturn {
+    isOpen: Ref<boolean>;
+    rootRef: Ref<HTMLElement | null>;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    handleClickOutside: (event: MouseEvent) => void;
+    handleKeydown: (event: KeyboardEvent) => void;
+}
+/** Shared disclosure state for dropdown-style SDK components. */
+export declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;

package/dist/composables/useEventListener.d.ts

@@ -0,0 +1,13 @@
+import { Ref } from 'vue';
+export type EventTargetGetter<TTarget extends EventTarget = EventTarget> = () => TTarget | null | undefined;
+export type EventTargetLike<TTarget extends EventTarget = EventTarget> = TTarget | Ref<TTarget | null | undefined> | EventTargetGetter<TTarget> | null | undefined;
+export type EventListenerEnabled = boolean | Ref<boolean>;
+export interface UseEventListenerObjectOptions extends AddEventListenerOptions {
+    enabled?: EventListenerEnabled;
+}
+export type UseEventListenerOptions = boolean | UseEventListenerObjectOptions;
+export type EventListenerStop = () => void;
+export type EventMapFor<TTarget extends EventTarget> = TTarget extends Window ? WindowEventMap : TTarget extends Document ? DocumentEventMap : TTarget extends HTMLElement ? HTMLElementEventMap : Record<string, Event>;
+export type EventFor<TTarget extends EventTarget, TType extends string> = TType extends keyof EventMapFor<TTarget> ? EventMapFor<TTarget>[TType] : Event;
+/** Bind a DOM event listener on mount, remove it on unmount, and rebind when a ref target changes. */
+export declare function useEventListener<TTarget extends EventTarget = EventTarget, TType extends string = string>(target: EventTargetLike<TTarget>, type: TType, listener: (event: EventFor<TTarget, TType>) => void, options?: UseEventListenerOptions): EventListenerStop;

package/dist/composables/useExpansionSet.d.ts

@@ -0,0 +1,21 @@
+import { ComputedRef, Ref } from 'vue';
+export type ExpansionSetSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export interface UseExpansionSetOptions {
+    defaultIds?: ExpansionSetSource<readonly string[] | null | undefined>;
+    allIds?: ExpansionSetSource<readonly string[] | null | undefined>;
+    expandAll?: ExpansionSetSource<boolean | null | undefined>;
+}
+export interface UseExpansionSetReturn {
+    expandedIds: Ref<Set<string>>;
+    expandedList: ComputedRef<string[]>;
+    isExpanded: (id: string) => boolean;
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggle: (id: string) => boolean;
+    expandMany: (ids: readonly string[]) => void;
+    setExpanded: (ids: readonly string[]) => void;
+    collapseAll: () => void;
+    reset: () => void;
+}
+/** Shared expansion state for trees, grouped selectors, and disclosure lists. */
+export declare function useExpansionSet(options?: UseExpansionSetOptions): UseExpansionSetReturn;

package/dist/composables/useExperimentData.d.ts

@@ -5,13 +5,23 @@ export interface UseExperimentDataOptions {
     immediate?: boolean;
 }
 export interface UseExperimentDataReturn {
+    /** Raw experiment data payload from `/experiments/{id}/data`, or null. */
     data: Ref<Record<string, unknown> | null>;
+    /** Hierarchy tree rows normalised from `tree_data` or `treeData`. */
     treeData: ComputedRef<TreeNode[]>;
+    /** Table rows normalised from `table_data` or `tableData`. */
     tableData: ComputedRef<Record<string, unknown>[]>;
+    /** Summary payload normalised from `summary_data` or `summaryData`, or null. */
     summaryData: ComputedRef<SummaryData | null>;
+    /** Whether experiment data is currently loading. */
     isLoading: Ref<boolean>;
+    /** Error message from the last failed fetch, or null. */
     error: Ref<string | null>;
+    /** Timestamp of the last successful experiment data fetch, or null. */
+    lastLoadedAt: Ref<Date | null>;
+    /** Fetch experiment data for an experiment id. */
     fetch: (experimentId: number) => Promise<void>;
+    /** Refetch the most recently fetched experiment id. */
     refresh: () => Promise<void>;
 }
 /** Fetches and normalises experiment output data (tree, table, summary) from the platform API. */

package/dist/composables/useExperimentSave.d.ts

@@ -1,4 +1,6 @@
-import { Ref } from 'vue';
+import { ComputedRef, Ref } from 'vue';
+import { CreateLcmsBatchCollectionOptions, CreateQpcrExpressionCollectionOptions, CreateWellPlateScreenCollectionOptions, TemplatePresetId } from '../templates';
+type TemplatePresetCollectionOptions = CreateWellPlateScreenCollectionOptions | CreateQpcrExpressionCollectionOptions | CreateLcmsBatchCollectionOptions;
 export interface UseExperimentSaveOptions {
     /** Default plugin_id for all save/load calls. */
     pluginId?: string;
@@ -8,16 +10,32 @@ export interface UseExperimentSaveOptions {
     apiBaseUrl?: string;
 }
 export interface UseExperimentSaveReturn {
+    /** Current experiment id from platform injection, URL query, or URL path. */
+    currentExperimentId: ComputedRef<number | undefined>;
+    /** Whether a current experiment id is available. */
+    hasCurrentExperiment: ComputedRef<boolean>;
     /** Whether a save operation is in progress. */
     isSaving: Ref<boolean>;
+    /** Whether a load or delete operation is in progress. */
+    isLoading: Ref<boolean>;
     /** Error message from the last failed operation, or null. */
     error: Ref<string | null>;
+    /** Timestamp of the last successful load, or null. */
+    lastLoadedAt: Ref<Date | null>;
     /** Timestamp of the last successful save, or null. */
     lastSavedAt: Ref<Date | null>;
     /** Save design data for an experiment. */
     saveDesign: (experimentId: number, data: Record<string, unknown>) => Promise<boolean>;
+    /** Save design data for the current experiment. */
+    saveCurrentDesign: (data: Record<string, unknown>) => Promise<boolean>;
+    /** Create and save a built-in biology template preset as experiment design data. */
+    saveTemplatePreset: (experimentId: number, name: TemplatePresetId | string, options?: TemplatePresetCollectionOptions) => Promise<boolean>;
+    /** Create and save a built-in biology template preset for the current experiment. */
+    saveCurrentTemplatePreset: (name: TemplatePresetId | string, options?: TemplatePresetCollectionOptions) => Promise<boolean>;
     /** Save analysis result for an experiment. */
     saveAnalysis: (experimentId: number, result: Record<string, unknown>) => Promise<boolean>;
+    /** Save analysis result for the current experiment. */
+    saveCurrentAnalysis: (result: Record<string, unknown>) => Promise<boolean>;
     /** Save design and/or analysis in one call. */
     save: (experimentId: number, opts: {
         design?: Record<string, unknown>;
@@ -25,12 +43,23 @@ export interface UseExperimentSaveReturn {
     }) => Promise<boolean>;
     /** Load design data for an experiment. */
     loadDesign: (experimentId: number) => Promise<Record<string, unknown> | null>;
+    /** Load design data for the current experiment. */
+    loadCurrentDesign: () => Promise<Record<string, unknown> | null>;
     /** Load analysis result for an experiment. */
     loadAnalysis: (experimentId: number) => Promise<Record<string, unknown> | null>;
+    /** Load analysis result for the current experiment. */
+    loadCurrentAnalysis: () => Promise<Record<string, unknown> | null>;
     /** Delete design data for an experiment. */
     deleteDesign: (experimentId: number) => Promise<boolean>;
+    /** Delete design data for the current experiment. */
+    deleteCurrentDesign: () => Promise<boolean>;
     /** Delete analysis result for an experiment. */
     deleteAnalysis: (experimentId: number) => Promise<boolean>;
+    /** Delete analysis result for the current experiment. */
+    deleteCurrentAnalysis: () => Promise<boolean>;
+    /** Require and return the current experiment id, or throw when missing. */
+    requireCurrentExperimentId: () => number;
 }
-/** Persists and loads experiment design and analysis data via the plugin's API endpoint. */
+/** Persists experiment design, analysis, and built-in template preset data through the platform API. */
 export declare function useExperimentSave(options?: UseExperimentSaveOptions): UseExperimentSaveReturn;
+export {};

package/dist/composables/useExperimentSelector.d.ts

@@ -7,23 +7,43 @@ export interface UseExperimentSelectorOptions {
     immediate?: boolean;
 }
 export interface UseExperimentSelectorReturn {
+    /** Current page of fetched experiment rows. */
     experiments: Ref<ExperimentSummary[]>;
+    /** Total matching experiment count reported by the platform. */
     total: Ref<number>;
+    /** Currently selected experiment, or null. */
     selectedExperiment: Ref<ExperimentSummary | null>;
+    /** Mutable filters used for the next fetch. */
     filters: ExperimentFilters;
+    /** Whether experiment rows are currently loading. */
     isLoading: Ref<boolean>;
+    /** Error message from the last failed fetch, or null. */
     error: Ref<string | null>;
+    /** Timestamp of the last successful experiment fetch, or null. */
+    lastLoadedAt: Ref<Date | null>;
+    /** Current zero-based page index. */
     page: Ref<number>;
+    /** Whether another page can be loaded. */
     hasMore: ComputedRef<boolean>;
+    /** Combined sort key in the form `<field>:<asc|desc>`. */
     sortKey: Ref<string>;
+    /** Available experiment type options for filter UI. */
     experimentTypes: Ref<ExperimentTypeOption[]>;
+    /** Available project options for filter UI. */
     projects: Ref<SelectOption<string>[]>;
+    /** Fetched experiments grouped by project name. */
     groupedByProject: ComputedRef<[string, ExperimentSummary[]][]>;
+    /** Fetch the current page with the current filters. */
     fetch: () => Promise<void>;
+    /** Fetch and append the next page when available. */
     loadMore: () => Promise<void>;
+    /** Clear fetched rows and refetch page zero. */
     reset: () => void;
+    /** Select an experiment. */
     select: (experiment: ExperimentSummary) => void;
+    /** Clear selection and filters. */
     clear: () => void;
+    /** Fetch experiment type and project filter options. */
     fetchFilterOptions: () => Promise<void>;
 }
 /** Fetches a paginated, filtered experiment list from the platform API for picker and selector UIs. */

package/dist/composables/useForm.d.ts

@@ -58,6 +58,8 @@ export interface UseFormReturn<T extends Record<string, unknown>> {
     validateField: (field: string) => boolean;
     validate: () => boolean;
     reset: (values?: Partial<T>) => void;
+    /** Replace the full form state and treat the provided values as the new clean baseline. */
+    replaceState: (values: T) => void;
     handleSubmit: (onSubmit: (data: T) => Promise<void> | void) => (e?: Event) => Promise<void>;
     getFieldProps: <K extends keyof T>(field: K) => {
         modelValue: T[K];

package/dist/composables/useGroupAssignment.d.ts

@@ -0,0 +1,31 @@
+import { ComputedRef, Ref } from 'vue';
+import { GroupItem } from '../types';
+export type GroupAssignmentZone = 'zone1' | 'zone2';
+export type GroupAssignmentSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export interface GroupAssignmentState {
+    group1: string[];
+    group2: string[];
+}
+export interface UseGroupAssignmentOptions {
+    groups: GroupAssignmentSource<readonly GroupItem[]>;
+    group1: GroupAssignmentSource<readonly string[]>;
+    group2: GroupAssignmentSource<readonly string[]>;
+    label1?: GroupAssignmentSource<string | null | undefined>;
+    label2?: GroupAssignmentSource<string | null | undefined>;
+    minPerGroup?: GroupAssignmentSource<number | null | undefined>;
+}
+export interface UseGroupAssignmentReturn {
+    unassignedGroups: ComputedRef<GroupItem[]>;
+    zone1Groups: ComputedRef<GroupItem[]>;
+    zone2Groups: ComputedRef<GroupItem[]>;
+    zone1Count: ComputedRef<number>;
+    zone2Count: ComputedRef<number>;
+    isValid: ComputedRef<boolean>;
+    validationMessage: ComputedRef<string | null>;
+    getZoneForGroup: (groupName: string) => GroupAssignmentZone | null;
+    assignToZone: (groupName: string, zone: GroupAssignmentZone) => GroupAssignmentState;
+    removeFromZone: (groupName: string, zone: GroupAssignmentZone) => GroupAssignmentState;
+    clearAll: () => GroupAssignmentState;
+}
+/** Shared two-zone group assignment model for control/treatment style workflows. */
+export declare function useGroupAssignment(options: UseGroupAssignmentOptions): UseGroupAssignmentReturn;

package/dist/composables/useListSelection.d.ts

@@ -0,0 +1,35 @@
+import { ComputedRef, Ref } from 'vue';
+import { SelectionLimitSource } from './useSelectionLimit';
+export type ListSelectionValue = string | number;
+export type ListSelectionSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export type WidenListSelectionValue<TValue extends ListSelectionValue> = TValue extends string ? string : TValue extends number ? number : TValue;
+export interface UseListSelectionOptions<TItem, TValue extends ListSelectionValue = ListSelectionValue> {
+    selected: ListSelectionSource<readonly TValue[]>;
+    items?: ListSelectionSource<readonly TItem[]>;
+    getValue?: (item: TItem) => TValue;
+    disabled?: ListSelectionSource<boolean | null | undefined>;
+    max?: SelectionLimitSource<number | null | undefined>;
+}
+export interface UseListSelectionReturn<TValue extends ListSelectionValue = ListSelectionValue> {
+    selectedValues: ComputedRef<TValue[]>;
+    selectedSet: ComputedRef<Set<TValue>>;
+    itemValues: ComputedRef<TValue[]>;
+    selectedCount: ComputedRef<number>;
+    itemCount: ComputedRef<number>;
+    isAllSelected: ComputedRef<boolean>;
+    isLimited: ComputedRef<boolean>;
+    isAtLimit: ComputedRef<boolean>;
+    canAddMore: ComputedRef<boolean>;
+    remaining: ComputedRef<number | undefined>;
+    isSelected: (value: TValue) => boolean;
+    isFullySelected: (values: readonly TValue[]) => boolean;
+    isPartiallySelected: (values: readonly TValue[]) => boolean;
+    selectValues: (values: readonly TValue[]) => TValue[];
+    toggleValue: (value: TValue) => TValue[];
+    toggleValues: (values: readonly TValue[]) => TValue[];
+    selectAll: () => TValue[];
+    toggleAll: () => TValue[];
+    clear: () => TValue[];
+}
+/** Shared list-selection state for checkbox lists, sample selectors, and chip selectors. */
+export declare function useListSelection<TItem = ListSelectionValue, TValue extends ListSelectionValue = TItem extends ListSelectionValue ? TItem : ListSelectionValue>(options: UseListSelectionOptions<TItem, TValue>): UseListSelectionReturn<WidenListSelectionValue<TValue>>;