@fusion.dev/helix-core 0.12.1 → 0.12.3

package/custom-elements.json

@@ -4529,6 +4529,22 @@
             "module": "./mixins/mixin-field/mixin-field.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "MixinTokens",
+          "declaration": {
+            "name": "MixinTokens",
+            "module": "./mixins/mixin-tokens/mixin-tokens.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinTokensInterface",
+          "declaration": {
+            "name": "MixinTokensInterface",
+            "module": "./mixins/mixin-tokens/mixin-tokens.js"
+          }
+        },
         {
           "kind": "js",
           "name": "anchorElement",
@@ -7012,6 +7028,238 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/mixins/mixin-tokens/mixin-tokens.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The public surface `MixinTokens` adds.\n\nDeclared separately for the reason `MixinFieldInterface` gives: TypeScript\ncannot emit declarations for an anonymous class holding private members.",
+          "name": "MixinTokensInterface",
+          "members": [
+            {
+              "kind": "field",
+              "name": "maxTags",
+              "type": {
+                "text": "number"
+              },
+              "description": "How many tokens to show before the rest become a count.\n\n`0` is all of them, and is the default: a cap that guesses is worse than no\ncap, because the number that fits depends on the width of the field and the\nlength of what is in it, neither of which this element knows. What a cap is\ngenuinely for is a field in a row or a table cell, where a set of twelve\nchoices would push everything below it down a line at a time.\n\nThe remainder is counted rather than hidden. `+3` is a fact a reader can act\non, where a row that silently stops is a field that appears to have lost\nwhat was put in it. Date Input and Time Input carry the same property and\nthe same reasoning without taking this mixin, which is why the name is\ntheirs rather than a fourth word for one idea."
+            },
+            {
+              "kind": "method",
+              "name": "renderTokenRow",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "content",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "over",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The row, given what goes in it and how many did not fit.\n\nThe host supplies the content because the two hosts get their tokens from\ndifferent places, and neither can use the other's route."
+            },
+            {
+              "kind": "method",
+              "name": "hideOverflow",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "slot",
+                  "type": {
+                    "text": "HTMLSlotElement | null | undefined"
+                  }
+                }
+              ],
+              "description": "Hides what is over the limit, for a host whose tokens are slotted.\n\n`hidden` rather than removal, because these are the consumer's own nodes\nand this mixin is not entitled to take them out of their document. Returns\nhow many were hidden, which is what the row's count renders."
+            },
+            {
+              "kind": "method",
+              "name": "tokenKeydown",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                },
+                {
+                  "name": "typed",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Backspace on an empty control, answered.\n\n**`typed` is passed rather than read off the control, and that is not\ntidiness.** Combobox writes completions into its own control behind Lit's\nback, so `control.value` holds a suggestion while nothing has been typed:\nreading the control there would refuse a Backspace the reader is entitled\nto. The host knows which of the two it means.\n\nReturns whether it took the key, so a host carries on to its own handling\nwhen it did not."
+            },
+            {
+              "kind": "method",
+              "name": "removeLastToken",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "What the host does when the last token is asked to go.\n\nThe policy is shared and the mechanism is not: a combobox drops a value out\nof its selection, and a filter field takes a token out of its own list."
+            }
+          ],
+          "helix": {}
+        },
+        {
+          "kind": "mixin",
+          "description": "A row of tokens inside a field, and the behavior that goes with it.\n\n**This owns the row and knows nothing about what a token is.** Not where they\ncame from, not whether they were chosen from a list or invented, not what\nremoving one means. Combobox's tokens are a view of its selection and carry a\n`data-value` it reads back; a filter field's are whatever a reader typed.\nBoth get the same row, the same overflow count and the same Backspace.\n\n**What it does not own is where the tokens come from, and that is not a gap.**\nCombobox renders its tags into its own shadow root from the options it was\ngiven; a filter field takes them as slotted children of the host. A slot\ncannot assign a shadow root's own children, so one route cannot serve both,\nand pretending otherwise would put a mode inside the mixin to hide a\ndifference that is real. The host passes what it has and this draws the row\naround it.\n\n**The control stays in the host's shadow root**, which is why this is a mixin\nand not an element to nest. Combobox reaches `[part=\"control\"]` four times,\nfor focus twice, for the floating anchor's width, and to set the selection\nrange across a completion. A shadow root does not pierce a child's, so a\nnested field holding that control would answer `null` to all four.",
+          "name": "MixinTokens",
+          "members": [
+            {
+              "kind": "field",
+              "name": "maxTags",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How many tokens to show before the rest become a count.",
+              "attribute": "max-tags"
+            },
+            {
+              "kind": "method",
+              "name": "renderTokenRow",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "content",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "over",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "hideOverflow",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "slot",
+                  "type": {
+                    "text": "HTMLSlotElement | null | undefined"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "tokenKeydown",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                },
+                {
+                  "name": "typed",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "removeLastToken",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "max-tags",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How many tokens to show before the rest become a count.",
+              "fieldName": "maxTags"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "Base",
+              "type": {
+                "text": "T"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MixinTokensInterface",
+          "declaration": {
+            "name": "MixinTokensInterface",
+            "module": "src/mixins/mixin-tokens/mixin-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinTokens",
+          "declaration": {
+            "name": "MixinTokens",
+            "module": "src/mixins/mixin-tokens/mixin-tokens.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/anchor-element/anchor-element.ts",

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export { MixinControllerOpen, type MixinControllerOpenInterface, } from './mixin
 export { MixinControllerValue, type MixinControllerValueInterface, } from './mixins/mixin-controller-value/mixin-controller-value.js';
 export { type DismissibleElement, MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.js';
 export { MixinField, type MixinFieldInterface } from './mixins/mixin-field/mixin-field.js';
+export { MixinTokens, type MixinTokensInterface } from './mixins/mixin-tokens/mixin-tokens.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closeMarkdown } from './utils/close-markdown/close-markdown.js';

package/dist/index.js

@@ -25,6 +25,7 @@ export { MixinControllerOpen, } from './mixins/mixin-controller-open/mixin-contr
 export { MixinControllerValue, } from './mixins/mixin-controller-value/mixin-controller-value.js';
 export { MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.js';
 export { MixinField } from './mixins/mixin-field/mixin-field.js';
+export { MixinTokens } from './mixins/mixin-tokens/mixin-tokens.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closeMarkdown } from './utils/close-markdown/close-markdown.js';

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

@@ -0,0 +1,87 @@
+import { nothing, type TemplateResult } from 'lit';
+import type { HelixElement } from '../../helix-element/helix-element.js';
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * The public surface `MixinTokens` adds.
+ *
+ * Declared separately for the reason `MixinFieldInterface` gives: TypeScript
+ * cannot emit declarations for an anonymous class holding private members.
+ */
+export declare class MixinTokensInterface {
+    /**
+     * How many tokens to show before the rest become a count.
+     *
+     * `0` is all of them, and is the default: a cap that guesses is worse than no
+     * cap, because the number that fits depends on the width of the field and the
+     * length of what is in it, neither of which this element knows. What a cap is
+     * genuinely for is a field in a row or a table cell, where a set of twelve
+     * choices would push everything below it down a line at a time.
+     *
+     * The remainder is counted rather than hidden. `+3` is a fact a reader can act
+     * on, where a row that silently stops is a field that appears to have lost
+     * what was put in it. Date Input and Time Input carry the same property and
+     * the same reasoning without taking this mixin, which is why the name is
+     * theirs rather than a fourth word for one idea.
+     */
+    maxTags: number;
+    /**
+     * The row, given what goes in it and how many did not fit.
+     *
+     * The host supplies the content because the two hosts get their tokens from
+     * different places, and neither can use the other's route.
+     */
+    protected renderTokenRow(content: unknown, over: number): TemplateResult | typeof nothing;
+    /**
+     * Hides what is over the limit, for a host whose tokens are slotted.
+     *
+     * `hidden` rather than removal, because these are the consumer's own nodes
+     * and this mixin is not entitled to take them out of their document. Returns
+     * how many were hidden, which is what the row's count renders.
+     */
+    protected hideOverflow(slot: HTMLSlotElement | null | undefined): number;
+    /**
+     * Backspace on an empty control, answered.
+     *
+     * **`typed` is passed rather than read off the control, and that is not
+     * tidiness.** Combobox writes completions into its own control behind Lit's
+     * back, so `control.value` holds a suggestion while nothing has been typed:
+     * reading the control there would refuse a Backspace the reader is entitled
+     * to. The host knows which of the two it means.
+     *
+     * Returns whether it took the key, so a host carries on to its own handling
+     * when it did not.
+     */
+    protected tokenKeydown(event: KeyboardEvent, typed: string): boolean;
+    /**
+     * What the host does when the last token is asked to go.
+     *
+     * The policy is shared and the mechanism is not: a combobox drops a value out
+     * of its selection, and a filter field takes a token out of its own list.
+     */
+    protected removeLastToken(): void;
+}
+/**
+ * A row of tokens inside a field, and the behavior that goes with it.
+ *
+ * **This owns the row and knows nothing about what a token is.** Not where they
+ * came from, not whether they were chosen from a list or invented, not what
+ * removing one means. Combobox's tokens are a view of its selection and carry a
+ * `data-value` it reads back; a filter field's are whatever a reader typed.
+ * Both get the same row, the same overflow count and the same Backspace.
+ *
+ * **What it does not own is where the tokens come from, and that is not a gap.**
+ * Combobox renders its tags into its own shadow root from the options it was
+ * given; a filter field takes them as slotted children of the host. A slot
+ * cannot assign a shadow root's own children, so one route cannot serve both,
+ * and pretending otherwise would put a mode inside the mixin to hide a
+ * difference that is real. The host passes what it has and this draws the row
+ * around it.
+ *
+ * **The control stays in the host's shadow root**, which is why this is a mixin
+ * and not an element to nest. Combobox reaches `[part="control"]` four times,
+ * for focus twice, for the floating anchor's width, and to set the selection
+ * range across a completion. A shadow root does not pierce a child's, so a
+ * nested field holding that control would answer `null` to all four.
+ */
+export declare const MixinTokens: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinTokensInterface> & T;
+export {};

package/dist/mixins/mixin-tokens/mixin-tokens.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+export const MixinTokens = (Base) => {
+    class TokensElement extends Base {
+        constructor() {
+            super(...arguments);
+            this.maxTags = 0;
+        }
+        renderTokenRow(content, over) {
+            return html `<span part="tags"
+        >${content}${over > 0 ? html `<span part="rest">${`+${over}`}</span>` : nothing}</span
+      >`;
+        }
+        hideOverflow(slot) {
+            if (!slot) {
+                return 0;
+            }
+            const tokens = slot.assignedElements({ flatten: true });
+            for (const [at, token] of tokens.entries()) {
+                token.toggleAttribute('hidden', this.maxTags > 0 && at >= this.maxTags);
+            }
+            return this.maxTags > 0 ? Math.max(0, tokens.length - this.maxTags) : 0;
+        }
+        tokenKeydown(event, typed) {
+            if (event.key !== 'Backspace' || typed !== '') {
+                return false;
+            }
+            event.preventDefault();
+            this.removeLastToken();
+            return true;
+        }
+        removeLastToken() { }
+    }
+    __decorate([
+        property({ attribute: 'max-tags', type: Number })
+    ], TokensElement.prototype, "maxTags", void 0);
+    return TokensElement;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "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.12.1"
+    "@fusion.dev/helix-icons": "0.12.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.12.1",
-    "@fusion.dev/helix-testing": "0.12.1",
+    "@fusion.dev/helix-cem": "0.12.3",
+    "@fusion.dev/helix-testing": "0.12.3",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",