@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/presentation/features/hooks/useContractsRegistry.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { AnyOperationSpec } from '@contractspec/lib.contracts';
+import type { OpRef } from '@contractspec/lib.contracts/features';
+import {
+  getContractSpecOperationRegistry,
+  resolveOperationSpec,
+} from '../../../features';
+
+export interface UseContractsRegistryReturn {
+  /** Resolve an OpRef to its full OperationSpec. */
+  resolveOperation: (ref: OpRef) => AnyOperationSpec | undefined;
+  /** Resolve an operation by key and optional version. */
+  getOperationSpec: (
+    key: string,
+    version?: string
+  ) => AnyOperationSpec | undefined;
+  /** List all registered operation specs. */
+  listOperations: () => AnyOperationSpec[];
+}
+
+/**
+ * Hook to access the ContractSpec contracts registry.
+ * Provides resolution of OpRef/EventRef/PresentationRef to their full specs.
+ */
+export function useContractsRegistry(): UseContractsRegistryReturn {
+  const registry = useMemo(() => getContractSpecOperationRegistry(), []);
+
+  return useMemo(
+    () => ({
+      resolveOperation: (ref: OpRef) =>
+        resolveOperationSpec(ref.key, ref.version),
+      getOperationSpec: (key: string, version?: string) =>
+        resolveOperationSpec(key, version),
+      listOperations: () => registry.list(),
+    }),
+    [registry]
+  );
+}

package/src/presentation/features/hooks/useFeatureFilters.ts

@@ -0,0 +1,137 @@
+'use client';
+
+import { useState, useMemo, useCallback } from 'react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+export interface FeatureFilters {
+  search: string;
+  tags: string[];
+  stability: string[];
+  domain: string[];
+}
+
+export interface UseFeatureFiltersReturn {
+  /** Current filter state. */
+  filters: FeatureFilters;
+  /** Update the search query. */
+  setSearch: (search: string) => void;
+  /** Toggle a tag filter. */
+  toggleTag: (tag: string) => void;
+  /** Toggle a stability filter. */
+  toggleStability: (stability: string) => void;
+  /** Toggle a domain filter. */
+  toggleDomain: (domain: string) => void;
+  /** Clear all filters. */
+  clearFilters: () => void;
+  /** Filtered features based on current filters. */
+  filteredFeatures: FeatureModuleSpec[];
+  /** Whether any filters are active. */
+  hasActiveFilters: boolean;
+}
+
+const defaultFilters: FeatureFilters = {
+  search: '',
+  tags: [],
+  stability: [],
+  domain: [],
+};
+
+/**
+ * Hook for managing feature filter state.
+ * Provides filter controls and filtered feature list.
+ */
+export function useFeatureFilters(
+  features: FeatureModuleSpec[]
+): UseFeatureFiltersReturn {
+  const [filters, setFilters] = useState<FeatureFilters>(defaultFilters);
+
+  const setSearch = useCallback((search: string) => {
+    setFilters((prev) => ({ ...prev, search }));
+  }, []);
+
+  const toggleTag = useCallback((tag: string) => {
+    setFilters((prev) => ({
+      ...prev,
+      tags: prev.tags.includes(tag)
+        ? prev.tags.filter((t) => t !== tag)
+        : [...prev.tags, tag],
+    }));
+  }, []);
+
+  const toggleStability = useCallback((stability: string) => {
+    setFilters((prev) => ({
+      ...prev,
+      stability: prev.stability.includes(stability)
+        ? prev.stability.filter((s) => s !== stability)
+        : [...prev.stability, stability],
+    }));
+  }, []);
+
+  const toggleDomain = useCallback((domain: string) => {
+    setFilters((prev) => ({
+      ...prev,
+      domain: prev.domain.includes(domain)
+        ? prev.domain.filter((d) => d !== domain)
+        : [...prev.domain, domain],
+    }));
+  }, []);
+
+  const clearFilters = useCallback(() => setFilters(defaultFilters), []);
+
+  const hasActiveFilters = useMemo(() => {
+    return (
+      filters.search.length > 0 ||
+      filters.tags.length > 0 ||
+      filters.stability.length > 0 ||
+      filters.domain.length > 0
+    );
+  }, [filters]);
+
+  const filteredFeatures = useMemo(() => {
+    return features.filter((feature) => {
+      // Search filter
+      if (filters.search) {
+        const searchLower = filters.search.toLowerCase();
+        const title = feature.meta.title ?? '';
+        const matches =
+          title.toLowerCase().includes(searchLower) ||
+          feature.meta.description?.toLowerCase().includes(searchLower) ||
+          feature.meta.key.toLowerCase().includes(searchLower);
+        if (!matches) return false;
+      }
+
+      // Tag filter
+      if (filters.tags.length > 0) {
+        const hasTag = filters.tags.some((tag) =>
+          feature.meta.tags?.includes(tag)
+        );
+        if (!hasTag) return false;
+      }
+
+      // Stability filter
+      if (filters.stability.length > 0) {
+        if (!filters.stability.includes(feature.meta.stability ?? 'unknown'))
+          return false;
+      }
+
+      // Domain filter
+      if (filters.domain.length > 0) {
+        if (!filters.domain.includes(feature.meta.domain ?? 'unknown'))
+          return false;
+      }
+
+      return true;
+    });
+  }, [features, filters]);
+
+  return {
+    filters,
+    setSearch,
+    toggleTag,
+    toggleStability,
+    toggleDomain,
+    clearFilters,
+    filteredFeatures,
+    hasActiveFilters,
+  };
+}

