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

package/dist/composables/usePlatformContext.d.ts

@@ -34,13 +34,18 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
             version: string;
             description?: string | undefined;
             icon?: string | undefined;
+            color?: string | undefined;
             route_prefix: string;
             api_prefix: string;
             nav_items?: {
-                id: string;
+                id?: string | undefined;
                 label: string;
                 path: string;
                 icon?: string | undefined;
+                description?: string | undefined;
+                requiresAuth?: boolean | undefined;
+                requiresAdmin?: boolean | undefined;
+                requiresFeature?: string | undefined;
                 children?: /*elided*/ any[] | undefined;
             }[] | undefined;
             settings?: import('..').PluginSettings | undefined;
@@ -56,7 +61,9 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
         theme: "light" | "dark" | "system";
         allowedExperimentTypes?: string[] | null | undefined;
         features?: {
+            admin?: boolean | undefined;
             experiments?: boolean | undefined;
+            samples?: boolean | undefined;
             passkey?: boolean | undefined;
             multiUser?: boolean | undefined;
         } | undefined;
@@ -68,13 +75,18 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
             version: string;
             description?: string | undefined;
             icon?: string | undefined;
+            color?: string | undefined;
             route_prefix: string;
             api_prefix: string;
             nav_items?: {
-                id: string;
+                id?: string | undefined;
                 label: string;
                 path: string;
                 icon?: string | undefined;
+                description?: string | undefined;
+                requiresAuth?: boolean | undefined;
+                requiresAdmin?: boolean | undefined;
+                requiresFeature?: string | undefined;
                 children?: /*elided*/ any[] | undefined;
             }[] | undefined;
             settings?: import('..').PluginSettings | undefined;
@@ -90,7 +102,9 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
         theme: "light" | "dark" | "system";
         allowedExperimentTypes?: string[] | null | undefined;
         features?: {
+            admin?: boolean | undefined;
             experiments?: boolean | undefined;
+            samples?: boolean | undefined;
             passkey?: boolean | undefined;
             multiUser?: boolean | undefined;
         } | undefined;
@@ -102,13 +116,18 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
         version: string;
         description?: string | undefined;
         icon?: string | undefined;
+        color?: string | undefined;
         route_prefix: string;
         api_prefix: string;
         nav_items?: {
-            id: string;
+            id?: string | undefined;
             label: string;
             path: string;
             icon?: string | undefined;
+            description?: string | undefined;
+            requiresAuth?: boolean | undefined;
+            requiresAdmin?: boolean | undefined;
+            requiresFeature?: string | undefined;
             children?: /*elided*/ any[] | undefined;
         }[] | undefined;
         settings?: import('..').PluginSettings | undefined;
@@ -121,7 +140,9 @@ export declare function usePlatformContext(options?: PlatformContextOptions): {
     } | undefined>;
     theme: import('vue').ComputedRef<"light" | "dark" | "system">;
     features: import('vue').ComputedRef<{
+        admin?: boolean | undefined;
         experiments?: boolean | undefined;
+        samples?: boolean | undefined;
         passkey?: boolean | undefined;
         multiUser?: boolean | undefined;
     } | undefined>;

package/dist/composables/usePluginApi.d.ts

@@ -6,24 +6,17 @@ export interface UsePluginApiOptions {
     fallbackPrefix?: string;
 }
 /**
- * Pre-configured API client for plugins.
+ * Legacy plugin API client resolving the plugin base URL from VITE_API_PREFIX or a fallback prefix.
  *
- * Resolves the base URL in priority order:
- * 1. `import.meta.env.VITE_API_PREFIX` (build-time env override)
- * 2. `fallbackPrefix` option (plugin's route prefix)
- * 3. `'/api'` (default)
+ * @deprecated Use `useGeneratedPluginClient()` from `mint sdk generate` for new
+ * plugin frontends. This helper remains as a compatibility shim for older
+ * plugins that still hand-wire API prefixes.
  *
- * Eliminates the repeated pattern across plugins:
+ * Migration shape for generated plugins:
  * ```ts
- * const API_BASE = import.meta.env.VITE_API_PREFIX || '/api/my-plugin'
- * const api = useApi({ baseUrl: API_BASE })
- * ```
+ * import { useGeneratedPluginClient } from '../generated/mint-plugin'
  *
- * @example
- * ```ts
- * const api = usePluginApi({ fallbackPrefix: '/api/drp' })
- * const data = await api.get('/sessions')
+ * const pluginClient = useGeneratedPluginClient()
  * ```
  */
