@dcs-tech/ui 0.2.0 → 0.3.0

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

@@ -1,47 +1,21 @@
 import type { CellRule, ConditionContext, EditableTableColumnDefinition } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Cell validation, decided purely.
- *
- * The table asks three questions and this answers all three without touching the DOM:
- * is THIS cell valid, is this ROW valid, and may a new row be created? Keeping it here is
- * what lets the same rules run in a test, in the API, or in a future mobile port — and it
- * is the reason a rule is `Condition`-shaped rather than a bespoke callback: a consumer
- * who already writes `disabled: { key: 'x', equals: 1 }` writes a rule the same way.
- */
 export interface ResolvedRule {
     valid: boolean;
-    /** The first failing rule's message. */
     message?: string;
     severity: 'block' | 'warn';
 }
-/**
- * A cell's rules, in order; the first failure wins.
- *
- * `when` decides whether a rule APPLIES before `valid` decides whether it PASSES — that
- * split is what makes "min qty, but only when the item is stocked" expressible without a
- * second rule list.
- */
 export declare function resolveCellRules<T>(rules: Array<CellRule<T>> | undefined, rowData: T, defaultData: T, context?: ConditionContext): ResolvedRule;
-/** One column's rules, resolved for one row. */
 export declare function resolveColumnRules<T>(column: EditableTableColumnDefinition<T> | undefined, rowData: T, defaultData: T, rowIndex: number, cellindex: number, tableDataKey?: string): ResolvedRule;
 export interface RowRuleFailure {
     cellindex: number;
     message: string;
     severity: 'block' | 'warn';
 }
-/** Every failing cell in a row, so a caller can report or jump to the first one. */
 export declare function resolveRowRules<T>(columns: Array<EditableTableColumnDefinition<T>>, rowData: T, defaultData: T, rowIndex: number, tableDataKey?: string): {
     valid: boolean;
     blocked: boolean;
     failures: RowRuleFailure[];
 };
