@antelopejs/dms 0.5.6 → 0.6.0

package/frontend-vue/layers/dms-ui/app/composables/confirm/types.ts

@@ -0,0 +1,102 @@
+import type { VNodeChild } from "vue";
+import type {
+  ConfirmDialog,
+  ConfirmDialogColor,
+  ConfirmDialogImpact,
+} from "#dms-core/app/types/confirm-dialog";
+
+export type ConfirmColor = ConfirmDialogColor;
+
+/** The footer button a confirm dialog focuses when it opens. */
+export type ConfirmInitialFocus = "cancel" | "confirm";
+
+/** Extra body content rendered between the impact list and the typed check. */
+export type ConfirmBodyRender = () => VNodeChild;
+
+/** One dependent affected by the confirmed action. */
+export type ConfirmImpact = ConfirmDialogImpact;
+
+/** The values the dialog's fields hold when the user confirms. */
+export type ConfirmValues = Record<string, unknown>;
+
+/**
+ * A confirmation dialog as `useConfirm()` opens it: a {@link ConfirmDialog}
+ * whose texts are already resolved, plus what only a caller in the browser
+ * can give (render functions, handlers).
+ */
+export interface ConfirmOptions extends Omit<ConfirmDialog, "params" | "icon"> {
+  /**
+   * The button focused on open (`"cancel"` for a dialog whose safe answer
+   * is to stay); left out, the dialog's first focusable element.
+   */
+  initialFocus?: ConfirmInitialFocus;
+  /** Leading icon of the confirm button. */
+  confirmIcon?: string;
+  /** Header icon; defaults per colour, `false` gives the minimal layout. */
+  icon?: string | false;
+  /**
+   * Extra content (a select, a note…) as a render function, re-run
+   * reactively: state it reads can be refs owned by the caller.
+   */
+  body?: ConfirmBodyRender;
+  /**
+   * Checks the `body` fields on confirm, before `onConfirm`: returns `false`
+   * after flagging the empty or wrong ones (and focusing the first), which
+   * keeps the modal open.
+   */
+  validate?: () => boolean | Promise<boolean>;
+  /**
+   * Awaited on confirm: the modal shows a loading confirm button, blocks
+   * dismissal, and resolves `true` only once it succeeds; a rejection is
+   * shown inline and the modal stays open (a {@link ConfirmTextError} under
+   * the typed field), its confirm button ready for a retry. The alert words
+   * the error for users (see `resolveActionError`): the server's message when
+   * it is user-facing, else a translated fallback. Resolving `false` also
+   * keeps it open, for a handler that already reported the problem itself
+   * (toast); resolving a {@link ConfirmPartialOutcome} keeps it open to say
+   * the action went only part of the way. It receives the values of the
+   * dialog's `fields`; a field error the server answers shows under its
+   * field.
+   */
+  onConfirm?: (
+    values: ConfirmValues,
+  ) => Promise<void | boolean | ConfirmPartialOutcome>;
+}
+
+/** A summary shown in the confirm modal's alert: a title and its detail. */
+export interface ConfirmNotice {
+  title: string;
+  description?: string;
+}
+
+/**
+ * Resolved by `onConfirm` when the action ran only part of the way (a bulk
+ * action some rows refused): what went through is done, so the modal turns
+ * into an acknowledgement — the summary in a warning alert, no confirm button
+ * — and resolves `true` once closed.
+ */
+export interface ConfirmPartialOutcome {
+  partial: ConfirmNotice;
+}
+
+/**
+ * Thrown by `onConfirm` with a message already worded for users (a title and
+ * its reason): the modal shows both in its error alert, as they are.
+ */
+export class ConfirmActionError extends Error {
+  readonly description?: string;
+
+  constructor(notice: ConfirmNotice) {
+    super(notice.title);
+    this.description = notice.description;
+  }
+}
+
+/**
+ * Thrown by `onConfirm` when the server refused the typed confirmation text:
+ * the modal shows the message under the typed field (marked invalid, then
+ * focused) instead of its error alert.
+ */
+export class ConfirmTextError extends Error {
+  readonly field = "confirmText";
+}

package/frontend-vue/layers/dms-ui/app/composables/confirm/useConfirm.ts

@@ -1,13 +1,11 @@
 import LazyDmsConfirmModal from "../../components/confirm/ConfirmModal.vue";
+import type { ConfirmOptions } from "./types";
 
