@peasant-labs/fairtrade 0.0.0

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

@@ -0,0 +1,71 @@
+/**
+ * @typedef {object} Commit
+ * @property {string} id - stable key (e.g. short hash)
+ * @property {number} lane - 0 = main line; >0 = a branch lane
+ * @property {string[]} [parents] - parent commit ids (>1 = a merge commit)
+ * @property {string} message - the commit subject (USER CONTENT — case preserved)
+ * @property {string} [branch] - branch name for the chip (USER CONTENT — case preserved)
+ * @property {boolean} [session] - a recorded AI session sits behind this commit (-> filled + sparkle)
+ * @property {boolean} [merged] - this commit merged a branch back in (-> merged chip)
+ * @property {boolean} [tip] - this commit is a branch tip (-> small tip affordance)
+ * @property {string} [time] - relative time label (e.g. "8m ago") — already humanised by the caller
+ */
+/**
+ * CommitGraph — render `commits` (newest first) as a lane gutter + a column of selectable rows.
+ *
+ * @param {object} props
+ * @param {Commit[]} props.commits - the history, newest first; lane 0 is the main line.
+ * @param {string} [props.selectedId] - id of the active/selected row (the scarce amber treatment).
+ * @param {(commit: Commit) => void} [props.onSelect] - called with the commit when a row is chosen.
+ * @param {boolean} [props.hasMore=false] - more history exists below the window -> show the "show older" ghost.
+ * @param {() => void} [props.onShowOlder] - called when "show older" is pressed.
+ * @param {string} [props.label='commit history'] - accessible name for the list (lowercase chrome).
+ * @param {string} [props.className] - extra classes appended to the root.
+ */
+export default function CommitGraph({ commits, selectedId, onSelect, hasMore, onShowOlder, label, className, ...rest }: {
+    commits: Commit[];
+    selectedId?: string;
+    onSelect?: (commit: Commit) => void;
+    hasMore?: boolean;
+    onShowOlder?: () => void;
+    label?: string;
+    className?: string;
+}): any;
+export type Commit = {
+    /**
+     * - stable key (e.g. short hash)
+     */
+    id: string;
+    /**
+     * - 0 = main line; >0 = a branch lane
+     */
+    lane: number;
+    /**
+     * - parent commit ids (>1 = a merge commit)
+     */
+    parents?: string[];
+    /**
+     * - the commit subject (USER CONTENT — case preserved)
+     */
+    message: string;
+    /**
+     * - branch name for the chip (USER CONTENT — case preserved)
+     */
+    branch?: string;
+    /**
+     * - a recorded AI session sits behind this commit (-> filled + sparkle)
+     */
+    session?: boolean;
+    /**
+     * - this commit merged a branch back in (-> merged chip)
+     */
+    merged?: boolean;
+    /**
+     * - this commit is a branch tip (-> small tip affordance)
+     */
+    tip?: boolean;
+    /**
+     * - relative time label (e.g. "8m ago") — already humanised by the caller
+     */
+    time?: string;
+};

package/dist/lib/types/CommitGraph.stories.d.ts

@@ -0,0 +1,17 @@
+export default meta;
+export namespace Default {
+    function render(): any;
+}
+export namespace Linear {
+    export function render_1(): any;
+    export { render_1 as render };
+}
+declare namespace meta {
+    export let title: string;
+    export { CommitGraph as component };
+    export let decorators: Function[];
+    export namespace parameters {
+        let layout: string;
+    }
+}
+import CommitGraph from './CommitGraph.jsx';

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

