@peasant-labs/fairtrade 0.0.60 → 0.0.62

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

@@ -0,0 +1,208 @@
+/**
+ * A host column.
+ *
+ * `id` is the host's closed-set member, so the table keys the column by `.wire`
+ * and never by a raw string. `render(row)` returns the cell content; the table
+ * owns only the cell and its alignment.
+ *
+ * @template Row
+ * @template {import('./closed-value.js').ClosedValue<string, string>} ColumnId
+ * @typedef {object} TranscriptLibraryColumn
+ * @property {ColumnId} id
+ * @property {string} label
+ * @property {import('./table/column-align.js').ColumnAlign} align
+ * @property {boolean} [numeric] pair counts and durations with tabular figures.
+ * @property {(row: Row) => import('react').ReactNode} render
+ */
+/**
+ * One composed saved view: `groupBy` from the URL and `visibleColumns`/`collapsed`
+ * from the device. The host composes it; the table receives it and reports
+ * changes back, never reading a URL or storage itself.
+ *
+ * `visibleColumns` holds the known column members the table shows; the first
+ * declared column is the row identity and always shows. An unknown member is
+ * dropped when the view is reported back, so the host can rewrite its stored
+ * value. `collapsed` lists the qualified group ids the reader closed; an empty
+ * list opens every group. The list is page-independent: a collapse recorded on
+ * one page is the same qualified id on every page, so it never closes an
+ * unrelated group. The host composes both fields from the device and clears
+ * `collapsed` when `groupBy` changes; the table reports it unchanged.
+ *
+ * @template {import('./closed-value.js').ClosedValue<string, string>} GroupBy
+ * @template {import('./closed-value.js').ClosedValue<string, string>} ColumnId
+ * @typedef {object} SavedView
+ * @property {GroupBy} groupBy
+ * @property {readonly ColumnId[]} visibleColumns
+ * @property {readonly string[]} collapsed
+ */
+/**
+ * A host offset page. `index` is the 1-based page the server returns (`page` on
+ * the wire), `size` is a schema `PageSize` member, and `total` counts
+ * transcripts, not rendered rows. `null` means the host renders a complete list:
+ * the table hides the pager and renders every row.
+ *
+ * @typedef {object} TranscriptLibraryPage
+ * @property {number} index
+ * @property {import('@peasant-labs/schema').PageSize} size
+ * @property {number} total
+ */
+/**
+ * @template Row
+ * @template {import('./closed-value.js').ClosedValue<string, string>} GroupBy
+ * @template {import('./closed-value.js').ClosedValue<string, string>} ColumnId
+ * @typedef {object} TranscriptLibraryTableProps
+ * @property {string} caption
+ * @property {readonly Row[]} rows
+ * @property {(row: Row) => string} rowKey required: the host supplies a stable key; the table never derives one.
+ * @property {readonly TranscriptLibraryColumn<Row, ColumnId>[]} columns every host column, in declaration order; the first column is the row identity and always shows.
+ * @property {GroupBy} groupBy the host default grouping, used when no saved view names a known member.
+ * @property {readonly GroupBy[]} [groupByOptions] the grouping members the picker offers; defaults to `[groupBy]`.
+ * @property {(row: Row) => readonly string[]} groupKeys bare keys, such as [row.projectHash].
+ * @property {(groupId: string) => string} groupLabel receives `${groupBy.wire}:${key}`.
+ * @property {readonly string[] | null} nextGroupKeys bare keys from `page.nextItems`, or null.
+ * @property {readonly string[] | null} continuedGroupKeys bare keys from the previous page, or null.
+ * @property {TranscriptLibraryPage | null} page
+ * @property {SavedView<GroupBy, ColumnId> | null} [viewState] the host's composed grouping, columns, and collapsed groups; a known saved view wins over the host default.
+ * @property {(view: SavedView<GroupBy, ColumnId>) => void} [onViewStateChange]
+ * @property {(index: number) => void} [onPageChange]
+ * @property {(size: import('@peasant-labs/schema').PageSize) => void} [onPageSizeChange]
+ * @property {import('react').ReactNode} [emptyState]
+ */
+/**
+ * The resolved saved view the table renders: the host's saved view read against
+ * the columns and grouping members this table actually knows. An unknown member
+ * falls back to the host default rather than rendering an empty or broken view.
+ *
+ * @template {import('./closed-value.js').ClosedValue<string, string>} GroupBy
+ * @template {import('./closed-value.js').ClosedValue<string, string>} ColumnId
+ * @typedef {object} ResolvedSavedView
+ * @property {GroupBy} groupBy
+ * @property {readonly GroupBy[]} groupByOptions
+ * @property {readonly ColumnId[]} visibleColumns
+ * @property {readonly string[]} collapsed the qualified group ids the reader closed.
+ */
+/**
+ * The canonical transcript library table: one real table with a caption, host
+ * columns, group header rows, a compact continuation row for a group that began
+ * on an earlier page, a numbered pager, and an end-of-page marker for a group
+ * that continues.
+ *
+ * The table is controlled. It renders the rows, page, and view it is given and
+ * reports changes; it holds no storage, reads no URL, and never resets a page.
+ * A saved view (when given) supplies the grouping, the visible columns, and the
+ * collapsed groups; without one every column shows, every group is open, and the two
+ * pickers are absent because they would have nothing to report to.
+ *
+ * @template Row
+ * @template {import('./closed-value.js').ClosedValue<string, string>} GroupBy
+ * @template {import('./closed-value.js').ClosedValue<string, string>} ColumnId
+ * @param {TranscriptLibraryTableProps<Row, GroupBy, ColumnId>} props
+ */
+export function TranscriptLibraryTable<Row, GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>>({ caption, rows, rowKey, columns, groupBy, groupByOptions, groupKeys, groupLabel, nextGroupKeys, continuedGroupKeys, page, viewState, onViewStateChange, emptyState, onPageChange, onPageSizeChange, }: TranscriptLibraryTableProps<Row, GroupBy, ColumnId>): import("react").JSX.Element;
+/**
+ * A host column.
+ *
+ * `id` is the host's closed-set member, so the table keys the column by `.wire`
+ * and never by a raw string. `render(row)` returns the cell content; the table
+ * owns only the cell and its alignment.
+ */
+export type TranscriptLibraryColumn<Row, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = {
+    id: ColumnId;
+    label: string;
+    align: import("./table/column-align.js").ColumnAlign;
+    /**
+     * pair counts and durations with tabular figures.
+     */
+    numeric?: boolean;
+    render: (row: Row) => import("react").ReactNode;
+};
+/**
+ * One composed saved view: `groupBy` from the URL and `visibleColumns`/`collapsed`
+ * from the device. The host composes it; the table receives it and reports
+ * changes back, never reading a URL or storage itself.
+ *
+ * `visibleColumns` holds the known column members the table shows; the first
+ * declared column is the row identity and always shows. An unknown member is
+ * dropped when the view is reported back, so the host can rewrite its stored
+ * value. `collapsed` lists the qualified group ids the reader closed; an empty
+ * list opens every group. The list is page-independent: a collapse recorded on
+ * one page is the same qualified id on every page, so it never closes an
+ * unrelated group. The host composes both fields from the device and clears
+ * `collapsed` when `groupBy` changes; the table reports it unchanged.
+ */
+export type SavedView<GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = {
+    groupBy: GroupBy;
+    visibleColumns: readonly ColumnId[];
+    collapsed: readonly string[];
+};
+/**
+ * A host offset page. `index` is the 1-based page the server returns (`page` on
+ * the wire), `size` is a schema `PageSize` member, and `total` counts
+ * transcripts, not rendered rows. `null` means the host renders a complete list:
+ * the table hides the pager and renders every row.
+ */
+export type TranscriptLibraryPage = {
+    index: number;
+    size: import("@peasant-labs/schema").PageSize;
+    total: number;
+};
+export type TranscriptLibraryTableProps<Row, GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = {
+    caption: string;
+    rows: readonly Row[];
+    /**
+     * required: the host supplies a stable key; the table never derives one.
+     */
+    rowKey: (row: Row) => string;
+    /**
+     * every host column, in declaration order; the first column is the row identity and always shows.
+     */
+    columns: readonly TranscriptLibraryColumn<Row, ColumnId>[];
+    /**
+     * the host default grouping, used when no saved view names a known member.
+     */
+    groupBy: GroupBy;
+    /**
+     * the grouping members the picker offers; defaults to `[groupBy]`.
+     */
+    groupByOptions?: readonly GroupBy[];
+    /**
+     * bare keys, such as [row.projectHash].
+     */
+    groupKeys: (row: Row) => readonly string[];
+    /**
+     * receives `${groupBy.wire}:${key}`.
+     */
+    groupLabel: (groupId: string) => string;
+    /**
+     * bare keys from `page.nextItems`, or null.
+     */
+    nextGroupKeys: readonly string[] | null;
+    /**
+     * bare keys from the previous page, or null.
+     */
+    continuedGroupKeys: readonly string[] | null;
+    page: TranscriptLibraryPage | null;
+    /**
+     * the host's composed grouping, columns, and collapsed groups; a known saved view wins over the host default.
+     */
+    viewState?: SavedView<GroupBy, ColumnId> | null;
+    onViewStateChange?: (view: SavedView<GroupBy, ColumnId>) => void;
+    onPageChange?: (index: number) => void;
+    onPageSizeChange?: (size: import("@peasant-labs/schema").PageSize) => void;
+    emptyState?: import("react").ReactNode;
+};
+/**
+ * The resolved saved view the table renders: the host's saved view read against
+ * the columns and grouping members this table actually knows. An unknown member
+ * falls back to the host default rather than rendering an empty or broken view.
+ */
+export type ResolvedSavedView<GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = {
+    groupBy: GroupBy;
+    groupByOptions: readonly GroupBy[];
+    visibleColumns: readonly ColumnId[];
+    /**
+     * the qualified group ids the reader closed.
+     */
+    collapsed: readonly string[];
+};
+export { groupPageRows, groupKeysFor } from "./groupPageRows.js";

