@hustle-together/api-dev-tools 3.6.5 → 3.10.0

package/templates/component/Component.stories.tsx

@@ -0,0 +1,172 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { __COMPONENT_NAME__ } from './__COMPONENT_NAME__';
+
+/**
+ * __COMPONENT_NAME__ - __COMPONENT_DESCRIPTION__
+ *
+ * This component was created using the Hustle UI Create workflow.
+ */
+const meta: Meta<typeof __COMPONENT_NAME__> = {
+  title: 'Components/__COMPONENT_NAME__',
+  component: __COMPONENT_NAME__,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: '__COMPONENT_DESCRIPTION__',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'destructive', 'outline', 'ghost'],
+      description: 'Visual style variant',
+      table: {
+        defaultValue: { summary: 'primary' },
+      },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size variant',
+      table: {
+        defaultValue: { summary: 'md' },
+      },
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Shows loading spinner',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the component',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    children: {
+      control: 'text',
+      description: 'Content inside the component',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default primary variant
+ */
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Primary __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Secondary variant for less prominent actions
+ */
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Secondary __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Destructive variant for dangerous actions
+ */
+export const Destructive: Story = {
+  args: {
+    variant: 'destructive',
+    children: 'Delete Item',
+  },
+};
+
+/**
+ * Outline variant with border
+ */
+export const Outline: Story = {
+  args: {
+    variant: 'outline',
+    children: 'Outline __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Ghost variant with no background
+ */
+export const Ghost: Story = {
+  args: {
+    variant: 'ghost',
+    children: 'Ghost __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Small size variant
+ */
+export const Small: Story = {
+  args: {
+    size: 'sm',
+    children: 'Small __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Large size variant
+ */
+export const Large: Story = {
+  args: {
+    size: 'lg',
+    children: 'Large __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * Loading state with spinner
+ */
+export const Loading: Story = {
+  args: {
+    loading: true,
+    children: 'Loading...',
+  },
+};
+
+/**
+ * Disabled state
+ */
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    children: 'Disabled __COMPONENT_NAME__',
+  },
+};
+
+/**
+ * All variants displayed together
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex gap-2">
+        <__COMPONENT_NAME__ variant="primary">Primary</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ variant="secondary">Secondary</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ variant="destructive">Destructive</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ variant="outline">Outline</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ variant="ghost">Ghost</__COMPONENT_NAME__>
+      </div>
+      <div className="flex items-center gap-2">
+        <__COMPONENT_NAME__ size="sm">Small</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ size="md">Medium</__COMPONENT_NAME__>
+        <__COMPONENT_NAME__ size="lg">Large</__COMPONENT_NAME__>
+      </div>
+    </div>
+  ),
+};

package/templates/component/Component.test.tsx

@@ -0,0 +1,237 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { __COMPONENT_NAME__ } from './__COMPONENT_NAME__';
+
+describe('__COMPONENT_NAME__', () => {
+  describe('Rendering', () => {
+    it('renders children correctly', () => {
+      render(<__COMPONENT_NAME__>Test Content</__COMPONENT_NAME__>);
+      expect(screen.getByText('Test Content')).toBeInTheDocument();
+    });
+
+    it('renders as a button element', () => {
+      render(<__COMPONENT_NAME__>Click me</__COMPONENT_NAME__>);
+      expect(screen.getByRole('button')).toBeInTheDocument();
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = vi.fn();
+      render(<__COMPONENT_NAME__ ref={ref}>Test</__COMPONENT_NAME__>);
+      expect(ref).toHaveBeenCalled();
+    });
+  });
+
+  describe('Variants', () => {
+    it('applies primary variant by default', () => {
+      const { container } = render(<__COMPONENT_NAME__>Primary</__COMPONENT_NAME__>);
+      expect(container.firstChild).toHaveClass('bg-primary');
+    });
+
+    it('applies secondary variant', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ variant="secondary">Secondary</__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('bg-secondary');
+    });
+
+    it('applies destructive variant', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ variant="destructive">Delete</__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('bg-destructive');
+    });
+
+    it('applies outline variant', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ variant="outline">Outline</__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('border');
+    });
+
+    it('applies ghost variant', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ variant="ghost">Ghost</__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('hover:bg-accent');
+    });
+  });
+
+  describe('Sizes', () => {
+    it('applies medium size by default', () => {
+      const { container } = render(<__COMPONENT_NAME__>Medium</__COMPONENT_NAME__>);
+      expect(container.firstChild).toHaveClass('h-10');
+    });
+
+    it('applies small size', () => {
+      const { container } = render(<__COMPONENT_NAME__ size="sm">Small</__COMPONENT_NAME__>);
+      expect(container.firstChild).toHaveClass('h-8');
+    });
+
+    it('applies large size', () => {
+      const { container } = render(<__COMPONENT_NAME__ size="lg">Large</__COMPONENT_NAME__>);
+      expect(container.firstChild).toHaveClass('h-12');
+    });
+  });
+
+  describe('States', () => {
+    it('handles disabled state', () => {
+      render(<__COMPONENT_NAME__ disabled>Disabled</__COMPONENT_NAME__>);
+      expect(screen.getByRole('button')).toBeDisabled();
+    });
+
+    it('handles loading state', () => {
+      render(<__COMPONENT_NAME__ loading>Loading</__COMPONENT_NAME__>);
+      const button = screen.getByRole('button');
+      expect(button).toBeDisabled();
+      expect(button).toHaveAttribute('aria-busy', 'true');
+    });
+
+    it('shows loading spinner when loading', () => {
+      const { container } = render(<__COMPONENT_NAME__ loading>Loading</__COMPONENT_NAME__>);
+      expect(container.querySelector('svg.animate-spin')).toBeInTheDocument();
+    });
+  });
+
+  describe('Interaction', () => {
+    it('calls onClick when clicked', () => {
+      const handleClick = vi.fn();
+      render(<__COMPONENT_NAME__ onClick={handleClick}>Click</__COMPONENT_NAME__>);
+      fireEvent.click(screen.getByRole('button'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call onClick when disabled', () => {
+      const handleClick = vi.fn();
+      render(
+        <__COMPONENT_NAME__ disabled onClick={handleClick}>
+          Disabled
+        </__COMPONENT_NAME__>
+      );
+      fireEvent.click(screen.getByRole('button'));
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('does not call onClick when loading', () => {
+      const handleClick = vi.fn();
+      render(
+        <__COMPONENT_NAME__ loading onClick={handleClick}>
+          Loading
+        </__COMPONENT_NAME__>
+      );
+      fireEvent.click(screen.getByRole('button'));
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('is focusable', () => {
+      render(<__COMPONENT_NAME__>Focus me</__COMPONENT_NAME__>);
+      const button = screen.getByRole('button');
+      button.focus();
+      expect(button).toHaveFocus();
+    });
+
+    it('is not focusable when disabled', () => {
+      render(<__COMPONENT_NAME__ disabled>Disabled</__COMPONENT_NAME__>);
+      const button = screen.getByRole('button');
+      expect(button).toHaveAttribute('disabled');
+    });
+
+    it('has aria-busy when loading', () => {
+      render(<__COMPONENT_NAME__ loading>Loading</__COMPONENT_NAME__>);
+      expect(screen.getByRole('button')).toHaveAttribute('aria-busy', 'true');
+    });
+  });
+
+  describe('Custom className', () => {
+    it('accepts custom className', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ className="custom-class">Custom</__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('custom-class');
+    });
+
+    it('merges custom className with variant classes', () => {
+      const { container } = render(
+        <__COMPONENT_NAME__ variant="primary" className="custom-class">
+          Merged
+        </__COMPONENT_NAME__>
+      );
+      expect(container.firstChild).toHaveClass('bg-primary');
+      expect(container.firstChild).toHaveClass('custom-class');
+    });
+  });
+
+  // ===================================
+  // Performance Tests (TDD GATES)
+  // These thresholds match .claude/performance-budgets.json
+  // Tests FAIL if exceeded, triggering TDD loop-back
+  // ===================================
+
+  describe('Performance', () => {
+    it('should not re-render excessively on mount', () => {
+      let renderCount = 0;
+
+      const TestWrapper = () => {
+        renderCount++;
+        return <__COMPONENT_NAME__>Test</__COMPONENT_NAME__>;
+      };
+
+      render(<TestWrapper />);
+
+      // THRESHOLD: Mount renders max 1
+      // If this fails, check for: useEffect dependencies, state initialization
+      expect(renderCount).toBeLessThanOrEqual(1);
+    });
+
+    it('should not re-render excessively on prop change', () => {
+      let renderCount = 0;
+
+      const TestWrapper = ({ variant }: { variant: 'primary' | 'secondary' }) => {
+        renderCount++;
+        return <__COMPONENT_NAME__ variant={variant}>Test</__COMPONENT_NAME__>;
+      };
+
+      const { rerender } = render(<TestWrapper variant="primary" />);
+      renderCount = 0; // Reset after initial render
+
+      rerender(<TestWrapper variant="secondary" />);
+
+      // THRESHOLD: Prop change renders max 1
+      // If this fails, check for: missing useMemo/useCallback, unstable references
+      expect(renderCount).toBeLessThanOrEqual(1);
+    });
+
+    it('should not cause unnecessary re-renders with same props', () => {
+      let renderCount = 0;
+
+      const TestWrapper = ({ variant }: { variant: 'primary' }) => {
+        renderCount++;
+        return <__COMPONENT_NAME__ variant={variant}>Test</__COMPONENT_NAME__>;
+      };
+
+      const { rerender } = render(<TestWrapper variant="primary" />);
+      renderCount = 0; // Reset after initial render
+
+      // Rerender with SAME props
+      rerender(<TestWrapper variant="primary" />);
+
+      // THRESHOLD: Same-prop renders max 0 (should be memoized)
+      // If this fails, consider wrapping component with React.memo
+      // Note: This is a warning, not a hard fail in some cases
+      expect(renderCount).toBeLessThanOrEqual(1);
+    });
+
+    it('should render within time budget', () => {
+      const startTime = performance.now();
+
+      render(<__COMPONENT_NAME__>Performance Test</__COMPONENT_NAME__>);
+
+      const renderTime = performance.now() - startTime;
+
+      // THRESHOLD: Initial render max 16ms (one frame at 60fps)
+      // If this fails, check for: expensive computations, large DOM trees
+      expect(renderTime).toBeLessThan(16);
+    });
+  });
+});

package/templates/component/Component.tsx

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+import type { __COMPONENT_NAME__Props } from './__COMPONENT_NAME__.types';
+
+/**
+ * __COMPONENT_NAME__ variants using class-variance-authority
+ * Customize variants based on interview decisions
+ */
+const __COMPONENT_NAME_LOWER__Variants = cva(
+  // Base styles - apply brand guide values
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-base',
+        lg: 'h-12 px-6 text-lg',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  }
+);
+
+/**
+ * __COMPONENT_NAME__ component
+ *
+ * @description __COMPONENT_DESCRIPTION__
+ *
+ * @example
+ * ```tsx
+ * <__COMPONENT_NAME__ variant="primary" size="md">
+ *   Click me
+ * </__COMPONENT_NAME__>
+ * ```
+ */
+export const __COMPONENT_NAME__ = React.forwardRef<
+  HTMLButtonElement,
+  __COMPONENT_NAME__Props
+>(({ variant, size, loading, disabled, className, children, ...props }, ref) => {
+  return (
+    <button
+      ref={ref}
+      className={cn(__COMPONENT_NAME_LOWER__Variants({ variant, size }), className)}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      {...props}
+    >
+      {loading && (
+        <svg
+          className="mr-2 h-4 w-4 animate-spin"
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+        >
+          <circle
+            className="opacity-25"
+            cx="12"
+            cy="12"
+            r="10"
+            stroke="currentColor"
+            strokeWidth="4"
+          />
+          <path
+            className="opacity-75"
+            fill="currentColor"
+            d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+          />
+        </svg>
+      )}
+      {children}
+    </button>
+  );
+});
+
+__COMPONENT_NAME__.displayName = '__COMPONENT_NAME__';

package/templates/component/Component.types.ts

@@ -0,0 +1,55 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { ComponentPropsWithoutRef } from 'react';
+
+/**
+ * __COMPONENT_NAME__ variant configuration
+ * Generated from interview decisions
+ */
+export type __COMPONENT_NAME__Variant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost';
+
+/**
+ * __COMPONENT_NAME__ size configuration
+ */
+export type __COMPONENT_NAME__Size = 'sm' | 'md' | 'lg';
+
+/**
+ * Props for the __COMPONENT_NAME__ component
+ *
+ * @property variant - Visual style variant
+ * @property size - Size variant
+ * @property loading - Shows loading spinner and disables interaction
+ * @property disabled - Disables the component
+ * @property className - Additional CSS classes
+ * @property children - Content to render inside the component
+ */
+export interface __COMPONENT_NAME__Props
+  extends ComponentPropsWithoutRef<'button'> {
+  /**
+   * Visual style variant
+   * @default 'primary'
+   */
+  variant?: __COMPONENT_NAME__Variant;
+
+  /**
+   * Size variant
+   * @default 'md'
+   */
+  size?: __COMPONENT_NAME__Size;
+
+  /**
+   * Shows loading spinner and disables interaction
+   * @default false
+   */
+  loading?: boolean;
+
+  /**
+   * Disables the component
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Content to render inside the component
+   */
+  children: React.ReactNode;
+}

package/templates/component/index.ts

@@ -0,0 +1,15 @@
+/**
+ * __COMPONENT_NAME__ Component
+ *
+ * @description __COMPONENT_DESCRIPTION__
+ * @see {@link ./README.md} for usage documentation
+ *
+ * Created with Hustle UI Create workflow (v3.9.0)
+ */
+
+export { __COMPONENT_NAME__ } from './__COMPONENT_NAME__';
+export type {
+  __COMPONENT_NAME__Props,
+  __COMPONENT_NAME__Variant,
+  __COMPONENT_NAME__Size,
+} from './__COMPONENT_NAME__.types';