-/** Pre-configured API client resolving the plugin base URL from VITE_API_PREFIX or a fallback prefix. */
 export declare function usePluginApi(options?: UsePluginApiOptions): import('./useApi').UseApiReturn;

package/dist/composables/usePluginClient.d.ts

@@ -0,0 +1,109 @@
+import { ComputedRef, Ref } from 'vue';
+export type PluginHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+export interface PluginEndpointContract {
+    name: string;
+    method: PluginHttpMethod;
+    path: string;
+    pathParams?: string[];
+    queryParams?: PluginEndpointParamContract[];
+    requestType?: string | null;
+    responseType?: string | null;
+}
+export interface PluginEndpointParamContract {
+    name: string;
+    fieldName: string;
+    type?: string;
+    required?: boolean;
+}
+export interface PluginNavItemContract {
+    path: string;
+    label: string;
+    id?: string;
+    icon?: string;
+    description?: string;
+    requiresAuth?: boolean;
+    requiresAdmin?: boolean;
+    requiresFeature?: string;
+}
+export interface PluginContract {
+    schemaVersion: number;
+    plugin: {
+        name?: string;
+        packageName?: string;
+        version?: string;
+        description?: string;
+        routesPrefix: string;
+        apiPrefix: string;
+        type: 'analysis' | 'experiment-design' | string;
+        analysisType?: string;
+        icon?: string;
+        color?: string;
+        navItems?: PluginNavItemContract[];
+        capabilities?: Record<string, unknown>;
+    };
+    endpoints: PluginEndpointContract[];
+    hash: string;
+}
+export interface PluginEndpointDefinition {
+    method: PluginHttpMethod;
+    path: string;
+    pathParams?: string[];
+    queryParams?: PluginEndpointParamDefinition[];
+    hasBody?: boolean;
+}
+export type PluginEndpointParamDefinition = string | {
+    name: string;
+    fieldName?: string;
+    type?: string;
+    required?: boolean;
+};
+export interface CreatePluginClientOptions {
+    endpoints: Record<string, PluginEndpointDefinition>;
+    baseUrl?: string;
+}
+export interface BuildPluginEndpointUrlOptions {
+    /** Override the generated or platform-injected API base URL. */
+    baseUrl?: string;
+    /** Return only the endpoint path and query string instead of base URL + path. */
+    includeBaseUrl?: boolean;
+}
+export interface UseCurrentExperimentOptions {
+    apiBaseUrl?: string;
+    immediate?: boolean;
+}
+export interface UseCurrentExperimentReturn<TExperiment = unknown> {
+    /** Current experiment id resolved from platform injection or URL conventions. */
+    experimentId: ComputedRef<number | undefined>;
+    /** Whether a current experiment id is available. */
+    hasExperiment: ComputedRef<boolean>;
+    /** Current experiment payload, if injected or successfully fetched. */
+    experiment: Ref<TExperiment | undefined>;
+    /** Whether the current experiment is currently loading. */
+    isLoading: Ref<boolean>;
+    /** Error message from the last failed current-experiment fetch, or null. */
+    error: Ref<string | null>;
+    /** Timestamp of the last successful current-experiment fetch, or null. */
+    lastLoadedAt: Ref<Date | null>;
+    /** Return the current experiment id or throw a clear SDK error when absent. */
+    requireExperimentId: () => number;
+    /** Fetch a specific experiment id, defaulting to the current experiment id. */
+    fetch: (experimentId?: number) => Promise<TExperiment | undefined>;
+    /** Refetch the currently resolved experiment id. */
+    refresh: () => Promise<TExperiment | undefined>;
+}
+export type PluginEndpointCaller = (payload?: unknown) => Promise<unknown>;
+export type GeneratedPluginClient = Record<string, (...args: any[]) => Promise<any>>;
+/** Resolve the runtime plugin API base URL from env, explicit options, platform injection, or contract metadata. */
+export declare function resolvePluginBaseUrl(contract: PluginContract, explicitBaseUrl?: string): string;
+/** Build the concrete URL for a generated plugin endpoint without making a request. */
+export declare function buildPluginEndpointUrl(contract: PluginContract, endpoint: PluginEndpointDefinition, payload?: unknown, options?: BuildPluginEndpointUrlOptions): string;
+/** Create a typed plugin API client from a generated MINT plugin contract. */
+export declare function createPluginClient<TClient extends object = GeneratedPluginClient>(contract: PluginContract, options: CreatePluginClientOptions): TClient;
+/** Return a generated plugin client from setup code with a stable typed identity. */
+export declare function usePluginClient<TClient>(client: TClient): TClient;
+/** Read plugin settings exposed through the platform context. */
+export declare function usePluginSettings<TSettings = Record<string, unknown>>(): {
+    settings: ComputedRef<TSettings | undefined>;
+};
+/** Read and optionally load the current platform experiment for integrated plugin views. */
+export declare function useCurrentExperiment<TExperiment = unknown>(options?: UseCurrentExperimentOptions): UseCurrentExperimentReturn<TExperiment>;

