@lightdash/query-sdk 3.89.0 → 3.91.0

package/dist/apiTransport.js

@@ -489,10 +489,18 @@ function mapApiRowsToQueryResult({ apiRows, columns, fields, fieldIds, fieldName
         const name = idToName.get(fieldId) ?? fieldId;
         const fieldMeta = fields[fieldId];
         const colMeta = columns[fieldId];
+        const urls = Array.isArray(fieldMeta?.urls)
+            ? fieldMeta.urls.filter((u) => typeof u === 'object' &&
+                u !== null &&
+                typeof u.label === 'string' &&
+                typeof u.url === 'string')
+            : [];
         return {
             name,
             label: fieldMeta?.label ?? fieldMeta?.displayName ?? name,
             type: mapColumnType(colMeta?.type ?? fieldMeta?.type ?? 'string'),
+            fieldId,
+            ...(urls.length > 0 ? { urls } : {}),
         };
     });
     const formattedCache = new Map();

package/dist/columnUrls.d.ts

@@ -0,0 +1,22 @@
+import type { Column, FormatFunction, Row } from './types';
+export type ResolvedColumnUrl = {
+    label: string;
+    href: string;
+};
+type ResolveArgs = {
+    /** The column whose cell is being rendered. */
+    column: Column;
+    /** The result row the cell belongs to (SDK row, keyed by column name). */
+    row: Row;
+    /** All result columns — used to resolve `${row.<table>.<field>}` references. */
+    columns: Column[];
+    /** The result's format function, for `.formatted` references. */
+    format?: FormatFunction;
+};
+/**
+ * Build the links a cell offers from its column's `urls` patterns. Patterns
+ * whose references cannot be resolved against this row (missing field, null
+ * value, unknown filter) are skipped, matching dashboard behavior.
+ */
+export declare const resolveColumnUrls: (args: ResolveArgs) => ResolvedColumnUrl[];
+export {};

package/dist/columnUrls.js

@@ -0,0 +1,88 @@
+const TEMPLATE_RE = /\$\{([^}]+)\}/g;
+/**
+ * Find the row key a `${row.<table>.<field>}` reference points at. Column
+ * names differ per result path (plain names, dot notation, or qualified ids
+ * in underlying-data results), so resolve through the column's `fieldId`
+ * (`<table>_<field>`), which preserves table identity everywhere. A dotted
+ * name match remains as a fallback for hand-built columns without a fieldId;
+ * a bare field name is never matched — the same name on another table would
+ * silently link the wrong record.
+ */
+const rowKeyForReference = (columns, table, field) => {
+    const fieldId = `${table}_${field}`;
+    const byFieldId = columns.find((c) => c.fieldId === fieldId);
+    if (byFieldId)
+        return byFieldId.name;
+    const dotted = `${table}.${field}`;
+    const byDottedName = columns.find((c) => c.fieldId === undefined && c.name === dotted);
+    return byDottedName ? byDottedName.name : null;
+};
+const applyFilters = (value, filters) => {
+    let out = value;
+    for (const filter of filters) {
+        if (filter === 'url_encode') {
+            out = encodeURIComponent(out);
+        }
+        else {
+            // Unknown filter — mirror the dashboard renderer's strict mode
+            // and drop the link rather than emit a wrong URL.
+            return null;
+        }
+    }
+    return out;
+};
+/**
+ * Resolve one `${...}` expression against the row. Returns null when the
+ * reference is invalid, the referenced value is missing, or a filter is
+ * unknown — the caller then skips the whole pattern.
+ */
+const resolveExpression = (expression, { column, row, columns, format }) => {
+    const [ref = '', ...filters] = expression
+        .split('|')
+        .map((part) => part.trim());
+    const parts = ref.split('.').map((part) => part.trim());
+    let key = null;
+    let mode = null;
+    if (parts.length === 2 && parts[0] === 'value') {
+        key = column.name;
+        mode = parts[1] === 'raw' || parts[1] === 'formatted' ? parts[1] : null;
+    }
+    else if (parts.length === 4 && parts[0] === 'row') {
+        key = rowKeyForReference(columns, parts[1], parts[2]);
+        mode = parts[3] === 'raw' || parts[3] === 'formatted' ? parts[3] : null;
+    }
+    if (key === null || mode === null)
+        return null;
+    const raw = row[key];
+    if (raw === null || raw === undefined)
+        return null;
+    const value = mode === 'formatted' && format ? format(row, key) : String(raw);
+    return applyFilters(value, filters);
+};
+/**
+ * Build the links a cell offers from its column's `urls` patterns. Patterns
+ * whose references cannot be resolved against this row (missing field, null
+ * value, unknown filter) are skipped, matching dashboard behavior.
+ */
+export const resolveColumnUrls = (args) => {
+    const urls = args.column.urls ?? [];
+    if (urls.length === 0)
+        return [];
+    if (args.row[args.column.name] === null)
+        return [];
+    const resolved = [];
+    for (const { label, url } of urls) {
+        let failed = false;
+        const href = url.replace(TEMPLATE_RE, (match, expression) => {
+            const substituted = resolveExpression(expression, args);
+            if (substituted === null) {
+                failed = true;
+                return match;
+            }
+            return substituted;
+        });
+        if (!failed)
+            resolved.push({ label, href });
+    }
+    return resolved;
+};

package/dist/features.js

