ai-design-system 0.1.0

package/components/features/SpecNavigator/useSpecNavigator.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Hook Contract Definition for SpecNavigator
+ *
+ * This file defines the interface contract between the SpecNavigator design system
+ * component and consuming applications. Applications should implement this hook
+ * to provide real data and state management for the SpecNavigator feature.
+ *
+ * @example
+ * ```typescript
+ * // Application implementation example
+ * import { useSpecNavigator } from './hooks/useSpecNavigator';
+ * import { SpecNavigator } from '@/components/features/SpecNavigator';
+ *
+ * function MySpecView() {
+ *   const { groups, selectedFileId, loading, handleFileSelect } = useSpecNavigator();
+ *
+ *   if (loading) {
+ *     return <div>Loading specifications...</div>;
+ *   }
+ *
+ *   return (
+ *     <SpecNavigator
+ *       groups={groups}
+ *       selectedFileId={selectedFileId}
+ *       onFileSelect={handleFileSelect}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real implementation with API integration
+ * export function useSpecNavigator(): UseSpecNavigatorReturn {
+ *   const [groups, setGroups] = useState<FileGroup[]>([]);
+ *   const [selectedFileId, setSelectedFileId] = useState<string>();
+ *   const [loading, setLoading] = useState(true);
+ *
+ *   useEffect(() => {
+ *     async function fetchSpecs() {
+ *       setLoading(true);
+ *       try {
+ *         const data = await api.getSpecifications();
+ *         setGroups(transformToFileGroups(data));
+ *       } catch (error) {
+ *         console.error('Failed to load specs:', error);
+ *       } finally {
+ *         setLoading(false);
+ *       }
+ *     }
+ *     fetchSpecs();
+ *   }, []);
+ *
+ *   const handleFileSelect = useCallback((fileId: string) => {
+ *     setSelectedFileId(fileId);
+ *     // Additional logic: navigate, load file content, etc.
+ *   }, []);
+ *
+ *   return { groups, selectedFileId, loading, handleFileSelect };
+ * }
+ * ```
+ */
+
+import type { FileGroup } from "@/components/composites/FileQueue";
+
+/**
+ * Return type for the useSpecNavigator hook
+ *
+ * This interface defines the contract that application implementations must fulfill
+ * to integrate with the SpecNavigator component.
+ */
+export interface UseSpecNavigatorReturn {
+  /**
+   * File groups to display in the navigator
+   *
+   * Each group represents a category of specification files (e.g., Instructions,
+   * Agents, Toolbox, Triggers) with associated files. Groups should be ordered as they should
+   * appear in the UI.
+   */
+  groups: FileGroup[];
+
+  /**
+   * ID of the currently selected file
+   *
+   * When set, the corresponding file in the navigator will be visually highlighted.
+   * This should match the `id` property of a file within one of the groups.
+   */
+  selectedFileId?: string;
+
+  /**
+   * Loading state indicator
+   *
+   * When true, indicates that specification data is being fetched or processed.
+   * Applications can use this to show loading states or disable interactions.
+   */
+  loading: boolean;
+
+  /**
+   * Handler for file selection events
+   *
+   * Called when a user selects a file in the navigator. Applications should
+   * implement this to update the selected file state and perform any additional
+   * actions (e.g., loading file content, navigation, analytics).
+   *
+   * @param fileId - The unique identifier of the selected file
+   */
+  handleFileSelect: (fileId: string) => void;
+}
+
+/**
+ * Hook for managing spec navigator state and interactions
+ *
+ * Applications must implement this hook to provide data and state management
+ * for the SpecNavigator component. The hook should handle:
+ * - Fetching specification file data from APIs or local sources
+ * - Managing file selection state
+ * - Transforming raw data into FileGroup format
+ * - Handling loading and error states
+ *
+ * @returns {UseSpecNavigatorReturn} Object containing groups, selection state, and handlers
+ */
+export function useSpecNavigator(): UseSpecNavigatorReturn;

package/components/features/SpecNavigator/useSpecNavigator.mock.ts

