@pinfold/react 0.1.0 → 0.2.0

package/schema/accordion.json

@@ -25,11 +25,14 @@
             "description": "A secondary line under the title."
           },
           "icon": {
-            "description": "A leading visual."
+            "description": "A leading visual: a node, or a string (an emoji, or an icon-font ligature with `classNames.icon`). Overrides the accordion-wide `icon`."
           },
           "badge": {
             "description": "A trailing chip before the indicator."
           },
+          "endIcon": {
+            "description": "A trailing visual just before the indicator. Overrides the accordion-wide `endIcon`."
+          },
           "indicator": {
             "description": "Overrides the accordion-wide indicator for this row.",
             "anyOf": [
@@ -93,6 +96,10 @@
                 "description": "The `badge` slot.",
                 "type": "string"
               },
+              "endIcon": {
+                "description": "The `endIcon` slot.",
+                "type": "string"
+              },
               "indicator": {
                 "description": "The `indicator` slot.",
                 "type": "string"
@@ -148,6 +155,10 @@
                 "description": "The `badge` slot.",
                 "type": "object"
               },
+              "endIcon": {
+                "description": "The `endIcon` slot.",
+                "type": "object"
+              },
               "indicator": {
                 "description": "The `indicator` slot.",
                 "type": "object"
@@ -194,6 +205,10 @@
           "description": "Source field for `icon`.",
           "type": "string"
         },
+        "endIcon": {
+          "description": "Source field for `endIcon`.",
+          "type": "string"
+        },
         "badge": {
           "description": "Source field for `badge`.",
           "type": "string"
@@ -218,7 +233,7 @@
       ]
     },
     "collapsible": {
-      "description": "In single mode, lets the user close the open row.",
+      "description": "Lets the user close the last open row. `false` keeps at least one row open, in either mode.",
       "default": true,
       "type": "boolean"
     },
@@ -241,6 +256,13 @@
       "default": false,
       "type": "boolean"
     },