@@ -211,6 +211,13 @@ export const SDK_FEATURES = [
         description: 'Reflows the layout for narrow and short tiles, such as a dashboard on a phone, so values stay readable and nothing scrolls sideways.',
         wiring: 'Rework the layout to the "Fitting the frame" section of the reusable-visualization skill. A chart type built on an older template first needs the frame runtime added to its own files, as described under viz-responsive-layout in the sdk-features skill: the VizFrame marker in src/main.jsx and the html[data-viz-frame] rules in src/index.css. Then size type, padding and gaps in rem or Tailwind classes instead of px, make rows of items wrap with a minimum item width that keeps values on one line (capped just under half the frame), remove any scroll regions of the chart\'s own so only the frame scrolls, and make a title or table header row sticky.',
     },
+    {
+        key: 'field-links',
+        appliesTo: ['data_app'],
+        label: 'Field links',
+        description: "Result columns carry the semantic layer's url link patterns, so values with configured links render as links, matching dashboards.",
+        wiring: 'In cell renderers (tables, underlying-data dialogs), call resolveColumnUrls({ column, row, columns, format }) and render the value as a link when it returns entries, styled visibly as a link.',
+    },
 ];
 export const SDK_FEATURE_KEYS = SDK_FEATURES.map((f) => f.key);
 /**

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "3.89.0";
+export declare const SDK_VERSION = "3.91.0";

package/dist/generated/sdkVersion.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generateSdkVersion.mjs (prebuild) — do not edit.
-export const SDK_VERSION = '3.89.0';
+export const SDK_VERSION = '3.91.0';

package/dist/index.d.ts

@@ -6,8 +6,9 @@ export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 export { createApiTransport, LightdashApiError, type FetchAdapter, } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
+export { resolveColumnUrls, type ResolvedColumnUrl } from './columnUrls';
 export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_FIXES, SDK_FIX_KEYS, SDK_FEATURE_TARGETS, SDK_MANIFEST_MESSAGE_TYPE, type SdkFeature, type SdkFeatureTarget, type SdkFix, type SdkManifestMessage, } from './features';
-export type { AdditionalMetric, AiPromptRequest, AiPromptResult, Column, ColumnType, CustomDimension, DownloadResultsFileType, DownloadResultsLimit, DownloadResultsOptions, DownloadResultsResult, DownloadResultsValues, DownloadUnderlyingDataOptions, ExternalFetchMethod, ExternalFetchOptions, ExternalFetchResult, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, UnderlyingDataOptions, UnderlyingDataResult, } from './types';
+export type { AdditionalMetric, AiPromptRequest, AiPromptResult, Column, ColumnType, ColumnUrl, CustomDimension, DownloadResultsFileType, DownloadResultsLimit, DownloadResultsOptions, DownloadResultsResult, DownloadResultsValues, DownloadUnderlyingDataOptions, ExternalFetchMethod, ExternalFetchOptions, ExternalFetchResult, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, UnderlyingDataOptions, UnderlyingDataResult, } from './types';
 export type { SdkExternalFetchRequest, SdkExternalFetchResponse, SdkFetchRequest, SdkFetchResponse, SdkReadyMessage, SdkScreenshotAvailableMessage, SdkScreenshotRequest, SdkScreenshotResponse, SdkGsheetExportRequest, SdkGsheetExportResponse, SdkGsheetExportColumn, SdkGsheetExportColumnType, SdkGsheetExportRow, } from './postMessageTransport';
 export type { InspectAvailableMessage, InspectSelectedMessage, } from './inspector';
 export { useDelivery } from './delivery';

package/dist/index.js

@@ -12,6 +12,7 @@ export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 // Transports
 export { createApiTransport, LightdashApiError, } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
+export { resolveColumnUrls } from './columnUrls';
 // Feature manifest (also exported via the "./features" subpath for hosts)
 export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_FIXES, SDK_FIX_KEYS, SDK_FEATURE_TARGETS, SDK_MANIFEST_MESSAGE_TYPE, } from './features';
 // Scheduled-delivery declarations (data apps)

package/dist/types.d.ts

@@ -94,10 +94,29 @@ export type QueryDefinition = {
     label?: string;
 };
 export type ColumnType = 'string' | 'number' | 'date' | 'timestamp' | 'boolean';
+/**
+ * A link pattern declared on the field in the semantic layer (`urls:` in the
+ * model YAML). `url` is a template: `${value.raw}` / `${value.formatted}` is
+ * the cell's own value, `${row.<table>.<field>.raw}` (or `.formatted`)
+ * references another field in the same result row, and a `| url_encode`
+ * filter URL-encodes the substituted value. Resolve with `resolveColumnUrls`.
+ */
+export type ColumnUrl = {
+    label: string;
+    url: string;
+};
 export type Column = {
     name: string;
     label: string;
     type: ColumnType;
+    /**
+     * The API field id (`<table>_<field>`), preserved across result paths so
+     * `${row.<table>.<field>}` url references resolve to the right column
+     * even where names are qualified differently (underlying data, joins).
+     */
+    fieldId?: string;
+    /** Link patterns for this field's values; render cells as links when set. */
+    urls?: ColumnUrl[];
 };
 export type Row = Record<string, string | number | boolean | null>;
 export type FormatFunction = (row: Row, fieldId: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "3.89.0",
+  "version": "3.91.0",
   "private": false,
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
   "license": "MIT",
@@ -26,7 +26,7 @@
     }
   },
   "devDependencies": {
-    "@lightdash/common": "3.89.0",
+    "@lightdash/common": "3.91.0",
     "@types/node": "22.13.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",