@artkit-ai/react 0.0.0-stage → 0.1.0

package/src/components/shared.tsx

@@ -0,0 +1,207 @@
+import type { ArtifactStatus, ChangeSummary } from '@artkit-ai/core';
+import { isArtifactError } from '@artkit-ai/core';
+import { RotateCw } from 'lucide-react';
+import {
+  Component,
+  type CSSProperties,
+  type ErrorInfo,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { type ArtkitContextValue, useArtkit } from '../context.js';
+import type { UiMessageKey } from '../i18n.js';
+
+/**
+ * Customization without forking (spec §13.5): each named part of a component accepts extra classes and
+ * inline styles. Base classes (`ak-*`) stay, so overrides compose with the default CSS.
+ */
+export type Slots<Part extends string> = Partial<Record<Part, { className?: string; style?: CSSProperties }>>;
+
+export function cx(...classes: (string | false | null | undefined)[]): string {
+  return classes.filter(Boolean).join(' ');
+}
+
+export function slot<Part extends string>(
+  slots: Slots<Part> | undefined,
+  part: Part,
+  base: string,
+): { className: string; style?: CSSProperties } {
+  const custom = slots?.[part];
+  return { className: cx(base, custom?.className), ...(custom?.style ? { style: custom.style } : {}) };
+}
+
+/** Attributes of every artkit root element: theme scope and forced light/dark. */
+export function rootAttributes(ctx: ArtkitContextValue, themeId?: string): Record<string, string> {
+  return {
+    ...(themeId ? { 'data-ak-theme': themeId } : {}),
+    ...(ctx.colorScheme !== 'system' ? { 'data-theme': ctx.colorScheme } : {}),
+  };
+}
+
+export function StatusBadge({ status, className }: { status: ArtifactStatus; className?: string }) {
+  const { t } = useArtkit();
+  return (
+    <span className={cx('ak-badge', className)} data-status={status}>
+      {t(`status_${status}` as UiMessageKey)}
+    </span>
+  );
+}
+
+export function errorMessage(error: unknown, fallback: string): string {
+  if (isArtifactError(error)) {
+    const hint = error.issues.find((issue) => issue.hint)?.hint;
+    return hint ? `${error.message} ${hint}` : error.message;
+  }
+  return fallback;
+}
+
+export function ErrorMessage({
+  error,
+  onRetry,
+  onDismiss,
+  className,
+  style,
+}: {
+  error: unknown;
+  onRetry?: () => void;
+  onDismiss?: () => void;
+  className?: string;
+  style?: CSSProperties;
+}) {
+  const { t } = useArtkit();
+  return (
+    <div role="alert" className={cx('ak-alert', className)} style={style}>
+      <span>{errorMessage(error, t('loadFailed'))}</span>{' '}
+      {onRetry ? (
+        <button type="button" className="ak-button" onClick={onRetry}>
+          <RotateCw aria-hidden="true" />
+          {t('retry')}
+        </button>
+      ) : null}
+      {onDismiss ? (
+        <button type="button" className="ak-button" onClick={onDismiss}>
+          {t('dismiss')}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function Loading({
+  label,
+  className,
+  style,
+}: {
+  label?: string;
+  className?: string;
+  style?: CSSProperties;
+}) {
+  const { t } = useArtkit();
+  return (
+    <div className={cx('ak-loading', className)} style={style} role="status" aria-busy="true">
+      {label ?? t('loading')}
+    </div>
+  );
+}
+
+/**
+ * Polite live region for screen readers (spec §18.2). The text is cleared first so repeating the same
+ * message is announced again.
+ */
+export function useAnnouncer(): [ReactNode, (message: string) => void] {
+  const [message, setMessage] = useState('');
+  const frame = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => () => clearTimeout(frame.current), []);
+  const announce = useCallback((text: string) => {
+    setMessage('');
+    clearTimeout(frame.current);
+    frame.current = setTimeout(() => setMessage(text), 30);
+  }, []);
+  const node = (
+    <div className="ak-sr-only" role="status" aria-live="polite" aria-atomic="true">
+      {message}
+    </div>
+  );
+  return [node, announce];
+}
+
+export function ChangeList({
+  changes,
+  className,
+  style,
+}: {
+  changes: ChangeSummary[];
+  className?: string;
+  style?: CSSProperties;
+}) {
+  const { t } = useArtkit();
+  if (changes.length === 0) return <p className="ak-notice">{t('noChanges')}</p>;
+  return (
+    <ul className={cx('ak-changes', className)} style={style}>
+      {withKeys(changes).map(({ change, key }) => (
+        <li key={key} className="ak-change" data-type={change.type}>
+          <span className="ak-change-type">{t(`change_${change.type}` as UiMessageKey)}</span>
+          <span className="ak-change-target">{change.target}</span>
+          <span className="ak-change-summary">{change.summary}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// Targets can repeat (changed + moved); a per-target counter keeps keys stable across renders.
+function withKeys(changes: ChangeSummary[]): { change: ChangeSummary; key: string }[] {
+  const seen = new Map<string, number>();
+  return changes.map((change) => {
+    const base = `${change.type}:${change.target}`;
+    const count = seen.get(base) ?? 0;
+    seen.set(base, count + 1);
+    return { change, key: count === 0 ? base : `${base}#${count}` };
+  });
+}
+
+interface BoundaryProps {
+  fallback: (error: unknown, reset: () => void) => ReactNode;
+  onReset?: () => void;
+  children?: ReactNode;
+}
+
+/** Catches loader and renderer failures so one broken kind does not take the page down. */
+export class ErrorBoundary extends Component<BoundaryProps, { error: unknown; failed: boolean }> {
+  override state = { error: undefined as unknown, failed: false };
+
+  static getDerivedStateFromError(error: unknown) {
+    return { error, failed: true };
+  }
+
+  override componentDidCatch(_error: unknown, _info: ErrorInfo): void {
+    // Rendering the fallback is enough; the host app can wrap its own reporting boundary around us.
+  }
+
+  reset = () => {
+    this.props.onReset?.();
+    this.setState({ error: undefined, failed: false });
+  };
+
+  override render() {
+    if (this.state.failed) return this.props.fallback(this.state.error, this.reset);
+    return this.props.children;
+  }
+}
+
+export function formatDate(value: string, locale: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'short', timeStyle: 'short' }).format(date);
+  } catch {
+    return date.toISOString();
+  }
+}
+
+export function kindLabel(ctx: ArtkitContextValue, kind: string): string {
+  return ctx.registry.has(kind) ? ctx.registry.get(kind).label : kind;
+}

package/src/components/version-diff.tsx

@@ -0,0 +1,266 @@
+import type { Artifact, ChangeSummary } from '@artkit-ai/core';
+import { Columns2, Rows2 } from 'lucide-react';
+import { useMemo, useState } from 'react';
+import { type ArtkitContextValue, useArtkit } from '../context.js';
+import { useArtifact } from '../hooks.js';
+import { diffLines, type LineDiffEntry, toSplitRows } from '../line-diff.js';
+import { ChangeList, cx, ErrorMessage, Loading, rootAttributes, type Slots, slot } from './shared.js';
+
+export type DiffLayout = 'unified' | 'split';
+export type ArtifactVersionDiffPart = 'toolbar' | 'changes' | 'lines';
+
+export interface ArtifactVersionDiffProps {
+  /** Load both versions by id. */
+  id?: string;
+  /** Older version; defaults to the one before `to`. */
+  from?: number;
+  /** Newer version; defaults to the latest. */
+  to?: number;
+  /** Or pass both artifacts directly. */
+  before?: Artifact;
+  after?: Artifact;
+  layout?: DiffLayout;
+  defaultLayout?: DiffLayout;
+  onLayoutChange?(layout: DiffLayout): void;
+  /** Show the structural change list from `kind.diff` (default true). */
+  showChanges?: boolean;
+  /** Show the line diff of the full projections (default true). */
+  showLines?: boolean;
+  className?: string;
+  slots?: Slots<ArtifactVersionDiffPart>;
+}
+
+export interface VersionComparison {
+  changes: ChangeSummary[];
+  lines: LineDiffEntry[];
+}
+
+/** Structural changes plus a line diff of the full text projections. `before` undefined means empty. */
+export function compareVersions(
+  ctx: ArtkitContextValue,
+  before: Artifact | undefined,
+  after: Artifact,
+): VersionComparison {
+  const kind = ctx.registry.get(after.kind);
+  const beforeContent = before?.content ?? kind.empty();
+  const changes: ChangeSummary[] = [];
+  if (before && before.title !== after.title) {
+    changes.push({
+      type: 'changed',
+      target: 'envelope:title',
+      summary: `'${before.title}' → '${after.title}'`,
+    });
+  }
+  try {
+    changes.push(...kind.diff(beforeContent, after.content));
+  } catch {
+    // The text diff below still shows what changed.
+  }
+  const project = (content: unknown, artifact: Artifact) => {
+    try {
+      return kind.project(content, {
+        mode: 'full',
+        locale: artifact.locale,
+        theme: ctx.themeFor(artifact.themeId),
+      }).text;
+    } catch {
+      return JSON.stringify(content, null, 2);
+    }
+  };
+  const lines = diffLines(before ? project(beforeContent, before) : '', project(after.content, after));
+  return { changes, lines };
+}
+
+/** Side-by-side or highlighted comparison between two versions (spec §13.1). */
+export function ArtifactVersionDiff(props: ArtifactVersionDiffProps) {
+  const ctx = useArtkit();
+  const { t } = ctx;
+  const [ownLayout, setOwnLayout] = useState<DiffLayout>(props.defaultLayout ?? 'unified');
+  const layout = props.layout ?? ownLayout;
+  const setLayout = (next: DiffLayout) => {
+    setOwnLayout(next);
+    props.onLayoutChange?.(next);
+  };
+
+  const afterQuery = useArtifact(
+    props.after ? undefined : props.id,
+    props.to === undefined ? {} : { version: props.to },
+  );
+  const after = props.after ?? afterQuery.artifact;
+  const fromVersion = props.from ?? (after && after.version > 1 ? after.version - 1 : undefined);
+  const beforeQuery = useArtifact(
+    props.before || fromVersion === undefined ? undefined : (props.id ?? after?.id),
+    {
+      ...(fromVersion === undefined ? {} : { version: fromVersion }),
+    },
+  );
+  const before = props.before ?? (fromVersion === undefined ? undefined : beforeQuery.artifact);
+
+  const comparison = useMemo(
+    () => (after && ctx.registry.has(after.kind) ? compareVersions(ctx, before, after) : undefined),
+    [ctx, before, after],
+  );
+
+  const error = afterQuery.error ?? beforeQuery.error;
+  const waiting = !after || (fromVersion !== undefined && !before);
+  const attrs = rootAttributes(ctx, after?.themeId);
+  if (error) {
+    return (
+      <div className={cx('ak-root ak-diff', props.className)} {...attrs}>
+        <ErrorMessage error={error} />
+      </div>
+    );
+  }
+  if (waiting || !comparison || !after) {
+    return (
+      <div className={cx('ak-root ak-diff', props.className)} {...attrs}>
+        <Loading />
+      </div>
+    );
+  }
+
+  const beforeLabel = before ? t('diffBefore', { version: before.version }) : '—';
+  const afterLabel = t('diffAfter', { version: after.version });
+
+  return (
+    <div className={cx('ak-root ak-diff', props.className)} {...attrs}>
+      {props.showChanges === false ? null : (
+        <section aria-label={t('changes')}>
+          <ChangeList changes={comparison.changes} {...slot(props.slots, 'changes', '')} />
+        </section>
+      )}
+      {props.showLines === false ? null : (
+        <>
+          <fieldset {...slot(props.slots, 'toolbar', 'ak-diff-toolbar')}>
+            <legend className="ak-sr-only">{t('diffViewLabel')}</legend>
+            {(['unified', 'split'] as const).map((option) => (
+              <button
+                key={option}
+                type="button"
+                className="ak-button"
+                aria-pressed={layout === option}
+                onClick={() => setLayout(option)}
+              >
+                {option === 'unified' ? <Rows2 aria-hidden="true" /> : <Columns2 aria-hidden="true" />}
+                {option === 'unified' ? t('diffUnified') : t('diffSplit')}
+              </button>
+            ))}
+          </fieldset>
+          {layout === 'unified' ? (
+            <UnifiedLines
+              lines={comparison.lines}
+              caption={`${beforeLabel} → ${afterLabel}`}
+              slots={props.slots}
+            />
+          ) : (
+            <SplitLines
+              lines={comparison.lines}
+              beforeLabel={beforeLabel}
+              afterLabel={afterLabel}
+              slots={props.slots}
+            />
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function Marker({ type }: { type: LineDiffEntry['type'] }) {
+  const { t } = useArtkit();
+  if (type === 'equal') return <td className="ak-diff-marker" />;
+  return (
+    <td className="ak-diff-marker">
+      <span aria-hidden="true">{type === 'insert' ? '+' : '−'}</span>
+      <span className="ak-sr-only">{type === 'insert' ? t('lineAdded') : t('lineRemoved')}</span>
+    </td>
+  );
+}
+
+function UnifiedLines({
+  lines,
+  caption,
+  slots,
+}: {
+  lines: LineDiffEntry[];
+  caption: string;
+  slots?: Slots<ArtifactVersionDiffPart> | undefined;
+}) {
+  return (
+    <table {...slot(slots, 'lines', 'ak-diff-lines')} data-layout="unified">
+      <caption className="ak-sr-only">{caption}</caption>
+      <tbody>
+        {lines.map((line) => (
+          <tr
+            key={`${line.type}:${line.oldLine ?? '-'}:${line.newLine ?? '-'}`}
+            className="ak-diff-line"
+            data-type={line.type}
+          >
+            <th scope="row">{line.oldLine ?? ''}</th>
+            <th scope="row">{line.newLine ?? ''}</th>
+            <Marker type={line.type} />
+            <td>{line.text}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+function SplitLines({
+  lines,
+  beforeLabel,
+  afterLabel,
+  slots,
+}: {
+  lines: LineDiffEntry[];
+  beforeLabel: string;
+  afterLabel: string;
+  slots?: Slots<ArtifactVersionDiffPart> | undefined;
+}) {
+  const rows = useMemo(() => toSplitRows(lines), [lines]);
+  return (
+    <table {...slot(slots, 'lines', 'ak-diff-lines')} data-layout="split">
+      <thead>
+        <tr>
+          <th scope="col" colSpan={3}>
+            {beforeLabel}
+          </th>
+          <th scope="col" colSpan={3}>
+            {afterLabel}
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={`${row.left?.oldLine ?? '-'}:${row.right?.newLine ?? '-'}`}>
+            <th scope="row">{row.left?.oldLine ?? ''}</th>
+            {row.left && row.left.type !== 'equal' ? (
+              <Marker type="delete" />
+            ) : (
+              <td className="ak-diff-marker" />
+            )}
+            <td
+              className="ak-diff-cell"
+              data-type={row.left && row.left.type !== 'equal' ? 'delete' : undefined}
+            >
+              {row.left?.text ?? ''}
+            </td>
+            <th scope="row">{row.right?.newLine ?? ''}</th>
+            {row.right && row.right.type !== 'equal' ? (
+              <Marker type="insert" />
+            ) : (
+              <td className="ak-diff-marker" />
+            )}
+            <td
+              className="ak-diff-cell"
+              data-type={row.right && row.right.type !== 'equal' ? 'insert' : undefined}
+            >
+              {row.right?.text ?? ''}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/src/components/view.tsx

@@ -0,0 +1,199 @@
+import type { Artifact, RenderContext } from '@artkit-ai/core';
+import { Suspense, use, useMemo, useRef } from 'react';
+import { type ArtkitContextValue, useArtkit } from '../context.js';
+import { useArtifact } from '../hooks.js';
+import { parsePartialJson } from '../partial-json.js';
+import { hashString } from '../styles.js';
+import { cx, ErrorBoundary, ErrorMessage, Loading, rootAttributes, type Slots, slot } from './shared.js';
+
+export type ArtifactViewPart = 'body' | 'badge' | 'loading' | 'error';
+
+export interface ArtifactViewProps {
+  /** Committed artifact to show. */
+  artifact?: Artifact;
+  /** Alternatively, load by id (latest or `version`). */
+  id?: string;
+  version?: number;
+  /**
+   * Content still being streamed by the model: a partial object or the raw JSON text so far. It goes
+   * through `kind.parsePartial` and shows as a provisional preview until a newer committed version
+   * arrives (spec §13.4).
+   */
+  partial?: unknown;
+  /** Kind of the partial content when no artifact exists yet. */
+  kind?: string;
+  /** Theme and locale of the partial content when no artifact exists yet. */
+  themeId?: string;
+  locale?: string;
+  mode?: RenderContext['mode'];
+  className?: string;
+  slots?: Slots<ArtifactViewPart>;
+}
+
+/** Turns streamed content into renderable content, or undefined while nothing complete arrived yet. */
+export function previewContent(ctx: ArtkitContextValue, kind: string, partial: unknown): unknown {
+  if (!ctx.registry.has(kind)) return undefined;
+  const raw = typeof partial === 'string' && /^\s*[[{]/.test(partial) ? parsePartialJson(partial) : partial;
+  if (raw === undefined) return undefined;
+  try {
+    return ctx.registry.get(kind).parsePartial(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+export function renderContext(
+  ctx: ArtkitContextValue,
+  themeId: string | undefined,
+  locale: string,
+  mode: RenderContext['mode'],
+  provisional: boolean,
+): RenderContext {
+  return {
+    theme: ctx.themeFor(themeId),
+    locale,
+    mode,
+    ...(provisional ? { provisional: true } : {}),
+    ...(ctx.resolveAssetUrl ? { resolveAssetUrl: ctx.resolveAssetUrl } : {}),
+  };
+}
+
+/** Read-only view of any artifact by kind (spec §13.1). */
+export function ArtifactView(props: ArtifactViewProps) {
+  const ctx = useArtkit();
+  const { t } = ctx;
+  const loaded = useArtifact(
+    props.artifact ? undefined : props.id,
+    props.version === undefined ? {} : { version: props.version },
+  );
+  const committed = props.artifact ?? loaded.artifact;
+
+  // Remember which committed version was on screen when streaming started: any other version arriving
+  // afterwards is the commit that replaces the preview, even if the caller still passes `partial`.
+  const streamStart = useRef<{ version: number | undefined } | null>(null);
+  const stillLoading = !props.artifact && props.id !== undefined && loaded.loading;
+  if (props.partial === undefined) streamStart.current = null;
+  else if (streamStart.current === null && !stillLoading)
+    streamStart.current = { version: committed?.version };
+  const showPartial =
+    props.partial !== undefined &&
+    (streamStart.current === null || committed?.version === streamStart.current.version);
+
+  const kind = props.kind ?? committed?.kind;
+  const partialContent = useMemo(
+    () => (showPartial && kind ? previewContent(ctx, kind, props.partial) : undefined),
+    [ctx, kind, props.partial, showPartial],
+  );
+
+  const themeId = committed?.themeId ?? props.themeId;
+  const locale = committed?.locale ?? props.locale ?? ctx.locale;
+  const mode = props.mode ?? 'screen';
+  const rootClass = cx('ak-root ak-view', props.className);
+  const attrs = rootAttributes(ctx, themeId);
+
+  if (showPartial) {
+    return (
+      <div className={rootClass} {...attrs} data-provisional="true" lang={locale} aria-busy="true">
+        <span
+          {...slot(props.slots, 'badge', 'ak-badge ak-view-badge')}
+          data-variant="provisional"
+          role="status"
+        >
+          {t('provisional')}
+        </span>
+        {partialContent === undefined || !kind ? (
+          <Loading label={t('generating')} {...slot(props.slots, 'loading', '')} />
+        ) : (
+          <div {...slot(props.slots, 'body', 'ak-view-body')}>
+            <KindRenderer
+              kind={kind}
+              content={partialContent}
+              ctx={renderContext(ctx, themeId, locale, mode, true)}
+            />
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  if (!committed) {
+    return (
+      <div className={rootClass} {...attrs}>
+        {loaded.error ? (
+          <ErrorMessage
+            error={loaded.error}
+            onRetry={() => void loaded.refresh().catch(() => undefined)}
+            {...slot(props.slots, 'error', '')}
+          />
+        ) : (
+          <Loading {...slot(props.slots, 'loading', '')} />
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={rootClass}
+      {...attrs}
+      lang={committed.locale}
+      data-kind={committed.kind}
+      data-version={committed.version}
+    >
+      <div {...slot(props.slots, 'body', 'ak-view-body')}>
+        <KindRenderer
+          kind={committed.kind}
+          content={committed.content}
+          ctx={renderContext(ctx, themeId, locale, mode, false)}
+        />
+      </div>
+    </div>
+  );
+}
+
+interface KindRendererProps {
+  kind: string;
+  content: unknown;
+  ctx: RenderContext;
+  className?: string;
+}
+
+/** Lazy kind renderer with a JSON fallback when the kind has no renderer loader. */
+export function KindRenderer(props: KindRendererProps) {
+  const ctx = useArtkit();
+  if (!ctx.hasRenderer(props.kind)) {
+    return (
+      <div className={props.className}>
+        <p className="ak-notice">{ctx.t('noRenderer', { kind: props.kind })}</p>
+        <pre className="ak-code">
+          <code>{JSON.stringify(props.content, null, 2)}</code>
+        </pre>
+      </div>
+    );
+  }
+  return (
+    <ErrorBoundary
+      onReset={() => ctx.resetLoad('renderer', props.kind)}
+      fallback={(error, reset) => <ErrorMessage error={error} onRetry={reset} />}
+    >
+      <Suspense fallback={<Loading />}>
+        <LoadedRenderer {...props} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+function LoadedRenderer({ kind, content, ctx: renderCtx, className }: KindRendererProps) {
+  const ctx = useArtkit();
+  const { Renderer, css } = use(ctx.loadRenderer(kind));
+  return (
+    <>
+      {css ? (
+        <style href={`artkit-kind-${kind}-${hashString(css)}`} precedence="artkit" nonce={ctx.nonce}>
+          {css}
+        </style>
+      ) : null}
+      <Renderer content={content} ctx={renderCtx} {...(className ? { className } : {})} />
+    </>
+  );
+}