Package Exports

@miethe/ui
@miethe/ui/bulk-actions
@miethe/ui/content-viewer
@miethe/ui/diff
@miethe/ui/display
@miethe/ui/editor
@miethe/ui/filters
@miethe/ui/pickers
@miethe/ui/primitives
@miethe/ui/utils

Readme

@miethe/ui

A collection of reusable React components for viewing, editing, and navigating file content. Provides an adapter abstraction pattern that decouples components from any specific backend API, allowing flexible integration with custom data sources.

Overview

This package (formerly @skillmeat/content-viewer) was extracted from the SkillMeat web application during a UI refactoring effort. It provides production-ready components for:

Content Viewing & Editing

File tree browser — Hierarchical navigation with keyboard support
File content viewer — Display files with markdown editing and split preview
Diff viewer — Side-by-side unified diff display with conflict resolution
File preview pane — Quick file preview with markdown rendering and tier badges
Frontmatter display — Collapsible YAML frontmatter viewer
Markdown editor — CodeMirror-based editor with live preview

Tab registry — Declarative tab configuration with entity type / edition / lens / feature-flag gating
Metadata grid — Key-value metadata display with collapsible sections
Timeline view — Ordered history or event timeline rendering

Artifact Type Visualization (Tiered Card System)

Type-aware badges — ColoredBadge and TypeIndicator with color mapping
Tag color provider — Context-based type-to-color mapping
Type-color utilities — Artifact/entity type to Tailwind color class resolution

Filtering & Operations

Filter components — Tag/Tool filter popovers, Filters dropdown with AND/OR toggle, Sort dropdown
Utilities — Frontmatter parsing, README extraction, type-color resolution, and more

The package uses an adapter pattern to remain backend-agnostic. You implement a simple ContentViewerAdapter interface and connect your own data-fetching hooks, making the components reusable across different APIs and applications.

Installation

From GitHub Packages (published package)

@miethe/ui is published to GitHub Packages at npm.pkg.github.com. Consuming it requires a GitHub token with read:packages scope.

Step 1 — Configure the registry in .npmrc at your project root:

@miethe:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Set the GITHUB_TOKEN environment variable to a personal access token with read:packages scope. Do not hard-code the token in .npmrc — use the env var reference as shown.

Step 2 — Install:

npm install @miethe/ui@0.1.0
# or
pnpm add @miethe/ui@0.1.0

Within the SkillMeat monorepo (workspace)

pnpm add @miethe/ui --filter your-package

Or reference the workspace package directly in package.json:

{
  "dependencies": {
    "@miethe/ui": "workspace:*"
  }
}

Subpath Imports

The package is organized into seven submodules with tree-shakeable exports:

// Content viewer components
import { FileTree, ContentPane, ContentViewerProvider } from '@miethe/ui/content-viewer';

// Diff viewing components
import { DiffViewer, DiffViewerSkeleton } from '@miethe/ui/diff';

// Editor components
import { MarkdownEditor, SplitPreview } from '@miethe/ui/editor';

// Display components
import { FrontmatterDisplay, FilePreviewPane } from '@miethe/ui/display';

// Filter components
import {
  TagFilterPopover, TagFilterBar,
  ToolFilterPopover, ToolFilterBar,
  FiltersDropdown,
  SortDropdown,
} from '@miethe/ui/filters';

// Bulk action toolbar
import { BulkActionBar } from '@miethe/ui/bulk-actions';
import type { BulkActionBarProps, BulkAction } from '@miethe/ui/bulk-actions';

// UI primitives
import { BaseArtifactModal, ModalHeader, TabNavigation, EnterpriseOwnerBadge, LockIcon } from '@miethe/ui/primitives';

// Tab registry system (consolidated modals)
import { TabRegistry, getTabsForContext, type TabConfig, type TabConditions } from '@miethe/ui/tab-registry';

// Metadata & timeline (Phase 3 extractions)
import { MetadataGrid, TimelineView } from '@miethe/ui/components';

// Card system (type-aware badges & indicators)
import { TagColorProvider, ColoredBadge, TypeIndicator } from '@miethe/ui/card-system';

// Utilities
import { parseFrontmatter, stripFrontmatter, extractFirstParagraph, getTypeBarColor, getCardTint, artifactTypeCardTints } from '@miethe/ui/utils';

Prerequisites

Tailwind CSS

Components use Tailwind CSS utility classes for all styling. Your build pipeline must have tailwindcss configured:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@miethe/ui/dist/**/*.js',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Important: Without Tailwind CSS configured, components will render with no styles. Components use semantic Tailwind classes like text-muted-foreground and bg-background — ensure your Tailwind config includes these classes (standard in shadcn/ui projects).

Dark Mode

Components support dark mode via the Tailwind dark: variant. Enable dark mode in your Tailwind config:

// tailwind.config.js
module.exports = {
  darkMode: 'class', // Enable dark mode with class strategy
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@miethe/ui/dist/**/*.js',
  ],
  // ... rest of config
};

Then add the dark class to your root HTML element to activate dark mode styles:

<!-- Dark mode enabled -->
<html class="dark">
  <body>...</body>
</html>

Or use a theme provider component that toggles the class dynamically based on user preference.

Quick Start

1. Create an Adapter

Implement the ContentViewerAdapter interface by wrapping your application's data-fetching hooks:

// lib/my-content-viewer-adapter.ts
import type { ContentViewerAdapter, AdapterHookOptions } from '@miethe/ui/content-viewer';
import { useFetchFileTree, useFetchFileContent } from '@/hooks';

