@antelopejs/dms 0.7.21 → 0.8.0

package/frontend-vue/layers/dms-ui/app/components/blocks/BannerBlock.vue

@@ -8,14 +8,16 @@ import DmsBlockActions, {
 import { useActionTargets } from "../../build/composables/actions/useActionTargets";
 import { useChartFetch } from "../../composables/chart/useChartFetch";
 import { refreshPageBlocks } from "../../utils/blockRefresh";
+import {
+  BANNER_TONE_ICONS,
+  type BannerTone,
+} from "../../utils/bannerToneIcons";
 import type { CustomButton } from "../../composables/table-view/types/custom-button";
 import { useWatch } from "../../../../dms-core/app/composables/watch/useWatch";
 import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
 import type { BlockText } from "../../../../dms-core/app/types/composed-text";
 
-type BannerTone = "info" | "success" | "warning" | "error" | "primary";
-
 /** What a banner shows (interface-dms `BannerContent`). */
 interface BannerContent {
   /** A string (`$` for an i18n key) or a composed text. */
@@ -83,14 +85,6 @@ const DISMISSED_MAX_KEYS = 40;
 const FALLBACK_COMPONENT_ID = "banner";
 const FALLBACK_PAGE_ID = "page";
 
-const TONE_ICONS: Record<BannerTone, string> = {
-  info: "i-ph-info",
-  success: "i-ph-check-circle",
-  warning: "i-ph-warning",
-  error: "i-ph-warning-circle",
-  primary: "i-ph-sparkle",
-};
-
 const { state: watchState } = useWatch(
   props.watchActions || [],
   props.componentId,
@@ -183,7 +177,7 @@ function press(action: BlockButtonAction): void {
     :description="
       banner.description ? processText(banner.description) : undefined
     "
-    :icon="banner.icon ?? TONE_ICONS[banner.tone]"
+    :icon="banner.icon ?? BANNER_TONE_ICONS[banner.tone]"
     :tone="banner.tone"
     :size="banner.size"
     :dismissible="banner.dismissible"

package/frontend-vue/layers/dms-ui/app/components/blocks/NavCardGridBlock.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageLink } from "../../build/composables/page/pageUrlValues";
 import { gridColumnsTemplate } from "../grid/columns";
 import {
   useCategoryNavCards,
@@ -217,7 +218,7 @@ const { t } = useI18n();
         >
           <DmsNavCard
             class="h-full"
-            :to="card.to"
+            :to="pageLink(card.to)"
             :icon="card.icon"
             :icon-tone="card.iconTone"
             :title="card.title"

package/frontend-vue/layers/dms-ui/app/components/chart/ApexChartHost.vue

@@ -24,7 +24,14 @@ interface Emits {
   (event: "drawn"): void;
 }
 
+/** The ApexCharts instance the wrapper exposes as `chart`. */
+interface ApexCore {
+  /** Apex's own (debounced) window resize handler: redraws at the container width. */
+  windowResizeHandler: () => void;
+}
+
 interface ApexChartInstance {
+  chart: ApexCore | null;
   updateOptions: (
     options: Record<string, unknown>,
     redrawPaths?: boolean,
@@ -39,6 +46,7 @@ const emit = defineEmits<Emits>();
 const REDRAW_PATHS = false;
 const ANIMATE = true;
 const UPDATE_SYNCED_CHARTS = false;
+const WIDTH_TOLERANCE_PX = 1;
 
 const { locale } = useI18n();
 
@@ -57,6 +65,7 @@ onMounted(() => {
   void ensureApexLocale(locale.value).catch(() => undefined);
 });
 
+const hostRef = ref<HTMLElement | null>(null);
 const chartRef = ref<ApexChartInstance | null>(null);
 
 /**
@@ -123,10 +132,31 @@ watch(
 function onDrawn() {
   emit("drawn");
 }
+
+function isDrawnAtStaleWidth(host: HTMLElement): boolean {
+  const svg = host.querySelector("svg.apexcharts-svg");
+  if (!svg) return false;
+  const drawnWidth = svg.getBoundingClientRect().width;
+  const hostWidth = host.getBoundingClientRect().width;
+  return Math.abs(drawnWidth - hostWidth) > WIDTH_TOLERANCE_PX;
+}
+
+/**
+ * Apex drops its container's resizes while an animation runs, so a sidebar
+ * collapsed or expanded during one leaves the chart at its old width, past
+ * its card when the container shrank, until the next window resize. Once the
+ * animation is over, a chart drawn at another width than its host redraws.
+ */
+function redrawIfResizedWhileAnimating() {
+  const host = hostRef.value;
+  const chart = chartRef.value?.chart;
+  if (!host || !chart || !isDrawnAtStaleWidth(host)) return;
+  chart.windowResizeHandler();
+}
 </script>
 
 <template>
-  <div class="dms-apex">
+  <div ref="hostRef" class="dms-apex">
     <ApexChart
       ref="chartRef"
       :type="apexType"
@@ -135,6 +165,7 @@ function onDrawn() {
       :series="apexSeries"
       @mounted="onDrawn"
       @updated="onDrawn"
+      @animation-end="redrawIfResizedWhileAnimating"
     />
   </div>
 </template>

package/frontend-vue/layers/dms-ui/app/components/check-list/CheckList.vue

@@ -75,7 +75,7 @@ const ICONS: Record<
     ok: "i-ph-check",
     warn: "i-ph-warning",
     error: "i-ph-x",
-    pending: "i-ph-x",
+    pending: "i-ph-circle",
     info: "i-ph-arrow-right",
   },
 };

package/frontend-vue/layers/dms-ui/app/components/form/Form.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageLink } from "../../build/composables/page/pageUrlValues";
 import type { FormProps } from "../../composables/form/types/props";
 import type {
   FormData,
@@ -64,6 +65,7 @@ import DmsFormErrorSummary from "../../build/components/form/FormErrorSummary.vu
 import DmsFormLoadError from "../../build/components/form/FormLoadError.vue";
 import {
   type FormRecordLoad,
+  missingRecordFailure,
   trackFormRecordLoad,
 } from "../../build/composables/form/formRecordLoad";
 import DmsFormRequiredLegend from "./FormRequiredLegend.vue";
@@ -492,7 +494,7 @@ function cancelForm(): void {
     window.history.back();
     return;
   }
-  if (props.backTo) void router.push(props.backTo);
+  if (props.backTo) void router.push(pageLink(props.backTo));
 }
 
 const validators = new Set<FormValidator>();
@@ -573,7 +575,15 @@ if (props.fetchUrl) {
   });
 }
 
-const loadFailure = computed(() => recordLoad?.failure.value ?? null);
+const loadFailure = computed(
+  () =>
+    recordLoad?.failure.value ??
+    missingRecordFailure({
+      requiresRecord: props.requiresRecord,
+      fetchUrl: props.fetchUrl,
+      resolvedFetchUrl: resolvedFetchUrl.value,
+    }),
+);
 const isRetryingLoad = computed(() => recordLoad?.retrying.value ?? false);
 
 /** Load the record again after a failure; it is what the form starts from. */

package/frontend-vue/layers/dms-ui/app/components/form/components/Cascader.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageRequestUrl } from "../../../build/composables/page/pageUrlValues";
 import {
   buildCascaderTree,
   CASCADER_FETCH_LIMIT,
@@ -68,8 +69,10 @@ interface CascaderResponse {
 
 const { data, status, execute } = await useDmsAsyncData(
   `cascader-${instanceId}`,
-  () =>
-    $authFetch<CascaderResponse>(props.searchUrl, {
+  () => {
+    const url = pageRequestUrl(props.searchUrl);
+    if (!url) return Promise.resolve({ results: [], total: 0 });
+    return $authFetch<CascaderResponse>(url, {
       params: { limit: CASCADER_FETCH_LIMIT },
       onRequestError: ({ error }: { error: Error }) => {
         toast.add({
@@ -78,7 +81,8 @@ const { data, status, execute } = await useDmsAsyncData(
           description: error.message,
         });
       },
-    }),
+    });
+  },
   { lazy: true, immediate: false },
 );
 

package/frontend-vue/layers/dms-ui/app/components/form/components/File.vue

@@ -349,6 +349,12 @@ const acceptString = computed(() =>
   props.constraints?.allowedMimetypes?.join(","),
 );
 
+const dropPromptKey = computed(() =>
+  props.multiple
+    ? "dms.form.file.drop_prompt_multiple"
+    : "dms.form.file.drop_prompt",
+);
+
 const maxSizeFormatted = computed(() => {
   if (!props.constraints?.maxSize) return null;
   return formatFileSize(props.constraints.maxSize);
@@ -373,6 +379,7 @@ onScopeDispose(() => {
       :disabled="disabled || isUploading"
       :color="color"
       :highlight="highlight"
+      :label="$t(dropPromptKey)"
       v-bind="dropZoneAria"
     >
       <template v-if="maxSizeFormatted" #description>

package/frontend-vue/layers/dms-ui/app/components/form/components/InputAddress.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageRequestUrl } from "../../../build/composables/page/pageUrlValues";
 import type { SelectMenuItem } from "@nuxt/ui";
 import { refDebounced } from "@vueuse/core";
 import {
@@ -225,7 +226,9 @@ interface CountryOptions {
 }
 
 async function fetchCountryOptions(): Promise<CountryOptions> {
-  const data = await $authFetch<CountryApiResponse>(props.searchUrl!, {
+  const url = pageRequestUrl(props.searchUrl);
+  if (!url) return { results: [], total: 0 };
+  const data = await $authFetch<CountryApiResponse>(url, {
     params: {
       q: countrySearchTermDebounced.value,
     },

package/frontend-vue/layers/dms-ui/app/components/form/components/InputCode.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageRequestUrl } from "../../../build/composables/page/pageUrlValues";
 import { getCurrentInstance, h, render } from "vue";
 import { useFormField } from "@nuxt/ui/composables/useFormField";
 import UIcon from "@nuxt/ui/runtime/vue/components/Icon.vue";
@@ -84,10 +85,11 @@ function checkSyntax(text: string): void {
 
 async function loadCompletions(): Promise<CodeEditorCompletion[]> {
   const fixed = props.completions ?? [];
-  if (!props.completionsUrl) return fixed;
+  const url = pageRequestUrl(props.completionsUrl);
+  if (!url) return fixed;
   const response = await $authFetch<
     CodeEditorCompletion[] | CompletionsResponse
-  >(props.completionsUrl).catch(() => []);
+  >(url).catch(() => []);
   const fetched = Array.isArray(response) ? response : (response.items ?? []);
   return [...fixed, ...fetched];
 }

package/frontend-vue/layers/dms-ui/app/components/form/components/InputSecret.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageRequestUrl } from "../../../build/composables/page/pageUrlValues";
 import { useConfirm } from "../../../composables/confirm/useConfirm";
 import DmsCopyButton from "../../copy/CopyButton.vue";
 
@@ -43,7 +44,7 @@ const masked = computed(() => {
 });
 
 async function rotate(): Promise<void> {
-  const url = props.rotateUrl;
+  const url = pageRequestUrl(props.rotateUrl);
   if (!url) return;
   const confirmed = await confirm({
     title: t("dms.form.secret.rotate_title"),
@@ -95,7 +96,7 @@ async function rotate(): Promise<void> {
     </UInput>
     <DmsCopyButton v-if="props.copyable && value" :value="value" />
     <UButton
-      v-if="props.rotateUrl"
+      v-if="pageRequestUrl(props.rotateUrl)"
       icon="i-ph-arrows-clockwise"
       :label="t('dms.form.secret.rotate')"
       color="neutral"

package/frontend-vue/layers/dms-ui/app/components/form/components/Relation.vue

@@ -3,6 +3,7 @@
   lang="ts"
   generic="T extends ArrayOrNested<SelectMenuItem>, M extends boolean = false"
 >
+import { pageRequestUrl } from "../../../build/composables/page/pageUrlValues";
 import { useForwardPropsEmits } from "reka-ui";
 import type {
   SelectMenuProps,
@@ -193,7 +194,9 @@ interface RelationItems {
 }
 
 async function fetchRelationItems(): Promise<RelationItems> {
-  const data = await $authFetch<RelationResponse>(props.searchUrl, {
+  const url = pageRequestUrl(props.searchUrl);
+  if (!url) return { results: [], total: 0 };
+  const data = await $authFetch<RelationResponse>(url, {
     params: {
       search: searchTermDebounced.value || undefined,
     },

package/frontend-vue/layers/dms-ui/app/components/grid/columns.ts

@@ -5,6 +5,18 @@ const SINGLE_COLUMN = 1;
 /** Track floor below which a column stops being usable, as a CSS length. */
 export const GRID_DEFAULT_MIN_COLUMN_WIDTH = "240px";
 
+const UNITLESS_NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)$/;
+
+/**
+ * A length usable inside `calc()`. A bare `0` is a valid `gap` but not a
+ * length in a calculation, where it would void the whole template and leave
+ * the grid on a single column; a unitless number reads as pixels.
+ */
+function calcLength(value: string): string {
+  const trimmed = value.trim();
+  return UNITLESS_NUMBER.test(trimmed) ? `${trimmed}px` : trimmed;
+}
+
 /**
  * The column track template a `Grid` and every `GridRow` inside it share.
  *
@@ -26,8 +38,8 @@ export function gridColumnsTemplate(
   minColumnWidth: string,
 ): string {
   const columns = Math.max(maxColumns, SINGLE_COLUMN);
-  const columnShare = `(100% - ${columns - SINGLE_COLUMN} * ${gap}) / ${columns}`;
-  return `repeat(auto-fill, minmax(min(100%, max(${minColumnWidth}, ${columnShare})), 1fr))`;
+  const columnShare = `(100% - ${columns - SINGLE_COLUMN} * ${calcLength(gap)}) / ${columns}`;
+  return `repeat(auto-fill, minmax(min(100%, max(${calcLength(minColumnWidth)}, ${columnShare})), 1fr))`;
 }
 
 /** Custom property a `Grid` / `GridRow` hands its cells: the tracks left. */
@@ -43,7 +55,7 @@ function trackBreakpoint(
   gap: string,
   minColumnWidth: string,
 ): string {
-  return `calc(${columns} * ${minColumnWidth} + ${columns - SINGLE_COLUMN} * ${gap})`;
+  return `calc(${columns} * ${calcLength(minColumnWidth)} + ${columns - SINGLE_COLUMN} * ${calcLength(gap)})`;
 }
 
 /** A container name / attribute value built from any id. */

package/frontend-vue/layers/dms-ui/app/components/key-value-list/KeyValueList.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageLink } from "../../build/composables/page/pageUrlValues";
 import { computed } from "vue";
 import { regionalDateTimeFormat } from "#dms-core/app/utils/regional";
 import DmsStatusPill from "../status-pill/StatusPill.vue";
@@ -216,7 +217,7 @@ function keyOf(item: KeyValueItem, index: number): string {
           <template v-else>
             <component
               :is="item.to ? DmsAutoLink : 'span'"
-              :to="item.to"
+              :to="pageLink(item.to)"
               class="min-w-0"
               :class="item.to && item.type !== 'status' && 'hover:underline'"
             >

package/frontend-vue/layers/dms-ui/app/components/list-row/ListRow.vue

@@ -125,6 +125,7 @@ const theme = tv({
     dot: "size-2 rounded-full bg-(--dms-accent-fill) shadow-[0_0_0_3px_var(--dms-accent-tint)]",
     body: "min-w-0 flex-1",
     title: "flex items-center gap-2",
+    titleText: "",
     description: "text-muted mt-0.5 text-[12.5px]",
     // The "·" closes each entry followed by another (rather than opening it),
     // so a wrapped line never starts with a separator.
@@ -188,7 +189,11 @@ const theme = tv({
     // end, so the title and meta wrap there instead.
     truncate: {
       true: {
-        title: "truncate max-sm:whitespace-normal",
+        title:
+          "truncate flex-nowrap max-sm:flex-wrap max-sm:whitespace-normal",
+        // The text box, not the flex title, carries the ellipsis: a flex
+        // container only clips its overflowing children.
+        titleText: "truncate max-sm:whitespace-normal",
         meta: "flex-nowrap overflow-hidden whitespace-nowrap max-sm:flex-wrap max-sm:whitespace-normal",
         detail: "truncate max-sm:whitespace-normal",
       },
@@ -281,7 +286,9 @@ const unreadText = computed(
           :class="ui.title()"
           :title="props.truncate ? props.title : undefined"
         >
-          <slot>{{ props.title }}</slot>
+          <slot>
+            <span :class="ui.titleText()">{{ props.title }}</span>
+          </slot>
         </div>
         <p v-if="hasDescription" :class="ui.description()">
           <slot name="description">{{ props.description }}</slot>

package/frontend-vue/layers/dms-ui/app/components/save-bar/InstantSaveBadge.vue

@@ -3,10 +3,11 @@ import type { SaveStatusState } from "./SaveStatus.vue";
 
 interface InstantSaveBadgeProps {
   /**
-   * Save activity of the page, for a subtle "just saved" flash: the icon
-   * spins while a change is being written and turns into a tick once it is,
-   * and the pill turns red while a save failed (the control says which).
-   * The wording never changes. Defaults to `idle` (a lightning bolt).
+   * Save activity of the page, for a subtle "just saved" flash: the pill
+   * reads "Saving" with a spinning icon while a change is being written,
+   * then "Saved instantly" with a tick once it is, and turns red with "Not
+   * saved" while a save failed (the control says which). Defaults to `idle`
+   * (a lightning bolt and "Saved instantly").
    */
   state?: SaveStatusState;
 }
@@ -23,6 +24,13 @@ const ICONS: Record<SaveStatusState, string> = {
   error: "i-ph-warning-circle",
 };
 
+const LABELS: Record<SaveStatusState, string> = {
+  idle: "dms.save_bar.instant",
+  saving: "dms.save_bar.saving",
+  saved: "dms.save_bar.instant",
+  error: "dms.save_bar.not_saved",
+};
+
 const TONE_CLASSES = {
   ok: "border-success/40 bg-success/10 text-success",
   error: "border-error/40 bg-error/10 text-error",
@@ -49,6 +57,6 @@ const TONE_CLASSES = {
       class="size-3.5 shrink-0"
       :class="{ 'animate-spin': props.state === 'saving' }"
     />
-    {{ t("dms.save_bar.instant") }}
+    {{ t(LABELS[props.state]) }}
   </span>
 </template>

package/frontend-vue/layers/dms-ui/app/components/save-bar/SaveBar.vue

@@ -40,7 +40,7 @@ interface SaveBarProps {
   kind?: FormKind;
   /**
    * Whether anything in the form can be changed: an `action` form nothing in
-   * which can be changed shows its submit alone, all the time.
+   * which can be changed never offers Reset.
    */
   resettable?: boolean;
 }

package/frontend-vue/layers/dms-ui/app/components/stat-group/StatGroup.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { pageLink } from "../../build/composables/page/pageUrlValues";
 import { computed } from "vue";
 import type { IconWellTone } from "../icon-well/IconWell.vue";
 import DmsStatCell from "../../build/components/stat/StatCell.vue";
@@ -146,7 +147,7 @@ function wellTone(item: StatGroupItem): IconWellTone {
           :icon="item.icon"
           :detail="item.detail"
           :detail-tone="item.detailTone"
-          :to="item.to"
+          :to="pageLink(item.to)"
           size="sm"
           :tone="wellTone(item)"
           :loading="props.loading"
@@ -175,7 +176,7 @@ function wellTone(item: StatGroupItem): IconWellTone {
           :icon="item.icon"
           :detail="item.detail"
           :detail-tone="item.detailTone"
-          :to="item.to"
+          :to="pageLink(item.to)"
           :tone="wellTone(item)"
           :loading="props.loading"
           stack

package/frontend-vue/layers/dms-ui/app/components/table-view/CascaderPath.vue

@@ -1,20 +1,28 @@
 <script setup lang="ts">
 import {
-  buildCascaderPathLabels,
   CASCADER_FETCH_LIMIT,
   CASCADER_PATH_SEPARATOR,
+  cascaderValuePath,
   resolveCascaderKeyMapping,
   type CascaderKeyMapping,
 } from "../../utils/cascader";
+import { MAX_RELATION_BADGES } from "../../build/composables/data-types/relationBadges";
 
 const DEFAULT_VALUE_KEY = "_id";
 
 interface CascaderPathProps {
+  /** One picked value, or the list a multiple cascader holds. */
   value: unknown;
   searchUrl?: string;
   keyMapping?: Partial<CascaderKeyMapping>;
 }
 
+/** A picked value of a multiple cascader: its name, its path on hover. */
+interface CascaderBadge {
+  label: string;
+  title: string;
+}
+
 const props = defineProps<CascaderPathProps>();
 
 const { $authFetch } = useAuthFetch();
@@ -31,22 +39,6 @@ const keyMapping = computed(() =>
   }),
 );
 
-const valueObject = computed(() =>
-  isObject(props.value) ? (props.value as Record<string, unknown>) : undefined,
-);
-
-const valueId = computed(() => {
-  const raw = valueObject.value
-    ? valueObject.value[keyMapping.value.value]
-    : props.value;
-  return raw === undefined || raw === null ? undefined : String(raw);
-});
-
-const ownLabel = computed(() => {
-  const label = valueObject.value?.[keyMapping.value.label];
-  return label === undefined || label === null ? undefined : String(label);
-});
-
 const { data } = await useDmsAsyncData(
   `cascader-path-${props.searchUrl}`,
   () =>
@@ -58,21 +50,51 @@ const { data } = await useDmsAsyncData(
   { lazy: true },
 );
 
-const pathLabel = computed(() => {
-  if (!valueId.value) return ownLabel.value ?? "";
-  const rows = data.value?.results;
-  if (rows) {
-    const labels = buildCascaderPathLabels(
-      rows,
-      keyMapping.value,
-      valueId.value,
-    );
-    if (labels.length > 0) return labels.join(CASCADER_PATH_SEPARATOR);
-  }
-  return ownLabel.value ?? valueId.value;
-});
+const pathOf = (item: unknown): string[] =>
+  cascaderValuePath(item, keyMapping.value, data.value?.results);
+
+const pathLabel = computed(() =>
+  pathOf(props.value).join(CASCADER_PATH_SEPARATOR),
+);
+
+const badges = computed<CascaderBadge[]>(() =>
+  (Array.isArray(props.value) ? props.value : [])
+    .map(pathOf)
+    .filter((path) => path.length > 0)
+    .map((path) => ({
+      label: path.at(-1) ?? "",
+      title: path.join(CASCADER_PATH_SEPARATOR),
+    })),
+);
+const visibleBadges = computed(() =>
+  badges.value.slice(0, MAX_RELATION_BADGES),
+);
+const hiddenBadges = computed(() => badges.value.slice(MAX_RELATION_BADGES));
 </script>
 
 <template>
-  <span class="truncate" :title="pathLabel">{{ pathLabel }}</span>
+  <span
+    v-if="Array.isArray(props.value)"
+    class="inline-flex flex-wrap items-center gap-1"
+  >
+    <UBadge
+      v-for="badge in visibleBadges"
+      :key="badge.title"
+      :label="badge.label"
+      :title="badge.title"
+      color="neutral"
+      variant="subtle"
+      size="sm"
+      class="max-w-40"
+    />
+    <UBadge
+      v-if="hiddenBadges.length"
+      :label="`+${hiddenBadges.length}`"
+      :title="hiddenBadges.map((badge) => badge.title).join(', ')"
+      color="neutral"
+      variant="subtle"
+      size="sm"
+    />
+  </span>
+  <span v-else class="truncate" :title="pathLabel">{{ pathLabel }}</span>
 </template>

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

@@ -9,7 +9,14 @@ import {
 
 const DEFAULT_BAR_RADIUS = 4;
 const DEFAULT_BAR_WIDTH_PCT = "60%";
-const DEFAULT_DONUT_HOLE = "76%";
+const HUNDRED_PERCENT = 100;
+/** Ring thickness, in percent of the radius, of a donut without `arcWidth`. */
+const DEFAULT_ARC_WIDTH = 24;
+/**
+ * The thinnest ring, in percent of the radius, a slice label ("33.0%") fits
+ * in: on a thinner one its white text runs past the ring onto the card.
+ */
+const MIN_LABELLED_ARC_WIDTH = 35;
 const DEFAULT_RADIAL_HOLE = "60%";
 const CENTER_NAME_FONT_SIZE = "10.5px";
 const CENTER_NAME_FONT_WEIGHT = 600;
@@ -17,7 +24,6 @@ const CENTER_VALUE_FONT_SIZE = "20px";
 const CENTER_VALUE_FONT_WEIGHT = 650;
 const HEATMAP_RADIUS = 4;
 const HEATMAP_DEFAULT_INTENSITY = 0.6;
-const HUNDRED_PERCENT = 100;
 
 type PlotBuilder = (props: UseApexChartInput) => Record<string, unknown>;
 
@@ -47,8 +53,13 @@ function buildBarPlotOptions(
 }
 
 function donutSizeFor(arcWidth: number | undefined): string {
-  if (arcWidth === undefined) return DEFAULT_DONUT_HOLE;
-  return `${HUNDRED_PERCENT - arcWidth}%`;
+  return `${HUNDRED_PERCENT - (arcWidth ?? DEFAULT_ARC_WIDTH)}%`;
+}
+
+/** Whether a slice label fits inside the chart's ring; always true off donuts. */
+export function ringFitsSliceLabels(input: UseApexChartInput): boolean {
+  if (input.type !== "donut") return true;
+  return (input.arcWidth ?? DEFAULT_ARC_WIDTH) >= MIN_LABELLED_ARC_WIDTH;
 }
 
 /** v2 donut centre: mono eyebrow over a 20px value. */