memos/docs/superpowers/plans/2026-05-12-placeholder-component.md

Placeholder Component Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace Empty.tsx with a reusable <Placeholder> component covering empty / loading / noResults / notFound states, each rendering a hand-curated ASCII bird from a pool-shaped data file with subtle CSS-only animation.

Architecture: Single component (Placeholder/index.tsx) reads from a co-located ascii-pool.ts data file via a pickPiece(variant) picker. Motion is CSS keyframes in Placeholder.css, gated by prefers-reduced-motion. Default messages live in a messages.ts seam ready for future i18n. Integration is narrow: only Inboxes.tsx is rewired in this PR; Empty.tsx is deleted.

Tech Stack: React 19 · TypeScript · Tailwind v4 (via @tailwindcss/vite) · Vitest + @testing-library/react + jsdom · Biome for lint/format · cn helper from @/lib/utils for class composition.

---

File Structure

Create:

• web/src/components/Placeholder/index.tsx — public component (default export)
• web/src/components/Placeholder/Placeholder.css — keyframes + motion classes
• web/src/components/Placeholder/ascii-pool.ts — types, ASCII_POOL array, pickPiece()
• web/src/components/Placeholder/messages.ts — DEFAULT_MESSAGES map
• web/src/components/Placeholder/CREDITS.md — Joan Stark attribution
• web/tests/placeholder-pool.test.ts — picker + pool integrity tests
• web/tests/placeholder-component.test.tsx — component render tests

Modify:

• web/src/pages/Inboxes.tsx — replace <Empty /> with <Placeholder variant="empty" message={…} />

Delete:

• web/src/components/Empty.tsx

---

Task 0: Commit this plan

Files:

• Add: docs/superpowers/plans/2026-05-12-placeholder-component.md

• Step 1: Commit the plan document on its own

git add docs/superpowers/plans/2026-05-12-placeholder-component.md
git commit -m "docs: add Placeholder component implementation plan"

This keeps the planning artifact separate from feature commits.

---

Task 1: Scaffold pool types and picker (TDD)

Files:

• Create: web/src/components/Placeholder/ascii-pool.ts

• Test: web/tests/placeholder-pool.test.ts

• Step 1: Write the failing tests for pickPiece and pool shape

Create web/tests/placeholder-pool.test.ts:

import { describe, expect, it } from "vitest";
import { ASCII_POOL, pickPiece, type PlaceholderVariant } from "@/components/Placeholder/ascii-pool";

const VARIANTS: PlaceholderVariant[] = ["empty", "loading", "noResults", "notFound"];

describe("ASCII_POOL integrity", () => {
  it("contains at least one piece per variant", () => {
    for (const variant of VARIANTS) {
      const matches = ASCII_POOL.filter((p) => p.variant === variant);
      expect(matches.length, `variant=${variant}`).toBeGreaterThanOrEqual(1);
    }
  });

  it("uses unique ids", () => {
    const ids = ASCII_POOL.map((p) => p.id);
    expect(new Set(ids).size).toBe(ids.length);
  });

  it("preserves the jgs credit on every piece", () => {
    for (const piece of ASCII_POOL) {
      expect(piece.credit, `piece=${piece.id}`).toMatch(/jgs/);
    }
  });

  it("uses a known motion style on every piece", () => {
    for (const piece of ASCII_POOL) {
      expect(["bob", "flutter", "none"]).toContain(piece.motion);
    }
  });
});

describe("pickPiece", () => {
  it("returns a piece matching the requested variant", () => {
    for (const variant of VARIANTS) {
      const piece = pickPiece(variant);
      expect(piece.variant).toBe(variant);
    }
  });

  it("returns a non-empty ascii string", () => {
    const piece = pickPiece("empty");
    expect(piece.ascii.length).toBeGreaterThan(0);
  });
});

• Step 2: Run the tests and verify they fail

cd web && pnpm test placeholder-pool

Expected: FAIL — module @/components/Placeholder/ascii-pool not found.

