@fusion.dev/helix 0.108.1 → 0.109.0

package/custom-elements.json

@@ -131288,7 +131288,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "The track this column takes, as CSS.\n\nA single track value, so anything valid in `grid-template-columns` works:\n`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column takes the track in\nits place in a `Table`'s `columns`, where that table sets one, and\notherwise shares what is left over equally, as `minmax(max-content, 1fr)`.\nSet here, it wins over that list, which is what lets a reader resize a\ncolumn in a table that set one.\n\n**The floor is `max-content`, never `0` and never `min-content`.** A zero\nfloor lets a track shrink under its own content: at 375 the columns squeeze\nto 75px and `eu-central-1` wraps across lines, which reads as corrupt data\nrather than as a table that ran out of room. A `min-content` floor still\nbreaks it, a hyphen being a wrap opportunity.\n\nThe overflow has somewhere to go: `@fusion.dev/helix` scrolls the table's\nown box, so a long value pushes past the container and the table scrolls\ninstead of the value being destroyed. Measured at 375: tracks of 192, 89 and\n102 against a 343 box, so the table scrolls 384 and the page does not move.\n\nThe cost is that a column of prose asks for its longest paragraph on one\nline, so a column holding sentences rather than values wants\n`width=\"minmax(0, 1fr)\"` to opt back into wrapping. A headless consumer owns\nthe overflow either way, that being paint, and gets the honest track list.",
+              "description": "The track this column takes, as CSS.\n\nA single track value, so anything valid in `grid-template-columns` works:\n`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column takes the track in\nits place in a `Table`'s `columns`, where that table sets one, and\notherwise shares what is left over equally, as `minmax(max-content, 1fr)`.\nSet here, it wins over that list, which is what lets a reader resize a\ncolumn in a table that set one.\n\n**A `Table` fits the columns that set neither to what they hold.** Once\nany of them holds a sentence, the columns of short values keep\n`max-content` and the columns of sentences wrap, above a floor of `14ch`,\neach taking a share of the room in proportion to its text. A table of\nvalues alone keeps the default.\n\n**The floor is `max-content`, never `0` and never `min-content`.** A zero\nfloor lets a track shrink under its own content: at 375 the columns squeeze\nto 75px and `eu-central-1` wraps across lines, which reads as corrupt data\nrather than as a table that ran out of room. A `min-content` floor still\nbreaks it, a hyphen being a wrap opportunity.\n\nThe overflow has somewhere to go: `@fusion.dev/helix` scrolls the table's\nown box, so a long value pushes past the container and the table scrolls\ninstead of the value being destroyed. Measured at 375: tracks of 192, 89 and\n102 against a 343 box, so the table scrolls 384 and the page does not move.\n\nA column of sentences does not pay for this: the table sees the sentences\nand lets that column wrap. A headless consumer owns the overflow either\nway, that being paint, and gets the honest track list.",
               "attribute": "width",
               "inheritedFrom": {
                 "name": "HelixHeadlessTableColumn",
@@ -132069,7 +132069,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "The track this column takes, as CSS.\n\nA single track value, so anything valid in `grid-template-columns` works:\n`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column takes the track in\nits place in a `Table`'s `columns`, where that table sets one, and\notherwise shares what is left over equally, as `minmax(max-content, 1fr)`.\nSet here, it wins over that list, which is what lets a reader resize a\ncolumn in a table that set one.\n\n**The floor is `max-content`, never `0` and never `min-content`.** A zero\nfloor lets a track shrink under its own content: at 375 the columns squeeze\nto 75px and `eu-central-1` wraps across lines, which reads as corrupt data\nrather than as a table that ran out of room. A `min-content` floor still\nbreaks it, a hyphen being a wrap opportunity.\n\nThe overflow has somewhere to go: `@fusion.dev/helix` scrolls the table's\nown box, so a long value pushes past the container and the table scrolls\ninstead of the value being destroyed. Measured at 375: tracks of 192, 89 and\n102 against a 343 box, so the table scrolls 384 and the page does not move.\n\nThe cost is that a column of prose asks for its longest paragraph on one\nline, so a column holding sentences rather than values wants\n`width=\"minmax(0, 1fr)\"` to opt back into wrapping. A headless consumer owns\nthe overflow either way, that being paint, and gets the honest track list.",
+              "description": "The track this column takes, as CSS.\n\nA single track value, so anything valid in `grid-template-columns` works:\n`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column takes the track in\nits place in a `Table`'s `columns`, where that table sets one, and\notherwise shares what is left over equally, as `minmax(max-content, 1fr)`.\nSet here, it wins over that list, which is what lets a reader resize a\ncolumn in a table that set one.\n\n**A `Table` fits the columns that set neither to what they hold.** Once\nany of them holds a sentence, the columns of short values keep\n`max-content` and the columns of sentences wrap, above a floor of `14ch`,\neach taking a share of the room in proportion to its text. A table of\nvalues alone keeps the default.\n\n**The floor is `max-content`, never `0` and never `min-content`.** A zero\nfloor lets a track shrink under its own content: at 375 the columns squeeze\nto 75px and `eu-central-1` wraps across lines, which reads as corrupt data\nrather than as a table that ran out of room. A `min-content` floor still\nbreaks it, a hyphen being a wrap opportunity.\n\nThe overflow has somewhere to go: `@fusion.dev/helix` scrolls the table's\nown box, so a long value pushes past the container and the table scrolls\ninstead of the value being destroyed. Measured at 375: tracks of 192, 89 and\n102 against a 343 box, so the table scrolls 384 and the page does not move.\n\nA column of sentences does not pay for this: the table sees the sentences\nand lets that column wrap. A headless consumer owns the overflow either\nway, that being paint, and gets the honest track list.",
               "fieldName": "width",
               "inheritedFrom": {
                 "name": "HelixHeadlessTableColumn",
@@ -132509,6 +132509,35 @@
                 "module": "src/table/root/table-root.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "fitted",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "declared",
+                  "type": {
+                    "text": "HelixHeadlessTableColumn[]"
+                  }
+                },
+                {
+                  "name": "listed",
+                  "type": {
+                    "text": "string[]"
+                  }
+                }
+              ],
+              "description": "Tracks for the columns that set nothing, from how much text each holds.\n\n**A column of sentences wraps and a column of values does not.** Every\ncolumn left at `minmax(max-content, 1fr)` asks for its longest cell on one\nline, which is right for `eu-central-1` and wrong for a description: the\ntable grows as wide as its longest sentence and scrolls, on a phone and on\na desktop alike. So once any column holds more than `SHORT` characters,\nthe short columns keep `max-content`, and each long one wraps above a\n`FLOOR`, taking a share of the room in proportion to its text.\n\nA table with no long column keeps the default, so a table of values lays\nout as it always has. A column's `width` and a track in `columns` are both\nstatements an author made, and each wins over this.\n\nCharacters stand in for width. They only have to rank columns against each\nother, and a count needs no layout, so it reads the same before paint as\nafter. Sampled, so a table of thousands of rows reads `SAMPLE` of them.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessTable",
+                "module": "src/table/root/table-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleSlotChange",
@@ -132527,7 +132556,7 @@
               },
               "privacy": "private",
               "default": "undefined",
