@jxsuite/ui 0.0.0 → 0.1.0

package/components/jx-action-button.json

@@ -21,11 +21,21 @@
     "stacked",
     "haspopup",
     "expanded",
-    "badge"
+    "badge",
+    "loading",
+    "labelledby",
+    "describedby",
+    "checked"
   ],
   "$elements": [
     {
       "$ref": "./jx-icon.json"
+    },
+    {
+      "$ref": "./jx-spinner.json"
+    },
+    {
+      "$ref": "./jx-tooltip.json"
     }
   ],
   "state": {
@@ -33,13 +43,13 @@
       "type": "string",
       "default": "",
       "attribute": "label",
-      "description": "The accessible name, required: an action button is icon-first, so its name is not on screen. Also its tooltip."
+      "description": "The accessible name, required: an action button is icon-first, so its name is not on screen. It is NOT also the tooltip — see hint."
     },
     "hint": {
       "type": "string",
       "default": "",
       "attribute": "hint",
-      "description": "The tooltip when it is more than the name: the name with its chord, or with why the button is off. Empty means the label is the tooltip."
+      "description": "The tooltip, and the whole of it. While the button is ENABLED it is drawn as a jx-tooltip child of this element — shown on keyboard focus at once and on hover after the tip's delay, hoverable and dismissible with Escape (SC 1.4.13) — and the control names it in aria-describedby, so it is a description beside the name and never the name itself. While the button is DISABLED it is the control's native title instead, because a disabled control receives no focus and no pointer event and could never open a tip, while the platform still shows a title on hover: that is the one affordance a button whose hint says why it cannot act still has. Never both at once. It used to fall back to label, so EVERY button got a tooltip whether or not its name was already on screen and a reader heard the name twice. Now each call site decides: pass hint on an icon-only button or one whose visible label ellipses, where a tooltip carrying the name is the standard affordance and hint equal to label is the right answer; leave it empty wherever the text is already fully visible."
     },
     "icon": {
       "type": "string",
@@ -69,7 +79,18 @@
       "type": "boolean",
       "default": false,
       "attribute": "selected",
-      "description": "The pressed state of a toggling button. A host may hold it: the property wins over the flip."
+      "description": "The pressed or chosen state, and the ONLY thing the selected drawing follows — whoever wrote it. A host that owns the selection sets it with toggles off and the button draws selected without flipping itself or emitting change; with toggles on the button also flips it on activation. What selected does NOT do is announce anything by itself: aria-pressed comes from toggles and aria-checked from checked, so a host-owned segment that must be announced is a checked radio (and setting checked also draws it selected, so the two never disagree)."
+    },
+    "checked": {
+      "type": "string",
+      "default": "",
+      "attribute": "checked",
+      "description": "Empty for a plain button; true or false for one segment of a radio group, which then carries role=radio and aria-checked on its control, is drawn selected while it is true, and puts role=none on the HOST so the radio is the radiogroup's own child rather than a grandchild behind a generic. It is the ALTERNATIVE to toggles, not a companion: a button that is one of several mutually exclusive choices is a radio, a button that is independently on or off is a toggle. Setting both is not a second opinion but a refusal — checked wins, so no aria-pressed is written on a radio (it is not a state of that role) and the button does not flip itself either."
+    },
+    "tabindex": {
+      "type": "string",
+      "default": "",
+      "description": "Forwarded to the inner control as its tabindex, which is what makes a roving caret possible: the focusable node is the button inside, not the host, so a group moving focus writes this rather than reaching into a child's internals. It is a PROPERTY ONLY (el.tabindex = \"0\") and deliberately not an observed attribute: written as an attribute it would land on the host as well, and a host carrying tabindex is itself focusable, so the one control would become two tab stops. Write tabindex on the host and you get the platform's meaning — the host is the tab stop and nothing reaches the control."
     },
     "quiet": {
       "type": "boolean",
@@ -93,7 +114,13 @@
       "type": "boolean",
       "default": false,
       "attribute": "disabled",
-      "description": "Cannot act. Disabled, never absent."
+      "description": "Cannot act. Disabled, never absent, and the hint moves from the tip to the control's title while it is: a disabled control cannot open a tip, and the reason it cannot act is exactly what the reader hovers to find out."
+    },
+    "loading": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "loading",
+      "description": "Working on the last activation: the click is swallowed, the glyph gives way to a spinner, and aria-busy says so. An action button draws its icon from a name and has no icon slot, so this is the only way a host can put a spinner where the glyph was."
     },
     "stacked": {
       "type": "boolean",
@@ -101,6 +128,18 @@
       "attribute": "stacked",
       "description": "Icon above the label, the label visible and small: the shape of a rail button. The label is then on screen, so it is the accessible name by itself."
     },
