@artkit-ai/react 0.0.0-stage → 0.2.0

package/src/components/editor.tsx

@@ -0,0 +1,292 @@
+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 { hashString } from '../styles.js';
+import { cx, ErrorBoundary, ErrorMessage, Loading, rootAttributes, type Slots, slot } from './shared.js';
+import { ArtifactView, renderContext } from './view.js';
+
+/**
+ * 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 {
+  /** Artifact to edit. Its content is the starting point of the draft. */
+  artifact?: Artifact;
+  /** 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>;
+}
+
+/**
+ * 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 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)}>
+        {fetched.error ? (
+          <ErrorMessage error={fetched.error} onRetry={() => void fetched.refresh().catch(() => undefined)} />
+        ) : (
+          <Loading />
+        )}
+      </div>
+    );
+  }
+
+  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"
+      >
+        <ArtifactView artifact={artifact} />
+      </div>
+    );
+  }
+  return <EditingHost key={artifact.id} {...props} artifact={artifact} />;
+}
+
+function EditingHost({
+  artifact,
+  readOnly,
+  onSave,
+  onChange,
+  className,
+  slots,
+}: ArtifactEditorProps & { artifact: Artifact }) {
+  const ctx = useArtkit();
+  const [session] = useState(
+    () => new DraftSession({ registry: ctx.registry, artifact, locale: ctx.locale }),
+  );
+  const snapshot = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState<unknown>();
+
+  // A newer artifact from the application (after a save, or a reload) moves the draft forward.
+  useEffect(() => {
+    if (
+      artifact.version !== session.getSnapshot().baseVersion ||
+      artifact.id !== session.getSnapshot().artifact.id
+    ) {
+      session.load(artifact);
+    }
+  }, [artifact, session]);
+
+  useEffect(() => {
+    onChange?.(snapshot);
+  }, [snapshot, onChange]);
+
+  const draft = snapshot.artifact;
+  const canSave = Boolean(onSave) && snapshot.dirty && !saving && !readOnly;
+
+  async function save() {
+    if (!canSave || !onSave) return;
+    setSaving(true);
+    setSaveError(undefined);
+    try {
+      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);
+    }
+  }
+
+  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', className)}
+      {...rootAttributes(ctx, draft.themeId)}
+      data-dirty={snapshot.dirty || undefined}
+      onKeyDown={onKeyDown}
+    >
+      {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
+              slots={slots}
+              actions={actions}
+              format={draft.format}
+              content={draft.content}
+              ctx={ctx}
+              themeId={draft.themeId}
+              locale={draft.locale}
+              emit={emit}
+              readOnly={Boolean(readOnly)}
+              lint={snapshot.lint}
+            />
+          </Suspense>
+        </ErrorBoundary>
+      </div>
+    </section>
+  );
+}
+
+function LoadedEditor({
+  format,
+  content,
+  ctx,
+  themeId,
+  locale,
+  emit,
+  readOnly,
+  lint,
+  actions,
+  slots,
+}: {
+  slots?: Slots<ArtifactEditorPart>;
+  actions: EditorActions;
+  format: string;
+  content: unknown;
+  ctx: ArtkitContextValue;
+  themeId: string;
+  locale: string;
+  emit(operations: unknown[], options?: EmitOptions): void;
+  readOnly: boolean;
+  lint: DraftSnapshot['lint'];
+}) {
+  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-${format}-${hashString(css)}`} precedence="artkit" nonce={ctx.nonce}>
+          {css}
+        </style>
+      ) : null}
+      {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

@@ -0,0 +1,14 @@
+import { File, FileText, type LucideIcon, Presentation, Sheet, Workflow } from 'lucide-react';
+
+/** Lucide icon per native kind; unknown kinds get a generic file. */
+export const KIND_ICONS: Record<string, LucideIcon> = {
+  document: FileText,
+  sheet: Sheet,
+  slides: Presentation,
+  diagram: Workflow,
+};
+
+export function KindIcon({ format, className }: { format: string; className?: string }) {
+  const Icon = KIND_ICONS[format] ?? File;
+  return <Icon aria-hidden="true" focusable="false" className={className} />;
+}

package/src/components/panel.tsx

