chore: add building-blocks skill

Author: bartstc

.agents/skills/building-blocks/README.md

@@ -0,0 +1,56 @@
+# Frontend Building Blocks
+
+A structured catalog of typed frontend building blocks, optimized for AI agents.
+
+## Structure
+
+- `rules/` — Individual building block files (one per block)
+- `metadata.json` — Catalog metadata (version, categories)
+- **`SKILL.md`** — Skill definition with progressive disclosure index
+
+## Building Block Categories
+
+| Category           | Blocks | Description                                                                    |
+| ------------------ | ------ | ------------------------------------------------------------------------------ |
+| Data Fetching      | 4      | Query factories, mutations, keys, DTOs                                         |
+| State Management   | 2      | Zustand stores, React Context providers                                        |
+| App Orchestration  | 1      | Use case hooks composing mutations + notifications                             |
+| Component Patterns | 6      | Pure components, compound components, pages, HOCs, facade hooks, named effects |
+| Data Modeling      | 2      | Frontend models, value objects                                                 |
+
+## How It Works
+
+1. Agent reads `SKILL.md` — gets the catalog index with short summaries
+2. When implementing a specific block, agent reads `rules/{block-name}.md`
+
+## Creating a New Building Block
+
+1. Create `rules/{block-name}.md`
+2. Add frontmatter with `title`, `category`, `layer`, `composedWith`
+3. Include: description, constraints, and a canonical code example
+4. Update the catalog table in `SKILL.md`
+
+## Block File Structure
+
+```markdown
+---
+title: Block Display Name
+category: Data Fetching | State Management | App Orchestration | Component Patterns | Data Modeling
+layer: providers/ | application/ | components/ | models/ | lib/api/ | pages/
+composedWith: other-block-1, other-block-2
+---
+
+## Block Display Name
+
+Description of what this block does, when to use it, and why.
+
+### Constraints
+
+- Hard rules for this block type
+
+### Example
+
+\`\`\`tsx
+// Canonical implementation example
+\`\`\`
+```