@@ -0,0 +1,82 @@
+/**
+ * ConnectionPill — the small, glanceable connection indicator. a square hairline pill carrying an
+ * icon and the word; the note ("on this computer · no internet") sits beside it as quiet mono
+ * chrome. the state never rides on color alone: the icon and the word both encode it (no status
+ * dot — a color-only dot would break that rule), and the whole pill is announced via role=status.
+ * the per-tone icon color is a tint on top, only where color is welcome.
+ *
+ * @param {object} props
+ * @param {'live'|'connecting'|'disconnected'} [props.status='live'] - the connection state.
+ * @param {boolean} [props.showNote=true] - render the trailing "on this computer · no internet"
+ *        style note. set false for the tightest, word-only pill.
+ * @param {string} [props.className]
+ */
+export function ConnectionPill({ status, showNote, className, ...rest }: {
+    status?: "live" | "connecting" | "disconnected";
+    showNote?: boolean;
+    className?: string;
+}): any;
+/**
+ * DataState — the discriminator between the states a data view can be in, so a dropped connection
+ * never reads as "empty". precedence is deliberate:
+ *
+ *   loading                  → a skeleton (don't show "empty" before the answer is in).
+ *   disconnected || error    → the calm lost-connection panel + retry (the key rule:
+ *                              disconnected != empty — a lost socket is not zero results).
+ *   empty                    → the teaching `empty` slot (connected, but genuinely nothing here).
+ *   else                     → children (the real content).
+ *
+ * @param {object} props
+ * @param {'live'|'connecting'|'disconnected'} [props.status] - the live connection status. when
+ *        'disconnected', the lost-connection panel wins over `empty` even if `empty` is provided.
+ * @param {boolean} [props.loading] - data is in flight; show the skeleton.
+ * @param {boolean|string} [props.error] - an error occurred; truthy shows the lost-connection
+ *        panel. a string overrides the panel body.
+ * @param {boolean} [props.empty] - connected, request resolved, but there is nothing to show.
+ * @param {import('react').ReactNode} [props.children] - the real content, shown when none of the
+ *        above apply.
+ * @param {import('react').ReactNode} [props.emptyState] - the teaching empty slot (e.g. a
+ *        <TeachingEmptyState/>), rendered when `empty` is true.
+ * @param {() => void} [props.onRetry] - retry handler for the lost-connection panel.
+ * @param {number} [props.skeletonRows=3] - how many skeleton bars to show while loading.
+ * @param {string} [props.className]
+ */
+export function DataState({ status, loading, error, empty, children, emptyState, onRetry, skeletonRows, className, ...rest }: {
+    status?: "live" | "connecting" | "disconnected";
+    loading?: boolean;
+    error?: boolean | string;
+    empty?: boolean;
+    children?: any;
+    emptyState?: any;
+    onRetry?: () => void;
+    skeletonRows?: number;
+    className?: string;
+}): any;
+/**
+ * TeachingEmptyState — an empty state that TEACHES the mechanism instead of just declaring the
+ * absence. a leading icon, a title, a line of guidance, and a copy-able `$ command` chip (the
+ * actual command to run, e.g. `peasant ingest`) with an inline copy button — then a short privacy
+ * line, because the whole point is that this runs locally and nothing leaves the machine.
+ *
+ * @param {object} props
+ * @param {import('react').ComponentType} [props.icon=HardDrive] - lucide icon for the heading.
+ * @param {import('react').ReactNode} props.title - the short headline.
+ * @param {import('react').ReactNode} [props.body] - a line of guidance prose (what the command
+ *        does, in plain words).
+ * @param {string} [props.command] - the command to teach, shown in a `$`-prefixed mono chip with a
+ *        copy button. the `$` is decoration; only the command itself is copied.
+ * @param {import('react').ReactNode} [props.privacy] - the privacy line. defaults to "nothing
+ *        leaves your machine". pass null to omit.
+ * @param {keyof JSX.IntrinsicElements} [props.as='h3'] - heading level for the title.
+ * @param {string} [props.className]
+ */
+export function TeachingEmptyState({ icon: Icon, title, body, command, privacy, as: Heading, className, ...rest }: {
+    icon?: any;
+    title: any;
+    body?: any;
+    command?: string;
+    privacy?: any;
+    as?: keyof JSX.IntrinsicElements;
+    className?: string;
+}): any;
+export default ConnectionPill;

package/dist/lib/types/ConnectionState.stories.d.ts