@@ -0,0 +1,334 @@
+import type { Artifact } from '@artkit-ai/core';
+import { ChevronDown, Copy, Download, X } from 'lucide-react';
+import {
+  type KeyboardEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useArtkit } from '../context.js';
+import type { DraftSnapshot } from '../editor-session.js';
+import { useArtifact, useArtifactExport } from '../hooks.js';
+import type { UiMessageKey } from '../i18n.js';
+import { ArtifactEditor, type ArtifactEditorProps } from './editor.js';
+import {
+  cx,
+  ErrorMessage,
+  formatLabel,
+  Loading,
+  rootAttributes,
+  type Slots,
+  slot,
+  useAnnouncer,
+} from './shared.js';
+import { ArtifactView } from './view.js';
+
+export type PanelTab = 'view' | 'edit' | 'code';
+export type ArtifactPanelPart = 'header' | 'title' | 'toolbar' | 'tabs' | 'body' | 'code';
+
+export interface ArtifactPanelProps {
+  id?: string;
+  artifact?: Artifact;
+  tab?: PanelTab;
+  defaultTab?: PanelTab;
+  onTabChange?(tab: PanelTab): void;
+  /** Save action of the editor tab: the application decides what saving means. */
+  onSave?: ArtifactEditorProps['onSave'];
+  /** Draft changes, forwarded from the editor tab. */
+  onChange?(snapshot: DraftSnapshot): void;
+  /** Export formats; defaults to the provider's server formats plus browser exporters. */
+  exportFormats?: string[];
+  onClose?(): void;
+  /** Extra controls rendered in the header. */
+  headerActions?: ReactNode;
+  className?: string;
+  slots?: Slots<ArtifactPanelPart>;
+}
+
+const TABS: PanelTab[] = ['view', 'edit', 'code'];
+const TAB_LABEL: Record<PanelTab, UiMessageKey> = { view: 'tabView', edit: 'tabEdit', code: 'tabCode' };
+
+/**
+ * Side panel of one artifact: View, Edit and Code tabs and the export menu (spec §13.1). There is no history, approval
+ * or archive here: the application owns versions and publication.
+ */
+export function ArtifactPanel(props: ArtifactPanelProps) {
+  const ctx = useArtkit();
+  const { t } = ctx;
+  const id = props.id ?? props.artifact?.id;
+  const latestQuery = useArtifact(id, props.artifact ? { initial: props.artifact } : {});
+  const latest = latestQuery.artifact;
+
+  const [ownTab, setOwnTab] = useState<PanelTab>(props.defaultTab ?? 'view');
+  const tab = props.tab ?? ownTab;
+  const selectTab = (next: PanelTab) => {
+    setOwnTab(next);
+    props.onTabChange?.(next);
+  };
+  const exporter = useArtifactExport(id ?? '', latest?.format);
+  const [live, announce] = useAnnouncer();
+  const baseId = useId();
+
+  if (!latest || !id) {
+    return (
+      <aside className={cx('ak-root ak-panel', props.className)} {...rootAttributes(ctx)}>
+        {latestQuery.error ? (
+          <ErrorMessage
+            error={latestQuery.error}
+            onRetry={() => void latestQuery.refresh().catch(() => undefined)}
+          />
+        ) : (
+          <Loading />
+        )}
+      </aside>
+    );
+  }
+
+  async function exportAs(format: string) {
+    try {
+      const result = await exporter.exportArtifact(format, {});
+      announce(t('exported', { filename: result.filename }));
+    } catch {
+      // The hook keeps the error; it is rendered below.
+    }
+  }
+
+  const tabId = (name: PanelTab) => `${baseId}-tab-${name}`;
+  const panelId = (name: PanelTab) => `${baseId}-panel-${name}`;
+  const onTabKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    const index = TABS.indexOf(tab);
+    let next: PanelTab | undefined;
+    if (event.key === 'ArrowRight') next = TABS[(index + 1) % TABS.length];
+    else if (event.key === 'ArrowLeft') next = TABS[(index + TABS.length - 1) % TABS.length];
+    else if (event.key === 'Home') next = TABS[0];
+    else if (event.key === 'End') next = TABS[TABS.length - 1];
+    if (!next) return;
+    event.preventDefault();
+    selectTab(next);
+    document.getElementById(tabId(next))?.focus();
+  };
+
+  const exportFormats = props.exportFormats ?? exporter.formats;
+
+  return (
+    <aside
+      className={cx('ak-root ak-panel', props.className)}
+      {...rootAttributes(ctx, latest.themeId)}
+      aria-labelledby={`${baseId}-title`}
+      data-format={latest.format}
+    >
+      {live}
+      <header {...slot(props.slots, 'header', 'ak-panel-header')}>
+        <h2 id={`${baseId}-title`} {...slot(props.slots, 'title', 'ak-panel-title')}>
+          {latest.title}
+        </h2>
+        <span className="ak-history-meta">{formatLabel(ctx, latest.format)}</span>
+        <span className="ak-badge">{t('versionShort', { version: latest.version })}</span>
+        {props.headerActions}
+        <ExportMenu
+          formats={exportFormats}
+          pending={exporter.pending}
+          onOpen={() => void exporter.loadFormats()}
+          onSelect={(format) => void exportAs(format)}
+        />
+        {props.onClose ? (
+          <button
+            type="button"
+            className="ak-button"
+            data-variant="quiet"
+            onClick={props.onClose}
+            aria-label={t('close')}
+          >
+            <X aria-hidden="true" />
+          </button>
+        ) : null}
+      </header>
+      {exporter.error ? <ErrorMessage error={exporter.error} className="ak-panel-notice" /> : null}
+
+      <div role="tablist" aria-label={latest.title} {...slot(props.slots, 'tabs', 'ak-tabs')}>
+        {TABS.map((name) => (
+          <button
+            key={name}
+            id={tabId(name)}
+            type="button"
+            role="tab"
+            className="ak-tab"
+            aria-selected={tab === name}
+            aria-controls={panelId(name)}
+            tabIndex={tab === name ? 0 : -1}
+            onClick={() => selectTab(name)}
+            onKeyDown={onTabKeyDown}
+          >
+            {t(TAB_LABEL[name])}
+          </button>
+        ))}
+      </div>
+
+      <div
+        id={panelId(tab)}
+        role="tabpanel"
+        aria-labelledby={tabId(tab)}
+        {...slot(props.slots, 'body', 'ak-panel-body')}
+      >
+        {tab === 'view' ? <ArtifactView artifact={latest} /> : null}
+        {tab === 'edit' ? (
+          <ArtifactEditor
+            artifact={latest}
+            {...(props.onSave ? { onSave: props.onSave } : {})}
+            {...(props.onChange ? { onChange: props.onChange } : {})}
+          />
+        ) : null}
+        {tab === 'code' ? <CodeTab artifact={latest} slots={props.slots} /> : null}
+      </div>
+    </aside>
+  );
+}
+
+function CodeTab({
+  artifact,
+  slots,
+}: {
+  artifact: Artifact | undefined;
+  slots?: Slots<ArtifactPanelPart> | undefined;
+}) {
+  const { t } = useArtkit();
+  const [copied, setCopied] = useState(false);
+  const text = useMemo(() => (artifact ? JSON.stringify(artifact.content, null, 2) : ''), [artifact]);
+  if (!artifact) return <Loading />;
+  const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
+  return (
+    <div className="ak-code-tab">
+      {clipboard ? (
+        <button
+          type="button"
+          className="ak-button"
+          onClick={() => {
+            clipboard.writeText(text).then(
+              () => setCopied(true),
+              () => setCopied(false),
+            );
+          }}
+        >
+          <Copy aria-hidden="true" />
+          {copied ? t('copied') : t('copy')}
+        </button>
+      ) : null}
+      <pre {...slot(slots, 'code', 'ak-code')}>
+        <code>{text}</code>
+      </pre>
+    </div>
+  );
+}
+
+function ExportMenu(props: {
+  formats: string[];
+  pending: string | undefined;
+  onOpen(): void;
+  onSelect(format: string): void;
+}) {
+  const { t } = useArtkit();
+  const [open, setOpen] = useState(false);
+  const button = useRef<HTMLButtonElement>(null);
+  const list = useRef<HTMLDivElement>(null);
+  const menuId = useId();
+
+  const items = useCallback(
+    () => [...(list.current?.querySelectorAll<HTMLButtonElement>('[role="menuitem"]') ?? [])],
+    [],
+  );
+  useEffect(() => {
+    if (open) items()[0]?.focus();
+  }, [open, items]);
+
+  const close = (refocus: boolean) => {
+    setOpen(false);
+    if (refocus) button.current?.focus();
+  };
+
+  const onMenuKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const all = items();
+    const index = all.indexOf(document.activeElement as HTMLButtonElement);
+    let next: HTMLButtonElement | undefined;
+    if (event.key === 'ArrowDown') next = all[(index + 1) % all.length];
+    else if (event.key === 'ArrowUp') next = all[(index - 1 + all.length) % all.length];
+    else if (event.key === 'Home') next = all[0];
+    else if (event.key === 'End') next = all[all.length - 1];
+    else if (event.key === 'Escape') {
+      event.preventDefault();
+      close(true);
+      return;
+    } else if (event.key === 'Tab') {
+      close(false);
+      return;
+    }
+    if (next) {
+      event.preventDefault();
+      next.focus();
+    }
+  };
+
+  return (
+    <div className="ak-menu">
+      <button
+        ref={button}
+        type="button"
+        className="ak-button"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? menuId : undefined}
+        disabled={props.pending !== undefined}
+        onClick={() => {
+          if (!open) props.onOpen();
+          setOpen(!open);
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'ArrowDown' && !open) {
+            event.preventDefault();
+            props.onOpen();
+            setOpen(true);
+          }
+        }}
+      >
+        <Download aria-hidden="true" />
+        {props.pending ? t('exporting') : t('export')}
+        <ChevronDown aria-hidden="true" />
+      </button>
+      {open ? (
+        <div
+          ref={list}
+          id={menuId}
+          role="menu"
+          className="ak-menu-list"
+          aria-label={t('export')}
+          tabIndex={-1}
+          onKeyDown={onMenuKeyDown}
+        >
+          {props.formats.length === 0 ? (
+            <p className="ak-menu-item">{t('noExportFormats')}</p>
+          ) : (
+            props.formats.map((format) => (
+              <button
+                key={format}
+                type="button"
+                role="menuitem"
+                className="ak-menu-item"
+                tabIndex={-1}
+                aria-label={t('exportAs', { format: format.toUpperCase() })}
+                onClick={() => {
+                  close(true);
+                  props.onSelect(format);
+                }}
+              >
+                {format.toUpperCase()}
+              </button>
+            ))
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+}