@fusion.dev/helix-headless 0.31.0 → 0.33.0

package/types/vue.d.ts

@@ -2401,7 +2401,8 @@ submits a string, and two fields for one question is a different control. */
 
 Worth more than one mainly for a range, where picking a start in March and
 an end in April otherwise means paging between them and losing sight of the
-first. The panel is sized by its content, so this widens it. */
+first. The panel is sized by its content, so this widens it, and where the
+window has no room for that width it shows one month until there is. */
   months?: (HelixHeadlessDateInput["months"]) | undefined;
   /** What the field says before a date is in it. */
   placeholder?: (HelixHeadlessDateInput["placeholder"]) | undefined;
@@ -3600,8 +3601,9 @@ container that cannot get narrow. */
 
 `1` is a status strip and `7` is a calendar week, which are the two readings
 this covers. Cells fill down the column and then across, which is what a
-calendar heatmap does: a week is a column, so the strip reads left to right
-in weeks and top to bottom in days. */
+calendar heatmap does: a week is a column, so the strip reads along the
+line in weeks, from the right on a right-to-left page, and top to bottom in
+days. */
   rows?: (HelixHeadlessHeatmap["rows"]) | undefined;
   /** Lower bounds for the tone buckets, in the order the tones are given.
 
@@ -3808,6 +3810,12 @@ export type HelixHeadlessIconButtonVueEvents = {};
 export type HelixHeadlessIconVueProps = {
   /** Accessible name, for an icon that is not decorative. */
   label?: (HelixHeadlessIcon["label"]) | undefined;
+  /** Turns the glyph round on a right-to-left page, for an arrow meaning forward or back.
+
+Asked for rather than inferred from the name. The names are physical, and
+`arrow-left` drawn pointing right on an Arabic page would be the icon
+disagreeing with its own name for every reader who meant the left. */
+  mirror?: (HelixHeadlessIcon["mirror"]) | undefined;
   /** Name of the icon in the Helix set. */
   name?: (HelixHeadlessIcon["name"]) | undefined;
 };
@@ -4176,7 +4184,7 @@ Absent is a dot, and absent rather than defaulted because a reflecting
 property with a default writes its attribute onto a host the consumer
 rendered, which React reports as a hydration mismatch.
 
-**One per series, in a column at the right edge**, because every series here
+**One per series, in a column at the far edge**, because every series here
 shares an x-axis and therefore ends at the same reading. That column is the
 useful thing: it is where a reader looks for "and what is it now", which is
 the question a sparkline's single mark answers too.
