@jxsuite/ui 0.0.0 → 0.2.0

package/src/testing/anchor-support.ts

@@ -0,0 +1,28 @@
+/**
+ * Pretend the engine does, or does not, position by anchor — for a test that drives one of the two
+ * placements the kit's overlays have (specs/ui.md §6).
+ *
+ * The kit asks `CSS.supports("position-area", "block-end")` (`supportsAnchorPositioning` in
+ * `behaviors/popover.ts`) to decide whether the platform is placing a panel or the clamp is, and a
+ * DOM shim answers that question however it likes — happy-dom says yes to everything — so a test
+ * that means one path or the other has to say which. Redefinition rather than assignment, because
+ * the shim exposes `CSS` through a read-only accessor.
+ *
+ * @param answer What `CSS.supports` should say.
+ * @returns The undo, to run in `finally`.
+ */
+export function withAnchorSupport(answer: boolean): () => void {
+  const before = Object.getOwnPropertyDescriptor(globalThis, "CSS");
+  Object.defineProperty(globalThis, "CSS", {
+    configurable: true,
+    value: { supports: () => answer },
+  });
+  return () => {
+    /* Put back what was there — or, on an engine that had no `CSS` at all, nothing. */
+    Object.defineProperty(
+      globalThis,
+      "CSS",
+      before ?? { configurable: true, value: undefined, writable: true },
+    );
+  };
+}

package/src/testing/popover-shim.ts

@@ -25,16 +25,39 @@ declare global {
   }
 }
 
