@igstack/app-catalog-frontend-core 0.9.1 → 0.9.2

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.d.ts

@@ -1,7 +1,16 @@
 import { default as React } from 'react';
 /**
- * Renders a markdown link with security attributes (opens in a new tab,
- * no referrer/opener leakage). Shared so all catalog text fields render
+ * Renders a markdown link.
+ *
+ * Internal cross-references — a relative `/app/<slug>` pointing at another
+ * catalog entry — navigate WITHIN the app via the TanStack router (same tab,
+ * no full reload), so authors can cross-link entries with plain markdown
+ * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded
+ * resources (canonical slug or a known alias); an unknown slug renders as
+ * plain text rather than a dead link.
+ *
+ * Everything else (external http/https links) opens in a new tab with
+ * `noopener noreferrer`, unchanged. Shared so all catalog text fields render
  * links identically.
  */
 export declare const MarkdownLink: ({ href, children, }: {

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.js

@@ -1,18 +1,50 @@
-import { jsx } from "react/jsx-runtime";
+import { jsx, Fragment } from "react/jsx-runtime";
+import { useRouterState, Link } from "@tanstack/react-router";
 import ReactMarkdown from "react-markdown";
+import { useAppCatalogContext } from "../../context/AppCatalogContext.js";
+const INTERNAL_APP_LINK = /^\/app\/([^/?#]+)$/;
 const MarkdownLink = ({
   href,
   children
-}) => /* @__PURE__ */ jsx(
-  "a",
-  {
-    href,
-    target: "_blank",
-    rel: "noopener noreferrer",
-    className: "text-primary hover:underline",
-    children
+}) => {
+  const { resources } = useAppCatalogContext();
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const internalMatch = href == null ? void 0 : href.match(INTERNAL_APP_LINK);
+  if (internalMatch) {
+    const slug = decodeURIComponent(internalMatch[1] ?? "");
+    const exists = resources.some(
+      (r) => {
+        var _a;
+        return r.slug === slug || ((_a = r.aliases) == null ? void 0 : _a.includes(slug));
+      }
+    );
+    if (!exists) {
+      return /* @__PURE__ */ jsx(Fragment, { children });
+    }
+    const isCurrent = pathname === `/app/${slug}`;
+    return /* @__PURE__ */ jsx(
+      Link,
+      {
+        to: "/app/$slug",
+        params: { slug },
+        search: (prev) => prev,
+        "aria-current": isCurrent ? "page" : void 0,
+        className: "text-primary hover:underline",
+        children
+      }
+    );
   }
-);
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      href,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      className: "text-primary hover:underline",
+      children
+    }
+  );
+};
 function MarkdownText({
   children,
   className

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.js.map

@@ -1 +1 @@
-{"version":3,"file":"MarkdownText.js","sources":["../../../../../../src/modules/appCatalog/ui/components/MarkdownText.tsx"],"sourcesContent":["import type React from 'react'\nimport ReactMarkdown from 'react-markdown'\n\n/**\n * Renders a markdown link with security attributes (opens in a new tab,\n * no referrer/opener leakage). Shared so all catalog text fields render\n * links identically.\n */\nexport const MarkdownLink = ({\n  href,\n  children,\n}: {\n  href?: string\n  children?: React.ReactNode\n}) => (\n  <a\n    href={href}\n    target=\"_blank\"\n    rel=\"noopener noreferrer\"\n    className=\"text-primary hover:underline\"\n  >\n    {children}\n  </a>\n)\n\n/**\n * Renders user-facing catalog text (descriptions, comments, prompts) as\n * markdown so links become clickable. Links use {@link MarkdownLink}.\n */\nexport function MarkdownText({\n  children,\n  className,\n}: {\n  children: string\n  className?: string\n}) {\n  return (\n    <span className={className}>\n      <ReactMarkdown components={{ a: MarkdownLink }}>{children}</ReactMarkdown>\n    </span>\n  )\n}\n"],"names":[],"mappings":";;AAQO,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AACF,MAIE;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,QAAO;AAAA,IACP,KAAI;AAAA,IACJ,WAAU;AAAA,IAET;AAAA,EAAA;AACH;AAOK,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAGG;AACD,SACE,oBAAC,QAAA,EAAK,WACJ,UAAA,oBAAC,eAAA,EAAc,YAAY,EAAE,GAAG,aAAA,GAAiB,SAAA,CAAS,EAAA,CAC5D;AAEJ;"}
+{"version":3,"file":"MarkdownText.js","sources":["../../../../../../src/modules/appCatalog/ui/components/MarkdownText.tsx"],"sourcesContent":["import { Link, useRouterState } from '@tanstack/react-router'\nimport type React from 'react'\nimport ReactMarkdown from 'react-markdown'\nimport { useAppCatalogContext } from '../../context/AppCatalogContext'\n\n/** Match a relative internal catalog link: `/app/<slug>` (slug only, no extra path). */\nconst INTERNAL_APP_LINK = /^\\/app\\/([^/?#]+)$/\n\n/**\n * Renders a markdown link.\n *\n * Internal cross-references — a relative `/app/<slug>` pointing at another\n * catalog entry — navigate WITHIN the app via the TanStack router (same tab,\n * no full reload), so authors can cross-link entries with plain markdown\n * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded\n * resources (canonical slug or a known alias); an unknown slug renders as\n * plain text rather than a dead link.\n *\n * Everything else (external http/https links) opens in a new tab with\n * `noopener noreferrer`, unchanged. Shared so all catalog text fields render\n * links identically.\n */\nexport const MarkdownLink = ({\n  href,\n  children,\n}: {\n  href?: string\n  children?: React.ReactNode\n}) => {\n  const { resources } = useAppCatalogContext()\n  const pathname = useRouterState({ select: (s) => s.location.pathname })\n\n  const internalMatch = href?.match(INTERNAL_APP_LINK)\n  if (internalMatch) {\n    const slug = decodeURIComponent(internalMatch[1] ?? '')\n    const exists = resources.some(\n      (r) => r.slug === slug || r.aliases?.includes(slug),\n    )\n    // Unknown slug → render plain text, never a dead internal link.\n    if (!exists) {\n      return <>{children}</>\n    }\n    const isCurrent = pathname === `/app/${slug}`\n    return (\n      <Link\n        to=\"/app/$slug\"\n        params={{ slug }}\n        search={(prev) => prev}\n        aria-current={isCurrent ? 'page' : undefined}\n        className=\"text-primary hover:underline\"\n      >\n        {children}\n      </Link>\n    )\n  }\n\n  return (\n    <a\n      href={href}\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n      className=\"text-primary hover:underline\"\n    >\n      {children}\n    </a>\n  )\n}\n\n/**\n * Renders user-facing catalog text (descriptions, comments, prompts) as\n * markdown so links become clickable. Links use {@link MarkdownLink}.\n */\nexport function MarkdownText({\n  children,\n  className,\n}: {\n  children: string\n  className?: string\n}) {\n  return (\n    <span className={className}>\n      <ReactMarkdown components={{ a: MarkdownLink }}>{children}</ReactMarkdown>\n    </span>\n  )\n}\n"],"names":[],"mappings":";;;;AAMA,MAAM,oBAAoB;AAgBnB,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AACF,MAGM;AACJ,QAAM,EAAE,UAAA,IAAc,qBAAA;AACtB,QAAM,WAAW,eAAe,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU;AAEtE,QAAM,gBAAgB,6BAAM,MAAM;AAClC,MAAI,eAAe;AACjB,UAAM,OAAO,mBAAmB,cAAc,CAAC,KAAK,EAAE;AACtD,UAAM,SAAS,UAAU;AAAA,MACvB,CAAC;;AAAM,iBAAE,SAAS,UAAQ,OAAE,YAAF,mBAAW,SAAS;AAAA;AAAA,IAAI;AAGpD,QAAI,CAAC,QAAQ;AACX,6CAAU,UAAS;AAAA,IACrB;AACA,UAAM,YAAY,aAAa,QAAQ,IAAI;AAC3C,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC,IAAG;AAAA,QACH,QAAQ,EAAE,KAAA;AAAA,QACV,QAAQ,CAAC,SAAS;AAAA,QAClB,gBAAc,YAAY,SAAS;AAAA,QACnC,WAAU;AAAA,QAET;AAAA,MAAA;AAAA,IAAA;AAAA,EAGP;AAEA,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,QAAO;AAAA,MACP,KAAI;AAAA,MACJ,WAAU;AAAA,MAET;AAAA,IAAA;AAAA,EAAA;AAGP;AAMO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAGG;AACD,SACE,oBAAC,QAAA,EAAK,WACJ,UAAA,oBAAC,eAAA,EAAc,YAAY,EAAE,GAAG,aAAA,GAAiB,SAAA,CAAS,EAAA,CAC5D;AAEJ;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-frontend-core",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Frontend core library for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -134,8 +134,8 @@
     "vite-plugin-static-copy": "^3.1.4",
     "vite-plugin-svgr": "^4.2.0",
     "vitest": "^4.1.2",
-    "@igstack/app-catalog-backend-core": "0.9.1",
-    "@igstack/app-catalog-shared-core": "0.9.1"
+    "@igstack/app-catalog-backend-core": "0.9.2",
+    "@igstack/app-catalog-shared-core": "0.9.2"
   },
   "peerDependencies": {
     "react": "19.1.2",
@@ -144,7 +144,7 @@
     "vite": "^6.3.5",
     "vite-plugin-svgr": "^4.2.0"
   },
-  "gitHead": "69c9cf1a9802f07ead88d1d97496cbabaec5ca37",
+  "gitHead": "bffb2faf1feacac02c3c49096dbb5eb18f54cd12",
   "scripts": {
     "build": "vite build",
     "build:lenient": "vite build --mode lenient",

package/src/__tests__/integration/crossRefLink.integration.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import { screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import '@testing-library/jest-dom/vitest'
+import { given } from './harness/given'
+import { magazine } from './mock-backend/magazines'
+
+// #25: when an app description references another catalog app via a relative
+// markdown link `[Name](/app/<slug>)`, it must navigate WITHIN the catalog
+// (TanStack Router, same tab) rather than opening a new browser tab. External
+// links stay `target=_blank`; links to unknown slugs render as plain text so
+// there are no dead internal links.
+describe('Cross-reference links between app entries (#25)', () => {
+  const withCrossRefApp = magazine.full(({ backendCfg }) => {
+    backendCfg.withApp({
+      slug: 'portals-hub',
+      displayName: 'Portals Hub',
+      description:
+        'See the [Jira](/app/jira) entry and the external [docs](https://example.com/docs). Also [Ghost](/app/no-such-app) which does not exist.',
+    })
+  })
+
+  it('navigates in-app (same tab, no new tab) when clicking an internal /app/<slug> link', async () => {
+    const { ui, router } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+
+    const jiraLink = screen.getByRole('link', { name: 'Jira' })
+    // Internal link must NOT open a new tab.
+    expect(jiraLink).not.toHaveAttribute('target', '_blank')
+    // It points at the router path (rendered as an href).
+    expect(jiraLink).toHaveAttribute('href', '/app/jira')
+
+    const user = userEvent.setup()
+    await user.click(jiraLink)
+
+    // In-app navigation: the router path changes and Jira's detail opens,
+    // without a full page reload / new tab.
+    await waitFor(() => {
+      expect(router.state.location.pathname).toBe('/app/jira')
+    })
+    await waitFor(() => {
+      expect(ui.app.getOpenTitle()).toContain('Jira')
+    })
+  })
+
+  it('sets aria-current="page" on an internal link that points at the open app', async () => {
+    const { ui } = await given(
+      magazine.full(({ backendCfg }) => {
+        backendCfg.withApp({
+          slug: 'self-ref',
+          displayName: 'Self Ref',
+          description: 'This links to [itself](/app/self-ref) recursively.',
+        })
+      }),
+      { initialRoute: '/app/self-ref' },
+    )
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    const selfLink = screen.getByRole('link', { name: 'itself' })
+    expect(selfLink).toHaveAttribute('aria-current', 'page')
+  })
+
+  it('renders a link to a non-existent slug as plain text (no dead link)', async () => {
+    const { ui } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    // "Ghost" text is present (as plain text merged into the paragraph)…
+    expect(screen.getAllByText(/Ghost.*does not exist/).length).toBeGreaterThan(
+      0,
+    )
+    // …but it is NOT a link (no dead internal link).
+    expect(screen.queryByRole('link', { name: 'Ghost' })).toBeNull()
+  })
+
+  it('keeps external links opening in a new tab', async () => {
+    const { ui } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    const docsLink = screen.getByRole('link', { name: 'docs' })
+    expect(docsLink).toHaveAttribute('target', '_blank')
+    expect(docsLink).toHaveAttribute('rel', expect.stringContaining('noopener'))
+    expect(docsLink).toHaveAttribute('href', 'https://example.com/docs')
+  })
+})

package/src/modules/appCatalog/ui/components/MarkdownText.tsx

@@ -1,9 +1,23 @@
+import { Link, useRouterState } from '@tanstack/react-router'
 import type React from 'react'
 import ReactMarkdown from 'react-markdown'
+import { useAppCatalogContext } from '../../context/AppCatalogContext'
+
+/** Match a relative internal catalog link: `/app/<slug>` (slug only, no extra path). */
+const INTERNAL_APP_LINK = /^\/app\/([^/?#]+)$/
 
 /**
- * Renders a markdown link with security attributes (opens in a new tab,
- * no referrer/opener leakage). Shared so all catalog text fields render
+ * Renders a markdown link.
+ *
+ * Internal cross-references — a relative `/app/<slug>` pointing at another
+ * catalog entry — navigate WITHIN the app via the TanStack router (same tab,
+ * no full reload), so authors can cross-link entries with plain markdown
+ * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded
+ * resources (canonical slug or a known alias); an unknown slug renders as
+ * plain text rather than a dead link.
+ *
+ * Everything else (external http/https links) opens in a new tab with
+ * `noopener noreferrer`, unchanged. Shared so all catalog text fields render
  * links identically.
  */
 export const MarkdownLink = ({
@@ -12,16 +26,45 @@ export const MarkdownLink = ({
 }: {
   href?: string
   children?: React.ReactNode
-}) => (
-  <a
-    href={href}
-    target="_blank"
-    rel="noopener noreferrer"
-    className="text-primary hover:underline"
-  >
-    {children}
-  </a>
-)
+}) => {
+  const { resources } = useAppCatalogContext()
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+
+  const internalMatch = href?.match(INTERNAL_APP_LINK)
+  if (internalMatch) {
+    const slug = decodeURIComponent(internalMatch[1] ?? '')
+    const exists = resources.some(
+      (r) => r.slug === slug || r.aliases?.includes(slug),
+    )
+    // Unknown slug → render plain text, never a dead internal link.
+    if (!exists) {
+      return <>{children}</>
+    }
+    const isCurrent = pathname === `/app/${slug}`
+    return (
+      <Link
+        to="/app/$slug"
+        params={{ slug }}
+        search={(prev) => prev}
+        aria-current={isCurrent ? 'page' : undefined}
+        className="text-primary hover:underline"
+      >
+        {children}
+      </Link>
+    )
+  }
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="text-primary hover:underline"
+    >
+      {children}
+    </a>
+  )
+}
 
 /**
  * Renders user-facing catalog text (descriptions, comments, prompts) as