export const myAdapter: ContentViewerAdapter = {
  useFileTree(artifactId: string, options?: AdapterHookOptions) {
    // Wrap your hook and normalize the return shape
    const result = useFetchFileTree(artifactId, {
      enabled: options?.enabled !== false,
    });

    return {
      data: result.data,
      isLoading: result.isLoading,
      error: result.error ?? null,
    };
  },

  useFileContent(artifactId: string, filePath: string, options?: AdapterHookOptions) {
    const result = useFetchFileContent(artifactId, filePath, {
      enabled: options?.enabled !== false,
    });

    return {
      data: result.data,
      isLoading: result.isLoading,
      error: result.error ?? null,
    };
  },
};

2. Provide the Adapter

Wrap your component tree with ContentViewerProvider:

// app/layout.tsx
import { ContentViewerProvider } from '@miethe/ui/content-viewer';
import { myAdapter } from '@/lib/my-content-viewer-adapter';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <ContentViewerProvider adapter={myAdapter}>
      {children}
    </ContentViewerProvider>
  );
}

3. Use Components

Now components can fetch data through your adapter:

// components/MyViewer.tsx
'use client';

import { useState } from 'react';
import { FileTree, ContentPane } from '@miethe/ui/content-viewer';
import { DiffViewer, FilePreviewPane } from '@miethe/ui/display';

export function MyViewer({ artifactId }: { artifactId: string }) {
  const [selectedPath, setSelectedPath] = useState<string | null>(null);

  return (
    <div className="flex h-screen gap-4">
      <div className="w-64 border-r">
        <FileTree
          entityId={artifactId}
          files={[]} // Loaded via adapter
          selectedPath={selectedPath}
          onSelect={setSelectedPath}
        />
      </div>
      <div className="flex-1">
        <ContentPane
          path={selectedPath}
          content={null} // Loaded via adapter
          isLoading={false}
          onSave={(content) => console.log('Save:', content)}
        />
      </div>
    </div>
  );
}

// Example: Diff Viewer for comparing versions
export function DiffExample() {
  return (
    <DiffViewer
      files={[]}
      leftLabel="Collection"
      rightLabel="Project"
    />
  );
}

// Example: File preview with tier information
export function FilePreviewExample() {
  return (
    <FilePreviewPane
      filePath="README.md"
      content={null}
      tier="collection"
      isLoading={false}
    />
  );
}

Components API

DiffViewer

A side-by-side unified diff viewer with file browser sidebar and optional sync conflict resolution actions.

Props:

interface DiffViewerProps {
  files: FileDiff[];                    // Array of file diffs to display
  leftLabel?: string;                   // Label for left (before) panel
  rightLabel?: string;                  // Label for right (after) panel
  onClose?: () => void;                 // Callback when user closes the viewer
  showResolutionActions?: boolean;      // Show resolution action buttons (for sync conflicts)
  onResolve?: (resolution: ResolutionType) => void; // Callback for resolution selection
  localLabel?: string;                  // Custom label for local version (default: "Local (Project)")
  remoteLabel?: string;                 // Custom label for remote version (default: "Remote (Collection)")
  previewMode?: boolean;                // Show preview mode UI before applying resolution
  isResolving?: boolean;                // Show loading state during resolution
  isLoading?: boolean;                  // Show skeleton loading state
}

type ResolutionType = 'keep_local' | 'keep_remote' | 'merge';

Features:

Side-by-side unified diff display with syntax-colored additions and deletions
File list sidebar for navigating multiple diffs
Summary badges showing file counts by status (added, modified, deleted, unchanged)
Optional conflict resolution actions for sync workflows
Large diff handling with lazy-loading (diffs > 50KB or 1000 lines collapsed by default)
Full keyboard navigation and accessibility support

Loading State:

Use DiffViewerSkeleton to show a loading state while diff data is being fetched:

import { DiffViewer, DiffViewerSkeleton } from '@miethe/ui/diff';

{isLoading ? (
  <DiffViewerSkeleton />
) : (
  <DiffViewer
    files={diffs}
    leftLabel="Collection"
    rightLabel="Project"
    showResolutionActions={true}
    onResolve={(resolution) => handleResolve(resolution)}
  />
)}

Example with Mock Data:

import { DiffViewer } from '@miethe/ui/diff';
import type { FileDiff } from '@miethe/ui/diff';

const mockDiffs: FileDiff[] = [
  {
    file_path: 'src/index.ts',
    status: 'modified',
    collection_hash: 'abc123',
    project_hash: 'def456',
    unified_diff: `--- a/src/index.ts
+++ b/src/index.ts
@@ -1,3 +1,4 @@
 export function hello() {
-  return 'world';
+  return 'world!';
 }`
  },
  {
    file_path: 'README.md',
    status: 'added',
    collection_hash: null,
    project_hash: '789abc',
    unified_diff: `--- /dev/null
+++ b/README.md
@@ -0,0 +1 @@
+# My Project`
  }
];

export function DiffExample() {
  return (
    <DiffViewer
      files={mockDiffs}
      leftLabel="Collection"
      rightLabel="Project"
      showResolutionActions={true}
      onResolve={(resolution) => console.log('Resolution:', resolution)}
    />
  );
}

Resolution Actions:

When showResolutionActions is true, users can choose from:

keep_local - Keep the local (project) version
keep_remote - Keep the remote (collection) version
merge - Merge changes from both versions

FilePreviewPane

File content preview with markdown rendering, code display, and plain text support. Includes a tier badge showing the source context (source, collection, or project).

Props:

interface FilePreviewPaneProps {
  filePath: string | null;              // Path of file being previewed
  content: string | null;               // File content to display
  tier: 'source' | 'collection' | 'project'; // Context tier for badge display
  isLoading: boolean;                   // Show loading skeleton
}

Features:

Auto-detects file type (markdown, code, text) based on extension
Markdown files rendered with basic HTML conversion (headers, bold, italic, code blocks, links, lists)
Code files displayed in monospace with line numbers
Tier badge indicating file source (Source, Collection, or Project)
Scrollable container for large files
Loading skeleton during fetch

Example with Markdown Preview:

import { FilePreviewPane } from '@miethe/ui/display';

export function PreviewExample() {
  const [content, setContent] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(false);

  return (
    <FilePreviewPane
      filePath="README.md"
      content={content}
      tier="collection"
      isLoading={isLoading}
    />
  );
}

Tier Badges:

The tier prop controls the badge appearance and label:

source - Outline badge labeled "Source"
collection - Secondary variant labeled "Collection"
project - Default/primary variant labeled "Project"

FileTree

A hierarchical file browser with keyboard navigation and selection support.

Props:

interface FileTreeProps {
  entityId: string;              // Unique identifier for the entity (used as adapter key)
  files: FileNode[];             // Array of file tree nodes
  selectedPath: string | null;   // Currently selected file path
  onSelect: (path: string) => void; // Called when user selects a file
  onAddFile?: () => void;        // Optional: called when user clicks "Add File"
  onDeleteFile?: (path: string) => void; // Optional: called when user deletes a file
  isLoading?: boolean;           // Show loading skeleton
  readOnly?: boolean;            // Hide create/delete buttons (default: false)
  ariaLabel?: string;            // Accessible label (default: "File browser")
}

Features:

Expandable/collapsible directories
File type icons (markdown, code, JSON, etc.)
Full keyboard navigation (arrows, home/end, enter/space)
ARIA tree pattern with roving tabindex
Optional file creation and deletion
Read-only mode for view-only interfaces

Example:

<FileTree
  entityId="skill-123"
  files={[
    { name: 'src', type: 'directory', path: 'src', children: [
      { name: 'index.ts', type: 'file', path: 'src/index.ts' }
    ] }
  ]}
  selectedPath="src/index.ts"
  onSelect={(path) => handleSelect(path)}
  onDeleteFile={(path) => handleDelete(path)}
  readOnly={false}
/>

ContentPane

Display and edit file content with syntax highlighting, markdown preview, and optional editing.

Props:

interface ContentPaneProps {
  path: string | null;           // File path being displayed
  content: string | null;        // File content
  isLoading?: boolean;           // Show loading skeleton
  error?: string | null;         // Error message to display
  readOnly?: boolean;            // Hide edit/save buttons (default: false)
  truncationInfo?: TruncationInfo; // Info about truncated files
  // Lifted edit state
  isEditing?: boolean;           // True when in edit mode
  editedContent?: string;        // Content being edited
  onEditStart?: () => void;      // Called when user clicks "Edit"
  onEditChange?: (content: string) => void; // Called on every keystroke
  onSave?: (content: string) => void | Promise<void>; // Called on save
  onCancel?: () => void;         // Called on cancel
  ariaLabel?: string;            // Accessible label
}

Features:

Breadcrumb navigation for file paths
Syntax highlighting for code files
Markdown split-preview (editor + preview) for .md files
Optional frontmatter display
Edit mode for supported file types
Truncation warning for large files
Lazy-loaded CodeMirror editor (bundle cost only on demand)

Example:

const [isEditing, setIsEditing] = useState(false);
const [editedContent, setEditedContent] = useState('');

<ContentPane
  path="README.md"
  content={fileContent}
  isLoading={isLoading}
  isEditing={isEditing}
  editedContent={editedContent}
  onEditStart={() => {
    setEditedContent(fileContent);
    setIsEditing(true);
  }}
  onEditChange={setEditedContent}
  onSave={async (content) => {
    await saveFile(content);
    setIsEditing(false);
  }}
  onCancel={() => setIsEditing(false)}
/>

FrontmatterDisplay

Display parsed YAML frontmatter as key-value pairs with collapsible state.

Props:

interface FrontmatterDisplayProps {
  frontmatter: Record<string, unknown>; // Parsed YAML frontmatter object
  defaultCollapsed?: boolean;           // Start collapsed (default: false)
  className?: string;                   // Additional CSS classes
}

Supports:

Strings, numbers, booleans, null
Arrays (rendered as comma-separated values)
Nested objects (one level, rendered indented)

Example:

const frontmatter = {
  title: 'My Document',
  tags: ['react', 'typescript'],
  author: { name: 'John', email: 'john@example.com' }
};

<FrontmatterDisplay
  frontmatter={frontmatter}
  defaultCollapsed={false}
  className="mb-4"
/>

SplitPreview

CodeMirror-based markdown editor with live preview. Lazy-loaded for performance.

Props:

interface SplitPreviewProps {
  content: string;                      // Current content
  onChange: (content: string) => void;  // Called on every keystroke
  isEditing: boolean;                   // Control editor visibility
}

Note: This component is lazy-loaded and only fetched when rendering a markdown file in edit mode. Non-markdown files never trigger the download.

MarkdownEditor

CodeMirror-based markdown editor for editing .md files. Also lazy-loaded.

Props:

interface MarkdownEditorProps {
  content: string;                      // Current content
  onChange: (content: string) => void;  // Called on every keystroke
  readOnly?: boolean;                   // Disable editing (default: false)
}

Primitives API (`@miethe/ui/primitives`)

Reusable UI primitives extracted from SkillMeat components. All primitives are production-ready, fully accessible, and compose with shadcn/ui components.

BaseArtifactModal

Controlled composition-based modal foundation for artifact-focused dialogs. Encapsulates common structure (dialog wrapper, header, tabs, content area) while delegating domain-specific logic to consumers.

Props:

interface BaseArtifactModalProps {
  artifact: Artifact;                  // Artifact to display
  open: boolean;                       // Dialog open state
  onClose: () => void;                 // Close handler
  activeTab: string;                   // Controlled tab value
  onTabChange: (tab: string) => void;  // Tab change callback
  tabs: Tab[];                         // Tab definitions for navigation
  headerActions?: React.ReactNode;     // Optional actions in header (right side)
  children: React.ReactNode;           // Tab content (TabContentWrapper elements)
  aboveTabsContent?: React.ReactNode;  // Content between header and tabs
  returnTo?: string;                   // Optional return URL
  onReturn?: () => void;               // Optional return button handler
}

interface Tab {
  value: string;
  label: string;
  icon?: React.ComponentType<{ className?: string }>;
}

Features:

Automatic artifact icon resolution from ARTIFACT_TYPES config
Composable tab content with TabContentWrapper
Header action slots for custom controls
Return navigation support
Full keyboard navigation and accessibility

Example:

const tabs: Tab[] = [
  { value: 'status', label: 'Status', icon: Activity },
  { value: 'sync', label: 'Sync', icon: RefreshCcw },
];

<BaseArtifactModal
  artifact={artifact}
  open={isOpen}
  onClose={() => setIsOpen(false)}
  activeTab={activeTab}
  onTabChange={setActiveTab}
  tabs={tabs}
  headerActions={<HealthIndicator artifact={artifact} />}
>
  <TabContentWrapper value="status">
    <StatusContent artifact={artifact} />
  </TabContentWrapper>
  <TabContentWrapper value="sync">
    <SyncContent artifact={artifact} />
  </TabContentWrapper>
</BaseArtifactModal>

ModalHeader

Header component for use within BaseArtifactModal or standalone dialogs. Displays artifact metadata with icon, name, and optional action buttons.

Props:

interface ModalHeaderProps {
  artifact?: Artifact;                 // Optional artifact for icon/name display
  title?: string;                      // Custom title (overrides artifact name)
  icon?: React.ReactNode;              // Custom icon
  actions?: React.ReactNode;           // Action buttons or controls
  className?: string;                  // Additional CSS classes
}

Features:

Icon auto-resolution from artifact type
Artifact name display
Right-aligned action slot
Consistent styling with SkillMeat modals
Accessible heading semantic

TabNavigation

Horizontal tab list component for BaseArtifactModal and custom tab interfaces. Supports icons and keyboard navigation.

Props:

interface TabNavigationProps {
  tabs: Tab[];                         // Tab definitions
  activeTab: string;                   // Active tab value
  onChange: (tab: string) => void;     // Tab change handler
  className?: string;                  // Additional CSS classes
}

interface Tab {
  value: string;                       // Tab identifier
  label: string;                       // Display label
  icon?: React.ComponentType<{ className?: string }>; // Optional icon component
  disabled?: boolean;                  // Disable tab (optional)
}

Features:

Icon display (from lucide-react or custom)
Full keyboard navigation (ArrowLeft, ArrowRight, Home, End)
Accessible ARIA attributes
Auto-activates on focus

EnterpriseOwnerBadge

Badge component indicating that an artifact is managed by the enterprise organization. Displays inline on artifact cards to signal enterprise governance.

Props:

interface EnterpriseOwnerBadgeProps {
  className?: string;                  // Additional CSS classes
}

Features:

Building2 icon from lucide-react
Violet color scheme for enterprise branding
"Enterprise Managed" label text
Accessible aria-label
Compact inline styling

Example:

import { EnterpriseOwnerBadge } from '@miethe/ui/primitives';

<div className="flex items-center gap-2">
  <ArtifactName artifact={artifact} />
  {artifact.owner_type === 'enterprise' && <EnterpriseOwnerBadge />}
</div>

LockIcon

Tooltip-wrapped lock indicator for artifacts with enforce_override=True. Renders a small lock icon with an accessible tooltip explaining the enforced state.

Props:

interface LockIconProps {
  className?: string;                  // Additional CSS classes
  tooltip?: string;                    // Custom tooltip text (optional)
}

Default tooltip: "This artifact cannot be modified — enforced by your organization"

Features:

Lock icon from lucide-react
Radix UI Tooltip for accessible popover
Keyboard-accessible trigger
Customizable tooltip message
Accessible ARIA labels on both trigger and icon

Example:

import { LockIcon } from '@miethe/ui/primitives';

<div className="flex items-center gap-2">
  <ArtifactName artifact={artifact} />
  {artifact.enforce_override && (
    <LockIcon tooltip="Custom enforcement message" />
  )}
</div>

Planning Primitives (`@miethe/ui/primitives`)

Five status and metadata display primitives extracted from the CCDash Planning Control Plane (PCP-709). These are generic enough to be reused across any planning-adjacent feature.

StatusChip

Five-variant status chip (neutral / ok / warn / error / info) as an inline-flex badge. Accepts an optional tooltip rendered as a title attribute.

import { StatusChip } from '@miethe/ui/primitives';

<StatusChip label="pending" variant="warn" tooltip="Waiting on upstream" />

Variants: neutral (slate) | ok (emerald) | warn (amber) | error (rose) | info (blue)

EffectiveStatusChips

Renders a raw status chip plus an optional effective status chip when the two differ. The raw chip gains a hover tooltip showing provenance source and reason when provenance is supplied.

import { EffectiveStatusChips } from '@miethe/ui/primitives';

<EffectiveStatusChips
  rawStatus="pending"
  effectiveStatus="blocked"
  isMismatch
  provenance={{ source: 'derived', reason: 'Blocked by upstream task', evidence: [] }}
/>

MismatchBadge

Amber mismatch indicator in two modes: compact inline chip or full banner with title, reason, and evidence label chips.

import { MismatchBadge } from '@miethe/ui/primitives';