• Step 3: Implement ascii-pool.ts with types, an empty pool, and the picker

Create web/src/components/Placeholder/ascii-pool.ts:

export type PlaceholderVariant = "empty" | "loading" | "noResults" | "notFound";

export type MotionStyle = "bob" | "flutter" | "none";

export interface AsciiPiece {
  /** Stable identifier — used as React key and for debugging. */
  id: string;
  /** Which placeholder state this piece is shown for. */
  variant: PlaceholderVariant;
  /** ASCII art preserved verbatim — must keep every space. */
  ascii: string;
  /** Attribution shown beneath the bird, e.g. "jgs · 4/97". */
  credit: string;
  /** Motion hint applied to the <pre>. */
  motion: MotionStyle;
}

export const ASCII_POOL: AsciiPiece[] = [];

export function pickPiece(variant: PlaceholderVariant): AsciiPiece {
  const matches = ASCII_POOL.filter((p) => p.variant === variant);
  if (matches.length === 0) {
    throw new Error(`No ASCII piece registered for variant "${variant}"`);
  }
  return matches[Math.floor(Math.random() * matches.length)];
}

• Step 4: Run the tests and verify they still fail (pool is empty)

cd web && pnpm test placeholder-pool

Expected: FAIL — "contains at least one piece per variant" expectations not met (because ASCII_POOL is []).

This is the expected red — pool gets seeded in the next task.

• Step 5: Commit

git add web/src/components/Placeholder/ascii-pool.ts web/tests/placeholder-pool.test.ts
git commit -m "feat(placeholder): scaffold ASCII pool types and picker"

---

Task 2: Seed the four ASCII pieces

Files:

• Modify: web/src/components/Placeholder/ascii-pool.ts

• Step 1: Replace the empty ASCII_POOL array with the four seed entries

In web/src/components/Placeholder/ascii-pool.ts, replace export const ASCII_POOL: AsciiPiece[] = []; with the four entries below. Preserve every space and newline in the ascii strings exactly — they are template literals with escaped backslashes/backticks per JS rules.

export const ASCII_POOL: AsciiPiece[] = [
  {
    id: "jgs-crested-parrot",
    variant: "empty",
    credit: "jgs · 4/97",
    motion: "bob",
    ascii: `       .---.
      /   6_6
      \\_  (__\\
      //   \\\\
     ((     ))
=====""===""=====
        |||
         |`,
  },
  {
    id: "jgs-hummingbird-sm",
    variant: "loading",
    credit: "jgs · 7/98",
    motion: "flutter",
    ascii: `           ,   _
          { \\/\`o;====-
     .----'-/\`-/
      \`'-..-| /
            /\\/\\
            \`--\``,
  },
  {
    id: "jgs-wide-eyed-owl",
    variant: "noResults",
    credit: "jgs · 2/01",
    motion: "bob",
    ascii: `      __       __
      \\ \`-'"'-\` /
      / \\_   _/ \\
      |  d\\_/b  |
     .'\\   V   /'.
    /   '-...-'   \\
    | /         \\ |
    \\/\\         /\\/
    ==(||)---(||)==`,
  },
  {
    id: "jgs-bird-flown-away",
    variant: "notFound",
    credit: "jgs · 7/96",
    motion: "flutter",
    ascii: `                      ___
                  _,-' ______
                .'  .-'  ____7
               /   /   ___7
             _|   /  ___7
           >(')\\ | ___7
             \\\\/     \\_______
             '        _======>
             \`'----\\\\\``,
  },
];

• Step 2: Run the pool tests and verify they pass

cd web && pnpm test placeholder-pool

Expected: PASS for all six assertions.

• Step 3: Commit

git add web/src/components/Placeholder/ascii-pool.ts
git commit -m "feat(placeholder): seed pool with four jgs ASCII bird pieces"

---

Task 3: Default messages

Files:

• Create: web/src/components/Placeholder/messages.ts

• Step 1: Add a tiny test for the messages map

Append to web/tests/placeholder-pool.test.ts:

