Crate logisheets_rs

Expand description

§logisheets-rs

The Rust API for the LogiSheets spreadsheet engine: open, edit, recalculate and save .xlsx workbooks.

This crate is a facade. The engine lives in logisheets_controller, file I/O in logisheets_workbook, shared ids in logisheets_base; this crate re-exports what callers need so they depend on it alone. The optional rpc feature adds [rpc], the message protocol the browser WASM binding (logisheets_wasm_server) and the desktop host drive the engine through.

§Quick start

use logisheets_rs::{CellInput, EditAction, PayloadsAction, StatusCode, Workbook};

// A new workbook already holds one sheet, "Sheet1".
let mut wb = Workbook::new();

// Writes are transactions of payloads. Content is parsed like typed
// input: "1" is a number, "=A1*2" a formula.
let action = PayloadsAction::new()
    .add_payload(CellInput { sheet_idx: 0, row: 0, col: 0, content: "1".into() })
    .add_payload(CellInput { sheet_idx: 0, row: 1, col: 0, content: "=A1*2".into() })
    .set_undoable(true);
let effect = wb.handle_action(EditAction::Payloads(action));
if let StatusCode::Err(_) = effect.status {
    panic!("rejected: {:?}", effect.error_message);
}

// Formulas recalculate as part of the write.
let value = wb.get_sheet_by_idx(0).unwrap().get_value(1, 0).unwrap();

// Round-trip through .xlsx bytes.
let bytes = wb.save().unwrap();
let reopened = Workbook::from_file(&bytes, "book.xlsx".to_string()).unwrap();

§Contracts worth knowing

Coordinates are 0-based: row: 0, col: 0 is A1. A sheet_idx is a sheet’s current position and shifts when sheets are added or removed; a SheetId is stable. Cells, rows and columns likewise have stable ids (CellId, RowId, ColId) that survive inserts and deletes.
A rejected write is not an Err. handle_action always returns an ActionEffect; check its status. A rejected transaction applies none of its payloads, and error_message names the one it stopped at.
Payloads run in order, each seeing the previous ones’ effects, so a write to B4 before an InsertRows lands on a different cell than after.
undoable defaults to false on PayloadsAction::new; call set_undoable(true) for a write the user should be able to undo.
The temp branch is workbook-wide. handle_action_in_temp_status opens one branch that later temp writes accumulate on until commit_temp_status or clean_temp_status; any non-temp write discards it. Check is_in_temp_mode before opening one of your own.
Reads return Result with Error; the RPC layer flattens that to ErrorMessage.

Structs§