@@ -0,0 +1,117 @@
+export default meta;
+export namespace Pills {
+    namespace parameters {
+        namespace controls {
+            let include: any[];
+        }
+    }
+    function render(): any;
+    function play({ canvasElement }: {
+        canvasElement: any;
+    }): Promise<void>;
+}
+export namespace SinglePill {
+    export function render_1(args: any): any;
+    export { render_1 as render };
+    export namespace args {
+        let status: string;
+        let showNote: boolean;
+    }
+}
+export namespace Disconnected {
+    export namespace parameters_1 {
+        export namespace controls_1 {
+            let include_1: any[];
+            export { include_1 as include };
+        }
+        export { controls_1 as controls };
+    }
+    export { parameters_1 as parameters };
+    export function render_2(): any;
+    export { render_2 as render };
+    export function play_1({ canvasElement }: {
+        canvasElement: any;
+    }): Promise<void>;
+    export { play_1 as play };
+}
+export namespace TeachingEmpty {
+    export namespace parameters_2 {
+        export namespace controls_2 {
+            let include_2: any[];
+            export { include_2 as include };
+        }
+        export { controls_2 as controls };
+    }
+    export { parameters_2 as parameters };
+    export function render_3(): any;
+    export { render_3 as render };
+    export function play_2({ canvasElement }: {
+        canvasElement: any;
+    }): Promise<void>;
+    export { play_2 as play };
+}
+export namespace TeachingStandalone {
+    export namespace parameters_3 {
+        export namespace controls_3 {
+            let include_3: any[];
+            export { include_3 as include };
+        }
+        export { controls_3 as controls };
+    }
+    export { parameters_3 as parameters };
+    export function render_4(): any;
+    export { render_4 as render };
+}
+export namespace Loading {
+    export namespace parameters_4 {
+        export namespace controls_4 {
+            let include_4: any[];
+            export { include_4 as include };
+        }
+        export { controls_4 as controls };
+    }
+    export { parameters_4 as parameters };
+    export function render_5(): any;
+    export { render_5 as render };
+    export function play_3({ canvasElement }: {
+        canvasElement: any;
+    }): Promise<void>;
+    export { play_3 as play };
+}
+export namespace LightTheme {
+    export namespace parameters_5 {
+        export namespace controls_5 {
+            let include_5: any[];
+            export { include_5 as include };
+        }
+        export { controls_5 as controls };
+    }
+    export { parameters_5 as parameters };
+    export function render_6(): any;
+    export { render_6 as render };
+    export namespace globals {
+        let theme: string;
+        namespace backgrounds {
+            let value: string;
+        }
+    }
+}
+declare namespace meta {
+    export let title: string;
+    export { ConnectionPill as component };
+    export let tags: string[];
+    export let decorators: Function[];
+    export namespace argTypes {
+        export namespace status_1 {
+            let control: string;
+            let options: string[];
+        }
+        export { status_1 as status };
+        export namespace showNote_1 {
+            let control_1: string;
+            export { control_1 as control };
+        }
+        export { showNote_1 as showNote };
+    }
+}
+import { ConnectionPill } from './ConnectionState.jsx';

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

