@jxsuite/ui 0.0.0 → 0.2.0

package/components/jx-option.json

@@ -0,0 +1,350 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "JxOption",
+  "tagName": "jx-option",
+  "observedAttributes": [
+    "value",
+    "label",
+    "description",
+    "selected",
+    "disabled",
+    "face",
+    "swatch",
+    "line",
+    "weight",
+    "slant",
+    "variant",
+    "transform",
+    "decoration"
+  ],
+  "state": {
+    "value": {
+      "type": "string",
+      "default": "",
+      "attribute": "value",
+      "description": "What the row stands for; the detail of the select event it dispatches. The empty string is a LEGAL value — a row meaning inherit or none — and never absence."
+    },
+    "label": {
+      "type": "string",
+      "default": "",
+      "attribute": "label",
+      "description": "The row's words, and its accessible name. There is deliberately no default slot, which is jx-tab's answer to the same question: option takes its name from its contents, so unnamed content in the row would join the name, and a row whose only content was a badge would be announced as the badge."
+    },
+    "description": {
+      "type": "string",
+      "default": "",
+      "attribute": "description",
+      "description": "A muted note drawn at the end of the row — a path, a category, a return type. It is TEXT and part of the row's name rather than a slot, exactly as jx-select's row description is, so a reader hears what they can see and the row keeps one accessible name. Absent draws no box."
+    },
+    "selected": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "selected",
+      "description": "Whether this is the row the caret is on. THE LISTBOX IS ITS SINGLE WRITER, exactly as jx-tabs is of every tab's: a consumer moves the highlight by writing the listbox's active id — the same id its owning field already points aria-activedescendant at — and never a row's flag. In this listbox the active descendant and the selection are ONE row, because selection follows the caret; a multi-select listbox, which would need them apart, is not offered."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "disabled",
+      "description": "A row that cannot be picked is disabled, never absent: it stays in the list, stays announced, and dispatches nothing when clicked."
+    },
+    "face": {
+      "type": "string",
+      "default": "",
+      "attribute": "face",
+      "description": "The font family the label draws in, for a row that IS its own preview. It reaches the label as a custom property set inline on that span, so seventy rows intern the rules two rows do (spec.md 9.1) — the same channel jx-select's rows carry, under the same token name."
+    },
+    "swatch": {
+      "type": "string",
+      "default": "",
+      "attribute": "swatch",
+      "description": "A colour chip drawn before the label, as any CSS colour. Absent by default, so a row that is not about a colour pays no box for one."
+    },
+    "line": {
+      "type": "string",
+      "default": "",
+      "attribute": "line",
+      "description": "A border-style keyword drawn as a short rule before the label: solid, dashed, dotted, double. Absent by default."
+    },
+    "weight": {
+      "type": "string",
+      "default": "",
+      "attribute": "weight",
+      "description": "The font weight the label draws in, for a row that IS its own preview: 700, bold, lighter. It reaches the label the way face does, as a custom property set inline on that span, so a list of nine weights interns one rule. Absent draws the row's own weight."
+    },
+    "slant": {
+      "type": "string",
+      "default": "",
+      "attribute": "slant",
+      "description": "The font style the label draws in: italic or oblique. Named slant rather than style because style is the attribute every element already has. Absent draws upright."
+    },
+    "variant": {
+      "type": "string",
+      "default": "",
+      "attribute": "variant",
+      "description": "The font variant the label draws in: small-caps. Absent draws the row's own."
+    },
+    "transform": {
+      "type": "string",
+      "default": "",
+      "attribute": "transform",
+      "description": "The text transform the label draws with: uppercase, lowercase, capitalize. The label's WORDS are unchanged, so a reader hears the row's name and sees what choosing it would do. Absent draws the words as written."
+    },
+    "decoration": {
+      "type": "string",
+      "default": "",
+      "attribute": "decoration",
+      "description": "The text decoration the label draws with, as any text-decoration value: underline, line-through, underline wavy. Absent draws none."
+    },
+    "noSwatch": {
+      "$expression": {
+        "operator": "!",
+        "target": {
+          "$ref": "#/state/swatch"
+        }
+      }
+    },
+    "noLine": {
+      "$expression": {
+        "operator": "!",
+        "target": {
+          "$ref": "#/state/line"
+        }
+      }
+    },
+    "noDescription": {
+      "$expression": {
+        "operator": "!",
+        "target": {
+          "$ref": "#/state/description"
+        }
+      }
+    },
+    "onClick": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "if": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/disabled"
+            }
+          },
+          "then": [
+            {
+              "dispatchEvent": "select",
+              "detail": {
+                "$ref": "#/state/value"
+              },
+              "bubbles": true,
+              "composed": true
+            }
+          ]
+        }
+      ],
+      "emits": [
+        {
+          "name": "select",
+          "description": "The row was picked; detail is its value. It bubbles, so the listbox's owner hears every row through one handler rather than one per row."
+        }
+      ],
+      "description": "Activation dispatches select unless the row is disabled. The click is NOT stopped, which is where this differs from jx-menu-item: a menu row can contain another menu row and would activate both, and a listbox row can contain nothing, so stopping the click here would only take the gesture away from the panel's own handler."
+    },
+    "onPointerDown": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "preventDefault": true
+        }
+      ],
+      "description": "Keeps the caret where it was while a row is pressed. A listbox row is not focusable, so the press would otherwise move focus to the nearest focusable ancestor — off the field that owns the keyboard, and out of the canvas the slash menu is filtering for — and a combobox would fire a change for a value the reader was in the middle of replacing. The same fix jx-textfield's clear button makes, for the same reason."
+    }
+  },
+  "attributes": {
+    "role": "option",
+    "aria-selected": "${state.selected ? 'true' : 'false'}",
+    "aria-disabled": "${state.disabled ? 'true' : null}"
+  },
+  "onclick": {
+    "$ref": "#/state/onClick"
+  },
+  "onpointerdown": {
+    "$ref": "#/state/onPointerDown"
+  },
+  "style": {
+    "display": "flex",
+    "&[hidden]": {
+      "display": "none"
+    },
+    "alignItems": "center",
+    "gap": "var(--jx-space-3)",
+    "minHeight": "var(--jx-control-h)",
+    "padding": "var(--jx-space-1) var(--jx-space-3)",
+    "borderRadius": "var(--jx-radius-sm)",
+    "color": "var(--jx-fg)",
+    "cursor": "pointer",
+    "userSelect": "none",
+    "scrollMarginBlock": "var(--jx-space-1)",
+    ":hover": {
+      "background": "var(--jx-hover-bg)"
+    },
+    "&[aria-selected=\"true\"]": {
+      "$description": "The highlight is keyed on aria-selected rather than on a second data attribute, so the state a reader hears and the state a reader sees cannot come apart — and :hover is left as its own weaker rule, because the pointer moving over a row is a suggestion and the caret is the answer.",
+      "background": "var(--jx-accent-solid)",
+      "color": "var(--jx-accent-fg)"
+    },
+    "&[aria-disabled=\"true\"]": {
+      "opacity": "0.45",
+      "cursor": "default"
+    },
+    "& [part=\"swatch\"]": {
+      "display": "block",
+      "flex": "0 0 auto",
+      "inlineSize": "16px",
+      "blockSize": "16px",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "var(--jx-row-swatch, transparent)",
+      "boxShadow": "inset 0 0 0 1px var(--jx-border)"
+    },
+    "& [part=\"line\"]": {
+      "display": "block",
+      "flex": "0 0 auto",
+      "inlineSize": "32px",
+      "blockSize": "0",
+      "borderBlockStart": "2px var(--jx-row-line, none) currentColor"
+    },
+    "& [part=\"icon\"]": {
+      "display": "inline-flex",
+      "flex": "0 0 auto",
+      "color": "var(--jx-fg-dim)"
+    },
+    "& [part=\"label\"]": {
+      "display": "block",
+      "minWidth": "0",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
+      "fontFamily": "var(--jx-row-face, inherit)",
+      "fontWeight": "var(--jx-row-weight, inherit)",
+      "fontStyle": "var(--jx-row-slant, inherit)",
+      "fontVariant": "var(--jx-row-variant, inherit)",
+      "textTransform": "var(--jx-row-transform, inherit)",
+      "textDecoration": "var(--jx-row-decoration, inherit)"
+    },
+    "& [part=\"description\"]": {
+      "display": "block",
+      "minWidth": "0",
+      "marginInlineStart": "auto",
+      "paddingInlineStart": "var(--jx-space-4)",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
+      "color": "var(--jx-fg-muted)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"end\"]": {
+      "display": "inline-flex",
+      "alignItems": "center",
+      "flex": "0 0 auto",
+      "paddingInlineStart": "var(--jx-space-3)",
+      "color": "var(--jx-fg-muted)",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"swatch\"][hidden], & [part=\"line\"][hidden], & [part=\"description\"][hidden]": {
+      "display": "none"
+    },
+    "& [part=\"icon\"]:empty, & [part=\"end\"]:empty": {
+      "$description": "A slot leaves NO node once its content is distributed (spec.md 16.6), so a container that received nothing is genuinely empty and asking it is how an element finds out (ui.md 3.2). Without this, a row using neither channel still pays two boxes and the one gap between its label and its end becomes three.",
+      "display": "none"
+    },
+    "& [part=\"description\"][hidden] + [part=\"end\"], & [part=\"description\"]:empty + [part=\"end\"]": {
+      "$description": "The auto margin that pushes the end of the row to the end of the row lives on the description, which is where it belongs when there is one. With no description there is nothing holding that space open, so it moves here — and a display:none sibling still matches +, which is what makes one rule enough.",
+      "marginInlineStart": "auto"
+    },
+    "&[aria-selected=\"true\"] [part=\"description\"], &[aria-selected=\"true\"] [part=\"end\"], &[aria-selected=\"true\"] [part=\"icon\"]": {
+      "$description": "A highlighted row draws on the accent, and a muted grey on an accent fails SC 1.4.3. Every channel takes the row's own ink instead of keeping its own.",
+      "color": "inherit"
+    }
+  },
+  "children": [
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "swatch",
+        "aria-hidden": "true"
+      },
+      "style": {
+        "--jx-row-swatch": "${state.swatch || 'transparent'}"
+      },
+      "hidden": {
+        "$ref": "#/state/noSwatch"
+      }
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "line",
+        "aria-hidden": "true"
+      },
+      "style": {
+        "--jx-row-line": "${state.line || 'none'}"
+      },
+      "hidden": {
+        "$ref": "#/state/noLine"
+      }
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "icon"
+      },
+      "children": [
+        {
+          "tagName": "slot",
+          "attributes": {
+            "name": "icon"
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "label"
+      },
+      "style": {
+        "--jx-row-face": "${state.face || 'inherit'}",
+        "--jx-row-weight": "${state.weight || 'inherit'}",
+        "--jx-row-slant": "${state.slant || 'inherit'}",
+        "--jx-row-variant": "${state.variant || 'inherit'}",
+        "--jx-row-transform": "${state.transform || 'inherit'}",
+        "--jx-row-decoration": "${state.decoration || 'inherit'}"
+      },
+      "textContent": "${state.label}"
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "description"
+      },
+      "hidden": {
+        "$ref": "#/state/noDescription"
+      },
+      "textContent": "${state.description}"
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "end"
+      },
+      "children": [
+        {
+          "tagName": "slot",
+          "attributes": {
+            "name": "end"
+          }
+        }
+      ]
+    }
+  ]
+}