ActionEffect: ActionEffect represents the result of handling an EditAction.
Alignment
AppData
Appendix: Appendix is one of the craft extensions.
AppendixWithCell
AsyncFuncResult: The results of the tasks which are passed to JS side to calculate previously.
AxisScaleUpdate: An axis’ scale. Every field None/false is a fully automatic axis, which is Excel’s default.
BindFormSchema
BindRandomSchema
BlockCellId: A cell inside a block. row/col are the BLOCK’s own line ids, not the sheet’s, so they stay valid when the block moves or its lines reorder.
BlockCellInfo
BlockDataRow: One exported block row: the field values in schema (column) order. Wrapping the row in a struct keeps the exported matrix as BlockDataRow[] rather than a nested Value[][], which the TS binding generator can’t render.
BlockDisplayInfo: A block with its on-sheet rectangle (CellPosition units; end is the far corner of its bottom-right cell).
BlockField
BlockInfo
BlockInput: CellInput addressed inside a block: row/col are 0-based offsets from the block’s top-left. Input to a cell whose field has a value template is dropped; the template computes it.
BlockLineNameFieldUpdate
BlockLineStyleUpdate
BlockModifyInfo: Read-only view of a block’s frontend-runtime write policy. Returned by Workbook::get_block_modify_info so the JS validate hook can decide whether a caller is allowed to write to a given block.
BlockOpForPayload: One entry of the payload → operation table.
BlockOpPolicy: What a block declares for one operation, beyond whether a given actor is allowed.
BlockPermissions: Per-operation overrides of a block’s ModifyPolicy.
BlockSchema
BlockSchemaRandomEntry
BlockSortOrder: The result of computing a block sort: which axis to permute and the new order of the current line indices.
CellClear: Empty a cell: its value and formula go, and dependents recalculate.
CellCoordinate: A 0-based grid position. Note the axis naming: x is the COLUMN and y is the ROW.
CellCoordinateWithSheet
CellFormatBrush: Format painter: copy one cell’s style onto every cell of the inclusive rectangle dst_row_start..=dst_row_end x dst_col_start..=dst_col_end.
CellImageInfo: An image placed in a cell. data is the base64-encoded image bytes and format is the bare file extension (e.g. png). Used by the frontend to render the image on the canvas at the cell’s position.
CellInfo: Everything a renderer needs about one cell.
CellInput: Take the content as input to the cell. The type of the content can be referred automatically.
CellPosition: An offset from the sheet’s top-left corner, in Excel’s native units, which DIFFER per axis: y sums row heights in points, x sums column widths in character-width units. Neither is pixels; hosts convert each axis separately (the engine UI uses ptToPx / widthToPx).
CellRefRange: A reference (a cell or range) resolved to a concrete rectangle, as used by the dependency-tracking API. start == end with neither all_rows nor all_cols set ⇒ a single-cell reference.
CellStyleUpdate: Apply a partial style change to one cell.
CfRuleInfo: One conditional-formatting rule as a UI would show it: an id to act on, a human-readable range, a preview of the format, and the spec to load into an editor and send back via UpdateConditionalFormattingRule.
ChartAxisScaleInfo: An axis’ scale as it will be drawn. All-None/false is a fully automatic axis, which is what most charts have.
ChartDataLabelsInfo: What a chart draws next to each data point. All-false means no labels.
ChartInfo: A chart anchored on a sheet, resolved for rendering. The anchor is its from/to cell positions plus EMU offsets into those cells; chart_type is one of col|bar|line|area|pie|doughnut|scatter|radar|bubble|stock|ofPie| barOfPie|surface|surface3d; legend_pos (if any) is top|bottom|left|right.
ChartOfPieSplitInfo: How a pie-of-pie / bar-of-pie divides its series between the two plots. Empty for every other chart kind.
ChartSeriesInfo: One data series of a chart, resolved for rendering. values holds the cached numeric values (gaps are null); the frontend re-reads live values from the source range and only falls back to these.
CheckpointManager: Session-scoped checkpoint store.
CheckpointMeta: Lightweight metadata returned by list. The full Status clone is kept inside the manager.
ColInfo
Comment: A comment thread anchored at a cell. notes is ordered (root first, then replies).
CreateAppendix: Attach an opaque craft-owned record to a block cell. row_idx/col_idx are 0-based within the block. Give sheet_idx or sheet_id; sheet_idx wins when both are set, and neither is rejected.
CreateBlock: Create a new block.
CreateDiyCell: Mark a block cell as host-rendered (“DIY”): the engine assigns it a DiyCellId and the host draws it. The cell must be inside a block.
CreateSheet: Insert a new, empty sheet.
DefineName: Create or replace a workbook-scoped defined name — TaxRate → 0.08, Sales → Sheet1!$B$2:$B$100.
DefinedNameInfo: A workbook-scoped defined name and what it refers to.
DeleteCellImage: Remove the image placed in a cell, if any.
DeleteCols: Column counterpart of DeleteRows.
DeleteColsInBlock
DeleteRows: Delete count sheet rows starting at start, with their cells. For rows inside a block use DeleteRowsInBlock.
DeleteRowsInBlock: Delete cnt block rows starting at start (0-based within the block). Only the block shrinks; the sheet’s rows are untouched.
DeleteSheet
DependentCell: One formula cell that depends on a queried range (Excel “trace dependents”), with the reference it used to reach that range.
DisplayWindow: Everything needed to paint a rectangle of the sheet. Hidden rows and columns are left out of rows/cols; merge_cells holds merges that intersect the window; blocks the blocks any included cell belongs to.
DisplayWindowRequest
DisplayWindowWithStartPoint
DuplicateBlockKey: One repeated key: which block, which value, and which records hold it.
EnumSetInfo: A named option list. Carries no colours — those are presentation and stay in the host, keyed by variant id.
EnumVariantInfo: One option: id is what the cell stores, label is what a reader sees.
EphemeralCellInput: CellInput for an ephemeral cell (see CellId::EphemeralCell): the cell is created on first write, can hold a formula that reads the sheet, and is never saved. sheet_idx is the sheet unqualified references in the formula resolve against.
ErrorMessage: A flattened error for hosts that cannot carry a Rust enum.
FieldValidationVerdict: What a proposed write would do to a cell’s validation rule.
FillRange: A rectangular block of cells, in row/col indices (0-based, inclusive).
FormulaDisplayInfo
InsertCols: Column counterpart of InsertRows.
InsertColsInBlock
InsertRows: Insert count empty rows so that the first new row sits at index start; the row previously at start moves down. References shift with the cells.
InsertRowsInBlock: Insert cnt block rows so the first lands at start (0-based within the block). Only the block grows; the sheet’s rows are untouched.
LineFormatBrush: Copy one cell’s style onto whole rows (row == true) or columns from..=to (inclusive). Sets the line style only; existing cells keep their own.
LineStyleUpdate: Apply a partial style change to whole rows (row == true) or columns from..=to (inclusive). Where a line crosses a styled column (or row), the change is also written onto that intersection cell, whose own style would otherwise win.
LinkInfo: A range that is linked to a backing block: the source range (the cells the user references, e.g. A1:A10) resolved to sheet coordinates, plus the block id it redirects to. The app draws an outer border around the source range.
MergeCell
MergeCells: Merge the inclusive rectangle. Both corners must be ordinary (non-block) cells. Overlap with an existing merge is not checked.
MoveBlock: Move a block so its top-left corner lands at the new sheet position. Its cells keep their BlockCellIds, so formulas follow it.
OfPieSplitUpdate: The division between an of-pie chart’s two plots.
PatternFill
PayloadsAction: A PayloadsAction contains one or more EditPayload. These EditPayloads will be withdrawn at the same time if user undo it. And if one of the payload is failed to be executed, this EditAction will not do anything at all.
PivotExcelNote: Whether a pivot survives a save to .xlsx as a REAL Excel pivot table.
PivotPlan: The shape a pivot should have, what it has, and the difference.
PivotSpecParts: A pivot’s recipe in its flat form. Re-exported here because block_manager is private to this crate, and both the RPC layer and any embedder need to name the type to declare a pivot. [PivotSpec] flattened for transport — the wire and on-disk form, in one shape, the way [FieldTypeParts] is for a field type.
RemoveBlock: Delete a block with its cells and schema. Analysis blocks that analyse it are removed in the same transaction.
RemoveName: Delete a defined name. Formulas that still use it evaluate to #NAME?, and come back to life if the name is defined again.
RenameName: Rename a defined name. Formulas that use it follow the rename — they hold the name’s id, not its spelling.
ReproduceCells
ReproducibleCell
ResizeBlock: Change a block’s record/field counts. None keeps that dimension.
RowInfo
SaveFileResult: The .xlsx bytes of a saved workbook. A save that produced none comes back as an ErrorMessage, so there is no status code to check.
SetBlockDescription: Rewrite a block’s prose description, or clear it with an empty string.
SetBlockPermissions: Replace a block’s per-operation policies, and optionally its default one.
SetCellImage: Place an image inside a cell. The image fills the cell and resizes with it. data is the base64-encoded image bytes; format is the image format (e.g. png, jpeg); image_id is a stable, workbook-unique identifier chosen by the caller (used to name the media part on save).
SetColWidth: Set a custom column width, in Excel character-width units (the default is 8.43), not pixels.
SetRowHeight: Set a custom row height, in points (Excel’s unit; the default is 15).
SetSheetColor: Set a sheet’s tab color.
SetSheetVisible: Hide or show a sheet tab.
ShadowCellInfo: A shadow cell’s value and the rectangle of the cell it shadows (CellPosition units).
SheetCellId: A cell by stable ids, as reported in ActionEffect.
SheetCoordinate: A 0-based (row, col) position.
SheetDimension: The used extent of a sheet. max_row/max_col are the 0-based indices of the furthest stored cell (a styled blank counts); height/width are the offsets where that cell STARTS, in the units of Worksheet::get_cell_position. All zero for a sheet with no cells.
SheetInfo
SheetRename: Rename a sheet, found by old_name or else by idx.
SplitMergedCells: Unmerge the merge whose TOP-LEFT cell is (row, col). Any other cell, including one inside a merge, is a no-op.
Style: A cell’s style resolved for rendering: theme and indexed colors are already turned into RGBA Colors with tint applied.
StyleUpdateType: A partial style change: every Some field is applied, None fields keep the cell’s current value.
Task
TempCellChange: One cell that changed inside the active temp branch. old_value is what’s in the committed branch (the fork_status snapshot taken when temp mode began); new_value is what the cell holds right now in the live temp branch. Position is the current (post-temp) sheet row/col — block inserts may shift earlier rows downward, so even cells that didn’t have a direct write may surface here with shifted positions.
TempStatusDiff: Diff between the active temp branch and the committed branch. Returned by Workbook::get_temp_status_changes; empty when no temp branch is currently active.
UpsertFieldRenderInfo
Workbook: The engine’s public facade: one open workbook.
Worksheet: A read-only view of one sheet, borrowed from a crate::Workbook.