-              "description": "Watches the light DOM for rows and columns arriving, leaving and moving.\n\n**A manually assigned slot does not announce them**, the same gap `Chat`\nand `Carousel` watch for. Under `slotAssignment: 'manual'` only `assign`\nchanges an assignment, so a row appended after the first render reached no\nslot and drew nowhere, and a column moved to another place lost its\nassignment on the way out and never got it back: measured in Chromium, both\n`assignedSlot` null a render later. A table whose definition loaded before\nits markup was parsed drew no columns at all, having rendered before any\narrived.",
+              "description": "Watches the light DOM for rows and columns arriving, leaving and moving.\n\n**A manually assigned slot does not announce them**, the same gap `Chat`\nand `Carousel` watch for. Under `slotAssignment: 'manual'` only `assign`\nchanges an assignment, so a row appended after the first render reached no\nslot and drew nowhere, and a column moved to another place lost its\nassignment on the way out and never got it back: measured in Chromium, both\n`assignedSlot` null a render later. A table whose definition loaded before\nits markup was parsed drew no columns at all, having rendered before any\narrived.\n\n**The cells' text too, all the way down.** The columns that set no width\nare sized from what their cells say, so a cell whose text changes can\nchange the track it sits in.",
               "inheritedFrom": {
                 "name": "HelixHeadlessTable",
                 "module": "src/table/root/table-root.ts"

package/dist/rehype.d.ts

@@ -1,11 +1,12 @@
 /**
- * **A rehype plugin that gives Markdown's two missing constructs their Helix
+ * **A rehype plugin that gives Markdown's fences, alerts and tables their Helix
  * elements, and parses nothing.** Your Markdown library turns `###` into
- * `<h3>`, and `data-prose` styles the HTML it writes. Two constructs carry
+ * `<h3>`, and `data-prose` styles the HTML it writes. Three constructs carry
  * what plain HTML cannot: a code fence, which a reader copies and which has a
- * language, and a GitHub alert, which says how much a passage matters. This
- * rewrites those two in the tree your parser already built, after your own
- * sanitizing, and leaves everything else as it is.
+ * language; a GitHub alert, which says how much a passage matters; and a
+ * table, whose values must stay whole on a narrow screen. This rewrites those
+ * three in the tree your parser already built, after your own sanitizing, and
+ * leaves everything else as it is.
  *
  * - A fence becomes `helix-code-block`, labeled with its language. What is
  *   inside the code is kept, so a highlighter that ran before this has its
@@ -14,6 +15,13 @@
  *   note is `info`, a tip `success`, a warning `warning`, and a caution
  *   `danger`. An important passage has no tone, since none of the four says
  *   it. Each keeps its kind as its heading, as GitHub shows it.
+ * - A table becomes `helix-table`: its header row becomes its columns, each
+ *   aligned as the Markdown aligned it, and every other row a
+ *   `helix-table-row` of `helix-table-cell`. The table sizes its columns from
+ *   what they hold, so a column of values stays whole and a column of
+ *   sentences wraps. A table the grid cannot draw as written, with a caption,
+ *   a cell spanning more than one column or row, or a heading cell outside the
+ *   one header row, stays a table.
  *
  * Any pipeline that reaches rehype takes it: `remark` with `remark-rehype`,
  * `react-markdown`, and MDX.
@@ -45,10 +53,13 @@ export interface RehypeHelixOptions {
     fences?: boolean | undefined;
     /** An alert's heading by its kind, for a page in another language. English by default. */
     headings?: Partial<Record<AlertKind, string>> | undefined;
+    /** Whether tables become Helix tables. `true` by default. */
+    tables?: boolean | undefined;
 }
 /**
  * The plugin: rewrites the tree in place, from the top down, so a fence
- * inside an alert becomes a code block inside a callout.
+ * inside an alert becomes a code block inside a callout, and a table inside
+ * one a Helix table.
  */
 export default function rehypeHelix(options?: RehypeHelixOptions): (tree: HastNode) => void;
 export { rehypeHelix };