+    "disabledIds": {
+      "description": "Disables these rows by id.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "orientation": {
       "description": "Arrow-key axis between headers.",
       "default": "vertical",
@@ -332,16 +354,70 @@
       ]
     },
     "radius": {
-      "description": "Corner radius preset.",
-      "default": "md",
-      "enum": [
-        "none",
-        "sm",
-        "md",
-        "lg",
-        "full"
+      "description": "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.",
+      "anyOf": [
+        {
+          "enum": [
+            "none",
+            "sm",
+            "md",
+            "lg",
+            "full"
+          ]
+        },
+        {
+          "type": [
+            "number",
+            "string"
+          ]
+        }
+      ]
+    },
+    "itemRadius": {
+      "description": "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.",
+      "anyOf": [
+        {
+          "enum": [
+            "none",
+            "sm",
+            "md",
+            "lg",
+            "full"
+          ]
+        },
+        {
+          "type": [
+            "number",
+            "string"
+          ]
+        }
+      ]
+    },
+    "gap": {
+      "description": "Space between rows: a preset, or a length (`12` is px). Default: none for solid, outline and ghost; `'sm'` for separated and filled.",
+      "anyOf": [
+        {
+          "enum": [
+            "none",
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        {
+          "type": [
+            "number",
+            "string"
+          ]
+        }
       ]
     },
+    "icon": {
+      "description": "Leading visual for every row: a node, or `(state) => node`. A row’s own `icon` wins."
+    },
+    "endIcon": {
+      "description": "Trailing visual for every row, just before the indicator. A row’s own `endIcon` wins."
+    },
     "indicator": {
       "description": "A built-in glyph, your own node, or `(state) => node`.",
       "default": "chevron",
@@ -366,6 +442,11 @@
         "end"
       ]
     },
+    "animateIndicator": {
+      "description": "Rotate (or morph) the indicator when a row opens.",
+      "default": true,
+      "type": "boolean"
+    },
     "headingLevel": {
       "description": "Heading level around each trigger.",
       "default": 3,
@@ -384,7 +465,7 @@
       "type": "boolean"
     },
     "dividers": {
-      "description": "Lines between rows.",
+      "description": "Lines between rows (solid, outline and ghost).",
       "default": true,
       "type": "boolean"
     },
@@ -459,7 +540,7 @@
           ]
         },
         "gap": {
-          "description": "Space between rows.",
+          "description": "Space between rows. Overrides `gap`.",
           "type": [
             "number",
             "string"
@@ -543,7 +624,14 @@
           ]
         },
         "radius": {
-          "description": "Corner radius as a length.",
+          "description": "Container corner radius. Overrides `radius`.",
+          "type": [
+            "number",
+            "string"
+          ]
+        },
+        "itemRadius": {
+          "description": "Row corner radius. Overrides `itemRadius`.",
           "type": [
             "number",
             "string"
@@ -612,6 +700,10 @@
           "description": "The `badge` slot.",
           "type": "string"
         },
+        "endIcon": {
+          "description": "The `endIcon` slot.",
+          "type": "string"
+        },
         "indicator": {
           "description": "The `indicator` slot.",
           "type": "string"
@@ -667,6 +759,10 @@
           "description": "The `badge` slot.",
           "type": "object"
         },
+        "endIcon": {
+          "description": "The `endIcon` slot.",
+          "type": "object"
+        },
         "indicator": {
           "description": "The `indicator` slot.",
           "type": "object"
@@ -722,6 +818,10 @@
           "description": "The `badge` slot.",
           "type": "object"
         },
+        "endIcon": {
+          "description": "The `endIcon` slot.",
+          "type": "object"
+        },
         "indicator": {
           "description": "The `indicator` slot.",
           "type": "object"
@@ -768,6 +868,9 @@
         "badge": {
           "description": "The `badge` slot."
         },
+        "endIcon": {
+          "description": "The `endIcon` slot."
+        },
         "indicator": {
           "description": "The `indicator` slot."
         },

package/dist/types-x01Q5sqz.d.cts

@@ -1,278 +0,0 @@
-import * as React from 'react';
-import { Slottable as Slottable$1, PropsBag, AccordionFieldMap, AccordionChangeDetails, PinfoldOrientation, PinfoldDir, AccordionMountPanels, PinfoldLazy, PinfoldSize, PinfoldTone, PinfoldRadius, Length } 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>;
-
-/** 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' | 'indicator' | 'panel' | 'content';
-type AccordionVariant = 'solid' | 'outline' | 'separated' | 'filled' | 'ghost';
-type AccordionIndicator = 'chevron' | 'plus' | 'caret' | 'arrow' | 'none';
-/** Runtime state of a single row. Passed to every function-valued config field. */
-interface AccordionItemState {
-    id: string;
-    index: number;
-    open: boolean;
-    disabled: boolean;
-    config: AccordionItemConfig;
-    triggerId: string;
-    panelId: string;
-}
-/** Anything renderable in a row: a node, or a function of the row's live state. */
-type AccordionNode = Slottable<AccordionItemState>;
-/** One row of the accordion. This is the JSON a consumer — or a model — writes. */
-interface AccordionItemConfig {
-    /** Stable key. Falls back to the array index when omitted. */
-    id?: string;
-    title: AccordionNode;
-    content?: AccordionNode;
-    /** Secondary line under the title. */
-    description?: AccordionNode;
-    /** Leading visual — icon, avatar, anything. */
-    icon?: AccordionNode;
-    /** Trailing chip rendered before the indicator. */
-    badge?: AccordionNode;
-    /** Overrides the accordion-wide indicator for this row only. */
-    indicator?: AccordionIndicator | AccordionNode;
-    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 = AccordionChangeDetails<Event | React.SyntheticEvent>;
-interface AccordionBehaviourConfig {
-    /**
-     * The rows. The only required option. With `fields`, any record shape works:
-     * `items: faqRows, fields: { id: 'slug', title: 'question', content: 'answer' }`.
-     */
-    items: AccordionItemConfig[] | ReadonlyArray<Record<string, any>>;
-    /** Maps raw records onto rows, so CMS or database results need no `.map()`. */
-    fields?: AccordionFieldMap;
-    /** `single` closes siblings on open. Default `single`. */
-    mode?: 'single' | 'multiple';
-    /** In `single` mode, allow closing the open item. Default true. */
-    collapsible?: boolean;
-    /** Controlled open ids. */
-    value?: string[];
-    defaultValue?: string[];
-    /** `details.reason`: 'click' | 'keyboard' | 'api' | 'find-in-page' | 'hash'. */
-    onValueChange?: (value: string[], details: AccordionValueDetails) => void;
-    /** Return `false` to block a change (e.g. unsaved edits in the open panel). */
-    onBeforeChange?: (details: AccordionValueDetails) => boolean | void;
-    /** Fires for one item, after `onValueChange`. */
-    onItemToggle?: (id: string, open: boolean) => void;
-    /** Arrow-key axis for moving between headers. Default `vertical`. */
-    orientation?: PinfoldOrientation;
-    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;
-    /**
-     * 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` (default) keeps it searchable
-     * and indexable; `open` mounts only open panels; `first-open` mounts on
-     * first open and keeps it.
-     */
-    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. */
-    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 (outline / separated / filled variants). */
-    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;
-    /** Corner radius as a length — overrides the `radius` token preset. */
-    radius?: Length;
-    /** Open/close transition duration, e.g. `'320ms'`. */
-    duration?: Length;
-}
-interface AccordionAppearanceConfig {
-    variant?: AccordionVariant;
-    size?: PinfoldSize;
-    tone?: PinfoldTone;
-    radius?: PinfoldRadius;
-    /** Built-in glyph, your own node, or a function of the row's state. */
-    indicator?: AccordionIndicator | AccordionNode;
-    /** Which edge the indicator sits on. Default `end`. */
-    indicatorPosition?: 'start' | 'end';
-    /** Heading level wrapping each trigger. Default 3. */
-    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Animate open/close. Default true; honours prefers-reduced-motion regardless. */
-    animate?: boolean;
-    /** Full-width dividers between rows (solid/ghost variants). Default true. */
-    dividers?: boolean;
-    /** Text overflow per slot. Default: 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`.
-     */
-    unstyled?: boolean;
-    className?: string;
-    style?: React.CSSProperties;
-}
-interface AccordionConfig extends AccordionBehaviourConfig, AccordionAppearanceConfig, SlotOverrides<AccordionSlot, AccordionItemState> {
-    /** Replace an entire row. The last resort before dropping to prop getters. */
-    renderItem?: (args: {
-        state: AccordionItemState;
-        /** 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;
-}
-/** 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?: string;
-    index?: number;
-    className?: string;
-    style?: React.CSSProperties;
-    children?: React.ReactNode;
-}
-interface AccordionState {
-    items: AccordionItemState[];
-    value: string[];
-    isOpen: (id: string) => boolean;
-    open: (id: string) => void;
-    close: (id: string) => void;
-    toggle: (id: string) => 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, props?: PropsBag) => PropsBag;
-    getHeaderProps: (item: AccordionItemState, props?: PropsBag) => PropsBag;
-    getTriggerProps: (item: AccordionItemState, props?: PropsBag) => PropsBag;
-    getPanelProps: (item: AccordionItemState, props?: PropsBag) => PropsBag;
-}
-/** The sub-components for hand-laid-out accordions. */
-interface AccordionParts {
-    /** One complete row: header plus panel. */
-    Item: (props: AccordionPartProps) => React.ReactElement | null;
-    /** Just the heading and its button. `children` replaces the default label. */
-    Trigger: (props: AccordionPartProps) => React.ReactElement | null;
-    /** Just the collapsible region. `children` replaces the configured content. */
-    Panel: (props: AccordionPartProps) => React.ReactElement | null;
-    /** Just the open/closed glyph. */
-    Indicator: (props: AccordionPartProps) => React.ReactElement | null;
-}
-/**
- * What `useAccordion()` returns: a component you render, that is also the
- * controller, that also carries its parts.
- */
-type AccordionApi = PinfoldComponent<AccordionState & AccordionParts, AccordionRootProps>;
-
-export { usePinfoldComponent as u };
-export type { AccordionConfig as A, PinfoldComponent as P, SlotOverrides as S, AccordionApi as a, AccordionRootProps as b, AccordionAppearanceConfig as c, AccordionBehaviourConfig as d, AccordionDimensions as e, AccordionIndicator as f, AccordionItemConfig as g, AccordionItemState as h, AccordionNode as i, AccordionOverflow as j, AccordionPartProps as k, AccordionParts as l, AccordionSlot as m, AccordionState as n, AccordionValueDetails as o, AccordionVariant as p, SlotRenderer as q, Slottable as r };