@antelopejs/dms 0.6.2 → 0.7.0

package/frontend-vue/layers/dms-layout/app/build/composables/command-palette/useCommandPaletteAssistantMode.ts

@@ -0,0 +1,249 @@
+import type { CommandPaletteGroup } from "@nuxt/ui";
+import { computed, ref, watch, type ComputedRef, type Ref } from "vue";
+import type { I18nTranslate } from "#dms-core/app/composables/translation/useTranslation";
+import {
+  appendAssistantAskGroup,
+  buildAssistantModeGroups,
+  type ResolvedAssistantSuggestion,
+} from "./assistantGroups";
+
+/** @internal */
+export type CommandPaletteMode = "search" | "assistant";
+
+/** @internal One submitted prompt; `id` changes on every submission. */
+export interface CommandPaletteSubmission {
+  id: number;
+  prompt: string;
+}
+
+/** @internal The registered assistant's fields, resolved for display. */
+export interface ResolvedCommandPaletteAssistant {
+  label: string;
+  icon: string;
+  placeholder: string;
+  answerComponent: string;
+  suggestions: ResolvedAssistantSuggestion[];
+}
+
+interface PaletteGroupsContext {
+  assistant: ResolvedCommandPaletteAssistant | undefined;
+  isAssistantMode: boolean;
+  hasAnswer: boolean;
+  prompt: string;
+  translate: I18nTranslate;
+  submit: (prompt: string) => void;
+}
+
+const MODE_ANNOUNCEMENT_KEYS: Record<CommandPaletteMode, string> = {
+  search: "commandPalette.assistant.modeSearch",
+  assistant: "commandPalette.assistant.modeAssistant",
+};
+
+const OTHER_MODE: Record<CommandPaletteMode, CommandPaletteMode> = {
+  search: "assistant",
+  assistant: "search",
+};
+
+/**
+ * Tab without a modifier: Shift+Tab and the browser's own combinations keep
+ * moving focus, so the dialog's keyboard navigation stays reachable.
+ *
+ * @internal
+ */
+export function isModeToggleKey(event: KeyboardEvent): boolean {
+  return (
+    event.key === "Tab" &&
+    !event.shiftKey &&
+    !event.altKey &&
+    !event.ctrlKey &&
+    !event.metaKey &&
+    !event.isComposing
+  );
+}
+
+function createModeToggleHandler(
+  isEnabled: () => boolean,
+  toggle: () => void,
+): (event: KeyboardEvent) => void {
+  return (event) => {
+    if (!isEnabled() || !isModeToggleKey(event)) return;
+    // The dialog's focus trap listens further up and would move focus.
+    event.preventDefault();
+    event.stopPropagation();
+    toggle();
+  };
+}
+
+function useResolvedAssistant(): ComputedRef<
+  ResolvedCommandPaletteAssistant | undefined
+> {
+  const { assistant } = useCommandPaletteAssistant();
+  const { t } = useI18n();
+  const { processI18n } = useTranslation();
+
+  return computed(() => {
+    const entry = assistant.value;
+    if (!entry) return undefined;
+
+    return {
+      label: processI18n(entry.label),
+      icon: entry.icon,
+      placeholder: entry.placeholder
+        ? processI18n(entry.placeholder)
+        : t("commandPalette.assistant.placeholder"),
+      answerComponent: entry.answerComponent,
+      suggestions: entry.suggestions().map((suggestion) => {
+        const label = processI18n(suggestion.label);
+        return {
+          label,
+          prompt: suggestion.prompt ?? label,
+          icon: suggestion.icon ?? entry.icon,
+        };
+      }),
+    };
+  });
+}
+
+function useAssistantSession(
+  isOpen: Ref<boolean>,
+  searchTerm: Ref<string>,
+  hasAssistant: ComputedRef<boolean>,
+) {
+  const { t } = useI18n();
+  const mode = ref<CommandPaletteMode>("search");
+  const submission = ref<CommandPaletteSubmission | null>(null);
+  const announcement = ref("");
+  let submissionCount = 0;
+
+  function setMode(next: CommandPaletteMode): void {
+    if (!hasAssistant.value) return;
+    mode.value = next;
+    submission.value = null;
+    announcement.value = t(MODE_ANNOUNCEMENT_KEYS[next]);
+  }
+
+  function submit(prompt: string): void {
+    const trimmed = prompt.trim();
+    if (!trimmed || !hasAssistant.value) return;
+    mode.value = "assistant";
+    searchTerm.value = trimmed;
+    submissionCount += 1;
+    submission.value = { id: submissionCount, prompt: trimmed };
+  }
+
+  watch(isOpen, (open) => {
+    if (open) return;
+    mode.value = "search";
+    submission.value = null;
+    announcement.value = "";
+  });
+  const onInputKeydown = createModeToggleHandler(
+    () => hasAssistant.value,
+    () => setMode(OTHER_MODE[mode.value]),
+  );
+
+  return { mode, submission, announcement, setMode, submit, onInputKeydown };
+}
+
+/** The submission whose answer shows: gone as soon as the prompt is edited. */
+function useShownAnswer(
+  isAssistantMode: ComputedRef<boolean>,
+  submission: Ref<CommandPaletteSubmission | null>,
+  searchTerm: Ref<string>,
+): ComputedRef<CommandPaletteSubmission | null> {
+  return computed(() =>
+    isAssistantMode.value &&
+    submission.value?.prompt === searchTerm.value.trim()
+      ? submission.value
+      : null,
+  );
+}
+
+function assistantModeGroups(
+  assistant: ResolvedCommandPaletteAssistant,
+  context: PaletteGroupsContext,
+): CommandPaletteGroup[] {
+  if (context.hasAnswer) return [];
+
+  return buildAssistantModeGroups(context.prompt, {
+    icon: assistant.icon,
+    promptLabel: assistant.label,
+    suggestionsLabel: context.translate(
+      "commandPalette.assistant.suggestions",
+      {},
+    ),
+    sendLabel: (prompt) =>
+      context.translate("commandPalette.assistant.send", { prompt }),
+    suggestions: assistant.suggestions,
+    onSubmit: context.submit,
+  });
+}
+
+/**
+ * The groups the palette renders: the sources' groups untouched while no
+ * assistant is registered, the same groups followed by the "Ask the
+ * assistant" item once a search is typed, and the prompt and suggestions in
+ * assistant mode — none once an answer is shown, which the empty slot renders.
+ *
+ * @internal
+ */
+export function buildPaletteGroups(
+  sourceGroups: CommandPaletteGroup[],
+  context: PaletteGroupsContext,
+): CommandPaletteGroup[] {
+  const { assistant } = context;
+  if (!assistant) return sourceGroups;
+  if (context.isAssistantMode) return assistantModeGroups(assistant, context);
+
+  return appendAssistantAskGroup(sourceGroups, context.prompt, {
+    label: assistant.label,
+    icon: assistant.icon,
+    askLabel: (query) =>
+      context.translate("commandPalette.assistant.ask", { query }),
+    onAsk: context.submit,
+  });
+}
+
+/**
+ * State of the command palette's assistant mode: the mode, the groups shown
+ * for it, the submitted prompt, and the Tab toggle bound to the input. Every
+ * piece degrades to the plain search palette while no assistant is registered.
+ *
+ * @internal
+ */
+export function useCommandPaletteAssistantMode(
+  searchGroups: Ref<CommandPaletteGroup[]>,
+) {
+  const { t } = useI18n();
+  const isOpen = ref(false);
+  const searchTerm = ref("");
+  const assistant = useResolvedAssistant();
+  const hasAssistant = computed(() => !!assistant.value);
+  const session = useAssistantSession(isOpen, searchTerm, hasAssistant);
+  const { mode, submission } = session;
+
+  const isAssistantMode = computed(
+    () => hasAssistant.value && mode.value === "assistant",
+  );
+  const answer = useShownAnswer(isAssistantMode, submission, searchTerm);
+  const groups = computed(() =>
+    buildPaletteGroups(searchGroups.value, {
+      assistant: assistant.value,
+      isAssistantMode: isAssistantMode.value,
+      hasAnswer: !!answer.value,
+      prompt: searchTerm.value.trim(),
+      translate: (key, params) => t(key, params),
+      submit: session.submit,
+    }),
+  );
+
+  return {
+    ...session,
+    isOpen,
+    searchTerm,
+    assistant,
+    isAssistantMode,
+    answer,
+    groups,
+  };
+}