@@ -0,0 +1,93 @@
+import { useState, useCallback } from "react";
+import type { FileGroup } from "@/components/composites/FileQueue";
+
+/**
+ * Mock hook for SpecNavigator state management
+ *
+ * This mock simulates the behavior of a real application hook that would:
+ * - Fetch specification files from an API or file system
+ * - Manage file selection state
+ * - Transform raw data into FileGroup format
+ * - Handle loading states during data fetching
+ *
+ * Use this as a reference for implementing real application hooks.
+ */
+export interface UseSpecNavigatorReturn {
+  /** File groups to display in the navigator */
+  groups: FileGroup[];
+  /** ID of the currently selected file */
+  selectedFileId?: string;
+  /** Loading state indicator */
+  loading: boolean;
+  /** Handler for file selection events */
+  handleFileSelect: (fileId: string) => void;
+}
+
+export interface UseSpecNavigatorOptions {
+  /** Initial file groups to display */
+  initialGroups?: FileGroup[];
+  /** Initial selected file ID */
+  initialSelectedId?: string;
+}
+
+/**
+ * Mock implementation of spec navigator state management
+ *
+ * This mock provides a simple state management implementation for Storybook
+ * demonstrations. Real applications should implement the useSpecNavigator hook
+ * with actual API integration, error handling, and more sophisticated state
+ * management.
+ *
+ * @param options - Configuration for mock behavior
+ * @returns State and handlers for spec navigation
+ *
+ * @example
+ * ```typescript
+ * // In a Storybook story
+ * const { groups, selectedFileId, handleFileSelect } = useMockSpecNavigator({
+ *   initialGroups: [
+ *     {
+ *       id: 'requirements',
+ *       title: 'Requirements',
+ *       files: [{ id: 'req1', name: 'requirements.md' }],
+ *     },
+ *   ],
+ *   initialSelectedId: 'req1',
+ * });
+ *
+ * return (
+ *   <SpecNavigator
+ *     groups={groups}
+ *     selectedFileId={selectedFileId}
+ *     onFileSelect={handleFileSelect}
+ *   />
+ * );
+ * ```
+ */
+export function useMockSpecNavigator(
+  options: UseSpecNavigatorOptions = {}
+): UseSpecNavigatorReturn {
+  const { initialGroups = [], initialSelectedId } = options;
+
+  const [groups] = useState<FileGroup[]>(initialGroups);
+  const [selectedFileId, setSelectedFileId] = useState<string | undefined>(
+    initialSelectedId
+  );
+  const [loading] = useState(false);
+
+  const handleFileSelect = useCallback((fileId: string) => {
+    setSelectedFileId(fileId);
+    // In a real implementation, this would also:
+    // - Load file content from API
+    // - Update URL/routing
+    // - Track analytics
+    // - Trigger side effects
+  }, []);
+
+  return {
+    groups,
+    selectedFileId,
+    loading,
+    handleFileSelect,
+  };
+}

package/components/features/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Features
+ *
+ * Central export point for all feature components.
+ * Features are complete, self-contained pieces of functionality.
+ */
+
+// RefinementPanel Feature
+export { RefinementPanel } from "./RefinementPanel";
+export type { RefinementPanelProps, RefinementMessage } from "./RefinementPanel";
+
+// SpecNavigator Feature
+export { SpecNavigator } from "./SpecNavigator";
+export type { SpecNavigatorProps } from "./SpecNavigator";
+
+// AIDocEditor Feature
+export { AIDocEditor } from "./AIDocEditor";
+export type { AIDocEditorProps } from "./AIDocEditor";

package/components/index.ts

@@ -0,0 +1,14 @@
+// Primitives
+export * from './primitives';
+
+// Composites
+export * from './composites';
+
+// Blocks
+export * from './blocks';
+
+// Features
+export * from './features';
+
+// Utilities
+export { cn } from '../lib/utils';