-function toggleEvent(type: "beforetoggle" | "toggle", oldState: string, newState: string): Event {
+/**
+ * A ToggleEvent, as the platform dispatches one: `oldState`, `newState`, and — for an opening shown
+ * from a source — `source`, which Chrome 152 carries on both `beforetoggle` and `toggle` and which
+ * the kit reads to know what a panel is anchored to.
+ */
+function toggleEvent(
+  type: "beforetoggle" | "toggle",
+  oldState: string,
+  newState: string,
+  source?: Element | null,
+): Event {
   const event = new Event(type, { bubbles: false, cancelable: type === "beforetoggle" });
-  Object.assign(event, { newState, oldState });
+  Object.assign(event, { newState, oldState, ...(source ? { source } : {}) });
   return event;
 }
 
+/**
+ * Whether the element light-dismisses and answers Escape: `auto` and `hint` both do, `manual` does
+ * not.
+ */
 function isAuto(el: HTMLElement): boolean {
   return el.getAttribute("popover") !== "manual";
 }
 
+/** The popover's mode, defaulting the way an invalid value does — to `manual`. */
+function modeOf(el: HTMLElement): "auto" | "hint" | "manual" {
+  const raw = el.getAttribute("popover");
+  if (raw === "hint") {
+    return "hint";
+  }
+  return raw === "auto" || raw === "" ? "auto" : "manual";
+}
+
 export function installPopoverShim(): void {
   const proto = HTMLElement.prototype as HTMLElement & {
     showPopover?: (options?: { source?: Element }) => void;
@@ -79,18 +102,28 @@ export function installPopoverShim(): void {
     } else {
       state.invokers.delete(this);
     }
-    if (isAuto(this)) {
+    /* Showing an `auto` closes every other `auto` and every `hint`; showing a `hint` closes only
+       other hints. That asymmetry is the whole reason `hint` exists — a tip can sit over an open
+       menu explaining a row — and it is measured, not assumed: with an auto popover open, Chrome
+       152 accepts `hint.showPopover()` and leaves the auto one open. Modelling hint as auto here
+       made a correct element look broken, so the one assertion that would have caught a
+       regression could not be written. */
+    const mode = modeOf(this);
+    if (mode !== "manual") {
+      const closes = mode === "auto" ? ["auto", "hint"] : ["hint"];
+      // A copy, because `hide` deletes from the set being walked.
       const showing = [...state.open];
       for (const other of showing) {
-        if (isAuto(other) && !other.contains(this)) {
+        if (closes.includes(modeOf(other)) && !other.contains(this)) {
           hide(other);
         }
       }
     }
-    this.dispatchEvent(toggleEvent("beforetoggle", "closed", "open"));
+    const source = options?.source ?? null;
+    this.dispatchEvent(toggleEvent("beforetoggle", "closed", "open", source));
     state.open.add(this);
     this.dataset.popoverOpen = "";
-    queueMicrotask(() => this.dispatchEvent(toggleEvent("toggle", "closed", "open")));
+    queueMicrotask(() => this.dispatchEvent(toggleEvent("toggle", "closed", "open", source)));
   };
   proto.hidePopover = function hidePopover(this: HTMLElement): void {
     if (!this.hasAttribute("popover")) {

package/src/theme.ts

@@ -16,16 +16,40 @@ import project from "../project.json";
 /** The cascade layer every kit stylesheet lives in. */
 export const THEME_LAYER = "jx-ui";
 
-/** The token block as authored: `project.json`'s `style`. */
-export const themeTokens = project.style as JxStyle;
+/** The `style` block as authored: one key, the cascade layer, holding every declaration. */
+const themeStyle = project.style as JxStyle;
 
-/** The theme as CSS text: every token on `:root`, inside `@layer jx-ui`. */
+/**
+ * The tokens themselves, from inside the layer.
+ *
+ * Every caller wants the declarations, never the wrapper — so this names them and `themeStyle`
+ * stays private. Pointing it at the raw block instead would hand each caller one key called `@layer
+ * jx-ui` and let it look up a token that is one level down, which returns `undefined` rather than
+ * failing.
+ */
+export const themeTokens = (themeStyle[`@layer ${THEME_LAYER}`] ?? {}) as JxStyle;
+
+/**
+ * The theme as CSS text: every token on `:root`, inside `@layer jx-ui`.
+ *
+ * Not one character of this is written here. The layer used to be a template literal wrapped around
+ * the builder's output, which made this module a THIRD reader of the same `style` block — beside
+ * the runtime and the site builder — and the three could disagree about what the block meant. The
+ * layer is now an authored `"@layer jx-ui"` key, so the builder emits it like any other at-rule and
+ * this function is the builder and nothing else.
+ */
 export function themeCSS(): string {
-  const rules = buildStyleRules(themeTokens, { scope: ":root" }).map((rule) => rule.text);
-  return `@layer ${THEME_LAYER} {\n${rules.join("\n")}\n}\n`;
+  return `${buildStyleRules(themeStyle, { scope: ":root" })
+    .map((rule) => rule.text)
+    .join("\n")}\n`;
 }
 
-/** The custom-property names the theme declares at the root, in declaration order. */
+/**
+ * The custom-property names the theme declares at the root, in declaration order.
+ *
+ * Read from inside the layer, like every other token access — a filter over the raw `style` block
+ * would return an empty array rather than fail, which is the shape of silence this slice is about.
+ */
 export function themeTokenNames(): string[] {
   return Object.keys(themeTokens).filter((key) => key.startsWith("--"));
 }

package/stylebook/jx-accordion-item.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StylebookAccordionItem",
+  "tagName": "main",
+  "$elements": [
+    {
+      "$ref": "../components/jx-icon.json"
+    },
+    {
+      "$ref": "../components/jx-spinner.json"
+    },
+    {
+      "$ref": "../components/jx-action-button.json"
+    },
+    {
+      "$ref": "../components/jx-accordion-item.json"
+    },
+    {
+      "$ref": "../components/jx-accordion.json"
+    },
+    {
+      "$ref": "../components/jx-dot.json"
+    }
+  ],
+  "state": {
+    "last": "nothing yet",
+    "note": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "operator": "=",
+          "target": {
+            "$ref": "#/state/last"
+          },
+          "value": {
+            "$ref": "event#/detail"
+          }
+        }
+      ]
+    }
+  },
+  "style": {
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "color": "var(--jx-fg)",
+    "background": "var(--jx-bg)",
+    "padding": "var(--jx-space-6)",
+    "minHeight": "100vh",
+    "& > h1": {
+      "fontSize": "var(--jx-text-lg)",
+      "fontWeight": "600",
+      "margin": "0 0 var(--jx-space-5)"
+    },
+    "& > h2": {
+      "fontSize": "var(--jx-text-md)",
+      "fontWeight": "600",
+      "color": "var(--jx-fg-dim)",
+      "margin": "var(--jx-space-5) 0 var(--jx-space-2)"
+    },
+    "& > p": {
+      "color": "var(--jx-fg-dim)",
+      "margin": "0 0 var(--jx-space-5)"
+    },
+    "& jx-accordion": {
+      "maxWidth": "420px",
+      "border": "1px solid var(--jx-border)",
+      "borderRadius": "var(--jx-radius-md)",
+      "background": "var(--jx-bg-panel)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "h1",
+      "textContent": "jx-accordion-item"
+    },
+    {
+      "tagName": "p",
+      "textContent": "A native details and summary pair made one addressable thing: the platform owns the toggle, Enter and Space, find-in-page reveal and print, and the element adds a label, a caret, an actions row that stays visible while the section is shut, and an open a host can both write and read back. The stack around it is jx-accordion, which draws the seam between one section and the next. Last toggle said: ${state.last}."
+    },
+    {
+      "tagName": "h2",
+      "textContent": "A panel of sections"
+    },
+    {
+      "tagName": "jx-accordion",
+      "children": [
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Layout",
+            "open": true
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Display, position and the box model."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Typography"
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "jx-dot",
+              "attributes": {
+                "slot": "heading",
+                "aria-hidden": "true"
+              }
+            },
+            {
+              "tagName": "jx-action-button",
+              "attributes": {
+                "slot": "actions"
+              },
+              "$props": {
+                "label": "Clear typography overrides",
+                "hint": "Clear typography overrides",
+                "icon": "arrow-u-up-left",
+                "size": "sm"
+              }
+            },
+            {
+              "tagName": "p",
+              "textContent": "The interactive control in the actions row does not toggle the section, and it is still there while the section is closed."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Custom",
+            "level": "3"
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "This one opts in to heading semantics with level=\"3\", so it is reachable by heading navigation."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "tagName": "h2",
+      "textContent": "One at a time"
+    },
+    {
+      "tagName": "jx-accordion",
+      "$props": {
+        "multiple": false
+      },
+      "children": [
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "First",
+            "name": "stylebook-exclusive",
+            "open": true
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Every item here carries the same name, so the platform closes the others when one opens."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Second",
+            "name": "stylebook-exclusive"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "No shipped Studio panel wants this — all six keep several sections open at once — but the platform gives it for one forwarded attribute."
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/stylebook/jx-accordion.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StylebookAccordion",
+  "tagName": "main",
+  "$elements": [
+    {
+      "$ref": "../components/jx-icon.json"
+    },
+    {
+      "$ref": "../components/jx-accordion-item.json"
+    },
+    {
+      "$ref": "../components/jx-accordion.json"
+    }
+  ],
+  "state": {
+    "last": "nothing yet",
+    "note": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "operator": "=",
+          "target": {
+            "$ref": "#/state/last"
+          },
+          "value": {
+            "$ref": "event#/detail"
+          }
+        }
+      ]
+    }
+  },
+  "style": {
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "color": "var(--jx-fg)",
+    "background": "var(--jx-bg)",
+    "padding": "var(--jx-space-6)",
+    "minHeight": "100vh",
+    "& > h1": {
+      "fontSize": "var(--jx-text-lg)",
+      "fontWeight": "600",
+      "margin": "0 0 var(--jx-space-5)"
+    },
+    "& > h2": {
+      "fontSize": "var(--jx-text-md)",
+      "fontWeight": "600",
+      "color": "var(--jx-fg-dim)",
+      "margin": "var(--jx-space-5) 0 var(--jx-space-2)"
+    },
+    "& > p": {
+      "color": "var(--jx-fg-dim)",
+      "margin": "0 0 var(--jx-space-5)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "h1",
+      "textContent": "jx-accordion"
+    },
+    {
+      "tagName": "p",
+      "textContent": "The stack a panel of sections stands in: a column that clips its children's width and draws one hairline BETWEEN them, so a rule falls in every seam and never above the first VISIBLE section. The first stack below opens with a section a panel has bound away, and no hairline is drawn across the top of what is left. The rule is the container's because it is a rule about a child's POSITION among its siblings, which no section can see about itself. Last toggle said: ${state.last}."
+    },
+    {
+      "tagName": "h2",
+      "textContent": "A panel of sections"
+    },
+    {
+      "tagName": "jx-accordion",
+      "style": {
+        "maxWidth": "420px",
+        "border": "1px solid var(--jx-border)",
+        "borderRadius": "var(--jx-radius-md)",
+        "background": "var(--jx-bg-panel)"
+      },
+      "children": [
+        {
+          "tagName": "jx-accordion-item",
+          "attributes": {
+            "hidden": ""
+          },
+          "$props": {
+            "label": "Bound away"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "A panel that binds hidden on a section is why the seam asks for the first VISIBLE child rather than the first child. Unhide this in the inspector and the hairline moves to the section below it."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Layout",
+            "open": true
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Display, position and the box model. The panel's frame is written on the usage site rather than in the element, because a border and a background are this page's idea of a panel and not the stack's."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Typography"
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "The hairline above this section is the container's rule, and the first section a reader sees has none — the hidden one above it does not count."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Nesting"
+          },
+          "ontoggle": {
+            "$ref": "#/state/note"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "A stack inside a section keeps its own seams, because the rule reaches direct children only."
+            },
+            {
+              "tagName": "jx-accordion",
+              "children": [
+                {
+                  "tagName": "jx-accordion-item",
+                  "$props": {
+                    "label": "Inner first"
+                  },
+                  "children": [
+                    {
+                      "tagName": "p",
+                      "textContent": "No rule above this one either."
+                    }
+                  ]
+                },
+                {
+                  "tagName": "jx-accordion-item",
+                  "$props": {
+                    "label": "Inner second"
+                  },
+                  "children": [
+                    {
+                      "tagName": "p",
+                      "textContent": "One seam, in the inner stack."
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "tagName": "h2",
+      "textContent": "One at a time"
+    },
+    {
+      "tagName": "p",
+      "textContent": "multiple=\"false\" is the container writing down what the panel is for; the platform's own switch is name on each section, and only the section may carry it."
+    },
+    {
+      "tagName": "jx-accordion",
+      "$props": {
+        "multiple": false
+      },
+      "style": {
+        "maxWidth": "420px",
+        "border": "1px solid var(--jx-border)",
+        "borderRadius": "var(--jx-radius-md)",
+        "background": "var(--jx-bg-panel)"
+      },
+      "children": [
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "First",
+            "name": "stylebook-exclusive",
+            "open": true
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Every item here carries the same name, so the platform closes the others when one opens."
+            }
+          ]
+        },
+        {
+          "tagName": "jx-accordion-item",
+          "$props": {
+            "label": "Second",
+            "name": "stylebook-exclusive"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "No shipped Studio panel wants this — all six keep several sections open at once — but the platform gives it for one forwarded attribute."
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}