package/src/presentation/features/hooks/useFeatureRegistry.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+import { getContractSpecFeatureRegistry } from '../../../features/registry';
+
+export interface UseFeatureRegistryReturn {
+  /** All registered features. */
+  features: FeatureModuleSpec[];
+  /** Get a feature by its key. */
+  getFeature: (key: string) => FeatureModuleSpec | undefined;
+  /** Get features with a specific tag. */
+  getByTag: (tag: string) => FeatureModuleSpec[];
+  /** Get features by owner. */
+  getByOwner: (owner: string) => FeatureModuleSpec[];
+  /** Get all unique tags across features. */
+  getUniqueTags: () => string[];
+  /** Get all unique domains across features. */
+  getUniqueDomains: () => string[];
+  /** Get all unique stability values across features. */
+  getUniqueStabilities: () => string[];
+}
+
+/**
+ * Hook to access the ContractSpec feature registry.
+ * Provides feature listing and filtering capabilities.
+ */
+export function useFeatureRegistry(): UseFeatureRegistryReturn {
+  const registry = useMemo(() => getContractSpecFeatureRegistry(), []);
+
+  return useMemo(() => {
+    const features = registry.list();
+
+    return {
+      features,
+      getFeature: (key: string) => registry.get(key),
+      getByTag: (tag: string) => registry.listByTag(tag),
+      getByOwner: (owner: string) => registry.listByOwner(owner),
+      getUniqueTags: () => registry.getUniqueTags(),
+      getUniqueDomains: () => {
+        const domains = new Set<string>();
+        for (const f of features) {
+          if (f.meta.domain) domains.add(f.meta.domain);
+        }
+        return [...domains].sort();
+      },
+      getUniqueStabilities: () => {
+        const stabilities = new Set<string>();
+        for (const f of features) {
+          if (f.meta.stability) stabilities.add(f.meta.stability);
+        }
+        return [...stabilities].sort();
+      },
+    };
+  }, [registry]);
+}

package/src/presentation/features/hooks/useRelatedDocs.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import { useMemo } from 'react';
+import { defaultDocRegistry } from '@contractspec/lib.contracts';
+
+/**
+ * Hook to fetch documentation blocks related to a specific key or set of tags.
+ */
+export function useRelatedDocs(key: string, tags?: string[]) {
+  const docs = useMemo(() => {
+    try {
+      const allDocs = defaultDocRegistry.list();
+      return allDocs
+        .filter(({ block }) => {
+          // Match by key in ID or title
+          const keyMatch =
+            block.id.toLowerCase().includes(key.toLowerCase()) ||
+            block.title.toLowerCase().includes(key.toLowerCase());
+
+          // Match by tags
+          const tagMatch = tags?.some((t) =>
+            block.tags?.some((bt) => bt.toLowerCase().includes(t.toLowerCase()))
+          );
+
+          return keyMatch || tagMatch;
+        })
+        .map(({ block, route }) => ({
+          id: block.id,
+          title: block.title,
+          summary: block.summary,
+          route,
+        }));
+    } catch (e) {
+      console.error('Failed to fetch related docs:', e);
+      return [];
+    }
+  }, [key, tags]);
+
+  return docs;
+}