@@ -0,0 +1,97 @@
+/**
+ * @typedef {Object} ConsentAxis
+ * @property {React.ElementType} [icon]  lucide component for the row (rendered in a square chip)
+ * @property {string} key                the mono, lowercase axis label (e.g. "identity", "data access")
+ * @property {React.ReactNode} value      the chosen value — may contain user content (NOT lowercased)
+ * @property {React.ReactNode} [scope]    optional "who can see / what changes" note shown under the value
+ * @property {'reveal'|'open'|'restricted'} [tone]  colors the icon chip: reveal=amber, open=teal, restricted=clay
+ */
+/**
+ * ConsentSummary — the reusable axes block. an aligned grid of rows, each an icon
+ * chip + a mono key + the value (+ an optional scope note). this is the seed that
+ * already lived in the join dialog; here it is generalized so every governance
+ * dialog renders the same legible "here is what is at stake" panel.
+ *
+ * @param {Object} props
+ * @param {ConsentAxis[]} props.axes              the rows to render
+ * @param {string} [props.caption]                optional mono eyebrow above the rows
+ * @param {string} [props.className]              extra classes appended after .cns-summary
+ */
+export function ConsentSummary({ axes, caption, className, ...rest }: {
+    axes: ConsentAxis[];
+    caption?: string;
+    className?: string;
+}): any;
+/**
+ * ConsentDialog — a scrim + bordered modal that frames a governance decision.
+ * structure: head (mono lowercase title + close) / body (intro prose, a
+ * <ConsentSummary>, an optional "i understand and consent" checkbox, optional
+ * extra children rendered after the summary) / foot (cancel secondary + the
+ * primary confirm in amber). when `requireConsent`, the primary stays disabled
+ * until the checkbox is ticked, so the irreversible action never rides on a
+ * single reflexive click.
+ *
+ * controlled by `open` + `onCancel`. focus is trapped while open; Escape and a
+ * scrim click cancel; focus returns to whatever was focused when it opened (or
+ * `returnFocusRef` if given); background scroll is locked.
+ *
+ * @param {Object} props
+ * @param {boolean} props.open                       whether the dialog is mounted/visible
+ * @param {React.ReactNode} props.title              the mono lowercase head title (may embed a .cns-name)
+ * @param {React.ReactNode} [props.intro]            reading-prose lede above the summary
+ * @param {ConsentAxis[]} [props.axes]               axes for the embedded <ConsentSummary>
+ * @param {string} [props.summaryCaption]            eyebrow above the summary rows
+ * @param {React.ReactNode} [props.children]         extra content rendered after the summary (e.g. a retention choice)
+ * @param {string} [props.confirmLabel='confirm']    primary button label (mono lowercase)
+ * @param {React.ElementType} [props.confirmIcon]    lucide icon for the primary button
+ * @param {string} [props.cancelLabel='cancel']      secondary button label
+ * @param {() => void} props.onCancel                called on cancel / esc / scrim / close
+ * @param {() => void} props.onConfirm               called when the (enabled) primary is pressed
+ * @param {boolean} [props.requireConsent=true]      gate the primary behind the consent checkbox
+ * @param {React.ReactNode} [props.consentLabel]     the checkbox label (default "i understand and consent")
+ * @param {'primary'|'danger'} [props.tone='primary'] primary button treatment (danger for leave/retract)
+ * @param {boolean} [props.busy=false]               disables controls + shows the primary as busy
+ * @param {string} [props.labelId='cns-title']       id wiring aria-labelledby (unique it if two can co-exist)
+ * @param {React.RefObject<HTMLElement>} [props.returnFocusRef]  where to send focus on close
+ */
+export default function ConsentDialog({ open, title, intro, axes, summaryCaption, children, confirmLabel, confirmIcon: ConfirmIcon, cancelLabel, onCancel, onConfirm, requireConsent, consentLabel, tone, busy, labelId, returnFocusRef, }: {
+    open: boolean;
+    title: React.ReactNode;
+    intro?: React.ReactNode;
+    axes?: ConsentAxis[];
+    summaryCaption?: string;
+    children?: React.ReactNode;
+    confirmLabel?: string;
+    confirmIcon?: React.ElementType;
+    cancelLabel?: string;
+    onCancel: () => void;
+    onConfirm: () => void;
+    requireConsent?: boolean;
+    consentLabel?: React.ReactNode;
+    tone?: "primary" | "danger";
+    busy?: boolean;
+    labelId?: string;
+    returnFocusRef?: React.RefObject<HTMLElement>;
+}): any;
+export type ConsentAxis = {
+    /**
+     * lucide component for the row (rendered in a square chip)
+     */
+    icon?: React.ElementType;
+    /**
+     * the mono, lowercase axis label (e.g. "identity", "data access")
+     */
+    key: string;
+    /**
+     * the chosen value — may contain user content (NOT lowercased)
+     */
+    value: React.ReactNode;
+    /**
+     * optional "who can see / what changes" note shown under the value
+     */
+    scope?: React.ReactNode;
+    /**
+     * colors the icon chip: reveal=amber, open=teal, restricted=clay
+     */
+    tone?: "reveal" | "open" | "restricted";
+};

package/dist/lib/types/ConsentDialog.stories.d.ts

