@k2b/cloud 0.39.0 → 0.41.0

package/src/ssr/layout-help-panel-reader.tsx

@@ -0,0 +1,159 @@
+import { Dropdown, LocaleProvider, MarkdownView, TableOfContents, useLocale } from "@k2b/ui";
+import { type Accessor, createMemo, createSignal, onMount } from "solid-js";
+import { render } from "solid-js/web";
+import type { HelpDocumentPayload } from "../shared/help";
+import { helpMessages } from "./help-messages";
+import { helpArticleParts } from "./layout-help-article";
+import type { HelpPanelState } from "./layout-help-panel-state";
+import type { HelpTopic } from "./layout-help-registry";
+import { HelpArticleView } from "./layout-help-views";
+
+function Sections(props: {
+  sections: { id: string; label: string }[];
+  onSection: (id: string) => void;
+  active: Accessor<string | null>;
+  activation?: { key: string; focused: boolean };
+}) {
+  const locale = useLocale();
+  const t = () => helpMessages.resolve([locale()]).t;
+  let trigger: HTMLButtonElement | undefined;
+  onMount(() => {
+    if (!props.activation) return;
+    if (props.activation.focused) trigger?.focus({ preventScroll: true });
+    trigger?.dispatchEvent(new KeyboardEvent("keydown", { key: props.activation.key, bubbles: true, cancelable: true }));
+  });
+  return (
+    <Dropdown.Root
+      label={t().onThisPage}
+      position="bottom-left"
+      items={props.sections.map((section) => ({
+        label: section.label,
+        choice: "radio" as const,
+        checked: () => props.active() === section.id,
+        action: () => {
+          props.onSection(section.id);
+        },
+      }))}
+    >
+      <Dropdown.Trigger
+        ref={(element) => {
+          trigger = element;
+        }}
+        label={t().onThisPage}
+        size="sm"
+        tooltip={false}
+        variant="secondary"
+      >
+        <i class="ti ti-list" aria-hidden="true" />
+        <span>{t().onThisPage}</span>
+        <i class="ti ti-chevron-down" aria-hidden="true" />
+      </Dropdown.Trigger>
+    </Dropdown.Root>
+  );
+}
+export function HelpPanelReader(props: {
+  state: HelpPanelState;
+  topic: HelpTopic;
+  document: HelpDocumentPayload;
+  onSection: (id: string) => void;
+}) {
+  const locale = useLocale();
+  const t = () => helpMessages.resolve([locale()]).t;
+  const parts = createMemo(() => helpArticleParts(props.document.html));
+  const [active, setActive] = createSignal<string | null>(parts().sections[0]?.id ?? null);
+  let content: HTMLDivElement | undefined;
+  return (
+    <HelpArticleView
+      surface="panel"
+      topic={props.topic}
+      appId={props.state.data.appId}
+      parts={parts()}
+      document={props.document}
+      Markdown={MarkdownView}
+      showTools={parts().sections.length > 0}
+      sectionMenu={
+        parts().sections.length ? (
+          <Sections
+            sections={parts().sections}
+            active={active}
+            onSection={(id) => {
+              setActive(id);
+              props.onSection(id);
+            }}
+          />
+        ) : null
+      }
+      copyButton={null}
+      loading={null}
+      failure={null}
+      toc={
+        <TableOfContents
+          items={parts().sections}
+          title={t().onThisPage}
+          scrollRoot={() => props.state.scroller() ?? undefined}
+          contentRoot={() => content}
+          onActiveChange={(id) => setActive(id ?? null)}
+        />
+      }
+      copyAction={null}
+      headingRef={() => {}}
+      contentRef={(element) => {
+        content = element;
+      }}
+      onBack={props.state.back}
+    />
+  );
+}
+export function mountPanelSections(
+  container: HTMLElement,
+  props: { locale: string; state: HelpPanelState; key: string; focused: boolean; onSection: (id: string) => void },
+): () => void {
+  const article = container.closest("article");
+  const sections = Array.from(article?.querySelectorAll<HTMLAnchorElement>(".help-article-aside a[href^='#']") ?? []).map((link) => ({
+    id: decodeURIComponent(link.getAttribute("href")!.slice(1)),
+    label: link.textContent ?? "",
+  }));
+  const [active, setActive] = createSignal<string | null>(sections[0]?.id ?? null);
+  const aside = article?.querySelector<HTMLElement>(".help-article-aside-sticky");
+  let disposeToc = () => {};
+  // The aside is hidden at every panel width. Upgrade its scroll spy only when the section menu needs it.
+  if (aside) {
+    aside.textContent = "";
+    disposeToc = render(
+      () => (
+        <LocaleProvider locale={props.locale}>
+          <TableOfContents
+            items={sections}
+            title={helpMessages.resolve([props.locale]).t.onThisPage}
+            scrollRoot={() => props.state.scroller() ?? undefined}
+            contentRoot={() => article ?? undefined}
+            onActiveChange={(id) => setActive(id ?? null)}
+          />
+        </LocaleProvider>
+      ),
+      aside,
+    );
+  }
+  container.textContent = "";
+  container.style.display = "contents";
+  const disposeMenu = render(
+    () => (
+      <LocaleProvider locale={props.locale}>
+        <Sections
+          sections={sections}
+          active={active}
+          onSection={(id) => {
+            setActive(id);
+            props.onSection(id);
+          }}
+          activation={{ key: props.key, focused: props.focused }}
+        />
+      </LocaleProvider>
+    ),
+    container,
+  );
+  return () => {
+    disposeMenu();
+    disposeToc();
+  };
+}

