@antelopejs/dms 0.6.1 → 0.7.0

package/frontend-vue/layers/dms-layout/app/composables/notification/useNotifications.ts

@@ -1,4 +1,5 @@
 import { NotificationEvents } from "./types/events";
+import { unreadToneWith } from "../../build/components/pages/settings/notification/notificationDisplay";
 
 /** Icon well colour a sender may set on a notification. */
 export type NotificationTone =
@@ -25,13 +26,14 @@ export interface UserNotification {
 }
 
 /**
- * The whole feed's totals, with what the header bell counts: the unread
- * notifications that arrived since it was last opened.
+ * The whole feed's totals, with the tone of the unread badge (the header
+ * bell, the Notifications entry): the most important unread notification's,
+ * which the server weighs as the inbox draws it.
  */
 interface FeedCounts {
   all: number;
   unread: number;
-  unseen?: number;
+  unreadTone?: NotificationTone;
 }
 
 const API_BASE = "/settings/user/notifications";
@@ -42,17 +44,14 @@ const buildListUrl = (offset: number) =>
   `${API_BASE}/list?limit=${NOTIFICATIONS_PAGE_SIZE}&offset=${offset}`;
 
 /**
- * Shared notification state of the header bell (unseen count, popover feed)
- * and of the settings navigation (unread count); the settings inbox is a
+ * Shared notification state of the header bell (unread count and tone,
+ * popover feed) and of the settings navigation; the settings inbox is a
  * table view of its own (`dms:inbox`), which lists the feed again when these
  * counts change.
  *
- * Seen and read are two states. The bell's badge (`unseenCount`) counts the
- * unread notifications that arrived since the bell last opened, and opening
- * it resets the badge (`markAllSeen`). A notification becomes read only when
- * it is opened or marked read; `unreadCount` (the whole feed's unread total)
- * feeds the Notifications entry of the settings navigation and its overview
- * card.
+ * The bell and the Notifications entry show the same badge: `unreadCount`,
+ * the whole feed's unread total, in `unreadTone`. Opening the bell changes
+ * neither; a notification leaves the count once opened or marked read.
  */
 export const useNotifications = () => {
   const { $authFetch } = useAuthFetch();
@@ -61,9 +60,9 @@ export const useNotifications = () => {
     "notifications-unread-count",
     () => 0,
   );
-  const unseenCount = useDmsState<number>(
-    "notifications-unseen-count",
-    () => 0,
+  const unreadTone = useDmsState<NotificationTone | undefined>(
+    "notifications-unread-tone",
+    () => undefined,
   );
   // Whether the counts have been asked once, answered or not: until then,
   // a 0 unread is not known to be true.
@@ -125,13 +124,13 @@ export const useNotifications = () => {
     );
   };
 
-  /** Takes the whole feed's unread and unseen totals. */
+  /** Takes the whole feed's unread total and its tone. */
   const applyFeedCounts = (counts: FeedCounts) => {
     unreadCount.value = counts.unread;
-    if (typeof counts.unseen === "number") unseenCount.value = counts.unseen;
+    unreadTone.value = counts.unread > 0 ? counts.unreadTone : undefined;
   };
 
-  /** Loads the bell's unseen count and the whole feed's unread count. */
+  /** Loads the whole feed's unread count and tone, the bell's badge. */
   const fetchBellCounts = async () => {
     try {
       const counts = await $authFetch<FeedCounts>(`${API_BASE}/counts`);
@@ -141,15 +140,6 @@ export const useNotifications = () => {
     }
   };
 
-  /**
-   * The bell was opened: its badge resets, and counts again what arrives
-   * later. The notifications stay unread.
-   */
-  const markAllSeen = async () => {
-    unseenCount.value = 0;
-    await $authFetch(`${API_BASE}/seen`, { method: "PUT" });
-  };
-
   const fetchUnreadPreview = async () => {
     const data = await $authFetch<UserNotification[]>(
       `${API_BASE}/unread-preview`,
@@ -231,14 +221,10 @@ export const useNotifications = () => {
     emitCount();
   };
 
-  /** The bell was opened in another tab: this one's badge resets too. */
-  const handleRemoteSeen = () => {
-    unseenCount.value = 0;
-  };
-
   /**
-   * A notification pushed in real time: the bell counts it as new (unseen)
-   * and unread, and lists it first.
+   * A notification pushed in real time: listed first, counted unread, and its
+   * tone weighed into the badge's here, without asking the server again — a
+   * broadcast would otherwise have every open tab fetch the counts at once.
    */
   const handleIncomingNotification = (incoming: UserNotification) => {
     const isAlreadyKnown = notifications.value.some(
@@ -247,10 +233,8 @@ export const useNotifications = () => {
     if (isAlreadyKnown) return;
     notifications.value = [incoming, ...notifications.value];
     unreadPreview.value = [incoming, ...unreadPreview.value];
-    if (!incoming.isRead) {
-      unreadCount.value += 1;
-      unseenCount.value += 1;
-    }
+    if (!incoming.isRead) unreadCount.value += 1;
+    unreadTone.value = unreadToneWith(unreadTone.value, incoming);
     sendComponentEvent(
       NotificationEvents.NOTIFICATION_RECEIVED,
       NOTIFICATION_COMPONENT_ID,
@@ -261,7 +245,7 @@ export const useNotifications = () => {
 
   return {
     unreadCount,
-    unseenCount,
+    unreadTone,
     areCountsLoaded,
     unreadPreview,
     notifications,
@@ -271,12 +255,10 @@ export const useNotifications = () => {
     fetchNotifications,
     markAsRead,
     markAsUnread,
-    markAllSeen,
     deleteNotification,
     handleIncomingNotification,
     handleRemoteRead,
     handleRemoteUnread,
     handleRemoteAllRead,
-    handleRemoteSeen,
   };
 };

package/frontend-vue/layers/dms-layout/app/composables/useAppSidePanels.ts

@@ -0,0 +1,96 @@
+/**
+ * A panel docked on the right of the dashboard. Unlike a free overlay (see
+ * {@link useAppOverlay}), the DMS owns the placement and the state: from `lg`
+ * the panel sits next to the page, which shrinks to make room, behind a resize
+ * handle; below `lg` it slides over the page as a sheet above a backdrop. The
+ * module only declares its component; it opens and closes the panel through
+ * {@link useSidePanel}.
+ *
+ * A registration is plain data, so it may run from a universal plugin: the
+ * server renders an open panel in place, and a reload shows it without the
+ * page jumping.
+ */
+export interface SidePanel {
+  /** Unique key: dedup on `register` (upsert), target of `unregister`, and the id `useSidePanel` opens. */
+  id: string;
+  /**
+   * Name of a global component rendered inside the panel. It fills the panel's
+   * height and scrolls its own content.
+   */
+  component: string;
+  /**
+   * Accessible name of the panel landmark. Resolved through the DMS i18n
+   * convention: a plain literal, or an i18n key when prefixed with "$".
+   */
+  ariaLabel?: string;
+  /** Width in px before the user resizes the panel. Defaults to `440`. */
+  defaultWidth?: number;
+  /** Narrowest width in px the resize handle allows. Defaults to `320`. */
+  minWidth?: number;
+  /** Widest width in px the resize handle allows. Defaults to `720`. */
+  maxWidth?: number;
+}
+
+/** The width bounds of a side panel, defaults applied. */
+export interface SidePanelWidthBounds {
+  defaultWidth: number;
+  minWidth: number;
+  maxWidth: number;
+}
+
+interface UseAppSidePanelsReturn {
+  panels: Readonly<Ref<SidePanel[]>>;
+}
+
+const SIDE_PANELS_STATE_KEY = "dms:side-panels";
+const DEFAULT_SIDE_PANEL_WIDTH = 440;
+const DEFAULT_SIDE_PANEL_MIN_WIDTH = 320;
+const DEFAULT_SIDE_PANEL_MAX_WIDTH = 720;
+
+function useSidePanelState() {
+  return useDmsState<SidePanel[]>(SIDE_PANELS_STATE_KEY, () => []);
+}
+
+/**
+ * Registers a {@link SidePanel}, replacing any panel registered under the same
+ * `id`. Call it inside the DMS app, from a universal plugin.
+ */
+export function registerSidePanel(panel: SidePanel): void {
+  const panels = useSidePanelState();
+  const next = panels.value.filter((entry) => entry.id !== panel.id);
+  next.push(panel);
+  panels.value = next;
+}
+
+/** Removes the side panel registered under `id`, if any. */
+export function unregisterSidePanel(id: string): void {
+  const panels = useSidePanelState();
+  panels.value = panels.value.filter((entry) => entry.id !== id);
+}
+
+/**
+ * Resolves the width bounds of a panel, defaults applied. A `defaultWidth`
+ * outside `[minWidth, maxWidth]` is brought back inside.
+ */
+export function resolveSidePanelWidthBounds(
+  panel: SidePanel,
+): SidePanelWidthBounds {
+  const minWidth = panel.minWidth ?? DEFAULT_SIDE_PANEL_MIN_WIDTH;
+  const maxWidth = Math.max(
+    minWidth,
+    panel.maxWidth ?? DEFAULT_SIDE_PANEL_MAX_WIDTH,
+  );
+  const defaultWidth = Math.min(
+    maxWidth,
+    Math.max(minWidth, panel.defaultWidth ?? DEFAULT_SIDE_PANEL_WIDTH),
+  );
+  return { defaultWidth, minWidth, maxWidth };
+}
+
+/**
+ * The registered side panels, in registration order. Read by the dashboard;
+ * modules normally only need `registerSidePanel` and {@link useSidePanel}.
+ */
+export function useAppSidePanels(): UseAppSidePanelsReturn {
+  return { panels: useSidePanelState() };
+}

package/frontend-vue/layers/dms-layout/app/composables/useCommandPaletteAssistant.ts

@@ -0,0 +1,129 @@
+/**
+ * A prompt the assistant mode of the command palette offers before the user
+ * types anything ("Try asking").
+ */
+export interface CommandPaletteAssistantSuggestion {
+  /**
+   * Text shown in the list. A `$`-prefixed value resolves as an i18n key
+   * (`useTranslation().processI18n`).
+   */
+  label: string;
+  /**
+   * Prompt submitted when the suggestion is picked. Defaults to the resolved
+   * `label`; set it when the shown text and the question differ.
+   */
+  prompt?: string;
+  /** Icon name shown in the item's well. Defaults to the assistant's icon. */
+  icon?: string;
+}
+
+/**
+ * The props the palette binds to an assistant's `answerComponent`, once per
+ * submitted prompt. The component is mounted afresh for every submission.
+ */
+export interface CommandPaletteAssistantAnswerProps {
+  /** The prompt the user submitted, trimmed. */
+  prompt: string;
+  /**
+   * Closes the palette. Call it before an action takes the user elsewhere —
+   * a navigation, or a hand-off to the module's own assistant UI.
+   */
+  close: () => void;
+}
+
+/**
+ * An assistant mode for the command palette (Ctrl/Cmd+K), provided by a
+ * frontend module. While one is registered, Tab switches the palette between
+ * search and assistant mode, every non-empty search ends with an
+ * "Ask the assistant" item, and a submitted prompt mounts `answerComponent`
+ * inside the palette. Without one, the palette has no assistant mode at all.
+ *
+ * The palette only frames the answer: whether it is computed inline, read-only,
+ * or handed off to the module's own interface is the component's decision. An
+ * `answerComponent` with an async `setup` (a top-level `await`) shows the
+ * palette's loading skeleton until it resolves; one that renders right away
+ * draws its own progress.
+ *
+ * Like {@link CommandPaletteSource}, an assistant carries a callable
+ * (`suggestions`), so it must be registered from CLIENT context (a `.client`
+ * plugin or component setup): a server-side registration would arrive on the
+ * client stripped of it, and the palette ignores such an entry.
+ */
+export interface CommandPaletteAssistant {
+  /** Unique key: dedup on `register` (upsert) and target of `unregister`. */
+  id: string;
+  /**
+   * Name of the assistant, shown in the answer frame and as the header of the
+   * "Ask" items. A `$`-prefixed value resolves as an i18n key.
+   */
+  label: string;
+  /** Icon name of the assistant mode: the input's lead icon and the items' well. */
+  icon: string;
+  /**
+   * Input placeholder in assistant mode. A `$`-prefixed value resolves as an
+   * i18n key. Defaults to the DMS's "Ask anything about your workspace…".
+   */
+  placeholder?: string;
+  /**
+   * Builds the suggestions listed while the prompt is empty. Evaluated inside
+   * a `computed`, so reactive state read here (the current page, the user's
+   * permissions) updates the list. Return `[]` for none.
+   */
+  suggestions: () => CommandPaletteAssistantSuggestion[];
+  /**
+   * Full registered name of the global component that answers a prompt. It
+   * receives {@link CommandPaletteAssistantAnswerProps}.
+   */
+  answerComponent: string;
+}
+
+const COMMAND_PALETTE_ASSISTANTS_STATE_KEY = "dms:command-palette-assistants";
+
+function isAssistantRenderable(assistant: CommandPaletteAssistant): boolean {
+  return (
+    typeof assistant.suggestions === "function" &&
+    typeof assistant.answerComponent === "string"
+  );
+}
+
+function useCommandPaletteAssistantState() {
+  return useDmsState<CommandPaletteAssistant[]>(
+    COMMAND_PALETTE_ASSISTANTS_STATE_KEY,
+    () => [],
+  );
+}
+
+/**
+ * Registers the command palette's assistant mode. Re-registering the same `id`
+ * replaces the entry. When several modules register one, the palette uses the
+ * one registered last.
+ */
+export function registerCommandPaletteAssistant(
+  assistant: CommandPaletteAssistant,
+): void {
+  const assistants = useCommandPaletteAssistantState();
+  const next = assistants.value.filter((entry) => entry.id !== assistant.id);
+  next.push(assistant);
+  assistants.value = next;
+}
+
+/** Removes the assistant registered under `id`; a no-op when there is none. */
+export function unregisterCommandPaletteAssistant(id: string): void {
+  const assistants = useCommandPaletteAssistantState();
+  assistants.value = assistants.value.filter((entry) => entry.id !== id);
+}
+
+/**
+ * The assistant the command palette offers, or `undefined` when no module
+ * registered a usable one. Read by the DMS palette; modules normally only need
+ * {@link registerCommandPaletteAssistant}.
+ */
+export function useCommandPaletteAssistant() {
+  const assistants = useCommandPaletteAssistantState();
+
+  const assistant = computed<CommandPaletteAssistant | undefined>(() =>
+    assistants.value.filter(isAssistantRenderable).at(-1),
+  );
+
+  return { assistant };
+}

package/frontend-vue/layers/dms-layout/app/composables/useHeaderActions.ts

@@ -1,11 +1,24 @@
+/**
+ * An icon-only button in the dashboard header. Either `onSelect` runs on
+ * click, or `sidePanelId` makes the button toggle that side panel: the DMS then
+ * derives the click and the engaged state from {@link useSidePanel}, and the
+ * action is plain data that a universal plugin may register.
+ */
 export interface HeaderAction {
   id: string;
   icon: string;
+  /** Tooltip and accessible name: a plain literal, or an i18n key when prefixed with "$". */
   label: string;
-  onSelect: () => void;
+  /** Run on click. Required unless `sidePanelId` is set, which it overrides. */
+  onSelect?: () => void;
+  /** The side panel this button opens and closes (see `registerSidePanel`). */
+  sidePanelId?: string;
   order?: number;
   isVisible?: () => boolean;
-  /** Renders the button as engaged — a toggle that is currently on. */
+  /**
+   * Renders the button as engaged — a toggle that is currently on. Derived
+   * from the side panel when `sidePanelId` is set.
+   */
   isActive?: () => boolean;
 }
 
@@ -20,13 +33,14 @@ export const BUILDER_ACTION_ID = "dms-builder-edit";
 // can register an action without a build-time dependency on this layer: it just
 // pushes to useDmsState(HEADER_ACTIONS_STATE_KEY).
 //
-// Because actions carry callables (onSelect/isVisible), they must be registered
-// from CLIENT context (a `.client` plugin or component setup): function values
-// are not part of the SSR payload, so a server-side registration would arrive on
-// the client with its callbacks stripped. `registerHeaderAction` calls useDmsState,
-// so it must run inside the DMS app context. `useHeaderActions` defensively drops
-// any entry whose onSelect was lost, so a stray server-side registration
-// degrades to "button not shown" rather than a runtime crash.
+// An action that carries callables (onSelect/isVisible/isActive) must be
+// registered from CLIENT context (a `.client` plugin or component setup):
+// function values are not part of the SSR payload, so a server-side
+// registration would arrive on the client with its callbacks stripped.
+// `useHeaderActions` defensively drops any entry left with neither an onSelect
+// nor a sidePanelId, so a stray server-side registration degrades to "button
+// not shown" rather than a runtime crash. A side panel action is plain data
+// and may be registered from a universal plugin.
 const HEADER_ACTIONS_STATE_KEY = "dms:header-actions";
 const DEFAULT_ORDER = 100;
 
@@ -35,8 +49,11 @@ function actionOrder(action: HeaderAction): number {
 }
 
 function isActionRenderable(action: HeaderAction): boolean {
-  if (typeof action.onSelect !== "function") return false;
-  if (!action.isVisible) return true;
+  const isSelectable =
+    typeof action.onSelect === "function" ||
+    typeof action.sidePanelId === "string";
+  if (!isSelectable) return false;
+  if (typeof action.isVisible !== "function") return true;
   return action.isVisible();
 }
 
@@ -44,6 +61,10 @@ function useHeaderActionState() {
   return useDmsState<HeaderAction[]>(HEADER_ACTIONS_STATE_KEY, () => []);
 }
 
+/**
+ * Registers a {@link HeaderAction}, replacing any action registered under the
+ * same `id`. Call it inside the DMS app.
+ */
 export function registerHeaderAction(action: HeaderAction): void {
   const actions = useHeaderActionState();
   const existingIndex = actions.value.findIndex(
@@ -60,6 +81,7 @@ export function registerHeaderAction(action: HeaderAction): void {
   actions.value = next;
 }
 
+/** The visible header actions, sorted by `order`. Read by the header. */
 export function useHeaderActions() {
   const actions = useHeaderActionState();
   const visibleActions = computed<HeaderAction[]>(() =>

package/frontend-vue/layers/dms-layout/app/composables/useSidePanel.ts

@@ -0,0 +1,41 @@
+import {
+  isSidePanelOpen,
+  setOpenSidePanel,
+  toggleSidePanel,
+  useSidePanelPreferences,
+} from "../build/composables/layout/sidePanelState";
+
+/** The open state of one side panel, and the actions that change it. */
+export interface SidePanelControls {
+  /** Whether this panel is the open one. */
+  isOpen: Readonly<Ref<boolean>>;
+  /** Opens this panel, closing the one that was open, if any. */
+  open: () => void;
+  /** Closes this panel; does nothing when another one is open. */
+  close: () => void;
+  /** Opens this panel when it is closed, closes it when it is open. */
+  toggle: () => void;
+}
+
+/**
+ * Opens and closes the side panel registered under `id` (see
+ * {@link registerSidePanel}). The DMS owns the state: one panel is open at a
+ * time, so opening one closes the other, and which one is open is remembered
+ * in a cookie, so the server renders it open on the next visit. Every caller
+ * of the same `id` shares the state, whatever component or plugin it runs in.
+ */
+export function useSidePanel(id: string): SidePanelControls {
+  const preferences = useSidePanelPreferences();
+  const isOpen = computed(() => isSidePanelOpen(preferences, id));
+
+  function close(): void {
+    if (isOpen.value) setOpenSidePanel(preferences, null);
+  }
+
+  return {
+    isOpen,
+    open: () => setOpenSidePanel(preferences, id),
+    close,
+    toggle: () => toggleSidePanel(preferences, id),
+  };
+}

package/frontend-vue/layers/dms-layout/app/pages/[...slug].vue

@@ -358,6 +358,13 @@ const fillingComponentId = computed(() =>
   fillHeight.value ? components.value.at(-1)?.id : undefined,
 );
 
+// The server leaves out the blocks the viewer may not see, and says when that
+// left nothing of a page that declares some. Never while the layout loads.
+const { t } = useI18n();
+const hidesEveryBlock = computed(
+  () => pageLayout.value?.allComponentsHidden === true,
+);
+
 // --- Live-edit highlight ---------------------------------------------------
 // When the active page's layout changes in place (DMS dev hot-reload, same
 // route), animate the components that changed. Added/removed components are
@@ -472,7 +479,15 @@ if (import.meta.env.DEV) {
 </script>
 
 <template>
+  <div v-if="hidesEveryBlock" class="dms-card overflow-hidden">
+    <DmsEmptyState
+      variant="no-access"
+      :title="t('page.no_visible_blocks.title')"
+      :description="t('page.no_visible_blocks.description')"
+    />
+  </div>
   <TransitionGroup
+    v-else
     tag="div"
     name="dms-fresh"
     class="dms-page-stack space-y-6"

package/frontend-vue/layers/dms-layout/app/plugins/notification-stream.client.ts

@@ -5,7 +5,6 @@ const NOTIFICATION_NEW_TYPE = "notification:new";
 const NOTIFICATION_READ_TYPE = "notification:read";
 const NOTIFICATION_ALL_READ_TYPE = "notification:all-read";
 const NOTIFICATION_UNREAD_TYPE = "notification:unread";
-const NOTIFICATION_SEEN_TYPE = "notification:seen";
 
 interface IncomingPayload {
   notification?: UserNotification;
@@ -28,14 +27,12 @@ export default defineDmsPlugin(() => {
     handleRemoteRead,
     handleRemoteUnread,
     handleRemoteAllRead,
-    handleRemoteSeen,
   } = useNotifications();
   const realtime = useUserRealtime();
 
   const handlers: Record<string, Handler> = {
     [NOTIFICATION_NEW_TYPE]: (payload) => {
-      if (payload?.notification)
-        handleIncomingNotification(payload.notification);
+      if (payload?.notification) handleIncomingNotification(payload.notification);
     },
     [NOTIFICATION_READ_TYPE]: async (payload) => {
       if (Array.isArray(payload?.ids)) await handleRemoteRead(payload.ids);
@@ -46,9 +43,6 @@ export default defineDmsPlugin(() => {
     [NOTIFICATION_ALL_READ_TYPE]: async () => {
       await handleRemoteAllRead();
     },
-    [NOTIFICATION_SEEN_TYPE]: () => {
-      handleRemoteSeen();
-    },
   };
 
   let unsubscribe: (() => void) | undefined;

package/frontend-vue/layers/dms-layout/app/plugins/side-panel-host.ts

@@ -0,0 +1,13 @@
+import { useAppOverlay } from "../composables/useAppOverlay";
+
+/** Registered name of `SidePanelHost.vue` (the layer's `Dms` prefix applied). */
+const SIDE_PANEL_HOST_COMPONENT = "DmsSidePanelHost";
+
+/**
+ * Mounts the side panel host as an app overlay, outside the routed layouts, so
+ * the open side panel survives a layout change. Universal: the server renders
+ * the open panel too.
+ */
+export default defineDmsPlugin(() => {
+  useAppOverlay().register(SIDE_PANEL_HOST_COMPONENT);
+});

package/frontend-vue/layers/dms-layout/app/types/page.ts

@@ -1,3 +1,6 @@
+import type { BlockText } from "#dms-core/app/types/composed-text";
+import type { BlockAction } from "#dms-ui/app/build/components/blocks/BlockActions.vue";
+
 export type MenuItemType = "label" | "link";
 // MenuItemVariant / MenuItemStatus / MenuItemQuery live in dms-core, the layer
 // that renders them: this one only consumes them.
@@ -86,6 +89,8 @@ export type SiteLayoutTree = Omit<PageInfo, "layoutUrl"> & {
   childrenOrders: string[];
   layoutUrl?: string;
   hasAccess?: boolean;
+  /** The tone of a `badge` the server counted (`navBadge`); neutral when absent. */
+  badgeTone?: MenuItemBadgeTone;
 };
 // Mirror of LayoutBannerVariant from @antelopejs/interface-dms/layout-banners.
 export type LayoutBannerVariant = "info" | "warning" | "error";
@@ -101,7 +106,10 @@ export interface LayoutBanner {
   order: number;
   dismissible: boolean;
   icon?: string;
-  text?: string;
+  /** A string (`$` for an i18n key) or a composed text. */
+  text?: BlockText;
+  /** Link buttons after the text; the last one leads. */
+  actions?: BlockAction[];
   component?: string;
   props?: Record<string, unknown>;
 }
@@ -170,4 +178,6 @@ export interface ResolvedComponentInfo<T = object> {
 export interface PageLayout {
   components: Record<string, ComponentInfo>;
   layout: ComponentInfo;
+  /** The page declares components and the viewer may see none of them. */
+  allComponentsHidden?: boolean;
 }