package/dist/composables/usePluginConfig.d.ts

@@ -1,12 +1,24 @@
 import { Ref, ComputedRef } from 'vue';
 export interface UsePluginConfigReturn {
+    /** Editable plugin configuration values. */
     config: Ref<Record<string, unknown>>;
+    /** Whether the config is currently loading. */
     isLoading: Ref<boolean>;
+    /** Whether the config is currently saving. */
     isSaving: 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>;
+    /** Whether local config differs from the last loaded or saved snapshot. */
     isDirty: ComputedRef<boolean>;
+    /** Load plugin configuration from the platform. */
     load: () => Promise<void>;
+    /** Save plugin configuration to the platform. */
     save: () => Promise<boolean>;
+    /** Restore the last loaded or saved configuration snapshot. */
     reset: () => void;
 }
 /** Loads, saves, and tracks dirty state for a plugin's persistent configuration via the platform API. */

package/dist/composables/useRequestSyncState.d.ts

@@ -0,0 +1,34 @@
+import { Ref } from 'vue';
+export type RequestSyncSuccessKind = 'load' | 'save' | 'run';
+export interface RequestSyncRunOptions {
+    success?: RequestSyncSuccessKind;
+    errorMessage?: string;
+}
+export interface UseRequestSyncStateReturn {
+    /** Whether a request is in progress. */
+    loading: Ref<boolean>;
+    /** Message from the last failed request, or null. */
+    error: Ref<string | null>;
+    /** Timestamp of the last successful load operation, or null. */
+    lastLoadedAt: Ref<Date | null>;
+    /** Timestamp of the last successful save operation, or null. */
+    lastSavedAt: Ref<Date | null>;
+    /** Timestamp of the last successful run operation, or null. */
+    lastRunAt: Ref<Date | null>;
+    /** Clear the current error without changing loading or timestamps. */
+    clearError: () => void;
+    /** Convert thrown values into a developer-facing error message. */
+    readErrorMessage: (value: unknown, fallback?: string) => string;
+    /** Store and return a normalized error message. */
+    setError: (value: unknown, fallback?: string) => string;
+    /** Mark the resource as successfully loaded. */
+    markLoaded: (date?: Date) => void;
+    /** Mark the resource as successfully saved. */
+    markSaved: (date?: Date) => void;
+    /** Mark the operation as successfully run. */
+    markRun: (date?: Date) => void;
+    /** Run a request with shared loading/error handling and optional sync marking. */
+    run: <T>(operation: () => Promise<T>, options?: RequestSyncRunOptions) => Promise<T>;
+}
+/** Shared loading/error/timestamp state for generated plugin request helpers. */
+export declare function useRequestSyncState(defaultErrorMessage?: string): UseRequestSyncStateReturn;

package/dist/composables/useSampleGroups.d.ts

@@ -0,0 +1,32 @@
+import { ComputedRef, Ref } from 'vue';
+import { SampleGroup } from '../types';
+export type SampleGroupSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export interface DisplaySampleSubGroup extends SampleGroup {
+    displayColor: string;
+    displayBg: string;
+    displayBorder: string;
+}
+export interface SampleMajorGroup {
+    name: string;
+    color: string;
+    subGroups: DisplaySampleSubGroup[];
+    allSamples: string[];
+}
+export interface UseSampleGroupsOptions {
+    groups: SampleGroupSource<readonly SampleGroup[]>;
+    samples?: SampleGroupSource<readonly string[]>;
+    separator?: SampleGroupSource<string | null | undefined>;
+    fallbackColor?: SampleGroupSource<string | null | undefined>;
+}
+export interface UseSampleGroupsReturn {
+    groups: ComputedRef<SampleGroup[]>;
+    separator: ComputedRef<string>;
+    hierarchicalGroups: ComputedRef<SampleMajorGroup[]>;
+    showHierarchy: ComputedRef<boolean>;
+    groupedSamples: ComputedRef<Set<string>>;
+    ungroupedSamples: ComputedRef<string[]>;
+    findGroup: (groupName: string) => SampleGroup | undefined;
+    getGroupColor: (groupName: string) => string;
+}
+/** Shared sample-group hierarchy, color, and ungrouped-sample derivation for lab selectors. */
+export declare function useSampleGroups(options: UseSampleGroupsOptions): UseSampleGroupsReturn;