package/src/ssr/layout-help-panel-search.tsx

@@ -0,0 +1,69 @@
+import { useLocale } from "@k2b/ui";
+import { createEffect, createMemo, createSignal, onCleanup, Show } from "solid-js";
+import { helpMessages } from "./help-messages";
+import type { HelpPanelState } from "./layout-help-panel-state";
+import { searchHelpTopics } from "./layout-help-search";
+import { HelpResultsView } from "./layout-help-views";
+
+export function HelpPanelSearchResults(props: { state: HelpPanelState }) {
+  const locale = useLocale();
+  const t = () => helpMessages.resolve([locale()]).t;
+  const query = createMemo(() => props.state.query().trim().toLocaleLowerCase());
+  const [ids, setIds] = createSignal<readonly string[] | null>(null);
+  const [searching, setSearching] = createSignal(false);
+  const [failed, setFailed] = createSignal(false);
+  const [attempt, setAttempt] = createSignal(0);
+  let version = 0;
+  createEffect(() => {
+    const value = query();
+    attempt();
+    const current = ++version;
+    setIds(null);
+    setSearching(false);
+    setFailed(false);
+    const urls = [...new Set(props.state.data.documents.map((topic) => topic.searchUrl))];
+    if (!value || !urls.length) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      setSearching(true);
+      void Promise.all(
+        urls.map(async (url) => {
+          const response = await fetch(`${url}?q=${encodeURIComponent(value)}`, {
+            signal: controller.signal,
+            headers: { Accept: "application/json" },
+          });
+          if (!response.ok) throw new Error(t().searchFailed);
+          const payload: unknown = await response.json();
+          return payload && typeof payload === "object" && "ids" in payload && Array.isArray(payload.ids)
+            ? payload.ids.filter((id): id is string => typeof id === "string")
+            : [];
+        }),
+      )
+        .then((groups) => {
+          if (current === version) setIds([...new Set(groups.flat())]);
+        })
+        .catch((error) => {
+          if (!(error instanceof DOMException && error.name === "AbortError") && current === version) setFailed(true);
+        })
+        .finally(() => {
+          if (current === version) setSearching(false);
+        });
+    }, 120);
+    onCleanup(() => {
+      clearTimeout(timer);
+      controller.abort();
+      if (current === version) version++;
+    });
+  });
+  return (
+    <Show when={query()}>
+      <HelpResultsView
+        results={searchHelpTopics(props.state.data.documents, query(), ids())}
+        searching={searching()}
+        failed={failed()}
+        onRetry={() => setAttempt((value) => value + 1)}
+        onOpen={() => {}}
+      />
+    </Show>
+  );
+}