-/**
- * Is this row still empty?
- *
- * Compared against `defaultData`, not against "falsy": a Qty that defaults to 0 and a
- * checkbox that defaults to false are BLANK, while a 0 typed into a field whose default is
- * `''` is not. The row's own key is ignored — it is generated, never typed.
- */
 export declare function isRowBlank<T extends Record<string, any>>(row: T | undefined, defaultData: T, rowKey?: string): boolean;
 export interface CreateRowPolicy {
     fixedRows?: boolean;
@@ -50,18 +24,9 @@ export interface CreateRowPolicy {
 }
 export interface CreateRowDecision {
     allowed: boolean;
-    /** Why not — for a message, and for tests that assert the REASON, not just the refusal. */
     reason?: 'fixedRows' | 'blankRow' | 'invalidRow' | 'consumer';
-    /** The row a blocked caller should go to instead: the blank one, or the invalid one. */
     focusRowIndex?: number;
 }
-/**
- * May a row be created right now?
- *
- * The default answers "not while a blank row is waiting" — holding Enter at the end of a
- * table used to append one empty row per press. Each half is a prop, because a table that
- * is a scratchpad may genuinely want the blanks.
- */
 export declare function canCreateRow<T extends Record<string, any>>(rows: T[], defaultData: T, policy: CreateRowPolicy, rowRules?: (rowIndex: number) => {
     blocked: boolean;
 }, rowKey?: string): CreateRowDecision;

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

@@ -1,18 +1,6 @@
-/**
- * ChipInput Logic — Pure functions for format string manipulation and suggestion filtering.
- * No React, no DOM.
- */
 import type { ChipTokenSyntax, ChipSources, ChipSuggestionItem, GroupedSuggestions, ParsedSegment, ResolveOptions, ExtractedPlaceholder, FormatValidationResult } from '../../../published/dcs-ui/src/publicTypes';
-/** The text of one token in the given syntax. */
 export declare function formatChipToken(source: string, key: string, syntax?: ChipTokenSyntax): string;
-/** The character that starts a token, and so opens the suggestions while typing. */
 export declare function chipTokenOpener(syntax?: ChipTokenSyntax): string;
-/**
- * Whether the text typed since the last opener is still an unfinished token.
- *
- * Percent also stops at whitespace: `%` doubles as ordinary punctuation ("5% off"), and a
- * suggestion list that opened on every percent sign would follow the author around.
- */
 export declare function isOpenChipToken(afterOpener: string, syntax?: ChipTokenSyntax): boolean;
 export declare function parseFormat(format: string, syntax?: ChipTokenSyntax): ParsedSegment[];
 export declare function resolveFormat(format: string, data: Record<string, Record<string, any>>, options?: ResolveOptions): string;

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

@@ -24,12 +24,5 @@ interface CollapsibleHeaderOpts {
     isDisabled: boolean;
 }
 export declare function buildCollapsibleHeaderClassKeys(opts: CollapsibleHeaderOpts): string[];
-/**
- * Given the triggers in one accordion and the one holding focus, returns the
- * index to move to. ArrowDown/Up wrap; Home/End jump to the ends. Returns null
- * for any other key, so the caller leaves the event alone.
- *
- * Pure index maths — the DOM query and the .focus() call stay in the component.
- */
 export declare function resolveCollapsibleFocusIndex(key: string, currentIndex: number, total: number): number | null;
 export {};

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

@@ -1,29 +1,15 @@
 export type ColorSchemeMode = 'light' | 'dark';
 export type ColorSchemeRole = 'title' | 'bg' | 'onBg';
 export interface ColorScheme {
-    /** the stored value */
     id: string;
-    /** shown in the picker */
     name: string;
-    /** hue, 0-359 */
     h: number;
-    /** saturation % in light mode */
     s: number;
-    /** saturation % in dark mode — tuned per hue, not a constant (see BUSINESS_COLOR_SCHEMES) */
     sd: number;
 }
 export type ColorSchemeTokens = Record<ColorSchemeRole, string>;
-/** Lightness per role per mode. The only numbers in the system. */
 export declare const COLOR_SCHEME_LIGHTNESS: Record<ColorSchemeMode, Record<ColorSchemeRole, number>>;
-/** One role, as an `hsl()` string. */
 export declare const schemeColor: (scheme: ColorScheme, role: ColorSchemeRole, mode?: ColorSchemeMode) => string;
-/** All three roles for one mode. Use for PDFs and anywhere CSS variables aren't available. */
 export declare const schemeTokens: (scheme: ColorScheme, mode?: ColorSchemeMode) => ColorSchemeTokens;
-/**
- * The custom properties to put on a wrapper element. Only hue and the two saturations —
- * the stylesheet owns the lightness per mode, so the theme switch stays in CSS where it
- * belongs rather than being recomputed in JS on every theme change.
- */
 export declare const schemeVars: (scheme: ColorScheme | null | undefined) => Record<string, string>;
-/** Look one up by stored id. Returns null for '' / unknown, which means "no scheme set". */
 export declare const findColorScheme: (schemes: ColorScheme[], id: string | null | undefined) => ColorScheme | null;

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

@@ -1,12 +1 @@
-/**
- * Merges a user's saved column order with the current config order.
- *
- * A column added to a report after the user saved their order is not in `saved`. It must
- * land where the config puts it — right after its nearest preceding config neighbour that
- * the user still has — not at the far right. Appending was the old behaviour, and it left
- * every new column stranded at the end until the user reordered or reset.
- *
- * Saved keys are kept in the user's order, including keys the config no longer has (the
- * table ignores them; dropping them here would silently rewrite the user's saved state).
- */
 export declare function mergeColumnOrder(saved: readonly string[], config: readonly string[]): string[];

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

@@ -0,0 +1,136 @@
+import type { DateDisplayFormat, DateTextOrder } from '../../../published/dcs-ui/src/publicTypes';
+export type IsoDay = string;
+export type DateValue = string;
+export interface DateParts {
+    y: number;
+    m: number;
+    d: number;
+}
+export declare const MIN_DATE_YEAR = 1900;
+export declare const daysInMonth: (y: number, m: number) => number;
+export declare function isRealDay({ y, m, d }: DateParts): boolean;
+export declare const toIsoDay: ({ y, m, d }: DateParts) => IsoDay;
+export declare function parseIsoDay(value: unknown): DateParts | null;
+export declare const isIsoDay: (value: unknown) => boolean;
+export declare const todayIso: (now?: Date) => IsoDay;
+export declare const compareDays: (a: IsoDay, b: IsoDay) => number;
+export declare const isSameDay: (a: unknown, b: unknown) => boolean;
+export declare function shiftDays(day: IsoDay, n: number): IsoDay;
+export declare function shiftMonths(day: IsoDay, n: number): IsoDay;
+export declare const shiftYears: (day: IsoDay, n: number) => IsoDay;
+export declare function startOfMonth(day: IsoDay): IsoDay;
+export declare function endOfMonth(day: IsoDay): IsoDay;
+export declare function weekdayOf(day: IsoDay): number;
+export declare const isDayInRange: (day: IsoDay, min?: string, max?: string) => boolean;
+export declare function clampDay(day: IsoDay, min?: string, max?: string): IsoDay;
+export declare function normalizeTime(value: unknown): string;
+export declare function splitDateValue(value: unknown): {
+    day: IsoDay;
+    time: string;
+};
+export declare function joinDateValue(day: IsoDay, time?: string): DateValue;
+export declare function parseDateText(text: unknown, opts?: {
+    within?: IsoDay;
+    today?: IsoDay;
+    order?: DateTextOrder;
+}): IsoDay | null;
+export declare const RANGE_ADVANCE_KEY = "+";
+export interface TypedDateRange {
+    from: IsoDay;
+    to: IsoDay;
+}
+export declare function parseDateRangeText(text: unknown, opts?: {
+    within?: IsoDay;
+    today?: IsoDay;
+    order?: DateTextOrder;
+}): TypedDateRange | null;
+export declare function formatDayText(day: unknown, format?: DateDisplayFormat): string;
+export declare const datePlaceholder: (format?: DateDisplayFormat, withTime?: boolean) => string;
+export declare function formatDateValueText(value: unknown, format?: DateDisplayFormat, withTime?: boolean): string;
+export declare function parseDateValueText(text: unknown, opts?: {
+    within?: IsoDay;
+    today?: IsoDay;
+    order?: DateTextOrder;
+    withTime?: boolean;
+}): {
+    day: IsoDay;
+    time: string;
+} | null;
+export interface CalendarDay {
+    day: IsoDay;
+    date: number;
+    inMonth: boolean;
+    isToday: boolean;
+    isSelected: boolean;
+    isHighlighted: boolean;
+    inRange: boolean;
+    isRangeStart: boolean;
+    isRangeEnd: boolean;
+    disabled: boolean;
+}
+export interface CalendarView {
+    month: IsoDay;
+    year: number;
+    monthIndex: number;
+    weeks: CalendarDay[][];
+    weekdays: number[];
+    canPagePrev: boolean;
+    canPageNext: boolean;
+}
+export interface CalendarOptions {
+    month: IsoDay;
+    today?: IsoDay;
+    selected?: string | null;
+    highlighted?: string | null;
+    rangeFrom?: string | null;
+    rangeTo?: string | null;
+    min?: string;
+    max?: string;
+    weekStart?: number;
+    fixedWeeks?: boolean;
+}
+export declare function buildCalendar(opts: CalendarOptions): CalendarView;
+export type DateHighlightAction = 'highlightLeft' | 'highlightRight' | 'highlightPrev' | 'highlightNext' | 'highlightFirst' | 'highlightLast' | 'highlightPrevPage' | 'highlightNextPage';
+export declare const DATE_HIGHLIGHT_ACTIONS: readonly DateHighlightAction[];
+export declare function moveHighlight(from: IsoDay, action: DateHighlightAction, opts?: {
+    min?: string;
+    max?: string;
+}): IsoDay;
+export declare function openingHighlight(value?: string | null, opts?: {
+    today?: IsoDay;
+    min?: string;
+    max?: string;
+}): IsoDay;
+export interface DatePreset {
+    key: string;
+    label: string;
+    single?: boolean;
+    from: IsoDay;
+    to: IsoDay;
+}
+export interface DatePresetOptions {
+    today?: IsoDay;
+    fyStartMonth?: number;
+    weekStart?: number;
+    only?: string[];
+}
+export declare function financialYearOf(day: IsoDay, fyStartMonth?: number): {
+    from: IsoDay;
+    to: IsoDay;
+};
+export declare function startOfWeek(day: IsoDay, weekStart?: number): IsoDay;
+export declare function quarterOf(day: IsoDay, fyStartMonth?: number): {
+    from: IsoDay;
+    to: IsoDay;
+};
+export declare function buildDatePresets(opts?: DatePresetOptions): DatePreset[];
+export declare function matchDatePresets(presets: DatePreset[], query: unknown): DatePreset[];
+export interface DayRange {
+    from: IsoDay;
+    to: IsoDay;
+}
+export declare function viewForRange(from: IsoDay, to: IsoDay, opts?: {
+    months?: number;
+    currentMonthSide?: 'left' | 'right';
+}): IsoDay;
+export declare function extendDateRange(range: Partial<DayRange> | null | undefined, day: IsoDay): DayRange;

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

@@ -1,43 +1,16 @@
-/**
- * EditableTable Logic — Pure functions for editable table state management.
- * No React, no DOM.
- */
 import type { EditableTableColumnDefinition } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Get table rows from state, handling nested paths via tableDataKey.
- */
 export declare function getEditableTableRows<T>(state: any, tableDataKey?: string): T[];
-/**
- * Wrap updated rows back into the parent state shape.
- */
 export declare function updateEditableTableRows<T>(state: any, updatedRows: T[], tableDataKey?: string): any;
-/**
- * Create a new row from defaultData template.
- * Uses tableDataKey to extract the row template from nested defaults.
- */
 export declare function createNewRow<T>(defaultData: T, rowKey: string, generateId: () => string, tableDataKey?: string): T;
-/**
- * Create a copied row from a source row, optionally limiting to specific keys.
- */
 export declare function createCopiedRow<T>(sourceRow: T, newRowTemplate: T, copyKeys: string[], rowKey: string, generateId: () => string): T;
-/**
- * Check if a cell is disabled based on column definition and row data.
- */
 export declare function isCellDisabled<T>(rowIndex: number, cellindex: number, tableRows: T[], columns: EditableTableColumnDefinition<T>[], defaultData: T, tableDataKey?: string, getRowField?: (context: {
     rowIndex: number;
     tableDataKey?: string;
 }) => EditableTableColumnDefinition<T>[]): boolean;
-/**
- * Pure grid navigation: find next focusable cell in a direction.
- * Returns target coordinates and whether a new row can be created.
- */
 export declare function findNextFocusableCell<T>(currentRowIndex: number, currentCellIndex: number, direction: 'forward' | 'backward', totalRows: number, totalColumns: number, fixedRows: boolean, checkDisabled: (rowIndex: number, cellindex: number) => boolean): {
     rowIndex: number;
     cellindex: number;
     found: boolean;
     canCreateNew?: boolean;
 };
-/**
- * Generate a random ID string.
- */
 export declare function generateEditableTableId(length?: number): string;

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

@@ -1,24 +1,12 @@
+import type { ControlSize } from '../../../published/dcs-ui/src/publicTypes';
 export interface FieldControlClassOptions {
-    /** FieldSize: 'xxs' | 'xs' | 'small' | 'medium' | 'large' | 'xl' */
     size?: string;
-    /** FieldVariant: 'outlined' | 'filled' | 'standard' | 'underlined' */
     variant?: string;
     error?: boolean;
     disabled?: boolean;
     readOnly?: boolean;
-    /** Reserve trailing space for in-field affixes (select arrow, clear button, …). */
     hasAffix?: boolean;
-    /**
-     * A joined popup is open beneath this control, so its bottom corners must square to meet
-     * the list. Ignored for variants with no box — those get a floating panel instead.
-     */
     popupOpen?: boolean;
 }
-/**
- * Class keys for the shared control surface used by Input, Select and Suggest.
- *
- * All three map these keys against the SAME CSS module
- * (shared-web-ui/src/styles/fieldControl.module.css), so a given size/variant
- * resolves to one identical set of rules regardless of which control renders it.
- */
 export declare const buildFieldControlClassKeys: ({ size, variant, error, disabled, readOnly, hasAffix, popupOpen, }: FieldControlClassOptions) => string[];
+export declare function smallerSize(size: ControlSize): ControlSize;

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

@@ -1,7 +1,3 @@
-/**
- * Form Logic — Pure functions for form state management
- * No React, no DOM.
- */
 export interface FormClassKeyOptions {
     variant: string;
     size: string;
@@ -10,8 +6,4 @@ export interface FormClassKeyOptions {
     loading?: boolean;
 }
 export declare function buildFormClassKeys(opts: FormClassKeyOptions): string[];
-/**
- * Evaluate a boolean-or-function condition against data.
- * Used for section/action visible, disabled, loading props.
- */
 export declare function evaluateFormCondition<T>(condition: boolean | ((data: T) => boolean) | undefined, data: T, defaultValue: boolean): boolean;

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

@@ -1,32 +1,3 @@
-/**
- * The UI half of `shared-logic`, on its own.
- *
- * WHY THIS FILE EXISTS — it is a privacy boundary, not a convenience.
- *
- * The package barrel (`shared-logic/src/index.ts`) re-exports this folder AND every domain
- * folder beside it. Anything that imports the barrel therefore pulls the whole package into
- * its TypeScript program — and `tsc` emits declarations for a whole program, not for the
- * subset a barrel happens to re-export.
- *
- * That is how `@dcs-tech/ui@0.1.0` shipped this business's domain type surface to the public
- * npm registry (audited 2026-09-28): the JS bundle was clean, because a bundler tree-shakes,
- * but the emitted `dist/types/` carried the domain declarations — signatures, field names and
- * doc comments. The `export *` gate in `dcs-ui/src/index.ts` guards the JS surface only; it
- * never governed the declaration emit.
- *
- * (This comment names no domain folder on purpose: it ships, as the leak it describes proves.)
- *
- * So the published build maps `@pdfinvoice/shared-logic` to this file instead, and the domain
- * never enters the program. Keep it that way:
- *
- *   - ONLY `./ui/*` modules belong here. Never add a domain module, however small, and never
- *     re-export the parent barrel.
- *   - A UI module that starts importing domain code re-opens the hole silently — the guard in
- *     `dcs-ui` (`npm run verify:no-leak`) is what catches it.
- *
- * It is also the import the API should use. `apps/api` must never touch the package barrel:
- * that pulls React in through `useMergeRefs` and kills every Cloud Run function at startup.
- */
 export * from './button.logic';
 export * from './cellRules.logic';
 export * from './checkbox.logic';
@@ -34,6 +5,8 @@ export * from './chipinput.logic';
 export * from './collapsible.logic';
 export * from './colorScheme';
 export * from './columnOrder.logic';
+export * from './datePicker.logic';
+export * from './timeField.logic';
 export * from './editableTable.logic';
 export * from './fieldControl.logic';
 export * from './fieldWrapper.logic';
@@ -44,6 +17,7 @@ export * from './keyboard.logic';
 export * from './navigation.logic';
 export * from './popover.logic';
 export * from './popupList.logic';
+export * from './quickAddGrid.logic';
 export * from './radio.logic';
 export * from './select.logic';
 export * from './suggest.logic';

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

@@ -1,72 +1,12 @@
 import type { FieldKeyboardConfig, KeyEventLike, KeyResolution, KeyResolutionContext, NavAction } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * The one place that decides who owns a key.
- *
- * Pure, and deliberately free of React and the DOM: it takes a `KeyEventLike`
- * (which a `React.KeyboardEvent` satisfies structurally) and returns a verdict.
- * That is what lets the whole truth table run under plain `node`, and what keeps
- * it mechanically portable to the mobile core package if mobile ever grows a grid.
- *
- * ── The two laws ────────────────────────────────────────────────────────────
- *
- * **L1** — in `navigate` mode the container owns every arrow, Enter, Tab,
- * Home/End and PageUp/Down.
- *
- * **L2** — an open popup owns ↑ ↓ Enter Escape for as long as it is open,
- * whichever widget opened it and whatever mode the cell is in.
- *
- * Everything below is a consequence of those two. L2 is checked before L1
- * because it is the narrower claim: a Select with its list down is not "a cell
- * being navigated", it is a list being navigated, and the grid must not see
- * those keys at all.
- */
-/**
- * Canonical form: modifiers alphabetically, then the key, all lower-case —
- * `alt+ctrl+shift+enter`. Sorting is what makes `'ctrl+shift+enter'` and
- * `'shift+ctrl+enter'` the same binding, so a consumer cannot write an override
- * that silently never matches because they ordered the modifiers differently.
- */
 export declare function parseBinding(binding: string): string;
-/** The canonical binding string an event represents. */
 export declare function eventBinding(event: KeyEventLike): string;
 export declare function matchBinding(event: KeyEventLike, binding: string): boolean;
-/**
- * The container bindings a grid starts with.
- *
- * The `ctrl+arrow*` and `alt+arrow*` entries are **aliases kept on purpose**.
- * They are what the current editable table binds, because Input owned no keys
- * and plain arrows never reached the grid. Keeping them means existing screens
- * and existing muscle memory survive the switch to plain arrows instead of
- * breaking on the day the new grid lands.
- */
 export declare const DEFAULT_GRID_BINDINGS: Record<string, NavAction>;
-/** A form is a one-column grid: no rows to add, and Ctrl+Enter submits. */
 export declare const DEFAULT_FORM_BINDINGS: Record<string, NavAction>;
 export declare const DEFAULT_KEYBOARD_CONFIG: Required<Pick<FieldKeyboardConfig, 'mode' | 'enter' | 'arrows' | 'arrowsInEdit' | 'typeBehaviour' | 'editKey' | 'openOn' | 'advanceOnSelect' | 'stepKeys'>>;
-/** What a cell wants when nothing overrides it: grid mode, Enter moves on, type to open. */
 export declare const GRID_CELL_KEYBOARD_DEFAULTS: FieldKeyboardConfig;
-/**
- * A key that produces a character. `metaKey`/`ctrlKey` exclude shortcuts;
- * `altKey` is *not* excluded because AltGr (which reports `ctrlKey && altKey`)
- * is how a great many non-US layouts type ordinary characters.
- */
 export declare function isPrintableKey(event: KeyEventLike): boolean;
 export declare function resolveFieldKey(event: KeyEventLike, ctx: KeyResolutionContext): KeyResolution;
-/**
- * The next index in a linear list, skipping the ones a predicate rejects.
- *
- * A form is a one-column grid, so this is the one-dimensional sibling of
- * `findNextFocusableCell`. Kept pure and separate from any DOM query: what
- * counts as "focusable" is the caller's business, and this way the traversal is
- * testable without a browser.
- *
- * @returns the next usable index, or `-1` when the list runs out.
- */
 export declare function nextFocusableIndex(count: number, current: number, direction: 'forward' | 'backward', isDisabled?: (index: number) => boolean, wrap?: boolean): number;
-/**
- * Resolves the config a field actually runs on: own prop → container → default.
- *
- * The same order `useFieldSurface` uses for `size`, and for the same reason — a
- * field must be able to tell "nobody said" from "someone said grid mode".
- */
 export declare function resolveKeyboardConfig(own: FieldKeyboardConfig | undefined, inherited: FieldKeyboardConfig | undefined): FieldKeyboardConfig;

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

@@ -1,30 +1,6 @@
 import type { NavItem } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Path from the root to the item with `id`, inclusive. `[]` when not found.
- *
- * This one function serves both surfaces, which is the point of a single `NavItem` shape:
- * a **Sidebar highlights** the trail (every ancestor of the active row reads as active), and
- * **Breadcrumbs render** it. Computing "where am I" twice, in two components, is how the two
- * end up disagreeing about it.
- */
 export declare function findNavTrail(items: NavItem[], id: string | null | undefined): NavItem[];
-/** Depth-first list of every item, groups included. */
 export declare function flattenNav(items: NavItem[]): NavItem[];
-/**
- * Drop items a predicate rejects, pruning branches bottom-up.
- *
- * A parent whose children are ALL removed is removed too — unless it is reachable in its own
- * right (it has an `href` or is a `group`). Otherwise a permission filter leaves behind
- * headings that expand to nothing.
- */
 export declare function filterNav(items: NavItem[], keep: (item: NavItem) => boolean): NavItem[];
-/** The ids on the trail to `activeId`, for "is this row on the active path" checks. */
 export declare function navTrailIds(items: NavItem[], activeId: string | null | undefined): Set<string>;
-/**
- * The item whose `href` best matches a pathname — longest match wins, so
- * `/reports/monthly/sales` prefers that over `/reports`.
- *
- * For apps that track location rather than an id. Returns null when nothing matches; callers
- * that know their active id should pass it directly instead.
- */
 export declare function findNavItemByPath(items: NavItem[], pathname: string): NavItem | null;

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

@@ -1,6 +1,5 @@
 export type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
 export type PopoverAlign = 'start' | 'center' | 'end';
-/** `side` plus optional alignment, e.g. `bottom-start`. Bare `bottom` means `bottom-center`. */
 export type PopoverPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
 export interface PopoverRect {
     top: number;
@@ -9,9 +8,7 @@ export interface PopoverRect {
     height: number;
 }
 export interface ComputePopoverPositionInput {
-    /** Trigger box in VIEWPORT coordinates — i.e. straight from getBoundingClientRect(). */
     anchor: PopoverRect;
-    /** Measured content box. Pass zeroes on the first pass; re-run once it is measured. */
     content: {
         width: number;
         height: number;
@@ -20,38 +17,43 @@ export interface ComputePopoverPositionInput {
         width: number;
         height: number;
     };
-    /** Page scroll, added to the result so the caller can position in DOCUMENT coordinates. */
-    scroll: {
+    scroll?: {
+        x: number;
+        y: number;
+    };
+    origin?: {
         x: number;
         y: number;
     };
     placement?: PopoverPlacement;
-    /** Gap between anchor and content, px. Default 4. */
     offset?: number;
-    /** Force the content to the anchor's width (what a Select dropdown wants). */
     matchAnchorWidth?: boolean;
-    /** Flip to the opposite side when the preferred one doesn't fit. Default true. */
     flip?: boolean;
-    /** Slide along the cross axis to stay on screen. Default true. */
     shift?: boolean;
-    /** Minimum gap from the viewport edge, px. Default 8. */
     padding?: number;
 }
 export interface PopoverPosition {
-    /** DOCUMENT coordinates — scroll already added. */
     top: number;
     left: number;
-    /** Only set when `matchAnchorWidth`. */
     width?: number;
-    /** Where it actually ended up, which may differ from the request after a flip. */
     placement: PopoverPlacement;
-    /** True when `flip` changed the side. Useful for pointing an arrow the right way. */
     flipped: boolean;
 }
-/**
- * Where to put a floating box relative to its anchor.
- *
- * Returns DOCUMENT coordinates (viewport rect + scroll), because a portalled layer is
- * positioned absolutely against the page, not the viewport.
- */
 export declare function computePopoverPosition(input: ComputePopoverPositionInput): PopoverPosition;
+export interface FloatingFrameMeasure {
+    rect: {
+        top: number;
+        left: number;
+    };
+    clientTop: number;
+    clientLeft: number;
+    scrollTop: number;
+    scrollLeft: number;
+}
+export declare function floatingOrigin(frame: FloatingFrameMeasure | null, pageScroll: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};

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

@@ -1,54 +1,19 @@
 import type { FieldSize, FieldVariant, SelectOption, GroupConfig } from '../../../published/dcs-ui/src/publicTypes';
-/**
- * Class keys for the shared option-list surface (styles/popupList.module.css),
- * used by both Select's dropdown and Suggest's suggestion list.
- */
 export interface PopupListClassOptions {
     size: FieldSize;
     variant: FieldVariant;
 }
-/**
- * The popup takes its shape from the field it hangs off:
- *
- * - `outlined` / `filled` have a box, so the list **joins** it — no top border,
- *   square top corners, flush against the field's lower edge.
- * - `standard` / `underlined` have only a rule under the text, so a box glued to
- *   that edge reads as a mistake. Those get a **floating** panel instead: closed
- *   border, all corners rounded, sitting just below the underline.
- */
-/**
- * Does this variant's field have a box the popup can continue?
- *
- * Exported because BOTH sides of the joint need the same answer: the list squares its top
- * (here) and the control squares its bottom (buildFieldControlClassKeys). Deciding it twice is
- * how you get a rounded control meeting a square list.
- */
 export declare const isJoinedPopupVariant: (variant: string | undefined) => boolean;
 export declare function buildPopupListClassKeys(opts: PopupListClassOptions): string[];
 export interface PopupRowClassOptions {
-    /** The keyboard/hover cursor is on this row. Neutral fill. */
     isCursor?: boolean;
-    /** This row is the current value. Accent tint + tick. */
     isSelected?: boolean;
     isDisabled?: boolean;
-    /** Multi-select rows carry a checkbox, so the tick is suppressed. */
     isMulti?: boolean;
 }
 export declare function buildPopupRowClassKeys(opts: PopupRowClassOptions): string[];
-/** One rendered group: its heading and the options under it. */
 export interface OptionGroup {
     name: string;
     options: SelectOption[];
 }
-/**
- * Splits options into ordered groups for a grouped list.
- *
- * Order: `groupOrder` if given (array = explicit order, function = comparator),
- * otherwise first-appearance order, which keeps a hand-written options array
- * rendering in the order it was written. Options with no group are emitted first
- * under an empty name so the caller can render them without a heading.
- *
- * Returns a single unnamed group when grouping is off, so callers have one shape
- * to render either way.
- */
 export declare function groupSelectOptions(options: SelectOption[], config?: GroupConfig): OptionGroup[];