@semiont/react-ui 0.5.10 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/react-ui",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -98,9 +98,9 @@
     "@types/react-dom": "^19",
     "@vitest/coverage-v8": "^4.1.8",
     "autoprefixer": "^10.5.2",
-    "fast-check": "^4.8.0",
     "axe-core": "^4.12.1",
     "cssnano": "^8.0.2",
+    "fast-check": "^4.8.0",
     "jest-axe": "^10.0.0",
     "jsdom": "^29.1.1",
     "postcss-import": "^16.1.1",
@@ -122,10 +122,10 @@
     "directory": "packages/react-ui"
   },
   "dependencies": {
-    "@semiont/core": "0.5.10",
-    "@semiont/http-transport": "0.5.10",
-    "@semiont/sdk": "0.5.10",
-    "pdfjs-dist": "^6.0.227",
+    "@semiont/core": "0.5.11",
+    "@semiont/http-transport": "0.5.11",
+    "@semiont/sdk": "0.5.11",
+    "pdfjs-dist": "^6.1.200",
     "react-error-boundary": "^6.1.2",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",

package/src/components/ResourceTagsInline.tsx

@@ -1,34 +1,117 @@
 'use client';
 
+import { useState } from 'react';
+
 interface ResourceTagsInlineProps {
   resourceId: string;
   tags: string[];
   isEditing: boolean;
+  /**
+   * Commit: called ONCE per edit with the FULL new tag set (the host diffs —
+   * its SDK call takes `(current, updated)`). Awaited; the editor renders
+   * inert while the returned promise is pending.
+   */
   onUpdate: (tags: string[]) => Promise<void>;
   disabled?: boolean;
+  /**
+   * The KB's registered entity types — the CONTROLLED VOCABULARY, host-supplied
+   * (the component is session-less; hosts fetch via `browse.entityTypes()`).
+   * Adds are a picker constrained to it: no free-text minting. Without it the
+   * editor is REMOVAL-ONLY (it cannot offer valid candidates). Removal is never
+   * vocabulary-gated — stale/unregistered tags must stay removable.
+   */
+  vocabulary?: string[];
 }
 
 export function ResourceTagsInline({
-  tags
+  tags,
+  isEditing,
+  onUpdate,
+  disabled = false,
+  vocabulary,
 }: ResourceTagsInlineProps) {
-  // If no tags, don't show anything
-  if (tags.length === 0) {
-    return null;
+  const [busy, setBusy] = useState(false);
+  const [picking, setPicking] = useState(false);
+
+  // Browse mode: exactly the historical read-only rendering (null when empty).
+  if (!isEditing) {
+    if (tags.length === 0) {
+      return null;
+    }
+    return (
+      <div className="semiont-resource-tags-inline">
+        <div className="semiont-resource-tags-list">
+          {tags.map((tag) => (
+            <span key={tag} className="semiont-resource-tag">
+              {tag}
+            </span>
+          ))}
+        </div>
+      </div>
+    );
   }
 
+  // Edit mode: the empty strip still renders — tagging an UNTAGGED resource is
+  // the primary case; the null short-circuit is browse-only.
+  const inert = disabled || busy;
+  const candidates = (vocabulary ?? []).filter((v) => !tags.includes(v));
+
+  const commit = async (next: string[]) => {
+    if (inert) return; // in-flight or host-disabled: block further commits
+    setBusy(true);
+    try {
+      await onUpdate(next);
+    } finally {
+      setBusy(false);
+      setPicking(false);
+    }
+  };
+
   return (
-    <div className="semiont-resource-tags-inline">
+    <div className="semiont-resource-tags-inline semiont-resource-tags-inline--editing">
       <div className="semiont-resource-tags-list">
-        {/* Display existing tags */}
         {tags.map((tag) => (
-          <span
-            key={tag}
-            className="semiont-resource-tag"
-          >
+          <span key={tag} className="semiont-resource-tag semiont-resource-tag--editable">
             {tag}
+            <button
+              type="button"
+              className="semiont-resource-tag__remove"
+              aria-label={`Remove ${tag}`}
+              disabled={inert}
+              onClick={() => void commit(tags.filter((t) => t !== tag))}
+            >
+              ✕
+            </button>
           </span>
         ))}
+        {vocabulary && (
+          <button
+            type="button"
+            className="semiont-resource-tag semiont-resource-tag--add"
+            aria-label="Add tag"
+            aria-expanded={picking}
+            disabled={inert || candidates.length === 0}
+            onClick={() => setPicking((v) => !v)}
+          >
+            +
+          </button>
+        )}
       </div>
+      {picking && candidates.length > 0 && (
+        <div className="semiont-form__entity-type-buttons">
+          {candidates.map((entityType) => (
+            <button
+              key={entityType}
+              type="button"
+              className="semiont-form__entity-type-button"
+              disabled={inert}
+              onClick={() => void commit([...tags, entityType])}
+            >
+              {entityType}
+            </button>
+          ))}
+        </div>
+      )}
     </div>
   );
-}
+}

package/src/components/StatusDisplay.css

@@ -209,6 +209,42 @@
   font-size: var(--semiont-font-size-xs);
 }
 
