@fusion.dev/helix-core 0.30.2 → 0.32.0

package/custom-elements.json

@@ -1372,7 +1372,7 @@
               },
               "privacy": "private",
               "readonly": true,
-              "default": "new FloatingController(host, { anchor: options.anchor, ...(options.arrow === undefined ? {} : { arrow: options.arrow }), floating: options.surface, ...(options.offset === undefined ? {} : { offset: options.offset }), ...(options.placement === undefined ? {} : { placement: options.placement }), ...(options.within === undefined ? {} : { within: options.within }), })"
+              "default": "new FloatingController(host, { anchor: options.anchor, ...(options.arrow === undefined ? {} : { arrow: options.arrow }), floating: options.surface, ...(options.offset === undefined ? {} : { offset: options.offset }), ...(options.onPlace === undefined ? {} : { onPlace: options.onPlace }), ...(options.placement === undefined ? {} : { placement: options.placement }), ...(options.within === undefined ? {} : { within: options.within }), })"
             },
             {
               "kind": "field",
@@ -3485,7 +3485,7 @@
                   }
                 }
               ],
-              "description": "One of this element's own parts, by name, or null where it is not rendered.\n\nNot `part`, which every element already has: `Element.part` is the\n`DOMTokenList` of the names the element itself carries, and a method under\nthat name is a type error on every subclass.\n\n**One guard for every lookup.** Lit's server shim has no `querySelector`\non the render root, so a lookup reached during a server render, from a\ngetter a template reads or from `willUpdate`, throws there and nowhere\nelse. Four spellings of the same guard had grown across the library, and\na fifth site with none. Null on the server, which is what the rest of the\ncode already treats a part that has not rendered as.\n\n`helix component`'s `selectors` reads these calls the way it reads a\n`querySelector('[part=\"x\"]')`, so a name nothing renders is a finding\nrather than a null an optional chain swallows."
+              "description": "One of this element's own parts, by name, or null where it is not rendered.\n\nNot `part`, which every element already has: `Element.part` is the\n`DOMTokenList` of the names the element itself carries, and a method under\nthat name is a type error on every subclass.\n\n**One guard for every lookup.** Lit's server shim has no `querySelector`\non the render root, so a lookup reached during a server render, from a\ngetter a template reads or from `willUpdate`, throws there and nowhere\nelse. Four spellings of the same guard had grown across the library, and\na fifth site with none. Null on the server, which is what the rest of the\ncode already treats a part that has not rendered as.\n\n**`~=` and not `=`.** A part drawn in a state carries a second name while\nthe state holds, `part=\"page page-current\"`, and an exact match stops\nfinding it for exactly as long as it is the one that matters.\n\n`helix component`'s `selectors` reads these calls the way it reads a\n`querySelector('[part=\"x\"]')`, so a name nothing renders is a finding\nrather than a null an optional chain swallows."
             },
             {
               "kind": "field",
@@ -3693,6 +3693,12 @@
             }
           ],
           "events": [],
+          "cssStates": [
+            {
+              "description": "Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.",
+              "name": "settled"
+            }
+          ],
           "superclass": {
             "name": "LitElement",
             "package": "lit"
@@ -4079,7 +4085,7 @@
                   }
                 }
               ],
