@fusion.dev/helix-core 0.169.0 → 0.171.0

package/custom-elements.json

@@ -12743,6 +12743,14 @@
             "package": "#audit-name"
           }
         },
+        {
+          "kind": "js",
+          "name": "auditServed",
+          "declaration": {
+            "name": "auditServed",
+            "package": "#audit-served"
+          }
+        },
         {
           "kind": "js",
           "name": "AriaForwardController",
@@ -24552,6 +24560,82 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/audit-served/audit-served-off.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "auditServed",
+          "description": "The served-rows check in a production build: nothing.\n\n`#audit-served` resolves here unless the bundler or runtime asks for the\n`development` condition, so a production build carries none of the check's\ncode. The signature is the check's, so a call site reads the same in both\nbuilds. See `audit-served.ts`.",
+          "type": {
+            "text": "typeof audit"
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "auditServed",
+          "declaration": {
+            "name": "auditServed",
+            "module": "src/utils/audit-served/audit-served-off.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/audit-served/audit-served.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "auditServed",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "host",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "name": "served",
+              "type": {
+                "text": "readonly Element[]"
+              }
+            },
+            {
+              "name": "drawn",
+              "type": {
+                "text": "readonly Element[]"
+              }
+            },
+            {
+              "name": "page",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Reports a table whose first drawn page differs from the rows the page\nserved, which a reader sees as the rows changing under them once the\nscript runs.\n\n**The served rows are the page's own markup and the drawn ones are the\ntable's**, so nothing else can catch it: the two are made by different\ncode, often on different machines, and either can sort, page or format\ndifferently. Compared by the words in each cell, which is what a reader\nsees change, and only as far as the first difference.\n\n**In a development build only**, as `missing-name` is: every table would pay\nfor a sentence meant for the person writing the page. Core imports it as\n`#audit-served`, which `package.json` resolves here under the `development`\ncondition and to `audit-served-off.ts`, which does nothing, everywhere else.\n\n`served` are the rows the page wrote, `drawn` the rows the table drew in\ntheir place, and `page` how many rows the first page holds."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "auditServed",
+          "declaration": {
+            "name": "auditServed",
+            "module": "src/utils/audit-served/audit-served.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/audit-source/audit-source-off.ts",
@@ -30094,11 +30178,41 @@
           "kind": "variable",
           "name": "UNITS",
           "type": {
-            "text": "Array<{ ms: number; unit: Intl.RelativeTimeFormatUnit }>"
+            "text": "Unit[]"
           },
           "default": "[ { ms: 1000, unit: 'second' }, { ms: 60_000, unit: 'minute' }, { ms: 3_600_000, unit: 'hour' }, { ms: 86_400_000, unit: 'day' }, { ms: 604_800_000, unit: 'week' }, { ms: 2_629_800_000, unit: 'month' }, { ms: 31_557_600_000, unit: 'year' }, ]",
           "description": "How long each unit lasts, in milliseconds, largest last. `elapsedTime`\nreads its minute, hour and day from here."
         },
+        {
+          "kind": "function",
+          "name": "roundedCount",
+          "return": {
+            "type": {
+              "text": "{ count: number; index: number; next: number }"
+            }
+          },
+          "parameters": [
+            {
+              "name": "size",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "units",
+              "type": {
+                "text": "readonly U[]"
+              }
+            },
+            {
+              "name": "growing",
+              "type": {
+                "text": "boolean"
+              }
+            }
+          ],
+          "description": "A size of time as a rounded count of one of `units`, and how long that\ncount holds while the size grows (`growing`, a moment gone) or shrinks (a\nmoment to come).\n\n**Rounded, as Shoelace's relative time rounds.** Truncated, a date 48 hours\nahead, measured a few milliseconds later, read \"tomorrow\", and 59 minutes\nread \"59 minutes\" while 61 read \"1 hour\". A count that rounds up to the next\nunit's size reads in that unit: 59.6 minutes is 1 hour, 6.6 days is 1 week.\n\n`units` run smallest first and the size is at least the first of them.\nExported for `elapsedTime`, which reads its minute, hour and day the same way."
+        },
         {
           "kind": "function",
           "name": "relativeTime",
@@ -30134,6 +30248,14 @@
             "module": "src/utils/relative-time/relative-time.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "roundedCount",
+          "declaration": {
+            "name": "roundedCount",
+            "module": "src/utils/relative-time/relative-time.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "relativeTime",
@@ -33589,7 +33711,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.169.0'",
+          "default": "'0.171.0'",
           "description": "The version of the package this file ships in.\n\n**Written by `fusion/scripts/version.mjs`** wherever it writes the package's\n`package.json`, and stamped back into the repository beside it after a\nrelease, so the two never disagree; a spec beside this holds them to it.\nNothing else in the running code knows which release it is."
         }
       ],
@@ -34149,6 +34271,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.169.0"
+    "version": "0.171.0"
   }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { auditName } from '@fusion.dev/helix-core/audits/name';
+export { auditServed } from '@fusion.dev/helix-core/audits/served';
 export { AriaForwardController, type AriaForwardOptions, } from './controllers/aria-forward-controller/aria-forward-controller.js';
 export { ArrivalController, type ArrivalOptions, } from './controllers/arrival-controller/arrival-controller.js';
 export { ChartPointerController, type ChartPointerHost, type ReadingHeard, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { auditName } from '@fusion.dev/helix-core/audits/name';
+export { auditServed } from '@fusion.dev/helix-core/audits/served';
 export { AriaForwardController, } from './controllers/aria-forward-controller/aria-forward-controller.js';
 export { ArrivalController, } from './controllers/arrival-controller/arrival-controller.js';
 export { ChartPointerController, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';

package/dist/mixins/mixin-field/mixin-field.js

@@ -142,6 +142,10 @@ export const MixinField = (Base) => {
             this.refreshFeedback();
         }
         copyValidity(control) {
+            if (!control.willValidate) {
+                this.internals.setValidity({});
+                return;
+            }
             const message = control.validity.valueMissing && this.valueMissingMessage
                 ? this.valueMissingMessage
                 : control.validationMessage;

package/dist/utils/audit-served/audit-served-off.d.ts

@@ -0,0 +1,10 @@
+import type { auditServed as audit } from './audit-served.js';
+/**
+ * The served-rows check in a production build: nothing.
+ *
+ * `#audit-served` resolves here unless the bundler or runtime asks for the
+ * `development` condition, so a production build carries none of the check's
+ * code. The signature is the check's, so a call site reads the same in both
+ * builds. See `audit-served.ts`.
+ */
+export declare const auditServed: typeof audit;

package/dist/utils/audit-served/audit-served-off.js

@@ -0,0 +1 @@
+export const auditServed = () => { };

package/dist/utils/audit-served/audit-served.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reports a table whose first drawn page differs from the rows the page
+ * served, which a reader sees as the rows changing under them once the
+ * script runs.
+ *
+ * **The served rows are the page's own markup and the drawn ones are the
+ * table's**, so nothing else can catch it: the two are made by different
+ * code, often on different machines, and either can sort, page or format
+ * differently. Compared by the words in each cell, which is what a reader
+ * sees change, and only as far as the first difference.
+ *
+ * **In a development build only**, as `missing-name` is: every table would pay
+ * for a sentence meant for the person writing the page. Core imports it as
+ * `#audit-served`, which `package.json` resolves here under the `development`
+ * condition and to `audit-served-off.ts`, which does nothing, everywhere else.
+ *
+ * `served` are the rows the page wrote, `drawn` the rows the table drew in
+ * their place, and `page` how many rows the first page holds.
+ */
+export declare const auditServed: (host: HTMLElement, served: readonly Element[], drawn: readonly Element[], page: number) => void;

package/dist/utils/audit-served/audit-served.js

@@ -0,0 +1,32 @@
+import { reportRuntime } from '../report-runtime/report-runtime.js';
+const audited = new WeakSet();
+const said = (row) => [...row.children]
+    .filter((cell) => /-table-cell$/.test(cell.localName) || cell.matches('[part~="cell"]'))
+    .map((cell) => (cell.textContent ?? '').replace(/\s+/g, ' ').trim())
+    .join(' | ');
+export const auditServed = (host, served, drawn, page) => {
+    if (served.length === 0 || audited.has(host)) {
+        return;
+    }
+    const table = `<${host.localName}${host.getAttribute('label') ? ` label="${host.getAttribute('label')}"` : ''}>`;
+    let differs = '';
+    if (served.length > page) {
+        differs = `serves ${served.length} rows and its first page holds ${page}`;
+    }
+    else {
+        const at = served.findIndex((row, index) => drawn[index] && said(row) !== said(drawn[index]));
+        if (at !== -1) {
+            differs = `serves row ${at + 1} as "${said(served[at])}" and draws it as "${said(drawn[at])}"`;
+        }
+    }
+    if (differs === '') {
+        return;
+    }
+    audited.add(host);
+    reportRuntime({
+        kind: 'served-rows-differ',
+        message: `${table} ${differs}, so the rows change once the table draws its own. ` +
+            'Serve the first page in the order, the page size and the formatting the table draws it with.',
+        tag: host.localName,
+    });
+};

package/dist/utils/elapsed-time/elapsed-time.js

@@ -1,4 +1,4 @@
-import { UNITS as TIME_UNITS } from '../relative-time/relative-time.js';
+import { roundedCount, UNITS as TIME_UNITS } from '../relative-time/relative-time.js';
 const held = new Map();
 const dated = new Map();
 const UNITS = TIME_UNITS.slice(1, 4);
@@ -44,15 +44,9 @@ export const elapsedTime = (locale) => {
             const format = sameYear ? dates[0] : dates[1];
             return { next: Number.POSITIVE_INFINITY, text: format.format(from) };
         }
-        let index = 0;
-        for (let at = 0; at < UNITS.length; at += 1) {
-            if (size >= UNITS[at].ms) {
-                index = at;
-            }
-        }
-        const chosen = UNITS[index];
-        const count = Math.trunc(size / chosen.ms);
-        const remaining = Math.min(chosen.ms - (size % chosen.ms), HORIZON - size);
+        const growing = elapsed > 0;
+        const { count, index, next } = roundedCount(size, UNITS, growing);
+        const remaining = growing ? Math.min(next, HORIZON - size) : next;
         return {
             next: Math.max(1000, Math.min(remaining, 3_600_000)),
             text: short[index].format(count),

package/dist/utils/relative-time/relative-time.d.ts

@@ -2,10 +2,32 @@
  * How long each unit lasts, in milliseconds, largest last. `elapsedTime`
  * reads its minute, hour and day from here.
  */
-export declare const UNITS: Array<{
+export declare const UNITS: Unit[];
+/** One unit of `UNITS`. */
+type Unit = {
     ms: number;
     unit: Intl.RelativeTimeFormatUnit;
-}>;
+};
+/**
+ * A size of time as a rounded count of one of `units`, and how long that
+ * count holds while the size grows (`growing`, a moment gone) or shrinks (a
+ * moment to come).
+ *
+ * **Rounded, as Shoelace's relative time rounds.** Truncated, a date 48 hours
+ * ahead, measured a few milliseconds later, read "tomorrow", and 59 minutes
+ * read "59 minutes" while 61 read "1 hour". A count that rounds up to the next
+ * unit's size reads in that unit: 59.6 minutes is 1 hour, 6.6 days is 1 week.
+ *
+ * `units` run smallest first and the size is at least the first of them.
+ * Exported for `elapsedTime`, which reads its minute, hour and day the same way.
+ */
+export declare const roundedCount: <U extends {
+    ms: number;
+}>(size: number, units: readonly U[], growing: boolean) => {
+    count: number;
+    index: number;
+    next: number;
+};
 /** What one timestamp reads as, and when that stops being true. */
 export interface Relative {
     /**
@@ -42,3 +64,4 @@ export interface RelativeOptions {
  * says aloud and what every caller wanted before Format Date offered the rest.
  */
 export declare const relativeTime: (locale: string, options?: RelativeOptions) => ((from: Date, now: Date) => Relative);
+export {};

package/dist/utils/relative-time/relative-time.js

@@ -8,6 +8,32 @@ export const UNITS = [
     { ms: 2_629_800_000, unit: 'month' },
     { ms: 31_557_600_000, unit: 'year' },
 ];
+export const roundedCount = (size, units, growing) => {
+    let index = 0;
+    for (let at = 1; at < units.length; at += 1) {
+        if (size >= units[at].ms) {
+            index = at;
+        }
+    }
+    const ms = (at) => units[at].ms;
+    let count = Math.round(size / ms(index));
+    while (index + 1 < units.length && count * ms(index) >= ms(index + 1)) {
+        index += 1;
+        count = Math.round(size / ms(index));
+    }
+    if (growing) {
+        return { count, index, next: (count + 0.5) * ms(index) - size };
+    }
+    const below = [(count - 0.5) * ms(index)];
+    if (size >= ms(index)) {
+        below.push(ms(index));
+    }
+    if (index > 0) {
+        below.push((Math.ceil(ms(index) / ms(index - 1)) - 0.5) * ms(index - 1));
+    }
+    const floor = Math.max(...below.filter((at) => at <= size));
+    return { count, index, next: size - floor + 1 };
+};
 export const relativeTime = (locale, options = {}) => {
     const numeric = options.numeric ?? 'auto';
     const style = options.style ?? 'long';
@@ -30,17 +56,11 @@ export const relativeTime = (locale, options = {}) => {
                 text: found.format(elapsed > 0 ? 0 : -0, 'second'),
             };
         }
-        let chosen = UNITS[1];
-        for (const unit of UNITS) {
-            if (size >= unit.ms) {
-                chosen = unit;
-            }
-        }
-        const count = Math.trunc(elapsed / chosen.ms);
-        const remaining = chosen.ms - (size % chosen.ms);
+        const { count, index, next } = roundedCount(size, UNITS.slice(1), elapsed < 0);
+        const chosen = UNITS[index + 1];
         return {
-            next: Math.max(1000, Math.min(remaining, 3_600_000)),
-            text: found.format(count, chosen.unit),
+            next: Math.max(1000, Math.min(next, 3_600_000)),
+            text: found.format(elapsed < 0 ? -count : count, chosen.unit),
         };
     };
 };

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -34,6 +34,8 @@ export type RuntimeKind =
  | 'misread-direction'
 /** A React handler prop names an event the element never dispatches itself. Development builds only. */
  | 'misplaced-handler'
+/** A Chat was given turns both as children and as `turns`, which it draws as two runs. */
+ | 'mixed-turns'
 /** An Image has no `alt`, so a screen reader announces its file name. */
  | 'missing-alt'
 /** The three.js driver could not load its layout, so the notes stay where they started. */
@@ -63,6 +65,11 @@ export type RuntimeKind =
  | 'refused-length'
 /** A React handler prop is a removed callback, which never ran from JSX. Development builds only. */
  | 'removed-callback'
+/**
+ * A Data Table's first drawn page differs from the rows the page served, so the rows change
+ * once it draws. Development builds only.
+ */
+ | 'served-rows-differ'
 /**
  * A React handler prop uses Solid's `on:`, which React reads as another event's name.
  * Development builds only.

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.169.0";
+export declare const VERSION = "0.171.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.169.0';
+export const VERSION = '0.171.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.169.0",
+  "version": "0.171.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -29,6 +29,12 @@
       "helix-development": "./dist/helix-element/react-audit.js",
       "default": "./dist/helix-element/react-audit-off.js"
     },
+    "./audits/served": {
+      "types": "./dist/utils/audit-served/audit-served.d.ts",
+      "development": "./dist/utils/audit-served/audit-served.js",
+      "helix-development": "./dist/utils/audit-served/audit-served.js",
+      "default": "./dist/utils/audit-served/audit-served-off.js"
+    },
     "./audits/source": {
       "types": "./dist/utils/audit-source/audit-source.d.ts",
       "development": "./dist/utils/audit-source/audit-source.js",
@@ -56,11 +62,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.169.0"
+    "@fusion.dev/helix-icons": "0.171.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.169.0",
-    "@fusion.dev/helix-testing": "0.169.0",
+    "@fusion.dev/helix-cem": "0.171.0",
+    "@fusion.dev/helix-testing": "0.171.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
@@ -71,6 +77,11 @@
       "helix-development": "./src/utils/audit-name/audit-name.ts",
       "default": "./src/utils/audit-name/audit-name-off.ts"
     },
+    "#audit-served": {
+      "development": "./src/utils/audit-served/audit-served.ts",
+      "helix-development": "./src/utils/audit-served/audit-served.ts",
+      "default": "./src/utils/audit-served/audit-served-off.ts"
+    },
     "#audit-source": {
       "development": "./src/utils/audit-source/audit-source.ts",
       "helix-development": "./src/utils/audit-source/audit-source.ts",