@pihanga2/shadcn 0.2.0 → 0.2.1

package/AGENT.md

@@ -30,12 +30,19 @@ 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) |
 
-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`.
+
+Switch to `AGENT.building-cards.md` only when you need to add a new card *type*
+to `src/cards/` itself.
 
 ---
 

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**
@@ -41,12 +45,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 +71,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 +83,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
-
-This command creates `components.json`, patches `tsconfig.json` with the `@/`
-path alias, and installs Tailwind CSS if not already present.
-
-### 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/*"]
-```
-
-### 3 — Configure `src/index.css` (Tailwind v4 + shadcn theme)
+## Channel 1 — shadcn registry (one-time project setup)
 
-> **⚠️ 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.
+> **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.
 
-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.
+Key things the setup guide covers:
 
-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 +197,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 +283,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 +364,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
@@ -1240,3 +1036,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/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?.shad };
+	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 {shad?: Record<string, string | number>} | undefined)?.shad,\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,GAAgE,KACtE;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/button/button.types.d.ts

@@ -4,6 +4,9 @@ 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;
 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

package/cards/button/button.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"button.types.js","names":[],"sources":["../../../src/cards/button/button.types.ts"],"sourcesContent":["import {\n  createCardDeclaration,\n  createOnAction,\n  PiCardRef,\n  registerActions,\n} from \"@pihanga2/core\";\n\nexport const PI_BUTTON_CARD = \"pi/button\";\n\nexport const Button = createCardDeclaration<PiButtonProps, PiButtonEvents>(\n  PI_BUTTON_CARD,\n);\n\nexport const PI_BUTTON_ACTION = registerActions(PI_BUTTON_CARD, [\"clicked\"]);\n\nexport const onPiButtonClicked = createOnAction<PiButtonClickedEvent>(\n  PI_BUTTON_ACTION.CLICKED,\n);\n\n/**\n * Declarative \"opts\" subset based on `src/registry/ui/button.tsx`.\n *\n * Notes:\n * - Any icon is referenced by name and resolved via `src/pihanga/icons.ts`.\n * - `children` are provided via `label` (simple) or `content` (card ref).\n */\nexport type PiButtonOpts = {\n  /**\n   * Visual style variant of the button.\n   * Determines the button's appearance (colors, borders, etc.).\n   */\n  variant?:\n    | \"default\"\n    | \"destructive\"\n    | \"outline\"\n    | \"secondary\"\n    | \"ghost\"\n    | \"ghost2\"\n    | \"ghost3\"\n    | \"ghostActive\"\n    | \"brand\"\n    | \"nav\"\n    | \"navAction\"\n    | \"menuAction\"\n    | \"blockAction\"\n    | \"blockActionSecondary\"\n    | \"primaryOutline\"\n    | \"radio\"\n    | \"none\";\n\n  /**\n   * Size of the button.\n   * Controls padding, font size, and overall dimensions.\n   */\n  size?:\n    | \"default\"\n    | \"xs\"\n    | \"sm\"\n    | \"md\"\n    | \"lg\"\n    | \"icon\"\n    | \"iconSm\"\n    | \"navAction\"\n    | \"menuAction\"\n    | \"blockAction\"\n    | \"none\";\n\n  /** Truncate button content with ellipsis if it overflows. */\n  truncate?: boolean;\n\n  /** If true, button is rendered as a menu trigger button. */\n  isMenu?: boolean;\n\n  /** Custom CSS class to apply to the loading spinner/indicator. */\n  loadingClassName?: string;\n\n  /** Icon to display before the button content. Set 'size' to 'icon' if ONLY show icon */\n  beforeIcon?: string;\n\n  /** Icon to display after the button content */\n  afterIcon?: string;\n};\n\nexport type PiButtonProps = {\n  id?: string; // optional 'id' to be added to events\n\n  /**\n   * Optional explicit aria-label.\n   *\n   * Useful for icon-only / letter-only buttons where the visible content\n   * shouldn't be used as the accessible name.\n   */\n  ariaLabel?: string;\n\n  /**\n   * Declarative options; maps closely to `@/registry/ui/button`.\n   */\n  opts?: PiButtonOpts;\n\n  /** Simple label; used as children and aria-label fallback. */\n  label?: string;\n\n  /**\n   * Icon name to use as the main button content (instead of text label).\n   * Resolved via `src/pihanga/icons.ts`.\n   * Takes precedence over `label` and `contentCard`.\n   */\n  iconLabel?: string;\n\n  /**\n   * If set, renders this card as the content instead of `label`.\n   * (Useful for rich content.)\n   */\n  contentCard?: PiCardRef;\n\n  /** When provided, button will render as an anchor. */\n  href?: string;\n  target?: string;\n\n  tooltip?: string;\n\n  /**\n   * If set, renders this card as the tooltip content instead of `tooltip`.\n   * (Useful for rich tooltip content.)\n   */\n  tooltipCard?: PiCardRef;\n\n  /**\n   * Controls tooltip visibility mode.\n   * - 'auto' (default): Normal hover behavior\n   * - 'open': Force tooltip to be visible\n   * - 'closed': Force tooltip to be hidden\n   */\n  tooltipMode?: \"auto\" | \"open\" | \"closed\";\n\n  /**\n   * Controls tooltip placement/position.\n   * - 'top': Tooltip appears above the button (default)\n   * - 'right': Tooltip appears to the right of the button\n   * - 'bottom': Tooltip appears below the button\n   * - 'left': Tooltip appears to the left of the button\n   */\n  tooltipPlacement?: \"top\" | \"right\" | \"bottom\" | \"left\";\n\n  /** Indicates whether the button is in an active/selected state. */\n  active?: boolean;\n\n  /** Indicates whether the button has focus state styling applied. */\n  focused?: boolean;\n\n  /** If true, disables the button and prevents interaction. */\n  disabled?: boolean;\n\n  /** If true, shows loading state and typically disables interaction. */\n  loading?: boolean;\n\n  /** If true, indicates an async operation is pending (similar to loading but distinct). */\n  isPending?: boolean;\n\n  className?: string;\n};\n\nexport type PiButtonClickedEvent = {\n  id?: string;\n};\n\nexport type PiButtonEvents = {\n  onClicked: PiButtonClickedEvent;\n};\n"],"mappings":";;AAOA,IAAa,IAAiB,aAEjB,IAAS,EACpB,CACF,GAEa,IAAmB,EAAgB,GAAgB,CAAC,SAAS,CAAC,GAE9D,IAAoB,EAC/B,EAAiB,OACnB"}
+{"version":3,"file":"button.types.js","names":[],"sources":["../../../src/cards/button/button.types.ts"],"sourcesContent":["import {\n  createCardDeclaration,\n  createOnAction,\n  PiCardRef,\n  registerActions,\n} from \"@pihanga2/core\";\n\nexport const PI_BUTTON_CARD = \"pi/button\";\n\nexport const Button = createCardDeclaration<PiButtonProps, PiButtonEvents>(\n  PI_BUTTON_CARD,\n);\n\nexport const PI_BUTTON_ACTION = registerActions(PI_BUTTON_CARD, [\"clicked\"]);\n\nexport const onButtonClicked = createOnAction<PiButtonClickedEvent>(\n  PI_BUTTON_ACTION.CLICKED,\n);\n\n/* @deprecated Use `onButtonClicked` instead. */\nexport const onPiButtonClicked = onButtonClicked;\n\n/**\n * Declarative \"opts\" subset based on `src/registry/ui/button.tsx`.\n *\n * Notes:\n * - Any icon is referenced by name and resolved via `src/pihanga/icons.ts`.\n * - `children` are provided via `label` (simple) or `content` (card ref).\n */\nexport type PiButtonOpts = {\n  /**\n   * Visual style variant of the button.\n   * Determines the button's appearance (colors, borders, etc.).\n   */\n  variant?:\n    | \"default\"\n    | \"destructive\"\n    | \"outline\"\n    | \"secondary\"\n    | \"ghost\"\n    | \"ghost2\"\n    | \"ghost3\"\n    | \"ghostActive\"\n    | \"brand\"\n    | \"nav\"\n    | \"navAction\"\n    | \"menuAction\"\n    | \"blockAction\"\n    | \"blockActionSecondary\"\n    | \"primaryOutline\"\n    | \"radio\"\n    | \"none\";\n\n  /**\n   * Size of the button.\n   * Controls padding, font size, and overall dimensions.\n   */\n  size?:\n    | \"default\"\n    | \"xs\"\n    | \"sm\"\n    | \"md\"\n    | \"lg\"\n    | \"icon\"\n    | \"iconSm\"\n    | \"navAction\"\n    | \"menuAction\"\n    | \"blockAction\"\n    | \"none\";\n\n  /** Truncate button content with ellipsis if it overflows. */\n  truncate?: boolean;\n\n  /** If true, button is rendered as a menu trigger button. */\n  isMenu?: boolean;\n\n  /** Custom CSS class to apply to the loading spinner/indicator. */\n  loadingClassName?: string;\n\n  /** Icon to display before the button content. Set 'size' to 'icon' if ONLY show icon */\n  beforeIcon?: string;\n\n  /** Icon to display after the button content */\n  afterIcon?: string;\n};\n\nexport type PiButtonProps = {\n  id?: string; // optional 'id' to be added to events\n\n  /**\n   * Optional explicit aria-label.\n   *\n   * Useful for icon-only / letter-only buttons where the visible content\n   * shouldn't be used as the accessible name.\n   */\n  ariaLabel?: string;\n\n  /**\n   * Declarative options; maps closely to `@/registry/ui/button`.\n   */\n  opts?: PiButtonOpts;\n\n  /** Simple label; used as children and aria-label fallback. */\n  label?: string;\n\n  /**\n   * Icon name to use as the main button content (instead of text label).\n   * Resolved via `src/pihanga/icons.ts`.\n   * Takes precedence over `label` and `contentCard`.\n   */\n  iconLabel?: string;\n\n  /**\n   * If set, renders this card as the content instead of `label`.\n   * (Useful for rich content.)\n   */\n  contentCard?: PiCardRef;\n\n  /** When provided, button will render as an anchor. */\n  href?: string;\n  target?: string;\n\n  tooltip?: string;\n\n  /**\n   * If set, renders this card as the tooltip content instead of `tooltip`.\n   * (Useful for rich tooltip content.)\n   */\n  tooltipCard?: PiCardRef;\n\n  /**\n   * Controls tooltip visibility mode.\n   * - 'auto' (default): Normal hover behavior\n   * - 'open': Force tooltip to be visible\n   * - 'closed': Force tooltip to be hidden\n   */\n  tooltipMode?: \"auto\" | \"open\" | \"closed\";\n\n  /**\n   * Controls tooltip placement/position.\n   * - 'top': Tooltip appears above the button (default)\n   * - 'right': Tooltip appears to the right of the button\n   * - 'bottom': Tooltip appears below the button\n   * - 'left': Tooltip appears to the left of the button\n   */\n  tooltipPlacement?: \"top\" | \"right\" | \"bottom\" | \"left\";\n\n  /** Indicates whether the button is in an active/selected state. */\n  active?: boolean;\n\n  /** Indicates whether the button has focus state styling applied. */\n  focused?: boolean;\n\n  /** If true, disables the button and prevents interaction. */\n  disabled?: boolean;\n\n  /** If true, shows loading state and typically disables interaction. */\n  loading?: boolean;\n\n  /** If true, indicates an async operation is pending (similar to loading but distinct). */\n  isPending?: boolean;\n\n  className?: string;\n};\n\nexport type PiButtonClickedEvent = {\n  id?: string;\n};\n\nexport type PiButtonEvents = {\n  onClicked: PiButtonClickedEvent;\n};\n"],"mappings":";;AAOA,IAAa,IAAiB,aAEjB,IAAS,EACpB,CACF,GAEa,IAAmB,EAAgB,GAAgB,CAAC,SAAS,CAAC,GAE9D,IAAkB,EAC7B,EAAiB,OACnB,GAGa,IAAoB"}

