@chelone/core 0.5.0 → 0.6.0

package/dist/controller/record-timeline.js

@@ -0,0 +1,36 @@
+import { getAtPath } from "../resource/get-at-path.js";
+import { parseCalendarDate } from "./calendar-dates.js";
+function toTimelineEntries(records, options) {
+  const { messageSource, timestampSource, userSource, iconSource } = options;
+  return records.map((record) => {
+    const message = getAtPath(record, messageSource);
+    const user = userSource === void 0 ? void 0 : getAtPath(record, userSource);
+    const icon = iconSource === void 0 ? void 0 : getAtPath(record, iconSource);
+    return {
+      id: record.id,
+      record,
+      message: message == null ? "" : String(message),
+      date: parseCalendarDate(getAtPath(record, timestampSource)),
+      user: user == null || user === "" ? void 0 : String(user),
+      icon: icon == null || icon === "" ? void 0 : String(icon)
+    };
+  });
+}
+const MINUTE = 60;
+const HOUR = 3600;
+const DAY = 86400;
+const MONTH = DAY * 30;
+function formatRelativeTime(date, now, locale) {
+  const delta = (date.getTime() - now.getTime()) / 1e3;
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+  const distance = Math.abs(delta);
+  if (distance < MINUTE) return rtf.format(Math.round(delta), "second");
+  if (distance < HOUR) return rtf.format(Math.round(delta / MINUTE), "minute");
+  if (distance < DAY) return rtf.format(Math.round(delta / HOUR), "hour");
+  if (distance < MONTH) return rtf.format(Math.round(delta / DAY), "day");
+  return rtf.format(Math.round(delta / MONTH), "month");
+}
+export {
+  formatRelativeTime,
+  toTimelineEntries
+};

package/dist/data/cache-ops.js