import { DEFAULT_MESSAGES } from "@/components/Placeholder/messages";

describe("DEFAULT_MESSAGES", () => {
  it("provides a non-empty message for every variant", () => {
    for (const variant of VARIANTS) {
      expect(DEFAULT_MESSAGES[variant], `variant=${variant}`).toBeTruthy();
      expect(DEFAULT_MESSAGES[variant].trim().length).toBeGreaterThan(0);
    }
  });
});

• Step 2: Run the test and verify it fails

cd web && pnpm test placeholder-pool

Expected: FAIL — module @/components/Placeholder/messages not found.

• Step 3: Create messages.ts

import type { PlaceholderVariant } from "./ascii-pool";

/**
 * Default copy shown beneath the ASCII art when no `message` prop is supplied.
 *
 * Future i18n: swap these strings for `t("placeholder.<variant>")` lookups via
 * `react-i18next` without touching the component.
 */
export const DEFAULT_MESSAGES: Record<PlaceholderVariant, string> = {
  empty: "No memos yet",
  loading: "Loading…",
  noResults: "Nothing matches that search",
  notFound: "This page flew the coop",
};

• Step 4: Run the test and verify it passes

cd web && pnpm test placeholder-pool

Expected: PASS — all variants have a non-empty default message.

• Step 5: Commit

git add web/src/components/Placeholder/messages.ts web/tests/placeholder-pool.test.ts
git commit -m "feat(placeholder): add DEFAULT_MESSAGES map"

---

Task 4: Animation keyframes

Files:

• Create: web/src/components/Placeholder/Placeholder.css

• Step 1: Create the stylesheet

/*
 * Animations for <Placeholder>.
 *
 * All keyframes are wrapped in a prefers-reduced-motion guard so users who
 * opt out of motion see a static bird and an instantly-visible message.
 */

@media (prefers-reduced-motion: no-preference) {
  .placeholder-motion-bob {
    animation: placeholder-bob 3.4s ease-in-out infinite;
  }

  .placeholder-motion-flutter {
    animation: placeholder-flutter 0.7s ease-in-out infinite;
  }

  .placeholder-fade-in {
    animation: placeholder-fade 1s ease-out 0.3s both;
    opacity: 0;
  }
}

@keyframes placeholder-bob {
  0%, 100% { transform: translateY(0); }
  50%      { transform: translateY(-4px); }
}

@keyframes placeholder-flutter {
  0%, 100% { transform: translate(0, 0); }
  50%      { transform: translate(2px, -1px); }
}

@keyframes placeholder-fade {
  to { opacity: 1; }
}

• Step 2: Commit

git add web/src/components/Placeholder/Placeholder.css
git commit -m "feat(placeholder): add motion keyframes with reduced-motion guard"

---

Task 5: Placeholder component (TDD)

Files:

• Create: web/src/components/Placeholder/index.tsx

• Test: web/tests/placeholder-component.test.tsx

• Step 1: Write the failing component tests

Create web/tests/placeholder-component.test.tsx:

import { render, screen } from "@testing-library/react";
import { describe, expect, it } from "vitest";
import Placeholder from "@/components/Placeholder";
import { DEFAULT_MESSAGES } from "@/components/Placeholder/messages";