// Compact inline chip (for card/list contexts)
<MismatchBadge state="stale" reason="Status diverged from progress" compact />

// Full banner (for detail headers)
<MismatchBadge
  state="mismatched"
  reason="Progress says done but PRD is pending"
  evidenceLabels={['PRD-outdated', 'progress-diverged']}
/>

BatchReadinessPill

Wraps StatusChip to show batch readiness state (ready / blocked / waiting / unknown) with optional blocking node/task IDs displayed below the chip.

import { BatchReadinessPill } from '@miethe/ui/primitives';

<BatchReadinessPill
  readinessState="blocked"
  blockingNodeIds={['prd-auth', 'prd-onboarding']}
  blockingTaskIds={['TASK-2.1']}
/>

PlanningNodeTypeIcon

Maps a PlanningNodeType string to a lucide-react icon. Supports 7 node types: design_spec, prd, implementation_plan, progress, context, tracker, report. Accepts size (default 13) and className props.

import { PlanningNodeTypeIcon } from '@miethe/ui/primitives';
import type { PlanningNodeType } from '@miethe/ui/primitives';

<PlanningNodeTypeIcon type="prd" size={16} className="text-blue-400" />

Variant Helpers

import { statusVariant, readinessVariant } from '@miethe/ui/primitives';
import type { StatusChipVariant, ReadinessVariant } from '@miethe/ui/primitives';

// Map any status string to a StatusChip variant
const variant = statusVariant('in_progress'); // → 'ok'
const readiness = readinessVariant('blocked'); // → 'error'

Filters API (`@miethe/ui/filters`)

Reusable filter components for building toolbar filter bars. All components are pure presentational — consumers provide data via props.

TagFilterPopover

Multi-select tag filter with search, color-coded badges, and artifact counts.

import { TagFilterPopover, TagFilterBar } from '@miethe/ui/filters';

<TagFilterPopover
  selectedTags={['design', 'canvas']}
  onChange={(tags) => setTags(tags)}
  availableTags={[
    { name: 'design', artifact_count: 5 },
    { name: 'canvas', artifact_count: 3 },
  ]}
/>

{/* Inline chip bar showing selected tags with remove buttons */}
<TagFilterBar
  selectedTags={selectedTags}
  onChange={setTags}
  availableTags={availableTags}
/>

ToolFilterPopover

Multi-select tool filter with search and counts.

import { ToolFilterPopover, ToolFilterBar } from '@miethe/ui/filters';

<ToolFilterPopover
  selectedTools={['Bash', 'Read']}
  onChange={(tools) => setTools(tools)}
  availableTools={[
    { name: 'Bash', artifact_count: 12 },
    { name: 'Read', artifact_count: 8 },
  ]}
/>

FiltersDropdown

Dropdown button with multi-select category sub-menus and AND/OR toggle.

import { FiltersDropdown, type FilterCategory } from '@miethe/ui/filters';

const categories: FilterCategory[] = [
  {
    id: 'status',
    label: 'Status',
    options: [
      { value: 'active', label: 'Active' },
      { value: 'error', label: 'Error' },
    ],
    selected: selectedStatuses,
    onChange: setStatuses,
  },
];

<FiltersDropdown
  categories={categories}
  filterMode="and"
  onFilterModeChange={setFilterMode}
/>

AND/OR mode: Controls how values within each category combine. AND = must match all selected, OR = match any. Across categories is always AND.

SortDropdown

Sort field + order toggle dropdown.

import { SortDropdown } from '@miethe/ui/filters';

<SortDropdown
  options={[
    { value: 'name', label: 'Name' },
    { value: 'updatedAt', label: 'Last Updated' },
  ]}
  sortField="name"
  sortOrder="asc"
  onSortChange={(field, order) => { /* ... */ }}
/>

Clicking an already-selected field toggles the order.

Bulk Actions API (`@miethe/ui/bulk-actions`)

Floating toolbar component for multi-select interfaces. Displays a bottom-fixed action bar with selection count and action buttons when items are selected.

BulkActionBar

Generic floating bulk action bar that slides in from the bottom of the viewport. Fully props-driven with no backend dependencies.

Props:

Prop	Type	Required	Description
`selectedCount`	`number`	Yes	Number of currently selected items
`hasSelection`	`boolean`	Yes	Controls visibility (true = visible, false = hidden)
`actions`	`BulkAction[]`	Yes	Array of action button definitions
`onClearSelection`	`() => void`	Yes	Callback when user clicks the clear/X button
`className`	`string`	No	Optional className for custom styling

BulkAction Interface:

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier used as React key and loading state key
`label`	`string`	Yes	Button label text
`icon`	`React.ReactNode`	No	Optional icon rendered left of label
`variant`	`'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost'`	No	Button visual style (default: 'ghost')
`onClick`	`() => void \| Promise<void>`	Yes	Click handler; may return a Promise for async actions
`disabled`	`boolean`	No	When true, button is disabled

Basic Usage:

import { BulkActionBar } from '@miethe/ui/bulk-actions';
import { Trash2, Download } from 'lucide-react';
import { useState } from 'react';

export function MyList() {
  const [selected, setSelected] = useState<Set<string>>(new Set());

  const actions = [
    {
      id: 'delete',
      label: 'Delete',
      icon: <Trash2 className="h-3.5 w-3.5" />,
      variant: 'destructive',
      onClick: () => handleDelete(Array.from(selected)),
    },
    {
      id: 'download',
      label: 'Download',
      icon: <Download className="h-3.5 w-3.5" />,
      onClick: async () => {
        await downloadItems(Array.from(selected));
      },
    },
  ];

  return (
    <>
      {/* Your list items with selection checkboxes */}
      <BulkActionBar
        selectedCount={selected.size}
        hasSelection={selected.size > 0}
        actions={actions}
        onClearSelection={() => setSelected(new Set())}
      />
    </>
  );
}

