@peasant-labs/fairtrade 0.0.1 → 0.0.2

package/dist/lib/types/GroupedMultiSelect.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A grouped tri-state multi-select tree. See GroupedMultiSelectProps.
+ * @param {GroupedMultiSelectProps} props
+ */
+export default function GroupedMultiSelect({ groups, value, defaultValue, onChange, tokenLabel, defaultOpen, ariaLabel, }: GroupedMultiSelectProps): any;
+export type GMSItem = {
+    /**
+     * unique selection id (what lands in the value Set).
+     */
+    id: string;
+    /**
+     * the item title — user content, rendered verbatim.
+     */
+    label: any;
+    /**
+     * one-line secondary metadata (e.g. "42 turns · jun 3").
+     */
+    meta?: any;
+    /**
+     * token count for the running tally; defaults to 0.
+     */
+    tokens?: number;
+};
+export type GMSGroup = {
+    /**
+     * unique group id.
+     */
+    id: string;
+    /**
+     * the group title — user content, rendered verbatim.
+     */
+    label: any;
+    /**
+     * the group's selectable items.
+     */
+    items: GMSItem[];
+};
+export type GroupedMultiSelectProps = {
+    /**
+     * the project-grouped tree to render.
+     */
+    groups: GMSGroup[];
+    /**
+     * controlled set of selected item ids; pair with onChange.
+     */
+    value?: Set<string>;
+    /**
+     * initial selection for uncontrolled use.
+     */
+    defaultValue?: Set<string>;
+    /**
+     * called with the next selection Set on any toggle.
+     */
+    onChange?: (next: Set<string>) => void;
+    /**
+     * noun for the tally (chrome, lowercased in display).
+     */
+    tokenLabel?: string;
+    /**
+     * ids of groups expanded on first render (uncontrolled).
+     */
+    defaultOpen?: string[];
+    /**
+     * accessible name for the tree container.
+     */
+    ariaLabel?: string;
+};

