@peasant-labs/fairtrade 0.0.1 → 0.0.2

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

@@ -0,0 +1,132 @@
+/**
+ * @typedef {Object} CheckboxProps
+ * @property {boolean} [checked]        controlled checked state (pair with onChange)
+ * @property {boolean} [defaultChecked] initial state for uncontrolled use (default false)
+ * @property {(checked: boolean, event: import('react').ChangeEvent<HTMLInputElement>) => void} [onChange]
+ * @property {boolean} [disabled]       native disabled attribute (default false)
+ * @property {import('react').ReactNode} [children] label text (rendered as passed, not lowercased)
+ */
+/**
+ * A single checkbox: <label class="check"> wrapping the styled <input type="checkbox" class="check-box">.
+ * @param {CheckboxProps & import('react').InputHTMLAttributes<HTMLInputElement>} props
+ */
+export default function Checkbox({ checked, defaultChecked, onChange, disabled, children, ...rest }: CheckboxProps & any): any;
+/**
+ * @typedef {Object} RadioProps
+ * @property {string} name              shared group name; radios must come in groups of >=2 so any one
+ *                                      can be deselected by picking another. for a lone binary choice
+ *                                      use Checkbox or Switch, never a single standalone Radio.
+ * @property {string} [value]           the value submitted / matched when this radio is selected
+ * @property {boolean} [checked]        controlled checked state (pair with onChange)
+ * @property {boolean} [defaultChecked] initial state for uncontrolled use (default false)
+ * @property {(event: import('react').ChangeEvent<HTMLInputElement>) => void} [onChange]
+ * @property {boolean} [disabled]       native disabled attribute (default false)
+ * @property {import('react').ReactNode} [children] label text (rendered as passed, not lowercased)
+ */
+/**
+ * A single radio: <label class="is-radio"> wrapping the styled <input type="radio" class="is-radio-dot">.
+ * Always render via RadioGroup (or at least two sibling radios sharing `name`) so a selection can be
+ * changed; a lone radio cannot be deselected, which is an accessibility anti-pattern. For a single
+ * binary choice use Checkbox or Switch instead.
+ * @param {RadioProps & import('react').InputHTMLAttributes<HTMLInputElement>} props
+ */
+export function Radio({ name, value, checked, defaultChecked, onChange, disabled, children, ...rest }: RadioProps & any): any;
+/**
+ * @typedef {Object} RadioOption
+ * @property {string} value
+ * @property {import('react').ReactNode} label
+ * @property {boolean} [disabled]
+ */
+/**
+ * @typedef {Object} RadioGroupProps
+ * @property {string} name              shared name for every radio in the group (required for single-select)
+ * @property {string} [value]          controlled selected value (pair with onChange)
+ * @property {string} [defaultValue]   initial selected value for uncontrolled use
+ * @property {(value: string, event: import('react').ChangeEvent<HTMLInputElement>) => void} [onChange]
+ * @property {RadioOption[]} options    the choices to render
+ * @property {string} ariaLabel        accessible name for the role=radiogroup container; required for
+ *                                     an accessible group (a radiogroup with no name is an a11y failure)
+ */
+/**
+ * A group of radios: <div class="is-radios" role="radiogroup"> of <label class="is-radio"> rows.
+ * Only one option is selectable because every input shares `name`.
+ * @param {RadioGroupProps & import('react').HTMLAttributes<HTMLDivElement>} props
+ */
+export function RadioGroup({ name, value, defaultValue, onChange, options, ariaLabel, ...rest }: RadioGroupProps & any): any;
+export type CheckboxProps = {
+    /**
+     * controlled checked state (pair with onChange)
+     */
+    checked?: boolean;
+    /**
+     * initial state for uncontrolled use (default false)
+     */
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean, event: any) => void;
+    /**
+     * native disabled attribute (default false)
+     */
+    disabled?: boolean;
+    /**
+     * label text (rendered as passed, not lowercased)
+     */
+    children?: any;
+};
+export type RadioProps = {
+    /**
+     * shared group name; radios must come in groups of >=2 so any one
+     * can be deselected by picking another. for a lone binary choice
+     * use Checkbox or Switch, never a single standalone Radio.
+     */
+    name: string;
+    /**
+     * the value submitted / matched when this radio is selected
+     */
+    value?: string;
+    /**
+     * controlled checked state (pair with onChange)
+     */
+    checked?: boolean;
+    /**
+     * initial state for uncontrolled use (default false)
+     */
+    defaultChecked?: boolean;
+    onChange?: (event: any) => void;
+    /**
+     * native disabled attribute (default false)
+     */
+    disabled?: boolean;
+    /**
+     * label text (rendered as passed, not lowercased)
+     */
+    children?: any;
+};
+export type RadioOption = {
+    value: string;
+    label: any;
+    disabled?: boolean;
+};
+export type RadioGroupProps = {
+    /**
+     * shared name for every radio in the group (required for single-select)
+     */
+    name: string;
+    /**
+     * controlled selected value (pair with onChange)
+     */
+    value?: string;
+    /**
+     * initial selected value for uncontrolled use
+     */
+    defaultValue?: string;
+    onChange?: (value: string, event: any) => void;
+    /**
+     * the choices to render
+     */
+    options: RadioOption[];
+    /**
+     * accessible name for the role=radiogroup container; required for
+     * an accessible group (a radiogroup with no name is an a11y failure)
+     */
+    ariaLabel: string;
+};

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

