Signals State Management Patterns

# Signals State Management Patterns for Google Antigravity

Implement modern signals-based state management in your Google Antigravity IDE projects. This comprehensive guide covers signal creation, computed values, effects, and React integration optimized for Gemini 3 agentic development.

## Signal Creation

Create reactive signals:

```typescript
// stores/signals.ts
import { signal, computed, effect, batch } from '@preact/signals-react';

interface Prompt {
  id: string;
  title: string;
  description: string;
  tags: string[];
  starCount: number;
}

// Primitive signals
export const prompts = signal<Prompt[]>([]);
export const searchQuery = signal('');
export const selectedTag = signal<string | null>(null);
export const isLoading = signal(false);
export const error = signal<string | null>(null);

// Computed signals (automatically update)
export const filteredPrompts = computed(() => {
  const search = searchQuery.value.toLowerCase();
  const tag = selectedTag.value;

  return prompts.value.filter((prompt) => {
    const matchesSearch = !search ||
      prompt.title.toLowerCase().includes(search) ||
      prompt.description.toLowerCase().includes(search);
    
    const matchesTag = !tag || prompt.tags.includes(tag);
    
    return matchesSearch && matchesTag;
  });
});

export const promptCount = computed(() => prompts.value.length);

export const starredPrompts = computed(() =>
  prompts.value.filter((p) => p.starCount > 0)
);

export const stats = computed(() => ({
  total: prompts.value.length,
  filtered: filteredPrompts.value.length,
  totalStars: prompts.value.reduce((sum, p) => sum + p.starCount, 0),
}));

// Available tags from prompts
export const availableTags = computed(() => {
  const tags = new Set<string>();
  prompts.value.forEach((p) => p.tags.forEach((t) => tags.add(t)));
  return Array.from(tags).sort();
});
```

## Signal Actions

Define actions for mutations:

```typescript
// stores/actions.ts
import { batch } from '@preact/signals-react';
import { prompts, isLoading, error, searchQuery, selectedTag } from './signals';

export async function fetchPrompts() {
  isLoading.value = true;
  error.value = null;

  try {
    const response = await fetch('/api/prompts');
    if (!response.ok) throw new Error('Failed to fetch');

    const data = await response.json();
    prompts.value = data.prompts;
  } catch (e) {
    error.value = e instanceof Error ? e.message : 'Unknown error';
  } finally {
    isLoading.value = false;
  }
}

export function addPrompt(prompt: Prompt) {
  prompts.value = [prompt, ...prompts.value];
}

export function updatePrompt(id: string, updates: Partial<Prompt>) {
  prompts.value = prompts.value.map((p) =>
    p.id === id ? { ...p, ...updates } : p
  );
}

export function removePrompt(id: string) {
  prompts.value = prompts.value.filter((p) => p.id !== id);
}

// Batch updates for performance
export function resetFilters() {
  batch(() => {
    searchQuery.value = '';
    selectedTag.value = null;
  });
}

export async function starPrompt(id: string) {
  // Optimistic update
  const current = prompts.value.find((p) => p.id === id);
  if (!current) return;

  updatePrompt(id, { starCount: current.starCount + 1 });

  try {
    const response = await fetch(`/api/prompts/${id}/star`, {
      method: 'POST',
    });

    if (!response.ok) {
      // Revert on failure
      updatePrompt(id, { starCount: current.starCount });
    }
  } catch {
    updatePrompt(id, { starCount: current.starCount });
  }
}
```

## Effects for Side Effects

Create reactive effects:

```typescript
// stores/effects.ts
import { effect } from '@preact/signals-react';
import { searchQuery, selectedTag, prompts } from './signals';

// Log filter changes
effect(() => {
  console.log('Search:', searchQuery.value);
  console.log('Tag:', selectedTag.value);
});

// Sync to URL
effect(() => {
  const params = new URLSearchParams();
  
  if (searchQuery.value) {
    params.set('q', searchQuery.value);
  }
  
  if (selectedTag.value) {
    params.set('tag', selectedTag.value);
  }

  const newUrl = params.toString()
    ? `?${params.toString()}`
    : window.location.pathname;

  window.history.replaceState(null, '', newUrl);
});

// Persist to localStorage
effect(() => {
  localStorage.setItem('cached-prompts', JSON.stringify(prompts.value));
});

// Load from localStorage on init
export function initFromStorage() {
  const cached = localStorage.getItem('cached-prompts');
  if (cached) {
    try {
      prompts.value = JSON.parse(cached);
    } catch {
      // Invalid cache
    }
  }
}
```

## React Integration

Use signals in React components:

```typescript
// components/PromptList.tsx
'use client';

import { useEffect } from 'react';
import { useSignals } from '@preact/signals-react/runtime';
import {
  filteredPrompts,
  isLoading,
  stats,
  searchQuery,
  selectedTag,
  availableTags,
} from '@/stores/signals';
import { fetchPrompts, starPrompt, resetFilters } from '@/stores/actions';

export function PromptList() {
  useSignals(); // Enable signals in this component

  useEffect(() => {
    fetchPrompts();
  }, []);

  if (isLoading.value) {
    return <LoadingSkeleton />;
  }

  return (
    <div>
      <div className="stats">
        <span>Showing {stats.value.filtered} of {stats.value.total}</span>
        <span>Total stars: {stats.value.totalStars}</span>
      </div>

      <div className="filters">
        <input
          type="search"
          value={searchQuery.value}
          onChange={(e) => (searchQuery.value = e.target.value)}
          placeholder="Search..."
        />

        <select
          value={selectedTag.value || ''}
          onChange={(e) => (selectedTag.value = e.target.value || null)}
        >
          <option value="">All tags</option>
          {availableTags.value.map((tag) => (
            <option key={tag} value={tag}>{tag}</option>
          ))}
        </select>

        <button onClick={resetFilters}>Reset</button>
      </div>

      <div className="grid">
        {filteredPrompts.value.map((prompt) => (
          <PromptCard
            key={prompt.id}
            prompt={prompt}
            onStar={() => starPrompt(prompt.id)}
          />
        ))}
      </div>
    </div>
  );
}
```

## Best Practices

1. **Use computed** for derived values
2. **Batch updates** for multiple changes
3. **Use effects** for side effects only
4. **Keep signals** at module scope
5. **Call useSignals()** in components
6. **Avoid .value in JSX** templates
7. **Use optimistic updates** for better UX