@pretable/ui 0.6.2 → 0.8.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/LICENSE CHANGED
@@ -19,3 +19,22 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
21
  SOFTWARE.
22
+
23
+ ---
24
+
25
+ Acknowledgements
26
+
27
+ @chenglou/pretext — MIT, Copyright (c) Pretext contributors
28
+ https://github.com/chenglou/pretext
29
+
30
+ Pretable's text layout predictor (`@pretable-internal/text-core`, together with
31
+ the canvas-backed measurer in `@pretable/react`) follows pretext's two-phase
32
+ design: measure each segment once, cache the result by (segment, font), and then
33
+ decide line breaks with pure arithmetic over those cached widths. Before that,
34
+ pretable modelled a whole font as a single number — pixels per character — and
35
+ wrapped by character count.
36
+
37
+ This is our own implementation against a different API, written independently
38
+ rather than adapted from pretext's source, so this acknowledgement is a courtesy
39
+ rather than a licence obligation. It is recorded because the idea is the load-
40
+ bearing part and it was not ours.
package/README.md CHANGED
@@ -50,7 +50,7 @@ Pick exactly one theme file. The theme files are unlayered and all declare at `:
50
50
 
51
51
  ### Density CSS variables
52
52
 
53
- The two variables `getDensityHeights()` reads:
53
+ The two variables `getDensityHeights` reads:
54
54
 
55
55
  | Variable | Purpose | JS fallback |
56
56
  | -------------------------- | ------------------ | ----------- |
@@ -59,7 +59,7 @@ The two variables `getDensityHeights()` reads:
59
59
 
60
60
  The fallbacks are hard-coded in [`src/density.ts`](./src/density.ts) and apply only when a variable is unset or is not a `<number>px` value — they are not a theme's values. Every shipped theme sets both at every density tier: `pretable` is `48px` / `52px` at standard, Excel `20px` / `24px` at its compact default.
61
61
 
62
- `@pretable/react` reads a third token in JS, `--pretable-group-panel-height`, and only while the drag-to-group panel is enabled. `getDensityHeights()` does not cover it; the remaining 47 tokens never enter JavaScript at all.
62
+ `@pretable/react` reads a third token in JS, `--pretable-group-panel-height`, and only while the drag-to-group panel is enabled. `getDensityHeights` does not cover it; the remaining 47 tokens never enter JavaScript at all.
63
63
 
64
64
  The full 50-token set is defined by the theme files in [`src/themes/`](./src/themes/); the [token reference](https://pretable.ai/docs/theming/token-reference) lists every name with its per-theme value. Override any token at `:root` or on a scoped element to change the look.
65
65
 
@@ -88,10 +88,26 @@ for the full contract.
88
88
  ```ts
89
89
  import { getDensityHeights } from "@pretable/ui";
90
90
 
91
+ // Reads the document root.
91
92
  const { rowHeight, headerHeight } = getDensityHeights();
