@messagevisor/catalog 0.0.1 → 0.1.0

package/src/components/lists/EntityList.tsx

@@ -0,0 +1,451 @@
+import * as React from "react";
+import { Link, useSearchParams } from "react-router-dom";
+
+import type { TranslationShard } from "../../api";
+import { fetchTranslationShard } from "../../api";
+import type { EntitySummary, EntityType } from "../../types";
+import { entityLabels, getEntityRoute } from "../../entityTypes";
+import { Badge } from "../ui/Badge";
+import { EmptyState } from "../ui/EmptyState";
+import { Input } from "../ui/Input";
+import { Button } from "../ui/Button";
+import { CATALOG_LIST_INITIAL_LIMIT } from "../../config";
+import type { ParsedQuery } from "../../utils/searchQuery";
+import { parseQuery } from "../../utils/searchQuery";
+
+function matchesQuery(
+  entity: EntitySummary,
+  parsed: ParsedQuery,
+  translationShard: TranslationShard | null,
+): boolean {
+  const { freeText, qualifiers } = parsed;
+
+  // Free text: key only
+  if (freeText.length > 0) {
+    const key = entity.key.toLowerCase();
+    if (!freeText.every((term) => key.includes(term))) return false;
+  }
+
+  const hasOverrides = qualifiers.some((q) => q.key === "has" && q.value === "overrides");
+  const localeQuals = qualifiers
+    .filter((q) => q.key === "locale")
+    .map((q) => q.value.toLowerCase());
+
+  for (const q of qualifiers) {
+    switch (q.key) {
+      case "description": {
+        const desc = (entity.description || "").toLowerCase();
+        if (!desc.includes(q.value.toLowerCase())) return false;
+        break;
+      }
+      case "target": {
+        const targets = (entity.targets || []).map((s) => s.toLowerCase());
+        if (!targets.includes(q.value.toLowerCase())) return false;
+        break;
+      }
+      case "is": {
+        if (q.value === "deprecated" && !entity.deprecated) return false;
+        if (q.value === "archived" && !entity.archived) return false;
+        break;
+      }
+      case "has": {
+        if (q.value === "overrides") {
+          if (localeQuals.length > 0) {
+            // has:overrides locale:X — overrides must cover that locale
+            const overrideLocales = (entity.overrideLocales || []).map((l) => l.toLowerCase());
+            if (!localeQuals.every((l) => overrideLocales.includes(l))) return false;
+          } else {
+            if (!entity.overrideLocales?.length) return false;
+          }
+        }
+        break;
+      }
+      case "locale": {
+        // Standalone locale: — direct translations only; handled by has:overrides when combined
+        if (!hasOverrides) {
+          const locales = (entity.locales || []).map((l) => l.toLowerCase());
+          if (!locales.includes(q.value.toLowerCase())) return false;
+        }
+        break;
+      }
+      case "translation": {
+        if (q.value.length < 3) return true; // require 3+ chars; don't filter otherwise
+        if (!translationShard) return true; // optimistically include while loading
+        const values = translationShard[entity.key];
+        if (!values || values.length === 0) return false;
+        if (q.value.length === 3) break; // shard presence is sufficient for exact 3-char terms
+        const term = q.value.toLowerCase();
+        if (!values.some((v) => v.includes(term))) return false; // values are pre-lowercased
+        break;
+      }
+    }
+  }
+
+  return true;
+}
+
+// ---- Query hints ----
+
+function getQueryHints(
+  type: EntityType,
+  firstTargetKey: string | undefined,
+  firstLocaleKey: string | undefined,
+): string[] | null {
+  const target = firstTargetKey;
+  const locale = firstLocaleKey;
+
+  if (type === "message") {
+    return [
+      'translation:"keyword"',
+      ...(target ? [`target:${target}`] : []),
+      ...(locale ? [`locale:${locale}`] : []),
+      'description:"keyword"',
+      "has:overrides",
+      ...(locale ? [`has:overrides locale:${locale}`] : ["has:overrides"]),
+      "is:deprecated",
+      "is:archived",
+    ];
+  }
+
+  return null;
+}
+
+function QueryHints({
+  type,
+  query,
+  firstTargetKey,
+  firstLocaleKey,
+  onHintClick,
+}: {
+  type: EntityType;
+  query: string;
+  firstTargetKey: string | undefined;
+  firstLocaleKey: string | undefined;
+  onHintClick: (hint: string) => void;
+}) {
+  const hints = getQueryHints(type, firstTargetKey, firstLocaleKey);
+  if (!hints) return null;
+
+  return (
+    <div className="flex flex-wrap items-center gap-x-2 gap-y-1.5 pt-2 text-xs text-muted">
+      <span className="shrink-0">Try:</span>
+      {hints.map((hint) => {
+        const isActive = query
+          .trim()
+          .split(/\s+/)
+          .some((t) => t.toLowerCase() === hint.toLowerCase());
+        return (
+          <button
+            key={hint}
+            type="button"
+            onClick={() => onHintClick(hint)}
+            className={[
+              "cursor-pointer rounded px-1.5 py-0.5 font-mono transition-colors",
+              isActive ? "bg-primary/10 text-primary" : "bg-elevated text-muted hover:text-text",
+            ].join(" ")}
+          >
+            {hint}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+// ---- Helpers ----
+
+function getStatusBadges(entity: EntitySummary) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      {entity.archived && <Badge tone="danger">archived</Badge>}
+      {entity.deprecated && <Badge tone="warning">deprecated</Badge>}
+    </div>
+  );
+}
+
+function LastModified(props: { entity: EntitySummary }) {
+  if (!props.entity.lastModified) {
+    return <span>Last modified n/a</span>;
+  }
+
+  const date = new Date(props.entity.lastModified.timestamp);
+  const formattedDate = Number.isNaN(date.getTime())
+    ? props.entity.lastModified.timestamp
+    : new Intl.DateTimeFormat(undefined, {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+      }).format(date);
+
+  return (
+    <span>
+      Last modified by <span className="font-semibold">{props.entity.lastModified.author}</span> on{" "}
+      {formattedDate}
+    </span>
+  );
+}
+
+function getRelationshipBadges(type: EntityType, entity: EntitySummary) {
+  if (type === "target") {
+    return [`${entity.messageCount || 0} ${entity.messageCount === 1 ? "message" : "messages"}`];
+  }
+
+  return entity.targets || [];
+}
+
+function getSortDirection(sortValue: string | null) {
+  if (!sortValue || sortValue === "name" || sortValue === "name:asc" || sortValue === "asc") {
+    return "asc";
+  }
+
+  if (sortValue === "-name" || sortValue === "name:desc" || sortValue === "desc") {
+    return "desc";
+  }
+
+  return "asc";
+}
+
+function setSearchParam(searchParams: URLSearchParams, key: string, value?: string) {
+  const next = new URLSearchParams(searchParams);
+
+  if (!value) {
+    next.delete(key);
+  } else {
+    next.set(key, value);
+  }
+
+  return next;
+}
+
+// ---- Component ----
+
+export function EntityList(props: {
+  type: EntityType;
+  entities: EntitySummary[];
+  setKey?: string;
+  allEntities?: Record<EntityType, EntitySummary[]>;
+}) {
+  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 query = searchParams.get("q") || "";
+  const [inputValue, setInputValue] = React.useState(query);
+
+  // Sync input display when the URL query changes externally (hint clicks, navigation)
+  React.useEffect(() => {
+    setInputValue(query);
+  }, [query]);
+
+  const firstTargetKey = props.allEntities?.target?.find((e) => !e.archived)?.key;
+  const firstLocaleKey = props.allEntities?.locale?.find((e) => !e.archived)?.key;
+  const hasHintsDefined = getQueryHints(props.type, firstTargetKey, firstLocaleKey) !== null;
+
+  // Compute the 3-char shard prefix needed for the current query
+  const _translationQual = parseQuery(query).qualifiers.find((q) => q.key === "translation");
+  const neededShardKey =
+    _translationQual && _translationQual.value.length >= 3
+      ? _translationQual.value.slice(0, 3).toLowerCase()
+      : null;
+
+  // Debounced fetch: only triggers when the 3-char prefix changes
+  React.useEffect(() => {
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+
+    if (!neededShardKey) {
+      setTranslationShard(null);
+      setLoadedShardKey(null);
+      return;
+    }
+
+    if (neededShardKey === loadedShardKey) return;
+
+    debounceRef.current = setTimeout(() => {
+      debounceRef.current = null;
+      fetchTranslationShard(neededShardKey, props.setKey).then((data) => {
+        setTranslationShard(data);
+        setLoadedShardKey(neededShardKey);
+      });
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, [neededShardKey, loadedShardKey, props.setKey]);
+  const sortDirection = getSortDirection(searchParams.get("sort"));
+
+  // Pass shard to matchesQuery only when the loaded shard matches what's needed
+  const activeShard = loadedShardKey === neededShardKey ? translationShard : null;
+
+  const filtered = React.useMemo(() => {
+    const parsed = parseQuery(query);
+    const hasQuery = query.trim().length > 0;
+
+    const matching = props.entities.filter((entity) => {
+      if (!hasQuery) return true;
+      return matchesQuery(entity, parsed, activeShard);
+    });
+
+    return matching.slice().sort((left, right) => {
+      const result = left.key.localeCompare(left.key === right.key ? "" : right.key);
+      return sortDirection === "desc" ? result * -1 : result;
+    });
+  }, [query, props.entities, sortDirection, activeShard]);
+
+  const visible = showAll ? filtered : filtered.slice(0, CATALOG_LIST_INITIAL_LIMIT);
+  const hasHiddenEntities = filtered.length > CATALOG_LIST_INITIAL_LIMIT && !showAll;
+
+  React.useEffect(() => {
+    setShowAll(false);
+  }, [query, sortDirection, props.type, props.setKey]);
+
+  function handleHintClick(hint: string) {
+    const current = query.trim();
+    // Toggle: if the exact hint token is already in the query, remove it; otherwise append
+    const tokens = current.split(/\s+/).filter(Boolean);
+    const idx = tokens.findIndex((t) => t.toLowerCase() === hint.toLowerCase());
+    const next =
+      idx !== -1
+        ? tokens.filter((_, i) => i !== idx).join(" ")
+        : current
+          ? `${current} ${hint}`
+          : hint;
+    setSearchParams(setSearchParam(searchParams, "q", next || undefined));
+  }
+
+  return (
+    <div className="space-y-4">
+      <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}
+                  onHintClick={handleHintClick}
+                />
+              </div>
+            </div>
+          </div>
+
+          <button
+            type="button"
+            className="inline-flex h-[46px] w-fit max-w-full cursor-pointer items-center gap-2 self-start rounded-full border border-border bg-surface px-3 py-2 text-left text-sm font-semibold text-muted outline-none focus-visible:ring-2 focus-visible:ring-ring md:justify-self-end"
+            onClick={() =>
+              setSearchParams(
+                setSearchParam(
+                  searchParams,
+                  "sort",
+                  sortDirection === "desc" ? undefined : "-name",
+                ),
+              )
+            }
+            aria-label={
+              sortDirection === "desc"
+                ? "Sorted Z-A by name. Activate to sort A-Z."
+                : "Sorted A-Z by name. Activate to sort Z-A."
+            }
+          >
+            <span>Sort</span>
+            <span className="whitespace-nowrap font-bold text-text">
+              {sortDirection === "desc" ? "Z-A" : "A-Z"}
+            </span>
+          </button>
+        </div>
+      </div>
+
+      {filtered.length === 0 && <EmptyState title="No results found" />}
+
+      <div className="divide-y divide-border bg-surface">
+        {visible.map((entity) => (
+          <Link
+            key={entity.key}
+            to={getEntityRoute(props.type, entity.key, props.setKey)}
+            className="block px-6 py-3 hover:bg-elevated"
+          >
+            <div className="flex flex-col justify-between gap-3 md:flex-row md:items-start">
+              <div className="min-w-0 flex-1">
+                <div className="flex flex-col justify-between gap-2 md:flex-row md:items-start">
+                  <div className="min-w-0">
+                    <div className="font-bold text-primary">{entity.key}</div>
+                    <div className="mt-1 truncate text-sm text-muted">
+                      {entity.description || "No description"}
+                    </div>
+                  </div>
+                  <div className="shrink-0">{getStatusBadges(entity)}</div>
+                </div>
+                <div className="mt-2 flex flex-col gap-2 text-xs text-muted md:flex-row md:items-center md:justify-between">
+                  <div className="flex flex-wrap gap-2">
+                    {getRelationshipBadges(props.type, entity).map((label) => (
+                      <Badge key={label}>{label}</Badge>
+                    ))}
+                  </div>
+                  <span className="shrink-0 md:text-right">
+                    <LastModified entity={entity} />
+                  </span>
+                </div>
+              </div>
+            </div>
+          </Link>
+        ))}
+      </div>
+
+      <div className="space-y-4 px-6 pb-6">
+        <p className="text-center text-sm text-muted">
+          {visible.length} of {filtered.length} {entityLabels[props.type].plural.toLowerCase()}
+          {filtered.length !== props.entities.length ? ` (${props.entities.length} total)` : ""}
+        </p>
+
+        {hasHiddenEntities && (
+          <div className="flex justify-center">
+            <Button onClick={() => setShowAll(true)}>
+              Load all {filtered.length} {entityLabels[props.type].plural.toLowerCase()}
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/ui/Badge.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+
+type BadgeTone = "neutral" | "success" | "warning" | "danger" | "primary";
+
+const toneClasses: Record<BadgeTone, string> = {
+  neutral: "border-pill bg-pill text-text",
+  success: "border-success-outline bg-success-surface text-text",
+  warning: "border-warning-outline bg-warning-surface text-text",
+  danger: "border-danger-outline bg-danger-surface text-danger",
+  primary: "border-pill bg-pill text-text",
+};
+
+export function Badge(props: { children: ReactNode; tone?: BadgeTone }) {
+  return (
+    <span
+      className={`inline-flex rounded-full border px-2 py-0.5 text-xs font-medium ${toneClasses[props.tone || "neutral"]}`}
+    >
+      {props.children}
+    </span>
+  );
+}

package/src/components/ui/Button.tsx

@@ -0,0 +1,12 @@
+import * as React from "react";
+
+type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+export function Button({ className = "", ...props }: ButtonProps) {
+  return (
+    <button
+      className={`rounded border border-border bg-elevated px-4 py-2 text-sm font-bold text-muted shadow-sm hover:bg-background ${className}`}
+      {...props}
+    />
+  );
+}

package/src/components/ui/Card.tsx

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+
+import { themeClasses } from "../../theme";
+
+export function Card(props: { children: ReactNode; className?: string }) {
+  return (
+    <section className={`${themeClasses.panel} ${props.className || ""}`}>{props.children}</section>
+  );
+}

package/src/components/ui/CodeBlock.tsx

@@ -0,0 +1,7 @@
+export function CodeBlock(props: { value: unknown }) {
+  return (
+    <pre className="max-w-full whitespace-pre-wrap rounded border border-border bg-elevated p-4 text-xs text-text [overflow-wrap:anywhere]">
+      {typeof props.value === "string" ? props.value : JSON.stringify(props.value, null, 2)}
+    </pre>
+  );
+}

package/src/components/ui/EmptyState.tsx

@@ -0,0 +1,8 @@
+export function EmptyState(props: { title: string; description?: string }) {
+  return (
+    <div className="mx-6 rounded border-2 border-warning-outline bg-warning-surface p-4 text-center text-text">
+      <p className="font-medium">{props.title}</p>
+      {props.description && <p className="mt-1 text-sm text-muted">{props.description}</p>}
+    </div>
+  );
+}

package/src/components/ui/Input.tsx

@@ -0,0 +1,12 @@
+import * as React from "react";
+
+type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
+
+export function Input({ className = "", ...props }: InputProps) {
+  return (
+    <input
+      className={`w-full rounded-full border border-border bg-surface px-5 py-2 text-xl text-text outline-none placeholder:text-placeholder focus:border-primary ${className}`}
+      {...props}
+    />
+  );
+}

package/src/components/ui/LabelValueBadge.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+import { Link } from "react-router-dom";
+
+type LabelValueBadgeTone = "neutral" | "inheritance" | "override";
+
+const toneClasses: Record<LabelValueBadgeTone, { label: string; value: string; link: string }> = {
+  neutral: {
+    label: "bg-elevated text-muted",
+    value: "bg-surface text-text",
+    link: "text-primary hover:underline",
+  },
+  inheritance: {
+    label: "bg-elevated text-muted",
+    value: "bg-surface text-text",
+    link: "text-primary hover:underline",
+  },
+  override: {
+    label: "bg-pill text-text",
+    value: "bg-surface text-text",
+    link: "text-primary hover:underline",
+  },
+};
+
+export function LabelValueBadge(props: {
+  label: ReactNode;
+  value: ReactNode;
+  to?: string;
+  tone?: LabelValueBadgeTone;
+  compact?: boolean;
+}) {
+  const tone = toneClasses[props.tone || "neutral"];
+  const valueContent = props.to ? (
+    <Link to={props.to} className={`font-medium ${tone.link}`}>
+      {props.value}
+    </Link>
+  ) : (
+    <span className="font-medium text-text">{props.value}</span>
+  );
+
+  return (
+    <span
+      className={[
+        "inline-flex overflow-hidden rounded-md border border-border shadow-sm",
+        props.compact ? "text-[10px] leading-4" : "text-xs",
+      ].join(" ")}
+    >
+      <span className={`${props.compact ? "px-1.5 py-px" : "px-2 py-1"} ${tone.label}`}>
+        {props.label}
+      </span>
+      <span className={`${props.compact ? "px-1.5 py-px" : "px-2 py-1"} ${tone.value}`}>
+        {valueContent}
+      </span>
+    </span>
+  );
+}

package/src/config.ts

@@ -0,0 +1,2 @@
+export const CATALOG_LIST_INITIAL_LIMIT = 1000;
+export const CATALOG_HISTORY_VISIBLE_ENTITY_LIMIT = 10;

package/src/context/CatalogContext.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+import { fetchManifest } from "../api";
+import type { CatalogManifest } from "../types";
+
+interface CatalogContextValue {
+  manifest: CatalogManifest;
+}
+
+const CatalogContext = React.createContext<CatalogContextValue | null>(null);
+
+export function CatalogProvider(props: {
+  children: React.ReactNode;
+  initialManifest?: CatalogManifest;
+}) {
+  const [manifest, setManifest] = React.useState<CatalogManifest | null>(
+    props.initialManifest || null,
+  );
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (props.initialManifest) {
+      return;
+    }
+
+    fetchManifest()
+      .then(setManifest)
+      .catch((err: Error) => setError(err.message));
+  }, [props.initialManifest]);
+
+  if (error) {
+    return <div className="p-8 text-danger">{error}</div>;
+  }
+
+  if (!manifest) {
+    return <div className="p-8 text-muted">Loading catalog...</div>;
+  }
+
+  return <CatalogContext.Provider value={{ manifest }}>{props.children}</CatalogContext.Provider>;
+}
+
+export function useCatalog() {
+  const context = React.useContext(CatalogContext);
+
+  if (!context) {
+    throw new Error("useCatalog must be used inside CatalogProvider.");
+  }
+
+  return context;
+}

package/src/entityTypes.ts

@@ -0,0 +1,49 @@
+import type { EntityPath, EntityType } from "./types";
+
+export const entityPaths: EntityPath[] = [
+  "messages",
+  "locales",
+  "attributes",
+  "segments",
+  "targets",
+];
+
+export const entityPathToType: Record<EntityPath, EntityType> = {
+  locales: "locale",
+  messages: "message",
+  attributes: "attribute",
+  segments: "segment",
+  targets: "target",
+};
+
+export const entityTypeToPath: Record<EntityType, EntityPath> = {
+  locale: "locales",
+  message: "messages",
+  attribute: "attributes",
+  segment: "segments",
+  target: "targets",
+};
+
+export const entityLabels: Record<EntityType, { singular: string; plural: string }> = {
+  locale: { singular: "Locale", plural: "Locales" },
+  message: { singular: "Message", plural: "Messages" },
+  attribute: { singular: "Attribute", plural: "Attributes" },
+  segment: { singular: "Segment", plural: "Segments" },
+  target: { singular: "Target", plural: "Targets" },
+};
+
+export function encodeRouteSegment(value: string) {
+  return encodeURIComponent(value);
+}
+
+export function getBasePath(setKey?: string) {
+  return setKey ? `/sets/${encodeRouteSegment(setKey)}` : "";
+}
+
+export function getEntityRoute(type: EntityType, key: string, setKey?: string) {
+  return `${getBasePath(setKey)}/${entityTypeToPath[type]}/${encodeRouteSegment(key)}`;
+}
+
+export function getDataBasePath(setKey?: string) {
+  return setKey ? `/data/sets/${encodeRouteSegment(setKey)}` : "/data/root";
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./node";