grist-widget-sdk 0.2.0 → 0.2.2-rc.0
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/CHANGELOG.md +16 -723
- package/LICENSE +18 -12
- package/dist/index.cjs +5 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +67 -1
- package/dist/index.d.ts +67 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/package.json +16 -13
package/dist/index.d.cts
CHANGED
|
@@ -822,4 +822,70 @@ type UseWidgetMetadataInput = {
|
|
|
822
822
|
};
|
|
823
823
|
declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
|
|
824
824
|
|
|
825
|
-
|
|
825
|
+
/**
|
|
826
|
+
* Standard React library for building Grist custom widgets.
|
|
827
|
+
*
|
|
828
|
+
* ---------------------------------------------------------------------------
|
|
829
|
+
* Agent "north star" (use this pattern unless you have a specific reason not to)
|
|
830
|
+
* ---------------------------------------------------------------------------
|
|
831
|
+
*
|
|
832
|
+
* ```tsx
|
|
833
|
+
* import {
|
|
834
|
+
* GristWidgetProvider,
|
|
835
|
+
* GristBoundary,
|
|
836
|
+
* useGrist,
|
|
837
|
+
* } from "grist-widget-sdk"
|
|
838
|
+
*
|
|
839
|
+
* export default function Page() {
|
|
840
|
+
* return (
|
|
841
|
+
* <GristWidgetProvider options={{ requiredAccess: "full", columns: [...] }}>
|
|
842
|
+
* <GristBoundary>
|
|
843
|
+
* <MyWidget />
|
|
844
|
+
* </GristBoundary>
|
|
845
|
+
* </GristWidgetProvider>
|
|
846
|
+
* )
|
|
847
|
+
* }
|
|
848
|
+
*
|
|
849
|
+
* function MyWidget() {
|
|
850
|
+
* const w = useGrist()
|
|
851
|
+
* if (w.mode === "empty") return <p>Select a row.</p>
|
|
852
|
+
* if (w.mode === "new-row") return <NewRowForm w={w} />
|
|
853
|
+
* return (
|
|
854
|
+
* <button onClick={() => w.table.update({ id: w.record!.id as number, fields: { Done: true } })}>
|
|
855
|
+
* Mark done
|
|
856
|
+
* </button>
|
|
857
|
+
* )
|
|
858
|
+
* }
|
|
859
|
+
* ```
|
|
860
|
+
*
|
|
861
|
+
* Rules for robust widget code:
|
|
862
|
+
*
|
|
863
|
+
* 1. Consume Grist only through `useGrist()` / `useGristSchema()`. Never import
|
|
864
|
+
* the `grist` or `docApi` globals in widget code — this is enforced by ESLint
|
|
865
|
+
* in `app/widgets/**`.
|
|
866
|
+
* 2. Writes:
|
|
867
|
+
* - **Records (default):** `w.table.*` (selected table) or `w.getTable(id).*`.
|
|
868
|
+
* These are `TableOperations` — they support single and bulk calls natively.
|
|
869
|
+
* - **Schema:** `w.applyActions([...])` with the exported action builders
|
|
870
|
+
* (`gristAddColumnAction`, `gristRenameColumnAction`, …).
|
|
871
|
+
* 3. Reads of the current section use `w.fetchSelectedTable()` /
|
|
872
|
+
* `w.fetchSelectedRecord()` — defaults are pinned to decoded `rows` format.
|
|
873
|
+
* 4. Column mapping: declare `columns` on the provider, then use
|
|
874
|
+
* `w.mappedRecord` / `w.resolveMappedColumnId()` / `w.mapBack()` on writes,
|
|
875
|
+
* and `w.columnMappingStatus` to gate UI when required columns are not mapped.
|
|
876
|
+
* Use {@link getGristSdkAlertDescriptors} / {@link formatColumnMappingAlertMessage}
|
|
877
|
+
* in your host UI (e.g. shadcn Alert) for shared copy — the SDK does not ship
|
|
878
|
+
* styled alert components.
|
|
879
|
+
* `mappedRecord` is `null` when `grist.mapColumnNames` cannot build a logical
|
|
880
|
+
* row (e.g. missing required mappings), not a disguised raw `record`.
|
|
881
|
+
* 5. Need schema/sample context for an LLM? Use `useGristSchema()` — it returns
|
|
882
|
+
* a replica document (`GristReplicaDocument`, exposed as `document` and `replicaDocument`) ready to feed a model.
|
|
883
|
+
* For a **full-document** replica (all tables, same options as the standalone {@link buildReplicaDocumentFromDocApi}),
|
|
884
|
+
* use **`w.buildReplicaDocumentFromDocApi({ … })`** from **`useGrist()`** / **`useGristContext()`** (no `docApi` argument).
|
|
885
|
+
*
|
|
886
|
+
* Load `https://docs.getgrist.com/grist-plugin-api.js` in your app shell before the widget bundle.
|
|
887
|
+
*/
|
|
888
|
+
|
|
889
|
+
declare const __RC_PUBLISH_TEST_MARKER_2__ = "rc-publish-verify-2-2026-07-12";
|
|
890
|
+
|
|
891
|
+
export { type BuildReplicaDocumentFromDocApiOptions, FetchGristTableRowsOptions, GRIST_BOUNDARY_PREPARING_COPY, type GetGristSdkAlertDescriptorsOptions, GristAccessToken, GristApplyUserActionsOptions, type GristAttachmentUploadResult, GristBoundary, type GristBoundaryActions, type GristBoundaryBlockingKind, type GristBoundaryBootPhase, type GristBoundaryGate, type GristBoundaryProps, GristBoundaryScreen, type GristBoundaryView, GristCapabilities, type GristChoiceListEntry, GristColumnInfo, GristColumnarTable, GristColumnsToMap, GristCursorPos, type GristDecodedValue, GristDocApi, GristDocumentMode, type GristEncodedAttachmentList, type GristEncodedBareRef, type GristEncodedDate, type GristEncodedDateTime, type GristEncodedError, type GristEncodedList, type GristEncodedPending, type GristEncodedRef, GristFetchSelectedOptions, type GristFetchedAttachment, type GristFetchedAttachmentBlob, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristRowRecord, GristSafeParseCellResult, type GristSchemaTableView, type GristSdkAlertDescriptor, type GristSdkAlertKind, type GristSdkAlertSeverity, type GristSdkAlertsWidgetSlice, GristTableOperations, type GristTheme, GristUserActionTuple, type GristWidgetActionStatus, GristWidgetColumnMap, GristWidgetInteraction, type GristWidgetMode, GristWidgetProvider, type GristWidgetProviderProps, GristWidgetStatus, ListColumnsOptions, ListTablesOptions, type ReplicaDocumentJsonOptions, type ReplicaJsonIncludeRows, type ReplicaTableColumnMetaLite, SafeParseGristTableDataOptions, type UseGristOptions, type UseGristResult, type UseGristSchemaOptions, type UseGristSchemaResult, type UseWidgetMetadataInput, type ValidateColumnMappingsResult, __RC_PUBLISH_TEST_MARKER_2__, buildReplicaColumnsFromColumnar, buildReplicaDocumentFromDocApi, buildReplicaJsonPayload, coerceGristDocApiRefRowId, decodeGristValue, deriveBoundaryBootLabel, deriveBoundaryBootPhase, deriveBoundaryView, encodeGristValue, extractAttachmentIdsFromUploadPayload, extractFirstAttachmentIdFromUploadPayload, extractGristAttachmentId, extractGristAttachmentIdsFromCell, fetchAttachmentBase64, fetchAttachmentBase64ForCell, fetchAttachmentBlob, formatAccessInsufficientMessage, formatBoundaryUserMessage, formatColumnMappingAlertMessage, formatLinkStaleAlertMessage, formatMappingPendingAlertMessage, formatMappingUnreportedAlertMessage, formatSectionNotLinkedAlertMessage, formatSourceNotWiredAlertMessage, getAttachmentDownloadUrl, getAttachmentDownloadUrlForCell, getGristSdkAlertDescriptors, getGristSdkAlertSeverity, getGristSdkAlertTitle, gristAttachmentCellValue, gristAttachmentCellValues, inferGristFormulaKind, isAccessInsufficientError, isGristCellError, isWidgetSectionNotLinked, loadColumnMetadataByTable, mergeGristAttachmentCellValue, normalizeGristChoiceListEntries, normalizeReplicaDocumentInput, normalizeReplicaTableInput, orderedColumnIds, parseGristAttachmentUploadResponse, parseGristAttachmentUploadResponseIds, parseGristWidgetOptionsCell, resolveGristFormulaKind, serializeJsonFriendly, uploadGristAttachment, useGrist, useGristContext, useGristOptional, useGristSchema, useGristSdkAlertDescriptors, useGristSelection, useGristStatus, useGristTheme, useGristWrites, useWidgetMetadata, validateColumnMappings };
|
package/dist/index.d.ts
CHANGED
|
@@ -822,4 +822,70 @@ type UseWidgetMetadataInput = {
|
|
|
822
822
|
};
|
|
823
823
|
declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
|
|
824
824
|
|
|
825
|
-
|
|
825
|
+
/**
|
|
826
|
+
* Standard React library for building Grist custom widgets.
|
|
827
|
+
*
|
|
828
|
+
* ---------------------------------------------------------------------------
|
|
829
|
+
* Agent "north star" (use this pattern unless you have a specific reason not to)
|
|
830
|
+
* ---------------------------------------------------------------------------
|
|
831
|
+
*
|
|
832
|
+
* ```tsx
|
|
833
|
+
* import {
|
|
834
|
+
* GristWidgetProvider,
|
|
835
|
+
* GristBoundary,
|
|
836
|
+
* useGrist,
|
|
837
|
+
* } from "grist-widget-sdk"
|
|
838
|
+
*
|
|
839
|
+
* export default function Page() {
|
|
840
|
+
* return (
|
|
841
|
+
* <GristWidgetProvider options={{ requiredAccess: "full", columns: [...] }}>
|
|
842
|
+
* <GristBoundary>
|
|
843
|
+
* <MyWidget />
|
|
844
|
+
* </GristBoundary>
|
|
845
|
+
* </GristWidgetProvider>
|
|
846
|
+
* )
|
|
847
|
+
* }
|
|
848
|
+
*
|
|
849
|
+
* function MyWidget() {
|
|
850
|
+
* const w = useGrist()
|
|
851
|
+
* if (w.mode === "empty") return <p>Select a row.</p>
|
|
852
|
+
* if (w.mode === "new-row") return <NewRowForm w={w} />
|
|
853
|
+
* return (
|
|
854
|
+
* <button onClick={() => w.table.update({ id: w.record!.id as number, fields: { Done: true } })}>
|
|
855
|
+
* Mark done
|
|
856
|
+
* </button>
|
|
857
|
+
* )
|
|
858
|
+
* }
|
|
859
|
+
* ```
|
|
860
|
+
*
|
|
861
|
+
* Rules for robust widget code:
|
|
862
|
+
*
|
|
863
|
+
* 1. Consume Grist only through `useGrist()` / `useGristSchema()`. Never import
|
|
864
|
+
* the `grist` or `docApi` globals in widget code — this is enforced by ESLint
|
|
865
|
+
* in `app/widgets/**`.
|
|
866
|
+
* 2. Writes:
|
|
867
|
+
* - **Records (default):** `w.table.*` (selected table) or `w.getTable(id).*`.
|
|
868
|
+
* These are `TableOperations` — they support single and bulk calls natively.
|
|
869
|
+
* - **Schema:** `w.applyActions([...])` with the exported action builders
|
|
870
|
+
* (`gristAddColumnAction`, `gristRenameColumnAction`, …).
|
|
871
|
+
* 3. Reads of the current section use `w.fetchSelectedTable()` /
|
|
872
|
+
* `w.fetchSelectedRecord()` — defaults are pinned to decoded `rows` format.
|
|
873
|
+
* 4. Column mapping: declare `columns` on the provider, then use
|
|
874
|
+
* `w.mappedRecord` / `w.resolveMappedColumnId()` / `w.mapBack()` on writes,
|
|
875
|
+
* and `w.columnMappingStatus` to gate UI when required columns are not mapped.
|
|
876
|
+
* Use {@link getGristSdkAlertDescriptors} / {@link formatColumnMappingAlertMessage}
|
|
877
|
+
* in your host UI (e.g. shadcn Alert) for shared copy — the SDK does not ship
|
|
878
|
+
* styled alert components.
|
|
879
|
+
* `mappedRecord` is `null` when `grist.mapColumnNames` cannot build a logical
|
|
880
|
+
* row (e.g. missing required mappings), not a disguised raw `record`.
|
|
881
|
+
* 5. Need schema/sample context for an LLM? Use `useGristSchema()` — it returns
|
|
882
|
+
* a replica document (`GristReplicaDocument`, exposed as `document` and `replicaDocument`) ready to feed a model.
|
|
883
|
+
* For a **full-document** replica (all tables, same options as the standalone {@link buildReplicaDocumentFromDocApi}),
|
|
884
|
+
* use **`w.buildReplicaDocumentFromDocApi({ … })`** from **`useGrist()`** / **`useGristContext()`** (no `docApi` argument).
|
|
885
|
+
*
|
|
886
|
+
* Load `https://docs.getgrist.com/grist-plugin-api.js` in your app shell before the widget bundle.
|
|
887
|
+
*/
|
|
888
|
+
|
|
889
|
+
declare const __RC_PUBLISH_TEST_MARKER_2__ = "rc-publish-verify-2-2026-07-12";
|
|
890
|
+
|
|
891
|
+
export { type BuildReplicaDocumentFromDocApiOptions, FetchGristTableRowsOptions, GRIST_BOUNDARY_PREPARING_COPY, type GetGristSdkAlertDescriptorsOptions, GristAccessToken, GristApplyUserActionsOptions, type GristAttachmentUploadResult, GristBoundary, type GristBoundaryActions, type GristBoundaryBlockingKind, type GristBoundaryBootPhase, type GristBoundaryGate, type GristBoundaryProps, GristBoundaryScreen, type GristBoundaryView, GristCapabilities, type GristChoiceListEntry, GristColumnInfo, GristColumnarTable, GristColumnsToMap, GristCursorPos, type GristDecodedValue, GristDocApi, GristDocumentMode, type GristEncodedAttachmentList, type GristEncodedBareRef, type GristEncodedDate, type GristEncodedDateTime, type GristEncodedError, type GristEncodedList, type GristEncodedPending, type GristEncodedRef, GristFetchSelectedOptions, type GristFetchedAttachment, type GristFetchedAttachmentBlob, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristRowRecord, GristSafeParseCellResult, type GristSchemaTableView, type GristSdkAlertDescriptor, type GristSdkAlertKind, type GristSdkAlertSeverity, type GristSdkAlertsWidgetSlice, GristTableOperations, type GristTheme, GristUserActionTuple, type GristWidgetActionStatus, GristWidgetColumnMap, GristWidgetInteraction, type GristWidgetMode, GristWidgetProvider, type GristWidgetProviderProps, GristWidgetStatus, ListColumnsOptions, ListTablesOptions, type ReplicaDocumentJsonOptions, type ReplicaJsonIncludeRows, type ReplicaTableColumnMetaLite, SafeParseGristTableDataOptions, type UseGristOptions, type UseGristResult, type UseGristSchemaOptions, type UseGristSchemaResult, type UseWidgetMetadataInput, type ValidateColumnMappingsResult, __RC_PUBLISH_TEST_MARKER_2__, buildReplicaColumnsFromColumnar, buildReplicaDocumentFromDocApi, buildReplicaJsonPayload, coerceGristDocApiRefRowId, decodeGristValue, deriveBoundaryBootLabel, deriveBoundaryBootPhase, deriveBoundaryView, encodeGristValue, extractAttachmentIdsFromUploadPayload, extractFirstAttachmentIdFromUploadPayload, extractGristAttachmentId, extractGristAttachmentIdsFromCell, fetchAttachmentBase64, fetchAttachmentBase64ForCell, fetchAttachmentBlob, formatAccessInsufficientMessage, formatBoundaryUserMessage, formatColumnMappingAlertMessage, formatLinkStaleAlertMessage, formatMappingPendingAlertMessage, formatMappingUnreportedAlertMessage, formatSectionNotLinkedAlertMessage, formatSourceNotWiredAlertMessage, getAttachmentDownloadUrl, getAttachmentDownloadUrlForCell, getGristSdkAlertDescriptors, getGristSdkAlertSeverity, getGristSdkAlertTitle, gristAttachmentCellValue, gristAttachmentCellValues, inferGristFormulaKind, isAccessInsufficientError, isGristCellError, isWidgetSectionNotLinked, loadColumnMetadataByTable, mergeGristAttachmentCellValue, normalizeGristChoiceListEntries, normalizeReplicaDocumentInput, normalizeReplicaTableInput, orderedColumnIds, parseGristAttachmentUploadResponse, parseGristAttachmentUploadResponseIds, parseGristWidgetOptionsCell, resolveGristFormulaKind, serializeJsonFriendly, uploadGristAttachment, useGrist, useGristContext, useGristOptional, useGristSchema, useGristSdkAlertDescriptors, useGristSelection, useGristStatus, useGristTheme, useGristWrites, useWidgetMetadata, validateColumnMappings };
|
package/dist/index.js
CHANGED
|
@@ -2343,11 +2343,15 @@ function setMetaTag(key, value, content) {
|
|
|
2343
2343
|
}
|
|
2344
2344
|
meta.setAttribute("content", content);
|
|
2345
2345
|
}
|
|
2346
|
+
|
|
2347
|
+
// src/sdk/index.ts
|
|
2348
|
+
var __RC_PUBLISH_TEST_MARKER_2__ = "rc-publish-verify-2-2026-07-12";
|
|
2346
2349
|
export {
|
|
2347
2350
|
GRIST_BOUNDARY_PREPARING_COPY,
|
|
2348
2351
|
GristBoundary,
|
|
2349
2352
|
GristBoundaryScreen,
|
|
2350
2353
|
GristWidgetProvider,
|
|
2354
|
+
__RC_PUBLISH_TEST_MARKER_2__,
|
|
2351
2355
|
buildReplicaColumnsFromColumnar,
|
|
2352
2356
|
buildReplicaDocumentFromDocApi,
|
|
2353
2357
|
buildReplicaJsonPayload,
|