describe("<Placeholder>", () => {
  it("renders the default message for variant=empty", () => {
    render(<Placeholder variant="empty" />);
    expect(screen.getByText(DEFAULT_MESSAGES.empty)).toBeInTheDocument();
  });

  it("renders the default message for variant=loading", () => {
    render(<Placeholder variant="loading" />);
    expect(screen.getByText(DEFAULT_MESSAGES.loading)).toBeInTheDocument();
  });

  it("renders the default message for variant=noResults", () => {
    render(<Placeholder variant="noResults" />);
    expect(screen.getByText(DEFAULT_MESSAGES.noResults)).toBeInTheDocument();
  });

  it("renders the default message for variant=notFound", () => {
    render(<Placeholder variant="notFound" />);
    expect(screen.getByText(DEFAULT_MESSAGES.notFound)).toBeInTheDocument();
  });

  it("overrides the default message when `message` prop is passed", () => {
    render(<Placeholder variant="empty" message="Custom copy goes here" />);
    expect(screen.getByText("Custom copy goes here")).toBeInTheDocument();
    expect(screen.queryByText(DEFAULT_MESSAGES.empty)).not.toBeInTheDocument();
  });

  it("renders the ASCII art inside a <pre> with aria-hidden", () => {
    const { container } = render(<Placeholder variant="empty" />);
    const pre = container.querySelector("pre");
    expect(pre).not.toBeNull();
    expect(pre).toHaveAttribute("aria-hidden", "true");
    expect(pre!.textContent!.length).toBeGreaterThan(0);
  });

  it("renders a jgs credit string", () => {
    render(<Placeholder variant="empty" />);
    expect(screen.getByText(/jgs/)).toBeInTheDocument();
  });

  it('applies role="status" and aria-live="polite" ONLY when variant=loading', () => {
    const { rerender, container } = render(<Placeholder variant="empty" />);
    expect(container.querySelector('[role="status"]')).toBeNull();

    rerender(<Placeholder variant="loading" />);
    const live = container.querySelector('[role="status"]');
    expect(live).not.toBeNull();
    expect(live).toHaveAttribute("aria-live", "polite");
  });

  it("renders children below the message when provided", () => {
    render(
      <Placeholder variant="notFound">
        <button type="button">Go home</button>
      </Placeholder>,
    );
    expect(screen.getByRole("button", { name: "Go home" })).toBeInTheDocument();
  });

  it("merges a custom className onto the outer wrapper", () => {
    const { container } = render(<Placeholder variant="empty" className="custom-test-class" />);
    expect(container.firstChild).toHaveClass("custom-test-class");
  });
});

• Step 2: Run the tests and verify they fail

cd web && pnpm test placeholder-component

Expected: FAIL — module @/components/Placeholder not found.

• Step 3: Implement index.tsx

Create web/src/components/Placeholder/index.tsx:

import { useMemo, type ReactNode } from "react";
import { cn } from "@/lib/utils";
import { pickPiece, type MotionStyle, type PlaceholderVariant } from "./ascii-pool";
import { DEFAULT_MESSAGES } from "./messages";
import "./Placeholder.css";

interface PlaceholderProps {
  variant: PlaceholderVariant;
  message?: string;
  children?: ReactNode;
  className?: string;
}

const MOTION_CLASS: Record<MotionStyle, string> = {
  bob: "placeholder-motion-bob",
  flutter: "placeholder-motion-flutter",
  none: "",
};

const Placeholder = ({ variant, message, children, className }: PlaceholderProps) => {
  // Stable for the lifetime of this mount; re-rolls only if `variant` changes
  // (which is rare in practice — most callers pass a constant).
  const piece = useMemo(() => pickPiece(variant), [variant]);
  const resolvedMessage = message ?? DEFAULT_MESSAGES[variant];
  const isLoading = variant === "loading";

  return (
    <div
      role={isLoading ? "status" : undefined}
      aria-live={isLoading ? "polite" : undefined}
      className={cn("flex flex-col items-center justify-center max-w-md mx-auto px-4 py-8", className)}
    >
      <pre
        aria-hidden="true"
        className={cn(
          "font-mono text-xs sm:text-sm leading-tight text-muted-foreground whitespace-pre m-0",
          MOTION_CLASS[piece.motion],
        )}
      >
        {piece.ascii}
      </pre>
      <p className="mt-3 font-mono text-sm text-muted-foreground placeholder-fade-in">
        {resolvedMessage}
      </p>
      <p className="mt-1 font-mono text-[10px] text-muted-foreground/60 placeholder-fade-in">
        {piece.credit}
      </p>
      {children && <div className="mt-4">{children}</div>}
    </div>
  );
};

export default Placeholder;

• Step 4: Run the tests and verify they pass

cd web && pnpm test placeholder-component

Expected: PASS — all ten assertions green.