Enums§

AsyncErr
BasicError: Failures from the engine’s lookup and addressing layer. Every message says which addressing scheme a number belongs to — an index (a position, which moves) or an id (stable) — never just “sheet 3”, since confusing the two is what causes most of these. Where it happened comes from the context around it, not from here.
BlockActor: Who is asking to change a block.
BlockOp: The operations a block’s permissions can speak about separately.
BlockSchemaType
CellId: A cell’s stable identity. It does not change when rows or columns are inserted or deleted around the cell; ask the worksheet for its current position.
EditAction: EditAction represents your update behavior to the workbook.
EditPayload: EditPayload is the basic update unit of the Workbook. Developers can config their own EditAction (e.g. setting a button to create a table) to facilitate their users.
Error: Every failure the engine reports. A write never surfaces this directly: a rejected transaction is turned into ActionEffect::error_message, with the failing payload wrapped in PayloadFailed.
HorizontalAlignment
ModifyPolicy: Controls who is allowed to write to a block at the frontend runtime layer. Reads are always allowed regardless of policy.
ShadowKind: What a shadow cell is FOR. A single (sheet, cell) can now own multiple shadow ephemeral cells, one per kind — letting different host-side concerns (validation warnings, dynamic editability, future widgets) each register their own derived formula without colliding.
StBorderStyle
StPatternType: 18.18.55
StUnderlineValues: 18.18.85
StatusCode: Outcome of an action. Err’s code is always 1; the reason is in ActionEffect::error_message.
Value
VerticalAlignment