package/dist/lib/types/Input.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Field — the label + control + hint/error wrapper (.is-field) the inputs compose into.
+ * Renders the label above, the control (children) in the middle, and a hint (.is-hint) or, when
+ * `error` is a non-empty string, an error (.is-error with a TriangleAlert icon) below. Wires the
+ * label's htmlFor and the hint/error id to the control via the {id, describedBy, invalid}
+ * render-prop args so the standalone <Field> can be used with any control. The shipped Input /
+ * Textarea / Select use this internally, so most callers never touch Field directly.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.label] - label text shown above the control. When `lock` is set it
+ *   is wrapped in `.is-lk` with a leading icon.
+ * @param {React.ComponentType<{size?:number}>} [props.lock] - optional lucide icon (e.g. lock={Lock})
+ *   rendered before the label inside `.is-lk` to flag a read-only/locked field.
+ * @param {string} [props.hint] - helper text rendered in `.is-hint` below the control (when no error).
+ * @param {string} [props.error] - error message; a non-empty string renders `.is-error` (TriangleAlert
+ *   + message) instead of the hint and is announced via aria-describedby.
+ * @param {string} [props.id] - control id; auto-generated when omitted. Used for label htmlFor.
+ * @param {(args:{id:string,describedBy:string|undefined,invalid:boolean})=>React.ReactNode} props.children
+ *   - render-prop receiving wiring ids; returns the control element.
+ * @returns {JSX.Element}
+ */
+export function Field({ label, lock: LockIcon, hint, error, id, children }: {
+    label?: React.ReactNode;
+    lock?: React.ComponentType<{
+        size?: number;
+    }>;
+    hint?: string;
+    error?: string;
+    id?: string;
+    children: (args: {
+        id: string;
+        describedBy: string | undefined;
+        invalid: boolean;
+    }) => React.ReactNode;
+}): JSX.Element;
+/**
+ * Input — a single-line text field with the full input-states wiring. When `iconLeft` is supplied the
+ * control sits inside an `.input-ico` wrapper (the icon is absolutely positioned, leaving room via the
+ * CSS padding). Error sets aria-invalid + the clay border via `.is-input[aria-invalid]` and links the
+ * message with aria-describedby. Supports controlled (`value` + `onChange`) and uncontrolled
+ * (`defaultValue`) use.
+ *
+ * Emits `<div class="is-field"><label class="label"/>[<div class="input-ico">]<input class="input is-input"/>[…]<span class="is-hint|is-error"/></div>`
+ * matching src/index.css with zero new CSS.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.label] - label above the field.
+ * @param {React.ComponentType<{size?:number}>} [props.lock] - optional lucide icon shown beside the label (.is-lk).
+ * @param {string} [props.hint] - helper text under the field.
+ * @param {string} [props.error] - error message; non-empty marks the field invalid (aria-invalid, clay border, icon).
+ * @param {boolean} [props.invalid=false] - force the invalid border without a message (sets aria-invalid).
+ * @param {React.ComponentType<{size?:number}>} [props.iconLeft] - leading lucide icon component (wraps the input in .input-ico).
+ * @param {string} [props.type='text'] - native input type.
+ * @param {boolean} [props.readOnly=false] - native readonly (surface-2 fill, quiet, still selectable).
+ * @param {boolean} [props.disabled=false] - native disabled.
+ * @param {string|number} [props.value] - controlled value.
+ * @param {string|number} [props.defaultValue] - initial value for uncontrolled use.
+ * @param {(e:React.ChangeEvent<HTMLInputElement>)=>void} [props.onChange] - change handler.
+ * @param {string} [props.id] - input id; auto-generated + associated with the label when omitted.
+ * @returns {JSX.Element}
+ */
+export default function Input({ label, lock, hint, error, invalid, iconLeft: IconLeft, type, readOnly, disabled, value, defaultValue, onChange, id, ...rest }: {
+    label?: React.ReactNode;
+    lock?: React.ComponentType<{
+        size?: number;
+    }>;
+    hint?: string;
+    error?: string;
+    invalid?: boolean;
+    iconLeft?: React.ComponentType<{
+        size?: number;
+    }>;
+    type?: string;
+    readOnly?: boolean;
+    disabled?: boolean;
+    value?: string | number;
+    defaultValue?: string | number;
+    onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    id?: string;
+}): JSX.Element;
+/**
+ * Textarea — the multi-line sibling of Input. Renders `textarea.input.is-input` (the CSS gives it an
+ * auto height with a min of one control row and vertical resize). Same label/hint/error and
+ * controlled/uncontrolled wiring as Input.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.label] - label above the field.
+ * @param {React.ComponentType<{size?:number}>} [props.lock] - optional lucide icon beside the label (.is-lk).
+ * @param {string} [props.hint] - helper text under the field.
+ * @param {string} [props.error] - error message; non-empty marks the field invalid.
+ * @param {boolean} [props.invalid=false] - force the invalid border (sets aria-invalid).
+ * @param {number} [props.rows=3] - visible rows.
+ * @param {boolean} [props.readOnly=false] - native readonly.
+ * @param {boolean} [props.disabled=false] - native disabled.
+ * @param {string} [props.value] - controlled value.
+ * @param {string} [props.defaultValue] - initial value for uncontrolled use.
+ * @param {(e:React.ChangeEvent<HTMLTextAreaElement>)=>void} [props.onChange] - change handler.
+ * @param {string} [props.id] - id; auto-generated + associated with the label when omitted.
+ * @returns {JSX.Element}
+ */
+export function Textarea({ label, lock, hint, error, invalid, rows, readOnly, disabled, value, defaultValue, onChange, id, ...rest }: {
+    label?: React.ReactNode;
+    lock?: React.ComponentType<{
+        size?: number;
+    }>;
+    hint?: string;
+    error?: string;
+    invalid?: boolean;
+    rows?: number;
+    readOnly?: boolean;
+    disabled?: boolean;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    id?: string;
+}): JSX.Element;
+/**
+ * Select — a styled native `<select>` inside a `.select-wrap` with a trailing ChevronDown (the chevron
+ * is decorative and ignores pointer events per the CSS). Pass options either as `children` (raw
+ * `<option>` elements) or an `options` array of {value,label}. Same label/hint/error +
+ * controlled/uncontrolled wiring as Input.
+ *
+ * Emits `<div class="is-field"><label/><div class="select-wrap"><select class="select"/>chevron</div>…</div>`.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.label] - label above the field.
+ * @param {React.ComponentType<{size?:number}>} [props.lock] - optional lucide icon beside the label (.is-lk).
+ * @param {string} [props.hint] - helper text under the field.
+ * @param {string} [props.error] - error message; non-empty marks the field invalid.
+ * @param {boolean} [props.invalid=false] - force the invalid border (sets aria-invalid).
+ * @param {{value:string,label:string}[]} [props.options] - option list; alternative to passing <option> children.
+ * @param {React.ReactNode} [props.children] - raw <option> elements (used when `options` is omitted).
+ * @param {boolean} [props.disabled=false] - native disabled.
+ * @param {string} [props.value] - controlled value.
+ * @param {string} [props.defaultValue] - initial value for uncontrolled use.
+ * @param {(e:React.ChangeEvent<HTMLSelectElement>)=>void} [props.onChange] - change handler.
+ * @param {string} [props.id] - id; auto-generated + associated with the label when omitted.
+ * @returns {JSX.Element}
+ */
+export function Select({ label, lock, hint, error, invalid, options, children, disabled, value, defaultValue, onChange, id, ...rest }: {
+    label?: React.ReactNode;
+    lock?: React.ComponentType<{
+        size?: number;
+    }>;
+    hint?: string;
+    error?: string;
+    invalid?: boolean;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    children?: React.ReactNode;
+    disabled?: boolean;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (e: React.ChangeEvent<HTMLSelectElement>) => void;
+    id?: string;
+}): JSX.Element;

