@peasant-labs/fairtrade 0.0.1 → 0.0.2

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

@@ -0,0 +1,242 @@
+/**
+ * formatRange({from,to}) -> a lowercase, tabular display string.
+ *   {from:'2026-06-01', to:'2026-06-14'} -> "jun 1 – jun 14, 2026"
+ *   same month is collapsed; a single day drops the dash; an open value returns "".
+ * @param {{from:string|null,to:string|null}} value
+ * @param {{long?:boolean}} [opts]  long=true spells the month ("june" not "jun")
+ */
+export function formatRange(value: {
+    from: string | null;
+    to: string | null;
+}, opts?: {
+    long?: boolean;
+}): string;
+/**
+ * @typedef {Object} CalendarProps
+ * @property {{from:string|null,to:string|null}} [value]         controlled ISO range
+ * @property {{from:string|null,to:string|null}} [defaultValue]  uncontrolled seed
+ * @property {(v:{from:string|null,to:string|null}) => void} [onChange]       fires on a committed range
+ * @property {(v:{from:string|null,to:string|null}) => void} [onDraftChange]  fires on each in-grid change before commit
+ * @property {string} [min]   ISO lower bound (inclusive); out-of-range days are aria-disabled
+ * @property {string} [max]   ISO upper bound (inclusive)
+ * @property {1|2} [numberOfMonths]  months shown side by side (collapses to 1 under ~560px via container query)
+ * @property {0|1|2|3|4|5|6} [weekStartsOn]  first column weekday (1 = monday, ISO default)
+ * @property {string} [className]  extra classes on the .dr-cal wrapper (e.g. "is-static" for embeds)
+ * @property {(focusedISO:string) => void} [onAutoFocus]  internal: notified when the grid focuses a day
+ * @property {boolean} [autoFocus]  move DOM focus into the focused day on mount
+ */
+export function DateRangeCalendar({ value, defaultValue, onChange, onDraftChange, min, max, numberOfMonths, weekStartsOn, className, autoFocus, gridLabelId, }: {
+    value: any;
+    defaultValue?: {
+        from: any;
+        to: any;
+    };
+    onChange: any;
+    onDraftChange: any;
+    min: any;
+    max: any;
+    numberOfMonths?: number;
+    weekStartsOn?: number;
+    className?: string;
+    autoFocus?: boolean;
+    gridLabelId: any;
+}): any;
+/**
+ * @typedef {Object} DateRangeProps
+ * @property {{from:string|null,to:string|null}} [value]         controlled ISO range
+ * @property {{from:string|null,to:string|null}} [defaultValue]  uncontrolled seed
+ * @property {(v:{from:string|null,to:string|null}) => void} [onChange]       fires only on a committed range / preset / clear
+ * @property {(v:{from:string|null,to:string|null}) => void} [onDraftChange]  fires on each in-popover change before commit
+ * @property {{id:string,label:string,range:() => ({from:string,to:string})}[]} [presets]  quick ranges; [] hides the rail
+ * @property {string} [min]  ISO lower bound (inclusive)
+ * @property {string} [max]  ISO upper bound (inclusive)
+ * @property {1|2} [numberOfMonths]  desktop month count (auto-collapses to 1 under ~560px)
+ * @property {0|1|2|3|4|5|6} [weekStartsOn]  first column weekday (1 = monday)
+ * @property {string} [placeholder]  trigger label when empty (lowercase chrome)
+ * @property {string} [label]  optional .label rendered above (form use)
+ * @property {'start'|'end'} [align]  which trigger edge the popover aligns to
+ * @property {'md'|'sm'} [size]  trigger height (36 / 28px)
+ * @property {boolean} [disabled]
+ * @property {boolean} [clearable]  show a clear (X) action in the footer when a range is set
+ * @property {string} [id]  trigger id; popover id derives `${id}-pop`
+ */
+export default function DateRange({ value, defaultValue, onChange, onDraftChange, presets, min, max, numberOfMonths, weekStartsOn, placeholder, label, align, size, disabled, clearable, id, }: {
+    value: any;
+    defaultValue?: {
+        from: any;
+        to: any;
+    };
+    onChange: any;
+    onDraftChange: any;
+    presets?: {
+        id: string;
+        label: string;
+        range: () => {
+            from: any;
+            to: any;
+        };
+    }[];
+    min: any;
+    max: any;
+    numberOfMonths?: number;
+    weekStartsOn?: number;
+    placeholder?: string;
+    label: any;
+    align?: string;
+    size?: string;
+    disabled?: boolean;
+    clearable?: boolean;
+    id: any;
+}): any;
+/**
+ * DATE_PRESETS - the default quick-range list. each `range()` is evaluated at open time
+ * against today's local date, so "last 7 days" always tracks the real calendar.
+ */
+export const DATE_PRESETS: {
+    id: string;
+    label: string;
+    range: () => {
+        from: any;
+        to: any;
+    };
+}[];
+export type CalendarProps = {
+    /**
+     * controlled ISO range
+     */
+    value?: {
+        from: string | null;
+        to: string | null;
+    };
+    /**
+     * uncontrolled seed
+     */
+    defaultValue?: {
+        from: string | null;
+        to: string | null;
+    };
+    /**
+     * fires on a committed range
+     */
+    onChange?: (v: {
+        from: string | null;
+        to: string | null;
+    }) => void;
+    /**
+     * fires on each in-grid change before commit
+     */
+    onDraftChange?: (v: {
+        from: string | null;
+        to: string | null;
+    }) => void;
+    /**
+     * ISO lower bound (inclusive); out-of-range days are aria-disabled
+     */
+    min?: string;
+    /**
+     * ISO upper bound (inclusive)
+     */
+    max?: string;
+    /**
+     * months shown side by side (collapses to 1 under ~560px via container query)
+     */
+    numberOfMonths?: 1 | 2;
+    /**
+     * first column weekday (1 = monday, ISO default)
+     */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * extra classes on the .dr-cal wrapper (e.g. "is-static" for embeds)
+     */
+    className?: string;
+    /**
+     * internal: notified when the grid focuses a day
+     */
+    onAutoFocus?: (focusedISO: string) => void;
+    /**
+     * move DOM focus into the focused day on mount
+     */
+    autoFocus?: boolean;
+};
+export type DateRangeProps = {
+    /**
+     * controlled ISO range
+     */
+    value?: {
+        from: string | null;
+        to: string | null;
+    };
+    /**
+     * uncontrolled seed
+     */
+    defaultValue?: {
+        from: string | null;
+        to: string | null;
+    };
+    /**
+     * fires only on a committed range / preset / clear
+     */
+    onChange?: (v: {
+        from: string | null;
+        to: string | null;
+    }) => void;
+    /**
+     * fires on each in-popover change before commit
+     */
+    onDraftChange?: (v: {
+        from: string | null;
+        to: string | null;
+    }) => void;
+    /**
+     * quick ranges; [] hides the rail
+     */
+    presets?: {
+        id: string;
+        label: string;
+        range: () => ({
+            from: string;
+            to: string;
+        });
+    }[];
+    /**
+     * ISO lower bound (inclusive)
+     */
+    min?: string;
+    /**
+     * ISO upper bound (inclusive)
+     */
+    max?: string;
+    /**
+     * desktop month count (auto-collapses to 1 under ~560px)
+     */
+    numberOfMonths?: 1 | 2;
+    /**
+     * first column weekday (1 = monday)
+     */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * trigger label when empty (lowercase chrome)
+     */
+    placeholder?: string;
+    /**
+     * optional .label rendered above (form use)
+     */
+    label?: string;
+    /**
+     * which trigger edge the popover aligns to
+     */
+    align?: "start" | "end";
+    /**
+     * trigger height (36 / 28px)
+     */
+    size?: "md" | "sm";
+    disabled?: boolean;
+    /**
+     * show a clear (X) action in the footer when a range is set
+     */
+    clearable?: boolean;
+    /**
+     * trigger id; popover id derives `${id}-pop`
+     */
+    id?: string;
+};

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

