@pinfold/react 0.1.0 → 0.2.0

package/dist/{types-BZqk8btE.d.cts → types-CkcgnWwL.d.cts}

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Slottable as Slottable$1, PropsBag, AccordionFieldMap, AccordionChangeDetails, PinfoldOrientation, PinfoldDir, AccordionMountPanels, PinfoldLazy, PinfoldSize, PinfoldTone, PinfoldRadius, Length } from '@pinfold/core';
+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.
@@ -34,6 +34,12 @@ declare function usePinfoldComponent<Api extends object, Props extends object, P
     [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>;
 /**
@@ -59,35 +65,41 @@ type SlotRenderer<State = unknown> = (args: {
     children: React.ReactNode;
 }) => React.ReactNode;
 
-type AccordionSlot = 'root' | 'item' | 'header' | 'trigger' | 'icon' | 'label' | 'title' | 'description' | 'badge' | 'indicator' | 'panel' | 'content';
+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 & {});
 /** Runtime state of a single row. Passed to every function-valued config field. */
-interface AccordionItemState {
-    id: string;
+interface AccordionItemState<Id extends string = string> {
+    id: Id;
     index: number;
     open: boolean;
     disabled: boolean;
-    config: AccordionItemConfig;
+    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 = Slottable<AccordionItemState>;
+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 {
-    /** Stable key. Falls back to the array index when omitted. */
-    id?: string;
-    title: AccordionNode;
-    content?: AccordionNode;
+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;
-    /** Leading visual — icon, avatar, anything. */
-    icon?: AccordionNode;
+    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;
+    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;
+    indicator?: AccordionIndicator | AccordionNode<Id>;
     disabled?: boolean;
     /** Open on first render (uncontrolled only). */
     defaultOpen?: boolean;
@@ -99,53 +111,78 @@ interface AccordionItemConfig {
 type AccordionOverflow = 'wrap' | 'truncate' | {
     lines: number;
 };
-type AccordionValueDetails = AccordionChangeDetails<Event | React.SyntheticEvent>;
-interface AccordionBehaviourConfig {
+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> {
     /**
-     * The rows. The only required option. With `fields`, any record shape works:
-     * `items: faqRows, fields: { id: 'slug', title: 'question', content: 'answer' }`.
+     * `single` closes siblings on open.
+     * @default 'single'
      */
-    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. */
+    /**
+     * Allow closing the last open row. `false` keeps at least one row open, in either mode.
+     * @default true
+     */
     collapsible?: boolean;
-    /** Controlled open ids. */
-    value?: string[];
-    defaultValue?: string[];
+    /**
+     * 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: string[], details: AccordionValueDetails) => void;
+    onValueChange?: (value: Id[], details: AccordionValueDetails<Id>) => void;
     /** Return `false` to block a change (e.g. unsaved edits in the open panel). */
-    onBeforeChange?: (details: AccordionValueDetails) => boolean | void;
+    onBeforeChange?: (details: AccordionValueDetails<Id>) => boolean | void;
     /** Fires for one item, after `onValueChange`. */
-    onItemToggle?: (id: string, open: boolean) => void;
-    /** Arrow-key axis for moving between headers. Default `vertical`. */
+    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. */
+    /**
+     * 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. */
+    /**
+     * 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.
+     * 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.
+     * 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. */
+    /**
+     * `#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. */
+    /**
+     * Code loading for the `/lazy` entry. The accordion is light, so `auto` loads eagerly.
+     * @default 'auto'
+     */
     lazy?: PinfoldLazy;
 }
 /**
@@ -159,7 +196,7 @@ interface AccordionDimensions {
     maxWidth?: Length;
     height?: Length;
     maxHeight?: Length;
-    /** Space between rows (outline / separated / filled variants). */
+    /** Space between rows. Overrides `gap`. */
     gap?: Length;
     /** Trigger padding. */
     paddingX?: Length;
@@ -175,27 +212,58 @@ interface AccordionDimensions {
     iconSize?: Length;
     indicatorSize?: Length;
     borderWidth?: Length;
-    /** Corner radius as a length — overrides the `radius` token preset. */
+    /** 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 {
+interface AccordionAppearanceConfig<Id extends string = string> {
+    /** @default 'solid' */
     variant?: AccordionVariant;
+    /** @default 'md' */
     size?: PinfoldSize;
+    /** @default 'primary' */
     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`. */
+    /** 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';
-    /** Heading level wrapping each trigger. Default 3. */
+    /**
+     * 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. Default true; honours prefers-reduced-motion regardless. */
+    /**
+     * Animate open/close; `prefers-reduced-motion` always wins.
+     * @default true
+     */
     animate?: boolean;
-    /** Full-width dividers between rows (solid/ghost variants). Default true. */
+    /**
+     * Lines between rows that touch.
+     * @default true
+     */
     dividers?: boolean;
-    /** Text overflow per slot. Default: title `wrap`, description `{ lines: 2 }`. */
+    /** Text overflow per slot. Unset: title `wrap`, description `{ lines: 2 }`. */
     overflow?: {
         title?: AccordionOverflow;
         description?: AccordionOverflow;
@@ -206,15 +274,17 @@ interface AccordionAppearanceConfig {
      * 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;
 }
-interface AccordionConfig extends AccordionBehaviourConfig, AccordionAppearanceConfig, SlotOverrides<AccordionSlot, AccordionItemState> {
+/** 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;
+        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. */
@@ -223,6 +293,25 @@ interface AccordionConfig extends AccordionBehaviourConfig, AccordionAppearanceC
         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;
@@ -231,20 +320,20 @@ interface AccordionRootProps {
     [key: `data-${string}`]: unknown;
 }
 /** Addressing a single row from a sub-component. */
-interface AccordionPartProps {
-    id?: string;
+interface AccordionPartProps<Id extends string = string> {
+    id?: Id;
     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;
+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. */
@@ -252,27 +341,27 @@ interface AccordionState {
     /** 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;
+    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 {
+interface AccordionParts<Id extends string = string> {
     /** One complete row: header plus panel. */
-    Item: (props: AccordionPartProps) => React.ReactElement | null;
+    Item: (props: AccordionPartProps<Id>) => React.ReactElement | null;
     /** Just the heading and its button. `children` replaces the default label. */
-    Trigger: (props: AccordionPartProps) => React.ReactElement | null;
+    Trigger: (props: AccordionPartProps<Id>) => React.ReactElement | null;
     /** Just the collapsible region. `children` replaces the configured content. */
-    Panel: (props: AccordionPartProps) => React.ReactElement | null;
+    Panel: (props: AccordionPartProps<Id>) => React.ReactElement | null;
     /** Just the open/closed glyph. */
-    Indicator: (props: AccordionPartProps) => React.ReactElement | null;
+    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 = PinfoldComponent<AccordionState & AccordionParts, AccordionRootProps>;
+type AccordionApi<Id extends string = string> = PinfoldComponent<AccordionState<Id> & AccordionParts<Id>, AccordionRootProps>;
 
 export { usePinfoldComponent as u };
-export type { AccordionConfig as A, PinfoldComponent as P, SlotOverrides as S, AccordionApi as a, SlotRenderer as b, Slottable as c };
+export type { AccordionConfig as A, PinfoldComponent as P, SlotOverrides as S, AccordionMappedConfig as a, AccordionApi as b, AnyAccordionConfig as c, AccordionOptions as d, SlotRenderer as e, Slottable as f };