@pinfold/react 0.0.0-stage → 0.1.0

package/llms-full.txt

@@ -0,0 +1,133 @@
+# Pinfold
+
+> Hooks-first, config-driven, accessible React UI (v0.1.0). One config object in, an accessible, themed, responsive component out. React 18+, Server Components, plain JS or TypeScript.
+
+Rules for generating Pinfold code:
+- Data goes in `items` (or raw records plus `fields`); everything else is optional with good defaults.
+- Client: `const Faq = useAccordion({ items }); return <Faq />`. Server Component: `const Faq = defineAccordion({ items }); return <Faq />`. Same import path.
+- Styles: `import '@pinfold/css/core.css'` once, then `@pinfold/css/<name>.css` per component, in the app entry. Never import CSS from library code.
+- Global defaults: `defineConfig({ theme, radius, stylePack, defaults: { <name>: {...} } })` passed to `<PinfoldProvider config>`.
+- Customise in this order: config, then `classNames`/`styles`/`slotProps`, then `render` per slot, then parts (`<Faq.Panel id>`), then prop getters.
+- Never pass functions from a Server Component; plain data and server-rendered JSX only.
+
+## Install
+
+- `npx pinfold init` (or `npm i @pinfold/react @pinfold/css`)
+- shadcn: `npx shadcn add @pinfold/<name>` with `"registries": { "@pinfold": "https://pinfold.indranildev.in/r/{name}.json" }` in components.json
+
+# Accordion
+
+A vertically stacked set of headings that each reveal a section of content. Config in, accessible accordion out.
+
+Import: `@pinfold/react/accordion` · Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+
+## Client hook
+
+```tsx
+import { useAccordion } from '@pinfold/react/accordion';
+
+export function Faq() {
+  const Faq = useAccordion({ items: [{ title: 'What is Pinfold?', content: 'Config in, accessible UI out.' }] });
+  return <Faq />;
+}
+```
+
+## Server Component
+
+```tsx
+import { defineAccordion } from '@pinfold/react/accordion';
+
+export default async function Page() {
+  const Faq = defineAccordion({ items: await getFaq(), fields: { id: 'slug', title: 'question', content: 'answer' } });
+  return <Faq />;
+}
+```
+
+## Options
+
+Only `items` is required. Every other option has a default; global defaults come from `defineConfig({ defaults: { accordion: {...} } })`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `items` (required) | array |  | The rows. The only required option. |
+| `fields` | object |  | Map raw records onto rows: `{ id: 'slug', title: 'question', content: 'answer' }`. |
+| `mode` | "single" \| "multiple" | `"single"` | `single` closes the other rows when one opens. |
+| `collapsible` | boolean | `true` | In single mode, lets the user close the open row. |
+| `value` | string[] |  | Controlled open ids. Pair with `onValueChange`. |
+| `defaultValue` | string[] |  | Initially open ids (uncontrolled). |
+| `disabled` | boolean | `false` | Disables every row. |
+| `orientation` | "vertical" \| "horizontal" | `"vertical"` | Arrow-key axis between headers. |
+| `dir` | "ltr" \| "rtl" |  | Text direction. Defaults to the provider. |
+| `loop` | boolean | `true` | Focus wraps around at the ends. |
+| `id` | string |  | Id prefix. Defaults to `useId()`, which is SSR-safe. |
+| `hiddenUntilFound` | boolean | `true` | Closed panels use `hidden="until-found"`, so the browser’s find-in-page opens them. |
+| `mountPanels` | "always" \| "open" \| "first-open" | `"always"` | When panel content is in the DOM. `always` keeps it searchable and indexable. |
+| `unmountClosed` (deprecated) | boolean |  | Deprecated alias of `mountPanels: "open"`. |
+| `syncWithHash` | boolean | `false` | A `#id` in the URL opens that row and scrolls to it; opening a row updates the hash. |
+| `lazy` | "auto" \| "eager" \| "visible" \| "idle" | `"auto"` | When the code loads, for the `/lazy` entry. The accordion is light, so `auto` is eager. |
+| `variant` | "solid" \| "outline" \| "separated" \| "filled" \| "ghost" | `"solid"` | Visual style. |
+| `size` | "sm" \| "md" \| "lg" | `"md"` | Size preset. |
+| `tone` | "primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info" | `"primary"` | Accent colour role. |
+| `radius` | "none" \| "sm" \| "md" \| "lg" \| "full" | `"md"` | Corner radius preset. |
+| `indicator` | "chevron" \| "plus" \| "caret" \| "arrow" \| "none" \| node | `"chevron"` | A built-in glyph, your own node, or `(state) => node`. |
+| `indicatorPosition` | "start" \| "end" | `"end"` | Which edge the indicator sits on. |
+| `headingLevel` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | `3` | Heading level around each trigger. |
+| `animate` | boolean | `true` | Animate open and close. `prefers-reduced-motion` always wins. |
+| `dividers` | boolean | `true` | Lines between rows. |
+| `overflow` | object |  | Text overflow per slot. Default: title wraps, description clamps to 2 lines. |
+| `dimensions` | object |  | Explicit sizes. Numbers are px. Each key overrides the size preset. |
+| `unstyled` | boolean | `false` | Drops every Pinfold class; ARIA and `data-*` stay. For Tailwind or your own CSS. |
+| `className` | string |  | Class on the root. |
+| `style` | object |  | Inline style on the root. |
+| `classNames` | object |  | Classes per slot. |
+| `styles` | object |  | Inline styles per slot. |
+| `slotProps` | object |  | Any DOM props per slot. Handlers chain. |
+| `render` | object |  | Replace a slot element: `({ props, state, children }) => node`. |
+| `renderItem` | function |  | Replace a whole row: `({ state, props, header, panel }) => node`. |
+| `onValueChange` | function |  | `(ids, details)`. `details: { id, open, reason: 'click' \| 'keyboard' \| 'api' \| 'find-in-page' \| 'hash', event }`. |
+| `onBeforeChange` | function |  | `(details) => boolean \| void`. Return `false` to block the change. |
+| `onItemToggle` | function |  | `(id, open)`, after `onValueChange`. |
+
+## Row options (`items[]`)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `id` | string |  | Stable key. Falls back to the array index. |
+| `title` (required) | node |  | The row heading. A node or `(state) => node`. |
+| `content` | node |  | The panel body. |
+| `description` | node |  | A secondary line under the title. |
+| `icon` | node |  | A leading visual. |
+| `badge` | node |  | A trailing chip before the indicator. |
+| `indicator` | "chevron" \| "plus" \| "caret" \| "arrow" \| "none" \| node |  | Overrides the accordion-wide indicator for this row. |
+| `disabled` | boolean |  | Blocks toggling. The row stays focusable. |
+| `defaultOpen` | boolean |  | Open on first render (uncontrolled only). |
+| `classNames` | object |  | Per-row classes, by slot. |
+| `styles` | object |  | Per-row inline styles, by slot. |
+
+## Slots
+
+`root`, `item`, `header`, `trigger`, `icon`, `label`, `title`, `description`, `badge`, `indicator`, `panel`, `content`
+
+## Keyboard
+
+- **Enter / Space**: Toggle the focused row.
+- **ArrowDown / ArrowUp**: Next / previous header (ArrowRight / ArrowLeft when horizontal; flipped in RTL). Wraps when `loop`.
+- **Home / End**: First / last header.
+- **Tab**: Leaves the header list. Closed panels are not in the tab order.
+
+## Accessibility
+
+- Each trigger is a `<button>` inside a heading with `aria-level`.
+- Triggers carry `aria-expanded` and `aria-controls` pointing at their panel.
+- Each panel is `role="region"` with `aria-labelledby` pointing at its trigger.
+- Disabled rows use `aria-disabled` and stay focusable.
+- Closed panels leave the accessibility tree and the tab order.
+
+## Data attributes
+
+- `data-state` on item, header, trigger, panel: "open" | "closed"
+- `data-disabled` on item, trigger: present when disabled
+- `data-index` on item: row index
+- `data-orientation` on root: "vertical" | "horizontal"
+- `data-mode` on root: "single" | "multiple"
+- `data-transition` on panel: "opening" | "closing", while animating

