@byline/admin 4.15.0 → 4.17.0

package/dist/modules/analytics/components/timeseries.js

@@ -0,0 +1,253 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useRef, useState } from "react";
+import { useTranslation } from "@byline/i18n/react";
+import clsx from "clsx";
+import timeseries_module from "./timeseries.module.js";
+const VIEWBOX_WIDTH = 900;
+const VIEWBOX_HEIGHT = 180;
+const COLUMN_GAP_RATIO = 0.38;
+const MAX_COLUMN_WIDTH = 26;
+function resolveAnalyticsChartGranularity(period, dayCount) {
+    if ('number' == typeof period || 'all' === period && dayCount <= 90) return 'day';
+    if ('ytd' === period || dayCount <= 732) return 'seven-day';
+    return 'month';
+}
+function bucketAnalyticsTimeseries(days, granularity) {
+    if ('day' === granularity) return days.map((day)=>({
+            from: day.day,
+            to: day.day,
+            granularity,
+            dayCount: 1,
+            views: day.views,
+            visitors: day.visitors,
+            downloads: day.downloads
+        }));
+    if ('seven-day' === granularity) return bucketBySevenDays(days);
+    return bucketByUtcMonth(days);
+}
+function buildAnalyticsColumns(buckets) {
+    if (0 === buckets.length) return [];
+    const ceiling = Math.max(1, ...buckets.map((bucket)=>bucket.views));
+    const step = VIEWBOX_WIDTH / buckets.length;
+    const width = Math.max(2, Math.min(step * (1 - COLUMN_GAP_RATIO), MAX_COLUMN_WIDTH));
+    return buckets.map((bucket, index)=>{
+        const centre = index * step + step / 2;
+        const height = bucket.views / ceiling * VIEWBOX_HEIGHT;
+        const insetHeight = bucket.visitors / ceiling * VIEWBOX_HEIGHT;
+        const insetWidth = Math.max(1, width / 2);
+        return {
+            index,
+            x: centre - width / 2,
+            width,
+            y: VIEWBOX_HEIGHT - height,
+            height,
+            insetX: centre - insetWidth / 2,
+            insetWidth,
+            insetY: VIEWBOX_HEIGHT - insetHeight,
+            insetHeight,
+            hitX: index * step,
+            hitWidth: step
+        };
+    });
+}
+function AnalyticsTimeseries({ days, granularity, locale }) {
+    const { t } = useTranslation('byline-admin');
+    const [hovered, setHovered] = useState(null);
+    const plot = useRef(null);
+    const buckets = useMemo(()=>bucketAnalyticsTimeseries(days, granularity), [
+        days,
+        granularity
+    ]);
+    const columns = useMemo(()=>buildAnalyticsColumns(buckets), [
+        buckets
+    ]);
+    const numbers = useMemo(()=>new Intl.NumberFormat(locale), [
+        locale
+    ]);
+    const dayLabel = useMemo(()=>new Intl.DateTimeFormat(locale, {
+            month: 'short',
+            day: 'numeric',
+            timeZone: 'UTC'
+        }), [
+        locale
+    ]);
+    const formatDay = (day)=>dayLabel.format(new Date(`${day}T00:00:00.000Z`));
+    const formatBucket = (bucket)=>1 === bucket.dayCount ? formatDay(bucket.from) : `${formatDay(bucket.from)} – ${formatDay(bucket.to)}`;
+    const visitorLabel = (bucket)=>'day' === bucket.granularity ? t('analytics.stats.dailyUniques') : t('analytics.stats.summedDailyUniques');
+    const active = null == hovered ? void 0 : buckets[hovered];
+    const readBucket = (bucket)=>[
+            formatBucket(bucket),
+            `${t('analytics.stats.views')} ${numbers.format(bucket.views)}`,
+            `${visitorLabel(bucket)} ${numbers.format(bucket.visitors)}`,
+            `${t('analytics.stats.downloads')} ${numbers.format(bucket.downloads)}`
+        ].join(', ');
+    const trackPointer = (event)=>{
+        if (0 === buckets.length || null == plot.current) return;
+        const bounds = plot.current.getBoundingClientRect();
+        if (0 === bounds.width) return;
+        const ratio = (event.clientX - bounds.left) / bounds.width;
+        setHovered(Math.min(buckets.length - 1, Math.max(0, Math.floor(ratio * buckets.length))));
+    };
+    const trackKey = (event)=>{
+        if (0 === buckets.length) return;
+        const step = 'ArrowRight' === event.key ? 1 : 'ArrowLeft' === event.key ? -1 : 0;
+        if (0 === step && 'Home' !== event.key && 'End' !== event.key && 'Escape' !== event.key) return;
+        event.preventDefault();
+        if ('Escape' === event.key) return setHovered(null);
+        if ('Home' === event.key) return setHovered(0);
+        if ('End' === event.key) return setHovered(buckets.length - 1);
+        setHovered((current)=>{
+            const next = (current ?? (step > 0 ? -1 : buckets.length)) + step;
+            return Math.min(buckets.length - 1, Math.max(0, next));
+        });
+    };
+    return /*#__PURE__*/ jsxs("div", {
+        className: clsx('byline-analytics-timeseries', timeseries_module.root),
+        role: "slider",
+        tabIndex: 0,
+        "aria-label": t('analytics.chart.views'),
+        "aria-valuemin": 0,
+        "aria-valuemax": Math.max(0, buckets.length - 1),
+        "aria-valuenow": hovered ?? 0,
+        "aria-valuetext": null == active ? t('analytics.chart.hint') : readBucket(active),
+        onPointerMove: trackPointer,
+        onPointerLeave: ()=>setHovered(null),
+        onKeyDown: trackKey,
+        onBlur: ()=>setHovered(null),
+        children: [
+            /*#__PURE__*/ jsxs("svg", {
+                ref: plot,
+                className: clsx('byline-analytics-chart', timeseries_module.chart),
+                viewBox: `0 0 ${VIEWBOX_WIDTH} ${VIEWBOX_HEIGHT}`,
+                preserveAspectRatio: "none",
+                "aria-hidden": "true",
+                children: [
+                    /*#__PURE__*/ jsx("title", {
+                        children: t('analytics.chart.views')
+                    }),
+                    [
+                        0.5,
+                        1
+                    ].map((fraction)=>/*#__PURE__*/ jsx("line", {
+                            className: timeseries_module.gridline,
+                            x1: 0,
+                            x2: VIEWBOX_WIDTH,
+                            y1: VIEWBOX_HEIGHT - VIEWBOX_HEIGHT * fraction,
+                            y2: VIEWBOX_HEIGHT - VIEWBOX_HEIGHT * fraction,
+                            vectorEffect: "non-scaling-stroke"
+                        }, fraction)),
+                    columns.map((column)=>/*#__PURE__*/ jsxs("g", {
+                            className: clsx(timeseries_module.column, hovered === column.index && timeseries_module.columnActive),
+                            children: [
+                                /*#__PURE__*/ jsx("rect", {
+                                    className: timeseries_module.views,
+                                    x: column.x,
+                                    width: column.width,
+                                    y: column.y,
+                                    height: column.height
+                                }),
+                                /*#__PURE__*/ jsx("rect", {
+                                    className: timeseries_module.visitors,
+                                    x: column.insetX,
+                                    width: column.insetWidth,
+                                    y: column.insetY,
+                                    height: column.insetHeight
+                                })
+                            ]
+                        }, buckets[column.index]?.from))
+                ]
+            }),
+            /*#__PURE__*/ jsxs("div", {
+                className: clsx('byline-analytics-axis', timeseries_module.axis),
+                "aria-hidden": "true",
+                children: [
+                    /*#__PURE__*/ jsx("span", {
+                        children: buckets.length > 0 && null != buckets[0] ? formatDay(buckets[0].from) : ''
+                    }),
+                    /*#__PURE__*/ jsx("span", {
+                        children: buckets.length > 0 && null != buckets[buckets.length - 1] ? formatDay(buckets[buckets.length - 1]?.to ?? '') : ''
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsx("p", {
+                className: clsx('byline-analytics-readout', timeseries_module.readout),
+                "aria-live": "polite",
+                children: null == active ? t('analytics.chart.hint') : /*#__PURE__*/ jsxs(Fragment, {
+                    children: [
+                        /*#__PURE__*/ jsx("strong", {
+                            children: formatBucket(active)
+                        }),
+                        /*#__PURE__*/ jsx("span", {
+                            className: timeseries_module.swatchViews
+                        }),
+                        t('analytics.stats.views'),
+                        " ",
+                        numbers.format(active.views),
+                        /*#__PURE__*/ jsx("span", {
+                            className: timeseries_module.swatchVisitors
+                        }),
+                        visitorLabel(active),
+                        " ",
+                        numbers.format(active.visitors),
+                        /*#__PURE__*/ jsx("span", {
+                            className: timeseries_module.swatchDownloads
+                        }),
+                        t('analytics.stats.downloads'),
+                        " ",
+                        numbers.format(active.downloads)
+                    ]
+                })
+            })
+        ]
+    });
+}
+function bucketBySevenDays(days) {
+    const buckets = [];
+    for(let index = 0; index < days.length; index += 7){
+        const rows = days.slice(index, index + 7);
+        const first = rows[0];
+        const last = rows[rows.length - 1];
+        if (null != first && null != last) buckets.push(combineRows(first.day, last.day, 'seven-day', rows));
+    }
+    return buckets;
+}
+function bucketByUtcMonth(days) {
+    const buckets = [];
+    let rows = [];
+    let month;
+    const flush = ()=>{
+        const first = rows[0];
+        const last = rows[rows.length - 1];
+        if (null != first && null != last) buckets.push(combineRows(first.day, last.day, 'month', rows));
+        rows = [];
+    };
+    for (const day of days){
+        const nextMonth = day.day.slice(0, 7);
+        if (null != month && nextMonth !== month) flush();
+        month = nextMonth;
+        rows.push(day);
+    }
+    flush();
+    return buckets;
+}
+function combineRows(from, to, granularity, rows) {
+    let views = 0;
+    let visitors = 0;
+    let downloads = 0;
+    for (const row of rows){
+        views += row.views;
+        visitors += row.visitors;
+        downloads += row.downloads;
+    }
+    return {
+        from,
+        to,
+        granularity,
+        dayCount: rows.length,
+        views,
+        visitors,
+        downloads
+    };
+}
+export { AnalyticsTimeseries, bucketAnalyticsTimeseries, buildAnalyticsColumns, resolveAnalyticsChartGranularity };

package/dist/modules/analytics/components/timeseries.module.js

@@ -0,0 +1,17 @@
+import "./timeseries_module.css";
+const timeseries_module = {
+    root: "root-L2qL4D",
+    chart: "chart-giYTrx",
+    gridline: "gridline-R_wAwP",
+    column: "column-_Cw2Ua",
+    views: "views-WHbm44",
+    columnActive: "columnActive-CwHwbo",
+    visitors: "visitors-n6IL4B",
+    hit: "hit-ZxDHvk",
+    axis: "axis-fBshTw",
+    readout: "readout-L9jEpz",
+    swatchViews: "swatchViews-OCeKNe",
+    swatchVisitors: "swatchVisitors-O3BWz6",
+    swatchDownloads: "swatchDownloads-SVo9mN"
+};
+export default timeseries_module;

package/dist/modules/analytics/components/timeseries_module.css

@@ -0,0 +1,126 @@
+.root-L2qL4D {
+  border-radius: .25rem;
+  flex-direction: column;
+  gap: .5rem;
+  display: flex;
+}
+
+.root-L2qL4D:focus-visible {
+  outline: 2px solid var(--primary-500);
+  outline-offset: 4px;
+}
+
+:is(.chart-giYTrx, .byline-analytics-chart) {
+  width: 100%;
+  height: 11rem;
+  display: block;
+}
+
+.gridline-R_wAwP {
+  stroke: var(--gray-200);
+  stroke-width: 1px;
+}
+
+.column-_Cw2Ua {
+  transition: opacity .12s;
+}
+
+.views-WHbm44 {
+  fill: #38bdf8;
+  opacity: .38;
+  transition: opacity .12s;
+}
+
+.columnActive-CwHwbo .views-WHbm44 {
+  opacity: .62;
+}
+
+.visitors-n6IL4B {
+  fill: #7c3aed;
+  opacity: .95;
+}
+
+.hit-ZxDHvk {
+  fill: #0000;
+  cursor: crosshair;
+}
+
+:is(.axis-fBshTw, .byline-analytics-axis) {
+  font-variant-numeric: tabular-nums;
+  letter-spacing: .04em;
+  color: var(--gray-500);
+  justify-content: space-between;
+  font-size: .6875rem;
+  display: flex;
+}
+
+:is(.readout-L9jEpz, .byline-analytics-readout) {
+  font-variant-numeric: tabular-nums;
+  min-height: 1.25rem;
+  color: var(--gray-500);
+  flex-wrap: wrap;
+  align-items: center;
+  gap: .35rem .75rem;
+  margin: 0;
+  font-size: .75rem;
+  display: flex;
+}
+
+.readout-L9jEpz strong {
+  color: inherit;
+  font-weight: 600;
+}
+
+.swatchViews-OCeKNe, .swatchVisitors-O3BWz6, .swatchDownloads-SVo9mN {
+  border-radius: 1px;
+  width: .5rem;
+  height: .5rem;
+  margin-inline: .4rem -.4rem;
+  display: inline-block;
+}
+
+.swatchViews-OCeKNe {
+  opacity: .55;
+  background-color: #38bdf8;
+}
+
+.swatchVisitors-O3BWz6 {
+  background-color: #7c3aed;
+}
+
+.swatchDownloads-SVo9mN {
+  background-color: #10b981;
+}
+
+:is([data-theme="dark"], .dark) .gridline-R_wAwP {
+  stroke: var(--gray-700);
+}
+
+:is(:is([data-theme="dark"], .dark) .axis-fBshTw, :is([data-theme="dark"], .dark) .byline-analytics-axis, :is([data-theme="dark"], .dark) .readout-L9jEpz, :is([data-theme="dark"], .dark) .byline-analytics-readout) {
+  color: var(--gray-400);
+}
+
+:is([data-theme="dark"], .dark) .visitors-n6IL4B {
+  fill: #a78bfa;
+}
+
+:is([data-theme="dark"], .dark) .swatchVisitors-O3BWz6 {
+  background-color: #a78bfa;
+}
+
+:is([data-theme="dark"], .dark) .swatchDownloads-SVo9mN {
+  background-color: #34d399;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .column-_Cw2Ua, .views-WHbm44 {
+    transition: none;
+  }
+}
+
+@media (max-width: 720px) {
+  :is(.chart-giYTrx, .byline-analytics-chart) {
+    height: 9rem;
+  }
+}
+

package/dist/modules/analytics/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export { ANALYTICS_ABILITIES, type AnalyticsAbilityKey, registerAnalyticsAbilities, } from './abilities.js';
+export type { AnalyticsDashboardData, AnalyticsDashboardPeriod } from './types.js';

package/dist/modules/analytics/index.js

@@ -0,0 +1 @@
+export { ANALYTICS_ABILITIES, registerAnalyticsAbilities } from "./abilities.js";

package/dist/modules/analytics/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { AnalyticsCountryTotal, AnalyticsDateRange, AnalyticsPathTotal, AnalyticsRankedTotals, AnalyticsReferrerTotal, AnalyticsReportCoverage, AnalyticsSummary } from '@byline/analytics';
+import type { AnalyticsDashboardPeriod as PortableAnalyticsDashboardPeriod } from '@byline/analytics/config';
+export type AnalyticsDashboardPeriod = PortableAnalyticsDashboardPeriod;
+export interface AnalyticsDashboardData {
+    range: AnalyticsDateRange;
+    coverage: AnalyticsReportCoverage;
+    summary: AnalyticsSummary;
+    pages: AnalyticsRankedTotals<AnalyticsPathTotal>;
+    downloads: AnalyticsRankedTotals<AnalyticsPathTotal>;
+    referrers: AnalyticsRankedTotals<AnalyticsReferrerTotal>;
+    /** Countries are unbounded by a top-N limit, so there is nothing to truncate. */
+    countries: AnalyticsCountryTotal[];
+}

package/dist/modules/analytics/types.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -77,6 +77,16 @@
       "import": "./dist/modules/admin-preferences/index.js",
       "require": "./dist/modules/admin-preferences/index.js"
     },
+    "./analytics": {
+      "types": "./dist/modules/analytics/index.d.ts",
+      "import": "./dist/modules/analytics/index.js",
+      "require": "./dist/modules/analytics/index.js"
+    },
+    "./analytics/components/dashboard": {
+      "types": "./dist/modules/analytics/components/dashboard.d.ts",
+      "import": "./dist/modules/analytics/components/dashboard.js",
+      "require": "./dist/modules/analytics/components/dashboard.js"
+    },
     "./services": {
       "types": "./dist/services/admin-services-context.d.ts",
       "import": "./dist/services/admin-services-context.js",
@@ -169,32 +179,32 @@
     "@lezer/highlight": "^1.2.3",
     "@tanstack/react-form-start": "^1.33.5",
     "clsx": "^2.1.1",
-    "jose": "^6.2.9",
+    "jose": "^6.2.10",
     "react-diff-viewer-continued": "^4.4.0",
     "uuid": "^14.0.2",
     "zod": "^4.4.3",
-    "@byline/auth": "4.15.0",
-    "@byline/core": "4.15.0",
-    "@byline/ui": "4.15.0",
-    "@byline/i18n": "4.15.0"
+    "@byline/auth": "4.17.0",
+    "@byline/i18n": "4.17.0",
+    "@byline/analytics": "4.17.0",
+    "@byline/analytics-agent": "4.17.0",
+    "@byline/core": "4.17.0",
+    "@byline/ui": "4.17.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.9",
+    "@biomejs/biome": "2.5.10",
     "@rsbuild/plugin-react": "^2.1.0",
     "@rslib/core": "^0.23.2",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.4",
+    "@types/react-dom": "19.2.5",
     "@vitejs/plugin-react": "^6.1.0",
     "jsdom": "^30.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "rimraf": "^6.1.3",
-    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "typescript-plugin-css-modules": "^5.2.0",
     "vitest": "^4.1.11"

package/src/abilities.ts

@@ -12,6 +12,7 @@ import { registerAdminActivityAbilities } from './modules/admin-activity/abiliti
 import { registerAdminPermissionsAbilities } from './modules/admin-permissions/abilities.js'
 import { registerAdminRolesAbilities } from './modules/admin-roles/abilities.js'
 import { registerAdminUsersAbilities } from './modules/admin-users/abilities.js'
+import { registerAnalyticsAbilities } from './modules/analytics/abilities.js'
 
 /**
  * Register every ability contributed by the admin subsystem.
@@ -30,5 +31,6 @@ export function registerAdminAbilities(registry: AbilityRegistry): void {
   registerAdminRolesAbilities(registry)
   registerAdminPermissionsAbilities(registry)
   registerAdminActivityAbilities(registry)
+  registerAnalyticsAbilities(registry)
   // registerAccountAbilities(registry) — added when that module lands
 }

package/src/fields/relation/relation-field.tsx

@@ -10,11 +10,11 @@ import { useState } from 'react'
 
 import type {
   CollectionAdminConfig,
-  CollectionDefinition,
   RelationField as FieldType,
+  MultiCollectionDefinition,
   RelatedDocumentValue,
 } from '@byline/core'
-import { getCollectionAdminConfig, getCollectionDefinition } from '@byline/core'
+import { getCollectionAdminConfig, getCollectionDefinition, isSingleton } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import {
   Button,
@@ -80,7 +80,9 @@ export const RelationField = ({
   // config drives the picker-column rendering inside RelationSummary so
   // the selected tile matches the picker row exactly. Missing target →
   // render an inline error and disable the picker.
-  const targetDef: CollectionDefinition | null = getCollectionDefinition(field.targetCollection)
+  const targetDefinition = getCollectionDefinition(field.targetCollection)
+  const targetDef: MultiCollectionDefinition | null =
+    targetDefinition != null && !isSingleton(targetDefinition) ? targetDefinition : null
   const targetAdminConfig: CollectionAdminConfig | null = getCollectionAdminConfig(
     field.targetCollection
   )

package/src/fields/relation/relation-many-field.tsx

@@ -10,11 +10,11 @@ import { type ReactNode, useState } from 'react'
 
 import type {
   CollectionAdminConfig,
-  CollectionDefinition,
   RelationField as FieldType,
+  MultiCollectionDefinition,
   RelatedDocumentValue,
 } from '@byline/core'
-import { getCollectionAdminConfig, getCollectionDefinition } from '@byline/core'
+import { getCollectionAdminConfig, getCollectionDefinition, isSingleton } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import {
   Button,
@@ -122,7 +122,9 @@ export const RelationManyField = ({ field, defaultValue, id, path }: RelationMan
   const fieldError = useFieldError(fieldPath)
   const { getFieldValue, setFieldValue } = useFormContext()
 
-  const targetDef: CollectionDefinition | null = getCollectionDefinition(field.targetCollection)
+  const targetDefinition = getCollectionDefinition(field.targetCollection)
+  const targetDef: MultiCollectionDefinition | null =
+    targetDefinition != null && !isSingleton(targetDefinition) ? targetDefinition : null
   const targetAdminConfig: CollectionAdminConfig | null = getCollectionAdminConfig(
     field.targetCollection
   )

package/src/fields/relation/relation-picker.tsx

@@ -8,7 +8,7 @@
 
 import { useCallback, useEffect, useState } from 'react'
 
-import type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import type { CollectionAdminConfig, MultiCollectionDefinition } from '@byline/core'
 import { getCollectionAdminConfig } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { Button, CheckIcon, LoaderRing, Modal, Search } from '@byline/ui/react'
@@ -57,7 +57,7 @@ interface RelationPickerBaseProps {
   /** The target collection path (e.g. `'media'`). */
   targetCollectionPath: string
   /** The target collection definition (used for labels + displayField fallback). */
-  targetDefinition?: CollectionDefinition | null
+  targetDefinition?: MultiCollectionDefinition | null
   /** Explicit display field to render as row label. */
   displayField?: string
   /**

package/src/fields/relation/relation-summary.tsx

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import type { CollectionAdminConfig, MultiCollectionDefinition } from '@byline/core'
 import cx from 'clsx'
 
 import { PickerCell, resolveFallbackDisplayField, resolveRowLabel } from './relation-display'
@@ -34,7 +34,7 @@ import styles from './relation-summary.module.css'
 // ---------------------------------------------------------------------------
 
 interface RelationSummaryProps {
-  targetDefinition: CollectionDefinition
+  targetDefinition: MultiCollectionDefinition
   targetAdminConfig: CollectionAdminConfig | null
   displayField?: string
   /** The raw relation value from the form. May be a plain ref or a populated envelope. */