package/dist/lib/types/Intensity.d.ts

@@ -0,0 +1,55 @@
+/** clamp any number into the 0..4 ramp domain (integers only). */
+export function clampLevel(level: any): number;
+/**
+ * coverage ratio (recorded / total) → ramp level. 0 / unknown = none; ≥ 0.9
+ * reads as fully covered. mirrors peasant's traceabilityLevel quantiles.
+ */
+export function coverageLevel(recorded: any, total: any): 0 | 4 | 1 | 2 | 3;
+/** density (0..1) → ramp level for the bottom-edge effort bar. */
+export function effortLevel(density: any): 0 | 4 | 1 | 2 | 3;
+/** generic value-vs-max quantization (heatmap cells, sparklines). */
+export function quantize(value: any, max: any): 0 | 4 | 1 | 2 | 3;
+/** loc → node size class. small files are compact; large ones get real estate. */
+export function locSize(loc: any): "sm" | "md" | "lg" | "xs" | "xl";
+export function IntensitySwatch({ level, accent, size, label, className, ...rest }: {
+    [x: string]: any;
+    level?: number;
+    accent: any;
+    size: any;
+    label: any;
+    className?: string;
+}): any;
+export function RampLegend({ title, words, className }: {
+    title?: string;
+    words?: string[];
+    className?: string;
+}): any;
+export function Heatmap({ values, levels, max, labels, ariaLabel, className }: {
+    values: any;
+    levels: any;
+    max: any;
+    labels: any;
+    ariaLabel?: string;
+    className?: string;
+}): any;
+export function MapNode({ label, loc, coverage, recorded, total, selected, violation, effortPct, size, as, onClick, className, ...rest }: {
+    [x: string]: any;
+    label: any;
+    loc: any;
+    coverage?: number;
+    recorded: any;
+    total: any;
+    selected?: boolean;
+    violation?: number;
+    effortPct: any;
+    size: any;
+    as?: string;
+    onClick: any;
+    className?: string;
+}): any;
+export function IntensityScope({ children, className, ...rest }: {
+    [x: string]: any;
+    children: any;
+    className?: string;
+}): any;
+export default MapNode;

