react-semaphor 0.1.386 → 0.1.388

package/dist/types/analytics-protocol.d.ts

@@ -80,6 +80,8 @@ export declare function isAnalyticsTechnicalIdentifierField(field: AnalyticsCata
 
 export declare function isSemaphorAnalyzeResultFieldName(value: string): value is SemaphorAnalyzeResultFieldName;
 
+export declare function isSemaphorDataAppCodegenSummary(value: unknown): value is SemaphorDataAppCodegenSummary;
+
 export declare type MatrixAxisLevelDescriptor = {
     instanceId: string;
     fieldKey: string;
@@ -668,6 +670,8 @@ export declare const SEMAPHOR_ANALYZE_RESULT_FIELD_CONTRACT: {
     readonly omitted: "stringArray";
 };
 
+export declare const SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION: "semaphor-data-app-codegen-summary/v1";
+
 export declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -959,6 +963,118 @@ export declare type SemaphorDashboardViewIntent = {
     text?: string;
 };
 
+export declare type SemaphorDataAppCodegenFieldRef = SemaphorFieldRef & {
+    sourceKey?: string;
+};
+
+export declare type SemaphorDataAppCodegenInput = {
+    id: string;
+    label?: string;
+    type?: string;
+    serverSide?: boolean;
+    fieldRef?: SemaphorDataAppCodegenFieldRef;
+    optionQuery?: SemaphorDataAppCodegenInputOptionQuery;
+    bindings?: SemaphorDataAppCodegenInputBinding[];
+    appliesToViewIds: string[];
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: Array<Record<string, unknown>>;
+};
+
+export declare type SemaphorDataAppCodegenInputBinding = {
+    appliesToViewIds: string[];
+    fieldRef: SemaphorDataAppCodegenFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: Array<Record<string, unknown>>;
+};
+
+export declare type SemaphorDataAppCodegenInputOptionQuery = {
+    id?: string;
+    builder?: string;
+    source?: SemaphorSourceRef | Record<string, unknown>;
+    sourceKey?: string;
+    valueFieldRef?: SemaphorDataAppCodegenFieldRef;
+    labelFieldRef?: SemaphorDataAppCodegenFieldRef;
+    filterFieldRef?: SemaphorDataAppCodegenFieldRef;
+    population?: Record<string, unknown>;
+    dependencies?: Record<string, unknown>;
+    limit?: number;
+    spec?: Record<string, unknown>;
+};
+
+export declare type SemaphorDataAppCodegenSdkSpec = {
+    builder: string;
+    spec: Record<string, unknown>;
+};
+
+export declare type SemaphorDataAppCodegenSummary = {
+    schemaVersion: SemaphorDataAppCodegenSummarySchemaVersion;
+    title: string;
+    purpose?: string;
+    userGoal?: string;
+    nextStep?: string;
+    sources: Array<SemaphorSourceRef | Record<string, unknown>>;
+    inputs: SemaphorDataAppCodegenInput[];
+    views: SemaphorDataAppCodegenView[];
+    filterContracts: SemaphorDataAppFilterContract[];
+    implementationChecklist: SemaphorDataAppImplementationChecklist;
+    nextRequiredTool?: {
+        name: string;
+        reason?: string;
+    };
+    unsupportedInsights?: Array<Record<string, unknown>>;
+    assumptions?: string[];
+    validation?: Record<string, unknown>;
+};
+
+export declare type SemaphorDataAppCodegenSummarySchemaVersion = typeof SEMAPHOR_DATA_APP_CODEGEN_SUMMARY_SCHEMA_VERSION;
+
+export declare type SemaphorDataAppCodegenView = {
+    id: string;
+    title?: string;
+    purpose?: string;
+    visual?: string;
+    visualSpec?: Record<string, unknown>;
+    queryKind?: string;
+    sdkBuilder?: string;
+    sdkSpec?: SemaphorDataAppCodegenSdkSpec;
+    fields?: SemaphorDataAppCodegenFieldRef[];
+    computation?: Record<string, unknown>;
+};
+
+export declare type SemaphorDataAppFilterContract = {
+    inputId: string;
+    label?: string;
+    type?: string;
+    serverSide?: boolean;
+    fieldRef?: SemaphorDataAppCodegenFieldRef;
+    optionQuery?: SemaphorDataAppCodegenInputOptionQuery;
+    bindings: SemaphorDataAppFilterContractBinding[];
+    appliesToViewIds: string[];
+    notAppliedToViewIds: string[];
+};
+
+export declare type SemaphorDataAppFilterContractBinding = {
+    viewId: string;
+    fieldRef: SemaphorDataAppCodegenFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+    relationshipsUsed?: Array<Record<string, unknown>>;
+};
+
+export declare type SemaphorDataAppImplementationChecklist = {
+    schemaVersion?: string;
+    requiredDevtools: {
+        mountRootDevtools: boolean;
+        providerDebugBridge?: string;
+        panelPosition?: string;
+        forbidden?: string[];
+    };
+    requiredInputOptions: Array<Record<string, unknown>>;
+    filterScopeByInput: Array<Record<string, unknown>>;
+    bindingsByView: Record<string, Array<Record<string, unknown>>>;
+    validationCommands: string[];
+    browserSmokeChecks: string[];
+};
+
 export declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
 
 export declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
@@ -1639,6 +1755,11 @@ export declare function validateSemaphorAnalyticsRecoveryPlan(plan: SemaphorAnal
 
 export declare function validateSemaphorDashboardIntent(intent: SemaphorDashboardIntent): SemaphorValidationResult;
 
+export declare function validateSemaphorDataAppCodegenSummary(value: unknown): {
+    ok: boolean;
+    issues: string[];
+};
+
 export declare function validateSemaphorDerivedFieldDefinition(definition: SemaphorDerivedFieldDefinition): SemaphorValidationResult;
 
 export declare function validateSemaphorOperationIntent(intent: SemaphorOperationIntent): SemaphorAnalyticsValidationResult;

package/dist/types/data-app-sdk.d.ts

@@ -705,6 +705,9 @@ export declare type SemaphorDataAppSourceHint = {
 export declare type SemaphorDataAppTrace = {
     traceId: string;
     viewId?: string;
+    viewTitle?: string;
+    visualType?: string;
+    sectionTitle?: string;
     queryId: string;
     queryLabel?: string;
     queryKind: SemaphorQueryDefinition['queryKind'];
@@ -1322,6 +1325,9 @@ declare type SemaphorProtocolVersion = 1;
 
 export declare type SemaphorQueryDebugOptions = {
     viewId?: string;
+    viewTitle?: string;
+    visualType?: string;
+    sectionTitle?: string;
     title?: string;
     sourceHint?: SemaphorDataAppSourceHint;
     sourceHints?: SemaphorDataAppSourceHint[];

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.386",
+  "version": "0.1.388",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",

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

@@ -9,6 +9,7 @@ patterns.
 ```tsx
 import {
   SemaphorDataAppProvider,
+  SemaphorDevtools,
   semaphor,
   useClearInvalidSemaphorInputValue,
   useSemaphorInputs,
@@ -23,6 +24,47 @@ import type {
 } from "react-semaphor/data-app-sdk";
 ```
 
+## Runtime Provider And DevTools
+
+Generated local/dev apps should mount one root DevTools instance and enable the
+debug bridge only outside production embeds.
+
+```tsx
+const runtimeToken = import.meta.env.VITE_SEMAPHOR_PROJECT_TOKEN;
+const enableDevtools =
+  import.meta.env.DEV ||
+  (typeof window !== "undefined" && window.location.hostname === "localhost");
+
+export function Root() {
+  return (
+    <SemaphorDataAppProvider
+      token={runtimeToken}
+      debug={enableDevtools ? { exposeWindowBridge: true } : false}
+    >
+      <App />
+      <SemaphorDevtools
+        initialIsOpen={false}
+        buttonPosition="bottom-right"
+        panelPosition="right"
+      />
+    </SemaphorDataAppProvider>
+  );
+}
+```
+
+Add hook-level debug source hints when they are cheap and non-repetitive:
+
+```tsx
+const result = useSemaphorQuery(revenueBySegment, {
+  debug: {
+    sourceHint: {
+      file: "src/views/RevenueBySegment.tsx",
+      component: "RevenueBySegment",
+    },
+  },
+});
+```
+
 ## Source And Fields
 
 ```tsx
@@ -149,12 +191,37 @@ function SegmentFilter() {
   });
 
   useClearInvalidSemaphorInputValue(segmentHandle, optionsResult);
+
+  const selectedValue = Array.isArray(segmentHandle.value)
+    ? String(segmentHandle.value[0] ?? "")
+    : "";
+
+  return (
+    <select
+      value={selectedValue}
+      onChange={(event) => {
+        const nextValue = event.target.value || null;
+        segmentHandle.setValue(nextValue ? [nextValue] : undefined);
+      }}
+    >
+      <option value="">All segments</option>
+      {(optionsResult.options ?? []).map((option) => (
+        <option key={String(option.value)} value={String(option.value)}>
+          {option.label ?? String(option.value)}
+        </option>
+      ))}
+    </select>
+  );
 }
 ```
 
 Pass the full `optionsResult` to `useClearInvalidSemaphorInputValue`; do not
 pass only `optionsResult.options`, because idle/loading results can also expose
 an empty options array.
+For shadcn/Base UI style selects, type the change callback as accepting
+`string | null` and call `handle.clear()` or `handle.setValue(undefined)` for
+the empty state. For multi-selects and date ranges, narrow `handle.value` with
+`Array.isArray(...)` before indexing or displaying it.
 
 ## Shared Inputs With Source-Specific Bindings