+    "labelledby": {
+      "type": "string",
+      "default": "",
+      "attribute": "labelledby",
+      "description": "Forwarded to the inner control as aria-labelledby: the id of the visible text that names this button, when something on screen already does."
+    },
+    "describedby": {
+      "type": "string",
+      "default": "",
+      "attribute": "describedby",
+      "description": "Forwarded to the inner control as aria-describedby: the id of a description beside the name, after the hint's own tip when there is one. A hint needs none of this — the element names its own tip — so it is for a description the host draws elsewhere."
+    },
     "haspopup": {
       "type": "string",
       "default": "",
@@ -143,6 +182,47 @@
       "attribute": "commandfor",
       "description": "The element the command is sent to; forwarded to the inner control."
     },
+    "uid": {
+      "type": "string",
+      "default": "",
+      "description": "This button's own id stem, minted on mount by the tooltip sidecar. The control's id, the tip's id and the three attributes that wire one to the other are all built from it, so a consumer writes none of them and two hinted buttons in one toolbar cannot collide. Empty until the mount microtask, which is why every binding that reads it guards on it."
+    },
+    "hasTip": {
+      "$expression": {
+        "operator": "&&",
+        "target": {
+          "operator": "!",
+          "target": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/hint"
+            }
+          }
+        },
+        "value": {
+          "operator": "&&",
+          "target": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/disabled"
+            }
+          },
+          "value": {
+            "operator": "!==",
+            "target": {
+              "$ref": "#/state/uid"
+            },
+            "value": ""
+          }
+        }
+      }
+    },
+    "onMount": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/tooltip.ts",
+      "$export": "mintHintId",
+      "description": "Mints the id stem the hint's tooltip is wired by. A document cannot: the closed operator set has no counter and no identity."
+    },
     "noIcon": {
       "$expression": {
         "operator": "!",
@@ -151,6 +231,59 @@
         }
       }
     },
+    "notLoading": {
+      "$expression": {
+        "operator": "!",
+        "target": {
+          "$ref": "#/state/loading"
+        }
+      }
+    },
+    "iconHidden": {
+      "$expression": {
+        "operator": "||",
+        "target": {
+          "$ref": "#/state/noIcon"
+        },
+        "value": {
+          "$ref": "#/state/loading"
+        }
+      }
+    },
+    "notRadio": {
+      "$expression": {
+        "operator": "!",
+        "target": {
+          "$ref": "#/state/checked"
+        }
+      }
+    },
+    "canToggle": {
+      "$expression": {
+        "operator": "&&",
+        "target": {
+          "$ref": "#/state/toggles"
+        },
+        "value": {
+          "operator": "&&",
+          "target": {
+            "$ref": "#/state/notRadio"
+          },
+          "value": {
+            "operator": "&&",
+            "target": {
+              "operator": "!",
+              "target": {
+                "$ref": "#/state/disabled"
+              }
+            },
+            "value": {
+              "$ref": "#/state/notLoading"
+            }
+          }
+        }
+      }
+    },
     "hasBadge": {
       "$expression": {
         "operator": "!==",
@@ -160,21 +293,44 @@
         "value": ""
       }
     },
