@pinfold/react 0.0.0-stage → 0.2.0

package/dist/types-N0Yo4zGa.d.ts

@@ -0,0 +1,374 @@
+import * as React from 'react';
+import { Slottable as Slottable$1, PropsBag, AccordionChangeDetails, PinfoldOrientation, PinfoldDir, AccordionMountPanels, PinfoldLazy, PinfoldSize, PinfoldTone, PinfoldRadius, Length, AccordionFieldMap } from '@pinfold/core';
+
+/**
+ * A component that is also its own controller.
+ *
+ *   const Accordion = useAccordion(config);
+ *   return <Accordion className="mt-6" />;   // renders
+ *   Accordion.toggle('faq-1');               // controls
+ *   <Accordion.Panel id="faq-1" />           // composes
+ */
+type PinfoldComponent<Api, Props> = ((props: Props) => React.ReactElement | null) & Api & {
+    displayName?: string;
+};
+type Part = (props: any) => React.ReactElement | null;
+/**
+ * Turn a render function plus an API object (and optional parts) into a
+ * stable component.
+ *
+ * Identity stability: a component created fresh on every render is a *new
+ * element type* to React, which remounts the whole subtree on each parent
+ * update, losing focus, selection, scroll position and running transitions.
+ * So the component and its parts are created once and read the current
+ * render through a ref.
+ *
+ * Freshness: because the identity never changes, a memoising parent (the
+ * React Compiler, `React.memo`, a cached element) may skip re-rendering it.
+ * So every hook render bumps a version, and after commit the component and
+ * each part re-render through `useSyncExternalStore` if they have not yet
+ * seen it. In the ordinary case they already rendered with the parent, the
+ * snapshot matches, and React does no extra work.
+ */
+declare function usePinfoldComponent<Api extends object, Props extends object, Parts extends {
+    [K in keyof Parts]: Part;
+} = {}>(displayName: string, api: Api, render: (props: Props) => React.ReactElement | null, buildParts?: () => Parts): PinfoldComponent<Api & Parts, Props>;
+
+/**
+ * Blocks type inference from a position, so a value there is checked against what was inferred
+ * elsewhere instead of widening it (a wrong id is an error, not a new id). TypeScript 5.4 has
+ * this built in; this form works back to 4.7, the published floor.
+ */
+type NoInfer<T> = [T][T extends any ? 0 : never];
+/** A config field that is a node, or a function of live state returning one. */
+type Slottable<State, T = React.ReactNode> = Slottable$1<State, T>;
+/**
+ * Per-slot escape hatches. Every Pinfold component exposes the same four, so
+ * learning one component teaches all of them.
+ *
+ * - `classNames` — append a class to one slot.
+ * - `slotProps`  — merge arbitrary DOM props into one slot (event handlers chain).
+ * - `styles`     — inline style for one slot.
+ * - `render`     — replace one slot's element entirely, keeping its behaviour props.
+ */
+interface SlotOverrides<Slot extends string, State = unknown> {
+    classNames?: Partial<Record<Slot, string>>;
+    styles?: Partial<Record<Slot, React.CSSProperties>>;
+    slotProps?: Partial<Record<Slot, PropsBag>>;
+    render?: Partial<Record<Slot, SlotRenderer<State>>>;
+}
+type SlotRenderer<State = unknown> = (args: {
+    /** Behaviour props (ARIA, handlers, refs). Spread these or accessibility breaks. */
+    props: PropsBag;
+    /** Live component state for this slot. */
+    state: State;
+    children: React.ReactNode;
+}) => React.ReactNode;
+
+type AccordionSlot = 'root' | 'item' | 'header' | 'trigger' | 'icon' | 'label' | 'title' | 'description' | 'badge' | 'endIcon' | 'indicator' | 'panel' | 'content';
+type AccordionVariant = 'solid' | 'outline' | 'separated' | 'filled' | 'ghost';
+type AccordionIndicator = 'chevron' | 'plus' | 'caret' | 'arrow' | 'none';
+/** A radius preset (the theme scale) or a length: `20` is px, strings pass through. */
+type AccordionRadius = PinfoldRadius | number | (string & {});
+/** A spacing preset or a length: `12` is px, strings pass through. */
+type AccordionGap = 'none' | 'sm' | 'md' | 'lg' | number | (string & {});
+/**
+ * The ids of a list of rows, e.g. for typed controlled state:
+ * `useState<AccordionItemId<typeof items>[]>([])`.
+ */
+type AccordionItemId<Items extends ReadonlyArray<{
+    id?: string;
+}>> = NonNullable<Items[number]['id']>;
+/** Runtime state of a single row. Passed to every function-valued config field. */
+interface AccordionItemState<Id extends string = string> {
+    id: Id;
+    index: number;
+    open: boolean;
+    disabled: boolean;
+    config: AccordionItemConfig<Id>;
+    triggerId: string;
+    panelId: string;
+}
+/** Anything renderable in a row: a node, or a function of the row's live state. */
+type AccordionNode<Id extends string = string> = Slottable<AccordionItemState<Id>>;
+/** One row of the accordion. This is the JSON a consumer — or a model — writes. */
+interface AccordionItemConfig<Id extends string = string> {
+    /** Stable key. Falls back to the array index when omitted. Give every row one to get typed ids. */
+    id?: Id;
+    title: AccordionNode<Id>;
+    content?: AccordionNode<Id>;
+    /** Secondary line under the title. */
+    description?: AccordionNode<Id>;
+    /** Leading visual: a node, or a string (an emoji, or an icon-font name with `classNames.icon`). Overrides the accordion-wide `icon`. */
+    icon?: AccordionNode<Id>;
+    /** Trailing chip rendered before the indicator. */
+    badge?: AccordionNode<Id>;
+    /** Trailing visual just before the indicator. Overrides the accordion-wide `endIcon`. */
+    endIcon?: AccordionNode<Id>;
+    /** Overrides the accordion-wide indicator for this row only. */
+    indicator?: AccordionIndicator | AccordionNode<Id>;
+    disabled?: boolean;
+    /** Open on first render (uncontrolled only). */
+    defaultOpen?: boolean;
+    /** Per-row class and style overrides, same slot names as the root config. */
+    classNames?: Partial<Record<AccordionSlot, string>>;
+    styles?: Partial<Record<AccordionSlot, React.CSSProperties>>;
+}
+/** Text overflow for one slot: wrap, one line with an ellipsis, or clamp to n lines. */
+type AccordionOverflow = 'wrap' | 'truncate' | {
+    lines: number;
+};
+type AccordionValueDetails<Id extends string = string> = Omit<AccordionChangeDetails<Event | React.SyntheticEvent>, 'id'> & {
+    /** The row that triggered the change. Absent for `openAll` / `closeAll`. */
+    id?: Id;
+};
+interface AccordionBehaviourConfig<Id extends string = string> {
+    /**
+     * `single` closes siblings on open.
+     * @default 'single'
+     */
+    mode?: 'single' | 'multiple';
+    /**
+     * Allow closing the last open row. `false` keeps at least one row open, in either mode.
+     * @default true
+     */
+    collapsible?: boolean;
+    /**
+     * Controlled open ids. Any `string[]` state works (`useState<string[]>`); for typed state use
+     * `useState<AccordionItemId<typeof items>[]>`.
+     */
+    value?: ReadonlyArray<string>;
+    /** Initially open ids (uncontrolled). */
+    defaultValue?: ReadonlyArray<NoInfer<Id>>;
+    /** `details.reason`: 'click' | 'keyboard' | 'api' | 'find-in-page' | 'hash'. */
+    onValueChange?: (value: Id[], details: AccordionValueDetails<Id>) => void;
+    /** Return `false` to block a change (e.g. unsaved edits in the open panel). */
+    onBeforeChange?: (details: AccordionValueDetails<Id>) => boolean | void;
+    /** Fires for one item, after `onValueChange`. */
+    onItemToggle?: (id: Id, open: boolean) => void;
+    /**
+     * Arrow-key axis for moving between headers.
+     * @default 'vertical'
+     */
+    orientation?: PinfoldOrientation;
+    /** Text direction. Defaults to the provider. */
+    dir?: PinfoldDir;
+    /**
+     * Wrap focus at the ends.
+     * @default true
+     */
+    loop?: boolean;
+    /** Prefix for generated ids — set it for deterministic SSR markup. */
+    id?: string;
+    /**
+     * Disables every row. Rows stay focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /** Disables these rows by id, for data you cannot annotate row by row. */
+    disabledIds?: ReadonlyArray<NoInfer<Id>>;
+    /**
+     * Closed panels use `hidden="until-found"`, so the browser's find-in-page
+     * searches them and opens the match.
+     * @default true
+     */
+    hiddenUntilFound?: boolean;
+    /**
+     * When panel content is in the DOM. `always` keeps it searchable and indexable;
+     * `open` mounts only open panels; `first-open` mounts on first open and keeps it.
+     * @default 'always'
+     */
+    mountPanels?: AccordionMountPanels;
+    /** @deprecated Use `mountPanels: 'open'`. */
+    unmountClosed?: boolean;
+    /**
+     * `#id` in the URL opens that row and scrolls to it; opening a row updates the hash.
+     * @default false
+     */
+    syncWithHash?: boolean;
+    /**
+     * Code loading for the `/lazy` entry. The accordion is light, so `auto` loads eagerly.
+     * @default 'auto'
+     */
+    lazy?: PinfoldLazy;
+}
+/**
+ * Explicit sizing. Numbers are px, strings pass through (`'50%'`, `'18rem'`,
+ * `'clamp(20rem, 40vw, 32rem)'`). Each key overrides the value the `size`
+ * preset would have chosen, so you can take one dimension and leave the rest.
+ */
+interface AccordionDimensions {
+    width?: Length;
+    minWidth?: Length;
+    maxWidth?: Length;
+    height?: Length;
+    maxHeight?: Length;
+    /** Space between rows. Overrides `gap`. */
+    gap?: Length;
+    /** Trigger padding. */
+    paddingX?: Length;
+    paddingY?: Length;
+    /** Panel padding. Defaults to the trigger padding. */
+    panelPaddingX?: Length;
+    panelPaddingY?: Length;
+    /** Cap the open panel and let it scroll past that. */
+    panelMaxHeight?: Length;
+    fontSize?: Length;
+    titleSize?: Length;
+    descriptionSize?: Length;
+    iconSize?: Length;
+    indicatorSize?: Length;
+    borderWidth?: Length;
+    /** Container corner radius as a length. Overrides `radius`. */
+    radius?: Length;
+    /** Row corner radius as a length. Overrides `itemRadius`. */
+    itemRadius?: Length;
+    /** Open/close transition duration, e.g. `'320ms'`. */
+    duration?: Length;
+}
+interface AccordionAppearanceConfig<Id extends string = string> {
+    /** @default 'solid' */
+    variant?: AccordionVariant;
+    /** @default 'md' */
+    size?: PinfoldSize;
+    /** @default 'primary' */
+    tone?: PinfoldTone;
+    /** Corner radius of the container (the element that holds the rows). Unset: the theme radius. */
+    radius?: AccordionRadius;
+    /** Corner radius of each row. Unset: follows `radius` (square rows inside a solid or outline card). */
+    itemRadius?: AccordionRadius;
+    /** Space between rows. Unset: none for solid, outline and ghost; `'sm'` for separated and filled. */
+    gap?: AccordionGap;
+    /** Leading visual for every row: a node, or `(state) => node` (e.g. per row, or open vs closed). */
+    icon?: AccordionNode<Id>;
+    /** Trailing visual for every row, just before the indicator. Same shape as `icon`. */
+    endIcon?: AccordionNode<Id>;
+    /**
+     * Built-in glyph, your own node, or a function of the row's state.
+     * @default 'chevron'
+     */
+    indicator?: AccordionIndicator | AccordionNode<Id>;
+    /** @default 'end' */
+    indicatorPosition?: 'start' | 'end';
+    /**
+     * Rotate (or morph) the indicator when a row opens.
+     * @default true
+     */
+    animateIndicator?: boolean;
+    /**
+     * Heading level wrapping each trigger.
+     * @default 3
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Animate open/close; `prefers-reduced-motion` always wins.
+     * @default true
+     */
+    animate?: boolean;
+    /**
+     * Lines between rows that touch.
+     * @default true
+     */
+    dividers?: boolean;
+    /** Text overflow per slot. Unset: title `wrap`, description `{ lines: 2 }`. */
+    overflow?: {
+        title?: AccordionOverflow;
+        description?: AccordionOverflow;
+    };
+    /** Explicit sizing, per dimension. Overrides the `size` preset. */
+    dimensions?: AccordionDimensions;
+    /**
+     * Drop every Pinfold class so no bundled CSS applies, keeping the behaviour,
+     * ARIA and `data-*` state hooks. For Tailwind or your own stylesheet:
+     * style entirely through `classNames`.
+     * @default false
+     */
+    unstyled?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Everything except the rows: shared by `AccordionConfig` and `AccordionMappedConfig`. */
+interface AccordionOptions<Id extends string = string> extends AccordionBehaviourConfig<Id>, AccordionAppearanceConfig<Id>, SlotOverrides<AccordionSlot, AccordionItemState<Id>> {
+    /** Replace an entire row. The last resort before dropping to prop getters. */
+    renderItem?: (args: {
+        state: AccordionItemState<Id>;
+        /** Root props for the row. Spread them or state styling breaks. */
+        props: PropsBag;
+        /** The default header, if you only want to swap the body around it. */
+        header: React.ReactNode;
+        /** The default panel. */
+        panel: React.ReactNode;
+    }) => React.ReactNode;
+}
+/** Config with rows written as `AccordionItemConfig`. Ids are inferred from them. */
+interface AccordionConfig<Id extends string = string> extends AccordionOptions<Id> {
+    /** The rows. The only required option. */
+    items: ReadonlyArray<AccordionItemConfig<Id>>;
+    /** Raw records need `AccordionMappedConfig` (a `fields` map). */
+    fields?: undefined;
+}
+/**
+ * Config for raw records (a CMS or database result): `fields` maps their keys onto rows, and
+ * every value must be a real key of the record, so a typo is a compile error.
+ *
+ *   useAccordion({ items: faqRows, fields: { id: 'slug', title: 'question', content: 'answer' } });
+ */
+interface AccordionMappedConfig<Row extends object = Record<string, unknown>> extends AccordionOptions<string> {
+    items: ReadonlyArray<Row>;
+    fields: AccordionFieldMap<Row>;
+}
+/** Either config shape. What the implementation and the generic APIs accept. */
+type AnyAccordionConfig = AccordionConfig | AccordionMappedConfig;
+/** Props accepted by `<Accordion />` itself, merged onto the root element. */
+interface AccordionRootProps {
+    className?: string;
+    style?: React.CSSProperties;
+    children?: never;
+    [key: `data-${string}`]: unknown;
+}
+/** Addressing a single row from a sub-component. */
+interface AccordionPartProps<Id extends string = string> {
+    id?: Id;
+    index?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+interface AccordionState<Id extends string = string> {
+    items: AccordionItemState<Id>[];
+    value: Id[];
+    isOpen: (id: Id) => boolean;
+    open: (id: Id) => void;
+    close: (id: Id) => void;
+    toggle: (id: Id) => void;
+    openAll: () => void;
+    closeAll: () => void;
+    /** Move DOM focus to a header by index. */
+    focusItem: (index: number) => void;
+    /** Equivalent to `<Accordion />`, for callers who prefer a call. */
+    render: (props?: AccordionRootProps) => React.ReactElement;
+    getRootProps: (props?: PropsBag) => PropsBag;
+    getItemProps: (item: AccordionItemState<Id>, props?: PropsBag) => PropsBag;
+    getHeaderProps: (item: AccordionItemState<Id>, props?: PropsBag) => PropsBag;
+    getTriggerProps: (item: AccordionItemState<Id>, props?: PropsBag) => PropsBag;
+    getPanelProps: (item: AccordionItemState<Id>, props?: PropsBag) => PropsBag;
+}
+/** The sub-components for hand-laid-out accordions. */
+interface AccordionParts<Id extends string = string> {
+    /** One complete row: header plus panel. */
+    Item: (props: AccordionPartProps<Id>) => React.ReactElement | null;
+    /** Just the heading and its button. `children` replaces the default label. */
+    Trigger: (props: AccordionPartProps<Id>) => React.ReactElement | null;
+    /** Just the collapsible region. `children` replaces the configured content. */
+    Panel: (props: AccordionPartProps<Id>) => React.ReactElement | null;
+    /** Just the open/closed glyph. */
+    Indicator: (props: AccordionPartProps<Id>) => React.ReactElement | null;
+}
+/**
+ * What `useAccordion()` returns: a component you render, that is also the
+ * controller, that also carries its parts.
+ */
+type AccordionApi<Id extends string = string> = PinfoldComponent<AccordionState<Id> & AccordionParts<Id>, AccordionRootProps>;
+
+export { usePinfoldComponent as y };
+export type { AccordionConfig as A, PinfoldComponent as P, SlotOverrides as S, AccordionMappedConfig as a, AccordionApi as b, AnyAccordionConfig as c, AccordionRootProps as d, AccordionAppearanceConfig as e, AccordionBehaviourConfig as f, AccordionDimensions as g, AccordionGap as h, AccordionIndicator as i, AccordionItemConfig as j, AccordionItemId as k, AccordionItemState as l, AccordionNode as m, AccordionOptions as n, AccordionOverflow as o, AccordionPartProps as p, AccordionParts as q, AccordionRadius as r, AccordionSlot as s, AccordionState as t, AccordionValueDetails as u, AccordionVariant as v, SlotRenderer as w, Slottable as x };

package/dist/validate-EQHBH4NH.cjs

@@ -0,0 +1,42 @@
+"use client";
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});'use client';
+
+// src/accordion/validate.ts
+var _core = require('@pinfold/core');
+var _meta = require('@pinfold/core/meta');
+function validateAccordion(input, config) {
+  var _a, _b, _c, _d;
+  const shape = input.fields ? { ...input, items: [] } : input;
+  for (const problem of _meta.validateConfig.call(void 0, _meta.accordionMeta, shape)) _core.warnOnce.call(void 0, true, problem.message);
+  const { items, mode = "single", value, defaultValue, collapsible = true } = config;
+  if (!Array.isArray(items)) return;
+  const ids = _core.mapAccordionFields.call(void 0, items, config.fields).map((item, i) => _core.accordionRowId.call(void 0, item, i));
+  const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+  _core.warnOnce.call(void 0, 
+    duplicates.length > 0,
+    `Accordion: duplicate item id ${JSON.stringify(duplicates[0])}. Ids must be unique \u2014 panels and triggers are wired together by id.`
+  );
+  _core.warnOnce.call(void 0, 
+    mode === "single" && ((_a = value == null ? void 0 : value.length) != null ? _a : 0) > 1,
+    'Accordion: `mode: "single"` was given more than one open id in `value`. Only the first will be honoured.'
+  );
+  _core.warnOnce.call(void 0, 
+    mode === "single" && !collapsible && ((_b = value != null ? value : defaultValue) != null ? _b : []).length === 0,
+    "Accordion: `collapsible: false` with nothing open means the user can never open a row by keyboard from a closed state. Provide a `defaultValue`."
+  );
+  _core.warnOnce.call(void 0, 
+    value !== void 0 && config.onValueChange === void 0,
+    "Accordion: `value` was passed without `onValueChange`, so the accordion is frozen. Use `defaultValue` for uncontrolled behaviour."
+  );
+  const inactive = _core.inactiveAccordionOptions.call(void 0, { ...config, gap: (_d = (_c = config.dimensions) == null ? void 0 : _c.gap) != null ? _d : config.gap });
+  for (const key in inactive) {
+    _core.warnOnce.call(void 0, key in input && input[key] !== void 0, `Accordion: \`${key}\` has no visible effect here. ${inactive[key]}`);
+  }
+  _core.warnOnce.call(void 0, 
+    config.unmountClosed !== void 0,
+    'Accordion: `unmountClosed` is deprecated. Use `mountPanels: "open"`.'
+  );
+}
+
+
+exports.validateAccordion = validateAccordion;

