react-semaphor 0.1.568 → 0.1.570

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/README.md +0 -7
  2. package/dist/analytics-protocol/index.js +434 -454
  3. package/dist/appearance/index.js +6 -3
  4. package/dist/appearance-runtime/index.js +1 -1
  5. package/dist/assistant-context/index.js +1 -1
  6. package/dist/brand-studio/index.js +572 -436
  7. package/dist/briefings/index.js +4 -4
  8. package/dist/chunks/appearance-context-BwBp25ZG.js +162 -0
  9. package/dist/chunks/appearance-runtime-provider-BRHYELkC.js +80 -0
  10. package/dist/chunks/assistant-chat-B-Ddyy8b.js +5940 -0
  11. package/dist/chunks/{bookmark-impact-CJ-65omV.js → bookmark-impact-DCYD-6Fr.js} +2 -2
  12. package/dist/chunks/{bookmark-state-Du3s13_V.js → bookmark-state-CflS88gq.js} +251 -250
  13. package/dist/chunks/brand-B4BdpAB_.js +54 -0
  14. package/dist/chunks/{card-filter-builder-BBuB99GZ.js → card-filter-builder-0VvKmRst.js} +992 -991
  15. package/dist/chunks/{comparison-window-caption-CMLb3mut.js → comparison-window-caption-PtcDWvkN.js} +252 -253
  16. package/dist/chunks/{dashboard-YnWZC4dK.js → dashboard-DxGIr1vZ.js} +1 -1
  17. package/dist/chunks/{dashboard-briefing-launcher-BF89TU2h.js → dashboard-briefing-launcher-B-quOOOQ.js} +253 -253
  18. package/dist/chunks/{dashboard-controls-atHc1EjP.js → dashboard-controls-Caodx80b.js} +288 -285
  19. package/dist/chunks/dashboard-json-Ct-AGDHF.js +66 -0
  20. package/dist/chunks/{dates-CKO05ino.js → dates-B9mL8BHE.js} +16 -15
  21. package/dist/chunks/edit-Bpdh_P_a.js +226 -0
  22. package/dist/chunks/{edit-dashboard-visual-DdmTfn-J.js → edit-dashboard-visual-DeDTuYB5.js} +2257 -2270
  23. package/dist/chunks/{filter-reach-copy-jZGzK_IH.js → filter-reach-copy-BSY33ro5.js} +1440 -1301
  24. package/dist/chunks/filter-value-text-DvvSNlho.js +146 -0
  25. package/dist/chunks/index-BVKzKl5d.js +90 -0
  26. package/dist/chunks/{index-RNaTnE3m.js → index-CV_Kzou0.js} +233 -223
  27. package/dist/chunks/{index-CPNZW0mu.js → index-y3HUzRNk.js} +76 -77
  28. package/dist/chunks/{layout-grid-0hIlqEtk.js → layout-grid-8rR-LPTk.js} +1 -1
  29. package/dist/chunks/{list-filter-DkgoCeBm.js → list-filter-C1-uTgjR.js} +1 -1
  30. package/dist/chunks/matrix-analytical-definition-dkS8szLM.js +1253 -0
  31. package/dist/chunks/matrix-member-presentation-DRa-9e6Q.js +169 -0
  32. package/dist/chunks/{matrix-operation-contract-Eb6elidS.js → matrix-operation-contract-DCVinw1o.js} +122 -122
  33. package/dist/chunks/{metric-comparison-ChXUFaZu.js → metric-comparison-n9NsIa-2.js} +175 -128
  34. package/dist/chunks/paintbrush-aR17Z3C9.js +27 -0
  35. package/dist/chunks/{palette-4vf2BEEg.js → palette-a5FCZKFI.js} +1 -1
  36. package/dist/chunks/{_commonjsHelpers-DimLPMtv.js → pickers-DkqmtnTL.js} +352 -290
  37. package/dist/chunks/pivot-result-contract-expectations-C-HnUKYe.js +55 -0
  38. package/dist/chunks/{pivot-result-identity-BlbLrqaC.js → pivot-result-identity-B89X5xjb.js} +1 -1
  39. package/dist/chunks/raw-temporal-value-DdT0s47W.js +159 -0
  40. package/dist/chunks/{report-preferences-dialog-Mbd-I0wV.js → report-preferences-dialog-Yvhv3WX2.js} +95 -97
  41. package/dist/chunks/{report-runtime-context-DnA_PiKo.js → report-runtime-context-BhPzLTbS.js} +1 -1
  42. package/dist/chunks/{resolve-dashboard-input-context-Du0fjN3h.js → resolve-dashboard-input-context-Lkbwycwe.js} +5491 -5683
  43. package/dist/chunks/resolver-DG_tfEpt.js +156 -0
  44. package/dist/chunks/{save-D6pHmSSP.js → save-D985VvYp.js} +1 -1
  45. package/dist/chunks/{saved-dashboard-context-y8N6RvjS.js → saved-dashboard-context-DC_TEd6y.js} +6 -6
  46. package/dist/chunks/schema-C9NPiIru.js +2568 -0
  47. package/dist/chunks/{semaphor-ready-indicator-BSEdUq40.js → semaphor-ready-indicator-ByFvqHEO.js} +35916 -36001
  48. package/dist/chunks/{shelf-drop-preview-context-D7QqPl36.js → shelf-drop-preview-context-CjoVaK6J.js} +64 -66
  49. package/dist/chunks/{stored-dashboard-d3xQYxBD.js → stored-dashboard-C0hekXiI.js} +332 -333
  50. package/dist/chunks/{code-editor-DJNOsgJH.js → style-sheet-parts-C7qGZuH1.js} +2402 -2040
  51. package/dist/chunks/{table-export-sheet--DUKWk6o.js → table-export-sheet-CP8zSOhj.js} +1 -1
  52. package/dist/chunks/{temporal-input-presentation--2r9BLr0.js → temporal-input-presentation-CqbJjIuu.js} +18 -18
  53. package/dist/chunks/{token-types-C8JymO8s.js → token-types-iKMplaBL.js} +1 -1
  54. package/dist/chunks/{upload-Cf3wXZT8.js → upload-CiGNKJ_0.js} +1 -1
  55. package/dist/chunks/validators-B8fpdinG.js +3651 -0
  56. package/dist/chunks/{variable-draft-DOX03R4A.js → variable-draft-9-huI1h4.js} +4 -4
  57. package/dist/dashboard/index.js +2 -2
  58. package/dist/dashboard-authoring/index.js +1888 -1826
  59. package/dist/format-utils/index.js +230 -231
  60. package/dist/index.js +349 -353
  61. package/dist/layouts/index.js +1 -1
  62. package/dist/report-runtime-context/index.js +1 -1
  63. package/dist/style.css +1 -1
  64. package/dist/surfboard/index.js +2 -2
  65. package/dist/types/appearance/index.d.ts +1 -0
  66. package/dist/types/brand-studio/brand-studio-draft.d.ts +7 -0
  67. package/dist/types/brand-studio/index.d.ts +1 -1
  68. package/dist/types/components/briefings/briefing-author/run-model.d.ts +1 -2
  69. package/dist/types/components/providers/appearance-runtime-provider.d.ts +4 -1
  70. package/dist/types/components/sharing-and-management/hooks/use-resource-management.d.ts +0 -2
  71. package/dist/types/components/sharing-and-management/utils/types.d.ts +0 -72
  72. package/dist/types/components/surfboard/filter/types.d.ts +5 -4
  73. package/dist/types/components/ui-custom/date-range-presets.d.ts +1 -17
  74. package/dist/types/components/visual/data-table/hooks/use-data-table-logic.d.ts +0 -1
  75. package/dist/types/components/visual/data-table/types/data-table.d.ts +0 -9
  76. package/dist/types/components/visual/data-table/utils/pagination-utils.d.ts +0 -19
  77. package/dist/types/components/visual/shared/utils/table-column-order.d.ts +0 -1
  78. package/dist/types/index.js +9 -9
  79. package/dist/types/lib/appearance/aliases.d.ts +42 -0
  80. package/dist/types/lib/appearance/compiler.d.ts +6 -0
  81. package/dist/types/lib/appearance/defaults.d.ts +6 -0
  82. package/dist/types/lib/appearance/index.d.ts +2 -0
  83. package/dist/types/lib/appearance/normalize-organization.d.ts +17 -0
  84. package/dist/types/lib/appearance/resolver.d.ts +2 -2
  85. package/dist/types/lib/appearance/types.d.ts +38 -1
  86. package/dist/types/lib/charts/types.d.ts +6 -2
  87. package/dist/types/lib/dashboard/semantic-dataset-references.d.ts +0 -1
  88. package/dist/types/lib/dashboard-inputs/dashboard-input-values.d.ts +0 -2
  89. package/dist/types/lib/dashboard-variables/types.d.ts +1 -6
  90. package/dist/types/lib/download-pdf.d.ts +0 -1
  91. package/dist/types/lib/hooks/use-dashboard.d.ts +3 -4
  92. package/dist/types/lib/hooks/use-date-filter.d.ts +3 -3
  93. package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts +1 -1
  94. package/dist/types/lib/stores/dashboard-store.d.ts +15 -6
  95. package/dist/types/lib/stores/editor-store.d.ts +0 -1
  96. package/dist/types/lib/stores/table-actions.d.ts +0 -1
  97. package/dist/types/lib/table-formatting/table-formatting-css.d.ts +0 -5
  98. package/dist/types/lib/types/common-types.d.ts +3 -2
  99. package/dist/types/lib/types/explorer-types.d.ts +2 -2
  100. package/dist/types/lib/types/index.d.ts +1 -1
  101. package/dist/types/lib/types/summary-types.d.ts +0 -5
  102. package/dist/types/lib/utils/card-definition.d.ts +7 -7
  103. package/dist/types/shared/analytics-protocol/agent-time-window.d.ts +84 -0
  104. package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +4 -4
  105. package/dist/types/shared/analytics-protocol/applied-constraints.d.ts +2 -2
  106. package/dist/types/shared/analytics-protocol/contracts.d.ts +8 -17
  107. package/dist/types/shared/analytics-protocol/execution-input-schemas.d.ts +10 -10
  108. package/dist/types/shared/analytics-protocol/fixtures.d.ts +3 -2
  109. package/dist/types/shared/analytics-protocol/index.d.ts +2 -4
  110. package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts +72 -72
  111. package/dist/types/shared/analytics-protocol/relative-date/describe.d.ts +18 -0
  112. package/dist/types/shared/analytics-protocol/relative-date/index.d.ts +7 -0
  113. package/dist/types/shared/analytics-protocol/relative-date/limits.d.ts +3 -0
  114. package/dist/types/shared/analytics-protocol/relative-date/presets.d.ts +11 -0
  115. package/dist/types/shared/analytics-protocol/relative-date/resolve.d.ts +49 -0
  116. package/dist/types/shared/analytics-protocol/relative-date/schemas.d.ts +76 -0
  117. package/dist/types/shared/analytics-protocol/relative-date/traits.d.ts +51 -0
  118. package/dist/types/shared/analytics-protocol/relative-date/window.d.ts +111 -0
  119. package/dist/types/shared/analytics-protocol/selection-contract.d.ts +1 -1
  120. package/dist/types/shared/assistant-protocol/context.d.ts +30 -30
  121. package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +0 -2
  122. package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +344 -1772
  123. package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +4 -1
  124. package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +8 -4
  125. package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +9 -0
  126. package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +104 -104
  127. package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +20 -20
  128. package/dist/types/shared/dashboard-authoring/dashboard-style/bounds.d.ts +17 -0
  129. package/dist/types/shared/dashboard-authoring/dashboard-style/brand.d.ts +20 -0
  130. package/dist/types/shared/dashboard-authoring/dashboard-style/edit-words.d.ts +7 -0
  131. package/dist/types/shared/dashboard-authoring/dashboard-style/edit.d.ts +19 -0
  132. package/dist/types/shared/dashboard-authoring/dashboard-style/index.d.ts +15 -0
  133. package/dist/types/shared/dashboard-authoring/dashboard-style/layers.d.ts +19 -0
  134. package/dist/types/shared/dashboard-authoring/dashboard-style/legacy.d.ts +21 -0
  135. package/dist/types/shared/dashboard-authoring/dashboard-style/parse.d.ts +18 -0
  136. package/dist/types/shared/dashboard-authoring/dashboard-style/pickers.d.ts +12 -0
  137. package/dist/types/shared/dashboard-authoring/dashboard-style/types.d.ts +122 -0
  138. package/dist/types/shared/dashboard-authoring/dashboard-style/view.d.ts +10 -0
  139. package/dist/types/shared/dashboard-authoring/index.d.ts +1 -0
  140. package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +11 -0
  141. package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +23 -0
  142. package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +10 -2
  143. package/dist/types/shared/format-utils/filter-detail.d.ts +2 -8
  144. package/dist/types/shared/format-utils/filter-line.d.ts +2 -2
  145. package/dist/types/shared/format-utils/matrix-continuation.d.ts +10 -10
  146. package/dist/types/shared/temporal/index.d.ts +0 -2
  147. package/dist/types/shared/temporal/temporal-parity-fixtures.d.ts +2 -2
  148. package/package.json +7 -26
  149. package/DATA_APP_SDK.md +0 -339
  150. package/dist/chunks/appearance-context-DEYtWinQ.js +0 -126
  151. package/dist/chunks/appearance-runtime-provider-B-M8gwlZ.js +0 -81
  152. package/dist/chunks/assistant-chat-BN5I8KuN.js +0 -8849
  153. package/dist/chunks/color-CJvdlFM_.js +0 -2162
  154. package/dist/chunks/dashboard-json-Cxp3inxd.js +0 -68
  155. package/dist/chunks/filter-value-text-7zhmth1S.js +0 -163
  156. package/dist/chunks/index-CLIro-EG.js +0 -425
  157. package/dist/chunks/index-CuHybtft.js +0 -51
  158. package/dist/chunks/matrix-analytical-definition-C9xB_T84.js +0 -717
  159. package/dist/chunks/matrix-card-BSUeSXpD.js +0 -42
  160. package/dist/chunks/matrix-member-presentation-DZNgQpUq.js +0 -105
  161. package/dist/chunks/operators-B3zZoskU.js +0 -66
  162. package/dist/chunks/pivot-result-contract-expectations-Ddh1rNz5.js +0 -56
  163. package/dist/chunks/raw-temporal-value-Bqz8wc7L.js +0 -242
  164. package/dist/chunks/selection-reducer-OaJ-N5uN.js +0 -46
  165. package/dist/chunks/source-entity-resolution-DF6GulDn.js +0 -607
  166. package/dist/chunks/validators-wtjw0aw6.js +0 -3332
  167. package/dist/data-app-sdk/index.js +0 -1412
  168. package/dist/data-app-sdk-adapters/index.js +0 -361
  169. package/dist/data-app-sdk-validation/index.js +0 -1031
  170. package/dist/types/components/sharing-and-management/utils/group-types.d.ts +0 -105
  171. package/dist/types/data-app-sdk/adapters.d.ts +0 -35
  172. package/dist/types/data-app-sdk/builders.d.ts +0 -62
  173. package/dist/types/data-app-sdk/contracts.d.ts +0 -419
  174. package/dist/types/data-app-sdk/executor.d.ts +0 -5
  175. package/dist/types/data-app-sdk/field-catalog-validation.d.ts +0 -29
  176. package/dist/types/data-app-sdk/hooks.d.ts +0 -11
  177. package/dist/types/data-app-sdk/index.d.ts +0 -9
  178. package/dist/types/data-app-sdk/provider.d.ts +0 -8
  179. package/dist/types/data-app-sdk/relationship-aware-field-policy.d.ts +0 -21
  180. package/dist/types/data-app-sdk/selection.d.ts +0 -2
  181. package/dist/types/data-app-sdk/validation.d.ts +0 -58
  182. package/dist/types/data-app-sdk-adapters.d.ts +0 -2
  183. package/dist/types/data-app-sdk-validation.d.ts +0 -2
  184. package/dist/types/data-app-sdk.d.ts +0 -2
  185. package/dist/types/shared/analytics-protocol/relative-date-filter.d.ts +0 -68
  186. package/dist/types/shared/analytics-protocol/relative-date-label.d.ts +0 -20
  187. package/dist/types/shared/analytics-protocol/time-window-schema.d.ts +0 -314
  188. package/dist/types/shared/analytics-protocol/time-window.d.ts +0 -52
  189. package/dist/types/shared/temporal/relative-date.d.ts +0 -21
  190. package/dist/types/shared/temporal/time-window-periods.d.ts +0 -21
  191. package/src/data-app-sdk/README.md +0 -402
