@pihanga2/shadcn 0.2.0 → 0.2.2

package/AGENT.building-cards.md

@@ -1,13 +1,217 @@
 # AGENT.building-cards.md — creating new pihanga-shadcn cards
 
-> **Scope:** adding a new card *type* to `src/cards/` in this repository.
+> **Scope:** building new cards — either by composing existing cards into a
+> **meta card** (recommended, TypeScript-only) or by adding a brand-new
+> React-based primitive card to `src/cards/`.
 > Read [`AGENT.md`](./AGENT.md) first for orientation and universal rules.
 > If you only need to *use* existing cards in an app, switch to
 > [`AGENT.using-cards.md`](./AGENT.using-cards.md).
 
 ---
 
-## ⚠️ Hard constraints before you write a single line
+## ⭐ Meta cards — composing new widgets from existing cards
+
+> **This is the recommended approach for building any complex or reusable UI
+> widget.**  A meta card is assembled entirely from existing cards using a
+> plain TypeScript mapper function — no JSX, no React imports, no DOM
+> knowledge required.  Read this section before considering a primitive card.
+
+### Why meta cards?
+
+| Concern | Meta card | New primitive card (React component) |
+|---|---|---|
+| Code volume | ~50 lines TypeScript | ~200 lines JSX + hooks |
+| Maintenance | Inherits upstream card fixes automatically | Must track shadcn/Radix updates manually |
+| Reusability | Portable across any Pihanga app unchanged | Tightly coupled to one project |
+| Testability | Pure function — mock props, assert card tree | Requires DOM + Redux environment |
+| Extendibility | Swap any inner card without touching consumers | Requires internal refactoring |
+| Learning curve | Pihanga config patterns only | JSX, React hooks, Pihanga internals |
+
+**Rule of thumb:** if you can describe the widget as *"a layout card containing
+some input and display cards"*, build it as a meta card.  Only drop to a
+primitive React component when the widget genuinely needs a DOM API, a
+third-party React hook, or a non-card rendering strategy.
+
+### How meta cards work
+
+A meta card has three ingredients:
+
+1. **Card declaration + actions** — same as any card; use
+   `createCardDeclaration`, `registerActions`, `createOnAction`.
+2. **Mapper function** — a plain function `(name, props, registerCard) =>
+   PiCardDef` that assembles child cards and returns the root card definition.
+3. **Registration** — `registerMetaCard({type, mapper, events})`.
+
+The Pihanga runtime calls the mapper whenever the meta card needs to be
+rendered or re-evaluated.  Child cards can use `resolve(props.foo)` inside
+their own prop functions to lazily read a value that may itself be a state
+selector.
+
+### Full worked example — `Counter` meta card
+
+The complete, annotated source lives at
+[`example/src/counter.card.ts`](./example/src/counter.card.ts).
+Abbreviated for reference:
+
+```ts
+import {
+  createCardDeclaration, createOnAction, registerActions, registerMetaCard,
+} from "@pihanga2/core";
+import type {PiCardDef, PiMapProps, PiRegisterMetaCard, ReduxState, RegisterCardF} from "@pihanga2/core";
+import {Stack, Button, Typography} from "@pihanga2/shadcn";
+
+// ── 1. Card identity ─────────────────────────────────────────────────────────
+const COUNTER_CARD = "meta/counter";   // convention: "meta/<name>" for app-level
+
+// ── 2. Public factory (consumers call Counter({value: ...})) ────────────────
+export const Counter = createCardDeclaration<CounterProps, CounterEvents>(COUNTER_CARD);
+
+// ── 3. Actions + typed event helper ─────────────────────────────────────────
+export const COUNTER_ACTION = registerActions(COUNTER_CARD, ["changed"]);
+export const onCounterChanged = createOnAction<CounterChangeEvent>(COUNTER_ACTION.CHANGED);
+
+// ── 4. Types ─────────────────────────────────────────────────────────────────
+type CounterProps  = { value: number };
+type CounterChangeEvent = { value: number };
+type CounterEvents = { onChange: CounterChangeEvent };
+type CounterMapperProps = CounterProps & CounterEvents;
+
+// ── 5. Mapper — assembles child cards ────────────────────────────────────────
+function CounterMapper(
+  _: string,
+  props: PiMapProps<CounterMapperProps, ReduxState, object>,
+  registerCard: RegisterCardF,
+): PiCardDef {
+  // Register a child card under a stable name (optional but shown for reference)
+  const plusButton = registerCard("plus", Button({
+    label: "+",
+    opts: {size: "lg"},
+    // Re-map raw click → COUNTER_ACTION.CHANGED { value + 1 }
+    onClickedMapper: (_, {resolve}) => ({
+      type: COUNTER_ACTION.CHANGED,
+      value: resolve(props.value) + 1,   // resolve() unwraps lazy state selectors
+    }),
+  }));
+
+  return Stack({
+    direction: "row", alignItems: "center", spacing: 4,
+    className: "p-16 justify-center",
+    content: [
+      Button({
+        label: "−",
+        opts: {size: "lg"},
+        onClickedMapper: (_, {resolve}) => ({
+          type: COUNTER_ACTION.CHANGED,
+          value: resolve(props.value) - 1,
+        }),
+      }),
+      Typography({
+        text: (_, {resolve}) => `Count: ${resolve(props.value)}`,   // reactive text
+        level: "h2",
+        className: "min-w-[120px] text-center",
+      }),
+      plusButton,
+    ],
+  });
+}
+
+// ── 6. Register ───────────────────────────────────────────────────────────────
+registerMetaCard({
+  type: COUNTER_CARD,
+  mapper: CounterMapper,
+  events: COUNTER_ACTION,
+} satisfies PiRegisterMetaCard);
+```
+
+**Usage at the app level** (`example/src/app.pihanga.ts`):
+
+```ts
+import {Counter} from "./counter.card";
+import type {AppState} from "./app.state";
+
+registerCard("page", Counter<AppState>({
+  value: (s) => s.count,   // state selector — auto-reactive
+}));
+```
+
+**Handling the emitted event** (`example/src/app.reducer.ts`):
+
+```ts
+import {onCounterChanged} from "./counter.card";
+
+register((r) => {
+  onCounterChanged<AppState>(r, (state, {value}) => {
+    state.count = value;   // raw button clicks never surface here — encapsulated
+  });
+});
+```
+
+### Key API reference for meta cards
+
+| Symbol | Source | Purpose |
+|---|---|---|
+| `registerMetaCard(opts)` | `@pihanga2/core` | Registers a mapper as a named card type |
+| `PiRegisterMetaCard` | `@pihanga2/core` | Type for the `opts` object (use `satisfies`) |
+| `MetaCardMapperF` | `@pihanga2/core` | Type of the mapper function |
+| `RegisterCardF` | `@pihanga2/core` | Type of the `registerCard` arg inside the mapper |
+| `PiMapProps<Props, State, Ctx>` | `@pihanga2/core` | Prop type inside the mapper (each prop may be a state selector) |
+| `resolve(prop)` | `StateMapperContext` | Unwraps a lazy prop value inside a child card's prop function |
+| `onClickedMapper` / `on*Mapper` | any card | Event mapper suffix — re-maps a child card's action to a different action type |
+
+### Patterns to know
+
+**Lazy prop propagation with `resolve`**
+
+When a meta card receives `value: (s) => s.count` (a state selector), child
+cards can't use that selector directly — it has to be unwrapped at the time the
+child's own prop function runs:
+
+```ts
+// ❌ Doesn't work — selector is passed as-is; child sees a function, not a number
+Typography({ text: props.value })
+
+// ✅ Correct — resolve() unwraps the selector inside the child's prop function
+Typography({ text: (_, {resolve}) => `Count: ${resolve(props.value)}` })
+```
+
+**Event remapping with `onXxxMapper`**
+
+Every card that emits an event supports an `on<EventName>Mapper` prop.  The
+mapper intercepts the raw event and returns a different action (or `null` to
+suppress):
+
+```ts
+Button({
+  label: "Save",
+  // Re-map generic click → domain-specific action
+  onClickedMapper: (_ev, _ctx) => ({ type: MY_ACTION.SAVED }),
+})
+```
+
+**Registering a stable child card name**
+
+Pass the result of `registerCard(name, def)` as a child in the `content` array.
+This is optional but gives the child a stable registry identity:
+
+```ts
+const saveBtn = registerCard("save-btn", Button({label: "Save", …}));
+return Stack({ content: [saveBtn] });
+```
+
+**Accessing metacard context from a deeply nested child**
+
+Use `metaCtxtProps` in a child card's state mapper when you need the context
+props that were passed to the meta card's top-level card:
+
+```ts
+// Inside a child card declaration within the mapper:
+properties: (s, { metaCtxtProps }) => metaCtxtProps.elementData.properties,
+```
+
+---
+
+## ⚠️ Hard constraints before you write a single line (primitive cards)
+
 
 1. **`src/components/` is read-only.** It is managed exclusively by the shadcn
    CLI (`npx shadcn@latest add <name>`).  Never create or edit files there.