+/* Editing affordances (RESOURCE-TAGS-INLINE-EDITING) */
+.semiont-resource-tag__remove {
+  display: inline-flex;
+  align-items: center;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font-size: var(--semiont-font-size-xs);
+  cursor: pointer;
+  opacity: 0.7;
+}
+
+.semiont-resource-tag__remove:hover:not(:disabled) {
+  opacity: 1;
+}
+
+.semiont-resource-tag__remove:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.semiont-resource-tag--add {
+  cursor: pointer;
+  background: none;
+}
+
+.semiont-resource-tag--add:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.semiont-resource-tags-inline--editing .semiont-form__entity-type-buttons {
+  margin-top: var(--semiont-spacing-xs);
+}
+
 /* Dark mode for ResourceTagsInline - Fixed to respect data-theme attribute */
 [data-theme="dark"] .semiont-resource-tags-inline {
   border-top-color: var(--semiont-color-neutral-700);

package/src/components/__tests__/ResourceTagsInline.test.tsx

@@ -1,9 +1,9 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import { ResourceTagsInline } from '../ResourceTagsInline';
 
 describe('ResourceTagsInline', () => {
-  const mockOnUpdate = vi.fn();
+  const mockOnUpdate = vi.fn(async () => {});
   const defaultProps = {
     resourceId: 'doc-123',
     tags: ['tag1', 'tag2', 'tag3'],
@@ -11,6 +11,11 @@ describe('ResourceTagsInline', () => {
     onUpdate: mockOnUpdate,
   };
 
+  beforeEach(() => {
+    mockOnUpdate.mockClear();
+    mockOnUpdate.mockImplementation(async () => {});
+  });
+
   describe('Rendering', () => {
     it('should render tags', () => {
       render(<ResourceTagsInline {...defaultProps} />);
@@ -177,4 +182,97 @@ describe('ResourceTagsInline', () => {
       expect(container.firstChild).toBeNull();
     });
   });
+
+  // ── RESOURCE-TAGS-INLINE-EDITING: the declared contract, implemented ──
+
+  describe('Editing mode', () => {
+    it('browse mode renders no editing affordances (pins today’s rendering)', () => {
+      const { container } = render(
+        <ResourceTagsInline {...defaultProps} isEditing={false} vocabulary={['Person']} />,
+      );
+      expect(container.querySelector('button')).toBeNull();
+    });
+
+    it('renders the editor for EMPTY tags while editing (the primary tagging case)', () => {
+      const { container } = render(
+        <ResourceTagsInline {...defaultProps} tags={[]} isEditing={true} vocabulary={['Person']} />,
+      );
+      // No null short-circuit in edit mode: the strip renders with an add affordance.
+      expect(container.firstChild).not.toBeNull();
+      expect(screen.getByLabelText('Add tag')).toBeInTheDocument();
+    });
+
+    it('removing a tag commits ONCE with the full new set', async () => {
+      render(<ResourceTagsInline {...defaultProps} isEditing={true} />);
+      fireEvent.click(screen.getByLabelText('Remove tag2'));
+      await waitFor(() => expect(mockOnUpdate).toHaveBeenCalledTimes(1));
+      expect(mockOnUpdate).toHaveBeenCalledWith(['tag1', 'tag3']);
+    });
+
+    it('disabled renders the editor inert', () => {
+      render(
+        <ResourceTagsInline {...defaultProps} isEditing={true} disabled={true} vocabulary={['Person']} />,
+      );
+      fireEvent.click(screen.getByLabelText('Remove tag1'));
+      expect(mockOnUpdate).not.toHaveBeenCalled();
+      expect(screen.getByLabelText('Remove tag1')).toBeDisabled();
+      expect(screen.getByLabelText('Add tag')).toBeDisabled();
+    });
+
+    it('an in-flight onUpdate blocks a second commit', async () => {
+      let resolveUpdate!: () => void;
+      mockOnUpdate.mockImplementation(() => new Promise<void>((r) => { resolveUpdate = r; }));
+      render(<ResourceTagsInline {...defaultProps} isEditing={true} />);
+
+      fireEvent.click(screen.getByLabelText('Remove tag1'));
+      fireEvent.click(screen.getByLabelText('Remove tag2')); // while pending — must not fire
+      expect(mockOnUpdate).toHaveBeenCalledTimes(1);
+
+      resolveUpdate();
+      await waitFor(() => expect(screen.getByLabelText('Remove tag2')).not.toBeDisabled());
+      fireEvent.click(screen.getByLabelText('Remove tag2')); // settled — fires again
+      expect(mockOnUpdate).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Vocabulary (controlled — adds are a picker, never free text)', () => {
+    it('the add affordance offers ONLY vocabulary entries minus already-applied tags', () => {
+      render(
+        <ResourceTagsInline {...defaultProps} tags={['Person']} isEditing={true}
+          vocabulary={['Person', 'Place', 'Topic']} />,
+      );
+      fireEvent.click(screen.getByLabelText('Add tag'));
+      expect(screen.getByRole('button', { name: 'Place' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Topic' })).toBeInTheDocument();
+      // Already applied → not a candidate (the chip renders as text, not a candidate button)
+      expect(screen.queryByRole('button', { name: 'Person' })).not.toBeInTheDocument();
+    });
+
+    it('picking a candidate commits the full set including the added tag', async () => {
+      render(
+        <ResourceTagsInline {...defaultProps} tags={['Person']} isEditing={true}
+          vocabulary={['Person', 'Place']} />,
+      );
+      fireEvent.click(screen.getByLabelText('Add tag'));
+      fireEvent.click(screen.getByRole('button', { name: 'Place' }));
+      await waitFor(() => expect(mockOnUpdate).toHaveBeenCalledTimes(1));
+      expect(mockOnUpdate).toHaveBeenCalledWith(['Person', 'Place']);
+    });
+
+    it('without a vocabulary the editor is REMOVAL-ONLY (no add affordance)', () => {
+      render(<ResourceTagsInline {...defaultProps} isEditing={true} />);
+      expect(screen.queryByLabelText('Add tag')).not.toBeInTheDocument();
+      expect(screen.getByLabelText('Remove tag1')).toBeInTheDocument();
+    });
+
+    it('removal is never vocabulary-gated — a stale tag not in the vocabulary is removable', async () => {
+      render(
+        <ResourceTagsInline {...defaultProps} tags={['LegacyType', 'Person']} isEditing={true}
+          vocabulary={['Person']} />,
+      );
+      fireEvent.click(screen.getByLabelText('Remove LegacyType'));
+      await waitFor(() => expect(mockOnUpdate).toHaveBeenCalledTimes(1));
+      expect(mockOnUpdate).toHaveBeenCalledWith(['Person']);
+    });
+  });
 });

package/src/components/annotation/AnnotateToolbar.tsx

@@ -2,8 +2,6 @@
 
 import React, { useState, useRef, useEffect } from 'react';
 import { useTranslations } from '../../contexts/TranslationContext';
-import { useSemiont } from '../../session/SemiontProvider';
-import { useObservable } from '../../hooks/useObservable';
 import { getSupportedShapes } from '../../lib/media-shapes';
 import type { Annotator } from '../../lib/annotation-registry';
 import './annotations.css';
@@ -14,12 +12,13 @@ export type SelectionMotivation = 'linking' | 'highlighting' | 'assessing' | 'co
 export type ClickAction = 'detail' | 'follow' | 'jsonld' | 'deleting';
 export type ShapeType = 'rectangle' | 'circle' | 'polygon';
 
+/** The bar's composable controls, in fixed render order. */
+export type ToolbarPart = 'clickAction' | 'mode' | 'selection' | 'shape';
+
 interface AnnotateToolbarProps {
   selectedMotivation: SelectionMotivation | null;
   selectedClick: ClickAction;
-  showSelectionGroup?: boolean;
   showDeleteButton?: boolean;
-  showShapeGroup?: boolean;
   selectedShape?: ShapeType;
   mediaType?: string | null;  // MIME type to determine supported shapes
 
@@ -28,6 +27,26 @@ interface AnnotateToolbarProps {
 
   // Annotators for emoji lookup
   annotators: Record<string, Annotator>;
+
+  /**
+   * Which controls to render (composition over CSS hiding). Default: all four.
+   * Order is fixed (click, mode, selection, shape); shape stays media-gated.
+   */
+  parts?: ToolbarPart[];
+
+  /**
+   * Purely presentational: each control reports the chosen value via its
+   * callback; the owner (viewer instance or host) applies it. The bar holds no
+   * pref state, emits no bus events, and touches no storage.
+   */
+  onModeChange?: (mode: boolean) => void;
+  onClickActionChange?: (action: ClickAction) => void;
+  onSelectionChange?: (motivation: SelectionMotivation | null) => void;
+  onShapeChange?: (shape: ShapeType) => void;
+
+  // Compact display form (display-only): icon-only, tight, chromeless — for inline
+  // embeds. The bar's functionality is identical; only its form changes.
+  compact?: boolean;
 }
 
 interface DropdownGroupProps {
@@ -101,26 +120,26 @@ function DropdownGroup({
 }
 
 /**
- * Toolbar for annotation controls with mode, selection, click, and shape options
- *
- * @emits mark:selection-changed - Selection motivation changed. Payload: { motivation: SelectionMotivation | null }
- * @emits mark:click-changed - Click action mode changed. Payload: { action: ClickAction }
- * @emits mark:shape-changed - Drawing shape changed. Payload: { shape: ShapeType }
- * @emits mark:mode-toggled - View mode toggled between browse and annotate. Payload: undefined
+ * Toolbar for annotation controls with mode, selection, click, and shape options.
+ * Purely presentational (TOOLBAR-PREFS-AS-PROPS): renders the given values for the
+ * given `parts` and reports choices via the on*Change callbacks — no bus, no storage.
  */
 export function AnnotateToolbar({
   selectedMotivation,
   selectedClick,
-  showSelectionGroup = true,
   showDeleteButton = true,
-  showShapeGroup = false,
   selectedShape = 'rectangle',
   mediaType,
   annotateMode = false,
-  annotators
+  annotators,
+  parts = ['clickAction', 'mode', 'selection', 'shape'],
+  onModeChange,
+  onClickActionChange,
+  onSelectionChange,
+  onShapeChange,
+  compact = false,
 }: AnnotateToolbarProps) {
   const t = useTranslations('AnnotateToolbar');
-  const session = useObservable(useSemiont().activeSession$);
 
   // Helper to get emoji from annotators by motivation (with fallback for safety)
   const getMotivationEmoji = (motivation: SelectionMotivation): string => {
@@ -188,32 +207,28 @@ export function AnnotateToolbar({
 
   const handleSelectionClick = (motivation: SelectionMotivation | null) => {
     // If null is clicked, always deselect. Otherwise toggle.
-    if (motivation === null) {
-      session?.client.mark.changeSelection(null);
-    } else {
-      session?.client.mark.changeSelection(selectedMotivation === motivation ? null : motivation);
-    }
+    onSelectionChange?.(motivation === null ? null : (selectedMotivation === motivation ? null : motivation));
     // Close dropdown after selection
     setSelectionPinned(false);
     setSelectionHovered(false);
   };
 
   const handleClickClick = (action: ClickAction) => {
-    session?.client.mark.changeClick(action);
+    onClickActionChange?.(action);
     // Close dropdown after selection
     setClickPinned(false);
     setClickHovered(false);
   };
 
   const handleShapeClick = (shape: ShapeType) => {
-    session?.client.mark.changeShape(shape);
+    onShapeChange?.(shape);
     // Close dropdown after selection
     setShapePinned(false);
     setShapeHovered(false);
   };
 
   const handleModeToggle = () => {
-    session?.client.mark.toggleMode();
+    onModeChange?.(!annotateMode);
     setModePinned(false);
     setModeHovered(false);
   };
@@ -288,9 +303,16 @@ export function AnnotateToolbar({
   const supportedShapes = getSupportedShapes(mediaType);
   const shapeTypes = allShapeTypes.filter(st => supportedShapes.includes(st.shape));
 
+  // Part gates (fixed order: click, mode, selection, shape); shape stays media-gated.
+  const showClick = parts.includes('clickAction');
+  const showMode = parts.includes('mode');
+  const showSelection = parts.includes('selection');
+  const showShape = parts.includes('shape') && shapeTypes.length > 0;
+
   return (
-    <div className="semiont-annotate-toolbar">
+    <div className={`semiont-annotate-toolbar${compact ? ' semiont-annotate-toolbar--compact' : ''}`}>
       {/* Click Group */}
+      {showClick && (
       <DropdownGroup
         label={t('clickGroup')}
         isExpanded={clickExpanded}
@@ -320,11 +342,13 @@ export function AnnotateToolbar({
           </>
         }
       />
+      )}
 
       {/* Separator */}
-      <div className="semiont-toolbar-separator" />
+      {showMode && showClick && <div className="semiont-toolbar-separator" />}
 
       {/* Mode Group */}
+      {showMode && (
       <DropdownGroup
         label={t('modeGroup')}
         isExpanded={modeExpanded}
@@ -346,12 +370,13 @@ export function AnnotateToolbar({
           </>
         }
       />
+      )}
 
       {/* Separator */}
-      {showSelectionGroup && <div className="semiont-toolbar-separator" />}
+      {showSelection && (showClick || showMode) && <div className="semiont-toolbar-separator" />}
 
       {/* Selection Group */}
-      {showSelectionGroup && (
+      {showSelection && (
         <DropdownGroup
           label={t('selectionGroup')}
           isExpanded={selectionExpanded}
@@ -394,10 +419,10 @@ export function AnnotateToolbar({
       )}
 
       {/* Separator */}
-      {showShapeGroup && <div className="semiont-toolbar-separator" />}
+      {showShape && (showClick || showMode || showSelection) && <div className="semiont-toolbar-separator" />}
 
       {/* Shape Group */}
-      {showShapeGroup && shapeTypes.length > 0 && (
+      {showShape && (
         <DropdownGroup
           label={t('shapeGroup')}
           isExpanded={shapeExpanded}

package/src/components/annotation/__tests__/AnnotateToolbar.display.test.tsx

@@ -0,0 +1,76 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 3 — Annotate Bar display forms.
+ *
+ * Behavior is mostly fixed (the bar IS the annotation capability); the host
+ * gets freedom over its display form. `compact` is a display-only variant:
+ * icon-only, tight, chromeless — the functional groups stay present and wired.
+ * BrowseView's `inline` embed shows the compact bar automatically. Theming
+ * (semiont-* classes + CSS vars) and labels (i18n) already exist — no new API
+ * for those.
+ *
+ * Started RED (no `compact` prop) and GREEN once Phase 3 lands.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { SemiontSession } from '@semiont/sdk';
+import { AnnotateToolbar } from '../AnnotateToolbar';
+import { ANNOTATORS } from '../../../lib/annotation-registry';
+import { BrowseView } from '../../resource/BrowseView';
+
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+const toolbarProps = {
+  selectedMotivation: null,
+  selectedClick: 'detail' as const,
+  annotateMode: false,
+  annotators: ANNOTATORS,
+  session: null,
+};
+
+describe('Annotate Bar display forms (Phase 3)', () => {
+  it('`compact` adds the display modifier; default does not', () => {
+    const { container: normal } = render(<AnnotateToolbar {...toolbarProps} />);
+    expect(normal.querySelector('.semiont-annotate-toolbar')).not.toHaveClass('semiont-annotate-toolbar--compact');
+
+    const { container } = render(<AnnotateToolbar {...toolbarProps} compact />);
+    expect(container.querySelector('.semiont-annotate-toolbar')).toHaveClass('semiont-annotate-toolbar--compact');
+  });
+
+  it('compact is display-only: the functional groups are still present', () => {
+    render(<AnnotateToolbar {...toolbarProps} compact />);
+    // Groups render with their aria labels (default-English translations, no provider).
+    expect(screen.getByLabelText(/mode/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/click/i)).toBeInTheDocument();
+  });
+
+  it('BrowseView inline embeds show the compact bar automatically', () => {
+    const props = {
+      content: 'x', mimeType: 'text/plain', resourceUri: 'res-1',
+      annotations: emptyAnnotations, annotateMode: false, session: fakeSession(),
+    };
+    const { container: pane } = render(<BrowseView {...props} />);
+    expect(pane.querySelector('.semiont-annotate-toolbar')).not.toHaveClass('semiont-annotate-toolbar--compact');
+
+    const { container } = render(<BrowseView {...props} inline />);
+    expect(container.querySelector('.semiont-annotate-toolbar')).toHaveClass('semiont-annotate-toolbar--compact');
+  });
+
+  it('stylesheet carries the compact form (static gate — icon-only, chromeless)', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/toolbar/Toolbar.css'), 'utf8');
+    expect(css).toMatch(/\.semiont-annotate-toolbar--compact\s*\{/);
+    expect(css).toMatch(/\.semiont-annotate-toolbar--compact\s+\.semiont-dropdown-label\s*\{[^}]*display:\s*none/);
+  });
+});