package/frontend-vue/layers/dms-layout/app/build/composables/general/useGithubStarPrompt.ts

@@ -0,0 +1,178 @@
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  type ComputedRef,
+} from "vue";
+import { GITHUB_REPOSITORY_URL } from "../../utils/github-repository";
+
+const STORAGE_PREFIX = "dms-github-star-prompt:";
+
+/** `localStorage` keys of the star prompt, per browser. */
+export const GITHUB_STAR_PROMPT_KEYS = {
+  /** Visible time spent on signed-in dashboard pages, in milliseconds. */
+  activeMs: `${STORAGE_PREFIX}active-ms`,
+  /** Epoch milliseconds until which "Later" keeps the prompt hidden. */
+  snoozedUntil: `${STORAGE_PREFIX}snoozed-until`,
+  /** Set once the prompt is starred or closed: it never shows again. */
+  dismissed: `${STORAGE_PREFIX}dismissed`,
+} as const;
+
+/** Active dashboard time before the prompt first shows. */
+export const GITHUB_STAR_PROMPT_DELAY_MS = 15 * 60 * 1000;
+/** How long "Later" hides the prompt. */
+export const GITHUB_STAR_PROMPT_SNOOZE_MS = 48 * 60 * 60 * 1000;
+/** How often the visible time is saved and the snooze checked. */
+export const GITHUB_STAR_PROMPT_TICK_MS = 30 * 1000;
+
+const DISMISSED = "1";
+const VISIBLE = "visible";
+
+function readStorage(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    /* storage unavailable (private mode, quota): the prompt state lasts the page */
+  }
+}
+
+function readCount(key: string): number {
+  const value = Number(readStorage(key));
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function isPageVisible(): boolean {
+  return document.visibilityState === VISIBLE;
+}
+
+export interface GithubStarPrompt {
+  /** Whether the prompt is due: enough active time, not snoozed, not dismissed. */
+  isDue: ComputedRef<boolean>;
+  /** "Later": hides the prompt for {@link GITHUB_STAR_PROMPT_SNOOZE_MS}. */
+  snooze: () => void;
+  /** Opens the repository in a new tab, then never shows the prompt again. */
+  star: () => void;
+  /** Never shows the prompt again. */
+  dismiss: () => void;
+}
+
+/**
+ * The GitHub star invitation's timing, kept per browser in `localStorage`.
+ * Only the time the tab is visible counts, added up across sessions, so a
+ * dashboard left open in a background tab does not bring the prompt sooner.
+ * Without `isEnabled` nothing is counted or shown.
+ */
+export const useGithubStarPrompt = (isEnabled: boolean): GithubStarPrompt => {
+  const isMounted = ref(false);
+  const activeMs = ref(0);
+  const snoozedUntil = ref(0);
+  const isDismissed = ref(false);
+  const now = ref(0);
+  let countedSince: number | null = null;
+  let ticker: ReturnType<typeof setInterval> | undefined;
+
+  const isDue = computed(
+    () =>
+      isMounted.value &&
+      !isDismissed.value &&
+      activeMs.value >= GITHUB_STAR_PROMPT_DELAY_MS &&
+      now.value >= snoozedUntil.value,
+  );
+
+  // Merged with what this page holds: a choice made in another tab is
+  // followed here, and one made here outlives a storage that cannot be read.
+  function load(): void {
+    activeMs.value = storedActiveMs();
+    snoozedUntil.value = Math.max(
+      snoozedUntil.value,
+      readCount(GITHUB_STAR_PROMPT_KEYS.snoozedUntil),
+    );
+    isDismissed.value ||=
+      readStorage(GITHUB_STAR_PROMPT_KEYS.dismissed) === DISMISSED;
+    now.value = Date.now();
+  }
+
+  function storedActiveMs(): number {
+    return Math.max(
+      activeMs.value,
+      readCount(GITHUB_STAR_PROMPT_KEYS.activeMs),
+    );
+  }
+
+  // Added to the stored total rather than written over it, so two tabs add
+  // up. One tick at most is counted per call: a longer gap means the device
+  // slept, which is not time spent on the dashboard.
+  function count(): void {
+    if (countedSince === null) return;
+    const at = Date.now();
+    const elapsed = Math.min(at - countedSince, GITHUB_STAR_PROMPT_TICK_MS);
+    countedSince = at;
+    if (activeMs.value >= GITHUB_STAR_PROMPT_DELAY_MS) return;
+    activeMs.value = storedActiveMs() + elapsed;
+    writeStorage(GITHUB_STAR_PROMPT_KEYS.activeMs, String(activeMs.value));
+  }
+
+  function onVisibilityChange(): void {
+    count();
+    countedSince = isPageVisible() ? Date.now() : null;
+  }
+
+  function tick(): void {
+    count();
+    load();
+    if (isDismissed.value) stop();
+  }
+
+  function stop(): void {
+    clearInterval(ticker);
+    ticker = undefined;
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+  }
+
+  function dismiss(): void {
+    isDismissed.value = true;
+    writeStorage(GITHUB_STAR_PROMPT_KEYS.dismissed, DISMISSED);
+    stop();
+  }
+
+  function snooze(): void {
+    now.value = Date.now();
+    snoozedUntil.value = now.value + GITHUB_STAR_PROMPT_SNOOZE_MS;
+    writeStorage(
+      GITHUB_STAR_PROMPT_KEYS.snoozedUntil,
+      String(snoozedUntil.value),
+    );
+  }
+
+  function star(): void {
+    window.open(GITHUB_REPOSITORY_URL, "_blank", "noopener,noreferrer");
+    dismiss();
+  }
+
+  onMounted(() => {
+    if (!isEnabled) return;
+    load();
+    isMounted.value = true;
+    if (isDismissed.value) return;
+    countedSince = isPageVisible() ? Date.now() : null;
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    ticker = setInterval(tick, GITHUB_STAR_PROMPT_TICK_MS);
+  });
+
+  onBeforeUnmount(() => {
+    if (ticker === undefined) return;
+    count();
+    stop();
+  });
+
+  return { isDue, snooze, star, dismiss };
+};

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

@@ -0,0 +1,191 @@
+import type { ComputedRef, Ref } from "vue";
+import {
+  resolveSidePanelWidthBounds,
+  type SidePanel,
+  type SidePanelWidthBounds,
+  useAppSidePanels,
+} from "../../../composables/useAppSidePanels";
+
+/**
+ * Set to the panel's width in px by the panel itself and by the dashboard
+ * frame, which keeps that much room free on its right from `lg`. Both cap it
+ * at 60vw.
+ *
+ * @internal
+ */
+export const SIDE_PANEL_WIDTH_VARIABLE = "--dms-side-panel-width";
+/** @internal */
+export const SIDE_PANEL_COOKIE = "dms-side-panel";
+const SIDE_PANEL_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+const SIDE_PANEL_DRAG_WIDTH_STATE_KEY = "dms:side-panel-drag-width";
+
+/**
+ * What the DMS remembers of the side panels on this device: which one is open
+ * and the width each was last given. A cookie, so the server renders the open
+ * panel at its width and a reload does not move the page.
+ *
+ * @internal
+ */
+export interface SidePanelPreferences {
+  openId: string | null;
+  widths: Record<string, number>;
+}
+
+/** @internal */
+export interface ActiveSidePanel {
+  panel: ComputedRef<SidePanel | null>;
+  bounds: ComputedRef<SidePanelWidthBounds | null>;
+  width: ComputedRef<number>;
+}
+
+function emptyPreferences(): SidePanelPreferences {
+  return { openId: null, widths: {} };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function readWidths(value: unknown): Record<string, number> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).filter(([, width]) => Number.isFinite(width)),
+  ) as Record<string, number>;
+}
+
+/**
+ * Reads the cookie value back defensively: it comes from the browser, and an
+ * older or hand-edited value must not break the dashboard.
+ *
+ * @internal
+ */
+export function readSidePanelPreferences(value: unknown): SidePanelPreferences {
+  if (!isRecord(value)) return emptyPreferences();
+  const openId = typeof value.openId === "string" ? value.openId : null;
+  return { openId, widths: readWidths(value.widths) };
+}
+
+/** @internal */
+export function useSidePanelPreferences(): Ref<SidePanelPreferences> {
+  return useDmsCookie<SidePanelPreferences>(SIDE_PANEL_COOKIE, {
+    default: emptyPreferences,
+    maxAge: SIDE_PANEL_COOKIE_MAX_AGE,
+  });
+}
+
+/**
+ * Opens the panel `openId`, or closes every panel with `null`. One panel is
+ * open at a time, so opening one closes the other.
+ *
+ * @internal
+ */
+export function setOpenSidePanel(
+  preferences: Ref<SidePanelPreferences>,
+  openId: string | null,
+): void {
+  const current = readSidePanelPreferences(preferences.value);
+  if (current.openId === openId) return;
+  preferences.value = { ...current, openId };
+}
+
+/** @internal */
+export function isSidePanelOpen(
+  preferences: Ref<SidePanelPreferences>,
+  id: string,
+): boolean {
+  return readSidePanelPreferences(preferences.value).openId === id;
+}
+
+/** @internal */
+export function toggleSidePanel(
+  preferences: Ref<SidePanelPreferences>,
+  id: string,
+): void {
+  setOpenSidePanel(preferences, isSidePanelOpen(preferences, id) ? null : id);
+}
+
+/** @internal */
+export function storeSidePanelWidth(
+  preferences: Ref<SidePanelPreferences>,
+  id: string,
+  width: number,
+): void {
+  const current = readSidePanelPreferences(preferences.value);
+  preferences.value = {
+    ...current,
+    widths: { ...current.widths, [id]: width },
+  };
+}
+
+/**
+ * The width of the panel being dragged, shared with the dashboard frame so the
+ * page follows the handle. The cookie is written once the drag ends.
+ *
+ * @internal
+ */
+export function useSidePanelDragWidth(): Ref<number | null> {
+  return useDmsState<number | null>(
+    SIDE_PANEL_DRAG_WIDTH_STATE_KEY,
+    () => null,
+  );
+}
+
+/** @internal */
+export function sidePanelWidthStyle(width: number): Record<string, string> {
+  return { [SIDE_PANEL_WIDTH_VARIABLE]: `${width}px` };
+}
+
+/** @internal */
+export function clampSidePanelWidth(
+  width: number,
+  bounds: SidePanelWidthBounds,
+): number {
+  return Math.round(
+    Math.min(bounds.maxWidth, Math.max(bounds.minWidth, width)),
+  );
+}
+
+/**
+ * The width a panel was last given, or its default, within its bounds.
+ *
+ * @internal
+ */
+export function storedSidePanelWidth(
+  preferences: SidePanelPreferences,
+  id: string,
+  bounds: SidePanelWidthBounds,
+): number {
+  return clampSidePanelWidth(
+    preferences.widths[id] ?? bounds.defaultWidth,
+    bounds,
+  );
+}
+
+/**
+ * The side panel the dashboard shows, and its width: the open panel, if it is
+ * registered and a user is signed in. Read by the panel host and by every
+ * dashboard frame, which reserves that width next to the page.
+ *
+ * @internal
+ */
+export function useActiveSidePanel(): ActiveSidePanel {
+  const { panels } = useAppSidePanels();
+  const preferences = useSidePanelPreferences();
+  const dragWidth = useSidePanelDragWidth();
+  const { loggedIn } = useUserSession();
+  const panel = computed(() => {
+    if (!loggedIn.value) return null;
+    const { openId } = readSidePanelPreferences(preferences.value);
+    return panels.value.find((entry) => entry.id === openId) ?? null;
+  });
+  const bounds = computed(() =>
+    panel.value ? resolveSidePanelWidthBounds(panel.value) : null,
+  );
+  const width = computed(() => {
+    if (!panel.value || !bounds.value) return 0;
+    if (dragWidth.value !== null) return dragWidth.value;
+    const current = readSidePanelPreferences(preferences.value);
+    return storedSidePanelWidth(current, panel.value.id, bounds.value);
+  });
+  return { panel, bounds, width };
+}

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

