@fusion.dev/helix-headless 0.12.3 → 0.13.1

package/types/vue.d.ts

@@ -40,6 +40,7 @@ import type {
   HelixHeadlessDrilldown,
   HelixHeadlessEmpty,
   HelixHeadlessFileInput,
+  HelixHeadlessFilterInput,
   HelixHeadlessFormatDate,
   HelixHeadlessHeatmap,
   HelixHeadlessIconButton,
@@ -1540,6 +1541,9 @@ export type HelixHeadlessComboboxHelixBeforeOpenElementEvent =
 /** `helix-create` event type */
 export type HelixHeadlessComboboxHelixCreateElementEvent =
   HelixHeadlessComboboxElementEvent<HelixCreateEvent>;
+/** `helix-filter` event type */
+export type HelixHeadlessComboboxHelixFilterElementEvent =
+  HelixHeadlessComboboxElementEvent<HelixFilterEvent>;
 
 export type HelixHeadlessComboboxVueProps = {
   /** What the browser may autofill in the text field, as a platform token.
@@ -1685,6 +1689,8 @@ export type HelixHeadlessComboboxVueEvents = {
   "helix-before-open": HelixHeadlessComboboxHelixBeforeOpenElementEvent;
   /** Fired when the reader asks for something the list does not hold, and cancelable. */
   "helix-create": HelixHeadlessComboboxHelixCreateElementEvent;
+  /** Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves. */
+  "helix-filter": HelixHeadlessComboboxHelixFilterElementEvent;
   /** Announced once the value has moved. */
   input: HelixHeadlessComboboxElementEvent;
   /** Says the state moved, carrying `newState` and `oldState`. */
@@ -2951,6 +2957,91 @@ export type HelixHeadlessFileInputVueEvents = {
   "helix-before-change": HelixHeadlessFileInputHelixBeforeChangeElementEvent;
 };
 
+/** `HelixHeadlessFilterInput` component event */
+export type HelixHeadlessFilterInputElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessFilterInput,
+  E
+>;
+/** `helix-before-change` event type */
+export type HelixHeadlessFilterInputHelixBeforeChangeElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeChangeEvent>;
+
+export type HelixHeadlessFilterInputVueProps = {
+  /** Whether the field offers a button that empties it.
+
+The text only. The tokens are the consumer's markup and this element is not
+entitled to take them out of the document, which is the same reason
+`hideOverflow` marks the ones over the cap `hidden` rather than removing
+them. */
+  clearable?: (HelixHeadlessFilterInput["clearable"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  "clear-label"?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  clearLabel?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** Shown while the field is empty.
+
+Not a label: it goes when typing starts. */
+  placeholder?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  "max-tags"?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  maxTags?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  "default-value"?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  defaultValue?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** What the control holds now, and what its form submits.
+
+One property, not two, so `input.value` answers the question anyone
+asking it meant. Writing always applies; `<helix-input value="x">` is the
+same statement in markup, and `default-value` is how markup seeds a value
+a reset should return to. */
+  value?: (HelixHeadlessFilterInput["value"]) | undefined;
+  /** What is wrong, in the reader's words rather than the browser's. */
+  feedback?: (HelixHeadlessFilterInput["feedback"]) | undefined;
+  /** Help under the control, shown while there is nothing wrong. */
+  hint?: (HelixHeadlessFilterInput["hint"]) | undefined;
+  /** The accessible name, and the fallback for the `label` slot. */
+  label?: (HelixHeadlessFilterInput["label"]) | undefined;
+  /** Whether the form refuses to submit without it. */
+  required?: (HelixHeadlessFilterInput["required"]) | undefined;
+  /** Whether the control is non-interactive.
+
+Reflected, because the styled tier selects on it, and mirrored to
+`aria-disabled` rather than removing the element from the accessibility
+tree, so a screen reader can still announce that the control exists.
+
+The mirror itself is in `willUpdate` below, here rather than in each
+control, because here is where `disabled` is. */
+  disabled?: (HelixHeadlessFilterInput["disabled"]) | undefined;
+  /** Name submitted with the form.
+
+**Reflected, and it is the exception to "reflect only what CSS selects
+on".** The platform builds a form's entry list from the `name` *content
+attribute*, not from the property, so a control named through the property
+submitted under no name at all and was silently dropped. Measured: two
+inputs in one form, one named by attribute and one by property, and the
+form carried a single entry.
+
+Safe for a React consumer, which is what the rule is protecting: React
+renders a custom element's props as attributes on the server, so the name
+is already in the markup being hydrated and reflecting it writes what is
+there. It is only a change to the markup when a consumer assigns it
+imperatively later, and nothing is hydrating by then.
+
+Here rather than on each control. */
+  name?: (HelixHeadlessFilterInput["name"]) | undefined;
+};
+
+export type HelixHeadlessFilterInputVueEvents = {
+  /** Relayed from the input once the reader has finished. */
+  change: HelixHeadlessFilterInputElementEvent;
+  /** Fired as the text changes, and cancelable. */
+  "helix-before-change": HelixHeadlessFilterInputHelixBeforeChangeElementEvent;
+  /** Announced once the text has moved. */
+  input: HelixHeadlessFilterInputElementEvent;
+};
+
 export type HelixHeadlessFormatDateVueProps = {
   /** The timestamp, as anything `Date` parses.
 
@@ -8222,6 +8313,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessFileInputVueProps,
     HelixHeadlessFileInputVueEvents
   >;
+  /** **The tokens are the consumer's own elements, slotted.** What a filter narrows by belongs to the consumer's model rather than to this element: a facet with a prefix, a saved query, a range. So they are slotted rather than rendered from a list of strings, and removing one is a request this element makes rather than a change it applies. Combobox is the other way round, and that is the difference between the two: its tokens are a view of a selection it owns, drawn from options it was handed.  **'value' is the text being typed, not the tokens**, which is what makes this a field a consumer can listen to. Every keystroke announces 'input' with the text on the element, so a table narrows as the reader types. The tokens need no reporting back, being markup the consumer already holds.  Backspace on an empty field asks the last token to go, through the same 'helix-dismiss' its own remove control fires, so a consumer who handled the pointer has already handled the keyboard. */
+  "helix-headless-filter-input": DefineCustomElement<
+    HelixHeadlessFilterInput,
+    HelixHeadlessFilterInputVueProps,
+    HelixHeadlessFilterInputVueEvents
+  >;
   /** A date in a page is almost never wanted as an ISO string, and formatting one in the consumer's own code means every consumer ships a copy of the same 'Intl' call and a different set of options. This is that call, as an element, so a date is written where it is shown.  **'elapsed' is the mode a feed wants, and it stops being relative on purpose.** "42m", "3h", "1d" is what a row of activity reads as, and past a week the compact form is a lie: 'Intl.NumberFormat' narrow renders both 'minute' and 'month' as 'm' in en-US, so "3m" is three minutes at the top of a feed and three months further down it. Past six days this shows a date, which is shorter to read and impossible to misread. 'elapsedTime' in 'helix/core' carries the measurement.  **The reading refreshes itself, from one timer the page shares.** A relative timestamp is correct for as long as its unit lasts and wrong afterwards, and a page left open is exactly where that shows. Each element asks to be woken when its own reading expires rather than polling, and an element showing a date asks for nothing at all: fifty rows and fifty intervals is fifty wakeups a second where one will do, and a feed of last month's notifications should cost nothing to leave open.  **'<time datetime>' whatever the text says**, so a screen reader, a copy and paste, and anything parsing the page all get the real instant rather than "yesterday". */
   "helix-headless-format-date": DefineCustomElement<
     HelixHeadlessFormatDate,