akanjs 3.0.0-alpha.97 → 3.0.0-alpha.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.97",
+  "version": "3.0.0-alpha.98",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/store/action.ts

@@ -584,6 +584,12 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     
     const current = (this.get() as { [key: string]: any })[names.modelDraft] as DraftState | null;
     if (current?.key !== draft.key) return;
+
+    const openedForm = (this.get() as { [key: string]: any })[names.modelForm] as object;
+    if (DraftStore.contentHash(record.form) === DraftStore.contentHash(DraftStore.encodeForm(refName, openedForm))) {
+      await DraftStore.remove(draft.key);
+      return;
+    }
     let form: object;
     try {
       form = DraftStore.decodeForm(refName, record.form);
@@ -1222,6 +1228,13 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
        * asking for what comes after them cannot drift from what is displayed. It also leaves `pageOf<Model>` at
        * 1, which is what keeps live placement — refused anywhere but the first page — working past the first
        * "more".
+       *
+       * It reads `<model>ListLoading` and never sets it: an append leaves the rows on screen, so raising it
+       * would put the whole-list spinner over one and would make `applyLive<Model>` drop every live event until
+       * the batch lands. So concurrent calls are NOT rejected — two of them fetch the same offset, since the
+       * list they measure has not grown yet. That is a wasted round trip and never a wrong list: the ticket
+       * makes only the newest response apply, and both asked for the same rows. A caller that minds the wasted
+       * request holds its own in-flight flag, the way `InfiniteScroll` does.
        */
       [namesOfSlice.loadMoreOfModel]: async function (this: SetGet, options?: FetchPolicy) {
         const currentState = this.get() as { [key: string]: any };

package/store/draftStore.ts

@@ -17,6 +17,9 @@ const MAX_DRAFTS_PER_IDENTITY = 30;
  */
 const VOLATILE_CLAIMS = ["iat", "exp", "nbf", "jti"] as const;
 
+/** The fields a form carries from its row rather than from what the user typed. */
+const RECORD_STAMPS = new Set(["createdAt", "updatedAt", "removedAt"]);
+
 export interface DraftRecord {
   v: number;
   /** ISO. Drives both the "n minutes ago" label and the TTL/LRU sweep. */
@@ -143,6 +146,17 @@ export class DraftStore {
     return DraftStore.#hash8(DraftStore.#stableStringify(DraftStore.encodeForm(refName, form)));
   }
 
+  /**
+   * What two encoded forms holding the same values hash to, whatever record stamps they carry.
+   *
+   * The stamps come from the row rather than from the user, so a save the form made itself moves `updatedAt` and
+   * would otherwise make a draft look different from the record that already holds it.
+   */
+  static contentHash(encoded: Record<string, unknown>): string {
+    const content = Object.fromEntries(Object.entries(encoded).filter(([key]) => !RECORD_STAMPS.has(key)));
+    return DraftStore.#hash8(DraftStore.#stableStringify(content));
+  }
+
   static async read(key: string): Promise<DraftRecord | null> {
     const storage = DraftStore.#storage();
     if (!storage) return null;

package/types/store/draftStore.d.ts

@@ -36,6 +36,13 @@ export declare class DraftStore {
     static decodeForm(refName: string, plain: Record<string, unknown>): object;
     /** What the dirty check compares. Cheap enough to take once per debounce window, not once per keystroke. */
     static formHash(refName: string, form: object): string;
+    /**
+     * What two encoded forms holding the same values hash to, whatever record stamps they carry.
+     *
+     * The stamps come from the row rather than from the user, so a save the form made itself moves `updatedAt` and
+     * would otherwise make a draft look different from the record that already holds it.
+     */
+    static contentHash(encoded: Record<string, unknown>): string;
     static read(key: string): Promise<DraftRecord | null>;
     static write(key: string, record: DraftRecord): Promise<void>;
     static remove(key: string): Promise<void>;

package/types/ui/InfiniteScroll.d.ts

@@ -2,6 +2,11 @@ export interface InfiniteScrollProps {
     hasMore: boolean;
     onLoadMore: () => Promise<void>;
     children: React.ReactNode;
+    /**
+     * Load earlier rows above the ones in hand, preserving the reading position across the prepend. Assumes
+     * normal column flow. It does not scroll anywhere at mount, so a list meant to open at its newest row scrolls
+     * itself — and until it does, the sentinel is on screen and loads one window unasked.
+     */
     reverse?: boolean;
 }
 export declare const InfiniteScroll: ({ hasMore, onLoadMore, children, reverse }: InfiniteScrollProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Model/DraftBar.d.ts

@@ -1,14 +1,24 @@
 import type { SliceMeta } from "akanjs/fetch";
+export interface DraftBarViewProps {
+    className?: string;
+    /** The model the recovered form belongs to. */
+    refName: string;
+    /**
+     * `conflict` is a decision the user has to settle — the record moved since the draft was taken, so the form
+     * shows the server's value and the bar offers the older one. `applied` is a notice: the draft is what is on
+     * screen, and the bar is the way back.
+     */
+    state: "conflict" | "applied";
+    /** When the draft was taken. */
+    savedAt: Date;
+    /** Puts the offered draft into the form. Passed in the `conflict` state only. */
+    onRestore?: () => void;
+    /** Drops the draft and keeps the form as it was opened. */
+    onDiscard: () => void;
+}
 interface DraftBarProps {
     className?: string;
     slice: SliceMeta;
 }
-/**
- * What the user is told about a recovered form.
- *
- * Two states, and the difference is whether the draft is already in the form. A pending one is a conflict the
- * user has to settle — the record moved since the draft was taken, so the form shows the server's value and this
- * offers the older one. An applied one is just a notice: the draft is what is on screen, and this is the way back.
- */
 export default function DraftBar({ className, slice }: DraftBarProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/types/ui/Model/Edit.d.ts

@@ -1,5 +1,6 @@
 import type { SliceMeta } from "akanjs/fetch";
 import type { ReactNode } from "react";
+import type { DraftProp } from "./draftScope.d.ts";
 interface EditProps {
     type?: "icon" | "button";
     className?: string;
@@ -11,6 +12,8 @@ interface EditProps {
     renderTitle?: ((model: {
         id: string;
     }) => string | ReactNode) | string;
+    /** Draft recovery for the form this opens. `false` turns it off; a string names the scope explicitly. */
+    draft?: DraftProp;
 }
-export default function Edit({ className, wrapperClassName, type, children, slice, modelId, modal, renderTitle, }: EditProps): import("react/jsx-runtime").JSX.Element;
+export default function Edit({ className, wrapperClassName, type, children, slice, modelId, modal, renderTitle, draft, }: EditProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/types/ui/Model/EditModal.d.ts

@@ -9,6 +9,8 @@ interface EditModelProps<Full> {
     slice: SliceMeta;
     /** Additional classes for the wrapper. */
     className?: string;
+    /** Additional classes for the recovered-form banner this shell draws above the form. */
+    draftBarClassName?: string;
     /** Re-check submit eligibility when form state changes. */
     checkSubmit?: boolean;
     /** Client edit promise or partial form seed. */
@@ -54,5 +56,5 @@ interface EditModalProps<Full extends {
 }
 export default function EditModal<Full extends {
     id: string;
-}>({ type, slice, id, className, disabled, checkSubmit, modalClassName, edit, modal, renderTitle, children, submitText, submitClassName, submitOption, renderSubmit, loadingWrapper, draft, onSubmit, onCancel, }: EditModalProps<Full>): import("react/jsx-runtime").JSX.Element | undefined;
+}>({ type, slice, id, className, draftBarClassName, disabled, checkSubmit, modalClassName, edit, modal, renderTitle, children, submitText, submitClassName, submitOption, renderSubmit, loadingWrapper, draft, onSubmit, onCancel, }: EditModalProps<Full>): import("react/jsx-runtime").JSX.Element | undefined;
 export {};

package/types/ui/UiOverride/context.d.ts

@@ -22,6 +22,7 @@ import type { SkeletonProps } from "../Loading/Skeleton.d.ts";
 import type { SpinProps } from "../Loading/Spin.d.ts";
 import type { MenuProps } from "../Menu.d.ts";
 import type { ModalProps } from "../Modal.d.ts";
+import type { DraftBarViewProps } from "../Model/DraftBar.d.ts";
 import type { PaginationProps } from "../Pagination.d.ts";
 import type { PopconfirmProps } from "../Popconfirm.d.ts";
 import type { ItemProps as RadioItemProps, RadioProps } from "../Radio.d.ts";
@@ -54,6 +55,7 @@ export interface AkanUiOverrides {
     Menu: ComponentType<MenuProps>;
     Tooltip: ComponentType<TooltipProps>;
     Unauthorized: ComponentType<UnauthorizedProps>;
+    DraftBar: ComponentType<DraftBarViewProps>;
     AgentChat: ComponentType<AgentChatProps>;
     AgentLauncher: ComponentType<AgentLauncherProps>;
     AgentBubble: ComponentType<AgentBubbleProps>;

package/ui/InfiniteScroll.tsx

@@ -6,19 +6,70 @@ export interface InfiniteScrollProps {
   hasMore: boolean;
   onLoadMore: () => Promise<void>;
   children: React.ReactNode;
+  /**
+   * Load earlier rows above the ones in hand, preserving the reading position across the prepend. Assumes
+   * normal column flow. It does not scroll anywhere at mount, so a list meant to open at its newest row scrolls
+   * itself — and until it does, the sentinel is on screen and loads one window unasked.
+   */
   reverse?: boolean;
 }
 
+let warnedColumnReverse = false;
+
+/**
+ * The sentinel is positioned by DOM order alone — first child to load earlier, last child to load more — so a
+ * `column-reverse` parent paints it at the opposite end from the rows it controls, and `scrollTop: 0` is then
+ * that same end, so it also fires at mount. `flex-col-reverse` is the usual no-JS way to pin a chat to the
+ * bottom, so a caller reaching for `reverse` may well already have it; the result reads as a control placed
+ * wrongly rather than as an error, which is why it is worth saying out loud once.
+ */
+const warnColumnReverse = (sentinel: Element | null) => {
+  if (warnedColumnReverse || process.env.AKAN_PUBLIC_ENV !== "local") return;
+  const parent = sentinel?.parentElement;
+  if (!parent || getComputedStyle(parent).flexDirection !== "column-reverse") return;
+  warnedColumnReverse = true;
+  console.warn(
+    "<InfiniteScroll> sits in a `flex-col-reverse` parent, which paints its load sentinel at the end opposite the rows it loads, and fires it at mount. Drop `flex-col-reverse` and let `reverse` hold the reading position instead.",
+  );
+};
+
+const scrollableOverflows = new Set(["auto", "scroll", "overlay"]);
+
+/**
+ * The element that actually scrolls the sentinel — the document only once no ancestor has taken the job.
+ *
+ * A chat timeline or a log tail scrolls inside its own `overflow-y-auto` box, and there the document does not
+ * move at all, so anchoring `document.scrollingElement` restores a position nothing changed. Resolved per load
+ * rather than once, because the box that scrolls is a layout outcome and a caller cannot be asked to name it.
+ */
+const scrollerOf = (sentinel: Element | null) => {
+  if (typeof document === "undefined") return null;
+  let el = sentinel?.parentElement ?? null;
+  while (el && el !== document.body && el !== document.documentElement) {
+
+    if (el.scrollHeight > el.clientHeight && scrollableOverflows.has(getComputedStyle(el).overflowY)) return el;
+    el = el.parentElement;
+  }
+  return document.scrollingElement;
+};
+
 export const InfiniteScroll = ({ hasMore, onLoadMore, children, reverse }: InfiniteScrollProps) => {
   const [isFetching, setIsFetching] = useState(false);
   const isFetchingRef = useRef(false);
   const target = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
-    const observer = new IntersectionObserver((entries) => {
-      const [entry] = entries;
-      if (entry.isIntersecting) void fetchMoreItems();
-    });
+
+    warnColumnReverse(target.current);
+    const scroller = scrollerOf(target.current);
+    const root = scroller && scroller !== document.scrollingElement ? scroller : null;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const [entry] = entries;
+        if (entry.isIntersecting) void fetchMoreItems();
+      },
+      { root },
+    );
     if (target.current) observer.observe(target.current);
     return () => {
       observer.disconnect();
@@ -28,7 +79,7 @@ export const InfiniteScroll = ({ hasMore, onLoadMore, children, reverse }: Infin
   const fetchMoreItems = async () => {
     if (isFetchingRef.current) return;
 
-    const scroller = reverse ? document.scrollingElement : null;
+    const scroller = reverse ? scrollerOf(target.current) : null;
     const prevScrollHeight = scroller?.scrollHeight ?? 0;
     const prevScrollTop = scroller?.scrollTop ?? 0;
 

package/ui/Model/DraftBar.tsx

@@ -9,21 +9,75 @@ import { AiOutlineDelete, AiOutlineHistory, AiOutlineRollback } from "react-icon
 import { agentAttrs } from "../agentAttrs";
 import { Button } from "../Button";
 import { RecentTime } from "../RecentTime";
+import { createOverridable } from "../UiOverride";
 
-interface DraftBarProps {
+export interface DraftBarViewProps {
   className?: string;
-  slice: SliceMeta;
+  /** The model the recovered form belongs to. */
+  refName: string;
+  /**
+   * `conflict` is a decision the user has to settle — the record moved since the draft was taken, so the form
+   * shows the server's value and the bar offers the older one. `applied` is a notice: the draft is what is on
+   * screen, and the bar is the way back.
+   */
+  state: "conflict" | "applied";
+  /** When the draft was taken. */
+  savedAt: Date;
+  /** Puts the offered draft into the form. Passed in the `conflict` state only. */
+  onRestore?: () => void;
+  /** Drops the draft and keeps the form as it was opened. */
+  onDiscard: () => void;
 }
 
+const DefaultDraftBar = ({ className, state, savedAt, onRestore, onDiscard }: DraftBarViewProps) => {
+  const { l } = usePage();
+  if (state === "conflict")
+    return (
+      <div
+        className={cn(
+          "mb-4 flex flex-wrap items-center gap-2 rounded-box border border-warning/40 bg-warning/10 p-3",
+          className,
+        )}
+      >
+        <AiOutlineHistory className="text-warning" />
+        <span className="flex-1 text-foreground/80 text-sm">
+          {l("base.draftConflict")} <RecentTime date={savedAt} />
+        </span>
+        <Button {...agentAttrs(onRestore)} size="sm" onClick={() => onRestore?.()}>
+          <AiOutlineRollback /> {l("base.draftRestore")}
+        </Button>
+        <Button {...agentAttrs(onDiscard)} size="sm" variant="ghost" onClick={() => onDiscard()}>
+          <AiOutlineDelete /> {l("base.draftDiscard")}
+        </Button>
+      </div>
+    );
+  return (
+    <div className={cn("mb-4 flex flex-wrap items-center gap-2 text-foreground/60 text-xs", className)}>
+      <AiOutlineHistory />
+      <span className="flex-1">
+        {l("base.draftApplied")} <RecentTime date={savedAt} />
+      </span>
+      <Button {...agentAttrs(onDiscard)} size="xs" variant="ghost" onClick={() => onDiscard()}>
+        {l("base.draftStartOver")}
+      </Button>
+    </div>
+  );
+};
+
 /**
- * What the user is told about a recovered form.
+ * The banner itself, route-overridable through `page/**\/_overrides.tsx` (slot `DraftBar`).
  *
- * Two states, and the difference is whether the draft is already in the form. A pending one is a conflict the
- * user has to settle — the record moved since the draft was taken, so the form shows the server's value and this
- * offers the older one. An applied one is just a notice: the draft is what is on screen, and this is the way back.
+ * The shell below keeps the draft state and publishes the two agent tools, so a replacement re-skins the notice
+ * without reaching into the store under string keys or re-declaring what an agent may pull.
  */
+const DraftBarView = createOverridable("DraftBar", DefaultDraftBar);
+
+interface DraftBarProps {
+  className?: string;
+  slice: SliceMeta;
+}
+
 export default function DraftBar({ className, slice }: DraftBarProps) {
-  const { l } = usePage();
   const { refName } = slice;
   const [modelName, ModelName] = useMemo(() => [lowerlize(refName), capitalize(refName)], []);
   const names = useMemo(
@@ -50,35 +104,24 @@ export default function DraftBar({ className, slice }: DraftBarProps) {
 
   if (draft?.pending)
     return (
-      <div
-        className={cn(
-          "mb-4 flex flex-wrap items-center gap-2 rounded-box border border-warning/40 bg-warning/10 p-3",
-          className,
-        )}
-      >
-        <AiOutlineHistory className="text-warning" />
-        <span className="flex-1 text-foreground/80 text-sm">
-          {l("base.draftConflict")} <RecentTime date={draft.pending.savedAt} />
-        </span>
-        <Button {...agentAttrs(restoreDraft)} size="sm" onClick={() => restoreDraft()}>
-          <AiOutlineRollback /> {l("base.draftRestore")}
-        </Button>
-        <Button {...agentAttrs(discardDraft)} size="sm" variant="ghost" onClick={() => discardDraft()}>
-          <AiOutlineDelete /> {l("base.draftDiscard")}
-        </Button>
-      </div>
+      <DraftBarView
+        className={className}
+        refName={refName}
+        state="conflict"
+        savedAt={draft.pending.savedAt}
+        onRestore={restoreDraft}
+        onDiscard={discardDraft}
+      />
     );
   if (draft?.appliedAt)
     return (
-      <div className={cn("mb-4 flex flex-wrap items-center gap-2 text-foreground/60 text-xs", className)}>
-        <AiOutlineHistory />
-        <span className="flex-1">
-          {l("base.draftApplied")} <RecentTime date={draft.appliedAt} />
-        </span>
-        <Button {...agentAttrs(discardDraft)} size="xs" variant="ghost" onClick={() => discardDraft()}>
-          {l("base.draftStartOver")}
-        </Button>
-      </div>
+      <DraftBarView
+        className={className}
+        refName={refName}
+        state="applied"
+        savedAt={draft.appliedAt}
+        onDiscard={discardDraft}
+      />
     );
   return null;
 }

package/ui/Model/Edit.tsx

@@ -3,6 +3,7 @@ import type { SliceMeta } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { AiOutlineEdit } from "react-icons/ai";
 
+import type { DraftProp } from "./draftScope";
 import EditModal from "./EditModal";
 import EditWrapper from "./EditWrapper";
 
@@ -15,6 +16,8 @@ interface EditProps {
   modelId: string;
   modal?: string | null;
   renderTitle?: ((model: { id: string }) => string | ReactNode) | string;
+  /** Draft recovery for the form this opens. `false` turns it off; a string names the scope explicitly. */
+  draft?: DraftProp;
 }
 
 export default function Edit({
@@ -26,6 +29,7 @@ export default function Edit({
   modelId,
   modal,
   renderTitle,
+  draft,
 }: EditProps) {
   const { l } = usePage();
   return (
@@ -35,10 +39,11 @@ export default function Edit({
         slice={slice}
         modelId={modelId}
         modal={modal}
+        draft={draft}
       >
         <AiOutlineEdit /> {type === "button" ? l("base.edit") : null}
       </EditWrapper>
-      <EditModal renderTitle={renderTitle} slice={slice} id={modelId}>
+      <EditModal renderTitle={renderTitle} slice={slice} id={modelId} draft={draft}>
         {children}
       </EditModal>
     </div>

package/ui/Model/EditModal.tsx

@@ -27,6 +27,8 @@ interface EditModelProps<Full> {
   slice: SliceMeta;
   /** Additional classes for the wrapper. */
   className?: string;
+  /** Additional classes for the recovered-form banner this shell draws above the form. */
+  draftBarClassName?: string;
   /** Re-check submit eligibility when form state changes. */
   checkSubmit?: boolean;
   /** Client edit promise or partial form seed. */
@@ -52,6 +54,7 @@ const EditModel = <Full,>({
   type = "modal",
   slice,
   className,
+  draftBarClassName,
   checkSubmit = true,
   edit,
   modal,
@@ -107,7 +110,7 @@ const EditModel = <Full,>({
 
   return (
     <LoadingWrapper className={cn("w-full", className)}>
-      <DraftBar slice={slice} />
+      <DraftBar className={draftBarClassName} slice={slice} />
       {children}
     </LoadingWrapper>
   );
@@ -142,6 +145,7 @@ export default function EditModal<Full extends { id: string }>({
   slice,
   id,
   className,
+  draftBarClassName,
   disabled,
   checkSubmit = true,
   modalClassName,
@@ -368,6 +372,7 @@ export default function EditModal<Full extends { id: string }>({
             type={type}
             slice={slice}
             className={className}
+            draftBarClassName={draftBarClassName}
             checkSubmit={checkSubmit}
             edit={edit}
             modal={modal}
@@ -385,6 +390,7 @@ export default function EditModal<Full extends { id: string }>({
         type={type}
         slice={slice}
         className={className}
+        draftBarClassName={draftBarClassName}
         checkSubmit={checkSubmit}
         edit={edit}
         modal={modal}

package/ui/UiOverride/context.ts

@@ -24,6 +24,7 @@ import type { SkeletonProps } from "../Loading/Skeleton";
 import type { SpinProps } from "../Loading/Spin";
 import type { MenuProps } from "../Menu";
 import type { ModalProps } from "../Modal";
+import type { DraftBarViewProps } from "../Model/DraftBar";
 import type { PaginationProps } from "../Pagination";
 import type { PopconfirmProps } from "../Popconfirm";
 import type { ItemProps as RadioItemProps, RadioProps } from "../Radio";
@@ -58,6 +59,8 @@ export interface AkanUiOverrides {
   Menu: ComponentType<MenuProps>;
   Tooltip: ComponentType<TooltipProps>;
   Unauthorized: ComponentType<UnauthorizedProps>;
+
+  DraftBar: ComponentType<DraftBarViewProps>;
   AgentChat: ComponentType<AgentChatProps>;
 
   AgentLauncher: ComponentType<AgentLauncherProps>;