SpreadsheetColumn extends DataGridColumn

Column controller for a Spreadsheet — extends DataGridColumn with a record-based editing API.

In a virtualized grid the cell for a given record may not be mounted (off-screen), so editing/paste operate on the record, not a live cell. Otherwise it mirrors Spreadsheet's column shape: input(record) builds a bound editor via Input, paste/parsePaste apply pasted values, clear empties.

Constructor


new SpreadsheetColumn(options)

options :


            
                Object

optional

attribute :


            
                string

optional

record key this column reads/writes

editable :


            
                boolean

optional

whether cells can be edited/pasted into

input :


            
                Object

optional

extra options merged into Input.create (e.g. dump/load)

contextMenu :


            
                function

optional

hook (menu, cell, column) to augment/replace the right-click menu

index :


            
                number

optional

0-based column position (assigned by the grid)

width :

optional

explicit column width (px number or CSS px string); falls back to the grid's default width when omitted

colspan :


            
                number

optional

number of grid tracks this column occupies. >1 splits the column into sub-tracks a cell can address (e.g. via grid-template-columns: subgrid) so its content aligns into aligned sub-columns across every row. Sub-tracks must be fixed px summing to width — see widths — so the px-based column geometry (offsets, selection, resize) stays in sync

widths :


            
                Array.<number>
                |
            
                string

optional

explicit sub-track widths for a colspan>1 column: a px-number array or a space-separated px string ([120,120,120] / "120px 120px 120px"). Their sum is the column's total width. Omit to split width evenly across colspan tracks

frozen :


            
                boolean

optional

pin this column to the left while the body scrolls

header :

optional

header content; function receives (column, grid)

render :


            
                function

optional

cell content renderer; receives (record, cell, column, grid)

value :


            
                function

optional

optional override for the copy/serialized value; receives (record, column). Defaults to the render result.

class :


            
                string

optional

extra class(es) applied to header + cells

unnest :


            
                function

optional

expand the record's nested collection into stacked sub-rows for this cell (SQL UNNEST/explode). A function (record) => Array returning the sub-records to stack (read-only display in v1)

splitInto :


            
                function

optional

deprecated alias for unnest

record :


            
                function

optional

resolve the record this column reads/writes from the row's record (e.g. a row TIM → its Trait). A function (rowRecord) => record | Promise<record>. When omitted the column operates on the row's record directly. renderContent/valueFor and (for Spreadsheet) input/paste/clear/toggle all operate on the resolved record.

Instance Properties


inputOptions

Extra Input.create options merged into every editor (override per type, e.g. number dump).


inputType

Input kind passed to Input.create; overflow-friendly rich text by default (mirrors Spreadsheet).


pasteAccepts

MIME types this column accepts on paste, most preferred first — a column that lists 'text/html' before 'text/plain' is handed the pasted HTML (e.g. a <td>'s innerHTML) when the clipboard carried a matching HTML table, falling back to 'text/plain' otherwise (see Spreadsheet#pasteMatrixAt).

Instance Methods


cellAt()

A CellHandle for this column at a 0-based row index (or null).


cellHandles()

CellHandles for this column across the whole dataset (lazy, transient).


clear()

Clear the record's value.


configuredWidth()

The configured width in px (parsed), or defaultWidth when unset/invalid.


contextMenu(menu, cell, column)
    
    
    
        →
        
            
                
                    HTMLElement

Per-column customization of the right-click context menu (mirrors Spreadsheet). Receives the built menu element and returns the (possibly augmented or replaced) menu. Defaults to returning the menu unchanged; supply a contextMenu option to override.

Parameters

menu :


            
                HTMLElement

cell :


            
                SpreadsheetCell

column :


            
                SpreadsheetColumn

Returns


                        
                            HTMLElement


gridColumn()

The grid-column value placing this column: its 1-based start line, spanning colspan tracks. startLine is assigned by the grid (prefix-sum of colspans); falls back to index + 1 before assignment.


headerContent()

Resolve header content.


input(record, session)
    
    
    
        →
        
            
                
                    HTMLElement
                    |
                
                    null

Build the bound edit control for a record (mirrors Spreadsheet via Input.create). The returned element is two-way bound to record[attribute] — edits write back on change/blur — and is shown in a Floater over the cell. Returns null when the column isn't editable.

Custom editors can take over completion via the session (see Spreadsheet#activateCell):

keep a key for yourself (e.g. Enter for newlines in a textarea) by calling stopPropagation() or preventDefault() on its keydown
call session.commit({ move }) / session.cancel() to end the edit, or session.hold(promise) to defer the closing re-render until async work settles

Pick what you need off the session — don't spread it into Input/element options, where its members would become HTML attributes on the editor.

Parameters

record :


            
                Object

session :


            
                Object

optional

editing session: { cell, column, record, floater, value, commit, cancel, hold } (value is the typed character seeding a type-to-edit)

Returns


                        
                            HTMLElement
                            |
                        
                            null


parsePaste(value, type)

Parse a pasted/typed string into the stored value. Override per type.

Parameters

value :


            
                string

type :


            
                string

optional

the MIME type value was pasted as (see SpreadsheetColumn#pasteAccepts); a column that accepts more than one type can branch on it (e.g. pull a data-id back out of pasted text/html).


paste(record, value, type)

Apply a pasted value to the record.

Parameters

record :


            
                Object

value :


            
                string

type :


            
                string

optional

which MIME representation value is, chosen by Spreadsheet#pasteMatrixAt from the column's pasteAccepts — forwarded to parsePaste.


renderAttribute()

Fallback used by DataGridColumn#renderContent when no render is configured: reads attribute off the record as-is. A column type overrides this (rather than renderContent) to format that value (e.g. a date column formatting a Date) while still being reachable by a caller-supplied render that wants the type's default formatting for a value it computed itself.


renderContent()

Resolve the display content for a record (string / node / dolla descriptor).


resizeTrack()

Resize sub-track i to size, taking the difference from its right neighbor so the column's total width is unchanged (redistribute within the column). Both are clamped to min. Materializes explicit widths from the current sizes first, so it works on default-split columns too. No-op without a right neighbor.


resolveRecord()

Resolve the record this column reads/writes from the row's record. With a record resolver a cell can edit a sub-record (e.g. a row TIM → its Trait) while the row stays the row record. Returns the row record unchanged when no resolver is set. May return a Promise (resolvers are often async); callers await as needed.


setWidth()

Set the column width, rescaling explicit widths proportionally so a resize of a multi-track column keeps its sub-track ratios. Default-split columns read width live, so setting it is enough.


totalWidth()

Total px width the grid geometry sizes this column at (sum of its tracks).


trackSizes()

The px sizes of the tracks this column contributes to the grid template: colspan tracks that sum to the column's width. Explicit widths win; otherwise the width is split evenly. Single-track columns yield [width].


valueFor()

Resolve the copy/serialized value for a record. Usually a string, but a column may instead return a MIME map (e.g. { 'text/plain': 'Ben Ehmke', 'text/html': '<span data-id="…">Ben Ehmke</span>' }) to carry a richer representation for copy/paste — see Spreadsheet#copyCells. A bare string is treated as { 'text/plain': value }.