Features:

Smooth slide-up/down transitions
Per-action loading spinners for async operations
Global disabled state during in-flight requests
Full keyboard navigation support
ARIA labels and live region announcements for selection count changes

Adapter Pattern

The adapter pattern is the core architectural decision that makes this package reusable. Instead of baking in dependencies on a specific API client or state management library, components call useContentViewerAdapter() to access injected hooks.

The `ContentViewerAdapter` Interface

import type { ContentViewerAdapter, AdapterHookOptions, AdapterQueryResult, FileTreeResponse, FileContentResponse } from '@miethe/ui/content-viewer';

interface ContentViewerAdapter {
  useFileTree(
    artifactId: string,
    options?: AdapterHookOptions
  ): AdapterQueryResult<FileTreeResponse>;

  useFileContent(
    artifactId: string,
    filePath: string,
    options?: AdapterHookOptions
  ): AdapterQueryResult<FileContentResponse>;
}

Implementing an Adapter

An adapter wraps your application's hooks and normalizes their return shape:

const myAdapter: ContentViewerAdapter = {
  useFileTree(artifactId, options) {
    const result = myCustomHook(artifactId, { enabled: options?.enabled });
    return {
      data: result.data,
      isLoading: result.loading,
      error: result.err ?? null, // Normalize error field
    };
  },

  useFileContent(artifactId, filePath, options) {
    const result = myOtherHook(artifactId, filePath, {
      enabled: options?.enabled
    });
    return {
      data: result.data,
      isLoading: result.loading,
      error: result.err ?? null,
    };
  },
};

Return Shape

All adapter hooks return AdapterQueryResult<T>:

interface AdapterQueryResult<T> {
  data: T | undefined;        // Undefined while loading or on error
  isLoading: boolean;          // True during initial fetch
  error: Error | null;         // Non-null when fetch fails
}

Error Handling

The error field can contain any Error object. Normalize errors from different data sources before returning:

REST API Adapter Example:

import { useQuery } from '@tanstack/react-query';
import type { ContentViewerAdapter } from '@miethe/ui/content-viewer';

export const restAdapter: ContentViewerAdapter = {
  useFileTree(artifactId: string, options) {
    const query = useQuery({
      queryKey: ['file-tree', artifactId],
      queryFn: async () => {
        const res = await fetch(`/api/files/${artifactId}/tree`);
        if (!res.ok) {
          throw new Error(`Failed to load file tree: ${res.status} ${res.statusText}`);
        }
        return res.json();
      },
      enabled: options?.enabled ?? true,
    });

    return {
      data: query.data ?? undefined,
      isLoading: query.isPending,
      error: query.error ?? null,
    };
  },

  useFileContent(artifactId: string, filePath: string, options) {
    const query = useQuery({
      queryKey: ['file-content', artifactId, filePath],
      queryFn: async () => {
        const res = await fetch(`/api/files/${artifactId}/content?path=${filePath}`);
        if (!res.ok) {
          throw new Error(`Failed to load file: ${res.status}`);
        }
        return res.json();
      },
      enabled: options?.enabled ?? true,
    });

    return {
      data: query.data ?? undefined,
      isLoading: query.isPending,
      error: query.error ?? null,
    };
  },
};

GraphQL Adapter Example:

import { useQuery } from '@apollo/client';
import gql from 'graphql-tag';
import type { ContentViewerAdapter } from '@miethe/ui/content-viewer';

const FILE_TREE_QUERY = gql`
  query GetFileTree($id: ID!) {
    fileTree(id: $id) {
      entries {
        name
        path
        type
      }
    }
  }
`;

const FILE_CONTENT_QUERY = gql`
  query GetFileContent($id: ID!, $path: String!) {
    fileContent(id: $id, path: $path) {
      content
      encoding
      size
    }
  }
`;

export const graphqlAdapter: ContentViewerAdapter = {
  useFileTree(artifactId: string, options) {
    const { data, loading, error } = useQuery(FILE_TREE_QUERY, {
      variables: { id: artifactId },
      skip: !(options?.enabled ?? true),
    });

    return {
      data: data?.fileTree ?? undefined,
      isLoading: loading,
      error: error ?? null,
    };
  },

  useFileContent(artifactId: string, filePath: string, options) {
    const { data, loading, error } = useQuery(FILE_CONTENT_QUERY, {
      variables: { id: artifactId, path: filePath },
      skip: !(options?.enabled ?? true),
    });

    return {
      data: data?.fileContent ?? undefined,
      isLoading: loading,
      error: error ?? null,
    };
  },
};

Error Display:

The ContentPane and FileTree components automatically display error states when the error field is truthy:

// Components handle error display automatically
<ContentPane
  path={selectedPath}
  content={content}
  error={fileError} // Will show error UI if non-null
  isLoading={isLoading}
/>

<FileTree
  entityId={artifactId}
  files={files}
  error={treeError} // Will show error UI if non-null
/>

Error Boundary:

Wrap components with a React error boundary to catch unexpected render errors:

import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error }: { error: Error }) {
  return (
    <div className="p-4 text-red-600">
      <p>Something went wrong:</p>
      <pre className="text-sm">{error.message}</pre>
    </div>
  );
}

export function MyViewer() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <FileTree entityId={artifactId} files={files} />
    </ErrorBoundary>
  );
}

Utilities

Type-Color Utilities

Generic color-coding helpers for artifact/entity type indicators. Maps type strings to Tailwind CSS classes for left-border accents and subtle background tints. Type-agnostic and safe to call with arbitrary strings — unknown types receive sensible fallbacks.

