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.
- package/README.md +0 -7
- package/dist/analytics-protocol/index.js +434 -454
- package/dist/appearance/index.js +6 -3
- package/dist/appearance-runtime/index.js +1 -1
- package/dist/assistant-context/index.js +1 -1
- package/dist/brand-studio/index.js +572 -436
- package/dist/briefings/index.js +4 -4
- package/dist/chunks/appearance-context-BwBp25ZG.js +162 -0
- package/dist/chunks/appearance-runtime-provider-BRHYELkC.js +80 -0
- package/dist/chunks/assistant-chat-B-Ddyy8b.js +5940 -0
- package/dist/chunks/{bookmark-impact-CJ-65omV.js → bookmark-impact-DCYD-6Fr.js} +2 -2
- package/dist/chunks/{bookmark-state-Du3s13_V.js → bookmark-state-CflS88gq.js} +251 -250
- package/dist/chunks/brand-B4BdpAB_.js +54 -0
- package/dist/chunks/{card-filter-builder-BBuB99GZ.js → card-filter-builder-0VvKmRst.js} +992 -991
- package/dist/chunks/{comparison-window-caption-CMLb3mut.js → comparison-window-caption-PtcDWvkN.js} +252 -253
- package/dist/chunks/{dashboard-YnWZC4dK.js → dashboard-DxGIr1vZ.js} +1 -1
- package/dist/chunks/{dashboard-briefing-launcher-BF89TU2h.js → dashboard-briefing-launcher-B-quOOOQ.js} +253 -253
- package/dist/chunks/{dashboard-controls-atHc1EjP.js → dashboard-controls-Caodx80b.js} +288 -285
- package/dist/chunks/dashboard-json-Ct-AGDHF.js +66 -0
- package/dist/chunks/{dates-CKO05ino.js → dates-B9mL8BHE.js} +16 -15
- package/dist/chunks/edit-Bpdh_P_a.js +226 -0
- package/dist/chunks/{edit-dashboard-visual-DdmTfn-J.js → edit-dashboard-visual-DeDTuYB5.js} +2257 -2270
- package/dist/chunks/{filter-reach-copy-jZGzK_IH.js → filter-reach-copy-BSY33ro5.js} +1440 -1301
- package/dist/chunks/filter-value-text-DvvSNlho.js +146 -0
- package/dist/chunks/index-BVKzKl5d.js +90 -0
- package/dist/chunks/{index-RNaTnE3m.js → index-CV_Kzou0.js} +233 -223
- package/dist/chunks/{index-CPNZW0mu.js → index-y3HUzRNk.js} +76 -77
- package/dist/chunks/{layout-grid-0hIlqEtk.js → layout-grid-8rR-LPTk.js} +1 -1
- package/dist/chunks/{list-filter-DkgoCeBm.js → list-filter-C1-uTgjR.js} +1 -1
- package/dist/chunks/matrix-analytical-definition-dkS8szLM.js +1253 -0
- package/dist/chunks/matrix-member-presentation-DRa-9e6Q.js +169 -0
- package/dist/chunks/{matrix-operation-contract-Eb6elidS.js → matrix-operation-contract-DCVinw1o.js} +122 -122
- package/dist/chunks/{metric-comparison-ChXUFaZu.js → metric-comparison-n9NsIa-2.js} +175 -128
- package/dist/chunks/paintbrush-aR17Z3C9.js +27 -0
- package/dist/chunks/{palette-4vf2BEEg.js → palette-a5FCZKFI.js} +1 -1
- package/dist/chunks/{_commonjsHelpers-DimLPMtv.js → pickers-DkqmtnTL.js} +352 -290
- package/dist/chunks/pivot-result-contract-expectations-C-HnUKYe.js +55 -0
- package/dist/chunks/{pivot-result-identity-BlbLrqaC.js → pivot-result-identity-B89X5xjb.js} +1 -1
- package/dist/chunks/raw-temporal-value-DdT0s47W.js +159 -0
- package/dist/chunks/{report-preferences-dialog-Mbd-I0wV.js → report-preferences-dialog-Yvhv3WX2.js} +95 -97
- package/dist/chunks/{report-runtime-context-DnA_PiKo.js → report-runtime-context-BhPzLTbS.js} +1 -1
- package/dist/chunks/{resolve-dashboard-input-context-Du0fjN3h.js → resolve-dashboard-input-context-Lkbwycwe.js} +5491 -5683
- package/dist/chunks/resolver-DG_tfEpt.js +156 -0
- package/dist/chunks/{save-D6pHmSSP.js → save-D985VvYp.js} +1 -1
- package/dist/chunks/{saved-dashboard-context-y8N6RvjS.js → saved-dashboard-context-DC_TEd6y.js} +6 -6
- package/dist/chunks/schema-C9NPiIru.js +2568 -0
- package/dist/chunks/{semaphor-ready-indicator-BSEdUq40.js → semaphor-ready-indicator-ByFvqHEO.js} +35916 -36001
- package/dist/chunks/{shelf-drop-preview-context-D7QqPl36.js → shelf-drop-preview-context-CjoVaK6J.js} +64 -66
- package/dist/chunks/{stored-dashboard-d3xQYxBD.js → stored-dashboard-C0hekXiI.js} +332 -333
- package/dist/chunks/{code-editor-DJNOsgJH.js → style-sheet-parts-C7qGZuH1.js} +2402 -2040
- package/dist/chunks/{table-export-sheet--DUKWk6o.js → table-export-sheet-CP8zSOhj.js} +1 -1
- package/dist/chunks/{temporal-input-presentation--2r9BLr0.js → temporal-input-presentation-CqbJjIuu.js} +18 -18
- package/dist/chunks/{token-types-C8JymO8s.js → token-types-iKMplaBL.js} +1 -1
- package/dist/chunks/{upload-Cf3wXZT8.js → upload-CiGNKJ_0.js} +1 -1
- package/dist/chunks/validators-B8fpdinG.js +3651 -0
- package/dist/chunks/{variable-draft-DOX03R4A.js → variable-draft-9-huI1h4.js} +4 -4
- package/dist/dashboard/index.js +2 -2
- package/dist/dashboard-authoring/index.js +1888 -1826
- package/dist/format-utils/index.js +230 -231
- package/dist/index.js +349 -353
- package/dist/layouts/index.js +1 -1
- package/dist/report-runtime-context/index.js +1 -1
- package/dist/style.css +1 -1
- package/dist/surfboard/index.js +2 -2
- package/dist/types/appearance/index.d.ts +1 -0
- package/dist/types/brand-studio/brand-studio-draft.d.ts +7 -0
- package/dist/types/brand-studio/index.d.ts +1 -1
- package/dist/types/components/briefings/briefing-author/run-model.d.ts +1 -2
- package/dist/types/components/providers/appearance-runtime-provider.d.ts +4 -1
- package/dist/types/components/sharing-and-management/hooks/use-resource-management.d.ts +0 -2
- package/dist/types/components/sharing-and-management/utils/types.d.ts +0 -72
- package/dist/types/components/surfboard/filter/types.d.ts +5 -4
- package/dist/types/components/ui-custom/date-range-presets.d.ts +1 -17
- package/dist/types/components/visual/data-table/hooks/use-data-table-logic.d.ts +0 -1
- package/dist/types/components/visual/data-table/types/data-table.d.ts +0 -9
- package/dist/types/components/visual/data-table/utils/pagination-utils.d.ts +0 -19
- package/dist/types/components/visual/shared/utils/table-column-order.d.ts +0 -1
- package/dist/types/index.js +9 -9
- package/dist/types/lib/appearance/aliases.d.ts +42 -0
- package/dist/types/lib/appearance/compiler.d.ts +6 -0
- package/dist/types/lib/appearance/defaults.d.ts +6 -0
- package/dist/types/lib/appearance/index.d.ts +2 -0
- package/dist/types/lib/appearance/normalize-organization.d.ts +17 -0
- package/dist/types/lib/appearance/resolver.d.ts +2 -2
- package/dist/types/lib/appearance/types.d.ts +38 -1
- package/dist/types/lib/charts/types.d.ts +6 -2
- package/dist/types/lib/dashboard/semantic-dataset-references.d.ts +0 -1
- package/dist/types/lib/dashboard-inputs/dashboard-input-values.d.ts +0 -2
- package/dist/types/lib/dashboard-variables/types.d.ts +1 -6
- package/dist/types/lib/download-pdf.d.ts +0 -1
- package/dist/types/lib/hooks/use-dashboard.d.ts +3 -4
- package/dist/types/lib/hooks/use-date-filter.d.ts +3 -3
- package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts +1 -1
- package/dist/types/lib/stores/dashboard-store.d.ts +15 -6
- package/dist/types/lib/stores/editor-store.d.ts +0 -1
- package/dist/types/lib/stores/table-actions.d.ts +0 -1
- package/dist/types/lib/table-formatting/table-formatting-css.d.ts +0 -5
- package/dist/types/lib/types/common-types.d.ts +3 -2
- package/dist/types/lib/types/explorer-types.d.ts +2 -2
- package/dist/types/lib/types/index.d.ts +1 -1
- package/dist/types/lib/types/summary-types.d.ts +0 -5
- package/dist/types/lib/utils/card-definition.d.ts +7 -7
- package/dist/types/shared/analytics-protocol/agent-time-window.d.ts +84 -0
- package/dist/types/shared/analytics-protocol/analytics-base-schemas.d.ts +4 -4
- package/dist/types/shared/analytics-protocol/applied-constraints.d.ts +2 -2
- package/dist/types/shared/analytics-protocol/contracts.d.ts +8 -17
- package/dist/types/shared/analytics-protocol/execution-input-schemas.d.ts +10 -10
- package/dist/types/shared/analytics-protocol/fixtures.d.ts +3 -2
- package/dist/types/shared/analytics-protocol/index.d.ts +2 -4
- package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts +72 -72
- package/dist/types/shared/analytics-protocol/relative-date/describe.d.ts +18 -0
- package/dist/types/shared/analytics-protocol/relative-date/index.d.ts +7 -0
- package/dist/types/shared/analytics-protocol/relative-date/limits.d.ts +3 -0
- package/dist/types/shared/analytics-protocol/relative-date/presets.d.ts +11 -0
- package/dist/types/shared/analytics-protocol/relative-date/resolve.d.ts +49 -0
- package/dist/types/shared/analytics-protocol/relative-date/schemas.d.ts +76 -0
- package/dist/types/shared/analytics-protocol/relative-date/traits.d.ts +51 -0
- package/dist/types/shared/analytics-protocol/relative-date/window.d.ts +111 -0
- package/dist/types/shared/analytics-protocol/selection-contract.d.ts +1 -1
- package/dist/types/shared/assistant-protocol/context.d.ts +30 -30
- package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts +0 -2
- package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts +344 -1772
- package/dist/types/shared/dashboard-authoring/changes/diagnostics.d.ts +4 -1
- package/dist/types/shared/dashboard-authoring/changes/read-card-query.d.ts +8 -4
- package/dist/types/shared/dashboard-authoring/changes/resolve-dashboard-changes.d.ts +9 -0
- package/dist/types/shared/dashboard-authoring/conditional-formatting/schema.d.ts +104 -104
- package/dist/types/shared/dashboard-authoring/control-execution-contract.d.ts +20 -20
- package/dist/types/shared/dashboard-authoring/dashboard-style/bounds.d.ts +17 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/brand.d.ts +20 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/edit-words.d.ts +7 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/edit.d.ts +19 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/index.d.ts +15 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/layers.d.ts +19 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/legacy.d.ts +21 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/parse.d.ts +18 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/pickers.d.ts +12 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/types.d.ts +122 -0
- package/dist/types/shared/dashboard-authoring/dashboard-style/view.d.ts +10 -0
- package/dist/types/shared/dashboard-authoring/index.d.ts +1 -0
- package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts +11 -0
- package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts +23 -0
- package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts +10 -2
- package/dist/types/shared/format-utils/filter-detail.d.ts +2 -8
- package/dist/types/shared/format-utils/filter-line.d.ts +2 -2
- package/dist/types/shared/format-utils/matrix-continuation.d.ts +10 -10
- package/dist/types/shared/temporal/index.d.ts +0 -2
- package/dist/types/shared/temporal/temporal-parity-fixtures.d.ts +2 -2
- package/package.json +7 -26
- package/DATA_APP_SDK.md +0 -339
- package/dist/chunks/appearance-context-DEYtWinQ.js +0 -126
- package/dist/chunks/appearance-runtime-provider-B-M8gwlZ.js +0 -81
- package/dist/chunks/assistant-chat-BN5I8KuN.js +0 -8849
- package/dist/chunks/color-CJvdlFM_.js +0 -2162
- package/dist/chunks/dashboard-json-Cxp3inxd.js +0 -68
- package/dist/chunks/filter-value-text-7zhmth1S.js +0 -163
- package/dist/chunks/index-CLIro-EG.js +0 -425
- package/dist/chunks/index-CuHybtft.js +0 -51
- package/dist/chunks/matrix-analytical-definition-C9xB_T84.js +0 -717
- package/dist/chunks/matrix-card-BSUeSXpD.js +0 -42
- package/dist/chunks/matrix-member-presentation-DZNgQpUq.js +0 -105
- package/dist/chunks/operators-B3zZoskU.js +0 -66
- package/dist/chunks/pivot-result-contract-expectations-Ddh1rNz5.js +0 -56
- package/dist/chunks/raw-temporal-value-Bqz8wc7L.js +0 -242
- package/dist/chunks/selection-reducer-OaJ-N5uN.js +0 -46
- package/dist/chunks/source-entity-resolution-DF6GulDn.js +0 -607
- package/dist/chunks/validators-wtjw0aw6.js +0 -3332
- package/dist/data-app-sdk/index.js +0 -1412
- package/dist/data-app-sdk-adapters/index.js +0 -361
- package/dist/data-app-sdk-validation/index.js +0 -1031
- package/dist/types/components/sharing-and-management/utils/group-types.d.ts +0 -105
- package/dist/types/data-app-sdk/adapters.d.ts +0 -35
- package/dist/types/data-app-sdk/builders.d.ts +0 -62
- package/dist/types/data-app-sdk/contracts.d.ts +0 -419
- package/dist/types/data-app-sdk/executor.d.ts +0 -5
- package/dist/types/data-app-sdk/field-catalog-validation.d.ts +0 -29
- package/dist/types/data-app-sdk/hooks.d.ts +0 -11
- package/dist/types/data-app-sdk/index.d.ts +0 -9
- package/dist/types/data-app-sdk/provider.d.ts +0 -8
- package/dist/types/data-app-sdk/relationship-aware-field-policy.d.ts +0 -21
- package/dist/types/data-app-sdk/selection.d.ts +0 -2
- package/dist/types/data-app-sdk/validation.d.ts +0 -58
- package/dist/types/data-app-sdk-adapters.d.ts +0 -2
- package/dist/types/data-app-sdk-validation.d.ts +0 -2
- package/dist/types/data-app-sdk.d.ts +0 -2
- package/dist/types/shared/analytics-protocol/relative-date-filter.d.ts +0 -68
- package/dist/types/shared/analytics-protocol/relative-date-label.d.ts +0 -20
- package/dist/types/shared/analytics-protocol/time-window-schema.d.ts +0 -314
- package/dist/types/shared/analytics-protocol/time-window.d.ts +0 -52
- package/dist/types/shared/temporal/relative-date.d.ts +0 -21
- package/dist/types/shared/temporal/time-window-periods.d.ts +0 -21
- 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.
|