@umituz/web-design-system 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "private": false,
   "description": "Web Design System - Atomic Design components (Atoms, Molecules, Organisms, Templates) for React applications",
   "main": "./src/index.ts",

package/src/presentation/molecules/ActiveFilterTags.tsx

@@ -0,0 +1,83 @@
+/**
+ * ActiveFilterTags Component (Molecule)
+ * @description Display active filters with remove buttons
+ */
+
+import type { BaseProps } from '../../domain/types';
+
+export interface ActiveFilterTagsProps extends BaseProps {
+  selectedCategory: string | null;
+  categories: Array<{ id: string; name: string }>;
+  selectedTags: string[];
+  onCategoryRemove: () => void;
+  onTagRemove: (tag: string) => void;
+  onClearAll: () => void;
+}
+
+export const ActiveFilterTags = ({
+  selectedCategory,
+  categories,
+  selectedTags,
+  onCategoryRemove,
+  onTagRemove,
+  onClearAll,
+  className,
+}: ActiveFilterTagsProps) => {
+  const categoryName = selectedCategory
+    ? categories.find(c => c.id === selectedCategory)?.name
+    : null;
+
+  if (!selectedCategory && selectedTags.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={`hidden lg:flex flex-wrap items-center gap-2 mb-4 md:mb-6 ${className || ''}`}>
+      <span className="text-sm text-text-secondary">Active filters:</span>
+
+      {/* Category Tag */}
+      {categoryName && (
+        <span className="inline-flex items-center gap-1 px-3 py-1.5 bg-primary-light text-text-primary rounded-full text-xs font-medium">
+          {categoryName}
+          <button
+            onClick={onCategoryRemove}
+            className="ml-1 hover:opacity-70 transition-opacity"
+            aria-label={`Remove ${categoryName} filter`}
+          >
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M18 6L6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </span>
+      )}
+
+      {/* Tag Buttons */}
+      {selectedTags.map((tag) => (
+        <span
+          key={tag}
+          className="inline-flex items-center gap-1 px-3 py-1.5 bg-bg-secondary text-text-primary rounded-full text-xs font-medium border border-border"
+        >
+          {tag}
+          <button
+            onClick={() => onTagRemove(tag)}
+            className="ml-1 hover:opacity-70 transition-opacity"
+            aria-label={`Remove ${tag} filter`}
+          >
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M18 6L6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </span>
+      ))}
+
+      {/* Clear All Button */}
+      <button
+        onClick={onClearAll}
+        className="px-3 py-1.5 text-primary-light hover:underline text-xs font-medium"
+        type="button"
+      >
+        Clear all
+      </button>
+    </div>
+  );
+};

package/src/presentation/molecules/Breadcrumb.tsx

@@ -0,0 +1,53 @@
+/**
+ * Breadcrumb Component (Molecule)
+ * @description Navigation breadcrumb with home icon
+ */
+
+import { Link } from 'react-router-dom';
+import type { BaseProps } from '../../domain/types';
+
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+export interface BreadcrumbProps extends BaseProps {
+  items: BreadcrumbItem[];
+}
+
+export const Breadcrumb = ({ items, className }: BreadcrumbProps) => {
+  return (
+    <nav className={`flex items-center gap-2 text-sm mb-4 md:mb-6 ${className || ''}`} aria-label="Breadcrumb">
+      {/* Home */}
+      <Link
+        to="/"
+        className="flex items-center gap-1 text-text-secondary hover:text-primary-light transition-colors"
+        aria-label="Home"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+          <polyline points="9 22 9 12 15 12 15 22" />
+        </svg>
+      </Link>
+
+      {/* Breadcrumb items */}
+      {items.map((item, index) => (
+        <div key={index} className="flex items-center gap-2">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="text-text-secondary">
+            <polyline points="9 18 15 12 9 6" />
+          </svg>
+          {item.href ? (
+            <Link
+              to={item.href}
+              className="text-text-secondary hover:text-primary-light transition-colors"
+            >
+              {item.label}
+            </Link>
+          ) : (
+            <span className="text-text-primary font-medium">{item.label}</span>
+          )}
+        </div>
+      ))}
+    </nav>
+  );
+};