Traits§

Context: logisheets_base::errors::Context for this crate’s Error.

Functions§

from_hex_str: Parse an 8-digit ARGB hex string (no #) and apply an OOXML tint. Anything shorter yields a color with every channel None.
lex_and_fmt: Tokenize a formula for display (syntax highlighting and reference colouring). s is the body without the leading =. None when it does not lex; a trailing incomplete token is tolerated (see logisheets_lexer4fmt).
lex_success: Whether a formula body lexes. f must NOT carry the leading =. Lexing only: unknown functions, sheets and names still pass.
take_last_error: Take (and clear) the message of the most recent rejected action. Global to the process, not per workbook. Prefer ActionEffect::error_message, which carries the same text.

Type Aliases§

AsyncCalcResult
BlockId: Chosen by the caller when creating a block; unique within a sheet.
ColId: A column id; same scoping as RowId.
DiyCellId
Result
RowId: A row id, stable across inserts and deletes. Scoped to one sheet (or, inside a BlockCellId, to one block); not a position.
SheetId: A sheet’s stable id. Unlike a sheet_idx (tab position) it does not change when sheets are added, removed or reordered, and it is not reused after a sheet is deleted.
TextId: Index into the workbook’s shared-text table.

Crate logisheets_rs

Crate logisheets_rs Copy item path

§logisheets-rs

§Quick start

§Contracts worth knowing

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate logisheets_rs