@dcs-tech/ui 0.2.0 → 0.3.0

package/dist/types/shared-logic/src/ui/quickAddGrid.logic.d.ts

@@ -0,0 +1,183 @@
+export type QuickAddAxisMode = 'variant' | 'reference';
+export interface QuickAddAxis {
+    key: string;
+    mode: QuickAddAxisMode;
+}
+export type QuickAddHeaderBehavior = 'none' | 'copy' | 'split' | 'dependentSplit';
+export type QuickAddCellFormula = {
+    op: 'value';
+    key: string;
+} | {
+    op: 'number';
+    value: number;
+} | {
+    op: 'add';
+    args: QuickAddCellFormula[];
+} | {
+    op: 'mul';
+    args: QuickAddCellFormula[];
+};
+export type QuickAddTotalRule = {
+    mode: 'off';
+} | {
+    mode: 'sum';
+    formula?: QuickAddCellFormula;
+};
+export interface QuickAddFieldSpec {
+    key: string;
+    numeric?: boolean;
+    decimalScale?: number;
+    defaultValue?: unknown;
+    isSubmitKey?: boolean;
+    onHeader?: QuickAddHeaderBehavior;
+    dependsOn?: string;
+    totalRule?: QuickAddTotalRule;
+}
+export type QuickAddCombo = Record<string, string>;
+export type QuickAddCell = Record<string, unknown>;
+export type QuickAddCells = Record<string, QuickAddCell>;
+export declare function buildQuickAddSpecs(config: {
+    axes?: string[];
+    refaxes?: string[];
+    fields?: string[];
+    split?: string[];
+    fieldMeta?: Record<string, {
+        decimalScale?: number;
+        isSubmitKey?: boolean;
+        editable?: boolean;
+        totalRule?: QuickAddTotalRule;
+    }>;
+}): {
+    axes: QuickAddAxis[];
+    fields: QuickAddFieldSpec[];
+};
+export declare function comboKey(axes: QuickAddAxis[], combo: QuickAddCombo): string;
+export declare function variantComboKey(axes: QuickAddAxis[], combo: QuickAddCombo): string;
+export declare function buildVariantKeySet(axes: QuickAddAxis[], variants: Array<Record<string, unknown>>): Set<string>;
+export declare function isComboAvailable(combo: QuickAddCombo, params: {
+    axes: QuickAddAxis[];
+    variantKeys: Set<string>;
+    requireVariantMatch?: boolean;
+}): boolean;
+export declare function resolveVariant<T extends Record<string, unknown>>(combo: QuickAddCombo, params: {
+    axes: QuickAddAxis[];
+    variants: T[];
+    itemid?: string;
+    itemKey?: string;
+}): T | undefined;
+export declare function quickAddLayout(axes: QuickAddAxis[]): {
+    columnAxis?: QuickAddAxis;
+    rowAxis?: QuickAddAxis;
+    slicerAxes: QuickAddAxis[];
+};
+export declare function axisValues<T extends {
+    value: string;
+}>(params: {
+    axis: QuickAddAxis;
+    options: T[];
+    variants: Array<Record<string, unknown>>;
+    emptyOption: T;
+}): T[];
+export declare function orderValues(picked: string[], order: string[]): string[];
+export declare function planQuickEntry(params: {
+    axes: QuickAddAxis[];
+    picked: Record<string, string | undefined>;
+    variantKeys?: Set<string>;
+    requireVariantMatch?: boolean;
+}): {
+    key: string;
+    missingAxes: string[];
+    available: boolean;
+};
+export declare function selectionFromRows(params: {
+    rows: Array<Record<string, unknown>>;
+    axes: QuickAddAxis[];
+    isEmpty?: (row: Record<string, unknown>) => boolean;
+}): Record<string, string[]>;
+export declare function singleAnswerAxes<T extends {
+    value: string;
+}>(params: {
+    axes: QuickAddAxis[];
+    valuesByAxis: Record<string, T[] | undefined>;
+}): {
+    auto: Record<string, string>;
+    preset: Record<string, string>;
+};
+export declare function dropAxisValue(params: {
+    cells: QuickAddCells;
+    axes: QuickAddAxis[];
+    axisKey: string;
+    value: string;
+}): QuickAddCells;
+export declare function buildCombos(params: {
+    axes: QuickAddAxis[];
+    selected: Record<string, string[]>;
+    variantKeys?: Set<string>;
+    requireVariantMatch?: boolean;
+}): Array<{
+    key: string;
+    combo: QuickAddCombo;
+}>;
+export declare function buildCellDefaults(fields: QuickAddFieldSpec[]): QuickAddCell;
+export declare function clampScale(scale: unknown): number;
+export declare function roundToScale(value: number, scale: number): number;
+export declare function isNumericField(field: QuickAddFieldSpec): boolean;
+export declare function cellNumber(cell: QuickAddCell | undefined, key: string): number;
+export declare function parseHeaderValue(field: QuickAddFieldSpec, raw: unknown): number | string | null;
+export declare function distributeEvenly(totalUnits: number, count: number): number[];
+export declare function distributeByWeights(totalUnits: number, weights: number[]): number[];
+export declare function applyHeaderValue(params: {
+    cells: QuickAddCells;
+    targetKeys: string[];
+    fields: QuickAddFieldSpec[];
+    field: QuickAddFieldSpec;
+    rawValue: unknown;
+}): QuickAddCells;
+export declare function evaluateCellFormula(cell: QuickAddCell | undefined, formula: QuickAddCellFormula): number;
+export declare function scopeTotal(cells: QuickAddCells, keys: string[], field: QuickAddFieldSpec): number;
+export type QuickAddDuplicates = 'first' | 'last' | 'merge';
+export declare function prefillCellsFromRows(params: {
+    rows: Array<Record<string, unknown>>;
+    axes: QuickAddAxis[];
+    fields: QuickAddFieldSpec[];
+    allowedKeys?: Iterable<string>;
+    duplicates?: QuickAddDuplicates;
+    rowKeyMap?: Record<string, string>;
+}): QuickAddCells;
+export declare function buildSubmitCombos(params: {
+    cells: QuickAddCells;
+    axes: QuickAddAxis[];
+    fields: QuickAddFieldSpec[];
+    keys: string[];
+    valueOrder?: Record<string, string[]>;
+}): Array<{
+    key: string;
+    combo: QuickAddCombo;
+    values: Record<string, unknown>;
+}>;
+export type SingleEntryBy = 'item' | 'variant' | 'sku';
+export declare function singleEntryViolations(params: {
+    rows: Array<Record<string, unknown>>;
+    by: SingleEntryBy;
+    itemKey?: string;
+    variantKey?: string;
+    isBlank?: (row: Record<string, unknown>) => boolean;
+}): number[];
+export declare function planRowUpsert(params: {
+    submitted: Array<{
+        combo: QuickAddCombo;
+        values: Record<string, unknown>;
+    }>;
+    rows: Array<Record<string, unknown>>;
+    axes: QuickAddAxis[];
+}): {
+    update: Array<{
+        index: number;
+        values: Record<string, unknown>;
+    }>;
+    create: Array<{
+        combo: QuickAddCombo;
+        values: Record<string, unknown>;
+    }>;
+    remove: number[];
+};