package/dist/validate-WKHQNNGD.js

@@ -0,0 +1,41 @@
+'use client';
+
+// src/accordion/validate.ts
+import { accordionRowId, inactiveAccordionOptions, mapAccordionFields, warnOnce } from "@pinfold/core";
+import { accordionMeta, validateConfig } from "@pinfold/core/meta";
+function validateAccordion(input, config) {
+  var _a, _b, _c, _d;
+  const shape = input.fields ? { ...input, items: [] } : input;
+  for (const problem of validateConfig(accordionMeta, shape)) warnOnce(true, problem.message);
+  const { items, mode = "single", value, defaultValue, collapsible = true } = config;
+  if (!Array.isArray(items)) return;
+  const ids = mapAccordionFields(items, config.fields).map((item, i) => accordionRowId(item, i));
+  const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+  warnOnce(
+    duplicates.length > 0,
+    `Accordion: duplicate item id ${JSON.stringify(duplicates[0])}. Ids must be unique \u2014 panels and triggers are wired together by id.`
+  );
+  warnOnce(
+    mode === "single" && ((_a = value == null ? void 0 : value.length) != null ? _a : 0) > 1,
+    'Accordion: `mode: "single"` was given more than one open id in `value`. Only the first will be honoured.'
+  );
+  warnOnce(
+    mode === "single" && !collapsible && ((_b = value != null ? value : defaultValue) != null ? _b : []).length === 0,
+    "Accordion: `collapsible: false` with nothing open means the user can never open a row by keyboard from a closed state. Provide a `defaultValue`."
+  );
+  warnOnce(
+    value !== void 0 && config.onValueChange === void 0,
+    "Accordion: `value` was passed without `onValueChange`, so the accordion is frozen. Use `defaultValue` for uncontrolled behaviour."
+  );
+  const inactive = inactiveAccordionOptions({ ...config, gap: (_d = (_c = config.dimensions) == null ? void 0 : _c.gap) != null ? _d : config.gap });
+  for (const key in inactive) {
+    warnOnce(key in input && input[key] !== void 0, `Accordion: \`${key}\` has no visible effect here. ${inactive[key]}`);
+  }
+  warnOnce(
+    config.unmountClosed !== void 0,
+    'Accordion: `unmountClosed` is deprecated. Use `mountPanels: "open"`.'
+  );
+}
+export {
+  validateAccordion
+};