@@ -0,0 +1,9 @@
+export default function Dialog({ open, onClose, title, labelId, children, footer, returnFocusRef }: {
+    open: any;
+    onClose: any;
+    title: any;
+    labelId?: string;
+    children: any;
+    footer: any;
+    returnFocusRef: any;
+}): any;

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

@@ -0,0 +1,39 @@
+/**
+ * DiffView — a unified hunk diff. two shapes, one chassis:
+ *
+ *  default:    pass `hunks` = [{ header, lines: [{ type:'add'|'del'|'ctx', oldNo, newNo, text }] }].
+ *              renders a file header (path + +N/−N churn) then each hunk's `@@` row and lines.
+ *
+ *  redaction:  variant="redaction", pass `matches` = [{ category, confidence, original,
+ *              replacement, oldNo, newNo }]. each match is a del→add pair with a category·
+ *              confidence badge and a per-match keep/revert button.
+ *
+ * @param {object} props
+ * @param {string} props.file - the file path shown in the header (mono, not lowercased)
+ * @param {Array<{header?:string, lines:Array<{type:'add'|'del'|'ctx', oldNo?:number|string, newNo?:number|string, text:string}>}>} [props.hunks] - structured hunks (default variant)
+ * @param {Array<{category:string, confidence:number, original:string, replacement:string, oldNo?:number|string, newNo?:number|string}>} [props.matches] - redaction matches (redaction variant)
+ * @param {'default'|'redaction'} [props.variant='default']
+ * @param {string} [props.className]
+ */
+export default function DiffView({ file, hunks, matches, variant, className, ...rest }: {
+    file: string;
+    hunks?: Array<{
+        header?: string;
+        lines: Array<{
+            type: "add" | "del" | "ctx";
+            oldNo?: number | string;
+            newNo?: number | string;
+            text: string;
+        }>;
+    }>;
+    matches?: Array<{
+        category: string;
+        confidence: number;
+        original: string;
+        replacement: string;
+        oldNo?: number | string;
+        newNo?: number | string;
+    }>;
+    variant?: "default" | "redaction";
+    className?: string;
+}): any;

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

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('react').ReactNode} ReactNode
+ * @typedef {import('react').ComponentType<{ size?: number, 'aria-hidden'?: boolean }>} IconComponent
+ */
+/**
+ * EmptyState — left-aligned empty/zero-state block: a ringed icon, title,
+ * message, and an optional action slot. Emits the exact `.empty` markup the
+ * existing `src/index.css` styles (left-aligned by design).
+ *
+ * @param {object} props
+ * @param {IconComponent} [props.icon] - lucide-react icon component reference (e.g. `Compass`); rendered decoratively inside the `.ring`. The CSS sizes `.ring .lucide` to --ic-lg (18px).
+ * @param {ReactNode} props.title - short heading, rendered by the `as` element (default `h3`).
+ * @param {ReactNode} [props.message] - supporting copy, rendered in `p`. Omitted if not provided.
+ * @param {ReactNode} [props.action] - optional action slot (e.g. a button). Takes precedence over `children`.
+ * @param {ReactNode} [props.children] - fallback action slot, used only when `action` is not provided.
+ * @param {keyof JSX.IntrinsicElements} [props.as='h3'] - heading element/level for the title, so the component can fit the surrounding heading outline (e.g. `h2`).
+ * @returns {JSX.Element}
+ */
+export default function EmptyState({ icon: Icon, title, message, action, children, as: Heading }: {
+    icon?: IconComponent;
+    title: ReactNode;
+    message?: ReactNode;
+    action?: ReactNode;
+    children?: ReactNode;
+    as?: keyof JSX.IntrinsicElements;
+}): JSX.Element;
+export type ReactNode = any;
+export type IconComponent = any;

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

