react-semaphor 0.1.381 → 0.1.382

package/dist/types/surfboard.d.ts

@@ -2015,15 +2015,9 @@ declare type SemaphorDerivedFieldInput = {
     kind: 'field';
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-} | {
-    kind: 'metric';
-    metric: SemaphorFieldRef;
-} | {
-    kind: 'dimension';
-    dimension: SemaphorFieldRef;
 };
 
-declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
@@ -2047,9 +2041,10 @@ declare type SemaphorFieldRef = {
 declare type SemaphorInputBinding = {
     inputId: string;
     kind?: 'filter' | 'control';
-    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
     operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
 };
 
 declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
@@ -2112,6 +2107,7 @@ declare type SemaphorMatrixIntent = {
     values: SemaphorMatrixValueField[];
     filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     totals?: SemaphorMatrixTotalOptions;
     sort?: SemaphorMatrixSortRule[];
     expansion?: SemaphorMatrixExpansionOptions;
@@ -2200,6 +2196,10 @@ declare type SemaphorMatrixValueField = {
 
 declare type SemaphorProtocolVersion = 1;
 
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;

package/dist/types/types.d.ts

@@ -3010,15 +3010,9 @@ declare type SemaphorDerivedFieldInput = {
     kind: 'field';
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-} | {
-    kind: 'metric';
-    metric: SemaphorFieldRef;
-} | {
-    kind: 'dimension';
-    dimension: SemaphorFieldRef;
 };
 
-declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
@@ -3042,9 +3036,10 @@ declare type SemaphorFieldRef = {
 declare type SemaphorInputBinding = {
     inputId: string;
     kind?: 'filter' | 'control';
-    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
     operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
 };
 
 declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
@@ -3107,6 +3102,7 @@ declare type SemaphorMatrixIntent = {
     values: SemaphorMatrixValueField[];
     filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     totals?: SemaphorMatrixTotalOptions;
     sort?: SemaphorMatrixSortRule[];
     expansion?: SemaphorMatrixExpansionOptions;
@@ -3230,6 +3226,10 @@ declare type SemaphorProtocolVersion = 1;
 
 declare type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
 
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.381",
+  "version": "0.1.382",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -16,7 +16,9 @@
   "type": "module",
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "DATA_APP_SDK.md",
+    "src/data-app-sdk/README.md"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -72,6 +74,11 @@
       "import": "./dist/data-app-sdk/index.js",
       "require": "./dist/data-app-sdk/index.cjs"
     },
+    "./data-app-sdk/adapters": {
+      "types": "./dist/types/data-app-sdk-adapters.d.ts",
+      "import": "./dist/data-app-sdk-adapters/index.js",
+      "require": "./dist/data-app-sdk-adapters/index.cjs"
+    },
     "./data-app-sdk/validation": {
       "types": "./dist/types/data-app-sdk-validation.d.ts",
       "import": "./dist/data-app-sdk-validation/index.js",

package/src/data-app-sdk/README.md

@@ -0,0 +1,240 @@
+# Data App SDK Quick Reference
+
+Use this file as the public contract quick reference for generated Semaphor
+Data Apps. Do not inspect SDK implementation internals to discover these
+patterns.
+
+## Imports
+
+```tsx
+import {
+  SemaphorDataAppProvider,
+  semaphor,
+  useClearInvalidSemaphorInputValue,
+  useSemaphorInputs,
+  useSemaphorQuery,
+} from "react-semaphor/data-app-sdk";
+
+import type {
+  SemaphorQueryResult,
+  SemaphorRecordsField,
+  SemaphorRecordsQueryResult,
+  SemaphorSourceRef,
+} from "react-semaphor/data-app-sdk";
+```
+
+## Source And Fields
+
+```tsx
+const source = {
+  kind: "semantic",
+  domainId: "sales",
+  datasetName: "orders",
+} satisfies SemaphorSourceRef;
+
+const revenue = {
+  name: "revenue",
+  label: "Revenue",
+  role: "measure",
+  dataType: "number",
+  aggregate: "SUM",
+  source,
+} satisfies SemaphorRecordsField;
+
+const segment = {
+  name: "segment",
+  label: "Segment",
+  role: "dimension",
+  dataType: "string",
+  source,
+} satisfies SemaphorRecordsField;
+```
+
+Use `SemaphorRecordsField` for `semaphor.records(...)` fields so every selected
+field has a concrete role.
+
+## Metric
+
+```tsx
+const revenueKpi = semaphor.metric({
+  id: "revenue-kpi",
+  source,
+  measures: [revenue],
+  primaryMeasure: revenue,
+});
+
+const result = useSemaphorQuery(revenueKpi);
+```
+
+## Records
+
+```tsx
+const revenueBySegment = semaphor.records({
+  id: "revenue-by-segment",
+  source,
+  fields: [segment, revenue],
+  orderBy: { field: revenue, direction: "desc" },
+  limit: 10,
+});
+
+const result = useSemaphorQuery(revenueBySegment);
+```
+
+## Row Access
+
+Read rows with `columns[].key`; display `columns[].label`.
+
+```tsx
+function RecordsTable({ result }: { result: SemaphorRecordsQueryResult }) {
+  const records = result.records ?? [];
+  const columns = result.columns ?? [];
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          {columns.map((column) => (
+            <th key={column.key}>{column.label || column.name}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {records.map((row, rowIndex) => (
+          <tr key={rowIndex}>
+            {columns.map((column) => (
+              <td key={column.key}>{String(row[column.key] ?? "")}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+When accepting a generic `SemaphorQueryResult`, narrow before reading records:
+
+```tsx
+function queryRecords(result: SemaphorQueryResult) {
+  return "records" in result && Array.isArray(result.records)
+    ? result.records
+    : [];
+}
+```
+
+## Input Options
+
+```tsx
+const segmentFilter = semaphor.filter({
+  id: "segment",
+  label: "Segment",
+  field: segment,
+  operator: "in",
+});
+
+const segmentOptions = semaphor.inputOptions({
+  id: "segment-options",
+  inputId: "segment",
+  source,
+  labelField: segment,
+  valueField: segment,
+  dependencies: { mode: "auto" },
+  limit: 100,
+});
+
+function SegmentFilter() {
+  const [segmentHandle] = useSemaphorInputs([segmentFilter]);
+  const optionsResult = useSemaphorQuery(segmentOptions, {
+    inputs: [segmentHandle],
+  });
+
+  useClearInvalidSemaphorInputValue(segmentHandle, optionsResult);
+}
+```
+
+Pass the full `optionsResult` to `useClearInvalidSemaphorInputValue`; do not
+pass only `optionsResult.options`, because idle/loading results can also expose
+an empty options array.
+
+## Shared Inputs With Source-Specific Bindings
+
+Use `semaphor.bindInput(...)` when one visible input maps to different query
+fields.
+
+```tsx
+const dateRange = semaphor.filter({
+  id: "date_range",
+  label: "Date Range",
+  field: orderDate,
+  operator: "between",
+});
+
+function Dashboard() {
+  const [dateRangeHandle] = useSemaphorInputs([dateRange]);
+
+  const orders = useSemaphorQuery(ordersQuery, {
+    inputs: [semaphor.bindInput(dateRangeHandle, { field: orderDate })],
+  });
+  const invoices = useSemaphorQuery(invoicesQuery, {
+    inputs: [semaphor.bindInput(dateRangeHandle, { field: invoiceDate })],
+  });
+
+  const range = Array.isArray(dateRangeHandle.value)
+    ? dateRangeHandle.value
+    : [];
+  const [start, end] = range;
+}
+```
+
+Narrow `handle.value` with `Array.isArray(...)` before indexing date ranges or
+multi-select values.
+
+## Related Dimension Filters
+
+Use a related human-readable dimension as the visible filter and preserve the
+relationship hint when binding that input into each fact query.
+
+```tsx
+const materialFamilyFilter = semaphor.filter<string[]>({
+  id: "material_family",
+  label: "Material Family",
+  field: materialFamily,
+  operator: "in",
+  multi: true,
+});
+
+const materialOptions = semaphor.inputOptions({
+  id: "material-family-options",
+  inputId: "material_family",
+  source: materialSource,
+  labelField: materialFamily,
+  valueField: materialFamily,
+  limit: 100,
+});
+
+function OpsViews() {
+  const materialHandle = useSemaphorInput(materialFamilyFilter);
+  useSemaphorQuery(materialOptions);
+
+  useSemaphorQuery(purchaseQuery, {
+    inputs: [
+      semaphor.bindInput(materialHandle, {
+        field: materialFamily,
+        relationshipHint: { relationshipIds: ["purchase_material"] },
+      }),
+    ],
+  });
+
+  useSemaphorQuery(salesQuery, {
+    inputs: [
+      semaphor.bindInput(materialHandle, {
+        field: materialFamily,
+        relationshipHint: { relationshipIds: ["sales_material"] },
+      }),
+    ],
+  });
+}
+```
+
+Do not fetch broad rows and filter or join them in React to simulate
+related-dimension behavior. Let Semaphor execute the relationship-aware filter.

package/dist/chunks/catalog-field-grounding-8L9I0zdg.js

@@ -1 +0,0 @@
-"use strict";const o={answerSummary:"string",responseDetail:"responseDetail",mode:"string",comparisonType:"string",executionResult:"unknown",compiledQuery:"unknown",data:"unknown",resultSets:"record",columns:"unknownArray",records:"recordArray",rowCount:"number",rowLimitExceeded:"boolean",output:"string",querySpec:"unknown",metadata:"record",validation:"unknown",coverage:"unknown",diagnosticFeedback:"unknown",missingFields:"stringArray",warnings:"unknownArray",comparison:"unknown",population:"unknown",comparisons:"recordArray",fieldsUsed:"unknown",changes:"recordArray",largestNegativeChanges:"recordArray",largestPositiveChanges:"recordArray",drivers:"recordArray",absoluteDeltaDrivers:"recordArray",largestNegativeDrivers:"recordArray",largestPositiveDrivers:"recordArray",periodRows:"recordArray",sql:"unknown",omitted:"stringArray"},b=new Set(Object.keys(o)),S=new Set(["compact","standard","debug"]);function D(){return Object.keys(o)}function g(e){return b.has(e)}function F(e){if(!e||typeof e!="object"||Array.isArray(e))throw new Error("Semaphor analyze result must be an object.");const n=e,t=Object.keys(n).filter(r=>!g(r));if(t.length)throw new Error(`Semaphor analyze result contains unsupported top-level field(s): ${t.join(", ")}.`);for(const[r,i]of Object.entries(n)){if(i===void 0)continue;const a=o[r];if(!k(i,a))throw new Error(`Semaphor analyze result field "${r}" does not match contract kind "${a}".`)}return n}function k(e,n){switch(n){case"boolean":return typeof e=="boolean";case"number":return typeof e=="number"&&Number.isFinite(e);case"record":return A(e);case"recordArray":return Array.isArray(e)&&e.every(A);case"responseDetail":return typeof e=="string"&&S.has(e);case"string":return typeof e=="string";case"stringArray":return Array.isArray(e)&&e.every(t=>typeof t=="string");case"unknown":return!0;case"unknownArray":return Array.isArray(e)}}function A(e){return!!(e&&typeof e=="object"&&!Array.isArray(e))}function c(e){return typeof e=="string"?e.trim().toLowerCase():""}function p(e){return String(e.column_name||e.name||e.qualifiedFieldName||"")}function w(e){return Array.from(new Set([e.column_name,e.name,e.qualifiedFieldName,e.alias].filter(n=>typeof n=="string"&&n.trim().length>0).map(n=>n.trim())))}function d(e){const n=T(e);return n?n.includes("int")||n.includes("uint")||n.includes("bigint")||n.includes("smallint")||n.includes("tinyint")||n.includes("numeric")||n.includes("decimal")||n.includes("double")||n.includes("float")||n.includes("number")||n.includes("real")||n.includes("money")||n.includes("currency")||n.includes("percent")?"number":n.includes("timestamp")||n.includes("datetime")||n.startsWith("time")?"datetime":n.includes("date")?"date":n.includes("bool")?"boolean":"string":"unknown"}function T(e){let n=c(e),t="";for(;n&&n!==t;)t=n,n=f(n,"nullable"),n=f(n,"lowcardinality");return n}function f(e,n){const t=`${n}(`;return!e.startsWith(t)||!e.endsWith(")")?e:e.slice(t.length,-1).trim()}function h(e){const n=d(e);return n==="date"||n==="datetime"}function u(e){return h(e.dataType||e.data_type)}function y(e){const n=C(e);return n==="id"||n==="row_id"}function l(e){const n=C(e);return y(e)||n.endsWith("_id")||n.endsWith("_key")||n.endsWith("_number")}function C(e){return c(p(e)||e.name||e.alias).replace(/[^a-z0-9]+/g,"_").replace(/^_+|_+$/g,"")}function m(e,n={}){const t=c(e.role);return t==="metric"||t==="measure"?!n.excludeIdentifiers||!l(e):t==="groupby"||t==="dimension"||t==="date"||t==="id"?!1:d(e.dataType||e.data_type)==="number"&&(!n.excludeIdentifiers||!l(e))}function _(e){return!m(e)&&!u(e)}function E(e){const n=new Set,t=new Set,r=new Set;for(const i of e){if(y(i))continue;const a=w(i);if(a.length!==0){if(u(i)){a.forEach(s=>t.add(s));continue}if(m(i,{excludeIdentifiers:!0})){a.forEach(s=>n.add(s));continue}a.forEach(s=>r.add(s))}}return{validMetricCandidates:Array.from(n).sort(),validDateCandidates:Array.from(t).sort(),validDimensionCandidates:Array.from(r).sort()}}exports.SEMAPHOR_ANALYZE_RESULT_FIELD_CONTRACT=o;exports.buildAnalyticsCatalogFieldSummary=E;exports.getAnalyticsCatalogFieldCandidates=w;exports.getAnalyticsCatalogFieldName=p;exports.getSemaphorAnalyzeResultFieldNames=D;exports.isAnalyticsCatalogDateField=u;exports.isAnalyticsCatalogDimensionField=_;exports.isAnalyticsCatalogMetricField=m;exports.isAnalyticsDateLikeDataType=h;exports.isAnalyticsMetricIdentifierField=l;exports.isAnalyticsTechnicalIdentifierField=y;exports.isSemaphorAnalyzeResultFieldName=g;exports.normalizeAnalyticsCatalogDataType=d;exports.normalizeAnalyticsCatalogName=c;exports.parseSemaphorAnalyzeResult=F;

package/dist/chunks/catalog-field-grounding-BK4BX8sZ.js

@@ -1,200 +0,0 @@
-const o = {
-  answerSummary: "string",
-  responseDetail: "responseDetail",
-  mode: "string",
-  comparisonType: "string",
-  executionResult: "unknown",
-  compiledQuery: "unknown",
-  data: "unknown",
-  resultSets: "record",
-  columns: "unknownArray",
-  records: "recordArray",
-  rowCount: "number",
-  rowLimitExceeded: "boolean",
-  output: "string",
-  querySpec: "unknown",
-  metadata: "record",
-  validation: "unknown",
-  coverage: "unknown",
-  diagnosticFeedback: "unknown",
-  missingFields: "stringArray",
-  warnings: "unknownArray",
-  comparison: "unknown",
-  population: "unknown",
-  comparisons: "recordArray",
-  fieldsUsed: "unknown",
-  changes: "recordArray",
-  largestNegativeChanges: "recordArray",
-  largestPositiveChanges: "recordArray",
-  drivers: "recordArray",
-  absoluteDeltaDrivers: "recordArray",
-  largestNegativeDrivers: "recordArray",
-  largestPositiveDrivers: "recordArray",
-  periodRows: "recordArray",
-  sql: "unknown",
-  omitted: "stringArray"
-}, g = new Set(
-  Object.keys(o)
-), w = /* @__PURE__ */ new Set([
-  "compact",
-  "standard",
-  "debug"
-]);
-function _() {
-  return Object.keys(
-    o
-  );
-}
-function h(e) {
-  return g.has(e);
-}
-function E(e) {
-  if (!e || typeof e != "object" || Array.isArray(e))
-    throw new Error("Semaphor analyze result must be an object.");
-  const n = e, r = Object.keys(n).filter(
-    (t) => !h(t)
-  );
-  if (r.length)
-    throw new Error(
-      `Semaphor analyze result contains unsupported top-level field(s): ${r.join(", ")}.`
-    );
-  for (const [t, a] of Object.entries(n)) {
-    if (a === void 0)
-      continue;
-    const i = o[t];
-    if (!b(a, i))
-      throw new Error(
-        `Semaphor analyze result field "${t}" does not match contract kind "${i}".`
-      );
-  }
-  return n;
-}
-function b(e, n) {
-  switch (n) {
-    case "boolean":
-      return typeof e == "boolean";
-    case "number":
-      return typeof e == "number" && Number.isFinite(e);
-    case "record":
-      return d(e);
-    case "recordArray":
-      return Array.isArray(e) && e.every(d);
-    case "responseDetail":
-      return typeof e == "string" && w.has(e);
-    case "string":
-      return typeof e == "string";
-    case "stringArray":
-      return Array.isArray(e) && e.every((r) => typeof r == "string");
-    case "unknown":
-      return !0;
-    case "unknownArray":
-      return Array.isArray(e);
-  }
-}
-function d(e) {
-  return !!(e && typeof e == "object" && !Array.isArray(e));
-}
-function c(e) {
-  return typeof e == "string" ? e.trim().toLowerCase() : "";
-}
-function k(e) {
-  return String(e.column_name || e.name || e.qualifiedFieldName || "");
-}
-function S(e) {
-  return Array.from(
-    new Set(
-      [
-        e.column_name,
-        e.name,
-        e.qualifiedFieldName,
-        e.alias
-      ].filter(
-        (n) => typeof n == "string" && n.trim().length > 0
-      ).map((n) => n.trim())
-    )
-  );
-}
-function y(e) {
-  const n = C(e);
-  return n ? n.includes("int") || n.includes("uint") || n.includes("bigint") || n.includes("smallint") || n.includes("tinyint") || n.includes("numeric") || n.includes("decimal") || n.includes("double") || n.includes("float") || n.includes("number") || n.includes("real") || n.includes("money") || n.includes("currency") || n.includes("percent") ? "number" : n.includes("timestamp") || n.includes("datetime") || n.startsWith("time") ? "datetime" : n.includes("date") ? "date" : n.includes("bool") ? "boolean" : "string" : "unknown";
-}
-function C(e) {
-  let n = c(e), r = "";
-  for (; n && n !== r; )
-    r = n, n = u(n, "nullable"), n = u(n, "lowcardinality");
-  return n;
-}
-function u(e, n) {
-  const r = `${n}(`;
-  return !e.startsWith(r) || !e.endsWith(")") ? e : e.slice(r.length, -1).trim();
-}
-function D(e) {
-  const n = y(e);
-  return n === "date" || n === "datetime";
-}
-function m(e) {
-  return D(e.dataType || e.data_type);
-}
-function f(e) {
-  const n = p(e);
-  return n === "id" || n === "row_id";
-}
-function l(e) {
-  const n = p(e);
-  return f(e) || n.endsWith("_id") || n.endsWith("_key") || n.endsWith("_number");
-}
-function p(e) {
-  return c(
-    k(e) || e.name || e.alias
-  ).replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-}
-function A(e, n = {}) {
-  const r = c(e.role);
-  return r === "metric" || r === "measure" ? !n.excludeIdentifiers || !l(e) : r === "groupby" || r === "dimension" || r === "date" || r === "id" ? !1 : y(
-    e.dataType || e.data_type
-  ) === "number" && (!n.excludeIdentifiers || !l(e));
-}
-function F(e) {
-  return !A(e) && !m(e);
-}
-function T(e) {
-  const n = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Set(), t = /* @__PURE__ */ new Set();
-  for (const a of e) {
-    if (f(a))
-      continue;
-    const i = S(a);
-    if (i.length !== 0) {
-      if (m(a)) {
-        i.forEach((s) => r.add(s));
-        continue;
-      }
-      if (A(a, { excludeIdentifiers: !0 })) {
-        i.forEach((s) => n.add(s));
-        continue;
-      }
-      i.forEach((s) => t.add(s));
-    }
-  }
-  return {
-    validMetricCandidates: Array.from(n).sort(),
-    validDateCandidates: Array.from(r).sort(),
-    validDimensionCandidates: Array.from(t).sort()
-  };
-}
-export {
-  o as S,
-  k as a,
-  S as b,
-  y as c,
-  D as d,
-  m as e,
-  f,
-  _ as g,
-  l as h,
-  h as i,
-  A as j,
-  F as k,
-  T as l,
-  c as n,
-  E as p
-};