@nivaro/react 0.1.33 → 0.1.34

package/dist/index.d.ts

@@ -58,6 +58,8 @@ export declare interface ApiVersionInfo {
     environment?: string;
 }
 
+declare type BinaryOp = '+' | '-' | '*' | '/' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '&&' | '||';
+
 export declare function BooleanField({ field, value, onChange, error, disabled, readOnly, inputId, errorId }: FieldComponentProps): JSX.Element;
 
 export declare function canOpenChatRoom(): boolean;
@@ -72,6 +74,7 @@ declare interface ChannelMeta {
     role: string | null;
     topic: string | null;
     created_by: string | null;
+    is_direct?: boolean;
 }
 
 export declare function chatAvatarColor(id: string): string;
@@ -122,25 +125,6 @@ export declare interface ChatConfig {
 
 export declare function chatInitials(name: string | null): string;
 
-/**
- * Nivaro chat — data layer.
- *
- * Messages, rooms and watermarks go through /api/chat, NOT plain /items: room
- * visibility (your DMs, the channels you belong to, entity rooms for records
- * you can read) cannot be expressed as a table-level policy, and the items API
- * now refuses these collections outright. Presence/typing stay on /items,
- * which is per-user by nature. Live delivery comes from a host-provided
- * realtime adapter, with polling fallbacks baked into every query.
- *
- * Ported from the EFP implementation with its semantics preserved:
- * - DM room keys are 'dm:<A>:<B>' with UPPERCASED sorted uuids (MSSQL returns
- *   uuids uppercased — a casing mismatch forks a second room).
- * - Read watermarks are serialized per room (markInFlight) because the reads
- *   table has UNIQUE(user, room) and the room view marks on entry AND on each
- *   new message — concurrent select-then-insert would 500 on duplicate key.
- * - Mentions store '@[Display Name]' with no id; notifications fire only for
- *   users picked from the autocomplete.
- */
 export declare interface ChatMessage {
     id: number;
     sender: string;
@@ -148,6 +132,10 @@ export declare interface ChatMessage {
     room: string;
     message: string;
     date_created: string;
+    edited_at?: string | null;
+    deleted_at?: string | null;
+    attachments?: string[];
+    reactions?: ChatReaction[];
 }
 
 export declare interface ChatOnlineUser {
@@ -204,12 +192,39 @@ declare interface ChatProviderProps {
     theme?: Partial<ChatTheme>;
 }
 
-export declare function ChatRoomList({ rooms, onOpen }: {
+/**
+ * Nivaro chat — data layer.
+ *
+ * Messages, rooms and watermarks go through /api/chat, NOT plain /items: room
+ * visibility (your DMs, the channels you belong to, entity rooms for records
+ * you can read) cannot be expressed as a table-level policy, and the items API
+ * now refuses these collections outright. Presence/typing stay on /items,
+ * which is per-user by nature. Live delivery comes from a host-provided
+ * realtime adapter, with polling fallbacks baked into every query.
+ *
+ * Ported from the EFP implementation with its semantics preserved:
+ * - DM room keys are 'dm:<A>:<B>' with UPPERCASED sorted uuids (MSSQL returns
+ *   uuids uppercased — a casing mismatch forks a second room).
+ * - Read watermarks are serialized per room (markInFlight) because the reads
+ *   table has UNIQUE(user, room) and the room view marks on entry AND on each
+ *   new message — concurrent select-then-insert would 500 on duplicate key.
+ * - Mentions store '@[Display Name]' with no id; notifications fire only for
+ *   users picked from the autocomplete.
+ */
+declare interface ChatReaction {
+    emoji: string;
+    user: string;
+    user_name: string | null;
+}
+
+export declare function ChatRoomList({ rooms, onOpen, onNewGroup }: {
     rooms: RoomInfo[];
     onOpen: (room: RoomInfo) => void;
+    /** Opens the group-conversation composer (host renders the dialog). */
+    onNewGroup?: () => void;
 }): JSX.Element;
 
-export declare function ChatRoomView({ room, label, onBack, onOpenSettings, renderMessageBody }: {
+export declare function ChatRoomView({ room, label, onBack, onOpenSettings, renderMessageBody, initialUnread }: {
     room: string;
     label: string;
     onBack: () => void;
@@ -218,6 +233,8 @@ export declare function ChatRoomView({ room, label, onBack, onOpenSettings, rend
     renderMessageBody?: (m: ChatMessage, ctx: {
         mine: boolean;
     }) => React.ReactNode;
+    /** Unread count at open — anchors the "New messages" divider. */
+    initialUnread?: number;
 }): JSX.Element;
 
 /**
@@ -461,6 +478,88 @@ export declare function effectiveScopeSeedIds(scopes: {
     restricted: Record<string, Array<string | number>>;
 }, dimName: string): Array<string | number>;
 
+/** Boolean convenience — for guards and conditions. */
+export declare function evaluateBoolean(src: string, row: TokenResolver | Record<string, unknown>, opts?: EvaluateOptions): boolean;
+
+/** Parse and evaluate in one call. Returns null on a parse error. */
+export declare function evaluateExpression(src: string, resolve: TokenResolver | Record<string, unknown>, opts?: EvaluateOptions): ExprValue;
+
+/** Numeric convenience — the shape every existing call site wants. */
+export declare function evaluateNumeric(src: string, row: TokenResolver | Record<string, unknown>, opts?: EvaluateOptions): number | null;
+
+declare interface EvaluateOptions {
+    /**
+     * What an unresolvable or non-numeric token means in arithmetic.
+     * 'zero' (default) matches every existing dialect. 'null' propagates, so a
+     * formula over a missing field shows nothing rather than a wrong number.
+     */
+    missing?: 'zero' | 'null';
+}
+
+declare type ExprNode = {
+    kind: 'number';
+    value: number;
+} | {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'null';
+} | {
+    kind: 'token';
+    path: string;
+} | {
+    kind: 'call';
+    name: string;
+    args: ExprNode[];
+} | {
+    kind: 'unary';
+    op: '-' | '!';
+    operand: ExprNode;
+} | {
+    kind: 'binary';
+    op: BinaryOp;
+    left: ExprNode;
+    right: ExprNode;
+};
+
+/**
+ * One expression language for the `{{token}}` formulas users author.
+ *
+ * Nivaro grew five separate arithmetic dialects — inline-grid client formulas,
+ * QueryTable column formulas, match-agg column formulas, allocate-drawer
+ * formulas and rollup value formulas — each with its own parser, its own token
+ * regex and its own failure behaviour. A user cannot tell which box takes which
+ * syntax, and every one of them shared the same two defects:
+ *
+ *   1. They SUBSTITUTED token values into the string and then parsed (or, in
+ *      two cases, `eval`ed) the result. A value that is not a bare number —
+ *      a negative, a date, a string, anything — corrupted the expression into
+ *      something that either threw or, worse, silently computed a different
+ *      sum than the author meant.
+ *   2. A missing or non-numeric token became `0` with no signal, so a formula
+ *      referencing a field that had been renamed quietly produced a plausible
+ *      wrong number instead of an error.
+ *
+ * This module parses to an AST once and evaluates against a resolver, so a
+ * token's VALUE is never able to change the SHAPE of the expression. It also
+ * separates the two questions those dialects conflated: "is this expression
+ * well-formed" (answerable at authoring time, which is what makes an editor
+ * possible) from "what does it evaluate to for this row".
+ *
+ * `missing: 'zero'` is the DEFAULT and preserves the existing behaviour that
+ * live formulas depend on — `{{amount}} - {{allocated_total}}` must keep
+ * working when nothing has been allocated yet. `missing: 'null'` opts into
+ * propagation for new call sites that would rather show nothing than a wrong
+ * number.
+ */
+export declare type ExprValue = number | string | boolean | null;
+
+/** Field paths an expression reads, without evaluating it. */
+export declare function extractExpressionTokens(src: string): string[];
+
 declare type Fetcher = () => Promise<ApiVersionInfo | null>;
 
 export declare function fetchSchema(client: NivaroClient, collection: string, includeHidden: boolean, layoutId?: number, layoutSlug?: string): Promise<FormSchema>;
@@ -639,6 +738,50 @@ export declare type FormStatus = {
     canSubmit: boolean;
 };
 
+/**
+ * Authoring surface for `{{token}}` formulas.
+ *
+ * The point is that a formula can be wrong in three distinct ways, and until
+ * now none of them said anything: a syntax error rendered as a blank cell, a
+ * renamed field silently became zero, and the author could not see what the
+ * expression actually produced without saving and going to look. Each gets its
+ * own signal here — a parse error with a caret position, an unknown-field
+ * warning, and a live result computed against a real record.
+ */
+export declare function FormulaEditor({ value, onChange, fields, sample, sampleLabel, placeholder, rows, serverEvaluated, className }: FormulaEditorProps): JSX.Element;
+
+export declare interface FormulaEditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    /** Fields offered by autocomplete and checked against for typos. */
+    fields: FormulaField[];
+    /**
+     * A record to evaluate against, so the author sees the answer rather than
+     * guessing. Omitted = no preview, which is honest rather than showing a
+     * result computed from nothing.
+     */
+    sample?: Record<string, unknown> | null;
+    /** Labels the preview, e.g. the id of the record it was computed from. */
+    sampleLabel?: string;
+    placeholder?: string;
+    rows?: number;
+    /**
+     * Set for formulas the SERVER evaluates (stored rollups, write-computed
+     * fields). The preview is then explicitly labelled as an approximation,
+     * because the server resolves relations this editor cannot see.
+     */
+    serverEvaluated?: boolean;
+    className?: string;
+}
+
+export declare interface FormulaField {
+    /** Token path, e.g. `amount` or `line.total`. */
+    field: string;
+    label?: string;
+    /** Shown in the picker so an author can tell a currency from a count. */
+    type?: string;
+}
+
 /** A single validation rule attached to a field. */
 export declare type FormValidationRule = {
     type: string;
@@ -843,7 +986,7 @@ declare type ItemEditAuthContextValue = {
     userId: string;
 };
 
-export declare function ItemEditForm({ collection, itemId: itemIdProp, layoutSlug, onBack, onSaved, onDeleted, showHeader, showItemActions, showRevisions, showClone, showPipeline, showWorkflow, showComments, showTasks, showLockBanner, className, headerClassName, renderField, extraTopContent, extraBottomContent, onHeaderWidgets, initialImportResult, initialValues, initialLinks, initialRows }: ItemEditFormProps): JSX.Element;
+export declare function ItemEditForm({ collection, itemId: itemIdProp, layoutSlug, onBack, onSaved, onDeleted, showHeader, showItemActions, onDuplicate, showRevisions, showClone, showPipeline, showWorkflow, showComments, showTasks, showLockBanner, className, headerClassName, renderField, extraTopContent, extraBottomContent, onHeaderWidgets, initialImportResult, initialValues, initialLinks, initialRows }: ItemEditFormProps): JSX.Element;
 
 export declare interface ItemEditFormProps {
     collection: string;
@@ -857,6 +1000,12 @@ export declare interface ItemEditFormProps {
      *  header toolbar. Off by default — the admin's ItemEdit page renders its
      *  own copy in the page header; headless hosts opt in. */
     showItemActions?: boolean;
+    /**
+     * When set, a Duplicate button renders on saved records. Receives a prefill
+     * object (plain scalar + M2O values; audit/auto-id/computed/alias fields
+     * excluded) — the host navigates to its new-record route with it.
+     */
+    onDuplicate?: (prefill: Record<string, unknown>) => void;
     showRevisions?: boolean;
     showClone?: boolean;
     showPipeline?: boolean;
@@ -1151,6 +1300,24 @@ export declare interface PageRendererWidget {
     config?: Record<string, unknown>;
 }
 
+export declare function parseExpression(src: string): ParseResult;
+
+declare interface ParseFailure {
+    ok: false;
+    error: string;
+    /** Zero-based index into the source where the problem is, for editor carets. */
+    position: number;
+}
+
+declare type ParseResult = ParseSuccess | ParseFailure;
+
+declare interface ParseSuccess {
+    ok: true;
+    ast: ExprNode;
+    /** Every distinct token path referenced, in first-appearance order. */
+    tokens: string[];
+}
+
 declare interface PendingTask {
     title: string;
     assignee: string | null;
@@ -1413,6 +1580,7 @@ export declare interface RoomInfo {
     lastMessage: ChatMessage | null;
     unread: number;
     muted: boolean;
+    notify_mode: 'all' | 'mentions';
     joined: boolean;
     channel: ChannelMeta | null;
 }
@@ -1514,6 +1682,8 @@ export declare function TextField({ field, value, onChange, error, disabled, rea
 
 export declare function TipLayer(): ReactPortal | null;
 
+declare type TokenResolver = (path: string) => unknown;
+
 /** Install the listeners. Safe to call more than once. */
 export declare function trackActivity(): void;
 
@@ -1739,6 +1909,7 @@ export declare function useSectionState(form: UseNivaroFormReturn, defaultCollap
 export declare function useSendChatMessage(room: string): UseMutationResult<void, Error, string | {
 text: string;
 mentions?: string[];
+attachments?: string[];
 }, unknown>;
 
 export declare function useSessionRecorder(options?: SessionRecorderOptions): void;
@@ -1755,6 +1926,23 @@ export declare function useUnreadChirp(totalUnread: number, rooms?: RoomInfo[]):
 
 export declare function useWatchFields(form: UseNivaroFormReturn, fields: string[]): Record<string, unknown>;
 
+/**
+ * Authoring-time check. The point of separating this from evaluation is that
+ * a formula can be told it is wrong while it is being written, instead of
+ * silently producing nothing at render time months later.
+ */
+export declare function validateExpression(src: string, knownFields?: string[]): ValidationResult;
+
+declare interface ValidationResult {
+    ok: boolean;
+    error?: string;
+    position?: number;
+    /** Every field the expression reads. */
+    tokens: string[];
+    /** Tokens not present in the supplied field list — probably typos or renames. */
+    unknownTokens: string[];
+}
+
 export declare function WorkflowPanel({ collection, item }: {
     collection: string;
     item: string;