@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/presentation/features/molecules/FeatureHoverPreview/FeatureHoverPreview.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+import * as React from 'react';
+import { StatusChip } from '@contractspec/lib.design-system';
+import { HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import {
+  ArrowRight,
+  Layout,
+  Radio,
+  Shield,
+  Tag,
+  Users,
+  Zap,
+} from 'lucide-react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+export interface FeatureHoverPreviewProps {
+  /** The feature to preview */
+  feature: FeatureModuleSpec;
+}
+
+/**
+ * Rich hover preview content for feature cards.
+ * Shows detailed stats, capabilities, and tags.
+ */
+export function FeatureHoverPreview({ feature }: FeatureHoverPreviewProps) {
+  const { meta, operations, events, presentations, capabilities } = feature;
+
+  const hasCapabilities =
+    capabilities?.provides?.length || capabilities?.requires?.length;
+
+  return (
+    <>
+      {/* Description */}
+      {meta.description && (
+        <p className="text-muted-foreground text-sm leading-relaxed">
+          {meta.description}
+        </p>
+      )}
+
+      {/* Stats Row */}
+      <HStack gap="md" className="py-2">
+        {operations?.length ? (
+          <div className="flex items-center gap-1.5 text-sm">
+            <Zap className="h-4 w-4 text-amber-500" />
+            <span className="font-medium">{operations.length}</span>
+            <span className="text-muted-foreground">ops</span>
+          </div>
+        ) : null}
+        {events?.length ? (
+          <div className="flex items-center gap-1.5 text-sm">
+            <Radio className="h-4 w-4 text-blue-500" />
+            <span className="font-medium">{events.length}</span>
+            <span className="text-muted-foreground">events</span>
+          </div>
+        ) : null}
+        {presentations?.length ? (
+          <div className="flex items-center gap-1.5 text-sm">
+            <Layout className="h-4 w-4 text-purple-500" />
+            <span className="font-medium">{presentations.length}</span>
+            <span className="text-muted-foreground">views</span>
+          </div>
+        ) : null}
+      </HStack>
+
+      {/* Capabilities */}
+      {hasCapabilities && (
+        <div className="border-border/50 space-y-1.5 border-t pt-1">
+          {capabilities?.provides?.length ? (
+            <HStack gap="xs" wrap="wrap" className="items-start">
+              <Shield className="mt-0.5 h-3.5 w-3.5 text-emerald-500" />
+              <span className="text-muted-foreground text-xs">Provides:</span>
+              {capabilities.provides.slice(0, 2).map((cap) => (
+                <StatusChip
+                  key={cap.key}
+                  tone="success"
+                  label={cap.key}
+                  size="sm"
+                />
+              ))}
+              {capabilities.provides.length > 2 && (
+                <span className="text-muted-foreground text-xs">
+                  +{capabilities.provides.length - 2}
+                </span>
+              )}
+            </HStack>
+          ) : null}
+          {capabilities?.requires?.length ? (
+            <HStack gap="xs" wrap="wrap" className="items-start">
+              <ArrowRight className="mt-0.5 h-3.5 w-3.5 text-blue-500" />
+              <span className="text-muted-foreground text-xs">Requires:</span>
+              {capabilities.requires.slice(0, 2).map((req) => (
+                <StatusChip
+                  key={req.key}
+                  tone="info"
+                  label={req.key}
+                  size="sm"
+                />
+              ))}
+              {capabilities.requires.length > 2 && (
+                <span className="text-muted-foreground text-xs">
+                  +{capabilities.requires.length - 2}
+                </span>
+              )}
+            </HStack>
+          ) : null}
+        </div>
+      )}
+
+      {/* Tags */}
+      {meta.tags?.length ? (
+        <HStack
+          gap="xs"
+          wrap="wrap"
+          className="border-border/50 items-center border-t pt-1"
+        >
+          <Tag className="text-muted-foreground h-3.5 w-3.5" />
+          {meta.tags.slice(0, 4).map((tag) => (
+            <span
+              key={tag}
+              className="bg-muted text-muted-foreground rounded px-1.5 py-0.5 text-xs"
+            >
+              #{tag}
+            </span>
+          ))}
+          {meta.tags.length > 4 && (
+            <span className="text-muted-foreground text-xs">
+              +{meta.tags.length - 4}
+            </span>
+          )}
+        </HStack>
+      ) : null}
+
+      {/* Owners */}
+      {meta.owners?.length ? (
+        <HStack gap="xs" className="text-muted-foreground items-center text-xs">
+          <Users className="h-3.5 w-3.5" />
+          <span>{meta.owners.join(', ')}</span>
+        </HStack>
+      ) : null}
+    </>
+  );
+}