@@ -6,9 +6,7 @@ function singleResultListKeyPrefixes(resource) {
   ];
 }
 function withoutIds(page, idSet) {
-  const kept = page.data.filter(
-    (record) => !idSet.has(String(record.id))
-  );
+  const kept = page.data.filter((record) => !idSet.has(String(record.id)));
   return kept.length === page.data.length ? void 0 : { ...page, data: kept };
 }
 function withPatchedRows(page, idSet, data) {

package/dist/form/edit-create-form.js

@@ -132,17 +132,17 @@ function createEditFormController(ctx, resource, options) {
       return;
     }
     if (action === "partial-apply") {
-      const pathAccess = form;
-      const fieldMeta = form.state.fieldMeta;
       const dirtyValues = [];
-      for (const [path, meta] of Object.entries(fieldMeta)) {
-        if (meta.isDirty) {
-          dirtyValues.push([path, pathAccess.getFieldValue(path)]);
-        }
+      for (const [path, meta] of Object.entries(
+        form.state.fieldMeta
+      )) {
+        if (!meta?.isDirty) continue;
+        const name = path;
+        dirtyValues.push([name, form.getFieldValue(name)]);
       }
       form.reset(merged);
       for (const [path, value] of dirtyValues) {
-        pathAccess.setFieldValue(path, value, { dontRunListeners: true });
+        form.setFieldValue(path, value, { dontRunListeners: true });
       }
       return;
     }

package/dist/i18n/i18n.d.ts

@@ -38,5 +38,11 @@ export declare function createI18n<const TCatalog extends MessageCatalog>(option
     locale: string;
     messages: Record<string, TCatalog>;
     fallbackLocale?: string;
+    /**
+     * Called when the current locale's catalog holds no own entry for a key,
+     * even when `fallbackLocale` supplies the text. `fallback` is the string `_`
+     * param. A throwing callback goes to `console.error`; `translate` is unchanged.
+     */
+    onMissingKey?: (key: string, locale: string, fallback: string | undefined) => void;
 }): CheloneI18n<TCatalog>;
 export {};

package/dist/i18n/i18n.js

@@ -26,7 +26,19 @@ function createI18n(options) {
   return {
     translate(key, ...args) {
       const params = args[0];
-      const value = lookup(options.messages[locale], key) ?? (options.fallbackLocale ? lookup(options.messages[options.fallbackLocale], key) : void 0);
+      const own = lookup(options.messages[locale], key);
+      if (own === void 0 && options.onMissingKey) {
+        try {
+          options.onMissingKey(
+            key,
+            locale,
+            typeof params?._ === "string" ? params._ : void 0
+          );
+        } catch (error) {
+          console.error(error);
+        }
+      }
+      const value = own ?? (options.fallbackLocale ? lookup(options.messages[options.fallbackLocale], key) : void 0);
       if (value === void 0) {
         if (typeof params?._ === "string") return interpolate(params._, params);
         return key;

package/dist/i18n/missing-keys.d.ts

@@ -0,0 +1,19 @@
+export interface MissingKeyEntry {
+    key: string;
+    fallback: string | undefined;
+    translation: string;
+}
+export interface MissingKeyStore {
+    /** Has the `onMissingKey` signature: pass it as `onMissingKey: store.record`. */
+    record(key: string, locale: string, fallback: string | undefined): void;
+    /** The same array until that locale's entries change. */
+    getEntries(locale: string): readonly MissingKeyEntry[];
+    /** Ignores a key that was not recorded. */
+    setTranslation(locale: string, key: string, text: string): void;
+    clear(locale: string): void;
+    /** Flat `{ key: text }` JSON, two-space indented, non-blank translations only. */
+    toJson(locale: string): string;
+    /** Notified once per microtask, however many entries changed. */
+    subscribe(callback: () => void): () => void;
+}
+export declare function createMissingKeyStore(): MissingKeyStore;

package/dist/i18n/missing-keys.js

@@ -0,0 +1,64 @@
+const NO_ENTRIES = [];
+function createMissingKeyStore() {
+  const byLocale = /* @__PURE__ */ new Map();
+  const snapshots = /* @__PURE__ */ new Map();
+  const subscribers = /* @__PURE__ */ new Set();
+  let scheduled = false;
+  const changed = (locale) => {
+    snapshots.delete(locale);
+    if (scheduled) return;
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      for (const cb of [...subscribers]) cb();
+    });
+  };
+  const getEntries = (locale) => {
+    const cached = snapshots.get(locale);
+    if (cached) return cached;
+    const entries = byLocale.get(locale);
+    if (!entries?.size) return NO_ENTRIES;
+    const snapshot = [...entries.values()];
+    snapshots.set(locale, snapshot);
+    return snapshot;
+  };
+  return {
+    record(key, locale, fallback) {
+      let entries = byLocale.get(locale);
+      if (!entries) {
+        entries = /* @__PURE__ */ new Map();
+        byLocale.set(locale, entries);
+      }
+      if (entries.has(key)) return;
+      entries.set(key, { key, fallback, translation: "" });
+      changed(locale);
+    },
+    getEntries,
+    setTranslation(locale, key, text) {
+      const entries = byLocale.get(locale);
+      const entry = entries?.get(key);
+      if (!entries || !entry || entry.translation === text) return;
+      entries.set(key, { ...entry, translation: text });
+      changed(locale);
+    },
+    clear(locale) {
+      if (!byLocale.get(locale)?.size) return;
+      byLocale.delete(locale);
+      changed(locale);
+    },
+    toJson(locale) {
+      const out = /* @__PURE__ */ new Map();
+      for (const { key, translation } of getEntries(locale)) {
+        if (translation.trim() !== "") out.set(key, translation);
+      }
+      return JSON.stringify(Object.fromEntries(out), null, 2);
+    },
+    subscribe(callback) {
+      subscribers.add(callback);
+      return () => void subscribers.delete(callback);
+    }
+  };
+}
+export {
+  createMissingKeyStore
+};

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 export { revalidateLogic } from "@tanstack/form-core";
+export type { AssistantSession, AssistantSessionState, CreateAssistantSessionOptions, } from "./assistant/assistant-session.js";
+export { createAssistantSession } from "./assistant/assistant-session.js";
+export type { EchoAssistantTransportOptions } from "./assistant/echo-transport.js";
+export { echoAssistantTransport } from "./assistant/echo-transport.js";
+export type { AssistantChunk, AssistantMessage, AssistantTool, AssistantToolCall, AssistantToolDeclaration, AssistantTransport, JsonObject, JsonValue, } from "./assistant/types.js";
 export type { Permission } from "./auth/access-control.js";
 export { canAccessWithPermissions } from "./auth/access-control.js";
 export type { CheckErrorOutcome } from "./auth/auth-options.js";
 export { authStateQueryOptions, canAccessQueryOptions, checkError, identityQueryOptions, permissionsQueryOptions, } from "./auth/auth-options.js";
 export type { AuthProvider, CanAccessParams, UserIdentity } from "./auth/types.js";
+export type { CartesianRow, DonutSlice, MetricDelta, } from "./chart/chart-data.js";
+export { chartColor, DEFAULT_CHART_COLORS, getMetricDelta, hasChartValues, toCartesianRows, toDonutSlices, } from "./chart/chart-data.js";
 export type { HotkeyEvent, HotkeyTarget } from "./command-menu/hotkey.js";
 export { isTypingTarget, matchesHotkey, shouldHandleHotkey, } from "./command-menu/hotkey.js";
 export type { RecentEntry } from "./command-menu/recents.js";
@@ -21,16 +28,22 @@ export { arrangeColumns, columnLabelMatches, dataTableColumnKeys, defaultDataTab
 export { isFilterSelected, toggleFilterValue, } from "./controller/filter-toggle.js";
 export type { InfiniteListController, InfiniteListControllerState, } from "./controller/infinite-list-controller.js";
 export { createInfiniteListController } from "./controller/infinite-list-controller.js";
+export type { JobActionOptions, JobActions, JobPlan, } from "./controller/job-monitor.js";
+export { DEFAULT_JOB_TABS, getJobActions, planJobCancel, planJobRetry, } from "./controller/job-monitor.js";
 export type { KanbanBucket, KanbanColumnDef, KanbanMove, } from "./controller/kanban-board.js";
 export { buildKanbanBuckets, planKanbanMove, } from "./controller/kanban-board.js";
 export type { ListController, ListControllerContext, ListControllerOptions, ListControllerState, ListParamsPatch, } from "./controller/list-controller.js";
 export { createListController, listControllerActions, } from "./controller/list-controller.js";
 export type { ListParamsQuery, ListUrlState, } from "./controller/list-params.js";
 export { hasCustomParams, listPatchFromSearch, parseListParams, serializeListParams, serializeListState, } from "./controller/list-params.js";
+export type { PivotAggregator, PivotOptions, PivotTable, } from "./controller/pivot-grid.js";
+export { buildPivotTable, formatPivotValue, } from "./controller/pivot-grid.js";
 export type { PrevNextOptions, PrevNextPage, PrevNextParams, PrevNextResolution, PrevNextStoredParams, } from "./controller/prev-next.js";
 export { canUseCachedPage, getPrevNextParams, resolvePrevNext, } from "./controller/prev-next.js";
 export type { CreateController, CreateControllerOptions, CreateControllerState, DeleteController, DeleteControllerOptions, DeleteControllerState, DeleteOneOptions, EditController, EditControllerOptions, EditControllerState, RecordControllerContext, RedirectRequest, RedirectTarget, SaveOptions, SaveTransform, ShowController, ShowControllerOptions, ShowControllerState, } from "./controller/record-controllers.js";
 export { createCreateController, createDeleteController, createEditController, createShowController, } from "./controller/record-controllers.js";
+export type { RecordTimelineEntry, ToTimelineEntriesOptions, } from "./controller/record-timeline.js";
+export { formatRelativeTime, toTimelineEntries, } from "./controller/record-timeline.js";
 export type { RecordTreeNode } from "./controller/record-tree.js";
 export { buildRecordTree } from "./controller/record-tree.js";
 export type { AllowedTransitions, ApprovalOptions, ApprovalState, TransitionOptions, } from "./controller/record-workflow.js";
@@ -125,13 +138,22 @@ export type { AnyCheloneI18n, CheloneI18n } from "./i18n/i18n.js";
 export { createI18n } from "./i18n/i18n.js";
 export type { ExtractParams, MessageCatalog, MessageKey, MessageValue, PluralMessage, TranslateParams, } from "./i18n/messages.js";
 export { defineMessages } from "./i18n/messages.js";
+export type { MissingKeyEntry, MissingKeyStore, } from "./i18n/missing-keys.js";
+export { createMissingKeyStore } from "./i18n/missing-keys.js";
 export type { TranslatableController, TranslatableOptions, TranslatableState, } from "./i18n/translatable.js";
 export { createTranslatableController, getRecordForLocale, } from "./i18n/translatable.js";
 export { stripJsonComments } from "./json/strip-json-comments.js";
 export type { Notification, NotificationStore, NotifyOptions, } from "./notification/notification-store.js";
 export { createNotificationStore } from "./notification/notification-store.js";
+export type { PlaceTourCardOptions, TourCardPosition, TourPlacement, TourRect, } from "./onboarding-tour/placement.js";
+export { placeTourCard, tourSpotlightPath, } from "./onboarding-tour/placement.js";
+export type { TourController, TourControllerOptions, TourEnd, TourState, } from "./onboarding-tour/tour-controller.js";
+export { createTourController, onboardingTourKey, } from "./onboarding-tour/tour-controller.js";
 export type { AddEventsForMutationsOptions } from "./realtime/add-events-for-mutations.js";
 export { addEventsForMutations } from "./realtime/add-events-for-mutations.js";
+export { announceLock } from "./realtime/announce-lock.js";
+export type { BroadcastChannelTransport, BroadcastChannelTransportOptions, } from "./realtime/broadcast-channel-transport.js";
+export { broadcastChannelTransport } from "./realtime/broadcast-channel-transport.js";
 export type { InMemoryLockProviderOptions } from "./realtime/in-memory-lock-provider.js";
 export { inMemoryLockProvider } from "./realtime/in-memory-lock-provider.js";
 export type { LiveOptions, LiveSubscription } from "./realtime/live.js";
@@ -144,8 +166,11 @@ export { memoryTransport } from "./realtime/memory-transport.js";
 export type { PresenceSession, PresenceSessionDataProvider, PresenceSessionOptions, PresenceSessionState, PresenceUser, } from "./realtime/presence.js";
 export { createPresenceSession, getPresenceInitials, toPresenceUser, } from "./realtime/presence.js";
 export { assertRealtimeDataProvider, isRealtimeDataProvider, realtimeDataProvider, } from "./realtime/realtime-data-provider.js";
+export type { RealtimeReconnectConfig } from "./realtime/reconnect-backoff.js";
 export type { RealtimeStatusState } from "./realtime/status-store.js";
 export { createRealtimeStatusStore } from "./realtime/status-store.js";
+export type { TopicHub } from "./realtime/topic-hub.js";
+export { createTopicHub } from "./realtime/topic-hub.js";
 export { lockResourceTopic, lockTopic, presenceTopic, recordTopic, resourceTopic, } from "./realtime/topics.js";
 export type { GetLockParams, GetLocksParams, Lock, LockParams, LockProvider, RealtimeConnectionStatus, RealtimeDataProvider, RealtimeDataProviderOptions, RealtimeEvent, RealtimeEventType, RealtimeTransport, RealtimeTransportError, RealtimeTransportErrorKind, SubscriptionCallback, UnlockParams, } from "./realtime/types.js";
 export { LockConflictError } from "./realtime/types.js";
@@ -162,6 +187,8 @@ export { defineResources } from "./resource/registry.js";
 export type { ComputeDefinitionProps, ResourceDefinition, ResourceDefinitionMap, ResourceRegistry, ResourceRegistryListener, } from "./resource/registry-store.js";
 export { computeDefinition, createResourceRegistry, } from "./resource/registry-store.js";
 export type { AnySourcePath, AnySourcePathOf, FilterSourceKey, RowSourcePath, SourceKey, SourcePath, SourceProp, SourceValue, } from "./resource/source-path.js";
+export type { IsSafeImageSrcOptions, RichTextBlockType, RichTextHeadingLevel, RichTextToolbarGroup, RichTextToolbarItem, RichTextToolbarItemId, } from "./rich-text/rich-text.js";
+export { isSafeImageSrc, isSafeLinkUrl, richTextBlockTypes, richTextSanitizeOptions, richTextStarterKitOptions, richTextToolbarItems, } from "./rich-text/rich-text.js";
 export type { CheloneLocation, NavigateOpts } from "./router/location.js";
 export { parseLocation } from "./router/location.js";
 export type { PathMatch } from "./router/match.js";

package/dist/index.js

@@ -1,6 +1,9 @@
 import { revalidateLogic } from "@tanstack/form-core";
+import { createAssistantSession } from "./assistant/assistant-session.js";
+import { echoAssistantTransport } from "./assistant/echo-transport.js";
 import { canAccessWithPermissions } from "./auth/access-control.js";
 import { authStateQueryOptions, canAccessQueryOptions, checkError, identityQueryOptions, permissionsQueryOptions } from "./auth/auth-options.js";
+import { DEFAULT_CHART_COLORS, chartColor, getMetricDelta, hasChartValues, toCartesianRows, toDonutSlices } from "./chart/chart-data.js";
 import { isTypingTarget, matchesHotkey, shouldHandleHotkey } from "./command-menu/hotkey.js";
 import { recentsKey, rememberRecent } from "./command-menu/recents.js";
 import { createCommandRegistry, getVisibleCommands, groupCommands } from "./command-menu/registry.js";
@@ -10,11 +13,14 @@ import { createClientListController } from "./controller/client-list-controller.
 import { arrangeColumns, columnLabelMatches, dataTableColumnKeys, defaultDataTableStoreKey, getDataTableColumnId, moveColumn, toggleHiddenColumn } from "./controller/data-table-columns.js";
 import { isFilterSelected, toggleFilterValue } from "./controller/filter-toggle.js";
 import { createInfiniteListController } from "./controller/infinite-list-controller.js";
+import { DEFAULT_JOB_TABS, getJobActions, planJobCancel, planJobRetry } from "./controller/job-monitor.js";
 import { buildKanbanBuckets, planKanbanMove } from "./controller/kanban-board.js";
 import { createListController, listControllerActions } from "./controller/list-controller.js";
 import { hasCustomParams, listPatchFromSearch, parseListParams, serializeListParams, serializeListState } from "./controller/list-params.js";
+import { buildPivotTable, formatPivotValue } from "./controller/pivot-grid.js";
 import { canUseCachedPage, getPrevNextParams, resolvePrevNext } from "./controller/prev-next.js";
 import { createCreateController, createDeleteController, createEditController, createShowController } from "./controller/record-controllers.js";
+import { formatRelativeTime, toTimelineEntries } from "./controller/record-timeline.js";
 import { buildRecordTree } from "./controller/record-tree.js";
 import { buildApprovalUpdate, getAllowedTransitions, getApprovalState } from "./controller/record-workflow.js";
 import { createReferenceManyController } from "./controller/reference-many-controller.js";
@@ -73,10 +79,15 @@ import { defaultMessages } from "./i18n/default-messages.js";
 import { englishMessages } from "./i18n/english-messages.js";
 import { createI18n } from "./i18n/i18n.js";
 import { defineMessages } from "./i18n/messages.js";
+import { createMissingKeyStore } from "./i18n/missing-keys.js";
 import { createTranslatableController, getRecordForLocale } from "./i18n/translatable.js";
 import { stripJsonComments } from "./json/strip-json-comments.js";
 import { createNotificationStore } from "./notification/notification-store.js";
+import { placeTourCard, tourSpotlightPath } from "./onboarding-tour/placement.js";
+import { createTourController, onboardingTourKey } from "./onboarding-tour/tour-controller.js";
 import { addEventsForMutations } from "./realtime/add-events-for-mutations.js";
+import { announceLock } from "./realtime/announce-lock.js";
+import { broadcastChannelTransport } from "./realtime/broadcast-channel-transport.js";
 import { inMemoryLockProvider } from "./realtime/in-memory-lock-provider.js";
 import { subscribeLiveLock, subscribeLiveLocks, subscribeLiveRecord, subscribeLiveRecords, subscribeLiveResource } from "./realtime/live.js";
 import { getLockOptions, getLocksOptions } from "./realtime/lock-options.js";
@@ -85,6 +96,7 @@ import { memoryTransport } from "./realtime/memory-transport.js";
 import { createPresenceSession, getPresenceInitials, toPresenceUser } from "./realtime/presence.js";
 import { assertRealtimeDataProvider, isRealtimeDataProvider, realtimeDataProvider } from "./realtime/realtime-data-provider.js";
 import { createRealtimeStatusStore } from "./realtime/status-store.js";
+import { createTopicHub } from "./realtime/topic-hub.js";
 import { lockResourceTopic, lockTopic, presenceTopic, recordTopic, resourceTopic } from "./realtime/topics.js";
 import { LockConflictError } from "./realtime/types.js";
 import { clearUnread, subscribeUnreadCount, unreadKey } from "./realtime/unread-count.js";
@@ -92,6 +104,7 @@ import { describeResource } from "./resource/describe-resource.js";
 import { getAtPath } from "./resource/get-at-path.js";
 import { defineResources } from "./resource/registry.js";
 import { computeDefinition, createResourceRegistry } from "./resource/registry-store.js";
+import { isSafeImageSrc, isSafeLinkUrl, richTextBlockTypes, richTextSanitizeOptions, richTextStarterKitOptions, richTextToolbarItems } from "./rich-text/rich-text.js";
 import { parseLocation } from "./router/location.js";
 import { matchPath } from "./router/match.js";
 import { createPath, joinBasename, removeDoubleSlashes } from "./router/paths.js";
@@ -100,6 +113,8 @@ import { localStorageAdapter, memoryStoreAdapter } from "./store/adapters.js";
 import { createMicroStore } from "./store/micro-store.js";
 import { createStore } from "./store/store.js";
 export {
+  DEFAULT_CHART_COLORS,
+  DEFAULT_JOB_TABS,
   DEFAULT_SHAPE_STYLE,
   HttpError,
   LockConflictError,
@@ -109,6 +124,7 @@ export {
   OverpassTimeoutError,
   ValidationError,
   addEventsForMutations,
+  announceLock,
   applyCsvMapping,
   areaInTypeOf,
   arrangeColumns,
@@ -117,9 +133,11 @@ export {
   assertRealtimeDataProvider,
   authStateQueryOptions,
   bboxToPolygon,
+  broadcastChannelTransport,
   buildApprovalUpdate,
   buildKanbanBuckets,
   buildOverpassQuery,
+  buildPivotTable,
   buildRecordTree,
   calendarDayKey,
   calendarDays,
@@ -131,6 +149,7 @@ export {
   canAccessQueryOptions,
   canAccessWithPermissions,
   canUseCachedPage,
+  chartColor,
   checkError,
   choices,
   clearUnread,
@@ -144,6 +163,7 @@ export {
   createApplicationUpdateStore,
   createArrayBinding,
   createArraySourceScope,
+  createAssistantSession,
   createChoicesController,
   createClientListController,
   createCommandRegistry,
@@ -162,6 +182,7 @@ export {
   createLocaleSourceScope,
   createLockSession,
   createMicroStore,
+  createMissingKeyStore,
   createMutationOptions,
   createNominatimProvider,
   createNotificationStore,
@@ -178,6 +199,8 @@ export {
   createSavedQueriesController,
   createShowController,
   createStore,
+  createTopicHub,
+  createTourController,
   createTranslatableController,
   csvErrorRows,
   csvSchemaFields,
@@ -193,6 +216,7 @@ export {
   describeResource,
   detectJsonShape,
   downloadCSV,
+  echoAssistantTransport,
   editorStyles,
   email,
   englishMessages,
@@ -204,6 +228,8 @@ export {
   filterFormReflectShape,
   findPresetForTags,
   formatJsonValue,
+  formatPivotValue,
+  formatRelativeTime,
   fromEditorFeatures,
   fromJsonText,
   geoAreaM2,
@@ -216,12 +242,14 @@ export {
   getDirtyFormValues,
   getFilterFormValues,
   getInfiniteListOptions,
+  getJobActions,
   getListOptions,
   getLockOptions,
   getLocksOptions,
   getManyAggregateOptions,
   getManyOptions,
   getManyReferenceOptions,
+  getMetricDelta,
   getOneOptions,
   getPresenceInitials,
   getPrevNextParams,
@@ -230,6 +258,7 @@ export {
   getVisibleCommands,
   groupCalendarAgenda,
   groupCommands,
+  hasChartValues,
   hasCustomParams,
   hasPendingUndoables,
   hasSelfIntersection,
@@ -247,6 +276,8 @@ export {
   isLngLatBox,
   isRealtimeDataProvider,
   isRequired,
+  isSafeImageSrc,
+  isSafeLinkUrl,
   isSavedQueryActive,
   isTypingTarget,
   joinBasename,
@@ -284,6 +315,7 @@ export {
   normalizeFormError,
   number,
   omitCalendarRangeFilter,
+  onboardingTourKey,
   oneKey,
   overpassQueryOptions,
   parseCalendarDate,
@@ -292,6 +324,9 @@ export {
   parseLocation,
   patchedRecord,
   permissionsQueryOptions,
+  placeTourCard,
+  planJobCancel,
+  planJobRetry,
   planKanbanMove,
   polygonToBBox,
   presenceTopic,
@@ -313,6 +348,10 @@ export {
   resourceTopic,
   revalidateLogic,
   reverseGeocodeQueryOptions,
+  richTextBlockTypes,
+  richTextSanitizeOptions,
+  richTextStarterKitOptions,
+  richTextToolbarItems,
   rootSourceScope,
   runCsvImport,
   savedQueriesKey,
@@ -333,12 +372,16 @@ export {
   subscribeUnreadCount,
   tagToFilter,
   toCalendarEvents,
+  toCartesianRows,
   toCoordinate,
+  toDonutSlices,
   toEditorFeatures,
   toJsonText,
   toPresenceUser,
+  toTimelineEntries,
   toggleFilterValue,
   toggleHiddenColumn,
+  tourSpotlightPath,
   undoableCallbacks,
   undoableDeleteOptions,
   undoableUpdateOptions,

package/dist/onboarding-tour/placement.d.ts

@@ -0,0 +1,34 @@
+/** A box in viewport pixels. The adapters measure it; core touches no DOM. */
+export interface TourRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export type TourPlacement = "auto" | "top" | "bottom" | "left" | "right";
+type Side = Exclude<TourPlacement, "auto">;
+export interface PlaceTourCardOptions {
+    /** `null` centres the card, for a step that points at nothing. */
+    target: TourRect | null;
+    card: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    placement: TourPlacement;
+    /** Gap between card and target, and the least distance to a viewport edge. */
+    margin?: number;
+}
+export interface TourCardPosition {
+    /** The card's top-left corner. */
+    top: number;
+    left: number;
+    side: Side;
+}
+export declare function placeTourCard({ target, card, viewport, placement, margin, }: PlaceTourCardOptions): TourCardPosition;
+/** A CSS `clip-path` that fills the page except the target's rect. */
+export declare function tourSpotlightPath(target: TourRect): string;
+export {};

package/dist/onboarding-tour/placement.js

@@ -0,0 +1,82 @@
+const SIDES = ["bottom", "top", "right", "left"];
+const OPPOSITE = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left"
+};
+function placeTourCard({
+  target,
+  card,
+  viewport,
+  placement,
+  margin = 12
+}) {
+  if (!target) {
+    return {
+      top: (viewport.height - card.height) / 2,
+      left: (viewport.width - card.width) / 2,
+      side: placement === "auto" ? "bottom" : placement
+    };
+  }
+  const room = {
+    top: target.top,
+    bottom: viewport.height - (target.top + target.height),
+    left: target.left,
+    right: viewport.width - (target.left + target.width)
+  };
+  const needed = (side2) => (side2 === "top" || side2 === "bottom" ? card.height : card.width) + margin * 2;
+  const fits = (side2) => room[side2] >= needed(side2);
+  let side;
+  if (placement === "auto") {
+    const roomiest = (candidates) => candidates.reduce(
+      (best, next) => room[next] > room[best] ? next : best
+    );
+    const fitting = SIDES.filter(fits);
+    side = roomiest(fitting.length > 0 ? fitting : SIDES);
+  } else {
+    side = !fits(placement) && fits(OPPOSITE[placement]) ? OPPOSITE[placement] : placement;
+  }
+  const centreX = target.left + target.width / 2 - card.width / 2;
+  const centreY = target.top + target.height / 2 - card.height / 2;
+  let top;
+  let left;
+  switch (side) {
+    case "bottom":
+      top = target.top + target.height + margin;
+      left = centreX;
+      break;
+    case "top":
+      top = target.top - margin - card.height;
+      left = centreX;
+      break;
+    case "right":
+      top = centreY;
+      left = target.left + target.width + margin;
+      break;
+    case "left":
+      top = centreY;
+      left = target.left - margin - card.width;
+      break;
+  }
+  return {
+    top: Math.max(
+      margin,
+      Math.min(top, viewport.height - card.height - margin)
+    ),
+    left: Math.max(
+      margin,
+      Math.min(left, viewport.width - card.width - margin)
+    ),
+    side
+  };
+}
+function tourSpotlightPath(target) {
+  const right = target.left + target.width;
+  const bottom = target.top + target.height;
+  return `polygon(0% 0%, 0% 100%, ${target.left}px 100%, ${target.left}px ${target.top}px, ${right}px ${target.top}px, ${right}px ${bottom}px, ${target.left}px ${bottom}px, ${target.left}px 100%, 100% 100%, 100% 0%)`;
+}
+export {
+  placeTourCard,
+  tourSpotlightPath
+};

package/dist/onboarding-tour/tour-controller.d.ts

@@ -0,0 +1,25 @@
+import { type MicroStore } from "../store/micro-store.js";
+import type { CheloneStore } from "../store/store.js";
+/** Where the onboarding tour keeps its done flag in a `CheloneStore`. */
+export declare function onboardingTourKey(id: string): string;
+export interface TourState {
+    active: boolean;
+    index: number;
+}
+export type TourEnd = "finished" | "skipped";
+export interface TourControllerOptions {
+    id: string;
+    stepCount: number;
+    store: CheloneStore;
+    /** Open on the first subscribe while the done flag is not `true`. */
+    autoStart?: boolean;
+    onComplete?: (reason: TourEnd) => void;
+}
+export interface TourController extends MicroStore<TourState> {
+    start(): void;
+    next(): void;
+    back(): void;
+    skip(): void;
+    finish(): void;
+}
+export declare function createTourController({ id, stepCount, store, autoStart, onComplete, }: TourControllerOptions): TourController;