package/dist/lib/types/closed-value.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A closed value: a frozen object that carries its wire value, the label a
+ * surface shows for it, and the conversion hooks.
+ *
+ * - `wire` is the exact value persisted, compared, and sent on the wire.
+ * - `label` is the human-readable text shown for the member.
+ * - `String()` is the Go-style explicit text conversion; it returns `String(wire)`.
+ * - `toString()` is the text conversion used by `String(value)` and template literals.
+ * - `toJSON()` is the persistence conversion used by `JSON.stringify`; it returns `wire`.
+ *
+ * @template {string | number} W - the exact value persisted, compared, and sent on the wire.
+ * @template {string} L - the human-readable label shown for the member.
+ * @typedef {{
+ *   readonly wire: W,
+ *   readonly label: L,
+ *   String: () => string,
+ *   toString: () => string,
+ *   toJSON: () => W,
+ * }} ClosedValue
+ */
+/**
+ * Create one frozen closed-set member.
+ *
+ * @template {string | number} W
+ * @template {string} L
+ * @param {W} wire - the exact value persisted, compared, and sent on the wire.
+ * @param {L} label - the human-readable text shown for the member.
+ * @returns {ClosedValue<W, L>} a new frozen member for this `(wire, label)` pair.
+ */
+export function closed<W extends string | number, L extends string>(wire: W, label: L): ClosedValue<W, L>;
+/**
+ * A closed value: a frozen object that carries its wire value, the label a
+ * surface shows for it, and the conversion hooks.
+ *
+ * - `wire` is the exact value persisted, compared, and sent on the wire.
+ * - `label` is the human-readable text shown for the member.
+ * - `String()` is the Go-style explicit text conversion; it returns `String(wire)`.
+ * - `toString()` is the text conversion used by `String(value)` and template literals.
+ * - `toJSON()` is the persistence conversion used by `JSON.stringify`; it returns `wire`.
+ */
+export type ClosedValue<W extends string | number, L extends string> = {
+    readonly wire: W;
+    readonly label: L;
+    String: () => string;
+    toString: () => string;
+    toJSON: () => W;
+};

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