package/src/presentation/features/molecules/FeatureHoverPreview/index.ts

@@ -0,0 +1,4 @@
+export {
+  FeatureHoverPreview,
+  type FeatureHoverPreviewProps,
+} from './FeatureHoverPreview';

package/src/presentation/features/molecules/index.ts

@@ -0,0 +1,13 @@
+export { FeatureCard, type FeatureCardProps } from './FeatureCard';
+export {
+  FeatureFiltersBar,
+  type FeatureFiltersBarProps,
+} from './FeatureFilters';
+export {
+  FeatureHoverPreview,
+  type FeatureHoverPreviewProps,
+} from './FeatureHoverPreview';
+export {
+  FeatureCategoryHeader,
+  type FeatureCategoryHeaderProps,
+} from './FeatureCategoryHeader';

package/src/presentation/features/organisms/FeatureDataViewsList.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { EntityCard } from '@contractspec/lib.design-system';
+import { Table } from 'lucide-react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+import { resolveSerializedDataViewSpec } from '../../../features';
+
+export function FeatureDataViewsList({
+  feature,
+}: {
+  feature: FeatureModuleSpec;
+}) {
+  if (!feature.dataViews?.length) return null;
+
+  return (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {feature.dataViews.map((view) => {
+        const spec = resolveSerializedDataViewSpec(view.key, view.version);
+
+        return (
+          <EntityCard
+            key={view.key}
+            cardTitle={view.key}
+            cardSubtitle={`v${view.version}`}
+            footer={spec?.meta.description}
+            icon={<Table className="h-4 w-4" />}
+            href={`/features/${feature.meta.key}/dataviews/${view.key}`}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/presentation/features/organisms/FeatureDetail/FeatureDetail.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import {
+  StatCard,
+  StatCardGroup,
+  StatusChip,
+} from '@contractspec/lib.design-system';
+import { Box, HStack, VStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { FeatureDetailProps } from './types';
+import Link from 'next/link';
+
+const stabilityTone = {
+  stable: 'success' as const,
+  beta: 'warning' as const,
+  experimental: 'info' as const,
+  deprecated: 'danger' as const,
+};
+
+/**
+ * Detailed view of a feature module.
+ * Shows full feature info including operations, events, capabilities, and tags.
+ */
+export function FeatureDetail({ feature, className }: FeatureDetailProps) {
+  const { meta, operations, events, presentations, capabilities } = feature;
+
+  const tone =
+    stabilityTone[meta.stability as keyof typeof stabilityTone] ?? 'neutral';
+
+  return (
+    <VStack gap="lg" className={cn('w-full', className)}>
+      <HStack gap="sm">
+        <StatusChip tone={tone} label={meta.stability ?? 'unknown'} />
+        <StatusChip tone="neutral" label={meta.key} size="sm" />
+        <StatusChip tone="neutral" label={`v${meta.version}`} size="sm" />
+      </HStack>
+
+      <StatCardGroup>
+        <Link href={`./${feature.meta.key}/operations`}>
+          <StatCard label="Operations" value={operations?.length ?? 0} />
+        </Link>
+        <Link href={`./${feature.meta.key}/events`}>
+          <StatCard label="Events" value={events?.length ?? 0} />
+        </Link>
+        <Link href={`./${feature.meta.key}/presentations`}>
+          <StatCard label="Presentations" value={presentations?.length ?? 0} />
+        </Link>
+      </StatCardGroup>
+
+      {capabilities?.provides?.length ? (
+        <Box className="flex-col rounded-lg border p-4" gap="sm" align="start">
+          <span className="font-semibold">Provides Capabilities</span>
+          <HStack gap="xs" wrap="wrap">
+            {capabilities.provides.map((cap) => (
+              <StatusChip
+                key={`${cap.key}-${cap.version}`}
+                tone="success"
+                label={`${cap.key} v${cap.version}`}
+                size="sm"
+              />
+            ))}
+          </HStack>
+        </Box>
+      ) : null}
+
+      {capabilities?.requires?.length ? (
+        <Box className="flex-col rounded-lg border p-4" gap="sm" align="start">
+          <span className="font-semibold">Requires Capabilities</span>
+          <HStack gap="xs" wrap="wrap">
+            {capabilities.requires.map((req) => (
+              <StatusChip
+                key={req.key}
+                tone="info"
+                label={`${req.key}${req.version ? ` v${req.version}` : ''}${req.optional ? ' (optional)' : ''}`}
+                size="sm"
+              />
+            ))}
+          </HStack>
+        </Box>
+      ) : null}
+
+      {meta.tags?.length ? (
+        <Box className="flex-col rounded-lg border p-4" gap="sm" align="start">
+          <span className="font-semibold">Tags</span>
+          <HStack gap="xs" wrap="wrap">
+            {meta.tags.map((tag) => (
+              <StatusChip
+                key={tag}
+                tone="neutral"
+                label={`#${tag}`}
+                size="sm"
+              />
+            ))}
+          </HStack>
+        </Box>
+      ) : null}
+
+      {meta.owners?.length ? (
+        <Box className="flex-col rounded-lg border p-4" gap="sm" align="start">
+          <span className="font-semibold">Owners</span>
+          <HStack gap="xs" wrap="wrap">
+            {meta.owners.map((owner) => (
+              <StatusChip key={owner} tone="neutral" label={owner} size="sm" />
+            ))}
+          </HStack>
+        </Box>
+      ) : null}
+    </VStack>
+  );
+}

package/src/presentation/features/organisms/FeatureDetail/index.ts

@@ -0,0 +1,2 @@
+export { FeatureDetail } from './FeatureDetail';
+export type { FeatureDetailProps } from './types';

package/src/presentation/features/organisms/FeatureDetail/types.ts

@@ -0,0 +1,8 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+export interface FeatureDetailProps {
+  /** The feature to display. */
+  feature: FeatureModuleSpec;
+  /** Additional class name. */
+  className?: string;
+}

package/src/presentation/features/organisms/FeatureDiscovery/FeatureDiscovery.tsx

@@ -0,0 +1,236 @@
+'use client';
+
+import * as React from 'react';
+import {
+  PageHeaderResponsive,
+  EmptyState,
+  Button,
+  StatusChip,
+} from '@contractspec/lib.design-system';
+import { VStack, HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import { LayoutGrid, List, Star } from 'lucide-react';
+import { useFeatureRegistry } from '../../hooks/useFeatureRegistry';
+import { useFeatureFilters } from '../../hooks/useFeatureFilters';
+import { FeatureCard } from '../../molecules/FeatureCard';
+import { FeatureFiltersBar } from '../../molecules/FeatureFilters';
+import { FeatureCategoryHeader } from '../../molecules/FeatureCategoryHeader';
+import type { FeatureDiscoveryProps, FeatureViewMode } from './types';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+// Group features by domain
+function groupFeaturesByDomain(features: FeatureModuleSpec[]) {
+  const groups: Record<string, FeatureModuleSpec[]> = {};
+  for (const feature of features) {
+    const domain = feature.meta.domain || 'Other';
+    if (!groups[domain]) groups[domain] = [];
+    groups[domain].push(feature);
+  }
+  return groups;
+}
+
+// Group features by stability
+function groupFeaturesByStability(features: FeatureModuleSpec[]) {
+  const order = ['stable', 'beta', 'experimental', 'deprecated', 'unknown'];
+  const groups: Record<string, FeatureModuleSpec[]> = {};
+  for (const feature of features) {
+    const stability = feature.meta.stability || 'unknown';
+    if (!groups[stability]) groups[stability] = [];
+    groups[stability].push(feature);
+  }
+  // Sort by order
+  const sorted: Record<string, FeatureModuleSpec[]> = {};
+  for (const key of order) {
+    if (groups[key]) sorted[key] = groups[key];
+  }
+  return sorted;
+}
+
+/**
+ * Main feature discovery UI.
+ * Provides search, filtering, view modes, and browsing of registered features.
+ */
+export function FeatureDiscovery({
+  onSelectFeature,
+  className,
+  defaultViewMode = 'grid',
+  groupBy = 'domain',
+  showFeatured = true,
+}: FeatureDiscoveryProps) {
+  const { features, getUniqueTags, getUniqueStabilities } =
+    useFeatureRegistry();
+  const {
+    filters,
+    setSearch,
+    toggleTag,
+    toggleStability,
+    clearFilters,
+    filteredFeatures,
+    hasActiveFilters,
+  } = useFeatureFilters(features);
+
+  const uniqueTags = getUniqueTags();
+  const uniqueStabilities = getUniqueStabilities();
+
+  const [viewMode, setViewMode] =
+    React.useState<FeatureViewMode>(defaultViewMode);
+  const [collapsedGroups, setCollapsedGroups] = React.useState<Set<string>>(
+    new Set()
+  );
+
+  // Featured features (stable)
+  const featuredFeatures = React.useMemo(
+    () => filteredFeatures.filter((f) => f.meta.stability === 'stable'),
+    [filteredFeatures]
+  );
+
+  const nonFeaturedFeatures = React.useMemo(
+    () =>
+      showFeatured
+        ? filteredFeatures.filter((f) => f.meta.stability !== 'stable')
+        : filteredFeatures,
+    [filteredFeatures, showFeatured]
+  );
+
+  // Group features
+  const groupedFeatures = React.useMemo(() => {
+    if (groupBy === 'none') return null;
+    if (groupBy === 'domain') return groupFeaturesByDomain(nonFeaturedFeatures);
+    return groupFeaturesByStability(nonFeaturedFeatures);
+  }, [nonFeaturedFeatures, groupBy]);
+
+  const toggleGroup = (group: string) => {
+    setCollapsedGroups((prev) => {
+      const next = new Set(prev);
+      if (next.has(group)) {
+        next.delete(group);
+      } else {
+        next.add(group);
+      }
+      return next;
+    });
+  };
+
+  const gridClasses =
+    viewMode === 'grid'
+      ? 'grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3'
+      : 'flex flex-col gap-3';
+
+  const renderFeatureCards = (featureList: FeatureModuleSpec[]) => (
+    <div className={gridClasses}>
+      {featureList.map((feature) => (
+        <FeatureCard
+          key={feature.meta.key}
+          feature={feature}
+          onSelect={onSelectFeature}
+        />
+      ))}
+    </div>
+  );
+
+  return (
+    <VStack gap="lg" className={cn('w-full p-6', className)}>
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <PageHeaderResponsive
+          title="Feature Discovery"
+          subtitle={`Browse ${features.length} available ContractSpec features`}
+        />
+        <HStack gap="xs">
+          <button
+            type="button"
+            onClick={() => setViewMode('grid')}
+            className={cn(
+              'rounded-md p-2 transition-colors',
+              viewMode === 'grid'
+                ? 'bg-primary text-primary-foreground'
+                : 'bg-muted hover:bg-muted/80 text-muted-foreground'
+            )}
+            aria-label="Grid view"
+          >
+            <LayoutGrid className="h-4 w-4" />
+          </button>
+          <button
+            type="button"
+            onClick={() => setViewMode('list')}
+            className={cn(
+              'rounded-md p-2 transition-colors',
+              viewMode === 'list'
+                ? 'bg-primary text-primary-foreground'
+                : 'bg-muted hover:bg-muted/80 text-muted-foreground'
+            )}
+            aria-label="List view"
+          >
+            <List className="h-4 w-4" />
+          </button>
+        </HStack>
+      </div>
+
+      <FeatureFiltersBar
+        uniqueTags={uniqueTags}
+        uniqueStabilities={uniqueStabilities}
+        filters={filters}
+        setSearch={setSearch}
+        toggleTag={toggleTag}
+        toggleStability={toggleStability}
+        clearFilters={clearFilters}
+        hasActiveFilters={hasActiveFilters}
+      />
+
+      {filteredFeatures.length === 0 ? (
+        <EmptyState
+          title="No features found"
+          description={
+            hasActiveFilters
+              ? 'Try adjusting your search or filters'
+              : 'No features are registered yet'
+          }
+          primaryAction={
+            hasActiveFilters ? (
+              <Button variant="outline" onClick={clearFilters}>
+                Clear filters
+              </Button>
+            ) : undefined
+          }
+        />
+      ) : (
+        <VStack gap="lg">
+          {/* Featured section */}
+          {showFeatured && featuredFeatures.length > 0 && (
+            <VStack gap="sm">
+              <HStack gap="sm" className="items-center">
+                <Star className="h-5 w-5 fill-amber-500 text-amber-500" />
+                <span className="text-lg font-semibold">Featured</span>
+                <StatusChip
+                  tone="success"
+                  label={`${featuredFeatures.length} stable`}
+                  size="sm"
+                />
+              </HStack>
+              {renderFeatureCards(featuredFeatures)}
+            </VStack>
+          )}
+
+          {/* Grouped or flat display */}
+          {groupedFeatures ? (
+            <VStack gap="md">
+              {Object.entries(groupedFeatures).map(([group, groupFeatures]) => (
+                <VStack key={group} gap="sm">
+                  <FeatureCategoryHeader
+                    title={group}
+                    count={groupFeatures.length}
+                    isCollapsed={collapsedGroups.has(group)}
+                    onToggle={() => toggleGroup(group)}
+                  />
+                  {!collapsedGroups.has(group) &&
+                    renderFeatureCards(groupFeatures)}
+                </VStack>
+              ))}
+            </VStack>
+          ) : (
+            renderFeatureCards(nonFeaturedFeatures)
+          )}
+        </VStack>
+      )}
+    </VStack>
+  );
+}

package/src/presentation/features/organisms/FeatureDiscovery/index.ts

@@ -0,0 +1,6 @@
+export { FeatureDiscovery } from './FeatureDiscovery';
+export type {
+  FeatureDiscoveryProps,
+  FeatureViewMode,
+  FeatureGroupBy,
+} from './types';

package/src/presentation/features/organisms/FeatureDiscovery/types.ts

@@ -0,0 +1,17 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+export type FeatureViewMode = 'grid' | 'list';
+export type FeatureGroupBy = 'none' | 'domain' | 'stability';
+
+export interface FeatureDiscoveryProps {
+  /** Callback when a feature is selected. */
+  onSelectFeature?: (feature: FeatureModuleSpec) => void;
+  /** Additional class name. */
+  className?: string;
+  /** Default view mode */
+  defaultViewMode?: FeatureViewMode;
+  /** Group features by category */
+  groupBy?: FeatureGroupBy;
+  /** Show featured/stable features at top */
+  showFeatured?: boolean;
+}

package/src/presentation/features/organisms/FeatureEventsList.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import { EntityCard } from '@contractspec/lib.design-system';
+import { Radio } from 'lucide-react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+import { resolveSerializedEventSpec } from '../../../features';
+
+export function FeatureEventsList({ feature }: { feature: FeatureModuleSpec }) {
+  if (!feature.events?.length) return null;
+
+  return (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {feature.events.map((ev) => {
+        const spec = resolveSerializedEventSpec(ev.key, ev.version);
+        return (
+          <EntityCard
+            key={ev.key}
+            cardTitle={ev.key}
+            cardSubtitle={`v${ev.version}`}
+            footer={spec?.meta.description}
+            icon={<Radio className="h-4 w-4" />}
+            href={`/features/${feature.meta.key}/events/${ev.key}`}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/presentation/features/organisms/FeatureFormsList.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { EntityCard } from '@contractspec/lib.design-system';
+import { FormInput } from 'lucide-react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+import { resolveSerializedFormSpec } from '../../../features';
+
+export function FeatureFormsList({ feature }: { feature: FeatureModuleSpec }) {
+  if (!feature.forms?.length) return null;
+
+  return (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {feature.forms.map((form) => {
+        const spec = resolveSerializedFormSpec(form.key, form.version);
+
+        return (
+          <EntityCard
+            key={form.key}
+            cardTitle={form.key}
+            cardSubtitle={form.version ? `v${form.version}` : undefined}
+            footer={spec?.meta.description}
+            icon={<FormInput className="h-4 w-4" />}
+            href={`/features/${feature.meta.key}/forms/${form.key}`}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/presentation/features/organisms/FeatureOperationsList.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { EntityCard } from '@contractspec/lib.design-system';
+import { Zap } from 'lucide-react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+import { resolveSerializedOperationSpec } from '../../../features/contracts-registry';
+
+export function FeatureOperationsList({
+  feature,
+}: {
+  feature: FeatureModuleSpec;
+}) {
+  if (!feature.operations?.length) return null;
+
+  return (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {feature.operations.map((op) => {
+        const spec = resolveSerializedOperationSpec(op.key, op.version);
+
+        return (
+          <EntityCard
+            key={op.key}
+            cardTitle={op.key}
+            cardSubtitle={`v${op.version}`}
+            footer={spec?.meta.description}
+            icon={<Zap className="h-4 w-4" />}
+            href={`/features/${feature.meta.key}/operations/${op.key}`}
+          />
+        );
+      })}
+    </div>
+  );
+}