@@ -0,0 +1,39 @@
+/**
+ * EvidenceCaption — the recap sentence assembled from fragments.
+ *
+ * @param {object} props
+ * @param {Array<{text: string, anchorId?: string, label?: string}>} props.fragments
+ *        the ordered fragments. a fragment WITH `anchorId` is a clickable proof link (jumps to the
+ *        <EvidenceTarget id={anchorId}> and flashes it); `label` names the destination for AT
+ *        (defaults to the anchorId). a fragment without `anchorId` is plain prose.
+ * @param {(anchorId: string) => void} [props.onJump] - called with the anchorId when a fragment is
+ *        activated (in addition to the built-in scroll + highlight).
+ * @param {string} [props['aria-label']] - accessible label for the recap region (default: "recap").
+ * @param {string} [props.className]
+ */
+export function EvidenceCaption({ fragments, onJump, "aria-label": ariaLabel, className, ...rest }: {
+    fragments: Array<{
+        text: string;
+        anchorId?: string;
+        label?: string;
+    }>;
+    onJump?: (anchorId: string) => void;
+}): any;
+/**
+ * EvidenceTarget — the proof block a fragment jumps to. it owns the `id` the caption scrolls to and
+ * the `data-ec-flash` attribute the CSS animates on arrival. give it an `eyebrow` (a small mono
+ * anchor label, lowercased chrome) so the reader sees which evidence they landed on.
+ *
+ * @param {object} props
+ * @param {string} props.id - the anchor id; a fragment's `anchorId` points here.
+ * @param {string} [props.eyebrow] - the small anchor label shown above the block (chrome → mono).
+ * @param {React.ReactNode} props.children - the evidence content.
+ * @param {string} [props.className]
+ */
+export function EvidenceTarget({ id, eyebrow, children, className, ...rest }: {
+    id: string;
+    eyebrow?: string;
+    children: React.ReactNode;
+    className?: string;
+}): any;
+export default EvidenceCaption;

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