@@ -383,7 +587,8 @@ Rules:
 
 | Need | Card to study |
 |---|---|
-| Minimal card structure | `src/cards/emptyCard.tsx` |
+| **Meta card (composition)** | **`example/src/counter.card.ts`** — fully annotated: Stack + Button × 2 + Typography, event remapping, `resolve()`, stable child names |
+| Minimal primitive card structure | `src/cards/emptyCard.tsx` |
 | Button with variants, icons, tooltip | `src/cards/button/` |
 | Dropdown / context menu | `src/cards/dropDownMenu/` |
 | Form input pattern | `src/cards/textField/`, `src/cards/checkbox/` |

package/AGENT.md

@@ -30,12 +30,67 @@ https://github.com/ivcap-works/pihanga-shadcn
 
 | If your task is … | Read this file |
 |---|---|
+| **Getting started** — brand-new project, shadcn/ui + pihanga setup, file layout | [`AGENTS.getting-started.md`](./AGENTS.getting-started.md) |
 | **Using** existing cards — install, wire, compose, navigate | [`AGENT.using-cards.md`](./AGENT.using-cards.md) |
-| **Building** new cards — create a new card type for this repo | [`AGENT.building-cards.md`](./AGENT.building-cards.md) |
+| **Building complex UI** — assembling a reusable widget from existing cards | [`AGENT.building-cards.md`](./AGENT.building-cards.md) — § *Meta cards* |
+| **Building** a new primitive card from scratch — new React component for this repo | [`AGENT.building-cards.md`](./AGENT.building-cards.md) |
 
