@artkit-ai/react 0.0.0-stage → 0.2.0

package/src/components/shared.tsx

@@ -0,0 +1,198 @@
+import type { 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 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 formatLabel(ctx: ArtkitContextValue, format: string): string {
+  return ctx.registry.has(format) ? ctx.registry.get(format).label : format;
+}

package/src/components/view.tsx

@@ -0,0 +1,196 @@
+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 the artifact by id. */
+  id?: string;
+  /**
+   * Content still being streamed by the model: a partial object or the raw JSON text so far. It goes
+   * through `format.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. */
+  format?: 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, format: string, partial: unknown): unknown {
+  if (!ctx.registry.has(format)) return undefined;
+  const raw = typeof partial === 'string' && /^\s*[[{]/.test(partial) ? parsePartialJson(partial) : partial;
+  if (raw === undefined) return undefined;
+  try {
+    // Adapters take the streamed text; structured partials (e.g. a workbook JSON) are serialized first.
+    return ctx.registry.get(format).parsePartial(typeof raw === 'string' ? raw : JSON.stringify(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);
+  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 format = props.format ?? committed?.format;
+  const partialContent = useMemo(
+    () => (showPartial && format ? previewContent(ctx, format, props.partial) : undefined),
+    [ctx, format, 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 || !format ? (
+          <Loading label={t('generating')} {...slot(props.slots, 'loading', '')} />
+        ) : (
+          <div {...slot(props.slots, 'body', 'ak-view-body')}>
+            <FormatRenderer
+              format={format!}
+              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-format={committed.format}
+      data-version={committed.version}
+    >
+      <div {...slot(props.slots, 'body', 'ak-view-body')}>
+        <FormatRenderer
+          format={committed.format}
+          content={committed.content}
+          ctx={renderContext(ctx, themeId, locale, mode, false)}
+        />
+      </div>
+    </div>
+  );
+}
+
+interface FormatRendererProps {
+  format: string;
+  content: unknown;
+  ctx: RenderContext;
+  className?: string;
+}
+
+/** Lazy kind renderer with a JSON fallback when the kind has no renderer loader. */
+export function FormatRenderer(props: FormatRendererProps) {
+  const ctx = useArtkit();
+  if (!ctx.hasRenderer(props.format)) {
+    return (
+      <div className={props.className}>
+        <p className="ak-notice">{ctx.t('noRenderer', { format: props.format })}</p>
+        <pre className="ak-code">
+          <code>{JSON.stringify(props.content, null, 2)}</code>
+        </pre>
+      </div>
+    );
+  }
+  return (
+    <ErrorBoundary
+      onReset={() => ctx.resetLoad('renderer', props.format)}
+      fallback={(error, reset) => <ErrorMessage error={error} onRetry={reset} />}
+    >
+      <Suspense fallback={<Loading />}>
+        <LoadedRenderer {...props} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+function LoadedRenderer({ format, content, ctx: renderCtx, className }: FormatRendererProps) {
+  const ctx = useArtkit();
+  const { Renderer, css } = use(ctx.loadRenderer(format));
+  return (
+    <>
+      {css ? (
+        <style href={`artkit-kind-${format}-${hashString(css)}`} precedence="artkit" nonce={ctx.nonce}>
+          {css}
+        </style>
+      ) : null}
+      <Renderer content={content} ctx={renderCtx} {...(className ? { className } : {})} />
+    </>
+  );
+}

package/src/context.ts

@@ -0,0 +1,87 @@
+import type {
+  AnyArtifactExporter,
+  ArtifactRegistry,
+  AssetResolver,
+  EditorBindings,
+  RenderContext,
+  Theme,
+} from '@artkit-ai/core';
+import { type ComponentType, createContext, useContext } from 'react';
+import type { ArtifactCache } from './cache.js';
+import type { ArtifactClient } from './client.js';
+import type { Translate } from './i18n.js';
+
+export interface RendererProps<Content = unknown> {
+  content: Content;
+  ctx: RenderContext;
+  className?: string;
+}
+
+/** What a kind's `/react` entry provides. */
+export interface RendererModule {
+  // biome-ignore lint/suspicious/noExplicitAny: renderers are typed by their own format.
+  Renderer: ComponentType<RendererProps<any>>;
+  css?: string;
+}
+
+/** What a kind's `/edit` entry provides. */
+export interface EditorModule {
+  // biome-ignore lint/suspicious/noExplicitAny: editors are typed by their own format.
+  Editor: ComponentType<EditorBindings<any, any>>;
+  css?: string;
+  /**
+   * Who draws the undo, redo and save controls. `host` (default): the editor host shows them above the format editor.
+   * `format`: the format editor receives `actions` and draws them inside its own toolbar.
+   */
+  toolbar?: 'host' | 'format';
+}
+
+/**
+ * Lazy loaders per format, so the bundle only pulls what is shown (spec §13.6). Typical use:
+ * `renderers: { document: () => import('@artkit-ai/kind-document/react').then((m) => ({ Renderer: m.DocumentRenderer, css: m.documentCss })) }`.
+ */
+export interface ArtifactLoaders {
+  renderers?: Record<string, () => Promise<RendererModule>>;
+  editors?: Record<string, () => Promise<EditorModule>>;
+  exporters?: Record<string, () => Promise<AnyArtifactExporter[]>>;
+}
+
+export type ColorScheme = 'light' | 'dark' | 'system';
+
+export interface ArtkitContextValue {
+  registry: ArtifactRegistry;
+  client: ArtifactClient;
+  cache: ArtifactCache;
+  locale: string;
+  t: Translate;
+  appTheme: Theme;
+  colorScheme: ColorScheme;
+  /** Theme of an artifact: provider themes, then registry themes, then the application theme. */
+  themeFor(themeId: string | undefined): Theme;
+  resolveAssetUrl?: (ref: string) => string | undefined;
+  assets?: AssetResolver;
+  /** Formats the server can export, per format. */
+  exportFormats: Record<string, readonly string[]>;
+  hasRenderer(format: string): boolean;
+  hasEditor(format: string): boolean;
+  hasExporters(format: string): boolean;
+  loadRenderer(format: string): Promise<RendererModule>;
+  loadEditor(format: string): Promise<EditorModule>;
+  loadExporters(format: string): Promise<AnyArtifactExporter[]>;
+  /** Forgets a failed load so it can be retried. */
+  resetLoad(type: 'renderer' | 'editor' | 'exporters', format: string): void;
+  nonce?: string;
+}
+
+export const ArtkitContext = createContext<ArtkitContextValue | null>(null);
+
+/** The artkit context, or null outside `<ArtifactProvider>` (for components that also work standalone). */
+export function useOptionalArtkit(): ArtkitContextValue | null {
+  return useContext(ArtkitContext);
+}
+
+export function useArtkit(): ArtkitContextValue {
+  const value = useContext(ArtkitContext);
+  if (!value) throw new Error('artkit components and hooks must be rendered inside <ArtifactProvider>.');
+  return value;
+}