package/dist/types/shared-logic/src/ui/select.logic.d.ts

@@ -10,20 +10,6 @@ export declare function buildSelectClassKeys(opts: SelectClassOpts): string[];
 export declare function normalizeSelectOptions(options: (string | number | SelectOption)[]): SelectOption[];
 export declare function sortSelectOptions(options: SelectOption[], sortConfig?: boolean | SortConfig): SelectOption[];
 export declare function filterSelectOptions(options: SelectOption[], searchTerm: string, searchConfig?: boolean | SearchConfig): SelectOption[];
-/**
- * Type-ahead for a closed or open Select: the index of the next option whose label
- * starts with `query`, searching forward from `fromIndex` and wrapping.
- *
- * Spec (FIELD_KEYBOARD_NAVIGATION.md §6.4): a printable key on a Select jumps to the
- * matching option. An operator entering sizes types `M`, not ↓↓↓. Starting AFTER
- * `fromIndex` is what makes a repeated letter cycle — `S`, `S` walks Small → S-Slim.
- *
- * Case-insensitive, disabled options skipped. Single-character cycling only: a
- * multi-key buffer ("me" typed quickly) needs a timer, and a timer-driven buffer is
- * exactly what throttles unpredictably in a background tab.
- *
- * @returns the matching index, or -1 when nothing matches.
- */
 export declare function findTypeaheadIndex(options: Array<{
     name: string | number;
     disabled?: boolean;

package/dist/types/shared-logic/src/ui/tableLayout.logic.d.ts

@@ -1,47 +1,13 @@
 import type { ColumnAlign, EditableTableColumnDefinition, ResolvedColumnLayout, ResolvedTableLayout } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Column layout, decided once and purely.
- *
- * The client editable table has no layout props at all, so every column in the
- * Program table renders at exactly 300px — a 2700px table in a 1542px
- * container, Qty as wide as Notes. This resolves each column's frame from its
- * props, and where a column names none, from a default for the kind of field it
- * holds. **Prop → default**, the same order `size` and `keyboard` resolve in.
- */
-/** What a column holds, as far as layout is concerned. */
 export type ColumnWidget = 'suggest' | 'select' | 'number' | 'derivedNumber' | 'date' | 'text' | 'derivedText' | 'toggle' | 'button' | 'other';
 interface ColumnDefault {
-    /** Present = fixed width. Absent = flexible, sharing the remaining space. */
     width?: number;
     minWidth: number;
     align: ColumnAlign;
 }
-/**
- * The defaults by widget. Tuned against a real production program table's columns:
- * an item name needs room to be read, a quantity does not.
- */
 export declare const COLUMN_LAYOUT_DEFAULTS: Readonly<Record<ColumnWidget, ColumnDefault>>;
 export declare function classifyColumn(column: EditableTableColumnDefinition<any>): ColumnWidget;
-/**
- * One column's frame.
- *
- * - An explicit `width` makes the column fixed, and a fixed column's floor IS its
- *   width — a `minWidth` beside a `width` has nothing left to decide.
- * - A **sticky** column is always fixed. Pinned columns stack by offset, and an
- *   offset can only be exact if every pinned width is known; a flexible pinned
- *   column would push the next one to the wrong place. Unsized, it pins at its
- *   floor.
- */
 export declare function resolveColumnLayout(column: EditableTableColumnDefinition<any>): ResolvedColumnLayout;
-/**
- * Every column's frame, plus the pinned-column offsets and the table's floor.
- *
- * Pinned columns stay pinned in the order they appear: left-pinned offsets
- * accumulate left to right, right-pinned offsets right to left. The innermost
- * pinned column on each side is its `stickyEdge`, which is where scrolling
- * content passes under and a divider belongs.
- */
 export declare function resolveTableLayout(columns: EditableTableColumnDefinition<any>[]): ResolvedTableLayout;
-/** A read-only cell renders text instead of a field — and the keyboard skips it. */
 export declare function isReadOnlyColumn(column: EditableTableColumnDefinition<any>): boolean;
 export {};

package/dist/types/shared-logic/src/ui/tableSummary.logic.d.ts

@@ -1,32 +1,13 @@
 import type { ColumnSummaryConfig, EditableTableColumnDefinition, ResolvedColumnTotal, ResolvedSummaryEntry, ResolvedSummaryGroup, SummaryAggregation, SummaryContext, SummaryFormat, TableSummaryConfig } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Totals and summaries, pure.
- *
- * A port of the client Table's `useTableSummary`
- * (`apps/web/client/src/Utils/CustomElements/Table/summary/useTableSummary.ts`) —
- * the same aggregation, the same `en-IN` formatting, the same id scheme for
- * column totals, the same "a group key the compute omitted is hidden" rule — so a
- * summary configured for a report table computes identically on an editable one.
- * Moved out of the hook because it makes no decision that needs React, and here
- * it can be asserted directly.
- *
- * One deliberate difference: the Table lists column totals among its summary
- * entries. The editable table renders them in a pinned footer row under their
- * columns instead, so they are returned separately — but they are still fed to
- * every item's `compute` as `resolved`, under the Table's ids.
- */
 export declare function formatSummaryValue(value: number, format?: SummaryFormat, decimals?: number, prefix?: string, suffix?: string, formatter?: (value: any) => string): string;
 export declare function aggregateValues(values: number[], type: SummaryAggregation): number;
-/** `summable: true` is shorthand for `summary: { type: 'sum' }`; an explicit `summary` wins. */
 export declare function columnSummaryConfig(column: EditableTableColumnDefinition<any>): ColumnSummaryConfig | undefined;
 export declare function computeColumnTotals<T>(columns: EditableTableColumnDefinition<T>[], rows: T[]): ResolvedColumnTotal[];
 export interface ResolvedTableSummary {
     columnTotals: ResolvedColumnTotal[];
-    /** Column totals keyed by column name — what a render-form summary and the footer row read. */
     totalsByColumn: Record<string, number>;
     entries: ResolvedSummaryEntry[];
     groups: ResolvedSummaryGroup[];
-    /** Every resolved value by id — column totals first, then items in order. */
     resolved: Record<string, number | string>;
     hasColumnTotals: boolean;
     hasSummary: boolean;

package/dist/types/shared-logic/src/ui/timeField.logic.d.ts

@@ -0,0 +1,26 @@
+export type TimeOfDay = string;
+export declare const MINUTES_IN_DAY: number;
+export declare function timeToMinutes(time: TimeOfDay): number;
+export declare function minutesToTime(minutes: number): TimeOfDay;
+export declare const isTimeOfDay: (time: unknown) => boolean;
+export declare function to12Hour(hour24: number): {
+    h12: number;
+    meridiem: 'AM' | 'PM';
+};
+export declare function from12Hour(h12: number, meridiem: 'AM' | 'PM'): number;
+export declare function formatTimeText(time: TimeOfDay, hour12?: boolean): string;
+export declare const timePlaceholder: (hour12?: boolean) => string;
+export declare function parseTimeText(text: string, opts?: {
+    within?: TimeOfDay;
+}): TimeOfDay | null;
+export interface TimeColumns {
+    hours: number[];
+    minutes: number[];
+    meridiems: ('AM' | 'PM')[];
+}
+export declare function buildTimeColumns(time: TimeOfDay, opts?: {
+    hour12?: boolean;
+    minuteStep?: number;
+}): TimeColumns;
+export declare function setTimePart(time: TimeOfDay, part: 'hour' | 'minute' | 'meridiem', value: number | 'AM' | 'PM', hour12?: boolean): TimeOfDay;
+export declare function isTimePartActive(time: TimeOfDay, part: 'hour' | 'minute' | 'meridiem', value: number | 'AM' | 'PM', hour12?: boolean): boolean;

package/dist/types/shared-logic/src/ui/tooltip.logic.d.ts

@@ -1,35 +1,11 @@
 import type { TooltipAnchorTo, TooltipConfig, TooltipPlacement, TooltipPosition, TooltipPositionInput, TooltipProp } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * A `tooltip` prop is either bare content or a config object. Anything that is
- * a React element counts as content — only a plain object carrying `content`
- * is treated as configuration.
- */
 export declare function normalizeTooltip(value: TooltipProp | undefined): TooltipConfig | null;
 export interface TooltipAnchorDecision {
     anchorTo: TooltipAnchorTo;
-    /** Keyboard focus has no cursor, so it can never be pointer-anchored. */
     openedBy: 'pointer' | 'focus';
     anchorWidth: number;
     tooltipWidth: number;
 }
-/**
- * Whether to place the tooltip at the cursor rather than against the trigger.
- *
- * The `auto` rule: element-anchoring only reads as "attached to this thing" while
- * the trigger is no wider than the tip. Past that — block text, a table row, a
- * full-width header — the tip centres on the element and lands far from where the
- * pointer actually is, so it follows the pointer instead.
- */
 export declare function shouldAnchorToPointer(decision: TooltipAnchorDecision): boolean;
-/** Requested placement first, then its opposite, then the perpendicular pair. */
 export declare function resolveTooltipPlacementOrder(placement: TooltipPlacement): TooltipPlacement[];
-/**
- * Viewport-coordinate position for a tooltip, flipping to the first placement
- * that fits and then clamping along the cross axis so it never leaves the
- * screen. Pure geometry — the caller measures the DOM and applies the result.
- *
- * Only the fallback path for browsers without CSS anchor positioning uses this;
- * where anchor positioning is supported the same behaviour comes from
- * `position-try-fallbacks`.
- */
 export declare function computeTooltipPosition(input: TooltipPositionInput): TooltipPosition;

package/dist/types/shared-logic/src/ui/useMergeRefs.d.ts

@@ -1,10 +1,2 @@
 import type { Ref, RefCallback } from 'react';
-/**
- * Merge several refs into one stable ref callback.
- *
- * The callback identity never changes, which matters: memoising on the spread
- * `refs` array instead produces a new callback on every render, and React
- * responds by calling the old callback with `null` and the new one with the
- * node — detaching and re-attaching the ref on every single render.
- */
 export declare function useMergeRefs<T>(...refs: (Ref<T> | undefined | null)[]): RefCallback<T>;

package/dist/types/shared-types/src/report/bands.d.ts

@@ -1,32 +1,12 @@
-/**
- * Report engine — bands, the sections of a page.
- *
- * Three kinds, and the order of `template.bands` is the print order:
- *
- * - `pageHeader` — the top of every page.
- * - `content` — prints once, where it stands. Tables inside it flow across pages.
- * - `pageFooter` — the foot of every page.
- *
- * v1 also had detail, group and report header/footer bands. They existed to serve the one main
- * grid; a table now carries its own rows, sections and closing rows, and "report header" is simply
- * the first content band. See `docs/REPORT_ENGINE.md` §14.3.
- */
 import type { Block } from './blocks';
 import type { ReportConditionGroup } from './conditions';
 export type BandKind = 'pageHeader' | 'content' | 'pageFooter';
 export interface Band {
     id: string;
     kind: BandKind;
-    /**
-     * For `content`: print it on every page, under the page header — the business and buyer block
-     * that several invoice formats repeat. Ignored for page bands, which repeat by definition.
-     */
     repeatOnEveryPage?: boolean;
-    /** Never split this band across a page break; move it whole to the next page instead. */
     keepTogether?: boolean;
-    /** Never end a page with this band: if the band after it moves on, this band moves with it. */
     keepWithNext?: boolean;
-    /** Suppress the band entirely when this fails. */
     condition?: ReportConditionGroup;
     blocks: Block[];
 }

package/dist/types/shared-types/src/report/blocks.d.ts

@@ -1,11 +1,3 @@
-/**
- * Report engine — blocks, the things a band is made of.
- *
- * A table is a block like any other and can go anywhere, as many times as a report needs. There is
- * no special "main grid": everything v1 did for it — a heading on every page, a closed box, empty
- * rows down the page, closing rows kept with what follows — belongs to every table that flows.
- * See `docs/REPORT_ENGINE.md` §14.4.
- */
 import type { ReportConditionGroup } from './conditions';
 import type { ColumnSpec, TableData } from './dataset';
 import type { GridFill, GridLines } from './template';
@@ -14,19 +6,14 @@ export interface BlockBase {
     id: string;
     condition?: ReportConditionGroup;
     style?: TextStyle;
-    /** Points, [top, right, bottom, left]. A negative side widens the block into the page margin. */
     margin?: [number, number, number, number];
 }
-/** An image at the left of a cell, the text beside it — a logo before the business name. */
 export interface CellImage {
-    /** A URL or data URI, or a placeholder resolving to one. Empty draws no image. */
     src: string;
     widthPt: number;
     heightPt: number;
-    /** Space between the image and the text. */
     gapPt?: number;
 }
-/** One cell of a text block's row. Width is a percentage of the block, or 'auto'. */
 export interface TextCell {
     id: string;
     width: number | 'auto';
@@ -34,7 +21,6 @@ export interface TextCell {
     style?: TextStyle;
     segments: TextSegment[];
     condition?: ReportConditionGroup;
-    /** A fixed width in points, overriding `width`; the other cells share what is left. */
     widthPt?: number;
     image?: CellImage;
 }
@@ -42,46 +28,25 @@ export interface TextRow {
     id: string;
     cells: TextCell[];
     condition?: ReportConditionGroup;
-    /**
-     * The row is at least this tall, points, padding included and lines excluded — room left for a
-     * signature, or a box that must not collapse when its fields are empty.
-     */
     minHeightPt?: number;
-    /** A line above this row when it sits inside a box — the rule over a total. */
     lineAbovePt?: number;
 }
-/**
- * One cell of a column-aligned row, covering the columns `from` through `to`, by column id.
- *
- * On a `groupColumns` column (with no `to`, or `to` the same column) the cell repeats once per
- * generated column, with that value's `%group.*%` in scope — a total under every size.
- */
 export interface AlignedCell {
     id: string;
     from: string;
-    /** Absent covers `from` alone. */
     to?: string;
     segments: TextSegment[];
     align?: Alignment;
     style?: TextStyle;
-    /** Format for every placeholder in the cell that has none of its own. */
     format?: PlaceholderFormat;
 }
-/**
- * A row laid out on a table's own columns rather than by percentages, so a figure sits exactly
- * under its column — a tax amount under Amount, "Total" spanning everything before it. A column no
- * cell covers prints empty, with its column lines. Cells name columns by id, which keeps them right
- * when a column is hidden by a condition or expanded per group value.
- */
 export interface AlignedRow {
     id: string;
     cells: AlignedCell[];
     condition?: ReportConditionGroup;
     minHeightPt?: number;
-    /** A line above this row — the rule over a grand total. */
     lineAbovePt?: number;
 }
-/** A heading above several column headings — "Central Tax" over Rate | Amount, "Sizes" over the size columns. */
 export interface HeaderGroup {
     id: string;
     label: string;
@@ -92,33 +57,19 @@ export interface HeaderGroup {
 export interface TextBlock extends BlockBase {
     type: 'text';
     rows: TextRow[];
-    /**
-     * Draws the block as a box: `outer` around it, `columns` between cells, `rows` between rows.
-     * `header` is unused here. These take space and are planned with.
-     */
     lines?: GridLines;
 }
 export interface TableHeader {
-    /** Default true. */
     show?: boolean;
-    /** Print the heading again at the top of every page the table continues onto. Default true. */
     repeat?: boolean;
     style?: TextStyle;
-    /** A heading row above the column headings, each label spanning the columns it groups. */
     groups?: HeaderGroup[];
 }
-/**
- * Rows split into sections each time `by` changes — a category heading, an ageing bucket with its
- * subtotal. Not the same thing as grouping values (`TableData.group`), and named apart for that.
- */
 export interface SectionSpec {
     by: string;
     sort?: 'asc' | 'desc';
-    /** Printed above each section. `%row.*%` is its first row; `%agg.*(row.x)%` covers the section. */
     header?: AlignedRow[];
-    /** Printed below each section, with the same scope. */
     footer?: AlignedRow[];
-    /** Try to keep a section on one page. */
     keepTogether?: boolean;
 }
 export interface TableBlock extends BlockBase {
@@ -127,23 +78,14 @@ export interface TableBlock extends BlockBase {
     columns: ColumnSpec[];
     header?: TableHeader;
     sections?: SectionSpec;
-    /** Rows closing the table after its last row — tax, round off, total — under their columns. */
     footer?: AlignedRow[];
-    /** Keep the closing rows on the page with whatever follows the table. */
     footerKeepWithNext?: boolean;
-    /** Ruling — box, between columns, under the heading, between rows. */
     lines?: GridLines;
-    /** Empty rows under the last row, so the box runs down the page. */
     fill?: GridFill;
-    /**
-     * true: the table moves to the next page whole rather than splitting — a small summary.
-     * false (default): it flows across pages, row by row, its heading repeating.
-     */
     keepTogether?: boolean;
 }
 export interface ImageBlock extends BlockBase {
     type: 'image';
-    /** Literal URL/data-URI, or a placeholder resolving to one. */
     src: string;
     widthPt: number;
     heightPt?: number | 'auto';
@@ -172,7 +114,6 @@ export interface SeparatorBlock extends BlockBase {
     stroke: StrokeStyle;
     thicknessPt?: number;
 }
-/** Vertical whitespace — a signature gap, a spacer above totals. */
 export interface SpacerBlock extends BlockBase {
     type: 'spacer';
     heightPt: number;

package/dist/types/shared-types/src/report/conditions.d.ts

@@ -1,21 +1,8 @@
-/**
- * Report engine — conditional visibility.
- *
- * Prefixed `Report*` because `ui/fields.types.ts` already exports a `ConditionOperator` — a
- * different thing (form-field visibility, generic over the form's own shape) that happens to
- * share the obvious name.
- *
- * Carried over from `ReceiptDesigner/types.ts` unchanged in meaning: the operator set was arrived
- * at by use and there is no reason to redesign it. The one change is that the legacy single-rule
- * shape is gone — nothing in production authored one, so the union does not need to survive.
- */
 export type ReportConditionOperator = '==' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'in' | 'notIn' | 'exists' | 'notExists';
 export interface ReportConditionRule {
     id: string;
-    /** `source.field` or `row.field`, resolved against the registry. */
     field: string;
     operator: ReportConditionOperator;
-    /** Omitted for `exists` / `notExists`. */
     value?: string | number | boolean | Array<string | number>;
 }
 export interface ReportConditionGroup {

package/dist/types/shared-types/src/report/dataset.d.ts

@@ -1,87 +1,40 @@
-/**
- * Report engine — what a table prints, and the rows it prints them from.
- *
- * Every table shapes its own rows (`TableData`), because a report has more than one table and each
- * wants different rows: items combined by item, tax by rate, tax by HSN, services apart from goods.
- * v1 gave that power to one "main grid" only, which is why a tax table by HSN could not be built.
- * See `docs/REPORT_ENGINE.md` §14.4.
- */
 import type { ReportConditionGroup } from './conditions';
 import type { Alignment, PlaceholderFormat, PlaceholderFormats, TextStyle } from './primitives';
-/**
- * One line inside a table cell.
- *
- * A description cell is rarely one line: the name, then the description, then the product code,
- * then the item's colours. Each is a line, so its height is known before anything is drawn.
- */
 export interface CellLine {
     id: string;
-    /** Literal text and `%source.key%` placeholders. */
     content: string;
     style?: TextStyle;
-    /**
-     * How individual placeholders on this line print, keyed by the token itself — `%row.sn%`.
-     *
-     * A line can name several fields, and they rarely want the same treatment: a serial number as a
-     * plain integer beside an amount to two decimals. A token with no entry here falls back to the
-     * column's own `format`, and then to the field's default from the registry.
-     */
     formats?: PlaceholderFormats;
     condition?: ReportConditionGroup;
-    /**
-     * Print once per group value of the row (`TableData.group`), with `%group.*%` in scope — an
-     * item's colours, with their quantities.
-     */
     repeat?: 'groups';
-    /** For `repeat: 'groups'`: a line each (default), or all on one running line. */
     display?: 'lines' | 'inline';
-    /** For `display: 'inline'`: what goes between values. Defaults to ", ". */
     separator?: string;
 }
-/**
- * `field` — an ordinary column.
- * `groupColumns` — expands into one column per distinct group value across the table (a column per
- * size), in lookup order. Its `header` and `value` read `%group.*%`.
- */
 export type ColumnKind = 'field' | 'groupColumns';
 export interface ColumnSpec {
     id: string;
-    /** Absent means `field`. */
     kind?: ColumnKind;
-    /** May contain placeholders. */
     header: string;
-    /** What each row prints here: `%row.total%`, or several lines for a rich cell. */
     value: string | CellLine[];
     width: number | '*' | 'auto';
     align?: Alignment;
-    /** The default for every placeholder in this column that has none of its own. */
     format?: PlaceholderFormat;
-    /** How individual placeholders print, keyed by the token — `%row.hsn%`. Beats `format`. */
     formats?: PlaceholderFormats;
     style?: TextStyle;
     headerStyle?: TextStyle;
-    /** Alignment of the heading when it differs from the values' — a left heading over right-aligned figures. */
     headerAlign?: Alignment;
-    /** Column is dropped entirely when this fails. */
     condition?: ReportConditionGroup;
 }
-/** Rows agreeing on every `by` field become one row; `sum` fields add up, the rest keep the first. */
 export interface CombineSpec {
     by: string[];
     sum?: string[];
 }
-/** A row set used to name and order group values. Filled from the row set's `LookupDef` by default. */
 export interface LookupRef {
     rowSet: string;
     key: string;
     label: string;
     order?: string;
 }
-/**
- * "Grouping usage": each row gathers the values of `by` from the rows combined into it — the item
- * gathers its colours. Every group value carries the fields of the rows it gathered (`sum` fields
- * added up, others first-seen), plus `key`, `label`, `order` and the lookup row as `lookup.*`.
- */
 export interface GroupValuesSpec {
     by: string;
     lookup?: LookupRef;
@@ -91,13 +44,7 @@ export interface SortSpec {
     by: string;
     dir: 'asc' | 'desc';
 }
-/**
- * The rows one table prints. Runs in this order: filter → combine and group → sort.
- *
- * Without `group` this is "direct usage": one printed row per (combined) data row.
- */
 export interface TableData {
-    /** A `rowSets` key in the `ReportContext`. */
     rowSet: string;
     filter?: ReportConditionGroup;
     combine?: CombineSpec;