package/dist/lib/types/MapCanvas.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @typedef {Object} MapNode
+ * @property {string} id                       stable key (repo-relative path)
+ * @property {string} label                    display label (leaf of a path is shown)
+ * @property {'folder'|'file'} kind            folder vs file — distinguished by ICON
+ * @property {number} [loc=0]                   lines of code — node WIDTH ∝ loc
+ * @property {number} [coverage=0]             0..4 monochrome coverage ramp (the FILL)
+ * @property {string} [parent]                 parent id (forms the tree)
+ * @property {number} [violations=0]           violation count — a clay badge
+ */
+/**
+ * @typedef {Object} MapEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {'structure'|'activity'} [kind='structure']  solid vs dashed
+ * @property {number} [weight=1]               stroke WIDTH ∝ weight (never hue)
+ */
+/**
+ * MapCanvas — an interactive code-structure map. Pan (drag), zoom (square controls /
+ * +/- keys, never wheel), semantic zoom (overview / folders / files) with edge
+ * ancestor-lifting, a minimap, and a node search combobox. Square metric-encoded
+ * nodes (width ∝ LOC, monochrome coverage fill, folder/file icon, amber selection +
+ * marker, clay violation badge) and square orthogonal edges (solid structure /
+ * dashed activity, width ∝ weight). Full roving-focus keyboard nav with an aria-live
+ * region. Pure: no data fetching, deterministic layout.
+ *
+ * @param {Object} props
+ * @param {{nodes: MapNode[], edges?: MapEdge[]}} [props.data]   the graph
+ * @param {'overview'|'folders'|'files'} [props.grain='folders'] initial semantic zoom
+ * @param {string} [props.selectedId]                            initial selection
+ * @param {(id:string|null, node:MapNode|null)=>void} [props.onSelect]  selection cb
+ * @param {number} [props.height=520]                            canvas height (px)
+ * @param {string} [props.ariaLabel='code map']                  application label
+ * @param {string} [props.className]                             extra container class
+ */
+export default function MapCanvas({ data, grain: initialGrain, selectedId: initialSelected, onSelect, height, ariaLabel, className, }: {
+    data?: {
+        nodes: MapNode[];
+        edges?: MapEdge[];
+    };
+    grain?: "overview" | "folders" | "files";
+    selectedId?: string;
+    onSelect?: (id: string | null, node: MapNode | null) => void;
+    height?: number;
+    ariaLabel?: string;
+    className?: string;
+}): any;
+export type MapNode = {
+    /**
+     * stable key (repo-relative path)
+     */
+    id: string;
+    /**
+     * display label (leaf of a path is shown)
+     */
+    label: string;
+    /**
+     * folder vs file — distinguished by ICON
+     */
+    kind: "folder" | "file";
+    /**
+     * lines of code — node WIDTH ∝ loc
+     */
+    loc?: number;
+    /**
+     * 0..4 monochrome coverage ramp (the FILL)
+     */
+    coverage?: number;
+    /**
+     * parent id (forms the tree)
+     */
+    parent?: string;
+    /**
+     * violation count — a clay badge
+     */
+    violations?: number;
+};
+export type MapEdge = {
+    from: string;
+    to: string;
+    /**
+     * solid vs dashed
+     */
+    kind?: "structure" | "activity";
+    /**
+     * stroke WIDTH ∝ weight (never hue)
+     */
+    weight?: number;
+};