@@ -0,0 +1,56 @@
+/**
+ * One rendered group.
+ *
+ * - `id` is `${groupBy.wire}:${key}`, or `''` for rows that name no group.
+ * - `label` is what `groupLabel(id)` returned; `''` for the ungrouped bucket.
+ * - `continued` means this group began on the previous page.
+ * - `continues` means this group has rows on the next page.
+ *
+ * @template Row
+ * @typedef {object} TranscriptLibraryGroup
+ * @property {string} id
+ * @property {string} label
+ * @property {readonly Row[]} rows
+ * @property {boolean} continued
+ * @property {boolean} continues
+ */
+/**
+ * Group one page of rows.
+ *
+ * @template Row
+ * @template {import('./closed-value.js').ClosedValue<string, string>} GroupBy
+ * @param {readonly Row[]} rows - the host's page rows, in display order.
+ * @param {GroupBy} groupBy - the host's grouping member; only `.wire` is read.
+ * @param {(row: Row) => readonly string[]} groupKeys - bare group keys for a row.
+ * @param {(groupId: string) => string} groupLabel - label for a qualified group id.
+ * @param {readonly string[] | null} nextGroupKeys - bare keys of `page.nextItems`, or null.
+ * @param {readonly string[] | null} [continuedGroupKeys] - bare keys of the previous page, or null.
+ * @returns {readonly TranscriptLibraryGroup<Row>[]}
+ */
+export function groupPageRows<Row, GroupBy extends import("./closed-value.js").ClosedValue<string, string>>(rows: readonly Row[], groupBy: GroupBy, groupKeys: (row: Row) => readonly string[], groupLabel: (groupId: string) => string, nextGroupKeys: readonly string[] | null, continuedGroupKeys?: readonly string[] | null): readonly TranscriptLibraryGroup<Row>[];
+/**
+ * The union of every row's bare group keys, de-duplicated in first-appearance
+ * order. A host uses it for `nextGroupKeys` (over `page.nextItems`) and for
+ * `continuedGroupKeys` (over the previous page it holds).
+ *
+ * @template Row
+ * @param {readonly Row[]} rows
+ * @param {(row: Row) => readonly string[]} groupKeys
+ * @returns {readonly string[]}
+ */
+export function groupKeysFor<Row>(rows: readonly Row[], groupKeys: (row: Row) => readonly string[]): readonly string[];
+/**
+ * One rendered group.
+ *
+ * - `id` is `${groupBy.wire}:${key}`, or `''` for rows that name no group.
+ * - `label` is what `groupLabel(id)` returned; `''` for the ungrouped bucket.
+ * - `continued` means this group began on the previous page.
+ * - `continues` means this group has rows on the next page.
+ */
+export type TranscriptLibraryGroup<Row> = {
+    id: string;
+    label: string;
+    rows: readonly Row[];
+    continued: boolean;
+    continues: boolean;
+};

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