package/dist/composables/useSelectionLimit.d.ts

@@ -0,0 +1,17 @@
+import { ComputedRef, Ref } from 'vue';
+export type SelectionLimitSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export interface UseSelectionLimitOptions {
+    count: SelectionLimitSource<number>;
+    max?: SelectionLimitSource<number | null | undefined>;
+}
+export interface UseSelectionLimitReturn {
+    count: ComputedRef<number>;
+    max: ComputedRef<number | undefined>;
+    isLimited: ComputedRef<boolean>;
+    isAtLimit: ComputedRef<boolean>;
+    canAddMore: ComputedRef<boolean>;
+    remaining: ComputedRef<number | undefined>;
+    canAdd: (amount?: number, fromCount?: number) => boolean;
+}
+/** Shared cap logic for chip, tag, and multi-select controls. */
+export declare function useSelectionLimit(options: UseSelectionLimitOptions): UseSelectionLimitReturn;

package/dist/composables/useSortedItems.d.ts

@@ -0,0 +1,32 @@
+import { ComputedRef, Ref } from 'vue';
+export type SortedItemsSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export type SortOrder = 'asc' | 'desc';
+export interface SortDescriptor<TKey extends string = string> {
+    key: TKey;
+    direction?: SortOrder | null;
+}
+export interface CompareSortValuesOptions {
+    caseSensitive?: boolean;
+}
+export interface SortComparatorContext<TItem, TKey extends string = string> {
+    key: TKey;
+    direction: SortOrder;
+    a: TItem;
+    b: TItem;
+}
+export type SortComparator<TItem, TKey extends string = string> = (aValue: unknown, bValue: unknown, context: SortComparatorContext<TItem, TKey>) => number;
+export interface UseSortedItemsOptions<TItem, TKey extends string = string> {
+    items: SortedItemsSource<readonly TItem[]>;
+    sort: SortedItemsSource<SortDescriptor<TKey> | null | undefined>;
+    enabled?: SortedItemsSource<boolean | null | undefined>;
+    caseSensitive?: SortedItemsSource<boolean | null | undefined>;
+    getValue: (item: TItem, key: TKey) => unknown;
+    compare?: SortComparator<TItem, TKey>;
+}
+export interface UseSortedItemsReturn<TItem, TKey extends string = string> {
+    sort: ComputedRef<SortDescriptor<TKey> | null | undefined>;
+    sortedItems: ComputedRef<TItem[]>;
+}
+/** Shared sorting for SDK tables and lists with stable empty-value handling. */
+export declare function useSortedItems<TItem, TKey extends string = string>(options: UseSortedItemsOptions<TItem, TKey>): UseSortedItemsReturn<TItem, TKey>;
+export declare function compareSortValues(aValue: unknown, bValue: unknown, direction?: SortOrder, options?: CompareSortValuesOptions): number;

package/dist/composables/useTemplateCollection.d.ts

@@ -0,0 +1,58 @@
+import { ComputedRef, Ref } from 'vue';
+import { UseExperimentSaveOptions } from './useExperimentSave';
+import { BioTemplateEnvelope, TemplateCollection, TemplateCollectionEnvelope } from '../templates';
+export type TemplateCollectionInput = TemplateCollectionEnvelope | BioTemplateEnvelope<unknown> | Array<BioTemplateEnvelope<unknown>>;
+export interface UseTemplateCollectionOptions extends UseExperimentSaveOptions {
+    /** Initial template collection or factory; defaults to an empty collection. */
+    initial?: TemplateCollectionInput | (() => TemplateCollectionInput);
+}
+export interface UseTemplateCollectionReturn {
+    /** 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>;
+    /** Full template collection envelope ready to save into design_data. */
+    templateCollection: Ref<TemplateCollectionEnvelope>;
+    /** Template map keyed by template_id. */
+    templates: ComputedRef<TemplateCollection>;
+    /** Collection-level metadata, or an empty object. */
+    metadata: ComputedRef<Record<string, unknown>>;
+    /** Template ids currently present in the collection. */
+    templateIds: ComputedRef<string[]>;
+    /** Whether the collection contains at least one template. */
+    hasTemplates: ComputedRef<boolean>;
+    /** Whether a load or delete operation is in progress. */
+    isLoading: Ref<boolean>;
+    /** Whether a save operation is in progress. */
+    isSaving: 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>;
+    /** Replace local state from a template envelope, collection envelope, or raw design_data. */
+    apply: (value: unknown, metadata?: Record<string, unknown>) => TemplateCollectionEnvelope;
+    /** Reset local state to the configured initial collection. */
+    reset: () => TemplateCollectionEnvelope;
+    /** Add or replace one template in the local collection. */
+    setTemplate: (template: BioTemplateEnvelope<unknown>) => TemplateCollectionEnvelope;
+    /** Remove one template from the local collection. */
+    removeTemplate: (templateId: string) => boolean;
+    /** Read one template from the local collection, returning null when missing. */
+    getTemplate: <TTemplate extends BioTemplateEnvelope<unknown> = BioTemplateEnvelope<unknown>>(templateId: string) => TTemplate | null;
+    /** Read one template from the local collection, throwing when missing or mismatched. */
+    requireTemplate: <TTemplate extends BioTemplateEnvelope<unknown> = BioTemplateEnvelope<unknown>>(templateId: string) => TTemplate;
+    /** Load template design_data for an experiment and apply it locally. */
+    load: (experimentId: number) => Promise<TemplateCollectionEnvelope | null>;
+    /** Load template design_data for the current experiment and apply it locally. */
+    loadCurrent: () => Promise<TemplateCollectionEnvelope | null>;
+    /** Save the local template collection as experiment design_data. */
+    save: (experimentId: number) => Promise<boolean>;
+    /** Save the local template collection as current experiment design_data. */
+    saveCurrent: () => Promise<boolean>;
+    /** Require and return the current experiment id, or throw when missing. */
+    requireCurrentExperimentId: () => number;
+}
+/** Manages a biology template collection in the current experiment's design_data. */
+export declare function useTemplateCollection(options?: UseTemplateCollectionOptions): UseTemplateCollectionReturn;

