@cobaltcore-dev/aurora 0.7.0 → 0.8.1

package/README.md

@@ -114,13 +114,14 @@ await server.listen({ host: "0.0.0.0", port: 4000 })
 
 ### `<AuroraApp />`
 
-| Prop            | Type                            | Default          | Description                                        |
-| --------------- | ------------------------------- | ---------------- | -------------------------------------------------- |
-| `bffEndpoint`   | `string`                        | `"/polaris-bff"` | Must match the server's `bffEndpoint`              |
-| `theme`         | `"theme-light" \| "theme-dark"` | `"theme-light"`  | Initial theme                                      |
-| `onThemeChange` | `(theme) => void`               | —                | Called when the user toggles the theme             |
-| `appName`       | `string`                        | `"Aurora"`       | App name shown in the header breadcrumb and logo   |
-| `slots`         | `Slots`                         | —                | Optional UI extension points — see [Slots](#slots) |
+| Prop            | Type                            | Default          | Description                                                             |
+| --------------- | ------------------------------- | ---------------- | ----------------------------------------------------------------------- |
+| `bffEndpoint`   | `string`                        | `"/polaris-bff"` | Must match the server's `bffEndpoint`                                   |
+| `theme`         | `"theme-light" \| "theme-dark"` | `"theme-light"`  | Initial theme                                                           |
+| `onThemeChange` | `(theme) => void`               | —                | Called when the user toggles the theme                                  |
+| `appName`       | `string`                        | `"Aurora"`       | App name shown in the header breadcrumb and logo                        |
+| `slots`         | `Slots`                         | —                | Optional UI extension points — see [Slots](#slots)                      |
+| `onTrackEvent`  | `OnTrackEventCallback`          | —                | Called on user interactions for analytics — see [Analytics](#analytics) |
 
 ## Slots
 
@@ -178,6 +179,99 @@ function MyBanner(_props: SlotProps) {
 }
 ```
 
+## Analytics
+
+Aurora provides an optional `onTrackEvent` callback to track user interactions and feature usage. The API is source-agnostic, supporting various event types like navigation, link clicks, modals, and more.
+
+### Basic usage
+
+```tsx
+import { AuroraApp, type TrackEventPayload } from "@cobaltcore-dev/aurora/client"
+
+function trackEvent(payload: TrackEventPayload) {
+  // Router navigation example:
+  // payload.source = "router"
+  // payload.action = "/_auth/projects/$projectId/compute/images"
+  // payload.metadata = { pathname: "/projects/abc/compute/images", search: "?tab=details", section: "compute", service: "images" }
+
+  sendAnalytics("user-interaction", {
+    source: payload.source,
+    action: payload.action,
+    ...payload.metadata,
+    timestamp: Date.now(),
+  })
+}
+
+;<AuroraApp bffEndpoint="/polaris-bff" onTrackEvent={trackEvent} />
+```
+
+### TrackEventPayload
+
+The callback receives a `TrackEventPayload` object with the following fields:
+
+| Field      | Type                                                       | Description                                                              |
+| ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `source`   | `string`                                                   | Event source (e.g., "router", "external-link", "modal")                  |
+| `action`   | `string`                                                   | Action identifier (e.g., route ID, button name, link URL)                |
+| `metadata` | `Record<string, string \| number \| boolean \| undefined>` | Source-specific context (pathname, section, service, href, target, etc.) |
+
+### Built-in tracking sources
+
+#### Router navigation (`source: "router"`)
+
+Automatically tracked when users navigate between routes. Fires on every route change via TanStack Router's `onResolved` event.
+
+- **`action`**: Route ID (e.g., `"/_auth/projects/$projectId/compute/images"`)
+- **`metadata`**: Always includes `pathname`; includes `search` (query string) when present; optionally includes `section` and `service` if the route defines them in `staticData`
+
+**Example event:**
+
+```javascript
+{
+  source: "router",
+  action: "/_auth/projects/$projectId/compute/images",
+  metadata: {
+    pathname: "/projects/my-project/compute/images",
+    search: "?memberStatus=accepted",  // Query string, undefined if empty
+    section: "compute",    // Optional: from route staticData
+    service: "images"      // Optional: from route staticData
+  }
+}
+```
+
+### Extending with custom tracking
+
+The `onTrackEvent` callback is available in the router context, allowing any component to track custom interactions:
+
+```tsx
+import { useRouteContext } from "@tanstack/react-router"
+
+function MyComponent() {
+  const { onTrackEvent } = useRouteContext()
+
+  const handleExternalLinkClick = (href: string) => {
+    onTrackEvent?.({
+      source: "external-link",
+      action: href,
+      metadata: { target: "_blank" },
+    })
+  }
+
+  return (
+    <a href="https://docs.example.com" onClick={() => handleExternalLinkClick("https://docs.example.com")}>
+      Docs
+    </a>
+  )
+}
+```
+
+### Implementation notes
+
+- Router events are tracked via subscription to TanStack Router's `onResolved` event
+- Automatic deduplication - fires once per navigation
+- Errors in your callback are caught and logged to prevent breaking the app
+- The callback executes **after** navigation completes
+
 ## License
 
 Apache-2.0

package/dist/client/AuroraApp.d.ts

@@ -16,6 +16,23 @@ export type Slots = {
     /** Replaces the default page footer. Renders outside shadow DOM — inherits page styles. */
     pageFooter?: FC<SlotProps>;
 };
+/**
+ * Payload for analytics tracking events.
+ * Generic structure that supports multiple event sources (router, links, modals, etc.)
+ */
+export type TrackEventPayload = {
+    /** Source of the event (e.g., "router", "external-link", "modal", "button") */
+    source: string;
+    /** Action identifier describing what happened (e.g., route ID, button name, link URL) */
+    action: string;
+    /** Additional context specific to the source. For router: pathname, section, service. For links: href, target. */
+    metadata?: Record<string, string | number | boolean | undefined>;
+};
+/**
+ * Callback invoked when users interact with trackable features.
+ * Use this to send analytics data about feature usage patterns.
+ */
+export type OnTrackEventCallback = (payload: TrackEventPayload) => void;
 /** Props for the top-level `<AuroraApp />` component. */
 export type AuroraAppProps = {
     /** Initial theme. Defaults to `"theme-light"`. */
@@ -28,5 +45,26 @@ export type AuroraAppProps = {
     slots?: Slots;
     /** App name shown in the header breadcrumb and as the default logo title. Defaults to `"Aurora"`. */
     appName?: string;
+    /**
+     * Analytics callback for tracking user interactions and feature usage.
+     * Called for various user actions like navigation, external link clicks, etc.
+     *
+     * @example
+     * ```tsx
+     * function trackEvent(payload: TrackEventPayload) {
+     *   // Router navigation: payload.action = "/_auth/projects/$projectId/compute/images"
+     *   // External link: payload.action = "https://docs.example.com"
+     *   sendAnalytics('user-interaction', {
+     *     action: payload.action,
+     *     source: payload.source,
+     *     ...payload.metadata,
+     *     timestamp: Date.now()
+     *   })
+     * }
+     *
+     * <AuroraApp onTrackEvent={trackEvent} />
+     * ```
+     */
+    onTrackEvent?: OnTrackEventCallback;
 };
 export declare const AuroraApp: FC<AuroraAppProps>;

package/dist/client/{ContentHeader-kx1Th5Sq.mjs → ContentHeader-C51H95X8.mjs}

@@ -1,60 +1,60 @@
-import { D as e, Q as t, _ as n, l as r, nt as i, q as a, st as o } from "./build-DeJcDjPi.mjs";
+import { A as e, C as t, Q as n, Y as r, c as i, o as a, st as o } from "./build-BdRRmNf5.mjs";
 import { jsx as s, jsxs as c } from "react/jsx-runtime";
 import { useState as l } from "react";
 import { Trans as u, useLingui as d } from "@lingui/react";
 //#region src/client/components/ClipboardText.tsx
-var f = ({ text: e, tooltipContent: a, className: u, truncateAt: f, showTooltip: p = !0, ...m }) => {
-	let { i18n: h, _: g } = d(), [_, v] = l(!1), [y, b] = l(!1), x = `copyableTooltip  inline-flex items-center ${u || ""}`, S = async (t) => {
-		t.preventDefault(), t.stopPropagation();
+var f = ({ text: n, tooltipContent: o, className: u, truncateAt: f, showTooltip: p = !0, ...m }) => {
+	let { i18n: h, _: g } = d(), [_, v] = l(!1), [y, b] = l(!1), x = `copyableTooltip  inline-flex items-center ${u || ""}`, S = async (e) => {
+		e.preventDefault(), e.stopPropagation();
 		try {
-			await navigator.clipboard.writeText(e), v(!0), b(!1), setTimeout(() => v(!1), 2e3);
+			await navigator.clipboard.writeText(n), v(!0), b(!1), setTimeout(() => v(!1), 2e3);
 		} catch (e) {
 			console.error("Failed to copy text:", e);
 		}
-	}, C = f && e.length > f ? `${e.slice(0, f)}...` : e, w = () => _ ? a || h._({ id: "u+VWhB" }) : h._({ id: "he3ygx" }), T = _ && p || y && p;
+	}, C = f && n.length > f ? `${n.slice(0, f)}...` : n, w = () => _ ? o || h._({ id: "u+VWhB" }) : h._({ id: "he3ygx" }), T = _ && p || y && p;
 	return /*#__PURE__*/ s("div", {
 		...m,
 		className: x,
-		children: /*#__PURE__*/ c(o, {
+		children: /*#__PURE__*/ c(e, {
 			open: T,
-			children: [/*#__PURE__*/ s(n, {
+			children: [/*#__PURE__*/ s(a, {
 				onClick: S,
 				onMouseEnter: () => !_ && b(!0),
 				onMouseLeave: () => b(!1),
 				"aria-label": h._({
 					id: "Wbg1jv",
-					values: { text: e }
+					values: { text: n }
 				}),
 				className: "cursor-pointer",
 				asChild: !0,
 				"data-testid": "clipboard-copy-trigger",
 				children: /*#__PURE__*/ s("div", {
 					className: "group",
-					children: /*#__PURE__*/ c(t, {
+					children: /*#__PURE__*/ c(r, {
 						direction: "horizontal",
 						gap: "1",
 						className: "items-center hover:underline",
 						children: [/*#__PURE__*/ s("span", {
 							className: "select-none",
 							children: C
-						}), /*#__PURE__*/ s(r, {
+						}), /*#__PURE__*/ s(i, {
 							icon: _ ? "check" : "contentCopy",
 							size: "18"
 						})]
 					})
 				})
-			}), /*#__PURE__*/ s(i, { children: w() })]
+			}), /*#__PURE__*/ s(t, { children: w() })]
 		})
 	});
 };
 //#endregion
 //#region src/client/components/ContentHeader/ContentHeader.tsx
-function p({ title: t, projectId: n, actions: r }) {
+function p({ title: e, projectId: t, description: r, actions: i }) {
 	return /*#__PURE__*/ c("header", { children: [
 		/*#__PURE__*/ c("div", {
 			className: "flex flex-col sm:flex-row sm:items-center sm:justify-between",
-			children: [/*#__PURE__*/ s(a, { children: t }), /*#__PURE__*/ c("div", {
-				className: "text-theme-light flex items-center gap-1 text-sm",
+			children: [/*#__PURE__*/ s(n, { children: e }), /*#__PURE__*/ c("div", {
+				className: "text-theme-light flex shrink-0 items-center gap-1 text-sm",
 				children: [/*#__PURE__*/ c("span", {
 					className: "font-semibold",
 					children: [
@@ -63,19 +63,23 @@ function p({ title: t, projectId: n, actions: r }) {
 						" "
 					]
 				}), /*#__PURE__*/ s(f, {
-					text: n,
+					text: t,
 					truncateAt: 15
 				})]
 			})]
 		}),
-		/*#__PURE__*/ s(e, { className: "mt-4" }),
-		r && /*#__PURE__*/ s("div", {
-			className: "mt-3 flex justify-end",
+		r && /*#__PURE__*/ s("p", {
+			className: "text-sm font-normal",
 			children: r
+		}),
+		/*#__PURE__*/ s(o, { className: "mt-4" }),
+		i && /*#__PURE__*/ s("div", {
+			className: "mt-3 flex justify-end",
+			children: i
 		})
 	] });
 }
 //#endregion
 export { f as n, p as t };
 
-//# sourceMappingURL=ContentHeader-kx1Th5Sq.mjs.map
+//# sourceMappingURL=ContentHeader-C51H95X8.mjs.map

package/dist/client/ContentHeader-C51H95X8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContentHeader-C51H95X8.mjs","names":["React","useState","Tooltip","TooltipTrigger","TooltipContent","Icon","Stack","ClipboardText","text","tooltipContent","className","truncateAt","showTooltip","props","useLingui","copied","setCopied","isHovering","setIsHovering","combinedClassName","handleCopy","e","preventDefault","stopPropagation","navigator","clipboard","writeText","setTimeout","err","console","error","displayText","length","slice","getTooltipContent","t","tooltipIsOpen","div","open","onClick","onMouseEnter","onMouseLeave","aria-label","asChild","data-testid","direction","gap","span","icon","size","Divider","ContentHeading","ClipboardText","ContentHeader","title","projectId","description","actions","header","div","className","span","text","truncateAt","p"],"sources":["../../src/client/components/ClipboardText.tsx","../../src/client/components/ContentHeader/ContentHeader.tsx"],"sourcesContent":["import React, { useState } from \"react\"\nimport { Tooltip, TooltipTrigger, TooltipContent, Icon, Stack } from \"@cloudoperators/juno-ui-components\"\nimport { useLingui } from \"@lingui/react/macro\"\n\nexport interface ClipboardTextProps extends React.HTMLAttributes<HTMLDivElement> {\n  tooltipContent?: string\n  text: string\n  className?: string\n  truncateAt?: number\n  showTooltip?: boolean\n}\n\nconst ClipboardText: React.FC<ClipboardTextProps> = ({\n  text,\n  tooltipContent,\n  className,\n  truncateAt,\n  showTooltip = true,\n  ...props\n}) => {\n  const { t } = useLingui()\n  const [copied, setCopied] = useState(false)\n  const [isHovering, setIsHovering] = useState(false)\n\n  const combinedClassName = `copyableTooltip  inline-flex items-center ${className || \"\"}`\n\n  const handleCopy = async (e: React.MouseEvent) => {\n    e.preventDefault()\n    e.stopPropagation()\n\n    try {\n      await navigator.clipboard.writeText(text)\n      setCopied(true)\n      setIsHovering(false)\n      setTimeout(() => setCopied(false), 2000)\n    } catch (err) {\n      console.error(\"Failed to copy text:\", err)\n    }\n  }\n\n  const displayText = truncateAt && text.length > truncateAt ? `${text.slice(0, truncateAt)}...` : text\n\n  // Determine tooltip content based on state\n  const getTooltipContent = () => {\n    if (copied) {\n      return tooltipContent || t`Copied to clipboard!`\n    }\n    return t`Copy`\n  }\n\n  const tooltipIsOpen = (copied && showTooltip) || (isHovering && showTooltip)\n\n  return (\n    <div {...props} className={combinedClassName}>\n      <Tooltip open={tooltipIsOpen}>\n        <TooltipTrigger\n          onClick={handleCopy}\n          onMouseEnter={() => !copied && setIsHovering(true)}\n          onMouseLeave={() => setIsHovering(false)}\n          aria-label={t`Copy ${text} to clipboard`}\n          className=\"cursor-pointer\"\n          asChild\n          data-testid=\"clipboard-copy-trigger\"\n        >\n          <div className=\"group\">\n            <Stack direction=\"horizontal\" gap=\"1\" className=\"items-center hover:underline\">\n              <span className=\"select-none\">{displayText}</span>\n              <Icon icon={copied ? \"check\" : \"contentCopy\"} size=\"18\" />\n            </Stack>\n          </div>\n        </TooltipTrigger>\n        <TooltipContent>{getTooltipContent()}</TooltipContent>\n      </Tooltip>\n    </div>\n  )\n}\n\nexport default ClipboardText\n","import type { ReactNode } from \"react\"\nimport { Divider, ContentHeading } from \"@cloudoperators/juno-ui-components\"\nimport { Trans } from \"@lingui/react/macro\"\nimport ClipboardText from \"../ClipboardText\"\n\ninterface ContentHeaderProps {\n  title: string\n  projectId: string\n  description?: string | null\n  actions?: ReactNode\n}\n\nexport function ContentHeader({ title, projectId, description, actions }: ContentHeaderProps) {\n  return (\n    <header>\n      <div className=\"flex flex-col sm:flex-row sm:items-center sm:justify-between\">\n        <ContentHeading>{title}</ContentHeading>\n        <div className=\"text-theme-light flex shrink-0 items-center gap-1 text-sm\">\n          <span className=\"font-semibold\">\n            <Trans>Project ID</Trans>:{\" \"}\n          </span>\n          <ClipboardText text={projectId} truncateAt={15} />\n        </div>\n      </div>\n      {description && <p className=\"text-sm font-normal\">{description}</p>}\n      <Divider className=\"mt-4\" />\n      {actions && <div className=\"mt-3 flex justify-end\">{actions}</div>}\n    </header>\n  )\n}\n"],"mappings":";;;;;AAYA,IAAMO,KAA+C,EACnDC,SACAC,mBACAC,cACAC,eACAC,iBAAc,IACd,GAAGC,QACJ;CACC,IAAM,EAAA,MAAA,GAAA,GAAA,MAAQC,EAAAA,GACR,CAACC,GAAQC,KAAaf,EAAS,EAAA,GAC/B,CAACgB,GAAYC,KAAiBjB,EAAS,EAAA,GAEvCkB,IAAoB,6CAA6CT,KAAa,MAE9EU,IAAa,OAAOC,MAAAA;EAExBA,AADAA,EAAEC,eAAc,GAChBD,EAAEE,gBAAe;EAEjB,IAAI;GAIFI,AAHA,MAAMH,UAAUC,UAAUC,UAAUlB,CAAAA,GACpCQ,EAAU,EAAA,GACVE,EAAc,EAAA,GACdS,iBAAiBX,EAAU,EAAA,GAAQ,GAAA;EACrC,SAASY,GAAK;GACZC,QAAQC,MAAM,wBAAwBF,CAAAA;EACxC;CACF,GAEMG,IAAcpB,KAAcH,EAAKwB,SAASrB,IAAa,GAAGH,EAAKyB,MAAM,GAAGtB,CAAAA,EAAY,OAAOH,GAG3F0B,UACAnB,IACKN,KAAkB0B,EAAAA,EAAC,EAAA,IAAA,SAAqB,CAAA,IAE1CA,EAAAA,EAAC,EAAA,IAAA,SAAK,CAAA,GAGTC,IAAgB,KAAWxB,KAAiBK,KAAcL;CAEhE,OACE,gBAACyB,OAAAA;EAAK,GAAGxB;EAAOH,WAAWS;YACzB,gBAACjB,GAAAA;GAAQoC,MAAMF;cACb,gBAACjC,GAAAA;IACCoC,SAASnB;IACToB,oBAAoB,CAACzB,KAAUG,EAAc,EAAA;IAC7CuB,oBAAoBvB,EAAc,EAAA;IAClCwB,cAAYP,EAAAA,EAAC;;eAAQ3B,QAAAA;IAAkB,CAAA;IACvCE,WAAU;IACViC,SAAO;IACPC,eAAY;cAEZ,gBAACP,OAAAA;KAAI3B,WAAU;eACb,gBAACJ,GAAAA;MAAMuC,WAAU;MAAaC,KAAI;MAAIpC,WAAU;iBAC9C,gBAACqC,QAAAA;OAAKrC,WAAU;iBAAeqB;UAC/B,gBAAC1B,GAAAA;OAAK2C,MAAMjC,IAAS,UAAU;OAAekC,MAAK;;;;OAIzD,gBAAC7C,GAAAA,EAAAA,UAAgB8B,EAAAA,EAAAA,CAAAA,CAAAA;;;AAIzB;;;AC/DA,SAAgBmB,EAAc,EAAEC,UAAOC,cAAWC,gBAAaC,cAA6B;CAC1F,OACE,gBAACC,UAAAA,EAAAA,UAAAA;EACC,gBAACC,OAAAA;GAAIC,WAAU;cACb,gBAACT,GAAAA,EAAAA,UAAgBG,EAAAA,CAAAA,GACjB,gBAACK,OAAAA;IAAIC,WAAU;eACb,gBAACC,QAAAA;KAAKD,WAAU;;MACd,gBAAA,GAAA,EAAA,IAAA,SAAA,CAAA;MAAyB;MAAE;;QAE7B,gBAACR,GAAAA;KAAcU,MAAMP;KAAWQ,YAAY;;;;EAG/CP,KAAe,gBAACQ,KAAAA;GAAEJ,WAAU;aAAuBJ;;EACpD,gBAACN,GAAAA,EAAQU,WAAU,OAAA,CAAA;EAClBH,KAAW,gBAACE,OAAAA;GAAIC,WAAU;aAAyBH;;;AAG1D"}