@@ -30,6 +30,11 @@ export { default as RepoPicker } from "./RepoPicker.jsx";
 export { default as VillageObservations } from "./VillageObservations.jsx";
 export * from "./transcript/index.js";
 export * from "./transcript/graph/index.js";
+export type SavedView<GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = import("./TranscriptLibraryTable.jsx").SavedView<GroupBy, ColumnId>;
+export type TranscriptLibraryColumn<Row, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = import("./TranscriptLibraryTable.jsx").TranscriptLibraryColumn<Row, ColumnId>;
+export type TranscriptLibraryTableProps<Row, GroupBy extends import("./closed-value.js").ClosedValue<string, string>, ColumnId extends import("./closed-value.js").ClosedValue<string, string>> = import("./TranscriptLibraryTable.jsx").TranscriptLibraryTableProps<Row, GroupBy, ColumnId>;
+export type TranscriptLibraryPage = import("./TranscriptLibraryTable.jsx").TranscriptLibraryPage;
+export type TranscriptLibraryGroup<Row> = import("./groupPageRows.js").TranscriptLibraryGroup<Row>;
 export type TimelineNavigationAction = import("./graph/timelineNavigation.js").TimelineNavigationAction;
 export type AppSidebarProps = import("./AppSidebar.jsx").AppSidebarProps;
 export type AppSidebarLayoutProps = import("./AppSidebar.jsx").AppSidebarLayoutProps;
@@ -59,6 +64,8 @@ export { formatCount, formatInteger, formatCost, formatDecimal, MISSING_NUMBER }
 export { providerAccent, providerDisplayName } from "./provider-policy.js";
 export { Skeleton, Progress, Spinner, Toast, FeedbackPanel } from "./Feedback.jsx";
 export { DataTableToolbar, DataTablePaginationControls } from "./DataTableControls.jsx";
+export { TranscriptLibraryTable, groupPageRows, groupKeysFor } from "./TranscriptLibraryTable.jsx";
+export { ColumnAlign, ALL_COLUMN_ALIGNS, parseColumnAlign } from "./table/column-align.js";
 export { default as HelperGroup, HelperGroupListItem, HelperThreadRow, useHelperSelection, helperOwnerState, helperSelectionIds, helperOwnerToggle, helperMemberToggle, HELPER_OWNER_STATE } from "./HelperGroup.jsx";
 export { default as Timeline, TimelineItem, ToolCall, ThinkingBlock } from "./Timeline.jsx";
 export { default as ToastProvider, useToast } from "./ToastHost.jsx";

package/dist/lib/types/table/align-class.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {string} base the cell or header class.
+ * @param {'left' | 'right' | 'center' | 'decimal'} align
+ * @returns {string}
+ */
+export function alignClass(base: string, align: "left" | "right" | "center" | "decimal"): string;