package/src/ssr/layout-help-panel-shortcuts.ts

@@ -0,0 +1,7 @@
+import { getContext } from "../browser/panel";
+import { panelShortcutsReceived, readPanelShortcuts } from "../browser/panel-shortcuts";
+import type { HelpShortcutCommand } from "./layout-help-start";
+
+/** An empty host list is authoritative too, including when a reader remounts. */
+export const readHelpPanelShortcuts = (seed: HelpShortcutCommand[]): HelpShortcutCommand[] =>
+  panelShortcutsReceived() && getContext() !== null ? readPanelShortcuts() : seed;

package/src/ssr/layout-help-panel-state.ts

@@ -0,0 +1,141 @@
+import { batch, createSignal } from "solid-js";
+import type { HelpDocumentManifest, HelpDocumentPayload } from "../shared/help";
+import { focusHelpArticleHeading } from "./layout-help-navigation";
+
+export type HelpPanelData = {
+  documents: HelpDocumentManifest[];
+  appId?: string;
+  pageBase?: string;
+  article?: Omit<HelpDocumentPayload, "html">;
+};
+const states = new WeakMap<Element, ReturnType<typeof createPanelState>>();
+export const panelRoot = (element: Element): HTMLElement => {
+  const root = element.closest<HTMLElement>('.help-shell[data-surface="panel"]');
+  if (!root) throw new Error("Missing Help panel");
+  return root;
+};
+const createPanelState = (root: HTMLElement) => {
+  // This is our own server's inert JSON, shared once instead of repeating it in island props.
+  const data: HelpPanelData = JSON.parse(root.querySelector("[data-help-panel-data]")?.textContent ?? "{}");
+  const [view, setView] = createSignal<"hub" | "article">(root.dataset.helpInitialTopic ? "article" : "hub");
+  const [activeId, setActiveId] = createSignal<string | null>(data.article?.id ?? root.dataset.helpInitialTopic ?? null);
+  const [query, setQuery] = createSignal("");
+  const [searchReturnId, setSearchReturnId] = createSignal<string | null>(null);
+  const [navigation, setNavigation] = createSignal({ hash: "", version: 0 });
+  const [announcement, setAnnouncement] = createSignal("");
+  const cache = new Map<string, HelpDocumentPayload>();
+  const [cacheVersion, setCacheVersion] = createSignal(0);
+  const cacheKey = (topic: HelpDocumentManifest) => `${topic.locale ?? "en"}:${topic.url}`;
+  if (data.article) {
+    const topic = data.documents.find((topic) => topic.id === data.article?.id);
+    if (topic) cache.set(cacheKey(topic), { ...data.article, html: "" });
+  }
+  const cachedDocument = (topic: HelpDocumentManifest) => {
+    cacheVersion();
+    return cache.get(cacheKey(topic));
+  };
+  const storeDocument = (topic: HelpDocumentManifest, payload: HelpDocumentPayload) => {
+    cache.set(cacheKey(topic), payload);
+    setCacheVersion((value) => value + 1);
+  };
+  const results = () => root.querySelector<HTMLElement>("[data-help-results]");
+  const scroller = () => root.querySelector<HTMLElement>("[data-scroll-fade-mode]");
+  const sync = () => {
+    const hub = view() === "hub";
+    const start = results();
+    if (start) start.hidden = !hub;
+    const server = root.querySelector<HTMLElement>("[data-help-server-article]");
+    if (server) server.hidden = hub || activeId() !== data.article?.id;
+  };
+  const back = () => {
+    setSearchReturnId(null);
+    setView("hub");
+    sync();
+  };
+  /** Where the article stood when a search started from it; clearing the search returns there. */
+  let articleScrollTop = 0;
+  const changeQuery = (value: string) => {
+    const searching = !!value.trim();
+    let returned = false;
+    batch(() => {
+      if (searching && view() === "article") {
+        articleScrollTop = scroller()?.scrollTop ?? 0;
+        setSearchReturnId(activeId());
+        const region = results();
+        if (region) region.style.minHeight = "";
+        setView("hub");
+      }
+      setQuery(value);
+      if (!searching) {
+        const region = results();
+        if (region) region.style.minHeight = "";
+        const id = searchReturnId();
+        setSearchReturnId(null);
+        if (id && data.documents.some((topic) => topic.id === id)) {
+          setActiveId(id);
+          setView("article");
+          returned = true;
+        }
+      }
+    });
+    sync();
+    // The article stayed in the document while results showed; give it back its place once it has its height again.
+    if (returned) {
+      const top = articleScrollTop;
+      requestAnimationFrame(() => {
+        const scroll = scroller();
+        if (scroll) scroll.scrollTop = top;
+      });
+    }
+  };
+  const open = (id: string, hash = "") => {
+    if (!data.documents.some((topic) => topic.id === id)) return;
+    try {
+      localStorage.setItem("cloud.layoutHelp.activeTopic", id);
+    } catch {
+      /* Storage is optional. */
+    }
+    batch(() => {
+      setSearchReturnId(null);
+      setActiveId(id);
+      setView("article");
+      setNavigation((value) => ({ hash, version: value.version + 1 }));
+    });
+    const scroll = scroller();
+    if (scroll) scroll.scrollTop = 0;
+    sync();
+  };
+  const focusHeading = () =>
+    focusHelpArticleHeading(root.querySelector<HTMLHeadingElement>("article:not([hidden]) .help-article-title") ?? undefined);
+  return {
+    root,
+    data,
+    view,
+    activeId,
+    query,
+    changeQuery,
+    back,
+    open,
+    navigation,
+    cache,
+    cacheKey,
+    cachedDocument,
+    storeDocument,
+    sync,
+    results,
+    scroller,
+    focusHeading,
+    announcement,
+    setAnnouncement,
+  };
+};
+export type HelpPanelState = ReturnType<typeof createPanelState>;
+export function helpPanelState(element: Element): HelpPanelState {
+  const root = panelRoot(element);
+  let state = states.get(root);
+  if (!state) {
+    state = createPanelState(root);
+    states.set(root, state);
+  }
+  return state;
+}

