@pihanga2/shadcn 0.2.0 → 0.2.2

package/AGENT.using-cards.md

@@ -4,6 +4,10 @@
 > Read [`AGENT.md`](./AGENT.md) first for orientation and universal rules.
 > If you need to *create* a new card type, switch to
 > [`AGENT.building-cards.md`](./AGENT.building-cards.md).
+>
+> **Starting from scratch?**  Follow [`AGENTS.getting-started.md`](./AGENTS.getting-started.md)
+> first to scaffold your Vite project, run `shadcn init`, install `@pihanga2/core`,
+> and wire up the initial file layout.  Return here once the scaffold is in place.
 
 > 💬 **Encountered a bug, a missing card, or an agent-unfriendly doc section?**
 > Please open an issue at **https://github.com/ivcap-works/pihanga-shadcn/issues**
@@ -26,9 +30,16 @@
 > shadcn/ui and Radix UI updates, it won't appear in the playground
 > automatically, and it won't benefit from upstream bug fixes.
 >
-> **If no suitable card exists:**
-> - Confirm the need is genuine and not already covered by composing existing
->   cards (`Conditional`, `FlexGrid`, `Stack`, `Box`).
+> **⭐ If no single card covers your need but existing cards could be combined:**
+> Build a **meta card** — a TypeScript-only mapper that assembles existing cards
+> into a reusable, self-contained widget.  Meta cards require no JSX, no React
+> imports, and no DOM knowledge.  They are easier to maintain, extend, and test
+> than a bespoke React component.  See
+> [Meta cards — building complex UIs by composition](#meta-cards--building-complex-uis-by-composition)
+> below, or the full guide in
+> [`AGENT.building-cards.md`](./AGENT.building-cards.md#meta-cards--composing-new-widgets-from-existing-cards).
+>
+> **If no suitable card or card combination exists:**
 > - Unless the card would expose confidential business logic, please
 >   **open an issue** at
 >   `https://github.com/ivcap-works/pihanga-shadcn/issues` describing what you
@@ -41,12 +52,10 @@
 ## Table of Contents
 
 - [Distribution channels — choose one](#distribution-channels--choose-one)
-- [Channel 1 — shadcn registry prerequisites](#channel-1--shadcn-registry-prerequisites)
+- [Channel 1 — shadcn registry (one-time project setup)](#channel-1--shadcn-registry-one-time-project-setup)
 - [Channel 2 — npm package `@pihanga2/shadcn`](#channel-2--npm-package-pihanga2shadcn)
   - [Migrating a card from npm to a local copy](#migrating-a-card-from-npm-to-a-local-customised-copy)
 - [Vite configuration (both channels)](#vite-configuration-both-channels)
-  - [Required Vite aliases](#required-vite-aliases)
-  - [Required `src/components/lib/utils.ts`](#required-srccomponentslibutils-ts)
   - [`@pihanga2/cards` — deprecated, do not use](#pihanga2cards--deprecated-do-not-use)
   - [Type-only import gotcha](#type-only-import-gotcha--picardref-store-etc)
   - [Transitive card dependencies](#transitive-card-dependencies)
@@ -69,7 +78,7 @@
 
 | | Registry | npm package |
 |---|---|---|
-| **Install** | `npx shadcn@latest add <url>` | `npm install @pihanga2/shadcn` |
+| **Install** | `npx shadcn@latest add <url>` (or `yarn dlx shadcn@latest add <url>`) | `npm install @pihanga2/shadcn` |
 | **Cards available** | All 34 | 30 core (no graphin / jsonViewer / markdownViewer / resizable) |
 | **Requires `shadcn init`** | Yes | No |
 | **Files land in your project** | Yes — editable source | No — compiled bundle |
@@ -81,192 +90,23 @@ a clean `npm install` workflow is preferred.
 
 ---
 
-## Channel 1 — shadcn registry prerequisites
-
-### 1 — Initialise shadcn (creates `components.json` and `@/` alias)
-
-```sh
-npx shadcn@latest init
-```
-
-When prompted, choose:
-- **Style**: New York
-- **Base colour**: Neutral
-- **CSS variables**: Yes
+## Channel 1 — shadcn registry (one-time project setup)
 
-This command creates `components.json`, patches `tsconfig.json` with the `@/`
-path alias, and installs Tailwind CSS if not already present.
+> **New project?** The full one-time setup (Vite scaffold, shadcn init, Tailwind
+> theme, Vite aliases, pihanga-core install) is documented step-by-step in
+> **[`AGENTS.getting-started.md`](./AGENTS.getting-started.md)**.  Follow that
+> guide first, then return here to install and wire individual cards.
 
-### 2 — Ensure `@/cards` alias is configured
-
-Pihanga cards are copied to `src/cards/` and import each other via the
-`@/cards/` alias.  After `shadcn init`, add this alias to `tsconfig.json`:
-
-```jsonc
-// tsconfig.json  →  compilerOptions.paths
-{
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}
-```
-
-The `@/*` → `./src/*` mapping (which `shadcn init` creates) already covers
-`@/cards/` → `src/cards/`, so **no extra alias is needed** as long as cards
-are placed at `src/cards/`.
-
-If cards end up elsewhere, add an explicit alias:
-```jsonc
-"@/cards/*": ["./src/cards/*"]
-```
+Key things the setup guide covers:
 
-### 3 — Configure `src/index.css` (Tailwind v4 + shadcn theme)
-
-> **⚠️ This is a Tailwind CSS project.**  `index.html` must NOT contain any
-> `<link rel="stylesheet">` tags for external CSS frameworks (Bootstrap, Bulma,
-> etc.) or manual font CDN links, and no `<style>` blocks.  Tailwind generates
-> all styles at build time from utility classes in your source files.  Adding
-> foreign stylesheets will conflict with Tailwind's generated output and break
-> the shadcn colour variables.
-
-Tailwind v4 no longer auto-discovers shadcn's semantic CSS variables.  Without
-an explicit `@theme inline` block, classes like `bg-card`, `bg-background`, and
-`border-border` have no associated colour and render as **transparent** — causing
-dialog panels, popovers, and cards to appear invisible.
-
-In addition, Radix UI overlays (Dialog, Sheet, etc.) apply `overflow: hidden` to
-`<body>` when open, which removes the scrollbar and widens the content area by
-~15 px, causing **visible text reflow** behind the dialog backdrop.
-
-The complete reference `src/index.css` is maintained in the pihanga-shadcn
-repository.  **Copy it directly** from:
-```
-https://raw.githubusercontent.com/ivcap-works/pihanga-shadcn/main/src/index.css
-```
-or from `src/index.css` in a local clone.  The full content is reproduced below
-for reference / offline use:
-
-The required `src/index.css`:
-
-```css
-@import "tailwindcss";
-
-/*
- * Tailwind v4 — map shadcn semantic CSS variables to Tailwind colour utilities.
- * Without this @theme block, classes like bg-card / bg-background / border-border
- * have no associated colour and render as transparent.  This means dialog panels,
- * cards, popovers, etc. will appear invisible or incorrectly coloured.
- */
-@theme inline {
-  /*
-   * Brand button tokens — override these in your app to retheme variant="brand".
-   * Defaults to the primary colour family.  See the pi/button section below.
-   */
-  --color-btn-brand: var(--primary);
-  --color-btn-brand-foreground: var(--primary-foreground);
-  --radius-btn-brand: var(--radius-md);
-
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-}
-
-/* ── Light theme (shadcn neutral / new-york) ─────────────────────────────── */
-:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --radius: 0.625rem;
-}
-
-/* ── Dark theme ──────────────────────────────────────────────────────────── */
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.922 0 0);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-
-  body {
-    @apply bg-background text-foreground;
-    /*
-     * Prevent layout reflow when a dialog (or any Radix overlay) applies
-     * `overflow: hidden` to <body> to disable background scrolling.
-     * Without this, removing the scrollbar widens the content area by ~15 px
-     * and causes visible text reflow behind the dialog backdrop.
-     */
-    scrollbar-gutter: stable;
-  }
-}
-```
-
-> **Why `@theme inline`?**  Tailwind v4 separates design tokens from utility
-> generation.  shadcn stores its colours as CSS custom properties (`--card`,
-> `--background`, …) but Tailwind v4 will not generate colour utilities from
-> raw CSS variables unless they are declared inside an `@theme` block.  Without
-> it the generated CSS contains no colour definitions for those utility classes.
-
-> **Why `scrollbar-gutter: stable`?**  When a Radix dialog opens, the library
-> `@radix-ui/react-remove-scroll` sets `overflow: hidden` on `<body>` to
-> prevent background scrolling.  This hides the scrollbar and adds ~15 px of
-> width back to the page — causing text to reflow.  `scrollbar-gutter: stable`
-> reserves a permanent gutter for the scrollbar so its appearance/disappearance
-> never changes the usable width.
+- **⚠️ npx + npm 11 + Node 24 incompatibility** — use `nvm use 22` or `yarn dlx`
+  as a drop-in (see getting-started § *npx compatibility*)
+- `npx shadcn@latest init` / `yarn dlx shadcn@latest init` — creates
+  `components.json`, patches `tsconfig.json` with `@/*` alias, installs Tailwind
+- `src/index.css` — requires a full `@theme inline` block; without it `bg-card`,
+  `bg-background` etc. render transparent and dialogs appear invisible
+- `src/components/lib/utils.ts` — must create the `cn()` helper at this path
+- `vite.config.ts` aliases — `@/lib`, `@/registry`, `@/components`, `@/cards`, `@`
 
 ---
 
@@ -364,62 +204,10 @@ import-order dependency.
 
 ## Vite configuration (both channels)
 
-When building a **Vite + React + TypeScript** app from scratch (i.e. without
-using `shadcn init` or copying the playground project), the following setup is
-required regardless of whether you use the registry or the npm channel.
-
-### Required Vite aliases
-
-pihanga-shadcn cards reference each other and shadcn UI primitives via these
-path aliases.  Without the `@/registry` alias in particular, `button.component.tsx`
-(and other cards) will fail at Vite dev time with a cryptic
-`"Failed to resolve import '@/registry/ui/button'"` error.
-
-```ts
-// vite.config.ts — required for both channels
-import path from "path";
-import tailwindcss from "@tailwindcss/vite";
-import react from "@vitejs/plugin-react";
-import {defineConfig} from "vite";
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-  resolve: {
-    alias: [
-      // @/lib  →  src/lib  (shared utilities used by cards)
-      {find: "@/lib", replacement: path.resolve(__dirname, "./src/lib")},
-      // @/registry  →  src/components  (shadcn UI primitives — cards import via
-      //   "@/registry/ui/button" etc.; this alias bridges them to the local copies)
-      {find: "@/registry", replacement: path.resolve(__dirname, "./src/components")},
-      // @/components  →  src/components  (needed for cross-component imports)
-      {find: "@/components", replacement: path.resolve(__dirname, "./src/components")},
-      // @/cards  →  src/cards  (explicit card-to-card imports)
-      {find: "@/cards", replacement: path.resolve(__dirname, "./src/cards")},
-      // @  →  src  (catch-all for everything else)
-      {find: "@", replacement: path.resolve(__dirname, "./src")},
-    ],
-  },
-});
-```
-
-### Required `src/components/lib/utils.ts`
-
-All shadcn UI components (`button.tsx`, `tooltip.tsx`, `sheet.tsx`, `badge.tsx`,
-etc.) import the `cn()` helper from `@/components/lib/utils` — **not** from
-`@/lib/utils`.  Create this file:
-
-```ts
-// src/components/lib/utils.ts
-import {clsx, type ClassValue} from "clsx";
-import {twMerge} from "tailwind-merge";
-
-export function cn(...inputs: ClassValue[]): string {
-  return twMerge(clsx(inputs));
-}
-```
-
-Note that `@/lib/utils.ts` can also exist for app-level utilities; they are two
-separate files at two separate paths.
+> **Vite project setup** (aliases, `src/components/lib/utils.ts`, `src/index.css`)
+> is documented in full in **[`AGENTS.getting-started.md`](./AGENTS.getting-started.md)
+> — Step 5 & Step 2**.  The sub-sections below cover **runtime-only gotchas** that
+> apply regardless of when the project was scaffolded.
 
 ### `@pihanga2/cards` — deprecated, do not use
 
@@ -502,15 +290,28 @@ After the one-time setup (Channel 1 prerequisites above), add any card with a
 single command. `@pihanga2/core` and all card-specific npm packages are
 installed automatically.
 
+> ⚠️ **npm 11 + Node 24:** `npx` fails on this combination — use Node 22 via
+> `nvm use 22`, or use `yarn dlx` instead (see the
+> [compatibility note above](#channel-1--shadcn-registry-prerequisites)).
+
 ```sh
-# Add a single card
+# npm / npx (Node 22 recommended)
 npx shadcn@latest add https://ivcap-works.github.io/pihanga-shadcn/r/button.json
 
-# Add multiple cards at once
+# yarn (works on all supported Node versions)
+yarn dlx shadcn@latest add https://ivcap-works.github.io/pihanga-shadcn/r/button.json
+
+# Add multiple cards at once (npx)
 npx shadcn@latest add \
   https://ivcap-works.github.io/pihanga-shadcn/r/button.json \
   https://ivcap-works.github.io/pihanga-shadcn/r/form.json \
-  https://ivcap-works.github.io/pihanga-shadcn/r/dataTa.jsonle
+  https://ivcap-works.github.io/pihanga-shadcn/r/dataTable.json
+
+# Add multiple cards at once (yarn dlx)
+yarn dlx shadcn@latest add \
+  https://ivcap-works.github.io/pihanga-shadcn/r/button.json \
+  https://ivcap-works.github.io/pihanga-shadcn/r/form.json \
+  https://ivcap-works.github.io/pihanga-shadcn/r/dataTable.json
 ```
 
 ### npm channel
@@ -570,6 +371,8 @@ Full registry index: `https://ivcap-works.github.io/pihanga-shadcn/r/registry.js
 **Registry channel:**
 - `npx shadcn@latest add <url>` automatically installs `@pihanga2/core` and all
   card-specific npm packages — no separate `npm install` needed.
+- **`npx` fails on npm 11 + Node 24** — use `nvm use 22` or replace every
+  `npx shadcn@latest` with `yarn dlx shadcn@latest` (identical output).
 - Cards land at `src/cards/<card-name>/` in the consumer's project.
 - The `framework` card is the Pihanga app root — add it first for new apps.
 - `graphin` has heavy AntV dependencies (~5 MB) — only add if graph
@@ -628,6 +431,137 @@ registerCard("myApp/save", Button({
 
 ---
 
+## Meta cards — building complex UIs by composition
+
+> **⭐ This is the recommended approach whenever you need a reusable UI widget
+> that combines several existing cards.**  Prefer a meta card over writing a new
+> React component; meta cards are easier to maintain, extend, test, and port.
+
+A **meta card** is a TypeScript-only module that assembles existing primitive
+cards (or other meta cards) inside a mapper function.  No JSX, no React hooks,
+no DOM knowledge is required.
+
+### Decision guide
+
+```
+Do I need a complex, multi-widget UI?
+    │
+    ├─► Can I build it from existing cards? ──► YES ──► Write a META CARD  ⭐
+    │                                                     (registerMetaCard)
+    └─► NO — needs a DOM API / third-party React hook
+            └─► Only then: write a PRIMITIVE CARD
+                           (registerCardComponent + React component)
+```
+
+### Minimal meta card skeleton
+
+```ts
+// src/myWidget.card.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"; // use whatever cards you need
+
+// ── 1. Identity (use "meta/<name>" convention for app-local meta cards) ─────
+const MY_WIDGET_CARD = "meta/my-widget";
+
+// ── 2. Public factory ────────────────────────────────────────────────────────
+export const MyWidget = createCardDeclaration<MyWidgetProps, MyWidgetEvents>(MY_WIDGET_CARD);
+
+// ── 3. Actions ───────────────────────────────────────────────────────────────
+export const MY_WIDGET_ACTION = registerActions(MY_WIDGET_CARD, ["submitted"]);
+export const onMyWidgetSubmitted = createOnAction<MyWidgetSubmitEvent>(MY_WIDGET_ACTION.SUBMITTED);
+
+// ── 4. Types ─────────────────────────────────────────────────────────────────
+type MyWidgetProps  = { label: string; value: string };
+type MyWidgetSubmitEvent = { value: string };
+type MyWidgetEvents = { onSubmit: MyWidgetSubmitEvent };
+type MapperProps = MyWidgetProps & MyWidgetEvents;
+
+// ── 5. Mapper ────────────────────────────────────────────────────────────────
+function MyWidgetMapper(
+  _: string,
+  props: PiMapProps<MapperProps, ReduxState, object>,
+  _registerCard: RegisterCardF,
+): PiCardDef {
+  return Stack({
+    direction: "row",
+    content: [
+      Typography({ text: (_, {resolve}) => resolve(props.label) }),
+      Button({
+        label: "Submit",
+        onClickedMapper: (_, {resolve}) => ({
+          type: MY_WIDGET_ACTION.SUBMITTED,
+          value: resolve(props.value),
+        }),
+      }),
+    ],
+  });
+}
+
+// ── 6. Register ───────────────────────────────────────────────────────────────
+registerMetaCard({
+  type: MY_WIDGET_CARD,
+  mapper: MyWidgetMapper,
+  events: MY_WIDGET_ACTION,
+} satisfies PiRegisterMetaCard);
+```
+
+**Using the meta card in your app:**
+
+```ts
+// src/app.pihanga.ts
+import {MyWidget, onMyWidgetSubmitted} from "./myWidget.card";
+import type {AppState} from "./app.state";
+
+register((r) => {
+  onMyWidgetSubmitted<AppState>(r, (state, {value}) => {
+    state.submittedValue = value;
+  });
+});
+
+registerCard("app/myWidget", MyWidget<AppState>({
+  label: "Enter name",
+  value: (s) => s.currentValue,   // reactive — updates when state changes
+}));
+```
+
+### Key patterns
+
+**`resolve(props.foo)` — unwrap lazy state selectors in child props**
+
+A meta card prop may be a plain value *or* a state selector `(s) => s.foo`.
+Inside child card prop functions, always use `resolve()` to unwrap it:
+
+```ts
+// ✅ Correct
+Typography({ text: (_, {resolve}) => `Hello ${resolve(props.name)}` })
+
+// ❌ Wrong — child sees a function reference, not the resolved string
+Typography({ text: props.name })
+```
+
+**`onXxxMapper` — remap child events into domain actions**
+
+Every event-emitting card supports an `on<Event>Mapper` prop that intercepts
+the raw event and emits a different action (or `null` to suppress):
+
+```ts
+Button({
+  label: "Delete",
+  onClickedMapper: (_, {resolve}) => ({
+    type: MY_WIDGET_ACTION.SUBMITTED,
+    value: resolve(props.value),
+  }),
+})
+```
+
+**Full reference:** See [`AGENT.building-cards.md`](./AGENT.building-cards.md#meta-cards--composing-new-widgets-from-existing-cards)
+and the complete annotated example at [`example/src/counter.card.ts`](./example/src/counter.card.ts).
+
+---
+
 ## Version pinning
 
 Use a git tag in the URL to pin to a specific release:
@@ -1196,7 +1130,7 @@ project that was bootstrapped without the reference `index.css`:
 Both fixes are now included in the reference `src/index.css` template in
 *Prerequisites step 3*.
 
-### 2026-06 agent evaluation — ViteJS app from scratch (BuhlOS-2)
+### 2026-06 agent evaluation — ViteJS app from scratch
 
 An agent built a new ViteJS + React + TypeScript app from scratch using
 `yarn create vite` and then manually copied pihanga-shadcn cards.  The
@@ -1240,3 +1174,16 @@ local modifications to the registry code for features that already existed.
 | `shad/list` icon decorators silently rendered nothing when icon names were unregistered | The `shad/list` card calls `getIcon(name)` which requires icons to be pre-registered via `registerIcon()` in `src/cards/icons.ts`; this contract is not visible in the type declarations | Added *`shad/list` — icon decorators require registered icons* to *Card API quick reference* |
 | `flexGrid.component.tsx` failed to compile under `verbatimModuleSyntax` / `noImplicitAny` strict TypeScript | Registry source mixed value and type imports; had implicit `any` in `.map()` callback; `Object.entries` lacked an explicit cast; `_style` lacked widened type for `gridTemplateAreas` | Fixed directly in `flexGrid.component.tsx`: split `import type`, added explicit `row: string[]` annotation, added `as [string, PiCardRef][]` cast, widened `_style` type |
 | `stack.component.tsx` contained commented-out Joy UI dead code | Leftover from a previous MUI Joy UI implementation; the current Tailwind implementation is complete and the comment block serves no purpose | Removed the dead code block |
+
+### 2026-06 user feedback — `npx shadcn@latest add` fails on npm 11 + Node 24
+
+Users reported that every `npx shadcn@latest` command failed with
+`npm error could not determine executable to run` when running Node 24 (which
+bundles npm 11).  The docs only showed `npx` examples with no mention of a
+yarn alternative or Node version constraint.
+
+| Reported gap | Fix applied |
+|---|---|
+| No `yarn dlx` alternative documented | Added `yarn dlx shadcn@latest` as the yarn-compatible alternative in the distribution channels table, Channel 1 init step, and "Adding individual cards" commands |
+| No warning about npm 11 + Node 24 incompatibility | Added a prominent compatibility callout at the top of *Channel 1 — shadcn registry prerequisites*, with the `nvm use 22` workaround and the `yarn dlx` alternative |
+| "Notes for AI agents" section did not mention the `npx` breakage | Added a bullet noting that `npx` fails on npm 11 + Node 24 and that `yarn dlx shadcn@latest` is a drop-in replacement |

package/README.md

@@ -73,7 +73,7 @@ import "@pihanga2/shadcn/cards/dataTable";
 
 ---
 
-## Included cards (30)
+## Included cards (33)
 
 - `badge`
 - `box`
@@ -84,6 +84,7 @@ import "@pihanga2/shadcn/cards/dataTable";
 - `dialog`
 - `dropDownMenu`
 - `field`
+- `fileDrop`
 - `flexGrid`
 - `form`
 - `framework`
@@ -97,6 +98,8 @@ import "@pihanga2/shadcn/cards/dataTable";
 - `pageWithNavbar`
 - `pasteTarget`
 - `select`
+- `slider`
+- `sliderValue`
 - `stack`
 - `stepper`
 - `switch`

package/cards/badge/badge.component.js

@@ -1,5 +1,6 @@
 import { Badge as e } from "../../components/ui/badge.js";
 import { cn as t } from "../../lib/utils.js";
+import "@pihanga2/core";
 import "react";
 import { jsx as n } from "react/jsx-runtime";
 //#region src/cards/badge/badge.component.tsx

package/cards/badge/badge.component.js.map

@@ -1 +1 @@
-{"version":3,"file":"badge.component.js","names":[],"sources":["../../../src/cards/badge/badge.component.tsx"],"sourcesContent":["import * as React from \"react\";\nimport {type PiCardProps} from \"@pihanga2/core\";\nimport {Badge} from \"@/components/ui/badge\";\nimport {cn} from \"@/lib/utils\";\nimport type {BadgeCardProps} from \"./badge.types\";\n\n/**\n * `shad/badge` card component.\n *\n * Renders a shadcn `<Badge>` element with a `label` and an optional `variant`.\n * The variant vocabulary is intentionally identical to the `BadgeColumn.variants`\n * map used by the `shad/data-table` card, so both can be driven from the same\n * source-of-truth value:\n *\n *   \"default\" | \"secondary\" | \"destructive\" | \"outline\"\n */\nexport const BadgeComponent = (\n  props: PiCardProps<BadgeCardProps>,\n): React.ReactNode => {\n  const {label, variant = \"secondary\", className, cardName} = props;\n\n  return (\n    <Badge\n      variant={variant}\n      className={cn(className)}\n      data-pihanga={cardName}\n    >\n      {label}\n    </Badge>\n  );\n};\n"],"mappings":";;;;;AAgBA,IAAa,KACX,MACoB;CACpB,IAAM,EAAC,UAAO,aAAU,aAAa,cAAW,gBAAY;CAE5D,OACE,kBAAC,GAAD;EACW;EACT,WAAW,EAAG,CAAS;EACvB,gBAAc;YAEb;CACI,CAAA;AAEX"}
+{"version":3,"file":"badge.component.js","names":[],"sources":["../../../src/cards/badge/badge.component.tsx"],"sourcesContent":["import * as React from \"react\";\nimport {type PiCardProps} from \"@pihanga2/core\";\nimport {Badge} from \"@/components/ui/badge\";\nimport {cn} from \"@/lib/utils\";\nimport type {BadgeCardProps} from \"./badge.types\";\n\n/**\n * `shad/badge` card component.\n *\n * Renders a shadcn `<Badge>` element with a `label` and an optional `variant`.\n * The variant vocabulary is intentionally identical to the `BadgeColumn.variants`\n * map used by the `shad/data-table` card, so both can be driven from the same\n * source-of-truth value:\n *\n *   \"default\" | \"secondary\" | \"destructive\" | \"outline\"\n */\nexport const BadgeComponent = (\n  props: PiCardProps<BadgeCardProps>,\n): React.ReactNode => {\n  const {label, variant = \"secondary\", className, cardName} = props;\n\n  return (\n    <Badge\n      variant={variant}\n      className={cn(className)}\n      data-pihanga={cardName}\n    >\n      {label}\n    </Badge>\n  );\n};\n"],"mappings":";;;;;;AAgBA,IAAa,KACX,MACoB;CACpB,IAAM,EAAC,UAAO,aAAU,aAAa,cAAW,gBAAY;CAE5D,OACE,kBAAC,GAAD;EACW;EACT,WAAW,EAAG,CAAS;EACvB,gBAAc;YAEb;CACI,CAAA;AAEX"}

package/cards/box/box.component.js

@@ -3,8 +3,8 @@ import "react";
 import { jsx as t, jsxs as n } from "react/jsx-runtime";
 //#region src/cards/box/box.component.tsx
 var r = (r) => {
-	let { content: i, className: a, style: o, cardName: s } = r, c = {};
-	r.height && (c.height = `${r.height}px`), r.width && (c.height = `${r.width}px`), r.marginTop && (c["margin-top"] = `${r.marginTop}px`), r.marginBottom && (c["margin-bottom"] = `${r.marginBottom}px`), r.marginLeft && (c["margin-ledt"] = `${r.marginLeft}px`), r.marginRight && (c["margin-right"] = `${r.marginRight}px`), r.paddingTop && (c["padding-top"] = `${r.paddingTop}px`), r.paddingBottom && (c["padding-bottom"] = `${r.paddingBottom}px`), r.paddingLeft && (c["padding-ledt"] = `${r.paddingLeft}px`), r.paddingRight && (c["padding-right"] = `${r.paddingRight}px`), c = { ...o?.shad };
+	let { content: i, className: a, style: o, cardName: s } = r, c = { ...o };
+	r.height && (c.height = `${r.height}px`), r.width && (c.width = `${r.width}px`), r.marginTop && (c.marginTop = `${r.marginTop}px`), r.marginBottom && (c.marginBottom = `${r.marginBottom}px`), r.marginLeft && (c.marginLeft = `${r.marginLeft}px`), r.marginRight && (c.marginRight = `${r.marginRight}px`), r.paddingTop && (c.paddingTop = `${r.paddingTop}px`), r.paddingBottom && (c.paddingBottom = `${r.paddingBottom}px`), r.paddingLeft && (c.paddingLeft = `${r.paddingLeft}px`), r.paddingRight && (c.paddingRight = `${r.paddingRight}px`);
 	function l() {
 		return i ? i.map((n, r) => /* @__PURE__ */ t(e, {
 			cardName: n,

package/cards/box/box.component.js.map

@@ -1 +1 @@
-{"version":3,"file":"box.component.js","names":[],"sources":["../../../src/cards/box/box.component.tsx"],"sourcesContent":["import * as React from \"react\";\n\nimport {Card, type PiCardProps} from \"@pihanga2/core\";\nimport type {BoxProps} from \"./box.types\";\n\nexport const BoxComponent = (props: PiCardProps<BoxProps>): React.ReactNode => {\n  const {content, className, style, cardName} = props;\n\n  let sy: Record<string, string | number> = {};\n  if (props.height) sy.height = `${props.height}px`;\n  if (props.width) sy.height = `${props.width}px`;\n\n  if (props.marginTop) sy[\"margin-top\"] = `${props.marginTop}px`;\n  if (props.marginBottom) sy[\"margin-bottom\"] = `${props.marginBottom}px`;\n  if (props.marginLeft) sy[\"margin-ledt\"] = `${props.marginLeft}px`;\n  if (props.marginRight) sy[\"margin-right\"] = `${props.marginRight}px`;\n\n  if (props.paddingTop) sy[\"padding-top\"] = `${props.paddingTop}px`;\n  if (props.paddingBottom) sy[\"padding-bottom\"] = `${props.paddingBottom}px`;\n  if (props.paddingLeft) sy[\"padding-ledt\"] = `${props.paddingLeft}px`;\n  if (props.paddingRight) sy[\"padding-right\"] = `${props.paddingRight}px`;\n\n  sy = {\n    ...(style as {shad?: Record<string, string | number>} | undefined)?.shad,\n  };\n\n  function renderContent() {\n    if (!content) return null;\n    return content.map((cn, i) => (\n      <Card cardName={cn} parentCard={cardName} key={i} />\n    ));\n  }\n\n  return (\n    <div className={className} style={sy} data-pihanga={cardName}>\n      {renderContent()}\n      {props.children}\n    </div>\n  );\n};\n"],"mappings":";;;;AAKA,IAAa,KAAgB,MAAkD;CAC7E,IAAM,EAAC,YAAS,cAAW,UAAO,gBAAY,GAE1C,IAAsC,CAAC;CAc3C,AAbI,EAAM,WAAQ,EAAG,SAAS,GAAG,EAAM,OAAO,MAC1C,EAAM,UAAO,EAAG,SAAS,GAAG,EAAM,MAAM,MAExC,EAAM,cAAW,EAAG,gBAAgB,GAAG,EAAM,UAAU,MACvD,EAAM,iBAAc,EAAG,mBAAmB,GAAG,EAAM,aAAa,MAChE,EAAM,eAAY,EAAG,iBAAiB,GAAG,EAAM,WAAW,MAC1D,EAAM,gBAAa,EAAG,kBAAkB,GAAG,EAAM,YAAY,MAE7D,EAAM,eAAY,EAAG,iBAAiB,GAAG,EAAM,WAAW,MAC1D,EAAM,kBAAe,EAAG,oBAAoB,GAAG,EAAM,cAAc,MACnE,EAAM,gBAAa,EAAG,kBAAkB,GAAG,EAAM,YAAY,MAC7D,EAAM,iBAAc,EAAG,mBAAmB,GAAG,EAAM,aAAa,MAEpE,IAAK,EACH,GAAI,GAAgE,KACtE;CAEA,SAAS,IAAgB;EAEvB,OADK,IACE,EAAQ,KAAK,GAAI,MACtB,kBAAC,GAAD;GAAM,UAAU;GAAI,YAAY;EAAmB,GAAJ,CAAI,CACpD,IAHoB;CAIvB;CAEA,OACE,kBAAC,OAAD;EAAgB;EAAW,OAAO;EAAI,gBAAc;YAApD,CACG,EAAc,GACd,EAAM,QACJ;;AAET"}
+{"version":3,"file":"box.component.js","names":[],"sources":["../../../src/cards/box/box.component.tsx"],"sourcesContent":["import * as React from \"react\";\n\nimport {Card, type PiCardProps} from \"@pihanga2/core\";\nimport type {BoxProps} from \"./box.types\";\n\nexport const BoxComponent = (props: PiCardProps<BoxProps>): React.ReactNode => {\n  const {content, className, style, cardName} = props;\n\n  const sy: Record<string, string | number> = {\n    ...(style as Record<string, string | number> | undefined),\n  };\n  if (props.height) sy.height = `${props.height}px`;\n  if (props.width) sy.width = `${props.width}px`;\n\n  if (props.marginTop) sy.marginTop = `${props.marginTop}px`;\n  if (props.marginBottom) sy.marginBottom = `${props.marginBottom}px`;\n  if (props.marginLeft) sy.marginLeft = `${props.marginLeft}px`;\n  if (props.marginRight) sy.marginRight = `${props.marginRight}px`;\n\n  if (props.paddingTop) sy.paddingTop = `${props.paddingTop}px`;\n  if (props.paddingBottom) sy.paddingBottom = `${props.paddingBottom}px`;\n  if (props.paddingLeft) sy.paddingLeft = `${props.paddingLeft}px`;\n  if (props.paddingRight) sy.paddingRight = `${props.paddingRight}px`;\n\n  function renderContent() {\n    if (!content) return null;\n    return content.map((cn, i) => (\n      <Card cardName={cn} parentCard={cardName} key={i} />\n    ));\n  }\n\n  return (\n    <div className={className} style={sy} data-pihanga={cardName}>\n      {renderContent()}\n      {props.children}\n    </div>\n  );\n};\n"],"mappings":";;;;AAKA,IAAa,KAAgB,MAAkD;CAC7E,IAAM,EAAC,YAAS,cAAW,UAAO,gBAAY,GAExC,IAAsC,EAC1C,GAAI,EACN;CAYA,AAXI,EAAM,WAAQ,EAAG,SAAS,GAAG,EAAM,OAAO,MAC1C,EAAM,UAAO,EAAG,QAAQ,GAAG,EAAM,MAAM,MAEvC,EAAM,cAAW,EAAG,YAAY,GAAG,EAAM,UAAU,MACnD,EAAM,iBAAc,EAAG,eAAe,GAAG,EAAM,aAAa,MAC5D,EAAM,eAAY,EAAG,aAAa,GAAG,EAAM,WAAW,MACtD,EAAM,gBAAa,EAAG,cAAc,GAAG,EAAM,YAAY,MAEzD,EAAM,eAAY,EAAG,aAAa,GAAG,EAAM,WAAW,MACtD,EAAM,kBAAe,EAAG,gBAAgB,GAAG,EAAM,cAAc,MAC/D,EAAM,gBAAa,EAAG,cAAc,GAAG,EAAM,YAAY,MACzD,EAAM,iBAAc,EAAG,eAAe,GAAG,EAAM,aAAa;CAEhE,SAAS,IAAgB;EAEvB,OADK,IACE,EAAQ,KAAK,GAAI,MACtB,kBAAC,GAAD;GAAM,UAAU;GAAI,YAAY;EAAmB,GAAJ,CAAI,CACpD,IAHoB;CAIvB;CAEA,OACE,kBAAC,OAAD;EAAgB;EAAW,OAAO;EAAI,gBAAc;YAApD,CACG,EAAc,GACd,EAAM,QACJ;;AAET"}

package/cards/box/box.types.d.ts

@@ -1,5 +1,4 @@
 import { PiCardRef } from '@pihanga2/core';
-import { AlignItemsT } from '../types';
 export declare const BOX_CARD = "shad/box";
 /**
  * Responsive display grid breakpoints.
@@ -37,13 +36,6 @@ export type BoxProps<S = object> = {
     paddingBottom?: number;
     paddingLeft?: number;
     paddingRight?: number;
-    alignItems?: AlignItemsT;
-    /** Tailwind gap spacing units */
-    gap?: number;
-    /** Uniform padding in pixels */
-    padding?: number;
-    /** Responsive display grid breakpoints */
-    display?: DisplayGridT;
     /** Card style object (use the `shad` key for Tailwind-compatible overrides) */
     style?: S;
     /** Additional Tailwind utility classes */

package/cards/box/box.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"box.types.js","names":[],"sources":["../../../src/cards/box/box.types.ts"],"sourcesContent":["import {type PiCardRef, createCardDeclaration} from \"@pihanga2/core\";\nimport { AlignItemsT } from \"../types\";\n\nexport const BOX_CARD = \"shad/box\";\n\n/**\n * Responsive display grid breakpoints.\n *\n * Each key maps to a CSS display value applied at that viewport width:\n * - `xs`: < 640 px (default / mobile-first)\n * - `sm`: ≥ 640 px\n * - `md`: ≥ 768 px\n * - `lg`: ≥ 1024 px\n * - `xl`: ≥ 1280 px\n * - `xxl`: ≥ 1536 px\n */\nexport type DisplayGridT = {\n  xs?: string;\n  sm?: string;\n  md?: string;\n  lg?: string;\n  xl?: string;\n  xxl?: string;\n};\n\nexport type BoxProps<S = object> = {\n  /** Child card refs rendered inside the box */\n  content?: PiCardRef[];\n\n  /** Override the root element type */\n  component?: React.ElementType;\n\n  /** Fixed height in pixels */\n  height?: number;\n  /** Fixed width in pixels */\n  width?: number;\n\n  marginTop?: number;\n  marginBottom?: number;\n  marginLeft?: number;\n  marginRight?: number;\n\n  paddingTop?: number;\n  paddingBottom?: number;\n  paddingLeft?: number;\n  paddingRight?: number;\n\n  alignItems?: AlignItemsT;\n  /** Tailwind gap spacing units */\n  gap?: number;\n  /** Uniform padding in pixels */\n  padding?: number;\n  /** Responsive display grid breakpoints */\n  display?: DisplayGridT;\n\n  /** Card style object (use the `shad` key for Tailwind-compatible overrides) */\n  style?: S;\n  /** Additional Tailwind utility classes */\n  className?: string;\n};\n\n/**\n * Factory function for declaring a `shad/box` card instance.\n *\n * ```ts\n * import {registerCard} from \"@pihanga2/core\";\n * import {Box} from \"@/cards/box\";\n *\n * registerCard(\"myApp/spacer\", Box({height: 24}));\n *\n * registerCard(\"myApp/contentRegion\", Box({\n *   content:    [\"myApp/card1\", \"myApp/card2\"],\n *   paddingTop: 16,\n *   className:  \"rounded-lg border bg-card\",\n * }));\n * ```\n */\nexport const Box = createCardDeclaration<BoxProps>(BOX_CARD);\n"],"mappings":";;AAGA,IAAa,IAAW,YA0EX,IAAM,EAAgC,CAAQ"}
+{"version":3,"file":"box.types.js","names":[],"sources":["../../../src/cards/box/box.types.ts"],"sourcesContent":["import {type PiCardRef, createCardDeclaration} from \"@pihanga2/core\";\n\nexport const BOX_CARD = \"shad/box\";\n\n/**\n * Responsive display grid breakpoints.\n *\n * Each key maps to a CSS display value applied at that viewport width:\n * - `xs`: < 640 px (default / mobile-first)\n * - `sm`: ≥ 640 px\n * - `md`: ≥ 768 px\n * - `lg`: ≥ 1024 px\n * - `xl`: ≥ 1280 px\n * - `xxl`: ≥ 1536 px\n */\nexport type DisplayGridT = {\n  xs?: string;\n  sm?: string;\n  md?: string;\n  lg?: string;\n  xl?: string;\n  xxl?: string;\n};\n\nexport type BoxProps<S = object> = {\n  /** Child card refs rendered inside the box */\n  content?: PiCardRef[];\n\n  /** Override the root element type */\n  component?: React.ElementType;\n\n  /** Fixed height in pixels */\n  height?: number;\n  /** Fixed width in pixels */\n  width?: number;\n\n  marginTop?: number;\n  marginBottom?: number;\n  marginLeft?: number;\n  marginRight?: number;\n\n  paddingTop?: number;\n  paddingBottom?: number;\n  paddingLeft?: number;\n  paddingRight?: number;\n\n  /** Card style object (use the `shad` key for Tailwind-compatible overrides) */\n  style?: S;\n  /** Additional Tailwind utility classes */\n  className?: string;\n};\n\n/**\n * Factory function for declaring a `shad/box` card instance.\n *\n * ```ts\n * import {registerCard} from \"@pihanga2/core\";\n * import {Box} from \"@/cards/box\";\n *\n * registerCard(\"myApp/spacer\", Box({height: 24}));\n *\n * registerCard(\"myApp/contentRegion\", Box({\n *   content:    [\"myApp/card1\", \"myApp/card2\"],\n *   paddingTop: 16,\n *   className:  \"rounded-lg border bg-card\",\n * }));\n * ```\n */\nexport const Box = createCardDeclaration<BoxProps>(BOX_CARD);\n"],"mappings":";;AAEA,IAAa,IAAW,YAkEX,IAAM,EAAgC,CAAQ"}

package/cards/button/button.types.d.ts

@@ -4,6 +4,10 @@ export declare const Button: <S extends import('@pihanga2/core').ReduxState>(p:
 export declare const PI_BUTTON_ACTION: {
     CLICKED: string;
 };
+export declare const onButtonClicked: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, import('@pihanga2/core').ReduxAction & {
+    cardID: string;
+} & PiButtonClickedEvent>) => void;
+/** @deprecated Use `onButtonClicked` instead. */
 export declare const onPiButtonClicked: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, import('@pihanga2/core').ReduxAction & {
     cardID: string;
 } & PiButtonClickedEvent>) => void;

package/cards/button/button.types.js

@@ -1,7 +1,7 @@
 import { createCardDeclaration as e, createOnAction as t, registerActions as n } from "@pihanga2/core";
 //#region src/cards/button/button.types.ts
-var r = "pi/button", i = e(r), a = n(r, ["clicked"]), o = t(a.CLICKED);
+var r = "pi/button", i = e(r), a = n(r, ["clicked"]), o = t(a.CLICKED), s = o;
 //#endregion
-export { i as Button, a as PI_BUTTON_ACTION, r as PI_BUTTON_CARD, o as onPiButtonClicked };
+export { i as Button, a as PI_BUTTON_ACTION, r as PI_BUTTON_CARD, o as onButtonClicked, s as onPiButtonClicked };
 
 //# sourceMappingURL=button.types.js.map