package/dist/lib/types/Menu.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @typedef {Object} MenuItem
+ * @property {string}   label            row label (passed-through children case preserved)
+ * @property {React.ComponentType<any>} [icon]    leading lucide icon component (e.g. icon={Copy})
+ * @property {string}   [brand]          leading provider mark (e.g. brand="claude-code"); takes precedence over icon
+ * @property {string}   [kbd]            right-aligned shortcut hint (e.g. "⌘D")
+ * @property {boolean}  [danger]         destructive (.menu-danger) variant - clay, keeps icon + label
+ * @property {boolean}  [disabled]       aria-disabled row, skipped by arrow keys, not selectable
+ * @property {boolean}  [separator]      a role="separator" .menu-sep hairline row, skipped by keyboard nav
+ * @property {() => void} [onSelect]     invoked when the row is chosen (click or Enter/Space)
+ */
+/**
+ * Menu - a dropdown menu controlled by a single trigger button.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} props.label             trigger label (lowercase chrome by default)
+ * @param {MenuItem[]} [props.items=[]]             menu rows
+ * @param {'start'|'end'} [props.align='start']     which edge of the trigger the popout aligns to
+ * @param {React.ReactNode} [props.caption]         optional .menu-cap caption rendered inside the popout before the list
+ * @param {boolean} [props.defaultOpen=false]       render with the popout already open (specimen / screenshot state)
+ */
+export default function Menu({ label, items, align, caption, defaultOpen }: {
+    label: React.ReactNode;
+    items?: MenuItem[];
+    align?: "start" | "end";
+    caption?: React.ReactNode;
+    defaultOpen?: boolean;
+}): any;
+export type MenuItem = {
+    /**
+     * row label (passed-through children case preserved)
+     */
+    label: string;
+    /**
+     * leading lucide icon component (e.g. icon={Copy})
+     */
+    icon?: React.ComponentType<any>;
+    /**
+     * leading provider mark (e.g. brand="claude-code"); takes precedence over icon
+     */
+    brand?: string;
+    /**
+     * right-aligned shortcut hint (e.g. "⌘D")
+     */
+    kbd?: string;
+    /**
+     * destructive (.menu-danger) variant - clay, keeps icon + label
+     */
+    danger?: boolean;
+    /**
+     * aria-disabled row, skipped by arrow keys, not selectable
+     */
+    disabled?: boolean;
+    /**
+     * a role="separator" .menu-sep hairline row, skipped by keyboard nav
+     */
+    separator?: boolean;
+    /**
+     * invoked when the row is chosen (click or Enter/Space)
+     */
+    onSelect?: () => void;
+};

package/dist/lib/types/ModerationQueue.d.ts