package/src/ssr/layout-help-panel-types.ts

@@ -0,0 +1,19 @@
+import type { HelpDocumentManifest } from "@k2b/cloud/shared";
+import type { KeyboardPlatform } from "@k2b/ui";
+import type { LayoutHelpArticle } from "./help";
+
+export type LayoutHelpPanelProps = {
+  documents: readonly HelpDocumentManifest[];
+  /** Absent when the context selected Help the reader may not see. */
+  app?: { id: string; name: string; icon?: string };
+  /** appAppearanceStyle() of the app, from the server. */
+  appearance?: string;
+  /** Server-filtered For this view ids. */
+  view?: readonly string[];
+  initialTopic?: string;
+  /** Authorized article and server-parsed parts for an identical first frame. */
+  initialArticle?: LayoutHelpArticle;
+  pageBase?: string;
+  platform: KeyboardPlatform;
+  state?: "failed" | "unavailable";
+};

package/src/ssr/layout-help-start.ts

@@ -1,10 +1,10 @@
-import type { HelpKind } from "../shared/help";
+import { HELP_VIEW_LIMIT, type HelpKind } from "../shared/help";
 import { SHELL_SHORTCUT_ORDER } from "./shell-shortcuts";
 
 /** The concept asks for at most eight tasks as tiles; more task articles follow as a list. */
 export const HELP_START_TILE_LIMIT = 8;
 /** "For this view" shows two or three articles the page names. */
-export const HELP_VIEW_LIMIT = 3;
+export { HELP_VIEW_LIMIT } from "../shared/help";
 export const HELP_START_GROUP_KINDS = ["start", "reference", "troubleshoot"] as const;
 export type HelpStartGroupKind = (typeof HELP_START_GROUP_KINDS)[number];
 export type HelpStartTopic = { id: string; title: string; order?: number; kind?: HelpKind };