+    "onSwallow": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "if": {
+            "$ref": "#/state/loading"
+          },
+          "then": [
+            {
+              "stopPropagation": true
+            },
+            {
+              "preventDefault": true
+            }
+          ]
+        }
+      ],
+      "description": "The swallow, on the INNER CONTROL rather than the host: stopPropagation halts an event at the node it is called on and every node after it, not the other listeners on that same node — so a swallow on the host cancels the default and then runs the host's own click listeners anyway, which is the one path a consumer actually uses. Called one node earlier, the click never reaches the host at all."
+    },
     "onClick": {
       "$prototype": "Function",
       "body": [
         {
           "if": {
-            "operator": "&&",
-            "target": {
-              "$ref": "#/state/toggles"
+            "$ref": "#/state/loading"
+          },
+          "then": [
+            {
+              "stopPropagation": true
             },
-            "value": {
-              "operator": "!",
-              "target": {
-                "$ref": "#/state/disabled"
-              }
+            {
+              "preventDefault": true
             }
+          ]
+        },
+        {
+          "if": {
+            "$ref": "#/state/canToggle"
           },
           "then": [
             {
@@ -205,17 +361,18 @@
           "description": "A toggling button flipped; detail is the new selected state."
         }
       ],
-      "description": "A toggling button flips selected and says so with change. A plain one leaves the click to the host, which listens for it on the element."
+      "description": "A toggling button flips selected and says so with change. A plain one leaves the click to the host, which listens for it on the element. The loading branch is the second half of the swallow: a click dispatched at the HOST never passes the inner control, so this is the only guard that sees it."
     }
   },
   "onclick": {
     "$ref": "#/state/onClick"
   },
   "attributes": {
+    "role": "${state.checked ? 'none' : null}",
     "data-size": "${state.size}",
     "data-quiet": "${state.quiet ? '' : null}",
     "data-emphasized": "${state.emphasized ? '' : null}",
-    "data-selected": "${state.toggles && state.selected ? '' : null}",
+    "data-selected": "${state.selected || state.checked === 'true' ? '' : null}",
     "data-stacked": "${state.stacked ? '' : null}"
   },
   "style": {
@@ -257,6 +414,9 @@
         "opacity": "0.5",
         "cursor": "default"
       },
+      "&[aria-busy=\"true\"]": {
+        "cursor": "progress"
+      },
       "position": "relative"
     },
     "&[data-quiet] > [part=\"control\"]": {
@@ -277,11 +437,15 @@
       "lineHeight": "var(--jx-leading-xs)"
     },
     "&[data-stacked] > [part=\"control\"] > [part=\"label\"]": {
+      "display": "block",
       "maxWidth": "100%",
       "overflow": "hidden",
       "textOverflow": "ellipsis",
       "whiteSpace": "nowrap"
     },
+    "&[data-stacked] > [part=\"control\"] > [part=\"label\"]:empty, &[data-stacked] > [part=\"control\"] > [part=\"label\"]:has([part=\"label-slot\"]:empty)": {
+      "display": "none"
+    },
     "&[data-selected] > [part=\"control\"]": {
       "background": "var(--jx-accent-15)",
       "color": "var(--jx-fg)"
@@ -307,44 +471,74 @@
     "& [part=\"icon\"][hidden]": {
       "display": "none"
     },
-    "& [part=\"label\"]:empty": {
-      "display": "none"
+    "& [part=\"label\"]": {
+      "display": "contents"
+    },
+    "& [part=\"label-slot\"]": {
+      "display": "contents"
+    },
+    "& [part=\"badge-slot\"]": {
+      "display": "contents"
+    },
+    "& > [part=\"tooltip\"]": {
+      "display": "contents"
     },
     "& [part=\"badge\"]": {
-      "position": "absolute",
-      "top": "2px",
-      "right": "2px",
+      "display": "inline-flex",
+      "alignItems": "center",
+      "justifyContent": "center",
       "minWidth": "16px",
-      "height": "16px",
-      "padding": "0 4px",
-      "boxSizing": "border-box",
-      "borderRadius": "8px",
+      "padding": "0 var(--jx-space-2)",
+      "borderRadius": "999px",
       "background": "var(--jx-accent-solid)",
       "color": "var(--jx-accent-fg)",
       "fontSize": "var(--jx-text-xs)",
       "lineHeight": "16px",
-      "textAlign": "center",
+      "fontVariantNumeric": "tabular-nums",
+      "position": "absolute",
+      "top": "2px",
+      "right": "2px",
+      "boxSizing": "border-box",
       "pointerEvents": "none"
+    },
+    "& [part=\"spinner\"]": {
+      "display": "inline-flex",
+      "color": "inherit"
+    },
+    "& [part=\"spinner\"][hidden]": {
+      "display": "none"
     }
   },
   "children": [
     {
       "tagName": "button",
+      "onclick": {
+        "$ref": "#/state/onSwallow"
+      },
       "attributes": {
         "part": "control",
         "type": "button",
         "disabled": {
           "$ref": "#/state/disabled"
         },
+        "id": "${state.uid || null}",
         "aria-label": "${state.label || null}",
-        "title": "${state.hint || state.label || null}",
-        "aria-pressed": "${state.toggles ? (state.selected ? 'true' : 'false') : null}",
+        "title": "${state.disabled && state.hint ? state.hint : null}",
+        "interestfor": "${state.hasTip ? state.uid + '-tip' : null}",
+        "role": "${state.checked ? 'radio' : null}",
+        "aria-checked": "${state.checked || null}",
+        "aria-pressed": "${state.toggles && !state.checked ? (state.selected ? 'true' : 'false') : null}",
+        "tabindex": "${state.tabindex || null}",
         "popovertarget": "${state.popovertarget || null}",
         "popovertargetaction": "${state.popovertargetaction || null}",
         "command": "${state.command || null}",
         "commandfor": "${state.commandfor || null}",
         "aria-haspopup": "${state.haspopup || null}",
-        "aria-expanded": "${state.haspopup ? (state.expanded ? 'true' : 'false') : null}"
+        "aria-expanded": "${state.haspopup ? (state.expanded ? 'true' : 'false') : null}",
+        "aria-labelledby": "${state.labelledby || null}",
+        "aria-describedby": "${[state.hasTip ? state.uid + '-tip' : null, state.describedby || null].filter(Boolean).join(' ') || null}",
+        "aria-busy": "${state.loading ? 'true' : null}",
+        "aria-disabled": "${state.loading ? 'true' : null}"
       },
       "children": [
         {
@@ -353,7 +547,7 @@
             "part": "icon"
           },
           "hidden": {
-            "$ref": "#/state/noIcon"
+            "$ref": "#/state/iconHidden"
           },
           "children": [
             {
@@ -375,6 +569,15 @@
             }
           ]
         },
+        {
+          "tagName": "jx-spinner",
+          "attributes": {
+            "part": "spinner"
+          },
+          "hidden": {
+            "$ref": "#/state/notLoading"
+          }
+        },
         {
           "tagName": "span",
           "attributes": {
@@ -382,10 +585,7 @@
           },
           "children": [
             {
-              "tagName": "slot",
-              "attributes": {
-                "part": "label-slot"
-              }
+              "tagName": "slot"
             }
           ]
         },
@@ -409,6 +609,34 @@
           }
         }
       ]
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "tooltip"
+      },
+      "$switch": {
+        "$ref": "#/state/hasTip"
+      },
+      "cases": {
+        "true": {
+          "tagName": "jx-tooltip",
+          "attributes": {
+            "part": "tip",
+            "id": "${state.uid}-tip",
+            "for": "${state.uid}"
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "attributes": {
+                "part": "tip-text"
+              },
+              "textContent": "${state.hint}"
+            }
+          ]
+        }
+      }
     }
   ]
 }

