@morscherlab/mint-sdk 1.2.0-beta.4 → 1.2.0-beta.5

package/src/composables/workspaceRecipes.ts

@@ -0,0 +1,267 @@
+import type { TopBarVariant } from '../types'
+import type { FormEnhancements } from '../types/form-builder'
+import type {
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+  UseControlWorkspaceReturn,
+} from './useControlSchema'
+import { mergeControlWorkspaceOptions, resolveControlModel } from './useControlSchema'
+
+/**
+ * Merges `initialValues`/external `modelValue`/`values` on top of a base
+ * `ControlWorkspaceOptions.initialValues`, matching the layering FormBuilder expects: base
+ * defaults, then caller-supplied initial values, then live external values win last. Shared by
+ * {@link controlWorkspaceProps} and {@link bioTemplatePresetWorkspaceProps} so both "generate a
+ * workspace from options, initialValues, and v-model" views merge options identically.
+ */
+export function resolveControlOptionsWithExternalValues<TOptions extends ControlWorkspaceOptions>(
+  base: TOptions,
+  initialValues: Record<string, unknown> | undefined,
+  externalValues: Record<string, unknown> | undefined,
+): TOptions {
+  if (initialValues === undefined && externalValues === undefined) return base
+
+  return {
+    ...base,
+    initialValues: {
+      ...(base.initialValues ?? {}),
+      ...(initialValues ?? {}),
+      ...(externalValues ?? {}),
+    },
+  }
+}
+
+export interface ControlWorkspaceModelProps {
+  model?: ControlModel | ControlModelBinding
+  controls?: ControlSchema
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+export interface ResolvedControlWorkspaceModel {
+  /** `modelValue` if provided, else `values` — the single external v-model source of truth. */
+  externalValues: Record<string, unknown> | undefined
+  /** `model` resolved through `resolveControlModel()`, or undefined for a raw `controls` schema. */
+  resolvedModel: ControlModelBinding | undefined
+  /** `controls` if provided, else the resolved model's controls, else `{}`. */
+  resolvedControls: ControlSchema
+  /** `controlOptions` merged over the resolved model's own options, with initialValues/external values layered on top. */
+  resolvedControlOptions: ControlWorkspaceOptions
+}
+
+/**
+ * Resolves ControlWorkspaceView's `model`/`controls`/`controlOptions`/`initialValues`/
+ * `modelValue`/`values` props into the schema + options pair `useControlWorkspace()` needs.
+ * Pure and framework-free so callers wrap each field in their own `computed()`.
+ *
+ * @example Recommended
+ * ```ts
+ * const resolved = computed(() => controlWorkspaceProps(props))
+ * const resolvedControls = computed(() => resolved.value.resolvedControls)
+ * ```
+ */
+export function controlWorkspaceProps(props: ControlWorkspaceModelProps): ResolvedControlWorkspaceModel {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedModel = resolveControlModel(props.model)
+  const resolvedControls: ControlSchema = props.controls ?? resolvedModel?.controls ?? {}
+  const baseControlOptions = mergeControlWorkspaceOptions(resolvedModel?.controlOptions, props.controlOptions)
+  const resolvedControlOptions = resolveControlOptionsWithExternalValues(
+    baseControlOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedModel, resolvedControls, resolvedControlOptions }
+}
+
+export interface DoseDesignWorkspacePassthroughProps {
+  workspace?: UseControlWorkspaceReturn<ControlSchema>
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+  title?: string
+  subtitle?: string
+  topBarVariant?: TopBarVariant
+  sidebarWidth?: string
+  sidebarVariant?: 'default' | 'analysis'
+  responsiveSidebar?: boolean
+  sidebarPosition?: 'left' | 'right'
+  sidebarTitle?: string
+  sidebarSubtitle?: string
+  sidebarBadge?: string | number
+  floating?: boolean
+  dense?: boolean
+  showSettings?: boolean
+  showFormActions?: boolean
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  formLoading?: boolean
+  formDisabled?: boolean
+  formReadonly?: boolean
+  formSize?: 'sm' | 'md' | 'lg'
+}
+
+/**
+ * Maps DoseDesignWorkspaceView's props straight through to the identically-named
+ * ControlWorkspaceView props it wraps — the ~25-key pass-through list that used to be spelled
+ * out attribute-by-attribute in the template. `model` is the caller's already-resolved dose
+ * design model, not the raw (possibly absent) `props.model`.
+ *
+ * @example Recommended
+ * ```vue
+ * <ControlWorkspaceView v-bind="doseDesignWorkspaceProps(props, resolvedModel)" />
+ * ```
+ */
+export function doseDesignWorkspaceProps(
+  props: DoseDesignWorkspacePassthroughProps,
+  model: ControlModel | ControlModelBinding,
+) {
+  return {
+    model,
+    workspace: props.workspace,
+    controlOptions: props.controlOptions,
+    initialValues: props.initialValues,
+    modelValue: props.modelValue,
+    values: props.values,
+    title: props.title,
+    subtitle: props.subtitle,
+    topBarVariant: props.topBarVariant,
+    sidebarWidth: props.sidebarWidth,
+    sidebarVariant: props.sidebarVariant,
+    responsiveSidebar: props.responsiveSidebar,
+    sidebarPosition: props.sidebarPosition,
+    sidebarTitle: props.sidebarTitle,
+    sidebarSubtitle: props.sidebarSubtitle,
+    sidebarBadge: props.sidebarBadge,
+    floating: props.floating,
+    dense: props.dense,
+    showSettings: props.showSettings,
+    showFormActions: props.showFormActions,
+    formEnhancements: props.formEnhancements,
+    formLoading: props.formLoading,
+    formDisabled: props.formDisabled,
+    formReadonly: props.formReadonly,
+    formSize: props.formSize,
+  }
+}
+
+export interface BioTemplateExperimentWorkspaceStatusProps {
+  status?: {
+    loading?: boolean
+    saving?: boolean
+    error?: string | null
+    hasExperiment?: boolean
+    currentExperimentId?: number
+    lastLoadedAt?: Date | null
+    lastSavedAt?: Date | null
+  }
+  loading?: boolean
+  error?: string | null
+  hasExperiment?: boolean
+  currentExperimentId?: number
+  lastLoadedAt?: Date | null
+  lastSavedAt?: Date | null
+}
+
+export interface ResolvedBioTemplateExperimentStatus {
+  loading: boolean
+  error: string | null | undefined
+  hasExperiment: boolean
+  currentExperimentId: number | undefined
+  lastLoadedAt: Date | null | undefined
+  lastSavedAt: Date | null | undefined
+}
+
+/**
+ * Merges BioTemplateExperimentWorkspaceView's grouped `status` prop over its individual
+ * `loading`/`error`/`hasExperiment`/... props: `status` wins whenever the corresponding field
+ * on it is set, otherwise the flat prop (or its default) is used. Centralizes the six
+ * independent fallback rules generated plugin pages rely on when they pass a request/experiment
+ * `status` object instead of wiring each field by hand.
+ */
+export function bioTemplateExperimentWorkspaceProps(
+  props: BioTemplateExperimentWorkspaceStatusProps,
+): ResolvedBioTemplateExperimentStatus {
+  const status = props.status
+  return {
+    loading: status?.loading !== undefined || status?.saving !== undefined
+      ? Boolean(status?.loading) || Boolean(status?.saving)
+      : Boolean(props.loading),
+    error: status?.error !== undefined ? status.error : props.error,
+    hasExperiment: status?.hasExperiment ?? props.hasExperiment ?? false,
+    currentExperimentId: status?.currentExperimentId ?? props.currentExperimentId,
+    lastLoadedAt: status?.lastLoadedAt !== undefined ? status.lastLoadedAt : props.lastLoadedAt,
+    lastSavedAt: status?.lastSavedAt !== undefined ? status.lastSavedAt : props.lastSavedAt,
+  }
+}
+
+export interface BioTemplatePackWorkspacePassthroughProps {
+  message?: string
+  dense?: boolean
+  readonly?: boolean
+  showStatus?: boolean
+  showTemplateSummary?: boolean
+  loadLabel?: string
+  resetLabel?: string
+  saveLabel?: string
+}
+
+/**
+ * Assembles the prop object BioTemplatePackWorkspaceView binds onto the
+ * BioTemplateExperimentWorkspaceView it wraps: its own display props passed straight through,
+ * plus the pack-derived `target`/`label`/`status`/`actions` computed by the caller.
+ */
+export function bioTemplatePackWorkspaceProps<TTarget, TStatus, TActions>(
+  props: BioTemplatePackWorkspacePassthroughProps,
+  derived: {
+    target: TTarget
+    label: string
+    status: TStatus
+    actions: TActions
+  },
+) {
+  return {
+    target: derived.target,
+    kind: 'collection' as const,
+    label: derived.label,
+    message: props.message,
+    status: derived.status,
+    actions: derived.actions,
+    dense: props.dense,
+    readonly: props.readonly,
+    showStatus: props.showStatus,
+    showTemplateSummary: props.showTemplateSummary,
+    loadLabel: props.loadLabel,
+    resetLabel: props.resetLabel,
+    saveLabel: props.saveLabel,
+  }
+}
+
+export interface BioTemplatePresetWorkspaceOptionsProps<TOptions extends ControlWorkspaceOptions> {
+  workspaceOptions?: TOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+/**
+ * Resolves BioTemplatePresetWorkspaceView's `workspaceOptions`/`initialValues`/`modelValue`/
+ * `values` props into the single options object `useBioTemplatePresetWorkspace()` needs,
+ * reusing the same base/initialValues/external-values layering as {@link controlWorkspaceProps}.
+ */
+export function bioTemplatePresetWorkspaceProps<TOptions extends ControlWorkspaceOptions>(
+  props: BioTemplatePresetWorkspaceOptionsProps<TOptions>,
+): { externalValues: Record<string, unknown> | undefined; resolvedWorkspaceOptions: TOptions } {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedWorkspaceOptions = resolveControlOptionsWithExternalValues(
+    (props.workspaceOptions ?? {}) as TOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedWorkspaceOptions }
+}

package/src/index.ts

@@ -41,6 +41,22 @@ export {
   deriveShade,
   type Hsl,
 } from './utils/color'
+export {
+  PLUGIN_SECRET_FORMAT_KEY,
+  PLUGIN_SECRET_FORMAT_REF,
+  PLUGIN_SECRET_REF_KEY,
+  clearPluginSecret,
+  isPluginSecretLocked,
+  isPluginSecretRef,
+  keepPluginSecret,
+  pluginSecretId,
+  pluginSecretLabel,
+  pluginSecretState,
+  setPluginSecret,
+  usesPluginSecretReferences,
+  type PluginSecretRef,
+  type PluginSecretState,
+} from './utils/pluginSecrets'
 export {
   LCMS_DEFAULT_CONTROL_POSITIONS,
   createLcmsControlWellEditData,

package/src/styles/components/secret-input.css

@@ -0,0 +1,60 @@
+/* SecretInput — plugin secret settings field with a set / not set / environment badge. */
+
+.mint-secret-input {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.mint-secret-input__status {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.mint-secret-input__badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1.4;
+  border: 1px solid transparent;
+  background-color: var(--bg-tertiary);
+  color: var(--text-secondary);
+}
+
+.mint-secret-input__badge--set {
+  background-color: color-mix(in srgb, var(--mint-success) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-success) 35%, transparent);
+  color: var(--mint-success);
+}
+
+.mint-secret-input__badge--environment {
+  background-color: color-mix(in srgb, var(--mint-info) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-info) 35%, transparent);
+  color: var(--mint-info);
+}
+
+.mint-secret-input__badge--pending {
+  background-color: color-mix(in srgb, var(--mint-warning) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-warning) 35%, transparent);
+  color: var(--mint-warning);
+}
+
+.mint-secret-input__hint {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+.mint-secret-input__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.mint-secret-input--error .mint-secret-input__badge {
+  border-color: color-mix(in srgb, var(--mint-error) 45%, transparent);
+}

package/src/styles/index.css

@@ -30,6 +30,7 @@
 @import './components/radio-group.css';
 @import './components/sample-legend.css';
 @import './components/section-card.css';
+@import './components/secret-input.css';
 @import './components/select.css';
 @import './components/skeleton.css';
 @import './components/slider.css';

package/src/templates/builderReadUtils.ts

@@ -1,6 +1,4 @@
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+export { isRecord } from '../utils/records'
 
 export function readStringList(value: unknown, fallback: string[]): string[] {
   if (Array.isArray(value)) {

package/src/templates/componentTargetResolvers.ts

@@ -1,3 +1,4 @@
+import { isObjectLike as isRecord } from '../utils/records'
 import { extractTemplateCollection } from './templateEnvelopes'
 import { getBioTemplateInfo } from './catalog'
 import { getBioTemplatePackInfo } from './packs'
@@ -64,6 +65,3 @@ function collectionPackName(value: unknown): string | undefined {
   return typeof value.metadata.pack === 'string' ? value.metadata.pack : undefined
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}

package/src/templates/controlSchemaTargets.ts

@@ -1,3 +1,4 @@
+import { isObjectLike as isRecord } from '../utils/records'
 import {
   getBioTemplateInfo,
 } from './catalog'
@@ -82,6 +83,3 @@ function collectionPackName(value: unknown): string | undefined {
   return typeof value.metadata.pack === 'string' ? value.metadata.pack : undefined
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}

package/src/types/form-builder.ts

@@ -11,6 +11,7 @@ export type FormFieldType =
   | 'text'
   | 'email'
   | 'password'
+  | 'secret'
   | 'number'
   | 'tel'
   | 'url'

package/src/utils/formModelSync.ts

@@ -1,4 +1,5 @@
 import type { FormSchema } from '../types/form-builder'
+import { isRecord } from './records'
 
 export function recordValuesEqualForKeys(
   left: Record<string, unknown>,
@@ -47,6 +48,3 @@ function valuesEqual(left: unknown, right: unknown): boolean {
   return false
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}

package/src/utils/pluginIcon.ts

@@ -1,3 +1,4 @@
+import { isRecord } from './records'
 export type PluginIconFormat = 'path' | 'data-url' | 'asset-url' | 'structured' | 'fallback'
 
 export interface StructuredPluginIconStop {
@@ -177,9 +178,6 @@ function parseOffset(value: unknown): string | undefined {
   return undefined
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
 
 function isSafeColor(value: unknown): value is string {
   return typeof value === 'string' && COLOR_REGEX.test(value)

package/src/utils/pluginSecrets.ts

@@ -0,0 +1,102 @@
+/**
+ * Stable references for plugin secret settings.
+ *
+ * A settings response never carries a secret's value. Every secret leaf is a
+ * marker instead:
+ *
+ * - `{ "$secret": "sec_…", "set": true }` — a stored secret, referenced by a
+ *   stable opaque id. Send the marker back unchanged to keep the stored value.
+ * - `null` — nothing stored at that position.
+ * - `{ "$secret": null, "locked": true }` — the effective value comes from the
+ *   environment and is never written back.
+ *
+ * On save each secret leaf accepts the reference, a plain string (a new value),
+ * or `null` (clear). Payloads carry `secret_format: "ref"` so a `null` reads as
+ * a deliberate clear rather than the deprecated "unchanged" placeholder.
+ */
+
+/** Reserved marker key that references a stored secret. */
+export const PLUGIN_SECRET_REF_KEY = '$secret'
+
+/** Reserved payload key declaring which secret wire format a client speaks. */
+export const PLUGIN_SECRET_FORMAT_KEY = 'secret_format'
+
+/** Wire format published and understood by this SDK. */
+export const PLUGIN_SECRET_FORMAT_REF = 'ref'
+
+/** One `$secret` marker as published by a settings response. */
+export interface PluginSecretRef {
+  $secret: string | null
+  set?: boolean
+  locked?: boolean
+}
+
+/** What a settings form should tell the user about one secret field. */
+export type PluginSecretState = 'set' | 'unset' | 'environment'
+
+const MARKER_KEYS = new Set([PLUGIN_SECRET_REF_KEY, 'set', 'locked'])
+
+/** Return whether one settings value is a `$secret` reference marker. */
+export function isPluginSecretRef(value: unknown): value is PluginSecretRef {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  if (!(PLUGIN_SECRET_REF_KEY in record)) return false
+  return Object.keys(record).every(key => MARKER_KEYS.has(key))
+}
+
+/** Return the stored secret id behind a marker, or `null` when nothing is stored. */
+export function pluginSecretId(value: unknown): string | null {
+  if (!isPluginSecretRef(value)) return null
+  return typeof value.$secret === 'string' ? value.$secret : null
+}
+
+/** Classify one secret field for display: stored, unset, or environment-provided. */
+export function pluginSecretState(value: unknown): PluginSecretState {
+  if (isPluginSecretRef(value)) {
+    if (value.locked) return 'environment'
+    return typeof value.$secret === 'string' ? 'set' : 'unset'
+  }
+  return typeof value === 'string' && value.length > 0 ? 'set' : 'unset'
+}
+
+/** Human label for one secret field's state. */
+export function pluginSecretLabel(value: unknown): string {
+  const state = pluginSecretState(value)
+  if (state === 'environment') return 'Provided by environment'
+  return state === 'set' ? 'Set' : 'Not set'
+}
+
+/** Whether a secret field is read-only because the environment supplies it. */
+export function isPluginSecretLocked(value: unknown): boolean {
+  return isPluginSecretRef(value) && value.locked === true
+}
+
+/**
+ * Value to submit for an untouched secret field: the reference, unchanged.
+ *
+ * A locked marker round-trips too, which is how the platform keeps a stored
+ * value that an environment variable currently hides.
+ */
+export function keepPluginSecret(current: unknown): PluginSecretRef | null {
+  if (isPluginSecretRef(current)) return { ...current }
+  return null
+}
+
+/** Value to submit when the user typed a new secret. */
+export function setPluginSecret(value: string): string {
+  return value
+}
+
+/** Value to submit when the user cleared a secret. */
+export function clearPluginSecret(): null {
+  return null
+}
+
+/** Whether a settings response declares the `$secret` reference wire format. */
+export function usesPluginSecretReferences(response: unknown): boolean {
+  if (!response || typeof response !== 'object') return false
+  return (
+    (response as Record<string, unknown>)[PLUGIN_SECRET_FORMAT_KEY]
+      === PLUGIN_SECRET_FORMAT_REF
+  )
+}

package/src/utils/records.ts

@@ -0,0 +1,9 @@
+/** Narrow an unknown value to a plain object (arrays and null excluded). */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Narrow an unknown value to any non-null object, arrays included. */
+export function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}