-If you are **unsure**, start with `AGENT.using-cards.md`; it covers the common
-app-building case.  Switch to `AGENT.building-cards.md` only when you need to
-add a new card *type* to `src/cards/` itself.
+If you are **starting from scratch**, read `AGENTS.getting-started.md` first — it
+covers Vite setup, shadcn/ui init, pihanga-core installation, and the initial file
+layout.  Then continue with `AGENT.using-cards.md` for wiring and composing cards.
+
+If you are adding cards to an **existing project**, go straight to
+`AGENT.using-cards.md`.
+
+### ⭐ Need a complex, reusable UI widget?  Use a meta card.
+
+Before writing a new React component, ask: *can I build this by composing
+existing cards?*  If yes — and that is almost always the answer — use a
+**meta card** instead.
+
+A meta card is a TypeScript-only module (no JSX, no React imports) that
+assembles other cards inside a mapper function and registers itself with
+`registerMetaCard`.  The result looks and feels exactly like a primitive card to
+consumers: a typed factory function, typed event helpers, and full `memo()`/state
+reactivity.
+
+```ts
+// example/src/counter.card.ts (abbreviated)
+import {registerMetaCard, createCardDeclaration, registerActions} from "@pihanga2/core";
+import {Stack, Button, Typography} from "@pihanga2/shadcn";
+
+const COUNTER_CARD = "meta/counter";
+export const Counter = createCardDeclaration<CounterProps, CounterEvents>(COUNTER_CARD);
+export const COUNTER_ACTION = registerActions(COUNTER_CARD, ["changed"]);
+
+registerMetaCard({
+  type: COUNTER_CARD,
+  mapper(_name, props, registerCard) {
+    return Stack({ content: [
+      Button({ label: "−", onClickedMapper: (_, {resolve}) => ({type: COUNTER_ACTION.CHANGED, value: resolve(props.value) - 1}) }),
+      Typography({ text: (_, {resolve}) => `Count: ${resolve(props.value)}` }),
+      Button({ label: "+", onClickedMapper: (_, {resolve}) => ({type: COUNTER_ACTION.CHANGED, value: resolve(props.value) + 1}) }),
+    ]});
+  },
+  events: COUNTER_ACTION,
+});
+```
+
+**Why meta cards over new React components?**
+
+| Concern | Meta card | New React component |
+|---|---|---|
+| Code complexity | Low — pure TypeScript config | High — JSX, hooks, event wiring |
+| Maintenance | Inherits upstream fixes automatically | Must be kept in sync manually |
+| Reusability | Drops into any Pihanga app | Tightly coupled to one project |
+| Testability | Plain function, mockable | Requires DOM + Redux setup |
+| Extendibility | Swap out any inner card without touching consumers | Requires internal refactoring |
+
+See the full meta card guide in [`AGENT.building-cards.md`](./AGENT.building-cards.md#meta-cards--composing-new-widgets-from-existing-cards)
+and the complete working example at [`example/src/counter.card.ts`](./example/src/counter.card.ts).
+
+Switch to `AGENT.building-cards.md` — § *Building a primitive card from scratch* — only
+when no combination of existing cards can achieve the required UI.
 
 ---
 
@@ -48,3 +103,10 @@ add a new card *type* to `src/cards/` itself.
   must ensure only one of them calls it.
 - **`children` is a reserved React prop** — never use it in a card's `…Props`
   type; use `content`, `contentCard`, or `items` instead.
+- **npm channel: add `lucide-react` to `optimizeDeps.include`** — excluding
+  `@pihanga2/shadcn` from Vite's pre-bundler (required to prevent duplicate
+  registries) also causes `lucide-react` to be served as raw ESM, triggering
+  ~1 000 individual icon file requests in the dev browser.  Adblockers block
+  `fingerprint.js` as a tracking script.  Always include `"lucide-react"` in
+  `optimizeDeps.include` (see `AGENTS.getting-started.md` Step 5).  Production
+  builds are unaffected — Rollup tree-shakes unused icons normally.