@fusion.dev/helix-headless 0.177.1 → 0.177.2

package/custom-elements.json

@@ -34499,38 +34499,6 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
-            {
-              "kind": "field",
-              "name": "pressedOpen",
-              "type": {
-                "text": "boolean"
-              },
-              "privacy": "private",
-              "default": "false",
-              "description": "Whether the trigger's press opened the panel that is open now."
-            },
-            {
-              "kind": "field",
-              "name": "handlePress",
-              "privacy": "private",
-              "readonly": true,
-              "description": "The trigger's press, which notes that it opened the panel, so Escape hands\nfocus back to the trigger."
-            },
-            {
-              "kind": "method",
-              "name": "returnFocus",
-              "privacy": "protected",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "description": "Hands focus back to the control that opened the panel: the trigger after\nits press, which is the APG date picker dialog's rule, and the text after\nArrowDown from it.",
-              "inheritedFrom": {
-                "name": "MixinPickerField",
-                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
-              }
-            },
             {
               "kind": "method",
               "name": "renderPicker",
@@ -34684,6 +34652,21 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "dismiss",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Escape's close, which hands focus back to the control that opened the\npanel: the trigger after its press, which is the APG date picker\ndialog's rule, and the field otherwise.\n\n**Here rather than in each family.** Color Input had the rule alone, and\nDate Input and Time Input, on the same code, put focus in the text after\nthe trigger's press: one control before where the reader had been.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleFocusOut",
@@ -34720,6 +34703,20 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "pressedOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the trigger's press opened the panel that is open now, so Escape returns there.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleKeypress",
@@ -34779,6 +34776,21 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "returnFocus",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Puts the caret back in the field without the field reopening the panel.\n\nThe anchor rather than the text, which is the trigger where there is no\ntext: Color Input's swatch dropped focus to the body on Escape.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -51472,8 +51484,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}'",
-              "description": "The message for text that is no date, where `bad-input-message` is not\nset. `{mode}` is `single`, `range`, or `multiple`.",
+              "default": "'{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}'",
+              "description": "The message for text that is no date, where `bad-input-message` is not\nset. `{mode}` is `single`, `range`, or `multiple`, and `{example}` is a\ndate written as the field writes one, `August 24, 2026` in `en-US` and\n`24. August 2026` in `de-DE` at the default `date-style`.\n\n**The default names a date the field reads back.** It said \"Enter a date\nas YYYY-MM-DD.\" to a reader whose field showed `August 4, 2026`, and a\npattern token is words for a developer. Time Input says the same.",
               "attribute": "unreadable-message",
               "helix": {
                 "words": true
@@ -52425,6 +52437,21 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "dismiss",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Escape's close, which hands focus back to the control that opened the\npanel: the trigger after its press, which is the APG date picker\ndialog's rule, and the field otherwise.\n\n**Here rather than in each family.** Color Input had the rule alone, and\nDate Input and Time Input, on the same code, put focus in the text after\nthe trigger's press: one control before where the reader had been.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleFocusOut",
@@ -52461,6 +52488,20 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "pressedOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the trigger's press opened the panel that is open now, so Escape returns there.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleKeypress",
@@ -54574,8 +54615,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}'",
-              "description": "The message for text that is no date, where `bad-input-message` is not\nset. `{mode}` is `single`, `range`, or `multiple`.",
+              "default": "'{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}'",
+              "description": "The message for text that is no date, where `bad-input-message` is not\nset. `{mode}` is `single`, `range`, or `multiple`, and `{example}` is a\ndate written as the field writes one, `August 24, 2026` in `en-US` and\n`24. August 2026` in `de-DE` at the default `date-style`.\n\n**The default names a date the field reads back.** It said \"Enter a date\nas YYYY-MM-DD.\" to a reader whose field showed `August 4, 2026`, and a\npattern token is words for a developer. Time Input says the same.",
               "fieldName": "unreadableMessage"
             },
             {
@@ -55202,8 +55243,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}'",
-              "description": "The validation message for a value that is not a date.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{mode}` is `single`, `range` or `multiple`, so each can have\nits own sentence.",
+              "default": "'{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}'",
+              "description": "The validation message for a value that is not a date.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{example}` is a date written as the calendar names one,\n`August 24, 2026` in `en-US` and `24. August 2026` in `de-DE`, and `{mode}`\nis `single`, `range` or `multiple`, so each can have its own sentence.\n\n**The default names a date in words.** It said \"Enter a date as\nYYYY-MM-DD.\", and a pattern token is words for a developer.",
               "attribute": "bad-input-message",
               "helix": {
                 "words": true
@@ -57467,8 +57508,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}'",
-              "description": "The validation message for a value that is not a date.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{mode}` is `single`, `range` or `multiple`, so each can have\nits own sentence.",
+              "default": "'{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}'",
+              "description": "The validation message for a value that is not a date.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{example}` is a date written as the calendar names one,\n`August 24, 2026` in `en-US` and `24. August 2026` in `de-DE`, and `{mode}`\nis `single`, `range` or `multiple`, so each can have its own sentence.\n\n**The default names a date in words.** It said \"Enter a date as\nYYYY-MM-DD.\", and a pattern token is words for a developer.",
               "fieldName": "badInputMessage"
             },
             {
@@ -171191,6 +171232,21 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "dismiss",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Escape's close, which hands focus back to the control that opened the\npanel: the trigger after its press, which is the APG date picker\ndialog's rule, and the field otherwise.\n\n**Here rather than in each family.** Color Input had the rule alone, and\nDate Input and Time Input, on the same code, put focus in the text after\nthe trigger's press: one control before where the reader had been.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleFocusOut",
@@ -171227,6 +171283,20 @@
                 "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "pressedOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the trigger's press opened the panel that is open now, so Escape returns there.",
+              "inheritedFrom": {
+                "name": "MixinPickerField",
+                "module": "src/mixins/mixin-picker-field/mixin-picker-field.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleKeypress",
@@ -173868,8 +173938,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a time as {shape}.} other {Enter times as {shape}, separated by commas.}}'",
-              "description": "The validation message for a value that is not a time.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{shape}` is how a time is written, `HH:mm` or `HH:mm:ss`, and\n`{mode}` is `single`, `range` or `multiple`, so each can have its own\nsentence.",
+              "default": "'{mode, select, single {Enter a time such as {example}.} other {Enter times such as {example}, separated by commas.}}'",
+              "description": "The validation message for a value that is not a time.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{example}` is a time written as the picker writes one,\n`2:30 PM` in `en-US` and `14:30` in `de-DE`, `{shape}` is `HH:mm` or\n`HH:mm:ss`, and `{mode}` is `single`, `range` or `multiple`, so each can\nhave its own sentence.\n\n**The default names a time as the picker shows one.** It said \"Enter a\ntime as HH:mm.\" to a reader whose list showed `2:30 PM`, and a pattern\ntoken is words for a developer. Time Input says the same.",
               "attribute": "bad-input-message",
               "helix": {
                 "words": true
@@ -175886,8 +175956,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "'{mode, select, single {Enter a time as {shape}.} other {Enter times as {shape}, separated by commas.}}'",
-              "description": "The validation message for a value that is not a time.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{shape}` is how a time is written, `HH:mm` or `HH:mm:ss`, and\n`{mode}` is `single`, `range` or `multiple`, so each can have its own\nsentence.",
+              "default": "'{mode, select, single {Enter a time such as {example}.} other {Enter times such as {example}, separated by commas.}}'",
+              "description": "The validation message for a value that is not a time.\n\n**Every sentence a control raises in the browser's bubble is a property**,\nnamed for the validity flag it reports, so a form in another language\nspeaks it. Unset is the sentence registered for the page's language, then\nthe English. `{example}` is a time written as the picker writes one,\n`2:30 PM` in `en-US` and `14:30` in `de-DE`, `{shape}` is `HH:mm` or\n`HH:mm:ss`, and `{mode}` is `single`, `range` or `multiple`, so each can\nhave its own sentence.\n\n**The default names a time as the picker shows one.** It said \"Enter a\ntime as HH:mm.\" to a reader whose list showed `2:30 PM`, and a pattern\ntoken is words for a developer. Time Input says the same.",
               "fieldName": "badInputMessage"
             },
             {
@@ -198932,6 +199002,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.177.1"
+    "version": "0.177.2"
   }
 }