package/src/presentation/features/index.ts

@@ -0,0 +1,82 @@
+// Atoms
+export {
+  FeatureIcon,
+  getFeatureIconTone,
+  type FeatureIconProps,
+} from './atoms/FeatureIcon';
+
+// Hooks
+export {
+  useFeatureRegistry,
+  type UseFeatureRegistryReturn,
+  useFeatureFilters,
+  type UseFeatureFiltersReturn,
+  type FeatureFilters,
+  useContractsRegistry,
+  type UseContractsRegistryReturn,
+} from './hooks';
+export { useRelatedDocs } from './hooks/useRelatedDocs';
+
+// Molecules
+export { FeatureCard, type FeatureCardProps } from './molecules/FeatureCard';
+export {
+  FeatureFiltersBar,
+  type FeatureFiltersBarProps,
+} from './molecules/FeatureFilters';
+export {
+  FeatureHoverPreview,
+  type FeatureHoverPreviewProps,
+} from './molecules/FeatureHoverPreview';
+export {
+  FeatureCategoryHeader,
+  type FeatureCategoryHeaderProps,
+} from './molecules/FeatureCategoryHeader';
+
+// Organisms
+export {
+  FeatureDiscovery,
+  type FeatureDiscoveryProps,
+  type FeatureViewMode,
+  type FeatureGroupBy,
+} from './organisms/FeatureDiscovery';
+export {
+  FeatureDetail,
+  type FeatureDetailProps,
+} from './organisms/FeatureDetail';
+export { FeatureOperationsList } from './organisms/FeatureOperationsList';
+export { FeatureEventsList } from './organisms/FeatureEventsList';
+export { FeaturePresentationsList } from './organisms/FeaturePresentationsList';
+export { FeatureDataViewsList } from './organisms/FeatureDataViewsList';
+export { FeatureFormsList } from './organisms/FeatureFormsList';
+
+// Templates
+export {
+  FeatureOverviewTemplate,
+  type FeatureOverviewTemplateProps,
+} from './templates/FeatureOverviewTemplate';
+export { FeatureOperationsTemplate } from './templates/FeatureOperationsTemplate';
+export { FeatureEventsTemplate } from './templates/FeatureEventsTemplate';
+export { FeaturePresentationsTemplate } from './templates/FeaturePresentationsTemplate';
+export { FeatureDataViewsTemplate } from './templates/FeatureDataViewsTemplate';
+export { FeatureFormsTemplate } from './templates/FeatureFormsTemplate';
+export {
+  FeatureOperationDetailTemplate,
+  type FeatureOperationDetailTemplateProps,
+} from './templates/FeatureOperationDetailTemplate';
+export {
+  FeatureEventDetailTemplate,
+  type FeatureEventDetailTemplateProps,
+} from './templates/FeatureEventDetailTemplate';
+export {
+  FeaturePresentationDetailTemplate,
+  type FeaturePresentationDetailTemplateProps,
+} from './templates/FeaturePresentationDetailTemplate';
+export {
+  FeatureDataViewDetailTemplate,
+  type FeatureDataViewDetailTemplateProps,
+} from './templates/FeatureDataViewDetailTemplate';
+export {
+  FeatureFormDetailTemplate,
+  type FeatureFormDetailTemplateProps,
+} from './templates/FeatureFormDetailTemplate';
+export type { FeatureListTemplateProps } from './templates/types';

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