package/src/presentation/molecules/CodeBlock.tsx

@@ -0,0 +1,144 @@
+/**
+ * CodeBlock Component (Molecule)
+ * @description Syntax-highlighted code block with copy button and expand/collapse
+ */
+
+import { useState, useEffect } from 'react';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import type { BaseProps } from '../../domain/types';
+
+export interface CodeBlockProps extends BaseProps {
+  children: string;
+  language?: string;
+  filename?: string;
+  showLineNumbers?: boolean;
+}
+
+export const CodeBlock = ({
+  children,
+  language = 'javascript',
+  filename,
+  showLineNumbers = false,
+  className,
+}: CodeBlockProps) => {
+  const [copied, setCopied] = useState(false);
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  // Cleanup copy timeout
+  useEffect(() => {
+    if (copied) {
+      const timeout = setTimeout(() => setCopied(false), 2000);
+      return () => clearTimeout(timeout);
+    }
+  }, [copied]);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(children);
+      setCopied(true);
+    } catch (error) {
+      console.error('Failed to copy code:', error);
+    }
+  };
+
+  // Auto-detect language if not provided
+  const detectedLanguage = language || 'javascript';
+
+  // Check if code is long enough for collapse
+  const lineCount = children.split('\n').length;
+  const isLongCode = lineCount > 10;
+
+  return (
+    <div className={`my-6 rounded-lg border border-border overflow-hidden bg-bg-card transition-theme ${className || ''}`}>
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-2 bg-bg-tertiary border-b border-border">
+        <div className="flex items-center gap-2">
+          {filename && (
+            <span className="text-xs font-medium text-text-secondary">{filename}</span>
+          )}
+          <span className="text-xs px-2 py-1 bg-bg-primary text-text-primary rounded-md font-medium">
+            {detectedLanguage}
+          </span>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {isLongCode && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="p-1 text-text-secondary hover:text-text-primary rounded transition-colors"
+              title={isExpanded ? 'Collapse' : 'Expand'}
+              type="button"
+              aria-label={isExpanded ? 'Collapse code' : 'Expand code'}
+            >
+              {isExpanded ? (
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                  <polyline points="18 15 12 9 6 15" />
+                </svg>
+              ) : (
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                  <polyline points="6 9 12 15 18 9" />
+                </svg>
+              )}
+            </button>
+          )}
+
+          <button
+            onClick={handleCopy}
+            className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-lg transition-all ${
+              copied
+                ? 'bg-green-500 text-white'
+                : 'bg-bg-secondary text-text-primary hover:bg-bg-tertiary border border-border'
+            }`}
+            title={copied ? 'Copied!' : 'Copy code'}
+            type="button"
+            aria-label={copied ? 'Code copied' : 'Copy code'}
+          >
+            {copied ? (
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <polyline points="20 6 9 17 4 12" />
+              </svg>
+            ) : (
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+              </svg>
+            )}
+            <span className="hidden sm:inline">{copied ? 'Copied!' : 'Copy'}</span>
+          </button>
+        </div>
+      </div>
+
+      {/* Code */}
+      <div className={isLongCode && !isExpanded ? 'max-h-80 overflow-hidden' : ''}>
+        <SyntaxHighlighter
+          language={detectedLanguage}
+          style={vscDarkPlus}
+          showLineNumbers={showLineNumbers}
+          customStyle={{
+            margin: 0,
+            borderRadius: 0,
+            fontSize: '14px',
+            background: 'transparent',
+          }}
+        >
+          {children}
+        </SyntaxHighlighter>
+      </div>
+
+      {/* Expand hint for collapsed code */}
+      {isLongCode && !isExpanded && (
+        <div className="px-4 py-2 bg-bg-secondary text-center border-t border-border">
+          <button
+            onClick={() => setIsExpanded(true)}
+            className="text-sm text-primary-light hover:underline font-medium"
+            type="button"
+            aria-label={`Show all ${lineCount} lines`}
+          >
+            Show all {lineCount} lines
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/presentation/molecules/index.ts

@@ -37,3 +37,13 @@ export { ScrollArea, ScrollBar } from './ScrollArea';
 
 export { ListItem } from './ListItem';
 export type { ListItemProps } from './ListItem';
+
+// NEW: Filter & Navigation Components
+export { ActiveFilterTags } from './ActiveFilterTags';
+export type { ActiveFilterTagsProps } from './ActiveFilterTags';
+
+export { Breadcrumb } from './Breadcrumb';
+export type { BreadcrumbProps, BreadcrumbItem } from './Breadcrumb';
+
+export { CodeBlock } from './CodeBlock';
+export type { CodeBlockProps } from './CodeBlock';

package/src/presentation/organisms/Comments.tsx

@@ -0,0 +1,103 @@
+/**
+ * Comments Component (Organism)
+ * @description Giscus-based GitHub Discussions comment widget
+ */
+
+import { useEffect, useRef } from 'react';
+import { cn } from '../../infrastructure/utils';
+import type { BaseProps } from '../../domain/types';
+
+export interface GiscusConfig {
+  repo: string;
+  repoId: string;
+  category?: string;
+  mapping?: 'pathname' | 'url' | 'title' | 'og:title' | 'custom';
+  term?: string;
+  strict?: '0' | '1';
+  reactionsEnabled?: '0' | '1';
+  emitMetadata?: '0' | '1';
+  inputPosition?: 'top' | 'bottom';
+  theme?: 'light' | 'dark' | 'dark_dimmed' | 'transparent_dark' | 'preferred_color_scheme';
+  lang?: string;
+}
+
+export interface CommentsProps extends BaseProps {
+  slug: string;
+  config?: Partial<GiscusConfig>;
+  title?: string;
+  description?: string;
+}
+
+declare global {
+  interface Window {
+    giscus?: {
+      render: (element: HTMLElement, config: Record<string, unknown>) => void;
+    };
+  }
+}
+
+export const Comments = ({
+  slug,
+  config,
+  title = 'Comments',
+  description = 'Join the discussion! Share your thoughts and questions below.',
+  className,
+}: CommentsProps) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // Load Giscus script dynamically
+    const script = document.createElement('script');
+    script.src = 'https://giscus.app/client.js';
+    script.async = true;
+    script.crossOrigin = 'anonymous';
+
+    script.addEventListener('load', () => {
+      if (window.giscus && rootRef.current) {
+        const defaultConfig: GiscusConfig = {
+          repo: 'umituz/umituz-apps',
+          repoId: 'R_kgDONJ7RJw',
+          category: 'Announcements',
+          mapping: 'pathname',
+          term: slug,
+          strict: '0',
+          reactionsEnabled: '1',
+          emitMetadata: '0',
+          inputPosition: 'top',
+          theme: 'dark',
+          lang: 'en',
+          ...config,
+        };
+
+        window.giscus.render(rootRef.current, defaultConfig);
+      }
+    });
+
+    document.head.appendChild(script);
+
+    return () => {
+      // Only remove if script exists and is in DOM
+      if (script.parentNode === document.head) {
+        document.head.removeChild(script);
+      }
+    };
+  }, [slug, config]);
+
+  return (
+    <div className={cn('mt-8', className)}>
+      <div className="bg-bg-card rounded-xl p-6 border border-border transition-theme">
+        <h3 className="text-xl font-bold text-text-primary mb-4">{title}</h3>
+        <p className="text-text-secondary text-sm mb-4">
+          {description}
+        </p>
+        <div
+          ref={rootRef}
+          id="giscus-comments"
+          className="min-h-[200px]"
+        />
+      </div>
+    </div>
+  );
+};
+
+Comments.displayName = 'Comments';

package/src/presentation/organisms/FilterBar.tsx

@@ -0,0 +1,186 @@
+/**
+ * FilterBar Component (Organism)
+ * @description Mobile filter bar with search, categories, tags, and sort
+ */
+
+import { useState } from 'react';
+import type { BaseProps } from '../../domain/types';
+
+export interface Category {
+  id: string;
+  name: string;
+  count: number;
+  icon: React.ComponentType<{ className?: string; size?: number }>;
+}
+
+export interface SortOption {
+  id: string;
+  name: string;
+}
+
+export interface FilterBarProps extends BaseProps {
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  selectedCategory: string | null;
+  onCategoryChange: (category: string) => void;
+  categories: Category[];
+  popularTags: string[];
+  selectedTags: string[];
+  onTagToggle: (tag: string) => void;
+  sortBy: string;
+  onSortChange: (sort: string) => void;
+  sortOptions: readonly SortOption[] | SortOption[];
+  hasActiveFilters: boolean;
+  onClearFilters: () => void;
+}
+
+export const FilterBar = ({
+  searchQuery,
+  setSearchQuery,
+  selectedCategory,
+  onCategoryChange,
+  categories,
+  popularTags,
+  selectedTags,
+  onTagToggle,
+  sortBy,
+  onSortChange,
+  sortOptions,
+  hasActiveFilters,
+  onClearFilters,
+  className,
+}: FilterBarProps) => {
+  const [isFilterOpen, setIsFilterOpen] = useState(false);
+
+  return (
+    <div className={`lg:hidden mb-4 space-y-3 ${className || ''}`}>
+      {/* Search */}
+      <div className="relative">
+        <svg
+          className="absolute left-3 top-1/2 -translate-y-1/2 text-text-secondary"
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="11" cy="11" r="8" />
+          <path d="m21 21-4.35-4.35" />
+        </svg>
+        <input
+          type="text"
+          placeholder="Search..."
+          value={searchQuery}
+          onChange={(e) => setSearchQuery(e.target.value)}
+          className="w-full pl-10 pr-4 py-2.5 bg-bg-secondary text-text-primary rounded-lg border border-border focus:border-primary-light focus:outline-none placeholder-text-secondary/50 transition-theme text-sm"
+          aria-label="Search"
+        />
+      </div>
+
+      {/* Filter Toggle + Sort + Clear Filters */}
+      <div className="flex items-center gap-2 flex-wrap">
+        <button
+          onClick={() => setIsFilterOpen(!isFilterOpen)}
+          className="flex items-center gap-2 px-4 py-2.5 bg-bg-secondary text-text-primary rounded-lg border border-border hover:border-primary-light transition-all text-sm font-medium transition-theme"
+          type="button"
+          aria-expanded={isFilterOpen}
+          aria-label="Toggle filters"
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M12 20v-6M6 20V10M18 20V4" />
+          </svg>
+          Filters
+          {(selectedCategory || selectedTags.length > 0) && (
+            <span className="ml-1 px-2 py-0.5 bg-primary-light text-text-primary text-xs rounded-full">
+              {[selectedCategory, ...selectedTags].filter(Boolean).length}
+            </span>
+          )}
+        </button>
+
+        {/* Sort Dropdown */}
+        <select
+          value={sortBy}
+          onChange={(e) => onSortChange(e.target.value)}
+          className="px-3 py-2.5 bg-bg-secondary text-text-primary rounded-lg border border-border focus:border-primary-light focus:outline-none transition-theme text-sm"
+          aria-label="Sort by"
+        >
+          {sortOptions.map((option) => (
+            <option key={option.id} value={option.id}>
+              {option.name}
+            </option>
+          ))}
+        </select>
+
+        {/* Clear Filters */}
+        {hasActiveFilters && (
+          <button
+            onClick={onClearFilters}
+            className="px-3 py-2.5 text-text-secondary hover:text-text-primary text-sm transition-colors"
+            type="button"
+          >
+            Clear All
+          </button>
+        )}
+      </div>
+
+      {/* Mobile Filter Drawer */}
+      {isFilterOpen && (
+        <div className="bg-bg-card rounded-xl p-4 border border-border space-y-4 transition-theme">
+          {/* Categories */}
+          <div>
+            <h4 className="text-sm font-semibold text-text-primary mb-3">Categories</h4>
+            <div className="grid grid-cols-2 gap-2">
+              {categories.map((category) => {
+                const Icon = category.icon;
+                const isActive = selectedCategory === category.id;
+                return (
+                  <button
+                    key={category.id}
+                    onClick={() => {
+                      onCategoryChange(category.id);
+                    }}
+                    className={`flex items-center gap-2 px-3 py-2 rounded-lg text-xs transition-all transition-theme ${
+                      isActive
+                        ? 'bg-primary-light text-text-primary font-medium'
+                        : 'bg-bg-secondary text-text-secondary hover:bg-bg-tertiary hover:text-text-primary'
+                    }`}
+                    type="button"
+                    aria-pressed={isActive}
+                  >
+                    <Icon size={14} />
+                    <span>{category.name}</span>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+
+          {/* Popular Tags */}
+          <div>
+            <h4 className="text-sm font-semibold text-text-primary mb-3">Popular Tags</h4>
+            <div className="flex flex-wrap gap-2">
+              {popularTags.map((tag) => (
+                <button
+                  key={tag}
+                  onClick={() => onTagToggle(tag)}
+                  className={`px-3 py-1.5 rounded-full text-xs font-medium transition-all transition-theme ${
+                    selectedTags.includes(tag)
+                      ? 'bg-primary-light text-text-primary'
+                      : 'bg-bg-secondary text-text-secondary hover:bg-bg-tertiary hover:text-text-primary'
+                  }`}
+                  type="button"
+                  aria-pressed={selectedTags.includes(tag)}
+                >
+                  {tag}
+                </button>
+              ))}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/presentation/organisms/FilterSidebar.tsx

@@ -0,0 +1,170 @@
+/**
+ * FilterSidebar Component (Organism)
+ * @description Desktop sidebar with search, categories, tags, and sort options
+ */
+
+import type { BaseProps, ChildrenProps } from '../../domain/types';
+
+export interface Category {
+  id: string;
+  name: string;
+  count: number;
+  icon: React.ComponentType<{ className?: string; size?: number }>;
+}
+
+export interface SortOption {
+  id: string;
+  name: string;
+}
+
+export interface FilterSidebarProps extends BaseProps, ChildrenProps {
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  selectedCategory: string | null;
+  onCategoryChange: (category: string) => void;
+  categories: Category[];
+  popularTags: string[];
+  selectedTags: string[];
+  onTagToggle: (tag: string) => void;
+  sortBy: string;
+  onSortChange: (sort: string) => void;
+  sortOptions: readonly SortOption[] | SortOption[];
+  hasActiveFilters: boolean;
+  onClearFilters: () => void;
+}
+
+export const FilterSidebar = ({
+  searchQuery,
+  setSearchQuery,
+  selectedCategory,
+  onCategoryChange,
+  categories,
+  popularTags,
+  selectedTags,
+  onTagToggle,
+  sortBy,
+  onSortChange,
+  sortOptions,
+  hasActiveFilters,
+  onClearFilters,
+  children,
+  className,
+}: FilterSidebarProps) => {
+  return (
+    <aside className={`hidden lg:block w-64 flex-shrink-0 ${className || ''}`}>
+      <div className="sticky top-24 space-y-6">
+        {/* Search */}
+        <div className="relative">
+          <svg
+            className="absolute left-3 top-1/2 -translate-y-1/2 text-text-secondary"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.35-4.35" />
+          </svg>
+          <input
+            type="text"
+            placeholder="Search..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="w-full pl-10 pr-4 py-2.5 bg-bg-secondary text-text-primary rounded-lg border border-border focus:border-primary-light focus:outline-none placeholder-text-secondary/50 transition-theme text-sm"
+            aria-label="Search"
+          />
+        </div>
+
+        {/* Categories */}
+        <div>
+          <h3 className="text-sm font-semibold text-text-primary mb-3">Categories</h3>
+          <div className="space-y-1">
+            {categories.map((category) => {
+              const Icon = category.icon;
+              const isActive = selectedCategory === category.id;
+              return (
+                <button
+                  key={category.id}
+                  onClick={() => onCategoryChange(category.id)}
+                  className={`w-full flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-all transition-theme ${
+                    isActive
+                      ? 'bg-primary-light text-text-primary font-medium'
+                      : 'text-text-secondary hover:bg-bg-secondary hover:text-text-primary'
+                  }`}
+                  type="button"
+                  aria-pressed={isActive}
+                >
+                  <Icon size={16} />
+                  <span className="flex-1 text-left">{category.name}</span>
+                  <span className={`text-xs ${isActive ? 'text-text-primary' : 'text-text-secondary'}`}>
+                    {category.count}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+
+        {/* Popular Tags */}
+        <div>
+          <h3 className="text-sm font-semibold text-text-primary mb-3">Popular Tags</h3>
+          <div className="flex flex-wrap gap-2">
+            {popularTags.map((tag) => (
+              <button
+                key={tag}
+                onClick={() => onTagToggle(tag)}
+                className={`px-3 py-1.5 rounded-full text-xs font-medium transition-all transition-theme ${
+                  selectedTags.includes(tag)
+                    ? 'bg-primary-light text-text-primary'
+                    : 'bg-bg-secondary text-text-secondary hover:bg-bg-tertiary hover:text-text-primary'
+                }`}
+                type="button"
+                aria-pressed={selectedTags.includes(tag)}
+              >
+                {tag}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Sort */}
+        <div>
+          <h3 className="text-sm font-semibold text-text-primary mb-3">Sort By</h3>
+          <select
+            value={sortBy}
+            onChange={(e) => onSortChange(e.target.value)}
+            className="w-full px-3 py-2.5 bg-bg-secondary text-text-primary rounded-lg border border-border focus:border-primary-light focus:outline-none transition-theme text-sm"
+            aria-label="Sort by"
+          >
+            {sortOptions.map((option) => (
+              <option key={option.id} value={option.id}>
+                {option.name}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {/* Additional Content */}
+        {children}
+
+        {/* Clear Filters */}
+        {hasActiveFilters && (
+          <button
+            onClick={onClearFilters}
+            className="w-full flex items-center justify-center gap-2 px-4 py-2.5 bg-bg-secondary text-text-secondary rounded-lg border border-border hover:border-primary-light hover:text-text-primary transition-all text-sm font-medium transition-theme"
+            type="button"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M18 6L6 18M6 6l12 12" />
+            </svg>
+            Clear All Filters
+          </button>
+        )}
+      </div>
+    </aside>
+  );
+};

package/src/presentation/organisms/NewsletterSignup.tsx

@@ -0,0 +1,165 @@
+/**
+ * NewsletterSignup Component (Organism)
+ * @description Newsletter subscription form with email validation
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import { cn } from '../../infrastructure/utils';
+import type { BaseProps } from '../../domain/types';
+import { Icon } from '../atoms/Icon';
+
+const SUBSCRIBER_COUNT_MIN = 1000;
+const SUBSCRIBER_COUNT_MAX = 6000;
+
+export interface NewsletterSignupProps extends BaseProps {
+  onSubscribe?: (email: string) => Promise<void>;
+  subscriberCountMin?: number;
+  subscriberCountMax?: number;
+}
+
+export const NewsletterSignup = ({
+  onSubscribe,
+  subscriberCountMin = SUBSCRIBER_COUNT_MIN,
+  subscriberCountMax = SUBSCRIBER_COUNT_MAX,
+  className,
+}: NewsletterSignupProps) => {
+  const [email, setEmail] = useState('');
+  const [isSubscribed, setIsSubscribed] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  // FIXED: Generate random count per component instance, not at module load
+  const subscriberCount = useMemo(
+    () => Math.floor(Math.random() * (subscriberCountMax - subscriberCountMin + 1)) + subscriberCountMin,
+    [subscriberCountMin, subscriberCountMax]
+  );
+
+  const validateEmail = (email: string) => {
+    const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return re.test(email);
+  };
+
+  // Reset success message after 5 seconds with cleanup
+  useEffect(() => {
+    if (isSubscribed) {
+      const timeout = setTimeout(() => {
+        setIsSubscribed(false);
+      }, 5000);
+      return () => clearTimeout(timeout);
+    }
+  }, [isSubscribed]);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError('');
+
+    // Validate email
+    if (!email) {
+      setError('Please enter your email address');
+      return;
+    }
+
+    if (!validateEmail(email)) {
+      setError('Please enter a valid email address');
+      return;
+    }
+
+    setIsLoading(true);
+
+    try {
+      // Call the subscribe function if provided
+      if (onSubscribe) {
+        await onSubscribe(email);
+      } else {
+        // Simulate API call for demo purposes
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+
+      setIsLoading(false);
+      setIsSubscribed(true);
+      setEmail('');
+    } catch (err) {
+      setIsLoading(false);
+      setError('Failed to subscribe. Please try again.');
+    }
+  };
+
+  if (isSubscribed) {
+    return (
+      <div className={cn('bg-bg-card rounded-xl p-4 border border-border', className)}>
+        <div className="flex items-center gap-3 text-green-600">
+          <Icon className="text-green-600" size="lg">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </Icon>
+          <div>
+            <div className="font-semibold text-sm">Thanks for subscribing!</div>
+            <div className="text-xs text-text-secondary">Check your inbox to confirm your subscription</div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('bg-bg-card rounded-xl p-4 border border-border', className)}>
+      <div className="flex items-center gap-2 mb-3">
+        <Icon className="text-primary-light" size="lg">
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={2}
+            d="M3 8l7.89 5.26a2 2 0 002.22 0l7.89-5.26a2 2 0 002.22 0L21 8V5a2 2 0 00-2-2H5a2 2 0 00-2 2v3a2 2 0 002.22 0z"
+          />
+        </Icon>
+        <h3 className="text-sm font-semibold text-text-primary">Newsletter</h3>
+      </div>
+      <p className="text-xs text-text-secondary mb-3">
+        Get the latest articles delivered straight to your inbox. No spam, ever.
+      </p>
+      <form onSubmit={handleSubmit} className="space-y-2">
+        <input
+          type="email"
+          placeholder="your@email.com"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          className="w-full px-3 py-2 bg-bg-secondary text-text-primary rounded-lg border border-border focus:border-primary-light focus:outline-none placeholder-text-secondary/50 transition-theme text-sm"
+          disabled={isLoading}
+        />
+        {error && (
+          <p className="text-xs text-red-500">{error}</p>
+        )}
+        <button
+          type="submit"
+          disabled={isLoading}
+          className="w-full flex items-center justify-center gap-2 px-4 py-2 bg-primary-gradient text-text-primary rounded-lg font-medium hover:shadow-lg transition-all disabled:opacity-50 disabled:cursor-not-allowed text-sm"
+        >
+          {isLoading ? (
+            <>Subscribing...</>
+          ) : (
+            <>
+              <Icon size="sm">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M22 2L11 13M22 2l-7 20M2 2l15 15L2 2l15-15"
+                />
+              </Icon>
+              Subscribe
+            </>
+          )}
+        </button>
+      </form>
+      <p className="text-xs text-text-secondary mt-2">
+        Join {subscriberCount.toLocaleString()}+ subscribers
+      </p>
+    </div>
+  );
+};
+
+NewsletterSignup.displayName = 'NewsletterSignup';

package/src/presentation/organisms/index.ts

@@ -135,3 +135,17 @@ export { ToggleGroup, ToggleGroupItem } from './ToggleGroup';
 // NEW: Media & Content Components
 export { ImageLightbox } from './ImageLightbox';
 export type { ImageLightboxProps, ImageLightboxImage } from './ImageLightbox';
+
+// NEW: Content & Engagement Components
+export { NewsletterSignup } from './NewsletterSignup';
+export type { NewsletterSignupProps } from './NewsletterSignup';
+
+export { Comments } from './Comments';
+export type { CommentsProps, GiscusConfig } from './Comments';
+
+// NEW: Filter Components
+export { FilterBar } from './FilterBar';
+export type { FilterBarProps, Category, SortOption } from './FilterBar';
+
+export { FilterSidebar } from './FilterSidebar';
+export type { FilterSidebarProps } from './FilterSidebar';