@scalewing/react 1.33.1 → 1.34.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @scalewing/react
 
+## 1.34.0
+
+### Minor Changes
+
+- 7e4cbb2: A whole-row press for a table row's one action, such as a search result that is picked (`docs/requests/teisoro-table-row-press.md`, Teisoro F-011 task 2185):
+
+  - `TableRow pressable` (opt-in): a plain primary pointer press anywhere on the row activates the row's first link or button. A press with a modifier key, on another control in the row, already handled, or ending a text selection is left alone, as is a row whose action is disabled. The row is not a control (no role, no tab stop): keyboard and screen reader users use the action itself. The row takes the pointer cursor and the quiet fill while hovered, pressed, or while its action has keyboard focus (an outline in `Highlight` under forced colours), and underlines its action on hover.
+  - `TableCell onPress` (a body cell or a row header): the cell's children become a button in the cell's own text style at weight 600, underlined on hover and focus, for the row's action. A non-function value or one on a sortable header throws a `TypeError`.
+
+  New generated classes `sw-table-row-press` and `sw-table-action`. No new tokens, no new dependency.
+
 ## 1.33.1
 
 ### Patch Changes

package/README.md

@@ -403,6 +403,15 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 
 `Table` aligns data in rows inside its own keyboard-reachable scroll region, named after the table. While the table is wider than the region, each inline edge with columns scrolled out past it draws a soft inset shade (`sw-scroll-more-start`, `sw-scroll-more-end`, mirrored right to left), so a phone, whose scrollbars stay hidden, still shows that the table goes on; a table that fits draws none, and in forced colors the system scrollbar is the cue. `TableCell` takes `numeric` (tabular numerals, end aligned), `align` and `truncate`; `density="compact"` densifies cells. `TableRow selected` sets `aria-selected` and marks the row with a 4 px accent bar at its inline start (3:1 or more against the surface and the page), the right edge in a right-to-left table. The bar is drawn inside the first cell's padding and takes no layout space, so no column moves when a row is picked, and the row takes no fill, so text, muted and accent text keep their contrast; forced colors keep the bar in the system highlight.
 