@@ -0,0 +1,61 @@
+export default meta;
+export namespace Join {
+    let name: string;
+    function render(): any;
+    function play({ canvasElement, step }: {
+        canvasElement: any;
+        step: any;
+    }): Promise<void>;
+}
+export namespace Contribute {
+    let name_1: string;
+    export { name_1 as name };
+    export function render_1(): any;
+    export { render_1 as render };
+    export function play_1({ canvasElement, step }: {
+        canvasElement: any;
+        step: any;
+    }): Promise<void>;
+    export { play_1 as play };
+}
+export namespace Leave {
+    let name_2: string;
+    export { name_2 as name };
+    export function render_2(): any;
+    export { render_2 as render };
+    export function play_2({ canvasElement, step }: {
+        canvasElement: any;
+        step: any;
+    }): Promise<void>;
+    export { play_2 as play };
+}
+export namespace Summary {
+    let name_3: string;
+    export { name_3 as name };
+    export function render_3(): any;
+    export { render_3 as render };
+}
+export namespace JoinStatic {
+    let name_4: string;
+    export { name_4 as name };
+    export function render_4(): any;
+    export { render_4 as render };
+}
+export namespace LeaveStatic {
+    let name_5: string;
+    export { name_5 as name };
+    export function render_5(): any;
+    export { render_5 as render };
+    export function play_3({ canvasElement }: {
+        canvasElement: any;
+    }): Promise<void>;
+    export { play_3 as play };
+}
+declare namespace meta {
+    export let title: string;
+    export { ConsentDialog as component };
+    export namespace parameters {
+        let layout: string;
+    }
+}
+import ConsentDialog from './ConsentDialog.jsx';

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