package/cards/button/index.js

@@ -1,13 +1,13 @@
 import { ButtonComponent as e } from "./button.component.js";
-import { Button as t, PI_BUTTON_ACTION as n, PI_BUTTON_CARD as r, onPiButtonClicked as i } from "./button.types.js";
-import { actionTypesToEvents as a, registerCardComponent as o } from "@pihanga2/core";
+import { Button as t, PI_BUTTON_ACTION as n, PI_BUTTON_CARD as r, onButtonClicked as i, onPiButtonClicked as a } from "./button.types.js";
+import { actionTypesToEvents as o, registerCardComponent as s } from "@pihanga2/core";
 //#region src/cards/button/index.ts
-o({
+s({
 	name: r,
 	component: e,
-	events: a(n)
+	events: o(n)
 });
 //#endregion
-export { t as Button, n as PI_BUTTON_ACTION, r as PI_BUTTON_CARD, i as onPiButtonClicked };
+export { t as Button, n as PI_BUTTON_ACTION, r as PI_BUTTON_CARD, i as onButtonClicked, a as onPiButtonClicked };
 
 //# sourceMappingURL=index.js.map

package/cards/chartGraph/chartGraph.component.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { PiCardProps } from '@pihanga2/core';
+import { PiChartGraphProps } from './chartGraph.types';
+export declare const ChartGraphComponent: (props: PiCardProps<PiChartGraphProps>) => React.ReactNode;

package/cards/chartGraph/chartGraph.types.d.ts

@@ -0,0 +1,102 @@
+import { ChartConfig } from '../../components/ui/chart';
+export declare const PI_CHART_GRAPH_CARD = "shad/chart-graph";
+export declare const ChartGraph: <S extends import('@pihanga2/core').ReduxState>(p: import('@pihanga2/core').PiMapProps<PiChartGraphProps, S, {}>) => import('@pihanga2/core').PiCardDef;
+export type { ChartConfig };
+export type PiChartSeries = {
+    /** Key in each data-point object whose value will be plotted on the y-axis. */
+    dataKey: string;
+    /** Human-readable label used in the tooltip and legend. Defaults to `dataKey`. */
+    label?: string;
+    /**
+     * CSS colour string for this series.
+     * Falls back to the shadcn chart CSS variables
+     * (`hsl(var(--chart-1))`, `hsl(var(--chart-2))`, …) in order.
+     */
+    color?: string;
+};
+export type PiChartGraphProps = {
+    /**
+     * Whether to render an **area** chart (filled) or a **line** chart (stroke only).
+     */
+    chartType: "area" | "line";
+    /**
+     * Array of data points.  Each entry must contain:
+     * - a value for `xDataKey` (used for the x-axis labels), and
+     * - a numeric value for each `series[].dataKey`.
+     *
+     * @example
+     * ```ts
+     * [
+     *   { month: "Jan", desktop: 186, mobile: 80 },
+     *   { month: "Feb", desktop: 305, mobile: 200 },
+     * ]
+     * ```
+     */
+    data: Array<Record<string, unknown>>;
+    /**
+     * Series definitions.  Each entry describes one plotted line or area.
+     * At least one series is required.
+     */
+    series: PiChartSeries[];
+    /** Key inside each data-point object used for the x-axis tick labels. */
+    xDataKey: string;
+    /**
+     * Optional card title rendered above the chart.
+     * When either `title` or `description` is set the chart is wrapped in a
+     * shadcn `<Card>` shell; otherwise it renders as a bare `<div>`.
+     */
+    title?: string;
+    /**
+     * Optional subtitle rendered below `title`.
+     * Has no effect when `title` is not set.
+     */
+    description?: string;
+    /**
+     * Minimum chart height in pixels.
+     * The chart expands if the responsive container requires more space.
+     * Defaults to `250`.
+     */
+    height?: number;
+    /** Show a legend beneath the chart.  Defaults to `true`. */
+    showLegend?: boolean;
+    /** Show horizontal cartesian grid lines.  Defaults to `true`. */
+    showGrid?: boolean;
+    /**
+     * Show the y-axis with numeric tick labels on the left edge of the chart.
+     * Defaults to `false` (y-axis hidden) to keep the chart compact.
+     */
+    showYAxis?: boolean;
+    /**
+     * Unit string appended to every y-axis tick label (e.g. `"ms"`, `"%"`, `" km"`).
+     * Only visible when `showYAxis` is `true`.
+     *
+     * @example `yAxisUnit="%"` renders ticks as `"0%"`, `"50%"`, `"100%"`.
+     */
+    yAxisUnit?: string;
+    /**
+     * Unit string appended to every x-axis tick label.
+     * Useful when x-axis values are numeric (e.g. seconds, iterations).
+     * Has no effect when x-axis values are already formatted strings (e.g. month names).
+     *
+     * @example `xAxisUnit="s"` renders ticks as `"1s"`, `"2s"`, etc.
+     */
+    xAxisUnit?: string;
+    /**
+     * Stack all area series on top of each other (area chart only).
+     * When `false` (default) the filled areas overlap.
+     */
+    stacked?: boolean;
+    /**
+     * Opacity of the filled area (area chart only).
+     * Range 0–1.  Defaults to `0.4`.
+     */
+    fillOpacity?: number;
+    /**
+     * Suppress the recharts entry animation so the chart renders immediately
+     * without the "draw-in" / "unfold" effect.
+     * Defaults to `false` (animation enabled).
+     */
+    suppressAnimation?: boolean;
+    /** Extra Tailwind / CSS classes forwarded to the outermost element. */
+    className?: string;
+};

package/cards/chartGraph/index.d.ts

@@ -0,0 +1 @@
+export * from './chartGraph.types';

package/cards/conditional/conditional.component.d.ts

@@ -4,8 +4,19 @@ import * as React from "react";
 /**
  * ConditionalComponent
  *
- * Transparent pass-through: renders the `content` card when `show` is `true`,
- * returns `null` otherwise.  No extra DOM wrapper is added — the mounted
- * card's own root element is the only node in the tree.
+ * Renders the `content` card when the combined visibility condition is `true`,
+ * returns `null` otherwise.
+ *
+ * Visibility rules (all must be satisfied):
+ *  1. `show`          — manual boolean gate (defaults to `true` when omitted)
+ *  2. `showOn`        — breakpoint selector (always `true` when omitted)
+ *     • `containerQuery: false` (default) → evaluated against the **viewport**
+ *       via `window.matchMedia`
+ *     • `containerQuery: true`            → evaluated against the width of the
+ *       **enclosing container** via `ResizeObserver`; a thin `<div>` wrapper
+ *       is rendered so the container width can be measured
+ *
+ * Both hooks are always called unconditionally (React rules); whichever is not
+ * "active" receives `undefined` and returns `true` immediately.
  */
 export declare const ConditionalComponent: (props: PiCardProps<ConditionalProps>) => React.ReactNode;