.agents/skills/building-blocks/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: building-blocks
+description: Frontend building block catalog — typed patterns for components, hooks, queries, mutations, stores, and models used across the project. Use this skill whenever implementing, reviewing, or planning feature code, API integrations, state management, component patterns, or data modeling within src/features/ or src/lib/. Also triggers for architectural decisions about where code should live or which pattern to apply.
+---
+
+# Frontend Building Blocks
+
+Typed catalog of building blocks used in this project. Each block has a fixed name, layer, composition rules, and canonical example.
+
+## How to Use
+
+Read the rule file for each block you are about to implement. The summaries below are for routing — the rule files contain the full pattern.
+
+## Block Catalog
+
+### Data Fetching
+
+| Block                   | Layer        | Summary                                                                                                              | File                             |
+| ----------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `mutation-hook`         | `providers/` | Server write via `useMutation` with domain error translation and cache invalidation. Returns `[handler, isPending]`. | `rules/mutation-hook.md`         |
+| `query-options-factory` | `lib/api/`   | Reusable `queryOptions()` factories — no hooks, no `useQuery`. Hook composition belongs in `providers/`.             | `rules/query-options-factory.md` |
+| `query-keys-factory`    | `lib/api/`   | Hierarchical `as const` key tuples per resource. Single source of truth for cache invalidation.                      | `rules/query-keys-factory.md`    |
+| `dto-model`             | `lib/api/`   | TypeScript interfaces mirroring the raw API wire format. No transformations.                                         | `rules/dto-model.md`             |
+
+### State Management
+
+| Block      | Layer          | Summary                                                                                            | File                |
+| ---------- | -------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| `store`    | `application/` | Zustand store — small, focused, selector-only subscriptions. Actions live inside the store.        | `rules/store.md`    |
+| `provider` | `providers/`   | Thin React Context wrapper for dependency injection. No logic — delivers state, doesn't manage it. | `rules/provider.md` |
+
+### App Orchestration
+
+| Block           | Layer          | Summary                                                                                          | File                     |
+| --------------- | -------------- | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `use-case-hook` | `application/` | Orchestrates mutation + notification into one feature-level operation. The feature's public API. | `rules/use-case-hook.md` |
+
+### Component Patterns
+
+| Block                | Layer          | Summary                                                                                            | File                          |
+| -------------------- | -------------- | -------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `notification-hook`  | `application/` | Maps operation outcomes to toast notifications. One hook per use case.                             | `rules/notification-hook.md`  |
+| `pure-component`     | `components/`  | Props in, JSX out. No side effects, no internal state beyond `useMemo`.                            | `rules/pure-component.md`     |
+| `compound-component` | `components/`  | Dot-notation sub-components. Composition over configuration — no boolean prop toggles.             | `rules/compound-component.md` |
+| `hoc`                | `components/`  | Component in → enhanced component out. For render-level decisions (auth gates, suspense wrappers). | `rules/hoc.md`                |
+| `page`               | `pages/`       | Route-level orchestrator. Only place where router coupling is acceptable.                          | `rules/page.md`               |
+| `facade-hook`        | `components/`  | Private logic extraction for a single component. Defined below the component, not exported.        | `rules/facade-hook.md`        |
+| `named-effect`       | `components/`  | Named function expressions in `useEffect`. Intent visible at a glance.                             | `rules/named-effect.md`       |
+
+### Data Modeling
+
+| Block            | Layer          | Summary                                                                                    | File                      |
+| ---------------- | -------------- | ------------------------------------------------------------------------------------------ | ------------------------- |
+| `frontend-model` | `models/`      | UI-friendly domain objects mapped from DTOs. Skip if DTO shape is identical.               | `rules/frontend-model.md` |
+| `value-object`   | `application/` | Static-method classes grouping domain logic for a single concept. Namespace, not instance. | `rules/value-object.md`   |
+
+## Rules
+
+- Block files live in `rules/` — one file per block.
+- Each file contains: description, constraints, and a canonical code example.
+- Block names are stable identifiers referenced in specs and task breakdowns.

.agents/skills/building-blocks/metadata.json

@@ -0,0 +1,40 @@
+{
+  "version": "1.0.0",
+  "date": "April 2026",
+  "abstract": "Typed catalog of frontend building blocks. Contains 15 blocks across 5 categories (Data Fetching, State Management, App Orchestration, Component Patterns, Data Modeling). Each block defines composition rules, layer constraints, and canonical implementation examples. Designed for AI agents — read the index to route, read the rule file to implement.",
+  "categories": [
+    {
+      "name": "Data Fetching",
+      "blocks": [
+        "mutation-hook",
+        "query-options-factory",
+        "query-keys-factory",
+        "dto-model"
+      ]
+    },
+    {
+      "name": "State Management",
+      "blocks": ["store", "provider"]
+    },
+    {
+      "name": "App Orchestration",
+      "blocks": ["use-case-hook"]
+    },
+    {
+      "name": "Component Patterns",
+      "blocks": [
+        "notification-hook",
+        "pure-component",
+        "compound-component",
+        "hoc",
+        "page",
+        "facade-hook",
+        "named-effect"
+      ]
+    },
+    {
+      "name": "Data Modeling",
+      "blocks": ["frontend-model", "value-object"]
+    }
+  ]
+}

.agents/skills/building-blocks/rules/compound-component.md