package/dist/lib/types/table/column-align.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resolve a persisted or host-supplied alignment to its member.
+ *
+ * Accepts a member (returned unchanged) or its wire value as a string. A label is
+ * not accepted: labels are chrome and may change, while the wire value is the
+ * stable identity. An unknown value throws rather than silently defaulting,
+ * because a silent default hides a host that drifted from this set.
+ *
+ * @param {unknown} raw - a `ColumnAlign` member or its wire value.
+ * @returns {ColumnAlign}
+ */
+export function parseColumnAlign(raw: unknown): ColumnAlign;
+/**
+ * The member type union; every value member is a `ColumnAlign`.
+ */
+export type ColumnAlign = (typeof ColumnAlignValues)[keyof typeof ColumnAlignValues];
+/**
+ * The alignment a host column declares.
+ *
+ * - `Start` is left-aligned in a left-to-right grid.
+ * - `End` is right-aligned; counts and durations pair it with `numeric`.
+ * - `Center` is centered.
+ * - `Decimal` right-aligns with tabular numbers. A decimal-point span is
+ *   `DataTable`'s own; this table does not export it.
+ */
+export const ColumnAlign: Readonly<{
+    Start: import("../closed-value.js").ClosedValue<"start", "start">;
+    End: import("../closed-value.js").ClosedValue<"end", "end">;
+    Center: import("../closed-value.js").ClosedValue<"center", "center">;
+    Decimal: import("../closed-value.js").ClosedValue<"decimal", "decimal">;
+}>;
+/**
+ * The member type union; every value member is a `ColumnAlign`.
+ * @typedef {(typeof ColumnAlignValues)[keyof typeof ColumnAlignValues]} ColumnAlign
+ */
+/** Every alignment member, in the order a surface lists them. */
+export const ALL_COLUMN_ALIGNS: readonly (import("../closed-value.js").ClosedValue<"start", "start"> | import("../closed-value.js").ClosedValue<"end", "end"> | import("../closed-value.js").ClosedValue<"center", "center"> | import("../closed-value.js").ClosedValue<"decimal", "decimal">)[];
+declare const ColumnAlignValues: Readonly<{
+    Start: import("../closed-value.js").ClosedValue<"start", "start">;
+    End: import("../closed-value.js").ClosedValue<"end", "end">;
+    Center: import("../closed-value.js").ClosedValue<"center", "center">;
+    Decimal: import("../closed-value.js").ClosedValue<"decimal", "decimal">;
+}>;
+export {};

package/dist/lib/types/table/library-pickers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The group-by picker. The trigger names the current grouping, and each offered
+ * member is a native radio, so the chosen row is announced as checked.
+ *
+ * @param {object} props
+ * @param {readonly { wire: string, label: string }[]} props.options the host's grouping members.
+ * @param {{ wire: string, label: string }} props.value the active grouping member.
+ * @param {(next: { wire: string, label: string }) => void} props.onChange receives the chosen member.
+ */
+export function GroupByPicker({ options, value, onChange }: {
+    options: readonly {
+        wire: string;
+        label: string;
+    }[];
+    value: {
+        wire: string;
+        label: string;
+    };
+    onChange: (next: {
+        wire: string;
+        label: string;
+    }) => void;
+}): import("react").JSX.Element;
+/**
+ * The column picker. The trigger names how many columns show, and every column is
+ * a native checkbox. The first declared column is the row identity and always
+ * shows, so its checkbox is checked and disabled; the label says why.
+ *
+ * @param {object} props
+ * @param {readonly { id: { wire: string }, label: string }[]} props.columns every host column, in declaration order.
+ * @param {readonly { wire: string }[]} props.visibleColumns the columns the saved view shows.
+ * @param {(column: { id: { wire: string }, label: string }, checked: boolean) => void} props.onChange receives the toggled column and whether it was checked before the change.
+ */
+export function ColumnPicker({ columns, visibleColumns, onChange }: {
+    columns: readonly {
+        id: {
+            wire: string;
+        };
+        label: string;
+    }[];
+    visibleColumns: readonly {
+        wire: string;
+    }[];
+    onChange: (column: {
+        id: {
+            wire: string;
+        };
+        label: string;
+    }, checked: boolean) => void;
+}): import("react").JSX.Element;

package/dist/lib/types/transcript/action-groups.d.ts

@@ -1,4 +1,8 @@
-/** Stable source user boundaries, followed by visibility projection. No hidden part is restored.
+/** Runs follow the source prose, not the filtered projection, so a hidden turn never moves a
+ * later action forward. Each prose turn starts its own run; a wordless turn appends to the
+ * current run; a user turn closes it; a system turn stays where it is and does not split it.
+ * A run without a renderable prose anchor keeps its work at the run's first visible work turn,
+ * and a run with no work draws no block. No hidden part is restored.
  * @param {import('./view-model.js').TurnVM[]} turns
  * @param {import('./view-model.js').TurnVM[]} visibleTurns
  */