import {
  typeBarColors,              // Record mapping types to border-l-{color} classes
  TYPE_BAR_FALLBACK,          // Gray fallback for unknown types
  getTypeBarColor,            // Resolve left-border color
  artifactTypeCardTints,      // Record mapping types to subtle bg tint classes
  getCardTint,                // Resolve background tint
} from '@miethe/ui/utils';

// Get left-border color for a type
const borderColor = getTypeBarColor('skill');     // 'border-l-purple-500'
const unknown = getTypeBarColor('unknown');        // 'border-l-gray-400' (fallback)

// Apply with Tailwind class composition
<div className={`border-l-4 ${getTypeBarColor(artifact.type)}`}>
  {artifact.name}
</div>

// Get background tint (for larger display sizes)
const tint = getCardTint('skill');  // 'bg-purple-500/[0.02] dark:bg-purple-500/[0.03]'
const unknown = getCardTint('unknown'); // '' (returns empty string)

// Apply tint to card
<div className={`p-4 rounded ${getCardTint(artifact.type)}`}>
  {artifact.content}
</div>

// Customize color maps
const customColors = {
  ...typeBarColors,
  customType: 'border-l-red-500',
};
const color = getTypeBarColor('customType', customColors); // 'border-l-red-500'

Supported Types:

skill, command, agent, mcp, hook - Core artifact types
composite, plugin, workflow - Extended types
context_entity, context_module, bundle, deployment_set - Context types
Unknown types default to gray (border-l-gray-400) or empty string (tints)

Frontmatter Parsing

import {
  parseFrontmatter,   // Parse YAML + content
  stripFrontmatter,   // Remove YAML block
  detectFrontmatter,  // Check if content has YAML
} from '@miethe/ui/utils';

// Parse frontmatter and content separately
const { frontmatter, content } = parseFrontmatter(fileContent);

// Remove frontmatter before displaying
const contentWithoutFrontmatter = stripFrontmatter(fileContent);

// Check if file has frontmatter
if (detectFrontmatter(fileContent)) {
  // Show frontmatter display component
}

README Utilities

import {
  extractFirstParagraph,  // Get first paragraph from markdown
  extractFolderReadme,    // Find README in folder tree
} from '@miethe/ui/utils';

// Extract first paragraph for preview
const description = extractFirstParagraph(content);

// Find README.md in a folder
const readmeEntry = extractFolderReadme(fileTree, 'docs');

Types

The package exports canonical type definitions for all data structures:

import type {
  FileNode,                // A file or directory node
  FileTreeEntry,          // A catalog file tree entry
  FileTreeResponse,       // Catalog file tree API response
  FileContentResponse,    // Catalog file content API response
  ContentViewerAdapter,   // The adapter interface
  AdapterQueryResult,     // Normalized query result shape
  AdapterHookOptions,     // Common adapter hook options
} from '@miethe/ui/content-viewer';

FileNode:

interface FileNode {
  name: string;
  path: string;
  type: 'file' | 'directory';
  size?: number;              // File size in bytes
  children?: FileNode[];      // Directory contents
}

FileTreeResponse (from API):

interface FileTreeResponse {
  entries: FileTreeEntry[];   // List of files/directories
  cached: boolean;            // Served from cache?
  cache_age_seconds?: number; // Cache age in seconds
}

FileContentResponse (from API):

interface FileContentResponse {
  content: string;            // Decoded file content
  encoding: string;           // Encoding (usually "utf-8")
  size: number;               // File size in bytes
  sha: string;                // Git blob SHA
  truncated?: boolean;        // Content was truncated?
  original_size?: number;     // Original size before truncation
  cached: boolean;            // Served from cache?
  cache_age_seconds?: number; // Cache age in seconds
}

Examples

Display a file viewer inside a modal dialog:

'use client';

import { useState } from 'react';
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog';
import { FileTree, ContentPane } from '@miethe/ui/content-viewer';

export function ViewerModal({ artifactId, open, onClose }: Props) {
  const [selectedPath, setSelectedPath] = useState<string | null>(null);
  const [isEditing, setIsEditing] = useState(false);
  const [editedContent, setEditedContent] = useState('');

  return (
    <Dialog open={open} onOpenChange={onClose}>
      <DialogContent className="max-w-4xl h-96">
        <DialogHeader>
          <DialogTitle>View Files</DialogTitle>
        </DialogHeader>
        <div className="flex gap-4">
          <div className="w-64 border-r overflow-auto">
            <FileTree
              entityId={artifactId}
              files={[]} // Loaded via adapter
              selectedPath={selectedPath}
              onSelect={setSelectedPath}
              readOnly
            />
          </div>
          <div className="flex-1">
            <ContentPane
              path={selectedPath}
              content={null} // Loaded via adapter
              isEditing={isEditing}
              editedContent={editedContent}
              onEditStart={() => setIsEditing(true)}
              onEditChange={setEditedContent}
              onSave={async (content) => {
                // Handle save
                setIsEditing(false);
              }}
              onCancel={() => setIsEditing(false)}
            />
          </div>
        </div>
      </DialogContent>
    </Dialog>
  );
}

Standalone Viewer

Use components without a modal:

'use client';

import { useState } from 'react';
import { FileTree, ContentPane } from '@miethe/ui/content-viewer';

export function FileViewer({ artifactId }: { artifactId: string }) {
  const [selectedPath, setSelectedPath] = useState<string | null>(null);

  return (
    <div className="grid grid-cols-3 gap-4 h-screen p-4">
      <div className="col-span-1 border rounded-lg overflow-hidden">
        <FileTree
          entityId={artifactId}
          files={[]}
          selectedPath={selectedPath}
          onSelect={setSelectedPath}
          readOnly
        />
      </div>
      <div className="col-span-2 border rounded-lg overflow-hidden">
        <ContentPane
          path={selectedPath}
          content={null}
          readOnly
        />
      </div>
    </div>
  );
}