@@ -0,0 +1,135 @@
+/**
+ * ApprovalBar — a sticky top bar for reviewing a single pending item. Once acted on it collapses
+ * to a one-line resolved acknowledgement (icon + word) rather than disappearing outright.
+ * @typedef {Object} ApprovalBarProps
+ * @property {React.ReactNode} subject  the thing under review, e.g. "pending share to {collective}";
+ *                                      the collective/title inside is USER CONTENT (case preserved).
+ * @property {() => void} [onApprove]   called when approve is clicked (after the optimistic resolve).
+ * @property {() => void} [onReject]    called when reject is clicked (after the optimistic resolve).
+ * @property {string} [approveLabel='approve'] lowercase label for the approve action.
+ * @property {string} [rejectLabel='reject']   lowercase label for the reject action.
+ * @property {string} [className]       extra classes appended to the .mod-bar root.
+ */
+/**
+ * @param {ApprovalBarProps} props
+ */
+export function ApprovalBar({ subject, onApprove, onReject, approveLabel, rejectLabel, className, }: ApprovalBarProps): any;
+/**
+ * ModerationQueue — a panel listing pending items (member requests OR shares). Each row shows who +
+ * detail + relative time, with approve/reject buttons. Acting on a row resolves it OPTIMISTICALLY in
+ * place: the buttons swap for an approved/rejected pill (olive/clay + icon) and the row is struck +
+ * dimmed, never removed — so the reviewer keeps an audit trail of what they just decided. When no
+ * items remain pending an empty state is shown.
+ * @typedef {Object} QueueItem
+ * @property {string} id                stable key.
+ * @property {'member'|'share'} [kind]  picks the leading icon (user-plus / inbox). defaults to share.
+ * @property {React.ReactNode} who       the actor — a handle/name. USER CONTENT (case preserved).
+ * @property {React.ReactNode} [detail]  the secondary line (org, title, …). USER CONTENT.
+ * @property {React.ReactNode} [when]    relative time, e.g. "2h ago". rendered tabular + lowercased.
+ *
+ * @typedef {Object} ModerationQueueProps
+ * @property {React.ReactNode} [title='pending review'] the panel header label (lowercase chrome).
+ * @property {QueueItem[]} [items=[]]   the pending items.
+ * @property {(item: QueueItem) => void} [onApprove] called with the item when approved.
+ * @property {(item: QueueItem) => void} [onReject]  called with the item when rejected.
+ * @property {React.ReactNode} [emptyLabel='nothing pending'] message for the empty state.
+ * @property {string} [className]       extra classes appended to the .mod-queue root.
+ */
+/**
+ * @param {ModerationQueueProps} props
+ */
+export function ModerationQueue({ title, items, onApprove, onReject, emptyLabel, className, }: ModerationQueueProps): any;
+export default ModerationQueue;
+/**
+ * ApprovalBar — a sticky top bar for reviewing a single pending item. Once acted on it collapses
+ * to a one-line resolved acknowledgement (icon + word) rather than disappearing outright.
+ */
+export type ApprovalBarProps = {
+    /**
+     * the thing under review, e.g. "pending share to {collective}";
+     * the collective/title inside is USER CONTENT (case preserved).
+     */
+    subject: React.ReactNode;
+    /**
+     * called when approve is clicked (after the optimistic resolve).
+     */
+    onApprove?: () => void;
+    /**
+     * called when reject is clicked (after the optimistic resolve).
+     */
+    onReject?: () => void;
+    /**
+     * lowercase label for the approve action.
+     */
+    approveLabel?: string;
+    /**
+     * lowercase label for the reject action.
+     */
+    rejectLabel?: string;
+    /**
+     * extra classes appended to the .mod-bar root.
+     */
+    className?: string;
+};
+/**
+ * ModerationQueue — a panel listing pending items (member requests OR shares). Each row shows who +
+ * detail + relative time, with approve/reject buttons. Acting on a row resolves it OPTIMISTICALLY in
+ * place: the buttons swap for an approved/rejected pill (olive/clay + icon) and the row is struck +
+ * dimmed, never removed — so the reviewer keeps an audit trail of what they just decided. When no
+ * items remain pending an empty state is shown.
+ */
+export type QueueItem = {
+    /**
+     * stable key.
+     */
+    id: string;
+    /**
+     * picks the leading icon (user-plus / inbox). defaults to share.
+     */
+    kind?: "member" | "share";
+    /**
+     * the actor — a handle/name. USER CONTENT (case preserved).
+     */
+    who: React.ReactNode;
+    /**
+     * the secondary line (org, title, …). USER CONTENT.
+     */
+    detail?: React.ReactNode;
+    /**
+     * relative time, e.g. "2h ago". rendered tabular + lowercased.
+     */
+    when?: React.ReactNode;
+};
+/**
+ * ModerationQueue — a panel listing pending items (member requests OR shares). Each row shows who +
+ * detail + relative time, with approve/reject buttons. Acting on a row resolves it OPTIMISTICALLY in
+ * place: the buttons swap for an approved/rejected pill (olive/clay + icon) and the row is struck +
+ * dimmed, never removed — so the reviewer keeps an audit trail of what they just decided. When no
+ * items remain pending an empty state is shown.
+ */
+export type ModerationQueueProps = {
+    /**
+     * the panel header label (lowercase chrome).
+     */
+    title?: React.ReactNode;
+    /**
+     * the pending items.
+     */
+    items?: QueueItem[];
+    /**
+     * called with the item when approved.
+     */
+    onApprove?: (item: QueueItem) => void;
+    /**
+     * called with the item when rejected.
+     */
+    onReject?: (item: QueueItem) => void;
+    /**
+     * message for the empty state.
+     */
+    emptyLabel?: React.ReactNode;
+    /**
+     * extra classes appended to the .mod-queue root.
+     */
+    className?: string;
+};