@@ -0,0 +1,82 @@
+/**
+ * @typedef {Object} ExplainerProps
+ * @property {React.ReactNode} children            the explanatory PROSE (rendered in var(--font-body)); may contain <Term> words.
+ * @property {React.ReactNode} [title='what am i looking at?']  the toggle-row heading (mono chrome, lowercased by css).
+ * @property {boolean} [defaultOpen=false]         initial open state when nothing is persisted.
+ * @property {string} [storageKey]                 when given, open/closed persists to localStorage under this surface key.
+ * @property {'card'|'inline'} [tone='card']       'card' = bordered panel; 'inline' = a quieter ghost (no fill/border).
+ * @property {string} [className]                  extra class on the root.
+ */
+/**
+ * The "what am i looking at?" block — one per surface. A square "?" / heading toggle row reveals or
+ * hides a short prose body (the heading reads aria-expanded; the body is the toggle's aria-controls
+ * region). The toggle target is the whole row (>= the 24px minimum). Open state persists per surface
+ * when `storageKey` is set. Two tones: a bordered `card` panel, or a quieter `inline` ghost.
+ * It is never a modal and never steals focus.
+ */
+export default function Explainer({ children, title, defaultOpen, storageKey, tone, className, }: {
+    children: any;
+    title?: string;
+    defaultOpen?: boolean;
+    storageKey: any;
+    tone?: string;
+    className?: string;
+}): any;
+/**
+ * @typedef {Object} TermProps
+ * @property {string} def              the plain-language definition shown in the tooltip (mono chrome).
+ * @property {React.ReactNode} children  the inline word(s) to underline.
+ * @property {string} [className]      extra class on the trigger.
+ */
+/**
+ * Inline glossary term: a dotted-underline word that reveals a small square tooltip with its
+ * definition on hover AND keyboard focus (and on tap, for touch). The trigger is a real <button> so
+ * it's reachable and operable from the keyboard; the bubble is wired via aria-describedby so the
+ * definition reinforces — never solely names — the word. A tooltip is reinforcement, so anything
+ * load-bearing must also live in visible copy.
+ */
+export function Term({ def, children, className }: {
+    def: any;
+    children: any;
+    className?: string;
+}): any;
+export type ExplainerProps = {
+    /**
+     * the explanatory PROSE (rendered in var(--font-body)); may contain <Term> words.
+     */
+    children: React.ReactNode;
+    /**
+     * the toggle-row heading (mono chrome, lowercased by css).
+     */
+    title?: React.ReactNode;
+    /**
+     * initial open state when nothing is persisted.
+     */
+    defaultOpen?: boolean;
+    /**
+     * when given, open/closed persists to localStorage under this surface key.
+     */
+    storageKey?: string;
+    /**
+     * 'card' = bordered panel; 'inline' = a quieter ghost (no fill/border).
+     */
+    tone?: "card" | "inline";
+    /**
+     * extra class on the root.
+     */
+    className?: string;
+};
+export type TermProps = {
+    /**
+     * the plain-language definition shown in the tooltip (mono chrome).
+     */
+    def: string;
+    /**
+     * the inline word(s) to underline.
+     */
+    children: React.ReactNode;
+    /**
+     * extra class on the trigger.
+     */
+    className?: string;
+};

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