@@ -0,0 +1,86 @@
+---
+title: Compound Component
+category: Component Patterns
+layer: components/
+composedWith: pure-component, facade-hook
+---
+
+## Compound Component
+
+Parent exposes dot-notation sub-components, consumers compose only the parts they need. Single import, internal structure hidden. The go-to for complex UI widgets (Tabs, Accordion, Select, Menu) where parts must coordinate but consumers need control over layout.
+
+### Constraints
+
+- Composition over configuration. If you're adding boolean props like `showHeader`, `showFooter`, `withSearch` — stop. Let the consumer compose the parts they need instead. Structure should be visible in JSX, not buried in prop logic.
+- Context is optional. Sometimes the pattern is just about providing a clean dot-notation API and avoiding falsy props that a root component would only pass through to its internal children. Use Context when sub-components genuinely need to coordinate shared state; skip it when the sub-components are independent.
+- Warning signs you need this: multiple boolean props toggling sections, large config objects controlling internal rendering, difficulty adding variations without modifying the component.
+- Don't over-apply. Single-purpose components with no optional sections stay as single units. Compound is for when consumers need structural flexibility.
+
+### Example
+
+```tsx
+// ❌ Prop-based configuration — inflexible, combinatorial explosion
+interface Props {
+  showHeader: boolean;
+  showSearch: boolean;
+  actions: Action[];
+}
+
+function ActionsMenu({ showHeader, showSearch, actions }: Props) {
+  return (
+    <div>
+      {showHeader && <h2>Actions</h2>}
+      {showSearch && <SearchInput />}
+      <ul>
+        {actions.map((action) => (
+          <li key={action.id}>{action.label}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+```tsx
+// ✅ Composition-based — each sub-component has one job,
+// structure is visible in JSX, only render what you need.
+// No Context needed here — sub-components are independent.
+function ActionsMenu({ children }: { children: React.ReactNode }) {
+  return <div className="actions-menu">{children}</div>;
+}
+
+ActionsMenu.Header = ({ children }: { children: React.ReactNode }) => (
+  <div className="actions-menu__header">{children}</div>
+);
+
+ActionsMenu.Search = ({ onSearch }: { onSearch: (query: string) => void }) => (
+  <input onChange={(e) => onSearch(e.target.value)} />
+);
+
+ActionsMenu.List = ({ children }: { children: React.ReactNode }) => (
+  <ul className="actions-menu__list">{children}</ul>
+);
+
+ActionsMenu.Item = ({
+  children,
+  onClick,
+}: {
+  children: React.ReactNode;
+  onClick: () => void;
+}) => <li onClick={onClick}>{children}</li>;
+```
+
+```tsx
+// Consumer composes only what they need
+<ActionsMenu>
+  <ActionsMenu.Header>Actions</ActionsMenu.Header>
+  <ActionsMenu.Search onSearch={handleSearch} />
+  <ActionsMenu.List>
+    {actions.map((action) => (
+      <ActionsMenu.Item key={action.id} onClick={action.handler}>
+        {action.label}
+      </ActionsMenu.Item>
+    ))}
+  </ActionsMenu.List>
+</ActionsMenu>
+```

.agents/skills/building-blocks/rules/dto-model.md

@@ -0,0 +1,42 @@
+---
+title: Dto Model
+category: Data Fetching
+layer: lib/api/
+composedWith: query-options-factory
+---
+
+## Dto Model
+
+TypeScript interfaces representing raw API response shapes — the wire format. Never use directly in UI or application logic; map to domain models when the shape diverges. Co-located with the `query-options-factory` that fetches the data.
+
+### Constraints
+
+- DTOs mirror the API contract exactly — no transformations, no computed fields, no UI conveniences. If the API returns `snake_case`, the DTO uses `snake_case`.
+- One DTO file per resource endpoint. Shared sub-types (like `Rating`) live in the same file if they're only used by that DTO.
+- Enums in DTOs represent server-defined value sets. Use `enum` when the API guarantees a closed set, union types when it doesn't.
+
+### Example
+
+```tsx
+export enum Category {
+  Men_clothing = "men's clothing",
+  Women_clothing = "women's clothing",
+  Jewelery = "jewelery",
+  Electronics = "electronics",
+}
+
+export interface Rating {
+  rate: number;
+  count: number;
+}
+
+export interface ProductDto {
+  id: number;
+  title: string;
+  description: string;
+  category: Category;
+  image: string;
+  price: number;
+  rating: Rating;
+}
+```

.agents/skills/building-blocks/rules/facade-hook.md

@@ -0,0 +1,68 @@
+---
+title: Facade Hook
+category: Component Patterns
+layer: components/
+composedWith: pure-component, compound-component
+---
+
+## Facade Hook
+
+Encapsulates logic a component needs so the component body stays pure — focused entirely on rendering JSX. Defined below the component in the same file. Think of it as the component's private method: not exported, not reused, exists solely to keep the render function clean.
+
+### Constraints
+
+- One facade hook per component. If you need two, the component probably has two responsibilities.
+- The hook returns exactly what the component's JSX needs — pre-shaped data, handlers, derived values. The component never transforms what the hook returns.
+- Facade hooks are for logic extraction, not data fetching orchestration. Loading states, queries, and mutations stay in the component or page. The facade hook handles formatting, derivations, and non-trivial transformations.
+- Don't confuse with shared hooks. A facade hook is private to its component. If multiple components need the same logic, that's a shared hook or `use-case-hook`, not a facade.
+
+### Example
+
+```tsx
+interface Props {
+  product: Product;
+  locale: string;
+}
+
+// Component stays focused on rendering
+export const ProductHeader = ({ product }: Props) => {
+  const { displayTitle, priceLabel, badge } = useFormattedProduct(product);
+
+  return (
+    <div className="product-header">
+      <h1>{displayTitle}</h1>
+      {badge && <span className="badge">{badge}</span>}
+      <span className="price">{priceLabel}</span>
+    </div>
+  );
+};
+
+// Facade hook — private, not exported, defined below the component
+const useFormattedProduct = (product: Product) => {
+  const displayTitle = useMemo(() => {
+    const base = product.name.trim();
+    const variant = product.variant ? ` — ${product.variant}` : "";
+    const limited = product.isLimitedEdition ? " (Limited Edition)" : "";
+    return `${base}${variant}${limited}`;
+  }, [product.name, product.variant, product.isLimitedEdition]);
+
+  const priceLabel = useMemo(() => {
+    const formatter = new MoneyVO.format({
+      style: "currency",
+      currency: product.currency,
+    });
+    return product.discountPrice
+      ? `${formatter.format(product.discountPrice)} (was ${formatter.format(product.price)})`
+      : formatter.format(product.price);
+  }, [product.price, product.discountPrice, product.currency]);
+
+  const badge = useMemo(() => {
+    if (product.stock === 0) return "Out of Stock";
+    if (product.stock <= 3) return `Only ${product.stock} left`;
+    if (product.isNew) return "New";
+    return null;
+  }, [product.stock, product.isNew]);
+
+  return { displayTitle, priceLabel, badge };
+};
+```

.agents/skills/building-blocks/rules/frontend-model.md

@@ -0,0 +1,31 @@
+---
+title: Frontend Model
+category: Data Modeling
+layer: models/
+composedWith: dto-model
+---
+
+## Frontend Model
+
+Frontend-friendly domain objects parsed or transformed from `dto-model`. Contains the shape your UI actually needs — renamed fields, computed properties, flattened nesting. Defined in `models/` of the feature slice.
+
+### Constraints
+
+- DTOs are the wire format, frontend models are the app format. When they diverge, map explicitly — don't let DTO shapes leak into components or application.
+- Keep models as plain interfaces/types — no methods, no class instances. Domain logic lives in `value-object` if needed.
+- If the DTO and frontend model are identical, skip the frontend model. Don't add a layer just for the sake of it.
+
+### Example
+
+```tsx
+// models/product.ts — what the UI actually works with
+export interface Product {
+  id: string;
+  name: string; // renamed from dto.title
+  price: number;
+  category: string;
+  imageUrl: string; // renamed from dto.image
+  rating: number; // flattened from dto.rating.rate
+  reviewCount: number; // flattened from dto.rating.count
+}
+```