93
+
94
+ // Reads whatever `element` paints under.
95
+ const scoped = getDensityHeights(element);
92
96
  ```
93
97
 
94
- `getDensityHeights()` is a synchronous snapshot of `--pretable-row-height` and `--pretable-header-height` on `document.documentElement`, with fallbacks of 32 / 36. SSR-safe (returns fallback values when `document` is undefined).
98
+ `getDensityHeights(element?: Element | null): DensityHeights` is a synchronous
99
+ snapshot of `--pretable-row-height` and `--pretable-header-height`, with
100
+ fallbacks of 32 / 36.
101
+
102
+ The tokens are inherited custom properties, so the element you pass decides the
103
+ answer: it resolves the values that element actually paints under, which is what
104
+ a `data-density` scoped to a wrapper sets — the root's own computed style never
105
+ sees it. Pass nothing and it reads `document.documentElement`, which is right
106
+ when the attribute lives on `<html>`. `@pretable/react` passes the grid's scroll
107
+ viewport, so a wrapper-scoped grid measures at the density it paints at. A
108
+ detached element resolves nothing in most browsers; read after mount.
109
+
110
+ SSR-safe (returns fallback values when `document` is undefined).
95
111
 
96
112
  See **[`ui.api.md`](./ui.api.md)** for the generated public-API report.
97
113
 
package/dist/grid.css CHANGED
@@ -134,6 +134,25 @@
134
134
  <span style="min-width:0; overflow:hidden; text-overflow:ellipsis">
135
135
  via a column's `render`. */
136
136
  overflow: hidden;
137
+ /* A marquee cell-range drag (pointerdown -> move -> up, see
138
+ pretable-surface.tsx) drags the pointer straight across this cell's
139
+ own text. Without this, at least local macOS WebKit starts its native
140
+ text-selection gesture on that same drag, painting a blue highlight
141
+ across the dragged cells.
142
+ This rule was originally added on the theory that this native
143
+ selection gesture was also the cause of a CI-only Linux WebKit bug
144
+ (the marquee range never growing past its anchor cell). It was NOT:
145
+ removing pointer capture from the drag (see marquee-drag.ts) fixed
146
+ that bug on its own, with no change here, so the native-selection
147
+ gesture was never the actual cause on CI. This rule stays anyway on
148
+ its own, narrower merit — a drag that is building a cell range
149
+ shouldn't simultaneously paint the browser's native text highlight
150
+ underneath it, regardless of which engine triggers that highlight or
151
+ whether doing so was ever what broke CI. Cell content is copied
152
+ through the grid's own Cmd/Ctrl+C range copy, never native OS text
153
+ selection, so losing native selectability here costs nothing
154
+ intended. */
155
+ user-select: none;
137
156
  }
138
157
 
139
158
  :where([data-pretable-cell]:last-of-type) {
@@ -741,6 +760,49 @@
741
760
  cursor: pointer;
742
761
  opacity: 0;
743
762
  transition: opacity 0.1s ease;
763
+ /* Containing block for the ::after hit area below. */
764
+ position: relative;
765
+ }
766
+ /* WCAG 2.5.8 (Target Size, Minimum) asks for 24x24 CSS px. The funnel drew
767
+ an 18x18 tap target on every filterable column, so a phone got an 18px
768
+ target on every header.
769
+ The GLYPH stays 18x18 — the header is dense by design and a bigger icon
770
+ would change the look of every grid — and the missing 6px is bought with a
771
+ transparent ::after. A pseudo-element rather than padding + negative
772
+ margin: padding would grow the button's own border box, and the button is
773
+ the thing the hover background and the focus ring are drawn on, so an
774
+ 18px glyph would suddenly wear a 24px hover chip. Out-of-flow also means
775
+ the header box cannot change size — @pretable/ui's `readDensity` and the
776
+ surface's virtualisation geometry both measure header/row height in JS,
777
+ and a change there would desynchronise painted from measured layout.
778
+ `right: 0`, NOT centred: the funnel's right edge is flush against the 4px
779
+ resize strip (the slots are parked at left:-22 and left:-4 off the
780
+ column's trailing edge — see pretable-surface.tsx). The strip is not at
781
+ risk — it carries z-index: 2 inside the overlay anchor's stacking context,
782
+ so it hit-tests above the funnel either way, and a centred box measurably
783
+ steals none of it. What a centred box costs is the FUNNEL: 3 of its 24px
784
+ land under the strip where nothing can ever tap them, and the reachable
785
+ target measures 21px — still short of the 24 this rule exists to reach.
786
+ (iPhone 13, hit-test sweep: right:0 → 24 wide, left:-3px → 21 wide.)
787
+ Growing leftward spends all 6px on the header cell instead, which is a
788
+ sort target hundreds of px wide.
789
+ Height is a flat 24px, not 100%: the tightest shipped header is Excel's
790
+ compact tier at exactly 24px, so 24 fits every tier without spilling into
791
+ the first data row.
792
+ KNOWN GAP: with the drag-to-group panel on, @pretable/react also renders an
793
+ 18px column-menu button immediately left of the funnel, and it paints above
794
+ the funnel's hit area (later in tree order, same stacking context). The
795
+ funnel then measures 24 tall but only ~17 wide. Three controls in the 40px
796
+ the overlay anchor allots cannot each have 24; closing that one needs the
797
+ slot offsets in pretable-surface.tsx to move, not another CSS rule. */
798
+ :where([data-pretable-filter-funnel])::after {
799
+ content: "";
800
+ position: absolute;
801
+ top: 50%;
802
+ right: 0;
803
+ width: 24px;
804
+ height: 24px;
805
+ transform: translateY(-50%);
744
806
  }
745
807
  /* Reveal funnels on header-row hover, on funnel keyboard focus, or when a
746
808
  filter is active. The header row is a flat list of sibling header cells,
package/dist/index.cjs CHANGED
@@ -8,14 +8,15 @@ function parsePx(value) {
8
8
  const match = trimmed.match(/^([\d.]+)px$/);
9
9
  return match ? parseFloat(match[1]) : null;
10
10
  }
11
- function getDensityHeights() {
12
- if (typeof document === "undefined") {
11
+ function getDensityHeights(element) {
12
+ const target = element ?? (typeof document === "undefined" ? null : document.documentElement);
13
+ if (target === null || typeof getComputedStyle !== "function") {
13
14
  return {
14
15
  rowHeight: FALLBACK_ROW_HEIGHT,
15
16
  headerHeight: FALLBACK_HEADER_HEIGHT
16
17
  };
17
18
  }
18
- const styles = getComputedStyle(document.documentElement);
19
+ const styles = getComputedStyle(target);
19
20
  const read = (name) => {
20
21
  if (typeof styles?.getPropertyValue !== "function") return "";
21
22
  return styles.getPropertyValue(name);
package/dist/index.d.cts CHANGED
@@ -8,14 +8,30 @@ interface DensityHeights {
8
8
  headerHeight: number;
9
9
  }
10
10
  /**
11
- * Synchronous snapshot of the resolved density-related CSS variables on
12
- * `document.documentElement`.
11
+ * Synchronous snapshot of the resolved density-related CSS variables, read
12
+ * from `element` — or from `document.documentElement` when none is given.
13
13
  *
14
14
  * Returns `{ rowHeight, headerHeight }` parsed from `--pretable-row-height`
15
15
  * and `--pretable-header-height`. Falls back to 32 / 36 when a variable is
16
16
  * unset, empty, or not parseable as a `<number>px` value.
17
17
  *
18
- * SSR-safe: returns the fallback values when `document` is undefined.
18
+ * ## Which element to pass
19
+ *
20
+ * These are CSS custom properties, so they INHERIT. Passing an element resolves
21
+ * the value that element actually paints under, which is what a `data-density`
22
+ * scoped to a wrapper (`<div data-density="compact">…`) sets — the root's own
23
+ * computed style never sees it. Passing nothing reads the root, which is right
24
+ * only when the density attribute lives on `<html>`.
25
+ *
26
+ * Pass the element whose geometry you are computing — the grid's own DOM node,
27
+ * or any descendant of the scoping wrapper. `@pretable/react` passes the grid's
28
+ * scroll viewport, so a wrapper-scoped grid measures at the density it paints
29
+ * at.
30
+ *
31
+ * A detached element resolves nothing in most browsers; read it after mount.
32
+ *
33
+ * SSR-safe: returns the fallback values when `document` is undefined, and when
34
+ * `element` is `null` or `undefined` and there is no document to fall back to.
19
35
  *
20
36
  * For non-React consumers, tests, custom virtualizers, and power users. This
21
37
  * is the only public way to read density into JavaScript: `@pretable/react`'s
@@ -25,6 +41,6 @@ interface DensityHeights {
25
41
  *
26
42
  * @public
27
43
  */
28
- declare function getDensityHeights(): DensityHeights;
44
+ declare function getDensityHeights(element?: Element | null): DensityHeights;
29
45
 
30
46
  export { type DensityHeights, getDensityHeights };
package/dist/index.d.ts CHANGED
@@ -8,14 +8,30 @@ interface DensityHeights {
8
8
  headerHeight: number;
9
9
  }
10
10
  /**
11
- * Synchronous snapshot of the resolved density-related CSS variables on
12
- * `document.documentElement`.
11
+ * Synchronous snapshot of the resolved density-related CSS variables, read
12
+ * from `element` — or from `document.documentElement` when none is given.
13
13
  *
14
14
  * Returns `{ rowHeight, headerHeight }` parsed from `--pretable-row-height`
15
15
  * and `--pretable-header-height`. Falls back to 32 / 36 when a variable is
16
16
  * unset, empty, or not parseable as a `<number>px` value.
17
17
  *
18
- * SSR-safe: returns the fallback values when `document` is undefined.
18
+ * ## Which element to pass
19
+ *
20
+ * These are CSS custom properties, so they INHERIT. Passing an element resolves
21
+ * the value that element actually paints under, which is what a `data-density`
22
+ * scoped to a wrapper (`<div data-density="compact">…`) sets — the root's own
23
+ * computed style never sees it. Passing nothing reads the root, which is right
24
+ * only when the density attribute lives on `<html>`.
25
+ *
26
+ * Pass the element whose geometry you are computing — the grid's own DOM node,
27
+ * or any descendant of the scoping wrapper. `@pretable/react` passes the grid's
28
+ * scroll viewport, so a wrapper-scoped grid measures at the density it paints
29
+ * at.
30
+ *
31
+ * A detached element resolves nothing in most browsers; read it after mount.
32
+ *
33
+ * SSR-safe: returns the fallback values when `document` is undefined, and when
34
+ * `element` is `null` or `undefined` and there is no document to fall back to.
19
35
  *
20
36
  * For non-React consumers, tests, custom virtualizers, and power users. This
21
37
  * is the only public way to read density into JavaScript: `@pretable/react`'s
@@ -25,6 +41,6 @@ interface DensityHeights {
25
41
  *
26
42
  * @public
27
43
  */
28
- declare function getDensityHeights(): DensityHeights;
44
+ declare function getDensityHeights(element?: Element | null): DensityHeights;
29
45
 
30
46
  export { type DensityHeights, getDensityHeights };
package/dist/index.mjs CHANGED
@@ -6,14 +6,15 @@ function parsePx(value) {
6
6
  const match = trimmed.match(/^([\d.]+)px$/);
7
7
  return match ? parseFloat(match[1]) : null;
8
8
  }
9
- function getDensityHeights() {
10
- if (typeof document === "undefined") {
9
+ function getDensityHeights(element) {
10
+ const target = element ?? (typeof document === "undefined" ? null : document.documentElement);
11
+ if (target === null || typeof getComputedStyle !== "function") {
11
12
  return {
12
13
  rowHeight: FALLBACK_ROW_HEIGHT,
13
14
  headerHeight: FALLBACK_HEADER_HEIGHT
14
15
  };
15
16
  }
16
- const styles = getComputedStyle(document.documentElement);
17
+ const styles = getComputedStyle(target);
17
18
  const read = (name) => {
18
19
  if (typeof styles?.getPropertyValue !== "function") return "";
19
20
  return styles.getPropertyValue(name);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pretable/ui",
3
- "version": "0.6.2",
3
+ "version": "0.8.0",
4
4
  "description": "CSS themes, tokens, and grid styles for Pretable.",
5
5
  "license": "MIT",
6
6
  "repository": {