@marimo-team/frontend 0.25.3-dev102 → 0.25.3-dev104

package/src/core/document/hooks.tsx

@@ -0,0 +1,118 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { CellId } from "@marimo-team/client/protocol";
+import { useAtomValue, useSetAtom, useStore } from "jotai";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { cellCodeBinding } from "./codemirror";
+import type { EditableCell } from "./draft";
+import type { DocumentModel } from "./model";
+import { selectCellField, selectOrder } from "./select";
+
+const DocumentContext = createContext<DocumentModel | null>(null);
+
+/**
+ * Expose a session-owned model to React. Construct the model with the same store
+ * as the enclosing Jotai Provider. The session owner controls its AbortSignal;
+ * mounting or unmounting this provider does not change the model's lifetime.
+ *
+ * ```tsx
+ * <Provider store={store}>
+ *   <DocumentProvider model={model}>
+ *     <Editor />
+ *   </DocumentProvider>
+ * </Provider>
+ * ```
+ */
+export function DocumentProvider({
+  model,
+  children,
+}: {
+  model: DocumentModel;
+  children: ReactNode;
+}) {
+  return (
+    <DocumentContext.Provider value={model}>
+      {children}
+    </DocumentContext.Provider>
+  );
+}
+
+function useDocumentModel() {
+  const model = useContext(DocumentContext);
+  if (model === null) {
+    throw new Error("Document hooks require a DocumentProvider");
+  }
+  return model;
+}
+
+/** Null while the document is unavailable; an empty array for an empty document. */
+export function useCellOrder() {
+  const { documentAtom } = useDocumentModel();
+  return useAtomValue(useMemo(() => selectOrder(documentAtom), [documentAtom]));
+}
+
+function useCellField<K extends keyof EditableCell>(id: CellId, field: K) {
+  const { documentAtom } = useDocumentModel();
+  return useAtomValue(
+    useMemo(
+      () => selectCellField(documentAtom, id, field),
+      [documentAtom, id, field],
+    ),
+  );
+}
+
+/** Undefined for an absent cell; null when the host withholds its source. */
+export function useCellCode(id: CellId) {
+  return useCellField(id, "code");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellName(id: CellId) {
+  return useCellField(id, "name");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellConfig(id: CellId) {
+  return useCellField(id, "config");
+}
+
+/**
+ * A CodeMirror extension that binds the editor's text to a cell's code.
+ * Stable until the cell id or document model changes.
+ *
+ * ```tsx
+ * const extension = useCellCodeExtension(cellId);
+ * ```
+ */
+export function useCellCodeExtension(id: CellId) {
+  const model = useDocumentModel();
+  const store = useStore();
+  return useMemo(
+    () => cellCodeBinding({ store, model, cellId: id }),
+    [model, store, id],
+  );
+}
+
+/**
+ * A stable edit function. Synchronous callbacks publish atomically or roll back.
+ *
+ * ```ts
+ * const edit = useDocumentEdit();
+ * edit((tx) => tx.setCode(cellId, code));
+ * ```
+ */
+export function useDocumentEdit() {
+  return useSetAtom(useDocumentModel().editAtom);
+}
+
+/**
+ * Sync status and explicit recovery. flush waits for edits, including newer
+ * typing, to reach the confirmed source and returns the revision for Run/Save.
+ * Rejections retain local edits; retry explicitly resubmits them. Requests
+ * with an unknown outcome reuse their original key within the retry window.
+ */
+export function useDocumentSync() {
+  const model = useDocumentModel();
+  const status = useAtomValue(model.syncStatusAtom);
+  return { status, flush: model.flush, retry: model.retry };
+}

package/src/core/document/index.ts

@@ -1,5 +1,15 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+export {
+  DocumentProvider,
+  useCellCode,
+  useCellCodeExtension,
+  useCellConfig,
+  useCellName,
+  useCellOrder,
+  useDocumentEdit,
+  useDocumentSync,
+} from "./hooks";
 export { createDocumentModel } from "./model";
 export type {
   DocumentEdit,

package/src/core/document/select.ts

@@ -30,3 +30,12 @@ export function selectOrder(
 ): Atom<readonly Protocol.CellId[] | null> {
   return selectAtom(document, (value) => value?.order ?? null, dequal);
 }
+
+/** Select one field of a cell, unchanged until that field's value changes. */
+export function selectCellField<K extends keyof EditableCell>(
+  document: Atom<EditableDocument | null>,
+  id: Protocol.CellId,
+  field: K,
+): Atom<EditableCell[K] | undefined> {
+  return selectAtom(document, (value) => value?.cells.get(id)?.[field], dequal);
+}

package/dist/assets/feedback-button-CONwLFpw.js

@@ -1 +0,0 @@
-import{n as e}from"./feedback-button-C5NgWpFg.js";export{e as FeedbackModal};