@semiont/react-ui 0.5.0 → 0.5.2

package/src/features/resource-compose/__tests__/UploadProgressBar.test.tsx

@@ -0,0 +1,225 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { UploadProgress } from '@semiont/sdk';
+import type { ResourceId } from '@semiont/core';
+import { UploadProgressBar } from '../components/UploadProgressBar';
+
+describe('UploadProgressBar', () => {
+  describe('null progress', () => {
+    it('renders nothing when progress is null', () => {
+      const { container } = render(<UploadProgressBar progress={null} />);
+      expect(container.firstChild).toBeNull();
+    });
+  });
+
+  describe('phase: started', () => {
+    const started: UploadProgress = { phase: 'started', totalBytes: 1024 };
+
+    it('shows the starting label with default "Upload" prefix', () => {
+      render(<UploadProgressBar progress={started} />);
+      expect(screen.getByText('Upload: starting…')).toBeInTheDocument();
+    });
+
+    it('uses a custom label when provided', () => {
+      render(<UploadProgressBar progress={started} label="Image" />);
+      expect(screen.getByText('Image: starting…')).toBeInTheDocument();
+    });
+
+    it('renders an indeterminate bar (no role=progressbar in this phase)', () => {
+      const { container } = render(<UploadProgressBar progress={started} />);
+      expect(screen.getByRole('status')).toBeInTheDocument();
+      expect(screen.queryByRole('progressbar')).not.toBeInTheDocument();
+      expect(container.querySelector('.semiont-progress--indeterminate')).not.toBeNull();
+    });
+
+    it('marks the live region polite for assistive tech', () => {
+      render(<UploadProgressBar progress={started} />);
+      const status = screen.getByRole('status');
+      expect(status).toHaveAttribute('aria-live', 'polite');
+    });
+  });
+
+  describe('phase: progress (determinate)', () => {
+    it('renders percentage and byte counts when totalBytes is known', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 512,
+        totalBytes: 2048,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      expect(screen.getByText('Upload: 25%')).toBeInTheDocument();
+      expect(screen.getByText('512 B / 2.0 KB')).toBeInTheDocument();
+    });
+
+    it('rounds percentage to nearest integer', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 333,
+        totalBytes: 1000,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      // 333/1000 = 33.3% → rounds to 33
+      expect(screen.getByText('Upload: 33%')).toBeInTheDocument();
+    });
+
+    it('caps percentage at 100 when bytesUploaded exceeds totalBytes', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 5000,
+        totalBytes: 1000,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      expect(screen.getByText('Upload: 100%')).toBeInTheDocument();
+      const bar = screen.getByRole('progressbar');
+      expect(bar).toHaveAttribute('aria-valuenow', '100');
+    });
+
+    it('exposes ARIA progressbar attributes for determinate progress', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 500,
+        totalBytes: 1000,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      const bar = screen.getByRole('progressbar');
+      expect(bar).toHaveAttribute('aria-valuemin', '0');
+      expect(bar).toHaveAttribute('aria-valuemax', '100');
+      expect(bar).toHaveAttribute('aria-valuenow', '50');
+    });
+
+    it('sets the fill width inline style to the percentage', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 750,
+        totalBytes: 1000,
+      };
+      const { container } = render(<UploadProgressBar progress={progress} />);
+      const fill = container.querySelector('.semiont-progress__fill') as HTMLElement;
+      expect(fill).not.toBeNull();
+      expect(fill.style.width).toBe('75%');
+    });
+
+    it('does not apply the indeterminate class when totalBytes is known', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 100,
+        totalBytes: 1000,
+      };
+      const { container } = render(<UploadProgressBar progress={progress} />);
+      expect(container.querySelector('.semiont-progress--indeterminate')).toBeNull();
+    });
+
+    it('uses the custom label in determinate mode', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 100,
+        totalBytes: 1000,
+      };
+      render(<UploadProgressBar progress={progress} label="Avatar" />);
+      expect(screen.getByText('Avatar: 10%')).toBeInTheDocument();
+    });
+  });
+
+  describe('phase: progress (indeterminate)', () => {
+    it('renders bytesUploaded only when totalBytes is 0', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 4096,
+        totalBytes: 0,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      expect(screen.getByText('Upload: 4.0 KB…')).toBeInTheDocument();
+      expect(screen.queryByText(/%/)).not.toBeInTheDocument();
+    });
+
+    it('renders bytesUploaded only when totalBytes is negative', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 1234,
+        totalBytes: -1,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      expect(screen.getByText('Upload: 1.2 KB…')).toBeInTheDocument();
+    });
+
+    it('omits aria-valuemax and aria-valuenow in indeterminate mode', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 100,
+        totalBytes: 0,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      const bar = screen.getByRole('progressbar');
+      expect(bar).toHaveAttribute('aria-valuemin', '0');
+      expect(bar).not.toHaveAttribute('aria-valuemax');
+      expect(bar).not.toHaveAttribute('aria-valuenow');
+    });
+
+    it('applies the indeterminate class and omits inline width', () => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: 100,
+        totalBytes: 0,
+      };
+      const { container } = render(<UploadProgressBar progress={progress} />);
+      expect(container.querySelector('.semiont-progress--indeterminate')).not.toBeNull();
+      const fill = container.querySelector('.semiont-progress__fill') as HTMLElement;
+      expect(fill.style.width).toBe('');
+    });
+  });
+
+  describe('phase: finished', () => {
+    const finished: UploadProgress = {
+      phase: 'finished',
+      resourceId: 'res-1' as ResourceId,
+    };
+
+    it('renders an "uploaded" label', () => {
+      render(<UploadProgressBar progress={finished} />);
+      expect(screen.getByText('Upload: uploaded')).toBeInTheDocument();
+    });
+
+    it('uses a custom label in the finished state', () => {
+      render(<UploadProgressBar progress={finished} label="Image" />);
+      expect(screen.getByText('Image: uploaded')).toBeInTheDocument();
+    });
+
+    it('reports 100% on the progressbar', () => {
+      render(<UploadProgressBar progress={finished} />);
+      const bar = screen.getByRole('progressbar');
+      expect(bar).toHaveAttribute('aria-valuemin', '0');
+      expect(bar).toHaveAttribute('aria-valuemax', '100');
+      expect(bar).toHaveAttribute('aria-valuenow', '100');
+    });
+
+    it('applies the success fill modifier and full width', () => {
+      const { container } = render(<UploadProgressBar progress={finished} />);
+      const fill = container.querySelector('.semiont-progress__fill--success') as HTMLElement;
+      expect(fill).not.toBeNull();
+      expect(fill.style.width).toBe('100%');
+    });
+  });
+
+  describe('byte formatting', () => {
+    // Exercises formatBytes() at every threshold via the visible label.
+    it.each([
+      [0, '0 B'],
+      [1023, '1023 B'],
+      [1024, '1.0 KB'],
+      [1024 * 1024 - 1, '1024.0 KB'],
+      [1024 * 1024, '1.0 MB'],
+      [1024 * 1024 * 1024 - 1, '1024.0 MB'],
+      [1024 * 1024 * 1024, '1.00 GB'],
+      [5 * 1024 * 1024 * 1024, '5.00 GB'],
+    ])('formats %i bytes as "%s"', (bytes, expected) => {
+      const progress: UploadProgress = {
+        phase: 'progress',
+        bytesUploaded: bytes,
+        totalBytes: 0,
+      };
+      render(<UploadProgressBar progress={progress} />);
+      expect(screen.getByText(`Upload: ${expected}…`)).toBeInTheDocument();
+    });
+  });
+});