@@ -0,0 +1,85 @@
+/**
+ * @typedef {'ok'|'warn'|'err'} ChipTone
+ * @typedef {'sm'} ChipSize
+ */
+/**
+ * a static chip: an icon names the thing, a short label confirms it, color reinforces. wraps
+ * `<span class="chip">` with the parametric tone / size modifiers and an optional real x-button.
+ * @param {object} props
+ * @param {ChipTone} [props.tone] - semantic tone -> .chip-ok / .chip-warn / .chip-err (default: none)
+ * @param {ChipSize} [props.size] - 'sm' -> .chip-sm dense box (default: none)
+ * @param {string} [props.brand] - a provider/company name (claude, gemini, openai, cursor, opencode, or an alias).
+ *        When the chip names a company, pass this instead of `icon`: it leads with the real brand mark, never a generic glyph. (ignored when not resolvable)
+ * @param {React.ElementType} [props.icon] - leading lucide icon component ref (e.g. icon={Hash}) (ignored when `brand` is set)
+ * @param {boolean} [props.chrome=false] - mark this as a ui-chrome chip -> lowercases the label. Leave off for user content (ids, names, data values).
+ * @param {boolean} [props.removable=false] - render a real .chipx-x button with an X icon
+ * @param {() => void} [props.onRemove] - called when the x-button is clicked
+ * @param {string} [props.removeLabel] - aria-label for the x-button (default: `remove ${children}`; effectively required when children is not a plain string)
+ * @param {string} [props.className] - extra classes appended after the chip classes
+ * @param {React.ReactNode} props.children - the chip label / content (not force-lowercased unless chrome)
+ */
+export default function Chip({ tone, size, brand, icon: Icon, chrome, removable, onRemove, removeLabel, className, children, ...rest }: {
+    tone?: ChipTone;
+    size?: ChipSize;
+    brand?: string;
+    icon?: React.ElementType;
+    chrome?: boolean;
+    removable?: boolean;
+    onRemove?: () => void;
+    removeLabel?: string;
+    className?: string;
+    children: React.ReactNode;
+}): any;
+/**
+ * a filter / toggle chip: a real `<button class="chip chip-toggle" aria-pressed>`. selected shows a
+ * leading check (.chipx-tick, revealed by css) and an amber fill; the css carries the rest. supports
+ * controlled (pressed + onChange) and uncontrolled (defaultPressed) use.
+ * @param {object} props
+ * @param {boolean} [props.pressed] - controlled pressed state
+ * @param {boolean} [props.defaultPressed=false] - initial pressed state when uncontrolled
+ * @param {(next: boolean) => void} [props.onChange] - called with the next pressed state on click
+ * @param {string} [props.brand] - a provider/company name; leads with the real brand mark when NOT pressed (ignored when `icon` is wanted instead)
+ * @param {React.ElementType} [props.icon] - leading icon shown when NOT pressed (e.g. icon={Filter}) (ignored when `brand` is set)
+ * @param {string} [props.className] - extra classes appended after the chip classes
+ * @param {React.ReactNode} props.children - the toggle label (not force-lowercased)
+ */
+export function FilterChip({ pressed, defaultPressed, onChange, brand, icon: Icon, className, children, ...rest }: {
+    pressed?: boolean;
+    defaultPressed?: boolean;
+    onChange?: (next: boolean) => void;
+    brand?: string;
+    icon?: React.ElementType;
+    className?: string;
+    children: React.ReactNode;
+}): any;
+/**
+ * a status dot ALWAYS paired with a label, so status never rides on color alone. renders the small
+ * filled .chipx-dot square (tinted via the --c color var) followed by the required label text.
+ * by default it ships inside a `.chip` chassis to match the specimen; pass bare to drop the wrapper.
+ * @param {object} props
+ * @param {string} props.label - the status word (required; names the state) — not force-lowercased
+ * @param {string} [props.color] - css color for the dot, written to style="--c:..." (default: token fallback)
+ * @param {boolean} [props.bare=false] - omit the surrounding .chip wrapper, render dot + label only
+ * @param {string} [props.className] - extra classes appended after the chip class (ignored when bare)
+ */
+export function StatusDot({ label, color, bare, className, ...rest }: {
+    label: string;
+    color?: string;
+    bare?: boolean;
+    className?: string;
+}): any;
+/**
+ * a numeric notification count: a trailing pill of tabular digits (.chipx-count). neutral by default;
+ * .unread flips it to the scarce amber. tnum keeps digits tabular.
+ * @param {object} props
+ * @param {number|string} props.count - the value to display
+ * @param {boolean} [props.unread=false] - amber unread treatment -> .unread
+ * @param {string} [props.className] - extra classes appended after the count classes
+ */
+export function CountBadge({ count, unread, className, ...rest }: {
+    count: number | string;
+    unread?: boolean;
+    className?: string;
+}): any;
+export type ChipTone = "ok" | "warn" | "err";
+export type ChipSize = "sm";

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

