vintage-frames 0.12.3 → 0.12.5

package/README.md

@@ -2,7 +2,7 @@
 
 A web component kit that rebuilds the classic Apple System 7 interface elements.
 
-View the [Examples Page](https://aportilla.github.io/vintage-frames/) to see every element live, with its full API.
+View the [Examples Page](https://vintage-frames.portill.io/) to see every element live, with its full API.
 
 ```sh
 npm install vintage-frames

package/custom-elements.json

@@ -233,7 +233,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.",
+          "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nWith an `href` it is a link instead: the same art over an `<a href>` in\nplace of the `<button>`, so it is followed the way any link is — a click,\nEnter, a modified or middle click into a new tab, the context menu's link\nitems — and `target`, `rel` and `download` mean what they mean on `<a>`.\nA link is not a form button: `type`, `name`, `value` and the `form*`\noverrides do nothing while `href` is set.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.",
           "name": "VfButton",
           "cssProperties": [
             {
@@ -244,7 +244,7 @@
           ],
           "cssParts": [
             {
-              "description": "The inner native `<button>` element.",
+              "description": "The inner native `<button>` element — an `<a>` with `href`.",
               "name": "button"
             }
           ],
@@ -362,6 +362,46 @@
               "attribute": "formtarget",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "href",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "A URL, and the button becomes a link to it: an `<a href>` renders in\nplace of the inner `<button>` under the same art, and the platform\nfollows it — a click, Enter, a modified or middle click, the context\nmenu's link items. An empty value is no link.\n\nA link is not a form button. While `href` is set, type,\nname, value and the `form*` overrides do nothing, and the\nbutton is never a form's default button for a field's Enter. Inside a\n`vf-dialog`, `variant=\"default\"` still makes it the dialog's default\nbutton, so Return follows the link.\n\nDisabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`\nkeeps rendering but loses its `href`, taking `role=\"link\"` and\n`aria-disabled=\"true\"` instead: out of the tab order, and inert to the\npointer and to click, as a disabled `<button>` is.",
+              "attribute": "href",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "target",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: where the link opens, as `<a target>`.",
+              "attribute": "target",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "rel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: the link's relationship to this page, as `<a rel>`.",
+              "attribute": "rel",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "download",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: download the resource instead of navigating to it, as\n`<a download>` — the value, when there is one, names the saved file.",
+              "attribute": "download",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "scale",
@@ -380,11 +420,22 @@
             },
             {
               "kind": "field",
-              "name": "buttonEl",
+              "name": "control",
               "type": {
-                "text": "HTMLButtonElement | null"
+                "text": "HTMLElement | null"
               },
-              "privacy": "private"
+              "privacy": "private",
+              "description": "The inner `<button>` — or `<a>`, under href."
+            },
+            {
+              "kind": "field",
+              "name": "isLink",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether href makes this a link.",
+              "readonly": true
             },
             {
               "kind": "field",
@@ -414,7 +465,34 @@
                   "text": "void"
                 }
               },
-              "description": "Forwards a synthetic activation to the real `<button>` in the shadow\nroot. A `click()` on the host dispatches at the host and propagates *up*,\nnever down to the inner button's listener — so the native control, the\nactual activation surface, is handed the call instead. Its click then\nbubbles back out composed, exactly as a pointer's does. This is what the\nfields' implicit submission (Enter) activates as the form's default\nbutton; a disabled button swallows it natively, as it should.\n\nBefore the first render there is no inner button to forward to. A native\n`click()` always fires, so rather than doing nothing this falls back to\ndispatching at the host — no activation behavior to run yet, but the\nevent a caller asked for."
+              "description": "Forwards a synthetic activation to the real `<button>` in the shadow\nroot. A `click()` on the host dispatches at the host and propagates *up*,\nnever down to the inner button's listener — so the native control, the\nactual activation surface, is handed the call instead. Its click then\nbubbles back out composed, exactly as a pointer's does. This is what the\nfields' implicit submission (Enter) activates as the form's default\nbutton; a disabled button swallows it natively, as it should. Under\nhref the `<a>` is handed the call and follows itself — which is\nhow a dialog's Return reaches a default button that is a link. A\ndisabled link has no native state to swallow it, so it is withheld here.\n\nBefore the first render there is no inner button to forward to. A native\n`click()` always fires, so rather than doing nothing this falls back to\ndispatching at the host — no activation behavior to run yet, but the\nevent a caller asked for."
+            },
+            {
+              "kind": "method",
+              "name": "renderButton",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "label",
+                  "type": {
+                    "text": "TemplateResult"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "renderLink",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "label",
+                  "type": {
+                    "text": "TemplateResult"
+                  }
+                }
+              ],
+              "description": "The link. No click listener: following it is the platform's activation\nbehavior. A disabled one is an `<a>` without an `href`, which has no\nlink role unless it is given one."
             },
             {
               "kind": "field",
@@ -1110,6 +1188,38 @@
               "description": "See formAction. Overrides the form's `target`.",
               "fieldName": "formTarget"
             },
+            {
+              "name": "href",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "A URL, and the button becomes a link to it: an `<a href>` renders in\nplace of the inner `<button>` under the same art, and the platform\nfollows it — a click, Enter, a modified or middle click, the context\nmenu's link items. An empty value is no link.\n\nA link is not a form button. While `href` is set, type,\nname, value and the `form*` overrides do nothing, and the\nbutton is never a form's default button for a field's Enter. Inside a\n`vf-dialog`, `variant=\"default\"` still makes it the dialog's default\nbutton, so Return follows the link.\n\nDisabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`\nkeeps rendering but loses its `href`, taking `role=\"link\"` and\n`aria-disabled=\"true\"` instead: out of the tab order, and inert to the\npointer and to click, as a disabled `<button>` is.",
+              "fieldName": "href"
+            },
+            {
+              "name": "target",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: where the link opens, as `<a target>`.",
+              "fieldName": "target"
+            },
+            {
+              "name": "rel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: the link's relationship to this page, as `<a rel>`.",
+              "fieldName": "rel"
+            },
+            {
+              "name": "download",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "With href: download the resource instead of navigating to it, as\n`<a download>` — the value, when there is one, names the saved file.",
+              "fieldName": "download"
+            },
             {
               "name": "top",
               "type": {

package/dist/components/vf-button.d.ts

@@ -1,3 +1,4 @@
+import { type TemplateResult } from 'lit';
 import { VfShadowRoleControl } from '../form-control.js';
 declare const VfButton_base: (new (...args: any[]) => import("../position.js").VfPositionedInterface) & typeof VfShadowRoleControl;
 /**
@@ -30,6 +31,13 @@ declare const VfButton_base: (new (...args: any[]) => import("../position.js").V
  * `event.submitter.closest('vf-button')`, and its identity from
  * `submitter.name`/`.value` rather than by comparing element references.
  *
+ * With an `href` it is a link instead: the same art over an `<a href>` in
+ * place of the `<button>`, so it is followed the way any link is — a click,
+ * Enter, a modified or middle click into a new tab, the context menu's link
+ * items — and `target`, `rel` and `download` mean what they mean on `<a>`.
+ * A link is not a form button: `type`, `name`, `value` and the `form*`
+ * overrides do nothing while `href` is set.
+ *
  * A host-level `aria-label` / `aria-labelledby` names the inner button, and
  * `description` (or a host-level `aria-describedby`) describes it — the same
  * bridge the fields use, since the role lives on a shadow-internal node the
@@ -37,7 +45,8 @@ declare const VfButton_base: (new (...args: any[]) => import("../position.js").V
  * name it: a `<button>` is not a labelable element.
  *
  * @slot - The button label.
- * @csspart button - The inner native `<button>` element.
+ * @csspart button - The inner native `<button>` element — an `<a>` with
+ *   `href`.
  * @cssprop [--vf-button-height=20px] - `vf-button` face (the default ring's
  *   inner box is 80×20)
  */
@@ -91,11 +100,41 @@ export declare class VfButton extends VfButton_base {
     formNoValidate: boolean;
     /** See {@link formAction}. Overrides the form's `target`. */
     formTarget: string;
+    /**
+     * A URL, and the button becomes a link to it: an `<a href>` renders in
+     * place of the inner `<button>` under the same art, and the platform
+     * follows it — a click, Enter, a modified or middle click, the context
+     * menu's link items. An empty value is no link.
+     *
+     * A link is not a form button. While `href` is set, {@link type},
+     * {@link name}, {@link value} and the `form*` overrides do nothing, and the
+     * button is never a form's default button for a field's Enter. Inside a
+     * `vf-dialog`, `variant="default"` still makes it the dialog's default
+     * button, so Return follows the link.
+     *
+     * Disabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`
+     * keeps rendering but loses its `href`, taking `role="link"` and
+     * `aria-disabled="true"` instead: out of the tab order, and inert to the
+     * pointer and to {@link click}, as a disabled `<button>` is.
+     */
+    href?: string;
+    /** With {@link href}: where the link opens, as `<a target>`. */
+    target?: string;
+    /** With {@link href}: the link's relationship to this page, as `<a rel>`. */
+    rel?: string;
+    /**
+     * With {@link href}: download the resource instead of navigating to it, as
+     * `<a download>` — the value, when there is one, names the saved file.
+     */
+    download?: string;
     /** Default-on display scaling (true 72dpi size); see src/scale.ts. */
     private readonly scale;
     /** Device-pixel grid snapping; see src/grid-snap.ts. */
     private readonly gridSnap;
-    private buttonEl;
+    /** The inner `<button>` — or `<a>`, under {@link href}. */
+    private control;
+    /** Whether {@link href} makes this a link. */
+    private get isLink();
     /**
      * {@link type}, resolved the way HTML resolves an enumerated attribute:
      * ASCII case-insensitively, with anything unrecognized falling to the
@@ -115,7 +154,10 @@ export declare class VfButton extends VfButton_base {
      * actual activation surface, is handed the call instead. Its click then
      * bubbles back out composed, exactly as a pointer's does. This is what the
      * fields' implicit submission (Enter) activates as the form's default
-     * button; a disabled button swallows it natively, as it should.
+     * button; a disabled button swallows it natively, as it should. Under
+     * {@link href} the `<a>` is handed the call and follows itself — which is
+     * how a dialog's Return reaches a default button that is a link. A
+     * disabled link has no native state to swallow it, so it is withheld here.
      *
      * Before the first render there is no inner button to forward to. A native
      * `click()` always fires, so rather than doing nothing this falls back to
@@ -123,7 +165,14 @@ export declare class VfButton extends VfButton_base {
      * event a caller asked for.
      */
     click(): void;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): TemplateResult<1>;
+    private renderButton;
+    /**
+     * The link. No click listener: following it is the platform's activation
+     * behavior. A disabled one is an `<a>` without an `href`, which has no
+     * link role unless it is given one.
+     */
+    private renderLink;
     /**
      * The click that may become a submission or a reset.
      *

package/dist/components/vf-button.js

@@ -90,8 +90,9 @@ var S = "vf-submitter", C = class extends i(h) {
          the stepped pseudo-element silhouettes below. Keeping the clip-paths
          off the button itself leaves the hit area a plain rectangle, and
          anything painted outside the silhouette (a ring a consumer restores
-         on ::part(button)) unclipped. */
-      button {
+         on ::part(button)) unclipped. .control is that button, or the <a>
+         that stands in for it under href: the art is the same either way. */
+      .control {
         position: relative;
         /* Own stacking context so the negative-z silhouettes stay inside the
            button: above everything behind it, below the label. */
@@ -118,31 +119,40 @@ var S = "vf-submitter", C = class extends i(h) {
         line-height: inherit;
         white-space: nowrap;
         cursor: inherit;
+        /* What the UA sheet gives a <button> and an <a> does not: no
+           underline, and none of the page's text styling inherited through
+           the host — so the link reads exactly as the button does. */
+        text-decoration: none;
+        text-transform: none;
+        text-indent: 0;
+        text-shadow: none;
+        letter-spacing: normal;
+        word-spacing: normal;
       }
       /* Frame: the outer silhouette in solid black. The face below covers all
          but the outline, leaving the reference's exact border pixels — the
          QuickDraw difference-of-silhouettes, not a stroked border. */
-      button::before,
-      button::after {
+      .control::before,
+      .control::after {
         content: '';
         position: absolute;
         inset: 0;
         z-index: -1;
       }
-      button::before {
+      .control::before {
         background: var(--vf-black, #000);
         clip-path: ${y(p(u))};
       }
       /* Face: white fill inset one pixel, with its own traced corner steps. */
-      button::after {
+      .control::after {
         background: var(--vf-white, #fff);
         clip-path: ${y(p(l))};
       }
       /* Pressed: instant white-on-black inversion. */
-      button:active:not(:disabled) {
+      .control:active:not(:disabled) {
         color: var(--vf-white, #fff);
       }
-      button:active:not(:disabled)::after {
+      .control:active:not(:disabled)::after {
         background: var(--vf-black, #000);
       }
       /* The label rides in its own box so the focus underline can span the
@@ -154,7 +164,7 @@ var S = "vf-submitter", C = class extends i(h) {
       }
       /* Keyboard focus is the dashed rule under the label, not a ring around
          the control — so the UA's own outline goes. */
-      button:focus-visible {
+      .control:focus-visible {
         outline: none;
       }
       /* …and off the host too. Blink doesn't currently propagate
@@ -166,39 +176,77 @@ var S = "vf-submitter", C = class extends i(h) {
       :host(:focus-visible) {
         outline: none;
       }
-      button:focus-visible .label::after {
+      .control:focus-visible .label::after {
         ${s}
       }
       /* Disabled: only the label dims to gray; the solid black border stays. */
-      button:disabled {
+      .control:disabled {
         color: var(--vf-disabled, #c0c0c0);
       }
+      /* A disabled link has no disabled state of its own, so it is spelled
+         out: the same dimmed label, and no press. Letting the pointer through
+         to the host keeps the face from inverting (:active never reaches the
+         link) and makes the press's target the host itself — a disabled form
+         control, which the platform dispatches no click to, as it dispatches
+         none to a disabled <button>. */
+      a.control[aria-disabled='true'] {
+        color: var(--vf-disabled, #c0c0c0);
+        pointer-events: none;
+      }
     `
 		];
 	}
+	get isLink() {
+		return !!this.href;
+	}
 	#e;
 	get resolvedType() {
 		let e = String(this.type ?? "").toLowerCase();
 		return e === "submit" ? "submit" : e === "reset" ? "reset" : "button";
 	}
 	click() {
-		let e = this.buttonEl;
-		e ? e.click() : super.click();
+		let e = this.control;
+		e ? this.isLink && this.isDisabled || e.click() : super.click();
 	}
 	render() {
+		let e = _`<span class="label"><slot></slot></span>`;
+		return _`
+      ${this.isLink ? this.renderLink(e) : this.renderButton(e)}
+      ${this.renderDescription()}
+    `;
+	}
+	renderButton(e) {
 		return _`
       <button
         part="button"
-        class="vf-snap"
+        class="control vf-snap"
         type="button"
         aria-label=${this.hostAriaLabel || v}
         aria-describedby=${this.describedBy}
         ?disabled=${this.isDisabled}
         @click=${this.handleClick}
       >
-        <span class="label"><slot></slot></span>
+        ${e}
       </button>
-      ${this.renderDescription()}
+    `;
+	}
+	renderLink(e) {
+		let t = this.isDisabled;
+		return _`
+      <a
+        part="button"
+        class="control vf-snap"
+        href=${t ? v : this.href}
+        target=${this.target || v}
+        rel=${this.rel || v}
+        download=${this.download ?? v}
+        role=${t ? "link" : v}
+        aria-disabled=${t ? "true" : v}
+        aria-label=${this.hostAriaLabel || v}
+        aria-describedby=${this.describedBy}
+      >
+        ${e}
+      </a>
     `;
 	}
 	activate() {
@@ -229,6 +277,6 @@ r([b({ reflect: !0 })], C.prototype, "variant", void 0), r([b({ reflect: !0 })],
 })], C.prototype, "formNoValidate", void 0), r([b({
 	attribute: "formtarget",
 	reflect: !0
-})], C.prototype, "formTarget", void 0), r([x("button")], C.prototype, "buttonEl", void 0), C = r([t("vf-button")], C);
+})], C.prototype, "formTarget", void 0), r([b({ reflect: !0 })], C.prototype, "href", void 0), r([b({ reflect: !0 })], C.prototype, "target", void 0), r([b({ reflect: !0 })], C.prototype, "rel", void 0), r([b({ reflect: !0 })], C.prototype, "download", void 0), r([x(".control")], C.prototype, "control", void 0), C = r([t("vf-button")], C);
 //#endregion
 export { C as VfButton };

package/dist/text-control.js

@@ -57,7 +57,7 @@ var l = class extends a {
 	requestImplicitSubmit() {
 		let e = this.internals.form;
 		if (!e) return !1;
-		let t = [...e.elements].find((e) => e instanceof HTMLButtonElement && e.type === "submit" || e instanceof HTMLInputElement && (e.type === "submit" || e.type === "image") || e.localName === "vf-button" && e.type?.toLowerCase() === "submit");
+		let t = [...e.elements].find((e) => e instanceof HTMLButtonElement && e.type === "submit" || e instanceof HTMLInputElement && (e.type === "submit" || e.type === "image") || e.localName === "vf-button" && !e.href && e.type?.toLowerCase() === "submit");
 		return t ? (t.matches(":disabled") || t.click(), !0) : (e.requestSubmit(), !0);
 	}
 	emitValue(t, n = { value: this.value }) {

package/docs/SPEC.md

@@ -250,8 +250,8 @@ System 7's fixed modal alert (double frame: 2px outer, 2px gap, 1px inner rule,
 ### Group B — buttons & toggles
 
 #### `vf-button` (`VfButton`, vf-button.ts)
-- **Attributes/props:** `variant?: 'default'` (the double-ring default button, e.g. "Install"), `disabled`, `type: 'button' | 'submit' | 'reset'` (reflected; default `'button'`), plus the submission overrides `formaction`, `formenctype`, `formmethod`, `formnovalidate` and `formtarget`, each honored on `type="submit"` only, as HTML honors them — they are handed to the native proxy below, so the behavior is the platform's rather than an emulation. (`formAction`'s *getter* returns the string as set, where the native IDL returns it resolved against the base URL; the submission resolves normally.) `type` is read the way HTML reads an enumerated attribute — ASCII case-insensitively, unrecognized values falling to the default — so `type="SUBMIT"` is a submit button. Two deliberate departures: HTML's missing-value default is `submit` and this one is `button`, because an element that silently submits the form it sits in is surprising; and the invalid-value default follows the missing one rather than HTML's `submit`, so a misspelling does nothing instead of submitting.
-- **Visual:** inner `<button>`: height `var(--vf-button-height, 20px)`, `min-width: 64px`, `padding: 0 14px`, bold black text, font per tokens. The button is 20px, not the fields' 22px: both 1x sheets measure the face at 80×20, and the default ring's *inner* box is exactly that, so the ring traces assume a 20px face. The label rides in its own `.label` span (the flex item, shrink-wrapped to the text) so the focus rule below can span the text rather than the padded face. The rounded rect is NOT `border-radius` (which antialiases): the button paints no box of its own; two pseudo-element layers carry stepped `clip-path` silhouettes traced from the reference sheet (`src/pixel-frame.ts`, traced from the 1x button reference sheet; `npm run verify:buttons` checks the compiled polygons render those profiles faithfully): `::before` fills `var(--vf-black)` clipped to the outer silhouette (corner insets `[3,1,1]`, then straight), `::after` fills `var(--vf-white)` clipped to the face (row 1 corner insets `[3,2]`, then 1px inside) — the 1px frame, corner steps included, is the QuickDraw-style difference of the two. Clip-paths stay off the `<button>` so the hit area stays a plain rectangle and anything painted outside the silhouette isn't swallowed. All coordinates are `calc(var(--vf-scale,1) * Npx)` system pixels, so edges land on whole device pixels and never antialias.
+- **Attributes/props:** `variant?: 'default'` (the double-ring default button, e.g. "Install"), `disabled`, `type: 'button' | 'submit' | 'reset'` (reflected; default `'button'`), plus the submission overrides `formaction`, `formenctype`, `formmethod`, `formnovalidate` and `formtarget`, each honored on `type="submit"` only, as HTML honors them — they are handed to the native proxy below, so the behavior is the platform's rather than an emulation. (`formAction`'s *getter* returns the string as set, where the native IDL returns it resolved against the base URL; the submission resolves normally.) `type` is read the way HTML reads an enumerated attribute — ASCII case-insensitively, unrecognized values falling to the default — so `type="SUBMIT"` is a submit button. Two deliberate departures: HTML's missing-value default is `submit` and this one is `button`, because an element that silently submits the form it sits in is surprising; and the invalid-value default follows the missing one rather than HTML's `submit`, so a misspelling does nothing instead of submitting. `href` (optional, reflected; unset by default so no `href=""` lands on every host) with `target`, `rel` and `download` makes it a link — see **Link** below.
+- **Visual:** inner `<button>` (an `<a>` under `href`, carrying the same `.control` rules): height `var(--vf-button-height, 20px)`, `min-width: 64px`, `padding: 0 14px`, bold black text, font per tokens. The button is 20px, not the fields' 22px: both 1x sheets measure the face at 80×20, and the default ring's *inner* box is exactly that, so the ring traces assume a 20px face. The label rides in its own `.label` span (the flex item, shrink-wrapped to the text) so the focus rule below can span the text rather than the padded face. The rounded rect is NOT `border-radius` (which antialiases): the button paints no box of its own; two pseudo-element layers carry stepped `clip-path` silhouettes traced from the reference sheet (`src/pixel-frame.ts`, traced from the 1x button reference sheet; `npm run verify:buttons` checks the compiled polygons render those profiles faithfully): `::before` fills `var(--vf-black)` clipped to the outer silhouette (corner insets `[3,1,1]`, then straight), `::after` fills `var(--vf-white)` clipped to the face (row 1 corner insets `[3,2]`, then 1px inside) — the 1px frame, corner steps included, is the QuickDraw-style difference of the two. Clip-paths stay off the `<button>` so the hit area stays a plain rectangle and anything painted outside the silhouette isn't swallowed. All coordinates are `calc(var(--vf-scale,1) * Npx)` system pixels, so edges land on whole device pixels and never antialias.
   - `:active` (pressed, not disabled): invert — the `::after` face flips to black, white text.
   - `:focus-visible`: **no ring** — the UA outline is off on both the inner button and the (`delegatesFocus`) host, replaced by `vfFocusUnderline` (§4) on the label: a 1px dashed rule 1px below the baseline, i.e. row 15 of the 20px face, one blank row under the glyph ink. It inverts with the label when pressed; the controls that cannot carry the mark on their own face keep the dotted ring. `npm run verify:focus` and the focused button in `npm run shot:verify` assert the rendered pixels.
   - `disabled`: only the label dims to `var(--vf-disabled, #c0c0c0)`; the 1px black border stays black. (For `variant="default"`, the fat outer ring dims to `var(--vf-disabled)` while the inner black border stays — the ring and the title dim together, the button's own frame does not. System 7 dimmed both with a 50% stipple; flat gray standing in for it is the kit's liberty, per §1.) The ring rule is keyed on **both** disabled routes — `[disabled]` and `:state(form-disabled)` — as separate rules: an ancestor `<fieldset disabled>` arrives through `formDisabledCallback` and sets no attribute, and keyed on the attribute alone it left a solid black ring around a greyed label.
@@ -260,10 +260,11 @@ System 7's fixed modal alert (double frame: 2px outer, 2px gap, 1px inner rule,
 - **Behavior:** form-associated. `type="submit"` submits by inserting a transient native proxy button carrying this button's `name`/`value` and any `form*` override, then clicking it — a form-associated custom element can't be a native submitter itself (`requestSubmit(vfButton)` throws a `TypeError`, "not a submit button"), and a bare `requestSubmit()` would submit with `event.submitter === null` and no name/value; `reset` → the same proxy path. Enter/Space work natively via the inner button, and the host overrides `click()` to forward to it (a click dispatched at the host propagates up, never down into the shadow tree; before the first render there is no inner button, so it falls back to dispatching at the host, since a native `click()` always fires) — which is also how the fields' Enter reaches this button as the form's default button (see `requestImplicitSubmit`, text-control.ts; its `vf-button` leg lowercases `type` for the enumerated rule above).
   - **When the action runs.** At the *end* of the click's propagation, not where the listener sits. HTML runs a button's activation behavior once the click has finished propagating, which is what lets `preventDefault()` on the button cancel the submission; this component's listener is on the inner `<button>`, first on that path rather than last, so acting there beat every listener a consumer could write and only a capture-phase cancel ever landed. It now defers by adding a listener to the window *during* dispatch (each node's listener list is read as that node is reached), so both phases cancel. `stopPropagation()` cancels nothing, per HTML — the event then never reaches the window and a task picks the action up instead; a task and never a microtask, which would interleave between the listeners of a trusted dispatch.
   - **Submitter identity.** `event.submitter` can never *be* the `vf-button` — the platform forbids it. It is the proxy, which is parented to the host and carries a `slot` name no shadow root offers: unslotted, so it is never rendered, measured or in the a11y tree, and off the flattened tree so its own click can't travel back up through the shadow `<button>` the click handler is bound to. Being a light-DOM descendant is what makes `event.submitter.closest('vf-button')` resolve to the component — the closest to identity the platform allows. Its own click is stopped at the proxy, so one press is one click at the form (`stopPropagation` leaves the activation behavior alone).
+- **Link:** a non-empty `href` renders an `<a part="button" href target rel download>` in place of the `<button>`, with no click listener of its own: following it — a click, Enter, a modified or middle click into a new tab, the context menu's link items — is the platform's. The art is identical at rest, focused and pressed; the `.control` rule adds the resets the UA sheet gives a `<button>` and not an `<a>` (`text-decoration`, `text-transform`, `text-indent`, `text-shadow`, `letter-spacing`, `word-spacing`), so the host's inherited text styling can't reach the label. A link is not a form button: `type`, `name`, `value` and the `form*` overrides do nothing, and `requestImplicitSubmit` skips a `vf-button` with an `href` whatever its `type`. The host stays form-associated (it cannot opt out per instance), so `disabled` and an ancestor `<fieldset disabled>` still disable it. Disabled, the `<a>` drops its `href` and takes `role="link"` + `aria-disabled="true"` — out of the tab order, label dimmed, ring dimmed — with `pointer-events: none`, which keeps the face from inverting and makes a press land on the disabled host, which gets no click; `click()` is withheld outright, since a disabled `<a>` has no native state to swallow it. `click()` on an enabled link forwards to the `<a>`, so a `vf-dialog`'s Return follows a `variant="default"` link, and the dialog's keydown leaves Enter on a focused link to the link (its composed path carries the `<a href>`).
 - **Name:** the slotted label, with a host-level `aria-label`/`aria-labelledby` bridged to the inner button when present (see §4's name bridge); a `<label for>` deliberately doesn't name it. `description` and a host-level `aria-describedby` reach it through the same shadow-internal span the fields use.
-- **Slots:** default (label). **Parts:** `button`.
+- **Slots:** default (label). **Parts:** `button` (the `<button>`, or the `<a>` under `href`).
 - **Events:** none custom (native `click` suffices).
-- **Verified by:** `npm run verify:button` (the form contract, the name bridge, the enumerated `type`, both disabled routes and the pinned metrics); `verify:buttons` (the clip-path traces), `verify:focus` (the dashed rule).
+- **Verified by:** `npm run verify:button` (the form contract, the name bridge, the enumerated `type`, both disabled routes, the pinned metrics, and the link: role, following by click/Enter/`click()`/modified click, the disabled link, form inertness, a dialog's default link and pixel parity with the button); `verify:buttons` (the clip-path traces), `verify:focus` (the dashed rule).
 
 #### `vf-button-group` (`VfButtonGroup`, vf-button-group.ts)
 - **Attributes/props:** `vertical` (stack in a column instead of a row), `natural` (let each button keep its own content width; off by default, so grouped buttons are uniform width — the classic System 7 dialog behavior).

package/editor/vscode.html-custom-data.json

@@ -41,7 +41,7 @@
     },
     {
       "name": "vf-button",
-      "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.\n---\n\n\n### **Slots:**\n - _default_ - The button label.\n\n### **CSS Properties:**\n - **--vf-button-height** - `vf-button` face (the default ring's inner box is 80×20) _(default: 20px)_\n\n### **CSS Parts:**\n - **button** - The inner native `<button>` element.",
+      "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nWith an `href` it is a link instead: the same art over an `<a href>` in\nplace of the `<button>`, so it is followed the way any link is — a click,\nEnter, a modified or middle click into a new tab, the context menu's link\nitems — and `target`, `rel` and `download` mean what they mean on `<a>`.\nA link is not a form button: `type`, `name`, `value` and the `form*`\noverrides do nothing while `href` is set.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.\n---\n\n\n### **Slots:**\n - _default_ - The button label.\n\n### **CSS Properties:**\n - **--vf-button-height** - `vf-button` face (the default ring's inner box is 80×20) _(default: 20px)_\n\n### **CSS Parts:**\n - **button** - The inner native `<button>` element — an `<a>` with `href`.",
       "attributes": [
         {
           "name": "variant",
@@ -92,6 +92,26 @@
           "description": "See formAction. Overrides the form's `target`.",
           "values": []
         },
+        {
+          "name": "href",
+          "description": "A URL, and the button becomes a link to it: an `<a href>` renders in\nplace of the inner `<button>` under the same art, and the platform\nfollows it — a click, Enter, a modified or middle click, the context\nmenu's link items. An empty value is no link.\n\nA link is not a form button. While `href` is set, type,\nname, value and the `form*` overrides do nothing, and the\nbutton is never a form's default button for a field's Enter. Inside a\n`vf-dialog`, `variant=\"default\"` still makes it the dialog's default\nbutton, so Return follows the link.\n\nDisabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`\nkeeps rendering but loses its `href`, taking `role=\"link\"` and\n`aria-disabled=\"true\"` instead: out of the tab order, and inert to the\npointer and to click, as a disabled `<button>` is.",
+          "values": []
+        },
+        {
+          "name": "target",
+          "description": "With href: where the link opens, as `<a target>`.",
+          "values": []
+        },
+        {
+          "name": "rel",
+          "description": "With href: the link's relationship to this page, as `<a rel>`.",
+          "values": []
+        },
+        {
+          "name": "download",
+          "description": "With href: download the resource instead of navigating to it, as\n`<a download>` — the value, when there is one, names the saved file.",
+          "values": []
+        },
         {
           "name": "top",
           "description": "Offset from the top of the positioning parent, in whole system px.\nSetting this (or `left`) absolutely positions the element within its\nparent; the coordinate left unset is 0. Remove both to return the\nelement to normal flow.",

package/editor/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "vintage-frames",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -85,7 +85,7 @@
         },
         {
           "name": "vf-button",
-          "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.\n---\n\n\n### **Slots:**\n - _default_ - The button label.\n\n### **CSS Properties:**\n - **--vf-button-height** - `vf-button` face (the default ring's inner box is 80×20) _(default: 20px)_\n\n### **CSS Parts:**\n - **button** - The inner native `<button>` element.",
+          "description": "The classic System 7 push button (\"OK\", \"Cancel\", \"Install\", …).\n\nA rounded-rectangle control with a 1px black border and white face that\ninverts to white-on-black while pressed. `variant=\"default\"` draws the\nclassic bold double ring around the button, marking it as the default\naction of a dialog.\n\nThe rounded corners are not `border-radius` arcs: frame, face, and ring are\nstepped `clip-path` silhouettes traced pixel-for-pixel from the kit's button\nreference sheet (see `src/pixel-frame.ts`), so every corner renders as the\nexact 1-bit staircase with no antialiasing.\n\nKeyboard focus — an affordance System 7 didn't have, drawn in its idiom\nanyway — is a 1px dashed rule under the label text (`vfFocusUnderline`)\nrather than a ring around the control.\n\nForm-associated: place it inside a `<form>` and `type=\"submit\"` submits the\nform (contributing its `name`/`value` and any `form*` override to the\nsubmission), `type=\"reset\"` resets it. Enter and Space activate it via the\ninner native button, and the submission runs at the end of the click's\npropagation, so `preventDefault()` on the button cancels it the way it\ncancels a native one.\n\nOne thing the platform will not allow: `event.submitter` cannot BE a\nform-associated custom element. It is the transient native proxy this\nbutton submits through — so read the submitting button as\n`event.submitter.closest('vf-button')`, and its identity from\n`submitter.name`/`.value` rather than by comparing element references.\n\nWith an `href` it is a link instead: the same art over an `<a href>` in\nplace of the `<button>`, so it is followed the way any link is — a click,\nEnter, a modified or middle click into a new tab, the context menu's link\nitems — and `target`, `rel` and `download` mean what they mean on `<a>`.\nA link is not a form button: `type`, `name`, `value` and the `form*`\noverrides do nothing while `href` is set.\n\nA host-level `aria-label` / `aria-labelledby` names the inner button, and\n`description` (or a host-level `aria-describedby`) describes it — the same\nbridge the fields use, since the role lives on a shadow-internal node the\nplatform can't deliver those to. A `<label for>` deliberately does not\nname it: a `<button>` is not a labelable element.\n---\n\n\n### **Slots:**\n - _default_ - The button label.\n\n### **CSS Properties:**\n - **--vf-button-height** - `vf-button` face (the default ring's inner box is 80×20) _(default: 20px)_\n\n### **CSS Parts:**\n - **button** - The inner native `<button>` element — an `<a>` with `href`.",
           "doc-url": "",
           "attributes": [
             {
@@ -136,6 +136,26 @@
               "description": "See formAction. Overrides the form's `target`.",
               "value": { "type": "string", "default": "''" }
             },
+            {
+              "name": "href",
+              "description": "A URL, and the button becomes a link to it: an `<a href>` renders in\nplace of the inner `<button>` under the same art, and the platform\nfollows it — a click, Enter, a modified or middle click, the context\nmenu's link items. An empty value is no link.\n\nA link is not a form button. While `href` is set, type,\nname, value and the `form*` overrides do nothing, and the\nbutton is never a form's default button for a field's Enter. Inside a\n`vf-dialog`, `variant=\"default\"` still makes it the dialog's default\nbutton, so Return follows the link.\n\nDisabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`\nkeeps rendering but loses its `href`, taking `role=\"link\"` and\n`aria-disabled=\"true\"` instead: out of the tab order, and inert to the\npointer and to click, as a disabled `<button>` is.",
+              "value": { "type": "string | undefined" }
+            },
+            {
+              "name": "target",
+              "description": "With href: where the link opens, as `<a target>`.",
+              "value": { "type": "string | undefined" }
+            },
+            {
+              "name": "rel",
+              "description": "With href: the link's relationship to this page, as `<a rel>`.",
+              "value": { "type": "string | undefined" }
+            },
+            {
+              "name": "download",
+              "description": "With href: download the resource instead of navigating to it, as\n`<a download>` — the value, when there is one, names the saved file.",
+              "value": { "type": "string | undefined" }
+            },
             {
               "name": "top",
               "description": "Offset from the top of the positioning parent, in whole system px.\nSetting this (or `left`) absolutely positions the element within its\nparent; the coordinate left unset is 0. Remove both to return the\nelement to normal flow.",
@@ -221,6 +241,26 @@
                 "description": "See formAction. Overrides the form's `target`.",
                 "type": "string"
               },
+              {
+                "name": "href",
+                "description": "A URL, and the button becomes a link to it: an `<a href>` renders in\nplace of the inner `<button>` under the same art, and the platform\nfollows it — a click, Enter, a modified or middle click, the context\nmenu's link items. An empty value is no link.\n\nA link is not a form button. While `href` is set, type,\nname, value and the `form*` overrides do nothing, and the\nbutton is never a form's default button for a field's Enter. Inside a\n`vf-dialog`, `variant=\"default\"` still makes it the dialog's default\nbutton, so Return follows the link.\n\nDisabled — by attribute or an ancestor `<fieldset disabled>` — the `<a>`\nkeeps rendering but loses its `href`, taking `role=\"link\"` and\n`aria-disabled=\"true\"` instead: out of the tab order, and inert to the\npointer and to click, as a disabled `<button>` is.",
+                "type": "string | undefined"
+              },
+              {
+                "name": "target",
+                "description": "With href: where the link opens, as `<a target>`.",
+                "type": "string | undefined"
+              },
+              {
+                "name": "rel",
+                "description": "With href: the link's relationship to this page, as `<a rel>`.",
+                "type": "string | undefined"
+              },
+              {
+                "name": "download",
+                "description": "With href: download the resource instead of navigating to it, as\n`<a download>` — the value, when there is one, names the saved file.",
+                "type": "string | undefined"
+              },
               {
                 "name": "top",
                 "description": "Offset from the top of the positioning parent, in whole system px.\nSetting this (or `left`) absolutely positions the element within its\nparent; the coordinate left unset is 0. Remove both to return the\nelement to normal flow.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintage-frames",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "Lit web components that emulate the look and feel of classic Mac OS System 7",
   "type": "module",
   "license": "MIT",