@@ -0,0 +1,105 @@
+'use client';
+
+import { EntityCard, StatusChip } from '@contractspec/lib.design-system';
+import { HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { Zap, Radio, Layout, Shield } from 'lucide-react';
+import { FeatureIcon, getFeatureIconTone } from '../../atoms/FeatureIcon';
+import { FeatureHoverPreview } from '../FeatureHoverPreview';
+import type { FeatureCardProps } from './types';
+
+const stabilityTone = {
+  stable: 'success' as const,
+  beta: 'warning' as const,
+  experimental: 'info' as const,
+  deprecated: 'danger' as const,
+};
+
+/**
+ * Enhanced card component for displaying a feature module.
+ * Shows icon, title, description, stability badge, stats, and capability indicators.
+ * Includes hover preview with full feature details.
+ */
+export function FeatureCard({
+  feature,
+  onSelect,
+  className,
+}: FeatureCardProps) {
+  const { meta, operations, events, presentations, capabilities } = feature;
+
+  const tone =
+    stabilityTone[meta.stability as keyof typeof stabilityTone] ?? 'neutral';
+
+  const iconTone = getFeatureIconTone(meta.stability);
+
+  // Use strong emphasis for stable features for visual highlight
+  const emphasis = meta.stability === 'stable' ? 'strong' : 'default';
+
+  const handleClick = onSelect ? () => onSelect(feature) : undefined;
+
+  const hasCapabilities =
+    capabilities?.provides?.length || capabilities?.requires?.length;
+
+  return (
+    <EntityCard
+      cardTitle={meta.title}
+      cardSubtitle={meta.key}
+      className={className}
+      onClick={handleClick}
+      emphasis={emphasis}
+      icon={
+        <FeatureIcon
+          domain={meta.domain}
+          tags={meta.tags}
+          stability={meta.stability}
+          size="md"
+        />
+      }
+      iconTone={iconTone}
+      chips={
+        <StatusChip tone={tone} label={meta.stability ?? 'unknown'} size="sm" />
+      }
+      meta={
+        meta.description ? (
+          <span className="text-muted-foreground line-clamp-2 text-sm">
+            {meta.description}
+          </span>
+        ) : undefined
+      }
+      preview={<FeatureHoverPreview feature={feature} />}
+      footer={
+        <HStack
+          gap="md"
+          className="text-muted-foreground w-full justify-between text-xs"
+        >
+          <HStack gap="sm">
+            {operations?.length ? (
+              <span className="flex items-center gap-1">
+                <Zap className="h-3 w-3 text-amber-500" />
+                {operations.length}
+              </span>
+            ) : null}
+            {events?.length ? (
+              <span className="flex items-center gap-1">
+                <Radio className="h-3 w-3 text-blue-500" />
+                {events.length}
+              </span>
+            ) : null}
+            {presentations?.length ? (
+              <span className="flex items-center gap-1">
+                <Layout className="h-3 w-3 text-purple-500" />
+                {presentations.length}
+              </span>
+            ) : null}
+          </HStack>
+          {hasCapabilities && (
+            <span className="flex items-center gap-1">
+              <Shield className="h-3 w-3 text-emerald-500" />
+              {(capabilities?.provides?.length ?? 0) +
+                (capabilities?.requires?.length ?? 0)}
+            </span>
+          )}
+        </HStack>
+      }
+    />
+  );
+}

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

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

package/src/presentation/features/molecules/FeatureCard/types.ts

@@ -0,0 +1,10 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts/features';
+
+export interface FeatureCardProps {
+  /** The feature to display. */
+  feature: FeatureModuleSpec;
+  /** Callback when the card is clicked. */
+  onSelect?: (feature: FeatureModuleSpec) => void;
+  /** Additional class name. */
+  className?: string;
+}

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

@@ -0,0 +1,67 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import { ChevronDown, Boxes } from 'lucide-react';
+import { HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { StatusChip } from '@contractspec/lib.design-system';
+
+export interface FeatureCategoryHeaderProps {
+  /** Category/domain title */
+  title: string;
+  /** Number of features in this category */
+  count: number;
+  /** Icon for the category */
+  icon?: React.ReactNode;
+  /** Whether the section is collapsed */
+  isCollapsed?: boolean;
+  /** Toggle collapse state */
+  onToggle?: () => void;
+  /** Additional class name */
+  className?: string;
+}
+
+/**
+ * Category/domain section header for grouped feature display.
+ */
+export function FeatureCategoryHeader({
+  title,
+  count,
+  icon,
+  isCollapsed = false,
+  onToggle,
+  className,
+}: FeatureCategoryHeaderProps) {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      className={cn(
+        'flex w-full items-center justify-between rounded-lg px-4 py-3',
+        'bg-muted/30 hover:bg-muted/50 transition-colors',
+        'group cursor-pointer',
+        className
+      )}
+    >
+      <HStack gap="sm" className="items-center">
+        <div className="text-muted-foreground group-hover:text-foreground transition-colors">
+          {icon || <Boxes className="h-5 w-5" />}
+        </div>
+        <span className="group-hover:text-primary text-lg font-semibold capitalize transition-colors">
+          {title}
+        </span>
+        <StatusChip
+          tone="neutral"
+          label={`${count} ${count === 1 ? 'feature' : 'features'}`}
+          size="sm"
+        />
+      </HStack>
+      <ChevronDown
+        className={cn(
+          'text-muted-foreground h-5 w-5 transition-transform duration-200',
+          isCollapsed && '-rotate-90'
+        )}
+      />
+    </button>
+  );
+}

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

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

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

@@ -0,0 +1,82 @@
+'use client';
+
+import { Button, Input } 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 type { FeatureFiltersBarProps } from './types';
+
+/**
+ * Filter bar for feature discovery.
+ * Provides search input, stability toggles, and tag pills.
+ */
+export function FeatureFiltersBar({
+  uniqueTags,
+  uniqueStabilities,
+  filters,
+  setSearch,
+  toggleTag,
+  toggleStability,
+  clearFilters,
+  hasActiveFilters,
+  className,
+}: FeatureFiltersBarProps) {
+  return (
+    <VStack gap="md" className={cn('w-full', className)}>
+      <HStack gap="md" justify="between" className="w-full">
+        <Input
+          placeholder="Search features..."
+          value={filters.search}
+          onChange={(e) => setSearch(e.target.value)}
+          className="max-w-md"
+          aria-label="Search features"
+        />
+        {hasActiveFilters && (
+          <Button variant="ghost" size="sm" onClick={clearFilters}>
+            Clear filters
+          </Button>
+        )}
+      </HStack>
+
+      {uniqueStabilities.length > 0 && (
+        <HStack gap="xs" wrap="wrap">
+          <span className="text-muted-foreground text-sm">Stability:</span>
+          {uniqueStabilities.map((stability) => (
+            <Button
+              key={stability}
+              variant={
+                filters.stability.includes(stability) ? 'default' : 'outline'
+              }
+              size="sm"
+              onClick={() => toggleStability(stability)}
+              aria-pressed={filters.stability.includes(stability)}
+            >
+              {stability}
+            </Button>
+          ))}
+        </HStack>
+      )}
+
+      {uniqueTags.length > 0 && (
+        <HStack gap="xs" wrap="wrap">
+          <span className="text-muted-foreground text-sm">Tags:</span>
+          {uniqueTags.slice(0, 10).map((tag) => (
+            <Button
+              key={tag}
+              variant={filters.tags.includes(tag) ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => toggleTag(tag)}
+              aria-pressed={filters.tags.includes(tag)}
+            >
+              #{tag}
+            </Button>
+          ))}
+          {uniqueTags.length > 10 && (
+            <span className="text-muted-foreground text-sm">
+              +{uniqueTags.length - 10} more
+            </span>
+          )}
+        </HStack>
+      )}
+    </VStack>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { FeatureFiltersBar } from './FeatureFilters';
+export type { FeatureFiltersBarProps } from './types';

package/src/presentation/features/molecules/FeatureFilters/types.ts

@@ -0,0 +1,25 @@
+import type {
+  FeatureFilters,
+  UseFeatureFiltersReturn,
+} from '../../hooks/useFeatureFilters';
+
+export interface FeatureFiltersBarProps {
+  /** Available tags to filter by. */
+  uniqueTags: string[];
+  /** Available stabilities to filter by. */
+  uniqueStabilities: string[];
+  /** Current filter state. */
+  filters: FeatureFilters;
+  /** Set the search query. */
+  setSearch: UseFeatureFiltersReturn['setSearch'];
+  /** Toggle a tag filter. */
+  toggleTag: UseFeatureFiltersReturn['toggleTag'];
+  /** Toggle a stability filter. */
+  toggleStability: UseFeatureFiltersReturn['toggleStability'];
+  /** Clear all filters. */
+  clearFilters: UseFeatureFiltersReturn['clearFilters'];
+  /** Whether any filters are active. */
+  hasActiveFilters: boolean;
+  /** Additional class name. */
+  className?: string;
+}