Custom Adapter Example (SkillMeat)

See SkillMeat's concrete implementation for reference:

// In your application
import { skillmeatContentViewerAdapter, makeCatalogArtifactId } from '@/lib/content-viewer-adapter';
import { ContentViewerProvider } from '@miethe/ui/content-viewer';

const artifactId = makeCatalogArtifactId(sourceId, artifactPath);

<ContentViewerProvider adapter={skillmeatContentViewerAdapter}>
  <FileTree artifactId={artifactId} />
</ContentViewerProvider>

The adapter encodes a composite key (sourceId + artifactPath) into a single string for the components to consume, making it easy to bridge between different identity schemes.

Performance Considerations

Lazy-Loaded Editor Bundle

The CodeMirror editor (used in SplitPreview and MarkdownEditor) is lazy-loaded and only fetched when needed:

Markdown files in edit mode: Editor chunk downloaded
Non-markdown files: Editor never downloaded
Read-only mode: Editor chunk may still load for markdown files (preview uses a lighter markdown renderer)

This significantly reduces the initial bundle size for consumers. If you're only using FileTree and ContentPane for viewing, you may never download the editor.

Component Structure

FileTree - ~8 KB gzipped (fully bundled, no lazy loading)
ContentPane - ~5 KB gzipped (fully bundled)
FrontmatterDisplay - ~2 KB gzipped (fully bundled)
SplitPreview + MarkdownEditor (lazy) - ~50 KB gzipped (on demand)

Accessibility

All components follow WCAG 2.1 AA standards:

FileTree: ARIA tree pattern with roving tabindex, keyboard navigation, labels
ContentPane: Region landmarks, breadcrumb navigation, semantic HTML
FrontmatterDisplay: Semantic structure with strong/emphasis for keys
Editor: Full keyboard support and screen reader compatibility via CodeMirror

Test keyboard navigation with your screen reader before deploying.

TypeScript

The package is fully typed with TypeScript. All components and utilities have complete type definitions. No @ts-ignore should be needed.

Releasing a New Version

This section is for maintainers of @miethe/ui.

Publishing is fully automated via GitHub Actions. When a meaty-ui-v* tag is pushed, the CI pipeline builds, tests, and publishes to GitHub Packages automatically.

Steps

1. Update CHANGELOG.md

Move entries from [Unreleased] into a new version section:

## [0.2.0] - 2026-04-01

### Added
- ...

### Changed
- ...

2. Bump the version in package.json

# From skillmeat/web/packages/ui/
npm version minor   # 0.1.0 → 0.2.0
# or
npm version patch   # 0.1.0 → 0.1.1

Or edit package.json manually and commit.

3. Commit

git add skillmeat/web/packages/ui/package.json skillmeat/web/packages/ui/CHANGELOG.md
git commit -m "chore(meaty-ui): bump version to v0.2.0"

4. Tag and push

Tags must use the meaty-ui-v prefix to avoid colliding with SkillMeat's own v* release tags:

git tag meaty-ui-v0.2.0 -m "Release @miethe/ui v0.2.0"
git push origin main meaty-ui-v0.2.0

The GitHub Actions publish job triggers on the tag push, runs CI, then publishes to GitHub Packages. Monitor progress in the Actions tab of the repository.

Required GitHub Secret

The NPM_TOKEN secret must be set in the repository's GitHub Actions secrets (Settings → Secrets → Actions). It must be a GitHub Personal Access Token with write:packages scope scoped to the @miethe namespace on npm.pkg.github.com. This is a one-time setup — no action needed per release.

License

See LICENSE file in the package root.

@miethe/ui

Package Exports

Readme

@miethe/ui

Overview

Content Viewing & Editing

Consolidated Modal System (Phase 3)

Artifact Type Visualization (Tiered Card System)

Filtering & Operations

Installation

From GitHub Packages (published package)

Within the SkillMeat monorepo (workspace)

Subpath Imports

Prerequisites

Tailwind CSS

Dark Mode

Quick Start

1. Create an Adapter

2. Provide the Adapter

3. Use Components

Components API

DiffViewer

FilePreviewPane

FileTree

ContentPane

FrontmatterDisplay

SplitPreview

MarkdownEditor

Primitives API (@miethe/ui/primitives)

BaseArtifactModal

ModalHeader

TabNavigation

EnterpriseOwnerBadge

LockIcon

Planning Primitives (@miethe/ui/primitives)

StatusChip

EffectiveStatusChips

MismatchBadge

BatchReadinessPill

PlanningNodeTypeIcon

Variant Helpers

Filters API (@miethe/ui/filters)

TagFilterPopover

ToolFilterPopover

FiltersDropdown

SortDropdown

Bulk Actions API (@miethe/ui/bulk-actions)

BulkActionBar

Adapter Pattern

The ContentViewerAdapter Interface

Implementing an Adapter

Return Shape

Error Handling

Utilities

Type-Color Utilities

Frontmatter Parsing

README Utilities

Types

Examples

Modal Integration

Standalone Viewer

Custom Adapter Example (SkillMeat)

Performance Considerations

Lazy-Loaded Editor Bundle

Component Structure

Accessibility

TypeScript

Releasing a New Version

Steps

Required GitHub Secret

License

Primitives API (`@miethe/ui/primitives`)

Planning Primitives (`@miethe/ui/primitives`)

Filters API (`@miethe/ui/filters`)

Bulk Actions API (`@miethe/ui/bulk-actions`)

The `ContentViewerAdapter` Interface