@fusion.dev/helix-headless 0.182.1 → 0.183.0

package/types/vue.d.ts

@@ -18957,6 +18957,13 @@ are rendered at a time.
 An `aria-label` or `aria-labelledby` on the host names the list too, and
 wins over this. */
   label?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** How items of more than one column are laid out. `grid`, the default, puts
+them in lines of equal columns. `waterfall` puts each item, in the order
+of the set, under the column that ends highest, as a wall of photos of
+different heights is: `columns`, or `min-column-width`, says how many
+columns. Rows of a waterfall are measured, and Up and Down move along a
+column. */
+  layout?: (HelixHeadlessVirtualList["layout"]) | undefined;
   /** Marks the list as busy fetching more items, and draws a row after the last
 item that says so.
 
@@ -18989,14 +18996,15 @@ follows the box as it resizes, which `columns` then does not decide. */
   /** Which way the list runs. `horizontal` lays the items out along a line
 and scrolls it sideways: Left and Right move between items, the other
 way round on a right-to-left page, and `estimate` is an item's width. A
-grid always runs down. */
+grid and a waterfall always run down. */
   orientation?: (HelixHeadlessVirtualList["orientation"]) | undefined;
   /** Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`
 (or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt
 with an arrow moves the row the keys are on, and a pointer drags a row.
 The list moves no item itself: you move your `items` on `helix-reorder`.
 Without that import it does nothing, so a list that never moves items
-carries none of the code. A list of one column, without sections. */
+carries none of the code. A list of one column, without sections or a
+waterfall. */
   reorderable?: (HelixHeadlessVirtualList["reorderable"]) | undefined;
   /** The field of each item that names its section, as a key or a path of
 keys. Set, the items are drawn in sections: a header, then the items, in
@@ -20180,7 +20188,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessVideoVueProps,
     HelixHeadlessVideoVueEvents
   >;
-  /** The items arrive as data, in one of two ways:  - 'items' takes an array. A framework sets it as a property, and React   hydration keeps it. - 'for' names a '<script type="application/json">' that holds an array, which   a server sends as markup.  Each item is drawn into a row in one of two ways:  - 'renderItem' is a function from an item and its index to the row's   content: a Lit template, a string, or a DOM node. - A '<template>' child defines one row. 'data-field="name"' fills an element   with the item's 'name' as text, and 'data-field-href="url"' writes the   item's 'url' into 'href', the same for any attribute. A field may be a path   of keys, such as 'author.name'.  Rows are your markup in the light DOM, so your stylesheet styles them.  **A grid.** 'columns' lays the items out that many to a line, as a grid of equal columns, and windows the set a line at a time, as React Aria's grid layout does. Each item draws one element, a cell of the grid, and 'estimate' is the height of a line. 'min-column-width' lays out as many columns as fit the box instead, as React Aria's grid layout does with its smallest item size, and follows the box as it resizes. 'gap' spaces the rows, and the columns of a grid, by a number of pixels the list counts in each row's place.  **Across.** 'orientation="horizontal"' lays the items out along a line and scrolls it sideways, as a strip of cards does, windowed the same way: 'estimate' is then an item's width, and the box needs an inline size.  **Sections.** 'section-field' names the field of each item that says which section it is in, and the list draws a header before each section's items, as React Aria's list box sections do. Each section is an element with the 'group' role, named by its header, which is its first child and carries 'data-header', so your stylesheet styles it, such as with 'position: sticky'. A section starts wherever the field changes, so give the items in order. The window counts the headers with the items, and a section the window starts inside is drawn with its header. 'renderSection' draws a header of your own.  **Keyboard.** The list is one tab stop.  | Key | What it does | |---|---| | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. | | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. | | Home, End | Moves to the first or the last item. | | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. | | A letter or a word | Moves to the next item whose text starts with what you typed. | | Escape | Lets go of every chosen item, in a list with 'selection-mode'. | | Alt with Up or Down | In a 'reorderable' list, moves the item a place. Alt with Home or End moves it to either end. | | Tab | Moves into the focused row's own links and buttons, then out of the list. |  An item that is not drawn is scrolled into view and focused, so a keyboard reaches the whole set. The row a reader last focused keeps the tab stop and stays drawn when it scrolls away, so Tab and Shift+Tab come back to it, as React Aria's collections do. In a list nobody has focused yet, the stop moves to the first row on screen. Typing matches each item's 'text-field', which is the first 'data-field' of the row template by default, or the item itself when it is a string or a number.  Each row says its place in the whole set with 'aria-posinset' and 'aria-setsize', so a screen reader says "4,000 of 10,000". The row holding focus stays drawn when it scrolls out.  **Selecting.** 'selection-mode' makes the list a list box a reader chooses from: 'single' selects one item and 'multiple' any number. Space or a press selects an item, Shift with Space, an arrow, Home, End or a press takes in the items from the last one chosen, and Control or Command with A selects them all, in 'multiple'. Escape lets go of every chosen item, and keeps the key from the dialog or menu around the list while there was something to let go of. 'value' holds the chosen items' keys, separated by commas, in the order of the set: 'key-field' names each item's key, and a string or a number item is its own key. A change asks with 'helix-before-change' and tells with 'change'. Each row is an 'option' marked 'aria-selected', so a row's own links and buttons are not reached there: keep those to a list without 'selection-mode'.  'selection-behavior="replace"' selects the item pressed alone, as a file list does, and the arrow keys carry the selection with them. Control or Command with a press or with Space adds or takes out one item, and with an arrow moves without selecting.  **Disabled items.** 'disabled-keys' names items by their keys, separated by commas. Their rows carry 'aria-disabled', the keys and typing pass over them, and a press, Space, or Control with A does not select them.  **Rows a stylesheet can tell apart.** A chosen row carries 'data-selected', a disabled one 'data-disabled', as React Aria's rows do, and the row the keys are on, which holds the tab stop, 'data-active', whether or not the list has focus.  **Loading more.** 'helix-range-change' fires as the items on screen change, and 'range' holds them. 'helix-load-more' fires once a reader is within one screen of the end, once for each length of the set: add to 'items' and it can fire again. While you fetch, set 'loading': the list is busy, and a row after the last item says "Loading more" ('loading-label', or your own content in the 'loading' slot). 'scrollToIndex' takes a reader to an item.  **Moving items** is a separate import, '@fusion.dev/helix/virtual-list/reorder', as React Aria's drag and drop is. With it imported, 'reorderable' lets a reader move items in a list of one column without sections:  - Alt with Up or Down moves the item the keys are on a place, and Alt with   Home or End to either end, as the APG's rearrangeable listbox does. - A pointer drags a whole row. A press that does not travel is still a   press. The list scrolls near an edge, and an item far down a long set is   reached by dragging to the edge. - A drop sends 'helix-before-reorder', which you can refuse, and then   'helix-reorder', whose 'keys' hold every item's key in the new order.   **You move the items**: set 'items' to them in that order. The keys stay   on the item that moved. - Each move is said in a region screen readers announce. The row being   dragged carries 'data-dragging', and the row a drop would land beside   'data-drop-before' or 'data-drop-after'.  **An empty list.** Set 'empty-label', or put your own content in the 'empty' slot, for a row shown when there are no items and none are loading, such as "No messages yet" and a link to write one. Without either, an empty list shows nothing, since a list whose items have not arrived yet has not said it has none.  The list takes the 'empty' state while it has read its items and holds none, and the 'loading' state while 'loading' is set, so your stylesheet can change the box around it for either. A list with no name is reported once in a development build. Name it with 'label' or 'aria-label'.  **Row height.** Rows are placed by 'estimate' until they are drawn. Then the list reads the drawn rows' height once and places every row by it, so a wrong estimate still reaches the last item. Set 'measured' for rows of different heights. Once the list draws rows of different heights, such as rows that wrap on a narrow screen, it places each row by its own height whether 'measured' is set or not.  The list follows its source. A new 'items' array, an edit to the script's text, or a script replaced under the same id draws the new rows. A row that stays in view keeps its element as the list scrolls.  The viewport scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root, so 'scrollTop' works with no stylesheet. You still need to set a block size. */
+  /** The items arrive as data, in one of two ways:  - 'items' takes an array. A framework sets it as a property, and React   hydration keeps it. - 'for' names a '<script type="application/json">' that holds an array, which   a server sends as markup.  Each item is drawn into a row in one of two ways:  - 'renderItem' is a function from an item and its index to the row's   content: a Lit template, a string, or a DOM node. - A '<template>' child defines one row. 'data-field="name"' fills an element   with the item's 'name' as text, and 'data-field-href="url"' writes the   item's 'url' into 'href', the same for any attribute. A field may be a path   of keys, such as 'author.name'.  Rows are your markup in the light DOM, so your stylesheet styles them.  **A grid.** 'columns' lays the items out that many to a line, as a grid of equal columns, and windows the set a line at a time, as React Aria's grid layout does. Each item draws one element, a cell of the grid, and 'estimate' is the height of a line. 'min-column-width' lays out as many columns as fit the box instead, as React Aria's grid layout does with its smallest item size, and follows the box as it resizes. 'gap' spaces the rows, and the columns of a grid, by a number of pixels the list counts in each row's place.  A grid without 'selection-mode' is a grid to a reader, as the APG's grid and React Aria's grid list are: the box is a 'grid' with 'aria-rowcount' and 'aria-colcount', each line drawn is a 'row' with 'aria-rowindex', and each item a 'gridcell' with 'aria-colindex'. Each line is a slot of the list's own, so your rows stay its children: give an item one element. With 'selection-mode' it stays a list box of options, as React Aria's list box in a grid layout does.  **A waterfall.** 'layout="waterfall"' puts each item, in the order of the set, under the column that ends highest so far, the leftmost of a tie, as a wall of photos of different heights is, and as React Aria's waterfall layout and TanStack Virtual's lanes do. 'columns', or 'min-column-width', says how many columns. Every item is measured, at the width of its column, and placed at its column and its height, so items of any height leave no holes. The list draws the items that reach into the box, and the item holding focus. A reader hears a list, or a list box, in the order of the set, which is also the order Tab and a screen reader's own keys take.  In a waterfall, Down and Up move along the column to the next or the previous item in it, Right and Left move to the next or the previous column, to the item there that sits beside this one the most, or the nearest above where none does, and Page Down and Page Up move a box down or up the column. Home and End go to the first and the last item of the set, and Shift with a key takes in the items between in the order of the set.  **Across.** 'orientation="horizontal"' lays the items out along a line and scrolls it sideways, as a strip of cards does, windowed the same way: 'estimate' is then an item's width, and the box needs an inline size.  **Sections.** 'section-field' names the field of each item that says which section it is in, and the list draws a header before each section's items, as React Aria's list box sections do. Each section is an element with the 'group' role, named by its header, which is its first child and carries 'data-header', so your stylesheet styles it, such as with 'position: sticky'. A section starts wherever the field changes, so give the items in order. The window counts the headers with the items, and a section the window starts inside is drawn with its header. 'renderSection' draws a header of your own.  **Keyboard.** The list is one tab stop.  | Key | What it does | |---|---| | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line, or in a waterfall to the next or the previous item down the same column. | | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a waterfall, moves to the item beside in the next or the previous column. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. | | Home, End | Moves to the first or the last item. In a grid without 'selection-mode', to the first or the last item of the line. | | Control or Command with Home or End | In a grid without 'selection-mode', moves to the first or the last item. | | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen, or in a waterfall a box down or up the column. | | A letter or a word | Moves to the next item whose text starts with what you typed. | | Escape | Lets go of every chosen item, in a list with 'selection-mode'. | | Alt with Up or Down | In a 'reorderable' list, moves the item a place. Alt with Home or End moves it to either end. | | Tab | Moves into the focused row's own links and buttons, then out of the list. |  An item that is not drawn is scrolled into view and focused, so a keyboard reaches the whole set. The row a reader last focused keeps the tab stop and stays drawn when it scrolls away, so Tab and Shift+Tab come back to it, as React Aria's collections do. In a list nobody has focused yet, the stop moves to the first row on screen. Typing matches each item's 'text-field', which is the first 'data-field' of the row template by default, or the item itself when it is a string or a number.  Each row says its place in the whole set with 'aria-posinset' and 'aria-setsize', so a screen reader says "4,000 of 10,000", and each cell of a grid its line and its column. The row holding focus stays drawn when it scrolls out.  **Selecting.** 'selection-mode' makes the list a list box a reader chooses from: 'single' selects one item and 'multiple' any number. Space or a press selects an item, Shift with Space, an arrow, Home, End or a press takes in the items from the last one chosen, and Control or Command with A selects them all, in 'multiple'. Escape lets go of every chosen item, and keeps the key from the dialog or menu around the list while there was something to let go of. 'value' holds the chosen items' keys, separated by commas, in the order of the set: 'key-field' names each item's key, and a string or a number item is its own key. A change asks with 'helix-before-change' and tells with 'change'. Each row is an 'option' marked 'aria-selected', so a row's own links and buttons are not reached there: keep those to a list without 'selection-mode'.  'selection-behavior="replace"' selects the item pressed alone, as a file list does, and the arrow keys carry the selection with them. Control or Command with a press or with Space adds or takes out one item, and with an arrow moves without selecting.  **Disabled items.** 'disabled-keys' names items by their keys, separated by commas. Their rows carry 'aria-disabled', the keys and typing pass over them, and a press, Space, or Control with A does not select them.  **Rows a stylesheet can tell apart.** A chosen row carries 'data-selected', a disabled one 'data-disabled', as React Aria's rows do, and the row the keys are on, which holds the tab stop, 'data-active', whether or not the list has focus.  **Loading more.** 'helix-range-change' fires as the items on screen change, and 'range' holds them. 'helix-load-more' fires once a reader is within one screen of the end, once for each length of the set: add to 'items' and it can fire again. While you fetch, set 'loading': the list is busy, and a row after the last item says "Loading more" ('loading-label', or your own content in the 'loading' slot). 'scrollToIndex' takes a reader to an item.  **Moving items** is a separate import, '@fusion.dev/helix/virtual-list/reorder', as React Aria's drag and drop is. With it imported, 'reorderable' lets a reader move items in a list of one column without sections:  - Alt with Up or Down moves the item the keys are on a place, and Alt with   Home or End to either end, as the APG's rearrangeable listbox does. - A pointer drags a whole row. A press that does not travel is still a   press. The list scrolls near an edge, and an item far down a long set is   reached by dragging to the edge. - A drop sends 'helix-before-reorder', which you can refuse, and then   'helix-reorder', whose 'keys' hold every item's key in the new order.   **You move the items**: set 'items' to them in that order. The keys stay   on the item that moved. - Each move is said in a region screen readers announce. The row being   dragged carries 'data-dragging', and the row a drop would land beside   'data-drop-before' or 'data-drop-after'.  **An empty list.** Set 'empty-label', or put your own content in the 'empty' slot, for a row shown when there are no items and none are loading, such as "No messages yet" and a link to write one. Without either, an empty list shows nothing, since a list whose items have not arrived yet has not said it has none.  The list takes the 'empty' state while it has read its items and holds none, and the 'loading' state while 'loading' is set, so your stylesheet can change the box around it for either. A list with no name is reported once in a development build. Name it with 'label' or 'aria-label'.  **Row height.** Rows are placed by 'estimate' until they are drawn. Then the list reads the drawn rows' height once and places every row by it, so a wrong estimate still reaches the last item. Set 'measured' for rows of different heights. Once the list draws rows of different heights, such as rows that wrap on a narrow screen, it places each row by its own height whether 'measured' is set or not.  The list follows its source. A new 'items' array, an edit to the script's text, or a script replaced under the same id draws the new rows. A row that stays in view keeps its element as the list scrolls.  The viewport scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root, so 'scrollTop' works with no stylesheet. You still need to set a block size. */
   "helix-headless-virtual-list": DefineCustomElement<
     HelixHeadlessVirtualList,
     HelixHeadlessVirtualListVueProps,