@@ -6834,7 +6842,21 @@ export type HelixHeadlessTableColumnVueProps = {
 
 `end` is what a column of numbers wants, so digits of the same magnitude sit
 above each other. Left unset the cell inherits the table's own alignment,
-which is `start` for text in either writing direction. */
+which is `start` for text in either writing direction. `helix-data-table`
+aligns the cells it draws. A `helix-table`'s cells are markup the consumer
+wrote, so the table writes nothing onto them: it publishes the edge to each
+cell under this column as `--table-cell-align`, which `@fusion.dev/helix`
+reads. The heading is this element's own, and `@fusion.dev/helix` sets it to
+the same edge in either table. `end` is the inline end, so in a
+right-to-left table it is the left.
+
+**Reflected, because the heading is drawn by a stylesheet and has no other
+way to learn it.** Set as a property, which is how React sets it, an
+unreflected `align` left no attribute to select on, so the heading stayed at
+the start over a column of digits set to the end. It is the author's
+declaration and nothing moves it afterwards, so an attribute cannot come to
+disagree with the element, which is the reason `open` records a custom
+state instead. No default, so an unset column writes nothing onto its host. */
   align?: (HelixHeadlessTableColumn["align"]) | undefined;
   /** The key this column reads out of a row.
 
@@ -6861,13 +6883,23 @@ stores the widths can take the decision. */
 
 Ignored without a `field`, and silently: a column with nothing to sort by
 has no order to offer, and refusing loudly would mean an actions column
-carrying `sortable` breaks a table rather than doing nothing. */
+carrying `sortable` breaks a table rather than doing nothing.
+
+**Reflected, because a stylesheet selects on it.** `@fusion.dev/helix`
+gives a data table's sortable headings a pointer through
+`::slotted(helix-table-column[sortable])`, and set as a property, which is
+how React sets it, an unreflected `sortable` left no attribute to match.
+`false` reflects as no attribute at all, so an unset column writes nothing
+onto its host. */
   sortable?: (HelixHeadlessTableColumn["sortable"]) | undefined;
   /** The track this column takes, as CSS.
 
 A single track value, so anything valid in `grid-template-columns` works:
-`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column shares what is
-left over equally, as `minmax(max-content, 1fr)`.
+`16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column takes the track
+in its place in a `helix-table`'s `columns`, where that table sets one, and
+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.
 
 **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
@@ -6908,15 +6940,24 @@ export type HelixHeadlessTableColumnVueEvents = {
 };
 
 export type HelixHeadlessTableVueProps = {
-  /** Column track list, as CSS. Deprecated: declare columns instead.
-
-Kept for a table that has no `helix-table-column` children, and ignored the
-moment it has one. A raw track list is the right shape for the value and
-the wrong place for it: the headings and the widths were two halves of one
-fact held in two places, and nothing checked that they agreed. Worse, the
-value is CSS, so handing it headings by mistake produced an invalid track
-list, which a grid ignores in silence: the table collapsed to one column
-and said nothing. Columns carry both halves now. */
+  /** The column widths as one track list, written once on the table.
+
+With `helix-table-column` children, each track sizes the column in its
+place, a hidden column counted, so hiding one takes its track with it and
+the rest keep theirs. The columns decide how many tracks there are and this
+list only how wide: a track past the last column is dropped, and a column
+past the last track shares what is left. With no columns declared it is
+the whole track list. Tracks count as the grid counts them, so
+`minmax(0, 1fr)` is one and `repeat(2, 8rem)` is two, and one the grid
+would refuse leaves its column at the default rather than taking the table
+down to one column.
+
+**A column's own `width` wins over its track here.** The width is written
+on the column it sizes, which is the more particular statement, and it is
+where a resize lands: a reader dragging a column's edge writes `width`, so
+were this list to win, the drag would move the separator and leave the
+track where the list put it. This is the table's default for its columns,
+and each column may say otherwise. */
   columns?: (HelixHeadlessTable["columns"]) | undefined;
   /** Accessible name for the table. */
   label?: (HelixHeadlessTable["label"]) | undefined;
@@ -8772,6 +8813,8 @@ export type CustomCssProperties = {
   "--splitter-corner-at"?: (string) | undefined;
   /** Where the divider sits, as a percentage of the box. */
   "--splitter-position"?: (string) | undefined;
+  /** The edge the column this cell sits under is set to, `start`, `center` or `end`, and unset under a column that sets none. Written by the table around it, since the cell is the consumer's markup and nothing is written onto it; read by the sheet that draws the cell, where `justify-content` and `text-align` both take it as it comes and both follow the writing direction. */
+  "--table-cell-align"?: (string) | undefined;
   /** Track list for the columns. */
   "--table-columns"?: (string) | undefined;
   /** The column track list this element worked out from the columns declared in it. Written by the component, read by the sheet that paints: a stylesheet takes it to lay the grid out, and setting it does nothing, because the component writes it inline on the very element that reads it and an inline declaration beats any sheet. `--table-columns` is the one to set. */
@@ -8906,7 +8949,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessChatMessageVueProps,
     HelixHeadlessChatMessageVueEvents
   >;
-  /** **It has no opinion about where it sits.** A chat is asked for as a floating button, a page, a palette, a sidebar, a modal and an inline block, and none of those is a variant of a conversation: they are containers, and the containers already exist. Nothing here is positioned, nothing has a backdrop, and nothing owns a trigger. If a form factor needs a mode on this element, the split is wrong.  **Scroll ownership is the behavior everything else depends on.** A transcript that grows wants to stay at the bottom, except when the reader has scrolled up to read, where pinning is hostile. The rule: pin while the reader is within 'threshold' of the bottom, and let go the moment they leave it. A turn growing under a pinned reader is not the reader leaving, so a streamed answer is followed to its last line.  **History loads upward, under a reader who does not move.** With 'history' set to 'more', reaching the top fires 'helix-history'; the consumer sets 'loading' while it fetches and prepends the older turns, and the turn the reader was looking at stays where it was on screen while the room above it grows.  **A turn is announced once, when it settles**, and not by the log. A log that is a live region reads what enters it, which is every token of a stream where 'aria-busy' is not honored, every page of history as it loads, and every window of a long transcript as the reader scrolls through it. So the log is 'aria-live="off"', and a status region of its own says each new turn when it has finished arriving: never the reader's own words unless they failed to send, never a turn loaded above the ones already there, and never what was in the transcript when it opened.  **Turns are markup children or data, not both.** Children serve whole from a server and are what most conversations want. 'turns' is for the transcript too long to hold as elements: it is drawn a window at a time, measured as it goes, and the log needs a block size of its own for that to mean anything. */
+  /** **It has no opinion about where it sits.** A chat is asked for as a floating button, a page, a palette, a sidebar, a modal and an inline block, and none of those is a variant of a conversation: they are containers, and the containers already exist. Nothing here is positioned, nothing has a backdrop, and nothing owns a trigger. If a form factor needs a mode on this element, the split is wrong.  **Scroll ownership is the behavior everything else depends on.** A transcript that grows wants to stay at the bottom, except when the reader has scrolled up to read, where pinning is hostile. The rule: pin while the reader is within 'threshold' of the bottom, and let go the moment they leave it. A turn growing under a pinned reader is not the reader leaving, so a streamed answer is followed to its last line.  **History loads upward, under a reader who does not move.** With 'history' set to 'more', reaching the top fires 'helix-history'; the consumer sets 'loading' while it fetches and prepends the older turns, and the turn the reader was looking at stays where it was on screen while the room above it grows.  **A turn is announced once, when it settles**, and not by the log. A log that is a live region reads what enters it, which is every token of a stream where 'aria-busy' is not honored, every page of history as it loads, and every window of a long transcript as the reader scrolls through it. So the log is 'aria-live="off"', and a status region of its own says each new turn when it has finished arriving: never the reader's own words unless they failed to send, never a turn loaded above the ones already there, and never what was in the transcript when it opened.  **Turns are markup children or data, not both.** Children serve whole from a server and are what most conversations want. 'turns' is for the transcript too long to hold as elements: it is drawn a window at a time, measured as it goes, and the log needs a block size of its own for that to mean anything.  **A fed turn is styled through this element, not its own.** Its message is drawn in this shadow root, where '[author="me"]' cannot reach it, so every fed turn's parts are forwarded as 'message-*', and the ones that change with the turn a second time while it holds: '-mine' for a turn by 'me', and 'message-meta-failed', 'message-content-sending' and 'message-content-streaming' for its state. Every other author has the plain names only, so a conversation styling each participant apart passes its turns as children. */
   "helix-headless-chat": DefineCustomElement<
     HelixHeadlessChat,
     HelixHeadlessChatVueProps,
@@ -9020,7 +9063,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessDrawerVueProps,
     HelixHeadlessDrawerVueEvents
   >;
-  /** A row that opens a page *contains* that page: its rows are this row's own children, assigned to the 'page' slot. The tree is the structure, so there are no ids to wire and a consumer who moves a row has moved its page with it.  **It renders one of three things**, and which one is the stack's business rather than its own. On the page showing, it is a row. Showing its own page, it contributes that page's rows and nothing else, because its row belongs to the page above. On neither, it renders nothing at all: the rows are in the light DOM and come back untouched, so there is no state to keep and nothing to hide with an attribute this element would have to write onto itself.  Choosing is announced, never applied. The row dispatches and the stack decides whether that means drilling in or choosing a command. */
+  /** A row that opens a page *contains* that page: its rows are this row's own children, assigned to the 'page' slot. The tree is the structure, so there are no ids to wire and a consumer who moves a row has moved its page with it.  **It renders one of three things**, and which one is the stack's business rather than its own. On the page showing, it is a row. Showing its own page, it contributes that page's rows and nothing else, because its row belongs to the page above. On neither, it renders nothing at all: the rows are in the light DOM and come back untouched, so there is no state to keep and nothing to hide with an attribute this element would have to write onto itself.  Choosing is announced, never applied. The row dispatches and the stack decides whether that means drilling in or choosing a command.  **A row that opens a page says so**, with a caret after its words and 'aria-haspopup', the way 'Menu' marks a row with a submenu: a row that goes somewhere and a row that does something otherwise look the same until one is pressed. Not on the server, which cannot see the children and so cannot know. */
   "helix-headless-drilldown-item": DefineCustomElement<
     HelixHeadlessDrilldownItem,
     HelixHeadlessDrilldownItemVueProps,
@@ -9248,7 +9291,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessPaginationSummaryVueProps,
     HelixHeadlessPaginationSummaryVueEvents
   >;
-  /** **One '<input>' per cell, rather than one input drawn as cells.** A single field autofills perfectly and needs a drawn caret nobody can style well; separate fields give every box a real focus ring, a real caret and a real tab stop for free. Autofill's gap is closed below rather than lived with.  **Anything longer than one character is treated as a paste, wherever it lands.** That covers the obvious case and two that are not: a browser autofilling an SMS code drops the whole thing into whichever box is focused, and a password manager does the same. So a six-character arrival in cell three fills from cell three rather than being truncated to its first character, which is what a per-cell 'maxlength' would have done silently.  **The code is one value to a form.** The cells are inside a shadow root and submit nothing on their own; the host is form-associated and reports the joined string, which is also what carries validity and answers a reset.  'autocomplete="one-time-code"' is on the first cell only. It is a hint about the field as a whole, and repeating it on six boxes offers a browser six places to put one code. */
+  /** **One '<input>' per cell, rather than one input drawn as cells.** A single field autofills perfectly and needs a drawn caret nobody can style well; separate fields give every box a real focus ring, a real caret and a real tab stop for free. Autofill's gap is closed below rather than lived with.  **Anything longer than one character is treated as a paste, wherever it lands.** That covers the obvious case and two that are not: a browser autofilling an SMS code drops the whole thing into whichever box is focused, and a password manager does the same. So a six-character arrival in cell three fills from cell three rather than being truncated to its first character, which is what a per-cell 'maxlength' would have done silently.  **The code is one value to a form.** The cells are inside a shadow root and submit nothing on their own; the host is form-associated and reports the joined string, which is also what carries validity and answers a reset.  'autocomplete="one-time-code"' is on the first cell only. It is a hint about the field as a whole, and repeating it on six boxes offers a browser six places to put one code.  **Left to right on every page.** A code is read the way a phone number is, one character after another from the left, in Arabic and Hebrew as in English, so the row carries 'dir="ltr"': the first box is the leftmost, a paste fills rightward and the right arrow moves on. The label, the hint and the feedback are words and keep the page's direction. */
   "helix-headless-pin-input": DefineCustomElement<
     HelixHeadlessPinInput,
     HelixHeadlessPinInputVueProps,
@@ -9296,7 +9339,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessRatingVueProps,
     HelixHeadlessRatingVueEvents
   >;
-  /** The chart for a relation rather than a series. The table's first numeric column is measured across and every other numeric column is measured up, one point per row, so a table of countries with a column of income and a column of life expectancy draws one dot for each country. More numeric columns are more series against the same across, each in its own color.  **Both axes are measured, so both are labeled.** A line chart's readings are named along the bottom and its values are read from the tooltip; here the horizontal position is itself a value, and a point with no scale under it says nothing about how far along it is. The ticks sit at round numbers and the range is widened to them, so the plot's edges are numbers a reader can name.  **What a reader without the picture is told is how strongly the two relate**, because that is the question a scatter is drawn to answer and the one a table of the same numbers makes hardest to see. The summary gives each series' correlation coefficient and how many points it rests on; the table has every number, and the drawing is 'aria-hidden'.  **The points are elements, not shapes in the drawing.** The drawing stretches to its box, and a circle in a stretched space is an ellipse, so each point is a '<span>' placed by percentage over it, which is how 'LineChart' draws its termini and for the same reason. */
+  /** The chart for a relation rather than a series. The table's first numeric column is measured across and every other numeric column is measured up, one point per row, so a table of countries with a column of income and a column of life expectancy draws one dot for each country. More numeric columns are more series against the same across, each in its own color.  **Both axes are measured, so both are labeled.** A line chart's readings are named along the bottom and its values are read from the tooltip; here the horizontal position is itself a value, and a point with no scale under it says nothing about how far along it is. The ticks sit at round numbers and the range is widened to them, so the plot's edges are numbers a reader can name.  **What a reader without the picture is told is how strongly the two relate**, because that is the question a scatter is drawn to answer and the one a table of the same numbers makes hardest to see. The summary gives each series' correlation coefficient and how many points it rests on; the table has every number, and the drawing is 'aria-hidden'.  **The points are elements, not shapes in the drawing.** The drawing stretches to its box, and a circle in a stretched space is an ellipse, so each point is a '<span>' placed by percentage over it, which is how 'LineChart' draws its termini and for the same reason.  **Left to right on every page, the one chart here that is.** A bar or a line chart's across is the order its readings are named in, which follows the line of text and turns with it. Here it is a measure, and a measure has a direction of its own: more is to the right in every script, as a number line is. So the plot, its axes and the names at their ends sit in a 'plane' part that carries 'dir="ltr"', which holds the y axis on the left and the points, rules, ticks, pointer and tooltip mark where a left-to-right page puts them, with no stylesheet asked to know. The names carry 'dir="auto"', so one written in Arabic or Hebrew still reads its own way; the summary is outside the plane and the bubble is told the page's direction, both being words. */
   "helix-headless-scatter-chart": DefineCustomElement<
     HelixHeadlessScatterChart,
     HelixHeadlessScatterChartVueProps,
@@ -9392,7 +9435,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessTableCellVueProps,
     HelixHeadlessTableCellVueEvents
   >;
-  /** **The column is the source of both its heading and its track.** Add one and the table has another track; remove one and it does not. Declaring the widths separately, as a CSS track list on the table, leaves nothing tying the two together: a table with three headings and a two-track list renders without complaint, and a track list that is accidentally the headings is invalid CSS the grid silently ignores, collapsing the whole table into one column.  **It is also where every per-column fact goes**, which is the reason 'helix-data-table' needs no column config object. 'field' names the key the cell reads, 'sortable' says a reader may reorder by it, 'align' says which edge the values line up against, and 'cell' takes a function for anything the field alone cannot express. The schema is markup and the data is a property: a schema is small, declarative, and something a reader should be able to see in the HTML, and data is large and windowed.  **The same element serves both tables**, the markup one and the data one. It is identified by a flag rather than by 'instanceof', so a 'helix-table-column' works inside either without the two roots sharing anything else.  **It generates no box of its own**, the same as a row: the heading is a grid item of the table, so it lines up with the cells under it rather than sitting in a wrapper that has to be kept the same width.  **A heading that does something holds a control that does it.** The host is the column header, and a header is not focusable, so a sortable heading is a '<button>' inside it: the pattern for a sortable table, and the only way a reader on a keyboard reaches the sort at all. A column a reader may resize carries a 'separator' on its end edge, moved by dragging it or with the arrow keys, and a column in a table that lets a reader reorder its columns carries a grip the table moves. */
+  /** **The column is the source of both its heading and its track.** Add one and the table has another track; remove one and it does not. Declaring the widths separately, as a CSS track list on the table, leaves nothing tying the two together: a table with three headings and a two-track list renders without complaint, and a track list that is accidentally the headings is invalid CSS the grid silently ignores, collapsing the whole table into one column.  **It is also where every per-column fact goes**, which is the reason 'helix-data-table' needs no column config object. 'field' names the key the cell reads, 'sortable' says a reader may reorder by it, 'align' says which edge the values line up against, and 'cell' takes a function for anything the field alone cannot express. The schema is markup and the data is a property: a schema is small, declarative, and something a reader should be able to see in the HTML, and data is large and windowed.  **The same element serves both tables**, the markup one and the data one. It is identified by a flag rather than by 'instanceof', so a 'helix-table-column' works inside either without the two roots sharing anything else.  **It generates no box of its own**, the same as a row: the heading is a grid item of the table, so it lines up with the cells under it rather than sitting in a wrapper that has to be kept the same width.  **'hidden' takes the column out of the grid**, its heading and its track both, so the columns after it keep their own widths and every row keeps its cells under their headings. 'hidden="until-found"' keeps its track, the heading being left drawn, as every Helix element leaves one with that value. 'helix-data-table' draws the cells, so it leaves out the ones under a hidden column. A 'helix-table''s cells are markup the consumer wrote, so hide them with the column, as removing a column means removing its cells: a row with a cell more than the table has tracks wraps into the next.  **A heading that does something holds a control that does it.** The host is the column header, and a header is not focusable, so a sortable heading is a '<button>' inside it: the pattern for a sortable table, and the only way a reader on a keyboard reaches the sort at all. A column a reader may resize carries a 'separator' on its end edge, moved by dragging it or with the arrow keys, and a column in a table that lets a reader reorder its columns carries a grip the table moves. */
   "helix-headless-table-column": DefineCustomElement<
     HelixHeadlessTableColumn,
     HelixHeadlessTableColumnVueProps,