@@ -0,0 +1,68 @@
+/**
+ * CommandBlock — a square `$ command` block: a mono command line with a leading dim `$`, and a copy
+ * button that flips to an olive check + the word "copied" for ~1.5s.
+ *
+ * @param {object} props
+ * @param {string} props.command - the literal shell command (case preserved — never lowercased).
+ * @param {string} [props.label] - an accessible name for the copy button; defaults to the command.
+ * @param {string} [props.className] - extra classes appended to the root.
+ */
+export function CommandBlock({ command, label, className, ...rest }: {
+    command: string;
+    label?: string;
+    className?: string;
+}): any;
+/**
+ * @typedef {object} CliStep
+ * @property {string} title - the step heading (e.g. "install"). Chrome — rendered lowercase by CSS.
+ * @property {string} [body] - optional prose explaining the step (body font, case preserved).
+ * @property {string} [command] - optional shell command for the step, rendered as a CommandBlock.
+ */
+/**
+ * CliSteps — a numbered step list: each step is a square amber-tinted number marker + a title + an
+ * optional body + an optional CommandBlock, with a connector line running between the markers.
+ *
+ * @param {object} props
+ * @param {CliStep[]} props.steps - the steps, in order; numbered from 1.
+ * @param {string} [props.label='getting started'] - accessible name for the list (lowercase chrome).
+ * @param {string} [props.className] - extra classes appended to the root.
+ */
+export function CliSteps({ steps, label, className, ...rest }: {
+    steps: CliStep[];
+    label?: string;
+    className?: string;
+}): any;
+/**
+ * GettingStarted — a dismissible card wrapping <CliSteps>: a header (title + close button) over the
+ * step list. Dismissing persists "dismissed" to localStorage under `storageKey`, so the card stays
+ * gone across reloads; when no key is given it dismisses for the session only.
+ *
+ * @param {object} props
+ * @param {string} [props.title='getting started'] - the card heading (lowercase chrome).
+ * @param {CliStep[]} props.steps - the onboarding steps, passed through to CliSteps.
+ * @param {string} [props.storageKey] - localStorage key the dismissed flag persists under.
+ * @param {() => void} [props.onDismiss] - called after the card is dismissed.
+ * @param {string} [props.className] - extra classes appended to the root.
+ */
+export function GettingStarted({ title, steps, storageKey, onDismiss, className, ...rest }: {
+    title?: string;
+    steps: CliStep[];
+    storageKey?: string;
+    onDismiss?: () => void;
+    className?: string;
+}): any;
+export default CliSteps;
+export type CliStep = {
+    /**
+     * - the step heading (e.g. "install"). Chrome — rendered lowercase by CSS.
+     */
+    title: string;
+    /**
+     * - optional prose explaining the step (body font, case preserved).
+     */
+    body?: string;
+    /**
+     * - optional shell command for the step, rendered as a CommandBlock.
+     */
+    command?: string;
+};

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

@@ -0,0 +1,6 @@
+export default function CommandPalette({ open, onClose, onTheme, sections }: {
+    open: any;
+    onClose: any;
+    onTheme: any;
+    sections: any;
+}): any;

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/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/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/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;