@@ -0,0 +1,116 @@
+/**
+ * a sortable + selectable data table. square, hairline, mono headers; both themes
+ * via tokens. sort + selection state/logic are powered by TanStack Table
+ * (@tanstack/react-table, headless) while this component still renders its own markup
+ * + token classes, so the look is unchanged and growth (filtering, pagination, column
+ * sizing/visibility) is a config away. sorting cycles none -> asc -> desc -> none on a
+ * sortable header (a real <button>, so it is keyboard-operable), exposes aria-sort on the
+ * <th>, and shows a lucide chevron indicator. selection reuses the existing .check-box control:
+ * a header checkbox selects/clears all (with an indeterminate middle state) and
+ * each row carries its own. selected rows get a subtle highlight.
+ *
+ * sort + selection are each independently controlled OR uncontrolled:
+ *  - sort: pass `sort` + `onSortChange` to control; otherwise `defaultSort` seeds it.
+ *  - selection: pass `selectedKeys` + `onSelectionChange` to control; otherwise
+ *    `defaultSelectedKeys` seeds it.
+ *
+ * @typedef {Object} DataTableColumn
+ * @property {string} key            object key this column reads from each row.
+ * @property {React.ReactNode} label header text (kept as passed; not forced-lowercase).
+ * @property {boolean} [sortable]    when true the header sorts; default false.
+ * @property {'left'|'right'|'center'} [align] cell alignment; 'right' also gets tabular nums. default 'left'.
+ * @property {string} [width] optional fixed column width (any css length, e.g. '12rem'); emits a <colgroup> entry so columns stay put as cell content changes.
+ * @property {(value: any, row: Object) => React.ReactNode} [render] custom cell renderer; falls back to row[key].
+ *
+ * @typedef {{ key: string, dir: 'asc'|'desc' } | null} DataTableSort
+ *
+ * @param {Object} props
+ * @param {DataTableColumn[]} props.columns                column definitions.
+ * @param {Object[]} props.rows                            row objects.
+ * @param {boolean} [props.selectable=false]              render the selection column.
+ * @param {(row: Object, index: number) => (string|number)} [props.rowKey] stable key per row; defaults to row.id ?? index.
+ * @param {DataTableSort} [props.defaultSort=null]        initial sort (uncontrolled).
+ * @param {DataTableSort} [props.sort]                    controlled sort.
+ * @param {(next: DataTableSort) => void} [props.onSortChange] called with the next sort state.
+ * @param {Array<string|number>} [props.defaultSelectedKeys=[]] initial selection (uncontrolled).
+ * @param {Array<string|number>} [props.selectedKeys]    controlled selection.
+ * @param {(keys: Array<string|number>) => void} [props.onSelectionChange] called with the next selection.
+ * @param {string} [props.caption]                       accessible <caption> for the table (visually present, mono/quiet).
+ * @param {string} [props.className]                      extra class on the scroll wrapper.
+ */
+export default function DataTable({ columns, rows, selectable, rowKey, defaultSort, sort: sortProp, onSortChange, defaultSelectedKeys, selectedKeys: selectedProp, onSelectionChange, caption, className, }: {
+    columns: DataTableColumn[];
+    rows: any[];
+    selectable?: boolean;
+    rowKey?: (row: any, index: number) => (string | number);
+    defaultSort?: DataTableSort;
+    sort?: DataTableSort;
+    onSortChange?: (next: DataTableSort) => void;
+    defaultSelectedKeys?: Array<string | number>;
+    selectedKeys?: Array<string | number>;
+    onSelectionChange?: (keys: Array<string | number>) => void;
+    caption?: string;
+    className?: string;
+}): any;
+/**
+ * a sortable + selectable data table. square, hairline, mono headers; both themes
+ * via tokens. sort + selection state/logic are powered by TanStack Table
+ * (@tanstack/react-table, headless) while this component still renders its own markup
+ * + token classes, so the look is unchanged and growth (filtering, pagination, column
+ * sizing/visibility) is a config away. sorting cycles none -> asc -> desc -> none on a
+ * sortable header (a real <button>, so it is keyboard-operable), exposes aria-sort on the
+ * <th>, and shows a lucide chevron indicator. selection reuses the existing .check-box control:
+ * a header checkbox selects/clears all (with an indeterminate middle state) and
+ * each row carries its own. selected rows get a subtle highlight.
+ *
+ * sort + selection are each independently controlled OR uncontrolled:
+ *  - sort: pass `sort` + `onSortChange` to control; otherwise `defaultSort` seeds it.
+ *  - selection: pass `selectedKeys` + `onSelectionChange` to control; otherwise
+ *    `defaultSelectedKeys` seeds it.
+ */
+export type DataTableColumn = {
+    /**
+     * object key this column reads from each row.
+     */
+    key: string;
+    /**
+     * header text (kept as passed; not forced-lowercase).
+     */
+    label: React.ReactNode;
+    /**
+     * when true the header sorts; default false.
+     */
+    sortable?: boolean;
+    /**
+     * cell alignment; 'right' also gets tabular nums. default 'left'.
+     */
+    align?: "left" | "right" | "center";
+    /**
+     * optional fixed column width (any css length, e.g. '12rem'); emits a <colgroup> entry so columns stay put as cell content changes.
+     */
+    width?: string;
+    /**
+     * custom cell renderer; falls back to row[key].
+     */
+    render?: (value: any, row: any) => React.ReactNode;
+};
+/**
+ * a sortable + selectable data table. square, hairline, mono headers; both themes
+ * via tokens. sort + selection state/logic are powered by TanStack Table
+ * (@tanstack/react-table, headless) while this component still renders its own markup
+ * + token classes, so the look is unchanged and growth (filtering, pagination, column
+ * sizing/visibility) is a config away. sorting cycles none -> asc -> desc -> none on a
+ * sortable header (a real <button>, so it is keyboard-operable), exposes aria-sort on the
+ * <th>, and shows a lucide chevron indicator. selection reuses the existing .check-box control:
+ * a header checkbox selects/clears all (with an indeterminate middle state) and
+ * each row carries its own. selected rows get a subtle highlight.
+ *
+ * sort + selection are each independently controlled OR uncontrolled:
+ *  - sort: pass `sort` + `onSortChange` to control; otherwise `defaultSort` seeds it.
+ *  - selection: pass `selectedKeys` + `onSelectionChange` to control; otherwise
+ *    `defaultSelectedKeys` seeds it.
+ */
+export type DataTableSort = {
+    key: string;
+    dir: "asc" | "desc";
+} | null;