-export interface ConfirmOptions {
-  title: string;
-  description: string;
-  confirmLabel?: string;
-  cancelLabel?: string;
-  confirmColor?: "primary" | "error" | "warning";
-}
-
+/**
+ * Opens the DMS confirmation modal.
+ *
+ * @returns `confirm(options)`, resolving `true` when the user confirmed.
+ */
 export function useConfirm() {
   const overlay = useOverlay();
 

package/frontend-vue/layers/dms-ui/app/composables/containers/openDynamicContainer.ts

@@ -84,6 +84,7 @@ export function openDynamicContainer<Result, Options extends ContainerOptions>(
 
   return {
     result,
+    patch: (patch) => instance.patch(patch),
     close: (value?: Result) => {
       if (opened) {
         instance.close(value);

package/frontend-vue/layers/dms-ui/app/composables/containers/types.ts

@@ -7,6 +7,15 @@ import type { ModalSize } from "../../types/modal";
  */
 export type DrawerDirection = "top" | "bottom" | "left" | "right";
 
+/** Tint of the optional header icon well of a container. */
+export type ContainerColor =
+  | "primary"
+  | "neutral"
+  | "success"
+  | "info"
+  | "warning"
+  | "error";
+
 /**
  * Options shared by every themed container opened through a public composable.
  * They map one-to-one onto the props of the internal Dynamic{Drawer,Modal}
@@ -17,9 +26,18 @@ export interface ContainerOptions {
   description?: string;
   component: Component;
   componentOptions?: Record<string, unknown>;
+  /**
+   * Mounts the body component anew when it changes: a drawer stepping to
+   * another row gives the component a fresh start on it.
+   */
+  componentKey?: string;
   headerComponent?: Component;
   headerComponentOptions?: Record<string, unknown>;
   containerId?: string;
+  /** Icon rendered in a 36px tinted well before the title. */
+  icon?: string;
+  /** Tint of the icon well (default primary). */
+  color?: ContainerColor;
 }
 
 /** Options accepted by {@link useDrawer}'s `open`. */
@@ -35,9 +53,20 @@ export interface ModalOptions extends ContainerOptions {
 /**
  * Handle returned when a container is opened. `result` settles with the value
  * the body component emits on `success` (or the value passed to `close`) once
- * the container is dismissed; `close` dismisses it programmatically.
+ * the container is dismissed; `close` dismisses it programmatically, `patch`
+ * changes it in place.
  */
 export interface ContainerInstance<Result = unknown> {
   result: Promise<Result>;
   close: (result?: Result) => void;
+  /** Updates the open container: its texts, or its body's options and key. */
+  patch: (options: ContainerPatch) => void;
 }
+
+/** What an open container can change in place. */
+export type ContainerPatch = Partial<
+  Pick<
+    ContainerOptions,
+    "title" | "description" | "componentOptions" | "componentKey"
+  >
+>;

package/frontend-vue/layers/dms-ui/app/composables/form/types/api.ts

@@ -1,5 +1,5 @@
 import type { FormData } from "./value";
-import type { WarningResponse } from "../../../utils/responseWarning";
+import type { WarningResponse } from "../../../build/utils/responseWarning";
 
 export interface FormFetchResponse extends FormData {}
 

package/frontend-vue/layers/dms-ui/app/composables/form/types/field.ts

@@ -1,11 +1,33 @@
 import type { FormFieldValue } from "./value";
 
+/** A pill beside a read-only field's value. */
+export interface FormFieldBadge {
+  label: string;
+  tone: string;
+}
+
+/** A link beside a read-only field's value: where it is changed. */
+export interface FormFieldLink {
+  label: string;
+  to: string;
+}
+
+/** A pill or a link beside a read-only field's value. */
+export interface FormFieldReadonly {
+  badge?: FormFieldBadge;
+  link?: FormFieldLink;
+}
+
 export interface FormField {
   id: string;
   label?: string;
   description?: string;
+  /** A grey help line under the control. */
+  hint?: string;
   component: ComponentInfo;
   disabled?: boolean;
+  /** Shown, not edited: `true`, or with a pill and a link. */
+  readonly?: boolean | FormFieldReadonly;
   required?: boolean;
   type?: string;
   defaultValue?: FormFieldValue;
@@ -23,6 +45,18 @@ export interface FieldGroup {
 
 export type FormFieldOrGroup = FormField | FieldGroup;
 
+/** How a sectioned form lists its sections. */
+export type FormSectionNav = "side" | "jump" | "none";
+
+/** A titled card of a form: the ids of the form's entries it holds. */
+export interface FormSection {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  fieldIds: string[];
+}
+
 export function isFieldGroup(item: FormFieldOrGroup): item is FieldGroup {
   return "fields" in item && Array.isArray(item.fields);
 }

package/frontend-vue/layers/dms-ui/app/composables/form/types/props.ts

@@ -1,4 +1,8 @@
-import type { FormFieldOrGroup } from "./field";
+import type { FormFieldOrGroup, FormSection, FormSectionNav } from "./field";
+import type {
+  FormKind,
+  FormSaveMode,
+} from "../../../build/composables/form/formFooter";
 
 interface FormComponentProps {
   componentId: string;
@@ -11,14 +15,39 @@ interface FormComponentProps {
 export interface FormProps extends FormComponentProps {
   title?: string;
   description?: string;
+  /** Every entry of the form, the sections' included. */
   fields: FormFieldOrGroup[];
+  /**
+   * Titled cards splitting the fields, reached from a navigation that marks
+   * the ones holding unsaved changes or errors. Entries in no section come
+   * first.
+   */
+  sections?: FormSection[];
+  /**
+   * `side`: a list beside the sections following the scroll (chips on a
+   * narrow form); `jump`: chips above them; `none`. Defaults to `side` from
+   * three sections.
+   */
+  sectionNav?: FormSectionNav;
   fetchUrl?: string;
   fetchUrlMethod?: HttpMethod;
   submitUrl?: string;
   submitUrlMethod?: HttpMethod;
   submitLabel?: string;
-  /** Whether the buttons show; left out, once there is somewhere to submit to. */
-  showActions?: boolean;
+  /**
+   * How the form offers to save: `bar` (default), a sticky bar shown while
+   * there are unsaved changes; `footer`, the footer buttons; `none`; `instant`
+   * saves like `bar` for now. In a drawer or a modal, the container's footer.
+   */
+  saveMode?: FormSaveMode;
+  /**
+   * `record` (default): keeps its values once saved, Cancel while clean when
+   * it has somewhere to go back to. `action` (send, invite, run): Reset and
+   * its submit label once a value changes, emptied after a submit.
+   */
+  kind?: FormKind;
+  /** Where Cancel leads a record form on a page; no Cancel without it. */
+  backTo?: string;
   successMessage?: string;
   errorMessage?: string;
   schema?: Record<string, unknown>;
@@ -28,4 +57,6 @@ export interface FormProps extends FormComponentProps {
   submitDefaults?: Record<string, unknown>;
   containerId?: string;
   redirectOnSuccess?: string;
+  /** Field of the loaded row a page form names in the breadcrumb. */
+  labelKey?: string;
 }