package/dist/lib/types/Pager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * the simple prev/next pager (the .pager specimen). a label naming the current page,
+ * flanked by previous/next icon buttons. reuses .pager + .btn.btn-secondary.btn-sm.btn-icon
+ * with no new css. for numbered pagination use a separate component.
+ *
+ * @typedef {Object} PagerProps
+ * @property {number} page - the current (1-based) page number. default 1.
+ * @property {number} total - the total number of pages. default 1.
+ * @property {() => void} [onPrev] - called when the previous button is clicked.
+ * @property {() => void} [onNext] - called when the next button is clicked.
+ * @property {(nextPage: number) => void} [onChange] - called with the new page number on either button (fallback when onPrev/onNext are not given).
+ * @property {string} [label] - aria-label for the whole pager nav. default 'pagination'.
+ *
+ * @param {PagerProps} props
+ */
+export default function Pager({ page, total, onPrev, onNext, onChange, label }: PagerProps): any;
+/**
+ * the simple prev/next pager (the .pager specimen). a label naming the current page,
+ * flanked by previous/next icon buttons. reuses .pager + .btn.btn-secondary.btn-sm.btn-icon
+ * with no new css. for numbered pagination use a separate component.
+ */
+export type PagerProps = {
+    /**
+     * - the current (1-based) page number. default 1.
+     */
+    page: number;
+    /**
+     * - the total number of pages. default 1.
+     */
+    total: number;
+    /**
+     * - called when the previous button is clicked.
+     */
+    onPrev?: () => void;
+    /**
+     * - called when the next button is clicked.
+     */
+    onNext?: () => void;
+    /**
+     * - called with the new page number on either button (fallback when onPrev/onNext are not given).
+     */
+    onChange?: (nextPage: number) => void;
+    /**
+     * - aria-label for the whole pager nav. default 'pagination'.
+     */
+    label?: string;
+};

package/dist/lib/types/Pagination.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @typedef {Object} PaginationProps
+ * @property {number} [page]            controlled current page (1-based); pair with onChange.
+ * @property {number} [defaultPage=1]   initial page when uncontrolled.
+ * @property {number} [total]           total number of pages. if omitted it is derived from
+ *                                      totalItems / pageSize.
+ * @property {number} [totalItems]      total item count, used with pageSize to derive `total`.
+ * @property {number} [pageSize=10]     items per page, used with totalItems to derive `total`.
+ * @property {(nextPage: number) => void} [onChange] called with the new 1-based page on any change.
+ * @property {number} [siblingCount=1]  page buttons shown on each side of the current page.
+ * @property {string} [label='pagination'] aria-label for the <nav>.
+ *
+ * @param {PaginationProps} props
+ */
+export default function Pagination({ page, defaultPage, total, totalItems, pageSize, onChange, siblingCount, label, }: PaginationProps): any;
+export type PaginationProps = {
+    /**
+     * controlled current page (1-based); pair with onChange.
+     */
+    page?: number;
+    /**
+     * initial page when uncontrolled.
+     */
+    defaultPage?: number;
+    /**
+     * total number of pages. if omitted it is derived from
+     *            totalItems / pageSize.
+     */
+    total?: number;
+    /**
+     * total item count, used with pageSize to derive `total`.
+     */
+    totalItems?: number;
+    /**
+     * items per page, used with totalItems to derive `total`.
+     */
+    pageSize?: number;
+    /**
+     * called with the new 1-based page on any change.
+     */
+    onChange?: (nextPage: number) => void;
+    /**
+     * page buttons shown on each side of the current page.
+     */
+    siblingCount?: number;
+    /**
+     * aria-label for the <nav>.
+     */
+    label?: string;
+};