@ai-matrx/design-system 0.41.0 → 0.42.1

package/dist/data-table/infer-filter.d.cts

@@ -1,4 +1,4 @@
-import { M as MatrxColumnDef, f as ColumnFilterKind } from '../types-DNkbHRVK.cjs';
+import { M as MatrxColumnDef, f as ColumnFilterKind } from '../types-q5ficDSo.cjs';
 import '../content-transfer.cjs';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
@@ -12,6 +12,7 @@ import './facets.cjs';
 import './spreadsheet.cjs';
 import './grid-selection.cjs';
 import './date-filter.cjs';
+import './menu-targets.cjs';
 
 type ResolvedFilterKind = "text" | "select" | "boolean" | "number" | "date";
 /**

package/dist/data-table/infer-filter.d.ts

@@ -1,4 +1,4 @@
-import { M as MatrxColumnDef, f as ColumnFilterKind } from '../types-Dx5hJgCi.js';
+import { M as MatrxColumnDef, f as ColumnFilterKind } from '../types-afUz93xo.js';
 import '../content-transfer.js';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
@@ -12,6 +12,7 @@ import './facets.js';
 import './spreadsheet.js';
 import './grid-selection.js';
 import './date-filter.js';
+import './menu-targets.js';
 
 type ResolvedFilterKind = "text" | "select" | "boolean" | "number" | "date";
 /**

package/dist/data-table/layered-filters.d.cts

@@ -1,4 +1,4 @@
-export { _ as LAYERED_FILTER_OPERATORS, $ as LAYERED_FILTER_OPERATOR_LABELS, a0 as LayeredFilterField, a1 as LayeredFilterOperator, L as LayeredFilterRule, a2 as columnFiltersToLayeredRules, a3 as completeLayeredFilterRules, a4 as decodeLayeredFilterRules, a5 as encodeLayeredFilterRules, a6 as isCompleteLayeredFilterRule, a7 as isLayeredFilterOperator, a8 as layeredFilterMatchesValue, a9 as layeredFilterNeedsValue, aa as layeredFilterRuleSummary, ab as operatorsForLayeredField } from '../types-DNkbHRVK.cjs';
+export { _ as LAYERED_FILTER_OPERATORS, $ as LAYERED_FILTER_OPERATOR_LABELS, a0 as LayeredFilterField, a1 as LayeredFilterOperator, L as LayeredFilterRule, a2 as columnFiltersToLayeredRules, a3 as completeLayeredFilterRules, a4 as decodeLayeredFilterRules, a5 as encodeLayeredFilterRules, a6 as isCompleteLayeredFilterRule, a7 as isLayeredFilterOperator, a8 as layeredFilterMatchesValue, a9 as layeredFilterNeedsValue, aa as layeredFilterRuleSummary, ab as operatorsForLayeredField } from '../types-q5ficDSo.cjs';
 import '../content-transfer.cjs';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
@@ -12,3 +12,4 @@ import './facets.cjs';
 import './spreadsheet.cjs';
 import './grid-selection.cjs';
 import './date-filter.cjs';
+import './menu-targets.cjs';

package/dist/data-table/layered-filters.d.ts

@@ -1,4 +1,4 @@
-export { _ as LAYERED_FILTER_OPERATORS, $ as LAYERED_FILTER_OPERATOR_LABELS, a0 as LayeredFilterField, a1 as LayeredFilterOperator, L as LayeredFilterRule, a2 as columnFiltersToLayeredRules, a3 as completeLayeredFilterRules, a4 as decodeLayeredFilterRules, a5 as encodeLayeredFilterRules, a6 as isCompleteLayeredFilterRule, a7 as isLayeredFilterOperator, a8 as layeredFilterMatchesValue, a9 as layeredFilterNeedsValue, aa as layeredFilterRuleSummary, ab as operatorsForLayeredField } from '../types-Dx5hJgCi.js';
+export { _ as LAYERED_FILTER_OPERATORS, $ as LAYERED_FILTER_OPERATOR_LABELS, a0 as LayeredFilterField, a1 as LayeredFilterOperator, L as LayeredFilterRule, a2 as columnFiltersToLayeredRules, a3 as completeLayeredFilterRules, a4 as decodeLayeredFilterRules, a5 as encodeLayeredFilterRules, a6 as isCompleteLayeredFilterRule, a7 as isLayeredFilterOperator, a8 as layeredFilterMatchesValue, a9 as layeredFilterNeedsValue, aa as layeredFilterRuleSummary, ab as operatorsForLayeredField } from '../types-afUz93xo.js';
 import '../content-transfer.js';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
@@ -12,3 +12,4 @@ import './facets.js';
 import './spreadsheet.js';
 import './grid-selection.js';
 import './date-filter.js';
+import './menu-targets.js';

package/dist/data-table/menu-targets.cjs

@@ -26,6 +26,7 @@ __export(menu_targets_exports, {
   MATRX_HEADER_COLUMN_ATTR: () => MATRX_HEADER_COLUMN_ATTR,
   MATRX_ROW_ID_ATTR: () => MATRX_ROW_ID_ATTR,
   MATRX_TABLE_ID_ATTR: () => MATRX_TABLE_ID_ATTR,
+  MATRX_TABLE_MENU_ICON_NAMES: () => MATRX_TABLE_MENU_ICON_NAMES,
   describeMenuLevel: () => describeMenuLevel,
   readMenuTarget: () => readMenuTarget
 });
@@ -74,4 +75,30 @@ function describeMenuLevel(payload) {
       return "Table";
   }
 }
+var MATRX_TABLE_MENU_ICON_NAMES = [
+  "copy",
+  "copy-plus",
+  "scissors",
+  "clipboard-paste",
+  "eraser",
+  "pencil",
+  "plus",
+  "trash",
+  "eye-off",
+  "arrow-up-a-z",
+  "arrow-down-a-z",
+  "arrow-up-down",
+  "arrow-down-to-line",
+  "palette",
+  "paintbrush",
+  "panel-left",
+  "panel-right",
+  "settings",
+  "sigma",
+  "zap",
+  "history",
+  "link",
+  "tag",
+  "filter"
+];
 //# sourceMappingURL=menu-targets.cjs.map

package/dist/data-table/menu-targets.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/data-table/menu-targets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — WHAT WAS RIGHT-CLICKED.\n *\n * A spreadsheet's right-click menu is not one menu: it is four, and which one\n * you get is decided by where the pointer was. A cell, the row it sits in, the\n * column it sits under, and — when the click lands inside an extended range —\n * the selection. The canonical table used to expose exactly ONE of those four\n * (the row), so every surface that wanted the other three forked the table.\n *\n * This module is the pure half of the fix: it reads the four levels off the\n * DOM anchors the table already renders, and nothing more. It does not build a\n * menu, name an action, or know what a menu is — the platform's universal\n * right-click menu is an application concern and stays there. The table's job\n * is to answer, truthfully, WHICH thing the person aimed at.\n *\n * THE PRECEDENCE, and why it is this way:\n *\n *   selection > cell > column > row > table\n *\n * A click inside an extended range means the range, because that is what the\n * person is looking at and what every spreadsheet acts on — taking the single\n * cell under the cursor there would silently throw away their selection. A\n * header click is the column even though the header is inside the table. A\n * click on a row but outside any cell (the checkbox gutter, the actions cell)\n * is the row. Anything else in the table is the table.\n *\n * Pure: no React, no package state. It reads `data-*` attributes and returns a\n * plain object. Nothing here throws on any input.\n */\n\n/** Which of the four things the pointer was aimed at. */\nexport type MatrxTableMenuLevel = \"cell\" | \"row\" | \"column\" | \"selection\" | \"table\";\n\nexport interface MatrxTableMenuTarget {\n  /** The table instance the click landed in. */\n  tableId: string;\n  level: MatrxTableMenuLevel;\n  /** Present for \"cell\" and \"row\". */\n  rowId?: string;\n  /** Present for \"cell\" and \"column\". */\n  columnId?: string;\n}\n\n/**\n * Attribute names, in one place, so the renderer and the reader cannot drift.\n * `data-row-id` predates this module and keeps its name: it is already read by\n * the row-drag preview and by every host that wired the row menu.\n */\nexport const MATRX_TABLE_ID_ATTR = \"data-matrx-table-id\";\nexport const MATRX_ROW_ID_ATTR = \"data-row-id\";\nexport const MATRX_CELL_ROW_ATTR = \"data-matrx-cell-row\";\nexport const MATRX_CELL_COLUMN_ATTR = \"data-matrx-table-column-id\";\nexport const MATRX_HEADER_COLUMN_ATTR = \"data-matrx-header-column-id\";\n/** Marks a cell that is inside the current extended range. */\nexport const MATRX_CELL_SELECTED_ATTR = \"data-matrx-cell-selected\";\n\ninterface MinimalElement {\n  closest(selector: string): MinimalElement | null;\n  getAttribute(name: string): string | null;\n}\n\nfunction attr(element: MinimalElement | null, name: string): string | undefined {\n  if (!element) return undefined;\n  const found = element.closest(`[${name}]`);\n  const value = found?.getAttribute(name);\n  return value === null || value === undefined || value === \"\" ? undefined : value;\n}\n\n/**\n * Read the four levels off the clicked element.\n *\n * Returns null when the click did not land in a canonical table at all — which\n * is the signal a host needs to leave its own page-level menu alone.\n */\nexport function readMenuTarget(\n  target: MinimalElement | null,\n): MatrxTableMenuTarget | null {\n  const tableId = attr(target, MATRX_TABLE_ID_ATTR);\n  if (!tableId) return null;\n\n  const headerColumnId = attr(target, MATRX_HEADER_COLUMN_ATTR);\n  if (headerColumnId) return { tableId, level: \"column\", columnId: headerColumnId };\n\n  // A cell's row comes from the `<tr>` it is in, which every table renders —\n  // the spreadsheet cursor's own row attribute is a second opinion, used only\n  // when the table is windowed sideways and the row wrapper is not an ancestor.\n  const cellColumnId = attr(target, MATRX_CELL_COLUMN_ATTR);\n  const cellRowId = attr(target, MATRX_ROW_ID_ATTR) ?? attr(target, MATRX_CELL_ROW_ATTR);\n  const rowId = cellRowId;\n\n  if (cellRowId && cellColumnId) {\n    // Inside an extended range the SELECTION is what the person sees and what\n    // the menu must act on. A range of one cell is not a range — acting on it\n    // as a selection would give a lone cell the plural verbs.\n    const selected = attr(target, MATRX_CELL_SELECTED_ATTR) === \"true\";\n    if (selected) return { tableId, level: \"selection\", rowId: cellRowId, columnId: cellColumnId };\n    return { tableId, level: \"cell\", rowId: cellRowId, columnId: cellColumnId };\n  }\n\n  if (rowId) return { tableId, level: \"row\", rowId };\n  return { tableId, level: \"table\" };\n}\n\n/**\n * The payload the table hands its host for the level that was clicked.\n *\n * The host builds the menu from this and never reaches back into the table.\n * Every level carries the table's own count of what it is acting on, because a\n * menu that says \"Clear 12 cells\" and clears 40 is worse than one that says\n * nothing.\n */\nexport type MatrxTableMenuPayload<T = unknown> =\n  | {\n      level: \"cell\";\n      row: T;\n      rowId: string;\n      columnId: string;\n      columnLabel: string;\n      value: unknown;\n      /** The cell's value as the table displays it, for Copy. */\n      text: string;\n      controls: unknown;\n    }\n  | { level: \"row\"; row: T; rowId: string; controls: unknown }\n  | {\n      level: \"column\";\n      columnId: string;\n      columnLabel: string;\n      /** Every rendered row's value for this column, in visual order. */\n      values: unknown[];\n    }\n  | {\n      level: \"selection\";\n      rowIds: string[];\n      columnIds: string[];\n      /** The selected rectangle as an Excel/Sheets-compatible TSV block. */\n      tsv: string;\n      cellCount: number;\n    }\n  | { level: \"table\"; rowCount: number; columnIds: string[] };\n\n/** Plain-English name for a level, for a host that labels its sections. */\nexport function describeMenuLevel(payload: MatrxTableMenuPayload): string {\n  switch (payload.level) {\n    case \"cell\":\n      return payload.columnLabel;\n    case \"row\":\n      return \"Row\";\n    case \"column\":\n      return payload.columnLabel;\n    case \"selection\": {\n      const cells = payload.cellCount;\n      return `${cells} ${cells === 1 ? \"cell\" : \"cells\"}`;\n    }\n    case \"table\":\n      return \"Table\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgDO,IAAM,sBAAsB;AAC5B,IAAM,oBAAoB;AAC1B,IAAM,sBAAsB;AAC5B,IAAM,yBAAyB;AAC/B,IAAM,2BAA2B;AAEjC,IAAM,2BAA2B;AAOxC,SAAS,KAAK,SAAgC,MAAkC;AAC9E,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,QAAQ,QAAQ,QAAQ,IAAI,IAAI,GAAG;AACzC,QAAM,QAAQ,OAAO,aAAa,IAAI;AACtC,SAAO,UAAU,QAAQ,UAAU,UAAa,UAAU,KAAK,SAAY;AAC7E;AAQO,SAAS,eACd,QAC6B;AAC7B,QAAM,UAAU,KAAK,QAAQ,mBAAmB;AAChD,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,iBAAiB,KAAK,QAAQ,wBAAwB;AAC5D,MAAI,eAAgB,QAAO,EAAE,SAAS,OAAO,UAAU,UAAU,eAAe;AAKhF,QAAM,eAAe,KAAK,QAAQ,sBAAsB;AACxD,QAAM,YAAY,KAAK,QAAQ,iBAAiB,KAAK,KAAK,QAAQ,mBAAmB;AACrF,QAAM,QAAQ;AAEd,MAAI,aAAa,cAAc;AAI7B,UAAM,WAAW,KAAK,QAAQ,wBAAwB,MAAM;AAC5D,QAAI,SAAU,QAAO,EAAE,SAAS,OAAO,aAAa,OAAO,WAAW,UAAU,aAAa;AAC7F,WAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,WAAW,UAAU,aAAa;AAAA,EAC5E;AAEA,MAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM;AACjD,SAAO,EAAE,SAAS,OAAO,QAAQ;AACnC;AAyCO,SAAS,kBAAkB,SAAwC;AACxE,UAAQ,QAAQ,OAAO;AAAA,IACrB,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK,aAAa;AAChB,YAAM,QAAQ,QAAQ;AACtB,aAAO,GAAG,KAAK,IAAI,UAAU,IAAI,SAAS,OAAO;AAAA,IACnD;AAAA,IACA,KAAK;AACH,aAAO;AAAA,EACX;AACF;","names":[]}
+{"version":3,"sources":["../../src/data-table/menu-targets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — WHAT WAS RIGHT-CLICKED.\n *\n * A spreadsheet's right-click menu is not one menu: it is four, and which one\n * you get is decided by where the pointer was. A cell, the row it sits in, the\n * column it sits under, and — when the click lands inside an extended range —\n * the selection. The canonical table used to expose exactly ONE of those four\n * (the row), so every surface that wanted the other three forked the table.\n *\n * This module is the pure half of the fix: it reads the four levels off the\n * DOM anchors the table already renders, and nothing more. It does not build a\n * menu, name an action, or know what a menu is — the platform's universal\n * right-click menu is an application concern and stays there. The table's job\n * is to answer, truthfully, WHICH thing the person aimed at.\n *\n * THE PRECEDENCE, and why it is this way:\n *\n *   selection > cell > column > row > table\n *\n * A click inside an extended range means the range, because that is what the\n * person is looking at and what every spreadsheet acts on — taking the single\n * cell under the cursor there would silently throw away their selection. A\n * header click is the column even though the header is inside the table. A\n * click on a row but outside any cell (the checkbox gutter, the actions cell)\n * is the row. Anything else in the table is the table.\n *\n * Pure: no React, no package state. It reads `data-*` attributes and returns a\n * plain object. Nothing here throws on any input.\n */\n\n/** Which of the four things the pointer was aimed at. */\nexport type MatrxTableMenuLevel = \"cell\" | \"row\" | \"column\" | \"selection\" | \"table\";\n\nexport interface MatrxTableMenuTarget {\n  /** The table instance the click landed in. */\n  tableId: string;\n  level: MatrxTableMenuLevel;\n  /** Present for \"cell\" and \"row\". */\n  rowId?: string;\n  /** Present for \"cell\" and \"column\". */\n  columnId?: string;\n}\n\n/**\n * Attribute names, in one place, so the renderer and the reader cannot drift.\n * `data-row-id` predates this module and keeps its name: it is already read by\n * the row-drag preview and by every host that wired the row menu.\n */\nexport const MATRX_TABLE_ID_ATTR = \"data-matrx-table-id\";\nexport const MATRX_ROW_ID_ATTR = \"data-row-id\";\nexport const MATRX_CELL_ROW_ATTR = \"data-matrx-cell-row\";\nexport const MATRX_CELL_COLUMN_ATTR = \"data-matrx-table-column-id\";\nexport const MATRX_HEADER_COLUMN_ATTR = \"data-matrx-header-column-id\";\n/** Marks a cell that is inside the current extended range. */\nexport const MATRX_CELL_SELECTED_ATTR = \"data-matrx-cell-selected\";\n\ninterface MinimalElement {\n  closest(selector: string): MinimalElement | null;\n  getAttribute(name: string): string | null;\n}\n\nfunction attr(element: MinimalElement | null, name: string): string | undefined {\n  if (!element) return undefined;\n  const found = element.closest(`[${name}]`);\n  const value = found?.getAttribute(name);\n  return value === null || value === undefined || value === \"\" ? undefined : value;\n}\n\n/**\n * Read the four levels off the clicked element.\n *\n * Returns null when the click did not land in a canonical table at all — which\n * is the signal a host needs to leave its own page-level menu alone.\n */\nexport function readMenuTarget(\n  target: MinimalElement | null,\n): MatrxTableMenuTarget | null {\n  const tableId = attr(target, MATRX_TABLE_ID_ATTR);\n  if (!tableId) return null;\n\n  const headerColumnId = attr(target, MATRX_HEADER_COLUMN_ATTR);\n  if (headerColumnId) return { tableId, level: \"column\", columnId: headerColumnId };\n\n  // A cell's row comes from the `<tr>` it is in, which every table renders —\n  // the spreadsheet cursor's own row attribute is a second opinion, used only\n  // when the table is windowed sideways and the row wrapper is not an ancestor.\n  const cellColumnId = attr(target, MATRX_CELL_COLUMN_ATTR);\n  const cellRowId = attr(target, MATRX_ROW_ID_ATTR) ?? attr(target, MATRX_CELL_ROW_ATTR);\n  const rowId = cellRowId;\n\n  if (cellRowId && cellColumnId) {\n    // Inside an extended range the SELECTION is what the person sees and what\n    // the menu must act on. A range of one cell is not a range — acting on it\n    // as a selection would give a lone cell the plural verbs.\n    const selected = attr(target, MATRX_CELL_SELECTED_ATTR) === \"true\";\n    if (selected) return { tableId, level: \"selection\", rowId: cellRowId, columnId: cellColumnId };\n    return { tableId, level: \"cell\", rowId: cellRowId, columnId: cellColumnId };\n  }\n\n  if (rowId) return { tableId, level: \"row\", rowId };\n  return { tableId, level: \"table\" };\n}\n\n/**\n * The payload the table hands its host for the level that was clicked.\n *\n * The host builds the menu from this and never reaches back into the table.\n * Every level carries the table's own count of what it is acting on, because a\n * menu that says \"Clear 12 cells\" and clears 40 is worse than one that says\n * nothing.\n */\nexport type MatrxTableMenuPayload<T = unknown> =\n  | {\n      level: \"cell\";\n      row: T;\n      rowId: string;\n      columnId: string;\n      columnLabel: string;\n      value: unknown;\n      /** The cell's value as the table displays it, for Copy. */\n      text: string;\n      controls: unknown;\n    }\n  | { level: \"row\"; row: T; rowId: string; controls: unknown }\n  | {\n      level: \"column\";\n      columnId: string;\n      columnLabel: string;\n      /** Every rendered row's value for this column, in visual order. */\n      values: unknown[];\n    }\n  | {\n      level: \"selection\";\n      rowIds: string[];\n      columnIds: string[];\n      /** The selected rectangle as an Excel/Sheets-compatible TSV block. */\n      tsv: string;\n      cellCount: number;\n    }\n  | { level: \"table\"; rowCount: number; columnIds: string[] };\n\n/** Plain-English name for a level, for a host that labels its sections. */\nexport function describeMenuLevel(payload: MatrxTableMenuPayload): string {\n  switch (payload.level) {\n    case \"cell\":\n      return payload.columnLabel;\n    case \"row\":\n      return \"Row\";\n    case \"column\":\n      return payload.columnLabel;\n    case \"selection\": {\n      const cells = payload.cellCount;\n      return `${cells} ${cells === 1 ? \"cell\" : \"cells\"}`;\n    }\n    case \"table\":\n      return \"Table\";\n  }\n}\n\n/* ─────────────────────────────────────────────────────────────────────────────\n * WHAT THE MENU SAYS — neutral sections a consumer adds to a level.\n *\n * The levels above answer WHICH thing was aimed at. A consumer that knows what\n * can be DONE to it (cut a cell, insert a row, rename a column, colour by a\n * field) says so with these plain objects, and the host draws them in its own\n * right-click menu — the package never renders a menu and the consumer never\n * learns which menu system the application uses. The same item shape fills the\n * column header's own menu (`MatrxColumnDef.headerMenu`), so a column action\n * reads the same in the header menu and on a right-click.\n *\n * The vocabulary is the one the /data grid's menus already speak (sections\n * Cell, Row, Column, Table; label, icon, shortcut hint, disabled-with-reason,\n * submenu), so those builders can move onto it unchanged in meaning.\n * ─────────────────────────────────────────────────────────────────────────── */\n\n/**\n * The icons a table menu item may name, lucide ids. Names, not glyphs: the\n * host maps each to its own icon set, so the package ships no icon library and\n * a host that has no glyph for a name simply draws the label.\n */\nexport const MATRX_TABLE_MENU_ICON_NAMES = [\n  \"copy\",\n  \"copy-plus\",\n  \"scissors\",\n  \"clipboard-paste\",\n  \"eraser\",\n  \"pencil\",\n  \"plus\",\n  \"trash\",\n  \"eye-off\",\n  \"arrow-up-a-z\",\n  \"arrow-down-a-z\",\n  \"arrow-up-down\",\n  \"arrow-down-to-line\",\n  \"palette\",\n  \"paintbrush\",\n  \"panel-left\",\n  \"panel-right\",\n  \"settings\",\n  \"sigma\",\n  \"zap\",\n  \"history\",\n  \"link\",\n  \"tag\",\n  \"filter\",\n] as const;\nexport type MatrxTableMenuIconName = (typeof MATRX_TABLE_MENU_ICON_NAMES)[number];\n\n/** One thing a person can do from a table menu. */\nexport interface MatrxTableMenuItem {\n  /** Stable id, unique within its section. */\n  id: string;\n  label: string;\n  icon?: MatrxTableMenuIconName | undefined;\n  /** Right-aligned keyboard hint, e.g. \"⌘C\". A hint only — the table binds no key for it. */\n  shortcut?: string | undefined;\n  /**\n   * PRESENT MEANS UNAVAILABLE HERE, and the sentence says why. The item keeps\n   * its place and its label and cannot fire — a menu whose rows appear and\n   * vanish per table teaches nothing; a disabled row that says \"View-only\n   * table\" teaches where the limit is.\n   */\n  disabledReason?: string | undefined;\n  /** Drawn in the destructive style (delete, clear). */\n  destructive?: boolean | undefined;\n  /** What choosing it does. Omit only for an item that carries a `submenu`. */\n  onSelect?: (() => void) | undefined;\n  /** Nested choices (a colour, a column to label by). */\n  submenu?: MatrxTableMenuItem[] | undefined;\n}\n\n/** A titled group of items — \"Cell\", \"Row\", \"Column\", \"Table\". */\nexport interface MatrxTableMenuSection {\n  /** Stable id, unique within one menu. */\n  id: string;\n  title: string;\n  items: MatrxTableMenuItem[];\n  /**\n   * The section for the thing that was actually right-clicked. The host draws\n   * it first and inline; at most one section per menu should carry it.\n   */\n  primary?: boolean | undefined;\n}\n\n/**\n * Asked by the host when its menu opens, with the level the pointer was aimed\n * at (read by `readMenuTarget`). The table resolves the row, column or\n * selection itself and answers the consumer's sections for it — an empty list\n * when there are none.\n */\nexport type MatrxTableMenuSectionsResolver = (target: MatrxTableMenuTarget) => MatrxTableMenuSection[];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgDO,IAAM,sBAAsB;AAC5B,IAAM,oBAAoB;AAC1B,IAAM,sBAAsB;AAC5B,IAAM,yBAAyB;AAC/B,IAAM,2BAA2B;AAEjC,IAAM,2BAA2B;AAOxC,SAAS,KAAK,SAAgC,MAAkC;AAC9E,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,QAAQ,QAAQ,QAAQ,IAAI,IAAI,GAAG;AACzC,QAAM,QAAQ,OAAO,aAAa,IAAI;AACtC,SAAO,UAAU,QAAQ,UAAU,UAAa,UAAU,KAAK,SAAY;AAC7E;AAQO,SAAS,eACd,QAC6B;AAC7B,QAAM,UAAU,KAAK,QAAQ,mBAAmB;AAChD,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,iBAAiB,KAAK,QAAQ,wBAAwB;AAC5D,MAAI,eAAgB,QAAO,EAAE,SAAS,OAAO,UAAU,UAAU,eAAe;AAKhF,QAAM,eAAe,KAAK,QAAQ,sBAAsB;AACxD,QAAM,YAAY,KAAK,QAAQ,iBAAiB,KAAK,KAAK,QAAQ,mBAAmB;AACrF,QAAM,QAAQ;AAEd,MAAI,aAAa,cAAc;AAI7B,UAAM,WAAW,KAAK,QAAQ,wBAAwB,MAAM;AAC5D,QAAI,SAAU,QAAO,EAAE,SAAS,OAAO,aAAa,OAAO,WAAW,UAAU,aAAa;AAC7F,WAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,WAAW,UAAU,aAAa;AAAA,EAC5E;AAEA,MAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM;AACjD,SAAO,EAAE,SAAS,OAAO,QAAQ;AACnC;AAyCO,SAAS,kBAAkB,SAAwC;AACxE,UAAQ,QAAQ,OAAO;AAAA,IACrB,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK,aAAa;AAChB,YAAM,QAAQ,QAAQ;AACtB,aAAO,GAAG,KAAK,IAAI,UAAU,IAAI,SAAS,OAAO;AAAA,IACnD;AAAA,IACA,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAuBO,IAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/dist/data-table/menu-targets.d.cts

@@ -104,5 +104,53 @@ type MatrxTableMenuPayload<T = unknown> = {
 };
 /** Plain-English name for a level, for a host that labels its sections. */
 declare function describeMenuLevel(payload: MatrxTableMenuPayload): string;
+/**
+ * The icons a table menu item may name, lucide ids. Names, not glyphs: the
+ * host maps each to its own icon set, so the package ships no icon library and
+ * a host that has no glyph for a name simply draws the label.
+ */
+declare const MATRX_TABLE_MENU_ICON_NAMES: readonly ["copy", "copy-plus", "scissors", "clipboard-paste", "eraser", "pencil", "plus", "trash", "eye-off", "arrow-up-a-z", "arrow-down-a-z", "arrow-up-down", "arrow-down-to-line", "palette", "paintbrush", "panel-left", "panel-right", "settings", "sigma", "zap", "history", "link", "tag", "filter"];
+type MatrxTableMenuIconName = (typeof MATRX_TABLE_MENU_ICON_NAMES)[number];
+/** One thing a person can do from a table menu. */
+interface MatrxTableMenuItem {
+    /** Stable id, unique within its section. */
+    id: string;
+    label: string;
+    icon?: MatrxTableMenuIconName | undefined;
+    /** Right-aligned keyboard hint, e.g. "⌘C". A hint only — the table binds no key for it. */
+    shortcut?: string | undefined;
+    /**
+     * PRESENT MEANS UNAVAILABLE HERE, and the sentence says why. The item keeps
+     * its place and its label and cannot fire — a menu whose rows appear and
+     * vanish per table teaches nothing; a disabled row that says "View-only
+     * table" teaches where the limit is.
+     */
+    disabledReason?: string | undefined;
+    /** Drawn in the destructive style (delete, clear). */
+    destructive?: boolean | undefined;
+    /** What choosing it does. Omit only for an item that carries a `submenu`. */
+    onSelect?: (() => void) | undefined;
+    /** Nested choices (a colour, a column to label by). */
+    submenu?: MatrxTableMenuItem[] | undefined;
+}
+/** A titled group of items — "Cell", "Row", "Column", "Table". */
+interface MatrxTableMenuSection {
+    /** Stable id, unique within one menu. */
+    id: string;
+    title: string;
+    items: MatrxTableMenuItem[];
+    /**
+     * The section for the thing that was actually right-clicked. The host draws
+     * it first and inline; at most one section per menu should carry it.
+     */
+    primary?: boolean | undefined;
+}
+/**
+ * Asked by the host when its menu opens, with the level the pointer was aimed
+ * at (read by `readMenuTarget`). The table resolves the row, column or
+ * selection itself and answers the consumer's sections for it — an empty list
+ * when there are none.
+ */
+type MatrxTableMenuSectionsResolver = (target: MatrxTableMenuTarget) => MatrxTableMenuSection[];
 
-export { MATRX_CELL_COLUMN_ATTR, MATRX_CELL_ROW_ATTR, MATRX_CELL_SELECTED_ATTR, MATRX_HEADER_COLUMN_ATTR, MATRX_ROW_ID_ATTR, MATRX_TABLE_ID_ATTR, type MatrxTableMenuLevel, type MatrxTableMenuPayload, type MatrxTableMenuTarget, describeMenuLevel, readMenuTarget };
+export { MATRX_CELL_COLUMN_ATTR, MATRX_CELL_ROW_ATTR, MATRX_CELL_SELECTED_ATTR, MATRX_HEADER_COLUMN_ATTR, MATRX_ROW_ID_ATTR, MATRX_TABLE_ID_ATTR, MATRX_TABLE_MENU_ICON_NAMES, type MatrxTableMenuIconName, type MatrxTableMenuItem, type MatrxTableMenuLevel, type MatrxTableMenuPayload, type MatrxTableMenuSection, type MatrxTableMenuSectionsResolver, type MatrxTableMenuTarget, describeMenuLevel, readMenuTarget };

package/dist/data-table/menu-targets.d.ts

@@ -104,5 +104,53 @@ type MatrxTableMenuPayload<T = unknown> = {
 };
 /** Plain-English name for a level, for a host that labels its sections. */
 declare function describeMenuLevel(payload: MatrxTableMenuPayload): string;
+/**
+ * The icons a table menu item may name, lucide ids. Names, not glyphs: the
+ * host maps each to its own icon set, so the package ships no icon library and
+ * a host that has no glyph for a name simply draws the label.
+ */
+declare const MATRX_TABLE_MENU_ICON_NAMES: readonly ["copy", "copy-plus", "scissors", "clipboard-paste", "eraser", "pencil", "plus", "trash", "eye-off", "arrow-up-a-z", "arrow-down-a-z", "arrow-up-down", "arrow-down-to-line", "palette", "paintbrush", "panel-left", "panel-right", "settings", "sigma", "zap", "history", "link", "tag", "filter"];
+type MatrxTableMenuIconName = (typeof MATRX_TABLE_MENU_ICON_NAMES)[number];
+/** One thing a person can do from a table menu. */
+interface MatrxTableMenuItem {
+    /** Stable id, unique within its section. */
+    id: string;
+    label: string;
+    icon?: MatrxTableMenuIconName | undefined;
+    /** Right-aligned keyboard hint, e.g. "⌘C". A hint only — the table binds no key for it. */
+    shortcut?: string | undefined;
+    /**
+     * PRESENT MEANS UNAVAILABLE HERE, and the sentence says why. The item keeps
+     * its place and its label and cannot fire — a menu whose rows appear and
+     * vanish per table teaches nothing; a disabled row that says "View-only
+     * table" teaches where the limit is.
+     */
+    disabledReason?: string | undefined;
+    /** Drawn in the destructive style (delete, clear). */
+    destructive?: boolean | undefined;
+    /** What choosing it does. Omit only for an item that carries a `submenu`. */
+    onSelect?: (() => void) | undefined;
+    /** Nested choices (a colour, a column to label by). */
+    submenu?: MatrxTableMenuItem[] | undefined;
+}
+/** A titled group of items — "Cell", "Row", "Column", "Table". */
+interface MatrxTableMenuSection {
+    /** Stable id, unique within one menu. */
+    id: string;
+    title: string;
+    items: MatrxTableMenuItem[];
+    /**
+     * The section for the thing that was actually right-clicked. The host draws
+     * it first and inline; at most one section per menu should carry it.
+     */
+    primary?: boolean | undefined;
+}
+/**
+ * Asked by the host when its menu opens, with the level the pointer was aimed
+ * at (read by `readMenuTarget`). The table resolves the row, column or
+ * selection itself and answers the consumer's sections for it — an empty list
+ * when there are none.
+ */
+type MatrxTableMenuSectionsResolver = (target: MatrxTableMenuTarget) => MatrxTableMenuSection[];
 
-export { MATRX_CELL_COLUMN_ATTR, MATRX_CELL_ROW_ATTR, MATRX_CELL_SELECTED_ATTR, MATRX_HEADER_COLUMN_ATTR, MATRX_ROW_ID_ATTR, MATRX_TABLE_ID_ATTR, type MatrxTableMenuLevel, type MatrxTableMenuPayload, type MatrxTableMenuTarget, describeMenuLevel, readMenuTarget };
+export { MATRX_CELL_COLUMN_ATTR, MATRX_CELL_ROW_ATTR, MATRX_CELL_SELECTED_ATTR, MATRX_HEADER_COLUMN_ATTR, MATRX_ROW_ID_ATTR, MATRX_TABLE_ID_ATTR, MATRX_TABLE_MENU_ICON_NAMES, type MatrxTableMenuIconName, type MatrxTableMenuItem, type MatrxTableMenuLevel, type MatrxTableMenuPayload, type MatrxTableMenuSection, type MatrxTableMenuSectionsResolver, type MatrxTableMenuTarget, describeMenuLevel, readMenuTarget };

package/dist/data-table/menu-targets.js

@@ -44,6 +44,32 @@ function describeMenuLevel(payload) {
       return "Table";
   }
 }
+var MATRX_TABLE_MENU_ICON_NAMES = [
+  "copy",
+  "copy-plus",
+  "scissors",
+  "clipboard-paste",
+  "eraser",
+  "pencil",
+  "plus",
+  "trash",
+  "eye-off",
+  "arrow-up-a-z",
+  "arrow-down-a-z",
+  "arrow-up-down",
+  "arrow-down-to-line",
+  "palette",
+  "paintbrush",
+  "panel-left",
+  "panel-right",
+  "settings",
+  "sigma",
+  "zap",
+  "history",
+  "link",
+  "tag",
+  "filter"
+];
 export {
   MATRX_CELL_COLUMN_ATTR,
   MATRX_CELL_ROW_ATTR,
@@ -51,6 +77,7 @@ export {
   MATRX_HEADER_COLUMN_ATTR,
   MATRX_ROW_ID_ATTR,
   MATRX_TABLE_ID_ATTR,
+  MATRX_TABLE_MENU_ICON_NAMES,
   describeMenuLevel,
   readMenuTarget
 };

package/dist/data-table/menu-targets.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/data-table/menu-targets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — WHAT WAS RIGHT-CLICKED.\n *\n * A spreadsheet's right-click menu is not one menu: it is four, and which one\n * you get is decided by where the pointer was. A cell, the row it sits in, the\n * column it sits under, and — when the click lands inside an extended range —\n * the selection. The canonical table used to expose exactly ONE of those four\n * (the row), so every surface that wanted the other three forked the table.\n *\n * This module is the pure half of the fix: it reads the four levels off the\n * DOM anchors the table already renders, and nothing more. It does not build a\n * menu, name an action, or know what a menu is — the platform's universal\n * right-click menu is an application concern and stays there. The table's job\n * is to answer, truthfully, WHICH thing the person aimed at.\n *\n * THE PRECEDENCE, and why it is this way:\n *\n *   selection > cell > column > row > table\n *\n * A click inside an extended range means the range, because that is what the\n * person is looking at and what every spreadsheet acts on — taking the single\n * cell under the cursor there would silently throw away their selection. A\n * header click is the column even though the header is inside the table. A\n * click on a row but outside any cell (the checkbox gutter, the actions cell)\n * is the row. Anything else in the table is the table.\n *\n * Pure: no React, no package state. It reads `data-*` attributes and returns a\n * plain object. Nothing here throws on any input.\n */\n\n/** Which of the four things the pointer was aimed at. */\nexport type MatrxTableMenuLevel = \"cell\" | \"row\" | \"column\" | \"selection\" | \"table\";\n\nexport interface MatrxTableMenuTarget {\n  /** The table instance the click landed in. */\n  tableId: string;\n  level: MatrxTableMenuLevel;\n  /** Present for \"cell\" and \"row\". */\n  rowId?: string;\n  /** Present for \"cell\" and \"column\". */\n  columnId?: string;\n}\n\n/**\n * Attribute names, in one place, so the renderer and the reader cannot drift.\n * `data-row-id` predates this module and keeps its name: it is already read by\n * the row-drag preview and by every host that wired the row menu.\n */\nexport const MATRX_TABLE_ID_ATTR = \"data-matrx-table-id\";\nexport const MATRX_ROW_ID_ATTR = \"data-row-id\";\nexport const MATRX_CELL_ROW_ATTR = \"data-matrx-cell-row\";\nexport const MATRX_CELL_COLUMN_ATTR = \"data-matrx-table-column-id\";\nexport const MATRX_HEADER_COLUMN_ATTR = \"data-matrx-header-column-id\";\n/** Marks a cell that is inside the current extended range. */\nexport const MATRX_CELL_SELECTED_ATTR = \"data-matrx-cell-selected\";\n\ninterface MinimalElement {\n  closest(selector: string): MinimalElement | null;\n  getAttribute(name: string): string | null;\n}\n\nfunction attr(element: MinimalElement | null, name: string): string | undefined {\n  if (!element) return undefined;\n  const found = element.closest(`[${name}]`);\n  const value = found?.getAttribute(name);\n  return value === null || value === undefined || value === \"\" ? undefined : value;\n}\n\n/**\n * Read the four levels off the clicked element.\n *\n * Returns null when the click did not land in a canonical table at all — which\n * is the signal a host needs to leave its own page-level menu alone.\n */\nexport function readMenuTarget(\n  target: MinimalElement | null,\n): MatrxTableMenuTarget | null {\n  const tableId = attr(target, MATRX_TABLE_ID_ATTR);\n  if (!tableId) return null;\n\n  const headerColumnId = attr(target, MATRX_HEADER_COLUMN_ATTR);\n  if (headerColumnId) return { tableId, level: \"column\", columnId: headerColumnId };\n\n  // A cell's row comes from the `<tr>` it is in, which every table renders —\n  // the spreadsheet cursor's own row attribute is a second opinion, used only\n  // when the table is windowed sideways and the row wrapper is not an ancestor.\n  const cellColumnId = attr(target, MATRX_CELL_COLUMN_ATTR);\n  const cellRowId = attr(target, MATRX_ROW_ID_ATTR) ?? attr(target, MATRX_CELL_ROW_ATTR);\n  const rowId = cellRowId;\n\n  if (cellRowId && cellColumnId) {\n    // Inside an extended range the SELECTION is what the person sees and what\n    // the menu must act on. A range of one cell is not a range — acting on it\n    // as a selection would give a lone cell the plural verbs.\n    const selected = attr(target, MATRX_CELL_SELECTED_ATTR) === \"true\";\n    if (selected) return { tableId, level: \"selection\", rowId: cellRowId, columnId: cellColumnId };\n    return { tableId, level: \"cell\", rowId: cellRowId, columnId: cellColumnId };\n  }\n\n  if (rowId) return { tableId, level: \"row\", rowId };\n  return { tableId, level: \"table\" };\n}\n\n/**\n * The payload the table hands its host for the level that was clicked.\n *\n * The host builds the menu from this and never reaches back into the table.\n * Every level carries the table's own count of what it is acting on, because a\n * menu that says \"Clear 12 cells\" and clears 40 is worse than one that says\n * nothing.\n */\nexport type MatrxTableMenuPayload<T = unknown> =\n  | {\n      level: \"cell\";\n      row: T;\n      rowId: string;\n      columnId: string;\n      columnLabel: string;\n      value: unknown;\n      /** The cell's value as the table displays it, for Copy. */\n      text: string;\n      controls: unknown;\n    }\n  | { level: \"row\"; row: T; rowId: string; controls: unknown }\n  | {\n      level: \"column\";\n      columnId: string;\n      columnLabel: string;\n      /** Every rendered row's value for this column, in visual order. */\n      values: unknown[];\n    }\n  | {\n      level: \"selection\";\n      rowIds: string[];\n      columnIds: string[];\n      /** The selected rectangle as an Excel/Sheets-compatible TSV block. */\n      tsv: string;\n      cellCount: number;\n    }\n  | { level: \"table\"; rowCount: number; columnIds: string[] };\n\n/** Plain-English name for a level, for a host that labels its sections. */\nexport function describeMenuLevel(payload: MatrxTableMenuPayload): string {\n  switch (payload.level) {\n    case \"cell\":\n      return payload.columnLabel;\n    case \"row\":\n      return \"Row\";\n    case \"column\":\n      return payload.columnLabel;\n    case \"selection\": {\n      const cells = payload.cellCount;\n      return `${cells} ${cells === 1 ? \"cell\" : \"cells\"}`;\n    }\n    case \"table\":\n      return \"Table\";\n  }\n}\n"],"mappings":";;AAgDO,IAAM,sBAAsB;AAC5B,IAAM,oBAAoB;AAC1B,IAAM,sBAAsB;AAC5B,IAAM,yBAAyB;AAC/B,IAAM,2BAA2B;AAEjC,IAAM,2BAA2B;AAOxC,SAAS,KAAK,SAAgC,MAAkC;AAC9E,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,QAAQ,QAAQ,QAAQ,IAAI,IAAI,GAAG;AACzC,QAAM,QAAQ,OAAO,aAAa,IAAI;AACtC,SAAO,UAAU,QAAQ,UAAU,UAAa,UAAU,KAAK,SAAY;AAC7E;AAQO,SAAS,eACd,QAC6B;AAC7B,QAAM,UAAU,KAAK,QAAQ,mBAAmB;AAChD,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,iBAAiB,KAAK,QAAQ,wBAAwB;AAC5D,MAAI,eAAgB,QAAO,EAAE,SAAS,OAAO,UAAU,UAAU,eAAe;AAKhF,QAAM,eAAe,KAAK,QAAQ,sBAAsB;AACxD,QAAM,YAAY,KAAK,QAAQ,iBAAiB,KAAK,KAAK,QAAQ,mBAAmB;AACrF,QAAM,QAAQ;AAEd,MAAI,aAAa,cAAc;AAI7B,UAAM,WAAW,KAAK,QAAQ,wBAAwB,MAAM;AAC5D,QAAI,SAAU,QAAO,EAAE,SAAS,OAAO,aAAa,OAAO,WAAW,UAAU,aAAa;AAC7F,WAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,WAAW,UAAU,aAAa;AAAA,EAC5E;AAEA,MAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM;AACjD,SAAO,EAAE,SAAS,OAAO,QAAQ;AACnC;AAyCO,SAAS,kBAAkB,SAAwC;AACxE,UAAQ,QAAQ,OAAO;AAAA,IACrB,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK,aAAa;AAChB,YAAM,QAAQ,QAAQ;AACtB,aAAO,GAAG,KAAK,IAAI,UAAU,IAAI,SAAS,OAAO;AAAA,IACnD;AAAA,IACA,KAAK;AACH,aAAO;AAAA,EACX;AACF;","names":[]}
+{"version":3,"sources":["../../src/data-table/menu-targets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — WHAT WAS RIGHT-CLICKED.\n *\n * A spreadsheet's right-click menu is not one menu: it is four, and which one\n * you get is decided by where the pointer was. A cell, the row it sits in, the\n * column it sits under, and — when the click lands inside an extended range —\n * the selection. The canonical table used to expose exactly ONE of those four\n * (the row), so every surface that wanted the other three forked the table.\n *\n * This module is the pure half of the fix: it reads the four levels off the\n * DOM anchors the table already renders, and nothing more. It does not build a\n * menu, name an action, or know what a menu is — the platform's universal\n * right-click menu is an application concern and stays there. The table's job\n * is to answer, truthfully, WHICH thing the person aimed at.\n *\n * THE PRECEDENCE, and why it is this way:\n *\n *   selection > cell > column > row > table\n *\n * A click inside an extended range means the range, because that is what the\n * person is looking at and what every spreadsheet acts on — taking the single\n * cell under the cursor there would silently throw away their selection. A\n * header click is the column even though the header is inside the table. A\n * click on a row but outside any cell (the checkbox gutter, the actions cell)\n * is the row. Anything else in the table is the table.\n *\n * Pure: no React, no package state. It reads `data-*` attributes and returns a\n * plain object. Nothing here throws on any input.\n */\n\n/** Which of the four things the pointer was aimed at. */\nexport type MatrxTableMenuLevel = \"cell\" | \"row\" | \"column\" | \"selection\" | \"table\";\n\nexport interface MatrxTableMenuTarget {\n  /** The table instance the click landed in. */\n  tableId: string;\n  level: MatrxTableMenuLevel;\n  /** Present for \"cell\" and \"row\". */\n  rowId?: string;\n  /** Present for \"cell\" and \"column\". */\n  columnId?: string;\n}\n\n/**\n * Attribute names, in one place, so the renderer and the reader cannot drift.\n * `data-row-id` predates this module and keeps its name: it is already read by\n * the row-drag preview and by every host that wired the row menu.\n */\nexport const MATRX_TABLE_ID_ATTR = \"data-matrx-table-id\";\nexport const MATRX_ROW_ID_ATTR = \"data-row-id\";\nexport const MATRX_CELL_ROW_ATTR = \"data-matrx-cell-row\";\nexport const MATRX_CELL_COLUMN_ATTR = \"data-matrx-table-column-id\";\nexport const MATRX_HEADER_COLUMN_ATTR = \"data-matrx-header-column-id\";\n/** Marks a cell that is inside the current extended range. */\nexport const MATRX_CELL_SELECTED_ATTR = \"data-matrx-cell-selected\";\n\ninterface MinimalElement {\n  closest(selector: string): MinimalElement | null;\n  getAttribute(name: string): string | null;\n}\n\nfunction attr(element: MinimalElement | null, name: string): string | undefined {\n  if (!element) return undefined;\n  const found = element.closest(`[${name}]`);\n  const value = found?.getAttribute(name);\n  return value === null || value === undefined || value === \"\" ? undefined : value;\n}\n\n/**\n * Read the four levels off the clicked element.\n *\n * Returns null when the click did not land in a canonical table at all — which\n * is the signal a host needs to leave its own page-level menu alone.\n */\nexport function readMenuTarget(\n  target: MinimalElement | null,\n): MatrxTableMenuTarget | null {\n  const tableId = attr(target, MATRX_TABLE_ID_ATTR);\n  if (!tableId) return null;\n\n  const headerColumnId = attr(target, MATRX_HEADER_COLUMN_ATTR);\n  if (headerColumnId) return { tableId, level: \"column\", columnId: headerColumnId };\n\n  // A cell's row comes from the `<tr>` it is in, which every table renders —\n  // the spreadsheet cursor's own row attribute is a second opinion, used only\n  // when the table is windowed sideways and the row wrapper is not an ancestor.\n  const cellColumnId = attr(target, MATRX_CELL_COLUMN_ATTR);\n  const cellRowId = attr(target, MATRX_ROW_ID_ATTR) ?? attr(target, MATRX_CELL_ROW_ATTR);\n  const rowId = cellRowId;\n\n  if (cellRowId && cellColumnId) {\n    // Inside an extended range the SELECTION is what the person sees and what\n    // the menu must act on. A range of one cell is not a range — acting on it\n    // as a selection would give a lone cell the plural verbs.\n    const selected = attr(target, MATRX_CELL_SELECTED_ATTR) === \"true\";\n    if (selected) return { tableId, level: \"selection\", rowId: cellRowId, columnId: cellColumnId };\n    return { tableId, level: \"cell\", rowId: cellRowId, columnId: cellColumnId };\n  }\n\n  if (rowId) return { tableId, level: \"row\", rowId };\n  return { tableId, level: \"table\" };\n}\n\n/**\n * The payload the table hands its host for the level that was clicked.\n *\n * The host builds the menu from this and never reaches back into the table.\n * Every level carries the table's own count of what it is acting on, because a\n * menu that says \"Clear 12 cells\" and clears 40 is worse than one that says\n * nothing.\n */\nexport type MatrxTableMenuPayload<T = unknown> =\n  | {\n      level: \"cell\";\n      row: T;\n      rowId: string;\n      columnId: string;\n      columnLabel: string;\n      value: unknown;\n      /** The cell's value as the table displays it, for Copy. */\n      text: string;\n      controls: unknown;\n    }\n  | { level: \"row\"; row: T; rowId: string; controls: unknown }\n  | {\n      level: \"column\";\n      columnId: string;\n      columnLabel: string;\n      /** Every rendered row's value for this column, in visual order. */\n      values: unknown[];\n    }\n  | {\n      level: \"selection\";\n      rowIds: string[];\n      columnIds: string[];\n      /** The selected rectangle as an Excel/Sheets-compatible TSV block. */\n      tsv: string;\n      cellCount: number;\n    }\n  | { level: \"table\"; rowCount: number; columnIds: string[] };\n\n/** Plain-English name for a level, for a host that labels its sections. */\nexport function describeMenuLevel(payload: MatrxTableMenuPayload): string {\n  switch (payload.level) {\n    case \"cell\":\n      return payload.columnLabel;\n    case \"row\":\n      return \"Row\";\n    case \"column\":\n      return payload.columnLabel;\n    case \"selection\": {\n      const cells = payload.cellCount;\n      return `${cells} ${cells === 1 ? \"cell\" : \"cells\"}`;\n    }\n    case \"table\":\n      return \"Table\";\n  }\n}\n\n/* ─────────────────────────────────────────────────────────────────────────────\n * WHAT THE MENU SAYS — neutral sections a consumer adds to a level.\n *\n * The levels above answer WHICH thing was aimed at. A consumer that knows what\n * can be DONE to it (cut a cell, insert a row, rename a column, colour by a\n * field) says so with these plain objects, and the host draws them in its own\n * right-click menu — the package never renders a menu and the consumer never\n * learns which menu system the application uses. The same item shape fills the\n * column header's own menu (`MatrxColumnDef.headerMenu`), so a column action\n * reads the same in the header menu and on a right-click.\n *\n * The vocabulary is the one the /data grid's menus already speak (sections\n * Cell, Row, Column, Table; label, icon, shortcut hint, disabled-with-reason,\n * submenu), so those builders can move onto it unchanged in meaning.\n * ─────────────────────────────────────────────────────────────────────────── */\n\n/**\n * The icons a table menu item may name, lucide ids. Names, not glyphs: the\n * host maps each to its own icon set, so the package ships no icon library and\n * a host that has no glyph for a name simply draws the label.\n */\nexport const MATRX_TABLE_MENU_ICON_NAMES = [\n  \"copy\",\n  \"copy-plus\",\n  \"scissors\",\n  \"clipboard-paste\",\n  \"eraser\",\n  \"pencil\",\n  \"plus\",\n  \"trash\",\n  \"eye-off\",\n  \"arrow-up-a-z\",\n  \"arrow-down-a-z\",\n  \"arrow-up-down\",\n  \"arrow-down-to-line\",\n  \"palette\",\n  \"paintbrush\",\n  \"panel-left\",\n  \"panel-right\",\n  \"settings\",\n  \"sigma\",\n  \"zap\",\n  \"history\",\n  \"link\",\n  \"tag\",\n  \"filter\",\n] as const;\nexport type MatrxTableMenuIconName = (typeof MATRX_TABLE_MENU_ICON_NAMES)[number];\n\n/** One thing a person can do from a table menu. */\nexport interface MatrxTableMenuItem {\n  /** Stable id, unique within its section. */\n  id: string;\n  label: string;\n  icon?: MatrxTableMenuIconName | undefined;\n  /** Right-aligned keyboard hint, e.g. \"⌘C\". A hint only — the table binds no key for it. */\n  shortcut?: string | undefined;\n  /**\n   * PRESENT MEANS UNAVAILABLE HERE, and the sentence says why. The item keeps\n   * its place and its label and cannot fire — a menu whose rows appear and\n   * vanish per table teaches nothing; a disabled row that says \"View-only\n   * table\" teaches where the limit is.\n   */\n  disabledReason?: string | undefined;\n  /** Drawn in the destructive style (delete, clear). */\n  destructive?: boolean | undefined;\n  /** What choosing it does. Omit only for an item that carries a `submenu`. */\n  onSelect?: (() => void) | undefined;\n  /** Nested choices (a colour, a column to label by). */\n  submenu?: MatrxTableMenuItem[] | undefined;\n}\n\n/** A titled group of items — \"Cell\", \"Row\", \"Column\", \"Table\". */\nexport interface MatrxTableMenuSection {\n  /** Stable id, unique within one menu. */\n  id: string;\n  title: string;\n  items: MatrxTableMenuItem[];\n  /**\n   * The section for the thing that was actually right-clicked. The host draws\n   * it first and inline; at most one section per menu should carry it.\n   */\n  primary?: boolean | undefined;\n}\n\n/**\n * Asked by the host when its menu opens, with the level the pointer was aimed\n * at (read by `readMenuTarget`). The table resolves the row, column or\n * selection itself and answers the consumer's sections for it — an empty list\n * when there are none.\n */\nexport type MatrxTableMenuSectionsResolver = (target: MatrxTableMenuTarget) => MatrxTableMenuSection[];\n"],"mappings":";;AAgDO,IAAM,sBAAsB;AAC5B,IAAM,oBAAoB;AAC1B,IAAM,sBAAsB;AAC5B,IAAM,yBAAyB;AAC/B,IAAM,2BAA2B;AAEjC,IAAM,2BAA2B;AAOxC,SAAS,KAAK,SAAgC,MAAkC;AAC9E,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,QAAQ,QAAQ,QAAQ,IAAI,IAAI,GAAG;AACzC,QAAM,QAAQ,OAAO,aAAa,IAAI;AACtC,SAAO,UAAU,QAAQ,UAAU,UAAa,UAAU,KAAK,SAAY;AAC7E;AAQO,SAAS,eACd,QAC6B;AAC7B,QAAM,UAAU,KAAK,QAAQ,mBAAmB;AAChD,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,iBAAiB,KAAK,QAAQ,wBAAwB;AAC5D,MAAI,eAAgB,QAAO,EAAE,SAAS,OAAO,UAAU,UAAU,eAAe;AAKhF,QAAM,eAAe,KAAK,QAAQ,sBAAsB;AACxD,QAAM,YAAY,KAAK,QAAQ,iBAAiB,KAAK,KAAK,QAAQ,mBAAmB;AACrF,QAAM,QAAQ;AAEd,MAAI,aAAa,cAAc;AAI7B,UAAM,WAAW,KAAK,QAAQ,wBAAwB,MAAM;AAC5D,QAAI,SAAU,QAAO,EAAE,SAAS,OAAO,aAAa,OAAO,WAAW,UAAU,aAAa;AAC7F,WAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,WAAW,UAAU,aAAa;AAAA,EAC5E;AAEA,MAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM;AACjD,SAAO,EAAE,SAAS,OAAO,QAAQ;AACnC;AAyCO,SAAS,kBAAkB,SAAwC;AACxE,UAAQ,QAAQ,OAAO;AAAA,IACrB,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,QAAQ;AAAA,IACjB,KAAK,aAAa;AAChB,YAAM,QAAQ,QAAQ;AACtB,aAAO,GAAG,KAAK,IAAI,UAAU,IAAI,SAAS,OAAO;AAAA,IACnD;AAAA,IACA,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAuBO,IAAM,8BAA8B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}