react-semaphor 0.1.385 → 0.1.387

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.385",
+  "version": "0.1.387",
   "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