@viewkitjs/views 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +571 -0
- package/README.md +5 -3
- package/dist/atoms/LoadMore.js +11 -1
- package/dist/atoms/RowMenu.js +5 -2
- package/dist/cells/cell-format.d.ts +3 -3
- package/dist/cells/cell-title.d.ts +1 -2
- package/dist/cells/cell-title.js +2 -2
- package/dist/cells/cell-values.js +6 -3
- package/dist/contract.d.ts +50 -9
- package/dist/contract.js +33 -5
- package/dist/display/converted.d.ts +19 -0
- package/dist/display/converted.js +12 -0
- package/dist/display/index.d.ts +1 -0
- package/dist/display/index.js +1 -0
- package/dist/display/link-click.d.ts +11 -0
- package/dist/display/link-click.js +3 -0
- package/dist/display/link.js +7 -3
- package/dist/display/multi-value.d.ts +1 -1
- package/dist/display/multi-value.js +1 -1
- package/dist/display/options.d.ts +7 -1
- package/dist/display/phone.js +3 -1
- package/dist/editors/ChipsEditor.d.ts +9 -4
- package/dist/editors/ChipsEditor.js +6 -2
- package/dist/editors/DateEditor.d.ts +21 -6
- package/dist/editors/DateEditor.js +118 -30
- package/dist/editors/EditorPanel.d.ts +61 -0
- package/dist/editors/EditorPanel.js +54 -0
- package/dist/editors/LocationEditor.d.ts +3 -0
- package/dist/editors/LocationEditor.js +14 -6
- package/dist/editors/NameEditor.d.ts +3 -0
- package/dist/editors/NameEditor.js +11 -7
- package/dist/editors/NumberEditor.d.ts +3 -0
- package/dist/editors/NumberEditor.js +6 -6
- package/dist/editors/RangeEditor.d.ts +16 -1
- package/dist/editors/RangeEditor.js +21 -5
- package/dist/editors/RelationEditor.d.ts +13 -28
- package/dist/editors/RelationEditor.js +17 -40
- package/dist/editors/RelationSetEditor.d.ts +53 -0
- package/dist/editors/RelationSetEditor.js +112 -0
- package/dist/editors/SelectEditor.d.ts +21 -3
- package/dist/editors/SelectEditor.js +55 -9
- package/dist/editors/TextEditor.d.ts +51 -0
- package/dist/editors/TextEditor.js +81 -0
- package/dist/editors/ValueListEditor.d.ts +3 -0
- package/dist/editors/ValueListEditor.js +4 -2
- package/dist/editors/edit-cores.d.ts +12 -9
- package/dist/editors/edit-cores.js +7 -6
- package/dist/editors/edit-session.d.ts +21 -11
- package/dist/editors/edit-session.js +19 -5
- package/dist/editors/keep-inside.d.ts +12 -0
- package/dist/editors/keep-inside.js +20 -0
- package/dist/editors/open-value.d.ts +21 -0
- package/dist/editors/open-value.js +36 -0
- package/dist/editors/open-values.d.ts +4 -0
- package/dist/editors/open-values.js +7 -0
- package/dist/editors/relation-kinds.d.ts +7 -0
- package/dist/editors/relation-kinds.js +21 -0
- package/dist/editors/relation-panel.d.ts +69 -0
- package/dist/editors/relation-panel.js +40 -0
- package/dist/field-row/FieldNoteLine.d.ts +14 -0
- package/dist/field-row/FieldNoteLine.js +14 -0
- package/dist/field-row/FieldRow.d.ts +73 -0
- package/dist/field-row/FieldRow.js +157 -0
- package/dist/field-row/FieldRowLane.d.ts +19 -0
- package/dist/field-row/FieldRowLane.js +11 -0
- package/dist/field-row/editors/RowChipsEditor.d.ts +11 -0
- package/dist/field-row/editors/RowChipsEditor.js +25 -0
- package/dist/field-row/editors/RowDateEditor.d.ts +16 -0
- package/dist/field-row/editors/RowDateEditor.js +18 -0
- package/dist/field-row/editors/RowEditor.d.ts +39 -0
- package/dist/field-row/editors/RowEditor.js +64 -0
- package/dist/field-row/editors/RowNameEditor.d.ts +4 -0
- package/dist/field-row/editors/RowNameEditor.js +15 -0
- package/dist/field-row/editors/RowNumberEditor.d.ts +12 -0
- package/dist/field-row/editors/RowNumberEditor.js +18 -0
- package/dist/field-row/editors/RowPlaceEditor.d.ts +8 -0
- package/dist/field-row/editors/RowPlaceEditor.js +18 -0
- package/dist/field-row/editors/RowRangeEditor.d.ts +4 -0
- package/dist/field-row/editors/RowRangeEditor.js +15 -0
- package/dist/field-row/editors/RowRelationEditor.d.ts +20 -0
- package/dist/field-row/editors/RowRelationEditor.js +77 -0
- package/dist/field-row/editors/RowSelectEditor.d.ts +13 -0
- package/dist/field-row/editors/RowSelectEditor.js +23 -0
- package/dist/field-row/editors/RowTextEditor.d.ts +15 -0
- package/dist/field-row/editors/RowTextEditor.js +16 -0
- package/dist/field-row/editors/RowValueListEditor.d.ts +4 -0
- package/dist/field-row/editors/RowValueListEditor.js +21 -0
- package/dist/field-row/editors/host.d.ts +59 -0
- package/dist/field-row/editors/host.js +1 -0
- package/dist/field-row/editors/row-session.d.ts +49 -0
- package/dist/field-row/editors/row-session.js +49 -0
- package/dist/field-row/index.d.ts +5 -0
- package/dist/field-row/index.js +5 -0
- package/dist/field-row/row-target.d.ts +20 -0
- package/dist/field-row/row-target.js +3 -0
- package/dist/field-row/useFieldWrite.d.ts +45 -0
- package/dist/field-row/useFieldWrite.js +190 -0
- package/dist/field-row/useRowSettlement.d.ts +33 -0
- package/dist/field-row/useRowSettlement.js +23 -0
- package/dist/fields/binding.d.ts +6 -1
- package/dist/fields/binding.js +13 -6
- package/dist/fields/edit-core-types.d.ts +9 -9
- package/dist/fields/edit-core-types.js +6 -6
- package/dist/fields/money.d.ts +5 -0
- package/dist/fields/money.js +10 -0
- package/dist/fields/number-edit.d.ts +6 -0
- package/dist/fields/number-edit.js +4 -0
- package/dist/fields/prepare-write.js +6 -1
- package/dist/fields/relation-source-types.d.ts +12 -0
- package/dist/fields/write-target.d.ts +50 -0
- package/dist/fields/write-target.js +10 -0
- package/dist/grid/chrome/GridAddColumn.js +1 -1
- package/dist/grid/chrome/GridAggregateMenu.d.ts +1 -1
- package/dist/grid/chrome/GridAggregateMenu.js +8 -6
- package/dist/grid/chrome/GridCellEditors.d.ts +7 -0
- package/dist/grid/chrome/GridCellEditors.js +87 -16
- package/dist/grid/chrome/GridCellOutline.d.ts +22 -43
- package/dist/grid/chrome/GridCellOutline.js +2 -7
- package/dist/grid/chrome/GridChipsEditor.d.ts +16 -6
- package/dist/grid/chrome/GridChipsEditor.js +21 -26
- package/dist/grid/chrome/GridColumnMenu.d.ts +1 -1
- package/dist/grid/chrome/GridColumnMenu.js +7 -3
- package/dist/grid/chrome/GridDateEditor.d.ts +23 -11
- package/dist/grid/chrome/GridDateEditor.js +13 -25
- package/dist/grid/chrome/GridFooter.d.ts +12 -2
- package/dist/grid/chrome/GridFooter.js +10 -6
- package/dist/grid/chrome/GridGroupMenu.js +20 -13
- package/dist/grid/chrome/GridHeader.d.ts +9 -4
- package/dist/grid/chrome/GridHeader.js +15 -10
- package/dist/grid/chrome/GridLongTextEditor.d.ts +28 -9
- package/dist/grid/chrome/GridLongTextEditor.js +16 -74
- package/dist/grid/chrome/GridNameEditor.d.ts +11 -6
- package/dist/grid/chrome/GridNameEditor.js +12 -27
- package/dist/grid/chrome/GridNumberEditor.d.ts +20 -6
- package/dist/grid/chrome/GridNumberEditor.js +46 -20
- package/dist/grid/chrome/GridPlaceEditor.d.ts +26 -0
- package/dist/grid/chrome/GridPlaceEditor.js +22 -0
- package/dist/grid/chrome/GridRangeEditor.d.ts +15 -5
- package/dist/grid/chrome/GridRangeEditor.js +16 -20
- package/dist/grid/chrome/GridRelationEditor.d.ts +38 -14
- package/dist/grid/chrome/GridRelationEditor.js +86 -24
- package/dist/grid/chrome/GridRow.d.ts +7 -1
- package/dist/grid/chrome/GridRow.js +57 -14
- package/dist/grid/chrome/GridRowActions.js +1 -1
- package/dist/grid/chrome/GridRowCells.js +18 -23
- package/dist/grid/chrome/GridSelectEditor.d.ts +19 -4
- package/dist/grid/chrome/GridSelectEditor.js +21 -27
- package/dist/grid/chrome/GridStructure.d.ts +9 -10
- package/dist/grid/chrome/GridStructure.js +10 -14
- package/dist/grid/chrome/GridTable.js +97 -30
- package/dist/grid/chrome/GridTableSurface.d.ts +39 -2
- package/dist/grid/chrome/GridTableSurface.js +12 -3
- package/dist/grid/chrome/GridTextEditor.d.ts +35 -1
- package/dist/grid/chrome/GridTextEditor.js +35 -37
- package/dist/grid/chrome/GridValueListEditor.d.ts +15 -3
- package/dist/grid/chrome/GridValueListEditor.js +10 -27
- package/dist/grid/chrome/cell-cut-off.d.ts +11 -0
- package/dist/grid/chrome/cell-cut-off.js +20 -0
- package/dist/grid/chrome/cells.js +1 -2
- package/dist/grid/chrome/checks.d.ts +2 -5
- package/dist/grid/chrome/checks.js +15 -5
- package/dist/grid/chrome/editors.d.ts +1 -1
- package/dist/grid/chrome/editors.js +1 -1
- package/dist/grid/chrome/grid-cell-classes.d.ts +2 -8
- package/dist/grid/chrome/grid-cell-classes.js +10 -8
- package/dist/grid/chrome/grid-cell-link.d.ts +13 -0
- package/dist/grid/chrome/grid-cell-link.js +9 -0
- package/dist/grid/chrome/grid-edit-session.d.ts +63 -0
- package/dist/grid/chrome/grid-edit-session.js +118 -0
- package/dist/grid/chrome/grid-hover.d.ts +60 -0
- package/dist/grid/chrome/grid-hover.js +81 -0
- package/dist/grid/chrome/grid-menu-focus.d.ts +43 -0
- package/dist/grid/chrome/grid-menu-focus.js +93 -0
- package/dist/grid/chrome/grid-row-menu-key.d.ts +15 -0
- package/dist/grid/chrome/grid-row-menu-key.js +36 -0
- package/dist/grid/chrome/grid-row-props.d.ts +16 -4
- package/dist/grid/chrome/grid-row-window.d.ts +61 -0
- package/dist/grid/chrome/grid-row-window.js +212 -0
- package/dist/grid/chrome/grid-scroll-owner.d.ts +38 -0
- package/dist/grid/chrome/grid-scroll-owner.js +75 -0
- package/dist/grid/chrome/grid-styles.d.ts +4 -1
- package/dist/grid/chrome/grid-styles.js +1 -0
- package/dist/grid/chrome/grid-table-props.d.ts +2 -3
- package/dist/grid/chrome/useGridFocus.d.ts +45 -0
- package/dist/grid/chrome/useGridFocus.js +122 -0
- package/dist/grid/chrome/useGridKeyboard.d.ts +21 -4
- package/dist/grid/chrome/useGridKeyboard.js +214 -38
- package/dist/grid/chrome/useGridRangeActions.d.ts +3 -1
- package/dist/grid/chrome/useGridRangeActions.js +17 -10
- package/dist/grid/chrome/useGridRangeGestures.js +68 -21
- package/dist/grid/chrome/useGridRowContextMenu.d.ts +4 -2
- package/dist/grid/chrome/useGridRowContextMenu.js +28 -2
- package/dist/grid/chrome/useGridScaleStyles.d.ts +3 -1
- package/dist/grid/chrome/useGridScaleStyles.js +6 -7
- package/dist/grid/chrome/useGridScrollArea.d.ts +21 -0
- package/dist/grid/chrome/useGridScrollArea.js +65 -0
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +28 -5
- package/dist/grid/chrome/useGridTableInteractionModel.js +66 -14
- package/dist/grid/chrome/useHeaderDragReorder.d.ts +2 -2
- package/dist/grid/core/clipboard-model.d.ts +2 -0
- package/dist/grid/core/clipboard-model.js +1 -1
- package/dist/grid/core/commit-model.d.ts +7 -0
- package/dist/grid/core/edge-scroll.d.ts +21 -0
- package/dist/grid/core/edge-scroll.js +23 -0
- package/dist/grid/core/editing-controller.d.ts +2 -1
- package/dist/grid/core/editing-controller.js +35 -9
- package/dist/grid/core/editing-model.d.ts +9 -0
- package/dist/grid/core/editing-model.js +12 -0
- package/dist/grid/core/flat-rows.d.ts +35 -0
- package/dist/grid/core/flat-rows.js +20 -0
- package/dist/grid/core/grid-aria.d.ts +27 -0
- package/dist/grid/core/grid-aria.js +39 -0
- package/dist/grid/core/grid-focus.d.ts +54 -0
- package/dist/grid/core/grid-focus.js +148 -0
- package/dist/grid/core/nav.d.ts +2 -2
- package/dist/grid/core/pending-reconciliation.d.ts +3 -0
- package/dist/grid/core/pending-reconciliation.js +5 -3
- package/dist/grid/core/row-window.d.ts +40 -0
- package/dist/grid/core/row-window.js +43 -0
- package/dist/grid/core/spreadsheet-operations.d.ts +17 -1
- package/dist/grid/core/spreadsheet-operations.js +33 -6
- package/dist/grid/core/useGridEditing.d.ts +3 -0
- package/dist/grid/core/useGridEditing.js +6 -3
- package/dist/grid/core/value-equality.d.ts +23 -1
- package/dist/grid/core/value-equality.js +46 -0
- package/dist/grid/useGridTablePrefs.d.ts +0 -1
- package/dist/grid/useGridTablePrefs.js +1 -3
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/internal/viewport.d.ts +0 -2
- package/dist/internal/viewport.js +0 -14
- package/dist/model/column-capabilities.d.ts +2 -1
- package/dist/model/column-capabilities.js +28 -8
- package/dist/model/column-from.js +3 -0
- package/dist/model/column-inspect.d.ts +10 -2
- package/dist/model/column-inspect.js +9 -0
- package/dist/model/column-schema.d.ts +6 -1
- package/dist/model/column-types.d.ts +3 -1
- package/dist/model/column-types.js +1 -1
- package/dist/model/preferences.d.ts +0 -4
- package/dist/model/preferences.js +0 -1
- package/dist/model/prefs-buckets.d.ts +0 -1
- package/dist/model/prefs-buckets.js +0 -3
- package/dist/model/render-count.d.ts +6 -0
- package/dist/model/render-count.js +11 -0
- package/dist/provider/ViewsProvider.d.ts +5 -1
- package/dist/provider/ViewsProvider.js +9 -3
- package/dist/provider/components.d.ts +19 -1
- package/dist/provider/components.js +4 -2
- package/dist/provider/context.d.ts +5 -2
- package/dist/provider/desktop.d.ts +9 -0
- package/dist/provider/desktop.js +22 -0
- package/dist/provider/plain-input.d.ts +8 -0
- package/dist/provider/plain-input.js +5 -0
- package/dist/react.d.ts +2 -1
- package/dist/react.js +1 -0
- package/dist/selection/SelectCheckbox.d.ts +3 -1
- package/dist/selection/SelectCheckbox.js +2 -2
- package/dist/selection/useCheckDragSelect.js +6 -5
- package/docs/contract.md +93 -35
- package/docs/guides/atoms.md +1 -1
- package/docs/guides/cells.md +2 -2
- package/docs/guides/columns.md +3 -2
- package/docs/guides/display.md +1 -0
- package/docs/guides/editors.md +71 -13
- package/docs/guides/the-grid.md +32 -13
- package/docs/guides/the-provider.md +3 -1
- package/docs/index.md +3 -1
- package/docs/install.md +1 -1
- package/docs/reference/cells.md +1 -1
- package/docs/reference/display.md +3 -1
- package/docs/reference/editors-chips.md +2 -2
- package/docs/reference/editors-date.md +3 -3
- package/docs/reference/editors-location.md +1 -1
- package/docs/reference/editors-number.md +1 -1
- package/docs/reference/editors-open-values.md +1 -0
- package/docs/reference/editors-panel.md +12 -0
- package/docs/reference/editors-range.md +1 -1
- package/docs/reference/editors-relation.md +6 -3
- package/docs/reference/editors-select.md +3 -2
- package/docs/reference/editors-session.md +4 -2
- package/docs/reference/editors-text.md +9 -0
- package/docs/reference/editors-value-list.md +1 -1
- package/docs/reference/editors.md +2 -2
- package/docs/reference/field-row.md +16 -0
- package/docs/reference/grid.md +3 -3
- package/docs/reference/react.md +8 -5
- package/docs/reference/views.md +36 -15
- package/package.json +23 -4
- package/skills/views/SKILL.md +4 -4
- package/dist/grid/chrome/useGridScrollSync.d.ts +0 -38
- package/dist/grid/chrome/useGridScrollSync.js +0 -176
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/session` in a client component: the door opens with the client directive. It holds the plumbing every host that opens an editor in a panel over a value repeats: the guard that lets a session answer once, and the gap that lets the popover's exit play before the value renders again behind it. A session that answers twice writes twice, and one that answers during its own exit unmounts the panel mid-flight. The host keeps its popover, its anchor, its focus and the shape of what it hands back. It is a door of its own so a host that needs the session does not load the editors. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `useAnchoredEditSession` — runs one edit session and returns `{ open, close }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts.
|
|
6
|
-
- Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns `
|
|
5
|
+
- `useAnchoredEditSession` — runs one edit session and returns an `EditSession`, `{ open, close, refusal }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts. Escape always discards: on `close("escape")` the session answers a cancel without asking the editor. On any other reason it asks the editor's `resolveClose(reason)` through `editorRef` (a `noop` when there is no editor) and passes a commit's value through `mapPayload`, which never sees a cancel or a noop. Then one of two modes:
|
|
6
|
+
- Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns an `EditSessionAttempt`. A refusal keeps the session open for another try, and its `reason` comes back as `refusal` until the next attempt; an acceptance closes it and calls `onClose` after the exit gap, a timer cleared if the host unmounts. While `onAttempt` runs the session counts as answered, so a close that arrives during it (a write that moves the focus, and a box that closes on blur) is ignored; a refusal, or an `onAttempt` that throws, opens it again for the next try.
|
|
7
7
|
- Deferred: the session closes at once and hands the answer to `onDone` after the exit gap, for a host whose answer still carries the write.
|
|
8
8
|
- Gap: `exitMs` sets it, defaulting to `EDITOR_EXIT_MS`.
|
|
9
|
+
- `EditSession` — what the session hands its host, and what `EditorPanel` (`@viewkitjs/views/editors/panel`) takes: `open`, `close(reason)`, and `refusal`, the reason the host gave for the last refused attempt until the next one, `null` otherwise and always in the deferred mode.
|
|
10
|
+
- `EditSessionAttempt` — the host's answer to an attempt: `{ accepted: boolean; reason?: string }`. A refusal may say why; the reason is what `refusal` shows.
|
|
9
11
|
- `EDITOR_EXIT_MS` — 160: the milliseconds an anchored host waits between closing its popover and reporting its answer, so the exit animation plays out first.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# `@viewkitjs/views/editors/text`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/editors/text` in a client component: the door opens with the client directive. It holds the one editor for every text-like value: `text`, `url`, `domain`, `email`, `phone` and `rich_text`, a line or a paragraph. It tidies what was typed (trimmed; rich text tidied only at its edges, with fields' `normalizeMarkdown`, so its first line keeps its indent), and an unchanged value closes as no save. It owns the box and what a close means; its host owns where it opens (in place, a popover, a sheet), the session and the write. It commits a string. Guide: [editors](../guides/editors.md#a-text-box).
|
|
4
|
+
|
|
5
|
+
- `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`.
|
|
6
|
+
- `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`, and `boxData` (`data-*` attributes set on the box, over its own slot).
|
|
7
|
+
- `TextEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Read-only answers `noop`; Escape cancels; otherwise the tidied draft against the tidied `initial`: equal is a `noop`, different a `commit` of the tidied draft.
|
|
8
|
+
- `TextEditorType` — the types it edits: `text`, `url`, `domain`, `email`, `phone`, `rich_text`.
|
|
9
|
+
- `TEXT_INPUT_TYPE` — the native input type per `TextEditorType`, the phone keyboard each brings: `text` and `rich_text` `text`, `url` and `domain` `url`, `email` `email`, `phone` `tel`.
|
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
|
|
3
3
|
Import from `@viewkitjs/views/editors/value-list` in a client component: the door opens with the client directive. It holds the editor of a field holding several values of one kind (a `multiple` email, phone, url or domain field), each with its label and one of them the main one. It is a draft, like the chips editor: the whole list commits once when the host closes it. It owns the rows, the reading of each value and what a close means; its host owns the popover, the anchor and the write. It commits a list of `ValueItem`s of `@viewkitjs/fields`, `{ value, label, main }`, the main one first, or null. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty
|
|
5
|
+
- `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
|
|
6
6
|
- `ValueListEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels; any other close keeps what was built. Blank rows are dropped. A row left untouched keeps its stored value exactly as stored, and a row typed in commits its trimmed text for the field's commit to read. With no main mark the first row is the main one. The same values, labels and main as opened is a `noop`; an empty list commits null with `allowEmpty` and cancels without it.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# `@viewkitjs/views/editors`
|
|
2
2
|
|
|
3
|
-
The table of editors, one per storage type. The door carries no client directive; each editor file behind it carries its own, and each editor also has a door of its own, which a host imports when it needs one editor and not the table. An editor owns its panel and what a close means. Its host (a grid cell, a form field, a drawer row, a card) owns the popover, the anchor, focus, when to commit, and the write. Every editor speaks the same handshake: when it sees a key or a pick that means done, it calls the host's `onRequestClose(reason)`; the host closes, then asks the editor's handle `resolveClose(reason)`, which answers `commit` with the value, `cancel` or `noop` (the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`). The words an editor draws come from the provider; an editor that takes `message` reads the fields messages from it instead. `hasEditCore`, documented with the root door, says whether a type
|
|
3
|
+
The table of editors, one per storage type. The door carries no client directive; each editor file behind it carries its own, and each editor also has a door of its own, which a host imports when it needs one editor and not the table. An editor owns its panel and what a close means. Its host (a grid cell, a form field, a drawer row, a card) owns the popover, the anchor, focus, when to commit, and the write. Every editor speaks the same handshake: when it sees a key or a pick that means done, it calls the host's `onRequestClose(reason)`; the host closes, then asks the editor's handle `resolveClose(reason)`, which answers `commit` with the value, `cancel` or `noop` (the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`). The words an editor draws come from the provider; an editor that takes `message` reads the fields messages from it instead. `hasEditCore`, documented with the root door, says whether a type has an editor of its own without loading any editor. Guide: [editors](../guides/editors.md).
|
|
4
4
|
|
|
5
|
-
- `EDIT_CORES` — the editor for each storage type, one member for every `FieldType`, so a type added to fields with no answer here fails to compile. `date` and `datetime` share `DateEditor`, `select` and `status` share `SelectEditor`, `multiselect` is `ChipsEditor`, `relation` and `user` share `RelationEditor`, `number`, `percent` and `currency` share `NumberEditor`, and `range`, `name` and `location` each have their own
|
|
5
|
+
- `EDIT_CORES` — the editor for each storage type, one member for every `FieldType`, so a type added to fields with no answer here fails to compile. `date` and `datetime` share `DateEditor`, `select` and `status` share `SelectEditor`, `multiselect` is `ChipsEditor`, `relation` and `user` share `RelationEditor`, `number`, `percent` and `currency` share `NumberEditor`, and `range`, `name` and `location` each have their own, and `text`, `url`, `domain`, `email`, `phone` and `rich_text` share `TextEditor`. A `null` member is a decision, not a gap: a `boolean` is edited by its checkbox, an `actor` is set by the system, and `lookup`, `rollup` and `formula` are read-only or derived. Each member is typed as its editor's props and handle, so binding the wrong editor is a type error. `ValueListEditor`, for a field holding several emails, phones, links or domains, has its own door and no member here.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# `@viewkitjs/views/field-row`
|
|
2
|
+
|
|
3
|
+
Import from `@viewkitjs/views/field-row` in a client component, under your `ViewsProvider`: the door opens with the client directive. It holds a record's field row: one field drawn as its label, its value and, on a click, its type's editor in place, and the write path that admits each edit at once, queues one record's writes, settles each on the save's receipt and rolls a failure back. The row knows no entity, only a binding, a value and a commit, so your app builds its record's panel (its sections, its related records) around the rows. It draws with your provider's `Popover`, `Sheet`, `Collapse`, `AppIcon`, icons, `CommandMenu` atom and toast port. The shapes its writes go through (the write target, the receipt, the admission, a value's note, the reconciliation error) are the root door's, described under [A write's target](views.md#a-writes-target), and this door re-exports them. Guide: [editors](../guides/editors.md).
|
|
4
|
+
|
|
5
|
+
- `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape always throws the edit away, and a sheet's swipe or ✕ changes nothing. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once a write still saving has saved and unless the focus moved meanwhile, so the next Tab moves on from that row; an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
|
|
6
|
+
- `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
|
|
7
|
+
- `RowEditor` — the editor a row mounts for its field's type, picked from `ROW_HOSTS`.
|
|
8
|
+
- `ROW_HOSTS` — the host each field type mounts in a row, or `null` for a type the row never opens (a boolean, a derived or system field).
|
|
9
|
+
- `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message` and `kindIcon`.
|
|
10
|
+
- `RowClosed` — what a host's close tells its row: `focusBack`, true when the editor closed from the keys or a pick off a sheet, and the row takes the focus back on its button.
|
|
11
|
+
- `RowEditorAttempt` — the row's answer to a close: `{ accepted: true }`, or `{ accepted: false, reason }`, which keeps the editor open.
|
|
12
|
+
- `RowHostProps` — a host's props: `RowEditorProps` plus the field narrowed to the host's types.
|
|
13
|
+
- `useFieldWrite` — the write path for one record: given `FieldWriteOptions`, it returns `commit(fieldKey, value)`, which answers a `FieldWriteAdmission` at once, and `row`, the latest confirmed row. A commit is refused at once when the guard, a pending reconciliation, the same field still saving, a lock or the binding refuses it. Writes to one record run one at a time, a queued one mapped again at dispatch against the latest row. A failed save toasts through your toast port and rejects, and `refresh` runs in the background after each save.
|
|
14
|
+
- `FieldWriteOptions` — `row`, `rowId`, `bindings`, `write` (an `EntityWriteTarget`), `refresh`, and optionally `locked`, `admit`, `conventions` (default: the provider's), `refusalOf` (reads a failed save's own sentence, shown after the toast's failure line and on the row) and `timing` (follows each edit from its commit to the paint, named `<noun> <fieldKey> drawer edit`).
|
|
15
|
+
- `EditTiming` — what `timing` returns: `mark(step)`, `painted()` and `failed()`.
|
|
16
|
+
- `FieldWriteRefusal` — the error a write rejects with when it is refused with a sentence of its own: by the server (the sentence `refusalOf` read), or at dispatch, when a queued edit is mapped again and the guard, a lock, a missing binding or the binding's write refuses it. The row shows its message.
|
package/docs/reference/grid.md
CHANGED
|
@@ -10,10 +10,10 @@ The spreadsheet. The door carries no client directive; every rendering file behi
|
|
|
10
10
|
- Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; the bar it opens is yours).
|
|
11
11
|
- Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
|
|
12
12
|
- Format overrides and their handlers, every map keyed by field key: `optionColors`, `dateStyles`, `durationStyles`, `numberFormats` (decimals null is the field's own), `showTimeOverrides` and `percentDisplays`, each with its `on…Change` handler taking the field key first, and `formatsWritable` (false hides the stored format knobs from the column menu; default true).
|
|
13
|
-
- Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, the grid's own lists the hidden columns), `renderColumnMenuRows` (your rows in a column's menu, above Hide), and the per-user toggles `freezeIdentity` (
|
|
13
|
+
- Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, the grid's own lists the hidden columns), `renderColumnMenuRows` (your rows in a column's menu, above Hide), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`.
|
|
14
14
|
- Writes: `onCellCommit` (`GridCellCommitFn`) and `onCellsCommit` (`GridCellsCommitFn`).
|
|
15
15
|
- List config: `listConfig` (the settings layer every user of the list inherits, which may only take away from what the columns declare: the table read-only, per-column locks; a constraint on the screen, while your API guards its own writes). The grid only reads it: a surface of your own changes it.
|
|
16
|
-
- `useGridTablePrefs` — wires a list's view preferences to the grid. It takes `prefs` (the list's `ListViewPrefs`), `setPrefs` (stores a patch of them), `columns` (whose money reading the number formats read) and `viewBacked`, and returns `{ gridProps }` to spread on `GridTable`: the borders, row icon, frozen identity,
|
|
16
|
+
- `useGridTablePrefs` — wires a list's view preferences to the grid. It takes `prefs` (the list's `ListViewPrefs`), `setPrefs` (stores a patch of them), `columns` (whose money reading the number formats read) and `viewBacked`, and returns `{ gridProps }` to spread on `GridTable`: the borders, row icon, frozen identity, checkboxes and scale, the format overrides, the column state, the group figures and the footer figures, each with the handler that writes it back through `setPrefs`.
|
|
17
17
|
|
|
18
18
|
## Sort, group and figures
|
|
19
19
|
|
|
@@ -28,7 +28,7 @@ The spreadsheet. The door carries no client directive; every rendering file behi
|
|
|
28
28
|
- `GridCellCommitFn` — writes one cell: `(row, columnId, value, context?)`, returning a promise of nothing or a `GridCommitOutcome`. Nothing counts as confirmed; a rejection rolls the cell back. `context` is present on an undo or a redo.
|
|
29
29
|
- `GridCellsCommitFn` — writes several cells at once (a paste, a fill, an undo of several): `(edits)`, each `{ row, columnId, value, context? }`, returning a promise of nothing or one outcome per edit, in order. A failed edit rolls its own cell back. Without it, or for a single cell, the grid calls `GridCellCommitFn` for each.
|
|
30
30
|
- `GridCommitContext` — what a write is: `{ kind: "commit" }`, with `reload: false` when the caller reloads once after a second write, or `{ kind: "restore", expected }`, an undo or a redo writing a value back, `expected` the value the cell is held to before it.
|
|
31
|
-
- `GridCommitOutcome` — how a write ended. `confirmed`, with an optional `history` (false keeps it out of undo, or `{ prev, next }` are the values undo and redo write instead)
|
|
31
|
+
- `GridCommitOutcome` — how a write ended. `confirmed`, with an optional `history` (false keeps it out of undo, or `{ prev, next }` are the values undo and redo write instead), `settlement` (`requested`: the row holds the value but its provider has not accepted it yet, and the cell says so) and `stored` (what was kept, when it isn't what the cell sent, as the row reads it in this column: the cell shows it in place of what was typed, undo and redo restore from it, and no "changed elsewhere" follows; ignored on an undo or a redo); `unconfirmed`, never in the undo history; or `failed`, with an optional `error`, which rolls the cell back.
|
|
32
32
|
|
|
33
33
|
## Helpers a binding shares
|
|
34
34
|
|
package/docs/reference/react.md
CHANGED
|
@@ -7,18 +7,20 @@ Import from `@viewkitjs/views/react` in a client component: the door opens with
|
|
|
7
7
|
Guide: [the provider](../guides/the-provider.md).
|
|
8
8
|
|
|
9
9
|
- `ViewsProvider` — the provider every view reads: mount it once at your app's client root, above every view, with its components, icons, ports and conventions. It lays your atoms over the defaults, hands your `Menu` its items with every row under a disabled group already disabled, and fills in the browser's own confirm where your ports carry no `confirm`. It hands its views one context value per distinct set of inputs, so pass module-level objects: a new one on each render re-renders every view.
|
|
10
|
-
- `ViewsProviderProps` — what the provider takes.
|
|
10
|
+
- `ViewsProviderProps` — what the provider takes. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`.
|
|
11
|
+
- `DEFAULT_DESKTOP_QUERY` — `(min-width: 1024px)`: the width a desktop starts at when the provider is handed no `desktopQuery`. Where the screen can't be asked (a server render, a browser with no `matchMedia`), it is a desktop.
|
|
11
12
|
- Required: `components` (your primitives, `ViewsComponents`), `icons` (your glyphs by meaning, `ViewsIcons`), `ports` (your runtime services, `ViewsPorts`), `conventions` (the `FieldConventions` of `@viewkitjs/fields` every value is read with) and `children`.
|
|
12
13
|
- Optional: `atoms`, any of your own atoms, each laid over the default of its name; `messages`, your wording for the package's own messages, defaulting to `resolveViewsMessage` (the package's English); `presentation`, `(defaults: FieldPresentation) => FieldPresentation`, how your numbers, dates and durations read: given the package's defaults in the conventions' locale, return yours. It is called where a value is drawn, so your provider imports none of the display.
|
|
13
14
|
- `useViews` — reads the nearest provider's value inside a view or an atom of your own. It throws an error that says where to mount one when no `ViewsProvider` is above it.
|
|
14
|
-
- `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`,
|
|
15
|
+
- `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`).
|
|
15
16
|
- `NOOP_PORTS` — ports that do nothing, for a server render, a test or an app without a device: the toasts and haptics are empty, the clipboard writes nothing (resolving `false`) and reads `null`, and the prefs store keeps nothing. It carries no `confirm`, so the provider falls back to the browser's.
|
|
16
17
|
|
|
17
18
|
## The components map
|
|
18
19
|
|
|
19
20
|
The primitives your app hands in, modelled on Base UI's shapes: a controlled `open` with `onOpenChange(open, details)`, an `anchor` rather than a trigger child on the popover and the menu, and no `asChild`. An adapter on Base UI wraps its copies thinly; one on Radix absorbs the difference. The package ships none of them and depends on neither library. The [contract](../contract.md) says what each slot promises and how to write an adapter.
|
|
20
21
|
|
|
21
|
-
- `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself.
|
|
22
|
+
- `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself. One key is optional, `Input`: leave it out and the editors draw a plain `<input>`.
|
|
23
|
+
- `ViewsResolvedComponents` — the map as `useViews()` hands it on: yours, with `Input` always there, your own or the plain one.
|
|
22
24
|
- `ViewsButtonProps` — a button: its `children`, `onClick`, `disabled`, a `variant` (`default`, `ghost`, `outline`, `destructive`), a `size` (`default`, `sm`, `icon`), its `type`, a class, `aria-label` and `title`.
|
|
23
25
|
- `ViewsPopoverProps` — a popover opened at an `anchor`, controlled by `open` and `onOpenChange`, placed by `side`, `align`, `sideOffset` and `alignOffset`.
|
|
24
26
|
- Focus: `initialFocus` false keeps focus where it was when the popup opens, for an editor that focuses its own input (with `preventScroll`). Default true.
|
|
@@ -28,10 +30,11 @@ The primitives your app hands in, modelled on Base UI's shapes: a controlled `op
|
|
|
28
30
|
- `ViewsCheckboxProps` — a checkbox: `checked`, and `indeterminate` for a box ticked partly, whose press hands `true` while `checked` is false. `onCheckedChange` hands the new value and, where your library reports it, `{ event }`, the press that changed it (a list reads its shift key for a range). `partialTone` colours the partial mark, `muted` by default or `brand` for a select-all with a live selection; with `disabled`, a class, `tabIndex` and `aria-label`.
|
|
29
31
|
- `ViewsMenuProps` — a menu opened at an `anchor`, with no trigger child and no flyouts, controlled by `open` and `onOpenChange`, drawing its `items` and placed by `side` and `align`. On Base UI it is the menu's root, positioner and popup, the anchor handed to the positioner.
|
|
30
32
|
- `ViewsMenuItem` — one row of a menu, as data your `Menu` draws: its `key`, `label`, `icon`, `onSelect`, `disabled` and `destructive`, a `separatorBefore`, a `shortcut` hint drawn at its end and never bound, and an `href` that makes it a link (with `onSelect` still firing). A `checked` row is checkable and closes the menu like any row. A row with `children` is a group: its rows drawn in place under its label, never a flyout, its own `onSelect`, `href` and `checked` ignored; a disabled group's rows reach your `Menu` already `disabled`.
|
|
31
|
-
- `ViewsCommandParts` — the command list's parts, the shape cmdk-based copies already have: `Root` (taking `label`, `shouldFilter` false to hand filtering to the host, a scoring `filter`,
|
|
33
|
+
- `ViewsCommandParts` — the command list's parts, the shape cmdk-based copies already have: `Root` (taking `label`, `shouldFilter` false to hand filtering to the host, a scoring `filter`, `loop` to wrap the arrows, and `defaultValue`, the value of the item highlighted as the list opens, none while no item has it), `Input` (a controlled `value` with `onValueChange`, a `placeholder`, `autoFocus`, a `ref`, `onKeyDown`, and `chrome` `search` for your search row or `bare` for the input alone), `List`, `Empty`, `Group` (with a `heading`) and `Item` (a `value`, `onSelect`, `disabled`, and `chosen`, which you colour as your chosen row while the package's row inside draws the check).
|
|
32
34
|
- `ViewsCalendarProps` — a calendar over ISO days (`YYYY-MM-DD`): its `value` and `onChange`, `min` and `max`, a `month` (`YYYY-MM`) controlled with `onMonthChange`, a `captionLayout` of `label` or `dropdown`, the `startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it draws its month and weekday names and starts its week (an adapter may keep its calendar's own). Your date library stays your own.
|
|
33
35
|
- `ViewsCollapseProps` — a box that opens and closes its `children` with `open`, over `durationMs`, with a class and a `clipClassName` on the box that crops the content.
|
|
34
36
|
- `ViewsSheetProps` — a phone sheet, controlled by `open` and `onOpenChange`, with a `title`, a `description`, a class, its `children`, and `snap` (`full`, `half`, `peek`, `auto`), a hint a sheet with no snap points ignores.
|
|
37
|
+
- `ViewsInputProps` — a single-line text box: every prop of an `<input>`, `ref` included, which your element must receive, and `chrome`, `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame).
|
|
35
38
|
- `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
|
|
36
39
|
- `ViewsSide` — the side a floating part opens on: `top`, `right`, `bottom` or `left`.
|
|
37
40
|
- `ViewsAlign` — how a floating part lines up along that side: `start`, `center` or `end`.
|
|
@@ -82,5 +85,5 @@ The pieces the rendering is built from, and your app's own pieces it cannot draw
|
|
|
82
85
|
- `ViewsRowMenuItem` — one row of the row's menu, the shape a host's own row-menu items already have: a rule (`{ separator: true }`), or a row with its `label`, `icon`, `onClick`, `destructive`, `disabled` and a `shortcut` hint drawn at its end and never bound.
|
|
83
86
|
- `ViewsRelationLinkProps` — where a relation chip goes: the `relation` value and the chip the display drew as `children`, for your app's own link around it. The default goes nowhere, since a relation is a fact as often as a destination.
|
|
84
87
|
- `ViewsLoadingProps` — a wait: `placement` `body` (the whole list reloading) or `footer` (more rows arriving), and the `label` read to assistive technology. The default is a plain ring, larger in the body.
|
|
85
|
-
- `ViewsLoadMoreProps` — how a list asks for its next page once its end comes near: `onReveal`, and an optional `label` drawn while it waits. The default watches a sentinel past the last row, calls `onReveal` as it comes within 600px of the viewport, and draws your `Loading` (or the label) meanwhile.
|
|
88
|
+
- `ViewsLoadMoreProps` — how a list asks for its next page once its end comes near: `onReveal`, and an optional `label` drawn while it waits. The default watches a sentinel past the last row, calls `onReveal` as it comes within 600px of the end of what it scrolls in (the grid's own scroll area, else the viewport), and draws your `Loading` (or the label) meanwhile.
|
|
86
89
|
- `ViewsPlatformMarkProps` — a link's platform, drawn before the link: the `platform` (its key says which, its name what to call it) and a class. The default draws nothing, so a link looks plain; the package ships no brand art, so an app that wants marks draws its own.
|
package/docs/reference/views.md
CHANGED
|
@@ -19,17 +19,21 @@ Guide: [the provider](../guides/the-provider.md).
|
|
|
19
19
|
- `VkColour` — one member of `VK_COLOURS`.
|
|
20
20
|
- `VK_OPTIONAL_COLOURS` — the status hues (`--vk-success`, `--vk-warning`, `--vk-info`) and the category hues (`--vk-label-blue` to `--vk-label-teal`) the default atoms and the display read when your app declares them, each with a built-in fallback ([Tokens](../contract.md#tokens)).
|
|
21
21
|
- `VkOptionalColour` — one member of `VK_OPTIONAL_COLOURS`.
|
|
22
|
-
- `VK_OPTIONAL_LAYOUT` — the layout your app may declare, each read with a `0px` fallback: `--vk-gutter`, the side padding your page gives its content, which the grid's rows line their content up with; and `--vk-
|
|
22
|
+
- `VK_OPTIONAL_LAYOUT` — the layout your app may declare, each read with a `0px` fallback: `--vk-gutter`, the side padding your page gives its content, which the grid's rows line their content up with; and `--vk-scroll-inset-bottom`, how much of the grid's foot your app covers with something it floats there (a phone's bottom bar), so the grid's scroll area runs underneath it and its last row scrolls clear of it ([Tokens](../contract.md#tokens)).
|
|
23
23
|
- `VkOptionalLayout` — one member of `VK_OPTIONAL_LAYOUT`.
|
|
24
24
|
- `VK_INTERNAL` — the grid's own variables, set and read by the grid alone: `--vk-drag-shift`, a header cell's offset while its column is dragged. Prefixed because they share the global namespace, and not public: your app neither sets nor reads them, and they may change in any release.
|
|
25
25
|
- `VkInternal` — one member of `VK_INTERNAL`.
|
|
26
26
|
- `VK_INTERNAL_FAMILIES` — the grid's internal variable families, a prefix with one variable per key after it: `--vk-col-w-<id>`, one column's resolved width, set on the grid's root for every visible column. Not public, like `VK_INTERNAL`.
|
|
27
27
|
- `COMPONENT_NAMES` — the primitives your app hands in through the provider: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command`, `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown` ([the components map](../contract.md#the-components-map)).
|
|
28
28
|
- `ComponentName` — one member of `COMPONENT_NAMES`.
|
|
29
|
+
- `OPTIONAL_COMPONENT_NAMES` — the primitives your app may leave out, each with a plain default the provider fills: `Input` ([the components map](../contract.md#the-components-map)).
|
|
30
|
+
- `OptionalComponentName` — one member of `OPTIONAL_COMPONENT_NAMES`.
|
|
29
31
|
- `ATOM_NAMES` — the pieces the rendering is built from, and the pieces of your app's own it cannot draw itself (a command cell's verb menu, the row's right-click menu, where a relation goes, a wait, how a list asks for more). Each ships as a default, and your app swaps any of them through the provider's `atoms` ([the atoms](../contract.md#the-atoms)).
|
|
30
32
|
- `AtomName` — one member of `ATOM_NAMES`.
|
|
31
33
|
- `ATOM_SLOTS` — the `data-slot` values the default atoms mark themselves with, prefixed like the grid's (`vk-row`, `vk-tick`, `vk-status`, `vk-row-menu` …) ([the atoms](../contract.md#the-atoms)).
|
|
32
34
|
- `AtomSlot` — one member of `ATOM_SLOTS`.
|
|
35
|
+
- `EDITOR_SLOTS` — the `data-slot` values the editor panel marks its parts with, prefixed like the grid's (`vk-editor-panel`, `vk-editor-bar`, `vk-editor-refusal`) ([the editor panel](../contract.md#the-editor-panel)).
|
|
36
|
+
- `EditorSlot` — one member of `EDITOR_SLOTS`.
|
|
33
37
|
- `ATOM_STATES` — the default atoms' states: `chosen`, `disabled`, `muted`, `checked` and `open` are flags present when true, `status` carries the status slot's name and `platform` a link's platform key ([the atoms](../contract.md#the-atoms)).
|
|
34
38
|
- `AtomState` — one member of `ATOM_STATES`.
|
|
35
39
|
- `PORT_NAMES` — the runtime services your app hands in through the provider: `toast`, `haptics`, `clipboard`, `viewPrefs` and `confirm` ([Ports](../contract.md#ports)).
|
|
@@ -54,7 +58,7 @@ A column is plain data: what a list shows in one place for every row, how it rea
|
|
|
54
58
|
|
|
55
59
|
- `ListColumn` — one column's declaration, generic over your row type. It requires `id`, `header` (a node) and `width` (the starting width every columnar view sizes from; what a person drags it to lives in their preferences). The optional members, by what they are for:
|
|
56
60
|
- Reading the row: `accessor` (the value the cell draws, compares and copies), `editAccessor` (the stored value an editor opens on, where the display read carries fallbacks), `aggAccessor` (the number the footer totals), `render` (a custom cell, handed the row and a `RenderedValue`), `indicator`, `actions` (buttons on the cell, `ListCellAction`).
|
|
57
|
-
- What the value is: `type` (`ListColumnType`), `options` (`ListColumnOption`), `multiple` (the cell holds several values), `labels: false` (a list whose rows keep only values, so its editor offers no label box), `chips.normalize` (the rule that turns typed text into a stored multiselect value), `relation` (a relation's candidates: a `source`, or static `options`, and the default `entity` kind), `nameFallback` (the words a name column draws for a row with an empty name), `format` (`ListColumnFormat`), `align`, `icon`.
|
|
61
|
+
- What the value is: `type` (`ListColumnType`), `options` (`ListColumnOption`), `multiple` (the cell holds several values), `labels: false` (a list whose rows keep only values, so its editor offers no label box), `region` (the record's country read off the row, where a phone typed, pasted or filled without its country code is read), `chips.normalize` (the rule that turns typed text into a stored multiselect value), `relation` (a relation's candidates: a `source`, or static `options`, and the default `entity` kind), `nameFallback` (the words a name column draws for a row with an empty name), `format` (`ListColumnFormat`), `align`, `icon`.
|
|
58
62
|
- Money: `currencyAccessor` (each row's own currency code, winning over `format.currency`), `surfaceOwnsCurrency` (the column, not the row, says which currency every figure is in), `money` and `reading` (a convertible column's declaration and the reading in force), `editUnit` (the unit picker beside the number editor).
|
|
59
63
|
- The footer: `defaultAggregate`, `footerKinds` (the picks the footer offers, `none` always among them), `footerField` (the field whose figures the footer reads when it is not the column's own), `aggregateSuffix` (the unit drawn after a figure), `ratio` (a ratio's numerator and denominator, summed and divided once).
|
|
60
64
|
- Order and splitting: `sortKey` (the key a sort hands your host), `sortable: false` (the source has no order for it), `bucketable: false` (take it out of Group by and Board by).
|
|
@@ -100,10 +104,10 @@ Guide: [columns](../guides/columns.md).
|
|
|
100
104
|
|
|
101
105
|
What the machinery may do with each column type, declared once per type so a new type cannot be added without answering every question.
|
|
102
106
|
|
|
103
|
-
- `GRID_TYPE_RULES` — the rule for every `ListColumnType`: which editor it mounts, which filter editor it opens, how a paste becomes its value and what a written value must look like. A boolean has no editor and is still writable;
|
|
107
|
+
- `GRID_TYPE_RULES` — the rule for every `ListColumnType`: which editor it mounts, which filter editor it opens, how a paste becomes its value and what a written value must look like. A boolean has no editor and is still writable; an actor has no editor and takes no paste; a location opens the place editor and takes no paste.
|
|
104
108
|
- `GridTypeRule` — one type's rule: `editor` (a `GridEditorId`, or `null` for none), `filter`, `paste` and `value`.
|
|
105
109
|
- `typeRule` — the rule for a type, or `null` for a column that declares no type.
|
|
106
|
-
- `GridEditorId` — which editor a writable column mounts when clicked, Entered or typed into: `text`, `select`, `number`, `date`, `relation`, `chips`, `range`, `name
|
|
110
|
+
- `GridEditorId` — which editor a writable column mounts when clicked, Entered or typed into: `text`, `select`, `number`, `date`, `relation`, `chips`, `range`, `name`, `values` (several emails, phones, links or domains, each with its label and a main one) or `place` (the country first, then its parts).
|
|
107
111
|
- `ListFilterEditor` — which editor a column opens in the filter panel: `options`, `text`, `number`, `date`, `boolean`, `range`, or `none` (listed, opens nothing).
|
|
108
112
|
- `GridPasteKind` — how a pasted clipboard cell becomes a commit: `text`, `option` (the pasted text matched against an offered option's label or key, exact before ignoring case, an in-grid copy landing on the exact option it copied, a label two options share refused), `number`, `date`, `boolean`, `relation` (the pasted label matched against the candidates, committing the id), `list` (the text split into several values, each read as an `option` is on a column of options), `range` (an in-grid pair, or text read as a range is written: "11–50", "10,001+", "up to 50"), or `none` (the type refuses paste).
|
|
109
113
|
- `GridValueKind` — what a written value must look like for a type: `any`, `email`, `url`, `boolean`, `relation` or `list`. `gridNormalizeWrite` holds a value to it.
|
|
@@ -115,7 +119,7 @@ What the machinery may do with each column type, declared once per type so a new
|
|
|
115
119
|
|
|
116
120
|
Three layers decide a write, and each may only take away from the one before: the column's declaration, the workspace's settings for the list (`ListSettingsConfig`), and a person's preferences. The `columnEffective…` and `gridColumnEffective…` answers apply the first two together, and are the ones a write gate asks.
|
|
117
121
|
|
|
118
|
-
- `gridEditorKind` — the editor a column mounts, or `null`: none unless the column is `editable` and typed. A `multiple` column mounts `values` for the four types that keep several values and nothing for any other; a `title` whose field is a name mounts `name`; any other column mounts its type's editor.
|
|
122
|
+
- `gridEditorKind` — the editor a column mounts, or `null`: none unless the column is `editable` and typed. A `multiple` column mounts `values` for the four types that keep several values and nothing for any other; a `title` whose field is a name mounts `name`; a `location` column mounts `place` when its field is a place, whose parts the editor reads, and nothing without one; any other column mounts its type's editor.
|
|
119
123
|
- `gridColumnHasEditor` — whether a column mounts an editor: the question a click, a double-click, Enter or typing asks. A boolean answers false and is still writable, which is why `columnWritable` is a separate answer.
|
|
120
124
|
- `columnWritable` — whether a column can be written by any route (an editor, Delete, Clear, a fill, a paste), by its declaration alone: false for a derived (`custom`) or `command` column and for one not `editable`; otherwise true when it mounts an editor or is a boolean. Gate sites ask `columnEffectiveWritable`, which adds the workspace's locks.
|
|
121
125
|
- `gridBooleanMode` — a boolean column's write model: `marker` (one-way, true to false) for a `marker` display, `toggle` for every other; `null` for a column that is not a boolean.
|
|
@@ -131,14 +135,16 @@ Three layers decide a write, and each may only take away from the one before: th
|
|
|
131
135
|
- `columnClearRefusal` — why a column can't be emptied, by its declaration alone: its `reasons.clearable`, else `views.grid.not-clearable`. A settings readout shows it as it is; the toast adds the lock case through `gridClearRefusal`.
|
|
132
136
|
- `columnEditRefusal` — why a column can't be edited, in the person's words: its `reasons.editable`, else the cause its field names (derived, system-set, provider-owned, create-only), else "Computed from …" for a `custom` column; `undefined` when there is no sentence to say. Takes the column, the conventions and a resolver that defaults to `resolveViewsMessage`.
|
|
133
137
|
- `gridEditRefusal` — why the grid won't edit a column: the workspace's lock first, then `columnEditRefusal`. The one sentence a refused gesture and a refused commit both say.
|
|
134
|
-
- `gridNormalizeWrite` — the write gate every route passes through once: coerces a value by the column's type, then, when the column presents a field, has the field accept it. A `multiple` column reads text as a list; a boolean reads `yes`, `1`, `true` and their opposites, and a marker refuses true; an email or a url is trimmed and must look like one (a url with `http://` or `https://`); a relation commits
|
|
138
|
+
- `gridNormalizeWrite` — the write gate every route passes through once: coerces a value by the column's type, then, when the column presents a field, has the field accept it. A `multiple` column reads text as a list; a boolean reads `yes`, `1`, `true` and their opposites, and a marker refuses true; an email or a url is trimmed and must look like one (a url with `http://` or `https://`); a relation commits what its row stores: an id, a ref `{ kind, id }` on a column that presents its field, or a relation holding several records' whole set (ids or links), each id refused outside a static candidate list, and an emptied set becomes the field's empty value; a multiselect commits the whole set, trimmed and without duplicates, and a clear as `[]`. An emptied value passes unchecked, since `clearable` decides whether a clear may run. Options: `region` (where a phone typed without its country code is read), `messages` (defaults to `resolveViewsMessage`) and `stored` (the value before the edit, so a value kept as stored is not read again). Returns a `GridWriteResult`.
|
|
135
139
|
- `GridWriteResult` — what `gridNormalizeWrite` returns: `{ ok: true, value }` with the value to commit, or `{ ok: false, reason }` with the sentence to show.
|
|
136
140
|
- `columnLabel` — a column's name for a toast or a readout: its header when that is a non-empty string, else its id made readable by `prettifyOptionValue`.
|
|
137
141
|
|
|
138
142
|
## Reading a cell in full
|
|
139
143
|
|
|
140
144
|
- `isLongTextColumn` — whether a column holds a paragraph rather than a phrase: a `text` column with `format.long`, or a `rich_text` column. It reads and edits in the anchored long-text panel rather than the one-line input.
|
|
141
|
-
- `gridColumnInspectable` — whether a cell opens a panel to be read in full, whatever its write state, so a long text that can't be edited can still be read. Long text is the one kind that does.
|
|
145
|
+
- `gridColumnInspectable` — whether a cell opens a panel to be read in full, whatever its write state, so a long text that can't be edited can still be read. Long text is the one kind that always does; a cut-off line does when its cell cuts it off (`isWholeTextColumn`).
|
|
146
|
+
- `isWholeTextColumn` — whether a column's text opens whole in that panel when its cell cuts it off: a plain `text` (not a paragraph) and a `title` that is text, not a person's name. Links, emails, phones and domains keep their one-line box.
|
|
147
|
+
- `gridTextOpensBox(column, whole)` — whether an open text cell is drawn in the panel over the cell rather than in the cell: a paragraph always, a line when it was opened `whole` (cut off when it opened).
|
|
142
148
|
|
|
143
149
|
## Column state
|
|
144
150
|
|
|
@@ -230,12 +236,13 @@ A binding says how one field reads and writes on one entity's row. Your app decl
|
|
|
230
236
|
- a writable currency amount whose code is read off the row, bound without its unit;
|
|
231
237
|
- a ratio formula bound without its two readers, and ratio readers on anything else;
|
|
232
238
|
- a labels choice on a field that does not hold several values;
|
|
233
|
-
- a writable relation with no candidates
|
|
239
|
+
- a writable relation with no candidates;
|
|
240
|
+
- a `create` row on a member field (a member is invited, not created), on any field but a relation, or without a `write`.
|
|
234
241
|
- `bindingWritable` — says whether a binding is writable in principle: it declares a write and its field's mutability is `always`. A `command` field answers false: every surface opens its verbs instead of an editor.
|
|
235
242
|
- `FieldBinding` — one field bound to a row:
|
|
236
243
|
- what it binds and reads: `field`, the field; `read`, the display value (a relation reads its resolved value); and `editRead`, the stored value when it differs (a relation's id, the raw value behind a fallback);
|
|
237
244
|
- how it writes: `write` maps a commit onto a `FieldPatch`, the request body or a refusal with the reason the surface shows, and absent, the field is never writable on any surface; `history`, a `FieldHistoryAdapter`, covers a write that also moves companion state;
|
|
238
|
-
- what its editor needs: `unit`, a `FieldUnit`, for an amount whose code is the row's (the number editor's unit chip is a picker only with it); `relation`, a writable relation's candidates as a `RelationSource`; and `labels: false` on a field holding several values that keeps only the values, so its editor offers no label box;
|
|
245
|
+
- what its editor needs: `unit`, a `FieldUnit`, for an amount whose code is the row's (the number editor's unit chip is a picker only with it); `region`, the record's country read off the row, where a phone typed without its country code is read (absent, the conventions' region); `relation`, a writable relation's candidates as a `RelationSource`; `create`, a relation's `RelationCellCreate` (refused on a member field, on any field but a relation, and without a `write`). A writable relation that stores refs or links binds, and the grid and a record's field row save it in its stored shape; a surface built on `RelationEditor` alone (a card, a form field) commits one bare id, so it can't save such a relation yet; and `labels: false` on a field holding several values that keeps only the values, so its editor offers no label box;
|
|
239
246
|
- how it draws and totals: `icon`, your app's own icon name for the field, drawn by the host (the type's glyph when absent); and `ratio`, a ratio formula's two parts read off the row, which a footer sums.
|
|
240
247
|
- `FieldBindingSpec` — a `FieldBinding` without its `field`: what `bindField` and `bindFields` take for each field.
|
|
241
248
|
- `BoundFields` — what `bindFields` returns: a frozen binding for every key of the registry, each typed to its own field.
|
|
@@ -248,19 +255,32 @@ A binding says how one field reads and writes on one entity's row. Your app decl
|
|
|
248
255
|
|
|
249
256
|
Every surface prepares a commit the same way before it sends anything. Both functions are pure, take an optional surface last (whether it is writable at all, the sentence it refuses in, and your conventions, `DEFAULT_CONVENTIONS` when it states none), and word every refusal through the conventions' messages.
|
|
250
257
|
|
|
251
|
-
- `prepareFieldWrite` — prepares one commit: takes the binding, the row and the commit, and returns a `PreparedFieldWrite`. It refuses when the surface is not writable (the surface's sentence, else `field.cannot-edit`) or the binding is not (the field's own reason, else `field.cannot-edit`). It then judges the commit (`acceptFieldCommit`, with the unit's options and, for a phone, the value stored before the edit), runs the binding's write, refuses a skip with its reason (else `field.cannot-save`), and judges the stored value (`acceptStoredFieldValue`). A number, percent, currency or datetime commit is a composite, so its write must say the stored value, or the result is `field.stored-value-required`. Only `body` is ever sent.
|
|
258
|
+
- `prepareFieldWrite` — prepares one commit: takes the binding, the row and the commit, and returns a `PreparedFieldWrite`. It refuses when the surface is not writable (the surface's sentence, else `field.cannot-edit`) or the binding is not (the field's own reason, else `field.cannot-edit`). It then judges the commit (`acceptFieldCommit`, with the unit's options, the binding's `region` for this row and, for a phone, a url, a multiselect or a relation, the value stored before the edit, so a closed multiselect keeps the values it already holds and a relation link the role it was stored with), runs the binding's write, refuses a skip with its reason (else `field.cannot-save`), and judges the stored value (`acceptStoredFieldValue`). A number, percent, currency or datetime commit is a composite, so its write must say the stored value, or the result is `field.stored-value-required`. Only `body` is ever sent.
|
|
252
259
|
- `prepareFieldRestore` — prepares the restore of a history entry: takes the binding, the row, the snapshot and the value it expects to find, and runs the same surface gate. A binding with no history is refused with `field.history-unavailable`, and a restore that skips with its reason (else `field.restore-refused`). A restore that names a stored value passes the stored-value gate; one that does not keeps the snapshot as its stored value.
|
|
253
260
|
- `PreparedFieldWrite` — what both return: `{ ok: true, body, storedValue }`, with an optional `settlement`, the binding's account of what the write achieves (`requested` when the body lands locally and a provider still has to accept it; the transport's result may upgrade it to `confirmed`), or `{ ok: false, reason }`.
|
|
254
261
|
- `FieldWriteContext` — how a write arrived: `{ kind: "commit" }`, or `{ kind: "restore", expected }`, a history restore that names the value it expects and is refused once the row has moved on.
|
|
255
262
|
- `PreparedRowEdit` — one admitted edit of an operation across cells of one row, such as a paste or a fill: its `columnId`, its `value` and its `FieldWriteContext`. A binding that groups a row's edits into one request names this shape.
|
|
256
263
|
- `GroupedRowWrite` — one request for every admitted edit of a same-row operation: `body`, and `historyColumnId`, the cell whose history snapshot covers the whole operation. The other cells stay confirmed and leave the history entry, so Undo sends exactly one restore.
|
|
257
264
|
|
|
265
|
+
## A write's target
|
|
266
|
+
|
|
267
|
+
The shapes a record's field writes go through, plain values with no React, so a write target and its tests read none of the rendering. `@viewkitjs/views/field-row` re-exports them beside the row and `useFieldWrite`.
|
|
268
|
+
|
|
269
|
+
- `FieldWriteReconciliationRequired` — thrown by a write target when a save may have landed but no confirmed row came back: the row warns, `refresh` runs, and no write is admitted until a new row arrives. Its `outcome` is `"saved-unconfirmed"` or `"uncertain"`, and its `warning` is the sentence shown.
|
|
270
|
+
- `EntityWriteTarget` — where a record's commits go: `save(rowId, body)`, resolving an `EntityWriteReceipt`, and `noun`, the record's singular name for toasts.
|
|
271
|
+
- `EntityWriteReceipt` — a save's answer: the confirmed `row`, an optional `warning`, and an optional `settlement` (`"requested"` draws the value pending until the next row arrives).
|
|
272
|
+
- `FieldWriteAdmission` — a commit's immediate answer: `{ accepted: false, reason }`, or `{ accepted: true, completion }`, the save's promise.
|
|
273
|
+
- `FieldWriteAdmissionGuard` — a function that refuses every write with a reason, or `null` to admit.
|
|
274
|
+
- `LockedResolver` — a field key to the reason it's locked on this surface, or `null`.
|
|
275
|
+
- `FieldNote` — a value's note: its `text`, and an optional `quote` it rests on.
|
|
276
|
+
|
|
258
277
|
## Relation candidates
|
|
259
278
|
|
|
260
279
|
The types a relation's candidates are built from. A binding's `relation` names them, and `@viewkitjs/views/editors/relation` re-exports them beside the editor that pages through them.
|
|
261
280
|
|
|
262
281
|
- `RelationSource` — where a relation's candidates come from: `{ kind: "static", items }`, a whole list your app already holds, with nothing to page; or `{ kind: "remote", search, pageSize }`, a search your app runs, with the empty query when the panel opens, then per typed query, then a page at a time as the list scrolls to its end. `pageSize` must match what your search asks its route for: a full page is the only sign there may be more.
|
|
263
282
|
- `RelationCandidate` — one thing a relation can point at, already resolved by your app: its `id` (compared, stored and committed, never shown), its `label` (shown, and what a static list matches on), and optionally a `sublabel` (a muted second line that tells two same-named rows apart), a `badge` (a muted word at the row's right edge, for a list of several kinds), an `icon` (a glyph of its own, which wins over the host's glyph for its kind), an `avatarUrl` and a `kind` (what a pick stores with the id, on a list of several kinds).
|
|
283
|
+
- `RelationCellCreate` — a create row your app hands a relation's binding, for a record not in the list yet: `label(query)` gives its words from the trimmed query, and `onCreate(query, link)` runs after the picker closes, so your own form opens with what was typed; call `link(id, kind?)` when that form saves, and the surface links the new record as a change of its own, with its own undo (on a relation holding several records, added to the set the editor saved). The grid links only a record its candidates offer: with a static list, add the new record to it before calling `link`.
|
|
264
284
|
- `RelationSearch` — your app's search: takes the query, an abort signal (it aborts on the next query and when the panel closes) and the offset, how many rows the panel already holds for this query, and resolves to the next candidates.
|
|
265
285
|
|
|
266
286
|
## A field's verb menu
|
|
@@ -274,9 +294,10 @@ A `command` field changes only through its entity's verbs: a transition that car
|
|
|
274
294
|
|
|
275
295
|
Guide: [editors](../guides/editors.md).
|
|
276
296
|
|
|
277
|
-
- `EDIT_CORE_TYPES` — every field type, mapped to whether it
|
|
278
|
-
- `hasEditCore` — says whether a field type
|
|
297
|
+
- `EDIT_CORE_TYPES` — every field type, mapped to whether it has an editor of its own: true for the dates, the options, relations, users, the numbers, places, names, ranges and the text types; false for the rest. It answers the question without loading the editors, and it agrees with `EDIT_CORES` on `@viewkitjs/views/editors` by construction.
|
|
298
|
+
- `hasEditCore` — says whether a field type has an editor of its own (the text-like types share the text editor), so a host can skip wiring an editor it does not need.
|
|
279
299
|
- `numberEditDecimals` — the decimals a number-shaped field edits at, the same on every surface: zero for an integer field, else the field's own decimals, else zero for a percent and two for money and plain numbers.
|
|
300
|
+
- `numberEditCode` — the code a money field's amount is typed in when the field fixes one (`code: { fixed }`), for the number editor's `code`; nothing for any other field, a money field whose currency is per record included.
|
|
280
301
|
- `durationUnitOf` — the unit a duration field stores (milliseconds when the field names none), or undefined for any other field.
|
|
281
302
|
|
|
282
303
|
## Format knobs
|
|
@@ -317,6 +338,7 @@ Money is stored in the currency each row was entered in, and a column is read ei
|
|
|
317
338
|
- `readMoneyColumn` — returns the column read the given way. Original sets the accessor to the amount, the total to its own figure and the currency to the row's code; a display currency converts the accessor and the total, sets the column's currency and marks the column as owning it. In every reading the `editAccessor` reads the row's own amount (one the column already has is kept), so an edit, an undo, a copy and a fill work on what the row stores, in its own currency, while the cell shows the converted figure. Every derivation starts from the declaration, so reading twice is reading once; a column with no declaration comes back unchanged.
|
|
318
339
|
- `readMoneyColumns` — reads every money column the reader's way: their chosen reading by field key, else the optional legacy reader's choice, else what the column opens on for the reader's default currency. A column with no declaration or no field comes back unchanged.
|
|
319
340
|
- `moneyReadingOf` — the reading in force on a money column: the one it was read with, else its declared reading; undefined for a column with no declaration, or one declared `"default"` and not yet read.
|
|
341
|
+
- `convertedFromOf` — the currency a column's figure was converted from for a row: the row's own code, when the column is read in a currency other than Original, the row has a figure to draw (it has rates) and stores another currency than the reading's; null otherwise. What `renderTypedCellValue` marks with ≈, and what a money editor names under the row's own amount.
|
|
320
342
|
- `shownCodeOf` — the code a cell draws for a row: a per-row column's row code, a converted column's one code, undefined for a column that is not money. Never `COLUMN_WIDE_CODE`.
|
|
321
343
|
- `DenominatedColumn` — what a column's denomination is read off: its `field`, `currencyAccessor` (each row keeps its own code), `surfaceOwnsCurrency` (one code for every row) and `format.currency`. Structural, so a grid column and a server-side source column both satisfy it.
|
|
322
344
|
- `denominationOf` — the currency a number read off a row is in, as a field reader's `codeOf` asks it for the money sort: the row's code for a column that keeps each row's own, the column's one code (or `COLUMN_WIDE_CODE`) for a column that owns its currency, and undefined for anything else, which leaves the field's own `code` in charge. A rollup or formula over money answers as money.
|
|
@@ -461,7 +483,7 @@ What a person keeps for one list: which view it opens on, on a desktop and on a
|
|
|
461
483
|
|
|
462
484
|
- `ListViewPrefs` — a list's preferences as one flat object. Its keys are stored, so they stay readable by every version that wrote them.
|
|
463
485
|
- Which view: `viewStyle` on a desktop, `viewStyleMobile` on a phone.
|
|
464
|
-
- The table's switches: vertical borders, the row icon in the title cell, the identity columns frozen at the left edge,
|
|
486
|
+
- The table's switches: vertical borders, the row icon in the title cell, the identity columns frozen at the left edge, every row's checkbox always shown.
|
|
465
487
|
- How fields read, by field key and sparse (a key that is absent keeps the column's own answer): option colours, date styles, duration styles, whether a date shows its time, percent displays, decimals and money readings.
|
|
466
488
|
- The footer's pick per column (`gridAggregates`), the columns' widths, order and visibility (`gridColumns`) and the density (`gridScale`).
|
|
467
489
|
- The calendar's date column and the board's field and lanes, `null` or empty to follow the host's default.
|
|
@@ -492,7 +514,7 @@ Guide: [the grid](../guides/the-grid.md).
|
|
|
492
514
|
|
|
493
515
|
A list keeps its preferences in separate buckets, by what each follows. The layout follows the list and the view: widths, order, visibility, density and the table's switches are one answer per view, shared by every surface that shows the list. Money readings follow the list and the reader. How a field reads follows the field, the same in every view. Filters stay with the surface. The store is the host's; these names give it the keys and the shapes.
|
|
494
516
|
|
|
495
|
-
- `ListViewLayout` — one view's layout, every key resolved: its columns and density, the table's optional switches (vertical borders, row icon, frozen identity,
|
|
517
|
+
- `ListViewLayout` — one view's layout, every key resolved: its columns and density, the table's optional switches (vertical borders, row icon, frozen identity, checkboxes always shown) that the rows views ignore, and three keys carried only when someone picked them: the calendar's `dateColumnId` and the board's `boardFieldId` and `boardLanes`.
|
|
496
518
|
- `StoredViewLayout` — what is stored for one view: only the keys someone set. A key that is absent follows the reader's default, so a key is written only where the view means to differ.
|
|
497
519
|
- `ListLayoutBucket` — a list's layouts, `{ views }`, the stored layout of each view by view id.
|
|
498
520
|
- `EMPTY_LAYOUT_BUCKET` — a layout bucket with no views.
|
|
@@ -598,4 +620,3 @@ Guide: [the grid](../guides/the-grid.md).
|
|
|
598
620
|
- `OrderChoice` — a mode and a direction, `{ mode, dir }`.
|
|
599
621
|
- `defaultDirFor` — a mode's natural direction, for seeding a new pick: `desc` for `count`, `asc` for the others.
|
|
600
622
|
- `sortGroupEntries` — sorts `[key, rows]` entries by an `OrderChoice` and returns a new array. It takes the lifecycle positions (a key without one sorts after), a label for each key and the key of the uncategorised group, which always sorts last; ties fall back to the label.
|
|
601
|
-
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@viewkitjs/views",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "ViewKit views — the grid, board, calendar and list over typed fields: a headless engine and a default rendering written to skin discipline. By Sheaf.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"type": "module",
|
|
@@ -37,6 +37,10 @@
|
|
|
37
37
|
"types": "./dist/editors/SelectEditor.d.ts",
|
|
38
38
|
"default": "./dist/editors/SelectEditor.js"
|
|
39
39
|
},
|
|
40
|
+
"./editors/text": {
|
|
41
|
+
"types": "./dist/editors/TextEditor.d.ts",
|
|
42
|
+
"default": "./dist/editors/TextEditor.js"
|
|
43
|
+
},
|
|
40
44
|
"./editors/relation": {
|
|
41
45
|
"types": "./dist/editors/RelationEditor.d.ts",
|
|
42
46
|
"default": "./dist/editors/RelationEditor.js"
|
|
@@ -73,10 +77,18 @@
|
|
|
73
77
|
"types": "./dist/editors/edit-session.d.ts",
|
|
74
78
|
"default": "./dist/editors/edit-session.js"
|
|
75
79
|
},
|
|
80
|
+
"./editors/panel": {
|
|
81
|
+
"types": "./dist/editors/EditorPanel.d.ts",
|
|
82
|
+
"default": "./dist/editors/EditorPanel.js"
|
|
83
|
+
},
|
|
76
84
|
"./editors/open-values": {
|
|
77
85
|
"types": "./dist/editors/open-values.d.ts",
|
|
78
86
|
"default": "./dist/editors/open-values.js"
|
|
79
87
|
},
|
|
88
|
+
"./field-row": {
|
|
89
|
+
"types": "./dist/field-row/index.d.ts",
|
|
90
|
+
"default": "./dist/field-row/index.js"
|
|
91
|
+
},
|
|
80
92
|
"./cells": {
|
|
81
93
|
"types": "./dist/cells/index.d.ts",
|
|
82
94
|
"default": "./dist/cells/index.js"
|
|
@@ -96,26 +108,33 @@
|
|
|
96
108
|
"access": "public"
|
|
97
109
|
},
|
|
98
110
|
"peerDependencies": {
|
|
99
|
-
"@viewkitjs/fields": "^0.
|
|
111
|
+
"@viewkitjs/fields": "^0.10.0",
|
|
100
112
|
"react": "^19.0.0",
|
|
101
113
|
"react-dom": "^19.0.0",
|
|
102
114
|
"zod": "^4.1.12"
|
|
103
115
|
},
|
|
104
116
|
"devDependencies": {
|
|
117
|
+
"@tailwindcss/postcss": "^4.3.3",
|
|
105
118
|
"@testing-library/react": "^16.3.2",
|
|
106
119
|
"@types/node": "^20",
|
|
107
120
|
"@types/react": "^19",
|
|
108
121
|
"@types/react-dom": "^19",
|
|
122
|
+
"esbuild": "^0.27.7",
|
|
123
|
+
"playwright": "^1.59.1",
|
|
124
|
+
"postcss": "^8.5.8",
|
|
109
125
|
"react": "19.2.0",
|
|
110
126
|
"react-dom": "19.2.0",
|
|
127
|
+
"tailwindcss": "^4.3.3",
|
|
111
128
|
"typescript": "^5",
|
|
112
129
|
"vitest": "^4.1.5",
|
|
113
130
|
"zod": "^4.1.12",
|
|
114
|
-
"@viewkitjs/fields": "0.
|
|
131
|
+
"@viewkitjs/fields": "0.10.0"
|
|
115
132
|
},
|
|
116
133
|
"scripts": {
|
|
117
134
|
"typecheck": "tsc -p tsconfig.json",
|
|
118
135
|
"build": "node ../../../scripts/clean-package-dist.mjs viewkit/views && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && node ../../../scripts/finalize-package-declarations.mjs viewkit/views",
|
|
119
|
-
"check": "node ../../../scripts/check-views-package.mjs"
|
|
136
|
+
"check": "node ../../../scripts/check-views-package.mjs",
|
|
137
|
+
"bench": "node bench/run.ts",
|
|
138
|
+
"bench:pin": "node bench/pin-check.ts"
|
|
120
139
|
}
|
|
121
140
|
}
|
package/skills/views/SKILL.md
CHANGED
|
@@ -5,11 +5,11 @@ description: Mount and adapt @viewkitjs/views — the provider, the components m
|
|
|
5
5
|
|
|
6
6
|
# ViewKit views
|
|
7
7
|
|
|
8
|
-
Use the package through its
|
|
8
|
+
Use the package through its twenty-one declared doors only, never a deep path: `@viewkitjs/views` (the
|
|
9
9
|
contract and the model), `@viewkitjs/views/react` (the provider, the atoms, the adapter's types),
|
|
10
|
-
`/display`, `/editors`, `/editors/select`, `/editors/relation`, `/editors/number`, `/editors/range`,
|
|
10
|
+
`/display`, `/editors`, `/editors/select`, `/editors/text`, `/editors/relation`, `/editors/number`, `/editors/range`,
|
|
11
11
|
`/editors/name`, `/editors/location`, `/editors/value-list`, `/editors/date`, `/editors/chips`,
|
|
12
|
-
`/editors/session`, `/editors/open-values`, `/cells`, `/selection` and `/grid`. The package's docs
|
|
12
|
+
`/editors/session`, `/editors/panel`, `/editors/open-values`, `/field-row`, `/cells`, `/selection` and `/grid`. The package's docs
|
|
13
13
|
start at `docs/index.md`: `docs/getting-started.md` goes from install to a grid on screen, a guide per
|
|
14
14
|
concept sits in `docs/guides/`, and `docs/reference/` names every export of each door.
|
|
15
15
|
|
|
@@ -58,7 +58,7 @@ export function AppViews({ children }: { children: ReactNode }) {
|
|
|
58
58
|
|
|
59
59
|
## Write the adapter against the contract
|
|
60
60
|
|
|
61
|
-
`docs/contract.md` lists the eleven components
|
|
61
|
+
`docs/contract.md` lists the eleven components and the optional `Input`, the five ports (`confirm` optional) and the icon names. Implement
|
|
62
62
|
`ViewsComponents` over your own shadcn copies: a controlled `open` with `onOpenChange(open, details)`,
|
|
63
63
|
an `anchor` element or ref on the popover and the menu, and no `asChild`; `AppIcon` is your own
|
|
64
64
|
icon component by your own names. The shapes are Base UI's; `docs/contract.md`'s "Writing an
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
import { type RefObject, type UIEvent } from "react";
|
|
2
|
-
/** What a group's rows scroller spreads on itself: its registration, its scroll handler, its
|
|
3
|
-
* overflow classes. Named, so its readers never spell it as an indexed type. */
|
|
4
|
-
export type GridScrollSurface = {
|
|
5
|
-
/** A ref callback: what it returns is React's ref cleanup, which a wrapper must hand back. */
|
|
6
|
-
register: (element: HTMLElement | null) => (() => void) | undefined;
|
|
7
|
-
onScroll: (event: UIEvent<HTMLElement>) => void;
|
|
8
|
-
className: string;
|
|
9
|
-
};
|
|
10
|
-
/**
|
|
11
|
-
* Horizontal lock-step scrolling for per-group scrollers and sticky headers.
|
|
12
|
-
*
|
|
13
|
-
* The page-sticky headers live OUTSIDE the scrollers (so they can pin
|
|
14
|
-
* vertically) but are themselves `overflow-x-hidden` scroll containers, driven
|
|
15
|
-
* programmatically.
|
|
16
|
-
*
|
|
17
|
-
* They must NOT be slid by `transform: translate3d(-x)`. Two bugs came from
|
|
18
|
-
* that: a transform has no end-stop, so the header over-travelled past its own
|
|
19
|
-
* content at the end of a scroll; and frozen header columns had to
|
|
20
|
-
* counter-transform in JS, which drifted a frame behind the compositor-driven
|
|
21
|
-
* body. As real scrollers, `scrollLeft` clamps itself and frozen header cells
|
|
22
|
-
* use plain `position: sticky` — pinned by the compositor, never lagging.
|
|
23
|
-
*
|
|
24
|
-
* Idempotent writes (`!== x` guards) make echoed scroll events terminate.
|
|
25
|
-
*/
|
|
26
|
-
export declare function useGridScrollSync(rootRef: RefObject<HTMLDivElement | null>): {
|
|
27
|
-
scrollXRef: RefObject<number>;
|
|
28
|
-
getScroller: () => HTMLElement | undefined;
|
|
29
|
-
surface: GridScrollSurface;
|
|
30
|
-
registerHeader: (element: HTMLElement | null) => (() => void) | undefined;
|
|
31
|
-
headerWheelRef: (element: HTMLElement | null) => (() => void) | undefined;
|
|
32
|
-
headerPanHandlers: {
|
|
33
|
-
onPointerDown: (event: React.PointerEvent) => void;
|
|
34
|
-
onPointerMove: (event: React.PointerEvent) => void;
|
|
35
|
-
onPointerUp: () => void;
|
|
36
|
-
onPointerCancel: () => void;
|
|
37
|
-
};
|
|
38
|
-
};
|