package/dist/rehype.js

@@ -77,6 +77,48 @@ const calloutOf = (node, headings) => {
         type: 'element',
     };
 };
+const EDGES = {
+    center: 'center',
+    left: 'start',
+    right: 'end',
+};
+const spans = (cell) => Number(cell.properties?.colSpan ?? 1) > 1 || Number(cell.properties?.rowSpan ?? 1) > 1;
+const helix = (tagName, children, properties = {}) => ({
+    children,
+    properties,
+    tagName,
+    type: 'element',
+});
+const tableOf = (node) => {
+    if (node.tagName !== 'table') {
+        return undefined;
+    }
+    const head = [];
+    const body = [];
+    for (const group of elements(node)) {
+        const rows = group.tagName === 'tr' ? [group] : elements(group);
+        if (!['tbody', 'tfoot', 'thead', 'tr'].includes(group.tagName ?? '') ||
+            rows.some((row) => row.tagName !== 'tr')) {
+            return undefined;
+        }
+        ;
+        (group.tagName === 'thead' ? head : body).push(...rows);
+    }
+    const [heading] = head;
+    const headings = heading ? elements(heading) : [];
+    const cells = body.map((row) => elements(row));
+    if (head.length !== 1 ||
+        headings.some((cell) => cell.tagName !== 'th' || spans(cell)) ||
+        cells.some((row) => row.some((cell) => cell.tagName !== 'td' || spans(cell)))) {
+        return undefined;
+    }
+    const columns = headings.map((cell) => {
+        const edge = EDGES[String(cell.properties?.align)];
+        return helix('helix-table-column', cell.children ?? [], edge ? { 'text-align': edge } : {});
+    });
+    const rows = cells.map((row) => helix('helix-table-row', row.map((cell) => helix('helix-table-cell', cell.children ?? []))));
+    return helix('helix-table', [...columns, ...rows]);
+};
 export default function rehypeHelix(options = {}) {
     const headings = { ...HEADINGS, ...options.headings };
     const rewrite = (node) => {
@@ -86,7 +128,8 @@ export default function rehypeHelix(options = {}) {
         }
         children.forEach((child, index) => {
             const replaced = (options.fences !== false ? codeBlockOf(child) : undefined) ??
-                (options.alerts !== false ? calloutOf(child, headings) : undefined);
+                (options.alerts !== false ? calloutOf(child, headings) : undefined) ??
+                (options.tables !== false ? tableOf(child) : undefined);
             if (replaced) {
                 children[index] = replaced;
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.108.1",
+  "version": "0.109.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -51,18 +51,19 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.108.1",
-    "@fusion.dev/helix-headless": "0.108.1",
-    "@fusion.dev/helix-styles": "0.108.1"
+    "@fusion.dev/helix-core": "0.109.0",
+    "@fusion.dev/helix-headless": "0.109.0",
+    "@fusion.dev/helix-styles": "0.109.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.108.1",
-    "@fusion.dev/helix-testing": "0.108.1",
+    "@fusion.dev/helix-cem": "0.109.0",
+    "@fusion.dev/helix-testing": "0.109.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",
     "@types/bun": "^1.3.0",
     "lit": "^3.2.1",
+    "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "unified": "^11.0.5"

package/types/jsx.d.ts

@@ -21195,6 +21195,12 @@ otherwise shares what is left over equally, as `minmax(max-content, 1fr)`.
 Set here, it wins over that list, which is what lets a reader resize a
 column in a table that set one.
 
+**A `Table` fits the columns that set neither to what they hold.** Once
+any of them holds a sentence, the columns of short values keep
+`max-content` and the columns of sentences wrap, above a floor of `14ch`,
+each taking a share of the room in proportion to its text. A table of
+values alone keeps the default.
+
 **The floor is `max-content`, never `0` and never `min-content`.** A zero
 floor lets a track shrink under its own content: at 375 the columns squeeze
 to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
@@ -21206,10 +21212,9 @@ own box, so a long value pushes past the container and the table scrolls
 instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
 102 against a 343 box, so the table scrolls 384 and the page does not move.
 
-The cost is that a column of prose asks for its longest paragraph on one
-line, so a column holding sentences rather than values wants
-`width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-the overflow either way, that being paint, and gets the honest track list. */
+A column of sentences does not pay for this: the table sees the sentences
+and lets that column wrap. A headless consumer owns the overflow either
+way, that being paint, and gets the honest track list. */
   width?: (HelixTableColumn["width"]) | undefined;
   /** The text screen readers announce for the column's width. `{width}` is
 replaced with the width. */
@@ -21359,6 +21364,12 @@ otherwise shares what is left over equally, as `minmax(max-content, 1fr)`.
 Set here, it wins over that list, which is what lets a reader resize a
 column in a table that set one.
 
+**A `Table` fits the columns that set neither to what they hold.** Once
+any of them holds a sentence, the columns of short values keep
+`max-content` and the columns of sentences wrap, above a floor of `14ch`,
+each taking a share of the room in proportion to its text. A table of
+values alone keeps the default.
+
 **The floor is `max-content`, never `0` and never `min-content`.** A zero
 floor lets a track shrink under its own content: at 375 the columns squeeze
 to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
@@ -21370,10 +21381,9 @@ own box, so a long value pushes past the container and the table scrolls
 instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
 102 against a 343 box, so the table scrolls 384 and the page does not move.
 
-The cost is that a column of prose asks for its longest paragraph on one
-line, so a column holding sentences rather than values wants
-`width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-the overflow either way, that being paint, and gets the honest track list. */
+A column of sentences does not pay for this: the table sees the sentences
+and lets that column wrap. A headless consumer owns the overflow either
+way, that being paint, and gets the honest track list. */
   "prop:width"?: (HelixTableColumn["width"]) | undefined;
   /** The text screen readers announce for the column's width. `{width}` is
 replaced with the width. */
@@ -43659,6 +43669,12 @@ export type CustomElements = {
    * Set here, it wins over that list, which is what lets a reader resize a
    * column in a table that set one.
    *
+   * **A `Table` fits the columns that set neither to what they hold.** Once
+   * any of them holds a sentence, the columns of short values keep
+   * `max-content` and the columns of sentences wrap, above a floor of `14ch`,
+   * each taking a share of the room in proportion to its text. A table of
+   * values alone keeps the default.
+   *
    * **The floor is `max-content`, never `0` and never `min-content`.** A zero
    * floor lets a track shrink under its own content: at 375 the columns squeeze
    * to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
@@ -43670,10 +43686,9 @@ export type CustomElements = {
    * instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
    * 102 against a 343 box, so the table scrolls 384 and the page does not move.
    *
-   * The cost is that a column of prose asks for its longest paragraph on one
-   * line, so a column holding sentences rather than values wants
-   * `width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-   * the overflow either way, that being paint, and gets the honest track list.
+   * A column of sentences does not pay for this: the table sees the sentences
+   * and lets that column wrap. A headless consumer owns the overflow either
+   * way, that being paint, and gets the honest track list.
    * - `width-label`/`widthLabel`: The text screen readers announce for the column's width. `{width}` is
    * replaced with the width.
    * - `cell`: A function that reads the cell's content from a row, for cells that `field`
@@ -65698,6 +65713,12 @@ export type CustomElementsSolidJs = {
    * Set here, it wins over that list, which is what lets a reader resize a
    * column in a table that set one.
    *
+   * **A `Table` fits the columns that set neither to what they hold.** Once
+   * any of them holds a sentence, the columns of short values keep
+   * `max-content` and the columns of sentences wrap, above a floor of `14ch`,
+   * each taking a share of the room in proportion to its text. A table of
+   * values alone keeps the default.
+   *
    * **The floor is `max-content`, never `0` and never `min-content`.** A zero
    * floor lets a track shrink under its own content: at 375 the columns squeeze
    * to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
@@ -65709,10 +65730,9 @@ export type CustomElementsSolidJs = {
    * instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
    * 102 against a 343 box, so the table scrolls 384 and the page does not move.
    *
-   * The cost is that a column of prose asks for its longest paragraph on one
-   * line, so a column holding sentences rather than values wants
-   * `width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-   * the overflow either way, that being paint, and gets the honest track list.
+   * A column of sentences does not pay for this: the table sees the sentences
+   * and lets that column wrap. A headless consumer owns the overflow either
+   * way, that being paint, and gets the honest track list.
    * - `width-label`/`widthLabel`: The text screen readers announce for the column's width. `{width}` is
    * replaced with the width.
    * - `cell`: A function that reads the cell's content from a row, for cells that `field`

package/types/vue.d.ts

@@ -10929,6 +10929,12 @@ otherwise shares what is left over equally, as `minmax(max-content, 1fr)`.
 Set here, it wins over that list, which is what lets a reader resize a
 column in a table that set one.
 
+**A `Table` fits the columns that set neither to what they hold.** Once
+any of them holds a sentence, the columns of short values keep
+`max-content` and the columns of sentences wrap, above a floor of `14ch`,
+each taking a share of the room in proportion to its text. A table of
+values alone keeps the default.
+
 **The floor is `max-content`, never `0` and never `min-content`.** A zero
 floor lets a track shrink under its own content: at 375 the columns squeeze
 to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
@@ -10940,10 +10946,9 @@ own box, so a long value pushes past the container and the table scrolls
 instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
 102 against a 343 box, so the table scrolls 384 and the page does not move.
 
-The cost is that a column of prose asks for its longest paragraph on one
-line, so a column holding sentences rather than values wants
-`width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-the overflow either way, that being paint, and gets the honest track list. */
+A column of sentences does not pay for this: the table sees the sentences
+and lets that column wrap. A headless consumer owns the overflow either
+way, that being paint, and gets the honest track list. */
   width?: (HelixTableColumn["width"]) | undefined;
   /** The text screen readers announce for the column's width. `{width}` is
 replaced with the width. */