package/components/jx-action-group.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "JxActionGroup",
+  "tagName": "jx-action-group",
+  "observedAttributes": ["selects", "compact", "label", "orientation"],
+  "state": {
+    "selects": {
+      "type": "string",
+      "default": "none",
+      "attribute": "selects",
+      "description": "Which ARIA pattern the row is: none is a toolbar of unrelated tools, single is a radiogroup of mutually exclusive choices, multiple is a plain group of independent toggles. It chooses the pattern and the keyboard; it does NOT own the selection. Every shipped call site keeps the selected value in the host, so in single the group clicks the child an arrow lands on and lets the host decide what that means. In single the host must also give every child a checked prop of \"true\" or \"false\": a radiogroup's required owned element is a radio, and jx-action-button becomes one only when checked is non-empty — a group of bare buttons is announced as a radiogroup with no checked member at all."
+    },
+    "compact": {
+      "type": "boolean",
+      "default": true,
+      "attribute": "compact",
+      "description": "Draw the children joined into one segmented control, sharing their inner borders and rounding only the outer corners. Off leaves them as separate buttons with a gap. This is the one thing no button can do about itself: joining N of them needs selectors about a child's position among its siblings. The seam is a DIRECT-CHILD rule: it reaches the buttons the group itself owns — a slot leaves no node, so a distributed child is one — and so a nested group keeps its own compact, and a button a surface wraps in a div of its own is roved but not joined."
+    },
+    "label": {
+      "type": "string",
+      "default": "",
+      "attribute": "label",
+      "description": "The accessible name of the group, and it is not optional in practice: a toolbar, a radiogroup and a group are all containers a reader is told they have entered, and an unnamed one is announced by its role alone. Nothing lints its absence — a bound role switches the naming rules off — so the element's own test pins it instead."
+    },
+    "orientation": {
+      "type": "string",
+      "default": "horizontal",
+      "attribute": "orientation",
+      "description": "horizontal or vertical. It chooses which arrow pair moves the caret, and it turns both the layout and the segmented seam through 90 degrees off data-orientation. It also sets aria-orientation, but only where ARIA permits one: role=group — what selects=\"multiple\" resolves to — supports neither aria-orientation nor its inheritance, and Chrome drops the attribute there, so writing it anyway would be an aria-allowed-attr violation in a consumer's own axe run."
+    },
+    "onKeydown": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/action-group.ts",
+      "$export": "onGroupKeydown",
+      "description": "The group keyboard contract: the arrow along its own axis moves the roving caret between enabled children with wrap, Home and End go to the ends, and in selects=single the child that takes the caret is clicked."
+    },
+    "onReady": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/action-group.ts",
+      "$export": "onGroupReady",
+      "description": "Collapses the group to one tab stop once it has rendered, and keeps it collapsed to one as children come and go. It listens for the element's own jx-ready because onMount is handed the reactive scope alone, and placing a caret needs the host."
+    },
+    "onMount": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "dispatchEvent": "jx-ready",
+          "bubbles": true
+        }
+      ],
+      "emits": [
+        {
+          "name": "jx-ready",
+          "description": "The group has rendered and distributed its children, so its caret can be placed."
+        }
+      ],
+      "description": "Announces that the element has rendered. The group's own onReady listens for it, and a host may too."
+    }
+  },
+  "attributes": {
+    "role": "${state.selects === 'single' ? 'radiogroup' : (state.selects === 'multiple' ? 'group' : 'toolbar')}",
+    "aria-label": "${state.label || null}",
+    "aria-orientation": "${state.selects === 'multiple' ? null : state.orientation}",
+    "data-orientation": "${state.orientation}",
+    "data-compact": "${state.compact ? '' : null}"
+  },
+  "onkeydown": {
+    "$ref": "#/state/onKeydown"
+  },
+  "onjx-ready": {
+    "$ref": "#/state/onReady"
+  },
+  "style": {
+    "display": "inline-flex",
+    "&[hidden]": {
+      "display": "none"
+    },
+    "verticalAlign": "middle",
+    "alignItems": "center",
+    "gap": "var(--jx-space-1)",
+    "&[data-orientation=\"vertical\"]": {
+      "flexDirection": "column",
+      "alignItems": "stretch"
+    },
+    "&[data-compact]": {
+      "gap": "0"
+    },
+    "&[data-compact] > jx-action-button > [part=\"control\"]": {
+      "borderRadius": "0"
+    },
+    "&[data-compact] > jx-action-button + jx-action-button > [part=\"control\"]": {
+      "marginInlineStart": "-1px"
+    },
+    "&[data-compact] > jx-action-button:first-of-type > [part=\"control\"]": {
+      "borderStartStartRadius": "var(--jx-radius-sm)",
+      "borderEndStartRadius": "var(--jx-radius-sm)"
+    },
+    "&[data-compact] > jx-action-button:last-of-type > [part=\"control\"]": {
+      "borderStartEndRadius": "var(--jx-radius-sm)",
+      "borderEndEndRadius": "var(--jx-radius-sm)"
+    },
+    "&[data-compact][data-orientation=\"vertical\"] > jx-action-button + jx-action-button > [part=\"control\"]": {
+      "marginInlineStart": "0",
+      "marginBlockStart": "-1px"
+    },
+    "&[data-compact][data-orientation=\"vertical\"] > jx-action-button:first-of-type > [part=\"control\"]": {
+      "borderEndStartRadius": "0",
+      "borderStartEndRadius": "var(--jx-radius-sm)"
+    },
+    "&[data-compact][data-orientation=\"vertical\"] > jx-action-button:last-of-type > [part=\"control\"]": {
+      "borderStartEndRadius": "0",
+      "borderEndStartRadius": "var(--jx-radius-sm)"
+    },
+    "&[data-compact] > jx-action-button > [part=\"control\"]:focus-visible": {
+      "zIndex": "1"
+    }
+  },
+  "children": [
+    {
+      "tagName": "slot"
+    }
+  ]
+}