package/llms.txt

@@ -0,0 +1,26 @@
+# Pinfold
+
+> Hooks-first, config-driven, accessible React UI (v0.1.0). One config object in, an accessible, themed, responsive component out. React 18+, Server Components, plain JS or TypeScript.
+
+Rules for generating Pinfold code:
+- Data goes in `items` (or raw records plus `fields`); everything else is optional with good defaults.
+- Client: `const Faq = useAccordion({ items }); return <Faq />`. Server Component: `const Faq = defineAccordion({ items }); return <Faq />`. Same import path.
+- Styles: `import '@pinfold/css/core.css'` once, then `@pinfold/css/<name>.css` per component, in the app entry. Never import CSS from library code.
+- Global defaults: `defineConfig({ theme, radius, stylePack, defaults: { <name>: {...} } })` passed to `<PinfoldProvider config>`.
+- Customise in this order: config, then `classNames`/`styles`/`slotProps`, then `render` per slot, then parts (`<Faq.Panel id>`), then prop getters.
+- Never pass functions from a Server Component; plain data and server-rendered JSX only.
+
+## Install
+
+- `npx pinfold init` (or `npm i @pinfold/react @pinfold/css`)
+- shadcn: `npx shadcn add @pinfold/<name>` with `"registries": { "@pinfold": "https://pinfold.indranildev.in/r/{name}.json" }` in components.json
+
+## Components
+
+- [Accordion](https://pinfold.indranildev.in/docs/accordion): A vertically stacked set of headings that each reveal a section of content. Config in, accessible accordion out. Import `@pinfold/react/accordion`. Schema: `schema/accordion.json`.
+
+## Reference
+
+- [Full reference](https://pinfold.indranildev.in/llms-full.txt): every option of every component (also `llms-full.txt` in this package)
+- [Theming](https://pinfold.indranildev.in/docs/theming): `npx pinfold theme`, style packs (glass, bauhaus, brutalist, noise, soft), DTCG tokens
+- Local MCP server: `npx pinfold mcp` (tools: list_components, get_component, get_schema, validate_config, get_install_steps)

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@pinfold/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pinfold for React: hooks-first, config-driven, accessible components. One subpath per component.",
+  "author": "Indranil Bhattacharya",
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "accordion",
+    "hooks",
+    "accessibility",
+    "aria",
+    "design-system",
+    "pinfold"
+  ],
+  "license": "MIT",
+  "homepage": "https://pinfold.indranildev.in",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IndranilBhattacharya/pinfold.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/IndranilBhattacharya/pinfold/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./accordion": {
+      "import": {
+        "types": "./dist/accordion/index.d.ts",
+        "default": "./dist/accordion/index.js"
+      },
+      "require": {
+        "types": "./dist/accordion/index.d.cts",
+        "default": "./dist/accordion/index.cjs"
+      }
+    },
+    "./accordion/lazy": {
+      "import": {
+        "types": "./dist/accordion/lazy.d.ts",
+        "default": "./dist/accordion/lazy.js"
+      },
+      "require": {
+        "types": "./dist/accordion/lazy.d.cts",
+        "default": "./dist/accordion/lazy.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "accordion": [
+        "./dist/accordion/index.d.cts"
+      ],
+      "accordion/lazy": [
+        "./dist/accordion/lazy.d.cts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "accordion",
+    "registry",
+    "schema",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsup && node ../../scripts/subpath-stubs.mjs && node ../../scripts/generate-artifacts.mjs"
+  },
+  "dependencies": {
+    "@pinfold/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/registry/accordion.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "accordion",
+  "type": "registry:ui",
+  "title": "Accordion",
+  "description": "A vertically stacked set of headings that each reveal a section of content. Config in, accessible accordion out.",
+  "dependencies": [
+    "@pinfold/react@^0.1.0",
+    "@pinfold/css@^0.1.0"
+  ],
+  "files": [
+    {
+      "path": "components/ui/accordion.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/accordion.tsx",
+      "content": "import '@pinfold/css/core.css';\nimport '@pinfold/css/accordion.css';\n\n/**\n * Pinfold accordion. This file is yours: import from here across the app,\n * and change shared defaults in one place.\n * Docs: https://pinfold.indranildev.in/docs/accordion\n */\nexport { useAccordion, defineAccordion, Accordion } from '@pinfold/react/accordion';\nexport type { AccordionConfig, AccordionItemConfig, AccordionApi } from '@pinfold/react/accordion';\n"
+    }
+  ],
+  "docs": "https://pinfold.indranildev.in/docs/accordion"
+}

package/registry/registry.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "pinfold",
+  "homepage": "https://pinfold.indranildev.in",
+  "items": [
+    {
+      "name": "accordion",
+      "type": "registry:ui",
+      "title": "Accordion",
+      "description": "A vertically stacked set of headings that each reveal a section of content. Config in, accessible accordion out.",
+      "dependencies": [
+        "@pinfold/react@^0.1.0",
+        "@pinfold/css@^0.1.0"
+      ],
+      "files": [
+        {
+          "path": "components/ui/accordion.tsx",
+          "type": "registry:ui",
+          "target": "components/ui/accordion.tsx"
+        }
+      ],
+      "docs": "https://pinfold.indranildev.in/docs/accordion"
+    }
+  ]
+}