package/dist/color-input/root/color-input-root.d.ts

@@ -306,19 +306,6 @@ export declare class HelixHeadlessColorInput extends HelixHeadlessColorInput_bas
      */
     protected sync(): void;
     protected updated(changed: PropertyValues): void;
-    /** Whether the trigger's press opened the panel that is open now. */
-    private pressedOpen;
-    /**
-     * The trigger's press, which notes that it opened the panel, so Escape hands
-     * focus back to the trigger.
-     */
-    private readonly handlePress;
-    /**
-     * Hands focus back to the control that opened the panel: the trigger after
-     * its press, which is the APG date picker dialog's rule, and the text after
-     * ArrowDown from it.
-     */
-    protected returnFocus(): void;
     /**
      * The picker the field opens, behind a seam the styled tier can move.
      *

package/dist/color-input/root/color-input-root.js

@@ -55,12 +55,6 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
         this.handleSampleEnd = () => {
             this.requestOpen(true);
         };
-        this.pressedOpen = false;
-        this.handlePress = () => {
-            const opening = !this.open;
-            this.handleTriggerClick();
-            this.pressedOpen = opening && this.open;
-        };
     }
     static { this.words = 'helix-color-input'; }
     requestValue(next) {
@@ -123,18 +117,6 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
         if (changed.has('value') && parseColor(this.value)) {
             this.settled = this.value;
         }
-        if (changed.has('open') && !this.open) {
-            this.pressedOpen = false;
-        }
-    }
-    returnFocus() {
-        const trigger = this.pressedOpen ? this.partNamed('trigger') : null;
-        this.pressedOpen = false;
-        if (trigger) {
-            trigger.focus();
-            return;
-        }
-        super.returnFocus();
     }
     renderPicker() {
         return html `<${this.tag('color-picker')}
@@ -222,7 +204,7 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
                 : 'swatch-value'
             : nothing}
           ?disabled=${this.isDisabled}
-          @click=${this.handlePress}
+          @click=${this.handleTriggerClick}
         >
           <span
             part="preview"

package/dist/date-input/root/date-input-root.d.ts

@@ -486,7 +486,13 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
     unavailableMessage: string;
     /**
      * The message for text that is no date, where `bad-input-message` is not
-     * set. `{mode}` is `single`, `range`, or `multiple`.
+     * set. `{mode}` is `single`, `range`, or `multiple`, and `{example}` is a
+     * date written as the field writes one, `August 24, 2026` in `en-US` and
+     * `24. August 2026` in `de-DE` at the default `date-style`.
+     *
+     * **The default names a date the field reads back.** It said "Enter a date
+     * as YYYY-MM-DD." to a reader whose field showed `August 4, 2026`, and a
+     * pattern token is words for a developer. Time Input says the same.
      */
     unreadableMessage: string;
     /**

package/dist/date-input/root/date-input-root.js

@@ -12,6 +12,7 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
 import '../../date-picker/index.js';
 import '../../tag/root/index.js';
+const EXAMPLE = '2026-08-24';
 const dates = (value) => value
     .replace(/\s+[–-]\s+/g, ',')
     .split(',')
@@ -119,7 +120,7 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinSegmented
             }
         };
         this.unavailableMessage = 'Choose a date that is available.';
-        this.unreadableMessage = '{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}';
+        this.unreadableMessage = '{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}';
         this.yearViewLabel = '{heading}. Choose a year';
         this.handleIconChange = () => {
             this.requestUpdate();
@@ -232,7 +233,10 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinSegmented
         const held = dates(this.value);
         if (held.length > 0 && !held.every(isDateValue)) {
             return (this.badInputMessage ||
-                formatWords(this, 'unreadableMessage', { mode: this.mode ?? 'single' }));
+                formatWords(this, 'unreadableMessage', {
+                    example: this.written(EXAMPLE),
+                    mode: this.mode ?? 'single',
+                }));
         }
         if (this.min !== '' && held.some((one) => one < this.min)) {
             return [

package/dist/date-picker/root/date-picker-root.d.ts

@@ -117,8 +117,12 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
      * speaks it. Unset is the sentence registered for the page's language, then
-     * the English. `{mode}` is `single`, `range` or `multiple`, so each can have
-     * its own sentence.
+     * the English. `{example}` is a date written as the calendar names one,
+     * `August 24, 2026` in `en-US` and `24. August 2026` in `de-DE`, and `{mode}`
+     * is `single`, `range` or `multiple`, so each can have its own sentence.
+     *
+     * **The default names a date in words.** It said "Enter a date as
+     * YYYY-MM-DD.", and a pattern token is words for a developer.
      */
     badInputMessage: string;
     /**

package/dist/date-picker/root/date-picker-root.js

@@ -9,6 +9,7 @@ import { caretLeft, caretRight } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+const EXAMPLE = '2026-08-24';
 const KEYS = new Set([
     'ArrowDown',
     'ArrowLeft',
@@ -25,7 +26,7 @@ const firstOf = (year, month) => addMonths(asDate('2000-01-01'), (year - 2000) *
 let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerFeedback(MixinControllerValue(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        this.badInputMessage = '{mode, select, single {Enter a date as YYYY-MM-DD.} other {Enter dates as YYYY-MM-DD, separated by commas.}}';
+        this.badInputMessage = '{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}';
         this.defaultMonth = '';
         this.disableDates = '';
         this.disableDays = '';
@@ -491,7 +492,10 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
         if (held.length > 0 && held.some((one) => asDate(one) === null)) {
             return [
                 { badInput: true },
-                formatWords(this, 'badInputMessage', { mode: this.mode ?? 'single' }),
+                formatWords(this, 'badInputMessage', {
+                    example: this.spoken(EXAMPLE),
+                    mode: this.mode ?? 'single',
+                }),
             ];
         }
         for (const one of held) {

package/dist/time-picker/root/time-picker-root.d.ts

@@ -131,9 +131,14 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
      * speaks it. Unset is the sentence registered for the page's language, then
-     * the English. `{shape}` is how a time is written, `HH:mm` or `HH:mm:ss`, and
-     * `{mode}` is `single`, `range` or `multiple`, so each can have its own
-     * sentence.
+     * the English. `{example}` is a time written as the picker writes one,
+     * `2:30 PM` in `en-US` and `14:30` in `de-DE`, `{shape}` is `HH:mm` or
+     * `HH:mm:ss`, and `{mode}` is `single`, `range` or `multiple`, so each can
+     * have its own sentence.
+     *
+     * **The default names a time as the picker shows one.** It said "Enter a
+     * time as HH:mm." to a reader whose list showed `2:30 PM`, and a pattern
+     * token is words for a developer. Time Input says the same.
      */
     badInputMessage: string;
     /**

package/dist/time-picker/root/time-picker-root.js

@@ -14,7 +14,7 @@ import '../../option/root/index.js';
 let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinPickerFeedback(MixinControllerValue(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        this.badInputMessage = '{mode, select, single {Enter a time as {shape}.} other {Enter times as {shape}, separated by commas.}}';
+        this.badInputMessage = '{mode, select, single {Enter a time such as {example}.} other {Enter times such as {example}, separated by commas.}}';
         this.disableTimes = '';
         this.emptyText = 'No times to choose from';
         this.hint = '';
@@ -300,6 +300,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinPickerF
             return [
                 { badInput: true },
                 formatWords(this, 'badInputMessage', {
+                    example: writeClock(this.seconds ? '14:30:15' : '14:30', this.clock, this.seconds),
                     mode: this.mode ?? 'single',
                     shape: this.seconds ? 'HH:mm:ss' : 'HH:mm',
                 }),