-              "description": "One of this element's own parts, by name, or null where it is not rendered.\n\nNot `part`, which every element already has: `Element.part` is the\n`DOMTokenList` of the names the element itself carries, and a method under\nthat name is a type error on every subclass.\n\n**One guard for every lookup.** Lit's server shim has no `querySelector`\non the render root, so a lookup reached during a server render, from a\ngetter a template reads or from `willUpdate`, throws there and nowhere\nelse. Four spellings of the same guard had grown across the library, and\na fifth site with none. Null on the server, which is what the rest of the\ncode already treats a part that has not rendered as.\n\n`helix component`'s `selectors` reads these calls the way it reads a\n`querySelector('[part=\"x\"]')`, so a name nothing renders is a finding\nrather than a null an optional chain swallows.",
+              "description": "One of this element's own parts, by name, or null where it is not rendered.\n\nNot `part`, which every element already has: `Element.part` is the\n`DOMTokenList` of the names the element itself carries, and a method under\nthat name is a type error on every subclass.\n\n**One guard for every lookup.** Lit's server shim has no `querySelector`\non the render root, so a lookup reached during a server render, from a\ngetter a template reads or from `willUpdate`, throws there and nowhere\nelse. Four spellings of the same guard had grown across the library, and\na fifth site with none. Null on the server, which is what the rest of the\ncode already treats a part that has not rendered as.\n\n**`~=` and not `=`.** A part drawn in a state carries a second name while\nthe state holds, `part=\"page page-current\"`, and an exact match stops\nfinding it for exactly as long as it is the one that matters.\n\n`helix component`'s `selectors` reads these calls the way it reads a\n`querySelector('[part=\"x\"]')`, so a name nothing renders is a finding\nrather than a null an optional chain swallows.",
               "inheritedFrom": {
                 "name": "HelixElement",
                 "module": "src/helix-element/helix-element.ts"
@@ -4381,7 +4387,17 @@
             "status": "experimental",
             "documentation": "https://helix.fusion.dev/core/form-element",
             "tier": "core"
-          }
+          },
+          "cssStates": [
+            {
+              "description": "Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.",
+              "name": "settled",
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            }
+          ]
         }
       ],
       "exports": [
@@ -6698,7 +6714,7 @@
         },
         {
           "kind": "mixin",
-          "description": "Grafts checked state onto a base class.\n\n`checked` is a seed and a correction rather than a claim: the element applies\nits own changes from wherever markup started it, `defaultChecked` is what a\nreset returns to, and a consumer takes the decision by refusing the\n`helix-before-toggle`.\n\nRecords `:state(checked)` whenever the element is checked. Styled tiers\nselect on that rather than on `[checked]`, which is absent until somebody\nwrites it.",
+          "description": "Grafts checked state onto a base class.\n\n`checked` is a seed and a correction rather than a claim: the element applies\nits own changes from wherever markup started it, `defaultChecked` is what a\nreset returns to, and a consumer takes the decision by refusing the\n`helix-before-toggle`.\n\nRecords `:state(checked)` whenever the element is checked. Styled tiers\nselect on that rather than on `[checked]`, which is absent until somebody\nwrites it. Each element applying this lists it as `@cssstate checked`: a\nclass-level tag on a mixin reaches no manifest, here or on the inner class.",
           "name": "MixinControllerChecked",
           "members": [
             {
@@ -6901,7 +6917,7 @@
         },
         {
           "kind": "mixin",
-          "description": "Grafts open state onto a base class, and says so twice.\n\n`helix-before-open` and `helix-before-close` announce the change while it is\nstill a request, so `preventDefault()` refuses it and nothing moves. Native\n`toggle` announces it afterwards, once the state has actually gone, carrying\n`newState` and `oldState` the way the platform does on `<details>` and on a\npopover. The first is how a consumer takes the decision; the second is what\nthey bind when they only want to know.\n\n`open` is a seed and a correction rather than a claim: the element applies\nits own changes from wherever markup started it, and `defaultOpen` is what a\nreset returns to.\n\nRecords `:state(open)` whenever the element is open. Styled tiers select on\nthat rather than on `[open]`, which is absent until somebody writes it.",
+          "description": "Grafts open state onto a base class, and says so twice.\n\n`helix-before-open` and `helix-before-close` announce the change while it is\nstill a request, so `preventDefault()` refuses it and nothing moves. Native\n`toggle` announces it afterwards, once the state has actually gone, carrying\n`newState` and `oldState` the way the platform does on `<details>` and on a\npopover. The first is how a consumer takes the decision; the second is what\nthey bind when they only want to know.\n\n`open` is a seed and a correction rather than a claim: the element applies\nits own changes from wherever markup started it, and `defaultOpen` is what a\nreset returns to.\n\nRecords `:state(open)` whenever the element is open. Styled tiers select on\nthat rather than on `[open]`, which is absent until somebody writes it. Each\nelement applying this lists it as `@cssstate open`, because a class-level\ntag on a mixin reaches no manifest, here or on the inner class below: the\nnote there is about members, which do travel.",
           "name": "MixinControllerOpen",
           "members": [
             {
@@ -7571,7 +7587,7 @@
         },
         {
           "kind": "mixin",
-          "description": "Grafts a label, help text, and a validation message onto a control.\n\n**Over `HelixElement` rather than `HelixFormElement`, because not every\ncontrol that wants a label is form-associated.** A checkbox group is the\ncase: each box in it submits itself already, so the group deliberately\nreports no value of its own, and every form-related member of\n`ElementInternals` throws `NotSupportedError` on an element that is not\nform-associated. Measured, and the ARIA members are fine on the same\nelement, which is why the naming and describing work there and only the\nvalidity has to ask first.\n\nEvery form control wants the same three things around it and wants them in a\ndifferent arrangement: a label above an input, beside a checkbox, and over a\ngroup. So this owns the properties, the parts, and the wiring, and each\ncontrol places the nodes where its own geometry needs them. Same part names\neither way, so one stylesheet in the styled tier dresses all of them.\n\n**Not a wrapping `Field` component, and that is not a style preference.** A\nwrapper cannot name what it wraps. Its label would live in its own shadow\nroot and the control in another, and measured in Chrome 148: an\n`aria-labelledby` IDREF cannot see across, and\n`control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero\nelements, the reference dropped. The same assignment with a label in the\ncontrol's own tree is kept. That pattern works in React libraries because\nthey have no shadow boundary; bringing it here brings the ergonomics and none\nof the conditions that made it work.\n\n**A control whose label is its content renders its own.** A checkbox is named\nby the words beside it, inside the `<label>` that forwards the press, so it\nuses its default slot and nesting `renderLabel`'s `<label>` in there would be\ninvalid markup. `label` is that slot's fallback either way.\n\nWorth knowing, because it costs a label and gives no warning: **a\nwhitespace-only text node is assigned to the default slot and defeats its\nfallback.** Measured in Chrome 148, and a newline between the tags is enough,\nso `<helix-checkbox label=\"Accept\">` closed on the next line renders no label\nat all. A named slot does not have this problem, because `slot=\"label\"` is an\nattribute and a text node has none. It is the platform's behavior rather\nthan ours, and the same is already true of every slot fallback here.\n\n**The ids are fixed rather than generated.** IDREFs resolve within the tree\nthat holds them, so two controls on a page each carrying `helix-hint` in\ntheir own shadow root do not collide. That also removes the usual hydration\nhazard, since there is no generated value for a server and a client to\ndisagree about.\n\n**A group has to say it differently.** A control's `<input>` and its hint\nare both in the shadow root, so a plain `aria-describedby` resolves. A\ngroup's host is in the light DOM and its hint is not, so the IDREF cannot\nreach and `element.ariaDescribedByElements` drops the reference. Only\n`internals.ariaDescribedByElements` keeps it, which is what `describeHost`\nuses. Measured the same way, and the failure is silent either way: the\ndescription simply never reaches the accessibility tree.\n\n**The label, the hint and the feedback are documented on each component that\napplies this, rather than here.** Declaring them once on this mixin is the\nobvious fix and does not work: the analyzer reads `@csspart` off a custom\nelement class, so a class-level tag here reaches the manifest as nothing at\nall, on this JSDoc and on the inner class alike. Measured both ways, and the\ninner-class version is the dangerous one, since it satisfies the rule while\nevery API page stays exactly as wrong as before. Members are different and\ndo inherit, which is what the note about the inner class in the area rules\nis about.",
+          "description": "Grafts a label, help text, and a validation message onto a control.\n\n**Over `HelixElement` rather than `HelixFormElement`, because not every\ncontrol that wants a label is form-associated.** A checkbox group is the\ncase: each box in it submits itself already, so the group deliberately\nreports no value of its own, and every form-related member of\n`ElementInternals` throws `NotSupportedError` on an element that is not\nform-associated. Measured, and the ARIA members are fine on the same\nelement, which is why the naming and describing work there and only the\nvalidity has to ask first.\n\nEvery form control wants the same three things around it and wants them in a\ndifferent arrangement: a label above an input, beside a checkbox, and over a\ngroup. So this owns the properties, the parts, and the wiring, and each\ncontrol places the nodes where its own geometry needs them. Same part names\neither way, so one stylesheet in the styled tier dresses all of them.\n\n**Not a wrapping `Field` component, and that is not a style preference.** A\nwrapper cannot name what it wraps. Its label would live in its own shadow\nroot and the control in another, and measured in Chrome 148: an\n`aria-labelledby` IDREF cannot see across, and\n`control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero\nelements, the reference dropped. The same assignment with a label in the\ncontrol's own tree is kept. That pattern works in React libraries because\nthey have no shadow boundary; bringing it here brings the ergonomics and none\nof the conditions that made it work.\n\n**A control whose label is its content renders its own.** A checkbox is named\nby the words beside it, inside the `<label>` that forwards the press, so it\nuses its default slot and nesting `renderLabel`'s `<label>` in there would be\ninvalid markup. `label` is that slot's fallback either way.\n\nWorth knowing, because it costs a label and gives no warning: **a\nwhitespace-only text node is assigned to the default slot and defeats its\nfallback.** Measured in Chrome 148, and a newline between the tags is enough,\nso `<helix-checkbox label=\"Accept\">` closed on the next line renders no label\nat all. A named slot does not have this problem, because `slot=\"label\"` is an\nattribute and a text node has none. It is the platform's behavior rather\nthan ours, and the same is already true of every slot fallback here.\n\n**The ids are fixed rather than generated.** IDREFs resolve within the tree\nthat holds them, so two controls on a page each carrying `helix-hint` in\ntheir own shadow root do not collide. That also removes the usual hydration\nhazard, since there is no generated value for a server and a client to\ndisagree about.\n\n**A group has to say it differently.** A control's `<input>` and its hint\nare both in the shadow root, so a plain `aria-describedby` resolves. A\ngroup's host is in the light DOM and its hint is not, so the IDREF cannot\nreach and `element.ariaDescribedByElements` drops the reference. Only\n`internals.ariaDescribedByElements` keeps it, which is what `describeHost`\nuses. Measured the same way, and the failure is silent either way: the\ndescription simply never reaches the accessibility tree.\n\n**The label, the hint and the feedback are documented on each component that\napplies this, rather than here.** Declaring them once on this mixin is the\nobvious fix and does not work: the analyzer reads `@csspart` off a custom\nelement class, so a class-level tag here reaches the manifest as nothing at\nall, on this JSDoc and on the inner class alike. Measured both ways, and the\ninner-class version is the dangerous one, since it satisfies the rule while\nevery API page stays exactly as wrong as before. Members are different and\ndo inherit, which is what the note about the inner class in the area rules\nis about. `:state(invalid)` is listed the same way, as a `@cssstate` on each\ncomponent, for the same reason.",
           "name": "MixinField",
           "members": [
             {

package/dist/controllers/floating-controller/floating-controller.d.ts

@@ -18,6 +18,15 @@ export interface FloatingOptions {
      * reader cannot use.
      */
     flip?: boolean;
+    /**
+     * Told the placement the element landed on, after every measurement.
+     *
+     * `data-placement` already says it, on the floating element, which is inside
+     * the host's shadow root. A stylesheet outside reaches that element through
+     * `::part()`, and `::part()` cannot be followed by an attribute selector, so
+     * a host whose surface is drawn from outside records the side on itself.
+     */
+    onPlace?: (placement: Placement) => void;
     /**
      * Space between the anchor and the floating element, in pixels.
      *

package/dist/controllers/floating-controller/floating-controller.js

@@ -37,7 +37,10 @@ export class FloatingController {
                 : this.options.placement;
             const middleware = [offset(gap ?? 0)];
             if (this.options.flip !== false) {
-                middleware.push(flip());
+                const side = (preferred ?? 'bottom-start').split('-')[0];
+                middleware.push(flip(side === 'left' || side === 'right'
+                    ? { crossAxis: 'alignment', fallbackAxisSideDirection: 'end' }
+                    : {}));
             }
             if (this.options.shift !== false) {
                 const inside = this.options.within?.();
@@ -72,6 +75,7 @@ export class FloatingController {
                 });
                 floating.setAttribute('data-placement', placement);
                 floating.setAttribute('data-placed', '');
+                this.options.onPlace?.(placement);
                 const point = middlewareData.arrow;
                 if (pointer && point) {
                     Object.assign(pointer.style, {

package/dist/controllers/popover-controller/popover-controller.d.ts

@@ -56,6 +56,11 @@ export interface PopoverOptions {
      * select puts focus back on its trigger, and a tooltip does neither.
      */
     onDismiss: () => void;
+    /**
+     * Told the placement the surface landed on, after every measurement. Passed
+     * through to the floating pass, which says why a host would want it.
+     */
+    onPlace?: (placement: Placement) => void;
     /**
      * Whether the host wants the surface up, read after every update.
      *

package/dist/controllers/popover-controller/popover-controller.js

@@ -9,6 +9,7 @@ export class PopoverController {
             ...(options.arrow === undefined ? {} : { arrow: options.arrow }),
             floating: options.surface,
             ...(options.offset === undefined ? {} : { offset: options.offset }),
+            ...(options.onPlace === undefined ? {} : { onPlace: options.onPlace }),
             ...(options.placement === undefined ? {} : { placement: options.placement }),
             ...(options.within === undefined ? {} : { within: options.within }),
         });

package/dist/helix-element/helix-element.d.ts

@@ -16,6 +16,8 @@ import { type StaticValue } from 'lit/static-html.js';
  * @since 0.1.0
  * @status experimental
  * @documentation https://helix.fusion.dev/core/helix-element
+ *
+ * @cssstate settled - Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
  */
 export declare class HelixElement extends LitElement {
     /**
@@ -64,6 +66,10 @@ export declare class HelixElement extends LitElement {
      * a fifth site with none. Null on the server, which is what the rest of the
      * code already treats a part that has not rendered as.
      *
+     * **`~=` and not `=`.** A part drawn in a state carries a second name while
+     * the state holds, `part="page page-current"`, and an exact match stops
+     * finding it for exactly as long as it is the one that matters.
+     *
      * `helix component`'s `selectors` reads these calls the way it reads a
      * `querySelector('[part="x"]')`, so a name nothing renders is a finding
      * rather than a null an optional chain swallows.

package/dist/helix-element/helix-element.js

@@ -31,7 +31,9 @@ export class HelixElement extends LitElement {
     }
     partNamed(name) {
         const root = this.renderRoot;
-        return typeof root?.querySelector === 'function' ? root.querySelector(`[part="${name}"]`) : null;
+        return typeof root?.querySelector === 'function'
+            ? root.querySelector(`[part~="${name}"]`)
+            : null;
     }
     toggleState(name, on) {
         if ('states' in this.internals) {

package/dist/mixins/mixin-controller-checked/mixin-controller-checked.d.ts

@@ -46,7 +46,8 @@ export declare class MixinControllerCheckedInterface {
  *
  * Records `:state(checked)` whenever the element is checked. Styled tiers
  * select on that rather than on `[checked]`, which is absent until somebody
- * writes it.
+ * writes it. Each element applying this lists it as `@cssstate checked`: a
+ * class-level tag on a mixin reaches no manifest, here or on the inner class.
  */
 export declare const MixinControllerChecked: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinControllerCheckedInterface> & T;
 export {};

package/dist/mixins/mixin-controller-open/mixin-controller-open.d.ts

@@ -43,7 +43,10 @@ export declare class MixinControllerOpenInterface {
  * reset returns to.
  *
  * Records `:state(open)` whenever the element is open. Styled tiers select on
- * that rather than on `[open]`, which is absent until somebody writes it.
+ * that rather than on `[open]`, which is absent until somebody writes it. Each
+ * element applying this lists it as `@cssstate open`, because a class-level
+ * tag on a mixin reaches no manifest, here or on the inner class below: the
+ * note there is about members, which do travel.
  */
 export declare const MixinControllerOpen: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinControllerOpenInterface> & T;
 export {};

package/dist/mixins/mixin-field/mixin-field.d.ts

@@ -137,7 +137,8 @@ export declare class MixinFieldInterface {
  * inner-class version is the dangerous one, since it satisfies the rule while
  * every API page stays exactly as wrong as before. Members are different and
  * do inherit, which is what the note about the inner class in the area rules
- * is about.
+ * is about. `:state(invalid)` is listed the same way, as a `@cssstate` on each
+ * component, for the same reason.
  */
 export declare const MixinField: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinFieldInterface> & T;
 export {};

package/dist/utils/draw-tooltip/draw-tooltip.js

@@ -19,7 +19,7 @@ export const drawTooltip = (rows, at, tag, where) => {
       style=${styleMap({ insetBlockStart: place.y, insetInlineStart: place.x })}
     ></div>
     <${tag}
-      exportparts="tooltip"
+      exportparts="arrow: tooltip-arrow, tooltip"
       for="helix-chart-mark"
       open
       part="tooltip-anchor"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.30.2",
+  "version": "0.32.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.30.2"
+    "@fusion.dev/helix-icons": "0.32.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.30.2",
-    "@fusion.dev/helix-testing": "0.30.2",
+    "@fusion.dev/helix-cem": "0.32.0",
+    "@fusion.dev/helix-testing": "0.32.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",