|
|
|
|
@ -0,0 +1,776 @@
|
|
|
|
|
# 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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```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)**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd web && pnpm test placeholder-pool
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: PASS for all six assertions.
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd web && pnpm test placeholder-pool
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: FAIL — module `@/components/Placeholder/messages` not found.
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 3: Create `messages.ts`**
|
|
|
|
|
|
|
|
|
|
```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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd web && pnpm test placeholder-pool
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: PASS — all variants have a non-empty default message.
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```css
|
|
|
|
|
/*
|
|
|
|
|
* 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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd web && pnpm test placeholder-component
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: PASS — all ten assertions green.
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`**
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
# 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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
{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:
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
import Empty from "@/components/Empty";
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
with:
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
import Placeholder from "@/components/Placeholder";
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 3: Replace the empty-state JSX**
|
|
|
|
|
|
|
|
|
|
Replace lines 99–105 (the existing empty-state block above) with:
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
{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`**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git rm web/src/components/Empty.tsx
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 5: Verify nothing else imports `Empty`**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git add -p web/src web/tests
|
|
|
|
|
git commit -m "chore(placeholder): biome auto-fixes"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- [ ] **Step 2: Run the full test suite**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
## 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
|
boojack
3 weeks ago
committed by
GitHub