package/components/primitives/Accordion/Accordion.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "./Accordion"
+
+const meta = {
+  title: "Primitives/Accordion",
+  component: Accordion,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Accordion>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => (
+    <Accordion type="single" collapsible className="w-full max-w-md">
+      <AccordionItem value="item-1">
+        <AccordionTrigger>Is it accessible?</AccordionTrigger>
+        <AccordionContent>
+          Yes. It adheres to the WAI-ARIA design pattern.
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>Is it styled?</AccordionTrigger>
+        <AccordionContent>
+          Yes. It comes with default styles that matches the other components.
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>Is it animated?</AccordionTrigger>
+        <AccordionContent>
+          Yes. It's animated by default, but you can disable it if you prefer.
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+}
+
+export const Multiple: Story = {
+  render: () => (
+    <Accordion type="multiple" className="w-full max-w-md">
+      <AccordionItem value="item-1">
+        <AccordionTrigger>Section 1</AccordionTrigger>
+        <AccordionContent>Content for section 1.</AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>Section 2</AccordionTrigger>
+        <AccordionContent>Content for section 2.</AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>Section 3</AccordionTrigger>
+        <AccordionContent>Content for section 3.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+}
+
+export const DarkMode: Story = {
+  parameters: {
+    backgrounds: { default: "dark" },
+  },
+  render: () => (
+    <div className="dark">
+      <Accordion type="single" collapsible className="w-full max-w-md">
+        <AccordionItem value="item-1">
+          <AccordionTrigger>Is it accessible?</AccordionTrigger>
+          <AccordionContent>
+            Yes. It adheres to the WAI-ARIA design pattern.
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="item-2">
+          <AccordionTrigger>Is it styled?</AccordionTrigger>
+          <AccordionContent>
+            Yes. It comes with default styles.
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}

package/components/primitives/Accordion/Accordion.tsx

@@ -0,0 +1,66 @@
+import * as React from "react"
+import {
+  Accordion as ShadcnAccordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "../../ui/accordion"
+
+/**
+ * Accordion Primitive
+ *
+ * A foundational accordion component for collapsible content sections.
+ * Built on Radix UI Accordion primitive with WCAG 2.1 Level AA compliance.
+ *
+ * ## Accessibility Features
+ * - Keyboard navigation (Tab, Space, Enter, Arrow keys)
+ * - Proper ARIA attributes (aria-expanded, aria-controls)
+ * - Focus management
+ * - Screen reader support
+ *
+ * @example
+ * ```tsx
+ * <Accordion type="single" collapsible>
+ *   <AccordionItem value="item-1">
+ *     <AccordionTrigger>Section 1</AccordionTrigger>
+ *     <AccordionContent>Content 1</AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @see https://ui.shadcn.com/docs/components/accordion
+ * @see https://www.radix-ui.com/primitives/docs/components/accordion
+ */
+
+export type AccordionProps = React.ComponentProps<typeof ShadcnAccordion>
+export type AccordionItemProps = React.ComponentProps<typeof AccordionItem>
+export type AccordionTriggerProps = React.ComponentProps<typeof AccordionTrigger>
+export type AccordionContentProps = React.ComponentProps<typeof AccordionContent>
+
+/**
+ * Accordion component
+ *
+ * A collapsible content container built on Radix UI Accordion primitive.
+ * Supports both single and multiple item expansion.
+ *
+ * Features:
+ * - Keyboard navigation (Tab, Space, Enter, Arrow keys)
+ * - Proper ARIA attributes
+ * - Focus management
+ * - Screen reader support
+ * - Smooth animations
+ * - Dark mode support
+ */
+export const Accordion = React.forwardRef<
+  React.ElementRef<typeof ShadcnAccordion>,
+  AccordionProps
+>((props, ref) => {
+  return <ShadcnAccordion {...props} />
+})
+
+Accordion.displayName = "Accordion"
+
+/**
+ * Re-export Accordion sub-components for composition
+ */
+export { AccordionContent, AccordionItem, AccordionTrigger }

package/components/primitives/Accordion/index.ts

@@ -0,0 +1,13 @@
+export {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "./Accordion"
+
+export type {
+  AccordionProps,
+  AccordionItemProps,
+  AccordionTriggerProps,
+  AccordionContentProps,
+} from "./Accordion"