@toclocoinc/lattice-grid 1.37.0 → 1.39.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.37.0</p>
+    <p class="rail__sub">Developer guide · v1.39.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -3370,6 +3370,54 @@ columns: [
 }}</code></pre>
     </div>
 
+    <h3 id="declarative-validation">Declarative validation</h3>
+    <p class="lead-in">
+      The <code>edit.validate</code> function above is the imperative form. Where the rules are simple
+      and the same across columns, declare them as data on <code>validation</code> instead
+      (BACKLOG-0000956): <code>required</code>, <code>min</code>/<code>max</code>,
+      <code>minLength</code>/<code>maxLength</code>, <code>pattern</code>, <code>oneOf</code>, and a
+      <code>crossField</code> predicate. Each is checked <strong>before the write</strong>, riding the
+      cancellable <code>beforeEdit</code> event: a failing value cancels the commit, marks the cell
+      with the same accessible invalid state an editor rejection uses, and fires
+      <code>validation:failed</code>. Correcting the value clears the mark and fires
+      <code>validation:cleared</code>. Only a user edit is gated — a host API write is the authority
+      and is never self-vetoed.
+    </p>
+    <div class="example">
+      <p class="example__label">Rules as data</p>
+      <pre><code>columns: [
+  { field: 'name', edit: true, validation: { required: true, minLength: 2 } },
+  { field: 'age',  type: 'number', edit: true, validation: { min: 0, max: 120 } },
+  { field: 'code', edit: true, validation: { pattern: '^[A-Z]{3}$', messages: { pattern: 'Three capitals.' } } },
+]
+
+<span class="cmt">// Why a write was refused, and clearing a mark by hand.</span>
+grid.validation.errorFor('r1', 'age');       <span class="cmt">// { code, message, key, colId } or null</span>
+grid.on('validation:failed', (e) =&gt; report(e.failures));
+grid.on('validation:cleared', () =&gt; refreshBanner());</code></pre>
+    </div>
+
+    <h3 id="deleting-rows">Deleting rows</h3>
+    <p class="lead-in">
+      Set <code>rowDelete: true</code> for the built-in delete gesture: Delete or Backspace on the
+      selected rows, and a "Delete row" item in the cell menu. It works on a memory grid, not only a
+      remote one, and every deletion flows through the cancellable <code>beforeDelete</code> event —
+      so a confirm dialog is a handler that calls <code>e.preventDefault(reason)</code>. It is off by
+      default because deleting data on a keystroke is destructive.
+    </p>
+    <div class="example">
+      <p class="example__label">Confirm before delete</p>
+      <pre><code>const grid = createGrid(el, { columns, rows, rowKey: 'id', selection: 'multiple', rowDelete: true });
+
+grid.on('beforeDelete', async (e) =&gt; {
+  const ok = await confirmDialog(`Delete ${e.rows.length} row(s)?`);
+  if (!ok) e.preventDefault('cancelled');   <span class="cmt">// the rows stay; delete:cancelled fires</span>
+});
+
+<span class="cmt">// The gesture calls this; you can call it too. Defaults to the selection.</span>
+grid.edit.deleteRows();</code></pre>
+    </div>
+
     <h2 id="appearance">Grid lines and corners</h2>
     <p class="lead-in">
       Two settings that change how the grid is drawn rather than what it draws.
@@ -6208,6 +6256,28 @@ grid.state.apply(savedView.state);
       to CSV takes about 100ms.</p>
     </div>
 
+    <h2 id="import-guide">Import</h2>
+    <p class="lead-in">
+      The mirror of export: rows coming in from a CSV or TSV file, a drop, or a pasted spreadsheet
+      block. The pipeline is parse, infer each column's type, map the columns onto your fields, then
+      preview and confirm — nothing lands until the user says so.
+    </p>
+    <div class="example">
+      <p class="example__label">Preview, then confirm</p>
+      <pre><code><span class="cmt">// Parse and map without touching the grid — this is what the dialog shows.</span>
+<span class="kw">const</span> preview = grid.import.preview(csvText);
+<span class="cmt">// preview.columns is the mapping the user can edit; preview.warnings flags a</span>
+<span class="cmt">// ragged file. Confirming appends (or, with { mode: 'replace' }, swaps).</span>
+grid.import.apply(preview);</code></pre>
+    </div>
+    <p class="lead-in">
+      Set <code>config.import</code> to <code>true</code> to add the DOM affordances — a
+      "Import rows from CSV…" cell-menu item, a file drop target, and paste — each opening the same
+      preview dialog. The <code>grid.import</code> API is present whether or not you do, so a server-side
+      or headless import runs the identical pipeline. <code>.xlsx</code> is not read (it needs an inflate
+      and XML reader the zero-dependency envelope does not carry); save the sheet as CSV.
+    </p>
+
     <h2 id="less-common">Options and calls you may not have met</h2>
     <p class="lead-in">
       The rest of the surface, in one place. Each of these is documented in full in the
@@ -6469,6 +6539,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
         <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
         <tbody>
           <tr><td class="name">column:filter:open</td><td class="desc">Header filter popup opened.</td></tr>
+          <tr><td class="name">column:profile:open</td><td class="desc">The column statistics ("describe") panel was asked to open on a column, from the column menu's "Column statistics" item (<code>{ colId }</code>). A mounted tool panel opens its <code>statistics</code> panel seeded on that column.</td></tr>
           <tr><td class="name">column:grouped</td><td class="desc">The row-group column list changed.</td></tr>
           <tr><td class="name">column:menu:open</td><td class="desc">Header menu opened.</td></tr>
           <tr><td class="name">column:moved</td><td class="desc">Reordered by drag or by API.</td></tr>