package/llms-full.txt

@@ -0,0 +1,140 @@
+# Pinfold
+
+> Hooks-first, config-driven, accessible React UI (v0.2.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` | Lets the user close the last open row. `false` keeps at least one row open, in either mode. |
+| `value` | string[] |  | Controlled open ids. Pair with `onValueChange`. |
+| `defaultValue` | string[] |  | Initially open ids (uncontrolled). |
+| `disabled` | boolean | `false` | Disables every row. |
+| `disabledIds` | string[] |  | Disables these rows by id. |
+| `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" \| length | auto: the theme radius (provider `radius`, default md) | Corner radius of the container that holds the rows: a preset, or a length (`20` is px, `'1.25rem'` passes through). Default: the theme radius. |
+| `itemRadius` | "none" \| "sm" \| "md" \| "lg" \| "full" \| length | auto: follows `radius` | Corner radius of each row, same values as `radius`. Default: `radius` for separated, filled and ghost rows; square rows inside a solid or outline card. |
+| `gap` | "none" \| "sm" \| "md" \| "lg" \| length | auto: none; sm for separated and filled | Space between rows: a preset, or a length (`12` is px). Default: none for solid, outline and ghost; `'sm'` for separated and filled. |
+| `icon` | node |  | Leading visual for every row: a node, or `(state) => node`. A row’s own `icon` wins. |
+| `endIcon` | node |  | Trailing visual for every row, just before the indicator. A row’s own `endIcon` wins. |
+| `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. |
+| `animateIndicator` | boolean | `true` | Rotate (or morph) the indicator when a row opens. |
+| `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 (solid, outline and ghost). |
+| `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: a node, or a string (an emoji, or an icon-font ligature with `classNames.icon`). Overrides the accordion-wide `icon`. |
+| `badge` | node |  | A trailing chip before the indicator. |
+| `endIcon` | node |  | A trailing visual just before the indicator. Overrides the accordion-wide `endIcon`. |
+| `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`, `endIcon`, `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.2.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, material, noise, brutalist), DTCG tokens
+- Local MCP server: `npx pinfold mcp` (tools: list_components, get_component, get_schema, validate_config, get_install_steps)