@echothink-ui/documents 0.1.0

package/src/components/DocumentToolbar.tsx

@@ -0,0 +1,179 @@
+import * as React from "react";
+import {
+  Button,
+  IconButton,
+  LinkButton,
+  type EthAction,
+  type EthDensity
+} from "@echothink-ui/core";
+import type { DocumentComponentBaseProps, DocumentMode } from "./types";
+import { actionIcon, cx, modeLabel } from "./utils";
+
+export interface DocumentToolbarProps extends Omit<
+  DocumentComponentBaseProps<HTMLDivElement>,
+  "children" | "title"
+> {
+  actions: EthAction[];
+  formattingActions?: EthAction[];
+  mode?: DocumentMode;
+  onModeChange?: (mode: DocumentMode) => void;
+  density?: EthDensity;
+}
+
+const modes: DocumentMode[] = ["edit", "review", "view"];
+type ToolbarActionVariant = "icon" | "button";
+
+export function DocumentToolbar({
+  actions,
+  formattingActions = [],
+  mode,
+  onModeChange,
+  density = "default",
+  className,
+  ...props
+}: DocumentToolbarProps) {
+  return (
+    <div
+      {...props}
+      className={cx("eth-doc-toolbar", className)}
+      role="toolbar"
+      aria-label="Document toolbar"
+      data-eth-component="DocumentToolbar"
+    >
+      {formattingActions.length ? (
+        <div
+          className="eth-doc-toolbar__group eth-doc-toolbar__group--formatting"
+          role="group"
+          aria-label="Formatting"
+        >
+          {formattingActions.map((action) => renderToolbarAction(action, density, "icon"))}
+        </div>
+      ) : null}
+
+      {mode && onModeChange ? (
+        <div
+          className="eth-doc-toolbar__group eth-doc-toolbar__group--mode"
+          role="group"
+          aria-label="Document mode"
+        >
+          {modes.map((candidate) => (
+            <Button
+              key={candidate}
+              className="eth-doc-toolbar__mode-button"
+              density={density}
+              intent={candidate === mode ? "primary" : "secondary"}
+              aria-pressed={candidate === mode}
+              onClick={() => onModeChange(candidate)}
+            >
+              {modeLabel(candidate)}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+
+      {actions.length ? (
+        <div
+          className="eth-doc-toolbar__group eth-doc-toolbar__group--actions"
+          role="group"
+          aria-label="Document actions"
+        >
+          {actions.map((action) => renderToolbarAction(action, density, "button"))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function renderToolbarAction(
+  action: EthAction,
+  density: EthDensity,
+  variant: ToolbarActionVariant
+) {
+  const icon = actionIcon(action);
+
+  if (variant === "button") {
+    if (action.href) {
+      return (
+        <LinkButton
+          key={action.id}
+          href={action.href}
+          density={density}
+          intent={action.intent ?? "secondary"}
+          aria-disabled={action.disabled}
+          tabIndex={action.disabled ? -1 : undefined}
+          className={cx(
+            "eth-doc-toolbar__action",
+            action.disabled && "eth-doc-toolbar__link--disabled"
+          )}
+          onClick={(event) => {
+            if (action.disabled) {
+              event.preventDefault();
+              return;
+            }
+            action.onSelect?.();
+          }}
+        >
+          <span className="eth-doc-toolbar__action-icon" aria-hidden="true">
+            {icon}
+          </span>
+          <span>{action.label}</span>
+        </LinkButton>
+      );
+    }
+
+    return (
+      <Button
+        key={action.id}
+        className="eth-doc-toolbar__action"
+        density={density}
+        intent={action.intent ?? "secondary"}
+        icon={icon}
+        disabled={action.disabled}
+        onClick={action.onSelect}
+      >
+        {action.label}
+      </Button>
+    );
+  }
+
+  if (action.href) {
+    return (
+      <a
+        key={action.id}
+        href={action.href}
+        aria-label={action.label}
+        tabIndex={action.disabled ? -1 : undefined}
+        className={cx(
+          "eth-button",
+          "eth-icon-button",
+          "eth-doc-toolbar__icon-link",
+          `eth-button--${action.intent ?? "ghost"}`,
+          `eth-button--${density}`,
+          action.disabled && "eth-doc-toolbar__link--disabled"
+        )}
+        aria-disabled={action.disabled}
+        onClick={(event) => {
+          if (action.disabled) {
+            event.preventDefault();
+            return;
+          }
+          action.onSelect?.();
+        }}
+      >
+        <span className="eth-button__icon">{icon}</span>
+      </a>
+    );
+  }
+
+  return (
+    <IconButton
+      key={action.id}
+      density={density}
+      intent={action.intent ?? "ghost"}
+      label={action.label}
+      icon={icon}
+      disabled={action.disabled}
+      onClick={action.onSelect}
+    />
+  );
+}

package/src/components/DocumentViewer.tsx

@@ -0,0 +1,81 @@
+import * as React from "react";
+import { Badge } from "@echothink-ui/core";
+import type { DocumentAnnotation, DocumentComponentBaseProps, DocumentMetadataItem } from "./types";
+import { cx, formatDateTime } from "./utils";
+
+export interface DocumentViewerProps extends Omit<
+  DocumentComponentBaseProps<HTMLElement>,
+  "children"
+> {
+  title: React.ReactNode;
+  content: React.ReactNode;
+  metadata?: DocumentMetadataItem[];
+  versionRef?: React.ReactNode;
+  annotations?: DocumentAnnotation[];
+}
+
+export function DocumentViewer({
+  title,
+  content,
+  metadata = [],
+  versionRef,
+  annotations = [],
+  className,
+  ...props
+}: DocumentViewerProps) {
+  const titleId = React.useId();
+  const meta = versionRef ? [...metadata, { label: "Version", value: versionRef }] : metadata;
+  const labelledBy = props["aria-labelledby"] ?? titleId;
+
+  return (
+    <article
+      {...props}
+      aria-labelledby={labelledBy}
+      className={cx(
+        "eth-doc-viewer",
+        annotations.length > 0 && "eth-doc-viewer--with-annotations",
+        className
+      )}
+      data-eth-component="DocumentViewer"
+    >
+      <header className="eth-doc-viewer__header">
+        <h2 id={titleId}>{title}</h2>
+      </header>
+
+      {meta.length ? (
+        <dl className="eth-meta-grid eth-doc-viewer__metadata">
+          {meta.map((item, index) => (
+            <div key={`${String(item.label)}-${index}`}>
+              <dt>{item.label}</dt>
+              <dd>{item.value}</dd>
+            </div>
+          ))}
+        </dl>
+      ) : null}
+
+      <div className="eth-doc-viewer__body">
+        <div className="eth-doc-viewer__content">{content}</div>
+
+        {annotations.length ? (
+          <aside className="eth-doc-viewer__annotations" aria-label="Annotations">
+            <h3>Annotations</h3>
+            <ul>
+              {annotations.map((annotation) => (
+                <li key={annotation.id} className="eth-doc-viewer__annotation">
+                  <div className="eth-doc-viewer__annotation-header">
+                    <strong>{annotation.author}</strong>
+                    {annotation.range ? <Badge severity="neutral">{annotation.range}</Badge> : null}
+                    <time dateTime={annotation.createdAt}>
+                      {formatDateTime(annotation.createdAt)}
+                    </time>
+                  </div>
+                  <p>{annotation.comment}</p>
+                </li>
+              ))}
+            </ul>
+          </aside>
+        ) : null}
+      </div>
+    </article>
+  );
+}

package/src/components/DocumentWorkspaceTemplate.tsx

@@ -0,0 +1,109 @@
+import * as React from "react";
+import { EmptyState, type EthAction } from "@echothink-ui/core";
+import { DocumentEditorShell } from "./DocumentEditorShell";
+import { DocumentOutline } from "./DocumentOutline";
+import { DocumentToolbar } from "./DocumentToolbar";
+import { DocumentViewer } from "./DocumentViewer";
+import type {
+  DocumentAnnotation,
+  DocumentComponentBaseProps,
+  DocumentHeading,
+  DocumentLockState,
+  DocumentMetadataItem,
+  DocumentMode,
+  DocumentOwner,
+  DocumentReference
+} from "./types";
+
+export interface DocumentWorkspaceTemplateProps
+  extends Omit<DocumentComponentBaseProps<HTMLElement>, "children"> {
+  title: React.ReactNode;
+  documentRef: DocumentReference;
+  mode?: DocumentMode;
+  lockState?: DocumentLockState;
+  lockOwner?: DocumentOwner;
+  actions?: EthAction[];
+  formattingActions?: EthAction[];
+  onModeChange?: (mode: DocumentMode) => void;
+  headings?: DocumentHeading[];
+  activeHeadingId?: string;
+  onSelectHeading?: (id: string) => void;
+  inspector?: React.ReactNode;
+  toolbar?: React.ReactNode;
+  metadata?: DocumentMetadataItem[];
+  versionRef?: React.ReactNode;
+  annotations?: DocumentAnnotation[];
+  content?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+export function DocumentWorkspaceTemplate({
+  title,
+  documentRef,
+  mode = "edit",
+  lockState = "unlocked",
+  lockOwner,
+  actions = [],
+  formattingActions,
+  onModeChange,
+  headings = [],
+  activeHeadingId,
+  onSelectHeading,
+  inspector,
+  toolbar,
+  metadata,
+  versionRef,
+  annotations,
+  content,
+  children,
+  density,
+  ...props
+}: DocumentWorkspaceTemplateProps) {
+  const outline = headings.length ? (
+    <DocumentOutline
+      headings={headings}
+      activeHeadingId={activeHeadingId}
+      onSelect={onSelectHeading}
+    />
+  ) : null;
+  const resolvedToolbar =
+    toolbar ?? (
+      <DocumentToolbar
+        actions={actions}
+        formattingActions={formattingActions}
+        mode={mode}
+        onModeChange={onModeChange}
+        density={density}
+      />
+    );
+  const body =
+    mode === "view" && content !== undefined ? (
+      <DocumentViewer
+        title={title}
+        content={content}
+        metadata={metadata}
+        versionRef={versionRef}
+        annotations={annotations}
+      />
+    ) : (
+      children ?? content ?? <EmptyState title="No document content" />
+    );
+
+  return (
+    <DocumentEditorShell
+      {...props}
+      title={title}
+      documentRef={documentRef}
+      mode={mode}
+      lockState={lockState}
+      lockOwner={lockOwner}
+      toolbar={resolvedToolbar}
+      outline={outline}
+      inspector={inspector}
+      density={density}
+      data-eth-component="DocumentWorkspaceTemplate"
+    >
+      {body}
+    </DocumentEditorShell>
+  );
+}

package/src/components/types.ts

@@ -0,0 +1,63 @@
+import type * as React from "react";
+import type { EthAction, EthDensity } from "@echothink-ui/core";
+
+export type DocumentMode = "edit" | "review" | "view";
+
+export type DocumentLockState =
+  | "unlocked"
+  | "locked-by-user"
+  | "locked-by-agent"
+  | "locked-by-other";
+
+export interface DocumentOwner {
+  id: string;
+  label: string;
+}
+
+export type DocumentReference =
+  | string
+  | {
+      id: string;
+      label?: React.ReactNode;
+      href?: string;
+      kind?: string;
+      version?: string;
+    };
+
+export interface DocumentMetadataItem {
+  label: React.ReactNode;
+  value: React.ReactNode;
+}
+
+export interface DocumentHeading {
+  id: string;
+  level: 1 | 2 | 3 | 4;
+  text: React.ReactNode;
+  href?: string;
+}
+
+export interface DocumentAnnotation {
+  id: string;
+  range?: string;
+  comment: React.ReactNode;
+  author: React.ReactNode;
+  createdAt: string;
+}
+
+export interface DocumentPendingChange {
+  id: string;
+  summary: React.ReactNode;
+  diffSnippet?: React.ReactNode;
+}
+
+export interface DocumentComponentBaseProps<T extends HTMLElement = HTMLElement>
+  extends Omit<React.HTMLAttributes<T>, "title" | "content" | "onSelect"> {
+  title?: React.ReactNode;
+  density?: EthDensity;
+  "data-eth-component"?: string;
+}
+
+export interface DocumentToolbarActionGroup {
+  actions: EthAction[];
+  formattingActions?: EthAction[];
+}

package/src/components/utils.tsx

@@ -0,0 +1,88 @@
+import * as React from "react";
+import type { EthAction } from "@echothink-ui/core";
+import {
+  AgentRunningIcon,
+  ApprovalRequiredIcon,
+  DocumentIcon,
+  DownloadIcon,
+  ExternalLinkIcon,
+  SearchIcon,
+  StatusIcon
+} from "@echothink-ui/icons";
+import type { DocumentMode, DocumentReference } from "./types";
+
+export function cx(...classes: Array<string | false | null | undefined>) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export function documentRefLabel(documentRef: DocumentReference) {
+  if (typeof documentRef === "string") return documentRef;
+  if (documentRef.label) return documentRef.label;
+  return documentRef.id;
+}
+
+export function documentRefId(documentRef: DocumentReference) {
+  return typeof documentRef === "string" ? documentRef : documentRef.id;
+}
+
+export function formatDateTime(value?: string) {
+  if (!value) return "Unknown";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short"
+  });
+}
+
+export function modeLabel(mode: DocumentMode) {
+  return mode.charAt(0).toUpperCase() + mode.slice(1);
+}
+
+export function actionIcon(action: EthAction) {
+  const key = `${action.id} ${action.label}`.toLowerCase();
+  if (key.includes("bold"))
+    return (
+      <strong className="eth-doc-toolbar__format-symbol" aria-hidden>
+        B
+      </strong>
+    );
+  if (key.includes("italic"))
+    return (
+      <em className="eth-doc-toolbar__format-symbol" aria-hidden>
+        I
+      </em>
+    );
+  if (key.includes("underline"))
+    return (
+      <span
+        className="eth-doc-toolbar__format-symbol eth-doc-toolbar__format-symbol--underline"
+        aria-hidden
+      >
+        U
+      </span>
+    );
+  if (key.includes("strike"))
+    return (
+      <span
+        className="eth-doc-toolbar__format-symbol eth-doc-toolbar__format-symbol--strike"
+        aria-hidden
+      >
+        S
+      </span>
+    );
+  if (key.includes("code"))
+    return (
+      <span className="eth-doc-toolbar__format-symbol" aria-hidden>
+        {"<>"}
+      </span>
+    );
+  if (key.includes("download") || key.includes("export")) return <DownloadIcon size={16} />;
+  if (key.includes("share") || key.includes("open")) return <ExternalLinkIcon size={16} />;
+  if (key.includes("link") || action.href) return <ExternalLinkIcon size={16} />;
+  if (key.includes("search") || key.includes("find")) return <SearchIcon size={16} />;
+  if (key.includes("agent")) return <AgentRunningIcon size={16} />;
+  if (key.includes("approve") || key.includes("review")) return <ApprovalRequiredIcon size={16} />;
+  if (key.includes("status")) return <StatusIcon size={16} />;
+  return <DocumentIcon size={16} />;
+}

package/src/index.tsx

@@ -0,0 +1,39 @@
+import "./styles.css";
+
+export {
+  DocumentEditorShell,
+  type DocumentEditorShellProps
+} from "./components/DocumentEditorShell";
+export { DocumentViewer, type DocumentViewerProps } from "./components/DocumentViewer";
+export { DocumentToolbar, type DocumentToolbarProps } from "./components/DocumentToolbar";
+export { DocumentOutline, type DocumentOutlineProps } from "./components/DocumentOutline";
+export { DocumentLockBadge, type DocumentLockBadgeProps } from "./components/DocumentLockBadge";
+export {
+  AgentLockedDocumentPanel,
+  type AgentLockedDocumentPanelProps
+} from "./components/AgentLockedDocumentPanel";
+export {
+  DocumentWorkspaceTemplate,
+  type DocumentWorkspaceTemplateProps
+} from "./components/DocumentWorkspaceTemplate";
+export type {
+  DocumentAnnotation,
+  DocumentHeading,
+  DocumentLockState,
+  DocumentMetadataItem,
+  DocumentMode,
+  DocumentOwner,
+  DocumentPendingChange,
+  DocumentReference
+} from "./components/types";
+
+export const DocumentsComponentNames = [
+  "DocumentEditorShell",
+  "DocumentViewer",
+  "DocumentToolbar",
+  "DocumentOutline",
+  "DocumentLockBadge",
+  "AgentLockedDocumentPanel",
+  "DocumentWorkspaceTemplate"
+] as const;
+export type DocumentsComponentName = (typeof DocumentsComponentNames)[number];