@@ -1,402 +0,0 @@
1
- # Data App SDK Quick Reference
2
-
3
- > Frozen: no new work goes into this SDK. A false start, to be retired; no
4
- > replacement SDK is planned for custom looks (they go through the dashboard
5
- > runtime).
6
-
7
- Use this file as the public contract quick reference for Data App SDK code.
8
- Do not inspect SDK implementation internals to discover these patterns.
9
-
10
- ## Imports
11
-
12
- ```tsx
13
- import {
14
- SemaphorDataAppProvider,
15
- semaphor,
16
- useClearInvalidSemaphorInputValue,
17
- useSemaphorInputs,
18
- useSemaphorSelection,
19
- useSemaphorQuery,
20
- } from "react-semaphor/data-app-sdk";
21
-
22
- import type {
23
- SemaphorQueryResult,
24
- SemaphorRecordsField,
25
- SemaphorRecordsQueryResult,
26
- SemaphorSourceRef,
27
- } from "react-semaphor/data-app-sdk";
28
- ```
29
-
30
- ## Runtime Provider
31
-
32
- ```tsx
33
- const runtimeToken = import.meta.env.VITE_SEMAPHOR_PROJECT_TOKEN;
34
-
35
- export function Root() {
36
- return (
37
- <SemaphorDataAppProvider token={runtimeToken} debug={import.meta.env.DEV}>
38
- <App />
39
- </SemaphorDataAppProvider>
40
- );
41
- }
42
- ```
43
-
44
- With `debug` on, each query asks the server for debug detail. For an
45
- organization user, the result's `executionResult.metadata.dataAppDebug` then
46
- carries the request id, duration and compiled SQL. Keep it off in production
47
- embeds.
48
-
49
- ## Query State
50
-
51
- `useSemaphorQuery` returns normal loading/error fields plus the governed
52
- Semaphor execution result fields. Generated apps should branch on these public
53
- fields instead of inspecting nested payload internals.
54
-
55
- Generated app code should keep query specs, input handles, and result rendering
56
- separate: construct sources/fields/queries from the accepted contract, pass
57
- generated input handles into every subscribed query, and render KPI, records,
58
- matrix, and analysis payloads from the public hook result. Do not rebuild source
59
- refs, filter bindings, row keys, matrix grids, or execution-result state inside
60
- card components.
61
-
62
- ```tsx
63
- const result = useSemaphorQuery(revenueBySegment, {
64
- inputs: [segmentHandle],
65
- });
66
-
67
- if (result.isLoading && !result.isStale) return <Spinner />;
68
- if (result.isStale) return <Table rows={result.records} subdued />;
69
-
70
- if (result.status === "error") {
71
- return (
72
- <ErrorPanel
73
- message={result.error?.message ?? "Query failed"}
74
- issues={result.validation?.errors ?? result.error?.validationIssues ?? []}
75
- />
76
- );
77
- }
78
-
79
- if (result.isEmpty) return <EmptyState />;
80
-
81
- return (
82
- <>
83
- {result.isPartial ? <WarningBanner issues={result.coverage?.warnings} /> : null}
84
- {result.isFiltered ? <FilterIndicator /> : null}
85
- {result.isValidated ? <ValidationBadge status={result.executionStatus} /> : null}
86
- <Table rows={result.records} />
87
- </>
88
- );
89
- ```
90
-
91
- Important state fields:
92
-
93
- - `executionStatus`: governed execution status, usually `answered`, `partial`,
94
- or `failed` when the server or SDK produced an execution result.
95
- - `executionResult`: full `SemaphorAnalyticsExecutionResult` for audit,
96
- diagnostics, coverage, and result metadata.
97
- - `validation`, `coverage`, and `diagnosticFeedback`: top-level aliases from
98
- `executionResult` or structured SDK validation errors.
99
- - `isEmpty`: successful query returned no meaningful rows/options/cells/value.
100
- - `isPartial`: execution status, coverage, diagnostic feedback, or row-limit
101
- metadata says the result is incomplete.
102
- - `isFiltered`: one or more active filter inputs or selections were applied to
103
- the query.
104
- - `isStale`: previous successful data is being shown while newer inputs load.
105
- - `isValidated`: validation metadata is present.
106
-
107
- Validation failures produce a structured `SemaphorDataAppQueryError` in
108
- `result.error`, with `kind: "data_app_query_error"`, `validation`,
109
- `validationIssues`, and `executionResult` when available.
110
-
111
- ## Source And Fields
112
-
113
- ```tsx
114
- const source = {
115
- kind: "semantic",
116
- domainId: "sales",
117
- datasetName: "orders",
118
- } satisfies SemaphorSourceRef;
119
-
120
- const revenue = {
121
- name: "revenue",
122
- label: "Revenue",
123
- role: "measure",
124
- dataType: "number",
125
- aggregate: "SUM",
126
- source,
127
- } satisfies SemaphorRecordsField;
128
-
129
- const segment = {
130
- name: "segment",
131
- label: "Segment",
132
- role: "dimension",
133
- dataType: "string",
134
- source,
135
- } satisfies SemaphorRecordsField;
136
- ```
137
-
138
- Use `SemaphorRecordsField` for `semaphor.records(...)` fields so every selected
139
- field has a concrete role.
140
-
141
- ## Metric
142
-
143
- ```tsx
144
- const revenueKpi = semaphor.metric({
145
- id: "revenue-kpi",
146
- source,
147
- measures: [revenue],
148
- primaryMeasure: revenue,
149
- });
150
-
151
- const result = useSemaphorQuery(revenueKpi);
152
- ```
153
-
154
- ## Records
155
-
156
- ```tsx
157
- const revenueBySegment = semaphor.records({
158
- id: "revenue-by-segment",
159
- source,
160
- fields: [segment, revenue],
161
- orderBy: { field: revenue, direction: "desc" },
162
- limit: 10,
163
- });
164
-
165
- const result = useSemaphorQuery(revenueBySegment);
166
- ```
167
-
168
- ## Click Selection
169
-
170
- Create one selection input per source chart. Keep it separate from scalar filter
171
- and control inputs, pass its handle through the `selections` query option, and
172
- render its removable chips in the app.
173
-
174
- ```tsx
175
- const segmentSelection = semaphor.selection({
176
- id: "segment-chart-selection",
177
- label: "Segment chart selection",
178
- fields: [segment],
179
- });
180
-
181
- function SegmentDashboard() {
182
- const selection = useSemaphorSelection(segmentSelection);
183
- const chartResult = useSemaphorQuery(revenueBySegment);
184
- const detailResult = useSemaphorQuery(revenueBySegment, {
185
- selections: [selection],
186
- });
187
-
188
- const enterprise = {
189
- conditions: [
190
- { field: segment, operator: "=" as const, value: "Enterprise" },
191
- ],
192
- };
193
-
194
- return (
195
- <>
196
- <SegmentChart result={chartResult} selection={selection} />
197
- <button onClick={() => selection.select(enterprise, { kind: "toggle" })}>
198
- Enterprise
199
- </button>
200
- {selection.tuples.map((tuple) => (
201
- <button
202
- key={JSON.stringify(tuple)}
203
- onClick={() => selection.select(tuple, { kind: "toggle" })}
204
- >
205
- {tuple.conditions.map((condition) => String(condition.value)).join(" · ")} ×
206
- </button>
207
- ))}
208
- <RecordsTable result={detailResult} />
209
- </>
210
- );
211
- }
212
- ```
213
-
214
- The source chart query deliberately omits its own selection handle, so selected
215
- marks stay visible. Pass the handle to every query that should respond.
216
-
217
- A tuple combines its conditions with AND. Multiple tuples combine with OR, so
218
- `(region = West AND segment = Enterprise) OR (region = East AND segment = SMB)`
219
- stays grouped. The shared reducer caps a selection at 100 distinct tuples and
220
- returns `limitReached`; show that outcome beside the chips. Selection handles
221
- have no `toAnalyticsInput()` method and never belong in `inputs`.
222
-
223
- ## Row Access
224
-
225
- Read rows with `columns[].key`; display `columns[].label`.
226
-
227
- ```tsx
228
- function RecordsTable({ result }: { result: SemaphorRecordsQueryResult }) {
229
- const records = result.records ?? [];
230
- const columns = result.columns ?? [];
231
-
232
- return (
233
- <table>
234
- <thead>
235
- <tr>
236
- {columns.map((column) => (
237
- <th key={column.key}>{column.label || column.name}</th>
238
- ))}
239
- </tr>
240
- </thead>
241
- <tbody>
242
- {records.map((row, rowIndex) => (
243
- <tr key={rowIndex}>
244
- {columns.map((column) => (
245
- <td key={column.key}>{String(row[column.key] ?? "")}</td>
246
- ))}
247
- </tr>
248
- ))}
249
- </tbody>
250
- </table>
251
- );
252
- }
253
- ```
254
-
255
- When accepting a generic `SemaphorQueryResult`, narrow before reading records:
256
-
257
- ```tsx
258
- function queryRecords(result: SemaphorQueryResult) {
259
- return "records" in result && Array.isArray(result.records)
260
- ? result.records
261
- : [];
262
- }
263
- ```
264
-
265
- ## Input Options
266
-
267
- ```tsx
268
- const segmentFilter = semaphor.filter({
269
- id: "segment",
270
- label: "Segment",
271
- field: segment,
272
- operator: "in",
273
- });
274
-
275
- const segmentOptions = semaphor.inputOptions({
276
- id: "segment-options",
277
- inputId: "segment",
278
- source,
279
- labelField: segment,
280
- valueField: segment,
281
- limit: 100,
282
- });
283
-
284
- function SegmentFilter() {
285
- const [segmentHandle] = useSemaphorInputs([segmentFilter]);
286
- const optionsResult = useSemaphorQuery(segmentOptions);
287
-
288
- useClearInvalidSemaphorInputValue(segmentHandle, optionsResult);
289
-
290
- const selectedValue = Array.isArray(segmentHandle.value)
291
- ? String(segmentHandle.value[0] ?? "")
292
- : "";
293
-
294
- return (
295
- <select
296
- value={selectedValue}
297
- onChange={(event) => {
298
- const nextValue = event.target.value || null;
299
- segmentHandle.setValue(nextValue ? [nextValue] : undefined);
300
- }}
301
- >
302
- <option value="">All segments</option>
303
- {(optionsResult.options ?? []).map((option) => (
304
- <option key={String(option.value)} value={String(option.value)}>
305
- {option.label ?? String(option.value)}
306
- </option>
307
- ))}
308
- </select>
309
- );
310
- }
311
- ```
312
-
313
- Pass the full `optionsResult` to `useClearInvalidSemaphorInputValue`; do not
314
- pass only `optionsResult.options`, because idle/loading results can also expose
315
- an empty options array.
316
- For shadcn/Base UI style selects, type the change callback as accepting
317
- `string | null` and call `handle.clear()` or `handle.setValue(undefined)` for
318
- the empty state. For multi-selects and date ranges, narrow `handle.value` with
319
- `Array.isArray(...)` before indexing or displaying it.
320
-
321
- ## Shared Inputs With Source-Specific Bindings
322
-
323
- Use `semaphor.bindInput(...)` when one visible input maps to different query
324
- fields.
325
-
326
- ```tsx
327
- const dateRange = semaphor.filter({
328
- id: "date_range",
329
- label: "Date Range",
330
- field: orderDate,
331
- operator: "between",
332
- });
333
-
334
- function Dashboard() {
335
- const [dateRangeHandle] = useSemaphorInputs([dateRange]);
336
-
337
- const orders = useSemaphorQuery(ordersQuery, {
338
- inputs: [semaphor.bindInput(dateRangeHandle, { field: orderDate })],
339
- });
340
- const invoices = useSemaphorQuery(invoicesQuery, {
341
- inputs: [semaphor.bindInput(dateRangeHandle, { field: invoiceDate })],
342
- });
343
-
344
- const range = Array.isArray(dateRangeHandle.value)
345
- ? dateRangeHandle.value
346
- : [];
347
- const [start, end] = range;
348
- }
349
- ```
350
-
351
- Narrow `handle.value` with `Array.isArray(...)` before indexing date ranges or
352
- multi-select values.
353
-
354
- ## Related Dimension Filters
355
-
356
- Use a related human-readable dimension as the visible filter and preserve the
357
- relationship hint when binding that input into each fact query.
358
-
359
- ```tsx
360
- const materialFamilyFilter = semaphor.filter<string[]>({
361
- id: "material_family",
362
- label: "Material Family",
363
- field: materialFamily,
364
- operator: "in",
365
- multi: true,
366
- });
367
-
368
- const materialOptions = semaphor.inputOptions({
369
- id: "material-family-options",
370
- inputId: "material_family",
371
- source: materialSource,
372
- labelField: materialFamily,
373
- valueField: materialFamily,
374
- limit: 100,
375
- });
376
-
377
- function OpsViews() {
378
- const materialHandle = useSemaphorInput(materialFamilyFilter);
379
- useSemaphorQuery(materialOptions);
380
-
381
- useSemaphorQuery(purchaseQuery, {
382
- inputs: [
383
- semaphor.bindInput(materialHandle, {
384
- field: materialFamily,
385
- relationshipHint: { relationshipIds: ["purchase_material"] },
386
- }),
387
- ],
388
- });
389
-
390
- useSemaphorQuery(salesQuery, {
391
- inputs: [
392
- semaphor.bindInput(materialHandle, {
393
- field: materialFamily,
394
- relationshipHint: { relationshipIds: ["sales_material"] },
395
- }),
396
- ],
397
- });
398
- }
399
- ```
400
-
401
- Do not fetch broad rows and filter or join them in React to simulate
402
- related-dimension behavior. Let Semaphor execute the relationship-aware filter.