@@ -0,0 +1,13 @@
+export default function FacetRail({ order, onOrder, providers, activeProviders, onProvider, topics, activeTopics, onTopic, onClear, className, ...rest }: {
+    [x: string]: any;
+    order?: string;
+    onOrder: any;
+    providers?: any[];
+    activeProviders?: Set<any>;
+    onProvider: any;
+    topics?: any[];
+    activeTopics?: Set<any>;
+    onTopic: any;
+    onClear: any;
+    className?: string;
+}): any;

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

@@ -0,0 +1,222 @@
+/**
+ * Skeleton — a placeholder block that mirrors the shape of loading content.
+ * @typedef {Object} SkeletonProps
+ * @property {string} [label='loading'] aria-label announcing what is loading.
+ * @property {boolean} [avatar=true]    render the leading 32px avatar block + two
+ *                                      stacked lines (w-40 / w-70) at the top.
+ * @property {number} [lines=2]         number of full-width body lines below the row;
+ *                                      they cycle through w-90 / w-70 widths.
+ * @property {string} [className]       extra classes appended to the .fb-skel root.
+ */
+/**
+ * @param {SkeletonProps} props
+ */
+export function Skeleton({ label, avatar, lines, className }: SkeletonProps): any;
+/**
+ * Progress — a determinate progress bar with a labelled head + tabular percent.
+ * @typedef {Object} ProgressProps
+ * @property {number} [value=0]         current value, 0–100 (clamped); drives the fill
+ *                                      width and aria-valuenow + the displayed percent.
+ * @property {number} [min=0]           aria-valuemin.
+ * @property {number} [max=100]         aria-valuemax.
+ * @property {React.ReactNode} [label]  caption shown at the left of the head row.
+ * @property {string} [ariaLabel]       accessible name for the track (progressbar);
+ *                                      falls back to the string `label` when omitted.
+ * @property {boolean} [showPct=true]   render the tabular percent on the right.
+ * @property {string} [className]       extra classes appended to the .fb-prog root.
+ */
+/**
+ * @param {ProgressProps} props
+ */
+export function Progress({ value, min, max, label, ariaLabel, showPct, className, }: ProgressProps): any;
+/**
+ * Spinner — an inline busy marker: spinning icon + lowercase label, in a live region.
+ * @typedef {Object} SpinnerProps
+ * @property {React.ReactNode} [children] label text beside the icon (the live message).
+ * @property {React.ComponentType} [icon=LoaderCircle] icon component reference; the CSS
+ *                                      spins .lucide only under no-preference + aria-busy.
+ * @property {string} [className]       extra classes appended to the .fb-spin root.
+ */
+/**
+ * @param {SpinnerProps} props
+ */
+export function Spinner({ children, icon: Icon, className }: SpinnerProps): any;
+/**
+ * Toast — a transient notification: icon + title + message + dismiss button.
+ * Render inside an aria-live region (e.g. a wrapper with aria-live="polite") for the
+ * announcement; the toast itself carries role status (ok) or alert (error).
+ * @typedef {Object} ToastProps
+ * @property {'ok'|'err'} [variant='ok'] tone; 'ok' = circle-check/olive + role=status,
+ *                                      'err' = circle-x/clay + role=alert.
+ * @property {React.ReactNode} title    the .fb-toast-title line.
+ * @property {React.ReactNode} [children] the body message (.fb-toast-msg).
+ * @property {React.ComponentType} [icon] override the leading icon component reference.
+ * @property {() => void} [onClose]     called when the dismiss button is clicked; when
+ *                                      omitted the close button is not rendered.
+ * @property {string} [closeLabel='dismiss notification'] aria-label for the close button.
+ * @property {string} [className]       extra classes appended to the .fb-toast root.
+ */
+/**
+ * @param {ToastProps} props
+ */
+export function Toast({ variant, title, children, icon: Icon, onClose, closeLabel, className, }: ToastProps): any;
+/**
+ * FeedbackPanel — a centred inline state surface (loading / error / empty), with an
+ * icon tile, lowercase title and a message. Loading sets aria-busy + role=status;
+ * error sets role=alert; the neutral (empty / resolved) panel has no role.
+ * @typedef {Object} FeedbackPanelProps
+ * @property {'loading'|'error'|'empty'} [variant='empty'] which surface to render; picks
+ *                                      the default icon, role and .is-err styling.
+ * @property {React.ReactNode} [title]  the .fb-panel-title (defaults per variant).
+ * @property {React.ReactNode} [children] the message body (.fb-panel-msg).
+ * @property {React.ComponentType} [icon] override the icon component reference; defaults
+ *                                      to loader-circle / circle-alert / search-x.
+ * @property {string} [className]       extra classes appended to the .fb-panel root.
+ */
+/**
+ * @param {FeedbackPanelProps} props
+ */
+export function FeedbackPanel({ variant, title, children, icon: Icon, className }: FeedbackPanelProps): any;
+export default Spinner;
+/**
+ * Skeleton — a placeholder block that mirrors the shape of loading content.
+ */
+export type SkeletonProps = {
+    /**
+     * aria-label announcing what is loading.
+     */
+    label?: string;
+    /**
+     * render the leading 32px avatar block + two
+     *     stacked lines (w-40 / w-70) at the top.
+     */
+    avatar?: boolean;
+    /**
+     * number of full-width body lines below the row;
+     *          they cycle through w-90 / w-70 widths.
+     */
+    lines?: number;
+    /**
+     * extra classes appended to the .fb-skel root.
+     */
+    className?: string;
+};
+/**
+ * Progress — a determinate progress bar with a labelled head + tabular percent.
+ */
+export type ProgressProps = {
+    /**
+     * current value, 0–100 (clamped); drives the fill
+     *          width and aria-valuenow + the displayed percent.
+     */
+    value?: number;
+    /**
+     * aria-valuemin.
+     */
+    min?: number;
+    /**
+     * aria-valuemax.
+     */
+    max?: number;
+    /**
+     * caption shown at the left of the head row.
+     */
+    label?: React.ReactNode;
+    /**
+     * accessible name for the track (progressbar);
+     *        falls back to the string `label` when omitted.
+     */
+    ariaLabel?: string;
+    /**
+     * render the tabular percent on the right.
+     */
+    showPct?: boolean;
+    /**
+     * extra classes appended to the .fb-prog root.
+     */
+    className?: string;
+};
+/**
+ * Spinner — an inline busy marker: spinning icon + lowercase label, in a live region.
+ */
+export type SpinnerProps = {
+    /**
+     * label text beside the icon (the live message).
+     */
+    children?: React.ReactNode;
+    /**
+     * icon component reference; the CSS
+     * spins .lucide only under no-preference + aria-busy.
+     */
+    icon?: React.ComponentType;
+    /**
+     * extra classes appended to the .fb-spin root.
+     */
+    className?: string;
+};
+/**
+ * Toast — a transient notification: icon + title + message + dismiss button.
+ * Render inside an aria-live region (e.g. a wrapper with aria-live="polite") for the
+ * announcement; the toast itself carries role status (ok) or alert (error).
+ */
+export type ToastProps = {
+    /**
+     * tone; 'ok' = circle-check/olive + role=status,
+     * 'err' = circle-x/clay + role=alert.
+     */
+    variant?: "ok" | "err";
+    /**
+     * the .fb-toast-title line.
+     */
+    title: React.ReactNode;
+    /**
+     * the body message (.fb-toast-msg).
+     */
+    children?: React.ReactNode;
+    /**
+     * override the leading icon component reference.
+     */
+    icon?: React.ComponentType;
+    /**
+     * called when the dismiss button is clicked; when
+     *      omitted the close button is not rendered.
+     */
+    onClose?: () => void;
+    /**
+     * aria-label for the close button.
+     */
+    closeLabel?: string;
+    /**
+     * extra classes appended to the .fb-toast root.
+     */
+    className?: string;
+};
+/**
+ * FeedbackPanel — a centred inline state surface (loading / error / empty), with an
+ * icon tile, lowercase title and a message. Loading sets aria-busy + role=status;
+ * error sets role=alert; the neutral (empty / resolved) panel has no role.
+ */
+export type FeedbackPanelProps = {
+    /**
+     * which surface to render; picks
+     * the default icon, role and .is-err styling.
+     */
+    variant?: "loading" | "error" | "empty";
+    /**
+     * the .fb-panel-title (defaults per variant).
+     */
+    title?: React.ReactNode;
+    /**
+     * the message body (.fb-panel-msg).
+     */
+    children?: React.ReactNode;
+    /**
+     * override the icon component reference; defaults
+     * to loader-circle / circle-alert / search-x.
+     */
+    icon?: React.ComponentType;
+    /**
+     * extra classes appended to the .fb-panel root.
+     */
+    className?: string;
+};