package/components/jx-popover.json

@@ -0,0 +1,227 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "JxPopover",
+  "tagName": "jx-popover",
+  "observedAttributes": ["label", "arrow", "match-width", "placement", "x", "y", "floor"],
+  "state": {
+    "label": {
+      "type": "string",
+      "default": "",
+      "attribute": "label",
+      "description": "The panel's accessible name. Set, the panel becomes a named role=\"group\"; empty, it carries no role at all. A PANEL HOLDING CONTROLS MUST SET IT: role=\"group\" is in neither the accessibility lint's content-named roles nor its labelled roles, so an unnamed one is invisible to every gate, and a non-modal group of form controls with no role and no name announces no boundary on entry. A panel holding only a jx-menu leaves it empty, because the menu carries its own name."
+    },
+    "arrow": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "arrow",
+      "description": "Draw a pointer at the panel's block-start edge. Decorative and aria-hidden; off by default, because a panel placed by measured coordinates cannot promise the arrow lands on its anchor. THE PANEL ITSELF NEVER SCROLLS: the scroll box is [part=\"content\"], because a scroll container clips whatever hangs outside its padding box and the arrow hangs 5px above it; with overflow on the host the arrow paints nothing at all."
+    },
+    "matchWidth": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "match-width",
+      "description": "Make the panel at least as wide as the element it was opened from, the way a select's list matches its trigger. The width is re-measured on each toggle and never continuously, from whatever the toggle names as its source: a raw <button popovertarget>, a kit button forwarding popovertarget, and openAt(panel, trigger) all measure the trigger."
+    },
+    "placement": {
+      "type": "string",
+      "default": "block-end span-inline-end",
+      "attribute": "placement",
+      "description": "Where the panel sits relative to the element it was opened from, as a CSS position-area value: block-end span-inline-end (below, its inline-start edge on the trigger's) by default; block-end span-inline-start for a panel that hangs from a trigger's trailing edge; block-start for one that opens above. It applies only while the panel is ANCHORED, which is whenever it was shown from a source, and only on an engine with CSS anchor positioning: the trigger becomes the popover's implicit anchor the moment it is passed to showPopover({ source }) or names the panel with popovertarget, so no anchor-name is ever written on a consumer's element (specs/ui.md 2, 6). Everywhere else the panel stands at x and y. The value is passed to the property as written and is not validated here, because the platform's own grammar is the contract and a value it refuses computes to none, which is the coordinate placement again."
+    },
+    "x": {
+      "type": "number",
+      "default": 0,
+      "attribute": "x",
+      "description": "Where the panel's inline-start edge sits, in viewport pixels, whenever the panel is NOT anchored: shown with no source, given a floor, or on an engine without CSS anchor positioning. A panel shown from a source is placed by the platform against that source (see placement) and ignores x and y, though an opener may still write them, because they are exactly the fallback the anchored rule stands on."
+    },
+    "y": {
+      "type": "number",
+      "default": 0,
+      "attribute": "y",
+      "description": "Where the panel's block-start edge sits, in viewport pixels, under the same condition as x. The gap between that edge and the anchor is the --jx-popover-offset token, not a prop: a numeric prop with a non-zero default cannot express \"unset\", because removing its attribute coerces through the current value's type and writes 0. Anchored, the same margin is the gap below the trigger."
+    },
+    "floor": {
+      "type": "number",
+      "default": 0,
+      "attribute": "floor",
+      "description": "The lowest edge the panel may reach, in viewport pixels; 0 means the viewport's bottom. A panel opened from a rail that abuts a status bar sets it to the rail's bottom, so a tall panel never runs down over the bar."
+    },
+    "open": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the panel is showing. THIS IS NOT A DOOR: writing el.open = true shows nothing. It follows the platform's toggle event; write it through showPopover() and hidePopover(), or through the openAt() and close() helpers in the behaviours module, not directly."
+    },
+    "settling": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether a discrete open or close transition is still running. Mirrored as data-jx-settling, so a host can wait for the panel to come to rest before measuring it."
+    },
+    "anchorWidth": {
+      "type": "number",
+      "default": 0,
+      "description": "The measured border-box width of the element the panel was opened from, in pixels. Written by the behaviour under matchWidth and read by the panel's own min-width; 0 when nothing has been measured."
+    },
+    "anchored": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the panel is showing from a source the platform knows, and therefore positioned by anchor rather than by x and y. Written by the behaviour on beforetoggle, before the panel is laid out, so the first frame is already in the right place; cleared when it closes. Mirrored as data-anchored, which the anchored rule keys on. Not an attribute, because it is the platform's fact and never a consumer's to set. A panel given a floor is never anchored: a floor is a limit the platform's fallbacks cannot express, so it keeps the coordinate placement the clamp honours."
+    },
+    "panelWidth": "${state.matchWidth && state.anchorWidth > 0 ? state.anchorWidth + 'px' : '180px'}",
+    "noArrow": {
+      "$expression": {
+        "operator": "===",
+        "target": {
+          "$ref": "#/state/arrow"
+        },
+        "value": false
+      }
+    },
+    "onBeforeToggle": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/popover.ts",
+      "$export": "onBeforeToggle",
+      "description": "Decides anchored before the panel is laid out: an opening toggle whose source the platform names, on a panel with no floor, is anchored; everything else is not. On beforetoggle rather than toggle because toggle is queued after the show and a panel that learned it was anchored one frame late would paint once at its coordinates and then jump."
+    },
+    "onToggle": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/popover.ts",
+      "$export": "onToggle",
+      "description": "Mirrors the platform's toggle event into open, raises settling for the transition, measures the anchor under matchWidth, and clamps a freshly shown panel into the viewport when it is not anchored; an anchored panel is placed and flipped by the platform and is left alone."
+    },
+    "onTransitionEnd": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/popover.ts",
+      "$export": "onTransitionEnd",
+      "description": "Clears settling when the panel's own transition finishes. A transition on a child is not the panel coming to rest, so only an event whose target is the host counts."
+    },
+    "onMount": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "dispatchEvent": "jx-ready",
+          "bubbles": true
+        }
+      ],
+      "description": "Announces that the element has rendered and carries its popover attribute, so a host may show it. A panel is always an auto popover: light dismiss, Escape and focus restoration are the platform's."
+    }
+  },
+  "onbeforetoggle": {
+    "$ref": "#/state/onBeforeToggle"
+  },
+  "ontoggle": {
+    "$ref": "#/state/onToggle"
+  },
+  "ontransitionend": {
+    "$ref": "#/state/onTransitionEnd"
+  },
+  "attributes": {
+    "popover": "auto",
+    "role": "${state.label ? 'group' : null}",
+    "aria-label": "${state.label || null}",
+    "data-open": "${state.open ? '' : null}",
+    "data-jx-settling": "${state.settling ? '' : null}",
+    "data-anchored": "${state.anchored ? '' : null}"
+  },
+  "style": {
+    "display": "revert-layer",
+    "&[hidden]": {
+      "display": "none"
+    },
+    "position": "fixed",
+    "insetInlineStart": "${state.x}px",
+    "insetBlockStart": "${state.y}px",
+    "insetInlineEnd": "auto",
+    "insetBlockEnd": "auto",
+    "margin": "0",
+    "marginBlockStart": "var(--jx-popover-offset, 4px)",
+    "padding": "var(--jx-space-2)",
+    "minWidth": "${state.panelWidth}",
+    "maxWidth": "min(360px, calc(100vw - 8px))",
+    "maxHeight": "calc(100vh - 8px)",
+    "overflow": "visible",
+    "boxSizing": "border-box",
+    "flexDirection": "column",
+    "background": "var(--jx-bg-overlay)",
+    "color": "var(--jx-fg)",
+    "border": "1px solid var(--jx-border-strong)",
+    "borderRadius": "var(--jx-radius-md)",
+    "boxShadow": "var(--jx-shadow-popover)",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "lineHeight": "var(--jx-leading-md)",
+    "pointerEvents": "auto",
+    "outline": "none",
+    "opacity": "0",
+    "transition": "opacity var(--jx-dur-1) var(--jx-ease-out), display var(--jx-dur-1) allow-discrete, overlay var(--jx-dur-1) allow-discrete",
+    ":popover-open": {
+      "display": "flex",
+      "opacity": "1"
+    },
+    "&[hidden]:popover-open": {
+      "display": "none"
+    },
+    "&:focus-visible": {
+      "outline": "var(--jx-focus-ring)"
+    },
+    "@supports (position-area: block-end)": {
+      "$description": "The anchored placement, and the whole of what CSS anchor positioning gives a panel: the platform puts it against its IMPLICIT anchor — the element it was shown from — follows that element through scroll and resize, and flips it to the other side when the first placement would overflow, none of which a measured coordinate can do without a listener per cause. No anchor-name is involved: a popover's invoker is its implicit anchor by the platform's own rule, which is what makes this reachable under ui.md 2 (an element writes no style on a consumer's trigger). The insets are released so x and y stop mattering, and matchWidth becomes anchor-size, which follows the trigger as it resizes where the measured width could not. Outside this block, and on a panel shown from nothing or with a floor, the coordinate placement above is the answer, unchanged.",
+      "&[data-anchored]": {
+        "insetInlineStart": "auto",
+        "insetBlockStart": "auto",
+        "positionArea": "${state.placement}",
+        "positionTryFallbacks": "flip-block, flip-inline, flip-block flip-inline",
+        "minWidth": "${state.matchWidth ? 'anchor-size(width)' : '180px'}"
+      }
+    },
+    "@starting-style": {
+      "&:popover-open": {
+        "opacity": "0"
+      }
+    },
+    "& > [part=\"content\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)",
+      "minHeight": "0",
+      "overflow": "auto"
+    },
+    "& > [part=\"arrow\"]": {
+      "display": "block",
+      "position": "absolute",
+      "insetBlockStart": "-5px",
+      "insetInlineStart": "var(--jx-space-4)",
+      "width": "8px",
+      "height": "8px",
+      "rotate": "45deg",
+      "background": "var(--jx-bg-overlay)",
+      "borderTop": "1px solid var(--jx-border-strong)",
+      "borderInlineStart": "1px solid var(--jx-border-strong)"
+    },
+    "& > [part=\"arrow\"][hidden]": {
+      "display": "none"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "content"
+      },
+      "children": [
+        {
+          "tagName": "slot"
+        }
+      ]
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "arrow",
+        "aria-hidden": "true"
+      },
+      "hidden": {
+        "$ref": "#/state/noArrow"
+      }
+    }
+  ]
+}