grist-widget-sdk 0.3.20 → 0.3.26

package/dist/app.d.cts

@@ -0,0 +1,147 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { UseGristOptions } from './index.cjs';
+import './types-D3JxUCfL.cjs';
+import './use-grist-reads-DpjVuI0H.cjs';
+import 'zod';
+
+/**
+ * Where a deployed build is being served from.
+ *
+ * A widget's deploy pipeline publishes the same build at its root and at
+ * `/latest/`, a preview at `/dev/`, and each release at `/v<version>/`, all
+ * under one base path (e.g. `/my-widget/` on GitHub Pages). Opened outside
+ * Grist, the page tells them apart from `window.location.pathname` alone.
+ */
+type DeployChannel = {
+    kind: "latest";
+} | {
+    kind: "dev";
+} | {
+    kind: "version";
+    version: string;
+};
+type DeployPath = {
+    channel: DeployChannel;
+    /**
+     * The path the channels live under, always ending in `/`: the current
+     * path without its channel segment. `"/my-widget/v1.2.0/"` gives
+     * `"/my-widget/"`.
+     */
+    basePath: string;
+};
+/**
+ * Parse a pathname into its deploy channel and base path. A path without a
+ * channel segment (the deployed root, or a local dev server) is `latest`:
+ * the deploy places the latest release at the root too.
+ */
+declare function parseDeployPath(pathname: string): DeployPath;
+/** `"latest"`, `"dev"` or `"v1.2.0"`. */
+declare function deployChannelLabel(channel: DeployChannel): string;
+
+type GristWidgetAppProps = {
+    /** The widget. A `React.lazy()` component works too: its code then loads only inside Grist. */
+    App: ComponentType;
+    /** The widget's `GRIST_OPTIONS`: access level, columns, and so on. */
+    options: UseGristOptions;
+    /**
+     * Whether this is the local dev server. Pass `import.meta.env.DEV`.
+     * Outside Grist it picks the local-dev page over the release page.
+     */
+    dev?: boolean;
+    /**
+     * Wraps the widget inside Grist, under {@link GristBoundary}. The default
+     * lists what needs the user's attention (column mapping, access level,
+     * failed writes) above the widget; `null` renders the widget alone.
+     */
+    Alerts?: ComponentType<{
+        children: ReactNode;
+    }> | null;
+    /** Shown outside Grist on the local dev server. Defaults to a page pointing at `pnpm test` and the `dev` loop. */
+    LocalDevPage?: ComponentType;
+    /**
+     * Shown outside Grist on a deployed URL (`/latest/`, `/dev/`, `/v<version>/`).
+     * Defaults to a page linking every channel and version, with the URL to
+     * paste into Grist.
+     */
+    ReleasePage?: ComponentType<{
+        channel: DeployChannel;
+    }>;
+};
+type MountGristWidgetConfig = GristWidgetAppProps & {
+    /** The element to render into, or its CSS selector. Defaults to `#root`. */
+    root?: Element | string;
+};
+type MountedGristWidget = {
+    unmount: () => void;
+};
+/**
+ * Render a widget into the page: everything `src/main.tsx` used to wire by
+ * hand.
+ *
+ * ```tsx
+ * import { mountGristWidget } from "grist-widget-sdk/app"
+ * import "./index.css"
+ * import App, { GRIST_OPTIONS } from "./App"
+ *
+ * mountGristWidget({ App, options: GRIST_OPTIONS, dev: import.meta.env.DEV })
+ * ```
+ *
+ * Inside Grist, the widget renders in {@link GristWidgetProvider} and
+ * {@link GristBoundary}, which gates on its mapped columns when it declares
+ * any, and follows Grist's light/dark theme. Outside Grist, where there is
+ * nothing to connect to, the page shows `LocalDevPage` on the dev server and
+ * `ReleasePage` on a deployed URL.
+ */
+declare function mountGristWidget(config: MountGristWidgetConfig): MountedGristWidget;
+/**
+ * The tree {@link mountGristWidget} renders, as a component: for a test, or
+ * for a page that manages its own React root.
+ */
+declare function GristWidgetApp({ App, options, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
+
+type WidgetTheme = "light" | "dark" | "system";
+type ResolvedWidgetTheme = "light" | "dark";
+type UseThemeResult = {
+    /**
+     * Inside Grist: Grist's theme, or `"system"` until Grist has sent it.
+     * Outside Grist: the saved choice, `"system"` by default.
+     */
+    theme: WidgetTheme;
+    /** The theme applied to `<html class>`: `"system"` resolved to light or dark. */
+    resolvedTheme: ResolvedWidgetTheme;
+    /**
+     * Choose a theme outside Grist; it is saved in `localStorage`. Inside Grist
+     * this does nothing: the widget follows Grist's theme.
+     */
+    setTheme: (theme: WidgetTheme) => void;
+};
+/**
+ * The widget's current theme, for components that need it in JavaScript
+ * (a toaster, a chart). Same shape as shadcn's `useTheme()`. Styles should
+ * rely on the `dark` class that {@link mountGristWidget} keeps on `<html>`.
+ * Outside a mounted widget (a unit test, for instance) it reports the
+ * system theme and `setTheme` does nothing.
+ */
+declare function useTheme(): UseThemeResult;
+
+/** One entry of the `versions.json` a widget's deploy pipeline maintains. */
+type ReleasedVersion = {
+    version: string;
+    publishedAt: string;
+};
+type UseReleasedVersionsResult = {
+    /** Newest first, as the deploy writes them; `null` until loaded. */
+    versions: ReleasedVersion[] | null;
+    /** `true` when `versions.json` couldn't be fetched or read. */
+    error: boolean;
+};
+/**
+ * The widget's released versions, read from the `versions.json` next to its
+ * channels (see {@link parseDeployPath}). For a page shown outside Grist,
+ * such as a release page linking to each version.
+ */
+declare function useReleasedVersions(pathname?: string): UseReleasedVersionsResult;
+
+export { GristWidgetApp, deployChannelLabel, mountGristWidget, parseDeployPath, useReleasedVersions, useTheme };
+export type { DeployChannel, DeployPath, GristWidgetAppProps, MountGristWidgetConfig, MountedGristWidget, ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };

package/dist/app.d.ts

@@ -0,0 +1,147 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { UseGristOptions } from './index.js';
+import './types-D3JxUCfL.js';
+import './use-grist-reads-DUMvJgV7.js';
+import 'zod';
+
+/**
+ * Where a deployed build is being served from.
+ *
+ * A widget's deploy pipeline publishes the same build at its root and at
+ * `/latest/`, a preview at `/dev/`, and each release at `/v<version>/`, all
+ * under one base path (e.g. `/my-widget/` on GitHub Pages). Opened outside
+ * Grist, the page tells them apart from `window.location.pathname` alone.
+ */
+type DeployChannel = {
+    kind: "latest";
+} | {
+    kind: "dev";
+} | {
+    kind: "version";
+    version: string;
+};
+type DeployPath = {
+    channel: DeployChannel;
+    /**
+     * The path the channels live under, always ending in `/`: the current
+     * path without its channel segment. `"/my-widget/v1.2.0/"` gives
+     * `"/my-widget/"`.
+     */
+    basePath: string;
+};
+/**
+ * Parse a pathname into its deploy channel and base path. A path without a
+ * channel segment (the deployed root, or a local dev server) is `latest`:
+ * the deploy places the latest release at the root too.
+ */
+declare function parseDeployPath(pathname: string): DeployPath;
+/** `"latest"`, `"dev"` or `"v1.2.0"`. */
+declare function deployChannelLabel(channel: DeployChannel): string;
+
+type GristWidgetAppProps = {
+    /** The widget. A `React.lazy()` component works too: its code then loads only inside Grist. */
+    App: ComponentType;
+    /** The widget's `GRIST_OPTIONS`: access level, columns, and so on. */
+    options: UseGristOptions;
+    /**
+     * Whether this is the local dev server. Pass `import.meta.env.DEV`.
+     * Outside Grist it picks the local-dev page over the release page.
+     */
+    dev?: boolean;
+    /**
+     * Wraps the widget inside Grist, under {@link GristBoundary}. The default
+     * lists what needs the user's attention (column mapping, access level,
+     * failed writes) above the widget; `null` renders the widget alone.
+     */
+    Alerts?: ComponentType<{
+        children: ReactNode;
+    }> | null;
+    /** Shown outside Grist on the local dev server. Defaults to a page pointing at `pnpm test` and the `dev` loop. */
+    LocalDevPage?: ComponentType;
+    /**
+     * Shown outside Grist on a deployed URL (`/latest/`, `/dev/`, `/v<version>/`).
+     * Defaults to a page linking every channel and version, with the URL to
+     * paste into Grist.
+     */
+    ReleasePage?: ComponentType<{
+        channel: DeployChannel;
+    }>;
+};
+type MountGristWidgetConfig = GristWidgetAppProps & {
+    /** The element to render into, or its CSS selector. Defaults to `#root`. */
+    root?: Element | string;
+};
+type MountedGristWidget = {
+    unmount: () => void;
+};
+/**
+ * Render a widget into the page: everything `src/main.tsx` used to wire by
+ * hand.
+ *
+ * ```tsx
+ * import { mountGristWidget } from "grist-widget-sdk/app"
+ * import "./index.css"
+ * import App, { GRIST_OPTIONS } from "./App"
+ *
+ * mountGristWidget({ App, options: GRIST_OPTIONS, dev: import.meta.env.DEV })
+ * ```
+ *
+ * Inside Grist, the widget renders in {@link GristWidgetProvider} and
+ * {@link GristBoundary}, which gates on its mapped columns when it declares
+ * any, and follows Grist's light/dark theme. Outside Grist, where there is
+ * nothing to connect to, the page shows `LocalDevPage` on the dev server and
+ * `ReleasePage` on a deployed URL.
+ */
+declare function mountGristWidget(config: MountGristWidgetConfig): MountedGristWidget;
+/**
+ * The tree {@link mountGristWidget} renders, as a component: for a test, or
+ * for a page that manages its own React root.
+ */
+declare function GristWidgetApp({ App, options, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
+
+type WidgetTheme = "light" | "dark" | "system";
+type ResolvedWidgetTheme = "light" | "dark";
+type UseThemeResult = {
+    /**
+     * Inside Grist: Grist's theme, or `"system"` until Grist has sent it.
+     * Outside Grist: the saved choice, `"system"` by default.
+     */
+    theme: WidgetTheme;
+    /** The theme applied to `<html class>`: `"system"` resolved to light or dark. */
+    resolvedTheme: ResolvedWidgetTheme;
+    /**
+     * Choose a theme outside Grist; it is saved in `localStorage`. Inside Grist
+     * this does nothing: the widget follows Grist's theme.
+     */
+    setTheme: (theme: WidgetTheme) => void;
+};
+/**
+ * The widget's current theme, for components that need it in JavaScript
+ * (a toaster, a chart). Same shape as shadcn's `useTheme()`. Styles should
+ * rely on the `dark` class that {@link mountGristWidget} keeps on `<html>`.
+ * Outside a mounted widget (a unit test, for instance) it reports the
+ * system theme and `setTheme` does nothing.
+ */
+declare function useTheme(): UseThemeResult;
+
+/** One entry of the `versions.json` a widget's deploy pipeline maintains. */
+type ReleasedVersion = {
+    version: string;
+    publishedAt: string;
+};
+type UseReleasedVersionsResult = {
+    /** Newest first, as the deploy writes them; `null` until loaded. */
+    versions: ReleasedVersion[] | null;
+    /** `true` when `versions.json` couldn't be fetched or read. */
+    error: boolean;
+};
+/**
+ * The widget's released versions, read from the `versions.json` next to its
+ * channels (see {@link parseDeployPath}). For a page shown outside Grist,
+ * such as a release page linking to each version.
+ */
+declare function useReleasedVersions(pathname?: string): UseReleasedVersionsResult;
+
+export { GristWidgetApp, deployChannelLabel, mountGristWidget, parseDeployPath, useReleasedVersions, useTheme };
+export type { DeployChannel, DeployPath, GristWidgetAppProps, MountGristWidgetConfig, MountedGristWidget, ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };