@excom/super-input 0.1.0

package/support/package-meta.json

@@ -0,0 +1,275 @@
+{
+  "shortName": "super-input",
+  "package": {
+    "name": "@excom/super-input",
+    "version": "0.1.0",
+    "description": "<super-input> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "comprehensive": "<form>\n  <super-input\n    text-format=\"(xxx) xxx-xxxx\"\n    invalid-message=\"That doesn't look like a US phone number\"\n    auto-label\n    class=\"raised\"\n  >\n    <label>Phone number</label>\n    <input required pattern=\"^\\(\\d{3}\\)\\s\\d{3}-\\d{4}\" placeholder=\"(123) 456-7890\"/>\n  </super-input>\n  <!-- Form and button exist purely for the demo -->\n  <button type=\"submit\">Submit</button>\n</form>\n",
+    "invalid-message": "<form>\n  <super-input text-format=\"(xxx) xxx-xxxx\" invalid-message=\"That doesn't look like a US phone number\">\n    <label>Phone number</label>\n    <input required pattern=\"^\\(\\d{3}\\)\\s\\d{3}-\\d{4}\" />\n  </super-input>\n  <button type=\"submit\">Submit</button>\n</form>",
+    "reflect-value": "<super-input reflect-value class=\"raised\" id=\"si-rv\">\n    <label>Email</label>\n    <input type=\"email\" />\n    <style>\n        super-input#si-rv {\n            &::after { color: orange; }\n            &:not([current-value*=\".\"])::after {\n                content: 'Email is missing \".\" character.';\n            }\n            &:not([current-value*=\"@\"])::after {\n                content: 'Email is missing \"@\" character.';\n            }\n        }\n    </style>\n</super-input>",
+    "slider": "<super-input reflect-value style=\"--super-input-min: 18; --super-input-max: 85;\">\n    <label>Age</label>\n    <input type=\"range\" name=\"age\" step=\"1\" value=\"36\" min=\"18\" max=\"85\">\n</super-input>",
+    "with-format": "<super-input text-format=\"(xxx) xxx-xxxx\">\n  <label>Phone number</label>\n  <input value=\"8902340170\" />\n</super-input>\n"
+  },
+  "readme": "<h1 id=\"md-super-input\">super-input</h1>\n<p>A lightweight element that wraps and upgrades the native <code>&lt;input&gt;</code> element.</p>\n<p><include-content data-demo=\"comprehensive\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Live text formatting</strong> e.g. phone numbers, dates, SSNs</li>\n<li><strong>Custom, native validity messages</strong> uses the browser&#39;s built-in validation UI to show your message</li>\n<li><strong>Auto-labeling</strong> it stitches a sibling <code>&lt;label&gt;</code> to the <code>&lt;input&gt;</code> via <code>id</code>/<code>for</code></li>\n<li><strong>Progressively enhanced</strong> Does <strong>not</strong> replace the native input; it enhances it. Everything you know\nabout <code>&lt;input&gt;</code> still applies.</li>\n<li><strong>Range slider</strong> ships with upgraded slider styling and functionality</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap a native <code>&lt;input&gt;</code> and optionally a <code>&lt;label&gt;</code>. Nothing else is required. </p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-formatting-input-as-the-user-types\">Formatting input as the user types</h4>\n<p>Set <code>text-format</code> to a template using <code>x</code> as a character placeholder.</p>\n<p><include-content data-demo=\"with-format\"></include-content></p>\n<p>Common templates:</p>\n<ul>\n<li>Phone (US): <code>(xxx) xxx-xxxx</code></li>\n<li>Date: <code>xx/xx/xxxx</code></li>\n<li>SSN: <code>xxx-xx-xxxx</code></li>\n</ul>\n<p>The wrapped <code>&lt;input&gt;</code> sees the formatted value. Pair with <code>pattern</code> for\nvalidation.</p>\n<h4 id=\"md-custom-validity-messages\">Custom validity messages</h4>\n<p>Set <code>invalid-message</code> and the browser&#39;s native validation UI will surface it\nwhen the input fails. Use the native <code>pattern</code>, <code>required</code>, <code>min</code>, <code>max</code>, etc for validation.\nTry submitting the form in the demo below with an invalid phone number.</p>\n<p><include-content data-demo=\"invalid-message\"></include-content></p>\n<p>The message is installed via <code>setCustomValidity()</code> on the <code>invalid</code> event and\ncleared on the next <code>keydown</code>, so the input stops being marked invalid as\nsoon as the user tries again.</p>\n<h4 id=\"md-using-reflect-value\">Using reflect-value</h4>\n<p>The <code>reflect-value</code> attribute has two primary uses:</p>\n<ul>\n<li>Is required for animating <code>raised</code> labels without an input <code>placeholder</code> attribute</li>\n<li>Allows you to hook into it to run your own behaviors</li>\n</ul>\n<p>Here&#39;s an example with a raising label that will display an error if the user has not entered an email with an <code>@</code> or <code>.</code> characters.</p>\n<p><include-content data-demo=\"reflect-value\"></include-content></p>\n<h4 id=\"md-range-slider\">Range slider</h4>\n<p><code>&lt;super-input&gt;</code> ships with advanced slider CSS. Add <code>[type=&quot;range&quot;]</code> to the <code>input</code>. <code>[reflect-value]</code> is required for this to work natively in Chromium browsers. Safari and Firefox will need some help via Quark or JS until they support <a href=\"https://caniuse.com/mdn-css_types_type\">the CSS <code>type()</code> function</a>. You must also set the min/max CSS variables to match the min/max on the input.</p>\n<p>Be cautious using this feature, as it aesthetically relies on non-standard pseudo elements for the time being.</p>\n<p><include-content data-demo=\"slider\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-super-input\">super-input</h1>\n<p>A lightweight element that wraps and upgrades the native <code>&lt;input&gt;</code> element.</p>\n<p><include-content data-demo=\"comprehensive\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Live text formatting</strong> e.g. phone numbers, dates, SSNs</li>\n<li><strong>Custom, native validity messages</strong> uses the browser&#39;s built-in validation UI to show your message</li>\n<li><strong>Auto-labeling</strong> it stitches a sibling <code>&lt;label&gt;</code> to the <code>&lt;input&gt;</code> via <code>id</code>/<code>for</code></li>\n<li><strong>Progressively enhanced</strong> Does <strong>not</strong> replace the native input; it enhances it. Everything you know\nabout <code>&lt;input&gt;</code> still applies.</li>\n<li><strong>Range slider</strong> ships with upgraded slider styling and functionality</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap a native <code>&lt;input&gt;</code> and optionally a <code>&lt;label&gt;</code>. Nothing else is required. </p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-formatting-input-as-the-user-types\">Formatting input as the user types</h4>\n<p>Set <code>text-format</code> to a template using <code>x</code> as a character placeholder.</p>\n<p><include-content data-demo=\"with-format\"></include-content></p>\n<p>Common templates:</p>\n<ul>\n<li>Phone (US): <code>(xxx) xxx-xxxx</code></li>\n<li>Date: <code>xx/xx/xxxx</code></li>\n<li>SSN: <code>xxx-xx-xxxx</code></li>\n</ul>\n<p>The wrapped <code>&lt;input&gt;</code> sees the formatted value. Pair with <code>pattern</code> for\nvalidation.</p>\n<h4 id=\"md-custom-validity-messages\">Custom validity messages</h4>\n<p>Set <code>invalid-message</code> and the browser&#39;s native validation UI will surface it\nwhen the input fails. Use the native <code>pattern</code>, <code>required</code>, <code>min</code>, <code>max</code>, etc for validation.\nTry submitting the form in the demo below with an invalid phone number.</p>\n<p><include-content data-demo=\"invalid-message\"></include-content></p>\n<p>The message is installed via <code>setCustomValidity()</code> on the <code>invalid</code> event and\ncleared on the next <code>keydown</code>, so the input stops being marked invalid as\nsoon as the user tries again.</p>\n<h4 id=\"md-using-reflect-value\">Using reflect-value</h4>\n<p>The <code>reflect-value</code> attribute has two primary uses:</p>\n<ul>\n<li>Is required for animating <code>raised</code> labels without an input <code>placeholder</code> attribute</li>\n<li>Allows you to hook into it to run your own behaviors</li>\n</ul>\n<p>Here&#39;s an example with a raising label that will display an error if the user has not entered an email with an <code>@</code> or <code>.</code> characters.</p>\n<p><include-content data-demo=\"reflect-value\"></include-content></p>\n<h4 id=\"md-range-slider\">Range slider</h4>\n<p><code>&lt;super-input&gt;</code> ships with advanced slider CSS. Add <code>[type=&quot;range&quot;]</code> to the <code>input</code>. <code>[reflect-value]</code> is required for this to work natively in Chromium browsers. Safari and Firefox will need some help via Quark or JS until they support <a href=\"https://caniuse.com/mdn-css_types_type\">the CSS <code>type()</code> function</a>. You must also set the min/max CSS variables to match the min/max on the input.</p>\n<p>Be cautious using this feature, as it aesthetically relies on non-standard pseudo elements for the time being.</p>\n<p><include-content data-demo=\"slider\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/super-input",
+    "shortName": "super-input",
+    "version": "0.1.0",
+    "description": "<super-input> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/super-input@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/super-input@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/super-input"
+    },
+    "imports": {
+      "js": "import \"@excom/super-input\";",
+      "css": "@import \"@excom/super-input\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/super-input\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/super-input\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "super-input",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "auto-label",
+          "type": "boolean",
+          "description": "When set, generates or uses an existing <code>id</code> on the <code>&lt;input&gt;</code> and associates the <code>&lt;label&gt;</code>.",
+          "fieldName": "autoLabel",
+          "surface": "option"
+        },
+        {
+          "name": "invalid-message",
+          "type": "string",
+          "description": "If set, this message is installed via <code>setCustomValidity()</code> when the native <code>invalid</code> event fires, and cleared on the next <code>keydown</code>. Makes built-in HTML validation surface a custom message.",
+          "fieldName": "invalidMessage",
+          "surface": "option"
+        },
+        {
+          "name": "reflect-value",
+          "type": "boolean",
+          "description": "When set, the current input value is mirrored to the <code>current-value</code> attribute so CSS and selectors can respond to it. Off by default because reflecting every keystroke is not free.",
+          "fieldName": "reflectValue",
+          "surface": "option"
+        },
+        {
+          "name": "text-format",
+          "type": "string",
+          "description": "Pattern defining visible formatting. Use <code>x</code> for any digit and any other character as a literal. Examples: <code>(xxx) xxx-xxxx</code>, <code>xx/xx/xxxx</code>, <code>xxx-xx-xxxx</code>. When set, the input value is live-formatted on every keystroke.",
+          "fieldName": "textFormat",
+          "surface": "option"
+        },
+        {
+          "name": "current-value",
+          "type": "string",
+          "description": "Mirrors the wrapped <code>&lt;input&gt;</code>&#39;s value when <code>reflect-value</code> is set. Read-only from the app&#39;s point of view — writing it does not change the input.",
+          "fieldName": "currentValue",
+          "surface": "state"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [
+        {
+          "name": "--super-input-accent",
+          "description": "Active track / accent color for the range fill.",
+          "syntax": "<color>",
+          "default": "var(--super-input-primary, blue)"
+        },
+        {
+          "name": "--super-input-bg",
+          "description": "Surface background behind the control (and raised-label mask).",
+          "syntax": "<color>",
+          "default": "var(--v-form-element-background-color, transparent)"
+        },
+        {
+          "name": "--super-input-border-color",
+          "description": "Default border color for raised inputs.",
+          "syntax": "<color>",
+          "default": "var( --v-form-element-border-color, currentColor )"
+        },
+        {
+          "name": "--super-input-border-radius",
+          "description": "Corner radius for raised inputs.",
+          "syntax": "<length>",
+          "default": "var(--v-border-radius, 4px)"
+        },
+        {
+          "name": "--super-input-border-width",
+          "description": "Border width for raised inputs.",
+          "syntax": "<length>",
+          "default": "var(--v-border-width, 1px)"
+        },
+        {
+          "name": "--super-input-color",
+          "description": "Foreground / label color.",
+          "syntax": "<color>",
+          "default": "var(--v-color, inherit)"
+        },
+        {
+          "name": "--super-input-focus-color",
+          "description": "Focus ring / focus border color.",
+          "syntax": "<color>",
+          "default": "var( --v-form-element-focus-color, var(--super-input-border-color) )"
+        },
+        {
+          "name": "--super-input-font-size",
+          "description": "Base font size for the control and value readout.",
+          "syntax": "<length>",
+          "default": "16px"
+        },
+        {
+          "name": "--super-input-font-weight",
+          "description": "Font weight for the range value readout.",
+          "syntax": "<number> | <integer>",
+          "default": "700"
+        },
+        {
+          "name": "--super-input-height",
+          "description": "Host height for range layout (thumb + value readout).",
+          "syntax": "<length>",
+          "default": "calc(var(--super-input-thumb-size) + 36px)"
+        },
+        {
+          "name": "--super-input-label-height",
+          "description": "Computed label line box height (used when a <code>&lt;label&gt;</code> is present).",
+          "syntax": "<length>",
+          "default": "calc( var(--v-line-height, 1.5) * var(--super-input-font-size) )"
+        },
+        {
+          "name": "--super-input-label-margin-bottom",
+          "description": "Gap between a floating label and the control.",
+          "syntax": "<length>",
+          "default": "calc(21px * 0.375)"
+        },
+        {
+          "name": "--super-input-max",
+          "description": "Range maximum. Prefer setting on the host (or via CSS).",
+          "syntax": "<number>",
+          "default": "100"
+        },
+        {
+          "name": "--super-input-min",
+          "description": "Range minimum. Prefer setting on the host (or via CSS): CSS cannot read the child input&#39;s <code>min</code> attribute from the parent.",
+          "syntax": "<number>",
+          "default": "0"
+        },
+        {
+          "name": "--super-input-primary",
+          "description": "Accent color (range fill, thumb border, focus chrome).",
+          "syntax": "<color>",
+          "default": "var(--v-primary, blue)"
+        },
+        {
+          "name": "--super-input-thumb-color",
+          "description": "Range thumb fill color.",
+          "syntax": "<color>",
+          "default": "var( --v-range-thumb-color, var(--super-input-bg) )"
+        },
+        {
+          "name": "--super-input-thumb-size",
+          "description": "Diameter of the range thumb.",
+          "syntax": "<length>",
+          "default": "44px"
+        },
+        {
+          "name": "--super-input-track-height",
+          "description": "Height of the range track.",
+          "syntax": "<length>",
+          "default": "2px"
+        },
+        {
+          "name": "--super-input-transition-duration",
+          "description": "Duration for border / label transitions.",
+          "syntax": "<time>",
+          "default": "var(--v-transition-duration-fast, 0.15s)"
+        },
+        {
+          "name": "--super-input-transition-ease",
+          "description": "Easing for border / label transitions.",
+          "syntax": "*",
+          "default": "var(--v-transition-ease-out, ease-out)"
+        },
+        {
+          "name": "--super-input-value",
+          "description": "Current range value used for fill / readout positioning. With <code>reflect-value</code>, may be driven from <code>attr(current-value)</code> where typed <code>attr()</code> is supported.",
+          "syntax": "<number>",
+          "default": "50"
+        },
+        {
+          "name": "--super-input-width",
+          "description": "Host width for range layout.",
+          "syntax": "<length> | <percentage>",
+          "default": "100%"
+        }
+      ],
+      "cssClasses": [
+        {
+          "name": "raised",
+          "description": "Raised / floating-label text field appearance. Apply as <code>class=&quot;raised&quot;</code> on <code>&lt;super-input&gt;</code> wrapping a text-like <code>&lt;input&gt;</code>."
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--super-input",
+          "selectors": [
+            "super-input",
+            ".tag-super-input"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--super-input--has-current-value",
+          "selectors": [
+            "[current-value]",
+            "[data-current-value]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--super-input--has-reflect-value",
+          "selectors": [
+            "[reflect-value]",
+            "[data-reflect-value]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [
+        {
+          "name": "descendant:input",
+          "relationship": "descendant",
+          "selector": "input",
+          "required": true,
+          "description": "Required native <code>&lt;input&gt;</code> to enhance."
+        },
+        {
+          "name": "descendant:label",
+          "relationship": "descendant",
+          "selector": "label",
+          "required": false,
+          "description": "Optional native <code>&lt;label&gt;</code>. When <code>auto-label</code> is set, its <code>for</code> attribute is linked to the input&#39;s <code>id</code>."
+        }
+      ],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/comprehensive.view.test.ts

@@ -0,0 +1,22 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("comprehensive view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("combines format, invalid-message, and auto-label", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "comprehensive"));
+    const host = root.querySelector("super-input")!;
+    expect(host.hasAttribute("auto-label")).toBe(true);
+    expect(host.getAttribute("text-format")).toBe("(xxx) xxx-xxxx");
+    expect(host.getAttribute("invalid-message")).toMatch(/US phone/);
+  });
+});

package/support/tests/invalid-message.view.test.ts

@@ -0,0 +1,21 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("invalid-message view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("exposes the custom invalid message", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "invalid-message"));
+    const host = root.querySelector("super-input")!;
+    expect(host.getAttribute("invalid-message")).toMatch(/US phone/);
+    expect(host.querySelector("input")?.required).toBe(true);
+  });
+});

package/support/tests/reflect-value.view.test.ts

@@ -0,0 +1,24 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { flush, mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("reflect-value view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("reflects typed email onto current-value", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "reflect-value"));
+    const host = root as unknown as HTMLSuperInputElement;
+    const input = root.querySelector("input")!;
+    input.value = "a@b.com";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    await flush();
+    expect(host.getAttribute("current-value")).toBe("a@b.com");
+  });
+});

package/support/tests/slider.view.test.ts

@@ -0,0 +1,24 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { flush, mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("slider view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("reflects the range value", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "slider"));
+    const input = root.querySelector<HTMLInputElement>("input")!;
+    expect(input.value).toBe("36");
+    input.value = "40";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    await flush();
+    expect(root.getAttribute("current-value")).toBe("40");
+  });
+});

package/support/tests/super-input.test.ts

@@ -0,0 +1,245 @@
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+
+describe("super-input", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("[auto-label] creates new id if necessary", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input auto-label>
+        <input />
+        <label></label>
+      </super-input>`,
+    );
+    const input = el.querySelector("input") as HTMLInputElement;
+    const label = el.querySelector("label") as HTMLLabelElement;
+    expect(input.id).toMatch(/super-input-/);
+    expect(input.id).toBe(label.htmlFor);
+  });
+
+  it("1. [auto-label] takes existing id if provided", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input auto-label>
+        <input id="my-input" />
+        <label for="will-be-replaced"></label>
+      </super-input>`,
+    );
+    expect(el).dom.to.equalTag(
+      `<super-input auto-label>
+        <input id="my-input" />
+        <label for="my-input"></label>
+      </super-input>`,
+    );
+  });
+
+  it("2. [auto-label] takes existing id if provided", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input auto-label>
+        <input />
+        <label for="my-input"></label>
+      </super-input>`,
+    );
+    expect(el).dom.to.equalTag(
+      `<super-input auto-label>
+        <input id="my-input" />
+        <label for="my-input"></label>
+      </super-input>`,
+    );
+  });
+
+  it("reflects input value when enabled", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input reflect-value><input /></super-input>`,
+    );
+    const input = el.querySelector("input") as HTMLInputElement;
+    input.value = "hello";
+    input.dispatchEvent(new Event("input"));
+    await wait(0);
+    expect(el).dom.to.equalTag(
+      `<super-input reflect-value current-value="hello"></super-input>`,
+    );
+  });
+
+  it("does not reflect value when reflectValue is false", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input><input /></super-input>`,
+    );
+    const input = el.querySelector("input") as HTMLInputElement;
+    input.value = "hello";
+    input.dispatchEvent(new Event("input"));
+    await wait(0);
+    expect(el).dom.to.equalTag(`<super-input></super-input>`);
+  });
+
+  it("formats input value configured in [text-format] and reflects that formatted value", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input text-format="xx-xx-xxxx" reflect-value><input value="1234567890" /></super-input>`,
+    );
+    const input = el.querySelector("input")!;
+    expect(input.value).toBe("12-34-5678");
+    expect(el.currentValue).toBe("12-34-5678");
+    el.textFormat = "xxxx-xxxx-xxxx";
+    expect(input.value).toBe("1234-5678");
+    expect(el.currentValue).toBe("1234-5678");
+    input.value = "1234567890";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    expect(input.value).toBe("1234-5678-90");
+    expect(el.currentValue).toBe("1234-5678-90");
+    el.textFormat = null;
+    expect(input.value).toBe("1234567890");
+    expect(el.currentValue).toBe("1234567890");
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    expect(input.value).toBe("1234567890");
+    expect(el.currentValue).toBe("1234567890");
+    input.value = "";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    expect(input.value).toBe("");
+    expect(el.currentValue).toBe(null);
+  });
+
+  it("adds and removes event listeners when needed", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input><input /></super-input>`,
+    );
+    const input = el._inputElement;
+    el.reflectValue = true;
+    expect(input).toMatchListeners({ input: 1 });
+    el.textFormat = "x-x"
+    expect(input).toMatchListeners({ input: 1 });
+    el.invalidMessage = "Invalid";
+    expect(input).toMatchListeners({ input: 1, invalid: 1, keydown: 1 });
+    el.reflectValue = false;
+    expect(input).toMatchListeners({ input: 1, invalid: 1, keydown: 1 });
+    el.textFormat = null;
+    expect(input).toMatchListeners({ invalid: 1, keydown: 1 });
+    el.invalidMessage = "test"
+    expect(input).toMatchListeners({ invalid: 1, keydown: 1 })
+    el.invalidMessage = null;
+    expect(input).toMatchListeners({});
+  });
+
+  it("does not push an external current-value write into the input", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input><input value="1" /></super-input>`,
+    );
+    const input = el.querySelector("input") as HTMLInputElement;
+    input.value = "typed";
+    el.setAttribute("current-value", "42");
+    await wait(0);
+    expect(input.value).toBe("typed");
+  });
+});
+
+describe("super-input (edge cases)", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("[invalid-message] installs the custom validity on `invalid` and clears it on `keydown`", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input invalid-message="Needs a value"><input required /></super-input>`,
+    );
+    const input = el.querySelector("input")!;
+    expect(input).toMatchListeners({ invalid: 1, keydown: 1 });
+
+    input.dispatchEvent(new Event("invalid"));
+    expect(input.validationMessage).toBe("Needs a value");
+    expect(input.validity.customError).toBe(true);
+
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "a" }));
+    expect(input.validity.customError).toBe(false);
+    expect(input.validationMessage).not.toBe("Needs a value");
+  });
+
+  it("[invalid-message] does nothing on `invalid` once the message is unset", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input invalid-message="Needs a value"><input required /></super-input>`,
+    );
+    const input = el.querySelector("input")!;
+    el.invalidMessage = null;
+    expect(input).toMatchListeners({});
+    // the listener is gone; invoking the handler directly is a no-op
+    el.handleInvalid();
+    expect(input.validity.customError).toBe(false);
+    input.dispatchEvent(new Event("invalid"));
+    expect(input.validity.customError).toBe(false);
+  });
+
+  it("[reflect-value] reflects `null` when the input is empty", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input reflect-value><input value="abc" /></super-input>`,
+    );
+    const input = el.querySelector("input")!;
+    expect(el.currentValue).toBe("abc");
+    input.value = "";
+    input.dispatchEvent(new Event("input"));
+    expect(el.currentValue).toBe(null);
+    expect(el.hasAttribute("current-value")).toBe(false);
+  });
+
+  it("[reflect-value] clears current-value when reflection is switched off", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input reflect-value><input value="abc" /></super-input>`,
+    );
+    expect(el.getAttribute("current-value")).toBe("abc");
+    el.reflectValue = false;
+    expect(el.currentValue).toBe(null);
+    const input = el.querySelector("input")!;
+    input.value = "typed";
+    input.dispatchEvent(new Event("input"));
+    expect(el.currentValue).toBe(null);
+  });
+
+  it("[text-format] formats a programmatic value when the format changes and keeps the caret-relative selection", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input text-format="(xxx) xxx-xxxx"><input /></super-input>`,
+    );
+    const input = el.querySelector("input")!;
+    // an empty input is left alone by doFormat
+    el.textFormat = "xxx-xxx";
+    expect(input.value).toBe("");
+    input.value = "5551234";
+    input.dispatchEvent(new Event("input"));
+    expect(input.value).toBe("555-123");
+    // no reflect-value: the attribute is never written
+    expect(el.hasAttribute("current-value")).toBe(false);
+  });
+
+  it("tolerates a missing <input>", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input reflect-value text-format="xx-xx" invalid-message="nope" auto-label>
+        <label>Orphan</label>
+      </super-input>`,
+    );
+    expect(el._inputElement).toBe(null);
+    expect(el.currentValue).toBe(null);
+    expect(el.querySelector("label")!.htmlFor).toBe("");
+    // prop toggles must not throw without an input
+    el.reflectValue = false;
+    el.textFormat = null;
+    el.invalidMessage = null;
+    expect(el.currentValue).toBe(null);
+    el.reflectValue = true;
+    el.textFormat = "xxx";
+    el.invalidMessage = "still nope";
+    expect(el.currentValue).toBe(null);
+    expect(el.hasAttribute("current-value")).toBe(false);
+  });
+
+  it("[auto-label] leaves the label alone when auto-label is unset", async () => {
+    const el = fixture<HTMLSuperInputElement>(
+      `<super-input><input /><label for="keep-me"></label></super-input>`,
+    );
+    expect(el.querySelector("input")!.id).toBe("");
+    expect(el.querySelector("label")!.htmlFor).toBe("keep-me");
+  });
+});

package/support/tests/with-format.view.test.ts

@@ -0,0 +1,20 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("with-format view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("formats the seeded phone number", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "with-format"));
+    const input = root.querySelector("input")!;
+    expect(input.value).toMatch(/\(\d{3}\)/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}