+`TableRow pressable` (opt-in) makes the whole row the pointer target of its one action, such as a search result that is picked: a plain primary press anywhere on it calls `click()` on the row's first link or button, so the action's own handler runs. Left alone: a modifier key or non-primary button, a press already handled, a press on another control, a press that ends a text selection (text stays selectable), and a disabled or missing action. Keep one control in the row: a control placed before the action (an icon button, say) would take the row's press. The row is not a control (no role, no tab stop), so keyboard and screen reader users use the action itself. It takes the pointer cursor and the quiet fill while hovered, pressed (a brief flash on touch) or while its action has keyboard focus (a `Highlight` outline in forced colours), and underlines its action on hover (`sw-table-row-press`). A consumer `onClick` runs once per press. Each click of a double click presses the action, as a native button's would, so keep it safe to repeat. `TableCell onPress` (a body cell or a row header in `TableBody`) makes the cell's children that action: a button in the cell's own text style at weight 600, underlined on hover and focus, with the accent focus ring (`sw-table-action`); a non-function value or one on a sortable header throws a `TypeError`.
+
+```tsx
+<TableRow pressable>
+  <TableCell onPress={() => pick('Red fox')}>Red fox</TableCell>
+  <TableCell>Forest</TableCell>
+</TableRow>
+```
+
 A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `'none'`) and `onSort` is its column's sort control: its children become a button in the header's own style with a chevron (before the name in a `numeric` or end-aligned column), and the cell carries `aria-sort` only while it is the sorted column. `sort` on a data cell, or one of the two without the other, throws a `TypeError`. `Table` `layout="fixed"` (default `auto`) sizes the columns from the header row alone, so a filter that hides a row moves no column, and `verticalAlign="top"` (default `middle`) starts every cell of a tall row on its first line. `TableCell` `width` is `min` (an auto table's column takes the least room its content allows, on one line; set it on each cell of the column) or a size, `xs` to `xl` (4, 6, 8, 12 and 16 rem); in a fixed table a column without a width shares what is left, so leave one column, such as a description, unsized. The HTML `width` attribute is not accepted. Unknown values throw a `RangeError`.
 
 A ledger read across as well as down takes `Table` `columnRules` (a hairline at the inline start of every cell after a row's first, mirrored right to left) and `TableCell` `tone` (`success`, `danger`, `muted` or `accent`: the cell's text in the theme colour, as `Text color` uses it; never the only signal, so keep the sign or the words). `TableRow` `variant="sub"` (default `"default"`) sets a row under the one above, as a batch's items: its row header, a `TableCell as="th" scope="row"`, is indented a `space-6` step with a guide bar at the indent (a sub row without a row header is not indented). `TableRow` `struck` keeps a voided row on the record: the subtle fill and the text muted and struck through, toned cells included; it works with either variant. A line-through is not read aloud, so say why in the row, such as a `Badge` "Voided": a Badge in a line of text is not struck, but one that is itself a flex item (a direct child of `Inline`) is, so put it in the title's line. A row header in the body or footer (`th scope="row"`) reads as body text. An unknown `tone` or `variant` throws a `RangeError`.

package/dist/components/table/TableCell.d.ts

@@ -46,5 +46,14 @@ export type TableCellProps = ((Omit<TdHTMLAttributes<HTMLTableCellElement>, 'wid
      * is never the only signal: keep the sign or the words.
      */
     tone?: TableCellTone;
+    /**
+     * Makes the cell's children a button in the cell's own text style at
+     * weight 600, underlined while hovered or focused: a row's one action,
+     * such as the name of a search result that picks it. Pair it with
+     * `TableRow pressable` so a press anywhere on the row does the same. A
+     * body cell's (`td`, or a row header `th` in `TableBody`; not for a
+     * column header in `TableHeader`), never with `sort`.
+     */
+    onPress?: () => void;
 };
 export declare const TableCell: import("react").ForwardRefExoticComponent<TableCellProps & import("react").RefAttributes<HTMLTableCellElement>>;

package/dist/components/table/TableCell.js

@@ -4,6 +4,15 @@ import { cx } from '../../class-names.js';
 import { assertTableCellTone, } from '../../css/css-table-ledger.js';
 import { assertTableColumnWidth, tableColumnWidthClass, } from './table-layout.js';
 const tableSorts = ['ascending', 'descending', 'none'];
+/** A cell's press is a function, and never on a sortable header. */
+function assertPress(onPress, sort) {
+    if (onPress === undefined)
+        return;
+    if (typeof onPress !== 'function')
+        throw new TypeError('TableCell onPress is a function');
+    if (sort !== undefined)
+        throw new TypeError('TableCell onPress is not for a sortable header');
+}
 /** `sort` and `onSort` come together, on a header cell, with a known value. */
 function assertSort(as, sort, onSort) {
     if (sort === undefined && onSort === undefined)
@@ -15,8 +24,9 @@ function assertSort(as, sort, onSort) {
     if (!tableSorts.includes(sort))
         throw new RangeError(`Unknown TableCell sort: ${String(sort)}`);
 }
-export const TableCell = forwardRef(function TableCell({ align = 'start', as = 'td', children, className, numeric = false, onSort, sort, tone, truncate = false, width, ...rest }, ref) {
+export const TableCell = forwardRef(function TableCell({ align = 'start', as = 'td', children, className, numeric = false, onPress, onSort, sort, tone, truncate = false, width, ...rest }, ref) {
     assertSort(as, sort, onSort);
+    assertPress(onPress, sort);
     assertTableColumnWidth(width);
     assertTableCellTone(tone);
     const Component = as;
@@ -25,5 +35,5 @@ export const TableCell = forwardRef(function TableCell({ align = 'start', as = '
         : align === 'end'
             ? 'sw-table-end'
             : undefined;
-    return (_jsx(Component, { ref: ref, "aria-sort": sort === undefined || sort === 'none' ? undefined : sort, className: cx(alignmentClass, truncate && 'sw-table-clip', tone && `sw-table-tone-${tone}`, width && tableColumnWidthClass(width), className), ...rest, children: sort !== undefined && onSort ? (_jsxs("button", { className: "sw-table-sort", onClick: onSort, type: "button", children: [children, _jsx("span", { "aria-hidden": "true", className: cx('sw-table-sort-glyph', `sw-table-sort-${sort}`) })] })) : (children) }));
+    return (_jsx(Component, { ref: ref, "aria-sort": sort === undefined || sort === 'none' ? undefined : sort, className: cx(alignmentClass, truncate && 'sw-table-clip', tone && `sw-table-tone-${tone}`, width && tableColumnWidthClass(width), className), ...rest, children: sort !== undefined && onSort ? (_jsxs("button", { className: "sw-table-sort", onClick: onSort, type: "button", children: [children, _jsx("span", { "aria-hidden": "true", className: cx('sw-table-sort-glyph', `sw-table-sort-${sort}`) })] })) : onPress ? (_jsx("button", { className: "sw-table-action", onClick: onPress, type: "button", children: children })) : (children) }));
 });

package/dist/components/table/TableRow.d.ts

@@ -18,6 +18,21 @@ export type TableRowProps = HTMLAttributes<HTMLTableRowElement> & {
      * flex item, a direct child of `Inline`, is). Works with either variant.
      */
     struck?: boolean;
+    /**
+     * Makes the whole row a press target for its one action, such as a
+     * search result that is picked: the row's first link or button (a
+     * `TableCell onPress`, or a `Box as="a"`), so keep one control in the
+     * row. A plain pointer press anywhere else on the row activates that
+     * control, unless it is disabled; a press with a modifier key, on another
+     * control, or one that ends a text selection is left alone. The row takes
+     * the pointer cursor and the quiet fill while hovered, pressed, or while
+     * its action has keyboard focus. Keyboard and assistive technology use
+     * the action itself: the row is not a control and adds no tab stop.
+     * A consumer `onClick` runs once per press, not again for the click the
+     * row hands its action. Each click of a double click presses the action,
+     * as a native button's would, so keep the action safe to repeat.
+     */
+    pressable?: boolean;
 };
 export declare const TableRow: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLTableRowElement> & {
     selected?: boolean;
@@ -36,4 +51,19 @@ export declare const TableRow: import("react").ForwardRefExoticComponent<HTMLAtt
      * flex item, a direct child of `Inline`, is). Works with either variant.
      */
     struck?: boolean;
+    /**
+     * Makes the whole row a press target for its one action, such as a
+     * search result that is picked: the row's first link or button (a
+     * `TableCell onPress`, or a `Box as="a"`), so keep one control in the
+     * row. A plain pointer press anywhere else on the row activates that
+     * control, unless it is disabled; a press with a modifier key, on another
+     * control, or one that ends a text selection is left alone. The row takes
+     * the pointer cursor and the quiet fill while hovered, pressed, or while
+     * its action has keyboard focus. Keyboard and assistive technology use
+     * the action itself: the row is not a control and adds no tab stop.
+     * A consumer `onClick` runs once per press, not again for the click the
+     * row hands its action. Each click of a double click presses the action,
+     * as a native button's would, so keep the action safe to repeat.
+     */
+    pressable?: boolean;
 } & import("react").RefAttributes<HTMLTableRowElement>>;

package/dist/components/table/TableRow.js

@@ -1,8 +1,29 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef } from 'react';
+import { forwardRef, useRef, } from 'react';
 import { cx } from '../../class-names.js';
 import { assertTableRowVariant, } from '../../css/css-table-ledger.js';
-export const TableRow = forwardRef(function TableRow({ className, selected = false, struck = false, variant = 'default', ...rest }, ref) {
+import { rowPressAction } from './row-press.js';
+export const TableRow = forwardRef(function TableRow({ className, onClick, pressable = false, selected = false, struck = false, variant = 'default', ...rest }, ref) {
     assertTableRowVariant(variant);
-    return (_jsx("tr", { ref: ref, "aria-selected": selected || undefined, className: cx(selected && 'sw-table-row-selected', variant === 'sub' && 'sw-table-row-sub', struck && 'sw-table-row-struck', className), ...rest }));
+    // The click the row hands its action bubbles back to the row; it is
+    // the action's, so neither the row nor a consumer onClick takes it.
+    const forwarding = useRef(false);
+    const press = (event) => {
+        if (forwarding.current)
+            return;
+        onClick?.(event);
+        if (!pressable)
+            return;
+        const action = rowPressAction(event.currentTarget, event);
+        if (action === null)
+            return;
+        forwarding.current = true;
+        try {
+            action.click();
+        }
+        finally {
+            forwarding.current = false;
+        }
+    };
+    return (_jsx("tr", { ref: ref, "aria-selected": selected || undefined, className: cx(selected && 'sw-table-row-selected', variant === 'sub' && 'sw-table-row-sub', struck && 'sw-table-row-struck', pressable && 'sw-table-row-press', className), onClick: pressable || onClick ? press : undefined, ...rest }));
 });

package/dist/components/table/row-press.d.ts

@@ -0,0 +1,17 @@
+/** What `rowPressAction` reads of a click. */
+export type RowPress = {
+    button: number;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    defaultPrevented: boolean;
+    target: EventTarget | null;
+};
+/**
+ * The control a press on a pressable row activates, or none: a plain
+ * primary press (no modifier key, not already handled) that lands on the
+ * row but not on a control in it, and does not end a text selection, goes
+ * to the row's first link or button, unless that is disabled.
+ */
+export declare function rowPressAction(row: HTMLElement, press: RowPress): HTMLElement | null;

package/dist/components/table/row-press.js

@@ -0,0 +1,60 @@
+/**
+ * The controls a press on a pressable row leaves alone: a press on one of
+ * them is that control's own, never the row's.
+ */
+const controlSelector = [
+    'a[href]',
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'label',
+    'summary',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="checkbox"]',
+    '[role="switch"]',
+    '[role="menuitem"]',
+    '[role="option"]',
+    '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+/** The row's action: its first link or button. */
+const actionSelector = 'a[href], button';
+function isDisabled(action) {
+    return ((action instanceof HTMLButtonElement && action.disabled) ||
+        action.getAttribute('aria-disabled') === 'true');
+}
+/** A selection the press ended, such as text dragged over in the row. */
+function endsSelection(row) {
+    const selection = row.ownerDocument.getSelection();
+    if (selection === null || selection.isCollapsed)
+        return false;
+    for (let index = 0; index < selection.rangeCount; index += 1)
+        if (selection.getRangeAt(index).intersectsNode(row))
+            return true;
+    return false;
+}
+/**
+ * The control a press on a pressable row activates, or none: a plain
+ * primary press (no modifier key, not already handled) that lands on the
+ * row but not on a control in it, and does not end a text selection, goes
+ * to the row's first link or button, unless that is disabled.
+ */
+export function rowPressAction(row, press) {
+    if (press.defaultPrevented || press.button !== 0)
+        return null;
+    if (press.altKey || press.ctrlKey || press.metaKey || press.shiftKey)
+        return null;
+    if (!(press.target instanceof Element) || !row.contains(press.target))
+        return null;
+    const control = press.target.closest(controlSelector);
+    if (control !== null && control !== row && row.contains(control))
+        return null;
+    if (endsSelection(row))
+        return null;
+    const action = row.querySelector(actionSelector);
+    if (action === null || isDisabled(action))
+        return null;
+    return action;
+}

package/dist/css/css-table-press.d.ts

@@ -0,0 +1,2 @@
+export declare function cssTablePressClasses(): string;
+export declare function tablePressClassCatalog(): string[];

package/dist/css/css-table-press.js

@@ -0,0 +1,87 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { quietFill } from './quiet-fill.js';
+const row = '.sw-table-row-press';
+const action = '.sw-table-action';
+/*
+ * A pressable row: the pointer cursor over all of it, and the quiet fill
+ * on its cells while it is hovered (on a pointer that hovers), pressed, or
+ * while its action has keyboard focus, so a keyboard user sees the row the
+ * focused name belongs to. The fill sits under the cells' text, so text,
+ * muted text and toned figures keep their contrast as on any quiet-filled
+ * row (an open menu's). Its action is underlined with it, so the row reads
+ * as that one action. Forced colours drop fills, so the row is outlined in
+ * the system highlight instead.
+ */
+function pressableRowRules() {
+    return `${row} {
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  ${row}:hover > :is(td, th) {
+    background: ${quietFill};
+  }
+
+  ${row}:hover ${action} {
+    text-decoration-line: underline;
+  }
+}
+
+${row}:active > :is(td, th),
+${row}:has(:focus-visible) > :is(td, th) {
+  background: ${quietFill};
+}
+
+@media (forced-colors: active) {
+  ${row}:hover,
+  ${row}:has(:focus-visible) {
+    outline: var(--sw-focus-ring-width) solid Highlight;
+    outline-offset: calc(-1 * var(--sw-focus-ring-width));
+  }
+}`;
+}
+/*
+ * A cell's action keeps the cell's own text (its colour, size and
+ * alignment) at weight 600, the label weight, as a quiet link does: the
+ * weight, not a colour, sets the name apart from the row's other text.
+ * Hover and keyboard focus underline it; focus draws the accent ring.
+ * Forced colours paint it as any button's text.
+ */
+function actionRules() {
+    return `${action} {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: var(--sw-radius-sm);
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-weight: ${typographyVariants.label.fontWeight};
+  letter-spacing: inherit;
+  margin: 0;
+  padding: 0;
+  text-align: inherit;
+}
+
+${action}:hover,
+${action}:focus-visible {
+  text-decoration-line: underline;
+}
+
+${action}:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: var(--sw-focus-ring-offset);
+}
+
+@media (forced-colors: active) {
+  ${action} { color: ButtonText; }
+}`;
+}
+export function cssTablePressClasses() {
+    return `${pressableRowRules()}
+
+${actionRules()}`;
+}
+export function tablePressClassCatalog() {
+    return ['sw-table-row-press', 'sw-table-action'];
+}

package/dist/css/css-table.js

@@ -3,6 +3,7 @@ import { scrollRegionRules } from './css-scroll-region.js';
 import { cssTableLayoutClasses, tableLayoutClassCatalog, } from './css-table-layout.js';
 import { cssTableLedgerClasses, tableLedgerClassCatalog, } from './css-table-ledger.js';
 import { cssTableFooterClasses, tableFooterClassCatalog, } from './css-table-footer.js';
+import { cssTablePressClasses, tablePressClassCatalog, } from './css-table-press.js';
 import { cssTableSortClasses, tableSortClassCatalog, } from './css-table-sort.js';
 import { zIndex } from './stacking.js';
 const caption = typographyVariants.caption;
@@ -95,6 +96,8 @@ ${cssTableLedgerClasses()}
 
 ${cssTableFooterClasses()}
 
+${cssTablePressClasses()}
+
 ${selectedRowRules()}`;
 }
 export function tableClassCatalog() {
@@ -111,5 +114,6 @@ export function tableClassCatalog() {
         ...tableSortClassCatalog(),
         ...tableLedgerClassCatalog(),
         ...tableFooterClassCatalog(),
+        ...tablePressClassCatalog(),
     ];
 }

package/dist/styles.css

@@ -1841,6 +1841,62 @@ body {
   .sw-table-sticky thead th { background: Canvas; backdrop-filter: none; -webkit-backdrop-filter: none; }
 }
 
+.sw-table-row-press {
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .sw-table-row-press:hover > :is(td, th) {
+    background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent);
+  }
+
+  .sw-table-row-press:hover .sw-table-action {
+    text-decoration-line: underline;
+  }
+}
+
+.sw-table-row-press:active > :is(td, th),
+.sw-table-row-press:has(:focus-visible) > :is(td, th) {
+  background: color-mix(in srgb, var(--sw-color-muted) 16%, transparent);
+}
+
+@media (forced-colors: active) {
+  .sw-table-row-press:hover,
+  .sw-table-row-press:has(:focus-visible) {
+    outline: var(--sw-focus-ring-width) solid Highlight;
+    outline-offset: calc(-1 * var(--sw-focus-ring-width));
+  }
+}
+
+.sw-table-action {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: var(--sw-radius-sm);
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-weight: 600;
+  letter-spacing: inherit;
+  margin: 0;
+  padding: 0;
+  text-align: inherit;
+}
+
+.sw-table-action:hover,
+.sw-table-action:focus-visible {
+  text-decoration-line: underline;
+}
+
+.sw-table-action:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: var(--sw-focus-ring-offset);
+}
+
+@media (forced-colors: active) {
+  .sw-table-action { color: ButtonText; }
+}
+
 .sw-table-row-selected > :first-child {
   position: relative;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.33.1",
+  "version": "1.34.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",