@@ -41,19 +41,42 @@ export const helpStart = <T extends HelpStartTopic>(topics: readonly T[], viewId
 };
 
 export type HelpShortcutScope = "everywhere" | "app" | "selection";
+// Three groups, each as scannable as HELP_START_TILE_LIMIT (8) task tiles: 3 x 8 rows.
+// Today's largest real page is well below this (shell 3 + Spaces about 8).
+export const HELP_START_SHORTCUT_LIMIT = 24;
+// Qualified command ids share CAPABILITY_QUALIFIED_ID_MAX_LENGTH.
+export const HELP_SHORTCUT_ID_MAX_LENGTH = 180;
+// One row label: the platform's CapabilityLink title / human-readable label bound.
+export const HELP_SHORTCUT_TITLE_MAX_LENGTH = 120;
+// Row tooltip: the platform's plain-text Action review message bound.
+export const HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH = 1000;
+// command-shortcuts grammar: five distinct modifier tokens "ctrl+alt+shift+meta+mod+" (24 chars)
+// plus the longest standard KeyboardEvent.key name "TVAudioDescriptionMixDown" (25 chars).
+export const HELP_SHORTCUT_KEYS_MAX_LENGTH = 49;
+export type HelpShortcut = { id: string; title: string; description?: string; shortcut: string; scope?: "selection" | "page" };
 export type HelpShortcutCommand = { id: string; title: string; description?: string; shortcut?: string; scope?: "selection" | "page" };
 /**
  * Group commands with a shortcut: scope "selection" -> "selection"; id starting with "cloud." -> "everywhere"; the rest -> "app".
  * Group order everywhere, app, selection; empty groups are absent. Inside "everywhere", the ids of SHELL_SHORTCUT_ORDER come first in that
  * order (so rows rendered on the server keep their place when the browser adds more), then the rest in input order; other groups keep input order.
- * Commands without a shortcut are dropped.
+ * Commands without a shortcut, with empty ids/titles or exceeding the string bounds are dropped.
+ * Keep at most HELP_START_SHORTCUT_LIMIT rows across groups in group order.
  */
 export const helpShortcutGroups = <T extends HelpShortcutCommand>(
   commands: readonly T[],
 ): { scope: HelpShortcutScope; shortcuts: (T & { shortcut: string })[] }[] => {
   const groups: Record<HelpShortcutScope, (T & { shortcut: string })[]> = { everywhere: [], app: [], selection: [] };
   for (const command of commands) {
-    if (!command.shortcut) continue;
+    if (
+      !command.shortcut ||
+      !command.id ||
+      !command.title ||
+      command.id.length > HELP_SHORTCUT_ID_MAX_LENGTH ||
+      command.title.length > HELP_SHORTCUT_TITLE_MAX_LENGTH ||
+      (command.description?.length ?? 0) > HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH ||
+      command.shortcut.length > HELP_SHORTCUT_KEYS_MAX_LENGTH
+    )
+      continue;
     const scope = command.scope === "selection" ? "selection" : command.id.startsWith("cloud.") ? "everywhere" : "app";
     groups[scope].push({ ...command, shortcut: command.shortcut });
   }
@@ -62,7 +85,10 @@ export const helpShortcutGroups = <T extends HelpShortcutCommand>(
     return index < 0 ? SHELL_SHORTCUT_ORDER.length : index;
   };
   groups.everywhere.sort((a, b) => rank(a.id) - rank(b.id));
-  return (["everywhere", "app", "selection"] as const).flatMap((scope) =>
-    groups[scope].length ? [{ scope, shortcuts: groups[scope] }] : [],
-  );
+  let remaining = HELP_START_SHORTCUT_LIMIT;
+  return (["everywhere", "app", "selection"] as const).flatMap((scope) => {
+    const shortcuts = groups[scope].slice(0, remaining);
+    remaining -= shortcuts.length;
+    return shortcuts.length ? [{ scope, shortcuts }] : [];
+  });
 };