package/dist/composables/useTextSearch.d.ts

@@ -0,0 +1,18 @@
+import { ComputedRef, Ref } from 'vue';
+export type TextSearchSource<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export type TextSearchCandidate = unknown | readonly unknown[];
+export interface UseTextSearchOptions<TItem> {
+    items: TextSearchSource<readonly TItem[]>;
+    query: TextSearchSource<string | null | undefined>;
+    enabled?: TextSearchSource<boolean | null | undefined>;
+    getText: (item: TItem) => TextSearchCandidate;
+}
+export interface UseTextSearchReturn<TItem> {
+    query: ComputedRef<string>;
+    filteredItems: ComputedRef<TItem[]>;
+    matches: (item: TItem, query?: string | null | undefined) => boolean;
+}
+/** Shared text-search filtering for tables, lists, selectors, and chip inputs. */
+export declare function useTextSearch<TItem>(options: UseTextSearchOptions<TItem>): UseTextSearchReturn<TItem>;
+export declare function normalizeSearchQuery(value: string | null | undefined): string;
+export declare function candidateMatchesSearch(candidate: TextSearchCandidate, query: string): boolean;

package/dist/composables/useTimeUtils.d.ts

@@ -4,6 +4,7 @@ export declare function parseTime(time: string): {
     minute: number;
 };
 export declare function formatTime(hour: number, minute: number, format?: '12h' | '24h'): string;
+export declare function formatTimeSlot(time: string, format?: '12h' | '24h'): string;
 export declare function generateTimeSlots(start: string, end: string, stepMinutes: number): string[];
 export declare function rangesOverlap(a: TimeRange, b: TimeRange): boolean;
 export declare function durationMinutes(start: string, end: string): number;
@@ -13,10 +14,14 @@ export declare function findAvailableSlots(dayStart: string, dayEnd: string, occ
 export declare function snapToSlot(time: string, stepMinutes: number): string;
 export declare function addMinutes(time: string, minutes: number): string;
 export declare function compareTime(a: string, b: string): number;
+export declare function findNearestTimeSlotIndex(time: string, slots: readonly string[]): number;
+export declare function toMinutes(time: string): number;
+export declare function fromMinutes(total: number): string;
 /** Time utility helpers for parsing, formatting, comparing, and snapping HH:MM strings. */
 export declare function useTimeUtils(): {
     parseTime: typeof parseTime;
     formatTime: typeof formatTime;
+    formatTimeSlot: typeof formatTimeSlot;
     generateTimeSlots: typeof generateTimeSlots;
     rangesOverlap: typeof rangesOverlap;
     durationMinutes: typeof durationMinutes;
@@ -26,4 +31,7 @@ export declare function useTimeUtils(): {
     snapToSlot: typeof snapToSlot;
     addMinutes: typeof addMinutes;
     compareTime: typeof compareTime;
+    findNearestTimeSlotIndex: typeof findNearestTimeSlotIndex;
+    toMinutes: typeof toMinutes;
+    fromMinutes: typeof fromMinutes;
 };