@@ -0,0 +1,51 @@
+import type { HeaderAction } from "../../../composables/useHeaderActions";
+import {
+  isSidePanelOpen,
+  toggleSidePanel,
+  useSidePanelPreferences,
+} from "./sidePanelState";
+
+/** @internal */
+export interface HeaderActionControls {
+  /** Whether the action is a toggle, whose button reports a pressed state. */
+  isToggle: (action: HeaderAction) => boolean;
+  /** Whether the toggle is on: its side panel is open, or `isActive()` says so. */
+  isActive: (action: HeaderAction) => boolean;
+  /** Toggles the action's side panel, or runs its `onSelect`. */
+  select: (action: HeaderAction) => void;
+}
+
+/**
+ * How the header reads and runs any {@link HeaderAction}: an action linked to
+ * a side panel gets its state and its click from the DMS, any other one from
+ * its own callables.
+ *
+ * @internal
+ */
+export function useHeaderActionControls(): HeaderActionControls {
+  const preferences = useSidePanelPreferences();
+
+  function isToggle(action: HeaderAction): boolean {
+    return (
+      typeof action.sidePanelId === "string" ||
+      typeof action.isActive === "function"
+    );
+  }
+
+  function isActive(action: HeaderAction): boolean {
+    if (typeof action.sidePanelId === "string") {
+      return isSidePanelOpen(preferences, action.sidePanelId);
+    }
+    return typeof action.isActive === "function" && action.isActive();
+  }
+
+  function select(action: HeaderAction): void {
+    if (typeof action.sidePanelId === "string") {
+      toggleSidePanel(preferences, action.sidePanelId);
+      return;
+    }
+    action.onSelect?.();
+  }
+
+  return { isToggle, isActive, select };
+}