grist-widget-sdk docs

Appearance

Conventions ​

Naming and file style ​

  • Use kebab-case for file names in SDK hooks and helpers (example: use-grist-schema.ts).
  • Use clear exported symbol names that start with useGrist for hooks and Grist for types/components.
  • Keep test files beside implementation when practical, named *.test.ts or *.test.tsx.

API boundaries ​

  • Only consume public exports from @grist-widget-sdk/core or @grist-widget-sdk/core/testing.
  • Never import from package internals such as @grist-widget-sdk/core/src/....
  • If a symbol should be public, export it from packages/core/src/hooks/index.ts.

Preferred widget integration pattern ​

  • Use GristWidgetProvider + GristBoundary + useGrist() for primary widget behavior.
  • Use useGristSchema() when schema/sample context is needed.
  • Use advanced hooks from @grist-widget-sdk/core/advanced only when the primary API surface is insufficient.

Error and fallback handling ​

  • Assume Grist context may be unavailable in local dev/tests.
  • Handle booting, empty, and new-row states explicitly in UI.
  • For write operations, prefer w.table.* helpers from useGrist() over custom action payloads.

Documentation and change hygiene ​

  • Update docs in apps/docs/files/ when changing exported API, command flows, or repo structure.
  • Keep examples aligned with current package names and workspace IDs.
  • Avoid stale path references (for example, use apps/widgets, not removed paths like apps/demos).