• Step 5: Commit

git add web/src/components/Placeholder/index.tsx web/tests/placeholder-component.test.tsx
git commit -m "feat(placeholder): implement <Placeholder> with variant-driven ASCII pool"

---

Task 6: Attribution credits

Files:

• Create: web/src/components/Placeholder/CREDITS.md

• Step 1: Create CREDITS.md

# ASCII Art Credits

The ASCII bird illustrations rendered by `<Placeholder>` are from **Joan Stark's**
classic ASCII art collection. Each piece is signed with her `jgs` tag and the
month/year it was published.

- Source archive: https://github.com/oldcompcz/jgs (Joan Stark's ASCII Art Gallery)
- Original site (preserved via WebArchive): https://web.archive.org/web/20091028013825/http://www.geocities.com/SoHo/7373/
- Wikipedia: https://en.wikipedia.org/wiki/Joan_Stark

Joan Stark distributed her art freely on Usenet and the early web. We retain
the `jgs` signature visible beneath each piece in the UI so attribution travels
with the art wherever it is shown.

If you add new ASCII pieces to `ascii-pool.ts`:

- Prefer well-attributed art from established collections.
- Keep the original artist signature in the `credit` field (e.g. `"jgs · 4/97"`).
- If using a different artist, link the source in this file.

• Step 2: Commit

git add web/src/components/Placeholder/CREDITS.md
git commit -m "docs(placeholder): credit Joan Stark for ASCII bird art"

---

Task 7: Wire into Inboxes.tsx and delete Empty.tsx

Files:

• Modify: web/src/pages/Inboxes.tsx

• Delete: web/src/components/Empty.tsx

• Step 1: Read the current empty-state block in Inboxes.tsx

Open web/src/pages/Inboxes.tsx. The relevant block is at lines 99–105:

{notifications.length === 0 ? (
  <div className="w-full py-16 flex flex-col justify-center items-center">
    <Empty />
    <p className="mt-4 text-sm text-muted-foreground">
      {filter === "unread" ? t("inbox.no-unread") : filter === "archived" ? t("inbox.no-archived") : t("message.no-data")}
    </p>
  </div>
) : (

The outer <div className="w-full py-16 flex flex-col justify-center items-center"> and the inner <p> both become redundant — <Placeholder> handles its own centering and message.

• Step 2: Swap the import

In web/src/pages/Inboxes.tsx, replace the import line:

import Empty from "@/components/Empty";

with:

import Placeholder from "@/components/Placeholder";

• Step 3: Replace the empty-state JSX

Replace lines 99–105 (the existing empty-state block above) with:

{notifications.length === 0 ? (
  <Placeholder
    variant="empty"
    message={
      filter === "unread"
        ? t("inbox.no-unread")
        : filter === "archived"
          ? t("inbox.no-archived")
          : t("message.no-data")
    }
  />
) : (

(Only the truthy branch of the ternary changes; leave the : ( start of the falsy branch and everything below it untouched.)

• Step 4: Delete Empty.tsx

git rm web/src/components/Empty.tsx

• Step 5: Verify nothing else imports Empty

cd /Users/steven/Projects/usememos/memos && grep -rn 'from "@/components/Empty"\|from "./Empty"\|from "../Empty"' web/src 2>/dev/null

Expected: no output. If anything matches, update that file to use <Placeholder variant="empty" /> before continuing.

• Step 6: Commit

git add web/src/pages/Inboxes.tsx web/src/components/Empty.tsx
git commit -m "feat(inboxes): use <Placeholder variant=empty> in place of <Empty>"

---

Task 8: Verification — lint, types, tests, build, dev preview

Files: none modified (verification only)

• Step 1: Run the lint + typecheck

cd web && pnpm lint

Expected: exits 0. If Biome flags anything (formatting, sort-order, unused imports), run pnpm lint:fix and re-run pnpm lint. Commit the fix separately if any changes are required:

git add -p web/src web/tests
git commit -m "chore(placeholder): biome auto-fixes"

• Step 2: Run the full test suite

cd web && pnpm test

Expected: all suites green, including placeholder-pool (8 assertions) and placeholder-component (10 assertions). Existing tests must still pass.

• Step 3: Run the production build

cd web && pnpm build

Expected: exits 0. Confirms TypeScript still compiles end-to-end and the new CSS import is picked up by Vite.

• Step 4: Manual visual check — start the dev server

cd web && pnpm dev

In a browser, navigate to the running URL (Vite prints it). Sign in with any test account, open the Inbox page, and confirm:

1. When inbox is empty, the crested-parrot ASCII bird is visible.
2. It bobs gently every ~3.4 seconds.
3. The message text (one of "no unread", "no archived", or "no data") appears below with a soft fade-in.
4. The small jgs · 4/97 credit is visible below the message.
5. No console errors or warnings.

Stop the dev server with Ctrl+C.

• Step 5: (Optional) Reduced-motion check

Open browser DevTools → command menu → "Emulate CSS prefers-reduced-motion: reduce". Reload the inbox empty state. The bird should be static and the message should appear instantly (no fade).

• Step 6: No-op commit point

If steps 1–4 all passed and no further changes were needed, there is nothing to commit. Proceed to the next task.

---

Task 9: Document the work in the PR body

Files: none modified

• Step 1: Draft a PR description

When opening the PR, use a body like:

## Summary

- Adds a new `<Placeholder variant="empty | loading | noResults | notFound">` component that renders a hand-curated ASCII bird from a pool-shaped data file, with subtle CSS-only motion that respects `prefers-reduced-motion`.
- Replaces the single-purpose `Empty.tsx` (used in `Inboxes.tsx`) with `<Placeholder variant="empty">`.
- ASCII art is from Joan Stark's (jgs) classic collection — attribution is preserved on every piece and in a co-located `CREDITS.md`.

## Out of scope (follow-up opportunities)

- Wire `<Placeholder variant="noResults">` into the memo search results page.
- Wire `<Placeholder variant="notFound">` into the router 404 catch-all.
- Wire `<Placeholder variant="loading">` into Suspense fallbacks.
- Seed additional ASCII pieces per variant — the pool architecture supports it; just append entries to `ASCII_POOL`.

## Test plan

- [ ] `pnpm lint` clean
- [ ] `pnpm test` green (incl. new `placeholder-pool` and `placeholder-component` suites)
- [ ] `pnpm build` succeeds
- [ ] Inbox empty state shows the ASCII parrot, bobs, and renders the filter-specific message
- [ ] `prefers-reduced-motion: reduce` produces a static bird and an instantly-visible message

• Step 2: Open the PR (skip if user prefers to do this themselves)

This step is left as a manual handoff — do not push or open the PR unless the user has explicitly authorized it.

---

Self-Review Notes

This plan covers the spec's nine sections as follows:

Spec section	Implemented by
Public Component	Task 5
ASCII Pool	Tasks 1, 2
Default Messages	Task 3
Animation	Task 4 (CSS) + Task 5 (component wires classes)
Accessibility	Task 5 (test assertions + impl)
File Layout	Tasks 1–6 (all five files created)
Integration	Task 7 (Inboxes rewire + Empty delete)
Credits	Task 6
Testing	Tasks 1, 3, 5 (pool tests + component tests)

No spec section is unimplemented. No "TBD" / "TODO" / vague-handwave language is used in any step. Types, method signatures, and class names referenced across tasks match:

• PlaceholderVariant, MotionStyle, AsciiPiece, ASCII_POOL, pickPiece — consistent across Tasks 1, 2, 3, 5
• DEFAULT_MESSAGES — defined in Task 3, consumed in Task 5
• placeholder-motion-bob, placeholder-motion-flutter, placeholder-fade-in — defined in Task 4 CSS, consumed in Task 5 component
• cn from @/lib/utils — matches existing codebase convention (verified in pre-plan exploration)
• Placeholder is a default export — matches the convention used by Empty.tsx and most other web/src/components/*.tsx files