@artkit-ai/react 0.1.0 → 0.2.0

package/src/components/editor.tsx

@@ -1,76 +1,62 @@
-import type { Actor, Artifact, ArtifactError, CommitResult, EmitOptions, LintIssue } from '@artkit-ai/core';
-import { Redo2, RotateCcw, Undo2 } from 'lucide-react';
-import {
-  type FocusEvent,
-  type KeyboardEvent,
-  Suspense,
-  use,
-  useCallback,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-  useSyncExternalStore,
-} from 'react';
-import { useArtkit } from '../context.js';
-import { EditorSession, type EditorSessionState } from '../editor-session.js';
+import type { Artifact, EditorActions, EmitOptions } from '@artkit-ai/core';
+import { Redo2, Save, Undo2 } from 'lucide-react';
+import { type KeyboardEvent, Suspense, use, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { type ArtkitContextValue, useArtkit } from '../context.js';
+import { DraftSession, type DraftSnapshot } from '../editor-session.js';
 import { useArtifact } from '../hooks.js';
-import type { UiMessageKey } from '../i18n.js';
 import { hashString } from '../styles.js';
-import {
-  ChangeList,
-  cx,
-  ErrorBoundary,
-  ErrorMessage,
-  errorMessage,
-  formatDate,
-  Loading,
-  rootAttributes,
-  type Slots,
-  slot,
-  useAnnouncer,
-} from './shared.js';
-import { ArtifactView, KindRenderer, renderContext } from './view.js';
+import { cx, ErrorBoundary, ErrorMessage, Loading, rootAttributes, type Slots, slot } from './shared.js';
+import { ArtifactView, renderContext } from './view.js';
 
-export type EditorPermission = 'read' | 'edit';
-export type ArtifactEditorPart = 'toolbar' | 'status' | 'body' | 'conflict' | 'error' | 'notice';
+/**
+ * What the application receives when the user clicks Save. The library does not store anything: the application
+ * decides what saving means (a new version, a database row, a sync to another system, nothing at all).
+ */
+export interface SaveEvent {
+  artifactId: string;
+  format: string;
+  /** Version the draft started from. Pass it back as `baseVersion` when you apply `operations` yourself. */
+  baseVersion: number;
+  title: string;
+  locale: string;
+  themeId: string;
+  /** Full content of the draft. */
+  content: unknown;
+  /** Operations applied since `baseVersion`, in order. */
+  operations: unknown[];
+}
+
+export type ArtifactEditorPart = 'toolbar' | 'status' | 'body';
 
 export interface ArtifactEditorProps {
-  id?: string;
-  /** Latest known artifact (e.g. from a chat message); newer versions from the cache win. */
+  /** Artifact to edit. Its content is the starting point of the draft. */
   artifact?: Artifact;
-  /** Set by the application (spec §13.6). `comment` arrives in phase 3. Default `edit`. */
-  permission?: EditorPermission;
-  /** Another actor holds the lock: the editor turns read-only and shows `partial` as a streaming preview. */
-  lockedBy?: Actor | null;
-  /** Streamed content shown while locked (see `ArtifactView`). */
-  partial?: unknown;
-  /** Typing batches are grouped within this window (default 600 ms). */
-  groupingWindowMs?: number;
-  onCommitted?(result: CommitResult): void;
-  onError?(error: ArtifactError): void;
+  /** Load the artifact by id through the client when `artifact` is not given. */
+  id?: string;
+  /** Read-only edition: the format editor is hidden and the view is shown instead. */
+  readOnly?: boolean;
+  /** Save action. Called with the draft; the application persists it and passes the saved artifact back. */
+  onSave?(event: SaveEvent): void | Promise<void>;
+  /** Called after every change of the draft. */
+  onChange?(snapshot: DraftSnapshot): void;
   className?: string;
   slots?: Slots<ArtifactEditorPart>;
 }
 
 /**
- * Kind editor host (spec §13.1, §13.6). Falls back to `ArtifactView` when the kind has no editor loader,
- * when the permission is `read` or while another actor holds the lock. The editor module is only loaded
- * here, when editing starts.
+ * Editor of one artifact (spec §11.6). Edits are applied to a local draft; nothing reaches the server. The Save button
+ * emits the draft through `onSave`, and Ctrl/Cmd+S does the same. Undo and redo are local.
  */
 export function ArtifactEditor(props: ArtifactEditorProps) {
   const ctx = useArtkit();
-  const { t } = ctx;
-  const id = props.id ?? props.artifact?.id;
-  const query = useArtifact(id, props.artifact ? { initial: props.artifact } : {});
-  const artifact = query.artifact;
+  const fetched = useArtifact(props.artifact ? undefined : props.id);
+  const artifact = props.artifact ?? fetched.artifact;
 
   if (!artifact) {
     return (
       <div className={cx('ak-root ak-editor', props.className)} {...rootAttributes(ctx)}>
-        {query.error ? (
-          <ErrorMessage error={query.error} onRetry={() => void query.refresh().catch(() => undefined)} />
+        {fetched.error ? (
+          <ErrorMessage error={fetched.error} onRetry={() => void fetched.refresh().catch(() => undefined)} />
         ) : (
           <Loading />
         )}
@@ -78,239 +64,131 @@ export function ArtifactEditor(props: ArtifactEditorProps) {
     );
   }
 
-  const editable =
-    (props.permission ?? 'edit') === 'edit' &&
-    ctx.hasEditor(artifact.kind) &&
-    ctx.registry.has(artifact.kind);
-  if (!editable || props.lockedBy) {
+  const editable = !props.readOnly && ctx.hasEditor(artifact.format) && ctx.registry.has(artifact.format);
+  if (!editable) {
     return (
       <div
         className={cx('ak-root ak-editor', props.className)}
         {...rootAttributes(ctx, artifact.themeId)}
         data-readonly="true"
       >
-        {props.lockedBy ? (
-          <p {...slot(props.slots, 'notice', 'ak-notice')} role="status">
-            {t('lockedBy', { actor: t(`actor_${props.lockedBy.type}` as UiMessageKey) })}
-          </p>
-        ) : null}
-        <ArtifactView
-          artifact={artifact}
-          {...(props.lockedBy && props.partial !== undefined ? { partial: props.partial } : {})}
-        />
+        <ArtifactView artifact={artifact} />
       </div>
     );
   }
   return <EditingHost key={artifact.id} {...props} artifact={artifact} />;
 }
 
-function EditingHost(props: ArtifactEditorProps & { artifact: Artifact }) {
+function EditingHost({
+  artifact,
+  readOnly,
+  onSave,
+  onChange,
+  className,
+  slots,
+}: ArtifactEditorProps & { artifact: Artifact }) {
   const ctx = useArtkit();
-  const { t, client, cache, registry } = ctx;
-  const callbacks = useRef(props);
-  callbacks.current = props;
-  const artifactId = props.artifact.id;
-
   const [session] = useState(
-    () =>
-      new EditorSession({
-        registry,
-        artifact: props.artifact,
-        locale: ctx.locale,
-        ...(props.groupingWindowMs === undefined ? {} : { groupingWindowMs: props.groupingWindowMs }),
-        send: (request) => client.apply(artifactId, request),
-        load: (version) => cache.load(artifactId, version, version === undefined),
-        onCommitted: (result) => {
-          cache.put(result.artifact);
-          callbacks.current.onCommitted?.(result);
-        },
-      }),
+    () => new DraftSession({ registry: ctx.registry, artifact, locale: ctx.locale }),
   );
-  const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
-
-  // Newer versions from the cache or props (agent commits, refetches) are rebased into the session.
-  useEffect(() => {
-    session.receive(props.artifact);
-  }, [session, props.artifact]);
-
-  useEffect(() => {
-    cache.put(state.confirmed);
-  }, [cache, state.confirmed]);
+  const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState<unknown>();
 
-  // Unmounting must not lose the last keystrokes still waiting in the grouping window.
-  useEffect(() => () => session.flush(), [session]);
-
-  const [live, announce] = useAnnouncer();
-  const lastSeq = useRef(0);
+  // A newer artifact from the application (after a save, or a reload) moves the draft forward.
   useEffect(() => {
-    const event = state.event;
-    if (!event || event.seq === lastSeq.current) return;
-    lastSeq.current = event.seq;
-    switch (event.type) {
-      case 'saved':
-        announce(t('savedVersion', { version: event.version }));
-        break;
-      case 'undone':
-        announce(t('undone'));
-        break;
-      case 'redone':
-        announce(t('redone'));
-        break;
-      case 'rebased':
-        announce(t('agentUpdated', { version: event.version }));
-        break;
-      case 'rejected':
-      case 'rolled_back':
-        announce(t('rolledBack', { message: errorMessage(event.error, event.error.message) }));
-        callbacks.current.onError?.(event.error);
-        break;
-      case 'conflict':
-        announce(t('conflictTitle'));
-        break;
-      case 'conflict_resolved':
-        break;
+    if (
+      artifact.version !== session.getSnapshot().baseVersion ||
+      artifact.id !== session.getSnapshot().artifact.id
+    ) {
+      session.load(artifact);
     }
-  }, [state.event, announce, t]);
+  }, [artifact, session]);
 
-  const [, forceRender] = useState(0);
   useEffect(() => {
-    if (!state.lockedUntil) return;
-    const delay = Date.parse(state.lockedUntil) - Date.now();
-    if (delay <= 0) return;
-    const timer = setTimeout(() => forceRender((n) => n + 1), delay + 10);
-    return () => clearTimeout(timer);
-  }, [state.lockedUntil]);
-  const locked = state.lockedUntil !== undefined && Date.parse(state.lockedUntil) > Date.now();
-  const readOnly = state.status === 'conflict' || locked;
+    onChange?.(snapshot);
+  }, [snapshot, onChange]);
 
-  const onKeyDown = useCallback(
-    (event: KeyboardEvent<HTMLDivElement>) => {
-      if (event.defaultPrevented || !(event.ctrlKey || event.metaKey) || event.altKey) return;
-      const key = event.key.toLowerCase();
-      if (key === 'z' && !event.shiftKey) {
-        event.preventDefault();
-        session.undo();
-      } else if ((key === 'z' && event.shiftKey) || key === 'y') {
-        event.preventDefault();
-        session.redo();
-      }
-    },
-    [session],
-  );
+  const draft = snapshot.artifact;
+  const canSave = Boolean(onSave) && snapshot.dirty && !saving && !readOnly;
 
-  const onBlur = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      if (!event.currentTarget.contains(event.relatedTarget as Node | null)) session.flush();
-    },
-    [session],
-  );
-
-  const view = state.view;
-  const renderCtx = useMemo(
-    () => renderContext(ctx, view.themeId, view.locale, 'screen', false),
-    [ctx, view.themeId, view.locale],
-  );
-  const lint = useMemo<LintIssue[]>(() => {
+  async function save() {
+    if (!canSave || !onSave) return;
+    setSaving(true);
+    setSaveError(undefined);
     try {
-      return registry
-        .get(props.artifact.kind)
-        .lint(view.content, { locale: view.locale, theme: ctx.themeFor(view.themeId) });
-    } catch {
-      return [];
+      await onSave({
+        artifactId: draft.id,
+        format: draft.format,
+        baseVersion: snapshot.baseVersion,
+        title: draft.title,
+        locale: draft.locale,
+        themeId: draft.themeId,
+        content: draft.content,
+        operations: snapshot.operations,
+      });
+    } catch (error) {
+      setSaveError(error);
+    } finally {
+      setSaving(false);
     }
-  }, [ctx, registry, props.artifact.kind, view]);
-  const emit = useCallback(
-    (operations: unknown[], options?: EmitOptions) => {
-      session.emit(operations, options);
-    },
-    [session],
-  );
+  }
 
-  const statusText =
-    state.status === 'saving'
-      ? t('saving')
-      : state.status === 'editing'
-        ? t('unsaved')
-        : state.status === 'conflict'
-          ? t('conflictTitle')
-          : t('saved');
+  function onKeyDown(event: KeyboardEvent<HTMLElement>) {
+    if (event.defaultPrevented || !(event.metaKey || event.ctrlKey)) return;
+    const key = event.key.toLowerCase();
+    if (key === 's') {
+      event.preventDefault();
+      void save();
+    } else if (key === 'z' && !event.shiftKey) {
+      event.preventDefault();
+      session.undo();
+    } else if (key === 'y' || (key === 'z' && event.shiftKey)) {
+      event.preventDefault();
+      session.redo();
+    }
+  }
+
+  const emit = (operations: unknown[], options?: EmitOptions) => {
+    void session.apply(operations, { ...(options?.kind ? { kind: options.kind } : {}) });
+  };
+
+  const actions: EditorActions = {
+    canUndo: snapshot.canUndo,
+    canRedo: snapshot.canRedo,
+    undo: () => session.undo(),
+    redo: () => session.redo(),
+    dirty: snapshot.dirty,
+    saving,
+    canSave,
+    save: () => void save(),
+  };
 
   return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: the shortcuts (Ctrl/Cmd+S, Z, Y) cover the whole editor.
     <section
-      className={cx('ak-root ak-editor', props.className)}
-      {...rootAttributes(ctx, view.themeId)}
-      aria-label={t('editorLabel', { title: view.title })}
-      lang={view.locale}
+      className={cx('ak-root ak-editor', className)}
+      {...rootAttributes(ctx, draft.themeId)}
+      data-dirty={snapshot.dirty || undefined}
       onKeyDown={onKeyDown}
-      onBlur={onBlur}
-      data-status={state.status}
     >
-      {live}
-      <div
-        {...slot(props.slots, 'toolbar', 'ak-editor-toolbar')}
-        role="toolbar"
-        aria-label={t('editorLabel', { title: view.title })}
-      >
-        <button
-          type="button"
-          className="ak-button"
-          onClick={session.undo}
-          disabled={!state.canUndo}
-          aria-keyshortcuts="Control+Z Meta+Z"
-        >
-          <Undo2 aria-hidden="true" />
-          {t('undo')}
-        </button>
-        <button
-          type="button"
-          className="ak-button"
-          onClick={session.redo}
-          disabled={!state.canRedo}
-          aria-keyshortcuts="Control+Shift+Z Meta+Shift+Z Control+Y"
-        >
-          <Redo2 aria-hidden="true" />
-          {t('redo')}
-        </button>
-        {lint.length > 0 ? (
-          <span className="ak-badge">{t('lintWarnings', { count: lint.length })}</span>
-        ) : null}
-        <span {...slot(props.slots, 'status', 'ak-editor-status')} aria-hidden="true">
-          {statusText}
-        </span>
-      </div>
-      {locked && state.lockedUntil ? (
-        <p {...slot(props.slots, 'notice', 'ak-notice')} role="status">
-          {t('lockedUntil', { time: formatDate(state.lockedUntil, ctx.locale) })}
-        </p>
-      ) : null}
-      {state.error && state.status !== 'conflict' ? (
-        <ErrorMessage
-          error={state.error}
-          onDismiss={session.dismissError}
-          {...slot(props.slots, 'error', '')}
-        />
-      ) : null}
-      {state.conflict ? <ConflictBox state={state} session={session} slots={props.slots} /> : null}
-      <div {...slot(props.slots, 'body', 'ak-view-body')}>
-        <ErrorBoundary
-          onReset={() => ctx.resetLoad('editor', props.artifact.kind)}
-          fallback={(error, reset) => (
-            <>
-              <ErrorMessage error={error} onRetry={reset} />
-              <KindRenderer kind={props.artifact.kind} content={view.content} ctx={renderCtx} />
-            </>
-          )}
-        >
-          <Suspense
-            fallback={<KindRenderer kind={props.artifact.kind} content={view.content} ctx={renderCtx} />}
-          >
+      {snapshot.error ? <ErrorMessage error={snapshot.error} onDismiss={() => session.undo()} /> : null}
+      {saveError ? <ErrorMessage error={saveError} /> : null}
+
+      <div {...slot(slots, 'body', 'ak-editor-body')}>
+        <ErrorBoundary fallback={(error) => <ErrorMessage error={error} />}>
+          <Suspense fallback={<Loading />}>
             <LoadedEditor
-              kind={props.artifact.kind}
-              content={view.content}
-              ctx={renderCtx}
+              slots={slots}
+              actions={actions}
+              format={draft.format}
+              content={draft.content}
+              ctx={ctx}
+              themeId={draft.themeId}
+              locale={draft.locale}
               emit={emit}
-              readOnly={readOnly}
-              lint={lint}
+              readOnly={Boolean(readOnly)}
+              lint={snapshot.lint}
             />
           </Suspense>
         </ErrorBoundary>
@@ -319,74 +197,96 @@ function EditingHost(props: ArtifactEditorProps & { artifact: Artifact }) {
   );
 }
 
-function ConflictBox({
-  state,
-  session,
-  slots,
-}: {
-  state: EditorSessionState;
-  session: EditorSession;
-  slots?: Slots<ArtifactEditorPart> | undefined;
-}) {
-  const { t } = useArtkit();
-  const conflict = state.conflict!;
-  const first = useRef<HTMLButtonElement>(null);
-  const titleId = useId();
-  useEffect(() => {
-    first.current?.focus();
-  }, []);
-  const undoing = conflict.reason === 'undo' || conflict.reason === 'redo';
-  return (
-    <section {...slot(slots, 'conflict', 'ak-conflict')} role="alert" aria-labelledby={titleId}>
-      <h3 className="ak-conflict-title" id={titleId}>
-        {t('conflictTitle')}
-      </h3>
-      <p>{undoing ? t('conflictUndoBody') : t('conflictBody', { version: conflict.latest.version })}</p>
-      <ChangeList changes={conflict.changes} />
-      <div className="ak-approval-actions">
-        <button
-          ref={first}
-          type="button"
-          className="ak-button"
-          data-variant="primary"
-          onClick={() => session.resolveConflict('keep-theirs')}
-        >
-          {t('keepTheirs')}
-        </button>
-        <button type="button" className="ak-button" onClick={() => session.resolveConflict('reapply')}>
-          <RotateCcw aria-hidden="true" />
-          {t('reapplyMine')}
-        </button>
-      </div>
-    </section>
-  );
-}
-
 function LoadedEditor({
-  kind,
+  format,
   content,
-  ctx: renderCtx,
+  ctx,
+  themeId,
+  locale,
   emit,
   readOnly,
   lint,
+  actions,
+  slots,
 }: {
-  kind: string;
+  slots?: Slots<ArtifactEditorPart>;
+  actions: EditorActions;
+  format: string;
   content: unknown;
-  ctx: ReturnType<typeof renderContext>;
+  ctx: ArtkitContextValue;
+  themeId: string;
+  locale: string;
   emit(operations: unknown[], options?: EmitOptions): void;
   readOnly: boolean;
-  lint: LintIssue[];
+  lint: DraftSnapshot['lint'];
 }) {
-  const ctx = useArtkit();
-  const { Editor, css } = use(ctx.loadEditor(kind));
+  const { Editor, css, toolbar } = use(ctx.loadEditor(format));
+  const renderCtx = useMemo(
+    () => renderContext(ctx, themeId, locale, 'screen', false),
+    [ctx, themeId, locale],
+  );
   return (
     <>
       {css ? (
-        <style href={`artkit-editor-${kind}-${hashString(css)}`} precedence="artkit" nonce={ctx.nonce}>
+        <style href={`artkit-editor-${format}-${hashString(css)}`} precedence="artkit" nonce={ctx.nonce}>
           {css}
         </style>
       ) : null}
-      <Editor content={content} ctx={renderCtx} emit={emit} readOnly={readOnly} lint={lint} />
+      {toolbar === 'format' ? null : <HostToolbar actions={actions} slots={slots} />}
+      <Editor
+        content={content}
+        ctx={renderCtx}
+        emit={emit}
+        readOnly={readOnly}
+        lint={lint}
+        actions={actions}
+      />
     </>
   );
 }
+
+/** Undo, redo, save status and save, drawn by the host above editors that do not draw their own toolbar. */
+function HostToolbar({ actions, slots }: { actions: EditorActions; slots?: Slots<ArtifactEditorPart> }) {
+  const { t } = useArtkit();
+  return (
+    <header {...slot(slots, 'toolbar', 'ak-editor-toolbar')}>
+      <div className="ak-editor-history">
+        <button
+          type="button"
+          className="ak-button"
+          data-variant="quiet"
+          disabled={!actions.canUndo}
+          onClick={actions.undo}
+          aria-label={t('undo')}
+          title={t('undo')}
+        >
+          <Undo2 aria-hidden="true" />
+        </button>
+        <button
+          type="button"
+          className="ak-button"
+          data-variant="quiet"
+          disabled={!actions.canRedo}
+          onClick={actions.redo}
+          aria-label={t('redo')}
+          title={t('redo')}
+        >
+          <Redo2 aria-hidden="true" />
+        </button>
+      </div>
+      <span {...slot(slots, 'status', 'ak-editor-status')} role="status" aria-live="polite">
+        {actions.dirty ? t('unsaved') : t('saved')}
+      </span>
+      <button
+        type="button"
+        className="ak-button"
+        data-variant="primary"
+        disabled={!actions.canSave}
+        onClick={actions.save}
+      >
+        <Save aria-hidden="true" />
+        {actions.saving ? t('saving') : t('save')}
+      </button>
+    </header>
+  );
+}

package/src/components/icons.tsx

@@ -8,7 +8,7 @@ export const KIND_ICONS: Record<string, LucideIcon> = {
   diagram: Workflow,
 };
 
-export function KindIcon({ kind, className }: { kind: string; className?: string }) {
-  const Icon = KIND_ICONS[kind] ?? File;
+export function KindIcon({ format, className }: { format: string; className?: string }) {
+  const Icon = KIND_ICONS[format] ?? File;
   return <Icon aria-hidden="true" focusable="false" className={className} />;
 }