@antelopejs/dms 0.9.7 → 0.10.0

package/frontend-vue/layers/dms-ui/app/composables/chart/useApexChart.ts

@@ -3,6 +3,15 @@ import { APEX_TYPE_CONFIGS } from "./apexTypeConfigs";
 import { buildAnnotations } from "./apexAnnotations";
 import { buildPlotOptions, ringFitsSliceLabels } from "./apexPlotOptions";
 import { buildAutoYRange, formatPlainAxisValue } from "./apexYRange";
+import { heatmapRangeColors, isDarkSurface } from "./heatmapColors";
+import { thinnedCategoryFormatter } from "./apexCategoryLabels";
+import {
+  bucketAxisFormatter,
+  bucketTooltipFormatter,
+  detectDatetimeBuckets,
+  toBucketSeries,
+  type DatetimeBuckets,
+} from "./apexDatetimeBuckets";
 import { isReducedMotionActive } from "../../build/utils/accessibilityPreferences";
 import {
   axisLabelStyle,
@@ -21,6 +30,7 @@ import {
   readThemeBorderAccented,
   readThemeHighlighted,
   readThemeMuted,
+  readThemeSurface,
 } from "./useChartTheme";
 import type {
   ChartSeries,
@@ -287,6 +297,12 @@ function applySeriesStroke(
 }
 
 const HIGH_CONTRAST_YAXIS_TYPES: ChartType[] = ["radar"];
+/**
+ * Charts whose Y axis lists categories (a heatmap's rows: its series names)
+ * rather than values: a card's value format would write each name as NaN.
+ * Their values are still formatted, in the tooltip.
+ */
+const CATEGORY_YAXIS_TYPES: ChartType[] = ["heatmap"];
 
 function buildYAxis(
   input: UseApexChartInput,
@@ -303,16 +319,43 @@ function buildYAxis(
     yaxis.min = input.yRange.min;
     yaxis.max = input.yRange.max;
   }
+  const valueFormatter = CATEGORY_YAXIS_TYPES.includes(input.type)
+    ? undefined
+    : input.yAxisFormatter;
   (yaxis.labels as Record<string, unknown>).formatter =
-    input.yAxisFormatter ?? formatPlainAxisValue;
+    valueFormatter ?? formatPlainAxisValue;
   return yaxis;
 }
 
+/**
+ * Charts whose category labels ApexCharts never thins, whatever
+ * `hideOverlappingLabels` says: the chart thins them itself.
+ */
+const SELF_THINNED_XAXIS_TYPES: ChartType[] = ["heatmap"];
+
+function thinsOwnXLabels(input: UseApexChartInput): boolean {
+  const settings = input.xAxis;
+  return (
+    SELF_THINNED_XAXIS_TYPES.includes(input.type) &&
+    (input.xaxisType ?? "category") === "category" &&
+    settings?.hideOverlappingLabels !== false &&
+    settings?.tickAmount === undefined &&
+    !settings?.rotate
+  );
+}
+
+function xLabelFormatter(input: UseApexChartInput): unknown {
+  if (thinsOwnXLabels(input))
+    return thinnedCategoryFormatter(input.xAxisFormatter);
+  return input.xAxisFormatter;
+}
+
 function buildXAxis(
   input: UseApexChartInput,
   theme: ApexThemeColors,
 ): Record<string, unknown> {
   const settings = input.xAxis;
+  const formatter = xLabelFormatter(input);
   const xaxis: Record<string, unknown> = {
     type: input.xaxisType ?? "category",
     axisBorder: { show: false },
@@ -330,7 +373,7 @@ function buildXAxis(
       settings?.datetimeFormat !== undefined
         ? { format: settings.datetimeFormat }
         : {}),
-      ...(input.xAxisFormatter ? { formatter: input.xAxisFormatter } : {}),
+      ...(formatter ? { formatter } : {}),
     },
     crosshairs: {
       stroke: { color: readThemeBorderAccented(), dashArray: CROSSHAIR_DASH },
@@ -568,6 +611,12 @@ function buildValueBasedRanges(
   });
 }
 
+/**
+ * Several colours split a heatmap's values into ranges, one colour each,
+ * laid over the card surface from faint to full: low values fade into the
+ * card in either theme. Apex's own shading is off there, as it would lighten
+ * each range towards white again.
+ */
 function applyValueBasedColorScale(
   plotOptions: Record<string, unknown>,
   input: UseApexChartInput,
@@ -577,15 +626,37 @@ function applyValueBasedColorScale(
   if (!VALUE_SCALED_TYPES.includes(input.type)) return;
   if (input.distributed) return;
   if (palette.length < 2) return;
-  const ranges = buildValueBasedRanges(extractNumericValues(series), palette);
-  if (ranges.length === 0) return;
   const subKey = VALUE_SCALED_PLOT_KEY[input.type]!;
   const subOptions =
     (plotOptions[subKey] as Record<string, unknown> | undefined) ?? {};
+  const colors = heatmapRangeColors(
+    palette,
+    readThemeSurface(),
+    Number(subOptions.shadeIntensity ?? 1),
+  );
+  const ranges = buildValueBasedRanges(extractNumericValues(series), colors);
+  if (ranges.length === 0) return;
   subOptions.colorScale = { ranges };
+  subOptions.enableShades = false;
   plotOptions[subKey] = subOptions;
 }
 
+/**
+ * A heatmap with one colour, or one per row (`distributed`), is shaded by
+ * Apex: towards white unless told the theme is dark, where it shades towards
+ * black, the side of a dark card. Only the shading reads this mode: every
+ * colour Apex would take from it is set explicitly.
+ */
+function applyHeatmapThemeMode(
+  baseOptions: Record<string, unknown>,
+  input: UseApexChartInput,
+): void {
+  if (!VALUE_SCALED_TYPES.includes(input.type)) return;
+  baseOptions.theme = {
+    mode: isDarkSurface(readThemeSurface()) ? "dark" : "light",
+  };
+}
+
 function applyOptionalSections(
   baseOptions: Record<string, unknown>,
   input: UseApexChartInput,
@@ -595,6 +666,7 @@ function applyOptionalSections(
 ): void {
   const plotOptions = buildPlotOptions(input);
   applyValueBasedColorScale(plotOptions, input, series, palette);
+  applyHeatmapThemeMode(baseOptions, input);
   if (Object.keys(plotOptions).length > 0)
     baseOptions.plotOptions = plotOptions;
 
@@ -609,18 +681,48 @@ function applyOptionalSections(
 function projectSeries(
   input: UseApexChartInput,
   isCircular: boolean,
+  buckets: DatetimeBuckets | null,
 ): ChartSeries[] {
   if (isCircular) return [];
   void input.themeRevision;
-  const series =
+  const mixed =
     input.type === "mixed"
       ? applyMixedSeriesDefs(input.series, input.seriesDefs)
       : input.series;
+  const series = buckets ? toBucketSeries(mixed, buckets) : mixed;
   return asComparisonLines(series, input).map((entry) =>
     entry.color ? { ...entry, color: resolveChartColor(entry.color) } : entry,
   );
 }
 
+/**
+ * Calendar buckets on a datetime axis become one category each: a column
+ * per month (or day), evenly spaced, under one label, the tooltip naming the
+ * whole bucket.
+ */
+function applyDatetimeBuckets(
+  options: Record<string, unknown>,
+  input: UseApexChartInput,
+  buckets: DatetimeBuckets | null,
+): void {
+  if (!buckets) return;
+  const xaxis = options.xaxis as Record<string, unknown>;
+  const { format: _datetimeFormat, ...labels } = xaxis.labels as Record<
+    string,
+    unknown
+  >;
+  options.xaxis = {
+    ...xaxis,
+    type: "category",
+    labels: { ...labels, formatter: bucketAxisFormatter(buckets, input) },
+  };
+  const tooltip = options.tooltip as Record<string, unknown>;
+  options.tooltip = {
+    ...tooltip,
+    x: { formatter: bucketTooltipFormatter(buckets, input) },
+  };
+}
+
 /**
  * On an area chart the comparison is drawn as a bare line (v2): Apex takes a
  * fill's opacity from an rgba colour over any fill setting, so an unfilled
@@ -700,6 +802,7 @@ function buildChartOptions(
   value: UseApexChartInput,
   cfg: (typeof APEX_TYPE_CONFIGS)[ChartType],
   finalSeries: ChartSeries[],
+  buckets: DatetimeBuckets | null,
 ): Record<string, unknown> {
   void value.themeRevision;
   const ctx = buildChartOptionsContext(value, cfg, finalSeries);
@@ -725,6 +828,7 @@ function buildChartOptions(
     finalSeries,
     ctx.baseColors,
   );
+  applyDatetimeBuckets(baseOptions, value, buckets);
   return injectRawOptions(baseOptions, value.rawOptions);
 }
 
@@ -732,8 +836,9 @@ export function useApexChart(
   input: () => UseApexChartInput,
 ): UseApexChartOutput {
   const config = computed(() => APEX_TYPE_CONFIGS[input().type]);
+  const buckets = computed(() => detectDatetimeBuckets(input()));
   const finalSeries = computed<ChartSeries[]>(() =>
-    projectSeries(input(), config.value.isCircular),
+    projectSeries(input(), config.value.isCircular, buckets.value),
   );
 
   const series = computed<unknown>(() => {
@@ -745,9 +850,12 @@ export function useApexChart(
   });
 
   const options = computed<Record<string, unknown>>(() =>
-    buildChartOptions(input(), config.value, finalSeries.value),
+    buildChartOptions(input(), config.value, finalSeries.value, buckets.value),
   );
 
   const apexType = computed(() => resolveApexType(input()));
-  return { apexType, options, series };
+  const sourcePointIndex = (seriesIndex: number, dataPointIndex: number) =>
+    buckets.value?.sourceIndexes[seriesIndex]?.[dataPointIndex] ??
+    dataPointIndex;
+  return { apexType, options, series, sourcePointIndex };
 }

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

@@ -72,6 +72,8 @@ export interface UseApexChartInput {
   xAxis?: ChartXAxis;
   xAxisFormatter?: ChartXAxisFormatter;
   yAxisFormatter?: (value: number) => string;
+  /** The reader's locale, for the dates the chart writes itself. */
+  locale?: string;
   onDataPointClick?: ApexClickHandler;
 }
 
@@ -79,4 +81,9 @@ export interface UseApexChartOutput {
   apexType: ComputedRef<string>;
   options: ComputedRef<Record<string, unknown>>;
   series: ComputedRef<unknown>;
+  /**
+   * The index, in the series as given, of the point Apex drew at
+   * `dataPointIndex` (they differ when the chart lays dates out in buckets).
+   */
+  sourcePointIndex: (seriesIndex: number, dataPointIndex: number) => number;
 }

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

@@ -1,5 +1,6 @@
 import type { Component } from "vue";
 import type { ModalSize } from "../../types/modal";
+import type { RowNavigation } from "../../types/row-navigation";
 
 /**
  * Side from which a {@link DrawerOptions} drawer slides in.
@@ -43,6 +44,71 @@ export interface ContainerOptions {
 /** Options accepted by {@link useDrawer}'s `open`. */
 export interface DrawerOptions extends ContainerOptions {
   direction?: DrawerDirection;
+  /**
+   * Width a `left` / `right` drawer opens at from `lg`: a modal's width at
+   * that size (`sm` 384px ... `5xl` 1024px), `full` the whole window; 600px
+   * without one, capped to the window. Below `lg` an unsized side drawer is
+   * 440px wide, and on a phone every side drawer, sized or not, leaves a 2rem
+   * strip of backdrop (only `full` fills the screen). A `top` / `bottom`
+   * drawer ignores it.
+   */
+  size?: ModalSize;
+  /**
+   * The key the size the user drags the drawer to is remembered under, on
+   * this device (a cookie): the same drawer opens again at that size. Sizes
+   * are kept per axis, so a side and a bottom drawer may share a key.
+   * Defaults to `containerId`, else to the body component's name (its
+   * `name`, or the file name of a `<script setup>` component): a drawer keeps
+   * its size without one. Set it when one component opens drawers that
+   * should not share a size, or when an anonymous component (a render
+   * function, an async wrapper) or a per-opening `containerId` would forget.
+   */
+  sizeKey?: string;
+  /**
+   * Draws the DMS's row header in place of the drawer's own title, as on a
+   * row action's drawer: the row's title, its position ("4 of 50") and
+   * previous / next, next to the close button; J and K step while the
+   * drawer is open. For a drawer a module opens on a row of its own list.
+   */
+  rowHeader?: DrawerRowHeader;
+}
+
+/**
+ * The DMS's row header over a drawer opened with {@link useDrawer}. Patch it
+ * (`patch({ rowHeader })`) as the drawer steps to another row.
+ */
+export interface DrawerRowHeader {
+  /** The row's title; the drawer's `title` without one. */
+  title?: string;
+  /**
+   * i18n key (`$`-prefixed) of the position, receiving `{ index, total }`
+   * (1-based, grouped as the locale does); "{index} of {total}" without one.
+   */
+  positionLabel?: string;
+  /**
+   * The row's place among the rows it steps through: the position, the
+   * previous / next buttons and J / K call its `prev()` and `next()`. No
+   * position nor buttons without one.
+   */
+  navigation?: RowNavigation;
+  /** Classes added to the title's (`font-mono` for a key); its size stays. */
+  titleClass?: string;
+  /**
+   * Wraps the title only after this separator (`"."` for a dotted key): each
+   * segment keeps the separator that follows it, a `<wbr>` between them.
+   */
+  titleBreakAfter?: string;
+  /**
+   * Text after the position, on its line after a "·", cut at its end (the
+   * whole text in its tooltip): "12 of 1,338 · helio › catalog".
+   */
+  subtitle?: string;
+  /** Classes added to the subtitle's (`font-mono`). */
+  subtitleClass?: string;
+  /** Drawn under the position line, in the title's column (pills, hints). */
+  component?: Component;
+  /** Props passed to `component`. */
+  componentOptions?: Record<string, unknown>;
 }
 
 /** Options accepted by {@link useModal}'s `open`. */
@@ -67,6 +133,23 @@ export interface ContainerInstance<Result = unknown> {
 export type ContainerPatch = Partial<
   Pick<
     ContainerOptions,
-    "title" | "description" | "componentOptions" | "componentKey"
+    | "title"
+    | "description"
+    | "componentOptions"
+    | "componentKey"
+    | "headerComponentOptions"
   >
 >;
+
+/**
+ * What an open drawer can change in place: a container's, and the row
+ * header it was opened with (`rowHeader`), replaced as a whole.
+ */
+export type DrawerPatch = ContainerPatch & Pick<DrawerOptions, "rowHeader">;
+
+/** The handle of a drawer opened with {@link useDrawer}. */
+export interface DrawerInstance<Result = unknown>
+  extends Omit<ContainerInstance<Result>, "patch"> {
+  /** Updates the open drawer: its texts, its body, its row header. */
+  patch: (options: DrawerPatch) => void;
+}

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

@@ -1,9 +1,31 @@
+import { getCurrentInstance } from "vue";
 import DynamicDrawer from "../../build/components/containers/drawer/DynamicDrawer.vue";
+import DmsRowHeader from "../../build/components/containers/row/RowHeader.vue";
+import { drawerRowHeaderProps } from "../../build/components/containers/row/drawerRowHeader";
+import { listenRowSteps } from "../../build/composables/actions/rowNavigation";
+import { DMS_OWN_DRAWER } from "../../build/composables/containers/context";
+import { componentSizeKey } from "../../build/composables/containers/drawerSize";
 import { openDynamicContainer } from "./openDynamicContainer";
-import type { ContainerInstance, DrawerOptions } from "./types";
+import type {
+  DrawerInstance,
+  DrawerOptions,
+  DrawerPatch,
+  DrawerRowHeader,
+} from "./types";
 
 const DRAWER_ID_PREFIX = "drawer";
 
+/** What `useDrawer` hands the drawer besides its options. */
+interface DrawerCallerContext {
+  /** The provides of the component that called `useDrawer` (see DynamicDrawer). */
+  callerProvides?: object;
+}
+
+/** The part of a component instance holding what it and its ancestors provide. */
+interface InstanceProvides {
+  provides?: object;
+}
+
 /**
  * Public composable to open a DMS-themed drawer from any module that extends the
  * layer. Wraps the internal DynamicDrawer container; `open` returns a handle
@@ -11,16 +33,55 @@ const DRAWER_ID_PREFIX = "drawer";
  */
 export function useDrawer() {
   const overlay = useOverlay();
+  // The drawer mounts under the app's overlay provider, outside the caller's
+  // tree: it inherits what the caller provides, as a drawer written in the
+  // caller's template does. Read at each opening, as the caller may provide
+  // after calling `useDrawer`. Vue keeps them in the instance's `provides`,
+  // which its public types do not list.
+  const caller = getCurrentInstance() as InstanceProvides | null;
 
   function open<Result = unknown>(
     options: DrawerOptions,
-  ): ContainerInstance<Result> {
-    return openDynamicContainer<Result, DrawerOptions>(
-      overlay,
-      DynamicDrawer,
-      DRAWER_ID_PREFIX,
-      options,
-    );
+  ): DrawerInstance<Result> {
+    const { rowHeader, ...containerOptions } = options;
+    // The row header follows the title and the row it was last patched with.
+    let title = options.title;
+    let header: DrawerRowHeader | undefined = rowHeader;
+    const headerProps = () => header && drawerRowHeaderProps(header, title);
+    const instance = openDynamicContainer<
+      Result,
+      DrawerOptions & DrawerCallerContext
+    >(overlay, DynamicDrawer, DRAWER_ID_PREFIX, {
+      ...containerOptions,
+      // The DMS's own drawers keep the app's provides only.
+      callerProvides: DMS_OWN_DRAWER in options ? undefined : caller?.provides,
+      ...(rowHeader && {
+        headerComponent: DmsRowHeader,
+        headerComponentOptions: headerProps(),
+      }),
+      sizeKey:
+        options.sizeKey ??
+        options.containerId ??
+        componentSizeKey(options.component),
+    });
+    if (!rowHeader) {
+      // Without a row header to update, a patch is a container's.
+      return {
+        ...instance,
+        patch: ({ rowHeader: _rowHeader, ...patch }: DrawerPatch) =>
+          instance.patch(patch),
+      };
+    }
+    const stopSteps = listenRowSteps(() => header?.navigation);
+    instance.result.then(stopSteps, stopSteps);
+    return {
+      ...instance,
+      patch: ({ rowHeader: nextHeader, ...patch }: DrawerPatch) => {
+        title = patch.title ?? title;
+        header = nextHeader ?? header;
+        instance.patch({ ...patch, headerComponentOptions: headerProps() });
+      },
+    };
   }
 
   return { open };

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

@@ -0,0 +1,11 @@
+import type { InjectionKey } from "vue";
+
+/**
+ * Makes `value` the saved value of the field `id`: a control whose value the
+ * server already stored on its own (a rotated secret) is not a change left to
+ * save, and "Discard" keeps it.
+ */
+export type MarkFieldSaved = (id: string, value: unknown) => void;
+
+export const FORM_FIELD_SAVED_KEY: InjectionKey<MarkFieldSaved> =
+  Symbol("form-field-saved");

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

@@ -28,9 +28,13 @@ export interface FormField {
   disabled?: boolean;
   /** Shown, not edited: `true`, or with a pill and a link. */
   readonly?: boolean | FormFieldReadonly;
+  /** A create form shows it read-only and empty, rather than leaving it out. */
+  showEmptyOnCreate?: boolean;
   required?: boolean;
   type?: string;
   defaultValue?: FormFieldValue;
+  /** "Module default · Use default" while it holds something else. */
+  offersDefault?: boolean;
   localized?: boolean;
 }
 

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

@@ -2,4 +2,5 @@ export const FormFunctions = {
   SET_FIELD_DISABLED: "DmsComponent.Form.SetFieldDisabled",
   SET_FIELD_HIDDEN: "DmsComponent.Form.SetFieldHidden",
   SET_FIELD_REQUIRED: "DmsComponent.Form.SetFieldRequired",
+  SET_FIELD_VALUE: "DmsComponent.Form.SetFieldValue",
 } as const;