package/src/features/resource-compose/components/ResourceComposePage.tsx

@@ -9,11 +9,13 @@
 import React, { useState, useEffect } from 'react';
 import type { GatheredContext } from '@semiont/core';
 import { isImageMimeType, isPdfMimeType, LOCALES } from '@semiont/core';
-import { type CloneData, type ReferenceData } from '@semiont/sdk';
-import { COMMON_PANELS, type ToolbarPanelType } from '@semiont/sdk';
+import type { UploadProgress } from '@semiont/sdk';
+import { type CloneData, type ReferenceData } from '../state/compose-page-state-unit';
+import { COMMON_PANELS, type ToolbarPanelType } from '../../../state/shell-state-unit';
 import { buttonStyles } from '../../../lib/button-styles';
 import { CodeMirrorRenderer } from '../../../components/CodeMirrorRenderer';
 import { useFormAnnouncements } from '../../../components/LiveRegion';
+import { UploadProgressBar } from './UploadProgressBar';
 
 export interface ResourceComposePageProps {
   mode: 'new' | 'clone' | 'reference';
@@ -37,6 +39,14 @@ export interface ResourceComposePageProps {
   onSaveResource: (params: SaveResourceParams) => Promise<void>;
   onCancel: () => void;
 
+  /**
+   * Live upload-progress for the in-flight save. Resolved by the route
+   * shell from `composeVM.uploadProgress$`. `null` between saves and
+   * after completion. When non-null, the form disables Save and the
+   * inline `<UploadProgressBar />` below the action buttons renders.
+   */
+  uploadProgress?: UploadProgress | null;
+
   // Translations
   translations: {
     title: string;
@@ -105,6 +115,7 @@ export function ResourceComposePage({
   activePanel,
   onSaveResource,
   onCancel,
+  uploadProgress = null,
   translations: t,
   ToolbarPanels,
   Toolbar,
@@ -655,14 +666,14 @@ export function ResourceComposePage({
             <button
               type="button"
               onClick={onCancel}
-              disabled={isCreating}
+              disabled={isCreating || uploadProgress !== null}
               className={buttonStyles.tertiary.base}
             >
               {t.cancel}
             </button>
             <button
               type="submit"
-              disabled={isCreating || !newResourceName.trim()}
+              disabled={isCreating || uploadProgress !== null || !newResourceName.trim()}
               className={buttonStyles.primary.base}
             >
               {isCreating
@@ -670,6 +681,10 @@ export function ResourceComposePage({
                 : (isClone ? t.saveClonedResource : isReferenceCompletion ? t.createAndLinkResource : t.createResource)}
             </button>
           </div>
+
+          {/* Inline upload progress — renders below the action buttons while
+              an upload is in flight. `null` between saves and after completion. */}
+          <UploadProgressBar progress={uploadProgress} />
         </form>
       </div>
       </div>

package/src/features/resource-compose/components/UploadProgressBar.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+/**
+ * Inline upload-progress affordance for the compose page.
+ *
+ * Subscribes (via prop) to a `UploadProgress | null` value derived from
+ * `composeVM.uploadProgress$`. Renders nothing when null; renders an
+ * indeterminate state on `started`; renders a labeled bar with byte
+ * counts on `progress`; renders a brief "Uploaded" success state on
+ * `finished` (cleared by the state unit's `null` push on complete).
+ *
+ * Designed to live below the Save button in the compose form so the
+ * visual association with the action that triggered the upload is
+ * direct. Uses the existing `.semiont-progress` styles in
+ * `packages/react-ui/src/styles/core/progress.css`.
+ */
+
+import React from 'react';
+import type { UploadProgress } from '@semiont/sdk';
+
+export interface UploadProgressBarProps {
+  progress: UploadProgress | null;
+  /** Optional label for the "starting" / "uploaded" lines. Defaults to "Upload". */
+  label?: string;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+export function UploadProgressBar({ progress, label = 'Upload' }: UploadProgressBarProps): React.ReactElement | null {
+  if (!progress) return null;
+
+  if (progress.phase === 'started') {
+    return (
+      <div className="semiont-progress-wrapper" role="status" aria-live="polite">
+        <div className="semiont-progress__label">
+          <span>{label}: starting…</span>
+        </div>
+        <div className="semiont-progress semiont-progress--indeterminate">
+          <div className="semiont-progress__fill" />
+        </div>
+      </div>
+    );
+  }
+
+  if (progress.phase === 'progress') {
+    const indeterminate = progress.totalBytes <= 0;
+    const percentage = indeterminate
+      ? 0
+      : Math.min(100, Math.round((progress.bytesUploaded / progress.totalBytes) * 100));
+    return (
+      <div className="semiont-progress-wrapper" role="status" aria-live="polite">
+        <div className="semiont-progress__label">
+          {indeterminate ? (
+            <span>{label}: {formatBytes(progress.bytesUploaded)}…</span>
+          ) : (
+            <>
+              <span>{label}: {percentage}%</span>
+              <span>{formatBytes(progress.bytesUploaded)} / {formatBytes(progress.totalBytes)}</span>
+            </>
+          )}
+        </div>
+        <div
+          className={`semiont-progress${indeterminate ? ' semiont-progress--indeterminate' : ''}`}
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={indeterminate ? undefined : 100}
+          aria-valuenow={indeterminate ? undefined : percentage}
+        >
+          <div
+            className="semiont-progress__fill"
+            style={indeterminate ? undefined : { width: `${percentage}%` }}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  // phase === 'finished'
+  return (
+    <div className="semiont-progress-wrapper" role="status" aria-live="polite">
+      <div className="semiont-progress__label">
+        <span>{label}: uploaded</span>
+      </div>
+      <div className="semiont-progress" role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={100}>
+        <div className="semiont-progress__fill semiont-progress__fill--success" style={{ width: '100%' }} />
+      </div>
+    </div>
+  );
+}

package/src/features/resource-compose/state/__tests__/compose-page-state-unit.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from 'vitest';
+import { BehaviorSubject, Observable, firstValueFrom } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import type { SemiontClient } from '@semiont/sdk';
+import type { ShellStateUnit } from '../../../../state/shell-state-unit';
+import { createComposePageStateUnit } from '../compose-page-state-unit';
+
+/** Build an `UploadObservable`-shaped mock that emits started → finished. */
+function mockUpload(resourceId: string) {
+  return vi.fn().mockReturnValue(
+    new Observable((subscriber) => {
+      subscriber.next({ phase: 'started', totalBytes: 100 });
+      subscriber.next({ phase: 'finished', resourceId });
+      subscriber.complete();
+    }),
+  );
+}
+
+function mockBrowse(): ShellStateUnit {
+  return { dispose: vi.fn() } as unknown as ShellStateUnit;
+}
+
+function mockClient(overrides: {
+  entityTypes$?: BehaviorSubject<string[] | undefined>;
+  fromToken?: ReturnType<typeof vi.fn>;
+  getResourceRepresentation?: ReturnType<typeof vi.fn>;
+  createFromToken?: ReturnType<typeof vi.fn>;
+  resource?: ReturnType<typeof vi.fn>;
+  body?: ReturnType<typeof vi.fn>;
+} = {}): SemiontClient {
+  const entityTypes$ = overrides.entityTypes$ ?? new BehaviorSubject<string[] | undefined>(['Person']);
+  return {
+    browse: {
+      entityTypes: () => entityTypes$.asObservable(),
+    },
+    yield: {
+      fromToken: overrides.fromToken ?? vi.fn().mockResolvedValue({ '@id': 'src-1', representations: [{ mediaType: 'text/plain' }] }),
+      createFromToken: overrides.createFromToken ?? vi.fn().mockResolvedValue({ resourceId: 'new-1' }),
+      resource: overrides.resource ?? mockUpload('new-2'),
+    },
+    bind: {
+      body: overrides.body ?? vi.fn().mockResolvedValue(undefined),
+    },
+    getResourceRepresentation: overrides.getResourceRepresentation ?? vi.fn().mockResolvedValue({
+      data: new TextEncoder().encode('source content').buffer,
+      contentType: 'text/plain',
+    }),
+  } as unknown as SemiontClient;
+}
+
+describe('createComposePageStateUnit', () => {
+  it('defaults to "new" mode', async () => {
+    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {});
+
+    const mode = await firstValueFrom(stateUnit.mode$);
+    expect(mode).toBe('new');
+
+    const loading = await firstValueFrom(stateUnit.loading$.pipe(filter((l) => !l)));
+    expect(loading).toBe(false);
+
+    stateUnit.dispose();
+  });
+
+  it('detects reference mode from params', async () => {
+    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+      annotationUri: 'ann-1',
+      sourceDocumentId: 'doc-1',
+      name: 'Reference Doc',
+      entityTypes: 'Person,Place',
+    });
+
+    const mode = await firstValueFrom(stateUnit.mode$);
+    expect(mode).toBe('reference');
+
+    const ref = await firstValueFrom(stateUnit.referenceData$.pipe(filter((r) => r !== null)));
+    expect(ref!.annotationUri).toBe('ann-1');
+    expect(ref!.entityTypes).toEqual(['Person', 'Place']);
+
+    stateUnit.dispose();
+  });
+
+  it('parses storedContext in reference mode', async () => {
+    const context = { annotation: { id: 'ann-1' }, sourceContext: 'text' };
+    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+      annotationUri: 'ann-1',
+      sourceDocumentId: 'doc-1',
+      name: 'Ref',
+      storedContext: JSON.stringify(context),
+    });
+
+    const gathered = await firstValueFrom(stateUnit.gatheredContext$.pipe(filter((g) => g !== null)));
+    expect(gathered).toEqual(context);
+
+    stateUnit.dispose();
+  });
+
+  it('ignores malformed storedContext', async () => {
+    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+      annotationUri: 'ann-1',
+      sourceDocumentId: 'doc-1',
+      name: 'Ref',
+      storedContext: 'not-json{{{',
+    });
+
+    const loading = await firstValueFrom(stateUnit.loading$.pipe(filter((l) => !l)));
+    expect(loading).toBe(false);
+
+    const gathered = await firstValueFrom(stateUnit.gatheredContext$);
+    expect(gathered).toBeNull();
+
+    stateUnit.dispose();
+  });
+
+  it('exposes entity types', async () => {
+    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {});
+
+    const types = await firstValueFrom(stateUnit.entityTypes$);
+    expect(types).toEqual(['Person']);
+
+    stateUnit.dispose();
+  });
+
+  it('save in new mode calls yield.resource', async () => {
+    const resource = mockUpload('new-3');
+    const stateUnit = createComposePageStateUnit(mockClient({ resource }), mockBrowse(), {});
+
+    const id = await stateUnit.save({
+      mode: 'new',
+      name: 'Test',
+      storageUri: '/docs/test.md',
+      content: '# Hello',
+      format: 'text/markdown',
+      language: 'en',
+    });
+
+    expect(id).toBe('new-3');
+    expect(resource).toHaveBeenCalledOnce();
+
+    stateUnit.dispose();
+  });
+
+  it('save in reference mode calls yield.resource then bind.body', async () => {
+    const resource = mockUpload('new-4');
+    const body = vi.fn().mockResolvedValue(undefined);
+    const stateUnit = createComposePageStateUnit(mockClient({ resource, body }), mockBrowse(), {
+      annotationUri: 'ann-1',
+      sourceDocumentId: 'doc-1',
+      name: 'Ref',
+    });
+
+    const id = await stateUnit.save({
+      mode: 'reference',
+      name: 'Ref Doc',
+      storageUri: '/docs/ref.md',
+      content: 'content',
+      language: 'en',
+      annotationUri: 'ann-1',
+      sourceDocumentId: 'doc-1',
+    });
+
+    expect(id).toBe('new-4');
+    expect(body).toHaveBeenCalledOnce();
+
+    stateUnit.dispose();
+  });
+
+  it('save in clone mode calls yield.createFromToken', async () => {
+    const createFromToken = vi.fn().mockResolvedValue({ resourceId: 'cloned-1' });
+    const stateUnit = createComposePageStateUnit(mockClient({ createFromToken }), mockBrowse(), {
+      mode: 'clone',
+      token: 'tok-abc',
+    });
+
+    const id = await stateUnit.save({
+      mode: 'clone',
+      name: 'Cloned',
+      storageUri: '/docs/cloned.md',
+      content: 'cloned content',
+      language: 'en',
+    });
+
+    expect(id).toBe('cloned-1');
+    expect(createFromToken).toHaveBeenCalledOnce();
+
+    stateUnit.dispose();
+  });
+});