@messagevisor/catalog 0.6.0 → 0.8.0

package/src/components/lists/EntityList.tsx

@@ -22,6 +22,8 @@ interface EntityListHighlightTerms {
   lastModified: string[];
 }
 
+const LIST_SEARCH_QUERY_DEBOUNCE_MS = 450;
+
 function matchesQuery(
   entity: EntitySummary,
   parsed: ParsedQuery,
@@ -260,6 +262,168 @@ function setSearchParam(searchParams: URLSearchParams, key: string, value?: stri
   return next;
 }
 
+const EntityListSearchControls = React.memo(function EntityListSearchControls({
+  type,
+  query,
+  firstTargetKey,
+  firstLocaleKey,
+  translationSearchEnabled,
+  onQueryCommit,
+  onHintClick,
+}: {
+  type: EntityType;
+  query: string;
+  firstTargetKey: string | undefined;
+  firstLocaleKey: string | undefined;
+  translationSearchEnabled: boolean;
+  onQueryCommit: (value: string) => void;
+  onHintClick: (hint: string) => void;
+}) {
+  const [inputValue, setInputValue] = React.useState(query);
+  const [showHints, setShowHints] = React.useState(false);
+  const debounceRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const idleRef = React.useRef<number | null>(null);
+  const animationFrameRef = React.useRef<number | null>(null);
+  const postPaintTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const hasHintsDefined =
+    getQueryHints(type, firstTargetKey, firstLocaleKey, translationSearchEnabled) !== null;
+
+  const clearPendingCommit = React.useCallback(() => {
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+      debounceRef.current = null;
+    }
+
+    if (idleRef.current !== null && "cancelIdleCallback" in window) {
+      window.cancelIdleCallback(idleRef.current);
+      idleRef.current = null;
+    }
+
+    if (animationFrameRef.current !== null) {
+      window.cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+
+    if (postPaintTimeoutRef.current) {
+      clearTimeout(postPaintTimeoutRef.current);
+      postPaintTimeoutRef.current = null;
+    }
+  }, []);
+
+  const commitAfterBrowserWork = React.useCallback(
+    (value: string) => {
+      if ("requestIdleCallback" in window) {
+        idleRef.current = window.requestIdleCallback(
+          () => {
+            idleRef.current = null;
+            onQueryCommit(value);
+          },
+          { timeout: 700 },
+        );
+        return;
+      }
+
+      animationFrameRef.current = window.requestAnimationFrame(() => {
+        animationFrameRef.current = null;
+        postPaintTimeoutRef.current = setTimeout(() => {
+          postPaintTimeoutRef.current = null;
+          onQueryCommit(value);
+        }, 0);
+      });
+    },
+    [onQueryCommit],
+  );
+
+  const scheduleQueryCommit = React.useCallback(
+    (value: string) => {
+      clearPendingCommit();
+      debounceRef.current = setTimeout(() => {
+        debounceRef.current = null;
+        commitAfterBrowserWork(value);
+      }, LIST_SEARCH_QUERY_DEBOUNCE_MS);
+    },
+    [clearPendingCommit, commitAfterBrowserWork],
+  );
+
+  const flushQueryCommit = React.useCallback(
+    (value: string) => {
+      clearPendingCommit();
+      onQueryCommit(value);
+    },
+    [clearPendingCommit, onQueryCommit],
+  );
+
+  React.useEffect(() => {
+    clearPendingCommit();
+    setInputValue(query);
+  }, [query, clearPendingCommit]);
+
+  React.useEffect(() => {
+    return () => {
+      clearPendingCommit();
+    };
+  }, [clearPendingCommit]);
+
+  return (
+    <div>
+      <div className="relative">
+        <Input
+          value={inputValue}
+          onChange={(event) => {
+            const val = event.target.value;
+            setInputValue(val);
+            scheduleQueryCommit(val);
+          }}
+          onBlur={(event) => {
+            flushQueryCommit(event.target.value);
+          }}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              flushQueryCommit(event.currentTarget.value);
+            }
+          }}
+          placeholder={`Search ${entityLabels[type].plural.toLowerCase()}...`}
+          className={hasHintsDefined ? "pr-10" : ""}
+        />
+        {hasHintsDefined && (
+          <button
+            type="button"
+            onClick={() => setShowHints((v) => !v)}
+            aria-label={showHints ? "Hide advanced search hints" : "Show advanced search hints"}
+            className={[
+              "absolute right-3 top-1/2 -translate-y-1/2 flex h-5 w-5 items-center justify-center rounded-full border text-xs font-bold transition-colors",
+              showHints
+                ? "border-primary bg-primary/10 text-primary"
+                : "border-border bg-surface text-muted hover:border-primary hover:text-primary",
+            ].join(" ")}
+          >
+            ?
+          </button>
+        )}
+      </div>
+
+      {/* Animated slide-down hints panel, aligned to input's inner text area */}
+      <div
+        className={[
+          "grid transition-all duration-200 ease-in-out",
+          showHints ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+        ].join(" ")}
+      >
+        <div className="overflow-hidden pl-5">
+          <QueryHints
+            type={type}
+            query={query}
+            firstTargetKey={firstTargetKey}
+            firstLocaleKey={firstLocaleKey}
+            translationSearchEnabled={translationSearchEnabled}
+            onHintClick={onHintClick}
+          />
+        </div>
+      </div>
+    </div>
+  );
+});
+
 // ---- Component ----
 
 export function EntityList(props: {
@@ -271,23 +435,39 @@ export function EntityList(props: {
 }) {
   const [searchParams, setSearchParams] = useSearchParams();
   const [showAll, setShowAll] = React.useState(false);
-  const [showHints, setShowHints] = React.useState(false);
   const [translationShard, setTranslationShard] = React.useState<TranslationShard | null>(null);
   const [loadedShardKey, setLoadedShardKey] = React.useState<string | null>(null);
-  const debounceRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const translationShardDebounceRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
   const query = searchParams.get("q") || "";
-  const [inputValue, setInputValue] = React.useState(query);
+  const searchParamsRef = React.useRef(searchParams);
 
-  // Sync input display when the URL query changes externally (hint clicks, navigation)
   React.useEffect(() => {
-    setInputValue(query);
-  }, [query]);
+    searchParamsRef.current = searchParams;
+  }, [searchParams]);
+
+  const commitSearchQuery = React.useCallback(
+    (value: string) => {
+      const nextQuery = value.trim() ? value : undefined;
+      if ((searchParamsRef.current.get("q") || "") === (nextQuery || "")) return;
+      React.startTransition(() => {
+        setSearchParams(setSearchParam(searchParamsRef.current, "q", nextQuery));
+      });
+    },
+    [setSearchParams],
+  );
+
+  React.useEffect(() => {
+    return () => {
+      if (translationShardDebounceRef.current) {
+        clearTimeout(translationShardDebounceRef.current);
+        translationShardDebounceRef.current = null;
+      }
+    };
+  }, []);
 
   const firstTargetKey = props.allEntities?.target?.find((e) => !e.archived)?.key;
   const firstLocaleKey = props.allEntities?.locale?.find((e) => !e.archived)?.key;
   const translationSearchEnabled = props.translationSearchEnabled === true;
-  const hasHintsDefined =
-    getQueryHints(props.type, firstTargetKey, firstLocaleKey, translationSearchEnabled) !== null;
 
   // Compute the 3-char shard prefix needed for the current query
   const _translationQual = parseQuery(query).qualifiers.find((q) => q.key === "translation");
@@ -298,7 +478,9 @@ export function EntityList(props: {
 
   // Debounced fetch: only triggers when the 3-char prefix changes
   React.useEffect(() => {
-    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (translationShardDebounceRef.current) {
+      clearTimeout(translationShardDebounceRef.current);
+    }
 
     if (!neededShardKey) {
       setTranslationShard(null);
@@ -308,8 +490,8 @@ export function EntityList(props: {
 
     if (neededShardKey === loadedShardKey) return;
 
-    debounceRef.current = setTimeout(() => {
-      debounceRef.current = null;
+    translationShardDebounceRef.current = setTimeout(() => {
+      translationShardDebounceRef.current = null;
       fetchTranslationShard(neededShardKey, props.setKey).then((data) => {
         setTranslationShard(data);
         setLoadedShardKey(neededShardKey);
@@ -317,7 +499,10 @@ export function EntityList(props: {
     }, 300);
 
     return () => {
-      if (debounceRef.current) clearTimeout(debounceRef.current);
+      if (translationShardDebounceRef.current) {
+        clearTimeout(translationShardDebounceRef.current);
+        translationShardDebounceRef.current = null;
+      }
     };
   }, [neededShardKey, loadedShardKey, props.setKey]);
   const sortDirection = getSortDirection(searchParams.get("sort"));
@@ -359,7 +544,7 @@ export function EntityList(props: {
         : current
           ? `${current} ${hint}`
           : hint;
-    setSearchParams(setSearchParam(searchParams, "q", next || undefined));
+    setSearchParams(setSearchParam(searchParamsRef.current, "q", next || undefined));
   }
 
   return (
@@ -367,56 +552,15 @@ export function EntityList(props: {
       <div className="px-6 pt-1">
         <div className="grid gap-3 md:grid-cols-[minmax(0,1fr)_auto]">
           {/* Input + slide-down hints, confined to the first column */}
-          <div>
-            <div className="relative">
-              <Input
-                value={inputValue}
-                onChange={(event) => {
-                  const val = event.target.value;
-                  setInputValue(val);
-                  setSearchParams(setSearchParam(searchParams, "q", val.trim() ? val : undefined));
-                }}
-                placeholder={`Search ${entityLabels[props.type].plural.toLowerCase()}...`}
-                className={hasHintsDefined ? "pr-10" : ""}
-              />
-              {hasHintsDefined && (
-                <button
-                  type="button"
-                  onClick={() => setShowHints((v) => !v)}
-                  aria-label={
-                    showHints ? "Hide advanced search hints" : "Show advanced search hints"
-                  }
-                  className={[
-                    "absolute right-3 top-1/2 -translate-y-1/2 flex h-5 w-5 items-center justify-center rounded-full border text-xs font-bold transition-colors",
-                    showHints
-                      ? "border-primary bg-primary/10 text-primary"
-                      : "border-border bg-surface text-muted hover:border-primary hover:text-primary",
-                  ].join(" ")}
-                >
-                  ?
-                </button>
-              )}
-            </div>
-
-            {/* Animated slide-down hints panel, aligned to input's inner text area */}
-            <div
-              className={[
-                "grid transition-all duration-200 ease-in-out",
-                showHints ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
-              ].join(" ")}
-            >
-              <div className="overflow-hidden pl-5">
-                <QueryHints
-                  type={props.type}
-                  query={query}
-                  firstTargetKey={firstTargetKey}
-                  firstLocaleKey={firstLocaleKey}
-                  translationSearchEnabled={translationSearchEnabled}
-                  onHintClick={handleHintClick}
-                />
-              </div>
-            </div>
-          </div>
+          <EntityListSearchControls
+            type={props.type}
+            query={query}
+            firstTargetKey={firstTargetKey}
+            firstLocaleKey={firstLocaleKey}
+            translationSearchEnabled={translationSearchEnabled}
+            onQueryCommit={commitSearchQuery}
+            onHintClick={handleHintClick}
+          />
 
           <button
             type="button"

package/src/node/index.spec.ts

@@ -9,7 +9,12 @@ import { Datasource } from "../../../core/src/datasource";
 import { resolveExamples } from "../../../core/src/examples";
 import { findDuplicateTranslations } from "../../../core/src/find-duplicates";
 import { getProjectSetExecutions } from "../../../core/src/sets";
-import { createCatalogApi, createCatalogPlugin, type CatalogRuntime } from "./index";
+import {
+  __catalogDevInternals,
+  createCatalogApi,
+  createCatalogPlugin,
+  type CatalogRuntime,
+} from "./index";
 
 const catalogApi = createCatalogApi({
   mergeFormats,
@@ -272,6 +277,12 @@ describe("catalog", function () {
     await expect(
       pathExists(root, "catalog-out/data/root/duplicates/locales/en-US.json"),
     ).resolves.toBe(false);
+    await expect(
+      pathExists(root, "catalog-out/data/root/history/message/common.welcome/page-1.json"),
+    ).resolves.toBe(false);
+    await expect(
+      pathExists(root, "catalog-out/data/root/history/message/common.draft/page-1.json"),
+    ).resolves.toBe(false);
     expect(index.counts.message).toBe(2);
     expect(
       index.entities.message.find((entry: any) => entry.key === "common.welcome").targets,
@@ -486,6 +497,8 @@ describe("catalog", function () {
     expect(output).toContain("Root catalog");
     expect(output).toContain("Processing entities");
     expect(output).toContain("Writing messages");
+    expect(output).toContain("Writing message details");
+    expect(output).toContain("Writing message history pages");
     expect(output).toContain("Writing manifest");
     expect(output).toContain("Catalog exported to catalog-out");
     expect(output).toContain("Time:");
@@ -514,6 +527,62 @@ describe("catalog", function () {
     expect(output).toContain("Building translation search shards");
   });
 
+  it("exports many messages deterministically without empty history files", async function () {
+    const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-catalog-"));
+    roots.push(root);
+
+    await writeFile(root, "messagevisor.config.js", "module.exports = {};\n");
+    await writeFile(root, "locales/en.yml", "description: English\n");
+
+    const messageCount = 1200;
+    await Promise.all(
+      Array.from({ length: messageCount }, (_, index) => {
+        const key = String(index).padStart(4, "0");
+        return writeFile(
+          root,
+          `messages/bulk/${key}.yml`,
+          `description: Bulk ${key}\ntranslations:\n  en: Bulk ${key}\n`,
+        );
+      }),
+    );
+
+    const projectConfig = getProjectConfig(root);
+    const datasource = new Datasource(projectConfig, root);
+
+    const output = await captureConsoleLog(async () => {
+      await catalogApi.exportCatalog(root, projectConfig, datasource, {
+        outDir: "catalog-out",
+        copyAssets: false,
+      });
+    });
+
+    const index = await readJson<any>(root, "catalog-out/data/root/index.json");
+    const firstMessage = await readJson<any>(
+      root,
+      "catalog-out/data/root/entities/message/bulk.0000.json",
+    );
+    const lastMessage = await readJson<any>(
+      root,
+      "catalog-out/data/root/entities/message/bulk.1199.json",
+    );
+
+    expect(index.counts.message).toBe(messageCount);
+    expect(index.entities.message.slice(0, 3).map((entry: any) => entry.key)).toEqual([
+      "bulk.0000",
+      "bulk.0001",
+      "bulk.0002",
+    ]);
+    expect(firstMessage.sourcePath).toBe("messages/bulk/0000.yml");
+    expect(lastMessage.translations).toEqual([
+      { locale: "en", value: "Bulk 1199", source: "direct" },
+    ]);
+    await expect(
+      pathExists(root, "catalog-out/data/root/history/message/bulk.0000/page-1.json"),
+    ).resolves.toBe(false);
+    expect(output).toContain("1200 messages");
+    expect(output).toContain("1200 empty histories skipped");
+  });
+
   it("streams Git history into project, entity, and last-modified catalog data", async function () {
     const root = await createProject();
     roots.push(root);
@@ -583,9 +652,12 @@ describe("catalog", function () {
       ]),
     );
     expect(messageHistory.entries).toHaveLength(2);
-    expect(spacedMessageHistory.entries[0].entities).toEqual(
-      expect.arrayContaining([{ type: "message", key: "common.with space" }]),
-    );
+    expect(messageHistory.entries[0].entities).toEqual([
+      { type: "message", key: "common.welcome" },
+    ]);
+    expect(spacedMessageHistory.entries[0].entities).toEqual([
+      { type: "message", key: "common.with space" },
+    ]);
     expect(message.lastModified).toMatchObject({
       author: "Catalog Tester",
       commit: projectHistory.entries[0].commit,
@@ -597,6 +669,67 @@ describe("catalog", function () {
     });
   });
 
+  it("keeps large commit entity lists out of per-entity history files", async function () {
+    const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-catalog-"));
+    roots.push(root);
+
+    await writeFile(root, "messagevisor.config.js", "module.exports = {};\n");
+    await writeFile(root, "locales/en.yml", "description: English\n");
+
+    const messageCount = 1200;
+    await Promise.all(
+      Array.from({ length: messageCount }, (_, index) => {
+        const key = String(index).padStart(4, "0");
+        return writeFile(
+          root,
+          `messages/bulk/${key}.yml`,
+          `description: Bulk ${key}\ntranslations:\n  en: Bulk ${key}\n`,
+        );
+      }),
+    );
+
+    git(root, ["init"]);
+    git(root, ["add", "."]);
+    gitCommit(root, "large message import");
+
+    const projectConfig = getProjectConfig(root);
+    const datasource = new Datasource(projectConfig, root);
+
+    await catalogApi.exportCatalog(root, projectConfig, datasource, {
+      outDir: "catalog-out",
+      copyAssets: false,
+    });
+
+    const projectHistory = await readJson<any>(
+      root,
+      "catalog-out/data/project/history/page-1.json",
+    );
+    const firstMessageHistory = await readJson<any>(
+      root,
+      "catalog-out/data/root/history/message/bulk.0000/page-1.json",
+    );
+    const lastMessageHistory = await readJson<any>(
+      root,
+      "catalog-out/data/root/history/message/bulk.1199/page-1.json",
+    );
+
+    expect(projectHistory.entries[0].entities).toHaveLength(messageCount + 1);
+    expect(projectHistory.entries[0].entities).toEqual(
+      expect.arrayContaining([
+        { type: "locale", key: "en" },
+        { type: "message", key: "bulk.0000" },
+        { type: "message", key: "bulk.1199" },
+      ]),
+    );
+    expect(firstMessageHistory.entries[0]).toMatchObject({
+      commit: projectHistory.entries[0].commit,
+      author: projectHistory.entries[0].author,
+      timestamp: projectHistory.entries[0].timestamp,
+      entities: [{ type: "message", key: "bulk.0000" }],
+    });
+    expect(lastMessageHistory.entries[0].entities).toEqual([{ type: "message", key: "bulk.1199" }]);
+  });
+
   it("exports branch-aware repository links and hash router mode when requested", async function () {
     const root = await createProject();
     roots.push(root);
@@ -1046,6 +1179,104 @@ describe("catalog", function () {
 
     expect(viteConfigSource).toContain('base: "/"');
   });
+
+  it("watches only catalog input roots in dev mode", async function () {
+    const root = await createProject();
+    roots.push(root);
+    const projectConfig = getProjectConfig(root);
+
+    const watchPaths = __catalogDevInternals.getCatalogInputWatchPaths(root, projectConfig);
+
+    expect(watchPaths).toEqual(
+      expect.arrayContaining([
+        path.join(root, "messagevisor.config.js"),
+        projectConfig.localesDirectoryPath,
+        projectConfig.messagesDirectoryPath,
+        projectConfig.attributesDirectoryPath,
+        projectConfig.segmentsDirectoryPath,
+        projectConfig.targetsDirectoryPath,
+        projectConfig.testsDirectoryPath,
+      ]),
+    );
+    expect(watchPaths).not.toContain(projectConfig.catalogDirectoryPath);
+    expect(watchPaths).not.toContain(path.join(root, "node_modules"));
+  });
+
+  it("plans incremental message rebuilds only for safe dev changes", async function () {
+    const root = await createProject();
+    roots.push(root);
+    const projectConfig = getProjectConfig(root);
+    const messagePath = path.join(root, "messages/common/welcome.yml");
+    const localePath = path.join(root, "locales/en-US.yml");
+
+    expect(
+      __catalogDevInternals.classifyCatalogDevChanges(root, projectConfig, [messagePath], {
+        withTranslationSearch: false,
+        withDuplicates: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        kind: "message",
+        messageKeys: ["common.welcome"],
+      }),
+    );
+
+    expect(
+      __catalogDevInternals.classifyCatalogDevChanges(root, projectConfig, [messagePath], {
+        withTranslationSearch: true,
+        withDuplicates: false,
+      }),
+    ).toEqual(expect.objectContaining({ kind: "full" }));
+
+    expect(
+      __catalogDevInternals.classifyCatalogDevChanges(root, projectConfig, [localePath], {
+        withTranslationSearch: false,
+        withDuplicates: false,
+      }),
+    ).toEqual(expect.objectContaining({ kind: "full" }));
+  });
+
+  it("plans set-scoped dev rebuilds for set project input changes", async function () {
+    const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-catalog-"));
+    roots.push(root);
+
+    await writeFile(root, "messagevisor.config.js", "module.exports = { sets: true };\n");
+    await writeFile(root, "sets/storefront/locales/en.yml", "description: English\n");
+    await writeFile(
+      root,
+      "sets/storefront/messages/common/welcome.yml",
+      "description: Welcome\ntranslations:\n  en: Welcome\n",
+    );
+
+    const projectConfig = getProjectConfig(root);
+    const localePath = path.join(root, "sets/storefront/locales/en.yml");
+    const messagePath = path.join(root, "sets/storefront/messages/common/welcome.yml");
+
+    expect(__catalogDevInternals.getCatalogInputWatchPaths(root, projectConfig)).toEqual(
+      expect.arrayContaining([
+        path.join(root, "messagevisor.config.js"),
+        projectConfig.setsDirectoryPath,
+      ]),
+    );
+    expect(
+      __catalogDevInternals.classifyCatalogDevChanges(root, projectConfig, [messagePath], {
+        withTranslationSearch: false,
+        withDuplicates: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        kind: "message",
+        set: "storefront",
+        messageKeys: ["common.welcome"],
+      }),
+    );
+    expect(
+      __catalogDevInternals.classifyCatalogDevChanges(root, projectConfig, [localePath], {
+        withTranslationSearch: false,
+        withDuplicates: false,
+      }),
+    ).toEqual(expect.objectContaining({ kind: "set", set: "storefront" }));
+  });
 });
 
 describe("catalog plugin", function () {